1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-02 04:40:29 +02:00

Remove unused doc/sources/

* doc/sources: Remove.  It is not used at all, presumably because all it
  had to offer was already incorporated in the manual.
This commit is contained in:
Andy Wingo 2012-02-02 12:16:30 +01:00
parent 64de6db5c6
commit c99acbf397
20 changed files with 0 additions and 3404 deletions

View file

@ -1,5 +0,0 @@
2001-08-27 Neil Jerram <neil@ossau.uklinux.net>
The change log for files in this directory continues backwards
from 2001-08-27 in ../ChangeLog, as all the Guile documentation
prior to this date was contained in a single directory.

View file

@ -1,7 +0,0 @@
# -*- Makefile -*-
EXTRA_DIST = libguile-overview.texi snarf.texi contributors.texi \
libguile-tools.texi strings.texi data-rep.texi new-types.texi tk.texi \
debug-c.texi old-intro.texi unix-other.texi debug-scheme.texi \
sample-APIs.texi unix.texi guile-slib.texi scheme-concepts.texi \
jimb-org.texi scm-ref.texi ChangeLog-2008

View file

@ -1,80 +0,0 @@
@node Contributors to Guile
@appendix Contributors to Guile
This Guile Manual was written by Mark Galassi, Jim Blandy and Gary
Houston.
Guile was developed over many years by the following people:
@table @strong
@item George Carrette
Wrote files present in Siod version 2.3, released in December of 1989.
@item Aubrey Jaffer
Wrote substantial portions of guile.texi, and surely others.
Changes to: eval.c, ioext.c, posix.c, gscm.c, scm.h, socket.c,
gsubr.c, sys.c, test.scm, stime.c, and unif.c.
@item Gary Houston
changes to many files in libguile.
wrote: libguile/socket.c, ice-9/expect.scm
@item Tom Lord
Many changes throughout.
In the subdirectory ctax, wrote:
Makefile.in configure.in hashtabs.scm macros.scm scm-ops.scm
c-ops.scm grammar.scm lexer.scm reader.scm
In the subdirectory gtcltk-lib, wrote:
Makefile.in guile-tcl.c guile-tk.c
configure.in guile-tcl.h guile-tk.h
In the subdirectory guile, wrote:
Makefile.in getopt.c getopt1.c
configure.in getopt.h guile.c
In the subdirectory ice-9, wrote:
Makefile.in configure.in lineio.scm poe.scm
boot-9.scm hcons.scm mapping.scm
In the subdirectory lang, wrote:
Makefile.in grammar.scm lr0.scm pp.scm
configure.in lex.scm lr1.scm
In the subdirectory rx, wrote:
Makefile.in runtests.c rxbitset.h rxnfa.c rxspencer.c
TESTS rx.c rxcontext.h rxnfa.h rxspencer.h
TESTS2C.sed rx.h rxcset.c rxnode.c rxstr.c
_rx.h rxall.h rxcset.h rxnode.h rxstr.h
configure.in rxanal.c rxdbug.c rxposix.c rxsuper.c
hashrexp.c rxanal.h rxgnucomp.c rxposix.h rxsuper.h
inst-rxposix.h rxbasic.c rxgnucomp.h rxproto.h rxunfa.c
rgx.c rxbasic.h rxhash.c rxsimp.c rxunfa.h
rgx.h rxbitset.c rxhash.h rxsimp.h testcases.h
In the subdirectory doc, wrote:
ctax.texi gtcltk.texi in.texi lang.texi
and portions of guile.texi.
@item Anthony Green
wrote the original code in the 'threads' directory, and
ice-9/threads.scm.
@item Mikael Djurfeldt
@example
In the subdirectory libguile, wrote:
backtrace.c debug.c options.c root.c srcprop.c stacks.c
backtrace.h debug.h options.h root.h srcprop.h stacks.h
In the subdirectory threads, rewrote:
coop-threads.c coop.c mit-pthreads.c threads.c
coop-threads.h fsu-pthreads.h mit-pthreads.h threads.h
Many other changes throughout.
@end example
@item Mark Galassi
@example
Designed and implemented the high-level libguile API (the @code{gh_}
interface), based largely on the defunct @code{gscm_} interface. In the
subdirectory gh, wrote:
gh.c gh_eval.c gh_io.c gh_test_c.c
gh.h gh_funcs.c gh_list.c gh_test_repl.c
gh_data.c gh_init.c gh_predicates.c
@end example
@end table

View file

@ -1,2 +0,0 @@
@node Debugging libguile
@chapter Debugging libguile

View file

@ -1,2 +0,0 @@
@node Debugging Scheme programs
@chapter Debugging Scheme programs

File diff suppressed because it is too large Load diff

View file

@ -1,434 +0,0 @@
@menu
* Format Interface::
* Format Specification::
@end menu
@node Format Interface, Format Specification, Format, Format
@subsection Format Interface
@defun format destination format-string . arguments
An almost complete implementation of Common LISP format description
according to the CL reference book @cite{Common LISP} from Guy L.
Steele, Digital Press. Backward compatible to most of the available
Scheme format implementations.
Returns @code{#t}, @code{#f} or a string; has side effect of printing
according to @var{format-string}. If @var{destination} is @code{#t},
the output is to the current output port and @code{#t} is returned. If
@var{destination} is @code{#f}, a formatted string is returned as the
result of the call. NEW: If @var{destination} is a string,
@var{destination} is regarded as the format string; @var{format-string} is
then the first argument and the output is returned as a string. If
@var{destination} is a number, the output is to the current error port
if available by the implementation. Otherwise @var{destination} must be
an output port and @code{#t} is returned.@refill
@var{format-string} must be a string. In case of a formatting error
format returns @code{#f} and prints a message on the current output or
error port. Characters are output as if the string were output by the
@code{display} function with the exception of those prefixed by a tilde
(~). For a detailed description of the @var{format-string} syntax
please consult a Common LISP format reference manual. For a test suite
to verify this format implementation load @file{formatst.scm}. Please
send bug reports to @code{lutzeb@@cs.tu-berlin.de}.
Note: @code{format} is not reentrant, i.e. only one @code{format}-call
may be executed at a time.
@end defun
@node Format Specification, , Format Interface, Format
@subsection Format Specification (Format version 3.0)
Please consult a Common LISP format reference manual for a detailed
description of the format string syntax. For a demonstration of the
implemented directives see @file{formatst.scm}.@refill
This implementation supports directive parameters and modifiers
(@code{:} and @code{@@} characters). Multiple parameters must be
separated by a comma (@code{,}). Parameters can be numerical parameters
(positive or negative), character parameters (prefixed by a quote
character (@code{'}), variable parameters (@code{v}), number of rest
arguments parameter (@code{#}), empty and default parameters. Directive
characters are case independent. The general form of a directive
is:@refill
@noindent
@var{directive} ::= ~@{@var{directive-parameter},@}[:][@@]@var{directive-character}
@noindent
@var{directive-parameter} ::= [ [-|+]@{0-9@}+ | '@var{character} | v | # ]
@subsubsection Implemented CL Format Control Directives
Documentation syntax: Uppercase characters represent the corresponding
control directive characters. Lowercase characters represent control
directive parameter descriptions.
@table @asis
@item @code{~A}
Any (print as @code{display} does).
@table @asis
@item @code{~@@A}
left pad.
@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}A}
full padding.
@end table
@item @code{~S}
S-expression (print as @code{write} does).
@table @asis
@item @code{~@@S}
left pad.
@item @code{~@var{mincol},@var{colinc},@var{minpad},@var{padchar}S}
full padding.
@end table
@item @code{~D}
Decimal.
@table @asis
@item @code{~@@D}
print number sign always.
@item @code{~:D}
print comma separated.
@item @code{~@var{mincol},@var{padchar},@var{commachar}D}
padding.
@end table
@item @code{~X}
Hexadecimal.
@table @asis
@item @code{~@@X}
print number sign always.
@item @code{~:X}
print comma separated.
@item @code{~@var{mincol},@var{padchar},@var{commachar}X}
padding.
@end table
@item @code{~O}
Octal.
@table @asis
@item @code{~@@O}
print number sign always.
@item @code{~:O}
print comma separated.
@item @code{~@var{mincol},@var{padchar},@var{commachar}O}
padding.
@end table
@item @code{~B}
Binary.
@table @asis
@item @code{~@@B}
print number sign always.
@item @code{~:B}
print comma separated.
@item @code{~@var{mincol},@var{padchar},@var{commachar}B}
padding.
@end table
@item @code{~@var{n}R}
Radix @var{n}.
@table @asis
@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar}R}
padding.
@end table
@item @code{~@@R}
print a number as a Roman numeral.
@item @code{~:@@R}
print a number as an ``old fashioned'' Roman numeral.
@item @code{~:R}
print a number as an ordinal English number.
@item @code{~:@@R}
print a number as a cardinal English number.
@item @code{~P}
Plural.
@table @asis
@item @code{~@@P}
prints @code{y} and @code{ies}.
@item @code{~:P}
as @code{~P but jumps 1 argument backward.}
@item @code{~:@@P}
as @code{~@@P but jumps 1 argument backward.}
@end table
@item @code{~C}
Character.
@table @asis
@item @code{~@@C}
prints a character as the reader can understand it (i.e. @code{#\} prefixing).
@item @code{~:C}
prints a character as emacs does (eg. @code{^C} for ASCII 03).
@end table
@item @code{~F}
Fixed-format floating-point (prints a flonum like @var{mmm.nnn}).
@table @asis
@item @code{~@var{width},@var{digits},@var{scale},@var{overflowchar},@var{padchar}F}
@item @code{~@@F}
If the number is positive a plus sign is printed.
@end table
@item @code{~E}
Exponential floating-point (prints a flonum like @var{mmm.nnn}@code{E}@var{ee}).
@table @asis
@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}E}
@item @code{~@@E}
If the number is positive a plus sign is printed.
@end table
@item @code{~G}
General floating-point (prints a flonum either fixed or exponential).
@table @asis
@item @code{~@var{width},@var{digits},@var{exponentdigits},@var{scale},@var{overflowchar},@var{padchar},@var{exponentchar}G}
@item @code{~@@G}
If the number is positive a plus sign is printed.
@end table
@item @code{~$}
Dollars floating-point (prints a flonum in fixed with signs separated).
@table @asis
@item @code{~@var{digits},@var{scale},@var{width},@var{padchar}$}
@item @code{~@@$}
If the number is positive a plus sign is printed.
@item @code{~:@@$}
A sign is always printed and appears before the padding.
@item @code{~:$}
The sign appears before the padding.
@end table
@item @code{~%}
Newline.
@table @asis
@item @code{~@var{n}%}
print @var{n} newlines.
@end table
@item @code{~&}
print newline if not at the beginning of the output line.
@table @asis
@item @code{~@var{n}&}
prints @code{~&} and then @var{n-1} newlines.
@end table
@item @code{~|}
Page Separator.
@table @asis
@item @code{~@var{n}|}
print @var{n} page separators.
@end table
@item @code{~~}
Tilde.
@table @asis
@item @code{~@var{n}~}
print @var{n} tildes.
@end table
@item @code{~}<newline>
Continuation Line.
@table @asis
@item @code{~:}<newline>
newline is ignored, white space left.
@item @code{~@@}<newline>
newline is left, white space ignored.
@end table
@item @code{~T}
Tabulation.
@table @asis
@item @code{~@@T}
relative tabulation.
@item @code{~@var{colnum,colinc}T}
full tabulation.
@end table
@item @code{~?}
Indirection (expects indirect arguments as a list).
@table @asis
@item @code{~@@?}
extracts indirect arguments from format arguments.
@end table
@item @code{~(@var{str}~)}
Case conversion (converts by @code{string-downcase}).
@table @asis
@item @code{~:(@var{str}~)}
converts by @code{string-capitalize}.
@item @code{~@@(@var{str}~)}
converts by @code{string-capitalize-first}.
@item @code{~:@@(@var{str}~)}
converts by @code{string-upcase}.
@end table
@item @code{~*}
Argument Jumping (jumps 1 argument forward).
@table @asis
@item @code{~@var{n}*}
jumps @var{n} arguments forward.
@item @code{~:*}
jumps 1 argument backward.
@item @code{~@var{n}:*}
jumps @var{n} arguments backward.
@item @code{~@@*}
jumps to the 0th argument.
@item @code{~@var{n}@@*}
jumps to the @var{n}th argument (beginning from 0)
@end table
@item @code{~[@var{str0}~;@var{str1}~;...~;@var{strn}~]}
Conditional Expression (numerical clause conditional).
@table @asis
@item @code{~@var{n}[}
take argument from @var{n}.
@item @code{~@@[}
true test conditional.
@item @code{~:[}
if-else-then conditional.
@item @code{~;}
clause separator.
@item @code{~:;}
default clause follows.
@end table
@item @code{~@{@var{str}~@}}
Iteration (args come from the next argument (a list)).
@table @asis
@item @code{~@var{n}@{}
at most @var{n} iterations.
@item @code{~:@{}
args from next arg (a list of lists).
@item @code{~@@@{}
args from the rest of arguments.
@item @code{~:@@@{}
args from the rest args (lists).
@end table
@item @code{~^}
Up and out.
@table @asis
@item @code{~@var{n}^}
aborts if @var{n} = 0
@item @code{~@var{n},@var{m}^}
aborts if @var{n} = @var{m}
@item @code{~@var{n},@var{m},@var{k}^}
aborts if @var{n} <= @var{m} <= @var{k}
@end table
@end table
@subsubsection Not Implemented CL Format Control Directives
@table @asis
@item @code{~:A}
print @code{#f} as an empty list (see below).
@item @code{~:S}
print @code{#f} as an empty list (see below).
@item @code{~<~>}
Justification.
@item @code{~:^}
(sorry I don't understand its semantics completely)
@end table
@subsubsection Extended, Replaced and Additional Control Directives
@table @asis
@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}D}
@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}X}
@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}O}
@item @code{~@var{mincol},@var{padchar},@var{commachar},@var{commawidth}B}
@item @code{~@var{n},@var{mincol},@var{padchar},@var{commachar},@var{commawidth}R}
@var{commawidth} is the number of characters between two comma characters.
@end table
@table @asis
@item @code{~I}
print an R5RS complex number as @code{~F~@@Fi} with passed parameters for
@code{~F}.
@item @code{~Y}
Pretty print formatting of an argument for scheme code lists.
@item @code{~K}
Same as @code{~?.}
@item @code{~!}
Flushes the output if format @var{destination} is a port.
@item @code{~_}
Print a @code{#\space} character
@table @asis
@item @code{~@var{n}_}
print @var{n} @code{#\space} characters.
@end table
@item @code{~/}
Print a @code{#\tab} character
@table @asis
@item @code{~@var{n}/}
print @var{n} @code{#\tab} characters.
@end table
@item @code{~@var{n}C}
Takes @var{n} as an integer representation for a character. No arguments
are consumed. @var{n} is converted to a character by
@code{integer->char}. @var{n} must be a positive decimal number.@refill
@item @code{~:S}
Print out readproof. Prints out internal objects represented as
@code{#<...>} as strings @code{"#<...>"} so that the format output can always
be processed by @code{read}.
@refill
@item @code{~:A}
Print out readproof. Prints out internal objects represented as
@code{#<...>} as strings @code{"#<...>"} so that the format output can always
be processed by @code{read}.
@item @code{~Q}
Prints information and a copyright notice on the format implementation.
@table @asis
@item @code{~:Q}
prints format version.
@end table
@refill
@item @code{~F, ~E, ~G, ~$}
may also print number strings, i.e. passing a number as a string and
format it accordingly.
@end table
@subsubsection Configuration Variables
Format has some configuration variables at the beginning of
@file{format.scm} to suit the systems and users needs. There should be
no modification necessary for the configuration that comes with SLIB.
If modification is desired the variable should be set after the format
code is loaded. Format detects automatically if the running scheme
system implements floating point numbers and complex numbers.
@table @asis
@item @var{format:symbol-case-conv}
Symbols are converted by @code{symbol->string} so the case type of the
printed symbols is implementation dependent.
@code{format:symbol-case-conv} is a one arg closure which is either
@code{#f} (no conversion), @code{string-upcase}, @code{string-downcase}
or @code{string-capitalize}. (default @code{#f})
@item @var{format:iobj-case-conv}
As @var{format:symbol-case-conv} but applies for the representation of
implementation internal objects. (default @code{#f})
@item @var{format:expch}
The character prefixing the exponent value in @code{~E} printing. (default
@code{#\E})
@end table
@subsubsection Compatibility With Other Format Implementations
@table @asis
@item SLIB format 2.x:
See @file{format.doc}.
@item SLIB format 1.4:
Downward compatible except for padding support and @code{~A}, @code{~S},
@code{~P}, @code{~X} uppercase printing. SLIB format 1.4 uses C-style
@code{printf} padding support which is completely replaced by the CL
@code{format} padding style.
@item MIT C-Scheme 7.1:
Downward compatible except for @code{~}, which is not documented
(ignores all characters inside the format string up to a newline
character). (7.1 implements @code{~a}, @code{~s},
~@var{newline}, @code{~~}, @code{~%}, numerical and variable
parameters and @code{:/@@} modifiers in the CL sense).@refill
@item Elk 1.5/2.0:
Downward compatible except for @code{~A} and @code{~S} which print in
uppercase. (Elk implements @code{~a}, @code{~s}, @code{~~}, and
@code{~%} (no directive parameters or modifiers)).@refill
@item Scheme->C 01nov91:
Downward compatible except for an optional destination parameter: S2C
accepts a format call without a destination which returns a formatted
string. This is equivalent to a #f destination in S2C. (S2C implements
@code{~a}, @code{~s}, @code{~c}, @code{~%}, and @code{~~} (no directive
parameters or modifiers)).@refill
@end table
This implementation of format is solely useful in the SLIB context
because it requires other components provided by SLIB.@refill

View file

@ -1,2 +0,0 @@
@node Guile and SLIB
@chapter Guile and SLIB

View file

@ -1,131 +0,0 @@
@menu
Preliminary
* Introduction::
* Using Guile::
@bye
>You can actually put any English text to break up the menu, so you
>could put the "Part n" headings in it.
Introduction
--- Explains Guile's goals, and gives brief examples of how to use
Guile interactively (show off repl), as a script interpreter,
and as an embedded interpreter.
Part I: Guile Scheme
R4RS Scheme as a Starting Point
--- Here we refer to R4RS, and explain that we're only
describing differences.
Block comments and interpreter triggers
Symbol case
Keywords
Exceptions
Modules
--- the preceding three come first, because we need them
in order to explain the behavior of some things later
Exception Handling
--- mention that repls usually establish default exception handlers
Dynamic Wind
Records
Structures
Arrays
Binary Numeric Operations
Shared and Read-Only Strings
Object Properties
Association Lists and Hash Tables
(Dictionaries In General)
association lists
hash tables (Hash Values)
Input/Output ports
file ports
soft ports
string ports
extended I/O (fseek; line read/write)
Garbage Collection
Threads and Dynamic Roots
Reflection
eval
Tag Values
Weak references
Regular Expressions
SLIB
POSIX system calls and networking
--- I think people will generally know whether they're looking
for a system call or not, so this should be an okay category.
conventions (includes error handling)
ports vs. file descriptors
file system (mknod goes here, no?)
user database
time (includes gettimeofday or whatever, strftime, strptime)
processes
terminals and pseudo-terminals
pipes
networking (includes databases, address conversion, and sockets)
system identification (uname)
locales (setlocale)
--- Note that there is no more 'misc'. It's better to have
small sections than unhelpful names.
SCSH
--- includes info on how to get SCSH features (open this
module), but mostly just a pointer to the SCSH manual.
This should not be under POSIX. SCSH includes plenty of
high-level stuff for starting processes and string
processing. SCSH is not a subset of POSIX, nor the
reverse.
Tcl/Tk interface
Module internals
first-class variables
first-class modules
internal debugging interface
--- The name of this chapter needs to clearly distinguish it
from the appendix describing the debugger UI. The intro
should have a pointer to the UI appendix.
Part II: Using Scheme with C --- a Portable Interface
--- We cover gh in a completely separate section. Why? I admit
I'm on shaky ground, but here's my reasoning: People who want
to write portable C code need to restrict themselves to only
using GH, and GH's semantics are (necessarily) well-defined
without reference to Guile's particulars. This makes life
more difficult for folks who just prefer to use the GH
interface when they can, but I really think the SCM interface
is not so bad, once you're used to it. A *lot* of GH
functions are just wrappers for SCM functions.
--- We cover repls here too, since GH has repl functions.
Part III: Using Scheme with C --- Guile's Interface
Scheme data representation
Relationship between Scheme and C functions
--- this is where we explain that all the functions marked as
"Primitive Functions" are also accessible from C, and how
to derive the C interface given the Scheme interface, when
we don't spell it out.
... I think there's other stuff needed here ...
I/O internals
linking Guile with your code
--- Mark's "Tools to automate adding libraries" is not a
well-defined concept. I think this is closer to what we
want to cover for now.
snarfing
Appendices:
Obtaining and Installing Guile
Invoking Guile
--- mentions read-eval-print loops
--- both the SCSH and GAWK manuals relegate invocation details
to an appendix. We can give examples in the introduction.
debugger user interface
--- The title and introduction of this appendix need to
distinguish this clearly from the chapter on the internal
debugging interface.
Indices:
--- At the top of the function/variable index, remind people
to look for functions under their Scheme names as well as
their C names.

View file

@ -1,30 +0,0 @@
@node Libguile overview
@chapter Libguile overview
@cindex libguile - overview
Extension languages, like Guile, Python and Tcl, can be embedded into a
C program, @footnote{Or a C++ or Fortran or Pascal program if you want.}
and thus allow the user to @emph{extend} the C program.
The way this is done is by providing a C language library with a well
defined interface. The interface consists of a set of public and
documented C-callable routines that offer the full interpreter
functionality, and allow the conversion of data between C and the
extension language.
@menu
* An example of libguile functionality::
* What can be done with libguile::
* Schizofrenia -- two APIs::
@end menu
@node An example of libguile functionality
@section An example of libguile functionality
[Two examples: using strings and using data conversion.]
@node What can be done with libguile
@section What can be done with libguile
@node Schizofrenia -- two APIs
@section Schizofrenia -- two APIs

View file

@ -1,191 +0,0 @@
@node Tools to automate adding libraries
@chapter Tools to automate adding libraries
You want to ...
The chapters @ref{Libguile -- high level interface} and @ref{Libguile --
SCM interface} showed how to make C libraries available from Scheme.
Here I will describe some automated tools that the Guile team has made
available. Some have been written especially for Guile (the Guile Magic
Snarfer), and some are also in use with other languages (Python, Perl,
...)
@menu
* By hand with gh_::
* By hand with Guile Magic Snarfer::
* Automatically using libtool::
* Automatically using SWIG::
@end menu
@node By hand with gh_
@section By hand with gh_
@node By hand with Guile Magic Snarfer
@section By hand with Guile Magic Snarfer
When writing C code for use with Guile, you typically define a set of C
functions, and then make some of them visible to the Scheme world by
calling the @code{scm_make_gsubr} function; a C functions published in
this way is called a @dfn{subr}. If you have many subrs to publish, it
can sometimes be annoying to keep the list of calls to
@code{scm_make_gsubr} in sync with the list of function definitions.
Frequently, a programmer will define a new subr in C, recompile his
application, and then discover that the Scheme interpreter cannot see
the subr, because he forgot to call @code{scm_make_gsubr}.
Guile provides the @code{guile-snarf} command to manage this problem.
Using this tool, you can keep all the information needed to define the
subr alongside the function definition itself; @code{guile-snarf} will
extract this information from your source code, and automatically
generate a file of calls to @code{scm_make_gsubr} which you can
@code{#include} into an initialization function. (The command name
comes from the verb ``to snarf'', here meaning ``to unceremoniously
extract information from a somewhat unwilling source.'')
@menu
* How guile-snarf works:: Using the @code{guile-snarf} command.
* Macros guile-snarf recognizes:: How to mark up code for @code{guile-snarf}.
@end menu
@node How guile-snarf works
@subsection How @code{guile-snarf} works
For example, here is how you might define a new subr called
@code{clear-image}, implemented by the C function @code{clear_image}:
@example
@group
#include <libguile.h>
@dots{}
SCM_PROC (s_clear_image, "clear-image", 1, 0, 0, clear_image);
SCM
clear_image (SCM image_smob)
@{
@dots{}
@}
@dots{}
void
init_image_type ()
@{
#include "image-type.x"
@}
@end group
@end example
The @code{SCM_PROC} declaration says that the C function
@code{clear_image} implements a Scheme subr called @code{clear-image},
which takes one required argument, no optional arguments, and no tail
argument. @code{SCM_PROC} also declares a static array of characters
named @code{s_clear_image}, initialized to the string
@code{"clear-image"}. The body of @code{clear_image} may use the array
in error messages, instead of writing out the literal string; this may
save string space on some systems.
Assuming the text above lives in a file named @file{image-type.c}, you will
need to execute the following command to compile this file:
@example
guile-snarf image-type.c > image-type.x
@end example
@noindent This scans @file{image-type.c} for @code{SCM_PROC}
declarations, and sends the following output to the file
@file{image-type.x}:
@example
scm_make_gsubr (s_clear_image, 1, 0, 0, clear_image);
@end example
When compiled normally, @code{SCM_PROC} is a macro which expands to a
declaration of the @code{s_clear_image} string.
In other words, @code{guile-snarf} scans source code looking for uses of
the @code{SCM_PROC} macro, and generates C code to define the
appropriate subrs. You need to provide all the same information you
would if you were using @code{scm_make_gsubr} yourself, but you can
place the information near the function definition itself, so it is less
likely to become incorrect or out-of-date.
If you have many files that @code{guile-snarf} must process, you should
consider using a rule like the following in your Makefile:
@example
.SUFFIXES: .x
.c.x:
./guile-snarf $(DEFS) $(INCLUDES) $(CPPFLAGS) $(CFLAGS) $< > $@
@end example
This tells make to run @code{guile-snarf} to produce each needed
@file{.x} file from the corresponding @file{.c} file.
@code{guile-snarf} passes all its command-line arguments directly to the
C preprocessor, which it uses to extract the information it needs from
the source code. this means you can pass normal compilation flags to
@code{guile-snarf} to define preprocessor symbols, add header file
directories, and so on.
@node Macros guile-snarf recognizes
@subsection Macros @code{guile-snarf} recognizes
Here are the macros you can use in your source code from which
@code{guile-snarf} can construct initialization code:
@defmac SCM_PROC (@var{namestr}, @var{name}, @var{req}, @var{opt}, @var{tail}, @var{c_func})
Declare a new Scheme primitive function, or @dfn{subr}. The new subr
will be named @var{name} in Scheme code, and be implemented by the C
function @var{c_func}. The subr will take @var{req} required arguments
and @var{opt} optional arguments. If @var{tail} is non-zero, the
function will accept any remaining arguments as a list.
Use this macro outside all function bodies, preferably above the
definition of @var{c_func} itself. When compiled, the @code{SCM_PROC}
declaration will expand to a definition for the @var{namestr} array,
initialized to @var{name}. The @code{guile-snarf} command uses this
declaration to automatically generate initialization code to create the
subr and bind it in the top-level environment. @xref{How guile-snarf
works}, for more info.
@xref{Subrs}, for details on argument passing and how to write
@var{c_func}.
@end defmac
@defmac SCM_GLOBAL (@var{var}, @var{scheme_name})
Declare a global Scheme variable named @var{scheme_name}, and a static C
variable named @var{var} to point to it. The value of the Scheme
variable lives in the @sc{cdr} of the cell @var{var} points to.
Initialize the variable to @code{#f}.
Use this macro outside all function bodies. When compiled, the
@code{SCM_GLOBAL} macro will expand to a definition for the variable
@var{var}, initialized to an innocuous value. The @code{guile-snarf}
command will use this declaration to automatically generate code to
create a global variable named @var{scheme_name}, and store a pointer to
its cell in @var{var}.
@end defmac
@defmac SCM_CONST_LONG (@var{var}, @var{scheme_name}, @var{value})
Like @code{SCM_GLOBAL}, but initialize the variable to @var{value},
which must be an integer.
@end defmac
@defmac SCM_SYMBOL (@var{var}, @var{name})
Declare a C variable of type @code{SCM} named @var{var}, and initialize
it to the Scheme symbol object whose name is @var{name}.
Use this macro outside all function bodies. When compiled, the
@code{SCM_SYMBOL} macro will expand to a definition for the variable
@var{var}, initialized to an innocuous value. The @code{guile-snarf}
command will use this declaration to automatically generate code to
create a symbol named @var{name}, and store it in @var{var}.
@end defmac
@node Automatically using libtool
@section Automatically using libtool
@node Automatically using SWIG
@section Automatically using SWIG

View file

@ -1,2 +0,0 @@
@node Adding types to Guile
@chapter Adding types to Guile

View file

@ -1,290 +0,0 @@
@node Introduction
@chapter Introduction
Guile is an interpreter for Scheme, a clean, economical programming
language in the Lisp family. You can invoke Guile from the shell to
evaluate Scheme expressions interactively, or use it as an interpreter
for script files. However, Guile is also packaged as a library, to be
embedded as an extension language into other applications. The
application can supplement the base language with special-purpose
functions and datatypes, allowing the user to customize and extend it by
writing Scheme code.
In its simplest form, Guile is an ordinary interpreter. The
@code{guile} program can read and evaluate Scheme expressions entered
from the terminal. Here is a sample interaction between Guile and a
user; the user's input appears after the @code{$} and @code{guile>}
prompts:
@example
$ guile
guile> (+ 1 2 3) ; add some numbers
6
guile> (define (factorial n) ; define a function
(if (zero? n) 1 (* n (factorial (- n 1)))))
guile> (factorial 20)
2432902008176640000
guile> (getpwnam "jimb") ; find my entry in /etc/passwd
#("jimb" ".0krIpK2VqNbU" 4008 10 "Jim Blandy" "/u/jimb"
"/usr/local/bin/bash")
guile> @kbd{C-d}
$
@end example
Guile can also interpret script files. For example, here is a Guile script
containing a script which displays the
application can
supplement the base language with its own functions, datatypes and
syntax, allowing the user to extend and
Guile interpret
. An
application the Guile interpreter to allow
, allowing
applications to incorporate the Scheme interpreter for customization
[[interactive]]
[[script interpreter]]
[[embedded]]
[[other languages]]
The concept of an extension language library does not originate with
Guile. However, Guile is the first to offer users a choice of languages
to program in.
Guile currently supports Scheme and Ctax , and we expect to support Emacs Lisp in the near future.
Scheme is powerful enough that other languages can be
conveniently translated into it,
However, unlike other extension packages, Guile gives users a choice of
languages to program in. Guile can
In this sense, Guile resembles the Tcl and Python packages, providing
both an ordinary interpreter and an extension language library.
However, unlike those packages, Guile supports more than one programming
language.
; users can
write Scheme code to control and customize applications which
incorporate Guile
, adding their own functions,
datatypes, and syntax, to allow the user to programm
link it into your own programs to make them
Guile is a library containing an interpreter for Scheme, a complete but
economical programming language, which the developer can customize to
suit the application at hand by adding new functions, data types, and
control structures. These may be implemented in C, and then
``exported'' for use by the interpreted code. Because Guile already
provides a full-featured interpreter, the developer need not neglect the
language's design in order to concentrate on code relevant to the task.
In this way, Guile provides a framework for the construction of
domain-specific languages.
Guile provides first-class functions, a rich set of data types,
exception handling, a module system, and a powerful macro facility.
Guile also supports dynamic linking and direct access to Unix system
calls. Releases in the near future will support a source-level
debugger and bindings for the Tk user interface toolkit.
Guile is a framework for writing applications controlled by specialized
languages. In its simplest form, Guile is an interpreter for Scheme, a
clean, economical programming language in the Lisp family. However,
Guile is packaged as a library, allowing applications to link against it
and use Scheme as their extension language. The application can add
primitive functions to the language, implement new data types, and even
adjust the language's syntax.
[the introduction is probably not what Jim has in mind; I just took the
one I had in earlier, since the file had the same name intro.texi]
Guile is an implementation of the Scheme programming language, but, like
other modern implementations of Scheme, it adds many features that the
community of Scheme programmers considers necessary for an ``industrial
strength'' language.
Examples of extensions to Scheme are the module system
(@pxref{Modules}), the Unix system programming tools (@pxref{POSIX
system calls and networking} and @pxref{The Scheme shell (scsh)}), an
interface to @emph{libtool} to make it easier to add C libraries as
primitives (@pxref{Linking Guile with your code}), and (FIXME add more).
On top of these extensions, which many other Scheme implementations
provide, Guile also offers the possibility of writing routines in other
languages and running them simultaneously with Scheme. The desire to
implement other languages (in particular Emacs Lisp) on top of Scheme is
responsible for Guile's only deviation from the R4RS @footnote{R4RS is
the Revised^4 Report on the Algorithmic Language Scheme, the closest
thing to a standard Scheme specification today} Scheme standard
(@cite{r4rs}): Guile is case sensitive, whereas ``standard'' Scheme is
not.
But even more fundamentally, Guile is meant to be an @emph{embeddable}
Scheme interpreter. This means that a lot of work has gone into
packaging the interpreter as a C library (@pxref{A Portable C to Scheme Interface} and @pxref{Scheme data representation}).
This reference manual is mainly driven by the need to document all the
features that go beyond standard Scheme.
@menu
* Getting started::
* Guile feature list::
* What you need to use Guile::
* Roadmap to the Manual::
* Motivation for Guile::
* History of Guile::
@end menu
@node Getting started
@section Getting started
We assume that you know how to program in Scheme, although we do not
assume advanced knowledge. If you don't know Scheme, there are many
good books on Scheme at all levels, and the Guile Tutorial might give
you a good enough feel for the language. We also assume that you know
how to program in C, since there will be many examples of how to program
in C using Guile as a library.
Many diverse topics from the world of Unix hacking will be covered here,
such as shared libraries, socket programming, garbage collection, and so
forth. If at any time you feel you don't have enough background on a
given topic, just go up a level or two in the manual, and you will find
that the chapter begins with a few paragraphs that introduce the topic.
If you are still lost, read through the Guile tutorial and then come
back to this reference manual.
To run the core Guile interpreter and extension library you need no more
than a basically configured GNU/Unix system and the Guile sources. You
should download and install the Guile sources (@pxref{Obtaining and
Installing Guile}).
@node Guile feature list
@section Guile feature list
In a reductionist view, Guile could be regarded as:
@itemize @bullet
@item
An R4RS-compliant Scheme interpreter.
@item
Some Scheme features that go beyond the R4RS standard, notably a module
system, exception handling primitives and an interface to Aubrey
Jaffer's SLIB.
@item
A symbolic debugger for Scheme, and gdb extensions to facilitate
debugging libguile programs.
@item
An embeddable version of the same interpreter, called @emph{libguile}.
@item
A portable high level API on top of libguile (the @code{gh_} interface).
@item
A collection of bundled C libraries with a Guile API. As we write, this
list includes:
@table @strong
@item Rx
a regular expression library.
@item Unix
a low-level interface to the POSIX system calls, socket library
and other Unix system services.
@item Tk
an interface to John Ousterhout's Tk toolkit.
@end table
@item
A set of tools for implementing other languages @emph{on top of Scheme},
and an example implementation of a language called @emph{Ctax}.
@end itemize
@node What you need to use Guile
@section What you need to use Guile
@node Roadmap to the Manual
@section Roadmap to the Manual
@node Motivation for Guile
@section Motivation for Guile
@node History of Guile
@section History of Guile
@page
@node Using Guile
@chapter Using Guile
[I think that this might go in the appendix in Jim's view of the manual]
@page
@node Invoking Guile
@appendix Invoking Guile
--- mentions read-eval-print loops
--- both the SCSH and GAWK manuals relegate invocation details
to an appendix. We can give examples in the introduction.
@table @samp
@item -h
@itemx --help
Display a helpful message.
@item -v
@item --version
Display the current version.
@item --emacs
To be used for emacs editing support.
@item -s @var{file}
Process @var{file} as a script then quit. This is a terminating option:
any further command line arguments can be accessed by the script using
the @code{(program-arguments)} procedure.
An executable script can start with the following:
@smallexample
#!/usr/bin/guile -s
!#
@end smallexample
Note the @code{!#} token on the second line. It is very important
to include this token when writing Guile scripts. Guile and SCSH,
the Scheme shell, share the convention that @code{#!} and
@code{!#} may be used to mark block comments (@pxref{Block
comments and interpreter triggers}). If the closing @code{!#}
token is not included, then Guile will consider the block comment
to be unclosed, and the script will probably not compile
correctly.
It is also important to include the @samp{-s} option at the
beginning of the Guile script, so that Guile knows not to behave
in an interactive fashion.
@end table

View file

@ -1,6 +0,0 @@
@node Examples of adding libraries
@chapter Examples of adding libraries
Should contain examples of brute-force gh_, Guile magic snarfer,
libtool, SWIG on a dummy API, followed by some real examples of how
libraries are added.

View file

@ -1,249 +0,0 @@
@node Guile Scheme concepts
@chapter Guile Scheme concepts
Most Scheme implementations go beyond what is specified in the R4RS
document @footnote{Remember? R4RS is the Revised^4 report on the
Algorithmic Language Scheme}, mostly because R4RS does not give
specifications (or even recommendations) regarding some issues that are
quite important in practical programming.
Here is a list of how Guile implements some of these much-needed Scheme
extensions; other Scheme implementations do so quite similarly.
@menu
* Scheme slang::
* Read-eval-print loops::
* Extra data types::
* Miscellaneous features::
@end menu
@node Scheme slang
@section Scheme slang
@cindex slang
Even if you read some of the nice books on Scheme, or the R4RS report,
you might not find some of the terms frequently used by Scheme hackers,
both in the manual and in the @url{news:comp.lang.scheme} newsgroup.
Here is a glossary of some of the terms that make Scheme beginners and
intermediate users say ``huh?''
@table @strong
@item thunk
@cindex thunk
A Scheme procedure that takes no arguments. In this example,
@code{thunk} and @code{another-thunk} are both thunks:
@lisp
(define (thunk)
(display "Dude, I'm a thunk!")
(newline))
(define another-thunk
(lambda ()
(display "Me too!\n")
(newline)))
@end lisp
@item closure
@cindex closure
A closure is a procedure. However, the term emphasizes the fact that a
Scheme procedure remembers (or @dfn{closes over}) the variables that
were visible when the @code{lambda} expression was
evaluated.
In the example below, we might refer to @code{q} as a closure, because
it has closed over the value of @code{x}:
@lisp
(define p
(lambda (x)
(lambda (y)
(+ x y))))
(define q (p 5.7))
(q 10)
@result{} 15.7
@end lisp
However, strictly speaking, every Scheme procedure is really a closure,
since it closes over the top-level environment.
@item alist
@itemx association list
@item plist
@itemx property list
@end table
@node Read-eval-print loops
@section Read-eval-print loops
@cindex Read-eval-print loop
@cindex REPL
To explicitly mention the Scheme read-eval-print loop (REPL) seems weird
because we are all accustomed to firing up an interpreter and having it
read and execute commands.
But the REPL is not specified in R4RS; rather, it is proposed by the
Scheme Bible @cite{Structure and Interpretation of Computer Programs}
(also known as @emph{SICP}), and implemented in some form in all Scheme
interpreters.
@cindex Structure and Interpretation of Computer Programs
@cindex SICP
[FIXME: Someone needs to tell me what needs to be said about Guile's
REPL.]
@node Extra data types
@section Extra data types
The fundamental Scheme data types specified in R4RS are @emph{numbers}
(both exact and inexact), @emph{characters}, @emph{strings},
@emph{symbols}, @emph{vectors}, @emph{pairs} and @emph{lists} [FIXME: is
this complete?].
Many Scheme interpreters offer more types, and Guile is no exception.
Guile is based on Aubrey Jaffer's SCM interpreter, and thus inherits
@emph{uniform arrays}, [FIXME: any others? How about records?].
On top of that, Guile allows you to add extra types, but that is covered
in @ref{Adding types to Guile}. Here I will simply document all the
extra Scheme types shipped with Guile.
@menu
* Conventional arrays::
* Uniform arrays::
* Bit vectors::
* Complex numbers::
@end menu
@node Conventional arrays
@subsection Conventional arrays
@node Uniform arrays
@subsection Uniform arrays
@cindex arrays - uniform
The motivation for uniform arrays in Scheme is performance. A vector
provides a performance increase over lists when you want a fixed-size
indexable list. But the elements in a vector can be of different types,
and this makes for larger storage requirements and slightly lower
performance.
A uniform array is similar to a vector, but all elements have to be of
the same type.
arrays, uniform arrays, bit vectors:
@deffn procedure array-fill ra fill
@end deffn
@deffn procedure serial-array-copy! src dst
@end deffn
@deffn procedure serial-array-map ra0 proc [lra]
@end deffn
@deffn procedure array-map ra0 proc [lra]
@end deffn
@deffn procedure array-for-each proc ra0 [lra]
@end deffn
@deffn procedure array-index-map! ra proc
@end deffn
@deffn procedure array-copy! src dst
@end deffn
@deffn procedure array-copy! src dst
@end deffn
@deffn procedure array-copy! src dst
@end deffn
@deffn procedure array-copy! src dst
@end deffn
@deffn procedure array-copy! src dst
@end deffn
@deffn procedure array? ra [prot]
@end deffn
@deffn procedure array-rank ra
@end deffn
@deffn procedure array-dimensions ra
@end deffn
@deffn procedure dimensions->uniform-array dims prot fill ...
@end deffn
@deffn procedure make-shared-array ra mapfunc dims ...
@end deffn
@deffn procedure transpose-array arg ...
@end deffn
@deffn procedure enclose-array axes ...
@end deffn
@deffn procedure array-in-bounds? arg ...
@end deffn
@deffn procedure array-ref ra arg ..
@end deffn
@deffn procedure uniform-vector-ref vec pos
@end deffn
@deffn procedure array-set! ra obj arg ...
@end deffn
@deffn procedure uniform-array-set1! ua obj arg
@end deffn
@deffn procedure array-contents ra [strict]
@end deffn
@deffn procedure uniform-array-read! ra [port-or-fd] [start] [end]
@end deffn
@deffn procedure uniform-array-write! ra [port-or-fd] [start] [end]
@end deffn
@deffn procedure bit-count item seq
@end deffn
@deffn procedure bit-position item v k
@end deffn
@deffn procedure bit-set! v kv obj
@end deffn
@deffn procedure bit-count* v kv obj
@end deffn
@deffn procedure bit-invert v
@end deffn
@deffn procedure array->list ra
@end deffn
@deffn procedure list->uniform-array ndim prot list
@end deffn
@deffn procedure array-prototype ra
@end deffn
Uniform arrays can be written and read, but @code{read} won't recognize
them unless the optional @code{read-sharp} parameter is supplied,
e.g,
@smalllisp
(read port #t read-sharp)
@end smalllisp
where @code{read-sharp} is the default procedure for parsing extended
sharp notations.
Reading an array is not very efficient at present, since it's implemented
by reading a list and converting the list to an array.
@c FIXME: must use @deftp, but its generation of TeX code is buggy.
@c Must fix it when TeXinfo gets fixed.
@deftp {Scheme type} {uniform array}
@end deftp
@node Bit vectors
@subsection Bit vectors
@node Complex numbers
@subsection Complex numbers
@c FIXME: must use @deftp, but its generation of TeX code is buggy.
@c Must fix it when TeXinfo gets fixed.
@deftp {Scheme type} complex
Standard complex numbers.
@end deftp
@node Miscellaneous features
@section Miscellaneous features
@defun defined? symbol
Returns @code{#t} if a symbol is bound to a value, @code{#f} otherwise.
This kind of procedure is not specified in R4RS because @c FIXME: finish
this thought
@end defun
@defun object-properties OBJ
and so forth
@end defun

View file

@ -1,4 +0,0 @@
@node Libguile -- SCM interface
@chapter Libguile -- SCM interface

View file

@ -1,45 +0,0 @@
@node Strings
@chapter Facilities for string manipulation
@deffn procedure string? string
@end deffn
@deffn procedure read-only-string? string
@end deffn
@deffn procedure list->string list
@end deffn
@deffn procedure make-string length [char]
@end deffn
@deffn procedure string-length string
@end deffn
@deffn procedure string-ref string [index]
@end deffn
@deffn procedure string-set! string index char
@end deffn
@deffn procedure substring string start [end]
@end deffn
@deffn procedure string-append arg ...
@end deffn
@deffn procedure make-shared-substring string [from] [to]
@end deffn
@deffn procedure string-set! string index char
@end deffn
@deffn procedure string-index string char [from] [to]
@end deffn
@deffn procedure string-rindex string char [from] [to]
@end deffn
@deffn procedure substring-move-left! string1 start1 [end1] [string2] [start2]
@end deffn
@deffn procedure substring-move-right! string1 start1 [end1] [string2] [start2]
@end deffn
@deffn procedure substring-fill! string start [end] [fill]
@end deffn
@deffn procedure string-null? string
@end deffn
@deffn procedure string->list string
@end deffn
@deffn procedure string-copy string
@end deffn
@deffn procedure string-upcase! string
@end deffn
@deffn procedure string-downcase! string
@end deffn

View file

@ -1,5 +0,0 @@
@node Tk interface
@chapter Tk interface
For now Guile has no well-specified Tk interface. It is an important part
of Guile, though, and will be documented here when it is written.

View file

@ -1,132 +0,0 @@
@node Other Unix
@chapter Other Unix-specific facilities
@menu
* Expect:: Expect, for pattern matching from a port.
@end menu
@node Expect
@section Expect: Pattern Matching from a Port
@code{expect} is a macro for selecting actions based on the output from
a port. The name comes from a tool of similar functionality by Don Libes.
Actions can be taken when a particular string is matched, when a timeout
occurs, or when end-of-file is seen on the port. The @code{expect} macro
is described below; @code{expect-strings} is a front-end to @code{expect}
based on regexec @xref{Regular expressions}.
Using these macros requires for now:
@smalllisp
(load-from-path "ice-9/expect")
@end smalllisp
@defun expect-strings clause @dots{}
By default, @code{expect-strings} will read from the current input port.
The first term in each clause consists of an expression evaluating to
a string pattern (regular expression). As characters
are read one-by-one from the port, they are accumulated in a buffer string
which is matched against each of the patterns. When a
pattern matches, the remaining expression(s) in
the clause are evaluated and the value of the last is returned. For example:
@smalllisp
(with-input-from-file "/etc/passwd"
(lambda ()
(expect-strings
("^nobody" (display "Got a nobody user.\n")
(display "That's no problem.\n"))
("^daemon" (display "Got a daemon user.\n")))))
@end smalllisp
The regular expression is compiled with the @code{REG_NEWLINE} flag, so
that the @code{^} and @code{$} anchors will match at any newline, not
just at the start
and end of the string.
There are two other ways to write a clause:
The expression(s) to evaluate on a match
can be omitted, in which case the result of the match
(converted to strings, as obtained from regexec with @var{match-pick}
set to @code{""}) will be returned if the pattern matches.
The symbol @code{=>} can be used to indicate that there is a single
expression to evaluate on a match, which must be a
procedure which will accept the result of a successful match (converted
to strings, as obtained from regexec with @var{match-pick} set to
@code{""}). E.g.,
@smalllisp
("^daemon" => write)
("^d\\(aemon\\)" => (lambda args (map write args)))
("^da\\(em\\)on" => (lambda (all sub)
(write all)
(write sub)))
@end smalllisp
The order of the substrings corresponds to the order in which the
opening brackets occur in the regular expression.
A number of variables can be used to control the behaviour
of @code{expect} (and @code{expect-strings}).
By default they are all bound at the top level to
the value @code{#f}, which produces the default behaviour.
They can be redefined at the
top level or locally bound in a form enclosing the @code{expect} expression.
@table @code
@item expect-port
A port to read characters from, instead of the current input port.
@item expect-timeout
@code{expect} will terminate after this number of
seconds, returning @code{#f} or the value returned by
@code{expect-timeout-proc}.
@item expect-timeout-proc
A procedure called if timeout occurs. The procedure takes a single argument:
the accumulated string.
@item expect-eof-proc
A procedure called if end-of-file is detected on the input port. The
procedure takes a single argument: the accumulated string.
@item expect-char-proc
A procedure to be called every time a character is read from the
port. The procedure takes a single argument: the character which was read.
@end table
Here's an example using all of the variables:
@smalllisp
(let ((expect-port (open-input-file "/etc/passwd"))
(expect-timeout 1)
(expect-timeout-proc
(lambda (s) (display "Times up!\n")))
(expect-eof-proc
(lambda (s) (display "Reached the end of the file!\n")))
(expect-char-proc display))
(expect-strings
("^nobody" (display "Got a nobody user\n"))))
@end smalllisp
@end defun
@defun expect clause @dots{}
@code{expect} is used in the same way as @code{expect-strings},
but tests are specified not as patterns, but as procedures. The
procedures are called in turn after each character is read from the
port, with the value of the accumulated string as the argument. The
test is successful if the procedure returns a non-false value.
If the @code{=>} syntax is used, then if the test succeeds it must return
a list containing the arguments to be provided to the corresponding
expression.
In the following example, a string will only be matched at the beginning
of the file:
@smalllisp
(let ((expect-port (open-input-file "/etc/passwd")))
(expect
((lambda (s) (string=? s "fnord!"))
(display "Got a nobody user!\n"))))
@end smalllisp
The control variables described for @code{expect-strings} can also
be used with @code{expect}.
@end defun

View file

@ -1,622 +0,0 @@
@node Low level Unix
@chapter Low level Unix interfaces
The low level Unix interfaces are currently available by
default in the Guile top level. However in the future they will probably
be placed in a module and @code{use-modules} or something similar will
be required to make them available.
@menu
* Unix conventions:: Conventions followed by the low level Unix
interfaces.
* Ports and descriptors:: Ports, file descriptors and how they
interact.
* Extended I/O:: Reading and writing to ports.
* File system:: Working in a hierarchical file system.
* User database:: Information about users from system databases.
* Processes:: Information and control of Unix processes.
* Terminals:: Terminals and pseudo-terminals.
* Network databases:: Network address conversion and information
from system databases.
* Network sockets:: An interface to the BSD socket library.
* Miscellaneous Unix:: Miscellaneous Unix interfaces.
@end menu
@node Unix conventions
@section Low level Unix conventions
The low-level interfaces are designed to give Scheme programs
access to as much functionality as possible from the underlying
Unix system. They can be used to implement higher level
interfaces such as the Scheme shell @ref{scsh}.
Generally there is a single procedure for each corresponding Unix
facility. However some of the procedures are implemented for
speed and convenience in Scheme and have no Unix equivalent
(e.g., @code{read-delimited}, @code{copy-file}.)
This interface is intended as far as possible to be portable across
different versions of Unix, so that Scheme programmers don't need to be
concerned with implementation differences. In some cases procedures
which can't be implemented (or reimplemented) on particular systems may
become no-ops, or perform limited actions. In other cases they may
throw errors. It should be possible to use the feature system to
determine what functionality is available.
General naming conventions are as follows:
@itemize @bullet
@item
The Scheme name is often identical to the name of the underlying Unix
facility.
@item
Underscores in Unix names are converted to hyphens.
@item
Procedures which destructively modify Scheme data gain appended
exclamation marks, e.g., @code{recv!}.
@item
Predicates have question marks appended, e.g., @code{access?}.
@item
Some names are changed to avoid conflict with dissimilar interfaces
defined by scsh.
@item
Unix preprocessor names such as @code{EPERM} or @code{R_OK} are converted
to Scheme variables of the same name (underscores are not replaced
with hyphens)
@end itemize
Most of the Unix interface procedures can be relied on to return a
well-specified value. Unexpected conditions are handled by raising
exceptions.
There are a few procedures which return a special
value if they don't succeed, e.g., @code{getenv} returns @code{#f}
if it the requested string is not found in the environment. These
cases will be noted in the documentation.
For ways to deal with exceptions, @ref{Exceptions}.
Errors which the C-library would report by returning a NULL
pointer or through some other means cause a @code{system-error} exception
to be raised. The value of the Unix @code{errno} variable is available
in the data passed by the exception, so there is no need to access the
global errno value (doing so would be unreliable in the presence of
continuations or multiple threads).
@deffn procedure errno [n]
@end deffn
@deffn procedure perror string
@end deffn
@node Ports and descriptors
@section Ports and file descriptors
@deffn procedure move->fdes port fd
@end deffn
@deffn procedure release-port-handle port
@end deffn
@deffn procedure set-port-revealed! @var{port} count
@end deffn
@deffn procedure fdes->ports fdes
@end deffn
@deffn procedure fileno port
@end deffn
@deffn procedure fdopen fdes modes
@end deffn
@deffn procedure duplicate-port port modes
@end deffn
@deffn procedure redirect-port into-port from-port
@end deffn
@deffn procedure freopen filename modes port
@end deffn
@node Extended I/O
@section Extended I/O
Extended I/O procedures are available which read or write lines of text,
read text delimited by a specified set of characters, or report or
set the current position of a port.
@findex fwrite
@findex fread
Interfaces to @code{read}/@code{fread} and @code{write}/@code{fwrite} are
also available, as @code{uniform-array-read!} and @code{uniform-array-write!},
@ref{Uniform arrays}.
@deffn procedure read-line [port] [handle-delim]
Return a line of text from @var{port} if specified, otherwise from the
value returned by @code{(current-input-port)}. Under Unix, a line of text
is terminated by the first end-of-line character or by end-of-file.
If @var{handle-delim} is specified, it should be one of the following
symbols:
@table @code
@item trim
Discard the terminating delimiter. This is the default, but it will
be impossible to tell whether the read terminated with a delimiter or
end-of-file.
@item concat
Append the terminating delimiter (if any) to the returned string.
@item peek
Push the terminating delimiter (if any) back on to the port.
@item split
Return a pair containing the string read from the port and the
terminating delimiter or end-of-file object.
NOTE: if the scsh module is loaded then
multiple values are returned instead of a pair.
@end table
@end deffn
@deffn procedure read-line! buf [port]
Read a line of text into the supplied string @var{buf} and return the
number of characters added to @var{buf}. If @var{buf} is filled, then
@code{#f} is returned.
Read from @var{port} if
specified, otherwise from the value returned by @code{(current-input-port)}.
@end deffn
@deffn procedure read-delimited delims [port] [handle-delim]
Read text until one of the characters in the string @var{delims} is found
or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
@var{handle-delim} takes the same values as described for @code{read-line}.
NOTE: if the scsh module is loaded then @var{delims} must be an scsh
char-set, not a string.
@end deffn
@deffn procedure read-delimited! delims buf [port] [handle-delim] [start] [end]
Read text into the supplied string @var{buf} and return the number of
characters added to @var{buf} (subject to @var{handle-delim}, which takes
the same values specified for @code{read-line}. If @var{buf} is filled,
@code{#f} is returned for both the number of characters read and the
delimiter. Also terminates if one of the characters in the string
@var{delims} is found
or end-of-file is reached. Read from @var{port} if supplied, otherwise
from the value returned by @code{(current-input-port)}.
NOTE: if the scsh module is loaded then @var{delims} must be an scsh
char-set, not a string.
@end deffn
@deffn procedure write-line obj [port]
Display @var{obj} and a new-line character to @var{port} if specified,
otherwise to the
value returned by @code{(current-output-port)}; equivalent to:
@smalllisp
(display obj [port])
(newline [port])
@end smalllisp
@end deffn
@deffn procedure ftell port
Returns an integer representing the current position of @var{port},
measured from the beginning.
@end deffn
@deffn procedure fseek port offset whence
Sets the current position of @var{port} to the integer @var{offset},
which is interpreted according to the value of @var{whence}.
One of the following variables should be supplied
for @var{whence}:
@defvar SEEK_SET
Seek from the beginning of the file.
@end defvar
@defvar SEEK_CUR
Seek from the current position.
@end defvar
@defvar SEEK_END
Seek from the end of the file.
@end defvar
@end deffn
@node File system
@section File system
These procedures query and set file system attributes (such as owner,
permissions, sizes and types of files); deleting, copying, renaming and
linking files; creating and removing directories and querying their
contents; and the @code{sync} interface.
@deffn procedure access? path how
Evaluates to @code{#t} if @var{path} corresponds to an existing
file and the current process
has the type of access specified by @var{how}, otherwise
@code{#f}.
@var{how} should be specified
using the values of the variables listed below. Multiple values can
be combined using a bitwise or, in which case @code{#t} will only
be returned if all accesses are granted.
Permissions are checked using the real id of the current process,
not the effective id, although it's the effective id which determines
whether the access would actually be granted.
@defvar R_OK
test for read permission.
@end defvar
@defvar W_OK
test for write permission.
@end defvar
@defvar X_OK
test for execute permission.
@end defvar
@defvar F_OK
test for existence of the file.
@end defvar
@end deffn
@findex fstat
@deffn procedure stat obj
Evaluates to an object containing various information
about the file determined by @var{obj}.
@var{obj} can be a string containing a file name or a port or file
descriptor which is open on a file (in which case @code{fstat} is used
as the underlying system call).
The object returned by @code{stat} can be passed as a single parameter
to the following procedures, all of which return integers:
@table @r
@item stat:dev
The device containing the file.
@item stat:ino
The file serial number, which distinguishes this file from all other
files on the same device.
@item stat:mode
The mode of the file. This includes file type information
and the file permission bits. See @code{stat:type} and @code{stat:perms}
below.
@item stat:nlink
The number of hard links to the file.
@item stat:uid
The user ID of the file's owner.
@item stat:gid
The group ID of the file.
@item stat:rdev
Device ID; this entry is defined only for character or block
special files.
@item stat:size
The size of a regular file in bytes.
@item stat:atime
The last access time for the file.
@item stat:mtime
The last modification time for the file.
@item stat:ctime
The last modification time for the attributes of the file.
@item stat:blksize
The optimal block size for reading or writing the file, in bytes.
@item stat:blocks
The amount of disk space that the file occupies measured in units of
512 byte blocks.
@end table
In addition, the following procedures return the information
from stat:mode in a more convenient form:
@table @r
@item stat:type
A symbol representing the type of file. Possible values are
currently: regular, directory, symlink, block-special, char-special,
fifo, socket, unknown
@item stat:perms
An integer representing the access permission bits.
@end table
@end deffn
@deffn procedure lstat path
Similar to @code{stat}, but does not follow symbolic links, i.e.,
it will return information about a symbolic link itself, not the
file it points to. @var{path} must be a string.
@end deffn
@deffn procedure readlink path
@end deffn
@deffn procedure chown path owner group
@end deffn
@deffn procedure chmod port-or-path mode
@end deffn
@deffn procedure utime path [actime] [modtime]
@end deffn
@deffn procedure delete-file path
@end deffn
@deffn procedure copy-file path-from path-to
@end deffn
@deffn procedure rename-file path-from path-to
@end deffn
@deffn procedure link path-from path-to
@end deffn
@deffn procedure symlink path-from path-to
@end deffn
@deffn procedure mkdir path [mode]
@end deffn
@deffn procedure rmdir path
@end deffn
@deffn procedure opendir path
@end deffn
@deffn procedure readdir port
@end deffn
@deffn procedure rewinddir port
@end deffn
@deffn procedure closedir port
@end deffn
@deffn procedure sync
@end deffn
@node User database
@section User database
@deffn procedure getpwuid uid
@end deffn
@deffn procedure getpwnam name
@end deffn
@deffn procedure getpwent
@end deffn
@deffn procedure setpwent port
@end deffn
@deffn procedure endpwent
@end deffn
@deffn procedure getgrgid uid
@end deffn
@deffn procedure getgrnam name
@end deffn
@deffn procedure getgrent
@end deffn
@deffn procedure setgrent port
@end deffn
@deffn procedure endgrent
@end deffn
@node Processes
@section Processes
@deffn procedure chdir path
@end deffn
@deffn procedure getcwd
@end deffn
@deffn procedure umask [mode]
@end deffn
@deffn procedure getpid
@end deffn
@deffn procedure getgroups
@end deffn
@deffn procedure kill pid sig
@var{sig} should be specified using a variable corresponding to
the Unix symbolic name, e.g,
@defvar SIGHUP
Hang-up signal.
@end defvar
@defvar SIGINT
Interrupt signal.
@end defvar
@end deffn
@deffn procedure waitpid pid options
@defvar WAIT_ANY
@end defvar
@defvar WAIT_MYPGRP
@end defvar
@defvar WNOHANG
@end defvar
@defvar WUNTRACED
@end defvar
@end deffn
@deffn procedure getppid
@end deffn
@deffn procedure getuid
@end deffn
@deffn procedure getgid
@end deffn
@deffn procedure geteuid
@end deffn
@deffn procedure getegid
@end deffn
@deffn procedure setuid id
@end deffn
@deffn procedure setgid id
@end deffn
@deffn procedure seteuid id
@end deffn
@deffn procedure setegid id
@end deffn
@deffn procedure getpgrp
@end deffn
@deffn procedure setpgid pid pgid
@end deffn
@deffn procedure setsid
@end deffn
@deffn procedure execl arg ...
@end deffn
@deffn procedure execlp arg ...
@end deffn
@deffn procedure primitive-fork
@end deffn
@deffn procedure environ [env]
@end deffn
@deffn procedure putenv string
@end deffn
@deffn procedure nice incr
@end deffn
@node Terminals
@section Terminals and pseudo-terminals
@deffn procedure isatty? port
@end deffn
@deffn procedure ttyname port
@end deffn
@deffn procedure ctermid
@end deffn
@deffn procedure tcgetpgrp port
@end deffn
@deffn procedure tcsetpgrp port pgid
@end deffn
@node Network databases
@section Network address conversion and system databases
@deffn procedure inet-aton address
@end deffn
@deffn procedure inet-ntoa number
@end deffn
@deffn procedure inet-netof address
@end deffn
@deffn procedure inet-lnaof address
@end deffn
@deffn procedure inet-makeaddr net lna
@end deffn
@deffn procedure gethostbyname name
@end deffn
@deffn procedure gethostbyaddr address
@end deffn
@deffn procedure gethostent
@end deffn
@deffn procedure sethostent port
@end deffn
@deffn procedure endhostent
@end deffn
@deffn procedure getnetbyname name
@end deffn
@deffn procedure getnetbyaddr address
@end deffn
@deffn procedure getnetent
@end deffn
@deffn procedure setnetent port
@end deffn
@deffn procedure endnetent
@end deffn
@deffn procedure getprotobyname name
@end deffn
@deffn procedure getprotobynumber number
@end deffn
@deffn procedure getprotoent
@end deffn
@deffn procedure setprotoent port
@end deffn
@deffn procedure endprotoent
@end deffn
@deffn procedure getservbyname name protocol
@end deffn
@deffn procedure getservbyport port protocol
@end deffn
@deffn procedure getservent
@end deffn
@deffn procedure setservent port
@end deffn
@deffn procedure endservent
@end deffn
@node Network sockets
@section BSD socket library interface
@deffn procedure socket family style protocol
@end deffn
@deffn procedure socketpair family style protocol
@end deffn
@deffn procedure getsockopt socket level optname
@end deffn
@deffn procedure setsockopt socket level optname value
@end deffn
@deffn procedure shutdown socket how
@end deffn
@deffn procedure connect socket family address arg ...
@end deffn
@deffn procedure bind socket family address arg ...
@end deffn
@deffn procedure listen socket backlog
@end deffn
@deffn procedure accept socket
@end deffn
@deffn procedure getsockname socket
@end deffn
@deffn procedure getpeername socket
@end deffn
@deffn procedure recv! socket buf [flags]
@end deffn
@deffn procedure send socket message [flags]
@end deffn
@deffn procedure recvfrom! socket buf [flags] [start] [end]
@end deffn
@deffn procedure sendto socket message family address args ... [flags]
@end deffn
@node Miscellaneous Unix
@section Miscellaneous Unix interfaces
Things which haven't been classified elsewhere (yet?).
@deffn procedure open path flags [mode]
@defvar O_RDONLY
@end defvar
@defvar O_WRONLY
@end defvar
@defvar O_RDWR
@end defvar
@defvar O_CREAT
@end defvar
@defvar O_EXCL
@end defvar
@defvar O_NOCTTY
@end defvar
@defvar O_TRUNC
@end defvar
@defvar O_APPEND
@end defvar
@defvar O_NONBLOCK
@end defvar
@defvar O_NDELAY
@end defvar
@defvar O_SYNC
@end defvar
@end deffn
@deffn procedure select reads writes excepts secs msecs
@end deffn
@deffn procedure uname
@end deffn
@deffn procedure pipe
@end deffn
@deffn procedure open-pipe command modes
@end deffn
@deffn procedure open-input-pipe command
@end deffn
@deffn procedure open-output-pipe command
@end deffn
@deffn procedure setlocale category [locale]
@defvar LC_COLLATE
@end defvar
@defvar LC_CTYPE
@end defvar
@defvar LC_MONETARY
@end defvar
@defvar LC_NUMERIC
@end defvar
@defvar LC_TIME
@end defvar
@defvar LC_MESSAGES
@end defvar
@defvar LC_ALL
@end defvar
@end deffn
@deffn procedure strftime format stime
@end deffn
@deffn procedure strptime format string
@end deffn
@deffn procedure mknod
@end deffn
@node scsh
@chapter The Scheme shell (scsh)
Guile includes an incomplete port of the Scheme shell (scsh) 0.4.4.
For information about scsh on the Web see
@url{http://www-swiss.ai.mit.edu/scsh/scsh.html}.
The original scsh is available by ftp from
@url{ftp://swiss-ftp.ai.mit.edu:/pub/su}.
This port of scsh does not currently use the Guile module system, but
can be initialized using:
@smalllisp
(load-from-path "scsh/init")
@end smalllisp
Note that SLIB must be installed before scsh can be initialized, see
@ref{SLIB} for details.
@node Threads
@chapter Programming Threads.