mirror of
https://git.savannah.gnu.org/git/guile.git
synced 2025-05-02 21:10:27 +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
parent
64de6db5c6
commit
c99acbf397
20 changed files with 0 additions and 3404 deletions
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
@node Debugging libguile
|
||||
@chapter Debugging libguile
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
@node Debugging Scheme programs
|
||||
@chapter Debugging Scheme programs
|
||||
1165
doc/sources/env.texi
1165
doc/sources/env.texi
File diff suppressed because it is too large
Load diff
|
|
@ -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
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
@node Guile and SLIB
|
||||
@chapter Guile and SLIB
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -1,2 +0,0 @@
|
|||
@node Adding types to Guile
|
||||
@chapter Adding types to Guile
|
||||
|
|
@ -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
|
||||
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -1,4 +0,0 @@
|
|||
@node Libguile -- SCM interface
|
||||
@chapter Libguile -- SCM interface
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
||||
Loading…
Add table
Add a link
Reference in a new issue