Changeset 8340 in project


Ignore:
Timestamp:
02/11/08 06:51:55 (12 years ago)
Author:
Ivan Raikov
Message:

Update of the Texinfo manual to 3.0.0

File:
1 edited

Legend:

Unmodified
Added
Removed
  • chicken/trunk/chicken.texi

    r5923 r8340  
    11\input texinfo @c -*- texinfo -*-
    2 @setfilename chicken.info
    32@settitle Chicken Scheme Reference Manual
    43@setchapternewpage on
    5 @ifinfo
    6 @format
    7 INFO-DIR-SECTION Programming
    8 START-INFO-DIR-ENTRY
    9 * Chicken: (chicken.info). A compiler that translates Scheme source files into C.
    10 END-INFO-DIR-ENTRY
    11 @end format
    12 @end ifinfo
    134@copying
    14 Copyright 2007 Felix Winkelmann
     5Copyright 2007-2008 Felix Winkelmann
    156@end copying
    167@titlepage
     
    2112@page
    2213@vskip 0pt plus 1fill
    23 Copyright 2007 Felix Winkelmann
     14Copyright 2007-2008 Felix Winkelmann
    2415@end titlepage
    2516@node Top, The User's Manual, (dir), (dir)
     
    7263
    7364
    74 @emph{(This document describes version 2.635)}
     65@emph{(This document describes version 3.0.0)}
    7566
    7667@b{CHICKEN is a compiler that translates Scheme source files into C}, which in turn can be fed to a C-compiler to generate a standalone executable.  An interpreter is also available and can be used as a scripting environment or for testing programs before compilation.
     
    164155The most portable way of creating separately linkable entities is supported by so-called @emph{unit}s.  A unit is a single compiled object module that contains a number of toplevel expressions that are executed either when the unit is the @emph{main} unit or if the unit is @emph{used}.  To use a unit, the unit has to be @emph{declare}ed as used, like this:
    165156
    166 <enscript highlight=scheme> (declare (uses UNITNAME)) </enscript>
    167 
     157@example
     158(declare (uses UNITNAME))
     159@end example
    168160The toplevel expressions of used units are executed in the order in which the units appear in the @code{uses} declaration. Units may be used multiple times and @code{uses} declarations may be circular (the unit is initialized at most once).  To compile a file as a unit, add a @code{unit} declaration:
    169161
    170 <enscript highlight=scheme> (declare (unit UNITNAME)) </enscript>
    171 
     162@example
     163(declare (unit UNITNAME))
     164@end example
    172165When compiling different object modules, make sure to have one main unit. This unit is called initially and initializes all used units before executing its toplevel expressions. The main-unit has no @code{unit} declaration.
    173166
    174167Another method of using definitions in separate source files is to @emph{include} them. This simply inserts the code in a given file into the current file:
    175168
    176 <enscript highlight=scheme> (include "FILENAME") </enscript>
    177 
     169@example
     170(include @strong{"FILENAME"})
     171@end example
    178172Macro definitions are only available when processed by @code{include} or @code{require-for-syntax}. Macro definitions in separate units are not available, since they are defined at compile time, i.e the time when that other unit was compiled (macros can optionally be available at runtime, see @code{define-macro} in @ref{Non-standard macros and special forms, Substitution forms and macros}).
    179173
     
    207201
    208202@verbatim
    209 chicken FILENAME @{OPTION@}
     203chicken FILENAME {OPTION}
    210204@end verbatim
    211205@code{FILENAME} is the complete pathname of the source file that is to be translated into C. A filename argument of @code{-} specifies that the source text should be read from standard input. Note that the filename has to be the first argument to @code{chicken}.
     
    232226
    233227Aborts compilation process after macro-expansion and syntax checks.
    234 @item -compress-literals THRESHOLD
    235 
    236 Compiles quoted literals that exceed the size @code{THRESHOLD} as strings and parse the strings at run-time. This reduces the size of the code and speeds up compile-times of the host C compiler, but has a small run-time performance penalty. The size of a literal is computed by counting recursively the objects in the literal, so a vector counts as 1 plus the count of the elements, a pair counts as the counts of the car and the cdr, respectively. All other objects count 1.
    237228@item -debug MODES
    238229
     
    355346@item -include-path PATHNAME
    356347
    357 Specifies an additional search path for files included via the @code{include} special form. This option may be given multiple times. If the environment variable @code{CHICKEN_INCLUDE_PATH} is set, it should contain a list of alternative include pathnames separated by @code{;}. The environment variable @code{CHICKEN_HOME} is also considered as a search path.
     348Specifies an additional search path for files included via the @code{include} special form. This option may be given multiple times. If the environment variable @code{CHICKEN_INCLUDE_PATH} is set, it should contain a list of alternative include pathnames separated by @code{;}.
    358349@item -inline
    359350
     
    361352@item -inline-limit THRESHOLD
    362353
    363 Sets the maximum size of a potentially inlinable procedure. This option is only effective when inlining has been enabled with the @code{-inline} option. The default threshold is @code{10}.
     354Sets the maximum size of a potentially inlinable procedure. The default threshold is @code{10}.
    364355@item -keyword-style STYLE
    365356
     
    534525
    535526@menu
    536 * Using the compiler - Examples - A simple example (with one source file)::
     527* Using the compiler - Examples - A simple example ;with one source file;::
    537528* Using the compiler - Examples - An example with multiple files::
    538529
     
    540531
    541532
    542 @node Using the compiler - Examples - A simple example (with one source file), Using the compiler - Examples - An example with multiple files,  , Using the compiler - Examples
     533@node Using the compiler - Examples - A simple example ;with one source file;, Using the compiler - Examples - An example with multiple files,  , Using the compiler - Examples
    543534@subsection A simple example (with one source file)
    544535
    545536@menu
    546 * Using the compiler - Examples - A simple example (with one source file) - Writing your source file::
    547 * Using the compiler - Examples - A simple example (with one source file) - Compiling your program::
    548 * Using the compiler - Examples - A simple example (with one source file) - Running your program::
     537* Using the compiler - Examples - A simple example ;with one source file; - Writing your source file::
     538* Using the compiler - Examples - A simple example ;with one source file; - Compiling your program::
     539* Using the compiler - Examples - A simple example ;with one source file; - Running your program::
    549540
    550541@end menu
     
    553544To compile a Scheme program (assuming a UNIX-like environment) consisting of a single source file, perform the following steps.
    554545
    555 @node Using the compiler - Examples - A simple example (with one source file) - Writing your source file, Using the compiler - Examples - A simple example (with one source file) - Compiling your program,  , Using the compiler - Examples - A simple example (with one source file)
     546@node Using the compiler - Examples - A simple example ;with one source file; - Writing your source file, Using the compiler - Examples - A simple example ;with one source file; - Compiling your program,  , Using the compiler - Examples - A simple example ;with one source file;
    556547@subsubsection Writing your source file
    557548
     
    559550In this example we will assume your source file is called @code{foo.scm}:
    560551
    561 <enscript highlight=scheme> ;;; foo.scm
    562 
    563 (define (fac n)
    564 
    565 @verbatim
    566  (if (zero? n)
    567      1
    568      (* n (fac (- n 1))) ) )
    569 @end verbatim
    570 (write (fac 10)) (newline) </enscript>
    571 
    572 @node Using the compiler - Examples - A simple example (with one source file) - Compiling your program, Using the compiler - Examples - A simple example (with one source file) - Running your program, Using the compiler - Examples - A simple example (with one source file) - Writing your source file, Using the compiler - Examples - A simple example (with one source file)
     552@example
     553@emph{;;; foo.scm
     554}
     555(@strong{define} (@strong{fac} n)
     556  (@strong{if} (zero? n)
     557      1
     558      (* n (fac (- n 1))) ) )
     559
     560(write (fac 10))
     561(newline)
     562@end example
     563@node Using the compiler - Examples - A simple example ;with one source file; - Compiling your program, Using the compiler - Examples - A simple example ;with one source file; - Running your program, Using the compiler - Examples - A simple example ;with one source file; - Writing your source file, Using the compiler - Examples - A simple example ;with one source file;
    573564@subsubsection Compiling your program
    574565
     
    585576foo  foo.scm
    586577@end verbatim
    587 @node Using the compiler - Examples - A simple example (with one source file) - Running your program,  , Using the compiler - Examples - A simple example (with one source file) - Compiling your program, Using the compiler - Examples - A simple example (with one source file)
     578@node Using the compiler - Examples - A simple example ;with one source file; - Running your program,  , Using the compiler - Examples - A simple example ;with one source file; - Compiling your program, Using the compiler - Examples - A simple example ;with one source file;
    588579@subsubsection Running your program
    589580
     
    597588If you get a @code{foo: command not found} error, you might want to try with @code{./foo} instead (or, in Unix machines, modify your @code{PATH} environment variable to include your current directory).
    598589
    599 @node Using the compiler - Examples - An example with multiple files,  , Using the compiler - Examples - A simple example (with one source file), Using the compiler - Examples
     590@node Using the compiler - Examples - An example with multiple files,  , Using the compiler - Examples - A simple example ;with one source file;, Using the compiler - Examples
    600591@subsection An example with multiple files
    601592
     
    617608The declarations in these files specify which of the compiled files is the main module, and which is the library module. An executable can only have one main module, since a program has only a single entry-point. In this case @code{foo.scm} is the main module, because it doesn't have a @code{unit} declaration:
    618609
    619 <enscript highlight=scheme> ;;; foo.scm
    620 
    621 @table @b
    622 @item The declaration marks this source file as dependant on the symbols provided
    623 
    624 
    625 @item by the bar unit
    626 
    627 
    628 
    629 @end table
    630 (declare (uses bar))
    631 
    632 (write (fac 10)) (newline) </enscript>
    633 
     610@example
     611@emph{;;; foo.scm
     612}
     613@emph{; The declaration marks this source file as dependant on the symbols provided
     614}@emph{; by the bar unit:
     615}(declare (uses bar))
     616
     617(write (fac 10)) (newline)
     618@end example
    634619@code{bar.scm} will be our library:
    635620
    636 <enscript highlight=scheme> ;;; bar.scm
    637 
    638 @table @b
    639 @item The declaration marks this source file as the bar unit.  The names of the
    640 
    641 
    642 @item units and your files don't need to match.
    643 
    644 
    645 
    646 @end table
    647 (declare (unit bar))
    648 
    649 (define (fac n)
    650 
    651 @verbatim
    652  (if (zero? n)
    653      1
    654      (* n (fac (- n 1))) ) )
    655 @end verbatim
    656 </enscript>
    657 
     621@example
     622@emph{;;; bar.scm
     623}
     624@emph{; The declaration marks this source file as the bar unit.  The names of the
     625}@emph{; units and your files don't need to match.
     626}(declare (unit bar))
     627
     628(@strong{define} (@strong{fac} n)
     629  (@strong{if} (zero? n)
     630      1
     631      (* n (fac (- n 1))) ) )
     632@end example
    658633@node Using the compiler - Examples - An example with multiple files - Compiling and running your program,  , Using the compiler - Examples - An example with multiple files - Writing your source files, Using the compiler - Examples - An example with multiple files
    659634@subsubsection Compiling and running your program
     
    720695It is relatively easy to create distributions of Scheme projects that have been compiled to C.  The runtime system of CHICKEN consists of only two handcoded C files (@code{runtime.c} and @code{chicken.h}), plus the file @code{chicken-config.h}, which is generated by the build process. All other modules of the runtime system and the extension libraries are just compiled Scheme code. The following example shows a minimal application, which should run without changes on the most frequent operating systems, like Windows, Linux or FreeBSD:
    721696
    722 Let's take a simple "Hello, world!":
    723 
    724 <enscript highlight=scheme> ; hello.scm
    725 
    726 (print "Hello, world!") </enscript>
    727 
     697Let's take a simple example.
     698
     699@example
     700@emph{; hello.scm
     701}
     702(print @strong{"Hello, world!"})
     703@end example
     704@verbatim
     705 % chicken hello.scm -optimize-level 3 -output-file hello.c
     706@end verbatim
    728707Compiled to C, we get @code{hello.c}. We need the files @code{chicken.h} and @code{runtime.c}, which contain the basic runtime system, plus the three basic library files @code{library.c}, @code{eval.c} and @code{extras.c} which contain the same functionality as the library linked into a plain CHICKEN-compiled application, or which is available by default in the interpreter, @code{csi}:
    729708
    730709@verbatim
    731 % csc hello.scm -O2 -d1
    732 @end verbatim
    733 A simple makefile is needed as well:
    734 
    735 <enscript highlight=makefile>
    736 
    737 @enumerate
    738 @item Makefile for UNIX systems
    739 
    740 
    741 @end enumerate
    742 hello: hello.o runtime.o library.o eval.o extras.o
    743 
    744 @verbatim
    745       $(CC) -o hello hello.o runtime.o library.o eval.o extras.o -lm
    746 @end verbatim
    747 hello.o: chicken.h runtime.o: chicken.h library.o: chicken.h eval.o: chicken.h extras.o: chicken.h </enscript>
    748 
     710 % cd /tmp
     711 %echo '(print "Hello World.")' > hello.scm
     712 % cp $CHICKEN_BUILD/runtime.c .
     713 % cp $CHICKEN_BUILD/library.c .
     714 % cp $CHICKEN_BUILD/eval.c    .
     715 % cp $CHICKEN_BUILD/extras.c  .
     716 % gcc -static -Os -fomit-frame-pointer runtime.c library.c eval.c \
     717   extras.c hello.c -o hello -lm
     718@end verbatim
    749719Now we have all files together, and can create an tarball containing all the files:
    750720
     
    753723% gzip hello.tar
    754724@end verbatim
    755 This is of naturally rather simplistic. Things like enabling dynamic loading, estimating the optimal stack-size and selecting supported features of the host system would need more configuration- and build-time support. All this can be addressed using more elaborate build-scripts, makefiles or by using autoconf/automake.
     725This is naturally rather simplistic. Things like enabling dynamic loading, estimating the optimal stack-size and selecting supported features of the host system would need more configuration- and build-time support. All this can be addressed using more elaborate build-scripts, makefiles or by using autoconf/automake.
    756726
    757727Note also that the size of the application can still be reduced by removing @code{extras} and @code{eval} and compiling @code{hello.scm} with the @code{-explicit-use} option.
     
    802772
    803773Evaluate @code{EXPRESSIONS}. This option implies @code{-batch} and @code{-quiet}, so no startup message will be printed and the interpreter exits after processing all @code{-eval} options and/or loading files given on the command-line.
     774@item -p  -print EXPRESSIONS
     775
     776Evaluate @code{EXPRESSIONS} and print the results of each expression using @code{print}. Implies @code{-batch} and @code{-quiet}.
     777@item -P  -pretty-print EXPRESSIONS
     778
     779Evaluate @code{EXPRESSIONS} and print the results of each expression using @code{pretty-print}. Implies @code{-batch} and @code{-quiet}.
    804780@item -D  -feature SYMBOL
    805781
    806 Registers @code{SYMBOL} to be a valid feature identifier for @code{cond-expand}.
     782Registers @code{SYMBOL} to be a valid feature identifier for @code{cond-expand} and @code{feature?}.
    807783@item -h  -help
    808784
     
    810786@item -I  -include-path PATHNAME
    811787
    812 Specifies an alternative search-path for files included via the @code{include} special form. This option may be given multiple times. If the environment variable @code{CHICKEN_INCLUDE_PATH} is set, it should contain a list of alternative include pathnames separated by @code{;}. The environment variable @code{CHICKEN_HOME} is also considered as a search path.
     788Specifies an alternative search-path for files included via the @code{include} special form. This option may be given multiple times. If the environment variable @code{CHICKEN_INCLUDE_PATH} is set, it should contain a list of alternative include pathnames separated by @code{;}.
    813789@item -k  -keyword-style STYLE
    814790
     
    822798@item -q  -quiet
    823799
    824 Do not print a startup message.
     800Do not print a startup message. Also disables generation of call-trace information for interpreted code.
    825801@item -s  -script PATHNAME
    826802
     
    863839@verbatim
    864840C:>type foo.bat
    865 @@;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
     841@;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
    866842(print (eval (with-input-from-string
    867843                (car (command-line-arguments))
     
    941917
    942918@end table
    943 <enscript highlight=scheme>
    944 
    945 @enumerate
    946 @item ;1> (fac 10)                       ==> 3628800
    947 
    948 @item ;2> ,tr fac
    949 
    950 @item ;3> (fac 3) |(fac 3) | (fac 2) |  (fac 1) |   (fac 0) |   fac -> 1  |  fac -> 1  | fac -> 2  |fac -> 6                          ==> 6
    951 
    952 @item ;4> ,utr fac
    953 
    954 @item ;5> (fac 3)                        ==> 6 </enscript>
    955 
    956 
    957 @end enumerate
     919@example
     920#@emph{;1> (fac 10)                       ==> 3628800
     921}#@emph{;2> ,tr fac
     922}#@emph{;3> (fac 3)
     923}|(fac 3)
     924| (fac 2)
     925|  (fac 1)
     926|   (fac 0)
     927|   fac -> 1
     928|  fac -> 1
     929| fac -> 2
     930|fac -> 6                          =@strong{=>} 6
     931#@emph{;4> ,utr fac
     932}#@emph{;5> (fac 3)                        ==> 6
     933}@end example
     934k
     935
    958936@table @b
    959937@item ,utr SYMBOL ...
     
    1011989@verbatim
    1012990#;1> (define-record point x y)
    1013 #;2> (set-describer! 'point (lambda (pt o) (print "a point with x=" (point-x pt) " and y=" (point-y pt))))
     991#;2> (set-describer! 'point
     992       (lambda (pt o)
     993         (print "a point with x=" (point-x pt) " and y=" (point-y pt))))
    1014994#;3> ,d (make-point 1 2)
    1015995a point with x=1 and y=2
     
    10261006(use readline regex)
    10271007(current-input-port (make-gnu-readline-port))
    1028 (gnu-history-install-file-manager (string-append (or (getenv "HOME") ".") "/.csi.history"))
     1008(gnu-history-install-file-manager
     1009  (string-append (or (getenv "HOME") ".") "/.csi.history"))
    10291010@end verbatim
    10301011More details are available in @uref{http://www.call-with-current-continuation.org/eggs/readline.html, the egg's documentation}.
     
    11151096
    11161097
    1117 @itemize
    1118 @item Identifiers are by default case-sensitive (see @uref{http://galinha.ucpel.tche.br:8080/Using%20the%20compiler#Compiler%20command%20line%20format, Compiler command line format}).
    1119 
    1120 @item [4.1.3] The maximal number of arguments that may be passed to a compiled procedure or macro is 120.  A macro-definition that has a single rest-parameter can have any number of arguments.  If the @code{libffi} library is available on this platform, and if it is installed, then CHICKEN can take advantage of this. See the @uref{http://chicken.wiki.br/chicken/README, README} file for more details.
    1121 
    1122 @item [4.2.2] @code{letrec} does evaluate the initial values for the bound variables sequentially and not in parallel, that is:
    1123 
    1124 
    1125 @end itemize
     1098Identifiers are by default case-sensitive (see @uref{http://galinha.ucpel.tche.br:8080/Using%20the%20compiler#Compiler%20command%20line%20format, Compiler command line format}).
     1099
     1100[4.1.3] The maximal number of arguments that may be passed to a compiled procedure or macro is 120.  A macro-definition that has a single rest-parameter can have any number of arguments.  If the @code{libffi} library is available on this platform, and if it is installed, then CHICKEN can take advantage of this. See the @uref{http://chicken.wiki.br/chicken/README, README} file for more details.
     1101
     1102[4.2.2] @code{letrec} does evaluate the initial values for the bound variables sequentially and not in parallel, that is:
     1103
    11261104@verbatim
    11271105 (letrec ((x 1) (y 2)) (cons x y))
     
    11441122     (cons x y) ) )
    11451123@end verbatim
    1146 @itemize
    1147 @item [4.3] @code{syntax-rules} macros are not provided but available separately.
    1148 
    1149 @item [6.1] @code{equal?} compares all structured data recursively, while R5RS specifies that @code{eqv?} is used for data other than pairs, strings and vectors.
    1150 
    1151 @item [6.2.4]  The runtime system uses the numerical string-conversion routines of the underlying C library and so does only understand standard (C-library) syntax for floating-point constants.
    1152 
    1153 @item [6.2.5] There is no built-in support for rationals, complex numbers or extended-precision integers (bignums). The routines @code{complex?}, @code{real?} and @code{rational?} are identical to the standard procedure @code{number?}. The procedures @code{numerator}, @code{denominator}, @code{rationalize}, @code{make-rectangular} and @code{make-polar} are not implemented. Fixnums are limited to ±2<nowiki><sup>30</sup></nowiki> (or ±2<nowiki><sup>62</sup></nowiki> on 64-bit hardware).  Support for extended numbers is available as a separate package, provided the GNU multiprecision library is installed.
    1154 
    1155 @item [6.2.6] The procedure @code{string->number} does not obey read/write invariance on inexact numbers.
    1156 
    1157 @item [6.4] The maximum number of values that can be passed to continuations captured using @code{call-with-current-continuation} is 120.
    1158 
    1159 @item [6.5] Code evaluated in @code{scheme-report-environment} or @code{null-environment} still sees non-standard syntax.
    1160 
    1161 @item [6.6.2] The procedure @code{char-ready?} always returns @code{#t} for terminal ports.  The procedure @code{read} does not obey read/write invariance on inexact numbers.
    1162 
    1163 @item [6.6.3] The procedures @code{write} and @code{display} do not obey read/write invariance to inexact numbers.
    1164 
    1165 @item [6.6.4] The @code{transcript-on} and @code{transcript-off} procedures are not implemented.
    1166 
    1167 
    1168 @end itemize
     1124[4.3] @code{syntax-rules} macros are not provided but available separately.
     1125
     1126[6.1] @code{equal?} compares all structured data recursively, while R5RS specifies that @code{eqv?} is used for data other than pairs, strings and vectors.
     1127
     1128[6.2.4] The runtime system uses the numerical string-conversion routines of the underlying C library and so does only understand standard (C-library) syntax for floating-point constants.
     1129
     1130[6.2.5] There is no built-in support for rationals, complex numbers or extended-precision integers (bignums). The routines @code{complex?}, @code{real?} and @code{rational?} are identical to the standard procedure @code{number?}. The procedures @code{numerator}, @code{denominator}, @code{rationalize}, @code{make-rectangular} and @code{make-polar} are not implemented. Fixnums are limited to ±2<nowiki><sup>30</sup></nowiki> (or ±2<nowiki><sup>62</sup></nowiki> on 64-bit hardware).  Support for extended numbers is available as a separate package, provided the GNU multiprecision library is installed.
     1131
     1132[6.2.6] The procedure @code{string->number} does not obey read/write invariance on inexact numbers.
     1133
     1134[6.4] The maximum number of values that can be passed to continuations captured using @code{call-with-current-continuation} is 120.
     1135
     1136[6.5] Code evaluated in @code{scheme-report-environment} or @code{null-environment} still sees non-standard syntax.
     1137
     1138[6.6.2] The procedure @code{char-ready?} always returns @code{#t} for terminal ports.  The procedure @code{read} does not obey read/write invariance on inexact numbers.
     1139
     1140[6.6.3] The procedures @code{write} and @code{display} do not obey read/write invariance to inexact numbers.
     1141
     1142[6.6.4] The @code{transcript-on} and @code{transcript-off} procedures are not implemented.
     1143
    11691144Previous: @ref{Supported language, Supported language}
    11701145
     
    11771152[2.1] Identifiers may contain special characters if delimited with @code{| ... |}.
    11781153
    1179 [2.3] The brackets @code{[ ... ]} are provided as an alternative syntax for @code{( ... )}.  A number of reader extensions is provided. See @ref{Non-standard read syntax, Non-standard read syntax}.
     1154[2.3] The brackets @code{[ ... ]} and the braces @code{ @{ ... @} } are provided as an alternative syntax for @code{( ... )}.  A number of reader extensions is provided. See @ref{Non-standard read syntax, Non-standard read syntax}.
    11801155
    11811156[4] Numerous non-standard macros are provided. See  @ref{Non-standard macros and special forms, Non-standard macros and special forms} for more information.
    11821157
    1183 [4.1.4] Extended DSSSL style lambda lists are supported. DSSSL formal argument lists are defined by the following grammar:
    1184 
    1185 @verbatim
    1186 <formal-argument-list> ==> <required-formal-argument>*
    1187                            [(#!optional <optional-formal-argument>*)]
    1188                            [(#!rest <rest-formal-argument>)]
    1189                            [(#!key <key-formal-argument>*)]
    1190 <required-formal-argument> ==> <ident>
    1191 <optional-formal-argument> ==> <ident>
    1192                              | (<ident> <initializer>)
    1193 <rest-formal-argument> ==> <ident>
    1194 <key-formal-argument> ==> <ident>
    1195                           | (<ident> <initializer>)
     1158[4.1.4] Extended DSSSL style lambda lists are supported. DSSSL parameter lists are defined by the following grammar:
     1159
     1160@verbatim
     1161<parameter-list> ==> <required-parameter>*
     1162                     [(#!optional <optional-parameter>*)]
     1163                     [(#!rest <rest-parameter>)]
     1164                     [(#!key <keyword-parameter>*)]
     1165<required-parameter> ==> <ident>
     1166<optional-parameter> ==> <ident>
     1167                         | (<ident> <initializer>)
     1168<rest-parameter> ==> <ident>
     1169<keyword-parameter> ==> <ident>
     1170                        | (<ident> <initializer>)
    11961171<initializer> ==> <expr>
    11971172@end verbatim
    1198 When a procedure is applied to a list of actual arguments, the formal and actual arguments are processed from left to right as follows:
     1173When a procedure is applied to a list of arguments, the parameters and arguments are processed from left to right as follows:
    11991174
    12001175@itemize
    1201 @item Variables in required-formal-arguments are bound to successive actual arguments starting with the first actual argument. It shall be an error if there are fewer actual arguments than required-formal-arguments.
    1202 
    1203 @item Next, variables in optional-formal-arguments are bound to any remaining actual arguments. If there are fewer remaining actual arguments than optional-formal-arguments, then variables are bound to the result of the evaluation of initializer if one was specified or otherwise to @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound.
    1204 
    1205 @item If there is a rest-formal-argument, then it is bound to a list of all remaining actual arguments. The remaining actual arguments are also eligible to be bound to keyword-formal-arguments. If there is no rest-formal-argument and there are no keywords, the it shall be an error if there are any remaining actual arguments.
    1206 
    1207 @item If @code{#!key} was specified in the formal-argument-list, there shall be an even number of remaining actual arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the argument name, and th corresponding value. It shall be an error if the first member of a pair is not a keyword. It shall be an error if the argument name is not the same as a variable in a keyword-formal-argument, unless there is a rest-formal-argument. If the same argument name occurs more than once in the list of actual arguments, then the first value is used. If there is no actual argument for a particular keyword-formal-argument, then the variable is bound to the result of evaluating initializer if one was specified or @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound.
     1176@item Required-parameters are bound to successive arguments starting with the first argument. It shall be an error if there are fewer arguments than required-parameters.
     1177
     1178@item Next, the optional-parameters are bound with the remaining arguments. If there are fewer arguments than optional-parameters, then the remaining optional-parameters are bound to the result of the evaluation of their corresponding <initializer>, if one was specified, otherwise @code{#f}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound.
     1179
     1180@item If there is a rest-parameter, then it is bound to a list containing all the remaining arguments left over after the argument bindings with required-parameters and optional-parameters have been made.
     1181
     1182@item If @code{#!key} was specified in the parameter-list, there should be an even number of remaining arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the parameter name, and the second member is the corresponding value. If the same keyword occurs more than once in the list of arguments, then the corresponding value of the first keyword is the binding value. If there is no argument for a particular keyword-parameter, then the variable is bound to the result of evaluating <initializer>, if one was specified, otherwise @code{#f}. The corresponding <initializer> is evaluated in an environment in which all previous parameters have been bound.
    12081183
    12091184
    12101185@end itemize
    1211 It shall be an error for an @code{<ident>} to appear more than once in a formal-argument-list.
     1186Needing a special mention is the close relationship between the rest-parameter and possible keyword-parameters.  Declaring a rest-parameter binds up all remaining arguments in a list, as described above. These same remaining arguments are also used for attempted matches with declared keyword-parameters, as described above, in which case a matching keyword-parameter binds to the corresponding value argument at the same time that both the keyword and value arguments are added to the rest parameter list. Note that for efficiency reasons, the keyword-parameter matching does nothing more than simply attempt to match with pairs that may exist in the remaining arguments.  Extra arguments that don't match are simply unused and forgotten if no rest-parameter has been declared.  Because of this, the caller of a procedure containing one or more keyword-parameters cannot rely on any kind of system error to report wrong keywords being passed in.
     1187
     1188It shall be an error for an @code{<ident>} to appear more than once in a parameter-list.
     1189
     1190If there is no rest-parameter and no keyword-parameters in the parameter-list, then it shall be an error for any extra arguments to be passed to the procedure.
    12121191
    12131192Example:
     
    12831262
    12841263[6.6.1] if the procedures @code{current-input-port} and @code{current-output-port} are called with an argument (which should be a port), then that argument is selected as the new current input- and output-port, respectively.  The procedures @code{open-input-file}, @code{open-output-file}, @code{with-input-from-file}, @code{with-output-to-file}, @code{call-with-input-file} and @code{call-with-output-file} accept an optional second (or third) argument which should be one or more keywords, if supplied. These arguments specify the mode in which the file is opened. Possible values are the keywords @code{#:text}, @code{#:binary} or @code{#:append}.
     1264
     1265[6.7] The @code{exit} procedure exits a program right away and does @emph{not} invoke pending @code{dynamic-wind} thunks.
    12851266
    12861267Previous: @ref{Deviations from the standard, Deviations from the standard}
     
    13981379This is a simple string with an embedded `##' character
    13991380and substituted expressions: (+ three 99) ==> #(+ three 99)
    1400 (three is "#@{three@}")
     1381(three is "#{three}")
    14011382EOF
    14021383)
     
    15181499
    15191500@menu
    1520 * Non-standard macros and special forms - Making extra libraries and extensions availablee::
     1501* Non-standard macros and special forms - Making extra libraries and extensions available::
    15211502* Non-standard macros and special forms - Binding forms for optional arguments::
    15221503* Non-standard macros and special forms - Other binding forms::
     
    15291510
    15301511
    1531 @node Non-standard macros and special forms - Making extra libraries and extensions availablee, Non-standard macros and special forms - Binding forms for optional arguments,  , Non-standard macros and special forms
    1532 @section Making extra libraries and extensions availablee
    1533 
    1534 @menu
    1535 * Non-standard macros and special forms - Making extra libraries and extensions availablee - require-extension::
    1536 * Non-standard macros and special forms - Making extra libraries and extensions availablee - define-extension::
    1537 
    1538 @end menu
    1539 
    1540 
    1541 @node Non-standard macros and special forms - Making extra libraries and extensions availablee - require-extension, Non-standard macros and special forms - Making extra libraries and extensions availablee - define-extension,  , Non-standard macros and special forms - Making extra libraries and extensions availablee
     1512@node Non-standard macros and special forms - Making extra libraries and extensions available, Non-standard macros and special forms - Binding forms for optional arguments,  , Non-standard macros and special forms
     1513@section Making extra libraries and extensions available
     1514
     1515@menu
     1516* Non-standard macros and special forms - Making extra libraries and extensions available - require-extension::
     1517* Non-standard macros and special forms - Making extra libraries and extensions available - define-extension::
     1518
     1519@end menu
     1520
     1521
     1522@node Non-standard macros and special forms - Making extra libraries and extensions available - require-extension, Non-standard macros and special forms - Making extra libraries and extensions available - define-extension,  , Non-standard macros and special forms - Making extra libraries and extensions available
    15421523@subsection require-extension
    15431524
     
    15471528[syntax] (use ID ...)
    15481529@end verbatim
    1549 This form does all necessary steps to make the libraries or extensions given in @code{ID ...} available. It loads syntactic extension, if needed and generates code for loading/linking with core library modules or separately installed extensions. @code{use} is just a shorter alias for @code{require-extension}. This implementation of @code{require-extension} is compliant to @uref{http://srfi.schemers.org/srfi-55/srfi-55.html, SRFI-55} (see the @uref{http://srfi.schemers.org/srfi-55/srfi-55.html, SRFI-55} document for more information).
     1530This form does all the necessary steps to make the libraries or extensions given in @code{ID ...} available. It loads syntactic extensions, if needed and generates code for loading/linking with core library modules or separately installed extensions. @code{use} is just a shorter alias for @code{require-extension}. This implementation of @code{require-extension} is compliant with @uref{http://srfi.schemers.org/srfi-55/srfi-55.html, SRFI-55} (see the @uref{http://srfi.schemers.org/srfi-55/srfi-55.html, SRFI-55} document for more information).
    15501531
    15511532During interpretation/evaluation @code{require-extension} performs one of the following:
     
    15561537@item If @code{ID} names one of the syntactic extensions @code{chicken-more-macros chicken-ffi-macros}, then this extension will be loaded.
    15571538
    1558 @item @code{ID} names one of the core library units shipped with CHICKEN, then a @code{(load-library 'ID)} will be performed.
    1559 
    1560 @item @code{ID} names an installed extension with the @code{syntax} or @code{require-at-runtime} attribute, then the equivalent of @code{(require-for-syntax 'ID)} is performed, probably followed by @code{(require ...)} for any run-time requirements.
    1561 
    1562 @item Otherwise @code{(require-extension ID)} is equivalent to @code{(require 'ID)}.
     1539@item If @code{ID} names one of the core library units shipped with CHICKEN, then a @code{(load-library 'ID)} will be performed.
     1540
     1541@item If @code{ID} names an installed extension with the @code{syntax} or @code{require-at-runtime} attribute, then the equivalent of @code{(require-for-syntax 'ID)} is performed, probably followed by @code{(require ...)} for any run-time requirements.
     1542
     1543@item Otherwise, @code{(require-extension ID)} is equivalent to @code{(require 'ID)}.
    15631544
    15641545
    15651546@end itemize
    1566 During compilation one of the following happens instead:
     1547During compilation, one of the following happens instead:
    15671548
    15681549@itemize
     
    15711552@item If @code{ID} names one of the syntactic extensions @code{chicken-more-macros chicken-ffi-macros}, then this extension will be loaded at compile-time, making the syntactic extensions available in compiled code.
    15721553
    1573 @item If @code{ID} names one of the core library units shipped with CHICKEN, or if the option @code{-uses ID} has been passed to the compiler then a @code{(declare (uses ID))} is generated.
     1554@item If @code{ID} names one of the core library units shipped with CHICKEN, or if the option @code{-uses ID} has been passed to the compiler, then a @code{(declare (uses ID))} is generated.
    15741555
    15751556@item If @code{ID} names an installed extension with the @code{syntax} or @code{require-at-runtime} attribute, then the equivalent of @code{(require-for-syntax 'ID)} is performed, and code is emitted to @code{(require ...)} any needed run-time requirements.
     
    15961577When syntax extensions are loaded that redefine the global toplevel macro-expander (for example the @uref{http://www.call-with-current-continuation.org/eggs/syntax-case.html, syntax-case} extension), then all remaining expression @emph{in the same toplevel form} are still expanded with the old toplevel macro-expander.
    15971578
    1598 @node Non-standard macros and special forms - Making extra libraries and extensions availablee - define-extension,  , Non-standard macros and special forms - Making extra libraries and extensions availablee - require-extension, Non-standard macros and special forms - Making extra libraries and extensions availablee
     1579@node Non-standard macros and special forms - Making extra libraries and extensions available - define-extension,  , Non-standard macros and special forms - Making extra libraries and extensions available - require-extension, Non-standard macros and special forms - Making extra libraries and extensions available
    15991580@subsection define-extension
    16001581
     
    16051586This macro simplifies the task of writing extensions that can be linked both statically and dynamically. If encountered in interpreted code or code that is compiled into a shared object (specifically if compiled with the feature @code{chicken-compile-shared}, done automatically by @code{csc} when compiling with the @code{-shared} or @code{-dynamic} option) then the code given by clauses of the form
    16061587
    1607 <enscript highlight=scheme> (dynamic EXPRESSION ...) </enscript>
    1608 
     1588@example
     1589(dynamic EXPRESSION ...)
     1590@end example
    16091591are inserted into the output as a @code{begin} form.
    16101592
    16111593If compiled statically (specifically if the feature @code{chicken-compile-shared} has not been given), then this form expands into the following:
    16121594
    1613 <enscript highlight=scheme> (declare (unit NAME)) (provide 'NAME) </enscript>
    1614 
     1595@example
     1596(declare (unit NAME))
     1597(provide 'NAME)
     1598@end example
    16151599and all clauses of the form
    16161600
    1617 <enscript highlight=scheme> (static EXPRESSION ...) </enscript>
    1618 
     1601@example
     1602(static EXPRESSION ...)
     1603@end example
    16191604all additionally inserted into the expansion.
    16201605
    16211606As a convenience, the clause
    16221607
    1623 <enscript highlight=scheme> (export IDENTIFIER ...) </enscript>
    1624 
     1608@example
     1609(export IDENTIFIER ...)
     1610@end example
    16251611is also allowed and is identical to @code{(declare (export IDENTIFIER ...))} (unless the @code{define-extension} form occurs in interpreted code, in with it is simply ignored).
    16261612
    16271613Note that the compiler option @code{-extension NAME} is equivalent to prefixing the compiled file with
    16281614
    1629 <enscript highlight=scheme> (define-extension NAME) </enscript>
    1630 
    1631 @node Non-standard macros and special forms - Binding forms for optional arguments, Non-standard macros and special forms - Other binding forms, Non-standard macros and special forms - Making extra libraries and extensions availablee, Non-standard macros and special forms
     1615@example
     1616(define-extension NAME)
     1617@end example
     1618@node Non-standard macros and special forms - Binding forms for optional arguments, Non-standard macros and special forms - Other binding forms, Non-standard macros and special forms - Making extra libraries and extensions available, Non-standard macros and special forms
    16321619@section Binding forms for optional arguments
    16331620
     
    16501637Use this form for procedures that take a single optional argument. If @code{ARGS} is the empty list @code{DEFAULT} is evaluated and returned, otherwise the first element of the list @code{ARGS}. It is an error if @code{ARGS} contains more than one value.
    16511638
    1652 <enscript highlight=scheme> (define (incr x . i) (+ x (optional i 1))) (incr 10)                                   ==> 11 (incr 12 5)                                 ==> 17 </enscript>
    1653 
     1639@example
     1640(@strong{define} (@strong{incr} x . i) (+ x (optional i 1)))
     1641(incr 10)                                   =@strong{=>} 11
     1642(incr 12 5)                                 =@strong{=>} 17
     1643@end example
    16541644@node Non-standard macros and special forms - Binding forms for optional arguments - case-lambda, Non-standard macros and special forms - Binding forms for optional arguments - let-optionals, Non-standard macros and special forms - Binding forms for optional arguments - optional, Non-standard macros and special forms - Binding forms for optional arguments
    16551645@subsection case-lambda
     
    16611651Expands into a lambda that invokes the body following the first matching lambda-list.
    16621652
    1663 <enscript highlight=scheme> (define plus
    1664 
    1665 @verbatim
    1666  (case-lambda
    1667    (() 0)
    1668    ((x) x)
    1669    ((x y) (+ x y))
    1670    ((x y z) (+ (+ x y) z))
    1671    (args (apply + args))))
    1672 @end verbatim
    1673 (plus)                      ==> 9 (plus 1)                    ==> 1 (plus 1 2 3)                ==> 6 </enscript>
    1674 
     1653@example
     1654(@strong{define} @strong{plus}
     1655  (case-lambda
     1656    (() 0)
     1657    ((x) x)
     1658    ((x y) (+ x y))
     1659    ((x y z) (+ (+ x y) z))
     1660    (args (apply + args))))
     1661
     1662(plus)                      =@strong{=>} 9
     1663(plus 1)                    =@strong{=>} 1
     1664(plus 1 2 3)                =@strong{=>} 6
     1665@end example
    16751666For more information see the documentation for @uref{http://srfi.schemers.org/srfi-16/srfi-16.html, SRFI-16}
    16761667
     
    16841675Binding constructs for optional procedure arguments. @code{ARGS} should be a rest-parameter taken from a lambda-list. @code{let-optionals} binds @code{VAR1 ...} to available arguments in parallel, or to @code{DEFAULT1 ...} if not enough arguments were provided. @code{let-optionals*} binds @code{VAR1 ...} sequentially, so every variable sees the previous ones. it is an error if any excess arguments are provided.
    16851676
    1686 <enscript highlight=scheme> (let-optionals '(one two) ((a 1) (b 2) (c 3))
    1687 
    1688 @verbatim
    1689  (list a b c) )                               ==> (one two 3)
    1690 @end verbatim
    1691 </enscript>
    1692 
     1677@example
     1678(let-optionals '(one two) ((a 1) (b 2) (c 3))
     1679  (list a b c) )                               =@strong{=>} (one two 3)
     1680@end example
    16931681@node Non-standard macros and special forms - Binding forms for optional arguments - let-optionals*,  , Non-standard macros and special forms - Binding forms for optional arguments - let-optionals, Non-standard macros and special forms - Binding forms for optional arguments
    16941682@subsection let-optionals*
     
    17001688Binding constructs for optional procedure arguments. @code{ARGS} should be a rest-parameter taken from a lambda-list. @code{let-optionals} binds @code{VAR1 ...} to available arguments in parallel, or to @code{DEFAULT1 ...} if not enough arguments were provided. @code{let-optionals*} binds @code{VAR1 ...} sequentially, so every variable sees the previous ones. If a single variable @code{RESTVAR} is given, then it is bound to any remaining arguments, otherwise it is an error if any excess arguments are provided.
    17011689
    1702 <enscript highlight=scheme> (let-optionals* '(one two) ((a 1) (b 2) (c a))
    1703 
    1704 @verbatim
    1705  (list a b c) )                               ==> (one two one)
    1706 @end verbatim
    1707 </enscript>
    1708 
     1690@example
     1691(let-optionals* '(one two) ((a 1) (b 2) (c a))
     1692  (list a b c) )                               =@strong{=>} (one two one)
     1693@end example
    17091694@node Non-standard macros and special forms - Other binding forms, Non-standard macros and special forms - Substitution forms and macros, Non-standard macros and special forms - Binding forms for optional arguments, Non-standard macros and special forms
    17101695@section Other binding forms
     
    17911776Binds multiple variables to the result values of @code{EXP ...}. The variables are bound sequentially.
    17921777
    1793 <enscript highlight=scheme> (let*-values (((a b) (values 2 3))
    1794 
    1795 @verbatim
    1796              ((p) (+ a b)) )
    1797  p)                               ==> 5
    1798 @end verbatim
    1799 </enscript>
    1800 
     1778@example
     1779(let*-values (((a b) (values 2 3))
     1780              ((p) (+ a b)) )
     1781  p)                               =@strong{=>} 5
     1782@end example
    18011783@node Non-standard macros and special forms - Other binding forms - letrec-values, Non-standard macros and special forms - Other binding forms - parameterize, Non-standard macros and special forms - Other binding forms - let*-values, Non-standard macros and special forms - Other binding forms
    18021784@subsection letrec-values
     
    18081790Binds the result values of @code{EXP ...} to multiple variables at once. All variables are mutually recursive.
    18091791
    1810 <enscript highlight=scheme> (letrec-values (((odd even)
    1811 
    1812 @verbatim
    1813                   (values
    1814                     (lambda (n) (if (zero? n) #f (even (sub1 n))))
    1815                     (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )
    1816  (odd 17) )                           ==> #t
    1817 @end verbatim
    1818 </enscript>
    1819 
     1792@example
     1793(letrec-values (((odd even)
     1794                   (values
     1795                     (@strong{lambda} (n) (@strong{if} (zero? n) #f (even (sub1 n))))
     1796                     (@strong{lambda} (n) (@strong{if} (zero? n) #t (odd (sub1 n)))) ) ) )
     1797  (odd 17) )                           =@strong{=>} #t
     1798@end example
    18201799@node Non-standard macros and special forms - Other binding forms - parameterize, Non-standard macros and special forms - Other binding forms - receive, Non-standard macros and special forms - Other binding forms - letrec-values, Non-standard macros and special forms - Other binding forms
    18211800@subsection parameterize
     
    18391818The syntax
    18401819
    1841 <enscript highlight=scheme> (receive VALUEEXP) </enscript>
    1842 
     1820@example
     1821(receive VALUEEXP)
     1822@end example
    18431823is equivalent to
    18441824
    1845 <enscript highlight=scheme> (receive _ VALUEEXP _) </enscript>
    1846 
     1825@example
     1826(receive _ VALUEEXP _)
     1827@end example
    18471828@node Non-standard macros and special forms - Other binding forms - set!-values,  , Non-standard macros and special forms - Other binding forms - receive, Non-standard macros and special forms - Other binding forms
    18481829@subsection set!-values
     
    19371918Equivalent to:
    19381919
    1939 <enscript highlight=scheme> (if (not TEST) (begin EXP1 EXP2 ...)) </enscript>
    1940 
     1920@example
     1921(@strong{if} (not TEST) (@strong{begin} EXP1 EXP2 ...))
     1922@end example
    19411923@node Non-standard macros and special forms - Conditional forms - when,  , Non-standard macros and special forms - Conditional forms - unless, Non-standard macros and special forms - Conditional forms
    19421924@subsection when
     
    19481930Equivalent to:
    19491931
    1950 <enscript highlight=scheme> (if TEST (begin EXP1 EXP2 ...)) </enscript>
    1951 
     1932@example
     1933(@strong{if} TEST (@strong{begin} EXP1 EXP2 ...))
     1934@end example
    19521935@node Non-standard macros and special forms - Record structures, Non-standard macros and special forms - Other forms, Non-standard macros and special forms - Conditional forms, Non-standard macros and special forms
    19531936@section Record structures
     
    19701953Defines a record type. Call @code{make-NAME} to create an instance of the structure (with one initialization-argument for each slot). @code{(NAME? STRUCT)} tests any object for being an instance of this structure.  Slots are accessed via @code{(NAME-SLOTNAME STRUCT)} and updated using @code{(NAME-SLOTNAME-set!} @code{STRUCT} @code{VALUE)}.
    19711954
    1972 <enscript highlight=scheme> (define-record point x y) (define p1 (make-point 123 456)) (point? p1)                      ==> #t (point-x p1)                     ==> 123 (point-y-set! p1 99) (point-y p1)                     ==> 99 </enscript>
    1973 
     1955@example
     1956(define-record point x y)
     1957(@strong{define} @strong{p1} (make-point 123 456))
     1958(point? p1)                      =@strong{=>} #t
     1959(point-x p1)                     =@strong{=>} 123
     1960(point-y-set! p1 99)
     1961(point-y p1)                     =@strong{=>} 99
     1962@end example
    19741963@node Non-standard macros and special forms - Record structures - define-record-printer, Non-standard macros and special forms - Record structures - define-record-type, Non-standard macros and special forms - Record structures - define-record, Non-standard macros and special forms - Record structures
    19751964@subsection define-record-printer
     
    19821971Defines a printing method for record of the type @code{NAME} by associating a procedure with the record type. When a record of this type is written using @code{display, write} or @code{print}, then the procedure is called with two arguments: the record to be printed and an output-port.
    19831972
    1984 <enscript highlight=scheme> (define-record foo x y z) (define f (make-foo 1 2 3)) (define-record-printer (foo x out)
    1985 
    1986 @verbatim
    1987  (fprintf out "#,(foo ~S ~S ~S)"
    1988           (foo-x x) (foo-y x) (foo-z x)) )
    1989 @end verbatim
    1990 (define-reader-ctor 'foo make-foo) (define s (with-output-to-string
    1991 
    1992 @verbatim
    1993              (lambda () (write f))))
    1994 @end verbatim
    1995 s                                   ==> "#,(foo 1 2 3)" (equal? f (with-input-from-string
    1996 
    1997 @verbatim
    1998              s read)))             ==> #t
    1999 @end verbatim
    2000 </enscript>
    2001 
     1973@example
     1974(define-record foo x y z)
     1975(@strong{define} @strong{f} (make-foo 1 2 3))
     1976(define-record-printer (foo x out)
     1977  (fprintf out @strong{"#,(foo ~S ~S ~S)"}
     1978           (foo-x x) (foo-y x) (foo-z x)) )
     1979(define-reader-ctor 'foo make-foo)
     1980(@strong{define} @strong{s} (with-output-to-string
     1981              (@strong{lambda} () (write f))))
     1982s                                   =@strong{=>} @strong{"#,(foo 1 2 3)"}
     1983(equal? f (with-input-from-string
     1984              s read)))             =@strong{=>} #t
     1985@end example
    20021986@code{define-record-printer} works also with SRFI-9 record types.
    20031987
     
    20632047The following feature-identifiers are available in all situations: @code{(machine-byte-order)}, @code{(machine-type)}, @code{(software-type)}, @code{(software-version)}, where the actual feature-identifier is platform dependent.
    20642048
    2065 In addition the following feature-identifiers may exist: @code{applyhook}, @code{extraslot}, @code{ptables}, @code{dload}, @code{libffi}.
     2049In addition the following feature-identifiers may exist: @code{applyhook}, @code{extraslot}, @code{ptables}, @code{dload}.
    20662050
    20672051For further information, see the documentation for @uref{http://srfi.schemers.org/srfi-0/srfi-0.html, SRFI-0}.
     
    21392123Pattern matching allows complicated control decisions based on data structure to be expressed in a concise manner.  Pattern matching is found in several modern languages, notably Standard ML, Haskell and Miranda. These syntactic extensions internally use the @code{match} library unit.
    21402124
     2125Note: this pattern matching package is not compatible with hygienic macro-expanders like the @code{syntax-case} extension (available separately).
     2126
    21412127The basic form of pattern matching expression is:
    21422128
    2143 <enscript highlight=scheme> (match exp [pat body] ...) </enscript>
    2144 
     2129@example
     2130(match exp [pat body] ...)
     2131@end example
    21452132where @code{exp} is an expression, @code{pat} is a pattern, and @code{body} is one or more expressions (like the body of a lambda-expression). The @code{match} form matches its first subexpression against a sequence of patterns, and branches to the @code{body} corresponding to the first pattern successfully matched. For example, the following code defines the usual @code{map} function:
    21462133
    2147 <enscript highlight=scheme> (define map
    2148 
    2149 @verbatim
    2150  (lambda (f l)
    2151    (match l
    2152      [() '()]
    2153      [(x . y) (cons (f x) (map f y))])))
    2154 @end verbatim
    2155 </enscript>
    2156 
     2134@example
     2135(@strong{define} @strong{map}
     2136  (@strong{lambda} (f l)
     2137    (match l
     2138      [() '()]
     2139      [(x . y) (cons (f x) (map f y))])))
     2140@end example
    21572141The first pattern @code{()} matches the empty list.  The second pattern @code{(x . y)} matches a pair, binding @code{x} to the first component of the pair and @code{y} to the second component of the pair.
    21582142
     
    22272211                             a vector of n+k or more elements
    22282212    |  ,pat                  a pattern
    2229     |  ,@@pat                 a pattern, spliced
     2213    |  ,@pat                 a pattern, spliced
    22302214@end verbatim
    22312215The notation @code{..k} denotes a keyword consisting of three consecutive dots (ie., @emph{@code{...}}),  or two dots and an non-negative integer (eg., @emph{@code{..1}}, @emph{@code{..2}}), or three consecutive underscores (ie., @emph{@code{___}}), or two underscores and a non-negative integer. The keywords @emph{@code{..k}} and @emph{@code{__ k}} are equivalent. The keywords @emph{@code{...}}, @emph{@code{___}}, @emph{@code{..0}}, and @emph{@code{__0}} are equivalent.
     
    22352219The @code{match-lambda} and @code{match-lambda*} forms are convenient combinations of @code{match} and @code{lambda}, and can be explained as follows:
    22362220
    2237 <enscript highlight=scheme> (match-lambda [pat body] ...)   =  (lambda (x) (match x [pat body] ...)) (match-lambda* [pat body] ...)  =  (lambda x (match x [pat body] ...)) </enscript>
    2238 
     2221@example
     2222(match-lambda [pat body] ...)   =  (@strong{lambda} (x) (match x [pat body] ...))
     2223(match-lambda* [pat body] ...)  =  (@strong{lambda} x (match x [pat body] ...))
     2224@end example
    22392225where @code{x} is a unique variable. The @code{match-lambda} form is convenient when defining a single argument function that immediately destructures its argument. The @code{match-lambda*} form constructs a function that accepts any number of arguments; the patterns of @code{match-lambda*} should be lists.
    22402226
    22412227The @code{match-let}, @code{match-let*}, @code{match-letrec}, and @code{match-define} forms generalize Scheme's @code{let}, @code{let*}, @code{letrec}, and @code{define} expressions to allow patterns in the binding position rather than just variables. For example, the following expression:
    22422228
    2243 <enscript highlight=scheme> (match-let ([(x y z) (list 1 2 3)]) body ...) </enscript>
    2244 
     2229@example
     2230(match-let ([(x y z) (list 1 2 3)]) body ...)
     2231@end example
    22452232binds @code{x} to 1, @code{y} to 2, and @code{z} to 3 in @code{body ...}. These forms are convenient for destructuring the result of a function that returns multiple values as a list or vector. As usual for @code{letrec} and @code{define}, pattern variables bound by @code{match-letrec} and @code{match-define} should not be used in computing the bound value.
    22462233
     
    22632250@code{(pat-1 ... pat-n pat-n+1 ...)}: matches a proper list of @code{n} or more elements, where each element of the tail matches @code{pat-n+1}.  Each pattern variable in @code{pat-n+1} is bound to a list of the matching values.  For example, the expression:
    22642251
    2265 <enscript highlight=scheme> (match '(let ([x 1][y 2]) z)
    2266 
    2267 @verbatim
    2268  [('let ((binding values) ...) exp)  body])
    2269 @end verbatim
    2270 </enscript>
    2271 
     2252@example
     2253(match '(@strong{let} ([x 1][y 2]) z)
     2254  [('@strong{let} ((binding values) ...) exp)  body])
     2255@end example
    22722256binds @code{binding} to the list @code{'(x y)}, @code{values} to the list \@code{'(1 2)}, and @code{exp} to @code{'z} in the body of the @code{match}-expression. For the special case where @code{pat-n+1} is a pattern variable, the list bound to that variable may share with the matched value.
    22732257
     
    22982282@code{(set! identifier)}: matches anything, and binds @code{identifier} to a procedure of one argument that mutates the corresponding field of the matching value. This pattern must be nested within a pair, vector, box, or structure pattern. For example, the expression:
    22992283
    2300 <enscript highlight=scheme> (define x (list 1 (list 2 3))) (match x [(_ (_ (set! setit)))  (setit 4)]) </enscript>
    2301 
     2284@example
     2285(@strong{define} @strong{x} (list 1 (list 2 3)))
     2286(match x [(_ (_ (@strong{set!} setit)))  (setit 4)])
     2287@end example
    23022288mutates the @code{cadadr} of @code{x} to 4, so that @code{x} is @code{'(1 (2 4))}.
    23032289
     
    23122298If no clause matches the value, the default action  is to invoke the procedure @code{(match-error-procedure)} with the value that did not match.  The default definition of @code{(match-error-procedure)} calls @code{error} with an appropriate message:
    23132299
    2314 <enscript highlight=scheme>
    2315 
    2316 @enumerate
    2317 @item ;1> (match 1 (2 2))
    2318 
    2319 
    2320 @end enumerate
    2321 Failed match: Error: no matching clause for : 1 </enscript>
    2322 
     2300@example
     2301#@emph{;1> (match 1 (2 2))
     2302}
     2303Failed match:
     2304Error: no matching clause for @strong{:} 1
     2305@end example
    23232306For most situations, this behavior is adequate, but it can be changed by altering the value of the parameter @code{match-error-control}:
    23242307
     
    23292312
    23302313@end table
    2331 <enscript highlight=scheme> (match-error-control [MODE]) </enscript> Selects a mode that specifies how @code{match...} macro forms are to be expanded.  With no argument this procedure returns the current mode. A single argument specifies the new mode that decides what should happen if no match-clause applies.  The following modes are supported:
     2314@example
     2315(match-error-control [MODE])
     2316@end example
     2317Selects a mode that specifies how @code{match...} macro forms are to be expanded.  With no argument this procedure returns the current mode. A single argument specifies the new mode that decides what should happen if no match-clause applies.  The following modes are supported:
    23322318
    23332319<table>
     
    23672353
    23682354@end table
    2369 <enscript highlight=scheme> (match-error-procedure [PROCEDURE]) </enscript> Sets or returns the procedure called upon a match error. The procedure takes one argument, the value which failed to match. When the error control mode is @code{#:match} a second argument, the source form of the match expression is available.
     2355@example
     2356(match-error-procedure [PROCEDURE])
     2357@end example
     2358Sets or returns the procedure called upon a match error. The procedure takes one argument, the value which failed to match. When the error control mode is @code{#:match} a second argument, the source form of the match expression is available.
    23702359
    23712360@node Pattern matching - Record Structures Pattern, Pattern matching - Code Generation, Pattern matching - Match Failure, Pattern matching
     
    23812370Pattern matching macros are compiled into @code{if}-expressions that decompose the value being matched with standard Scheme procedures, and test the components with standard predicates. Rebinding or lexically shadowing the names of any of these procedures will change the semantics of the @code{match} macros.  The names that should not be rebound or shadowed are:
    23822371
    2383 <enscript highlight=scheme> null? pair? number? string? symbol? boolean? char? procedure? vector? list? equal? car cdr cadr cdddr ... vector-length vector-ref reverse length call/cc </enscript>
    2384 
     2372@example
     2373null? pair? number? string? symbol? boolean? char? procedure? vector? list?
     2374equal?
     2375car cdr cadr cdddr ...
     2376vector-length vector-ref
     2377reverse length call/cc
     2378@end example
    23852379Additionally, the code generated to match a structure pattern like @code{($ Foo pat-1 ... pat-n)} refers to the name @code{Foo?}. This name also should not be shadowed.
    23862380
     
    24012395* Declarations - c-options::
    24022396* Declarations - check-c-syntax::
    2403 * Declarations - compress-literals::
    24042397* Declarations - constant::
    24052398* Declarations - export::
     
    24922485Declares additional C/C++ compiler options that are to be passed to the subsequent compilation pass that translates C to machine code. This declaration will only work if the source file is compiled with the @code{csc} compiler driver.
    24932486
    2494 @node Declarations - check-c-syntax, Declarations - compress-literals, Declarations - c-options, Declarations
     2487@node Declarations - check-c-syntax, Declarations - constant, Declarations - c-options, Declarations
    24952488@section check-c-syntax
    24962489
     
    25022495Enables or disables syntax-checking of embedded C/C++ code fragments. Checking C syntax is the default.
    25032496
    2504 @node Declarations - compress-literals, Declarations - constant, Declarations - check-c-syntax, Declarations
    2505 @section compress-literals
    2506 
    2507 
    2508 @verbatim
    2509 [declaration specifier] (compress-literals [THRESHOLD [INITIALIZER]])
    2510 @end verbatim
    2511 The same as the @code{-compress-literals} compiler option. The threshold argument defaults to 50. If the optional argument @code{INITIALIZER} is given, then the literals will not be created at module startup, but when the procedure with this name will be called.
    2512 
    2513 @node Declarations - constant, Declarations - export, Declarations - compress-literals, Declarations
     2497@node Declarations - constant, Declarations - export, Declarations - check-c-syntax, Declarations
    25142498@section constant
    25152499
     
    27892773Certain behavior of the interpreter and compiled programs can be customized via 'parameters', where a parameter is a procedure of zero or one arguments. To retrieve the value of a parameter call the parameter-procedure with zero arguments. To change the setting of the parameter, call the parameter-procedure with the new value as argument:
    27902774
    2791 <enscript highlight=scheme> (define foo (make-parameter 123)) (foo)                             ==> 123 (foo 99) (foo)                             ==> 99 </enscript>
    2792 
     2775@example
     2776(@strong{define} @strong{foo} (make-parameter 123))
     2777(foo)                             =@strong{=>} 123
     2778(foo 99)
     2779(foo)                             =@strong{=>} 99
     2780@end example
    27932781Parameters are fully thread-local, each thread of execution owns a local copy of a parameters' value.
    27942782
     
    29002888* Unit library - Execution time::
    29012889* Unit library - Interrupts and error-handling::
    2902 * Unit library - Garbage collection::
     2890* Unit library - Garbage collection procedures::
    29032891* Unit library - Other control structures::
    29042892* Unit library - String utilities::
     
    29062894* Unit library - Standard Input/Output::
    29072895* Unit library - User-defined named characters::
     2896* Unit library - Blobs::
    29082897* Unit library - Vectors::
    29092898* Unit library - The unspecified value::
     
    29112900* Unit library - Setters::
    29122901* Unit library - Reader extensions::
     2902* Unit library - Property lists::
    29132903
    29142904@end menu
     
    29272917* Unit library - Arithmetic - Arithmetic fixnum operations::
    29282918* Unit library - Arithmetic - Arithmetic floating-point operations::
     2919* Unit library - Arithmetic - flonum-print-precision::
    29292920* Unit library - Arithmetic - signum::
    29302921* Unit library - Arithmetic - finite?::
     
    29522943
    29532944
    2954 Binary integer operations. @code{arithmetic-shift} shifts the argument @code{N1} by @code{N2} bits to the left. If @code{N2} is negative, than @code{N1} is shifted to the right.  These operations only accept exact integers or inexact integers in word range (32 bit signed on 32-bit platforms, or 64 bit signed on 64-bit platforms).
     2945Binary integer operations. @code{arithmetic-shift} shifts the argument @code{N1} by @code{N2} bits to the left. If @code{N2} is negative, than @code{N1} is shifted to the right. These operations only accept exact integers or inexact integers in word range (32 bit signed on 32-bit platforms, or 64 bit signed on 64-bit platforms).
    29552946
    29562947@table @b
     
    30603051
    30613052@end table
    3062 @node Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic - signum, Unit library - Arithmetic - Arithmetic fixnum operations, Unit library - Arithmetic
     3053@node Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic - flonum-print-precision, Unit library - Arithmetic - Arithmetic fixnum operations, Unit library - Arithmetic
    30633054@subsection Arithmetic floating-point operations
    30643055
    30653056
    3066 In safe mode, these procedures throw a type error with non-float arguments (except @code{flonum?}, which returns @code{#f}).  In unsafe mode, these procedures do not check their arguments. A non-flonum argument in unsafe mode can crash the system.
     3057In safe mode, these procedures throw a type error with non-float arguments (except @code{flonum?}, which returns @code{#f}). In unsafe mode, these procedures do not check their arguments. A non-flonum argument in unsafe mode can crash the system.
    30673058
    30683059@table @b
     
    31083099
    31093100@end table
    3110 @node Unit library - Arithmetic - signum, Unit library - Arithmetic - finite?, Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic
     3101@node Unit library - Arithmetic - flonum-print-precision, Unit library - Arithmetic - signum, Unit library - Arithmetic - Arithmetic floating-point operations, Unit library - Arithmetic
     3102@subsection flonum-print-precision
     3103
     3104
     3105@verbatim
     3106[procedure] (flonum-print-precision [PRECISION])
     3107@end verbatim
     3108Gets and sets the number of significant digits printed for a floating-point number. @code{PRECISION} must be a positive @code{fixnum}. Always returns the setting in effect at the moment of invocation.
     3109
     3110@node Unit library - Arithmetic - signum, Unit library - Arithmetic - finite?, Unit library - Arithmetic - flonum-print-precision, Unit library - Arithmetic
    31113111@subsection signum
    31123112
     
    31153115[procedure] (signum N)
    31163116@end verbatim
    3117 Returns @code{1} if @code{N} is positive, @code{-1} if @code{N}  is negative or @code{0} if @code{N} is zero. @code{signum} is exactness preserving.
     3117Returns @code{1} if @code{N} is positive, @code{-1} if @code{N} is negative or @code{0} if @code{N} is zero. @code{signum} is exactness preserving.
    31183118
    31193119@node Unit library - Arithmetic - finite?,  , Unit library - Arithmetic - signum, Unit library - Arithmetic
     
    31473147[procedure] (current-output-port [PORT])
    31483148@end verbatim
    3149 Returns default output port.  If @code{PORT} is given, then that port is selected as the new current output port.
    3150 
    3151 Note that the default output port is not buffered. Use @ref{Unit posix - Setting the file buffering mode, @code{set-buffering-mode!}} if you need a different behaviour.
     3149Returns default output port. If @code{PORT} is given, then that port is selected as the new current output port.
     3150
     3151Note that the default output port is not buffered. Use [[Unit posix#Setting the file buffering mode|@code{set-buffering-mode!}]] if you need a different behavior.
    31523152
    31533153@node Unit library - File Input/Output - current-error-port, Unit library - File Input/Output - flush-output, Unit library - File Input/Output - current-output-port, Unit library - File Input/Output
     
    31603160Returns default error output port. If @code{PORT} is given, then that port is selected as the new current error output port.
    31613161
    3162 Note that the default error output port is not buffered. Use @ref{Unit posix - Setting the file buffering mode, @code{set-buffering-mode!}} if you need a different behaviour.
     3162Note that the default error output port is not buffered. Use [[Unit posix#Setting the file buffering mode|@code{set-buffering-mode!}]] if you need a different behavior.
    31633163
    31643164@node Unit library - File Input/Output - flush-output, Unit library - File Input/Output - port-name, Unit library - File Input/Output - current-error-port, Unit library - File Input/Output
     
    31783178[procedure] (port-name [PORT])
    31793179@end verbatim
    3180 Fetch filename from @code{PORT}. This returns the filename that was used to open this file.  Returns a special tag string, enclosed into parentheses for non-file ports. @code{PORT} defaults to the value of @code{(current-input-port)}.
     3180Fetch filename from @code{PORT}. This returns the filename that was used to open this file. Returns a special tag string, enclosed into parentheses for non-file ports. @code{PORT} defaults to the value of @code{(current-input-port)}.
    31813181
    31823182@node Unit library - File Input/Output - port-position, Unit library - File Input/Output - set-port-name!, Unit library - File Input/Output - port-name, Unit library - File Input/Output
     
    32863286
    32873287
    3288 CHICKEN maintains a global list of @emph{features} naming functionality available int the current system. Additionally the @code{cond-expand} form accesses this feature list to infer what features are provided. Predefined features are @code{chicken}, and the SRFIs (Scheme Request For Implementation) provided by the base system: @code{srfi-23, srfi-30, srfi-39}. If the @code{eval} unit is used (the default), the features @code{srfi-0, srfi-2, srfi-6, srfi-8, srfi-9} and @code{srfi-10} are defined. When compiling code (during compile-time) the feature @code{compiling} is registered. When evaluating code in the interpreter (csi), the feature @code{csi} is registered.
     3288CHICKEN maintains a global list of @emph{features} naming functionality available in the current system. Additionally the @code{cond-expand} form accesses this feature list to infer what features are provided. Predefined features are @code{chicken}, and the SRFIs (Scheme Request For Implementation) provided by the base system: @code{srfi-23, srfi-30, srfi-39}. If the @code{eval} unit is used (the default), the features @code{srfi-0, srfi-2, srfi-6, srfi-8, srfi-9} and @code{srfi-10} are defined. When compiling code (during compile-time) the feature @code{compiling} is registered. When evaluating code in the interpreter (csi), the feature @code{csi} is registered.
    32893289
    32903290@node Unit library - Feature identifiers - features, Unit library - Feature identifiers - feature?,  , Unit library - Feature identifiers
     
    33363336
    33373337
    3338 Keywords are special symbols prefixed with @code{#:} that evaluate to themselves.  Procedures can use keywords to accept optional named parameters in addition to normal required parameters. Assignment to and bindings of keyword symbols is not allowed. The parameter @code{keyword-style} and the compiler/interpreter option @code{-keyword-style} can be used to allow an additional keyword syntax, either compatible to Common LISP, or to DSSSL.
     3338Keywords are special symbols prefixed with @code{#:} that evaluate to themselves. Procedures can use keywords to accept optional named parameters in addition to normal required parameters. Assignment to and bindings of keyword symbols is not allowed. The parameter @code{keyword-style} and the compiler/interpreter option @code{-keyword-style} can be used to allow an additional keyword syntax, either compatible to Common LISP, or to DSSSL.
    33393339
    33403340@node Unit library - Keywords - get-keyword, Unit library - Keywords - keyword?,  , Unit library - Keywords
     
    33453345[procedure] (get-keyword KEYWORD ARGLIST [THUNK])
    33463346@end verbatim
    3347 Returns the argument from @code{ARGLIST} specified under the keyword @code{KEYWORD}.  If the keyword is not found, then the zero-argument procedure @code{THUNK} is invoked and the result value is returned. If @code{THUNK} is not given, @code{#f} is returned.
    3348 
    3349 <enscript highlight=scheme> (define (increase x . args)
    3350 
    3351 @verbatim
    3352  (+ x (get-keyword #:amount args (lambda () 1))) )
    3353 @end verbatim
    3354 (increase 123)                                      ==> 124 (increase 123 #:amount 10)                          ==> 133 </enscript>
    3355 
     3347Returns the argument from @code{ARGLIST} specified under the keyword @code{KEYWORD}. If the keyword is not found, then the zero-argument procedure @code{THUNK} is invoked and the result value is returned. If @code{THUNK} is not given, @code{#f} is returned.
     3348
     3349@example
     3350(@strong{define} (@strong{increase} x . args)
     3351  (+ x (get-keyword #:amount args (@strong{lambda} () 1))) )
     3352(increase 123)                                      =@strong{=>} 124
     3353(increase 123 #:amount 10)                          =@strong{=>} 133
     3354@end example
    33563355Note: the @code{KEYWORD} may actually be any kind of object.
    33573356
     
    34043403Evaluates @code{EXPRESSION} and handles any exceptions that are covered by @code{CLAUSE ...}, where @code{CLAUSE} should be of the following form:
    34053404
    3406 <enscript highlight=scheme> CLAUSE = ([VARIABLE] (KIND ...) BODY ...) </enscript>
    3407 
    3408 If provided, @code{VARIABLE} will be bound to the signalled exception object. @code{BODY ...} is executed when the exception is a property- or composite condition with the kinds given @code{KIND ...} (unevaluated). If no clause applies, the exception is re-signalled in the same dynamic context as the @code{condition-case} form.
    3409 
    3410 <enscript highlight=scheme> (define (check thunk)
    3411 
    3412 @verbatim
    3413  (condition-case (thunk)
    3414    [(exn file) (print "file error")]
    3415    [(exn) (print "other error")]
    3416    [var () (print "something else")] ) )
    3417 @end verbatim
    3418 (check (lambda () (open-input-file "")))   ; -> "file error" (check (lambda () some-unbound-variable))  ; -> "othererror" (check (lambda () (signal 99)))            ; -> "something else"
    3419 
     3405@example
     3406CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
     3407@end example
     3408If provided, @code{VARIABLE} will be bound to the signaled exception object. @code{BODY ...} is executed when the exception is a property- or composite condition with the kinds given @code{KIND ...} (unevaluated). If no clause applies, the exception is re-signaled in the same dynamic context as the @code{condition-case} form.
     3409
     3410@example
     3411(@strong{define} (@strong{check} thunk)
     3412  (condition-case (thunk)
     3413    [(exn file) (print @strong{"file error"})]
     3414    [(exn) (print @strong{"other error"})]
     3415    [var () (print @strong{"something else"})] ) )
     3416
     3417(check (@strong{lambda} () (open-input-file @strong{""})))   @emph{; -> "file error"
     3418}(check (@strong{lambda} () some-unbound-variable))  @emph{; -> "othererror"
     3419}(check (@strong{lambda} () (signal 99)))            @emph{; -> "something else"
     3420}
    34203421(condition-case some-unbound-variable
    3421 
    3422 @verbatim
    3423  [(exn file) (print "ignored")] )      ; -> signals error
    3424 @end verbatim
    3425 </enscript>
    3426 
     3422  [(exn file) (print @strong{"ignored"})] )      @emph{; -> signals error
     3423}
     3424@end example
    34273425@node Unit library - Exceptions - breakpoint,  , Unit library - Exceptions - condition-case, Unit library - Exceptions
    34283426@subsection breakpoint
     
    34343432Programmatically triggers a breakpoint (similar to the @code{,br} top-level csi command).
    34353433
    3436 All error-conditions signalled by the system are of kind @code{exn}. The following composite conditions are additionally defined:
     3434All error-conditions signaled by the system are of kind @code{exn}. The following composite conditions are additionally defined:
    34373435
    34383436<table>
     
    34403438<tr><td> (exn arity)
    34413439
    3442 Signalled when a procedure is called with the wrong number of arguments.
     3440Signaled when a procedure is called with the wrong number of arguments.
    34433441
    34443442</td></tr><tr><td> (exn type)
    34453443
    3446 Signalled on type-mismatch errors, for example when an argument of the wrong type is passed to a builtin procedure.
     3444Signaled on type-mismatch errors, for example when an argument of the wrong type is passed to a built-in procedure.
    34473445
    34483446</td></tr><tr><td> (exn arithmetic)
    34493447
    3450 Signalled on arithmetic errors, like division by zero.
     3448Signaled on arithmetic errors, like division by zero.
    34513449
    34523450</td></tr><tr><td> (exn i/o)
    34533451
    3454 Signalled on input/output errors.
     3452Signaled on input/output errors.
    34553453
    34563454</td></tr><tr><td> (exn i/o file)
    34573455
    3458 Signalled on file-related errors.
     3456Signaled on file-related errors.
    34593457
    34603458</td></tr><tr><td> (exn i/o net)
    34613459
    3462 Signalled on network errors.
     3460Signaled on network errors.
    34633461
    34643462</td></tr><tr><td> (exn bounds)
    34653463
    3466 Signalled on errors caused by accessing non-existent elements of a collection.
     3464Signaled on errors caused by accessing non-existent elements of a collection.
    34673465
    34683466</td></tr><tr><td> (exn runtime)
    34693467
    3470 Signalled on low-level runtime-system error-situations.
     3468Signaled on low-level runtime-system error-situations.
    34713469
    34723470</td></tr><tr><td> (exn runtime limit)
    34733471
    3474 Signalled when an internal limit is exceeded (like running out of memory).
     3472Signaled when an internal limit is exceeded (like running out of memory).
    34753473
    34763474</td></tr><tr><td> (exn match)
    34773475
    3478 Signalled on errors raised by failed matches (see the section on @code{match}).
     3476Signaled on errors raised by failed matches (see the section on @code{match}).
    34793477
    34803478</td></tr><tr><td> (exn syntax)
    34813479
    3482 Signalled on syntax errors.
     3480Signaled on syntax errors.
    34833481
    34843482</td></tr><tr><td> (exn breakpoint)
    34853483
    3486 Signalled when a breakpoint is reached.
     3484Signaled when a breakpoint is reached.
    34873485
    34883486</td></tr>
     
    34993497@item When the @code{posix} unit is available and used, then a user-interrupt (@code{signal/int}) signals an exception of the kind @code{user-interrupt}.
    35003498
    3501 @item the procedure @code{condition-property-accessor} accepts an optional third argument. If the condition does not have a value for the desired property and if the optional argument is given, no error is signalled and the accessor returns the third argument.
    3502 
    3503 @item In composite conditionss all properties are currently collected in a single property-list, so in the case that to conditions have the same named property, only one will be visible.
     3499@item the procedure @code{condition-property-accessor} accepts an optional third argument. If the condition does not have a value for the desired property and if the optional argument is given, no error is signaled and the accessor returns the third argument.
     3500
     3501@item In composite conditions all properties are currently collected in a single property-list, so in the case that to conditions have the same named property, only one will be visible.
    35043502
    35053503
     
    35123510* Unit library - Environment information and system interface - exit::
    35133511* Unit library - Environment information and system interface - build-platform::
    3514 * Unit library - Environment information and system interface - build-style::
    35153512* Unit library - Environment information and system interface - chicken-version::
    35163513* Unit library - Environment information and system interface - errno::
     
    35343531[procedure] (argv)
    35353532@end verbatim
    3536 Return a list of all supplied command-line arguments. The first item in the list is a string containing the name of the executing program. The other items are the arguments passed to the application. This list is freshly created on every invocation of @code{(argv)}.  It depends on the host-shell whether arguments are expanded ('globbed') or not.
     3533Return a list of all supplied command-line arguments. The first item in the list is a string containing the name of the executing program. The other items are the arguments passed to the application. This list is freshly created on every invocation of @code{(argv)}. It depends on the host-shell whether arguments are expanded ('globbed') or not.
    35373534
    35383535@node Unit library - Environment information and system interface - exit, Unit library - Environment information and system interface - build-platform, Unit library - Environment information and system interface - argv, Unit library - Environment information and system interface
     
    35453542Exit the running process and return exit-code, which defaults to 0 (Invokes @code{exit-handler}).
    35463543
    3547 @node Unit library - Environment information and system interface - build-platform, Unit library - Environment information and system interface - build-style, Unit library - Environment information and system interface - exit, Unit library - Environment information and system interface
     3544Note that pending @code{dynamic-wind} thunks are @emph{not} invoked when exiting your program in this way.
     3545
     3546@node Unit library - Environment information and system interface - build-platform, Unit library - Environment information and system interface - chicken-version, Unit library - Environment information and system interface - exit, Unit library - Environment information and system interface
    35483547@subsection build-platform
    35493548
     
    35563555@verbatim
    35573556cygwin
    3558 msvc
    35593557mingw32
    35603558gnu
    3561 metrowerks
    35623559intel
    3563 watcom
    35643560unknown
    35653561@end verbatim
    3566 @node Unit library - Environment information and system interface - build-style, Unit library - Environment information and system interface - chicken-version, Unit library - Environment information and system interface - build-platform, Unit library - Environment information and system interface
    3567 @subsection build-style
    3568 
    3569 
    3570 @verbatim
    3571  [procedure] (build-style)
    3572 @end verbatim
    3573 Returns a symbol indicating the build system used to create the CHICKEN instance running this program. Possible values are:
    3574 
    3575 @verbatim
    3576  cmake
    3577  autotools
    3578  diy
    3579  custom
    3580 @end verbatim
    3581 @node Unit library - Environment information and system interface - chicken-version, Unit library - Environment information and system interface - errno, Unit library - Environment information and system interface - build-style, Unit library - Environment information and system interface
     3562@node Unit library - Environment information and system interface - chicken-version, Unit library - Environment information and system interface - errno, Unit library - Environment information and system interface - build-platform, Unit library - Environment information and system interface
    35823563@subsection chicken-version
    35833564
     
    36443625[procedure] (on-exit THUNK)
    36453626@end verbatim
    3646 Schedules the zero-argument procexdures @code{THUNK} to be executed before the process exits, either explicitly via @code{exit} or implicitly after exection of the last toplevel form. Note that finalizers for unreferenced finalized data are run before exit procedures.
     3627Schedules the zero-argument procedures @code{THUNK} to be executed before the process exits, either explicitly via @code{exit} or implicitly after execution of the last top-level form. Note that finalizers for unreferenced finalized data are run before exit procedures.
    36473628
    36483629@node Unit library - Environment information and system interface - software-type, Unit library - Environment information and system interface - software-version, Unit library - Environment information and system interface - on-exit, Unit library - Environment information and system interface
     
    37483729Returns the number of milliseconds spent in major garbage collections since the last call of @code{current-gc-milliseconds} and returns an exact integer.
    37493730
    3750 @node Unit library - Interrupts and error-handling, Unit library - Garbage collection, Unit library - Execution time, Unit library
     3731@node Unit library - Interrupts and error-handling, Unit library - Garbage collection procedures, Unit library - Execution time, Unit library
    37513732@section Interrupts and error-handling
    37523733
     
    37813762[procedure] (error [LOCATION] [STRING] EXP ...)
    37823763@end verbatim
    3783 Prints error message, writes all extra arguments to the value of @code{(current-error-port)} and invokes the current exception-handler.  This conforms to @uref{http://srfi.schemers.org/srfi-23/srfi-23.html, SRFI-23}. If @code{LOCATION} is given and a symbol, it specifies the @emph{location} (the name of the procedure) where the error occurred.
     3764Prints error message, writes all extra arguments to the value of @code{(current-error-port)} and invokes the current exception-handler. This conforms to @uref{http://srfi.schemers.org/srfi-23/srfi-23.html, SRFI-23}. If @code{LOCATION} is given and a symbol, it specifies the @emph{location} (the name of the procedure) where the error occurred.
    37843765
    37853766@node Unit library - Interrupts and error-handling - get-call-chain, Unit library - Interrupts and error-handling - print-call-chain, Unit library - Interrupts and error-handling - error, Unit library - Interrupts and error-handling
     
    37903771[procedure] (get-call-chain [START [THREAD]])
    37913772@end verbatim
    3792 Returns a list with the call history. Backtrace information is only generated in code compiled without @code{-no-trace} and evaluated code. If the optional argument @code{START} is given, the backtrace starts at this offset, i.e. when @code{START} is 1, the next to last trace-entry  is printed, and so on. If the optional argument @code{THREAD} is given, then the call-chain will only be constructed for calls performed by this thread.
     3773Returns a list with the call history. Backtrace information is only generated in code compiled without @code{-no-trace} and evaluated code. If the optional argument @code{START} is given, the backtrace starts at this offset, i.e. when @code{START} is 1, the next to last trace-entry is printed, and so on. If the optional argument @code{THREAD} is given, then the call-chain will only be constructed for calls performed by this thread.
    37933774
    37943775@node Unit library - Interrupts and error-handling - print-call-chain, Unit library - Interrupts and error-handling - print-error-message, Unit library - Interrupts and error-handling - get-call-chain, Unit library - Interrupts and error-handling
     
    38463827Executes the code in the zero-procedure @code{THUNK} in single-stepping mode.
    38473828
    3848 @node Unit library - Garbage collection, Unit library - Other control structures, Unit library - Interrupts and error-handling, Unit library
    3849 @section Garbage collection
    3850 
    3851 @menu
    3852 * Unit library - Garbage collection - gc::
    3853 * Unit library - Garbage collection - memory-statistics::
    3854 * Unit library - Garbage collection - set-finalizer!::
    3855 * Unit library - Garbage collection - set-gc-report!::
    3856 
    3857 @end menu
    3858 
    3859 
    3860 @node Unit library - Garbage collection - gc, Unit library - Garbage collection - memory-statistics,  , Unit library - Garbage collection
     3829@node Unit library - Garbage collection procedures, Unit library - Other control structures, Unit library - Interrupts and error-handling, Unit library
     3830@section Garbage collection procedures
     3831
     3832@menu
     3833* Unit library - Garbage collection procedures - gc::
     3834* Unit library - Garbage collection procedures - memory-statistics::
     3835* Unit library - Garbage collection procedures - set-finalizer!::
     3836* Unit library - Garbage collection procedures - set-gc-report!::
     3837
     3838@end menu
     3839
     3840
     3841@node Unit library - Garbage collection procedures - gc, Unit library - Garbage collection procedures - memory-statistics,  , Unit library - Garbage collection procedures
    38613842@subsection gc
    38623843
     
    38653846[procedure] (gc [FLAG])
    38663847@end verbatim
    3867 Invokes a garbage-collection and returns the number of free bytes in the heap. The flag specifies whether a minor (@code{#f}) or major (@code{#t}) GC is to be triggered. If no argument is given, @code{#t} is assumed. When the argument is @code{#t}, all pending finalizers are executed.
    3868 
    3869 @node Unit library - Garbage collection - memory-statistics, Unit library - Garbage collection - set-finalizer!, Unit library - Garbage collection - gc, Unit library - Garbage collection
     3848Invokes a garbage-collection and returns the number of free bytes in the heap. The flag specifies whether a minor (@code{#f}) or major (@code{#t}) GC is to be triggered. If no argument is given, @code{#t} is assumed. An explicit @code{#t} argument will cause all pending finalizers to be executed.
     3849
     3850@node Unit library - Garbage collection procedures - memory-statistics, Unit library - Garbage collection procedures - set-finalizer!, Unit library - Garbage collection procedures - gc, Unit library - Garbage collection procedures
    38703851@subsection memory-statistics
    38713852
     
    38743855[procedure] (memory-statistics)
    38753856@end verbatim
    3876 Performs a major garbage collection and returns a three element vector  containing the total heap size in bytes, the number of bytes currently used and the size of the nursery (the first heap generation). Note that the actual heap is actually twice the size given in the heap size, because CHICKEN uses a copying semi-space collector.
    3877 
    3878 @node Unit library - Garbage collection - set-finalizer!, Unit library - Garbage collection - set-gc-report!, Unit library - Garbage collection - memory-statistics, Unit library - Garbage collection
     3857Performs a major garbage collection and returns a three element vector containing the total heap size in bytes, the number of bytes currently used and the size of the nursery (the first heap generation). Note that the actual heap is actually twice the size given in the heap size, because CHICKEN uses a copying semi-space collector.
     3858
     3859@node Unit library - Garbage collection procedures - set-finalizer!, Unit library - Garbage collection procedures - set-gc-report!, Unit library - Garbage collection procedures - memory-statistics, Unit library - Garbage collection procedures
    38793860@subsection set-finalizer!
    38803861
     
    38833864[procedure] (set-finalizer! X PROC)
    38843865@end verbatim
    3885 Registers a procedure of one argument @code{PROC}, that will be called as soon as the non-immediate data object @code{X} is about to be garbage-collected (with that object as its argument).  Note that the finalizer will @b{not} be called while interrupts are disabled. This procedure returns @code{X}.
    3886 
    3887 @node Unit library - Garbage collection - set-gc-report!,  , Unit library - Garbage collection - set-finalizer!, Unit library - Garbage collection
     3866Registers a procedure of one argument @code{PROC}, that will be called as soon as the non-immediate data object @code{X} is about to be garbage-collected (with that object as its argument). Note that the finalizer will @b{not} be called while interrupts are disabled. This procedure returns @code{X}.
     3867
     3868@node Unit library - Garbage collection procedures - set-gc-report!,  , Unit library - Garbage collection procedures - set-finalizer!, Unit library - Garbage collection procedures
    38883869@subsection set-gc-report!
    38893870
     
    38943875Print statistics after every GC, depending on @code{FLAG}. A value of @code{#t} shows statistics after every major GC. A true value different from @code{#t} shows statistics after every minor GC. @code{#f} switches statistics off.
    38953876
    3896 @node Unit library - Other control structures, Unit library - String utilities, Unit library - Garbage collection, Unit library
     3877@node Unit library - Other control structures, Unit library - String utilities, Unit library - Garbage collection procedures, Unit library
    38973878@section Other control structures
    38983879
    38993880@menu
    3900 * Unit library - Other control structures - andmap::
    3901 * Unit library - Other control structures - ormap::
    39023881* Unit library - Other control structures - promise?::
    39033882
     
    39053884
    39063885
    3907 @node Unit library - Other control structures - andmap, Unit library - Other control structures - ormap,  , Unit library - Other control structures
    3908 @subsection andmap
    3909 
    3910 
    3911 @verbatim
    3912 [procedure] (andmap PROC LIST1 ...)
    3913 @end verbatim
    3914 Repeatedly calls @code{PROC} with arguments taken from @code{LIST1 ...}.   If any invocation should return @code{#f}, the result of @code{andmap} is @code{#f}. If all invocations return a true result, then the result of @code{andmap} is @code{#t}.
    3915 
    3916 @node Unit library - Other control structures - ormap, Unit library - Other control structures - promise?, Unit library - Other control structures - andmap, Unit library - Other control structures
    3917 @subsection ormap
    3918 
    3919 
    3920 @verbatim
    3921 [procedure] (ormap PROC LIST1 ...)
    3922 @end verbatim
    3923 Repeatedly calls @code{PROC} with arguments taken from @code{LIST1 ...}.   If any invocation should return a value different from @code{#f}, then this value is returned as the  result of @code{ormap}. If all invocations return @b{#f}, then the result of @code{ormap} is @code{#f}.
    3924 
    3925 @node Unit library - Other control structures - promise?,  , Unit library - Other control structures - ormap, Unit library - Other control structures
     3886@node Unit library - Other control structures - promise?,  ,  , Unit library - Other control structures
    39263887@subsection promise?
    39273888
     
    40033964
    40043965@verbatim
    4005 [procedure] (print EXP1 EXP2 ...)
    4006 @end verbatim
    4007 Outputs the arguments @code{EXP1 EXP2 ...} using @code{display} and writes a newline character to the port that is the value of @code{(current-output-port)}. Returns its first argument.
     3966[procedure] (print [EXP1 ...])
     3967@end verbatim
     3968Outputs the optional arguments @code{EXP1 ...} using @code{display} and writes a newline character to the port that is the value of @code{(current-output-port)}. Returns @code{(void)}.
    40083969
    40093970@node Unit library - Standard Input/Output - print*,  , Unit library - Standard Input/Output - print, Unit library - Standard Input/Output
     
    40123973
    40133974@verbatim
    4014 [procedure] (print* EXP1 ...)
    4015 @end verbatim
    4016 Similar to @code{print}, but does not output a terminating newline character and performs a @code{flush-outout} after writing its arguments.
    4017 
    4018 @node Unit library - User-defined named characters, Unit library - Vectors, Unit library - Standard Input/Output, Unit library
     3975[procedure] (print* [EXP1 ...])
     3976@end verbatim
     3977Similar to @code{print}, but does not output a terminating newline character and performs a @code{flush-output} after writing its arguments.
     3978
     3979@node Unit library - User-defined named characters, Unit library - Blobs, Unit library - Standard Input/Output, Unit library
    40193980@section User-defined named characters
    40203981
     
    40323993[procedure] (char-name SYMBOL-OR-CHAR [CHAR])
    40333994@end verbatim
    4034 This procedure can be used to inquire about character names or to define new ones. With a single argument the behavior is as follows: If @code{SYMBOL-OR-CHAR} is a symbol, then @code{char-name} returns the character with this name, or @code{#f} if no character is defined under this name.  If @code{SYMBOL-OR-CHAR} is a character, then the name of the character is returned as a symbol, or @code{#f} if the character has no associated name.
    4035 
    4036 If the optional argument @code{CHAR} is provided, then @code{SYMBOL-OR-CHAR} should be a symbol that will be the new name of the given character.  If multiple names designate the same character, then the @code{write} will use the character name that was defined last.
    4037 
    4038 <enscript highlight=scheme> (char-name 'space)                  ==> #\space (char-name #\space)                 ==> space (char-name 'bell)                   ==> #f (char-name (integer->char 7))       ==> #f (char-name 'bell (integer->char 7)) (char-name 'bell)                   ==> #\bell (char->integer (char-name 'bell))   ==> 7 </enscript>
    4039 
    4040 @node Unit library - Vectors, Unit library - The unspecified value, Unit library - User-defined named characters, Unit library
     3995This procedure can be used to inquire about character names or to define new ones. With a single argument the behavior is as follows: If @code{SYMBOL-OR-CHAR} is a symbol, then @code{char-name} returns the character with this name, or @code{#f} if no character is defined under this name. If @code{SYMBOL-OR-CHAR} is a character, then the name of the character is returned as a symbol, or @code{#f} if the character has no associated name.
     3996
     3997If the optional argument @code{CHAR} is provided, then @code{SYMBOL-OR-CHAR} should be a symbol that will be the new name of the given character. If multiple names designate the same character, then the @code{write} will use the character name that was defined last.
     3998
     3999@example
     4000(char-name 'space)                  =@strong{=>} #\space
     4001(char-name #\space)                 =@strong{=>} space
     4002(char-name 'bell)                   =@strong{=>} #f
     4003(char-name (integer->char 7))       =@strong{=>} #f
     4004(char-name 'bell (integer->char 7))
     4005(char-name 'bell)                   =@strong{=>} #\bell
     4006(char->integer (char-name 'bell))   =@strong{=>} 7
     4007@end example
     4008@node Unit library - Blobs, Unit library - Vectors, Unit library - User-defined named characters, Unit library
     4009@section Blobs
     4010
     4011@menu
     4012* Unit library - Blobs - make-blob::
     4013* Unit library - Blobs - blob?::
     4014* Unit library - Blobs - blob-size::
     4015* Unit library - Blobs - blob->string::
     4016* Unit library - Blobs - string->blob::
     4017* Unit library - Blobs - blob=?::
     4018
     4019@end menu
     4020
     4021
     4022"blobs" are collections of unstructured bytes. You can't do much with them, but allow conversion to and from SRFI-4 number vectors.
     4023
     4024@node Unit library - Blobs - make-blob, Unit library - Blobs - blob?,  , Unit library - Blobs
     4025@subsection make-blob
     4026
     4027
     4028@verbatim
     4029[procedure] (make-blob SIZE)
     4030@end verbatim
     4031Returns a blob object of @code{SIZE} bytes, aligned on an 8-byte boundary, uninitialized.
     4032
     4033@node Unit library - Blobs - blob?, Unit library - Blobs - blob-size, Unit library - Blobs - make-blob, Unit library - Blobs
     4034@subsection blob?
     4035
     4036
     4037@verbatim
     4038[procedure] (blob? X)
     4039@end verbatim
     4040Returns @code{#t} if @code{X} is a blob object, or @code{#f} otherwise.
     4041
     4042@node Unit library - Blobs - blob-size, Unit library - Blobs - blob->string, Unit library - Blobs - blob?, Unit library - Blobs
     4043@subsection blob-size
     4044
     4045
     4046@verbatim
     4047[procedure] (blob-size BLOB)
     4048@end verbatim
     4049Returns the number of bytes in @code{BLOB}.
     4050
     4051@node Unit library - Blobs - blob->string, Unit library - Blobs - string->blob, Unit library - Blobs - blob-size, Unit library - Blobs
     4052@subsection blob->string
     4053
     4054
     4055@verbatim
     4056[procedure] (blob->string BLOB)
     4057@end verbatim
     4058Returns a string with the contents of @code{BLOB}.
     4059
     4060@node Unit library - Blobs - string->blob, Unit library - Blobs - blob=?, Unit library - Blobs - blob->string, Unit library - Blobs
     4061@subsection string->blob
     4062
     4063
     4064@verbatim
     4065[procedure] (string->blob STRING)
     4066@end verbatim
     4067Returns a blob with the contents of @code{STRING}.
     4068
     4069@node Unit library - Blobs - blob=?,  , Unit library - Blobs - string->blob, Unit library - Blobs
     4070@subsection blob=?
     4071
     4072
     4073@verbatim
     4074[procedure] (blob=? BLOB1 BLOB2)
     4075@end verbatim
     4076Returns @code{#t} if the two argument blobs are of the same size and have the same content.
     4077
     4078@node Unit library - Vectors, Unit library - The unspecified value, Unit library - Blobs, Unit library
    40414079@section Vectors
    40424080
     
    41154153[procedure] (continuation-capture PROCEDURE)
    41164154@end verbatim
    4117 Creates a continuation object representing the current continuation and tail-calls  @code{PROCEDURE} with this continuation as the single argument.
     4155Creates a continuation object representing the current continuation and tail-calls @code{PROCEDURE} with this continuation as the single argument.
    41184156
    41194157More information about this continuation API can be found in the paper @uref{http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf, http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf} @emph{A Better API for first class Continuations} by Marc Feeley.
     
    41264164[procedure] (continuation? X)
    41274165@end verbatim
    4128 Returns @code{#t} if @code{X} is a continuation object, or @code{#f} otherwise.
     4166Returns @code{#t} if @code{X} is a continuation object, or @code{#f} otherwise. Please note that this applies only to continuations created by the Continuation API, but not by call/cc, i.e.: @code{(call-with-current-continuation continuation?)} returns @code{#f}, whereas @code{(continuation-capture continuation?)} returns @code{#t}.
    41294167
    41304168@node Unit library - Continuations - continuation-graft, Unit library - Continuations - continuation-return, Unit library - Continuations - continuation?, Unit library - Continuations
     
    41464184Returns the value(s) to the continuation @code{CONT}. @code{continuation-return} could be implemented like this:
    41474185
    4148 <enscript highlight=scheme> (define (continuation-return k . vals)
    4149 
    4150 @verbatim
    4151  (continuation-graft
    4152    k
    4153    (lambda () (apply values vals)) ) )
    4154 @end verbatim
    4155 </enscript>
    4156 
     4186@example
     4187(@strong{define} (@strong{continuation-return} k . vals)
     4188  (continuation-graft
     4189    k
     4190    (@strong{lambda} () (apply values vals)) ) )
     4191@end example
    41574192@node Unit library - Setters, Unit library - Reader extensions, Unit library - Continuations, Unit library
    41584193@section Setters
     
    41874222Returns a copy of the procedure @code{GETTER} with the associated setter procedure @code{SETTER}. Contrary to the SRFI specification, the setter of the returned procedure may be changed.
    41884223
    4189 @node Unit library - Reader extensions,  , Unit library - Setters, Unit library
     4224@node Unit library - Reader extensions, Unit library - Property lists, Unit library - Setters, Unit library
    41904225@section Reader extensions
    41914226
     
    42164251[procedure] (set-read-syntax! CHAR-OR-SYMBOL PROC)
    42174252@end verbatim
    4218 When the reader is encounting the non-whitespace character @code{CHAR} while reading an expression from a given port, then the procedure @code{PROC} will be called with that port as its argument. The procedure should return a value that will be returned to the reader:
    4219 
    4220 <enscript highlight=scheme>
    4221 
    4222 @verbatim
    4223 ; A simple RGB color syntax:
    4224 @end verbatim
    4225 @verbatim
    4226 (set-read-syntax! #\%
    4227   (lambda (port)
    4228     (apply vector
    4229       (map (cut string->number <> 16)
    4230 @end verbatim
     4253When the reader encounters the non-whitespace character @code{CHAR} while reading an expression from a given port, then the procedure @code{PROC} will be called with that port as its argument. The procedure should return a value that will be returned to the reader:
     4254
     4255@example
     4256 @emph{; A simple RGB color syntax:
     4257}
     4258 (set-read-syntax! #\%
     4259   (@strong{lambda} (port)
     4260     (apply vector
     4261       (map (cut string->number <> 16)
    42314262            (string-chop (read-string 6 port) 2) ) ) ) )
    42324263
    4233 @verbatim
    4234 (with-input-from-string "(1 2 %f0f0f0 3)" read)
    4235 ; ==> (1 2 #(240 240 240) 3)
    4236 @end verbatim
    4237 </enscript>
    4238 
     4264 (with-input-from-string @strong{"(1 2 %f0f0f0 3)"} read)
     4265 @emph{; ==> (1 2 #(240 240 240) 3)
     4266}@end example
    42394267If @code{CHAR-OR-SYMBOL} is a symbol, then a so-called @emph{read-mark} handler is defined. In that case the handler procedure will be called when a character-sequence of the form
    42404268
     
    42744302@end verbatim
    42754303Returns a copy of the given read-table. You can access the currently active read-table with @code{(current-read-table)}.
     4304
     4305@node Unit library - Property lists,  , Unit library - Reader extensions, Unit library
     4306@section Property lists
     4307
     4308@menu
     4309* Unit library - Property lists - get::
     4310* Unit library - Property lists - put!::
     4311* Unit library - Property lists - remprop!::
     4312* Unit library - Property lists - symbol-plist::
     4313* Unit library - Property lists - get-properties::
     4314
     4315@end menu
     4316
     4317
     4318As in other Lisp dialects, CHICKEN supports "property lists" associated with symbols. Properties are accessible via a key that can be any kind of value but which will be compared using @code{eq?}.
     4319
     4320@node Unit library - Property lists - get, Unit library - Property lists - put!,  , Unit library - Property lists
     4321@subsection get
     4322
     4323
     4324@verbatim
     4325 [procedure] (get SYMBOL PROPERTY [DEFAULT])
     4326@end verbatim
     4327Returns the value stored under the key @code{PROPERTY} in the property list of @code{SYMBOL}. If no such property is stored, returns @code{DEFAULT}. The @code{DEFAULT} is optional and defaults to @code{#f}.
     4328
     4329@node Unit library - Property lists - put!, Unit library - Property lists - remprop!, Unit library - Property lists - get, Unit library - Property lists
     4330@subsection put!
     4331
     4332
     4333@verbatim
     4334 [procedure] (put! SYMBOL PROPERTY VALUE)
     4335 [setter] (set! (get SYMBOL PROPERTY) VALUE)
     4336@end verbatim
     4337Stores @code{VALUE} under the key @code{PROPERTY} in the property list of @code{SYMBOL} replacing any previously stored value.
     4338
     4339@node Unit library - Property lists - remprop!, Unit library - Property lists - symbol-plist, Unit library - Property lists - put!, Unit library - Property lists
     4340@subsection remprop!
     4341
     4342
     4343@verbatim
     4344 [procedure] (remprop! SYMBOL PROPERTY)
     4345@end verbatim
     4346Deletes the first property matching the key @code{PROPERTY} in the property list of @code{SYMBOL}. Returns @code{#t} when a deletion performed, and @code{#f} otherwise.
     4347
     4348@node Unit library - Property lists - symbol-plist, Unit library - Property lists - get-properties, Unit library - Property lists - remprop!, Unit library - Property lists
     4349@subsection symbol-plist
     4350
     4351
     4352@verbatim
     4353 [procedure] (symbol-plist SYMBOL)
     4354 [setter] (set! (symbol-plist SYMBOL) LST)
     4355@end verbatim
     4356Returns the property list of @code{SYMBOL} or sets it.
     4357
     4358@node Unit library - Property lists - get-properties,  , Unit library - Property lists - symbol-plist, Unit library - Property lists
     4359@subsection get-properties
     4360
     4361
     4362@verbatim
     4363 [procedure] (get-properties SYMBOL PROPERTIES)
     4364@end verbatim
     4365Searches the property list of @code{SYMBOL} for the first property with a key in the list @code{PROPERTIES}. Returns 3 values: the matching property key, value, and the tail of property list after the matching property. When no match found all values are @code{#f}.
     4366
     4367@code{PROPERTIES} may also be an atom, in which case it is treated as a list of one element.
    42764368
    42774369Previous: @ref{Parameters, Parameters}
     
    45104602
    45114603@end table
    4512 Contains a string naming the path to the extension repository, which defaults to either the value of the environment variable @code{CHICKEN_REPOSITORY}, the value of the environment variable @code{CHICKEN_HOME} or the default library path (usually @code{/usr/local/lib/chicken} on UNIX systems).
     4604Contains a string naming the path to the extension repository, which defaults to either the value of the environment variable @code{CHICKEN_REPOSITORY} or the default library path (usually @code{/usr/local/lib/chicken} on UNIX systems).
    45134605
    45144606@node Unit eval - Loading extension libraries - extension-information, Unit eval - Loading extension libraries - provide, Unit eval - Loading extension libraries - repository-path, Unit eval - Loading extension libraries
     
    45504642
    45514643@itemize
    4552 @item the current include path, which defaults to the pathnames given in @code{CHICKEN_INCLUDE_PATH} and @code{CHICKEN_HOME}.
     4644@item the current include path, which defaults to the pathnames given in @code{CHICKEN_INCLUDE_PATH}.
    45534645
    45544646@item the current directory
     
    45674659Registers the handler-procedure @code{PROC} as a extension-specifier with the name @code{SYMBOL}. This facility allows extending the set of valid extension specifiers to be used with @code{require-extension}. When @code{register-extension} is called with an extension specifier of the form @code{(SPEC ...)} and @code{SPEC} has been registered with @code{set-extension-specifier!}, then @code{PROC} will be called with two arguments: the specifier and the previously installed handler (or @code{#f} if no such handler was defined). The handler should return a new specifier that will be processed recursively. If the handler returns a vector, then each element of the vector will be processed recursively.  Alternatively the handler may return a string which specifies a file to be loaded:
    45684660
    4569 <enscript highlight=scheme> (eval-when (compile eval)
    4570 
    4571 @verbatim
    4572  (set-extension-specifier!
    4573    'my-package
    4574    (lambda (spec old)
    4575      (make-pathname my-package-directory (->string (cadr spec))) ) ) )
    4576 @end verbatim
    4577 (require-extension (my-package stuff))     ; --> expands into '(load "my-package-dir/stuff") </enscript>
    4578 
     4661@example
     4662(eval-when (compile eval)
     4663  (set-extension-specifier!
     4664    'my-package
     4665    (@strong{lambda} (spec old)
     4666      (make-pathname my-package-directory (->string (cadr spec))) ) ) )
     4667
     4668(require-extension (my-package stuff))     @emph{; --> expands into '(load "my-package-dir/stuff")
     4669}@end example
    45794670Note that the handler has to be registered at compile time, if it is to be  visible in compiled code.
    45804671
     
    45954686[procedure] (chicken-home)
    45964687@end verbatim
    4597 Returns a string given the installation directory (usually @code{/usr/local/share/chicken} on UNIX-like systems). If the environment variable @code{CHICKEN_HOME} is set, then its value will be returned. As a last option, if the environment variable @code{CHICKEN_PREFIX} is set, then @code{chicken-home} will return @code{$CHICKEN_PREFIX/share}.
     4688Returns a string given the installation directory (usually @code{/usr/local/share/chicken} on UNIX-like systems). As a last option, if the environment variable @code{CHICKEN_PREFIX} is set, then @code{chicken-home} will return @code{$CHICKEN_PREFIX/share}.
    45984689
    45994690@node Unit eval - Eval,  , Unit eval - System information, Unit eval
     
    46384729
    46394730
    4640 This unit contains a collection of useful utility definitions.  This unit is used by default, unless the program is compiled with the @code{-explicit-use} option.
     4731This unit contains a collection of useful utility definitions. This unit is used by default, unless the program is compiled with the @code{-explicit-use} option.
    46414732
    46424733@node Unit extras - Lists, Unit extras - String-port extensions,  , Unit extras
     
    47144805Returns a new list of sublists, where each sublist contains @code{N} elements of @code{LIST}. If @code{LIST} has a length that is not a multiple of @code{N}, then the last sublist contains the remaining elements.
    47154806
    4716 <enscript highlight=scheme> (chop '(1 2 3 4 5 6) 2) ==> ((1 2) (3 4) (5 6)) (chop '(a b c d) 3)     ==> ((a b c) (d)) </enscript>
    4717 
     4807@example
     4808(chop '(1 2 3 4 5 6) 2) =@strong{=>} ((1 2) (3 4) (5 6))
     4809(chop '(a b c d) 3)     =@strong{=>} ((a b c) (d))
     4810@end example
    47184811@node Unit extras - Lists - compress, Unit extras - Lists - flatten, Unit extras - Lists - chop, Unit extras - Lists
    47194812@subsection compress
     
    47254818Returns a new list with elements taken from @code{LIST} with corresponding true values in the list @code{BLIST}.
    47264819
    4727 <enscript highlight=scheme> (define nums '(99 100 110 401 1234)) (compress (map odd? nums) nums)      ==> (99 401) </enscript>
    4728 
     4820@example
     4821(@strong{define} @strong{nums} '(99 100 110 401 1234))
     4822(compress (map odd? nums) nums)      =@strong{=>} (99 401)
     4823@end example
    47294824@node Unit extras - Lists - flatten, Unit extras - Lists - intersperse, Unit extras - Lists - compress, Unit extras - Lists
    47304825@subsection flatten
     
    47544849Concatenates the lists in @code{LISTOFLISTS} with @code{LIST} placed between each sublist. @code{LIST} defaults to the empty list.
    47554850
    4756 <enscript highlight=scheme> (join '((a b) (c d) (e)) '(x y)) ==> (a b x y c d x y e) (join '((p q) () (r (s) t)) '(-))  ==> (p q - - r (s) t) </enscript>
    4757 
     4851@example
     4852(join '((a b) (c d) (e)) '(x y)) =@strong{=>} (a b x y c d x y e)
     4853(join '((p q) () (r (s) t)) '(-))  =@strong{=>} (p q - - r (s) t)
     4854@end example
    47584855@code{join} could be implemented as follows:
    47594856
    4760 <enscript highlight=scheme> (define (join lstoflsts #!optional (lst '()))
    4761 
    4762 @verbatim
    4763  (apply append (intersperse lstoflists lst)) )
    4764 @end verbatim
    4765 </enscript>
    4766 
     4857@example
     4858(@strong{define} (@strong{join} lstoflsts #!optional (lst '()))
     4859  (apply append (intersperse lstoflists lst)) )
     4860@end example
    47674861@node Unit extras - Lists - shuffle, Unit extras - Lists - tail?, Unit extras - Lists - join, Unit extras - Lists
    47684862@subsection shuffle
     
    48574951@verbatim
    48584952[procedure] (fprintf PORT FORMATSTRING ARG ...)
    4859 [procedure] (printf FORMATSTRING ARG)
     4953[procedure] (printf FORMATSTRING ARG ...)
    48604954[procedure] (sprintf FORMATSTRING ARG ...)
    48614955@end verbatim
    4862 Simple formatted output to a given port (@code{fprintf}), the value of @code{(current-output-port)} (@code{printf}) or a string (@code{sprintf}).  The @code{FORMATSTRING} can contain any sequence of characters. The character `~' prefixes special formatting directives:
     4956Simple formatted output to a given port (@code{fprintf}), the value of @code{(current-output-port)} (@code{printf}), or a string (@code{sprintf}).  The @code{FORMATSTRING} can contain any sequence of characters.  There must be at least as many @code{ARG} arguments given as there are format directives that require an argument in @code{FORMATSTRING}.  Extra @code{ARG} arguments are ignored. The character `~' prefixes special formatting directives:
    48634957
    48644958<table> <tr><td> ~% write newline character </td></tr><tr><td> ~N the same as @code{~%} </td></tr><tr><td> ~S write the next argument </td></tr><tr><td> ~A display the next argument </td></tr><tr><td> ~\n skip all whitespace in the format-string until the next non-whitespace character </td></tr><tr><td> ~B write the next argument as a binary number </td></tr><tr><td> ~O write the next argument as an octal number </td></tr><tr><td> ~X write the next argument as a hexadecimal number </td></tr><tr><td> ~C write the next argument as a character </td></tr><tr><td> ~~ display `~' </td></tr><tr><td> ~! flush all pending output </td></tr><tr><td> ~? invoke formatted output routine recursively with the next two arguments as format-string and list of parameters </td></tr></table>
     
    48794973
    48804974@menu
     4975* Unit extras - Hash tables - make-hash-table::
     4976* Unit extras - Hash tables - hash-table-min-load::
     4977* Unit extras - Hash tables - hash-table-max-load::
     4978* Unit extras - Hash tables - hash-table-weak-keys::
     4979* Unit extras - Hash tables - hash-table-weak-values::
     4980* Unit extras - Hash tables - hash-table-has-initial::
     4981* Unit extras - Hash tables - hash-table-initial::
     4982* Unit extras - Hash tables - hash-table-update!::
    48814983* Unit extras - Hash tables - hash-table-remove!::
    4882 
    4883 @end menu
    4884 
    4885 
    4886 CHICKEN implements SRFI-69. For more information,  see @uref{http://srfi.schemers.org/srfi-69/srfi-69.html, SRFI-69}.
     4984* Unit extras - Hash tables - hash-table-merge::
     4985* Unit extras - Hash tables - hash-table-fold::
     4986* Unit extras - Hash tables - hash-table-map::
     4987* Unit extras - Hash tables - hash-table-for-each::
     4988
     4989@end menu
     4990
     4991
     4992CHICKEN implements SRFI-69. For more information, see @uref{http://srfi.schemers.org/srfi-69/srfi-69.html, SRFI-69}.
    48874993
    48884994A setter for @code{hash-table-ref} is defined, so
    48894995
    4890 <enscript highlight=scheme> (set! (hash-table-ref HT KEY) VAL) </enscript>
    4891 
     4996@example
     4997(@strong{set!} (hash-table-ref HT KEY) VAL)
     4998@end example
    48924999is equivalent to
    48935000
    4894 <enscript highlight=scheme> (hash-table-set! HT KEY VAL) </enscript>
    4895 
     5001@example
     5002(hash-table-set! HT KEY VAL)
     5003@end example
    48965004As an extension to SRFI-69, @code{hash-table-update!} and @code{hash-table-update!/default} return the new value (after applying the update procedure).
    48975005
    4898 @node Unit extras - Hash tables - hash-table-remove!,  ,  , Unit extras - Hash tables
     5006@node Unit extras - Hash tables - make-hash-table, Unit extras - Hash tables - hash-table-min-load,  , Unit extras - Hash tables
     5007@subsection make-hash-table
     5008
     5009
     5010@verbatim
     5011[procedure] (make-hash-table [TEST [HASH [SIZE]]] [#:TEST #:HASH #:SIZE #:INITIAL #:MIN-LOAD #:MAX-LOAD #:WEAK-KEYS #:WEAK-VALUES])
     5012@end verbatim
     5013Returns a new @code{HASH-TABLE}, parameterized as follows:
     5014
     5015@code{TEST} is a procedure of one argument, @code{(scheme-object -> boolean)}; an equality predicate.
     5016
     5017@code{HASH} is a procedure of two arguments, @code{(scheme-object (positive number) -> fixnum)}; a bounded hash function.
     5018
     5019@code{SIZE} is a @code{fixnum}; the initial size of the hash-table.
     5020
     5021@code{INITIAL} is a @code{scheme-object}; the default initial value for any @code{KEY}.
     5022
     5023@code{MIN-LOAD} is an @code{flonum} in @code{(0.0 1.0)}; the lower bound for resizing the table.
     5024
     5025@code{MAX-LOAD} is an @code{flonum} in @code{(0.0 1.0)}; the upper bound for resizing the table.
     5026
     5027@code{WEAK-KEYS} is an @code{boolean}; always @code{#f} (until further notice).
     5028
     5029@code{WEAK-VALUES} is an @code{boolean}; always @code{#f} (until further notice).
     5030
     5031@code{Note} - Keyword arguments take precedence over optional arguments.
     5032
     5033@node Unit extras - Hash tables - hash-table-min-load, Unit extras - Hash tables - hash-table-max-load, Unit extras - Hash tables - make-hash-table, Unit extras - Hash tables
     5034@subsection hash-table-min-load
     5035
     5036
     5037@verbatim
     5038[procedure] (hash-table-min-load HASH-TABLE)
     5039@end verbatim
     5040Returns the @code{MIN-LOAD} property of the @code{HASH-TABLE}.
     5041
     5042@node Unit extras - Hash tables - hash-table-max-load, Unit extras - Hash tables - hash-table-weak-keys, Unit extras - Hash tables - hash-table-min-load, Unit extras - Hash tables
     5043@subsection hash-table-max-load
     5044
     5045
     5046@verbatim
     5047[procedure] (hash-table-max-load HASH-TABLE)
     5048@end verbatim
     5049Returns the @code{MAX-LOAD} property of the @code{HASH-TABLE}.
     5050
     5051@node Unit extras - Hash tables - hash-table-weak-keys, Unit extras - Hash tables - hash-table-weak-values, Unit extras - Hash tables - hash-table-max-load, Unit extras - Hash tables
     5052@subsection hash-table-weak-keys
     5053
     5054
     5055@verbatim
     5056[procedure] (hash-table-weak-keys HASH-TABLE)
     5057@end verbatim
     5058Returns the @code{WEAK-KEYS} property of the @code{HASH-TABLE}.
     5059
     5060@node Unit extras - Hash tables - hash-table-weak-values, Unit extras - Hash tables - hash-table-has-initial, Unit extras - Hash tables - hash-table-weak-keys, Unit extras - Hash tables
     5061@subsection hash-table-weak-values
     5062
     5063
     5064@verbatim
     5065[procedure] (hash-table-weak-values HASH-TABLE)
     5066@end verbatim
     5067Returns the @code{WEAK-VALUES} property of the @code{HASH-TABLE}.
     5068
     5069@node Unit extras - Hash tables - hash-table-has-initial, Unit extras - Hash tables - hash-table-initial, Unit extras - Hash tables - hash-table-weak-values, Unit extras - Hash tables
     5070@subsection hash-table-has-initial
     5071
     5072
     5073@verbatim
     5074[procedure] (hash-table-has-initial HASH-TABLE)
     5075@end verbatim
     5076Does the @code{HASH-TABLE} have an @code{INITIAL} property.
     5077
     5078@node Unit extras - Hash tables - hash-table-initial, Unit extras - Hash tables - hash-table-update!, Unit extras - Hash tables - hash-table-has-initial, Unit extras - Hash tables
     5079@subsection hash-table-initial
     5080
     5081
     5082@verbatim
     5083[procedure] (hash-table-initial HASH-TABLE)
     5084@end verbatim
     5085Returns the @code{INITIAL} property of the @code{HASH-TABLE}.
     5086
     5087@node Unit extras - Hash tables - hash-table-update!, Unit extras - Hash tables - hash-table-remove!, Unit extras - Hash tables - hash-table-initial, Unit extras - Hash tables
     5088@subsection hash-table-update!
     5089
     5090
     5091@verbatim
     5092[procedure] (hash-table-update! HASH-TABLE KEY [FUNCTION [THUNK]])
     5093@end verbatim
     5094The SRFI-69 procedure is extended to allow a default procedure for @code{FUNCTION}, the default is @code{identity}.
     5095
     5096@node Unit extras - Hash tables - hash-table-remove!, Unit extras - Hash tables - hash-table-merge, Unit extras - Hash tables - hash-table-update!, Unit extras - Hash tables
    48995097@subsection hash-table-remove!
    49005098
    49015099
    49025100@verbatim
    4903 [procedure] (hash-table-remove! HASHTABLE PROC)
    4904 @end verbatim
    4905 Calls @code{PROC} for all entries in @code{HASHTABLE} with the key and value of each entry. If @code{PROC} returns true, then that entry is removed.
     5101[procedure] (hash-table-remove! HASH-TABLE PROC)
     5102@end verbatim
     5103Calls @code{PROC} for all entries in @code{HASH-TABLE} with the key and value of each entry. If @code{PROC} returns true, then that entry is removed.
     5104
     5105@node Unit extras - Hash tables - hash-table-merge, Unit extras - Hash tables - hash-table-fold, Unit extras - Hash tables - hash-table-remove!, Unit extras - Hash tables
     5106@subsection hash-table-merge
     5107
     5108
     5109@verbatim
     5110[procedure] (hash-table-merge HASH-TABLE-1 HASH-TABLE-2)
     5111@end verbatim
     5112Returns a new @code{hash-table}, the merged result of @code{HASH-TABLE-1} & @code{HASH-TABLE-2}.
     5113
     5114@node Unit extras - Hash tables - hash-table-fold, Unit extras - Hash tables - hash-table-map, Unit extras - Hash tables - hash-table-merge, Unit extras - Hash tables
     5115@subsection hash-table-fold
     5116
     5117
     5118@verbatim
     5119[procedure] (hash-table-fold HASH-TABLE PROC INIT)
     5120@end verbatim
     5121Applies the @code{PROC} to every @code{KEY}/@code{VALUE} pair in the @code{HASH-TABLE}.
     5122
     5123@code{PROC} is a procedure of 3 arguments, @code{(object object object -> object)}; the first argument is the @code{KEY}, the second argument is the @code{VALUE}, and the third argument is the current accumulated value. The return value becomes the new accumulated value.
     5124
     5125Returns the final accumulated value.
     5126
     5127@node Unit extras - Hash tables - hash-table-map, Unit extras - Hash tables - hash-table-for-each, Unit extras - Hash tables - hash-table-fold, Unit extras - Hash tables
     5128@subsection hash-table-map
     5129
     5130
     5131@verbatim
     5132[procedure] (hash-table-map HASH-TABLE PROC)
     5133@end verbatim
     5134Applies the @code{PROC} to every @code{KEY}/@code{VALUE} pair in the @code{HASH-TABLE}.
     5135
     5136@code{PROC} is a procedure of 2 arguments, @code{(object object -> object)}; the first argument is the @code{KEY}, and the second argument is the @code{VALUE}. The return value is collected in a list.
     5137
     5138Returns the list collection.
     5139
     5140@node Unit extras - Hash tables - hash-table-for-each,  , Unit extras - Hash tables - hash-table-map, Unit extras - Hash tables
     5141@subsection hash-table-for-each
     5142
     5143
     5144@verbatim
     5145[procedure] (hash-table-for-each HASH-TABLE PROC)
     5146@end verbatim
     5147Applies the @code{PROC} to every @code{KEY}/@code{VALUE} pair in the @code{HASH-TABLE}.
     5148
     5149@code{PROC} is a procedure of 2 arguments, @code{(object object -> void)}; the first argument is the @code{KEY}, and the second argument is the @code{VALUE}.
     5150
     5151No return value.
    49065152
    49075153@node Unit extras - Queues, Unit extras - Sorting, Unit extras - Hash tables, Unit extras
     
    51715417[procedure] (read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
    51725418@end verbatim
    5173 Returns a list containing all toplevel expressions read from the file or port @code{FILE-OR-PORT}. If no argument is given, input is read from the port that is the current value of @code{(current-input-port)}. After all expressions are read, and if the argument is a port, then the port will not be closed. The @code{READER} argument specifies the procedure used to read  expressions from the given file or port and defaults to @code{read}. The reader procedure will be called with a single argument (an input port). If @code{MAXCOUNT} is given then only up to @code{MAXCOUNT} expressions will be read in.
     5419Returns a list containing all toplevel expressions read from the file or port @code{FILE-OR-PORT}. If no argument is given, input is read from the port that is the current value of @code{(current-input-port)}. After all expressions are read, and if the argument is a port, then the port will not be closed. The @code{READER} argument specifies the procedure used to read expressions from the given file or port and defaults to @code{read}. The reader procedure will be called with a single argument (an input port). If @code{MAXCOUNT} is given then only up to @code{MAXCOUNT} expressions will be read in.
    51745420
    51755421@node Unit extras - Input/Output extensions - read-line, Unit extras - Input/Output extensions - write-line, Unit extras - Input/Output extensions - read-file, Unit extras - Input/Output extensions
     
    51855431[procedure] (write-line STRING [PORT])
    51865432@end verbatim
    5187 Line-input and -output. @code{PORT} defaults to the value of @code{(current-input-port)} and @code{(current-output-port)}, respectively. if the optional argument @code{LIMIT} is given and not @code{#f}, then @code{read-line} reads at most @code{LIMIT} characters per line.
     5433Line-input and -output. @code{PORT} defaults to the value of @code{(current-input-port)} and @code{(current-output-port)}, respectively. If the optional argument @code{LIMIT} is given and not @code{#f}, then @code{read-line} reads at most @code{LIMIT} characters per line. @code{read-line} returns a string without the terminating newline and @code{write-line} adds a terminating newline  before outputting.
    51885434
    51895435@node Unit extras - Input/Output extensions - read-lines, Unit extras - Input/Output extensions - read-string, Unit extras - Input/Output extensions - write-line, Unit extras - Input/Output extensions
     
    51945440[procedure] (read-lines [PORT [MAX]])
    51955441@end verbatim
    5196 Read @code{MAX} or fewer lines from @code{PORT}. @code{PORT} defaults to the value of @code{(current-input-port)}. @code{PORT} may optionally be a string naming a file.
     5442Read @code{MAX} or fewer lines from @code{PORT}. @code{PORT} defaults to the value of @code{(current-input-port)}. @code{PORT} may optionally be a string naming a file. Returns a list of strings, each string representing a line read, not including any line separation character(s).
    51975443
    51985444@node Unit extras - Input/Output extensions - read-string, Unit extras - Input/Output extensions - read-string!, Unit extras - Input/Output extensions - read-lines, Unit extras - Input/Output extensions
     
    52135459[procedure] (write-string STRING [NUM [PORT]]
    52145460@end verbatim
    5215 Read or write @code{NUM} characters from/to @code{PORT}, which defaults to the value of @code{(current-input-port)} or @code{(current-output-port)}, respectively.  If @code{NUM} is @code{#f} or not given, then all data up to the end-of-file is read, or, in the case of @code{write-string} the whole string is written. If no more input is available, @code{read-string} returns the empty string. @code{read-string!} reads destructively into the given @code{STRING} argument, but never more characters that would fit into @code{STRING}. If @code{START} is given, then the read characters are stored starting at that position. @code{read-string!} returns the actual number of characters read.
     5461Read or write @code{NUM} characters from/to @code{PORT}, which defaults to the value of @code{(current-input-port)} or @code{(current-output-port)}, respectively. If @code{NUM} is @code{#f} or not given, then all data up to the end-of-file is read, or, in the case of @code{write-string} the whole string is written. If no more input is available, @code{read-string} returns the empty string. @code{read-string!} reads destructively into the given @code{STRING} argument, but never more characters that would fit into @code{STRING}. If @code{START} is given, then the read characters are stored starting at that position. @code{read-string!} returns the actual number of characters read.
    52165462
    52175463@node Unit extras - Input/Output extensions - read-token, Unit extras - Input/Output extensions - with-error-output-to-port, Unit extras - Input/Output extensions - write-string, Unit extras - Input/Output extensions
     
    52795525Returns a string with the string-represenation of all arguments concatenated together. @code{conc} could be implemented as
    52805526
    5281 <enscript highlight=scheme> (define (conc . args)
    5282 
    5283 @verbatim
    5284  (apply string-append (map ->string args)) )
    5285 @end verbatim
    5286 </enscript>
    5287 
     5527@example
     5528(@strong{define} (@strong{conc} . args)
     5529  (apply string-append (map ->string args)) )
     5530@end example
    52885531@node Unit extras - Strings - ->string, Unit extras - Strings - string-chop, Unit extras - Strings - conc, Unit extras - Strings
    52895532@subsection ->string
     
    53045547Returns a list of substrings taken by @emph{chopping} @code{STRING} every @code{LENGTH} characters:
    53055548
    5306 <enscript highlight=scheme> (string-chop "one two three" 4)  ==>  ("one " "two " "thre" "e") </enscript>
    5307 
     5549@example
     5550(string-chop @strong{"one two three"} 4)  =@strong{=>}  (@strong{"one "} @strong{"two "} @strong{"thre"} @strong{"e"})
     5551@end example
    53085552@node Unit extras - Strings - string-chomp, Unit extras - Strings - string-compare3, Unit extras - Strings - string-chop, Unit extras - Strings
    53095553@subsection string-chomp
     
    53345578Returns a string that contains all strings in @code{LIST} concatenated together.  @code{STRING} is placed between each concatenated string and defaults to @code{" "}.
    53355579
    5336 <enscript highlight=scheme> (string-intersperse '("one" "two") "three") </enscript>
    5337 
     5580@example
     5581(string-intersperse '(@strong{"one"} @strong{"two"}) @strong{"three"})
     5582@end example
    53385583is equivalent to
    53395584
    5340 <enscript highlight=scheme> (apply string-append (intersperse '("one" "two") "three")) </enscript>
    5341 
     5585@example
     5586(apply string-append (intersperse '(@strong{"one"} @strong{"two"}) @strong{"three"}))
     5587@end example
    53425588@node Unit extras - Strings - string-split, Unit extras - Strings - string-translate, Unit extras - Strings - string-intersperse, Unit extras - Strings
    53435589@subsection string-split
     
    53475593[procedure] (string-split STRING [DELIMITER-STRING [KEEPEMPTY]])
    53485594@end verbatim
    5349 Split string into substrings separated by the given delimiters. If no delimiters are specified, a string comprising the tab, newline and space characters  is assumed. If the parameter @code{KEEPEMPTY} is given and not @code{#f}, then empty substrings are retained:
    5350 
    5351 <enscript highlight=scheme> (string-split "one  two  three") ==> ("one" "two" "three") (string-split "foo:bar::baz:" ":" #t) ==> ("foo" "bar" "" "baz" "") </enscript>
    5352 
     5595Split string into substrings separated by the given delimiters. If no delimiters are specified, a string comprising the tab, newline and space characters is assumed. If the parameter @code{KEEPEMPTY} is given and not @code{#f}, then empty substrings are retained:
     5596
     5597@example
     5598(string-split @strong{"one  two  three"}) =@strong{=>} (@strong{"one"} @strong{"two"} @strong{"three"})
     5599(string-split @strong{"foo:bar::baz:"} @strong{":"} #t) =@strong{=>} (@strong{"foo"} @strong{"bar"} @strong{""} @strong{"baz"} @strong{""})
     5600@end example
    53535601@node Unit extras - Strings - string-translate, Unit extras - Strings - string-translate*, Unit extras - Strings - string-split, Unit extras - Strings
    53545602@subsection string-translate
     
    53695617Substitutes elements of @code{STRING} according to @code{SMAP}. @code{SMAP} should be an association-list where each element of the list is a pair of the form @code{(MATCH \. REPLACEMENT)}. Every occurrence of the string @code{MATCH} in @code{STRING} will be replaced by the string @code{REPLACEMENT}:
    53705618
    5371 <enscript highlight=scheme> (string-translate*
    5372 
    5373 @verbatim
    5374  "<h1>this is a \"string\"</h1>"
    5375  '(("<" . "&lt;") (">" . "&gt;") ("\"" . "&quot;")) )
    5376 @end verbatim
    5377 =>  "&lt;h1&gt;this is a &quot;string&quot;&lt;/ht&gt;" </enscript>
    5378 
     5619@example
     5620(string-translate*
     5621  @strong{"<h1>this is a \"string\"</h1>"}
     5622  '((@strong{"<"} . @strong{"&lt;"}) (@strong{">"} . @strong{"&gt;"}) (@strong{"\""} . @strong{"&quot;"})) )
     5623@strong{=>}  @strong{"&lt;h1&gt;this is a &quot;string&quot;&lt;/ht&gt;"}
     5624@end example
    53795625@node Unit extras - Strings - substring=?, Unit extras - Strings - substring-index, Unit extras - Strings - string-translate*, Unit extras - Strings
    53805626@subsection substring=?
     
    54145660* Unit extras - Combinators - noop::
    54155661* Unit extras - Combinators - o::
     5662* Unit extras - Combinators - left-section::
     5663* Unit extras - Combinators - right-section::
    54165664
    54175665@end menu
     
    54365684Returns a procedure that always returns the values @code{X ...} regardless of the number and value of its arguments.
    54375685
    5438 <enscript highlight=scheme> (constantly X) <=> (lambda args X) </enscript>
    5439 
     5686@example
     5687(constantly X) <@strong{=>} (@strong{lambda} args X)
     5688@end example
    54405689@node Unit extras - Combinators - complement, Unit extras - Combinators - compose, Unit extras - Combinators - constantly, Unit extras - Combinators
    54415690@subsection complement
     
    54475696Returns a procedure that returns the boolean inverse of @code{PROC}.
    54485697
    5449 <enscript highlight=scheme> (complement PROC) <=> (lambda (x) (not (PROC x))) </enscript>
    5450 
     5698@example
     5699(complement PROC) <@strong{=>} (@strong{lambda} (x) (not (PROC x)))
     5700@end example
    54515701@node Unit extras - Combinators - compose, Unit extras - Combinators - conjoin, Unit extras - Combinators - complement, Unit extras - Combinators
    54525702@subsection compose
     
    54585708Returns a procedure that represents the composition of the argument-procedures @code{PROC1 PROC2 ...}.
    54595709
    5460 <enscript highlight=scheme> (compose F G) <=> (lambda args
    5461 
    5462 @verbatim
    5463                      (call-with-values
    5464                         (lambda () (apply G args))
    5465                         F))
    5466 @end verbatim
    5467 </enscript>
    5468 
     5710@example
     5711(compose F G) <@strong{=>} (@strong{lambda} args
     5712                      (call-with-values
     5713                         (@strong{lambda} () (apply G args))
     5714                         F))
     5715@end example
    54695716@code{(compose)} is equivalent to @code{values}.
    54705717
     
    54765723[procedure] (conjoin PRED ...)
    54775724@end verbatim
    5478 Returns a procedure that returns @code{#t} if its argument satisfies the predicates @code{PRED ...}. <enscript highlight=scheme> ((conjoin odd? positive?) 33)   ==>  #t ((conjoin odd? positive?) -33)  ==>  #f </enscript>
     5725Returns a procedure that returns @code{#t} if its argument satisfies the predicates @code{PRED ...}. @example
     5726((conjoin odd? positive?) 33)   =@strong{=>}  #t
     5727((conjoin odd? positive?) -33)  =@strong{=>}  #f
     5728@end example
     5729
    54795730
    54805731@node Unit extras - Combinators - disjoin, Unit extras - Combinators - each, Unit extras - Combinators - conjoin, Unit extras - Combinators
     
    54855736[procedure] (disjoin PRED ...)
    54865737@end verbatim
    5487 Returns a procedure that returns @code{#t} if its argument satisfies any predicate @code{PRED ...}. <enscript highlight=scheme> ((disjoin odd? positive?) 32)    ==>  #t ((disjoin odd? positive?) -32)   ==>  #f </enscript>
     5738Returns a procedure that returns @code{#t} if its argument satisfies any predicate @code{PRED ...}. @example
     5739((disjoin odd? positive?) 32)    =@strong{=>}  #t
     5740((disjoin odd? positive?) -32)   =@strong{=>}  #f
     5741@end example
     5742
    54885743
    54895744@node Unit extras - Combinators - each, Unit extras - Combinators - flip, Unit extras - Combinators - disjoin, Unit extras - Combinators
     
    54965751Returns a procedure that applies @code{PROC ...} to its arguments, and returns the result(s) of the last procedure application. For example
    54975752
    5498 <enscript highlight=scheme> (each pp eval) </enscript>
    5499 
     5753@example
     5754(each pp eval)
     5755@end example
    55005756is equivalent to
    55015757
    5502 <enscript highlight=scheme> (lambda args
    5503 
    5504 @verbatim
    5505  (apply pp args)
    5506  (apply eval args) )
    5507 @end verbatim
    5508 </enscript>
    5509 
     5758@example
     5759(@strong{lambda} args
     5760  (apply pp args)
     5761  (apply eval args) )
     5762@end example
    55105763@code{(each PROC)} is equivalent to @code{PROC} and @code{(each)} is equivalent to @code{noop}.
    55115764
     
    55175770[procedure] (flip PROC)
    55185771@end verbatim
    5519 Returns a two-argument procedure that calls @code{PROC} with its arguments swapped: <enscript highlight=scheme> (flip PROC) <=> (lambda (x y) (PROC y x)) </enscript>
     5772Returns a two-argument procedure that calls @code{PROC} with its arguments swapped: @example
     5773(flip PROC) <@strong{=>} (@strong{lambda} (x y) (PROC y x))
     5774@end example
     5775
    55205776
    55215777@node Unit extras - Combinators - identity, Unit extras - Combinators - project, Unit extras - Combinators - flip, Unit extras - Combinators
     
    55465802Returns a procedure of one argument that returns @code{#t} when applied to a list of elements that all satisfy the predicate procedure @code{PRED}, or @code{#f} otherwise.
    55475803
    5548 <enscript highlight=scheme> ((list-of even?) '(1 2 3))   ==> #f ((list-of number?) '(1 2 3)) ==> #t </enscript>
    5549 
     5804@example
     5805((list-of even?) '(1 2 3))   =@strong{=>} #f
     5806((list-of number?) '(1 2 3)) =@strong{=>} #t
     5807@end example
    55505808@node Unit extras - Combinators - noop, Unit extras - Combinators - o, Unit extras - Combinators - list-of, Unit extras - Combinators
    55515809@subsection noop
     
    55575815Ignores it's arguments, does nothing and returns an unspecified value.
    55585816
    5559 @node Unit extras - Combinators - o,  , Unit extras - Combinators - noop, Unit extras - Combinators
     5817@node Unit extras - Combinators - o, Unit extras - Combinators - left-section, Unit extras - Combinators - noop, Unit extras - Combinators
    55605818@subsection o
    55615819
     
    55655823@end verbatim
    55665824A single value version of @code{compose} (slightly faster). @code{(o)} is equivalent to @code{identity}.
     5825
     5826@node Unit extras - Combinators - left-section, Unit extras - Combinators - right-section, Unit extras - Combinators - o, Unit extras - Combinators
     5827@subsection left-section
     5828
     5829
     5830@verbatim
     5831[procedure] (left-section PROC ARG ...)
     5832@end verbatim
     5833A left section partially applies arguments starting from the left.
     5834
     5835Returns a variadic procedure in which some prefix of its arguments, @code{ARG ...}, are partially applied to @code{PROC}.
     5836
     5837@node Unit extras - Combinators - right-section,  , Unit extras - Combinators - left-section, Unit extras - Combinators
     5838@subsection right-section
     5839
     5840
     5841@verbatim
     5842[procedure] (right-section PROC ARG ...)
     5843@end verbatim
     5844A right section partially applies arguments starting from the right.
     5845
     5846Returns a variadic procedure in which some reversed suffix of its arguments, @code{ARG ...}, are partially applied to @code{PROC}.
    55675847
    55685848@node Unit extras - Binary searching,  , Unit extras - Combinators, Unit extras
     
    58866166[procedure] (read-u8vector LENGTH [PORT])
    58876167@end verbatim
    5888 Reads @code{LENGTH} bytes from the @code{PORT} and returns a fresh @code{u8vector} or less of end-of-file is encountered. @code{PORT} defaults to the value of @code{(current-input-port)}. If @code{LENGTH} is @code{#f}, the vector will be filled completely until end-of-file is reached.
     6168Reads @code{LENGTH} bytes from the @code{PORT} and returns a fresh @code{u8vector} or less if end-of-file is encountered. @code{PORT} defaults to the value of @code{(current-input-port)}. If @code{LENGTH} is @code{#f}, the vector will be filled completely until end-of-file is reached.
    58896169
    58906170@node Unit srfi-4 - read-u8vector!, Unit srfi-4 - write-u8vector, Unit srfi-4 - read-u8vector, Unit srfi-4
     
    59186198On systems that support dynamic loading, the @code{srfi-13} unit can be made available in the interpreter (@code{csi}) by entering
    59196199
    5920 <enscript highlight=scheme> (require-extension srfi-13) </enscript>
    5921 
     6200@example
     6201(require-extension srfi-13)
     6202@end example
    59226203Previous: @ref{Unit srfi-4, Unit srfi-4}
    59236204
     
    59326213On systems that support dynamic loading, the @code{srfi-14} unit can be made available in the interpreter (@code{csi}) by entering
    59336214
    5934 <enscript highlight=scheme> (require-extension srfi-14) </enscript>
    5935 
     6215@example
     6216(require-extension srfi-14)
     6217@end example
    59366218This library provides only the Latin-1 character set.
    59376219
     
    59586240* Unit regex - glob?::
    59596241* Unit regex - regexp::
     6242* Unit regex - regexp*::
    59606243* Unit regex - regexp?::
     6244* Unit regex - regexp-optimize::
    59616245* Unit regex - string-match::
    59626246* Unit regex - string-match-positions::
     
    59676251* Unit regex - string-substitute*::
    59686252* Unit regex - regexp-escape::
     6253* Unit regex - make-anchored-pattern::
    59696254
    59706255@end menu
     
    59756260To test that PCRE support has been built into Chicken properly, try:
    59766261
    5977 <enscript highlight=scheme> (require 'regex) (test-feature? 'pcre) => t </enscript>
    5978 
     6262@example
     6263(require 'regex)
     6264(test-feature? 'pcre) @strong{=>} t
     6265@end example
    59796266@node Unit regex - grep, Unit regex - glob->regexp,  , Unit regex
    59806267@section grep
     
    59866273Returns all items of @code{LIST} that match the regular expression @code{REGEX}.  This procedure could be defined as follows:
    59876274
    5988 <enscript highlight=scheme> (define (grep regex lst)
    5989 
    5990 @verbatim
    5991  (filter (lambda (x) (string-search regex x)) lst) )
    5992 @end verbatim
    5993 </enscript>
    5994 
     6275@example
     6276(@strong{define} (@strong{grep} regex lst)
     6277  (filter (@strong{lambda} (x) (string-search regex x)) lst) )
     6278@end example
    59956279@node Unit regex - glob->regexp, Unit regex - glob?, Unit regex - grep, Unit regex
    59966280@section glob->regexp
     
    60026286Converts the file-pattern @code{PATTERN} into a regular expression.
    60036287
    6004 <enscript highlight=scheme> (glob->regexp "foo.*") => "foo\..*" </enscript>
    6005 
     6288@example
     6289(glob->regexp @strong{"foo.*"})
     6290@strong{=>} @strong{"foo\..*"}
     6291@end example
    60066292@code{PATTERN} should follow "glob" syntax. Allowed wildcards are
    60076293
     
    60246310A string without any "glob" wildcards does not meet the criteria, even though it technically is a valid "glob" file-pattern.
    60256311
    6026 @node Unit regex - regexp, Unit regex - regexp?, Unit regex - glob?, Unit regex
     6312@node Unit regex - regexp, Unit regex - regexp*, Unit regex - glob?, Unit regex
    60276313@section regexp
    60286314
     
    60336319Returns a precompiled regular expression object for @code{string}. The optional arguments @code{IGNORECASE}, @code{IGNORESPACE} and @code{UTF8} specify whether the regular expression should be matched with case- or whitespace-differences ignored, or whether the string should be treated as containing UTF-8 encoded characters, respectively.
    60346320
    6035 @node Unit regex - regexp?, Unit regex - string-match, Unit regex - regexp, Unit regex
     6321@node Unit regex - regexp*, Unit regex - regexp?, Unit regex - regexp, Unit regex
     6322@section regexp*
     6323
     6324
     6325@verbatim
     6326[procedure] (regexp* STRING [OPTIONS [TABLES]])
     6327@end verbatim
     6328Returns a precompiled regular expression object for @code{string}. The optional argument @code{OPTIONS} must be a list of option symbols. The optional argument @code{TABLES} must be a character definitions table (not defined here).
     6329
     6330Option Symbols:
     6331
     6332@table @b
     6333@item caseless
     6334
     6335Character case insensitive match
     6336@item multiline
     6337
     6338Equivalent to Perl's /m option
     6339@item dotall
     6340
     6341Equivalent to Perl's /s option
     6342@item extended
     6343
     6344Ignore whitespace
     6345@item anchored
     6346
     6347Anchor pattern match
     6348@item dollar-endonly
     6349
     6350`$' metacharacter in the pattern matches only at the end of the subject string
     6351@item extra
     6352
     6353Currently of very little use
     6354@item notbol
     6355
     6356First character of the string is not the beginning of a line
     6357@item noteol
     6358
     6359End of the string is not the end of a line
     6360@item ungreedy
     6361
     6362Inverts the "greediness" of the quantifiers so that they are not greedy by default
     6363@item notempty
     6364
     6365The empty string is not considered to be a valid match
     6366@item utf8
     6367
     6368UTF-8 encoded characters
     6369@item no-auto-capture
     6370
     6371Disables the use of numbered capturing parentheses
     6372@item no-utf8-check
     6373
     6374Skip valid UTF-8 sequence check
     6375@item auto-callout
     6376
     6377Automatically inserts callout items (not defined here)
     6378@item partial
     6379
     6380Partial match ok
     6381@item firstline
     6382
     6383An unanchored pattern is required to match before or at the first newline
     6384@item dupnames
     6385
     6386Names used to identify capturing subpatterns need not be unique
     6387@item newline-cr
     6388
     6389Newline definition is `\r'
     6390@item newline-lf
     6391
     6392Newline definition is `\n'
     6393@item newline-crlf
     6394
     6395Newline definition is `\r\n'
     6396@item newline-anycrlf
     6397
     6398Newline definition is any of `\r', `\n', or `\r\n'
     6399@item newline-any
     6400
     6401ewline definition is any Unicode newline sequence
     6402@item bsr-anycrlf
     6403
     6404`\R' escape sequence matches only CR, LF, or CRLF
     6405@item bsr-unicode
     6406
     6407`\R' escape sequence matches only Unicode newline sequence
     6408@item dfa-shortest
     6409
     6410Currently unused
     6411@item dfa-restart
     6412
     6413Currently unused
     6414
     6415@end table
     6416@node Unit regex - regexp?, Unit regex - regexp-optimize, Unit regex - regexp*, Unit regex
    60366417@section regexp?
    60376418
     
    60426423Returns @code{#t} if @code{X} is a precompiled regular expression, or @code{#f} otherwise.
    60436424
    6044 @node Unit regex - string-match, Unit regex - string-match-positions, Unit regex - regexp?, Unit regex
     6425@node Unit regex - regexp-optimize, Unit regex - string-match, Unit regex - regexp?, Unit regex
     6426@section regexp-optimize
     6427
     6428
     6429@verbatim
     6430[procedure] (regexp-optimize RX)
     6431
     6432@end verbatim
     6433Perform available optimizations for the precompiled regular expression @code{RX}. Returns @code{#t} when optimization performed, and @code{#f} otherwise.
     6434
     6435@node Unit regex - string-match, Unit regex - string-match-positions, Unit regex - regexp-optimize, Unit regex
    60456436@section string-match
    60466437
     
    60796470Splits @code{STRING} into a list of fields according to @code{MODE}, where @code{MODE} can be the keyword @code{#:infix} (@code{REGEXP} matches field separator), the keyword @code{#:suffix} (@code{REGEXP} matches field terminator) or @code{#t} (@code{REGEXP} matches field), which is the default.
    60806471
    6081 <enscript highlight=scheme> (define s "this is a string 1, 2, 3,")
    6082 
    6083 (string-split-fields "[^ ]+" s)
    6084 
    6085 @verbatim
    6086  => ("this" "is" "a" "string" "1," "2," "3,")
    6087 @end verbatim
    6088 (string-split-fields " " s #:infix)
    6089 
    6090 @verbatim
    6091  => ("this" "is" "a" "string" "1," "2," "3,")
    6092 @end verbatim
    6093 (string-split-fields "," s #:suffix))
    6094 
    6095 @verbatim
    6096 
    6097  => ("this is a string 1" " 2" " 3")
    6098 @end verbatim
    6099 </enscript>
    6100 
     6472@example
     6473(@strong{define} @strong{s} @strong{"this is a string 1, 2, 3,"})
     6474
     6475(string-split-fields @strong{"[^ ]+"} s)
     6476
     6477  @strong{=>} (@strong{"this"} @strong{"is"} @strong{"a"} @strong{"string"} @strong{"1,"} @strong{"2,"} @strong{"3,"})
     6478
     6479(string-split-fields @strong{" "} s #:infix)
     6480
     6481  @strong{=>} (@strong{"this"} @strong{"is"} @strong{"a"} @strong{"string"} @strong{"1,"} @strong{"2,"} @strong{"3,"})
     6482
     6483(string-split-fields @strong{","} s #:suffix)
     6484 
     6485  @strong{=>} (@strong{"this is a string 1"} @strong{" 2"} @strong{" 3"})
     6486@end example
    61016487@node Unit regex - string-substitute, Unit regex - string-substitute*, Unit regex - string-split-fields, Unit regex
    61026488@section string-substitute
     
    61086494Searches substrings in @code{STRING} that match @code{REGEXP} and substitutes them with the string @code{SUBST}. The substitution can contain references to subexpressions in  @code{REGEXP} with the @code{\NUM} notation, where @code{NUM} refers to the NUMth parenthesized expression. The optional argument @code{MODE} defaults to 1 and specifies the number of the match to be substituted. Any non-numeric index specifies that all matches are to be substituted.
    61096495
    6110 <enscript highlight=scheme> (string-substitute "([0-9]+) (eggs|chicks)"
    6111 
    6112 @verbatim
    6113                   "\\2 (\\1)" "99 eggs or 99 chicks" 2)
    6114 @end verbatim
    6115 => "99 eggs or chicks (99)" </enscript>
    6116 
     6496@example
     6497(string-substitute @strong{"([0-9]+) (eggs|chicks)"}
     6498                   @strong{"\\2 (\\1)"} @strong{"99 eggs or 99 chicks"} 2)
     6499@strong{=>} @strong{"99 eggs or chicks (99)"}
     6500@end example
    61176501Note that a regular expression that matches an empty string will signal an error.
    61186502
     
    61266510Substitutes elements of @code{STRING} with @code{string-substitute} according to @code{SMAP}. @code{SMAP} should be an association-list where each element of the list is a pair of the form @code{(MATCH . REPLACEMENT)}. Every occurrence of the regular expression @code{MATCH} in @code{STRING} will be replaced by the string @code{REPLACEMENT}
    61276511
    6128 <enscript highlight=scheme> (string-substitute* "<h1>Hello, world!</h1>"
    6129 
    6130 @verbatim
    6131                    '(("<[/A-Za-z0-9]+>" . ""))))
    6132 @end verbatim
    6133 =>  "Hello, world!" </enscript>
    6134 
    6135 @node Unit regex - regexp-escape,  , Unit regex - string-substitute*, Unit regex
     6512@example
     6513(string-substitute* @strong{"<h1>Hello, world!</h1>"}
     6514                    '((@strong{"<[/A-Za-z0-9]+>"} . @strong{""})))
     6515
     6516@strong{=>}  @strong{"Hello, world!"}
     6517@end example
     6518@node Unit regex - regexp-escape, Unit regex - make-anchored-pattern, Unit regex - string-substitute*, Unit regex
    61366519@section regexp-escape
    61376520
     
    61426525Escapes all special characters in @code{STRING} with @code{\}, so that the string can be embedded into a regular expression.
    61436526
    6144 <enscript highlight=scheme> (regexp-escape "^[0-9]+:.*$") =>  "\\^\\[0-9\\]\\+:.\n.\\*\\$" </enscript>
     6527@example
     6528(regexp-escape @strong{"^[0-9]+:.*$"})
     6529@strong{=>}  @strong{"\\^\\[0-9\\]\\+:.\n.\\*\\$"}
     6530@end example
     6531@node Unit regex - make-anchored-pattern,  , Unit regex - regexp-escape, Unit regex
     6532@section make-anchored-pattern
     6533
     6534
     6535@verbatim
     6536[procedure] (make-anchored-pattern REGEXP [WITHOUT-BOL [WITHOUT-EOL]])
     6537@end verbatim
     6538Makes an anchored pattern from @code{REGEXP} (a string or a precompiled regular expression) and returns the updated pattern. When @code{WITHOUT-BOL} is @code{#t} the beginning-of-line anchor is not added. When @code{WITHOUT-EOL} is @code{#t} the end-of-line anchor is not added.
     6539
     6540The @code{WITHOUT-BOL} and @{WITHOUT-EOL@}@} arguments are ignored for a precompiled regular expression.
    61456541
    61466542Previous: @ref{Unit match, Unit match}
     
    61576553* Unit srfi-18 - thread-suspend!::
    61586554* Unit srfi-18 - thread-resume!::
     6555* Unit srfi-18 - thread-wait-for-i/o!::
    61596556* Unit srfi-18 - time->milliseconds::
    61606557
     
    62326629Suspends the execution of @code{THREAD} until resumed.
    62336630
    6234 @node Unit srfi-18 - thread-resume!, Unit srfi-18 - time->milliseconds, Unit srfi-18 - thread-suspend!, Unit srfi-18
     6631@node Unit srfi-18 - thread-resume!, Unit srfi-18 - thread-wait-for-i/o!, Unit srfi-18 - thread-suspend!, Unit srfi-18
    62356632@section thread-resume!
    62366633
     
    62416638Readies the suspended thread @code{THREAD}.
    62426639
    6243 @node Unit srfi-18 - time->milliseconds,  , Unit srfi-18 - thread-resume!, Unit srfi-18
     6640@node Unit srfi-18 - thread-wait-for-i/o!, Unit srfi-18 - time->milliseconds, Unit srfi-18 - thread-resume!, Unit srfi-18
     6641@section thread-wait-for-i/o!
     6642
     6643
     6644@verbatim
     6645[procedure] (thread-wait-for-i/o! FD [MODE])
     6646@end verbatim
     6647Suspends the current thread until input (@code{MODE} is @code{#:input}), output (@code{MODE} is @code{#:output}) or both (@code{MODE} is @code{#:all}) is available. @code{FD} should be a file-descriptor (not a port!) open for input or output, respectively.
     6648
     6649@node Unit srfi-18 - time->milliseconds,  , Unit srfi-18 - thread-wait-for-i/o!, Unit srfi-18
    62446650@section time->milliseconds
    62456651
     
    62586664
    62596665@menu
     6666* Unit posix - Constants::
    62606667* Unit posix - Directories::
    62616668* Unit posix - Pipes::
     
    62666673* Unit posix - Processes::
    62676674* Unit posix - Hard and symbolic links::
    6268 * Unit posix - Permissions::
     6675* Unit posix - Retrieving user & group information::
     6676* Unit posix - Changing user & group information::
    62696677* Unit posix - Record locking::
    62706678* Unit posix - Signal handling::
     
    62906698All errors related to failing file-operations will signal a condition of kind @code{(exn i/o file)}.
    62916699
    6292 @node Unit posix - Directories, Unit posix - Pipes,  , Unit posix
     6700@node Unit posix - Constants, Unit posix - Directories,  , Unit posix
     6701@section Constants
     6702
     6703@menu
     6704* Unit posix - Constants - File-control Commands::
     6705* Unit posix - Constants - Standard I/O file-descriptors::
     6706* Unit posix - Constants - Open flags::
     6707* Unit posix - Constants - Permission bits::
     6708
     6709@end menu
     6710
     6711
     6712@node Unit posix - Constants - File-control Commands, Unit posix - Constants - Standard I/O file-descriptors,  , Unit posix - Constants
     6713@subsection File-control Commands
     6714
     6715@menu
     6716* Unit posix - Constants - File-control Commands - fcntl/dupfd::
     6717* Unit posix - Constants - File-control Commands - fcntl/getfd::
     6718* Unit posix - Constants - File-control Commands - fcntl/setfd::
     6719* Unit posix - Constants - File-control Commands - fcntl/getfl::
     6720* Unit posix - Constants - File-control Commands - fcntl/setfl::
     6721
     6722@end menu
     6723
     6724
     6725@node Unit posix - Constants - File-control Commands - fcntl/dupfd, Unit posix - Constants - File-control Commands - fcntl/getfd,  , Unit posix - Constants - File-control Commands
     6726@subsubsection fcntl/dupfd
     6727
     6728
     6729@node Unit posix - Constants - File-control Commands - fcntl/getfd, Unit posix - Constants - File-control Commands - fcntl/setfd, Unit posix - Constants - File-control Commands - fcntl/dupfd, Unit posix - Constants - File-control Commands
     6730@subsubsection fcntl/getfd
     6731
     6732
     6733@node Unit posix - Constants - File-control Commands - fcntl/setfd, Unit posix - Constants - File-control Commands - fcntl/getfl, Unit posix - Constants - File-control Commands - fcntl/getfd, Unit posix - Constants - File-control Commands
     6734@subsubsection fcntl/setfd
     6735
     6736
     6737@node Unit posix - Constants - File-control Commands - fcntl/getfl, Unit posix - Constants - File-control Commands - fcntl/setfl, Unit posix - Constants - File-control Commands - fcntl/setfd, Unit posix - Constants - File-control Commands
     6738@subsubsection fcntl/getfl
     6739
     6740
     6741@node Unit posix - Constants - File-control Commands - fcntl/setfl,  , Unit posix - Constants - File-control Commands - fcntl/getfl, Unit posix - Constants - File-control Commands
     6742@subsubsection fcntl/setfl
     6743
     6744
     6745@node Unit posix - Constants - Standard I/O file-descriptors, Unit posix - Constants - Open flags, Unit posix - Constants - File-control Commands, Unit posix - Constants
     6746@subsection Standard I/O file-descriptors
     6747
     6748@menu
     6749* Unit posix - Constants - Standard I/O file-descriptors - fileno/stdin::
     6750* Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout::
     6751* Unit posix - Constants - Standard I/O file-descriptors - fileno/stderr::
     6752
     6753@end menu
     6754
     6755
     6756@node Unit posix - Constants - Standard I/O file-descriptors - fileno/stdin, Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout,  , Unit posix - Constants - Standard I/O file-descriptors
     6757@subsubsection fileno/stdin
     6758
     6759
     6760@node Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout, Unit posix - Constants - Standard I/O file-descriptors - fileno/stderr, Unit posix - Constants - Standard I/O file-descriptors - fileno/stdin, Unit posix - Constants - Standard I/O file-descriptors
     6761@subsubsection fileno/stdout
     6762
     6763
     6764@node Unit posix - Constants - Standard I/O file-descriptors - fileno/stderr,  , Unit posix - Constants - Standard I/O file-descriptors - fileno/stdout, Unit posix - Constants - Standard I/O file-descriptors
     6765@subsubsection fileno/stderr
     6766
     6767
     6768@node Unit posix - Constants - Open flags, Unit posix - Constants - Permission bits, Unit posix - Constants - Standard I/O file-descriptors, Unit posix - Constants
     6769@subsection Open flags
     6770
     6771@menu
     6772* Unit posix - Constants - Open flags - open/rdonly::
     6773* Unit posix - Constants - Open flags - open/wronly::
     6774* Unit posix - Constants - Open flags - open/rdwr::
     6775* Unit posix - Constants - Open flags - open/read::
     6776* Unit posix - Constants - Open flags - open/write::
     6777* Unit posix - Constants - Open flags - open/creat::
     6778* Unit posix - Constants - Open flags - open/append::
     6779* Unit posix - Constants - Open flags - open/excl::
     6780* Unit posix - Constants - Open flags - open/noctty::
     6781* Unit posix - Constants - Open flags - open/nonblock::
     6782* Unit posix - Constants - Open flags - open/trunc::
     6783* Unit posix - Constants - Open flags - open/sync::
     6784* Unit posix - Constants - Open flags - open/fsync::
     6785* Unit posix - Constants - Open flags - open/binary::
     6786* Unit posix - Constants - Open flags - open/text::
     6787
     6788@end menu
     6789
     6790
     6791@node Unit posix - Constants - Open flags - open/rdonly, Unit posix - Constants - Open flags - open/wronly,  , Unit posix - Constants - Open flags
     6792@subsubsection open/rdonly
     6793
     6794
     6795@node Unit posix - Constants - Open flags - open/wronly, Unit posix - Constants - Open flags - open/rdwr, Unit posix - Constants - Open flags - open/rdonly, Unit posix - Constants - Open flags
     6796@subsubsection open/wronly
     6797
     6798
     6799@node Unit posix - Constants - Open flags - open/rdwr, Unit posix - Constants - Open flags - open/read, Unit posix - Constants - Open flags - open/wronly, Unit posix - Constants - Open flags
     6800@subsubsection open/rdwr
     6801
     6802
     6803@node Unit posix - Constants - Open flags - open/read, Unit posix - Constants - Open flags - open/write, Unit posix - Constants - Open flags - open/rdwr, Unit posix - Constants - Open flags
     6804@subsubsection open/read
     6805
     6806
     6807@node Unit posix - Constants - Open flags - open/write, Unit posix - Constants - Open flags - open/creat, Unit posix - Constants - Open flags - open/read, Unit posix - Constants - Open flags
     6808@subsubsection open/write
     6809
     6810
     6811@node Unit posix - Constants - Open flags - open/creat, Unit posix - Constants - Open flags - open/append, Unit posix - Constants - Open flags - open/write, Unit posix - Constants - Open flags
     6812@subsubsection open/creat
     6813
     6814
     6815@node Unit posix - Constants - Open flags - open/append, Unit posix - Constants - Open flags - open/excl, Unit posix - Constants - Open flags - open/creat, Unit posix - Constants - Open flags
     6816@subsubsection open/append
     6817
     6818
     6819@node Unit posix - Constants - Open flags - open/excl, Unit posix - Constants - Open flags - open/noctty, Unit posix - Constants - Open flags - open/append, Unit posix - Constants - Open flags
     6820@subsubsection open/excl
     6821
     6822
     6823@node Unit posix - Constants - Open flags - open/noctty, Unit posix - Constants - Open flags - open/nonblock, Unit posix - Constants - Open flags - open/excl, Unit posix - Constants - Open flags
     6824@subsubsection open/noctty
     6825
     6826
     6827@node Unit posix - Constants - Open flags - open/nonblock, Unit posix - Constants - Open flags - open/trunc, Unit posix - Constants - Open flags - open/noctty, Unit posix - Constants - Open flags
     6828@subsubsection open/nonblock
     6829
     6830
     6831@node Unit posix - Constants - Open flags - open/trunc, Unit posix - Constants - Open flags - open/sync, Unit posix - Constants - Open flags - open/nonblock, Unit posix - Constants - Open flags
     6832@subsubsection open/trunc
     6833
     6834
     6835@node Unit posix - Constants - Open flags - open/sync, Unit posix - Constants - Open flags - open/fsync, Unit posix - Constants - Open flags - open/trunc, Unit posix - Constants - Open flags
     6836@subsubsection open/sync
     6837
     6838
     6839@node Unit posix - Constants - Open flags - open/fsync, Unit posix - Constants - Open flags - open/binary, Unit posix - Constants - Open flags - open/sync, Unit posix - Constants - Open flags
     6840@subsubsection open/fsync
     6841
     6842
     6843@node Unit posix - Constants - Open flags - open/binary, Unit posix - Constants - Open flags - open/text, Unit posix - Constants - Open flags - open/fsync, Unit posix - Constants - Open flags
     6844@subsubsection open/binary
     6845
     6846
     6847@node Unit posix - Constants - Open flags - open/text,  , Unit posix - Constants - Open flags - open/binary, Unit posix - Constants - Open flags
     6848@subsubsection open/text
     6849
     6850
     6851@node Unit posix - Constants - Permission bits,  , Unit posix - Constants - Open flags, Unit posix - Constants
     6852@subsection Permission bits
     6853
     6854@menu
     6855* Unit posix - Constants - Permission bits - perm/irusr::
     6856* Unit posix - Constants - Permission bits - perm/iwusr::
     6857* Unit posix - Constants - Permission bits - perm/ixusr::
     6858* Unit posix - Constants - Permission bits - perm/irgrp::
     6859* Unit posix - Constants - Permission bits - perm/iwgrp::
     6860* Unit posix - Constants - Permission bits - perm/ixgrp::
     6861* Unit posix - Constants - Permission bits - perm/iroth::
     6862* Unit posix - Constants - Permission bits - perm/iwoth::
     6863* Unit posix - Constants - Permission bits - perm/ixoth::
     6864* Unit posix - Constants - Permission bits - perm/irwxu::
     6865* Unit posix - Constants - Permission bits - perm/irwxg::
     6866* Unit posix - Constants - Permission bits - perm/irwxo::
     6867* Unit posix - Constants - Permission bits - perm/isvtx::
     6868* Unit posix - Constants - Permission bits - perm/isuid::
     6869* Unit posix - Constants - Permission bits - perm/isgid::
     6870
     6871@end menu
     6872
     6873
     6874@node Unit posix - Constants - Permission bits - perm/irusr, Unit posix - Constants - Permission bits - perm/iwusr,  , Unit posix - Constants - Permission bits
     6875@subsubsection perm/irusr
     6876
     6877
     6878@node Unit posix - Constants - Permission bits - perm/iwusr, Unit posix - Constants - Permission bits - perm/ixusr, Unit posix - Constants - Permission bits - perm/irusr, Unit posix - Constants - Permission bits
     6879@subsubsection perm/iwusr
     6880
     6881
     6882@node Unit posix - Constants - Permission bits - perm/ixusr, Unit posix - Constants - Permission bits - perm/irgrp, Unit posix - Constants - Permission bits - perm/iwusr, Unit posix - Constants - Permission bits
     6883@subsubsection perm/ixusr
     6884
     6885
     6886@node Unit posix - Constants - Permission bits - perm/irgrp, Unit posix - Constants - Permission bits - perm/iwgrp, Unit posix - Constants - Permission bits - perm/ixusr, Unit posix - Constants - Permission bits
     6887@subsubsection perm/irgrp
     6888
     6889
     6890@node Unit posix - Constants - Permission bits - perm/iwgrp, Unit posix - Constants - Permission bits - perm/ixgrp, Unit posix - Constants - Permission bits - perm/irgrp, Unit posix - Constants - Permission bits
     6891@subsubsection perm/iwgrp
     6892
     6893
     6894@node Unit posix - Constants - Permission bits - perm/ixgrp, Unit posix - Constants - Permission bits - perm/iroth, Unit posix - Constants - Permission bits - perm/iwgrp, Unit posix - Constants - Permission bits
     6895@subsubsection perm/ixgrp
     6896
     6897
     6898@node Unit posix - Constants - Permission bits - perm/iroth, Unit posix - Constants - Permission bits - perm/iwoth, Unit posix - Constants - Permission bits - perm/ixgrp, Unit posix - Constants - Permission bits
     6899@subsubsection perm/iroth
     6900
     6901
     6902@node Unit posix - Constants - Permission bits - perm/iwoth, Unit posix - Constants - Permission bits - perm/ixoth, Unit posix - Constants - Permission bits - perm/iroth, Unit posix - Constants - Permission bits
     6903@subsubsection perm/iwoth
     6904
     6905
     6906@node Unit posix - Constants - Permission bits - perm/ixoth, Unit posix - Constants - Permission bits - perm/irwxu, Unit posix - Constants - Permission bits - perm/iwoth, Unit posix - Constants - Permission bits
     6907@subsubsection perm/ixoth
     6908
     6909
     6910@node Unit posix - Constants - Permission bits - perm/irwxu, Unit posix - Constants - Permission bits - perm/irwxg, Unit posix - Constants - Permission bits - perm/ixoth, Unit posix - Constants - Permission bits
     6911@subsubsection perm/irwxu
     6912
     6913
     6914@node Unit posix - Constants - Permission bits - perm/irwxg, Unit posix - Constants - Permission bits - perm/irwxo, Unit posix - Constants - Permission bits - perm/irwxu, Unit posix - Constants - Permission bits
     6915@subsubsection perm/irwxg
     6916
     6917
     6918@node Unit posix - Constants - Permission bits - perm/irwxo, Unit posix - Constants - Permission bits - perm/isvtx, Unit posix - Constants - Permission bits - perm/irwxg, Unit posix - Constants - Permission bits
     6919@subsubsection perm/irwxo
     6920
     6921
     6922@node Unit posix - Constants - Permission bits - perm/isvtx, Unit posix - Constants - Permission bits - perm/isuid, Unit posix - Constants - Permission bits - perm/irwxo, Unit posix - Constants - Permission bits
     6923@subsubsection perm/isvtx
     6924
     6925
     6926@node Unit posix - Constants - Permission bits - perm/isuid, Unit posix - Constants - Permission bits - perm/isgid, Unit posix - Constants - Permission bits - perm/isvtx, Unit posix - Constants - Permission bits
     6927@subsubsection perm/isuid
     6928
     6929
     6930@node Unit posix - Constants - Permission bits - perm/isgid,  , Unit posix - Constants - Permission bits - perm/isuid, Unit posix - Constants - Permission bits
     6931@subsubsection perm/isgid
     6932
     6933
     6934@node Unit posix - Directories, Unit posix - Pipes, Unit posix - Constants, Unit posix
    62936935@section Directories
    62946936
     
    64717113Temporarily set the value of @code{current-input-port/current-output-port} to a port for a pipe connected to the subprocess named in @code{CMDLINE} and call the procedure @code{THUNK} with no arguments. After @code{THUNK} returns normally the pipe is closed and the standard input-/output port is restored to its previous value and any result values are returned.
    64727114
    6473 <enscript highlight=scheme> (with-output-to-pipe
    6474 
    6475 @verbatim
    6476  "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
    6477  (lambda ()
    6478    (print #<<EOF
    6479 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<@uref{mailto:xxxxxxxx@@xx.xxxxxx.xx.xx, xxxxxxxx@@xx.xxxxxx.xx.xx}>
    6480 /C/neg/d/mul/R/rlineto/E/exp/H@{@{cvx def@}repeat@}def/T/dup/g/gt/r/roll/J/ifelse 8
    6481 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
    6482 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
    6483 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
    6484 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
    6485 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
    6486 V1c&j2AYdjmMdjjd!o&1r!M)@{( )T 0 4 3 r put T(/)g@{T(9)g@{cvn@}@{cvi@}J@}@{($)g[]J@}J
    6487 cvx@}forall/moveto/p/floor/w/div/S/add 29 H[@{[@{]setgray fill@}for Y@}for showpage
    6488 EOF
    6489 ) ) )
    6490 @end verbatim
    6491 </enscript>
    6492 
     7115@example
     7116(with-output-to-pipe
     7117  @strong{"gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"}
     7118  (@strong{lambda} ()
     7119    (print #<<EOF
     7120 %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@@xx.xxxxxx.xx.xx>
     7121 /C/neg/d/mul/R/rlineto/E/exp/H@{@{cvx def@}repeat@}def/T/dup/g/gt/r/roll/J/ifelse 8
     7122 H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
     7123 X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
     7124 F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
     7125 Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
     7126 ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
     7127 V1c&j2AYdjmMdjjd!o&1r!M)@{( )T 0 4 3 r put T(/)g@{T(9)g@{cvn@}@{cvi@}J@}@{($)g[]J@}J
     7128 cvx@}forall/moveto/p/floor/w/div/S/add 29 H[@{[@{]setgray fill@}for Y@}for showpage
     7129 EOF
     7130 ) ) )
     7131@end example
    64937132@node Unit posix - Fifos, Unit posix - File descriptors and low-level I/O, Unit posix - Pipes, Unit posix
    64947133@section Fifos
     
    65107149Creates a FIFO with the name @code{FILENAME} and the permission bits @code{MODE}, which defaults to
    65117150
    6512 <enscript highlight=scheme>
    6513 
    6514 @verbatim
    6515 [procedure] (+ perm/irwxu perm/irwxg perm/irwxo)
    6516 @end verbatim
    6517 </enscript>
    6518 
     7151@example
     7152 [procedure] (+ perm/irwxu perm/irwxg perm/irwxo)
     7153@end example
    65197154@node Unit posix - Fifos - fifo?,  , Unit posix - Fifos - create-fifo, Unit posix - Fifos
    65207155@subsection fifo?
     
    65387173* Unit posix - File descriptors and low-level I/O - file-write::
    65397174* Unit posix - File descriptors and low-level I/O - file-control::
    6540 * Unit posix - File descriptors and low-level I/O - fcntl/dupfd::
    6541 * Unit posix - File descriptors and low-level I/O - fcntl/getfd::
    6542 * Unit posix - File descriptors and low-level I/O - fcntl/setfd::
    6543 * Unit posix - File descriptors and low-level I/O - fcntl/getfl::
    6544 * Unit posix - File descriptors and low-level I/O - fcntl/setfl::
    6545 * Unit posix - File descriptors and low-level I/O - fileno/stdin::
    6546 * Unit posix - File descriptors and low-level I/O - fileno/stdout::
    6547 * Unit posix - File descriptors and low-level I/O - fileno/stderr::
    6548 * Unit posix - File descriptors and low-level I/O - open/rdonly::
    6549 * Unit posix - File descriptors and low-level I/O - open/wronly::
    6550 * Unit posix - File descriptors and low-level I/O - open/rdwr::
    6551 * Unit posix - File descriptors and low-level I/O - open/read::
    6552 * Unit posix - File descriptors and low-level I/O - open/write::
    6553 * Unit posix - File descriptors and low-level I/O - open/creat::
    6554 * Unit posix - File descriptors and low-level I/O - open/append::
    6555 * Unit posix - File descriptors and low-level I/O - open/excl::
    6556 * Unit posix - File descriptors and low-level I/O - open/noctty::
    6557 * Unit posix - File descriptors and low-level I/O - open/nonblock::
    6558 * Unit posix - File descriptors and low-level I/O - open/trunc::
    6559 * Unit posix - File descriptors and low-level I/O - open/sync::
    6560 * Unit posix - File descriptors and low-level I/O - open/fsync::
    6561 * Unit posix - File descriptors and low-level I/O - open/binary::
    6562 * Unit posix - File descriptors and low-level I/O - open/text::
    65637175* Unit posix - File descriptors and low-level I/O - open-input-file*::
    65647176* Unit posix - File descriptors and low-level I/O - open-output-file*::
     
    65937205[procedure] (file-open FILENAME FLAGS [MODE])
    65947206@end verbatim
    6595 Opens the file specified with the string @code{FILENAME} and open-flags @code{FLAGS} using the C function @code{open()}. On success a file-descriptor for the opened file is returned.  @code{FLAGS} should be a bitmask containing one or more of the @code{open/...} values @b{or}ed together using @code{bitwise-ior} (or simply added together).  The optional @code{MODE} should be a bitmask composed of one or more permission values like @code{perm/irusr} and is only relevant when a new file is created. The default mode is  @code{perm/irwxu | perm/irgrp | perm/iroth}.
     7207Opens the file specified with the string @code{FILENAME} and open-flags @code{FLAGS} using the C function @code{open()}. On success a file-descriptor for the opened file is returned.  @code{FLAGS} should be a bitmask containing one or more of the @code{open/...} values @b{or}ed together using @code{bitwise-ior} (or simply added together).  The optional @code{MODE} should be a bitmask composed of one or more permission values like @code{perm/irusr} and is only relevant when a new file is created. The default mode is @code{perm/irwxu | perm/irgrp | perm/iroth}.
    65967208
    65977209@node Unit posix - File descriptors and low-level I/O - file-mkstemp, Unit posix - File descriptors and low-level I/O - file-read, Unit posix - File descriptors and low-level I/O - file-open, Unit posix - File descriptors and low-level I/O
     
    66067218Example usage:
    66077219
    6608 <enscript highlight=scheme>
    6609 
    6610 @verbatim
    6611 (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
    6612  (let ((temp-port (open-output-file* fd)))
    6613    (format temp-port "This file is ~A.~%" temp-path)
    6614    (close-output-port temp-port)))
    6615 @end verbatim
    6616 </enscript>
    6617 
     7220@example
     7221 (let-values (((fd temp-path) (file-mkstemp @strong{"/tmp/mytemporary.XXXXXX"})))
     7222  (@strong{let} ((temp-port (open-output-file* fd)))
     7223    (format temp-port @strong{"This file is ~A.~%"} temp-path)
     7224    (close-output-port temp-port)))
     7225@end example
    66187226@node Unit posix - File descriptors and low-level I/O - file-read, Unit posix - File descriptors and low-level I/O - file-select, Unit posix - File descriptors and low-level I/O - file-mkstemp, Unit posix - File descriptors and low-level I/O
    66197227@subsection file-read
     
    66437251Writes the contents of the string or bytevector @code{BUFFER} into the file with the file-descriptor @code{FILENO}. If the optional argument @code{SIZE} is given, then only the specified number of bytes are written.
    66447252
    6645 @node Unit posix - File descriptors and low-level I/O - file-control, Unit posix - File descriptors and low-level I/O - fcntl/dupfd, Unit posix - File descriptors and low-level I/O - file-write, Unit posix - File descriptors and low-level I/O
     7253@node Unit posix - File descriptors and low-level I/O - file-control, Unit posix - File descriptors and low-level I/O - open-input-file*, Unit posix - File descriptors and low-level I/O - file-write, Unit posix - File descriptors and low-level I/O
    66467254@subsection file-control
    66477255
    66487256
    66497257@verbatim
    6650 [procedure] (file-control FILENO COMMAND  [ARGUMENT])
     7258[procedure] (file-control FILENO COMMAND [ARGUMENT])
    66517259@end verbatim
    66527260Performs the fcntl operation @code{COMMAND} with the given @code{FILENO} and optional @code{ARGUMENT}. The return value is meaningful depending on the @code{COMMAND}.
    66537261
    6654 @node Unit posix - File descriptors and low-level I/O - fcntl/dupfd, Unit posix - File descriptors and low-level I/O - fcntl/getfd, Unit posix - File descriptors and low-level I/O - file-control, Unit posix - File descriptors and low-level I/O
    6655 @subsection fcntl/dupfd
    6656 
    6657 
    6658 @node Unit posix - File descriptors and low-level I/O - fcntl/getfd, Unit posix - File descriptors and low-level I/O - fcntl/setfd, Unit posix - File descriptors and low-level I/O - fcntl/dupfd, Unit posix - File descriptors and low-level I/O
    6659 @subsection fcntl/getfd
    6660 
    6661 
    6662 @node Unit posix - File descriptors and low-level I/O - fcntl/setfd, Unit posix - File descriptors and low-level I/O - fcntl/getfl, Unit posix - File descriptors and low-level I/O - fcntl/getfd, Unit posix - File descriptors and low-level I/O
    6663 @subsection fcntl/setfd
    6664 
    6665 
    6666 @node Unit posix - File descriptors and low-level I/O - fcntl/getfl, Unit posix - File descriptors and low-level I/O - fcntl/setfl, Unit posix - File descriptors and low-level I/O - fcntl/setfd, Unit posix - File descriptors and low-level I/O
    6667 @subsection fcntl/getfl
    6668 
    6669 
    6670 @node Unit posix - File descriptors and low-level I/O - fcntl/setfl, Unit posix - File descriptors and low-level I/O - fileno/stdin, Unit posix - File descriptors and low-level I/O - fcntl/getfl, Unit posix - File descriptors and low-level I/O
    6671 @subsection fcntl/setfl
    6672 
    6673 
    6674 These variables contain commands for @code{file-control}.
    6675 
    6676 @node Unit posix - File descriptors and low-level I/O - fileno/stdin, Unit posix - File descriptors and low-level I/O - fileno/stdout, Unit posix - File descriptors and low-level I/O - fcntl/setfl, Unit posix - File descriptors and low-level I/O
    6677 @subsection fileno/stdin
    6678 
    6679 
    6680 @node Unit posix - File descriptors and low-level I/O - fileno/stdout, Unit posix - File descriptors and low-level I/O - fileno/stderr, Unit posix - File descriptors and low-level I/O - fileno/stdin, Unit posix - File descriptors and low-level I/O
    6681 @subsection fileno/stdout
    6682 
    6683 
    6684 @node Unit posix - File descriptors and low-level I/O - fileno/stderr, Unit posix - File descriptors and low-level I/O - open/rdonly, Unit posix - File descriptors and low-level I/O - fileno/stdout, Unit posix - File descriptors and low-level I/O
    6685 @subsection fileno/stderr
    6686 
    6687 
    6688 These variables contain file-descriptors for the standard I/O files.
    6689 
    6690 @node Unit posix - File descriptors and low-level I/O - open/rdonly, Unit posix - File descriptors and low-level I/O - open/wronly, Unit posix - File descriptors and low-level I/O - fileno/stderr, Unit posix - File descriptors and low-level I/O
    6691 @subsection open/rdonly
    6692 
    6693 
    6694 @node Unit posix - File descriptors and low-level I/O - open/wronly, Unit posix - File descriptors and low-level I/O - open/rdwr, Unit posix - File descriptors and low-level I/O - open/rdonly, Unit posix - File descriptors and low-level I/O
    6695 @subsection open/wronly
    6696 
    6697 
    6698 @node Unit posix - File descriptors and low-level I/O - open/rdwr, Unit posix - File descriptors and low-level I/O - open/read, Unit posix - File descriptors and low-level I/O - open/wronly, Unit posix - File descriptors and low-level I/O
    6699 @subsection open/rdwr
    6700 
    6701 
    6702 @node Unit posix - File descriptors and low-level I/O - open/read, Unit posix - File descriptors and low-level I/O - open/write, Unit posix - File descriptors and low-level I/O - open/rdwr, Unit posix - File descriptors and low-level I/O
    6703 @subsection open/read
    6704 
    6705 
    6706 @node Unit posix - File descriptors and low-level I/O - open/write, Unit posix - File descriptors and low-level I/O - open/creat, Unit posix - File descriptors and low-level I/O - open/read, Unit posix - File descriptors and low-level I/O
    6707 @subsection open/write
    6708 
    6709 
    6710 @node Unit posix - File descriptors and low-level I/O - open/creat, Unit posix - File descriptors and low-level I/O - open/append, Unit posix - File descriptors and low-level I/O - open/write, Unit posix - File descriptors and low-level I/O
    6711 @subsection open/creat
    6712 
    6713 
    6714 @node Unit posix - File descriptors and low-level I/O - open/append, Unit posix - File descriptors and low-level I/O - open/excl, Unit posix - File descriptors and low-level I/O - open/creat, Unit posix - File descriptors and low-level I/O
    6715 @subsection open/append
    6716 
    6717 
    6718 @node Unit posix - File descriptors and low-level I/O - open/excl, Unit posix - File descriptors and low-level I/O - open/noctty, Unit posix - File descriptors and low-level I/O - open/append, Unit posix - File descriptors and low-level I/O
    6719 @subsection open/excl
    6720 
    6721 
    6722 @node Unit posix - File descriptors and low-level I/O - open/noctty, Unit posix - File descriptors and low-level I/O - open/nonblock, Unit posix - File descriptors and low-level I/O - open/excl, Unit posix - File descriptors and low-level I/O
    6723 @subsection open/noctty
    6724 
    6725 
    6726 @node Unit posix - File descriptors and low-level I/O - open/nonblock, Unit posix - File descriptors and low-level I/O - open/trunc, Unit posix - File descriptors and low-level I/O - open/noctty, Unit posix - File descriptors and low-level I/O
    6727 @subsection open/nonblock
    6728 
    6729 
    6730 @node Unit posix - File descriptors and low-level I/O - open/trunc, Unit posix - File descriptors and low-level I/O - open/sync, Unit posix - File descriptors and low-level I/O - open/nonblock, Unit posix - File descriptors and low-level I/O
    6731 @subsection open/trunc
    6732 
    6733 
    6734 @node Unit posix - File descriptors and low-level I/O - open/sync, Unit posix - File descriptors and low-level I/O - open/fsync, Unit posix - File descriptors and low-level I/O - open/trunc, Unit posix - File descriptors and low-level I/O
    6735 @subsection open/sync
    6736 
    6737 
    6738 @node Unit posix - File descriptors and low-level I/O - open/fsync, Unit posix - File descriptors and low-level I/O - open/binary, Unit posix - File descriptors and low-level I/O - open/sync, Unit posix - File descriptors and low-level I/O
    6739 @subsection open/fsync
    6740 
    6741 
    6742 @node Unit posix - File descriptors and low-level I/O - open/binary, Unit posix - File descriptors and low-level I/O - open/text, Unit posix - File descriptors and low-level I/O - open/fsync, Unit posix - File descriptors and low-level I/O
    6743 @subsection open/binary
    6744 
    6745 
    6746 @node Unit posix - File descriptors and low-level I/O - open/text, Unit posix - File descriptors and low-level I/O - open-input-file*, Unit posix - File descriptors and low-level I/O - open/binary, Unit posix - File descriptors and low-level I/O
    6747 @subsection open/text
    6748 
    6749 
    6750 Flags for use with @code{file-open}.
    6751 
    6752 @node Unit posix - File descriptors and low-level I/O - open-input-file*, Unit posix - File descriptors and low-level I/O - open-output-file*, Unit posix - File descriptors and low-level I/O - open/text, Unit posix - File descriptors and low-level I/O
     7262@node Unit posix - File descriptors and low-level I/O - open-input-file*, Unit posix - File descriptors and low-level I/O - open-output-file*, Unit posix - File descriptors and low-level I/O - file-control, Unit posix - File descriptors and low-level I/O
    67537263@subsection open-input-file*
    67547264
     
    67847294* Unit posix - Retrieving file attributes - file-size::
    67857295* Unit posix - Retrieving file attributes - regular-file?::
     7296* Unit posix - Retrieving file attributes - file-owner::
     7297* Unit posix - Retrieving file attributes - file-permissions::
     7298* Unit posix - Retrieving file attributes - file-read-access?::
     7299* Unit posix - Retrieving file attributes - file-write-access?::
     7300* Unit posix - Retrieving file attributes - file-execute-access?::
    67867301
    67877302@end menu
     
    68147329[procedure] (file-stat FILE [LINK])
    68157330@end verbatim
    6816 Returns a 13-element vector with the following contents: inode-number, mode (as with @code{file-permissions}), number of hard links, uid of owner (as with @code{file-owner}), gid of owner, size (as with @code{file-size}) and access-, change- and modification-time (as with @code{file-access-time}, @code{file-change-time} and @code{file-modification-time}, device id, device type (for special file inode, blocksize and blocks allocated.  On Windows systems the last 4 values are undefined.  If the optional argument @code{LINK} is given and not @code{#f}, then the file-statistics vector will be resolved for symbolic links (otherwise symbolic links are not resolved).
     7331Returns a 13-element vector with the following contents: inode-number, mode (as with @code{file-permissions}), number of hard links, uid of owner (as with @code{file-owner}), gid of owner, size (as with @code{file-size}) and access-, change- and modification-time (as with @code{file-access-time}, @code{file-change-time} and @code{file-modification-time}, device id, device type (for special file inode, blocksize and blocks allocated.  On Windows systems the last 4 values are undefined.  If the optional argument @code{LINK} is given and not @code{#f}, then the file-statistics vector will be resolved for symbolic links (otherwise symbolic links are not resolved). Note that for very large files, the @code{file-size} value may be an inexact integer.
    68177332
    68187333@node Unit posix - Retrieving file attributes - file-position, Unit posix - Retrieving file attributes - file-size, Unit posix - Retrieving file attributes - file-stat, Unit posix - Retrieving file attributes
     
    68327347[procedure] (file-size FILENAME)
    68337348@end verbatim
    6834 Returns the size of the file designated by @code{FILE}.  @code{FILE} may be a filename or a file-descriptor.  If the file does not exist, an error is signaled.
    6835 
    6836 @node Unit posix - Retrieving file attributes - regular-file?,  , Unit posix - Retrieving file attributes - file-size, Unit posix - Retrieving file attributes
     7349Returns the size of the file designated by @code{FILE}.  @code{FILE} may be a filename or a file-descriptor.  If the file does not exist, an error is signaled. Note that for very large files, @code{file-size} may return an inexact integer.
     7350
     7351@node Unit posix - Retrieving file attributes - regular-file?, Unit posix - Retrieving file attributes - file-owner, Unit posix - Retrieving file attributes - file-size, Unit posix - Retrieving file attributes
    68377352@subsection regular-file?
    68387353
     
    68427357@end verbatim
    68437358Returns true, if @code{FILENAME} names a regular file (not a directory or symbolic link).
     7359
     7360@node Unit posix - Retrieving file attributes - file-owner, Unit posix - Retrieving file attributes - file-permissions, Unit posix - Retrieving file attributes - regular-file?, Unit posix - Retrieving file attributes
     7361@subsection file-owner
     7362
     7363
     7364@verbatim
     7365[procedure] (file-owner FILE)
     7366@end verbatim
     7367Returns the user-id of @code{FILE}.  @code{FILE} may be a filename or a file-descriptor.
     7368
     7369@node Unit posix - Retrieving file attributes - file-permissions, Unit posix - Retrieving file attributes - file-read-access?, Unit posix - Retrieving file attributes - file-owner, Unit posix - Retrieving file attributes
     7370@subsection file-permissions
     7371
     7372
     7373@verbatim
     7374[procedure] (file-permissions FILE)
     7375@end verbatim
     7376Returns the permission bits for @code{FILE}. You can test this value by performing bitwise operations on the result and the @code{perm/...} values.  @code{FILE} may be a filename or a file-descriptor.
     7377
     7378@node Unit posix - Retrieving file attributes - file-read-access?, Unit posix - Retrieving file attributes - file-write-access?, Unit posix - Retrieving file attributes - file-permissions, Unit posix - Retrieving file attributes
     7379@subsection file-read-access?
     7380
     7381
     7382@node Unit posix - Retrieving file attributes - file-write-access?, Unit posix - Retrieving file attributes - file-execute-access?, Unit posix - Retrieving file attributes - file-read-access?, Unit posix - Retrieving file attributes
     7383@subsection file-write-access?
     7384
     7385
     7386@node Unit posix - Retrieving file attributes - file-execute-access?,  , Unit posix - Retrieving file attributes - file-write-access?, Unit posix - Retrieving file attributes
     7387@subsection file-execute-access?
     7388
     7389
     7390@verbatim
     7391[procedure] (file-read-access? FILENAME)
     7392[procedure] (file-write-access? FILENAME)
     7393[procedure] (file-execute-access? FILENAME)
     7394@end verbatim
     7395These procedures return @code{#t} if the current user has read, write or execute permissions on the file named @code{FILENAME}.
    68447396
    68457397@node Unit posix - Changing file attributes, Unit posix - Processes, Unit posix - Retrieving file attributes, Unit posix
     
    68497401* Unit posix - Changing file attributes - file-truncate::
    68507402* Unit posix - Changing file attributes - set-file-position!::
     7403* Unit posix - Changing file attributes - change-file-mode::
     7404* Unit posix - Changing file attributes - change-file-owner::
    68517405
    68527406@end menu
     
    68627416Truncates the file @code{FILE} to the length @code{OFFSET}, which should be an integer. If the file-size is smaller or equal to @code{OFFSET} then nothing is done.  @code{FILE} should be a filename or a file-descriptor.
    68637417
    6864 @node Unit posix - Changing file attributes - set-file-position!,  , Unit posix - Changing file attributes - file-truncate, Unit posix - Changing file attributes
     7418@node Unit posix - Changing file attributes - set-file-position!, Unit posix - Changing file attributes - change-file-mode, Unit posix - Changing file attributes - file-truncate, Unit posix - Changing file attributes
    68657419@subsection set-file-position!
    68667420
     
    68747428Exceptions: @code{(exn bounds)}, @code{(exn i/o file)}
    68757429
     7430@node Unit posix - Changing file attributes - change-file-mode, Unit posix - Changing file attributes - change-file-owner, Unit posix - Changing file attributes - set-file-position!, Unit posix - Changing file attributes
     7431@subsection change-file-mode
     7432
     7433
     7434@verbatim
     7435[procedure] (change-file-mode FILENAME MODE)
     7436@end verbatim
     7437Changes the current file mode of the file named @code{FILENAME} to @code{MODE} using the @code{chmod()} system call.  The @code{perm/...} variables contain the various permission bits and can be combinded with the @code{bitwise-ior} procedure.
     7438
     7439@node Unit posix - Changing file attributes - change-file-owner,  , Unit posix - Changing file attributes - change-file-mode, Unit posix - Changing file attributes
     7440@subsection change-file-owner
     7441
     7442
     7443@verbatim
     7444[procedure] (change-file-owner FILENAME UID GID)
     7445@end verbatim
     7446Changes the owner information of the file named @code{FILENAME} to the user- and group-ids @code{UID} and @code{GID} (which should be exact integers) using the @code{chown()} system call.
     7447
    68767448@node Unit posix - Processes, Unit posix - Hard and symbolic links, Unit posix - Changing file attributes, Unit posix
    68777449@section Processes
     
    68807452* Unit posix - Processes - current-process-id::
    68817453* Unit posix - Processes - parent-process-id::
     7454* Unit posix - Processes - process-group-id::
    68827455* Unit posix - Processes - process-execute::
    68837456* Unit posix - Processes - process-fork::
     
    68887461* Unit posix - Processes - process*::
    68897462* Unit posix - Processes - sleep::
     7463* Unit posix - Processes - create-session::
    68907464
    68917465@end menu
     
    69017475Returns the process ID of the current process.
    69027476
    6903 @node Unit posix - Processes - parent-process-id, Unit posix - Processes - process-execute, Unit posix - Processes - current-process-id, Unit posix - Processes
     7477@node Unit posix - Processes - parent-process-id, Unit posix - Processes - process-group-id, Unit posix - Processes - current-process-id, Unit posix - Processes
    69047478@subsection parent-process-id
    69057479
     
    69107484Returns the process ID of the parent of the current process.
    69117485
    6912 @node Unit posix - Processes - process-execute, Unit posix - Processes - process-fork, Unit posix - Processes - parent-process-id, Unit posix - Processes
     7486@node Unit posix - Processes - process-group-id, Unit posix - Processes - process-execute, Unit posix - Processes - parent-process-id, Unit posix - Processes
     7487@subsection process-group-id
     7488
     7489
     7490@verbatim
     7491[procedure] (process-group-id PID)
     7492@end verbatim
     7493Returns the process group ID of the process specified by @code{PID}.
     7494
     7495@node Unit posix - Processes - process-execute, Unit posix - Processes - process-fork, Unit posix - Processes - process-group-id, Unit posix - Processes
    69137496@subsection process-execute
    69147497
     
    70017584Like @code{process} but returns 4 values: an input port from which data written by the sub-process can be read, an output port from which any data written to will be received as input in the sub-process, the process-id of the started sub-process, and an input port from which data written by the sub-process to @code{stderr} can be read.
    70027585
    7003 @node Unit posix - Processes - sleep,  , Unit posix - Processes - process*, Unit posix - Processes
     7586@node Unit posix - Processes - sleep, Unit posix - Processes - create-session, Unit posix - Processes - process*, Unit posix - Processes
    70047587@subsection sleep
    70057588
     
    70107593Puts the process to sleep for @code{SECONDS}. Returns either 0 if the time has completely elapsed, or the number of remaining seconds, if a signal occurred.
    70117594
    7012 @node Unit posix - Hard and symbolic links, Unit posix - Permissions, Unit posix - Processes, Unit posix
     7595@node Unit posix - Processes - create-session,  , Unit posix - Processes - sleep, Unit posix - Processes
     7596@subsection create-session
     7597
     7598
     7599@verbatim
     7600[procedure] (create-session)
     7601@end verbatim
     7602Creates a new session if the calling process is not a process group leader and returns the session ID.
     7603
     7604@node Unit posix - Hard and symbolic links, Unit posix - Retrieving user & group information, Unit posix - Processes, Unit posix
    70137605@section Hard and symbolic links
    70147606
     
    70587650Creates a hard link from @code{OLDNAME} to @code{NEWNAME} (both strings).
    70597651
    7060 @node Unit posix - Permissions, Unit posix - Record locking, Unit posix - Hard and symbolic links, Unit posix
    7061 @section Permissions
    7062 
    7063 @menu
    7064 * Unit posix - Permissions - file-owner::
    7065 * Unit posix - Permissions - file-permissions::
    7066 * Unit posix - Permissions - file-read-access?::
    7067 * Unit posix - Permissions - file-write-access?::
    7068 * Unit posix - Permissions - file-execute-access?::
    7069 * Unit posix - Permissions - change-file-mode::
    7070 * Unit posix - Permissions - change-file-owner::
    7071 * Unit posix - Permissions - current-user-id::
    7072 * Unit posix - Permissions - current-group-id::
    7073 * Unit posix - Permissions - current-effective-user-id::
    7074 * Unit posix - Permissions - current-effective-group-id::
    7075 * Unit posix - Permissions - process-group-id::
    7076 * Unit posix - Permissions - group-information::
    7077 * Unit posix - Permissions - get-groups::
    7078 * Unit posix - Permissions - set-groups!::
    7079 * Unit posix - Permissions - initialize-groups::
    7080 * Unit posix - Permissions - perm/irusr::
    7081 * Unit posix - Permissions - perm/iwusr::
    7082 * Unit posix - Permissions - perm/ixusr::
    7083 * Unit posix - Permissions - perm/irgrp::
    7084 * Unit posix - Permissions - perm/iwgrp::
    7085 * Unit posix - Permissions - perm/ixgrp::
    7086 * Unit posix - Permissions - perm/iroth::
    7087 * Unit posix - Permissions - perm/iwoth::
    7088 * Unit posix - Permissions - perm/ixoth::
    7089 * Unit posix - Permissions - perm/irwxu::
    7090 * Unit posix - Permissions - perm/irwxg::
    7091 * Unit posix - Permissions - perm/irwxo::
    7092 * Unit posix - Permissions - perm/isvtx::
    7093 * Unit posix - Permissions - perm/isuid::
    7094 * Unit posix - Permissions - perm/isgid::
    7095 * Unit posix - Permissions - set-process-group-id!::
    7096 * Unit posix - Permissions - user-information::
    7097 * Unit posix - Permissions - create-session::
    7098 
    7099 @end menu
    7100 
    7101 
    7102 @node Unit posix - Permissions - file-owner, Unit posix - Permissions - file-permissions,  , Unit posix - Permissions
    7103 @subsection file-owner
    7104 
    7105 
    7106 @verbatim
    7107 [procedure] (file-owner FILE)
    7108 @end verbatim
    7109 Returns the user-id of @code{FILE}.  @code{FILE} may be a filename or a file-descriptor.
    7110 
    7111 @node Unit posix - Permissions - file-permissions, Unit posix - Permissions - file-read-access?, Unit posix - Permissions - file-owner, Unit posix - Permissions
    7112 @subsection file-permissions
    7113 
    7114 
    7115 @verbatim
    7116 [procedure] (file-permissions FILE)
    7117 @end verbatim
    7118 Returns the permission bits for @code{FILE}. You can test this value by performing bitwise operations on the result and the @code{perm/...} values.  @code{FILE} may be a filename or a file-descriptor.
    7119 
    7120 @node Unit posix - Permissions - file-read-access?, Unit posix - Permissions - file-write-access?, Unit posix - Permissions - file-permissions, Unit posix - Permissions
    7121 @subsection file-read-access?
    7122 
    7123 
    7124 @node Unit posix - Permissions - file-write-access?, Unit posix - Permissions - file-execute-access?, Unit posix - Permissions - file-read-access?, Unit posix - Permissions
    7125 @subsection file-write-access?
    7126 
    7127 
    7128 @node Unit posix - Permissions - file-execute-access?, Unit posix - Permissions - change-file-mode, Unit posix - Permissions - file-write-access?, Unit posix - Permissions
    7129 @subsection file-execute-access?
    7130 
    7131 
    7132 @verbatim
    7133 [procedure] (file-read-access? FILENAME)
    7134 [procedure] (file-write-access? FILENAME)
    7135 [procedure] (file-execute-access? FILENAME)
    7136 @end verbatim
    7137 These procedures return @code{#t} if the current user has read, write or execute permissions on the file named @code{FILENAME}.
    7138 
    7139 @node Unit posix - Permissions - change-file-mode, Unit posix - Permissions - change-file-owner, Unit posix - Permissions - file-execute-access?, Unit posix - Permissions
    7140 @subsection change-file-mode
    7141 
    7142 
    7143 @verbatim
    7144 [procedure] (change-file-mode FILENAME MODE)
    7145 @end verbatim
    7146 Changes the current file mode of the file named @code{FILENAME} to @code{MODE} using the @code{chmod()} system call.  The @code{perm/...} variables contain the various permission bits and can be combinded with the @code{bitwise-ior} procedure.
    7147 
    7148 @node Unit posix - Permissions - change-file-owner, Unit posix - Permissions - current-user-id, Unit posix - Permissions - change-file-mode, Unit posix - Permissions
    7149 @subsection change-file-owner
    7150 
    7151 
    7152 @verbatim
    7153 [procedure] (change-file-owner FILENAME UID GID)
    7154 @end verbatim
    7155 Changes the owner information of the file named @code{FILENAME} to the user- and group-ids @code{UID} and @code{GID} (which should be exact integers) using the @code{chown()} system call.
    7156 
    7157 @node Unit posix - Permissions - current-user-id, Unit posix - Permissions - current-group-id, Unit posix - Permissions - change-file-owner, Unit posix - Permissions
     7652@node Unit posix - Retrieving user & group information, Unit posix - Changing user & group information, Unit posix - Hard and symbolic links, Unit posix
     7653@section Retrieving user & group information
     7654
     7655@menu
     7656* Unit posix - Retrieving user & group information - current-user-id::
     7657* Unit posix - Retrieving user & group information - current-effective-user-id::
     7658* Unit posix - Retrieving user & group information - user-information::
     7659* Unit posix - Retrieving user & group information - current-group-id::
     7660* Unit posix - Retrieving user & group information - current-effective-group-id::
     7661* Unit posix - Retrieving user & group information - group-information::
     7662* Unit posix - Retrieving user & group information - get-groups::
     7663
     7664@end menu
     7665
     7666
     7667@node Unit posix - Retrieving user & group information - current-user-id, Unit posix - Retrieving user & group information - current-effective-user-id,  , Unit posix - Retrieving user & group information
    71587668@subsection current-user-id
    7159 
    7160 
    7161 @node Unit posix - Permissions - current-group-id, Unit posix - Permissions - current-effective-user-id, Unit posix - Permissions - current-user-id, Unit posix - Permissions
    7162 @subsection current-group-id
    7163 
    7164 
    7165 @node Unit posix - Permissions - current-effective-user-id, Unit posix - Permissions - current-effective-group-id, Unit posix - Permissions - current-group-id, Unit posix - Permissions
    7166 @subsection current-effective-user-id
    7167 
    7168 
    7169 @node Unit posix - Permissions - current-effective-group-id, Unit posix - Permissions - process-group-id, Unit posix - Permissions - current-effective-user-id, Unit posix - Permissions
    7170 @subsection current-effective-group-id
    71717669
    71727670
     
    71747672[procedure] (current-user-id)
    71757673[setter] (set! (current-user-id) UID)
     7674@end verbatim
     7675Get or set the real user-id of the current process.
     7676
     7677@node Unit posix - Retrieving user & group information - current-effective-user-id, Unit posix - Retrieving user & group information - user-information, Unit posix - Retrieving user & group information - current-user-id, Unit posix - Retrieving user & group information
     7678@subsection current-effective-user-id
     7679
     7680
     7681@verbatim
     7682[procedure] (current-effective-user-id)
     7683[setter] (set! (current-effective-user-id) UID)
     7684@end verbatim
     7685Get or set the effective user-id of the current process.
     7686
     7687@node Unit posix - Retrieving user & group information - user-information, Unit posix - Retrieving user & group information - current-group-id, Unit posix - Retrieving user & group information - current-effective-user-id, Unit posix - Retrieving user & group information
     7688@subsection user-information
     7689
     7690
     7691@verbatim
     7692[procedure] (user-information USER [AS-VECTOR])
     7693@end verbatim
     7694If @code{USER} specifes a valid username (as a string) or user ID, then the user database is consulted and a list of 7 values are returned: the user-name, the encrypted password, the user ID, the group ID, a user-specific string, the home directory and the default shell. When @code{AS-VECTOR} is @code{#t} a vector of 7 elements is returned instead of a list. If no user with this name or id then @code{#f} is returned.
     7695
     7696@node Unit posix - Retrieving user & group information - current-group-id, Unit posix - Retrieving user & group information - current-effective-group-id, Unit posix - Retrieving user & group information - user-information, Unit posix - Retrieving user & group information
     7697@subsection current-group-id
     7698
     7699
     7700@verbatim
    71767701[procedure] (current-group-id)
    71777702[setter] (set! (current-group-id) GID)
    7178 [procedure] (current-effective-user-id)
    7179 [setter] (set! (current-effective-user-id) UID)
     7703@end verbatim
     7704Get or set the real group-id of the current process.
     7705
     7706@node Unit posix - Retrieving user & group information - current-effective-group-id, Unit posix - Retrieving user & group information - group-information, Unit posix - Retrieving user & group information - current-group-id, Unit posix - Retrieving user & group information
     7707@subsection current-effective-group-id
     7708
     7709
     7710@verbatim
    71807711[procedure] (current-effective-group-id)
    71817712[setter] (set! (current-effective-group-id) GID)
    71827713@end verbatim
    7183 Get or set the real/effective user- and group-ids of the current process.
    7184 
    7185 @node Unit posix - Permissions - process-group-id, Unit posix - Permissions - group-information, Unit posix - Permissions - current-effective-group-id, Unit posix - Permissions
    7186 @subsection process-group-id
    7187 
    7188 
    7189 @verbatim
    7190 [procedure] (process-group-id PID)
    7191 @end verbatim
    7192 Returns the process group ID of the process specified by @code{PID}.
    7193 
    7194 @node Unit posix - Permissions - group-information, Unit posix - Permissions - get-groups, Unit posix - Permissions - process-group-id, Unit posix - Permissions
     7714Get or set the effective group-id of the current process. ID can be found, then @code{#f} is returned.
     7715
     7716@node Unit posix - Retrieving user & group information - group-information, Unit posix - Retrieving user & group information - get-groups, Unit posix - Retrieving user & group information - current-effective-group-id, Unit posix - Retrieving user & group information
    71957717@subsection group-information
    71967718
     
    72017723If @code{GROUP} specifies a valid group-name or group-id, then this procedure returns a list of four values: the group-name, the encrypted group password, the group ID and a list of the names of all group members. If no group with the given name or ID exists, then @code{#f} is returned.
    72027724
    7203 @node Unit posix - Permissions - get-groups, Unit posix - Permissions - set-groups!, Unit posix - Permissions - group-information, Unit posix - Permissions
     7725@node Unit posix - Retrieving user & group information - get-groups,  , Unit posix - Retrieving user & group information - group-information, Unit posix - Retrieving user & group information
    72047726@subsection get-groups
    72057727
     
    72107732Returns a list with the supplementary group IDs of the current user.
    72117733
    7212 @node Unit posix - Permissions - set-groups!, Unit posix - Permissions - initialize-groups, Unit posix - Permissions - get-groups, Unit posix - Permissions
     7734@node Unit posix - Changing user & group information, Unit posix - Record locking, Unit posix - Retrieving user & group information, Unit posix
     7735@section Changing user & group information
     7736
     7737@menu
     7738* Unit posix - Changing user & group information - set-groups!::
     7739* Unit posix - Changing user & group information - initialize-groups::
     7740* Unit posix - Changing user & group information - set-process-group-id!::
     7741
     7742@end menu
     7743
     7744
     7745@node Unit posix - Changing user & group information - set-groups!, Unit posix - Changing user & group information - initialize-groups,  , Unit posix - Changing user & group information
    72137746@subsection set-groups!
    72147747
     
    72217754Only the superuser may invoke this procedure.
    72227755
    7223 @node Unit posix - Permissions - initialize-groups, Unit posix - Permissions - perm/irusr, Unit posix - Permissions - set-groups!, Unit posix - Permissions
     7756@node Unit posix - Changing user & group information - initialize-groups, Unit posix - Changing user & group information - set-process-group-id!, Unit posix - Changing user & group information - set-groups!, Unit posix - Changing user & group information
    72247757@subsection initialize-groups
    72257758
     
    72287761[procedure] (initialize-groups USERNAME BASEGID)
    72297762@end verbatim
    7230 Sets the supplementrary group IDs of the current user to the IDs from the user with name @code{USERNAME}  (a string), including @code{BASEGID}.
     7763Sets the supplementrary group IDs of the current user to the IDs from the user with name @code{USERNAME} (a string), including @code{BASEGID}.
    72317764
    72327765Only the superuser may invoke this procedure.
    72337766
    7234 @node Unit posix - Permissions - perm/irusr, Unit posix - Permissions - perm/iwusr, Unit posix - Permissions - initialize-groups, Unit posix - Permissions
    7235 @subsection perm/irusr
    7236 
    7237 
    7238 @node Unit posix - Permissions - perm/iwusr, Unit posix - Permissions - perm/ixusr, Unit posix - Permissions - perm/irusr, Unit posix - Permissions
    7239 @subsection perm/iwusr
    7240 
    7241 
    7242 @node Unit posix - Permissions - perm/ixusr, Unit posix - Permissions - perm/irgrp, Unit posix - Permissions - perm/iwusr, Unit posix - Permissions
    7243 @subsection perm/ixusr
    7244 
    7245 
    7246 @node Unit posix - Permissions - perm/irgrp, Unit posix - Permissions - perm/iwgrp, Unit posix - Permissions - perm/ixusr, Unit posix - Permissions
    7247 @subsection perm/irgrp
    7248 
    7249 
    7250 @node Unit posix - Permissions - perm/iwgrp, Unit posix - Permissions - perm/ixgrp, Unit posix - Permissions - perm/irgrp, Unit posix - Permissions
    7251 @subsection perm/iwgrp
    7252 
    7253 
    7254 @node Unit posix - Permissions - perm/ixgrp, Unit posix - Permissions - perm/iroth, Unit posix - Permissions - perm/iwgrp, Unit posix - Permissions
    7255 @subsection perm/ixgrp
    7256 
    7257 
    7258 @node Unit posix - Permissions - perm/iroth, Unit posix - Permissions - perm/iwoth, Unit posix - Permissions - perm/ixgrp, Unit posix - Permissions
    7259 @subsection perm/iroth
    7260 
    7261 
    7262 @node Unit posix - Permissions - perm/iwoth, Unit posix - Permissions - perm/ixoth, Unit posix - Permissions - perm/iroth, Unit posix - Permissions
    7263 @subsection perm/iwoth
    7264 
    7265 
    7266 @node Unit posix - Permissions - perm/ixoth, Unit posix - Permissions - perm/irwxu, Unit posix - Permissions - perm/iwoth, Unit posix - Permissions
    7267 @subsection perm/ixoth
    7268 
    7269 
    7270 @node Unit posix - Permissions - perm/irwxu, Unit posix - Permissions - perm/irwxg, Unit posix - Permissions - perm/ixoth, Unit posix - Permissions
    7271 @subsection perm/irwxu
    7272 
    7273 
    7274 @node Unit posix - Permissions - perm/irwxg, Unit posix - Permissions - perm/irwxo, Unit posix - Permissions - perm/irwxu, Unit posix - Permissions
    7275 @subsection perm/irwxg
    7276 
    7277 
    7278 @node Unit posix - Permissions - perm/irwxo, Unit posix - Permissions - perm/isvtx, Unit posix - Permissions - perm/irwxg, Unit posix - Permissions
    7279 @subsection perm/irwxo
    7280 
    7281 
    7282 @node Unit posix - Permissions - perm/isvtx, Unit posix - Permissions - perm/isuid, Unit posix - Permissions - perm/irwxo, Unit posix - Permissions
    7283 @subsection perm/isvtx
    7284 
    7285 
    7286 @node Unit posix - Permissions - perm/isuid, Unit posix - Permissions - perm/isgid, Unit posix - Permissions - perm/isvtx, Unit posix - Permissions
    7287 @subsection perm/isuid
    7288 
    7289 
    7290 @node Unit posix - Permissions - perm/isgid, Unit posix - Permissions - set-process-group-id!, Unit posix - Permissions - perm/isuid, Unit posix - Permissions
    7291 @subsection perm/isgid
    7292 
    7293 
    7294 These variables contain permission bits as used in @code{change-file-mode}.
    7295 
    7296 @node Unit posix - Permissions - set-process-group-id!, Unit posix - Permissions - user-information, Unit posix - Permissions - perm/isgid, Unit posix - Permissions
     7767@node Unit posix - Changing user & group information - set-process-group-id!,  , Unit posix - Changing user & group information - initialize-groups, Unit posix - Changing user & group information
    72977768@subsection set-process-group-id!
    72987769
     
    73047775Sets the process group ID of the process specifed by @code{PID} to @code{PGID}.
    73057776
    7306 @node Unit posix - Permissions - user-information, Unit posix - Permissions - create-session, Unit posix - Permissions - set-process-group-id!, Unit posix - Permissions
    7307 @subsection user-information
    7308 
    7309 
    7310 @verbatim
    7311 [procedure] (user-information USER)
    7312 @end verbatim
    7313 If @code{USER} specifes a valid username (as a string) or user ID, then the user database is consulted and a list of 7 values are returned: the user-name, the encrypted password, the user ID, the group ID, a user-specific string, the home directory and the default shell. If no user with this name or ID can be found, then @code{#f} is returned.
    7314 
    7315 @node Unit posix - Permissions - create-session,  , Unit posix - Permissions - user-information, Unit posix - Permissions
    7316 @subsection create-session
    7317 
    7318 
    7319 @verbatim
    7320 [procedure] (create-session)
    7321 @end verbatim
    7322 Creates a new session if the calling process is not a process group leader and returns the session ID.
    7323 
    7324 @node Unit posix - Record locking, Unit posix - Signal handling, Unit posix - Permissions, Unit posix
     7777@node Unit posix - Record locking, Unit posix - Signal handling, Unit posix - Changing user & group information, Unit posix
    73257778@section Record locking
    73267779
     
    76058058[procedure] (current-environment)
    76068059@end verbatim
    7607 Returns a association list of the environment variables and their current values. 
     8060Returns a association list of the environment variables and their current values.
    76088061
    76098062@node Unit posix - Environment access - setenv, Unit posix - Environment access - unsetenv, Unit posix - Environment access - current-environment, Unit posix - Environment access
     
    76848137* Unit posix - Date and time routines - utc-time->seconds::
    76858138* Unit posix - Date and time routines - time->string::
     8139* Unit posix - Date and time routines - string->time::
    76868140
    76878141@end menu
     
    77558209[procedure] (seconds->string SECONDS)
    77568210@end verbatim
    7757 Converts the local time represented in @code{SECONDS} into a string of the form @code{"Tue May 21 13:46:22 1991\n"}.
     8211Converts the local time represented in @code{SECONDS} into a string of the form @code{"Tue May 21 13:46:22 1991"}.
    77588212
    77598213@node Unit posix - Date and time routines - seconds->utc-time, Unit posix - Date and time routines - utc-time->seconds, Unit posix - Date and time routines - seconds->string, Unit posix - Date and time routines
     
    77758229Converts the ten-element vector @code{VECTOR} representing the UTC time value into the number of seconds since the first of January, 1970 UTC.
    77768230
    7777 @node Unit posix - Date and time routines - time->string,  , Unit posix - Date and time routines - utc-time->seconds, Unit posix - Date and time routines
     8231@node Unit posix - Date and time routines - time->string, Unit posix - Date and time routines - string->time, Unit posix - Date and time routines - utc-time->seconds, Unit posix - Date and time routines
    77788232@subsection time->string
    77798233
    77808234
    77818235@verbatim
    7782 [procedure] (time->string VECTOR)
    7783 @end verbatim
    7784 Converts the broken down time represented in the 10 element vector @code{VECTOR} into a string of the form @code{"Tue May 21 13:46:22 1991\n"}.
     8236[procedure] (time->string VECTOR [FORMAT])
     8237@end verbatim
     8238Without a @code{FORMAT} string converts the broken out time represented in the 10 element vector @code{VECTOR} into a string of the form @code{"Tue May 21 13:46:22 1991"}.
     8239
     8240Otherwise returns the time as a string formatted per the @code{FORMAT} string.
     8241
     8242See the @code{strftime} C procedure for a specification of the @code{FORMAT} string.
     8243
     8244@node Unit posix - Date and time routines - string->time,  , Unit posix - Date and time routines - time->string, Unit posix - Date and time routines
     8245@subsection string->time
     8246
     8247
     8248@verbatim
     8249[procedure] (string->time STRING [FORMAT])
     8250@end verbatim
     8251Returns the time string parsed per the @code{FORMAT} string as a broken out time 10 element vector.
     8252
     8253The default @code{FORMAT} string is @code{"%a %b %e %H:%M:%S %Z %Y"}. (The default @code{date} command format.)
     8254
     8255See the @code{strptime} C procedure for a specification of the @code{FORMAT} string.
    77858256
    77868257@node Unit posix - Raw exit, Unit posix - ERRNO values, Unit posix - Date and time routines, Unit posix
     
    77948265
    77958266@node Unit posix - Raw exit - _exit,  ,  , Unit posix - Raw exit
    7796 @subsection _exit
    7797 
    7798 
    7799 @verbatim
    7800 [procedure] (_exit [CODE])
     8267@subsection @code{_exit}
     8268
     8269
     8270@verbatim
     8271[procedure] (code{_exit} [CODE])
    78018272@end verbatim
    78028273Exits the current process without flushing any buffered output (using the C function @code{_exit}).  Note that the @code{exit-handler} is not called when this procedure is invoked. The optional return-code @code{CODE} defaults to @code{0}.
     
    79438414[procedure] (find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])
    79448415@end verbatim
    7945 Recursively traverses the contents of @code{DIRECTORY} (which should be a string) and invokes the procedure @code{ACTION} for all files for which the procedure @code{PREDICATE} is true.  @code{PREDICATE} may me a procedure of one argument or a regular-expression string. @code{ACTION} should be a procedure of two arguments: the currently encountered file and the result of the previous invocation of @code{ACTION}, or, if this is the first invocation, the value of @code{IDENTITY}. @code{ACTION} defaults to @code{cons}, @code{IDENTITY} defaults to @code{()}.  @code{LIMIT} should a procedure of one argument that is called for each nested directory and which should return true, if that directory is to be traversed recursively. @code{LIMIT} may also be an exact integer that gives the maximum recursion depth. A depth of @code{0} means the files in the specified directory are traversed but not any nested directories. @code{LIMIT} may also be @code{#f} (the default), which is equivalent to @code{(constantly #t)}.
     8416Recursively traverses the contents of @code{DIRECTORY} (which should be a string) and invokes the procedure @code{ACTION} for all files in which the procedure @code{PREDICATE} is true.  @code{PREDICATE} may me a procedure of one argument or a regular-expression string. @code{ACTION} should be a procedure of two arguments: the currently encountered file and the result of the previous invocation of @code{ACTION}, or, if this is the first invocation, the value of @code{IDENTITY}. @code{ACTION} defaults to @code{cons}, @code{IDENTITY} defaults to @code{()}.  @code{LIMIT} should be a procedure of one argument that is called for each nested directory and which should return true, if that directory is to be traversed recursively. @code{LIMIT} may also be an exact integer that gives the maximum recursion depth. For example, a depth of @code{0} means that only files in the top-level, specified directory are to be traversed. In this case, all nested directories are ignored. @code{LIMIT} may also be @code{#f} (the default), which is equivalent to @code{(constantly #t)}.
    79468417
    79478418Note that @code{ACTION} is called with the full pathname of each file, including the directory prefix.
     
    79998470* Unit posix - Terminal ports - terminal-name::
    80008471* Unit posix - Terminal ports - terminal-port?::
     8472* Unit posix - Terminal ports - terminal-size::
    80018473
    80028474@end menu
     
    80128484Returns the name of the terminal that is connected to @code{PORT}.
    80138485
    8014 @node Unit posix - Terminal ports - terminal-port?,  , Unit posix - Terminal ports - terminal-name, Unit posix - Terminal ports
     8486@node Unit posix - Terminal ports - terminal-port?, Unit posix - Terminal ports - terminal-size, Unit posix - Terminal ports - terminal-name, Unit posix - Terminal ports
    80158487@subsection terminal-port?
    80168488
     
    80208492@end verbatim
    80218493Returns @code{#t} if @code{PORT} is connected to a terminal and @code{#f} otherwise.
     8494
     8495@node Unit posix - Terminal ports - terminal-size,  , Unit posix - Terminal ports - terminal-port?, Unit posix - Terminal ports
     8496@subsection terminal-size
     8497
     8498
     8499@verbatim
     8500[procedure] (terminal-size PORT)
     8501@end verbatim
     8502Returns two values: The height and width of the terminal connected to @code{PORT}.
    80228503
    80238504@node Unit posix - How Scheme procedures relate to UNIX C functions, Unit posix - Windows specific notes, Unit posix - Terminal ports, Unit posix
     
    80848565process-group-id  set-process-group-id!
    80858566create-symbolic-link  read-symbolic-link
    8086 file-truncate 
     8567file-truncate
    80878568file-lock  file-lock/blocking  file-unlock  file-test-lock
    80888569create-fifo  fifo?
     
    80918572map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
    80928573set-alarm!
    8093 terminal-port?  terminal-name
     8574terminal-port?  terminal-name terminal-size
    80948575process-fork  process-signal
    8095 parent-process-id 
     8576parent-process-id
    80968577set-root-directory!
    80978578utc-time->seconds
     8579string->time
    80988580@end verbatim
    80998581@node Unit posix - Windows specific notes - Additional Definitions, Unit posix - Windows specific notes - process-spawn, Unit posix - Windows specific notes - Unsupported Definitions, Unit posix - Windows specific notes
     
    81238605
    81248606@end itemize
    8125 These variables contains special flags that specify the exact semantics of @code{process-spawn}: @code{spawn/overlay} replaces the current process with the new one.  @code{spawn/wait} suspends execution of the current process until the spawned process returns. @code{spawn/nowait} does the opposite (@code{spawn/nowaito} is identical, according to the Microsoft documentation) and runs the process asynchronously. @code{spawn/detach} runs the new process in the background, without being attached to a console.
     8607These variables contains special flags that specify the exact semantics of @code{process-spawn}: @code{spawn/overlay} replaces the current process with the new one. @code{spawn/wait} suspends execution of the current process until the spawned process returns. @code{spawn/nowait} does the opposite (@code{spawn/nowaito} is identical, according to the Microsoft documentation) and runs the process asynchronously. @code{spawn/detach} runs the new process in the background, without being attached to a console.
    81268608
    81278609@node Unit posix - Windows specific notes - process-spawn,  , Unit posix - Windows specific notes - Additional Definitions, Unit posix - Windows specific notes
     
    83948876[procedure] (for-each-line PROCEDURE [PORT])
    83958877@end verbatim
    8396 Calls @code{PROCEDURE} for each line read from @code{PORT} (which defaults to the value of @code{(current-input-port)}. The argument passed to @code{PORCEDURE} is a string with the contents of the line, excluding any line-terminators. When all input has been read from the port, @code{for-each-line} returns some unspecified value.
     8878Calls @code{PROCEDURE} for each line read from @code{PORT} (which defaults to the value of @code{(current-input-port)}. The argument passed to @code{PROCEDURE} is a string with the contents of the line, excluding any line-terminators. When all input has been read from the port, @code{for-each-line} returns some unspecified value.
    83978879
    83988880@node Unit utils - Iterating over input lines and files - for-each-argv-line, Unit utils - Iterating over input lines and files - port-for-each, Unit utils - Iterating over input lines and files - for-each-line, Unit utils - Iterating over input lines and files
     
    84078889This code will act as a simple Unix cat(1) command:
    84088890
    8409 <enscript highlight=scheme> (for-each-argv-line print) </enscript>
    8410 
     8891@example
     8892(for-each-argv-line print)
     8893@end example
    84118894@node Unit utils - Iterating over input lines and files - port-for-each, Unit utils - Iterating over input lines and files - port-map, Unit utils - Iterating over input lines and files - for-each-argv-line, Unit utils - Iterating over input lines and files
    84128895@subsection port-for-each
     
    85048987
    85058988@menu
    8506 * Unit utils - Miscellaneous handy things - shift!::
    8507 * Unit utils - Miscellaneous handy things - unshift!::
    8508 
    8509 @end menu
    8510 
    8511 
    8512 @node Unit utils - Miscellaneous handy things - shift!, Unit utils - Miscellaneous handy things - unshift!,  , Unit utils - Miscellaneous handy things
    8513 @subsection shift!
     8989* Unit utils - Miscellaneous handy things - shift! DEPRECATED::
     8990* Unit utils - Miscellaneous handy things - unshift! DEPRECATED::
     8991
     8992@end menu
     8993
     8994
     8995@node Unit utils - Miscellaneous handy things - shift! DEPRECATED, Unit utils - Miscellaneous handy things - unshift! DEPRECATED,  , Unit utils - Miscellaneous handy things
     8996@subsection shift! DEPRECATED
    85148997
    85158998
     
    85199002Returns the car of @code{LIST} (or @code{DEFAULT} if @code{LIST} is empty) and replaces the car of @code{LIST} with it's cadr and the cdr with the cddr. If @code{DEFAULT} is not given, and the list is empty, @code{#f} is returned. An example might be clearer, here:
    85209003
    8521 <enscript highlight=scheme> (define lst '(1 2 3)) (shift! lst)             ==> 1, lst is now (2 3) </enscript>
    8522 
     9004@example
     9005(@strong{define} @strong{lst} '(1 2 3))
     9006(shift! lst)             =@strong{=>} 1, lst is now (2 3)
     9007@end example
     9008@verbatim
     9009
     9010@end verbatim
    85239011The list must contain at least 2 elements.
    85249012
    8525 @node Unit utils - Miscellaneous handy things - unshift!,  , Unit utils - Miscellaneous handy things - shift!, Unit utils - Miscellaneous handy things
    8526 @subsection unshift!
     9013@node Unit utils - Miscellaneous handy things - unshift! DEPRECATED,  , Unit utils - Miscellaneous handy things - shift! DEPRECATED, Unit utils - Miscellaneous handy things
     9014@subsection unshift! DEPRECATED
    85279015
    85289016
     
    85329020Sets the car of @code{PAIR} to @code{X} and the cdr to its cddr. Returns @code{PAIR}:
    85339021
    8534 <enscript highlight=scheme> (define lst '(2)) (unshift! 99 lst)      ; lst is now (99 2) </enscript>
    8535 
     9022@example
     9023(@strong{define} @strong{lst} '(2))
     9024(unshift! 99 lst)      @emph{; lst is now (99 2)
     9025}@end example
    85369026Previous: @ref{Unit posix, Unit posix}
    85379027
     
    86929182[parameter] tcp-read-timeout
    86939183@end verbatim
    8694 Determines the timeout for TCP read operations in milliseconds. A timeout of @code{#f} disables timeout checking and is the default.
     9184Determines the timeout for TCP read operations in milliseconds. A timeout of @code{#f} disables timeout checking. The default read timeout is 60000, i.e. 1 minute.
    86959185
    86969186@node Unit tcp - tcp-write-timeout, Unit tcp - tcp-connect-timeout, Unit tcp - tcp-read-timeout, Unit tcp
     
    87019191[parameter] tcp-write-timeout
    87029192@end verbatim
    8703 Determines the timeout for TCP write operations in milliseconds. A timeout of @code{#f} disables timeout checking and is the default.
     9193Determines the timeout for TCP write operations in milliseconds. A timeout of @code{#f} disables timeout checking. The default write timeout is 60000, i.e. 1 minute.
    87049194
    87059195@node Unit tcp - tcp-connect-timeout, Unit tcp - tcp-accept-timeout, Unit tcp - tcp-write-timeout, Unit tcp
     
    87279217A very simple example follows. Say we have the two files @code{client.scm} and @code{server.scm}:
    87289218
    8729 <enscript highlight=scheme> ; client.scm (declare (uses tcp)) (define-values (i o) (tcp-connect "localhost" 4242)) (write-line "Good Bye!" o) (print (read-line i)) </enscript>
    8730 
    8731 <enscript highlight=scheme> ; server.scm (declare (uses tcp)) (define l (tcp-listen 4242)) (define-values (i o) (tcp-accept l)) (write-line "Hello!" o) (print (read-line i)) (close-input-port i) (close-output-port o) </enscript>
    8732 
     9219@example
     9220@emph{; client.scm
     9221}(declare (uses tcp))
     9222(define-values (i o) (tcp-connect @strong{"localhost"} 4242))
     9223(write-line @strong{"Good Bye!"} o)
     9224(print (read-line i))
     9225@end example
     9226@example
     9227@emph{; server.scm
     9228}(declare (uses tcp))
     9229(@strong{define} @strong{l} (tcp-listen 4242))
     9230(define-values (i o) (tcp-accept l))
     9231(write-line @strong{"Hello!"} o)
     9232(print (read-line i))
     9233(close-input-port i)
     9234(close-output-port o)
     9235@end example
    87339236@verbatim
    87349237% csc server.scm
     
    87509253* Unit lolevel - Tagged pointers::
    87519254* Unit lolevel - Extending procedures with data::
    8752 * Unit lolevel - Blobs::
    87539255* Unit lolevel - Data in unmanaged memory::
    87549256* Unit lolevel - Locatives::
     
    88199321Returns a pointer to a freshly allocated region of static memory. This procedure could be defined as follows:
    88209322
    8821 <enscript highlight=scheme> (define allocate (foreign-lambda c-pointer "malloc" integer)) </enscript>
    8822 
     9323@example
     9324(@strong{define} @strong{allocate} (foreign-lambda c-pointer @strong{"malloc"} integer))
     9325@end example
    88239326@node Unit lolevel - Foreign pointers - free, Unit lolevel - Foreign pointers - null-pointer, Unit lolevel - Foreign pointers - allocate, Unit lolevel - Foreign pointers
    88249327@subsection free
     
    88309333Frees the memory pointed to by @code{POINTER}.  This procedure could be defined as follows:
    88319334
    8832 <enscript highlight=scheme> (define free (foreign-lambda c-pointer "free" integer)) </enscript>
    8833 
     9335@example
     9336(@strong{define} @strong{free} (foreign-lambda c-pointer @strong{"free"} integer))
     9337@end example
    88349338@node Unit lolevel - Foreign pointers - null-pointer, Unit lolevel - Foreign pointers - null-pointer?, Unit lolevel - Foreign pointers - free, Unit lolevel - Foreign pointers
    88359339@subsection null-pointer
     
    91059609If @code{PTR} is a tagged pointer object, its tag is returned. If @code{PTR} is a normal, untagged foreign pointer object @code{#f} is returned. Otherwise an error is signalled.
    91069610
    9107 @node Unit lolevel - Extending procedures with data, Unit lolevel - Blobs, Unit lolevel - Tagged pointers, Unit lolevel
     9611@node Unit lolevel - Extending procedures with data, Unit lolevel - Data in unmanaged memory, Unit lolevel - Tagged pointers, Unit lolevel
    91089612@section Extending procedures with data
    91099613
     
    91539657Changes the data object contained in the extended procedure @code{PROCEDURE} to @code{X}.
    91549658
    9155 <enscript highlight=scheme> (define foo
    9156 
    9157 @verbatim
    9158  (letrec ((f (lambda () (procedure-data x)))
    9159           (x #f) )
    9160    (set! x (extend-procedure f 123))
    9161    x) )
    9162 @end verbatim
    9163 (foo)                                         ==> 123 (set-procedure-data! foo 'hello) (foo)                                         ==> hello </enscript>
    9164 
    9165 @node Unit lolevel - Blobs, Unit lolevel - Data in unmanaged memory, Unit lolevel - Extending procedures with data, Unit lolevel
    9166 @section Blobs
    9167 
    9168 @menu
    9169 * Unit lolevel - Blobs - blob?::
    9170 * Unit lolevel - Blobs - blob-size::
    9171 * Unit lolevel - Blobs - blob->string::
    9172 * Unit lolevel - Blobs - string->blob::
    9173 
    9174 @end menu
    9175 
    9176 
    9177 "blobs" are collections of unstructured bytes. You can't do much with them, but allow conversion to and from SRFI-4 number vectors.
    9178 
    9179 @node Unit lolevel - Blobs - blob?, Unit lolevel - Blobs - blob-size,  , Unit lolevel - Blobs
    9180 @subsection blob?
    9181 
    9182 
    9183 @verbatim
    9184 [procedure] (blob? X)
    9185 @end verbatim
    9186 Returns @code{#t} if @code{X} is a blob object, or @code{#f} otherwise.
    9187 
    9188 @node Unit lolevel - Blobs - blob-size, Unit lolevel - Blobs - blob->string, Unit lolevel - Blobs - blob?, Unit lolevel - Blobs
    9189 @subsection blob-size
    9190 
    9191 
    9192 @verbatim
    9193 [procedure] (blob-size BLOB)
    9194 @end verbatim
    9195 Returns the number of bytes in @code{BLOB}.
    9196 
    9197 @node Unit lolevel - Blobs - blob->string, Unit lolevel - Blobs - string->blob, Unit lolevel - Blobs - blob-size, Unit lolevel - Blobs
    9198 @subsection blob->string
    9199 
    9200 
    9201 @verbatim
    9202 [procedure] (blob->string BLOB)
    9203 @end verbatim
    9204 Returns a string with the contents of @code{BLOB}.
    9205 
    9206 @node Unit lolevel - Blobs - string->blob,  , Unit lolevel - Blobs - blob->string, Unit lolevel - Blobs
    9207 @subsection string->blob
    9208 
    9209 
    9210 @verbatim
    9211 [procedure] (string->blob STRING)
    9212 @end verbatim
    9213 Returns a blob with the contents of @code{STRING}.
    9214 
    9215 @node Unit lolevel - Data in unmanaged memory, Unit lolevel - Locatives, Unit lolevel - Blobs, Unit lolevel
     9659@example
     9660(@strong{define} @strong{foo}
     9661  (@strong{letrec} ((f (@strong{lambda} () (procedure-data x)))
     9662           (x #f) )
     9663    (@strong{set!} x (extend-procedure f 123))
     9664    x) )
     9665(foo)                                         =@strong{=>} 123
     9666(set-procedure-data! foo 'hello)
     9667(foo)                                         =@strong{=>} hello
     9668@end example
     9669@node Unit lolevel - Data in unmanaged memory, Unit lolevel - Locatives, Unit lolevel - Extending procedures with data, Unit lolevel
    92169670@section Data in unmanaged memory
    92179671
     
    92369690Copies the object @code{X} recursively into the memory pointed to by the foreign pointer object returned by @code{ALLOCATOR}, which should be a procedure of a single argument (the number of bytes to allocate). The freshly copied object is returned.  This facility allows moving arbitrary objects into static memory, but care should be taken when mutating evicted data: setting slots in evicted vector-like objects to non-evicted data is not allowed. It @b{is} possible to set characters/bytes in evicted strings or byte-vectors, though.  It is advisable @b{not} to evict ports, because they might be mutated by certain file-operations.  @code{object-evict} is able to handle circular and shared structures, but evicted symbols are no longer unique: a fresh copy of the symbol is created, so
    92379691
    9238 <enscript highlight=scheme> (define x 'foo) (define y (object-evict 'foo)) y                              ==> foo (eq? x y)                      ==> #f (define z (object-evict '(bar bar))) (eq? (car z) (cadr z))         ==> #t </enscript>
    9239 
     9692@example
     9693(@strong{define} @strong{x} 'foo)
     9694(@strong{define} @strong{y} (object-evict 'foo))
     9695y                              =@strong{=>} foo
     9696(eq? x y)                      =@strong{=>} #f
     9697(@strong{define} @strong{z} (object-evict '(bar bar)))
     9698(eq? (car z) (cadr z))         =@strong{=>} #t
     9699@end example
    92409700The @code{ALLOCATOR} defaults to @code{allocate}.
    92419701
     
    93109770[procedure] (make-locative EXP [INDEX])
    93119771@end verbatim
    9312 Creates a locative that refers to the element of the non-immediate object @code{EXP} at position @code{INDEX}. @code{EXP} may be a vector, pair, string, byte-vector, SRFI-4 number-vector, or record. @code{INDEX} should be a fixnum. @code{INDEX} defaults to 0.
     9772Creates a locative that refers to the element of the non-immediate object @code{EXP} at position @code{INDEX}. @code{EXP} may be a vector, pair, string, blob, SRFI-4 number-vector, or record. @code{INDEX} should be a fixnum. @code{INDEX} defaults to 0.
    93139773
    93149774@node Unit lolevel - Locatives - make-weak-locative, Unit lolevel - Locatives - locative?, Unit lolevel - Locatives - make-locative, Unit lolevel - Locatives
     
    94539913Returns a new instance of the record type @code{SYMBOL}, with its slots initialized to @code{ARG1 ...}.  To illustrate:
    94549914
    9455 <enscript highlight=scheme> (define-record point x y) </enscript>
    9456 
     9915@example
     9916(define-record point x y)
     9917@end example
    94579918expands into something quite similar to:
    94589919
    9459 <enscript highlight=scheme> (begin
    9460 
    9461 @verbatim
    9462  (define (make-point x y)
    9463    (make-record-instance 'point x y) )
    9464  (define (point? x)
    9465    (and (record-instance? x)
    9466         (eq? 'point (block-ref x 0)) ) )
    9467  (define (point-x p) (block-ref p 1))
    9468  (define (point-x-set! p x) (block-set! p 1 x))
    9469  (define (point-y p) (block-ref p 2))
    9470  (define (point-y-set! p y) (block-set! p 1 y)) )
    9471 @end verbatim
    9472 </enscript>
    9473 
     9920@example
     9921(@strong{begin}
     9922  (@strong{define} (@strong{make-point} x y)
     9923    (make-record-instance 'point x y) )
     9924  (@strong{define} (@strong{point?} x)
     9925    (@strong{and} (record-instance? x)
     9926         (eq? 'point (block-ref x 0)) ) )
     9927  (@strong{define} (@strong{point-x} p) (block-ref p 1))
     9928  (@strong{define} (@strong{point-x-set!} p x) (block-set! p 1 x))
     9929  (@strong{define} (@strong{point-y} p) (block-ref p 2))
     9930  (@strong{define} (@strong{point-y-set!} p y) (block-set! p 1 y)) )
     9931@end example
    94749932@node Unit lolevel - Low-level data access - move-memory!, Unit lolevel - Low-level data access - number-of-bytes, Unit lolevel - Low-level data access - make-record-instance, Unit lolevel - Low-level data access
    94759933@subsection move-memory!
     
    95389996Sets an internal hook that is invoked when a call to an object other than a procedure is executed at runtime. The procedure @code{PROC} will in that case be called with two arguments: the object being called and a list of the passed arguments.
    95399997
    9540 <enscript highlight=scheme> ;;; Access sequence-elements as in ARC:
    9541 
     9998@example
     9999@emph{;;; Access sequence-elements as in ARC:
     10000}
    954210001(set-invalid-procedure-call-handler!
    9543 
    9544 @verbatim
    9545  (lambda (proc args)
    9546    (cond [(string? proc) (apply string-ref proc args)]
    9547          [(vector? proc) (apply vector-ref proc args)]
    9548          [else (error "call of non-procedure" proc)] ) ) )
    9549 @end verbatim
    9550 ("hello" 4)    ==>  #\o </enscript>
    9551 
     10002  (@strong{lambda} (proc args)
     10003    (@strong{cond} [(string? proc) (apply string-ref proc args)]
     10004          [(vector? proc) (apply vector-ref proc args)]
     10005          [@strong{else} (error @strong{"call of non-procedure"} proc)] ) ) )
     10006
     10007(@strong{"hello"} 4)    =@strong{=>}  #\o
     10008@end example
    955210009This facility does not work in code compiled with the @emph{unsafe} setting.
    955310010
     
    958210039Changes the identity of the value of the car of each pair in @code{ALIST} to the value of the cdr. Both values may not be immediate (i.e. exact integers, characters, booleans or the empty list).
    958310040
    9584 <enscript highlight=scheme> (define x "i used to be a string") (define y '#(and now i am a vector)) (object-become! (list (cons x y))) x                                    ==> #(and now i am a vector) y                                    ==> #(and now i am a vector) (eq? x y)                            ==> #t </enscript>
    9585 
     10041@example
     10042(@strong{define} @strong{x} @strong{"i used to be a string"})
     10043(@strong{define} @strong{y} '#(@strong{and} now i am a vector))
     10044(object-become! (list (cons x y)))
     10045x                                    =@strong{=>} #(@strong{and} now i am a vector)
     10046y                                    =@strong{=>} #(@strong{and} now i am a vector)
     10047(eq? x y)                            =@strong{=>} #t
     10048@end example
    958610049Note: this operation invokes a major garbage collection.
    958710050
     
    959710060Replaces the procedure @code{OLD} with the result of calling the one-argument procedure @code{PROC}. @code{PROC} will receive a copy of @code{OLD} that will be identical in behaviour to the result of @code{PROC}:
    959810061
    9599 <enscript highlight=scheme> ;;; Replace arbitrary procedure with tracing one:
    9600 
     10062@example
     10063@emph{;;; Replace arbitrary procedure with tracing one:
     10064}
    960110065(mutate-procedure my-proc
    9602 
    9603 @verbatim
    9604  (lambda (new)
    9605    (lambda args
    9606      (printf "~s called with arguments: ~s~%" new args)
    9607      (apply new args) ) ) )
    9608 @end verbatim
    9609 </enscript>
    9610 
     10066  (@strong{lambda} (new)
     10067    (@strong{lambda} args
     10068      (printf @strong{"~s called with arguments: ~s~%"} new args)
     10069      (apply new args) ) ) )
     10070@end example
    961110071Previous: @ref{Unit tcp, Unit tcp}
    961210072
     
    966710127Executes the embedded C/C++ code @code{STRING ...}, which should be a sequence of C statements, which are executed and return an unspecified result.
    966810128
    9669 <enscript highlight=scheme> (foreign-code "doSomeInitStuff();")     =>  #<unspecified> </enscript>
    9670 
     10129@example
     10130(foreign-code @strong{"doSomeInitStuff();"})     @strong{=>}  #<unspecified>
     10131@end example
    967110132Code wrapped inside @code{foreign-code} may not invoke callbacks into Scheme.
    967210133
     
    968010141Evaluates the embedded C/C++ expression @code{STRING}, returning a value of type given in the foreign-type specifier @code{TYPE}.
    968110142
    9682 <enscript highlight=scheme> (print (foreign-value "my_version_string" c-string)) </enscript>
    9683 
     10143@example
     10144(print (foreign-value @strong{"my_version_string"} c-string))
     10145@end example
    968410146@node Accessing external objects - foreign-declare, Accessing external objects - define-foreign-type, Accessing external objects - foreign-value, Accessing external objects
    968510147@section foreign-declare
     
    970010162Defines an alias for @code{TYPE} with the name @code{NAME} (a symbol). @code{TYPE} may be a type-specifier or a string naming a C type. The namespace of foreign type specifiers is separate from the normal Scheme namespace.  The optional arguments @code{ARGCONVERT} and @code{RETCONVERT} should evaluate to procedures that map argument- and result-values to a value that can be transformed to @code{TYPE}:
    970110163
    9702 <enscript highlight=scheme> (define-foreign-type char-vector
    9703 
    9704 @verbatim
    9705  nonnull-c-string
    9706  (compose list->string vector->list)
    9707  (compose list->vector string->list) )
    9708 @end verbatim
    9709 (define strlen
    9710 
    9711 @verbatim
    9712  (foreign-lambda int "strlen" char-vector) )
    9713 @end verbatim
    9714 (strlen '#(#\a #\b #\c))                      ==> 3
    9715 
    9716 (define memset
    9717 
    9718 @verbatim
    9719  (foreign-lambda char-vector "memset" char-vector char int) )
    9720 @end verbatim
    9721 (memset '#(#_ #_ #_) #\X 3)                ==> #(#\X #\X #\X) </enscript>
    9722 
     10164@example
     10165(define-foreign-type char-vector
     10166  nonnull-c-string
     10167  (compose list->string vector->list)
     10168  (compose list->vector string->list) )
     10169
     10170(@strong{define} @strong{strlen}
     10171  (foreign-lambda int @strong{"strlen"} char-vector) )
     10172
     10173(strlen '#(#\a #\b #\c))                      =@strong{=>} 3
     10174
     10175(@strong{define} @strong{memset}
     10176  (foreign-lambda char-vector @strong{"memset"} char-vector char int) )
     10177
     10178(memset '#(#_ #_ #_) #\X 3)                =@strong{=>} #(#\X #\X #\X)
     10179@end example
    972310180Foreign type-definitions are only visible in the compilation-unit in which they are defined, so use @code{include} to use the same definitions in multiple files.
    972410181
     
    973210189Defines a foreign variable of name @code{NAME} (a symbol). @code{STRING} should be the real name of a foreign variable or parameterless macro. If @code{STRING} is not given, then the variable name @code{NAME} will be converted to a string and used instead. All references and assignments (via @code{set!}) are modified to correctly convert values between Scheme and C representation. This foreign variable can only be accessed in the current compilation unit, but the name can be lexically shadowed.  Note that @code{STRING} can name an arbitrary C expression. If no assignments are performed, then @code{STRING} doesn't even have to specify an lvalue.
    973310190
    9734 <enscript highlight=scheme>
    9735 
    9736 @enumerate
    9737 @item > enum @{ abc=3, def, ghi @}; <#
    9738 
    9739 
    9740 @end enumerate
     10191@example
     10192#>
     10193enum @{ abc=3, def, ghi @}@emph{;
     10194}<#
     10195
    974110196(define-macro (define-simple-foreign-enum . items)
    9742 
    9743 @verbatim
    9744  `(begin
    9745     ,@@(map (match-lambda
    9746              [(name realname) `(define-foreign-variable ,name int ,realname)]
    9747              [name `(define-foreign-variable ,name int)] )
    9748     items) ) )
    9749 @end verbatim
     10197  `(@strong{begin}
     10198     ,@@(map (match-lambda
     10199              [(name realname) `(define-foreign-variable ,name int ,realname)]
     10200              [name `(define-foreign-variable ,name int)] )
     10201     items) ) )
     10202
    975010203(define-simple-foreign-enum abc def ghi)
    975110204
    9752 ghi                               ==> 5 </enscript>
    9753 
     10205ghi                               =@strong{=>} 5
     10206@end example
    975410207@node Accessing external objects - define-foreign-record, Accessing external objects - define-foreign-enum, Accessing external objects - define-foreign-variable, Accessing external objects
    975510208@section define-foreign-record
     
    983210285An example:
    983310286
    9834 <enscript highlight=scheme> (require-for-syntax 'srfi-13)
     10287@example
     10288(require-for-syntax 'srfi-13)
    983510289
    983610290(define-foreign-record Some_Struct
    9837 
    9838 @verbatim
    9839  (rename: (compose string-downcase (cut string-translate <> "_" "-")))
    9840  (constructor: make-some-struct)
    9841  (destructor: free-some-struct)
    9842  (int xCoord)
    9843  (int yCoord) )
    9844 @end verbatim
    9845 </enscript>
    9846 
     10291  (rename: (compose string-downcase (cut string-translate <> @strong{"_"} @strong{"-"})))
     10292  (constructor: make-some-struct)
     10293  (destructor: free-some-struct)
     10294  (int xCoord)
     10295  (int yCoord) )
     10296@end example
    984710297will generate the following procedures:
    984810298
    9849 <enscript highlight=scheme> (make-some-struct)              --> C-POINTER (free-some-struct C-POINTER)
    9850 
    9851 (some-struct-xcoord C-POINTER)  --> NUMBER (some-struct-ycoord C-POINTER)  --> NUMBER
    9852 
    9853 (some-struct-xcoord-set! C-POINTER NUMBER) (some-struct-ycoord-set! C-POINTER NUMBER) </enscript>
    9854 
     10299@example
     10300(make-some-struct)              --> C-POINTER
     10301(free-some-struct C-POINTER)
     10302
     10303(some-struct-xcoord C-POINTER)  --> NUMBER
     10304(some-struct-ycoord C-POINTER)  --> NUMBER
     10305
     10306(some-struct-xcoord-set! C-POINTER NUMBER)
     10307(some-struct-ycoord-set! C-POINTER NUMBER)
     10308@end example
    985510309@node Accessing external objects - define-foreign-enum, Accessing external objects - foreign-lambda, Accessing external objects - define-foreign-record, Accessing external objects
    985610310@section define-foreign-enum
     
    985810312
    985910313@verbatim
    9860 [syntax] (define-foreign-enum TYPENAME ITEM ...)
    9861 @end verbatim
    9862 Defines a foreign type (as with @code{define-foreign-type}) that maps the elements of a C/C++ enum (or a enum-like list of constants) to and from a set of symbols. @code{TYPENAME} names a foreign type that converts a symbol argument from the set @code{ITEM ...} into the appropriate enum value when passed as an argument to a foreign function. A list of symbols passed as an argument will be combined using @code{bitwise-ior}. An empty list will be passed as 0 (zero). Results of the enum type are automatically converted into a symbol (note that combinations are not supported in this case). @code{TYPENAME} may alternatively be a list of the form @code{(SCHEMENAME REALTYPE)} - in this case @code{REALTYPE} designates the native type used. The default native type is @code{"TYPENAME"}. Additionally two procedures are generated named @code{SCHEMENAME->number} and @code{number->SCHEMENAME} which take one argument and convert a  symbol (or a list of symbols) into its numeric value and vice versa.
     10314[syntax] (define-foreign-enum TYPESPEC [USE-ALIASES] ENUMSPEC ...)
     10315@end verbatim
     10316Defines a foreign type (as with @code{define-foreign-type}) that maps the elements of a C/C++ enum (or a enum-like list of constants) to and from a set of symbols.
     10317
     10318@code{TYPESPEC} specifies a foreign type that converts a symbol argument from the set @code{ENUMSPEC ...} into the appropriate enum value when passed as an argument to a foreign function.
     10319
     10320A list of symbols passed as an argument will be combined using @code{bitwise-ior}. An empty list will be passed as 0 (zero). Results of the enum type are automatically converted into a scheme value (note that combinations are not supported in this case).
     10321
     10322@code{TYPESPEC} maybe a TYPENAME symbol or a list of the form @code{(SCHEMENAME REALTYPE [DEFAULT-SCHEME-VALUE])}, where @code{REALTYPE} designates the native type used. The default type specification is @code{(TYPENAME TYPENAME)}. The @code{DEFAULT-SCHEME-VALUE} overrides the default result of mapping from the native type; i.e. when no such mapping exists. When supplied the form is used unquoted, otherwise the result is @code{'()}.
     10323
     10324@code{ENUMSPEC} is a TYPENAME symbol or a list of the form @code{(SCHEMENAME REALTYPE [SCHEME-VALUE])}, where @code{REALTYPE} designates the native type used. The default enum specification is @code{(TYPENAME TYPENAME)}. The @code{SCHEME-VALUE} overrides the result of mapping from the native type. When supplied the form is used unquoted, otherwise the @code{SCHEMENAME} symbol is returned.
     10325
     10326@code{USE-ALIASES} is an optional boolean flag that determines whether an alias or the @code{SCHEMENAME} is used as the defined foreign variable name. The default is @code{#t}.
     10327
     10328Additionally two procedures are defined named @code{SCHEMENAME->number} and @code{number->SCHEMENAME}. @code{SCHEMENAME->number} takes one argument and converts a symbol (or a list of symbols) into its numeric value.  @code{number->SCHEMENAME} takes one argument and converts a numeric value into its scheme value.
     10329
     10330Note that the specification of a scheme value override (@code{SCHEME-VALUE}) means the mapping may not be closed! @code{(number->SCHEMENAME (SCHEMENAME->number SCHEMENAME))} may not equal @code{SCHEMENAME}.
    986310331
    986410332Here a heavily contrived example:
    986510333
    9866 <enscript highlight=scheme>
    9867 
    9868 @enumerate
    9869 @item > enum foo @{ a_foo = 4, b_foo, c_foo @}; enum foo bar(enum foo x) @{ printf("%d\n", x); return b_foo; @} <#
    9870 
    9871 
    9872 @end enumerate
    9873 (define-foreign-enum (foo (enum "foo")) a_foo b_foo (c c_foo))
    9874 
    9875 (define bar (foreign-lambda foo bar foo))
    9876 
    9877 (pp (bar '())) (pp (bar 'a_foo)) (pp (bar '(b_foo c))) </enscript>
    9878 
     10334@example
     10335#>
     10336enum foo @{ a_foo = 4, b_foo, c_foo @}@emph{;
     10337}enum foo bar(enum foo x) @{ printf(@strong{"%d\n"}, x)@emph{; return b_foo; @}
     10338}<#
     10339
     10340(define-foreign-enum (foo (enum @strong{"foo"})) a_foo b_foo (c c_foo))
     10341
     10342(@strong{define} @strong{bar} (foreign-lambda foo bar foo))
     10343
     10344(pp (bar '()))
     10345(pp (bar 'a_foo))
     10346(pp (bar '(b_foo c)))
     10347@end example
    987910348@node Accessing external objects - foreign-lambda, Accessing external objects - foreign-lambda*, Accessing external objects - define-foreign-enum, Accessing external objects
    988010349@section foreign-lambda
     
    989510364Similar to @code{foreign-lambda}, but instead of generating code to call an external function, the body of the C procedure is directly given in @code{STRING ...}:
    989610365
    9897 <enscript highlight=scheme> (define my-strlen
    9898 
    9899 @verbatim
    9900  (foreign-lambda* int ((c-string str))
    9901    "int n = 0;
    9902     while(*(str++)) ++n;
    9903     C_return(n);") )
    9904 @end verbatim
    9905 (my-strlen "one two three")             ==> 13 </enscript>
    9906 
     10366@example
     10367(@strong{define} @strong{my-strlen}
     10368  (foreign-lambda* int ((c-string str))
     10369    @strong{"int n = 0;
     10370     while(*(str++)) ++n;
     10371     C_return(n);"}) )
     10372
     10373(my-strlen @strong{"one two three"})             =@strong{=>} 13
     10374@end example
    990710375For obscure technical reasons you should use the @code{C_return} macro instead of the normal @code{return} statement to return a result from the foreign lambda body as some cleanup code has to be run before execution commences in the calling code.
    990810376
     
    993410402This is also similar to @code{foreign-lambda*} but the code will be executed in a @emph{primitive} CPS context, which means it will not actually return, but call it's continuation on exit. This means that code inside this form may allocate Scheme data on the C stack (the @emph{nursery}) with @code{C_alloc} (see below). If the @code{RETURNTYPE} is omitted it defaults to @code{void}. You can return multiple values inside the body of the @code{foreign-primitive} form by calling this C function:
    993510403
    9936 <enscript highlight=scheme> C_values(N + 2, C_SCHEME_UNDEFINED, C_k, X1, ...) </enscript>
    9937 
     10404@example
     10405C_values(N + 2, C_SCHEME_UNDEFINED, C_k, X1, ...)
     10406@end example
    993810407where @code{N} is the number of values to be returned, and @code{X1, ...} are the results, which should be Scheme data objects. When returning multiple values, the return-type should be omitted.
    993910408
     
    996110430* Foreign type specifiers - c-pointer::
    996210431* Foreign type specifiers - nonnull-c-pointer::
    9963 * Foreign type specifiers - scheme-or-c-pointer::
    9964 * Foreign type specifiers - [nonnull-] blob::
    9965 * Foreign type specifiers - [nonnull-] u8vector [nonnull-] u16vector [nonnull-] u32vector [nonnull-] s8vector [nonnull-] s16vector [nonnull-] s32vector [nonnull-] f32vector [nonnull-] f64vector::
     10432* Foreign type specifiers - blob::
     10433* Foreign type specifiers - nonnull-blob::
     10434* Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector::
     10435* Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector::
    996610436* Foreign type specifiers - c-string::
    996710437* Foreign type specifiers - nonnull-c-string::
     
    997110441* Foreign type specifiers - c-string-list*::
    997210442* Foreign type specifiers - void::
    9973 * Foreign type specifiers - (const TYPE)::
    9974 * Foreign type specifiers - (enum NAME)::
    9975 * Foreign type specifiers - (pointer TYPE) (c-pointer TYPE)::
    9976 * Foreign type specifiers - (nonnull-pointer TYPE) (nonnull-c-pointer TYPE)::
    9977 * Foreign type specifiers - (ref TYPE)::
    9978 * Foreign type specifiers - (struct NAME)::
    9979 * Foreign type specifiers - (template TYPE ARGTYPE ...)::
    9980 * Foreign type specifiers - (union NAME)::
    9981 * Foreign type specifiers - (instance CNAME SCHEMECLASS)::
    9982 * Foreign type specifiers - (instance-ref CNAME SCHEMECLASS)::
    9983 * Foreign type specifiers - (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])::
     10443* Foreign type specifiers - ;const TYPE;::
     10444* Foreign type specifiers - ;enum NAME;::
     10445* Foreign type specifiers - ;c-pointer TYPE;::
     10446* Foreign type specifiers - ;nonnull-c-pointer TYPE;::
     10447* Foreign type specifiers - ;ref TYPE;::
     10448* Foreign type specifiers - ;struct NAME;::
     10449* Foreign type specifiers - ;template TYPE ARGTYPE ;;;;::
     10450* Foreign type specifiers - ;union NAME;::
     10451* Foreign type specifiers - ;instance CNAME SCHEMECLASS;::
     10452* Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;::
     10453* Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];::
    998410454* Foreign type specifiers - Mappings::
    998510455
     
    999910469
    1000010470
    10001 As argument: any value (@code{#f} is false, anything else is true). As result: anything different from 0 and the @code{NULL}-pointer is @code{#t}.
     10471As argument: any value (@code{#f} is false, anything else is true).
     10472
     10473As result: anything different from 0 and the @code{NULL} pointer is @code{#t}.
    1000210474
    1000310475@node Foreign type specifiers - byte unsigned-byte, Foreign type specifiers - char unsigned-char, Foreign type specifiers - bool, Foreign type specifiers
     
    1005310525
    1005410526
    10055 A symbol, which will be passed to foreign code as a zero-terminated string. When declared as the result of foreign code, the result should be a string and a symbol with the same name will be interned in the symbol table (and returned to the caller).
     10527A symbol, which will be passed to foreign code as a zero-terminated string.
     10528
     10529When declared as the result of foreign code, the result should be a string and a symbol with the same name will be interned in the symbol table (and returned to the caller).
    1005610530
    1005710531@node Foreign type specifiers - scheme-pointer, Foreign type specifiers - nonnull-scheme-pointer, Foreign type specifiers - symbol, Foreign type specifiers
     
    1005910533
    1006010534
    10061 An untyped pointer to the contents of a non-immediate Scheme object (not allowed as return type).  The value @code{#f} is also allowed and is passed as a @code{NULL} pointer.  Don't confuse this type with @code{(pointer ...)} which means something different (a machine-pointer object).
     10535An untyped pointer to the contents of a non-immediate Scheme object (not allowed as return type). The value @code{#f} is also allowed and is passed as a @code{NULL} pointer.
     10536
     10537Don't confuse this type with @code{(c-pointer ...)} which means something different (a machine-pointer object).
    1006210538
    1006310539@node Foreign type specifiers - nonnull-scheme-pointer, Foreign type specifiers - c-pointer, Foreign type specifiers - scheme-pointer, Foreign type specifiers
     
    1006510541
    1006610542
    10067 As @code{pointer}, but guaranteed not to be @code{#f}. Don't confuse this type with @code{(nonnull-pointer ...)} which means something different (a machine-pointer object).
     10543As @code{scheme-pointer}, but guaranteed not to be @code{#f}.
     10544
     10545Don't confuse this type with @code{(nonnull-c-pointer ...)} which means something different (a machine-pointer object).
    1006810546
    1006910547@node Foreign type specifiers - c-pointer, Foreign type specifiers - nonnull-c-pointer, Foreign type specifiers - nonnull-scheme-pointer, Foreign type specifiers
     
    1007110549
    1007210550
    10073 An untyped operating-system pointer or a locative.  The value @code{#f} is also allowed and is passed as a @code{NULL} pointer. If uses as the type of a return value, a @code{NULL} pointer will be returned as @code{#f}.
    10074 
    10075 @node Foreign type specifiers - nonnull-c-pointer, Foreign type specifiers - scheme-or-c-pointer, Foreign type specifiers - c-pointer, Foreign type specifiers
     10551An untyped operating-system pointer or a locative. The value @code{#f} is also allowed and is passed as a @code{NULL} pointer. If uses as the type of a return value, a @code{NULL} pointer will be returned as @code{#f}.
     10552
     10553@node Foreign type specifiers - nonnull-c-pointer, Foreign type specifiers - blob, Foreign type specifiers - c-pointer, Foreign type specifiers
    1007610554@section nonnull-c-pointer
    1007710555
     
    1007910557As @code{c-pointer}, but guaranteed not to be @code{#f/NULL}.
    1008010558
    10081 @node Foreign type specifiers - scheme-or-c-pointer, Foreign type specifiers - [nonnull-] blob, Foreign type specifiers - nonnull-c-pointer, Foreign type specifiers
    10082 @section scheme-or-c-pointer
    10083 
    10084 
    10085 An untyped pointer. If the argument is a machine-pointer object, the wrapped C pointer will be passed. If it is any other object, then this type is treated as @code{scheme-pointer}.
    10086 
    10087 Not allowed as a result type.
    10088 
    10089 @node Foreign type specifiers - [nonnull-] blob, Foreign type specifiers - [nonnull-] u8vector [nonnull-] u16vector [nonnull-] u32vector [nonnull-] s8vector [nonnull-] s16vector [nonnull-] s32vector [nonnull-] f32vector [nonnull-] f64vector, Foreign type specifiers - scheme-or-c-pointer, Foreign type specifiers
    10090 @section [nonnull-] blob
    10091 
    10092 
    10093 A blob object, passed as a pointer to its contents. Arguments of type @code{blob} may optionally be @code{#f}, which is passed as a NULL pointer.  This is not allowed as a return type.
    10094 
    10095 @node Foreign type specifiers - [nonnull-] u8vector [nonnull-] u16vector [nonnull-] u32vector [nonnull-] s8vector [nonnull-] s16vector [nonnull-] s32vector [nonnull-] f32vector [nonnull-] f64vector, Foreign type specifiers - c-string, Foreign type specifiers - [nonnull-] blob, Foreign type specifiers
    10096 @section [nonnull-] u8vector [nonnull-] u16vector [nonnull-] u32vector [nonnull-] s8vector [nonnull-] s16vector [nonnull-] s32vector [nonnull-] f32vector [nonnull-] f64vector
    10097 
    10098 
    10099 A SRFI-4 number-vector object, passed as a pointer to its contents. These type specifiers are not allowed as return types.
    10100 
    10101 @node Foreign type specifiers - c-string, Foreign type specifiers - nonnull-c-string, Foreign type specifiers - [nonnull-] u8vector [nonnull-] u16vector [nonnull-] u32vector [nonnull-] s8vector [nonnull-] s16vector [nonnull-] s32vector [nonnull-] f32vector [nonnull-] f64vector, Foreign type specifiers
     10559@node Foreign type specifiers - blob, Foreign type specifiers - nonnull-blob, Foreign type specifiers - nonnull-c-pointer, Foreign type specifiers
     10560@section blob
     10561
     10562
     10563A blob object, passed as a pointer to its contents. Arguments of type @code{blob} may optionally be @code{#f}, which is passed as a NULL pointer.
     10564
     10565This is not allowed as a return type.
     10566
     10567@node Foreign type specifiers - nonnull-blob, Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector, Foreign type specifiers - blob, Foreign type specifiers
     10568@section nonnull-blob
     10569
     10570
     10571As @code{blob}, but guaranteed not to be @code{#f}.
     10572
     10573@node Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector, Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector, Foreign type specifiers - nonnull-blob, Foreign type specifiers
     10574@section u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector
     10575
     10576
     10577A SRFI-4 number-vector object, passed as a pointer to its contents.
     10578
     10579These type specifiers are not allowed as return types.
     10580
     10581@node Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector, Foreign type specifiers - c-string, Foreign type specifiers - u8vector u16vector u32vector s8vector s16vector s32vector f32vector f64vector, Foreign type specifiers
     10582@section nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector
     10583
     10584
     10585As @code{u8vector ...}, but guaranteed not to be @code{#f}.
     10586
     10587@node Foreign type specifiers - c-string, Foreign type specifiers - nonnull-c-string, Foreign type specifiers - nonnull-u8vector nonnull-u16vector nonnull-u32vector nonnull-s8vector nonnull-s16vector nonnull-s32vector nonnull-f32vector nonnull-f64vector, Foreign type specifiers
    1010210588@section c-string
    1010310589
     
    1011510601
    1011610602
    10117 Similar to @code{[nonnull-]c-string}, but if used as a result-type, the pointer returned by the foreign code will be freed (using the C-libraries @code{free(1)}) after copying. This type specifier is not valid as a result type for callbacks defined with @code{define-external}.
     10603Similar to @code{[nonnull-] c-string}, but if used as a result-type, the pointer returned by the foreign code will be freed (using the C-libraries @code{free(1)}) after copying. This type specifier is not valid as a result type for callbacks defined with @code{define-external}.
    1011810604
    1011910605@node Foreign type specifiers - [nonnull-] unsigned-c-string[*], Foreign type specifiers - c-string-list, Foreign type specifiers - [nonnull-] c-string*, Foreign type specifiers
     
    1012710613
    1012810614
    10129 Expects a pointer to a list of C strings teminated by a @code{NULL} pointer and returns a list of strings. Only valid as a result type of non-callback functions.
     10615Expects a pointer to a list of C strings teminated by a @code{NULL} pointer and returns a list of strings.
     10616
     10617Only valid as a result type of non-callback functions.
    1013010618
    1013110619@node Foreign type specifiers - c-string-list*, Foreign type specifiers - void, Foreign type specifiers - c-string-list, Foreign type specifiers
     
    1013510623Similar to @code{c-string-list} but releases the storage of each string and the pointer array using @code{free(1)}.
    1013610624
    10137 @node Foreign type specifiers - void, Foreign type specifiers - (const TYPE), Foreign type specifiers - c-string-list*, Foreign type specifiers
     10625@node Foreign type specifiers - void, Foreign type specifiers - ;const TYPE;, Foreign type specifiers - c-string-list*, Foreign type specifiers
    1013810626@section void
    1013910627
    1014010628
    10141 Specifies an undefined return value. Not allowed as argument type.
    10142 
    10143 @node Foreign type specifiers - (const TYPE), Foreign type specifiers - (enum NAME), Foreign type specifiers - void, Foreign type specifiers
     10629Specifies an undefined return value.
     10630
     10631Not allowed as argument type.
     10632
     10633@node Foreign type specifiers - ;const TYPE;, Foreign type specifiers - ;enum NAME;, Foreign type specifiers - void, Foreign type specifiers
    1014410634@section (const TYPE)
    1014510635
     
    1014710637The foreign type @code{TYPE} with an additional @code{const} specifier.
    1014810638
    10149 @node Foreign type specifiers - (enum NAME), Foreign type specifiers - (pointer TYPE) (c-pointer TYPE), Foreign type specifiers - (const TYPE), Foreign type specifiers
     10639@node Foreign type specifiers - ;enum NAME;, Foreign type specifiers - ;c-pointer TYPE;, Foreign type specifiers - ;const TYPE;, Foreign type specifiers
    1015010640@section (enum NAME)
    1015110641
     
    1015310643An enumeration type. Handled internally as an @code{integer}.
    1015410644
    10155 @node Foreign type specifiers - (pointer TYPE) (c-pointer TYPE), Foreign type specifiers - (nonnull-pointer TYPE) (nonnull-c-pointer TYPE), Foreign type specifiers - (enum NAME), Foreign type specifiers
    10156 @section (pointer TYPE) (c-pointer TYPE)
     10645@node Foreign type specifiers - ;c-pointer TYPE;, Foreign type specifiers - ;nonnull-c-pointer TYPE;, Foreign type specifiers - ;enum NAME;, Foreign type specifiers
     10646@section (c-pointer TYPE)
    1015710647
    1015810648
    1015910649An operating-system pointer or a locative to an object of @code{TYPE}.
    1016010650
    10161 @node Foreign type specifiers - (nonnull-pointer TYPE) (nonnull-c-pointer TYPE), Foreign type specifiers - (ref TYPE), Foreign type specifiers - (pointer TYPE) (c-pointer TYPE), Foreign type specifiers
    10162 @section (nonnull-pointer TYPE) (nonnull-c-pointer TYPE)
    10163 
    10164 
    10165 As @code{(pointer TYPE)}, but guaranteed not to be @code{#f/NULL}.
    10166 
    10167 @node Foreign type specifiers - (ref TYPE), Foreign type specifiers - (struct NAME), Foreign type specifiers - (nonnull-pointer TYPE) (nonnull-c-pointer TYPE), Foreign type specifiers
     10651@node Foreign type specifiers - ;nonnull-c-pointer TYPE;, Foreign type specifiers - ;ref TYPE;, Foreign type specifiers - ;c-pointer TYPE;, Foreign type specifiers
     10652@section (nonnull-c-pointer TYPE)
     10653
     10654
     10655As @code{(c-pointer TYPE)}, but guaranteed not to be @code{#f/NULL}.
     10656
     10657@node Foreign type specifiers - ;ref TYPE;, Foreign type specifiers - ;struct NAME;, Foreign type specifiers - ;nonnull-c-pointer TYPE;, Foreign type specifiers
    1016810658@section (ref TYPE)
    1016910659
     
    1017110661A C++ reference type. Reference types are handled the same way as pointers inside Scheme code.
    1017210662
    10173 @node Foreign type specifiers - (struct NAME), Foreign type specifiers - (template TYPE ARGTYPE ...), Foreign type specifiers - (ref TYPE), Foreign type specifiers
     10663@node Foreign type specifiers - ;struct NAME;, Foreign type specifiers - ;template TYPE ARGTYPE ;;;;, Foreign type specifiers - ;ref TYPE;, Foreign type specifiers
    1017410664@section (struct NAME)
    1017510665
    1017610666
    10177 A struct of the name @code{NAME}, which should be a string. Structs can not be directly passed as arguments to foreign function, neither can they be result values. Pointers to structs are allowed, though.
    10178 
    10179 @node Foreign type specifiers - (template TYPE ARGTYPE ...), Foreign type specifiers - (union NAME), Foreign type specifiers - (struct NAME), Foreign type specifiers
     10667A struct of the name @code{NAME}, which should be a string.
     10668
     10669Structs cannot be directly passed as arguments to foreign function, neither can they be result values. Pointers to structs are allowed, though.
     10670
     10671@node Foreign type specifiers - ;template TYPE ARGTYPE ;;;;, Foreign type specifiers - ;union NAME;, Foreign type specifiers - ;struct NAME;, Foreign type specifiers
    1018010672@section (template TYPE ARGTYPE ...)
    1018110673
    1018210674
    10183 A C++ template type. For example @code{vector<int>} would be specified as @code{(template "vector" int)}. Template types can not be directly passed as arguments or returned as results.
    10184 
    10185 @node Foreign type specifiers - (union NAME), Foreign type specifiers - (instance CNAME SCHEMECLASS), Foreign type specifiers - (template TYPE ARGTYPE ...), Foreign type specifiers
     10675A C++ template type. For example @code{vector<int>} would be specified as @code{(template "vector" int)}.
     10676
     10677Template types cannot be directly passed as arguments or returned as results.
     10678
     10679@node Foreign type specifiers - ;union NAME;, Foreign type specifiers - ;instance CNAME SCHEMECLASS;, Foreign type specifiers - ;template TYPE ARGTYPE ;;;;, Foreign type specifiers
    1018610680@section (union NAME)
    1018710681
    1018810682
    10189 A union of the name @code{NAME}, which should be a string. Unions can not be directly passed as arguments to foreign function, neither can they be result values. Pointers to unions are allowed, though.
    10190 
    10191 @node Foreign type specifiers - (instance CNAME SCHEMECLASS), Foreign type specifiers - (instance-ref CNAME SCHEMECLASS), Foreign type specifiers - (union NAME), Foreign type specifiers
     10683A union of the name @code{NAME}, which should be a string.
     10684
     10685Unions cannot be directly passed as arguments to foreign function, neither can they be result values. Pointers to unions are allowed, though.
     10686
     10687@node Foreign type specifiers - ;instance CNAME SCHEMECLASS;, Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;, Foreign type specifiers - ;union NAME;, Foreign type specifiers
    1019210688@section (instance CNAME SCHEMECLASS)
    1019310689
     
    1019510691A pointer to a C++ class instance. @code{CNAME} should designate the name of the C++ class, and @code{SCHEMECLASS} should be the class that wraps the instance pointer. Normally @code{SCHEMECLASS} should be a subclass of @code{<c++-object>}.
    1019610692
    10197 @node Foreign type specifiers - (instance-ref CNAME SCHEMECLASS), Foreign type specifiers - (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV]), Foreign type specifiers - (instance CNAME SCHEMECLASS), Foreign type specifiers
     10693@node Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;, Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];, Foreign type specifiers - ;instance CNAME SCHEMECLASS;, Foreign type specifiers
    1019810694@section (instance-ref CNAME SCHEMECLASS)
    1019910695
     
    1020110697A reference to a C++ class instance.
    1020210698
    10203 @node Foreign type specifiers - (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV]), Foreign type specifiers - Mappings, Foreign type specifiers - (instance-ref CNAME SCHEMECLASS), Foreign type specifiers
     10699@node Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];, Foreign type specifiers - Mappings, Foreign type specifiers - ;instance-ref CNAME SCHEMECLASS;, Foreign type specifiers
    1020410700@section (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])
    1020510701
    1020610702
    10207 A function pointer. @code{CALLCONV} specifies an optional calling convention and should be a string. The meaning of this string is entirely platform dependent.  The value @code{#f} is also allowed and is passed as a @code{NULL} pointer.
    10208 
    10209 @node Foreign type specifiers - Mappings,  , Foreign type specifiers - (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV]), Foreign type specifiers
     10703A function pointer. @code{CALLCONV} specifies an optional calling convention and should be a string. The meaning of this string is entirely platform dependent. The value @code{#f} is also allowed and is passed as a @code{NULL} pointer.
     10704
     10705@node Foreign type specifiers - Mappings,  , Foreign type specifiers - ;function RESULTTYPE ;ARGUMENTTYPE1 ;;; [;;;]; [CALLCONV];, Foreign type specifiers
    1021010706@section Mappings
    1021110707
     
    1021310709Foreign types are mapped to C types in the following manner:
    1021410710
    10215 <table> <tr><td>bool</td><td> int </td></tr><tr><td>[unsigned-]char</td><td> [unsigned] char </td></tr><tr><td>[unsigned-]short</td><td> [unsigned] short </td></tr><tr><td>[unsigned-]int</td><td> [unsigned] int </td></tr><tr><td>[unsigned-]integer</td><td> [unsigned] int </td></tr><tr><td>[unsigned-]long</td><td> [unsigned] long </td></tr><tr><td>float</td><td> float </td></tr><tr><td>double</td><td> double </td></tr><tr><td>number</td><td> double </td></tr><tr><td>[nonnull-]pointer</td><td> void * </td></tr><tr><td>[nonnull-]c-pointer</td><td> void * </td></tr><tr><td>[nonnull-]blob</td><td> unsigned char * </td></tr><tr><td>[nonnull-]u8vector</td><td> unsigned char * </td></tr><tr><td>[nonnull-]s8vector</td><td> char * </td></tr><tr><td>[nonnull-]u16vector</td><td> unsigned short * </td></tr><tr><td>[nonnull-]s16vector</td><td> short * </td></tr><tr><td>[nonnull-]u32vector</td><td> uint32_t * </td></tr><tr><td>[nonnull-]s32vector</td><td> int32_t * </td></tr><tr><td>[nonnull-]f32vector</td><td> float * </td></tr><tr><td>[nonnull-]f64vector</td><td> double * </td></tr><tr><td>[nonnull-]c-string</td><td> char * </td></tr><tr><td>[nonnull-]unsigned-c-string</td><td> unsigned char * </td></tr> <tr><td>c-string-list</td><td>char **</td></tr> <tr><td>symbol</td><td> char * </td></tr><tr><td>void</td><td> void </td></tr><tr><td>([nonnull-]pointer TYPE)</td><td> TYPE * </td></tr><tr><td>(enum NAME)</td><td> enum NAME </td></tr><tr><td>(struct NAME)</td><td> struct NAME </td></tr><tr><td>(ref TYPE)</td><td> TYPE & </td></tr><tr><td>(template T1 T2 ...)</td><td> T1<T2, ...> </td></tr><tr><td>(union NAME)</td><td> union NAME </td></tr><tr><td>(function RTYPE (ATYPE ...) [CALLCONV])</td><td> [CALLCONV] RTYPE (*)(ATYPE, ...) </td></tr><tr><td>(instance CNAME SNAME)</td><td> CNAME * </td></tr><tr><td>(instance-ref CNAME SNAME)</td><td> CNAME & </td></tr></table>
     10711<table> <tr><td>bool</td><td> int </td></tr><tr><td>[unsigned-]char</td><td> [unsigned] char </td></tr><tr><td>[unsigned-]short</td><td> [unsigned] short </td></tr><tr><td>[unsigned-]int</td><td> [unsigned] int </td></tr><tr><td>[unsigned-]integer</td><td> [unsigned] int </td></tr><tr><td>[unsigned-]long</td><td> [unsigned] long </td></tr><tr><td>float</td><td> float </td></tr><tr><td>double</td><td> double </td></tr><tr><td>number</td><td> double </td></tr><tr><td>[nonnull-]c-pointer</td><td> void * </td></tr><tr><td>[nonnull-]blob</td><td> unsigned char * </td></tr><tr><td>[nonnull-]u8vector</td><td> unsigned char * </td></tr><tr><td>[nonnull-]s8vector</td><td> char * </td></tr><tr><td>[nonnull-]u16vector</td><td> unsigned short * </td></tr><tr><td>[nonnull-]s16vector</td><td> short * </td></tr><tr><td>[nonnull-]u32vector</td><td> uint32_t * </td></tr><tr><td>[nonnull-]s32vector</td><td> int32_t * </td></tr><tr><td>[nonnull-]f32vector</td><td> float * </td></tr><tr><td>[nonnull-]f64vector</td><td> double * </td></tr><tr><td>[nonnull-]c-string</td><td> char * </td></tr><tr><td>[nonnull-]unsigned-c-string</td><td> unsigned char * </td></tr> <tr><td>c-string-list</td><td>char **</td></tr> <tr><td>symbol</td><td> char * </td></tr><tr><td>void</td><td> void </td></tr><tr><td>([nonnull-]c-pointer TYPE)</td><td> TYPE * </td></tr><tr><td>(enum NAME)</td><td> enum NAME </td></tr><tr><td>(struct NAME)</td><td> struct NAME </td></tr><tr><td>(ref TYPE)</td><td> TYPE & </td></tr><tr><td>(template T1 T2 ...)</td><td> T1<T2, ...> </td></tr><tr><td>(union NAME)</td><td> union NAME </td></tr><tr><td>(function RTYPE (ATYPE ...) [CALLCONV])</td><td> [CALLCONV] RTYPE (*)(ATYPE, ...) </td></tr><tr><td>(instance CNAME SNAME)</td><td> CNAME * </td></tr><tr><td>(instance-ref CNAME SNAME)</td><td> CNAME & </td></tr></table>
    1021610712
    1021710713Previous: @ref{Accessing external objects, Accessing external objects}
     
    1040710903extern double baz(int);
    1040810904
    10409 int main() @{
     10905int main() {
    1041010906  char buffer[ 256 ];
    1041110907  int status;
     
    1044310939
    1044410940  return 0;
    10445 @}
     10941}
    1044610942
    1044710943% csc x.scm y.c -embedded
     
    1048710983
    1048810984int main()
    10489 @{
     10985{
    1049010986  C_word k = CHICKEN_run(C_toplevel);
    1049110987
     
    1049410990
    1049510991  return 0;
    10496 @}
     10992}
    1049710993
    1049810994% csc x.scm y.c -embedded
     
    1057711073* Callbacks - define-external::
    1057811074* Callbacks - C_callback::
    10579 * Callbacks - C_callback_adjust_stack_limits::
     11075* Callbacks - C_callback_adjust_stack::
    1058011076
    1058111077@end menu
     
    1059811094The first form defines an externally callable Scheme procedure. @code{NAME} should be a symbol, which, when converted to a string, represents a legal C identifier. @code{ARGUMENTTYPE1 ...} and @code{RETURNTYPE} are foreign type specifiers for the argument variables @code{VAR1 ...} and the result, respectively.  @code{QUALIFIERS} is an optional qualifier for the foreign procedure definition, like @code{__stdcall}.
    1059911095
    10600 <enscript highlight=scheme> (define-external (foo (c-string x)) int (string-length x)) </enscript>
    10601 
     11096@example
     11097(define-external (foo (c-string x)) int (string-length x))
     11098@end example
    1060211099The second form of @code{define-external} can be used to define variables that are accessible from foreign code. It declares a global variable named by the symbol @code{NAME} that has the type @code{TYPE}. @code{INIT} can be an arbitrary expression that is used to initialize the variable. @code{NAME} is accessible from Scheme just like any other foreign variable defined by @code{define-foreign-variable}. 
    1060311100
    10604 <enscript highlight=scheme> (define-external foo int 42) ((foreign-lambda* int ()
    10605 
    10606 @verbatim
    10607  "C_return(foo);"))           ==> 42
    10608 @end verbatim
    10609 </enscript>
    10610 
     11101@example
     11102(define-external foo int 42)
     11103((foreign-lambda* int ()
     11104  @strong{"C_return(foo);"}))           =@strong{=>} 42
     11105@end example
    1061111106@b{Note:} don't be tempted to assign strings or bytevectors to external variables. Garbage collection moves those objects around, so it is very bad idea to assign pointers to heap-data. If you have to do so, then copy the data object into statically allocated memory (for example by using @code{object-evict}).
    1061211107
    1061311108Results of type @code{scheme-object} returned by @code{define-external} are always allocated in the secondary heap, that is, not in the stack.
    1061411109
    10615 @node Callbacks - C_callback, Callbacks - C_callback_adjust_stack_limits, Callbacks - define-external, Callbacks
     11110@node Callbacks - C_callback, Callbacks - C_callback_adjust_stack, Callbacks - define-external, Callbacks
    1061611111@section C_callback
    1061711112
     
    1062211117This function can be used to invoke the Scheme procedure @code{closure}. @code{argc} should contain the number of arguments that are passed to the procedure on the temporary stack. Values are put onto the temporary stack with the @code{C_save} macro.
    1062311118
    10624 @node Callbacks - C_callback_adjust_stack_limits,  , Callbacks - C_callback, Callbacks
    10625 @section C_callback_adjust_stack_limits
    10626 
    10627 
    10628 @verbatim
    10629 [C function] void C_callback_adjust_stack_limits (C_word *ptr)
    10630 @end verbatim
    10631 The runtime-system uses the stack as a special allocation area and internally holds pointers to estimated limits to distinguish between Scheme data objects inside the stack from objects outside of it. If you invoke callbacks at wildly differing stack-levels, these limits may shift from invocation to invocation. Callbacks defined with @code{define-external} will perform appropriate adjustments automatically, but if you invoke @code{C_callback} manually, you should perform a @code{C_callback_adjust_stack_limits} to make sure the internal limits are set properly. @code{ptr} should point to some data object on the stack. The call will make sure the limits are adjusted so that the value pointed to by @code{ptr} is located in the stack.
     11119@node Callbacks - C_callback_adjust_stack,  , Callbacks - C_callback, Callbacks
     11120@section C_callback_adjust_stack
     11121
     11122
     11123@verbatim
     11124[C function] void C_callback_adjust_stack (C_word *ptr, int size)
     11125@end verbatim
     11126The runtime-system uses the stack as a special allocation area and internally holds pointers to estimated limits to distinguish between Scheme data objects inside the stack from objects outside of it.  If you invoke callbacks at wildly differing stack-levels, these limits may shift from invocation to invocation. Callbacks defined with @code{define-external} will perform appropriate adjustments automatically, but if you invoke @code{C_callback} manually, you should perform a @code{C_callback_adjust_stack} to make sure the internal limits are set properly. @code{ptr} should point to some data object on the stack and @code{size} is the number of words contained in the data object (or some estimate). The call will make sure the limits are adjusted so that the value pointed to by @code{ptr} is located in the stack.
    1063211127
    1063311128Previous: @ref{Embedding, Embedding}
     
    1068811183Note that @code{(location X)} may be abbreviated as @code{#$X}.
    1068911184
    10690 <enscript highlight=scheme> (define-external foo int) ((foreign-lambda* void (((pointer int) ip)) "*ip = 123;")
    10691 
    10692 @verbatim
    10693  (location foo))
    10694 @end verbatim
    10695 foo                                                                               ==> 123 </enscript>
    10696 
     11185@example
     11186(define-external foo int)
     11187((foreign-lambda* void (((c-pointer int) ip)) @strong{"*ip = 123;"})
     11188  (location foo))
     11189foo                                                                               =@strong{=>} 123
     11190@end example
    1069711191This facility is especially useful in situations, where a C function returns more than one result value:
    1069811192
    10699 <enscript highlight=scheme>
    10700 
    10701 @enumerate
    10702 @item >
    10703 
    10704 @item include <math.h> <#
    10705 
    10706 
    10707 @end enumerate
    10708 (define modf
    10709 
    10710 @verbatim
    10711  (foreign-lambda double "modf" double (pointer double)) )
    10712 @end verbatim
     11193@example
     11194#>
     11195#include <math.h>
     11196<#
     11197
     11198(@strong{define} @strong{modf}
     11199  (foreign-lambda double @strong{"modf"} double (c-pointer double)) )
     11200
    1071311201(let-location ([i double])
    10714 
    10715 @verbatim
    10716  (let ([f (modf 1.99 (location i))])
    10717    (print "i=" i ", f=" f) ) )
    10718 @end verbatim
    10719 </enscript>
     11202  (@strong{let} ([f (modf 1.99 (location i))])
     11203    (print @strong{"i="} i @strong{", f="} f) ) )
     11204@end example
     11205See @uref{http://chicken.wiki.br/location-and-c-string-star, location and c-string*}  for a tip on returning a @code{c-string*} type.
    1072011206
    1072111207@code{location} returns a value of type @code{c-pointer}, when given the name of a callback-procedure defined with @code{define-external}.
     
    1079611282* C interface - C_gc_protect::
    1079711283* C interface - C_gc_unprotect::
     11284* C interface - C_pre_gc_hook::
    1079811285* C interface - C_post_gc_hook::
     11286* C interface - An example for simple calls to foreign code involving callbacks::
     11287* C interface - Notes;::
    1079911288
    1080011289@end menu
     
    1114511634For a slightly simpler interface to creating and using GC roots see @code{CHICKEN_new_gc_root}.
    1114611635
    11147 @node C interface - C_gc_unprotect, C interface - C_post_gc_hook, C interface - C_gc_protect, C interface
     11636@node C interface - C_gc_unprotect, C interface - C_pre_gc_hook, C interface - C_gc_protect, C interface
    1114811637@section C_gc_unprotect
    1114911638
     
    1115411643Removes the last @code{n} registered variables from the set of root variables.
    1115511644
    11156 @node C interface - C_post_gc_hook,  , C interface - C_gc_unprotect, C interface
     11645@node C interface - C_pre_gc_hook, C interface - C_post_gc_hook, C interface - C_gc_unprotect, C interface
     11646@section C_pre_gc_hook
     11647
     11648
     11649@verbatim
     11650[C Variable] void (*C_pre_gc_hook)(int mode)
     11651@end verbatim
     11652If not @code{NULL}, the function pointed to by this variable will be called before each garbage collection with a flag indicating what kind of collection was performed (either @code{0} for a minor collection or @code{2} for a resizing collection). A "resizing" collection means a secondary collection that moves all live data into a enlarged (or shrinked) heap-space. Minor collections happen very frequently, so the hook function should not consume too much time. The hook function may not invoke Scheme callbacks.
     11653
     11654Note that resizing collections may be nested in normal major collections.
     11655
     11656@node C interface - C_post_gc_hook, C interface - An example for simple calls to foreign code involving callbacks, C interface - C_pre_gc_hook, C interface
    1115711657@section C_post_gc_hook
    1115811658
    1115911659
    1116011660@verbatim
    11161 [C Variable] void (*C_post_gc_hook)(int mode)
    11162 @end verbatim
    11163 If not @code{NULL}, the function pointed to by this variable will be called after each garbage collection with a flag indicating what kind of collection was performed (either @code{0} for a minor collection or @code{1} for a major collection). Minor collections happen very frequently, so the hook function should not consume too much time. The hook function may not invoke Scheme callbacks.
    11164 
    11165 An example:
     11661[C Variable] void (*C_post_gc_hook)(int mode, long ms)
     11662@end verbatim
     11663If not @code{NULL}, the function pointed to by this variable will be called after each garbage collection with a flag indicating what kind of collection was performed (either @code{0} for a minor collection, @code{1} for a major collection or @code{2} for a resizing collection). Minor collections happen very frequently, so the hook function should not consume too much time. The hook function may not invoke Scheme callbacks. The @code{ms} argument records the number of milliseconds required for the garbage collection, if the collection was a major one. For minor collections the value of the @code{ms} argument is undefined.
     11664
     11665@node C interface - An example for simple calls to foreign code involving callbacks, C interface - Notes;, C interface - C_post_gc_hook, C interface
     11666@section An example for simple calls to foreign code involving callbacks
     11667
    1116611668
    1116711669@verbatim
     
    1119311695@verbatim
    1119411696int callout(int x, int y, int z)
    11195 @{
     11697{
    1119611698  C_word *ptr = C_alloc(C_SIZEOF_LIST(3));
    1119711699  C_word lst;
     
    1120111703  lst = C_list(&ptr, 3, C_fix(x), C_fix(y), C_fix(z));
    1120211704  return callin(lst);  /* Note: `callin' will have GC'd the data in `ptr' */
    11203 @}
     11705}
    1120411706@end verbatim
    1120511707@verbatim
     
    1121011712123
    1121111713@end verbatim
    11212 @b{Notes:}
     11714@node C interface - Notes;,  , C interface - An example for simple calls to foreign code involving callbacks, C interface
     11715@section Notes:
     11716
    1121311717
    1121411718Scheme procedures can call C functions, and C functions can call Scheme procedures, but for every pending C stack frame, the available size of the first heap generation (the @emph{nursery}) will be decreased, because the C stack is identical to the nursery. On systems with a small nursery this might result in thrashing, since the C code between the invocation of C from Scheme and the actual calling back to Scheme might build up several stack-frames or allocates large amounts of stack data. To prevent this it is advisable to increase the default nursery size, either when compiling the file (using the @code{-nursery} option) or when running the executable (using the @code{-:s} runtime option).
     
    1124011744* chicken-setup - Windows notes::
    1124111745* chicken-setup - Security::
    11242 * chicken-setup - Other modes if installation::
     11746* chicken-setup - Other modes of installation::
    1124311747* chicken-setup - Linking extensions statically::
    1124411748
     
    1129911803* chicken-setup - Procedures and macros available in setup scripts - required-extension-version::
    1130011804* chicken-setup - Procedures and macros available in setup scripts - cross-chicken::
     11805* chicken-setup - Procedures and macros available in setup scripts - host-extension::
    1130111806
    1130211807@end menu
     
    1132611831@code{FILELIST} may be a filename, a list of filenames, or a list of pairs of the form @code{(SOURCE DEST)} (if you want to copy into a particular sub-directory - the destination directory will be created as needed). If @code{DEST} is a relative pathname, < it will be copied into the extension repository.
    1132711832
    11328 The optional argument @code{INFOLIST} should be an association list that maps symbols to values, this list will be stored as @code{ID.setup} at the same location as the extension code. Currently the following properties are used:
     11833The optional argument @code{INFOLIST} should be an association list that maps symbols to values, this list will be stored as @code{ID.setup-info} at the same location as the extension code. Currently the following properties are used:
    1132911834
    1133011835@node chicken-setup - Procedures and macros available in setup scripts - install-extension - syntax, chicken-setup - Procedures and macros available in setup scripts - install-extension - require-at-runtime,  , chicken-setup - Procedures and macros available in setup scripts - install-extension
     
    1137111876[extension property] (examples FILENAME ...)
    1137211877@end verbatim
    11373 Copies the given files into the examples directory, which is usually  @code{$prefix/share/chicken/examples} (equivalent to @code{$CHICKEN_HOME/examples} or @code{(make-pathname (chicken-home) "examples")}).
     11878Copies the given files into the examples directory, which is usually  @code{$prefix/share/chicken/examples} or @code{(make-pathname (chicken-home) "examples")}).
    1137411879
    1137511880Note that the files listed in this property should not be listed in the normal list of files to install passed to @code{install-extension}. This is the only exception - other files that are installed in the repository must be given in the file list.
     
    1153712042[parameter] (program-path [PATH])
    1153812043@end verbatim
    11539 Holds the path where executables are installed and defaults to either @code{$CHICKEN_PREFIX/bin}, if the environment variable @code{CHICKEN_PREFIX} is set, @code{$CHICKEN_HOME} or the path where the CHICKEN binaries (@code{chicken}, @code{csi}, etc.) are installed.
     12044Holds the path where executables are installed and defaults to either @code{$CHICKEN_PREFIX/bin}, if the environment variable @code{CHICKEN_PREFIX} is set or the path where the CHICKEN binaries (@code{chicken}, @code{csi}, etc.) are installed.
    1154012045
    1154112046@node chicken-setup - Procedures and macros available in setup scripts - setup-root-directory, chicken-setup - Procedures and macros available in setup scripts - setup-build-directory, chicken-setup - Procedures and macros available in setup scripts - program-path, chicken-setup - Procedures and macros available in setup scripts
     
    1159312098Checks whether the extensions @code{EXTENSION1 ...} are installed and at least of version @code{VERSION1 ...}. The test is made by lexicographically comparing the string-representations of the given version with the version  of the installed extension. If one of the listed extensions is not installed, has no associated version information or is of a version older than the one specified.
    1159412099
    11595 @node chicken-setup - Procedures and macros available in setup scripts - cross-chicken,  , chicken-setup - Procedures and macros available in setup scripts - required-extension-version, chicken-setup - Procedures and macros available in setup scripts
     12100@node chicken-setup - Procedures and macros available in setup scripts - cross-chicken, chicken-setup - Procedures and macros available in setup scripts - host-extension, chicken-setup - Procedures and macros available in setup scripts - required-extension-version, chicken-setup - Procedures and macros available in setup scripts
    1159612101@subsection cross-chicken
    1159712102
     
    1160012105[procedure] (cross-chicken)
    1160112106@end verbatim
    11602 Retrusn @code{#t} if this system is configured for cross-compilation or @code{#f} otherwise.
     12107Returns @code{#t} if this system is configured for cross-compilation or @code{#f} otherwise.
     12108
     12109@node chicken-setup - Procedures and macros available in setup scripts - host-extension,  , chicken-setup - Procedures and macros available in setup scripts - cross-chicken, chicken-setup - Procedures and macros available in setup scripts
     12110@subsection host-extension
     12111
     12112
     12113@verbatim
     12114[parameter] host-extension
     12115@end verbatim
     12116For a cross-compiling CHICKEN, when compiling an extension, then it should be built for the host environment (as opposed to the target environment). This parameter is controlled by the @code{-host-extension} command-line option. A setup script should perform the proper steps of compiling any code by passing @code{-host} when invoking @code{csc} or using the @code{compile} macro.
    1160312117
    1160412118@node chicken-setup - Examples for extensions, chicken-setup - chicken-setup reference, chicken-setup - Procedures and macros available in setup scripts, chicken-setup
     
    1160812122The simplest case is a single file that does not export any syntax. For example
    1160912123
    11610 <enscript highlight=scheme> ;;;; hello.scm
    11611 
    11612 (define (hello name)
    11613 
    11614 @verbatim
    11615  (print "Hello, " name " !") )
    11616 @end verbatim
    11617 </enscript>
    11618 
     12124@example
     12125@emph{;;;; hello.scm
     12126}
     12127(@strong{define} (@strong{hello} name)
     12128  (print @strong{"Hello, "} name @strong{" !"}) )
     12129@end example
    1161912130We need a @code{.setup} script to build and install our nifty extension:
    1162012131
    11621 <enscript highlight=scheme> ;;;; hello.setup
    11622 
    11623 @table @b
    11624 @item ; compile the code into a dynamically loadable shared object
    11625 
    11626 
    11627 @item ; (will generate hello.so)
    11628 
    11629 
    11630 
    11631 @end table
    11632 (compile -s hello.scm)
    11633 
    11634 @table @b
    11635 @item ; Install as extension library
    11636 
    11637 
    11638 
    11639 @end table
    11640 (install-extension 'hello "hello.so") </enscript>
    11641 
     12132@example
     12133@emph{;;;; hello.setup
     12134}
     12135@emph{;; compile the code into a dynamically loadable shared object
     12136}@emph{;; (will generate hello.so)
     12137}(compile -s hello.scm)
     12138
     12139@emph{;; Install as extension library
     12140}(install-extension 'hello @strong{"hello.so"})
     12141@end example
    1164212142After entering
    1164312143
     
    1165912159Here we create a simple application:
    1166012160
    11661 <enscript highlight=scheme> ;;;; hello2.scm
    11662 
    11663 (print "Hello, ") (for-each (lambda (x) (printf "~A " x)) (command-line-arguments)) (print "!") </enscript>
    11664 
     12161@example
     12162@emph{;;;; hello2.scm
     12163}
     12164(print @strong{"Hello, "})
     12165(for-each (@strong{lambda} (x) (printf @strong{"~A "} x)) (command-line-arguments))
     12166(print @strong{"!"})
     12167@end example
    1166512168We also need a setup script:
    1166612169
    11667 <enscript highlight=scheme> ;;;; hello2.setup
    11668 
    11669 (compile hello2.scm)  ; compile `hello2' (install-program 'hello2 "hello2") ; name of the extension and files to be installed </enscript>
    11670 
     12170@example
     12171@emph{;;;; hello2.setup
     12172}
     12173(compile hello2.scm)  @emph{; compile `hello2'
     12174}(install-program 'hello2 @strong{"hello2"}) @emph{; name of the extension and files to be installed
     12175}@end example
    1167112176To use it, just run @code{chicken-setup} in the same directory:
    1167212177
     
    1168912194Finally a somewhat more complex example: We want to package a syntax extension with additional support code that is to be loaded at run-time of any Scheme code that uses that extension. We create a @emph{glass} lambda, a procedure with free variables that can be manipulated from outside:
    1169012195
    11691 <enscript highlight=scheme> ;;;; glass.scm
    11692 
     12196@example
     12197@emph{;;;; glass.scm
     12198}
    1169312199(define-macro (glass-lambda llist vars . body)
    11694 
    11695 @verbatim
    11696  ;; Low-level macros are fun!
    11697  (let ([lvar (gensym)]
    11698 @end verbatim
    11699         [svar (gensym)]         [x (gensym)]    [y (gensym)]    [yn (gensym)] )
    11700 
    11701 @verbatim
    11702    `(let ,(map (lambda (v) (list v #f)) vars)
    11703       (define (,svar ,x . ,y)
    11704 @end verbatim
    11705          (let* ([,yn (pair? ,y)]                [,y (and ,yn (car ,y))] )          (case ,x          ,@@(map (lambda (v)                      `([,v] (if ,yn                             (set! ,v ,y)                            ,v) ) )                    vars)            (else (error "variable not found" ,x)) ) ) )
    11706 
    11707 @verbatim
    11708       (define ,lvar (lambda ,llist ,@@body))
    11709       (extend-procedure ,lvar ,svar) ) ) )
    11710 @end verbatim
    11711 </enscript>
    11712 
     12200  @emph{;; Low-level macros are fun!
     12201}  (@strong{let} ([lvar (gensym)]
     12202        [svar (gensym)]
     12203        [x (gensym)]
     12204        [y (gensym)]
     12205        [yn (gensym)] )
     12206    `(@strong{let} ,(map (@strong{lambda} (v) (list v #f)) vars)
     12207       (@strong{define} (,svar ,x . ,y)
     12208         (@strong{let*} ([,yn (pair? ,y)]
     12209                [,y (@strong{and} ,yn (car ,y))] )
     12210           (@strong{case} ,x
     12211             ,@@(map (@strong{lambda} (v)
     12212                      `([,v] (@strong{if} ,yn
     12213                                 (@strong{set!} ,v ,y)
     12214                                 ,v) ) )
     12215                    vars)
     12216             (@strong{else} (error @strong{"variable not found"} ,x)) ) ) )
     12217       (@strong{define} ,lvar (@strong{lambda} ,llist ,@@body))
     12218       (extend-procedure ,lvar ,svar) ) ) )
     12219@end example
    1171312220Here some support code that needs to be loaded at runtime:
    1171412221
    11715 <enscript highlight=scheme> ;;;; glass-support.scm
    11716 
     12222@example
     12223@emph{;;;; glass-support.scm
     12224}
    1171712225(require-extension lolevel)
    1171812226
    11719 (define glass-lambda-accessor procedure-data) (define (glass-lambda-ref gl v) ((procedure-data gl) v)) (define (glass-lambda-set! gl v x) ((procedure-data gl) v x)) </enscript>
    11720 
     12227(@strong{define} @strong{glass-lambda-accessor} procedure-data)
     12228(@strong{define} (@strong{glass-lambda-ref} gl v) ((procedure-data gl) v))
     12229(@strong{define} (@strong{glass-lambda-set!} gl v x) ((procedure-data gl) v x))
     12230@end example
    1172112231The setup script looks like this:
    1172212232
    11723 <enscript highlight=scheme> (compile -s glass-support.scm)
     12233@example
     12234(compile -s glass-support.scm)
    1172412235
    1172512236(install-extension
    11726 
    11727 @verbatim
    11728  'glass
    11729  '("glass.scm" "glass-support.so")
    11730  '((syntax) (require-at-runtime glass-support)) )
    11731 @end verbatim
    11732 </enscript>
    11733 
     12237  'glass
     12238  '(@strong{"glass.scm"} @strong{"glass-support.so"})
     12239  '((syntax) (require-at-runtime glass-support)) )
     12240@end example
    1173412241The invocation of @code{install-extension} provides the files that are to be copied into the extension repository, and a metadata list that specifies that the extension @code{glass} is a syntax extension and that, if it is declared to be used by other code (either with the @code{require-extension} or @code{require-for-syntax} form), then client code should perform an implicit @code{(require 'glass-support)} at startup.
    1173512242
     
    1178812295@item @code{-e  -eval EXPRESSION}
    1178912296
    11790 Evaluates the given expression(s).
     12297Evaluates the given expression(s)
    1179112298@item @code{-v  -verbose}
    1179212299
    11793 Display additional debug information.
     12300Display additional debug information
    1179412301@item @code{-k  -keep}
    1179512302
    11796 Keep temporary files and directories.
     12303Keep temporary files and directories
    1179712304@item @code{-c  -csc-option OPTION}
    1179812305
    11799 Passes @code{OPTION} as an extra argument to invocations of the compiler-driver (@code{csc}). This works only if @code{csc} is invoked as @code{(run (csc ...))}.
     12306Passes @code{OPTION} as an extra argument to invocations of the compiler-driver (@code{csc}); this works only if @code{csc} is invoked as @code{(run (csc ...))}
    1180012307@item @code{-d  -dont-ask}
    1180112308
    11802 Do not ask the user before trying to download required extensions.
     12309Do not ask the user before trying to download required extensions
    1180312310@item @code{-n  -no-install}
    1180412311
    11805 Do not install generated binaries and/or support files. Any invocations of @code{install-program}, @code{install-extension} or @code{install-script} will be be no-ops.
     12312Do not install generated binaries and/or support files; any invocations of @code{install-program}, @code{install-extension} or @code{install-script} will be be no-ops
    1180612313@item @code{-i  -docindex}
    1180712314
    11808 Displays the path to the index-page of any installed extension-documentation. If the index page does not exist, it is created.
     12315Displays the path to the index-page of any installed extension-documentation; if the index page does not exist, it is created
    1180912316@item @code{-t  -test EXTENSION ...}
    1181012317
     
    1181612323
    1181712324Download and print the repository catalog
     12325@item @code{-create-tree DIRECTORY}
     12326
     12327Create a fresh, minimal repository catalog and writes it to stdout
    1181812328@item @code{-t  -test}
    1181912329
    11820 If the extension sources contain a directory named @code{tests} and this directory includes a file named @code{run.scm} then this file is executed (with @code{tests} being the current working directory).
     12330If the extension sources contain a directory named @code{tests} and this directory includes a file named @code{run.scm} then this file is executed (with @code{tests} being the current working directory)
    1182112331@item @code{-tree FILENAME}
    1182212332
     
    1183412344
    1183512345Specify alternative installation prefix (for packaging)
     12346@item @code{-host-extension}
     12347
     12348Compile extension in "host" mode (sets the parameter @code{host-extension} to @code{#f})
    1183612349@item @code{--}
    1183712350
    11838 Ignore all following arguments.
     12351Ignore all following arguments
    1183912352
    1184012353@end table
     
    1184512358
    1184612359
    11847 @code{chicken-setup} works on Windows, when compiled with Visual C++, but depends on the @code{tar} and @code{gunzip} tools to extract the contents of an egg. The best way is to download an egg either manually (or with @code{chicken-setup -fetch}) and extract its contents with a separate program (like @code{winzip}). the @code{CHICKEN_REPOSITORY} environment variable has to be set (in addition to @code{CHICKEN_HOME}) to a directory where your compiled extensions should be located.
     12360@code{chicken-setup} works on Windows, when compiled with Visual C++, but depends on the @code{tar} and @code{gunzip} tools to extract the contents of an egg. The best way is to download an egg either manually (or with @code{chicken-setup -fetch}) and extract its contents with a separate program (like @code{winzip}). the @code{CHICKEN_REPOSITORY} environment variable has to be set to a directory where your compiled extensions should be located.
    1184812361
    1184912362The @code{.setup} scripts will not always work under Windows, and the extensions may require libraries that are not provided for Windows or work differently. Under these circumstances it is recommended to perform the required steps to build an extension manually.
     
    1185112364The required UNIX tools are also available as Windows binaries. Google or ask on the CHICKEN mailing list if you need help locating them.
    1185212365
    11853 @node chicken-setup - Security, chicken-setup - Other modes if installation, chicken-setup - Windows notes, chicken-setup
     12366@node chicken-setup - Security, chicken-setup - Other modes of installation, chicken-setup - Windows notes, chicken-setup
    1185412367@section Security
    1185512368
     
    1185912372Security-conscious users should never run @code{chicken-setup} as root. A simple remedy is to set the environment variable @code{CHICKEN_REPOSITORY}, which will transparently place the repository at an arbitrary user-selected location. Alternatively obtain write/execute access to the default location of the repository (usually @code{/usr/local/lib/chicken}) to avoid running as root.
    1186012373
    11861 @node chicken-setup - Other modes if installation, chicken-setup - Linking extensions statically, chicken-setup - Security, chicken-setup
    11862 @section Other modes if installation
    11863 
    11864 
    11865 It is possible to install extensions directly from a @uref{http://subversion.tigris.org, Subversion} repository or from a local checkout by using the @code{-svn} or @code{-local} options. By using either the @code{svn} client program (which must be installed) or file-system operations all necessary files will be copied into the current directory (creating a subdirectory named @code{EXTENSIONNAME.egg-dir}), built and subsequently installed.
    11866 
    11867 Dependency information which is necessary to ensure required extensions are also installed is downloaded automatically.  If you have no internet connection or don't want to connect, you can als use a local file containing the necessary dependency information.  The @code{-fetch-tree} option retrieves the canonical @emph{repository file} at @uref{http://www.call-with-current-continuation.org/eggs/repository, http://www.call-with-current-continuation.org/eggs/repository}, writing it to stdout. Redirecting this output into a file and passing the file via the @code{-tree} option to @code{chicken-setup} allows you now to use the local repository file:
     12374@node chicken-setup - Other modes of installation, chicken-setup - Linking extensions statically, chicken-setup - Security, chicken-setup
     12375@section Other modes of installation
     12376
     12377
     12378It is possible to install extensions directly from a @uref{http://subversion.tigris.org, Subversion} repository or from a local checkout by using the @code{-svn} or @code{-local} options. By using either the @code{svn} client program (which must be installed) or file-system operations, all necessary files will be copied into the current directory (creating a subdirectory named @code{EXTENSIONNAME.egg-dir}), built and subsequently installed.
     12379
     12380Dependency information, which is necessary to ensure required extensions are also installed, is downloaded automatically.  If you have no internet connection or don't want to connect, you can also use a local file containing the necessary dependency information.  The @code{-fetch-tree} option retrieves the canonical @emph{repository file} at @uref{http://www.call-with-current-continuation.org/eggs/repository, http://www.call-with-current-continuation.org/eggs/repository}, writing it to stdout. Redirecting this output into a file and passing the file via the @code{-tree} option to @code{chicken-setup} allows you now to use the local repository file:
    1186812381
    1186912382Retrieve complete extension repository (big):
     
    1187112384@verbatim
    1187212385% cd /opt
    11873 % svn co @uref{https://galinha.ucpel.tche.br/svn/chicken-eggs, https://galinha.ucpel.tche.br/svn/chicken-eggs}
     12386% svn co uref{https://galinha.ucpel.tche.br/svn/chicken-eggs/release/3, https://galinha.ucpel.tche.br/svn/chicken-eggs/release/3} eggs
    1187412387@end verbatim
    1187512388Get your own copy of the repository file:
     
    1188212395@verbatim
    1188312396% cd ~/tmp
    11884 % chicken-setup -local /opt/eggs/chicken-eggs -tree ~/my-repository-file opengl
    11885 @end verbatim
    11886 @node chicken-setup - Linking extensions statically,  , chicken-setup - Other modes if installation, chicken-setup
     12397% chicken-setup -local /opt/eggs -tree ~/my-repository-file opengl
     12398@end verbatim
     12399@node chicken-setup - Linking extensions statically,  , chicken-setup - Other modes of installation, chicken-setup
    1188712400@section Linking extensions statically
    1188812401
     
    1189012403The compiler and @ref{chicken-setup, chicken-setup} support statically linked  eggs. The general approach is to generate an object file or static library (in addition to the usual shared library) in your @code{.setup} script and install it along with the dynamically loadable extension. The setup properties @code{static}  should contain the name of the object file (or static library) to be linked, when @code{csc} gets passed the @code{-static-extensions} option:
    1189112404
    11892 <enscript highlight=scheme> (compile -s -O2 -d1 my-ext.scm)   ; dynamically loadable "normal" version (compile -c -O2 -d1 my-ext -unit my-ext)  ; statically linkable version (install-extension
    11893 
    11894 @verbatim
    11895  'my-ext
    11896  '("my-ext.so" "my-ext.o")
    11897  '((static "my-ext.o")) )
    11898 @end verbatim
    11899 </enscript>
    11900 
     12405@example
     12406(compile -s -O2 -d1 my-ext.scm)   @emph{; dynamically loadable "normal" version
     12407}(compile -c -O2 -d1 my-ext -unit my-ext)  @emph{; statically linkable version
     12408}(install-extension
     12409  'my-ext
     12410  '(@strong{"my-ext.so"} @strong{"my-ext.o"})
     12411  '((static @strong{"my-ext.o"})) )
     12412@end example
    1190112413Note the use of the @code{-unit} option in the second compilation step: static linking must use static library units. @code{chicken-setup} will perform  platform-dependent file-extension translation for the file list, but does currently not do that for the @code{static} extension property.
    1190212414
     
    1194012452@b{other values}: the empty list, the value of unbound identifiers, the undefined value (void), and end-of-file.  Bits 1-4 are equal to @code{C_SPECIAL_BITS}; bits 5 to 8 contain an identifying number for this type of object.  The following constants are defined: @code{C_SCHEME_END_OF_LIST C_SCHEME_UNDEFINED C_SCHEME_UNBOUND C_SCHEME_END_OF_FILE}
    1194112453
    11942 Collectively, bits 1 and 2 are known as the @emph{immediate mark bits}.  When bit 1 is set, the object is a fixnum, as described above.  When bit 2 is set, it is an immediate object other than a fixnum.  If neither is set, the object is non-immediate, as described below.  (By definition, bits 1 and 2 may not both be set.)
     12454Collectively, bits 1 and 2 are known as the @emph{immediate mark bits}.  When bit 1 is set, the object is a fixnum, as described above, and bit 2 is part of its value.  When bit 1 is clear but bit 2 is set, it is an immediate object other than a fixnum.  If neither bit 1 nor bit 2 is set, the object is non-immediate, as described below.
    1194312455
    1194412456@node Data representation - Non-immediate objects,  , Data representation - Immediate objects, Data representation
     
    1205312565* FAQ - General - How can I specialize a generic function method to match instances of every class?::
    1205412566* FAQ - General - Does CHICKEN support native threads?::
     12567* FAQ - General - Does CHICKEN support Unicode strings?::
     12568* FAQ - General - Why do I get an "Error; invalid syntax;;;;" using 'match' and 'syntax-case'?::
    1205512569
    1205612570@end menu
     
    1211212626Use @code{eval-when}, like this:
    1211312627
    12114 <enscript highlight=scheme> (eval-when (compile) (match-error-control #:unspecified) ) </enscript>
    12115 
     12628@example
     12629(eval-when (compile)
     12630(match-error-control #:unspecified) )
     12631@end example
    1211612632@node FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?, FAQ - General - How can I specialize a generic function method to match instances of every class?, FAQ - General - How can I change match-error-control during compilation?, FAQ - General
    1211712633@subsection Why doesn't CHICKEN support the full numeric tower by default?
     
    1212012636The short answer:
    1212112637
    12122 <enscript highlight=scheme> % chicken-setup numbers % csi -q
    12123 
    12124 @enumerate
    12125 @item ;1> (use numbers) </enscript>
    12126 
    12127 
    12128 @end enumerate
     12638@example
     12639% chicken-setup numbers
     12640% csi -q
     12641#@emph{;1> (use numbers)
     12642}@end example
    1212912643The long answer:
    1213012644
     
    1213712651- Dispatching of arithmetic operations is more efficient.
    1213812652
    12139 There is an extension based on the GNU Multiprecision Package that implements most of the full numeric tower, see @uref{http://www.call-with-current-continuation.org/eggs/numbers.html, http://www.call-with-current-continuation.org/eggs/numbers.html}.
     12653There is an extension based on the GNU Multiprecision Package that implements most of the full numeric tower, see @uref{http://chicken.wiki.br/numbers, numbers}.
    1214012654
    1214112655@node FAQ - General - How can I specialize a generic function method to match instances of every class?, FAQ - General - Does CHICKEN support native threads?, FAQ - General - Why doesn't CHICKEN support the full numeric tower by default?, FAQ - General
     
    1214512659Specializing a method on @code{<object>} doesn't work on primitive data objects like numbers, strings, etc. so for example
    1214612660