Changeset 13437 in project for chicken


Ignore:
Timestamp:
03/01/09 12:20:52 (11 years ago)
Author:
Ivan Raikov
Message:

Updated maketexi script to support new stream-wiki interface.

Location:
chicken/branches/chicken-3
Files:
1 deleted
2 edited

Legend:

Unmodified
Added
Removed
  • chicken/branches/chicken-3/chicken.texi

    r13143 r13437  
    22@settitle Chicken Scheme Reference Manual
    33@setchapternewpage on
    4 @ifinfo
    5 @format
    6 START-INFO-DIR-ENTRY
    7 * Chicken: (chicken.info). Chicken Scheme Reference Manual.
    8 END-INFO-DIR-ENTRY
    9 @end format
    10 @end ifinfo
    114@copying
    12 Copyright 2007-2008 Felix Winkelmann and the Chicken Team
     5Copyright 2007-2009 Felix Winkelmann and the Chicken Team
    136@end copying
    147@titlepage
     
    1912@page
    2013@vskip 0pt plus 1fill
    21 Copyright 2007-2008 Felix Winkelmann and the Chicken Team
     14Copyright 2007-2009 Felix Winkelmann and the Chicken Team
    2215@end titlepage
    2316@node Top, The User's Manual, (dir), (dir)
     
    4235* Unit data-structures::
    4336* Unit ports::
     37* Unit files::
    4438* Unit extras::
    4539* Unit srfi-1::
     
    7468
    7569
    76 This is the user's manual for the Chicken Scheme compiler, version 3.2.7.
     70This is the user's manual for the Chicken Scheme compiler, version 3.5.2
    7771
    7872@table @b
     
    167161Chicken is an implementation of Scheme that has many advantages.
    168162
    169 <blockquote> Chicken Scheme combines an optimising compiler with a reasonably fast interpreter.  It supports almost all of R5RS and the important SRFIs. The compiler generates portable C code that supports tail recursion, first-class continuations, and lightweight threads, and the interface to and from C libraries is flexible, efficient, and easy to use.  There are hundreds of contributed Chicken libraries that make the programmer's task easier.  The interpreter allows interactive use, fast prototyping, debugging, and scripting.  The active and helpful Chicken community fixes bugs and provides support.  Extensive documentation is supplied. </blockquote>
    170 
     163@quotation
     164Chicken Scheme combines an optimising compiler with a reasonably fast interpreter.  It supports almost all of R5RS and the important SRFIs. The compiler generates portable C code that supports tail recursion, first-class continuations, and lightweight threads, and the interface to and from C libraries is flexible, efficient, and easy to use.  There are hundreds of contributed Chicken libraries that make the programmer's task easier.  The interpreter allows interactive use, fast prototyping, debugging, and scripting.  The active and helpful Chicken community fixes bugs and provides support.  Extensive documentation is supplied.
     165
     166
     167@end quotation
    171168Chicken was developed by Felix L. Winkelmann over the period from 2000 through 2007. In early 2008, Felix asked the community to take over the responsibility of developing and maintaining the system, though he still takes a strong interest in it, and participates actively.
    172169
     
    627624The 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:
    628625
    629 @example
    630 (declare (uses UNITNAME))
    631 @end example
    632626The 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:
    633627
    634 @example
    635 (declare (unit UNITNAME))
    636 @end example
    637628When 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.
    638629
    639630Another 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:
    640631
    641 @example
    642 (include @strong{"FILENAME"})
    643 @end example
    644632Macro 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}).
    645633
     
    914902@item -no-usual-integrations
    915903
    916 Specifies that standard procedures and certain internal procedures may be redefined, and cannot be inlined. This is equivalent to declaring @code{(not usual-integrations)}.
     904Specifies that standard procedures and certain internal procedures may be redefined, and can not be inlined. This is equivalent to declaring @code{(not usual-integrations)}.
    917905@item -version
    918906
     
    10221010In this example we will assume your source file is called @code{foo.scm}:
    10231011
    1024 @example
    1025 @emph{;;; foo.scm
    1026 }
    1027 (@strong{define} (@strong{fac} n)
    1028   (@strong{if} (zero? n)
    1029       1
    1030       (* n (fac (- n 1))) ) )
    1031 
    1032 (write (fac 10))
    1033 (newline)
    1034 @end example
    10351012@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;
    10361013@subsubsection Compiling your program
     
    10801057The 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:
    10811058
    1082 @example
    1083 @emph{;;; foo.scm
    1084 }
    1085 @emph{; The declaration marks this source file as dependant on the symbols provided
    1086 }@emph{; by the bar unit:
    1087 }(declare (uses bar))
    1088 
    1089 (write (fac 10)) (newline)
    1090 @end example
    10911059@code{bar.scm} will be our library:
    10921060
    1093 @example
    1094 @emph{;;; bar.scm
    1095 }
    1096 @emph{; The declaration marks this source file as the bar unit.  The names of the
    1097 }@emph{; units and your files don't need to match.
    1098 }(declare (unit bar))
    1099 
    1100 (@strong{define} (@strong{fac} n)
    1101   (@strong{if} (zero? n)
    1102       1
    1103       (* n (fac (- n 1))) ) )
    1104 @end example
    11051061@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
    11061062@subsubsection Compiling and running your program
     
    11691125Let's take a simple example.
    11701126
    1171 @example
    1172 @emph{; hello.scm
    1173 }
    1174 (print @strong{"Hello, world!"})
    1175 @end example
    11761127@verbatim
    11771128 % chicken hello.scm -optimize-level 3 -output-file hello.c
     
    12291180@code{csi @{FILENAME|OPTION}@}
    12301181
    1231 where @code{FILENAME} specifies a file with Scheme source-code.  If the extension of the source file is @code{.scm}, it may be omitted. The runtime options described in @uref{http://galinha.ucpel.tche.br/Using%20the%20compiler#Compiler%20command%20line%20format, Compiler command line format} are also available for the interpreter.  If the environment variable @code{CSI_OPTIONS} is set to a list of options, then these options are additionally passed to every direct or indirect invocation of @code{csi}. Please note that runtime options (like @code{-:...}) cannot be passed using this method. The options recognized by the interpreter are:
     1182where @code{FILENAME} specifies a file with Scheme source-code.  If the extension of the source file is @code{.scm}, it may be omitted. The runtime options described in @uref{http://galinha.ucpel.tche.br/Using%20the%20compiler#Compiler%20command%20line%20format, Compiler command line format} are also available for the interpreter.  If the environment variable @code{CSI_OPTIONS} is set to a list of options, then these options are additionally passed to every direct or indirect invocation of @code{csi}. Please note that runtime options (like @code{-:...}) can not be passed using this method. The options recognized by the interpreter are:
    12321183
    12331184@table @b
     
    13891340
    13901341@end table
    1391 @example
    1392 #@emph{;1> (fac 10)                       ==> 3628800
    1393 }#@emph{;2> ,tr fac
    1394 }#@emph{;3> (fac 3)
    1395 }|(fac 3)
    1396 | (fac 2)
    1397 |  (fac 1)
    1398 |   (fac 0)
    1399 |   fac -> 1
    1400 |  fac -> 1
    1401 | fac -> 2
    1402 |fac -> 6                          =@strong{=>} 6
    1403 #@emph{;4> ,utr fac
    1404 }#@emph{;5> (fac 3)                        ==> 6
    1405 }@end example
    14061342k
    14071343
     
    15371473
    15381474@item @ref{Unit ports, Unit ports} I/O ports
     1475
     1476@item @ref{Unit files, Unit files} File and pathname operations
    15391477
    15401478@item @ref{Unit extras, Unit extras} useful utility definitions
     
    20642002This 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
    20652003
    2066 @example
    2067 (dynamic EXPRESSION ...)
    2068 @end example
    20692004are inserted into the output as a @code{begin} form.
    20702005
    20712006If compiled statically (specifically if the feature @code{chicken-compile-shared} has not been given), then this form expands into the following:
    20722007
    2073 @example
    2074 (declare (unit NAME))
    2075 (provide 'NAME)
    2076 @end example
    20772008and all clauses of the form
    20782009
    2079 @example
    2080 (static EXPRESSION ...)
    2081 @end example
    20822010all additionally inserted into the expansion.
    20832011
    20842012As a convenience, the clause
    20852013
    2086 @example
    2087 (export IDENTIFIER ...)
    2088 @end example
    20892014is 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).
    20902015
    20912016Note that the compiler option @code{-extension NAME} is equivalent to prefixing the compiled file with
    20922017
    2093 @example
    2094 (define-extension NAME)
    2095 @end example
    20962018@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
    20972019@section Binding forms for optional arguments
     
    21152037Use 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.
    21162038
    2117 @example
    2118 (@strong{define} (@strong{incr} x . i) (+ x (optional i 1)))
    2119 (incr 10)                                   =@strong{=>} 11
    2120 (incr 12 5)                                 =@strong{=>} 17
    2121 @end example
    21222039@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
    21232040@subsection case-lambda
     
    21292046Expands into a lambda that invokes the body following the first matching lambda-list.
    21302047
    2131 @example
    2132 (@strong{define} @strong{plus}
    2133   (case-lambda
    2134     (() 0)
    2135     ((x) x)
    2136     ((x y) (+ x y))
    2137     ((x y z) (+ (+ x y) z))
    2138     (args (apply + args))))
    2139 
    2140 (plus)                      =@strong{=>} 0
    2141 (plus 1)                    =@strong{=>} 1
    2142 (plus 1 2 3)                =@strong{=>} 6
    2143 @end example
    21442048For more information see the documentation for @uref{http://srfi.schemers.org/srfi-16/srfi-16.html, SRFI-16}
    21452049
     
    21532057Binding 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.
    21542058
    2155 @example
    2156 (let-optionals '(one two) ((a 1) (b 2) (c 3))
    2157   (list a b c) )                               =@strong{=>} (one two 3)
    2158 @end example
    21592059@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
    21602060@subsection let-optionals*
     
    21662066Binding 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.
    21672067
    2168 @example
    2169 (let-optionals* '(one two) ((a 1) (b 2) (c a))
    2170   (list a b c) )                               =@strong{=>} (one two one)
    2171 @end example
    21722068@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
    21732069@section Other binding forms
     
    22542150Binds multiple variables to the result values of @code{EXP ...}. The variables are bound sequentially.
    22552151
    2256 @example
    2257 (let*-values (((a b) (values 2 3))
    2258               ((p) (+ a b)) )
    2259   p)                               =@strong{=>} 5
    2260 @end example
    22612152@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
    22622153@subsection letrec-values
     
    22682159Binds the result values of @code{EXP ...} to multiple variables at once. All variables are mutually recursive.
    22692160
    2270 @example
    2271 (letrec-values (((odd even)
    2272                    (values
    2273                      (@strong{lambda} (n) (@strong{if} (zero? n) #f (even (sub1 n))))
    2274                      (@strong{lambda} (n) (@strong{if} (zero? n) #t (odd (sub1 n)))) ) ) )
    2275   (odd 17) )                           =@strong{=>} #t
    2276 @end example
    22772161@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
    22782162@subsection parameterize
     
    22962180The syntax
    22972181
    2298 @example
    2299 (receive VALUEEXP)
    2300 @end example
    23012182is equivalent to
    23022183
    2303 @example
    2304 (receive _ VALUEEXP _)
    2305 @end example
    23062184@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
    23072185@subsection set!-values
     
    23962274Equivalent to:
    23972275
    2398 @example
    2399 (@strong{if} (not TEST) (@strong{begin} EXP1 EXP2 ...))
    2400 @end example
    24012276@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
    24022277@subsection when
     
    24082283Equivalent to:
    24092284
    2410 @example
    2411 (@strong{if} TEST (@strong{begin} EXP1 EXP2 ...))
    2412 @end example
    24132285@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
    24142286@section Record structures
     
    24312303Defines 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)}.
    24322304
    2433 @example
    2434 (define-record point x y)
    2435 (@strong{define} @strong{p1} (make-point 123 456))
    2436 (point? p1)                      =@strong{=>} #t
    2437 (point-x p1)                     =@strong{=>} 123
    2438 (point-y-set! p1 99)
    2439 (point-y p1)                     =@strong{=>} 99
    2440 @end example
    24412305@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
    24422306@subsection define-record-printer
     
    24492313Defines 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.
    24502314
    2451 @example
    2452 (define-record foo x y z)
    2453 (@strong{define} @strong{f} (make-foo 1 2 3))
    2454 (define-record-printer (foo x out)
    2455   (fprintf out @strong{"#,(foo ~S ~S ~S)"}
    2456            (foo-x x) (foo-y x) (foo-z x)) )
    2457 (define-reader-ctor 'foo make-foo)
    2458 (@strong{define} @strong{s} (with-output-to-string
    2459               (@strong{lambda} () (write f))))
    2460 s                                   =@strong{=>} @strong{"#,(foo 1 2 3)"}
    2461 (equal? f (with-input-from-string
    2462               s read)))             =@strong{=>} #t
    2463 @end example
    24642315@code{define-record-printer} works also with SRFI-9 record types.
    24652316
     
    25492400The following table should make this clearer:
    25502401
    2551 <table> <tr><th></th><th>In compiled code</th><th>In interpreted code</th></tr> <tr><td>@code{eval}</td><td>ignore</td><td>evaluate</td></tr> <tr><td>@code{compile}</td><td>evaluate at compile time</td><td>ignore</td></tr> <tr><td>@code{load}</td><td>compile as normal</td><td>ignore</td></tr> </table>
    2552 
     2402[[table is unsupported for texi]]
    25532403The situation specifiers @code{compile-time} and @code{run-time} are also defined and have the same meaning as @code{compile} and @code{load}, respectively.
    25542404
     
    26052455The basic form of pattern matching expression is:
    26062456
    2607 @example
    2608 (match exp [pat body] ...)
    2609 @end example
    26102457where @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:
    26112458
    2612 @example
    2613 (@strong{define} @strong{map}
    2614   (@strong{lambda} (f l)
    2615     (match l
    2616       [() '()]
    2617       [(x . y) (cons (f x) (map f y))])))
    2618 @end example
    26192459The 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.
    26202460
     
    26972537The @code{match-lambda} and @code{match-lambda*} forms are convenient combinations of @code{match} and @code{lambda}, and can be explained as follows:
    26982538
    2699 @example
    2700 (match-lambda [pat body] ...)   =  (@strong{lambda} (x) (match x [pat body] ...))
    2701 (match-lambda* [pat body] ...)  =  (@strong{lambda} x (match x [pat body] ...))
    2702 @end example
    27032539where @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.
    27042540
    27052541The @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:
    27062542
    2707 @example
    2708 (match-let ([(x y z) (list 1 2 3)]) body ...)
    2709 @end example
    27102543binds @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.
    27112544
     
    27282561@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:
    27292562
    2730 @example
    2731 (match '(@strong{let} ([x 1][y 2]) z)
    2732   [('@strong{let} ((binding values) ...) exp)  body])
    2733 @end example
    27342563binds @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.
    27352564
     
    27602589@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:
    27612590
    2762 @example
    2763 (@strong{define} @strong{x} (list 1 (list 2 3)))
    2764 (match x [(_ (_ (@strong{set!} setit)))  (setit 4)])
    2765 @end example
    27662591mutates the @code{cadadr} of @code{x} to 4, so that @code{x} is @code{'(1 (2 4))}.
    27672592
     
    27762601If 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:
    27772602
    2778 @example
    2779 #@emph{;1> (match 1 (2 2))
    2780 }
    2781 Failed match:
    2782 Error: no matching clause for @strong{:} 1
    2783 @end example
    27842603For most situations, this behavior is adequate, but it can be changed by altering the value of the parameter @code{match-error-control}:
    27852604
     
    27902609
    27912610@end table
    2792 @example
    2793 (match-error-control [MODE])
    2794 @end example
    27952611Selects 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:
    27962612
    2797 <table>
    2798 
    2799 <tr> <td>#:error</td> <td>
    2800 
    2801 Signal an error. This is the default.
    2802 
    2803 </td> </tr>
    2804 
    2805 <tr> <td>#:match</td> <td>
    2806 
    2807 Signal an error and output the offending form.
    2808 
    2809 </td> </tr>
    2810 
    2811 <tr> <td>#:fail</td> <td>
    2812 
    2813 Omits @code{pair?} tests when the consequence is to fail in @code{car} or @code{cdr} rather than to signal an error.
    2814 
    2815 </td> </tr>
    2816 
    2817 <tr> <td>unspecified</td> <td>
    2818 
    2819 Non-matching expressions will either fail in @code{car} or @code{cdr} or return an unspecified value.  This mode applies to files compiled with the @code{unsafe} option or declaration.
    2820 
    2821 </td> </tr>
    2822 
    2823 </table>
    2824 
     2613[[table is unsupported for texi]]
    28252614When an error is signalled, the raised exception will be of kind @code{(exn match)}.
    28262615
     
    28312620
    28322621@end table
    2833 @example
    2834 (match-error-procedure [PROCEDURE])
    2835 @end example
    28362622Sets 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.
    28372623
     
    28482634Pattern 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:
    28492635
    2850 @example
    2851 null? pair? number? string? symbol? boolean? char? procedure? vector? list?
    2852 equal?
    2853 car cdr cadr cdddr ...
    2854 vector-length vector-ref
    2855 reverse length call/cc
    2856 @end example
    28572636Additionally, 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.
    28582637
     
    28902669* Declarations - no-procedure-checks::
    28912670* Declarations - post-process::
     2671* Declarations - profile::
    28922672* Declarations - number-type::
    28932673* Declarations - fixnum-arithmetic::
     
    30172797[declaration specifier] (not interrupts-enabled)
    30182798@end verbatim
    3019 Disable timer-interrupts checks in the compiled program. Threads cannot be preempted in main- or library-units that contain this declaration.
     2799Disable timer-interrupts checks in the compiled program. Threads can not be preempted in main- or library-units that contain this declaration.
    30202800
    30212801@node Declarations - disable-warning, Declarations - import, Declarations - disable-interrupts, Declarations
     
    31212901Disables checking of values in operator position for being of procedure type.
    31222902
    3123 @node Declarations - post-process, Declarations - number-type, Declarations - no-procedure-checks, Declarations
     2903@node Declarations - post-process, Declarations - profile, Declarations - no-procedure-checks, Declarations
    31242904@section post-process
    31252905
     
    31302910Arranges for the shell commands @code{STRING ...} to be invoked after the current file has been translated to C. Any occurrences of the substring @code{$@@@@} in the strings given for this declaration will be replaced by the pathname of the currently compiled file, without the file-extension. This declaration will only work if the source file is compiled with the @code{csc} compiler driver.
    31312911
    3132 @node Declarations - number-type, Declarations - fixnum-arithmetic, Declarations - post-process, Declarations
     2912@node Declarations - profile, Declarations - number-type, Declarations - post-process, Declarations
     2913@section profile
     2914
     2915
     2916@verbatim
     2917[declaration specifier] (profile IDENTIFIER ...)
     2918@end verbatim
     2919Enable profiling exclusively for given identifiers. Normally the compiler enables profiling decorations for all globally defined procedures. With this declaration, profiling can be enabled for selected procedures.
     2920
     2921@node Declarations - number-type, Declarations - fixnum-arithmetic, Declarations - profile, Declarations
    31332922@section number-type
    31342923
     
    32513040Certain 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:
    32523041
    3253 @example
    3254 (@strong{define} @strong{foo} (make-parameter 123))
    3255 (foo)                             =@strong{=>} 123
    3256 (foo 99)
    3257 (foo)                             =@strong{=>} 99
    3258 @end example
    32593042Parameters are fully thread-local, each thread of execution owns a local copy of a parameters' value.
    32603043
     
    38153598Returns 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.
    38163599
    3817 @example
    3818 (@strong{define} (@strong{increase} x . args)
    3819   (+ x (get-keyword #:amount args (@strong{lambda} () 1))) )
    3820 (increase 123)                                      =@strong{=>} 124
    3821 (increase 123 #:amount 10)                          =@strong{=>} 133
    3822 @end example
    38233600Note: the @code{KEYWORD} may actually be any kind of object.
    38243601
     
    38713648Evaluates @code{EXPRESSION} and handles any exceptions that are covered by @code{CLAUSE ...}, where @code{CLAUSE} should be of the following form:
    38723649
    3873 @example
    3874 CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
    3875 @end example
    38763650If 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.
    38773651
    3878 @example
    3879 (@strong{define} (@strong{check} thunk)
    3880   (condition-case (thunk)
    3881     [(exn file) (print @strong{"file error"})]
    3882     [(exn) (print @strong{"other error"})]
    3883     [var () (print @strong{"something else"})] ) )
    3884 
    3885 (check (@strong{lambda} () (open-input-file @strong{""})))   @emph{; -> "file error"
    3886 }(check (@strong{lambda} () some-unbound-variable))  @emph{; -> "othererror"
    3887 }(check (@strong{lambda} () (signal 99)))            @emph{; -> "something else"
    3888 }
    3889 (condition-case some-unbound-variable
    3890   [(exn file) (print @strong{"ignored"})] )      @emph{; -> signals error
    3891 }
    3892 @end example
    38933652@node Unit library - Exceptions - breakpoint,  , Unit library - Exceptions - condition-case, Unit library - Exceptions
    38943653@subsection breakpoint
     
    39023661All error-conditions signaled by the system are of kind @code{exn}. The following composite conditions are additionally defined:
    39033662
    3904 <table>
    3905 
    3906 <tr><td> (exn arity)
    3907 
    3908 Signaled when a procedure is called with the wrong number of arguments.
    3909 
    3910 </td></tr><tr><td> (exn type)
    3911 
    3912 Signaled on type-mismatch errors, for example when an argument of the wrong type is passed to a built-in procedure.
    3913 
    3914 </td></tr><tr><td> (exn arithmetic)
    3915 
    3916 Signaled on arithmetic errors, like division by zero.
    3917 
    3918 </td></tr><tr><td> (exn i/o)
    3919 
    3920 Signaled on input/output errors.
    3921 
    3922 </td></tr><tr><td> (exn i/o file)
    3923 
    3924 Signaled on file-related errors.
    3925 
    3926 </td></tr><tr><td> (exn i/o net)
    3927 
    3928 Signaled on network errors.
    3929 
    3930 </td></tr><tr><td> (exn bounds)
    3931 
    3932 Signaled on errors caused by accessing non-existent elements of a collection.
    3933 
    3934 </td></tr><tr><td> (exn runtime)
    3935 
    3936 Signaled on low-level runtime-system error-situations.
    3937 
    3938 </td></tr><tr><td> (exn runtime limit)
    3939 
    3940 Signaled when an internal limit is exceeded (like running out of memory).
    3941 
    3942 </td></tr><tr><td> (exn match)
    3943 
    3944 Signaled on errors raised by failed matches (see the section on @code{match}).
    3945 
    3946 </td></tr><tr><td> (exn syntax)
    3947 
    3948 Signaled on syntax errors.
    3949 
    3950 </td></tr><tr><td> (exn breakpoint)
    3951 
    3952 Signaled when a breakpoint is reached.
    3953 
    3954 </td></tr>
    3955 
    3956 </table>
    3957 
     3663[[table is unsupported for texi]]
    39583664Notes:
    39593665
     
    41683874[procedure] (cpu-time)
    41693875@end verbatim
    4170 Returns the used CPU time of the current process in milliseconds as two values: the time spent in user code, and the time spent in system code. On platforms where user and system time cannot be differentiated, system time will be always be 0.
     3876Returns the used CPU time of the current process in milliseconds as two values: the time spent in user code, and the time spent in system code. On platforms where user and system time can not be differentiated, system time will be always be 0.
    41713877
    41723878@node Unit library - Execution time - current-milliseconds, Unit library - Execution time - current-seconds, Unit library - Execution time - cpu-time, Unit library - Execution time
     
    43344040Registers 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}.
    43354041
     4042Finalizers are invoked asynchronously, in the thread that happens to be currently running.
     4043
    43364044@node Unit library - Garbage collection - set-gc-report!,  , Unit library - Garbage collection - set-finalizer!, Unit library - Garbage collection
    43374045@subsection set-gc-report!
     
    44654173If 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.
    44664174
    4467 @example
    4468 (char-name 'space)                  =@strong{=>} #\space
    4469 (char-name #\space)                 =@strong{=>} space
    4470 (char-name 'bell)                   =@strong{=>} #f
    4471 (char-name (integer->char 7))       =@strong{=>} #f
    4472 (char-name 'bell (integer->char 7))
    4473 (char-name 'bell)                   =@strong{=>} #\bell
    4474 (char->integer (char-name 'bell))   =@strong{=>} 7
    4475 @end example
    44764175@node Unit library - Blobs, Unit library - Vectors, Unit library - User-defined named characters, Unit library
    44774176@section Blobs
     
    46524351Returns the value(s) to the continuation @code{CONT}. @code{continuation-return} could be implemented like this:
    46534352
    4654 @example
    4655 (@strong{define} (@strong{continuation-return} k . vals)
    4656   (continuation-graft
    4657     k
    4658     (@strong{lambda} () (apply values vals)) ) )
    4659 @end example
    46604353@node Unit library - Setters, Unit library - Reader extensions, Unit library - Continuations, Unit library
    46614354@section Setters
     
    47214414When 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:
    47224415
    4723 @example
    4724  @emph{; A simple RGB color syntax:
    4725 }
    4726  (set-read-syntax! #\%
    4727    (@strong{lambda} (port)
    4728      (apply vector
    4729        (map (cut string->number <> 16)
    4730             (string-chop (read-string 6 port) 2) ) ) ) )
    4731 
    4732  (with-input-from-string @strong{"(1 2 %f0f0f0 3)"} read)
    4733  @emph{; ==> (1 2 #(240 240 240) 3)
    4734 }@end example
    47354416If @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
    47364417
     
    51274808Registers 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:
    51284809
    5129 @example
    5130 (eval-when (compile eval)
    5131   (set-extension-specifier!
    5132     'my-package
    5133     (@strong{lambda} (spec old)
    5134       (make-pathname my-package-directory (->string (cadr spec))) ) ) )
    5135 
    5136 (require-extension (my-package stuff))     @emph{; --> expands into '(load "my-package-dir/stuff")
    5137 }@end example
    51384810Note that the handler has to be registered at compile time, if it is to be  visible in compiled code.
    51394811
     
    52694941Returns 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.
    52704942
    5271 @example
    5272 (chop '(1 2 3 4 5 6) 2) =@strong{=>} ((1 2) (3 4) (5 6))
    5273 (chop '(a b c d) 3)     =@strong{=>} ((a b c) (d))
    5274 @end example
    52754943@node Unit data-structures - Lists - compress, Unit data-structures - Lists - flatten, Unit data-structures - Lists - chop, Unit data-structures - Lists
    52764944@subsection compress
     
    52824950Returns a new list with elements taken from @code{LIST} with corresponding true values in the list @code{BLIST}.
    52834951
    5284 @example
    5285 (@strong{define} @strong{nums} '(99 100 110 401 1234))
    5286 (compress (map odd? nums) nums)      =@strong{=>} (99 401)
    5287 @end example
    52884952@node Unit data-structures - Lists - flatten, Unit data-structures - Lists - intersperse, Unit data-structures - Lists - compress, Unit data-structures - Lists
    52894953@subsection flatten
     
    53134977Concatenates the lists in @code{LISTOFLISTS} with @code{LIST} placed between each sublist. @code{LIST} defaults to the empty list.
    53144978
    5315 @example
    5316 (join '((a b) (c d) (e)) '(x y)) =@strong{=>} (a b x y c d x y e)
    5317 (join '((p q) () (r (s) t)) '(-))  =@strong{=>} (p q - - r (s) t)
    5318 @end example
    53194979@code{join} could be implemented as follows:
    53204980
    5321 @example
    5322 (@strong{define} (@strong{join} lstoflsts #!optional (lst '()))
    5323   (apply append (intersperse lstoflists lst)) )
    5324 @end example
    53254981@node Unit data-structures - Lists - shuffle, Unit data-structures - Lists - tail?, Unit data-structures - Lists - join, Unit data-structures - Lists
    53264982@subsection shuffle
     
    55455201Returns a string with the string-represenation of all arguments concatenated together. @code{conc} could be implemented as
    55465202
    5547 @example
    5548 (@strong{define} (@strong{conc} . args)
    5549   (apply string-append (map ->string args)) )
    5550 @end example
    55515203@node Unit data-structures - Strings - ->string, Unit data-structures - Strings - string-chop, Unit data-structures - Strings - conc, Unit data-structures - Strings
    55525204@subsection ->string
     
    55675219Returns a list of substrings taken by @emph{chopping} @code{STRING} every @code{LENGTH} characters:
    55685220
    5569 @example
    5570 (string-chop @strong{"one two three"} 4)  =@strong{=>}  (@strong{"one "} @strong{"two "} @strong{"thre"} @strong{"e"})
    5571 @end example
    55725221@node Unit data-structures - Strings - string-chomp, Unit data-structures - Strings - string-compare3, Unit data-structures - Strings - string-chop, Unit data-structures - Strings
    55735222@subsection string-chomp
     
    55985247Returns a string that contains all strings in @code{LIST} concatenated together.  @code{STRING} is placed between each concatenated string and defaults to @code{" "}.
    55995248
    5600 @example
    5601 (string-intersperse '(@strong{"one"} @strong{"two"}) @strong{"three"})
    5602 @end example
    56035249is equivalent to
    56045250
    5605 @example
    5606 (apply string-append (intersperse '(@strong{"one"} @strong{"two"}) @strong{"three"}))
    5607 @end example
    56085251@node Unit data-structures - Strings - string-split, Unit data-structures - Strings - string-translate, Unit data-structures - Strings - string-intersperse, Unit data-structures - Strings
    56095252@subsection string-split
     
    56155258Split 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:
    56165259
    5617 @example
    5618 (string-split @strong{"one  two  three"}) =@strong{=>} (@strong{"one"} @strong{"two"} @strong{"three"})
    5619 (string-split @strong{"foo:bar::baz:"} @strong{":"} #t) =@strong{=>} (@strong{"foo"} @strong{"bar"} @strong{""} @strong{"baz"} @strong{""})
    5620 @end example
    56215260@node Unit data-structures - Strings - string-translate, Unit data-structures - Strings - string-translate*, Unit data-structures - Strings - string-split, Unit data-structures - Strings
    56225261@subsection string-translate
     
    56375276Substitutes 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}:
    56385277
    5639 @example
    5640 (string-translate*
    5641   @strong{"<h1>this is a \"string\"</h1>"}
    5642   '((@strong{"<"} . @strong{"&lt;"}) (@strong{">"} . @strong{"&gt;"}) (@strong{"\""} . @strong{"&quot;"})) )
    5643 @strong{=>}  @strong{"&lt;h1&gt;this is a &quot;string&quot;&lt;/h1&gt;"}
    5644 @end example
    56455278@node Unit data-structures - Strings - substring=?, Unit data-structures - Strings - substring-index, Unit data-structures - Strings - string-translate*, Unit data-structures - Strings
    56465279@subsection substring=?
     
    56685301@menu
    56695302* Unit data-structures - Combinators - any?::
     5303* Unit data-structures - Combinators - none?::
     5304* Unit data-structures - Combinators - always?::
     5305* Unit data-structures - Combinators - never?::
    56705306* Unit data-structures - Combinators - constantly::
    56715307* Unit data-structures - Combinators - complement::
     
    56805316* Unit data-structures - Combinators - noop::
    56815317* Unit data-structures - Combinators - o::
    5682 
    5683 @end menu
    5684 
    5685 
    5686 @node Unit data-structures - Combinators - any?, Unit data-structures - Combinators - constantly,  , Unit data-structures - Combinators
     5318* Unit data-structures - Combinators - left-section::
     5319* Unit data-structures - Combinators - right-section::
     5320
     5321@end menu
     5322
     5323
     5324@node Unit data-structures - Combinators - any?, Unit data-structures - Combinators - none?,  , Unit data-structures - Combinators
    56875325@subsection any?
    56885326
     
    56935331Ignores its argument and always returns @code{#t}. This is actually useful sometimes.
    56945332
    5695 @node Unit data-structures - Combinators - constantly, Unit data-structures - Combinators - complement, Unit data-structures - Combinators - any?, Unit data-structures - Combinators
     5333@node Unit data-structures - Combinators - none?, Unit data-structures - Combinators - always?, Unit data-structures - Combinators - any?, Unit data-structures - Combinators
     5334@subsection none?
     5335
     5336
     5337@verbatim
     5338[procedure] (none? X)
     5339@end verbatim
     5340Ignores its argument and always returns @code{#f}. This is actually useful sometimes.
     5341
     5342@node Unit data-structures - Combinators - always?, Unit data-structures - Combinators - never?, Unit data-structures - Combinators - none?, Unit data-structures - Combinators
     5343@subsection always?
     5344
     5345
     5346@verbatim
     5347[procedure] (always? X)
     5348@end verbatim
     5349Ignores its arguments and always returns @code{#t}. This is actually useful sometimes.
     5350
     5351@node Unit data-structures - Combinators - never?, Unit data-structures - Combinators - constantly, Unit data-structures - Combinators - always?, Unit data-structures - Combinators
     5352@subsection never?
     5353
     5354
     5355@verbatim
     5356[procedure] (never? X)
     5357@end verbatim
     5358Ignores its arguments and always returns @code{#f}. This is actually useful sometimes.
     5359
     5360@node Unit data-structures - Combinators - constantly, Unit data-structures - Combinators - complement, Unit data-structures - Combinators - never?, Unit data-structures - Combinators
    56965361@subsection constantly
    56975362
     
    57025367Returns a procedure that always returns the values @code{X ...} regardless of the number and value of its arguments.
    57035368
    5704 @example
    5705 (constantly X) <@strong{=>} (@strong{lambda} args X)
    5706 @end example
    57075369@node Unit data-structures - Combinators - complement, Unit data-structures - Combinators - compose, Unit data-structures - Combinators - constantly, Unit data-structures - Combinators
    57085370@subsection complement
     
    57145376Returns a procedure that returns the boolean inverse of @code{PROC}.
    57155377
    5716 @example
    5717 (complement PROC) <@strong{=>} (@strong{lambda} (x) (not (PROC x)))
    5718 @end example
    57195378@node Unit data-structures - Combinators - compose, Unit data-structures - Combinators - conjoin, Unit data-structures - Combinators - complement, Unit data-structures - Combinators
    57205379@subsection compose
     
    57265385Returns a procedure that represents the composition of the argument-procedures @code{PROC1 PROC2 ...}.
    57275386
    5728 @example
    5729 (compose F G) <@strong{=>} (@strong{lambda} args
    5730                       (call-with-values
    5731                          (@strong{lambda} () (apply G args))
    5732                          F))
    5733 @end example
    57345387@code{(compose)} is equivalent to @code{values}.
    57355388
     
    57415394[procedure] (conjoin PRED ...)
    57425395@end verbatim
    5743 Returns a procedure that returns @code{#t} if its argument satisfies the predicates @code{PRED ...}. @example
    5744 ((conjoin odd? positive?) 33)   =@strong{=>}  #t
    5745 ((conjoin odd? positive?) -33)  =@strong{=>}  #f
    5746 @end example
    5747 
     5396Returns a procedure that returns @code{#t} if its argument satisfies the predicates @code{PRED ...}.
    57485397
    57495398@node Unit data-structures - Combinators - disjoin, Unit data-structures - Combinators - each, Unit data-structures - Combinators - conjoin, Unit data-structures - Combinators
     
    57545403[procedure] (disjoin PRED ...)
    57555404@end verbatim
    5756 Returns a procedure that returns @code{#t} if its argument satisfies any predicate @code{PRED ...}. @example
    5757 ((disjoin odd? positive?) 32)    =@strong{=>}  #t
    5758 ((disjoin odd? positive?) -32)   =@strong{=>}  #f
    5759 @end example
    5760 
     5405Returns a procedure that returns @code{#t} if its argument satisfies any predicate @code{PRED ...}.
    57615406
    57625407@node Unit data-structures - Combinators - each, Unit data-structures - Combinators - flip, Unit data-structures - Combinators - disjoin, Unit data-structures - Combinators
     
    57695414Returns a procedure that applies @code{PROC ...} to its arguments, and returns the result(s) of the last procedure application. For example
    57705415
    5771 @example
    5772 (each pp eval)
    5773 @end example
    57745416is equivalent to
    57755417
    5776 @example
    5777 (@strong{lambda} args
    5778   (apply pp args)
    5779   (apply eval args) )
    5780 @end example
    57815418@code{(each PROC)} is equivalent to @code{PROC} and @code{(each)} is equivalent to @code{noop}.
    57825419
     
    57885425[procedure] (flip PROC)
    57895426@end verbatim
    5790 Returns a two-argument procedure that calls @code{PROC} with its arguments swapped: @example
    5791 (flip PROC) <@strong{=>} (@strong{lambda} (x y) (PROC y x))
    5792 @end example
    5793 
     5427Returns a two-argument procedure that calls @code{PROC} with its arguments swapped:
    57945428
    57955429@node Unit data-structures - Combinators - identity, Unit data-structures - Combinators - project, Unit data-structures - Combinators - flip, Unit data-structures - Combinators
     
    58205454Returns 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.
    58215455
    5822 @example
    5823 ((list-of even?) '(1 2 3))   =@strong{=>} #f
    5824 ((list-of number?) '(1 2 3)) =@strong{=>} #t
    5825 @end example
    58265456@node Unit data-structures - Combinators - noop, Unit data-structures - Combinators - o, Unit data-structures - Combinators - list-of, Unit data-structures - Combinators
    58275457@subsection noop
     
    58335463Ignores it's arguments, does nothing and returns an unspecified value.
    58345464
    5835 @node Unit data-structures - Combinators - o,  , Unit data-structures - Combinators - noop, Unit data-structures - Combinators
     5465@node Unit data-structures - Combinators - o, Unit data-structures - Combinators - left-section, Unit data-structures - Combinators - noop, Unit data-structures - Combinators
    58365466@subsection o
    58375467
     
    58415471@end verbatim
    58425472A single value version of @code{compose} (slightly faster). @code{(o)} is equivalent to @code{identity}.
     5473
     5474@node Unit data-structures - Combinators - left-section, Unit data-structures - Combinators - right-section, Unit data-structures - Combinators - o, Unit data-structures - Combinators
     5475@subsection left-section
     5476
     5477
     5478@verbatim
     5479[procedure] (left-section PROC ARG0 ...)
     5480@end verbatim
     5481Returns a procedure that partially applies some of its' arguments starting from the left.
     5482
     5483@code{PROC} a procedure.
     5484
     5485@code{ARG0 ...} some prefix of the arguments for @code{PROC}.
     5486
     5487@node Unit data-structures - Combinators - right-section,  , Unit data-structures - Combinators - left-section, Unit data-structures - Combinators
     5488@subsection right-section
     5489
     5490
     5491@verbatim
     5492[procedure] (right-section PROC ARG0 ...)
     5493@end verbatim
     5494Returns a procedure that partially applies some of its' arguments starting from the right.
     5495
     5496@code{PROC} a procedure.
     5497
     5498@code{ARG0 ...} some reversed suffix of the arguments for @code{PROC}.
    58435499
    58445500@node Unit data-structures - Binary searching,  , Unit data-structures - Combinators, Unit data-structures
     
    58645520Next: @ref{Unit ports, Unit ports} 
    58655521
    5866 @node Unit ports, Unit extras, Unit data-structures, Top
     5522@node Unit ports, Unit files, Unit data-structures, Top
    58675523@chapter Unit ports
    58685524
     
    60525708Previous: @ref{Unit data-structures, Unit data-structures}
    60535709
     5710Next: @ref{Unit files, Unit files} 
     5711
     5712@node Unit files, Unit extras, Unit ports, Top
     5713@chapter Unit files
     5714
     5715@menu
     5716* Unit files - Pathname operations::
     5717* Unit files - Temporary files::
     5718* Unit files - Deleting a file without signalling an error::
     5719* Unit files - File move/copy::
     5720
     5721@end menu
     5722
     5723
     5724This unit contains file- and pathname-oriented procedures. It uses the @code{regex} unit.
     5725
     5726@node Unit files - Pathname operations, Unit files - Temporary files,  , Unit files
     5727@section Pathname operations
     5728
     5729@menu
     5730* Unit files - Pathname operations - absolute-pathname?::
     5731* Unit files - Pathname operations - decompose-pathname::
     5732* Unit files - Pathname operations - make-pathname::
     5733* Unit files - Pathname operations - make-absolute-pathname::
     5734* Unit files - Pathname operations - pathname-directory::
     5735* Unit files - Pathname operations - pathname-file::
     5736* Unit files - Pathname operations - pathname-extension::
     5737* Unit files - Pathname operations - pathname-replace-directory::
     5738* Unit files - Pathname operations - pathname-replace-file::
     5739* Unit files - Pathname operations - pathname-replace-extension::
     5740* Unit files - Pathname operations - pathname-strip-directory::
     5741* Unit files - Pathname operations - pathname-strip-extension::
     5742* Unit files - Pathname operations - directory-null?::
     5743
     5744@end menu
     5745
     5746
     5747@node Unit files - Pathname operations - absolute-pathname?, Unit files - Pathname operations - decompose-pathname,  , Unit files - Pathname operations
     5748@subsection absolute-pathname?
     5749
     5750
     5751@verbatim
     5752[procedure] (absolute-pathname? PATHNAME)
     5753@end verbatim
     5754Returns @code{#t} if the string @code{PATHNAME} names an absolute pathname, and returns @code{#f} otherwise.
     5755
     5756@node Unit files - Pathname operations - decompose-pathname, Unit files - Pathname operations - make-pathname, Unit files - Pathname operations - absolute-pathname?, Unit files - Pathname operations
     5757@subsection decompose-pathname
     5758
     5759
     5760@verbatim
     5761[procedure] (decompose-pathname PATHNAME)
     5762@end verbatim
     5763Returns three values: the directory-, filename- and extension-components of the file named by the string @code{PATHNAME}. For any component that is not contained in @code{PATHNAME}, @code{#f} is returned.
     5764
     5765@node Unit files - Pathname operations - make-pathname, Unit files - Pathname operations - make-absolute-pathname, Unit files - Pathname operations - decompose-pathname, Unit files - Pathname operations
     5766@subsection make-pathname
     5767
     5768
     5769@node Unit files - Pathname operations - make-absolute-pathname, Unit files - Pathname operations - pathname-directory, Unit files - Pathname operations - make-pathname, Unit files - Pathname operations
     5770@subsection make-absolute-pathname
     5771
     5772
     5773@verbatim
     5774[procedure] (make-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
     5775[procedure] (make-absolute-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
     5776@end verbatim
     5777Returns a string that names the file with the components @code{DIRECTORY, FILENAME} and (optionally) @code{EXTENSION} with @code{SEPARATOR} being the directory separation indicator (usually @code{/} on UNIX systems and @code{\} on Windows, defaulting to whatever platform this is running on).  @code{DIRECTORY} can be @code{#f} (meaning no directory component), a string or a list of strings. @code{FILENAME} and @code{EXTENSION} should be strings or @code{#f}. @code{make-absolute-pathname} returns always an absolute pathname.
     5778
     5779@node Unit files - Pathname operations - pathname-directory, Unit files - Pathname operations - pathname-file, Unit files - Pathname operations - make-absolute-pathname, Unit files - Pathname operations
     5780@subsection pathname-directory
     5781
     5782
     5783@verbatim
     5784[procedure] (pathname-directory PATHNAME)
     5785@end verbatim
     5786@node Unit files - Pathname operations - pathname-file, Unit files - Pathname operations - pathname-extension, Unit files - Pathname operations - pathname-directory, Unit files - Pathname operations
     5787@subsection pathname-file
     5788
     5789
     5790@verbatim
     5791[procedure] (pathname-file PATHNAME)
     5792@end verbatim
     5793@node Unit files - Pathname operations - pathname-extension, Unit files - Pathname operations - pathname-replace-directory, Unit files - Pathname operations - pathname-file, Unit files - Pathname operations
     5794@subsection pathname-extension
     5795
     5796
     5797@verbatim
     5798[procedure] (pathname-extension PATHNAME)
     5799@end verbatim
     5800Accessors for the components of @code{PATHNAME}. If the pathname does not contain the accessed component, then @code{#f} is returned.
     5801
     5802@node Unit files - Pathname operations - pathname-replace-directory, Unit files - Pathname operations - pathname-replace-file, Unit files - Pathname operations - pathname-extension, Unit files - Pathname operations
     5803@subsection pathname-replace-directory
     5804
     5805
     5806@verbatim
     5807[procedure] (pathname-replace-directory PATHNAME DIRECTORY)
     5808@end verbatim
     5809@node Unit files - Pathname operations - pathname-replace-file, Unit files - Pathname operations - pathname-replace-extension, Unit files - Pathname operations - pathname-replace-directory, Unit files - Pathname operations
     5810@subsection pathname-replace-file
     5811
     5812
     5813@verbatim
     5814[procedure] (pathname-replace-file PATHNAME FILENAME)
     5815@end verbatim
     5816@node Unit files - Pathname operations - pathname-replace-extension, Unit files - Pathname operations - pathname-strip-directory, Unit files - Pathname operations - pathname-replace-file, Unit files - Pathname operations
     5817@subsection pathname-replace-extension
     5818
     5819
     5820@verbatim
     5821[procedure] (pathname-replace-extension PATHNAME EXTENSION)
     5822@end verbatim
     5823Return a new pathname with the specified component of @code{PATHNAME} replaced by a new value.
     5824
     5825@node Unit files - Pathname operations - pathname-strip-directory, Unit files - Pathname operations - pathname-strip-extension, Unit files - Pathname operations - pathname-replace-extension, Unit files - Pathname operations
     5826@subsection pathname-strip-directory
     5827
     5828
     5829@verbatim
     5830[procedure] (pathname-strip-directory PATHNAME)
     5831@end verbatim
     5832@node Unit files - Pathname operations - pathname-strip-extension, Unit files - Pathname operations - directory-null?, Unit files - Pathname operations - pathname-strip-directory, Unit files - Pathname operations
     5833@subsection pathname-strip-extension
     5834
     5835
     5836@verbatim
     5837[procedure] (pathname-strip-extension PATHNAME)
     5838@end verbatim
     5839Return a new pathname with the specified component of @code{PATHNAME} stripped.
     5840
     5841@node Unit files - Pathname operations - directory-null?,  , Unit files - Pathname operations - pathname-strip-extension, Unit files - Pathname operations
     5842@subsection directory-null?
     5843
     5844
     5845@verbatim
     5846[procedure] (directory-null? DIRECTORY)
     5847@end verbatim
     5848Does the @code{DIRECTORY} consist only of path separators and the period?
     5849
     5850@code{DIRECTORY} may be a string or a list of strings.
     5851
     5852@node Unit files - Temporary files, Unit files - Deleting a file without signalling an error, Unit files - Pathname operations, Unit files
     5853@section Temporary files
     5854
     5855@menu
     5856* Unit files - Temporary files - create-temporary-file::
     5857
     5858@end menu
     5859
     5860
     5861@node Unit files - Temporary files - create-temporary-file,  ,  , Unit files - Temporary files
     5862@subsection create-temporary-file
     5863
     5864
     5865@verbatim
     5866[procedure] (create-temporary-file [EXTENSION])
     5867@end verbatim
     5868Creates an empty temporary file and returns its pathname. If @code{EXTENSION} is not given, then @code{.tmp} is used. If the environment variable @code{TMPDIR, TEMP} or @code{TMP} is set, then the pathname names a file in that directory.
     5869
     5870@node Unit files - Deleting a file without signalling an error, Unit files - File move/copy, Unit files - Temporary files, Unit files
     5871@section Deleting a file without signalling an error
     5872
     5873@menu
     5874* Unit files - Deleting a file without signalling an error - delete-file*::
     5875
     5876@end menu
     5877
     5878
     5879@node Unit files - Deleting a file without signalling an error - delete-file*,  ,  , Unit files - Deleting a file without signalling an error
     5880@subsection delete-file*
     5881
     5882
     5883@verbatim
     5884[procedure] (delete-file* FILENAME)
     5885@end verbatim
     5886If the file @code{FILENAME} exists, it is deleted and @code{#t} is returned.  If the file does not exist, nothing happens and @code{#f} is returned.
     5887
     5888@node Unit files - File move/copy,  , Unit files - Deleting a file without signalling an error, Unit files
     5889@section File move/copy
     5890
     5891@menu
     5892* Unit files - File move/copy - file-copy::
     5893* Unit files - File move/copy - file-move::
     5894
     5895@end menu
     5896
     5897
     5898@node Unit files - File move/copy - file-copy, Unit files - File move/copy - file-move,  , Unit files - File move/copy
     5899@subsection file-copy
     5900
     5901
     5902@verbatim
     5903[procedure] (file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
     5904@end verbatim
     5905Copies @code{ORIGFILE} (a string denoting some filename) to @code{NEWFILE},  @code{BLOCKSIZE} bytes at a time.  @code{BLOCKSIZE} defaults to 1024, and must be a positive integer.  Returns the number of bytes copied on success, or errors on failure.  @code{CLOBBER} determines the behaviour of @code{file-copy} when @code{NEWFILE} is already extant.  When set to @code{#f} (default), an error is signalled.  When set to any other value, @code{NEWFILE} is overwritten. @code{file-copy} will work across filesystems and devices and is not platform-dependent.
     5906
     5907@node Unit files - File move/copy - file-move,  , Unit files - File move/copy - file-copy, Unit files - File move/copy
     5908@subsection file-move
     5909
     5910
     5911@verbatim
     5912[procedure] (file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
     5913@end verbatim
     5914Moves @code{ORIGFILE} (a string denoting some filename) to @code{NEWFILE}, with the same semantics as @code{file-copy}, above.  @code{file-move} is safe across filesystems and devices (unlike @code{file-rename}).  It is possible for an error to be signalled despite partial success if @code{NEWFILE} could be created and fully written but removing @code{ORIGFILE} fails.
     5915
     5916Previous: @ref{Unit ports, Unit ports}
     5917
    60545918Next: @ref{Unit extras, Unit extras} 
    60555919
    6056 @node Unit extras, Unit srfi-1, Unit ports, Top
     5920@node Unit extras, Unit srfi-1, Unit files, Top
    60575921@chapter Unit extras
    60585922
     
    60985962Simple 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:
    60995963
    6100 <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>
    6101 
     5964[[table is unsupported for texi]]
    61025965@node Unit extras - Formatted output - format,  , Unit extras - Formatted output - sprintf, Unit extras - Formatted output
    61035966@subsection format
     
    62596122Reads characters from @code{PORT} (which defaults to the value of @code{(current-input-port)}) and calls the procedure @code{PREDICATE} with each character until @code{PREDICATE} returns false. Returns a string with the accumulated characters.
    62606123
    6261 Previous: @ref{Unit ports, Unit ports}
     6124Previous: @ref{Unit files, Unit files}
    62626125
    62636126Next: @ref{Unit srfi-1, Unit srfi-1}
     
    65936456On systems that support dynamic loading, the @code{srfi-13} unit can be made available in the interpreter (@code{csi}) by entering
    65946457
    6595 @example
    6596 (require-extension srfi-13)
    6597 @end example
    65986458Previous: @ref{Unit srfi-4, Unit srfi-4}
    65996459
     
    66086468On systems that support dynamic loading, the @code{srfi-14} unit can be made available in the interpreter (@code{csi}) by entering
    66096469
    6610 @example
    6611 (require-extension srfi-14)
    6612 @end example
    66136470This library provides only the Latin-1 character set.
    66146471
     
    68726729A setter for @code{hash-table-ref} is defined, so
    68736730
    6874 @example
    6875 (@strong{set!} (hash-table-ref HASH-TABLE KEY) VALUE)
    6876 @end example
    68776731is equivalent to
    68786732
    6879 @example
    6880 (hash-table-set! HASH-TABLE KEY VALUE)
    6881 @end example
    68826733@node Unit srfi-69 - Hash Table Procedures - hash-table-update!, Unit srfi-69 - Hash Table Procedures - hash-table-update!/default, Unit srfi-69 - Hash Table Procedures - hash-table-set!, Unit srfi-69 - Hash Table Procedures
    68836734@subsection hash-table-update!
     
    71446995* Unit regex - glob?::
    71456996* Unit regex - regexp::
    7146 * Unit regex - regexp*::
    71476997* Unit regex - regexp?::
    7148 * Unit regex - regexp-optimize::
    71496998* Unit regex - string-match::
    71506999* Unit regex - string-match-positions::
     
    71557004* Unit regex - string-substitute*::
    71567005* Unit regex - regexp-escape::
    7157 * Unit regex - make-anchored-pattern::
    7158 
    7159 @end menu
    7160 
    7161 
    7162 This library unit provides support for regular expressions. The regular  expression package used is @code{PCRE} (@emph{Perl Compatible Regular Expressions})  written by Philip Hazel. See @uref{http://www.pcre.org, http://www.pcre.org} for information about the particular regexp flavor and extensions provided by this library.
    7163 
    7164 To test that PCRE support has been built into Chicken properly, try:
    7165 
    7166 @example
    7167 (require 'regex)
    7168 (feature? 'pcre) @strong{=>} #t
    7169 @end example
     7006
     7007@end menu
     7008
     7009
     7010This library unit provides support for regular expressions. The regular expression package used is @code{irregex} written by Alex Shinn. See @uref{http://synthcode.com/scheme/irregex/, http://synthcode.com/scheme/irregex/} for information about the particular regexp flavor and extensions provided by this library.
     7011
     7012To test that @code{irregex} support has been built into Chicken properly, try:
     7013
     7014Note on SRE syntax: instead of @code{(| <sre> ...)}, use @code{(or <sre> ...)}. The character @code{|} (vertical pipe) is handled specially in Chicken, and cannot be used on its own as a symbol.
     7015
    71707016@node Unit regex - grep, Unit regex - glob->regexp,  , Unit regex
    71717017@section grep
     
    71777023Returns all items of @code{LIST} that match the regular expression @code{REGEX}.  This procedure could be defined as follows:
    71787024
    7179 @example
    7180 (@strong{define} (@strong{grep} regex lst)
    7181   (filter (@strong{lambda} (x) (string-search regex x)) lst) )
    7182 @end example
    71837025@node Unit regex - glob->regexp, Unit regex - glob?, Unit regex - grep, Unit regex
    71847026@section glob->regexp
     
    71907032Converts the file-pattern @code{PATTERN} into a regular expression.
    71917033
    7192 @example
    7193 (glob->regexp @strong{"foo.*"})
    7194 @strong{=>} @strong{"foo\..*"}
    7195 @end example
    71967034@code{PATTERN} should follow "glob" syntax. Allowed wildcards are
    71977035
     
    72147052A string without any "glob" wildcards does not meet the criteria, even though it technically is a valid "glob" file-pattern.
    72157053
    7216 @node Unit regex - regexp, Unit regex - regexp*, Unit regex - glob?, Unit regex
     7054@node Unit regex - regexp, Unit regex - regexp?, Unit regex - glob?, Unit regex
    72177055@section regexp
    72187056
     
    72237061Returns 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.
    72247062
    7225 @node Unit regex - regexp*, Unit regex - regexp?, Unit regex - regexp, Unit regex
    7226 @section regexp*
    7227 
    7228 
    7229 @verbatim
    7230 [procedure] (regexp* STRING [OPTIONS [TABLES]])
    7231 @end verbatim
    7232 Returns 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).
    7233 
    7234 Option Symbols:
    7235 
    7236 @table @b
    7237 @item caseless
    7238 
    7239 Character case insensitive match
    7240 @item multiline
    7241 
    7242 Equivalent to Perl's /m option
    7243 @item dotall
    7244 
    7245 Equivalent to Perl's /s option
    7246 @item extended
    7247 
    7248 Ignore whitespace
    7249 @item anchored
    7250 
    7251 Anchor pattern match
    7252 @item dollar-endonly
    7253 
    7254 `$' metacharacter in the pattern matches only at the end of the subject string
    7255 @item extra
    7256 
    7257 Currently of very little use
    7258 @item notbol
    7259 
    7260 First character of the string is not the beginning of a line
    7261 @item noteol
    7262 
    7263 End of the string is not the end of a line
    7264 @item ungreedy
    7265 
    7266 Inverts the "greediness" of the quantifiers so that they are not greedy by default
    7267 @item notempty
    7268 
    7269 The empty string is not considered to be a valid match
    7270 @item utf8
    7271 
    7272 UTF-8 encoded characters
    7273 @item no-auto-capture
    7274 
    7275 Disables the use of numbered capturing parentheses
    7276 @item no-utf8-check
    7277 
    7278 Skip valid UTF-8 sequence check
    7279 @item auto-callout
    7280 
    7281 Automatically inserts callout items (not defined here)
    7282 @item partial
    7283 
    7284 Partial match ok
    7285 @item firstline
    7286 
    7287 An unanchored pattern is required to match before or at the first newline
    7288 @item dupnames
    7289 
    7290 Names used to identify capturing subpatterns need not be unique
    7291 @item newline-cr
    7292 
    7293 Newline definition is `\r'
    7294 @item newline-lf
    7295 
    7296 Newline definition is `\n'
    7297 @item newline-crlf
    7298 
    7299 Newline definition is `\r\n'
    7300 @item newline-anycrlf
    7301 
    7302 Newline definition is any of `\r', `\n', or `\r\n'
    7303 @item newline-any
    7304 
    7305 Newline definition is any Unicode newline sequence
    7306 @item bsr-anycrlf
    7307 
    7308 `\R' escape sequence matches only CR, LF, or CRLF
    7309 @item bsr-unicode
    7310 
    7311 `\R' escape sequence matches only Unicode newline sequence
    7312 @item dfa-shortest
    7313 
    7314 Currently unused
    7315 @item dfa-restart
    7316 
    7317 Currently unused
    7318 
    7319 @end table
    7320 @node Unit regex - regexp?, Unit regex - regexp-optimize, Unit regex - regexp*, Unit regex
     7063@node Unit regex - regexp?, Unit regex - string-match, Unit regex - regexp, Unit regex
    73217064@section regexp?
    73227065
     
    73277070Returns @code{#t} if @code{X} is a precompiled regular expression, or @code{#f} otherwise.
    73287071
    7329 @node Unit regex - regexp-optimize, Unit regex - string-match, Unit regex - regexp?, Unit regex
    7330 @section regexp-optimize
    7331 
    7332 
    7333 @verbatim
    7334 [procedure] (regexp-optimize RX)
    7335 
    7336 @end verbatim
    7337 Perform available optimizations for the precompiled regular expression @code{RX}. Returns @code{#t} when optimization performed, and @code{#f} otherwise.
    7338 
    7339 @node Unit regex - string-match, Unit regex - string-match-positions, Unit regex - regexp-optimize, Unit regex
     7072@node Unit regex - string-match, Unit regex - string-match-positions, Unit regex - regexp?, Unit regex
    73407073@section string-match
    73417074
     
    73467079
    73477080@verbatim
    7348 [procedure] (string-match REGEXP STRING [START])
    7349 [procedure] (string-match-positions REGEXP STRING [START])
    7350 @end verbatim
    7351 Matches the regular expression in @code{REGEXP} (a string or a precompiled regular expression) with @code{STRING} and returns either @code{#f} if the match failed, or a list of matching groups, where the first element is the complete match. If the optional argument @code{START} is supplied, it specifies the starting position in @code{STRING}.  For each matching group the result-list contains either: @code{#f} for a non-matching but optional group; a list of start- and end-position of the match in @code{STRING} (in the case of @code{string-match-positions}); or the matching substring (in the case of @code{string-match}). Note that the exact string is matched. For searching a pattern inside a string, see below. Note also that @code{string-match} is implemented by calling @code{string-search} with the regular expression wrapped in @code{^ ... $}. If invoked with a precompiled regular expression argument (by using @code{regexp}), @code{string-match} is identical to @code{string-search}.
     7081[procedure] (string-match REGEXP STRING )
     7082[procedure] (string-match-positions REGEXP STRING )
     7083@end verbatim
     7084Matches the regular expression in @code{REGEXP} (a string or a precompiled regular expression) with @code{STRING} and returns either @code{#f} if the match failed, or a list of matching groups, where the first element is the complete match. For each matching group the result-list contains either: @code{#f} for a non-matching but optional group; a list of start- and end-position of the match in @code{STRING} (in the case of @code{string-match-positions}); or the matching substring (in the case of @code{string-match}). Note that the exact string is matched. For searching a pattern inside a string, see below.  Note also that @code{string-match} is implemented by calling @code{string-search} with the regular expression wrapped in @code{^ ... $}. If invoked with a precompiled regular expression argument (by using @code{regexp}), @code{string-match} is identical to @code{string-search}.
    73527085
    73537086@node Unit regex - string-search, Unit regex - string-search-positions, Unit regex - string-match-positions, Unit regex
     
    73747107Splits @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.
    73757108
    7376 @example
    7377 (@strong{define} @strong{s} @strong{"this is a string 1, 2, 3,"})
    7378 
    7379 (string-split-fields @strong{"[^ ]+"} s)
    7380 
    7381   @strong{=>} (@strong{"this"} @strong{"is"} @strong{"a"} @strong{"string"} @strong{"1,"} @strong{"2,"} @strong{"3,"})
    7382 
    7383 (string-split-fields @strong{" "} s #:infix)
    7384 
    7385   @strong{=>} (@strong{"this"} @strong{"is"} @strong{"a"} @strong{"string"} @strong{"1,"} @strong{"2,"} @strong{"3,"})
    7386 
    7387 (string-split-fields @strong{","} s #:suffix)
    7388  
    7389   @strong{=>} (@strong{"this is a string 1"} @strong{" 2"} @strong{" 3"})
    7390 @end example
    73917109@node Unit regex - string-substitute, Unit regex - string-substitute*, Unit regex - string-split-fields, Unit regex
    73927110@section string-substitute
     
    73987116Searches 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.
    73997117
    7400 @example
    7401 (string-substitute @strong{"([0-9]+) (eggs|chicks)"}
    7402                    @strong{"\\2 (\\1)"} @strong{"99 eggs or 99 chicks"} 2)
    7403 @strong{=>} @strong{"99 eggs or chicks (99)"}
    7404 @end example
    74057118Note that a regular expression that matches an empty string will signal an error.
    74067119
     
    74147127Substitutes 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}
    74157128
    7416 @example
    7417 (string-substitute* @strong{"<h1>Hello, world!</h1>"}
    7418                     '((@strong{"<[/A-Za-z0-9]+>"} . @strong{""})))
    7419 
    7420 @strong{=>}  @strong{"Hello, world!"}
    7421 @end example
    7422 @node Unit regex - regexp-escape, Unit regex - make-anchored-pattern, Unit regex - string-substitute*, Unit regex
     7129@node Unit regex - regexp-escape,  , Unit regex - string-substitute*, Unit regex
    74237130@section regexp-escape
    74247131
     
    74287135@end verbatim
    74297136Escapes all special characters in @code{STRING} with @code{\}, so that the string can be embedded into a regular expression.
    7430 
    7431 @example
    7432 (regexp-escape @strong{"^[0-9]+:.*$"})
    7433 @strong{=>}  @strong{"\\^\\[0-9\\]\\+:.\n.\\*\\$"}
    7434 @end example
    7435 @node Unit regex - make-anchored-pattern,  , Unit regex - regexp-escape, Unit regex
    7436 @section make-anchored-pattern
    7437 
    7438 
    7439 @verbatim
    7440 [procedure] (make-anchored-pattern REGEXP [WITHOUT-BOL [WITHOUT-EOL]])
    7441 @end verbatim
    7442 Makes 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.
    7443 
    7444 The @code{WITHOUT-BOL} and @{WITHOUT-EOL@}@} arguments are ignored for a precompiled regular expression.
    74457137
    74467138Previous: @ref{Unit match, Unit match}
     
    80487740Temporarily 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.
    80497741
    8050 @example
    8051 (with-output-to-pipe
    8052   @strong{"gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"}
    8053   (@strong{lambda} ()
    8054     (print #<<EOF
    8055  %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@@xx.xxxxxx.xx.xx>
    8056  /C/neg/d/mul/R/rlineto/E/exp/H@{@{cvx def@}repeat@}def/T/dup/g/gt/r/roll/J/ifelse 8
    8057  H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
    8058  X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
    8059  F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
    8060  Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
    8061  ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
    8062  V1c&j2AYdjmMdjjd!o&1r!M)@{( )T 0 4 3 r put T(/)g@{T(9)g@{cvn@}@{cvi@}J@}@{($)g[]J@}J
    8063  cvx@}forall/moveto/p/floor/w/div/S/add 29 H[@{[@{]setgray fill@}for Y@}for showpage
    8064  EOF
    8065  ) ) )
    8066 @end example
    80677742@node Unit posix - Fifos, Unit posix - File descriptors and low-level I/O, Unit posix - Pipes, Unit posix
    80687743@section Fifos
     
    80847759Creates a FIFO with the name @code{FILENAME} and the permission bits @code{MODE}, which defaults to
    80857760
    8086 @example
    8087  [procedure] (+ perm/irwxu perm/irwxg perm/irwxo)
    8088 @end example
    80897761@node Unit posix - Fifos - fifo?,  , Unit posix - Fifos - create-fifo, Unit posix - Fifos
    80907762@subsection fifo?
     
    81537825Example usage:
    81547826
    8155 @example
    8156  (let-values (((fd temp-path) (file-mkstemp @strong{"/tmp/mytemporary.XXXXXX"})))
    8157   (@strong{let} ((temp-port (open-output-file* fd)))
    8158     (format temp-port @strong{"This file is ~A.~%"} temp-path)
    8159     (close-output-port temp-port)))
    8160 @end example
    81617827@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
    81627828@subsection file-read
     
    98229488@menu
    98239489* Unit utils - Environment Query::
    9824 * Unit utils - Pathname operations::
    9825 * Unit utils - Temporary files::
    9826 * Unit utils - Deleting a file without signalling an error::
    9827 * Unit utils - File move/copy::
    98289490* Unit utils - Iterating over input lines and files::
    98299491* Unit utils - Executing shell commands with formatstring and error checking::
     
    98339495
    98349496
    9835 This unit contains file/pathname oriented procedures, apropos, plus acts as a "grab bag" for procedures without a good home, and which don't have to be available by default (as compared to the @ref{Unit extras, extras} unit).
     9497This unit contains apropos and functions as a "grab bag" of procedures without a good home, and which don't have to be available by default (as compared to the @ref{Unit extras, extras} unit).
    98369498
    98379499This unit uses the @code{extras} and @code{regex} units.
    98389500
    9839 @node Unit utils - Environment Query, Unit utils - Pathname operations,  , Unit utils
     9501@node Unit utils - Environment Query, Unit utils - Iterating over input lines and files,  , Unit utils
    98409502@section Environment Query
    98419503
     
    98779539Like @code{apropos} but returns a list of matching symbols.
    98789540
    9879 @node Unit utils - Pathname operations, Unit utils - Temporary files, Unit utils - Environment Query, Unit utils
    9880 @section Pathname operations
    9881 
    9882 @menu
    9883 * Unit utils - Pathname operations - absolute-pathname?::
    9884 * Unit utils - Pathname operations - decompose-pathname::
    9885 * Unit utils - Pathname operations - make-pathname::
    9886 * Unit utils - Pathname operations - make-absolute-pathname::
    9887 * Unit utils - Pathname operations - pathname-directory::
    9888 * Unit utils - Pathname operations - pathname-file::
    9889 * Unit utils - Pathname operations - pathname-extension::
    9890 * Unit utils - Pathname operations - pathname-replace-directory::
    9891 * Unit utils - Pathname operations - pathname-replace-file::
    9892 * Unit utils - Pathname operations - pathname-replace-extension::
    9893 * Unit utils - Pathname operations - pathname-strip-directory::
    9894 * Unit utils - Pathname operations - pathname-strip-extension::
    9895 * Unit utils - Pathname operations - directory-null?::
    9896 
    9897 @end menu
    9898 
    9899 
    9900 @node Unit utils - Pathname operations - absolute-pathname?, Unit utils - Pathname operations - decompose-pathname,  , Unit utils - Pathname operations
    9901 @subsection absolute-pathname?
    9902 
    9903 
    9904 @verbatim
    9905 [procedure] (absolute-pathname? PATHNAME)
    9906 @end verbatim
    9907 Returns @code{#t} if the string @code{PATHNAME} names an absolute pathname, and returns @code{#f} otherwise.
    9908 
    9909 @node Unit utils - Pathname operations - decompose-pathname, Unit utils - Pathname operations - make-pathname, Unit utils - Pathname operations - absolute-pathname?, Unit utils - Pathname operations
    9910 @subsection decompose-pathname
    9911 
    9912 
    9913 @verbatim
    9914 [procedure] (decompose-pathname PATHNAME)
    9915 @end verbatim
    9916 Returns three values: the directory-, filename- and extension-components of the file named by the string @code{PATHNAME}. For any component that is not contained in @code{PATHNAME}, @code{#f} is returned.
    9917 
    9918 @node Unit utils - Pathname operations - make-pathname, Unit utils - Pathname operations - make-absolute-pathname, Unit utils - Pathname operations - decompose-pathname, Unit utils - Pathname operations
    9919 @subsection make-pathname
    9920 
    9921 
    9922 @node Unit utils - Pathname operations - make-absolute-pathname, Unit utils - Pathname operations - pathname-directory, Unit utils - Pathname operations - make-pathname, Unit utils - Pathname operations
    9923 @subsection make-absolute-pathname
    9924 
    9925 
    9926 @verbatim
    9927 [procedure] (make-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
    9928 [procedure] (make-absolute-pathname DIRECTORY FILENAME [EXTENSION [SEPARATOR]])
    9929 @end verbatim
    9930 Returns a string that names the file with the components @code{DIRECTORY, FILENAME} and (optionally) @code{EXTENSION} with @code{SEPARATOR} being the directory separation indicator (usually @code{/} on UNIX systems and @code{\} on Windows, defaulting to whatever platform this is running on).  @code{DIRECTORY} can be @code{#f} (meaning no directory component), a string or a list of strings. @code{FILENAME} and @code{EXTENSION} should be strings or @code{#f}. @code{make-absolute-pathname} returns always an absolute pathname.
    9931 
    9932 @node Unit utils - Pathname operations - pathname-directory, Unit utils - Pathname operations - pathname-file, Unit utils - Pathname operations - make-absolute-pathname, Unit utils - Pathname operations
    9933 @subsection pathname-directory
    9934 
    9935 
    9936 @verbatim
    9937 [procedure] (pathname-directory PATHNAME)
    9938 @end verbatim
    9939 @node Unit utils - Pathname operations - pathname-file, Unit utils - Pathname operations - pathname-extension, Unit utils - Pathname operations - pathname-directory, Unit utils - Pathname operations
    9940 @subsection pathname-file
    9941 
    9942 
    9943 @verbatim
    9944 [procedure] (pathname-file PATHNAME)
    9945 @end verbatim
    9946 @node Unit utils - Pathname operations - pathname-extension, Unit utils - Pathname operations - pathname-replace-directory, Unit utils - Pathname operations - pathname-file, Unit utils - Pathname operations
    9947 @subsection pathname-extension
    9948 
    9949 
    9950 @verbatim
    9951 [procedure] (pathname-extension PATHNAME)
    9952 @end verbatim
    9953 Accessors for the components of @code{PATHNAME}. If the pathname does not contain the accessed component, then @code{#f} is returned.
    9954 
    9955 @node Unit utils - Pathname operations - pathname-replace-directory, Unit utils - Pathname operations - pathname-replace-file, Unit utils - Pathname operations - pathname-extension, Unit utils - Pathname operations
    9956 @subsection pathname-replace-directory
    9957 
    9958 
    9959 @verbatim
    9960 [procedure] (pathname-replace-directory PATHNAME DIRECTORY)
    9961 @end verbatim
    9962 @node Unit utils - Pathname operations - pathname-replace-file, Unit utils - Pathname operations - pathname-replace-extension, Unit utils - Pathname operations - pathname-replace-directory, Unit utils - Pathname operations
    9963 @subsection pathname-replace-file
    9964 
    9965 
    9966 @verbatim
    9967 [procedure] (pathname-replace-file PATHNAME FILENAME)
    9968 @end verbatim
    9969 @node Unit utils - Pathname operations - pathname-replace-extension, Unit utils - Pathname operations - pathname-strip-directory, Unit utils - Pathname operations - pathname-replace-file, Unit utils - Pathname operations
    9970 @subsection pathname-replace-extension
    9971 
    9972 
    9973 @verbatim
    9974 [procedure] (pathname-replace-extension PATHNAME EXTENSION)
    9975 @end verbatim
    9976 Return a new pathname with the specified component of @code{PATHNAME} replaced by a new value.
    9977 
    9978 @node Unit utils - Pathname operations - pathname-strip-directory, Unit utils - Pathname operations - pathname-strip-extension, Unit utils - Pathname operations - pathname-replace-extension, Unit utils - Pathname operations
    9979 @subsection pathname-strip-directory
    9980 
    9981 
    9982 @verbatim
    9983 [procedure] (pathname-strip-directory PATHNAME)
    9984 @end verbatim
    9985 @node Unit utils - Pathname operations - pathname-strip-extension, Unit utils - Pathname operations - directory-null?, Unit utils - Pathname operations - pathname-strip-directory, Unit utils - Pathname operations
    9986 @subsection pathname-strip-extension
    9987 
    9988 
    9989 @verbatim
    9990 [procedure] (pathname-strip-extension PATHNAME)
    9991 @end verbatim
    9992 Return a new pathname with the specified component of @code{PATHNAME} stripped.
    9993 
    9994 @node Unit utils - Pathname operations - directory-null?,  , Unit utils - Pathname operations - pathname-strip-extension, Unit utils - Pathname operations
    9995 @subsection directory-null?
    9996 
    9997 
    9998 @verbatim
    9999 [procedure] (directory-null? DIRECTORY)
    10000 @end verbatim
    10001 Does the @code{DIRECTORY} consist only of path separators and the period?
    10002 
    10003 @code{DIRECTORY} may be a string or a list of strings.
    10004 
    10005 @node Unit utils - Temporary files, Unit utils - Deleting a file without signalling an error, Unit utils - Pathname operations, Unit utils
    10006 @section Temporary files
    10007 
    10008 @menu
    10009 * Unit utils - Temporary files - create-temporary-file::
    10010 
    10011 @end menu
    10012 
    10013 
    10014 @node Unit utils - Temporary files - create-temporary-file,  ,  , Unit utils - Temporary files
    10015 @subsection create-temporary-file
    10016 
    10017 
    10018 @verbatim
    10019 [procedure] (create-temporary-file [EXTENSION])
    10020 @end verbatim
    10021 Creates an empty temporary file and returns its pathname. If @code{EXTENSION} is not given, then @code{.tmp} is used. If the environment variable @code{TMPDIR, TEMP} or @code{TMP} is set, then the pathname names a file in that directory.
    10022 
    10023 @node Unit utils - Deleting a file without signalling an error, Unit utils - File move/copy, Unit utils - Temporary files, Unit utils
    10024 @section Deleting a file without signalling an error
    10025 
    10026 @menu
    10027 * Unit utils - Deleting a file without signalling an error - delete-file*::
    10028 
    10029 @end menu
    10030 
    10031 
    10032 @node Unit utils - Deleting a file without signalling an error - delete-file*,  ,  , Unit utils - Deleting a file without signalling an error
    10033 @subsection delete-file*
    10034 
    10035 
    10036 @verbatim
    10037 [procedure] (delete-file* FILENAME)
    10038 @end verbatim
    10039 If the file @code{FILENAME} exists, it is deleted and @code{#t} is returned.  If the file does not exist, nothing happens and @code{#f} is returned.
    10040 
    10041 @node Unit utils - File move/copy, Unit utils - Iterating over input lines and files, Unit utils - Deleting a file without signalling an error, Unit utils
    10042 @section File move/copy
    10043 
    10044 @menu
    10045 * Unit utils - File move/copy - file-copy::
    10046 * Unit utils - File move/copy - file-move::
    10047 
    10048 @end menu
    10049 
    10050 
    10051 @node Unit utils - File move/copy - file-copy, Unit utils - File move/copy - file-move,  , Unit utils - File move/copy
    10052 @subsection file-copy
    10053 
    10054 
    10055 @verbatim
    10056 [procedure] (file-copy ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
    10057 @end verbatim
    10058 Copies @code{ORIGFILE} (a string denoting some filename) to @code{NEWFILE},  @code{BLOCKSIZE} bytes at a time.  @code{BLOCKSIZE} defaults to 1024, and must be a positive integer.  Returns the number of bytes copied on success, or errors on failure.  @code{CLOBBER} determines the behaviour of @code{file-copy} when @code{NEWFILE} is already extant.  When set to @code{#f} (default), an error is signalled.  When set to any other value, @code{NEWFILE} is overwritten. @code{file-copy} will work across filesystems and devices and is not platform-dependent.
    10059 
    10060 @node Unit utils - File move/copy - file-move,  , Unit utils - File move/copy - file-copy, Unit utils - File move/copy
    10061 @subsection file-move
    10062 
    10063 
    10064 @verbatim
    10065 [procedure] (file-move ORIGFILE NEWFILE #!optional CLOBBER BLOCKSIZE)
    10066 @end verbatim
    10067 Moves @code{ORIGFILE} (a string denoting some filename) to @code{NEWFILE}, with the same semantics as @code{file-copy}, above.  @code{file-move} is safe across filesystems and devices (unlike @code{file-rename}).  It is possible for an error to be signalled despite partial success if @code{NEWFILE} could be created and fully written but removing @code{ORIGFILE} fails.
    10068 
    10069 @node Unit utils - Iterating over input lines and files, Unit utils - Executing shell commands with formatstring and error checking, Unit utils - File move/copy, Unit utils
     9541@node Unit utils - Iterating over input lines and files, Unit utils - Executing shell commands with formatstring and error checking, Unit utils - Environment Query, Unit utils
    100709542@section Iterating over input lines and files
    100719543
     
    100979569This code will act as a simple Unix cat(1) command:
    100989570
    10099 @example
    10100 (for-each-argv-line print)
    10101 @end example
    101029571@node Unit utils - Executing shell commands with formatstring and error checking, Unit utils - Reading a file's contents, Unit utils - Iterating over input lines and files, Unit utils
    101039572@section Executing shell commands with formatstring and error checking
     
    103299798A very simple example follows. Say we have the two files @code{client.scm} and @code{server.scm}:
    103309799
    10331 @example
    10332 @emph{; client.scm
    10333 }(declare (uses tcp))
    10334 (define-values (i o) (tcp-connect @strong{"localhost"} 4242))
    10335 (write-line @strong{"Good Bye!"} o)
    10336 (print (read-line i))
    10337 @end example
    10338 @example
    10339 @emph{; server.scm
    10340 }(declare (uses tcp))
    10341 (@strong{define} @strong{l} (tcp-listen 4242))
    10342 (define-values (i o) (tcp-accept l))
    10343 (write-line @strong{"Hello!"} o)
    10344 (print (read-line i))
    10345 (close-input-port i)
    10346 (close-output-port o)
    10347 @end example
    103489800@verbatim
    103499801% csc server.scm
     
    103639815@menu
    103649816* Unit lolevel - Foreign pointers::
     9817* Unit lolevel - SRFI-4 Foreign pointers::
    103659818* Unit lolevel - Tagged pointers::
     9819* Unit lolevel - Locatives::
    103669820* Unit lolevel - Extending procedures with data::
     9821* Unit lolevel - Low-level data access::
    103679822* Unit lolevel - Data in unmanaged memory::
    10368 * Unit lolevel - Locatives::
    103699823* Unit lolevel - Accessing toplevel variables::
    10370 * Unit lolevel - Low-level data access::
     9824* Unit lolevel - Record instance::
    103719825* Unit lolevel - Procedure-call- and variable reference hooks::
    103729826* Unit lolevel - Magic::
     
    103799833This unit uses the @code{srfi-4} and @code{extras} units.
    103809834
    10381 @node Unit lolevel - Foreign pointers, Unit lolevel - Tagged pointers,  , Unit lolevel
     9835@node Unit lolevel - Foreign pointers, Unit lolevel - SRFI-4 Foreign pointers,  , Unit lolevel
    103829836@section Foreign pointers
    103839837
     
    103899843* Unit lolevel - Foreign pointers - null-pointer?::
    103909844* Unit lolevel - Foreign pointers - object->pointer::
     9845* Unit lolevel - Foreign pointers - pointer->object::
    103919846* Unit lolevel - Foreign pointers - pointer?::
     9847* Unit lolevel - Foreign pointers - pointer-like?::
    103929848* Unit lolevel - Foreign pointers - pointer=?::
    103939849* Unit lolevel - Foreign pointers - pointer->address::
    10394 * Unit lolevel - Foreign pointers - pointer->object::
    103959850* Unit lolevel - Foreign pointers - pointer-offset::
    10396 * Unit lolevel - Foreign pointers - pointer-u8-ref::
    10397 * Unit lolevel - Foreign pointers - pointer-s8-ref::
    10398 * Unit lolevel - Foreign pointers - pointer-u16-ref::
    10399 * Unit lolevel - Foreign pointers - pointer-s16-ref::
    10400 * Unit lolevel - Foreign pointers - pointer-u32-ref::
    10401 * Unit lolevel - Foreign pointers - pointer-s32-ref::
    10402 * Unit lolevel - Foreign pointers - pointer-f32-ref::
    10403 * Unit lolevel - Foreign pointers - pointer-f64-ref::
    10404 * Unit lolevel - Foreign pointers - pointer-u8-set!::
    10405 * Unit lolevel - Foreign pointers - pointer-s8-set!::
    10406 * Unit lolevel - Foreign pointers - pointer-u16-set!::
    10407 * Unit lolevel - Foreign pointers - pointer-s16-set!::
    10408 * Unit lolevel - Foreign pointers - pointer-u32-set!::
    10409 * Unit lolevel - Foreign pointers - pointer-s32-set!::
    10410 * Unit lolevel - Foreign pointers - pointer-f32-set!::
    10411 * Unit lolevel - Foreign pointers - pointer-f64-set!::
    104129851* Unit lolevel - Foreign pointers - align-to-word::
    104139852
    104149853@end menu
    104159854
     9855
     9856The abstract class of @emph{pointer} is divided into 2 categories:
     9857
     9858@table @b
     9859@item @emph{pointer object}
     9860
     9861is a foreign pointer object, a tagged foreign pointer object (see @code{Tagged pointers}), or a SWIG-pointer.
     9862@item @emph{pointer-like object} " is a closure, port, locative (see @code{Locatives}, or a pointer object.
     9863
     9864
     9865
     9866@end table
     9867SWIG-pointers are currently an issue due to "bitrot" in the SWIG Chicken translator. While they are considered a pointer object unexpected results are possible.
     9868
     9869Note that Locatives, while technically pointers, are not considered a @emph{pointer object}, but a @emph{pointer-like object}. The distinction is artificial.
    104169870
    104179871@node Unit lolevel - Foreign pointers - address->pointer, Unit lolevel - Foreign pointers - allocate,  , Unit lolevel - Foreign pointers
     
    104319885[procedure] (allocate BYTES)
    104329886@end verbatim
    10433 Returns a pointer to a freshly allocated region of static memory. This procedure could be defined as follows:
    10434 
    10435 @example
    10436 (@strong{define} @strong{allocate} (foreign-lambda c-pointer @strong{"malloc"} integer))
    10437 @end example
     9887Returns a foreign pointer object to a freshly allocated region of static memory.
     9888
     9889This procedure could be defined as follows:
     9890
    104389891@node Unit lolevel - Foreign pointers - free, Unit lolevel - Foreign pointers - null-pointer, Unit lolevel - Foreign pointers - allocate, Unit lolevel - Foreign pointers
    104399892@subsection free
     
    104439896[procedure] (free POINTER)
    104449897@end verbatim
    10445 Frees the memory pointed to by @code{POINTER}.  This procedure could be defined as follows:
    10446 
    10447 @example
    10448 (@strong{define} @strong{free} (foreign-lambda c-pointer @strong{"free"} integer))
    10449 @end example
     9898Frees the memory pointed to by @code{POINTER}.
     9899
     9900This procedure could be defined as follows:
     9901
    104509902@node Unit lolevel - Foreign pointers - null-pointer, Unit lolevel - Foreign pointers - null-pointer?, Unit lolevel - Foreign pointers - free, Unit lolevel - Foreign pointers
    104519903@subsection null-pointer
     
    104629914
    104639915@verbatim
    10464 [procedure] (null-pointer? PTR)
    10465 @end verbatim
    10466 Returns @code{#t} if @code{PTR} contains a @code{NULL} pointer, or @code{#f} otherwise.
    10467 
    10468 @node Unit lolevel - Foreign pointers - object->pointer, Unit lolevel - Foreign pointers - pointer?, Unit lolevel - Foreign pointers - null-pointer?, Unit lolevel - Foreign pointers
     9916[procedure] (null-pointer? POINTER*)
     9917@end verbatim
     9918Returns @code{#t} if the pointer-like object @code{POINTER*} contains a @code{NULL} pointer, or @code{#f} otherwise.
     9919
     9920@node Unit lolevel - Foreign pointers - object->pointer, Unit lolevel - Foreign pointers - pointer->object, Unit lolevel - Foreign pointers - null-pointer?, Unit lolevel - Foreign pointers
    104699921@subsection object->pointer
    104709922
     
    104739925[procedure] (object->pointer X)
    104749926@end verbatim
    10475 Returns a pointer pointing to the Scheme object X, which should be a non-immediate object.  Note that data in the garbage collected heap moves during garbage collection.
    10476 
    10477 @node Unit lolevel - Foreign pointers - pointer?, Unit lolevel - Foreign pointers - pointer=?, Unit lolevel - Foreign pointers - object->pointer, Unit lolevel - Foreign pointers
     9927Returns a foreign pointer object pointing to the Scheme object X, which should be a non-immediate object. ("foreign" here is a bit of a misnomer.)
     9928
     9929Note that data in the garbage collected heap moves during garbage collection.
     9930
     9931@node Unit lolevel - Foreign pointers - pointer->object, Unit lolevel - Foreign pointers - pointer?, Unit lolevel - Foreign pointers - object->pointer, Unit lolevel - Foreign pointers
     9932@subsection pointer->object
     9933
     9934
     9935@verbatim
     9936[procedure] (pointer->object POINTER)
     9937@end verbatim
     9938Returns the Scheme object pointed to by the pointer object @code{POINTER}.
     9939
     9940Whether the @code{POINTER} actually points to a Scheme object is not guaranteed. Use at your own risk.
     9941
     9942@node Unit lolevel - Foreign pointers - pointer?, Unit lolevel - Foreign pointers - pointer-like?, Unit lolevel - Foreign pointers - pointer->object, Unit lolevel - Foreign pointers
    104789943@subsection pointer?
    104799944
     
    104829947[procedure] (pointer? X)
    104839948@end verbatim
    10484 Returns @code{#t} if @code{X} is a foreign pointer object, and @code{#f} otherwise.
    10485 
    10486 @node Unit lolevel - Foreign pointers - pointer=?, Unit lolevel - Foreign pointers - pointer->address, Unit lolevel - Foreign pointers - pointer?, Unit lolevel - Foreign pointers
     9949Returns @code{#t} if @code{X} is a pointer object, or @code{#f} otherwise.
     9950
     9951@node Unit lolevel - Foreign pointers - pointer-like?, Unit lolevel - Foreign pointers - pointer=?, Unit lolevel - Foreign pointers - pointer?, Unit lolevel - Foreign pointers
     9952@subsection pointer-like?
     9953
     9954
     9955@verbatim
     9956[procedure] (pointer-like? X)
     9957@end verbatim
     9958Returns @code{#t} if @code{X} is a pointer-like object, or @code{#f} otherwise.
     9959
     9960@node Unit lolevel - Foreign pointers - pointer=?, Unit lolevel - Foreign pointers - pointer->address, Unit lolevel - Foreign pointers - pointer-like?, Unit lolevel - Foreign pointers
    104879961@subsection pointer=?
    104889962
    104899963
    104909964@verbatim
    10491 [procedure] (pointer=? PTR1 PTR2)
    10492 @end verbatim
    10493 Returns @code{#t} if the pointer-like objects @code{PTR1} and @code{PTR2} point to the same address.
    10494 
    10495 @node Unit lolevel - Foreign pointers - pointer->address, Unit lolevel - Foreign pointers - pointer->object, Unit lolevel - Foreign pointers - pointer=?, Unit lolevel - Foreign pointers
     9965[procedure] (pointer=? POINTER*1 POINTER*2)
     9966@end verbatim
     9967Returns @code{#t} if the pointer-like objects @code{POINTER*1} and @code{POINTER*2} point to the same address, or @code{#f} otherwise.
     9968
     9969@node Unit lolevel - Foreign pointers - pointer->address, Unit lolevel - Foreign pointers - pointer-offset, Unit lolevel - Foreign pointers - pointer=?, Unit lolevel - Foreign pointers
    104969970@subsection pointer->address
    104979971
    104989972
    104999973@verbatim
    10500 [procedure] (pointer->address PTR)
    10501 @end verbatim
    10502 Returns the address, to which the pointer @code{PTR} points.
    10503 
    10504 @node Unit lolevel - Foreign pointers - pointer->object, Unit lolevel - Foreign pointers - pointer-offset, Unit lolevel - Foreign pointers - pointer->address, Unit lolevel - Foreign pointers
    10505 @subsection pointer->object
    10506 
    10507 
    10508 @verbatim
    10509 [procedure] (pointer->object PTR)
    10510 @end verbatim
    10511 Returns the Scheme object pointed to by the pointer @code{PTR}.
    10512 
    10513 @node Unit lolevel - Foreign pointers - pointer-offset, Unit lolevel - Foreign pointers - pointer-u8-ref, Unit lolevel - Foreign pointers - pointer->object, Unit lolevel - Foreign pointers
     9974[procedure] (pointer->address POINTER*)
     9975@end verbatim
     9976Returns the address, to which the pointer-like object @code{POINTER*} points.
     9977
     9978@node Unit lolevel - Foreign pointers - pointer-offset, Unit lolevel - Foreign pointers - align-to-word, Unit lolevel - Foreign pointers - pointer->address, Unit lolevel - Foreign pointers
    105149979@subsection pointer-offset
    105159980
    105169981
    105179982@verbatim
    10518 [procedure] (pointer-offset PTR N)
    10519 @end verbatim
    10520 Returns a new pointer representing the pointer @code{PTR} increased by @code{N}.
    10521 
    10522 @node Unit lolevel - Foreign pointers - pointer-u8-ref, Unit lolevel - Foreign pointers - pointer-s8-ref, Unit lolevel - Foreign pointers - pointer-offset, Unit lolevel - Foreign pointers
     9983[procedure] (pointer-offset POINTER* N)
     9984@end verbatim
     9985Returns a new foreign pointer object representing the pointer-like object @code{POINTER*} address value increased by the byte-offset @code{N}.
     9986
     9987Use of anything other than a pointer object as an argument is questionable.
     9988
     9989@node Unit lolevel - Foreign pointers - align-to-word,  , Unit lolevel - Foreign pointers - pointer-offset, Unit lolevel - Foreign pointers
     9990@subsection align-to-word
     9991
     9992
     9993@verbatim
     9994[procedure] (align-to-word POINTER*-OR-INT)
     9995@end verbatim
     9996Accepts either a pointer-like object or an integer as the argument and returns a new foreign pointer or integer aligned to the native word size of the host platform.
     9997
     9998Use of anything other than an integer or pointer object as an argument is questionable.
     9999
     10000@node Unit lolevel - SRFI-4 Foreign pointers, Unit lolevel - Tagged pointers, Unit lolevel - Foreign pointers, Unit lolevel
     10001@section SRFI-4 Foreign pointers
     10002
     10003@menu
     10004* Unit lolevel - SRFI-4 Foreign pointers - pointer-u8-ref::
     10005* Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-ref::
     10006* Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-ref::
     10007* Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-ref::
     10008* Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-ref::
     10009* Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-ref::
     10010* Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-ref::
     10011* Unit lolevel - SRFI-4 Foreign pointers - pointer-f64-ref::
     10012* Unit lolevel - SRFI-4 Foreign pointers - pointer-u8-set!::
     10013* Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-set!::
     10014* Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-set!::
     10015* Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-set!::
     10016* Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-set!::
     10017* Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-set!::
     10018* Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-set!::
     10019* Unit lolevel - SRFI-4 Foreign pointers - pointer-f64-set!::
     10020
     10021@end menu
     10022
     10023
     10024These procedures actually accept a pointer-like object as the @code{POINTER} argument. However, as usual, use of anything other than a pointer object is questionable.
     10025
     10026@node Unit lolevel - SRFI-4 Foreign pointers - pointer-u8-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-ref,  , Unit lolevel - SRFI-4 Foreign pointers
    1052310027@subsection pointer-u8-ref
    1052410028
    1052510029
    1052610030@verbatim
    10527 [procedure] (pointer-u8-ref PTR)
    10528 @end verbatim
    10529 Returns the unsigned byte at the address designated by @code{PTR}.
    10530 
    10531 @node Unit lolevel - Foreign pointers - pointer-s8-ref, Unit lolevel - Foreign pointers - pointer-u16-ref, Unit lolevel - Foreign pointers - pointer-u8-ref, Unit lolevel - Foreign pointers
     10031[procedure] (pointer-u8-ref POINTER)
     10032@end verbatim
     10033Returns the unsigned byte at the address designated by @code{POINTER}.
     10034
     10035@node Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-u8-ref, Unit lolevel - SRFI-4 Foreign pointers
    1053210036@subsection pointer-s8-ref
    1053310037
    1053410038
    1053510039@verbatim
    10536 [procedure] (pointer-s8-ref PTR)
    10537 @end verbatim
    10538 Returns the signed byte at the address designated by @code{PTR}.
    10539 
    10540 @node Unit lolevel - Foreign pointers - pointer-u16-ref, Unit lolevel - Foreign pointers - pointer-s16-ref, Unit lolevel - Foreign pointers - pointer-s8-ref, Unit lolevel - Foreign pointers
     10040[procedure] (pointer-s8-ref POINTER)
     10041@end verbatim
     10042Returns the signed byte at the address designated by @code{POINTER}.
     10043
     10044@node Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-ref, Unit lolevel - SRFI-4 Foreign pointers
    1054110045@subsection pointer-u16-ref
    1054210046
    1054310047
    1054410048@verbatim
    10545 [procedure] (pointer-u16-ref PTR)
    10546 @end verbatim
    10547 Returns the unsigned 16-bit integer at the address designated by @code{PTR}.
    10548 
    10549 @node Unit lolevel - Foreign pointers - pointer-s16-ref, Unit lolevel - Foreign pointers - pointer-u32-ref, Unit lolevel - Foreign pointers - pointer-u16-ref, Unit lolevel - Foreign pointers
     10049[procedure] (pointer-u16-ref POINTER)
     10050@end verbatim
     10051Returns the unsigned 16-bit integer at the address designated by @code{POINTER}.
     10052
     10053@node Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-ref, Unit lolevel - SRFI-4 Foreign pointers
    1055010054@subsection pointer-s16-ref
    1055110055
    1055210056
    1055310057@verbatim
    10554 [procedure] (pointer-s16-ref PTR)
    10555 @end verbatim
    10556 Returns the signed 16-bit integer at the address designated by @code{PTR}.
    10557 
    10558 @node Unit lolevel - Foreign pointers - pointer-u32-ref, Unit lolevel - Foreign pointers - pointer-s32-ref, Unit lolevel - Foreign pointers - pointer-s16-ref, Unit lolevel - Foreign pointers
     10058[procedure] (pointer-s16-ref POINTER)
     10059@end verbatim
     10060Returns the signed 16-bit integer at the address designated by @code{POINTER}.
     10061
     10062@node Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-ref, Unit lolevel - SRFI-4 Foreign pointers
    1055910063@subsection pointer-u32-ref
    1056010064
    1056110065
    1056210066@verbatim
    10563 [procedure] (pointer-u32-ref PTR)
    10564 @end verbatim
    10565 Returns the unsigned 32-bit integer at the address designated by @code{PTR}.
    10566 
    10567 @node Unit lolevel - Foreign pointers - pointer-s32-ref, Unit lolevel - Foreign pointers - pointer-f32-ref, Unit lolevel - Foreign pointers - pointer-u32-ref, Unit lolevel - Foreign pointers
     10067[procedure] (pointer-u32-ref POINTER)
     10068@end verbatim
     10069Returns the unsigned 32-bit integer at the address designated by @code{POINTER}.
     10070
     10071@node Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-ref, Unit lolevel - SRFI-4 Foreign pointers
    1056810072@subsection pointer-s32-ref
    1056910073
    1057010074
    1057110075@verbatim
    10572 [procedure] (pointer-s32-ref PTR)
    10573 @end verbatim
    10574 Returns the signed 32-bit integer at the address designated by @code{PTR}.
    10575 
    10576 @node Unit lolevel - Foreign pointers - pointer-f32-ref, Unit lolevel - Foreign pointers - pointer-f64-ref, Unit lolevel - Foreign pointers - pointer-s32-ref, Unit lolevel - Foreign pointers
     10076[procedure] (pointer-s32-ref POINTER)
     10077@end verbatim
     10078Returns the signed 32-bit integer at the address designated by @code{POINTER}.
     10079
     10080@node Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-f64-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-ref, Unit lolevel - SRFI-4 Foreign pointers
    1057710081@subsection pointer-f32-ref
    1057810082
    1057910083
    1058010084@verbatim
    10581 [procedure] (pointer-f32-ref PTR)
    10582 @end verbatim
    10583 Returns the 32-bit float at the address designated by @code{PTR}.
    10584 
    10585 @node Unit lolevel - Foreign pointers - pointer-f64-ref, Unit lolevel - Foreign pointers - pointer-u8-set!, Unit lolevel - Foreign pointers - pointer-f32-ref, Unit lolevel - Foreign pointers
     10085[procedure] (pointer-f32-ref POINTER)
     10086@end verbatim
     10087Returns the 32-bit float at the address designated by @code{POINTER}.
     10088
     10089@node Unit lolevel - SRFI-4 Foreign pointers - pointer-f64-ref, Unit lolevel - SRFI-4 Foreign pointers - pointer-u8-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-ref, Unit lolevel - SRFI-4 Foreign pointers
    1058610090@subsection pointer-f64-ref
    1058710091
    1058810092
    1058910093@verbatim
    10590 [procedure] (pointer-f64-ref PTR)
    10591 @end verbatim
    10592 Returns the 64-bit double at the address designated by @code{PTR}.
    10593 
    10594 @node Unit lolevel - Foreign pointers - pointer-u8-set!, Unit lolevel - Foreign pointers - pointer-s8-set!, Unit lolevel - Foreign pointers - pointer-f64-ref, Unit lolevel - Foreign pointers
     10094[procedure] (pointer-f64-ref POINTER)
     10095@end verbatim
     10096Returns the 64-bit double at the address designated by @code{POINTER}.
     10097
     10098@node Unit lolevel - SRFI-4 Foreign pointers - pointer-u8-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-f64-ref, Unit lolevel - SRFI-4 Foreign pointers
    1059510099@subsection pointer-u8-set!
    1059610100
    1059710101
    1059810102@verbatim
    10599 [procedure] (pointer-u8-set! PTR N)
    10600 [procedure] (set! (pointer-u8-ref PTR) N)
    10601 @end verbatim
    10602 Stores the unsigned byte @code{N} at the address designated by @code{PTR}.
    10603 
    10604 @node Unit lolevel - Foreign pointers - pointer-s8-set!, Unit lolevel - Foreign pointers - pointer-u16-set!, Unit lolevel - Foreign pointers - pointer-u8-set!, Unit lolevel - Foreign pointers
     10103[procedure] (pointer-u8-set! POINTER N)
     10104[procedure] (set! (pointer-u8-ref POINTER) N)
     10105@end verbatim
     10106Stores the unsigned byte @code{N} at the address designated by @code{POINTER}.
     10107
     10108@node Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-u8-set!, Unit lolevel - SRFI-4 Foreign pointers
    1060510109@subsection pointer-s8-set!
    1060610110
    1060710111
    1060810112@verbatim
    10609 [procedure] (pointer-s8-set! PTR N)
    10610 [procedure] (set! (pointer-s8-ref PTR) N)
    10611 @end verbatim
    10612 Stores the signed byte @code{N} at the address designated by @code{PTR}.
    10613 
    10614 @node Unit lolevel - Foreign pointers - pointer-u16-set!, Unit lolevel - Foreign pointers - pointer-s16-set!, Unit lolevel - Foreign pointers - pointer-s8-set!, Unit lolevel - Foreign pointers
     10113[procedure] (pointer-s8-set! POINTER N)
     10114[procedure] (set! (pointer-s8-ref POINTER) N)
     10115@end verbatim
     10116Stores the signed byte @code{N} at the address designated by @code{POINTER}.
     10117
     10118@node Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-s8-set!, Unit lolevel - SRFI-4 Foreign pointers
    1061510119@subsection pointer-u16-set!
    1061610120
    1061710121
    1061810122@verbatim
    10619 [procedure] (pointer-u16-set! PTR N)
    10620 [procedure] (set! (pointer-u16-ref PTR) N)
    10621 @end verbatim
    10622 Stores the unsigned 16-bit integer @code{N} at the address designated by @code{PTR}.
    10623 
    10624 @node Unit lolevel - Foreign pointers - pointer-s16-set!, Unit lolevel - Foreign pointers - pointer-u32-set!, Unit lolevel - Foreign pointers - pointer-u16-set!, Unit lolevel - Foreign pointers
     10123[procedure] (pointer-u16-set! POINTER N)
     10124[procedure] (set! (pointer-u16-ref POINTER) N)
     10125@end verbatim
     10126Stores the unsigned 16-bit integer @code{N} at the address designated by @code{POINTER}.
     10127
     10128@node Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-u16-set!, Unit lolevel - SRFI-4 Foreign pointers
    1062510129@subsection pointer-s16-set!
    1062610130
    1062710131
    1062810132@verbatim
    10629 [procedure] (pointer-s16-set! PTR N)
    10630 [procedure] (set! (pointer-s16-ref PTR) N)
    10631 @end verbatim
    10632 Stores the signed 16-bit integer @code{N} at the address designated by @code{PTR}.
    10633 
    10634 @node Unit lolevel - Foreign pointers - pointer-u32-set!, Unit lolevel - Foreign pointers - pointer-s32-set!, Unit lolevel - Foreign pointers - pointer-s16-set!, Unit lolevel - Foreign pointers
     10133[procedure] (pointer-s16-set! POINTER N)
     10134[procedure] (set! (pointer-s16-ref POINTER) N)
     10135@end verbatim
     10136Stores the signed 16-bit integer @code{N} at the address designated by @code{POINTER}.
     10137
     10138@node Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-s16-set!, Unit lolevel - SRFI-4 Foreign pointers
    1063510139@subsection pointer-u32-set!
    1063610140
    1063710141
    1063810142@verbatim
    10639 [procedure] (pointer-u32-set! PTR N)
    10640 [procedure] (set! (pointer-u32-ref PTR) N)
    10641 @end verbatim
    10642 Stores the unsigned 32-bit integer @code{N} at the address designated by @code{PTR}.
    10643 
    10644 @node Unit lolevel - Foreign pointers - pointer-s32-set!, Unit lolevel - Foreign pointers - pointer-f32-set!, Unit lolevel - Foreign pointers - pointer-u32-set!, Unit lolevel - Foreign pointers
     10143[procedure] (pointer-u32-set! POINTER N)
     10144[procedure] (set! (pointer-u32-ref POINTER) N)
     10145@end verbatim
     10146Stores the unsigned 32-bit integer @code{N} at the address designated by @code{POINTER}.
     10147
     10148@node Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-u32-set!, Unit lolevel - SRFI-4 Foreign pointers
    1064510149@subsection pointer-s32-set!
    1064610150
    1064710151
    1064810152@verbatim
    10649 [procedure] (pointer-s32-set! PTR N)
    10650 [procedure] (set! (pointer-s32-ref PTR) N)
    10651 @end verbatim
    10652 Stores the 32-bit integer @code{N} at the address designated by @code{PTR}.
    10653 
    10654 @node Unit lolevel - Foreign pointers - pointer-f32-set!, Unit lolevel - Foreign pointers - pointer-f64-set!, Unit lolevel - Foreign pointers - pointer-s32-set!, Unit lolevel - Foreign pointers
     10153[procedure] (pointer-s32-set! POINTER N)
     10154[procedure] (set! (pointer-s32-ref POINTER) N)
     10155@end verbatim
     10156Stores the 32-bit integer @code{N} at the address designated by @code{POINTER}.
     10157
     10158@node Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-f64-set!, Unit lolevel - SRFI-4 Foreign pointers - pointer-s32-set!, Unit lolevel - SRFI-4 Foreign pointers
    1065510159@subsection pointer-f32-set!
    1065610160
    1065710161
    1065810162@verbatim
    10659 [procedure] (pointer-f32-set! PTR N)
    10660 [procedure] (set! (pointer-f32-ref PTR) N)
    10661 @end verbatim
    10662 Stores the 32-bit floating-point number @code{N} at the address designated by @code{PTR}.
    10663 
    10664 @node Unit lolevel - Foreign pointers - pointer-f64-set!, Unit lolevel - Foreign pointers - align-to-word, Unit lolevel - Foreign pointers - pointer-f32-set!, Unit lolevel - Foreign pointers
     10163[procedure] (pointer-f32-set! POINTER N)
     10164[procedure] (set! (pointer-f32-ref POINTER) N)
     10165@end verbatim
     10166Stores the 32-bit floating-point number @code{N} at the address designated by @code{POINTER}.
     10167
     10168@node Unit lolevel - SRFI-4 Foreign pointers - pointer-f64-set!,  , Unit lolevel - SRFI-4 Foreign pointers - pointer-f32-set!, Unit lolevel - SRFI-4 Foreign pointers
    1066510169@subsection pointer-f64-set!
    1066610170
    1066710171
    1066810172@verbatim
    10669 [procedure] (pointer-f64-set! PTR N)
    10670 [procedure] (set! (pointer-f64-ref PTR) N)
    10671 @end verbatim
    10672 Stores the 64-bit floating-point number @code{N} at the address designated by @code{PTR}.
    10673 
    10674 @node Unit lolevel - Foreign pointers - align-to-word,  , Unit lolevel - Foreign pointers - pointer-f64-set!, Unit lolevel - Foreign pointers
    10675 @subsection align-to-word
    10676 
    10677 
    10678 @verbatim
    10679 [procedure] (align-to-word PTR-OR-INT)
    10680 @end verbatim
    10681 Accepts either a machine pointer or an integer as argument and returns a new pointer or integer aligned to the native word size of the host platform.
    10682 
    10683 @node Unit lolevel - Tagged pointers, Unit lolevel - Extending procedures with data, Unit lolevel - Foreign pointers, Unit lolevel
     10173[procedure] (pointer-f64-set! POINTER N)
     10174[procedure] (set! (pointer-f64-ref POINTER) N)
     10175@end verbatim
     10176Stores the 64-bit floating-point number @code{N} at the address designated by @code{POINTER}.
     10177
     10178@node Unit lolevel - Tagged pointers, Unit lolevel - Locatives, Unit lolevel - SRFI-4 Foreign pointers, Unit lolevel
    1068410179@section Tagged pointers
    1068510180
     
    1069910194
    1070010195@verbatim
    10701 [procedure] (tag-pointer PTR TAG)
    10702 @end verbatim
    10703 Creates a new tagged pointer object from the foreign pointer @code{PTR} with the tag @code{TAG}, which may an arbitrary Scheme object.
     10196[procedure] (tag-pointer POINTER* TAG)
     10197@end verbatim
     10198Creates a new tagged foreign pointer object from the pointer-like object @code{POINTER*} with the tag @code{TAG}, which may an arbitrary Scheme object.
     10199
     10200Use of anything other than a pointer object is questionable.
    1070410201
    1070510202@node Unit lolevel - Tagged pointers - tagged-pointer?, Unit lolevel - Tagged pointers - pointer-tag, Unit lolevel - Tagged pointers - tag-pointer, Unit lolevel - Tagged pointers
     
    1070810205
    1070910206@verbatim
    10710 [procedure] (tagged-pointer? X TAG)
    10711 @end verbatim
    10712 Returns @code{#t}, if @code{X} is a tagged pointer object with the tag @code{TAG} (using an @code{eq?} comparison), or @code{#f} otherwise.
     10207[procedure] (tagged-pointer? X [TAG])
     10208@end verbatim
     10209Returns @code{#t} if @code{X} is a tagged foreign pointer object, or @code{#f} otherwise.
     10210
     10211Further, returns @code{#t} when @code{X} has the optional tag @code{TAG} (using an @code{equal?} comparison), or @code{#f} otherwise.
    1071310212
    1071410213@node Unit lolevel - Tagged pointers - pointer-tag,  , Unit lolevel - Tagged pointers - tagged-pointer?, Unit lolevel - Tagged pointers
     
    1071710216
    1071810217@verbatim
    10719 [procedure] (pointer-tag PTR)
    10720 @end verbatim
    10721 If @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.
    10722 
    10723 @node Unit lolevel - Extending procedures with data, Unit lolevel - Data in unmanaged memory, Unit lolevel - Tagged pointers, Unit lolevel
    10724 @section Extending procedures with data
    10725 
    10726 @menu
    10727 * Unit lolevel - Extending procedures with data - extend-procedure::
    10728 * Unit lolevel - Extending procedures with data - extended-procedure?::
    10729 * Unit lolevel - Extending procedures with data - procedure-data::
    10730 * Unit lolevel - Extending procedures with data - set-procedure-data!::
    10731 
    10732 @end menu
    10733 
    10734 
    10735 @node Unit lolevel - Extending procedures with data - extend-procedure, Unit lolevel - Extending procedures with data - extended-procedure?,  , Unit lolevel - Extending procedures with data
    10736 @subsection extend-procedure
    10737 
    10738 
    10739 @verbatim
    10740 [procedure] (extend-procedure PROCEDURE X)
    10741 @end verbatim
    10742 Returns a copy of the procedure @code{PROCEDURE} which contains an additional data slot initialized to @code{X}. If @code{PROCEDURE} is already an extended procedure, then its data slot is changed to contain @code{X} and the same procedure is returned.
    10743 
    10744 @node Unit lolevel - Extending procedures with data - extended-procedure?, Unit lolevel - Extending procedures with data - procedure-data, Unit lolevel - Extending procedures with data - extend-procedure, Unit lolevel - Extending procedures with data
    10745 @subsection extended-procedure?
    10746 
    10747 
    10748 @verbatim
    10749 [procedure] (extended-procedure? PROCEDURE)
    10750 @end verbatim
    10751 Returns @code{#t} if @code{PROCEDURE} is an extended procedure, or @code{#f} otherwise.
    10752 
    10753 @node Unit lolevel - Extending procedures with data - procedure-data, Unit lolevel - Extending procedures with data - set-procedure-data!, Unit lolevel - Extending procedures with data - extended-procedure?, Unit lolevel - Extending procedures with data
    10754 @subsection procedure-data
    10755 
    10756 
    10757 @verbatim
    10758 [procedure] (procedure-data PROCEDURE)
    10759 @end verbatim
    10760 Returns the data object contained in the extended procedure @code{PROCEDURE}, or @code{#f} if it is not an extended procedure.
    10761 
    10762 @node Unit lolevel - Extending procedures with data - set-procedure-data!,  , Unit lolevel - Extending procedures with data - procedure-data, Unit lolevel - Extending procedures with data
    10763 @subsection set-procedure-data!
    10764 
    10765 
    10766 @verbatim
    10767 [procedure] (set-procedure-data! PROCEDURE X)
    10768 @end verbatim
    10769 Changes the data object contained in the extended procedure @code{PROCEDURE} to @code{X}.
    10770 
    10771 @example
    10772 (@strong{define} @strong{foo}
    10773   (@strong{letrec} ((f (@strong{lambda} () (procedure-data x)))
    10774            (x #f) )
    10775     (@strong{set!} x (extend-procedure f 123))
    10776     x) )
    10777 (foo)                                         =@strong{=>} 123
    10778 (set-procedure-data! foo 'hello)
    10779 (foo)                                         =@strong{=>} hello
    10780 @end example
    10781 @node Unit lolevel - Data in unmanaged memory, Unit lolevel - Locatives, Unit lolevel - Extending procedures with data, Unit lolevel
    10782 @section Data in unmanaged memory
    10783 
    10784 @menu
    10785 * Unit lolevel - Data in unmanaged memory - object-evict::
    10786 * Unit lolevel - Data in unmanaged memory - object-evict-to-location::
    10787 * Unit lolevel - Data in unmanaged memory - object-evicted?::
    10788 * Unit lolevel - Data in unmanaged memory - object-size::
    10789 * Unit lolevel - Data in unmanaged memory - object-release::
    10790 * Unit lolevel - Data in unmanaged memory - object-unevict::
    10791 
    10792 @end menu
    10793 
    10794 
    10795 @node Unit lolevel - Data in unmanaged memory - object-evict, Unit lolevel - Data in unmanaged memory - object-evict-to-location,  , Unit lolevel - Data in unmanaged memory
    10796 @subsection object-evict
    10797 
    10798 
    10799 @verbatim
    10800 [procedure] (object-evict X [ALLOCATOR])
    10801 @end verbatim
    10802 Copies 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
    10803 
    10804 @example
    10805 (@strong{define} @strong{x} 'foo)
    10806 (@strong{define} @strong{y} (object-evict 'foo))
    10807 y                              =@strong{=>} foo
    10808 (eq? x y)                      =@strong{=>} #f
    10809 (@strong{define} @strong{z} (object-evict '(bar bar)))
    10810 (eq? (car z) (cadr z))         =@strong{=>} #t
    10811 @end example
    10812 The @code{ALLOCATOR} defaults to @code{allocate}.
    10813 
    10814 @node Unit lolevel - Data in unmanaged memory - object-evict-to-location, Unit lolevel - Data in unmanaged memory - object-evicted?, Unit lolevel - Data in unmanaged memory - object-evict, Unit lolevel - Data in unmanaged memory
    10815 @subsection object-evict-to-location
    10816 
    10817 
    10818 @verbatim
    10819 [procedure] (object-evict-to-location X PTR [LIMIT])
    10820 @end verbatim
    10821 As @code{object-evict} but moves the object at the address pointed to by the machine pointer @code{PTR}. If the number of copied bytes exceeds the optional @code{LIMIT} then an error is signalled (specifically a composite condition of types @code{exn} and @code{evict}. The latter provides a @code{limit} property which holds the exceeded limit. Two values are returned: the evicted object and a new pointer pointing to the first free address after the evicted object.
    10822 
    10823 @node Unit lolevel - Data in unmanaged memory - object-evicted?, Unit lolevel - Data in unmanaged memory - object-size, Unit lolevel - Data in unmanaged memory - object-evict-to-location, Unit lolevel - Data in unmanaged memory
    10824 @subsection object-evicted?
    10825 
    10826 
    10827 @verbatim
    10828 [procedure] (object-evicted? X)
    10829 @end verbatim
    10830 Returns @code{#t} if @code{X} is a non-immediate evicted data object, or @code{#f} otherwise.
    10831 
    10832 @node Unit lolevel - Data in unmanaged memory - object-size, Unit lolevel - Data in unmanaged memory - object-release, Unit lolevel - Data in unmanaged memory - object-evicted?, Unit lolevel - Data in unmanaged memory
    10833 @subsection object-size
    10834 
    10835 
    10836 @verbatim
    10837 [procedure] (object-size X)
    10838 @end verbatim
    10839 Returns the number of bytes that would be needed to evict the data object @code{X}.
    10840 
    10841 @node Unit lolevel - Data in unmanaged memory - object-release, Unit lolevel - Data in unmanaged memory - object-unevict, Unit lolevel - Data in unmanaged memory - object-size, Unit lolevel - Data in unmanaged memory
    10842 @subsection object-release
    10843 
    10844 
    10845 @verbatim
    10846 [procedure] (object-release X [RELEASER])
    10847 @end verbatim
    10848 Frees memory occupied by the evicted object @code{X} recursively. @code{RELEASER} should be a procedure of a single argument (a foreign pointer object to the static memory to be freed) and defaults to @code{free}.
    10849 
    10850 @node Unit lolevel - Data in unmanaged memory - object-unevict,  , Unit lolevel - Data in unmanaged memory - object-release, Unit lolevel - Data in unmanaged memory
    10851 @subsection object-unevict
    10852 
    10853 
    10854 @verbatim
    10855 [procedure] (object-unevict X [FULL])
    10856 @end verbatim
    10857 Copies the object @code{X} and nested objects back into the normal Scheme heap.  Symbols are re-interned into the symbol table. Strings and byte-vectors are @b{not} copied, unless @code{FULL} is given and not @code{#f}.
    10858 
    10859 @node Unit lolevel - Locatives, Unit lolevel - Accessing toplevel variables, Unit lolevel - Data in unmanaged memory, Unit lolevel
     10218[procedure] (pointer-tag POINTER*)
     10219@end verbatim
     10220If @code{POINTER} is a tagged foreign pointer object, its tag is returned. If @code{POINTER*} is any other kind of pointer-like object @code{#f} is returned. Otherwise an error is signalled.
     10221
     10222@node Unit lolevel - Locatives, Unit lolevel - Extending procedures with data, Unit lolevel - Tagged pointers, Unit lolevel
    1086010223@section Locatives
    1086110224
     
    1088010243
    1088110244@verbatim
    10882 [procedure] (make-locative EXP [INDEX])
    10883 @end verbatim
    10884 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, blob, SRFI-4 number-vector, or record. @code{INDEX} should be a fixnum. @code{INDEX} defaults to 0.
     10245[procedure] (make-locative OBJ [INDEX])
     10246@end verbatim
     10247Creates a locative that refers to the element of the non-immediate object @code{OBJ} at position @code{INDEX}. @code{OBJ} may be a vector, pair, string, blob, SRFI-4 number-vector, or record structure. @code{INDEX} should be a fixnum. @code{INDEX} defaults to 0.
    1088510248
    1088610249@node Unit lolevel - Locatives - make-weak-locative, Unit lolevel - Locatives - locative?, Unit lolevel - Locatives - make-locative, Unit lolevel - Locatives
     
    1088910252
    1089010253@verbatim
    10891 [procedure] (make-weak-locative EXP [INDEX])
     10254[procedure] (make-weak-locative OBJ [INDEX])
    1089210255@end verbatim
    1089310256Creates a @emph{weak} locative. Even though the locative refers to an element of a container object, the container object will still be reclaimed by garbage collection if no other references to it exist.
     
    1091110274Returns the element to which the locative @code{LOC} refers. If the containing object has been reclaimed by garbage collection, an error is signalled.
    1091210275
     10276@verbatim
     10277(locative-ref (make-locative "abc" 1)) ==> #\b
     10278@end verbatim
    1091310279@node Unit lolevel - Locatives - locative-set!, Unit lolevel - Locatives - locative->object, Unit lolevel - Locatives - locative-ref, Unit lolevel - Locatives
    1091410280@subsection locative-set!
     
    1093010296Returns the object that contains the element referred to by @code{LOC} or @code{#f} if the container has been reclaimed by garbage collection.
    1093110297
    10932 @node Unit lolevel - Accessing toplevel variables, Unit lolevel - Low-level data access, Unit lolevel - Locatives, Unit lolevel
     10298@verbatim
     10299(locative->object (make-locative "abc" 1)) ==> "abc"
     10300@end verbatim
     10301@node Unit lolevel - Extending procedures with data, Unit lolevel - Low-level data access, Unit lolevel - Locatives, Unit lolevel
     10302@section Extending procedures with data
     10303
     10304@menu
     10305* Unit lolevel - Extending procedures with data - extend-procedure::
     10306* Unit lolevel - Extending procedures with data - extended-procedure?::
     10307* Unit lolevel - Extending procedures with data - procedure-data::
     10308* Unit lolevel - Extending procedures with data - set-procedure-data!::
     10309
     10310@end menu
     10311
     10312
     10313@node Unit lolevel - Extending procedures with data - extend-procedure, Unit lolevel - Extending procedures with data - extended-procedure?,  , Unit lolevel - Extending procedures with data
     10314@subsection extend-procedure
     10315
     10316
     10317@verbatim
     10318[procedure] (extend-procedure PROCEDURE X)
     10319@end verbatim
     10320Returns a copy of the procedure @code{PROCEDURE} which contains an additional data slot initialized to @code{X}. If @code{PROCEDURE} is already an extended procedure, then its data slot is changed to contain @code{X} and the same procedure is returned. Signals an error when @code{PROCEDURE} is not a procedure.
     10321
     10322@node Unit lolevel - Extending procedures with data - extended-procedure?, Unit lolevel - Extending procedures with data - procedure-data, Unit lolevel - Extending procedures with data - extend-procedure, Unit lolevel - Extending procedures with data
     10323@subsection extended-procedure?
     10324
     10325
     10326@verbatim
     10327[procedure] (extended-procedure? PROCEDURE)
     10328@end verbatim
     10329Returns @code{#t} if @code{PROCEDURE} is an extended procedure, or @code{#f} otherwise.
     10330
     10331@node Unit lolevel - Extending procedures with data - procedure-data, Unit lolevel - Extending procedures with data - set-procedure-data!, Unit lolevel - Extending procedures with data - extended-procedure?, Unit lolevel - Extending procedures with data
     10332@subsection procedure-data
     10333
     10334
     10335@verbatim
     10336[procedure] (procedure-data PROCEDURE)
     10337@end verbatim
     10338Returns the data object contained in the extended procedure @code{PROCEDURE}, or @code{#f} if it is not an extended procedure.
     10339
     10340@node Unit lolevel - Extending procedures with data - set-procedure-data!,  , Unit lolevel - Extending procedures with data - procedure-data, Unit lolevel - Extending procedures with data
     10341@subsection set-procedure-data!
     10342
     10343
     10344@verbatim
     10345[procedure] (set-procedure-data! PROCEDURE X)
     10346@end verbatim
     10347Changes the data object contained in the extended procedure @code{PROCEDURE} to @code{X}. Signals an error when @code{PROCEDURE} is not an extended procedure.
     10348
     10349@node Unit lolevel - Low-level data access, Unit lolevel - Data in unmanaged memory, Unit lolevel - Extending procedures with data, Unit lolevel
     10350@section Low-level data access
     10351
     10352@menu
     10353* Unit lolevel - Low-level data access - vector-like?::
     10354* Unit lolevel - Low-level data access - block-ref::
     10355* Unit lolevel - Low-level data access - block-set!::
     10356* Unit lolevel - Low-level data access - number-of-slots::
     10357* Unit lolevel - Low-level data access - number-of-bytes::
     10358* Unit lolevel - Low-level data access - object-copy::
     10359* Unit lolevel - Low-level data access - move-memory!::
     10360
     10361@end menu
     10362
     10363
     10364These procedures operate with what are known as @code{vector-like objects}. A @code{vector-like object} is a vector, record structure, pair, symbol or keyword.
     10365
     10366Note that strings and blobs are not considered vector-like.
     10367
     10368@node Unit lolevel - Low-level data access - vector-like?, Unit lolevel - Low-level data access - block-ref,  , Unit lolevel - Low-level data access
     10369@subsection vector-like?
     10370
     10371
     10372@verbatim
     10373[procedure] (vector-like? X)
     10374@end verbatim
     10375Returns @code{#t} when @code{X} is a vector-like object, returns @code{#f} otherwise.
     10376
     10377@node Unit lolevel - Low-level data access - block-ref, Unit lolevel - Low-level data access - block-set!, Unit lolevel - Low-level data access - vector-like?, Unit lolevel - Low-level data access
     10378@subsection block-ref
     10379
     10380
     10381@verbatim
     10382[procedure] (block-ref VECTOR* INDEX)
     10383@end verbatim
     10384Returns the contents of the @code{INDEX}th slot of the vector-like object @code{VECTOR*}.
     10385
     10386@node Unit lolevel - Low-level data access - block-set!, Unit lolevel - Low-level data access - number-of-slots, Unit lolevel - Low-level data access - block-ref, Unit lolevel - Low-level data access
     10387@subsection block-set!
     10388
     10389
     10390@verbatim
     10391[procedure] (block-set! VECTOR* INDEX X)
     10392[procedure] (set! (block-ref VECTOR* INDEX) X)
     10393@end verbatim
     10394Sets the contents of the @code{INDEX}th slot of the vector-like object @code{VECTOR*} to the value of @code{X}.
     10395
     10396@node Unit lolevel - Low-level data access - number-of-slots, Unit lolevel - Low-level data access - number-of-bytes, Unit lolevel - Low-level data access - block-set!, Unit lolevel - Low-level data access
     10397@subsection number-of-slots
     10398
     10399
     10400@verbatim
     10401[procedure] (number-of-slots VECTOR*)
     10402@end verbatim
     10403Returns the number of slots that the vector-like object @code{VECTOR*} contains.
     10404
     10405@node Unit lolevel - Low-level data access - number-of-bytes, Unit lolevel - Low-level data access - object-copy, Unit lolevel - Low-level data access - number-of-slots, Unit lolevel - Low-level data access
     10406@subsection number-of-bytes
     10407
     10408
     10409@verbatim
     10410[procedure] (number-of-bytes BLOCK)
     10411@end verbatim
     10412Returns the number of bytes that the object @code{BLOCK} contains. @code{BLOCK} may be any non-immediate value.
     10413
     10414@node Unit lolevel - Low-level data access - object-copy, Unit lolevel - Low-level data access - move-memory!, Unit lolevel - Low-level data access - number-of-bytes, Unit lolevel - Low-level data access
     10415@subsection object-copy
     10416
     10417
     10418@verbatim
     10419[procedure] (object-copy X)
     10420@end verbatim
     10421Copies @code{X} recursively and returns the fresh copy. Objects allocated in static memory are copied back into garbage collected storage.
     10422
     10423@node Unit lolevel - Low-level data access - move-memory!,  , Unit lolevel - Low-level data access - object-copy, Unit lolevel - Low-level data access
     10424@subsection move-memory!
     10425
     10426
     10427@verbatim
     10428[procedure] (move-memory! FROM TO [BYTES [FROM-OFFSET [TO-OFFSET]])
     10429@end verbatim
     10430Copies @code{BYTES} bytes of memory from @code{FROM} to @code{TO}. @code{FROM} and @code{TO} may be strings, blobs, SRFI-4 number-vectors (see: @@ref@{Unit srfi-4@}), memory mapped files, foreign pointers (as obtained from a call to @code{foreign-lambda}, for example), tagged-pointers or locatives. if @code{BYTES} is not given and the size of the source or destination operand is known then the maximal number of bytes will be copied. Moving memory to the storage returned by locatives will cause havoc, if the locative refers to containers of non-immediate data, like vectors or pairs.
     10431
     10432The additional fourth and fifth argument specify starting offsets (in bytes) for the source and destination arguments.
     10433
     10434Signals an error if any of the above constraints is violated.
     10435
     10436@node Unit lolevel - Data in unmanaged memory, Unit lolevel - Accessing toplevel variables, Unit lolevel - Low-level data access, Unit lolevel
     10437@section Data in unmanaged memory
     10438
     10439@menu
     10440* Unit lolevel - Data in unmanaged memory - object-evict::
     10441* Unit lolevel - Data in unmanaged memory - object-evict-to-location::
     10442* Unit lolevel - Data in unmanaged memory - object-evicted?::
     10443* Unit lolevel - Data in unmanaged memory - object-release::
     10444* Unit lolevel - Data in unmanaged memory - object-unevict::
     10445* Unit lolevel - Data in unmanaged memory - object-size::
     10446
     10447@end menu
     10448
     10449
     10450@node Unit lolevel - Data in unmanaged memory - object-evict, Unit lolevel - Data in unmanaged memory - object-evict-to-location,  , Unit lolevel - Data in unmanaged memory
     10451@subsection object-evict
     10452
     10453
     10454@verbatim
     10455[procedure] (object-evict X [ALLOCATOR])
     10456@end verbatim
     10457Copies 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.
     10458
     10459This 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
     10460
     10461The @code{ALLOCATOR} defaults to @code{allocate}.
     10462
     10463@node Unit lolevel - Data in unmanaged memory - object-evict-to-location, Unit lolevel - Data in unmanaged memory - object-evicted?, Unit lolevel - Data in unmanaged memory - object-evict, Unit lolevel - Data in unmanaged memory
     10464@subsection object-evict-to-location
     10465
     10466
     10467@verbatim
     10468[procedure] (object-evict-to-location X POINTER* [LIMIT])
     10469@end verbatim
     10470As @code{object-evict} but moves the object at the address pointed to by the pointer-like object @code{POINTER*}. If the number of copied bytes exceeds the optional @code{LIMIT} then an error is signalled (specifically a composite condition of types @code{exn} and @code{evict}. The latter provides a @code{limit} property which holds the exceeded limit. Two values are returned: the evicted object and a new pointer pointing to the first free address after the evicted object.
     10471
     10472Use of anything other than a pointer object as the @code{POINTER*} argument is questionable.
     10473
     10474@node Unit lolevel - Data in unmanaged memory - object-evicted?, Unit lolevel - Data in unmanaged memory - object-release, Unit lolevel - Data in unmanaged memory - object-evict-to-location, Unit lolevel - Data in unmanaged memory
     10475@subsection object-evicted?
     10476
     10477
     10478@verbatim
     10479[procedure] (object-evicted? X)
     10480@end verbatim
     10481Returns @code{#t} if @code{X} is a non-immediate evicted data object, or @code{#f} otherwise.
     10482
     10483@node Unit lolevel - Data in unmanaged memory - object-release, Unit lolevel - Data in unmanaged memory - object-unevict, Unit lolevel - Data in unmanaged memory - object-evicted?, Unit lolevel - Data in unmanaged memory
     10484@subsection object-release
     10485
     10486
     10487@verbatim
     10488[procedure] (object-release X [RELEASER])
     10489@end verbatim
     10490Frees memory occupied by the evicted object @code{X} recursively. @code{RELEASER} should be a procedure of a single argument (a foreign pointer object to the static memory to be freed) and defaults to @code{free}.
     10491
     10492@node Unit lolevel - Data in unmanaged memory - object-unevict, Unit lolevel - Data in unmanaged memory - object-size, Unit lolevel - Data in unmanaged memory - object-release, Unit lolevel - Data in unmanaged memory
     10493@subsection object-unevict
     10494
     10495
     10496@verbatim
     10497[procedure] (object-unevict X [FULL])
     10498@end verbatim
     10499Copies the object @code{X} and nested objects back into the normal Scheme heap. Symbols are re-interned into the symbol table. Strings and byte-vectors are @b{not} copied, unless @code{FULL} is given and not @code{#f}.
     10500
     10501@node Unit lolevel - Data in unmanaged memory - object-size,  , Unit lolevel - Data in unmanaged memory - object-unevict, Unit lolevel - Data in unmanaged memory
     10502@subsection object-size
     10503
     10504
     10505@verbatim
     10506[procedure] (object-size X)
     10507@end verbatim
     10508Returns the number of bytes that would be needed to evict the data object @code{X}.
     10509
     10510@node Unit lolevel - Accessing toplevel variables, Unit lolevel - Record instance, Unit lolevel - Data in unmanaged memory, Unit lolevel
    1093310511@section Accessing toplevel variables
    1093410512
     
    1097110549Sets the global variable named @code{SYMBOL} to the value @code{X}.
    1097210550
    10973 @node Unit lolevel - Low-level data access, Unit lolevel - Procedure-call- and variable reference hooks, Unit lolevel - Accessing toplevel variables, Unit lolevel
    10974 @section Low-level data access
    10975 
    10976 @menu
    10977 * Unit lolevel - Low-level data access - block-ref::
    10978 * Unit lolevel - Low-level data access - block-set!::
    10979 * Unit lolevel - Low-level data access - object-copy::
    10980 * Unit lolevel - Low-level data access - make-record-instance::
    10981 * Unit lolevel - Low-level data access - move-memory!::
    10982 * Unit lolevel - Low-level data access - number-of-bytes::
    10983 * Unit lolevel - Low-level data access - number-of-slots::
    10984 * Unit lolevel - Low-level data access - record-instance?::
    10985 * Unit lolevel - Low-level data access - record->vector::
    10986 
    10987 @end menu
    10988 
    10989 
    10990 @node Unit lolevel - Low-level data access - block-ref, Unit lolevel - Low-level data access - block-set!,  , Unit lolevel - Low-level data access
    10991 @subsection block-ref
    10992 
    10993 
    10994 @verbatim
    10995 [procedure] (block-ref BLOCK INDEX)
    10996 @end verbatim
    10997 Returns the contents of the @code{INDEX}th slot of the object @code{BLOCK}.  @code{BLOCK} may be a vector, record structure, pair or symbol.
    10998 
    10999 @node Unit lolevel - Low-level data access - block-set!, Unit lolevel - Low-level data access - object-copy, Unit lolevel - Low-level data access - block-ref, Unit lolevel - Low-level data access
    11000 @subsection block-set!
    11001 
    11002 
    11003 @verbatim
    11004 [procedure] (block-set! BLOCK INDEX X)
    11005 [procedure] (set! (block-ref BLOCK INDEX) X)
    11006 @end verbatim
    11007 Sets the contents of the @code{INDEX}th slot of the object @code{BLOCK} to the value of @code{X}.  @code{BLOCK} may be a vector, record structure, pair or symbol.
    11008 
    11009 @node Unit lolevel - Low-level data access - object-copy, Unit lolevel - Low-level data access - make-record-instance, Unit lolevel - Low-level data access - block-set!, Unit lolevel - Low-level data access
    11010 @subsection object-copy
    11011 
    11012 
    11013 @verbatim
    11014 [procedure] (object-copy X)
    11015 @end verbatim
    11016 Copies @code{X} recursively and returns the fresh copy. Objects allocated in static memory are copied back into garbage collected storage.
    11017 
    11018 @node Unit lolevel - Low-level data access - make-record-instance, Unit lolevel - Low-level data access - move-memory!, Unit lolevel - Low-level data access - object-copy, Unit lolevel - Low-level data access
     10551@node Unit lolevel - Record instance, Unit lolevel - Procedure-call- and variable reference hooks, Unit lolevel - Accessing toplevel variables, Unit lolevel
     10552@section Record instance
     10553
     10554@menu
     10555* Unit lolevel - Record instance - make-record-instance::
     10556* Unit lolevel - Record instance - record-instance?::
     10557* Unit lolevel - Record instance - record-instance-type::
     10558* Unit lolevel - Record instance - record-instance-length::
     10559* Unit lolevel - Record instance - record-instance-slot::
     10560* Unit lolevel - Record instance - record-instance-slot-set!::
     10561* Unit lolevel - Record instance - record->vector::
     10562
     10563@end menu
     10564
     10565
     10566@node Unit lolevel - Record instance - make-record-instance, Unit lolevel - Record instance - record-instance?,  , Unit lolevel - Record instance
    1101910567@subsection make-record-instance
    1102010568
     
    1102310571[procedure] (make-record-instance SYMBOL ARG1 ...)
    1102410572@end verbatim
    11025 Returns a new instance of the record type @code{SYMBOL}, with its slots initialized to @code{ARG1 ...}.  To illustrate:
    11026 
    11027 @example
    11028 (define-record point x y)
    11029 @end example
     10573Returns a new instance of a record structure of type @code{SYMBOL}, with its slots initialized to @code{ARG1 ...}.
     10574
     10575To illustrate:
     10576
    1103010577expands into something quite similar to:
    1103110578
    11032 @example
    11033 (@strong{begin}
    11034   (@strong{define} (@strong{make-point} x y)
    11035     (make-record-instance 'point x y) )
    11036   (@strong{define} (@strong{point?} x)
    11037     (@strong{and} (record-instance? x)
    11038          (eq? 'point (block-ref x 0)) ) )
    11039   (@strong{define} (@strong{point-x} p) (block-ref p 1))
    11040   (@strong{define} (@strong{point-x-set!} p x) (block-set! p 1 x))
    11041   (@strong{define} (@strong{point-y} p) (block-ref p 2))
    11042   (@strong{define} (@strong{point-y-set!} p y) (block-set! p 1 y)) )
    11043 @end example
    11044 @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
    11045 @subsection move-memory!
    11046 
    11047 
    11048 @verbatim
    11049 [procedure] (move-memory! FROM TO [BYTES [FROM-OFFSET [TO-OFFSET]])
    11050 @end verbatim
    11051 Copies @code{BYTES} bytes of memory from @code{FROM} to @code{TO}. @code{FROM} and @code{TO} may be strings, primitive byte-vectors, SRFI-4 byte-vectors (see: @@ref@{Unit srfi-4@}), memory mapped files, foreign pointers (as obtained from a call to @code{foreign-lambda}, for example) or locatives. if @code{BYTES} is not given and the size of the source or destination operand is known then the maximal number of bytes will be copied. Moving memory to the storage returned by locatives will cause havoc,  if the locative refers to containers of non-immediate data, like vectors or pairs.
    11052 
    11053 The additional fourth and fifth argument specify starting offsets  (in bytes) for the source and destination arguments.
    11054 
    11055 @node Unit lolevel - Low-level data access - number-of-bytes, Unit lolevel - Low-level data access - number-of-slots, Unit lolevel - Low-level data access - move-memory!, Unit lolevel - Low-level data access
    11056 @subsection number-of-bytes
    11057 
    11058 
    11059 @verbatim
    11060 [procedure] (number-of-bytes BLOCK)
    11061 @end verbatim
    11062 Returns the number of bytes that the object @code{BLOCK} contains. @code{BLOCK} may be any non-immediate value.
    11063 
    11064 @node Unit lolevel - Low-level data access - number-of-slots, Unit lolevel - Low-level data access - record-instance?, Unit lolevel - Low-level data access - number-of-bytes, Unit lolevel - Low-level data access
    11065 @subsection number-of-slots
    11066 
    11067 
    11068 @verbatim
    11069 [procedure] (number-of-slots BLOCK)
    11070 @end verbatim
    11071 Returns the number of slots that the object @code{BLOCK} contains. @code{BLOCK} may be a vector, record structure, pair or symbol.
    11072 
    11073 @node Unit lolevel - Low-level data access - record-instance?, Unit lolevel - Low-level data access - record->vector, Unit lolevel - Low-level data access - number-of-slots, Unit lolevel - Low-level data access
     10579@node Unit lolevel - Record instance - record-instance?, Unit lolevel - Record instance - record-instance-type, Unit lolevel - Record instance - make-record-instance, Unit lolevel - Record instance
    1107410580@subsection record-instance?
    1107510581
    1107610582
    1107710583@verbatim
    11078 [procedure] (record-instance? X)
    11079 @end verbatim
    11080 Returns @code{#t} if @code{X} is an instance of a record type. See also: @code{make-record-instance}.
    11081 
    11082 @node Unit lolevel - Low-level data access - record->vector,  , Unit lolevel - Low-level data access - record-instance?, Unit lolevel - Low-level data access
     10584[procedure] (record-instance? X [SYMBOL])
     10585@end verbatim
     10586Returns @code{#t} if @code{X} is a record structure, or @code{#f} otherwise.
     10587
     10588Further, returns @code{#t} if @code{X} is of type @code{SYMBOL}, or @code{#f} otherwise.
     10589
     10590@node Unit lolevel - Record instance - record-instance-type, Unit lolevel - Record instance - record-instance-length, Unit lolevel - Record instance - record-instance?, Unit lolevel - Record instance
     10591@subsection record-instance-type
     10592
     10593
     10594@verbatim
     10595[procedure] (record-instance-type RECORD)
     10596@end verbatim
     10597Returns type symbol of the record structure @code{RECORD}. Signals an error if @code{RECORD} is not a record structure.
     10598
     10599@node Unit lolevel - Record instance - record-instance-length, Unit lolevel - Record instance - record-instance-slot, Unit lolevel - Record instance - record-instance-type, Unit lolevel - Record instance
     10600@subsection record-instance-length
     10601
     10602
     10603@verbatim
     10604[procedure] (record-instance-length RECORD)
     10605@end verbatim
     10606Returns number of slots for the record structure @code{RECORD}. The record-instance type is not counted. Signals an error if @code{RECORD} is not a record structure.
     10607
     10608@node Unit lolevel - Record instance - record-instance-slot, Unit lolevel - Record instance - record-instance-slot-set!, Unit lolevel - Record instance - record-instance-length, Unit lolevel - Record instance
     10609@subsection record-instance-slot
     10610
     10611
     10612@verbatim
     10613[procedure] (record-instance-slot RECORD INDEX)
     10614@end verbatim
     10615Returns the contents of the @code{INDEX}th slot of the record structure @code{RECORD}. The slot index range is the open interval (([0 record-instance-length)@}@}. Signals an error if @code{RECORD} is not a record structure.
     10616
     10617@node Unit lolevel - Record instance - record-instance-slot-set!, Unit lolevel - Record instance - record->vector, Unit lolevel - Record instance - record-instance-slot, Unit lolevel - Record instance
     10618@subsection record-instance-slot-set!
     10619
     10620
     10621@verbatim
     10622[procedure] (record-instance-slot-set! RECORD INDEX X)
     10623[procedure] (set! (record-instance-slot RECORD INDEX) X)
     10624@end verbatim
     10625Sets the @code{INDEX}th slot of the record structure @code{RECORD} to @code{X}. The slot index range is the open interval (([0 record-instance-length)@}@}. Signals an error if @code{RECORD} is not a record structure.
     10626
     10627@node Unit lolevel - Record instance - record->vector,  , Unit lolevel - Record instance - record-instance-slot-set!, Unit lolevel - Record instance
    1108310628@subsection record->vector
    1108410629
    1108510630
    1108610631@verbatim
    11087 [procedure] (record->vector BLOCK)
    11088 @end verbatim
    11089 Returns a new vector with the type and the elements of the record @code{BLOCK}.
    11090 
    11091 @node Unit lolevel - Procedure-call- and variable reference hooks, Unit lolevel - Magic, Unit lolevel - Low-level data access, Unit lolevel
     10632[procedure] (record->vector RECORD)
     10633@end verbatim
     10634Returns a new vector with the type and the elements of the record structure @code{RECORD}. Signals an error if @code{RECORD} is not a record structure.
     10635
     10636@node Unit lolevel - Procedure-call- and variable reference hooks, Unit lolevel - Magic, Unit lolevel - Record instance, Unit lolevel
    1109210637@section Procedure-call- and variable reference hooks
    1109310638
     
    1110810653Sets 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.
    1110910654
    11110 @example
    11111 @emph{;;; Access sequence-elements as in ARC:
    11112 }
    11113 (set-invalid-procedure-call-handler!
    11114   (@strong{lambda} (proc args)
    11115     (@strong{cond} [(string? proc) (apply string-ref proc args)]
    11116           [(vector? proc) (apply vector-ref proc args)]
    11117           [@strong{else} (error @strong{"call of non-procedure"} proc)] ) ) )
    11118 
    11119 (@strong{"hello"} 4)    =@strong{=>}  #\o
    11120 @end example
    1112110655This facility does not work in code compiled with the @emph{unsafe} setting.
    1112210656
     
    1115110685Changes 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).
    1115210686
    11153 @example
    11154 (@strong{define} @strong{x} @strong{"i used to be a string"})
    11155 (@strong{define} @strong{y} '#(@strong{and} now i am a vector))
    11156 (object-become! (list (cons x y)))
    11157 x                                    =@strong{=>} #(@strong{and} now i am a vector)
    11158 y                                    =@strong{=>} #(@strong{and} now i am a vector)
    11159 (eq? x y)                            =@strong{=>} #t
    11160 @end example
    1116110687Note: this operation invokes a major garbage collection.
    1116210688
     
    1117210698Replaces 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}:
    1117310699
    11174 @example
    11175 @emph{;;; Replace arbitrary procedure with tracing one:
    11176 }
    11177 (mutate-procedure my-proc
    11178   (@strong{lambda} (new)
    11179     (@strong{lambda} args
    11180       (printf @strong{"~s called with arguments: ~s~%"} new args)
    11181       (apply new args) ) ) )
    11182 @end example
    1118310700Previous: @ref{Unit tcp, Unit tcp}
    1118410701
    11185 Next: @ref{Interface to external functions and variables, Interface to external functions and variables}
     10702Next: @ref{Interface to external functions and variables, Interface to external functions and variables} 
    1118610703
    1118710704@node Interface to external functions and variables, Accessing external objects, Unit lolevel, Top
     
    1123910756Executes the embedded C/C++ code @code{STRING ...}, which should be a sequence of C statements, which are executed and return an unspecified result.
    1124010757
    11241 @example
    11242 (foreign-code @strong{"doSomeInitStuff();"})     @strong{=>}  #<unspecified>
    11243 @end example
    1124410758Code wrapped inside @code{foreign-code} may not invoke callbacks into Scheme.
    1124510759
     
    1125310767Evaluates the embedded C/C++ expression @code{STRING}, returning a value of type given in the foreign-type specifier @code{TYPE}.
    1125410768
    11255 @example
    11256 (print (foreign-value @strong{"my_version_string"} c-string))
    11257 @end example
    1125810769@node Accessing external objects - foreign-declare, Accessing external objects - define-foreign-type, Accessing external objects - foreign-value, Accessing external objects
    1125910770@section foreign-declare
     
    1127410785Defines 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}:
    1127510786
    11276 @example
    11277 (define-foreign-type char-vector
    11278   nonnull-c-string
    11279   (compose list->string vector->list)
    11280   (compose list->vector string->list) )
    11281 
    11282 (@strong{define} @strong{strlen}
    11283   (foreign-lambda int @strong{"strlen"} char-vector) )
    11284 
    11285 (strlen '#(#\a #\b #\c))                      =@strong{=>} 3
    11286 
    11287 (@strong{define} @strong{memset}
    11288   (foreign-lambda char-vector @strong{"memset"} char-vector char int) )
    11289 
    11290 (memset '#(#_ #_ #_) #\X 3)                =@strong{=>} #(#\X #\X #\X)
    11291 @end example
    1129210787Foreign 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.
    1129310788
     
    1130110796Defines 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.
    1130210797
    11303 @example
    11304 #>
    11305 enum @{ abc=3, def, ghi @}@emph{;
    11306 }<#
    11307 
    11308 (define-macro (define-simple-foreign-enum . items)
    11309   `(@strong{begin}
    11310      ,@@(map (match-lambda
    11311               [(name realname) `(define-foreign-variable ,name int ,realname)]
    11312               [name `(define-foreign-variable ,name int)] )
    11313      items) ) )
    11314 
    11315 (define-simple-foreign-enum abc def ghi)
    11316 
    11317 ghi                               =@strong{=>} 5
    11318 @end example
    1131910798@node Accessing external objects - define-foreign-record, Accessing external objects - define-foreign-enum, Accessing external objects - define-foreign-variable, Accessing external objects
    1132010799@section define-foreign-record
     
    1139710876An example:
    1139810877
    11399 @example
    11400 (require-for-syntax 'srfi-13)
    11401 
    11402 (define-foreign-record Some_Struct
    11403   (rename: (compose string-downcase (cut string-translate <> @strong{"_"} @strong{"-"})))
    11404   (constructor: make-some-struct)
    11405   (destructor: free-some-struct)
    11406   (int xCoord)
    11407   (int yCoord) )
    11408 @end example
    1140910878will generate the following procedures:
    1141010879
    11411 @example
    11412 (make-some-struct)              --> C-POINTER
    11413 (free-some-struct C-POINTER)
    11414 
    11415 (some-struct-xcoord C-POINTER)  --> NUMBER
    11416 (some-struct-ycoord C-POINTER)  --> NUMBER
    11417 
    11418 (some-struct-xcoord-set! C-POINTER NUMBER)
    11419 (some-struct-ycoord-set! C-POINTER NUMBER)
    11420 @end example
    1142110880@node Accessing external objects - define-foreign-enum, Accessing external objects - foreign-lambda, Accessing external objects - define-foreign-record, Accessing external objects
    1142210881@section define-foreign-enum
     
    1144410903Here a heavily contrived example:
    1144510904
    11446 @example
    11447 #>
    11448 enum foo @{ a_foo = 4, b_foo, c_foo @}@emph{;
    11449 }enum foo bar(enum foo x) @{ printf(@strong{"%d\n"}, x)@emph{; return b_foo; @}
    11450 }<#
    11451 
    11452 (define-foreign-enum (foo (enum @strong{"foo"})) a_foo b_foo (c c_foo))
    11453 
    11454 (@strong{define} @strong{bar} (foreign-lambda foo bar foo))
    11455 
    11456 (pp (bar '()))
    11457 (pp (bar 'a_foo))
    11458 (pp (bar '(b_foo c)))
    11459 @end example
    1146010905@node Accessing external objects - foreign-lambda, Accessing external objects - foreign-lambda*, Accessing external objects - define-foreign-enum, Accessing external objects
    1146110906@section foreign-lambda
     
    1147610921Similar 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 ...}:
    1147710922
    11478 @example
    11479 (@strong{define} @strong{my-strlen}
    11480   (foreign-lambda* int ((c-string str))
    11481     @strong{"int n = 0;
    11482      while(*(str++)) ++n;
    11483      C_return(n);"}) )
    11484 
    11485 (my-strlen @strong{"one two three"})             =@strong{=>} 13
    11486 @end example
    1148710923For 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.
    1148810924
     
    1151410950This 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:
    1151510951
    11516 @example
    11517 C_values(N + 2, C_SCHEME_UNDEFINED, C_k, X1, ...)
    11518 @end example
    1151910952where @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.
    1152010953
     
    1182111254Foreign types are mapped to C types in the following manner:
    1182211255
    11823 <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>
    11824 
     11256[[table is unsupported for texi]]
    1182511257Previous: @ref{Accessing external objects, Accessing external objects}
    1182611258
     
    1220611638The 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}.
    1220711639
    12208 @example
    12209 (define-external (foo (c-string x)) int (string-length x))
    12210 @end example
    1221111640The 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}. 
    1221211641
    12213 @example
    12214 (define-external foo int 42)
    12215 ((foreign-lambda* int ()
    12216   @strong{"C_return(foo);"}))           =@strong{=>} 42
    12217 @end example
    1221811642@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}).
    1221911643
     
    1229511719Note that @code{(location X)} may be abbreviated as @code{#$X}.
    1229611720
    12297 @example
    12298 (define-external foo int)
    12299 ((foreign-lambda* void (((c-pointer int) ip)) @strong{"*ip = 123;"})
    12300   (location foo))
    12301 foo                                                                               =@strong{=>} 123
    12302 @end example
    1230311721This facility is especially useful in situations, where a C function returns more than one result value:
    1230411722
    12305 @example
    12306 #>
    12307 #include <math.h>
    12308 <#
    12309 
    12310 (@strong{define} @strong{modf}
    12311   (foreign-lambda double @strong{"modf"} double (c-pointer double)) )
    12312 
    12313 (let-location ([i double])
    12314   (@strong{let} ([f (modf 1.99 (location i))])
    12315     (print @strong{"i="} i @strong{", f="} f) ) )
    12316 @end example
    12317 See @uref{http://chicken.wiki.br/location-and-c-string-star, location and c-string*} for a tip on returning a @code{c-string*} type.
     11723See @uref{http://chicken.wiki.br/location-and-c-string-star, location and c-string*}  for a tip on returning a @code{c-string*} type.
    1231811724
    1231911725@code{location} returns a value of type @code{c-pointer}, when given the name of a callback-procedure defined with @code{define-external}.
     
    1278412190extern int callout(int, int, int);
    1278512191<#
    12786 @end verbatim
    12787 @verbatim
     12192
    1278812193(define callout (foreign-safe-lambda int "callout" int int int))
    12789 @end verbatim
    12790 @verbatim
     12194
    1279112195(define-external (callin (scheme-object xyz)) int
    1279212196  (print "This is 'callin': " xyz)
    1279312197  123)
    12794 @end verbatim
    12795 @verbatim
     12198
    1279612199(print (callout 1 2 3))
    1279712200@end verbatim
     
    1280012203#include <stdio.h>
    1280112204#include "chicken.h"
    12802 @end verbatim
    12803 @verbatim
     12205
    1280412206extern int callout(int, int, int);
    1280512207extern int callin(C_word x);
    12806 @end verbatim
    12807 @verbatim
     12208
    1280812209int callout(int x, int y, int z)
    1280912210{
    1281012211  C_word *ptr = C_alloc(C_SIZEOF_LIST(3));
    1281112212  C_word lst;
    12812 @end verbatim
    12813 @verbatim
     12213
    1281412214  printf("This is 'callout': %d, %d, %d\n", x, y, z);
    1281512215  lst = C_list(&ptr, 3, C_fix(x), C_fix(y), C_fix(z));
     
    1326012660The simplest case is a single file that does not export any syntax. For example
    1326112661
    13262 @example
    13263 @emph{;;;; hello.scm
    13264 }
    13265 (@strong{define} (@strong{hello} name)
    13266   (print @strong{"Hello, "} name @strong{" !"}) )
    13267 @end example
    1326812662We need a @code{.setup} script to build and install our nifty extension:
    1326912663
    13270 @example
    13271 @emph{;;;; hello.setup
    13272 }
    13273 @emph{;; compile the code into a dynamically loadable shared object
    13274 }@emph{;; (will generate hello.so)
    13275 }(compile -s hello.scm)
    13276 
    13277 @emph{;; Install as extension library
    13278 }(install-extension 'hello @strong{"hello.so"})
    13279 @end example
    1328012664After entering
    1328112665
     
    1329712681Here we create a simple application:
    1329812682
    13299 @example
    13300 @emph{;;;; hello2.scm
    13301 }
    13302 (print @strong{"Hello, "})
    13303 (for-each (@strong{lambda} (x) (printf @strong{"~A "} x)) (command-line-arguments))
    13304 (print @strong{"!"})
    13305 @end example
    1330612683We also need a setup script:
    1330712684
    13308 @example
    13309 @emph{;;;; hello2.setup
    13310 }
    13311 (compile hello2.scm)  @emph{; compile `hello2'
    13312 }(install-program 'hello2 @strong{"hello2"}) @emph{; name of the extension and files to be installed
    13313 }@end example
    1331412685To use it, just run @code{chicken-setup} in the same directory:
    1331512686
     
    1333212703Finally 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:
    1333312704
    13334 @example
    13335 @emph{;;;; glass.scm
    13336 }
    13337 (define-macro (glass-lambda llist vars . body)
    13338   @emph{;; Low-level macros are fun!
    13339 }  (@strong{let} ([lvar (gensym)]
    13340         [svar (gensym)]
    13341         [x (gensym)]
    13342         [y (gensym)]
    13343         [yn (gensym)] )
    13344     `(@strong{let} ,(map (@strong{lambda} (v) (list v #f)) vars)
    13345        (@strong{define} (,svar ,x . ,y)
    13346          (@strong{let*} ([,yn (pair? ,y)]
    13347                 [,y (@strong{and} ,yn (car ,y))] )
    13348            (@strong{case} ,x
    13349              ,@@(map (@strong{lambda} (v)
    13350                       `([,v] (@strong{if} ,yn
    13351                                  (@strong{set!} ,v ,y)
    13352                                  ,v) ) )
    13353                     vars)
    13354              (@strong{else} (error @strong{"variable not found"} ,x)) ) ) )
    13355        (@strong{define} ,lvar (@strong{lambda} ,llist ,@@body))
    13356        (extend-procedure ,lvar ,svar) ) ) )
    13357 @end example
    1335812705Here some support code that needs to be loaded at runtime:
    1335912706
    13360 @example
    13361 @emph{;;;; glass-support.scm
    13362 }
    13363 (require-extension lolevel)
    13364 
    13365 (@strong{define} @strong{glass-lambda-accessor} procedure-data)
    13366 (@strong{define} (@strong{glass-lambda-ref} gl v) ((procedure-data gl) v))
    13367 (@strong{define} (@strong{glass-lambda-set!} gl v x) ((procedure-data gl) v x))
    13368 @end example
    1336912707The setup script looks like this:
    1337012708
    13371 @example
    13372 (compile -s glass-support.scm)
    13373 
    13374 (install-extension
    13375   'glass
    13376   '(@strong{"glass.scm"} @strong{"glass-support.so"})
    13377   '((syntax) (require-at-runtime glass-support)) )
    13378 @end example
    1337912709The 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.
    1338012710
     
    1355012880The 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:
    1355112881
    13552 @example
    13553 (compile -s -O2 -d1 my-ext.scm)   @emph{; dynamically loadable "normal" version
    13554 }(compile -c -O2 -d1 my-ext -unit my-ext)  @emph{; statically linkable version
    13555 }(install-extension
    13556   'my-ext
    13557   '(@strong{"my-ext.so"} @strong{"my-ext.o"})
    13558   '((static @strong{"my-ext.o"})) )
    13559 @end example
    1356012882Note 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.
    1356112883
     
    1356512887% csc -static-extensions my-program.scm -uses my-ext
    1356612888@end verbatim
    13567 The compiler will try to do the right thing, but cannot handle all extensions, since the ability to statically link eggs is relatively new. Eggs that support static linking are designated as being able to do so. If you require a statically linkable version of an egg that has not been converted yet, contact the extension author or the CHICKEN  mailing list.
     12889The compiler will try to do the right thing, but can not handle all extensions, since the ability to statically link eggs is relatively new. Eggs that support static linking are designated as being able to do so. If you require a statically linkable version of an egg that has not been converted yet, contact the extension author or the CHICKEN  mailing list.
    1356812890
    1356912891Previous: @ref{Interface to external functions and variables, Interface to external functions and variables}
     
    1377113093
    1377213094
    13773 @code{case} expands into a cascaded @code{if} expression, where the first item in each arm is treated as a quoted list. So the @code{case} macro cannot infer whether a symbol is to be treated as a constant-name (defined via @code{define-constant}) or a literal symbol.
     13095@code{case} expands into a cascaded @code{if} expression, where the first item in each arm is treated as a quoted list. So the @code{case} macro can not infer whether a symbol is to be treated as a constant-name (defined via @code{define-constant}) or a literal symbol.
    1377413096
    1377513097@node FAQ - General - How can I enable case sensitive reading/writing in user code?, FAQ - General - How can I change match-error-control during compilation?, FAQ - General - Why are constants defined by define-constant not honoured in case constructs?, FAQ - General
     
    1378513107Use @code{eval-when}, like this:
    1378613108
    13787 @example
    13788 (eval-when (compile)
    13789 (match-error-control #:unspecified) )
    13790 @end example
    1379113109@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
    1379213110@subsection Why doesn't CHICKEN support the full numeric tower by default?
     
    1379513113The short answer:
    1379613114
    13797 @example
    13798 % chicken-setup numbers
    13799 % csi -q
    13800 #@emph{;1> (use numbers)
    13801 }@end example
    1380213115The long answer:
    1380313116
     
    1381813131Specializing a method on @code{<object>} doesn't work on primitive data objects like numbers, strings, etc. so for example
    1381913132
    13820 @example
    13821 (define-method (foo (x <my-class>)) ...)
    13822 (define-method (foo (x <object>)) ...)
    13823 (foo 123)
    13824 @end example
    1382513133will signal an error, because to applicable method can be found. To specialize a method for primitive objects, use @code{<top>}:
    1382613134
    13827 @example
    13828 (define-method (foo (x <top>)) ...)
    13829 @end example
    1383013135@node FAQ - General - Does CHICKEN support native threads?, FAQ - General - Does CHICKEN support Unicode strings?, FAQ - General - How can I specialize a generic function method to match instances of every class?, FAQ - General
    1383113136@subsection Does CHICKEN support native threads?
     
    1384613151You can enable UTF-8 support by placing the following two lines at the beginning of your source file (or in your ~/.csirc for interactive sessions) before any other code, including other use directives:
    1384713152
    13848 @example
    13849 (use iset syntax-case utf8)
    13850 (import utf8)
    13851 @end example
    1385213153This will replace all builtin string operators with UTF-8-aware versions, that will treat strings as sequences of multibyte UTF-8 characters, thus enabling you to represent and manipulate Unicode characters while remaining compatible with most C libraries and system interfaces.
    1385313154
     
    1393513236When you invoke the C compiler for your translated Scheme source program, add the C compiler option @code{-DC_EMBEDDED}, or pass @code{-embedded} to the @code{csc} driver program, so no entry-point function will be generated (@code{main()}). When your are finished with your startup processing, invoke:
    1393613237
    13937 @example
    13938 @strong{CHICKEN_main}(argc, argv, C_toplevel);
    13939 @end example
    1394013238where @code{C_toplevel} is the entry-point into the compiled Scheme code. You should add the following  declarations at the head of your code:
    1394113239
    13942 @example
    13943 #@strong{include} @strong{"chicken.h"}
    13944 @strong{extern} @strong{void} @strong{C_toplevel}(C_word,C_word,C_word) C_noret;
    13945 @end example
    1394613240@node FAQ - Customization - How can I add compiled user passes?,  , FAQ - Customization - How do I run custom startup code before the runtime-system is invoked?, FAQ - Customization
    1394713241@subsection How can I add compiled user passes?
     
    1395013244To add a compiled user pass instead of an interpreted one, create a library unit and recompile the main unit of the compiler (in the file @code{chicken.scm}) with an additional @code{uses} declaration. Then link all compiler modules and your (compiled) extension to create a new version of the compiler, like this (assuming all sources are in the current directory):
    1395113245
    13952 @example
    13953 % cat userpass.scm
    13954 @emph{;;;; userpass.scm - My very own compiler pass
    13955 }
    13956 (declare (unit userpass))
    13957 
    13958 @emph{;; Perhaps more user passes/extensions are added:
    13959 }(@strong{let} ([old (user-pass)])
    13960 (user-pass
    13961 (@strong{lambda} (x)
    13962 (@strong{let} ([x2 (do-something-with x)])
    13963           (@strong{if} old
    13964               (old x2)
    13965               x2) ) ) ) )
    13966 @end example
    1396713246@verbatim
    1396813247% csc -c -x userpass.scm
     
    1406313342
    1406413343
    14065 Even when the @code{match} unit is not used, the macros from that package are visible in the compiler. The reason for this is that macros cannot be accessed from library units (only when explicitly evaluated in running code). To speed up macro-expansion time, the compiler and the interpreter both already provide the compiled  @code{match-...} macro definitions. Macros shadowed lexically are no problem, but global definitions of variables named identically to (global) macros are useless - the macro definition shadows the global variable.
     13344Even when the @code{match} unit is not used, the macros from that package are visible in the compiler. The reason for this is that macros can not be accessed from library units (only when explicitly evaluated in running code). To speed up macro-expansion time, the compiler and the interpreter both already provide the compiled  @code{match-...} macro definitions. Macros shadowed lexically are no problem, but global definitions of variables named identically to (global) macros are useless - the macro definition shadows the global variable.
    1406613345
    1406713346This problem can be solved using a different name or undefining the macro, like this:
    1406813347
    14069 @example
    14070 (eval-when (compile eval) (undefine-macro! 'match))
    14071 @end example
    1407213348@node FAQ - Warnings and errors - Why don't toplevel-continuations captured in interpreted code work?, FAQ - Warnings and errors - Why does define-reader-ctor not work in my compiled program?, FAQ - Warnings and errors - Why do I get a warning when I define a global variable named match?, FAQ - Warnings and errors
    1407313349@subsection Why don't toplevel-continuations captured in interpreted code work?
     
    1407613352Consider the following piece of code:
    1407713353
    14078 @example
    14079  
    14080 (@strong{define} @strong{k} (call-with-current-continuation (@strong{lambda} (k) k)))
    14081 (k k)
    14082 @end example
    1408313354When compiled, this will loop endlessly. But when interpreted, @code{(k k)} will return to the read-eval-print loop! This happens because the continuation captured will eventually read the next toplevel expression from the standard-input (or an input-file if loading from a file). At the moment @code{k} was defined, the next expression was @code{(k k)}. But when @code{k} is invoked, the next expression will be whatever follows after @code{(k k)}. In other words, invoking a captured continuation will not rewind the file-position of the input source. A solution is to wrap the whole code into a @code{(begin ...)} expression, so all toplevel expressions will be loaded together.
    1408413355
     
    1408913360The following piece of code does not work as expected:
    1409013361
    14091 @example
    14092 (eval-when (compile)
    14093 (define-reader-ctor 'integer->char integer->char) )
    14094 (print #,(integer->char 33))
    14095 @end example
    1409613362The problem is that the compiler reads the complete source-file before doing any processing on it, so the sharp-comma form is encountered before the reader-ctor is defined. A possible solution is to include the file containing the sharp-comma form, like this:
    1409713363
    14098 @example
    14099 (eval-when (compile)
    14100 (define-reader-ctor 'integer->char integer->char) )
    14101 
    14102 (include @strong{"other-file"})
    14103 @end example
    14104 @example
    14105 @emph{;;; other-file.scm:
    14106 }(print #,(integer->char 33))
    14107 @end example
    1410813364@node FAQ - Warnings and errors - Why do built-in units; such as srfi-1; srfi-18; and posix fail to load?, FAQ - Warnings and errors - How can I increase the size of the trace shown when runtime errors are detected?, FAQ - Warnings and errors - Why does define-reader-ctor not work in my compiled program?, FAQ - Warnings and errors
    1410913365@subsection Why do built-in units, such as srfi-1, srfi-18, and posix fail to load?
     
    1411213368When you try to @code{use} a built-in unit such as @code{srfi-18}, you may get the following error:
    1411313369
    14114 @example
    14115 #@emph{;1> (use srfi-18)
    14116 }@emph{; loading library srfi-18 ...
    14117 }Error: (load-library) unable to load library
    14118 srfi-18
    14119 @strong{"dlopen(libchicken.dylib, 9): image not found"}                @emph{;; on a Mac
    14120 }@strong{"libchicken.so: cannot open shared object file: No such file or directory"}  @emph{;; Linux
    14121 }@end example
    1412213370Another symptom is that @code{(require 'srfi-18)} will silently fail.
    1412313371
     
    1415213400If you don't need @code{eval} or the stuff in the @code{extras} library unit,  you can just use the @code{library} unit:
    1415313401
    14154 @example
    14155         (declare (uses library))
    14156         (display @strong{"Hello, world!\n"})
    14157 @end example
    1415813402(Don't forget to compile with the @code{-explicit-use} option) Compiled with Visual C++ this generates an executable of around 240 kilobytes. It is theoretically possible to compile something without the library, but a program would have to implement quite a lot of support code on its own.
    1415913403
     
    1425613500CSI doesn't support it natively but it can be activated with the @uref{http://www.call-with-current-continuation.org/eggs/readline.html, http://www.call-with-current-continuation.org/eggs/readline.html} egg. After installing the egg, add the following to your @code{~/.csirc} or equivalent file:
    1425713501
    14258 @example
    14259 (require-extension readline)
    14260 (current-input-port (make-gnu-readline-port))
    14261 (gnu-history-install-file-manager (string-append (@strong{or} (getenv @strong{"HOME"}) @strong{"."}) @strong{"/.csi.history"}))
    14262 @end example
    1426313502Users of *nix-like systems (including Cygwin), may also want to check out @uref{http://utopia.knoware.nl/~hlub/rlwrap/, rlwrap}.  This program lets you "wrap" another process (e.g. @code{rlwrap csi}) with the readline library, giving you history, autocompletion, and the ability to set the keystroke set. Vi fans can get vi keystrokes by adding "set editing-mode vi" to their @code{.inputrc} file.
    1426413503
     
    1429113530In order to make programs (including csi) see these eggs, you should set this variable when you run them. Alternatively, you can call the @code{repository-path} Scheme procedure before loading the eggs, as in:
    1429213531
    14293 @example
    14294 (repository-path @strong{"/home/azul/chicken"})
    14295 (use format-modular)
    14296 @end example
    1429713532Note, however, that using @code{repository-path} as above hard-codes the location of your eggs in your source files.  While this might not be an issue in your case, it might be safe to keep this configuration outside of the source code (that is, specifying it as an environment variable) to make it easier to maintain.
    1429813533
     
    1431113546
    1431213547
    14313 Many thanks to Nico Amtsberg, William Annis, Marc Baily, Peter Barabas, Jonah Beckford, Arto Bendiken, Peter Bex, Jean-Francois Bignolles, Alaric Blagrave-Snellpym, Dave Bodenstab, Fabian Boehlke, T. Kurt Bond, Ashley Bone, Dominique Boucher, Terence Brannon, Roy Bryant, Adam Buchbinder, Hans Bulfone, Category 5, Taylor Campbell, Naruto Canada, Esteban U. Caamano Castro, Franklin Chen, Thomas Chust, Gian Paolo Ciceri, John Cowan, Grzegorz Chrupa&#322;a, James Crippen, Tollef Fog Heen, Alejandro Forero Cuervo, Linh Dang, Brian Denheyer, dgym, Don, Chris Double, Jarod Eells, Petter Egesund, Steve Elkins, Daniel B. Faken, Will Farr, Graham Fawcett, Marc Feeley, Fizzie, Kimura Fuyuki, Tony Garnock-Jones, Martin Gasbichler, Joey Gibson, Stephen C. Gilardi, Joshua Griffith, Johannes Groedem, Damian Gryski, Mario Domenech Goulart, Andreas Gustafsson, Sven Hartrumpf, Jun-ichiro itojun Hagino, Ahdi Hargo, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Bill Hoffman, Bruce Hoult, Hans Huebner, Markus Huelsmann, Goetz Isenmann, Paulo Jabardo, David Janssens, Christian Jaeger, Dale Jordan, Valentin Kamyshenko, Daishi Kato, Peter Keller, Brad Kind, Ron Kneusel, Matthias Koeppe, Krysztof Kowa&#322;czyk, Andre Kuehne, Todd R. Kueny Sr, Goran Krampe, David Krentzlin, Ben Kurtz, Micky Latowicki, John Lenz, Kirill Lisovsky, Juergen Lorenz, Kon Lovett, Dennis Marti, Charles Martin, Bob McIsaac, Alain Mellan, Eric Merrit, Perry Metzger, Scott G. Miller, Mikael, Bruce Mitchener, Chris Moline, Eric E. Moore, Julian Morrison, Dan Muresan, Lars Nilsson, Ian Oversby, o.t., Gene Pavlovsky, Levi Pearson, Nicolas Pelletier, Carlos Pita, Robin Lee Powell, Pupeno, Davide Puricelli, Doug Quale, Eric Raible, Ivan Raikov, Joel Reymont, Eric Rochester, Andreas Rottman, David Rush, Lars Rustemeier, Daniel Sadilek, Oskar Schirmer, Burton Samograd, Reed Sheridan, Ronald Schroeder, Spencer Schumann, Alex Shinn, Ivan Shmakov, Shmul, Tony Sidaway, Jeffrey B. Siegal, Andrey Sidorenko, Michele Simionato, Volker Stolz, Jon Strait, Dorai Sitaram, Robert Skeels, Jason Songhurst, Clifford Stein, Sunnan, Zbigniew Szadkowski, Rick Taube, Mike Thomas, Minh Thu, Christian Tismer, Andre van Tonder, John Tobey, Henrik Tramberend, Vladimir Tsichevsky, Neil van Dyke, Sander Vesik, Jaques Vidrine, Panagiotis Vossos, Shawn Wagner, Peter Wang, Ed Watkeys, Brad Watson, Thomas Weidner, Goeran Weinholt, Matthew Welland, Joerg Wittenberger, Peter Wright, Mark Wutka, Richard Zidlicky and Houman Zolfaghari for bug-fixes, tips and suggestions.
     13548Many thanks to Nico Amtsberg, Alonso Andres, William Annis, Marc Baily, Peter Barabas, Jonah Beckford, Arto Bendiken, Kevin Beranek,  Peter Bex, Jean-Francois Bignolles, Alaric Blagrave-Snellpym,  Dave Bodenstab, Fabian Boehlke, T. Kurt Bond, Ashley Bone,  Dominique Boucher, Terence Brannon, Roy Bryant, Adam Buchbinder,  Hans Bulfone, Category 5, Taylor Campbell, Naruto Canada,  Esteban U. Caamano Castro, Franklin Chen, Thomas Chust, Gian Paolo Ciceri,  John Cowan, Grzegorz Chrupa&#322;a, James Crippen, Tollef Fog Heen, Alejandro Forero Cuervo, Linh Dang, Brian Denheyer, dgym, Don, Chris Double, Brown Dragon, Jarod Eells, Petter Egesund, Steve Elkins, Daniel B. Faken, Will Farr, Graham Fawcett, Marc Feeley, Fizzie, Kimura Fuyuki, Tony Garnock-Jones, Martin Gasbichler, Joey Gibson, Stephen C. Gilardi, Joshua Griffith, Johannes Groedem, Damian Gryski, Mario Domenech Goulart, Andreas Gustafsson, Sven Hartrumpf, Jun-ichiro itojun Hagino, Ahdi Hargo, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Bill Hoffman, Bruce Hoult, Hans Huebner, Markus Huelsmann, Goetz Isenmann, Paulo Jabardo, David Janssens, Christian Jaeger, Dale Jordan, Valentin Kamyshenko, Daishi Kato, Peter Keller, Brad Kind, Ron Kneusel, Matthias Koeppe, Krysztof Kowa&#322;czyk, Andre Kuehne, Todd R. Kueny Sr, Goran Krampe, David Krentzlin, Ben Kurtz, Micky Latowicki, John Lenz, Kirill Lisovsky, Juergen Lorenz, Kon Lovett, Dennis Marti, Charles Martin, Bob McIsaac, Alain Mellan, Eric Merrit, Perry Metzger, Scott G. Miller, Mikael, Bruce Mitchener, Chris Moline, Eric E. Moore, Julian Morrison, Dan Muresan, Lars Nilsson, Ian Oversby, o.t., Gene Pavlovsky, Levi Pearson, Nicolas Pelletier, Carlos Pita, Robin Lee Powell, Pupeno, Davide Puricelli, Doug Quale, Eric Raible, Ivan Raikov, Joel Reymont, Eric Rochester, Andreas Rottman, David Rush, Lars Rustemeier, Daniel Sadilek, Oskar Schirmer, Burton Samograd, Reed Sheridan, Ronald Schroeder, Spencer Schumann, Alex Shinn, Ivan Shmakov, Shmul, Tony Sidaway, Jeffrey B. Siegal, Andrey Sidorenko, Michele Simionato, Volker Stolz, Jon Strait, Dorai Sitaram, Robert Skeels, Jason Songhurst, Clifford Stein, Sunnan, Zbigniew Szadkowski, Rick Taube, Nathan Thern, Mike Thomas, Minh Thu, Christian Tismer, Andre van Tonder, John Tobey, Henrik Tramberend, Vladimir Tsichevsky, Neil van Dyke, Sander Vesik, Jaques Vidrine, Panagiotis Vossos, Shawn Wagner, Peter Wang, Ed Watkeys, Brad Watson, Thomas Weidner, Goeran Weinholt, Matthew Welland, Drake Wilson, Joerg Wittenberger, Peter Wright, Mark Wutka, Richard Zidlicky and Houman Zolfaghari for bug-fixes, tips and suggestions.
    1431413549
    1431513550CHICKEN uses the PCRE regular expression package (@uref{http://www.pcre.org, http://www.pcre.org}), which is written by Philip Hazel.
     
    1432413559
    1432513560@table @b
     13561@item Richard Kelsey, Jonathan Rees and Taylor Campbell
     13562
     13563@code{syntax-rules} expander
    1432613564@item Eli Barzilay
    1432713565
     
    1434513583
    1434613584queues.
    14347 @item Andrew Wright
    14348 
    14349 pattern matcher.
    1435013585@item @uref{http://chicken.wiki.br/Alex Shinn, Alex Shinn}
    1435113586
  • chicken/branches/chicken-3/scripts/maketexi.scm

    r11233 r13437  
    33; (by Ivan Raikov)
    44
    5 (require-extension syntax-case)
    65(require-extension srfi-1)
    7 (require-extension srfi-69)
    86(require-extension posix)
    9 (require-extension utils)
    107(require-extension srfi-40)
    118(require-extension html-stream)
    129(require-extension stream-ext)
    1310(require-extension stream-wiki)
    14 
    15 (define extensions (make-hash-table))
    16 
    17 (load-extensions-from-file extensions (or (file-exists? "enscript-texinfo.scm")
    18                                           (file-exists? "scripts/enscript-texinfo.scm")))
     11(require-extension svnwiki-extensions)
    1912
    2013(define wikipath (optional (command-line-arguments) "manual"))
     
    7366  "Felix Winkelmann and the Chicken Team"
    7467  "Chicken Scheme Reference Manual"
    75   "Copyright 2007-2008 Felix Winkelmann and the Chicken Team"
     68  "Copyright 2007-2009 Felix Winkelmann and the Chicken Team"
    7669  "The User's Manual"
    7770  (wiki->texi str
     
    8174              (lambda (name tail) tail) ;; include
    8275              (make-hash-table) ;; linktypes
    83               extensions))
     76              ))
    8477 (open-output-file "chicken.texi"))
Note: See TracChangeset for help on using the changeset viewer.