Changeset 628 in project


Ignore:
Timestamp:
05/24/06 23:46:31 (12 years ago)
Author:
felix
Message:

egg-post-commit modifications, small fixes

Files:
7 added
1 deleted
4 edited
2 copied

Legend:

Unmodified
Added
Removed
  • egg-post-commit

    r578 r628  
    1414
    1515
    16 (use utils srfi-1 posix regex ftp http-client format)
     16(define-constant +coop-egg-index-page+ "galinha.ucpel.tche.br/coop?page=egg%20index")
     17(define-constant +call/cc-ftp-url+ "www.call-with-current-continuation.org")
     18(define-constant +call/cc-eggs-url+ "http://www.call-with-current-continuation.org/eggs")
     19
     20(use utils (srfi 1 13) posix regex ftp http-client format url base64)
     21
     22(assert (string>=? (->string (cadr (assq 'version (extension-information 'http)))) "1.46")
     23        "Please install a newer version of the http egg")
    1724
    1825(define username)
     
    148155
    149156(define (upload . files)
    150   (let ([ftp (ftp:connect "www.call-with-current-continuation.org" username password)])
     157  (let ([ftp (ftp:connect +call/cc-ftp-url+ username password)])
    151158    (define (out fname)
    152159      (let* ([p (ftp:open-output-file ftp (pathname-strip-directory fname))]
     
    161168    (for-each out files)
    162169    (ftp:disconnect ftp) ) )
     170
     171(define (put-coop-index-page eggnames repofile)
     172  (http:send-request
     173   (http:make-request
     174    'PUT
     175    (conc +coop-egg-index-page+
     176          "&comment="
     177          (url-encode
     178           (format #f "egg update ~a ~a" (string-trim-right (seconds->string (current-seconds)))
     179                   eggnames) ) )
     180    `(("Authorization" . ,(conc "Basic " (base64:encode (conc "egg-maintainers:" username password))))
     181      ("Content-type" . "text/plain")
     182      ("Connection" . "close") )
     183    (with-output-to-string
     184      (cut pp
     185           `((head "Egg status index")
     186             "\n\nRecently updated eggs: " ,(->string eggnames)
     187             "\n\n"
     188             (html
     189              "<table class='changes' style='width: 60%;' border='0'><tr><th align='left'><b>Release</b></th><th align='left'>Egg</th></td></tr>"
     190              ,@(map (lambda (item f)
     191                       (conc "<tr class=" f "><td class='trdate'>" (car item) "</td><td class='trname'>"
     192                             "<a href='" +call/cc-eggs-url+ "/" (cdr item) ".html'>"
     193                             (cdr item) "</a></td></tr>") )
     194                     (sort (map (match-lambda
     195                                  ((name (attrs ...) . _)
     196                                   (let ((a (assq 'date attrs)))
     197                                     (cons (cadr a) name) ) ) )
     198                                repofile)
     199                           (lambda (a b) (string>? (car a) (car b))) )
     200                     (circular-list "odd" "even")) )
     201             (html "</table>")
     202             (readonly) ) ) ) ) ) )
    163203
    164204(define (post-commit eggnames pack-only?)
     
    193233      (cut sxml->xml (make-egg-index-page)) )
    194234    (print "Reading current repository file...")
    195     (match-let ((rf (with-input-from-string (http:GET "http://www.call-with-current-continuation.org/eggs/repository") read))
     235    (match-let ((rf (with-input-from-string (http:GET (conc +call/cc-eggs-url+ "/repository")) read))
    196236                (#(_ m h md mo yr _ _ _ _) (seconds->utc-time (current-seconds))) )
    197       (let ((date (format #f "~d~2'0d~2'0d~2'0d~2'0d" (+ 1900 yr) (add1 mo) md h m)))
    198         (print "Creating repository file...")
    199         (with-output-to-file "repository"
    200           (cut pp (map (lambda (info)
     237      (let* ((date (format #f "~d~2'0d~2'0d~2'0d~2'0d" (+ 1900 yr) (add1 mo) md h m))
     238             (rf2 (map (lambda (info)
    201239                         `(,(car info)
    202240                           ,(let ((e (assq (car info) rf)))
     
    215253                                   (cdr needs)
    216254                                   '() ) ) ) )
    217                        eggs) ) ) ) )
     255                       eggs) ) )
     256        (print "Creating repository file...")
     257        (with-output-to-file "repository" (cut pp rf2))
     258        (print "Pushing coop index page...")
     259        (put-coop-index-page eggnames rf2) )  )
    218260    (unless pack-only?
    219261      (print "Uploading files:")
     
    240282    (system* cmd) ) )
    241283
     284(unless (file-exists? ".egg-post-commit-anchor")
     285  (error "egg-post-commit must be executed in root egg directory") )
     286
    242287(match (command-line-arguments)
    243288  (("-build-archive" name)
     
    250295   (set! password p)
    251296   (post-commit files #f))
    252   (_ (print "Usage: maintenance/egg-post-commit USERNAME PASSWORD EGGNAME ...") ) )
     297  (_ (print "Usage: egg-post-commit USERNAME PASSWORD EGGNAME ...") ) )
  • http/http-client.scm

    r466 r628  
    115115  (match (string-match url-rx url)
    116116    [(_ serv host port path)
    117      (values
    118       (substring serv 0 (- (string-length serv) 3))
    119       host
    120       (cond [port (string->number (substring port 1 (string-length port)))]
    121             [serv (let ((port (getservbyname (substring serv 0 (- (string-length serv) 3)))))
    122                     (if (> port 0)
    123                         port
    124                         (error "invalid service" serv)))]
    125             [else 80] )
    126       (or path "/") ) ]
     117     (let ((servs (and serv (substring serv 0 (- (string-length serv) 3)))))
     118       (values
     119        (or servs "http")
     120        host
     121        (cond [port (string->number (substring port 1 (string-length port)))]
     122              [serv (let ((port (getservbyname servs)))
     123                      (if (> port 0)
     124                          port
     125                          (error "invalid service" serv)))]
     126              [else 80] )
     127        (or path "/") ) ) ]
    127128    [else (values "http" url 80 "/")] ) )
    128129
  • http/http.html

    r466 r628  
    1717<h3>Version:</h3>
    1818<ul>
     19<li>1.46
     20Bugfix in url-parser
    1921<li>1.45
    2022cookie hack for http:GET and http:POST [Daishi Kato]
  • http/http.setup

    r466 r628  
    44      "") )
    55
    6 (make (("http-client.so" ("http-client.scm") (run (csc -s -O2 -no-trace http-client.scm ,libs)))
    7        ("http-server.so" ("http-server.scm") (run (csc -s -O2 -no-trace http-server.scm)))
    8        ("http-utils.so" ("http-utils.scm") (run (csc -s -O2 -no-trace http-utils.scm))) )
     6(make (("http-client.so" ("http-client.scm") (run (csc -s -O2 -d1 http-client.scm ,libs)))
     7       ("http-server.so" ("http-server.scm") (run (csc -s -O2 -d1 http-server.scm)))
     8       ("http-utils.so" ("http-utils.scm") (run (csc -s -O2 -d1 http-utils.scm))) )
    99  '#("http-client.so" "http-server.so" "http-utils.so") )
    1010
     
    1212 'http
    1313 '("http-client.so" "http-server.so" "http-utils.so" "http.html")
    14  '((version 1.45)
     14 '((version 1.46)
    1515   (documentation "http.html") ) )
  • man/chicken.texi

    r4 r628  
    11\input texinfo @c -*-texinfo-*-
    22@setfilename chicken.info
    3 @settitle CHICKEN - A practical and portable Scheme system. Version 2, Build 0
     3@settitle CHICKEN - A practical and portable Scheme system. Version 2, Build 314
    44
    55@ifnottex
     
    1717@copying
    1818@noindent
    19 Copyright @copyright{} 2000-2005, Felix L. Winkelmann
     19Copyright @copyright{} 2000-2006, Felix L. Winkelmann
    2020All rights reserved.
    2121
     
    5757@dircategory The Algorithmic Language Scheme
    5858@direntry
    59 * CHICKEN: (chicken).          A pratical and portable Scheme system (Version 2, Build 0).
     59* CHICKEN: (chicken).          A pratical and portable Scheme system (Version 2, Build 314).
    6060@end direntry
    6161
     
    6464@subtitle A practical and portable Scheme system
    6565@subtitle User's Manual
    66 @subtitle Version 1, Build 944
     66@subtitle Version 2, Build 314
    6767@author Felix L. Winkelmann
    6868@end titlepage
     
    7979
    8080CHICKEN - A practical and portable Scheme system
    81 User's manual (Version 1, Build 944)
    82 
    83 (c) 2000-2005, Felix L. Winkelmann
     81User's manual (Version 2, Build 314)
     82
     83(c) 2000-2006, Felix L. Winkelmann
    8484All rights reserved. Translated to LaTeX by Peter Keller. Translated to texinfo by Linh Dang.
    8585
     
    124124* Non standard read syntax::   
    125125* Non-standard macros and special forms:: 
     126* Pattern Matching::
    126127* Declarations::               
    127128* Parameters::                 
     
    136137* Unit regex::                 
    137138* Unit srfi-18::               
    138 * Unit format::                 
    139139* Unit posix::                 
    140140* Unit utils::           
     
    171171* User-defined named characters:: 
    172172* Vectors::                     
    173 * The unspecified value::       
    174 * Continuations::                     
     173* The unspecified value::
     174* Continuations::
     175* Setters::
    175176
    176177Unit eval
     
    212213* Environment access::         
    213214* Memory mapped I/O::           
    214 * Time routines::               
     215* Date and time routines::               
    215216* Raw exit::                   
    216217* ERRNO values::               
    217218* Finding files::               
    218219* Getting the hostname and system information:: 
    219 * Setting a files buffering mode:: 
     220* Setting the file buffering mode:: 
    220221* Terminal ports::             
    221222* How Scheme procedures relate to UNIX C functions:: 
     
    257258* Accessing external objects:: 
    258259* Foreign type specifiers::     
    259 * Entry points::               
     260* Embedding::               
    260261* Callbacks::                   
    261262* Locations::                   
     
    272273* C notes::                     
    273274* C++ notes::
    274 * Using the builtin parser::
    275 * Specification grammar::
    276275
    277276chicken-setup
     
    286285* chicken-more-macros.scm::     
    287286* chicken-ffi-macros.scm::     
    288 * chicken-entry-points.scm::   
    289 * chicken-default-entry-points.scm:: 
    290287
    291288@end detailmenu
     
    318315Some of the features supported by CHICKEN:
    319316@itemize
    320 @item SRFIs 0, 1, 2, 4, 6, 7, 8, 9, 10, 13, 14, 16, 18, 23, 28, 30, 39 and 55.
     317@item SRFIs 0, 1, 2, 4, 6, 7, 8, 9, 10, 13, 14, 16, 17, 18, 23, 28, 30, 31, 39, 55, 61 and 62.
    321318@item Lightweight threads based on first-class continuations
    322319@item Pattern matching with Andrew Wright's @code{match} package
     
    325322                meta-object protocol
    326323@item Extended comment- and string-literal syntaxes
    327 @item Libraries for regular expressions, string handling, Common LISP
    328                 style @code{format},
     324@item Libraries for regular expressions, string handling
    329325UNIX system calls and extended data structures
    330326@item Create interpreted or compiled shell scripts written in Scheme
     
    400396dependent makefiles, shell-scripts or batch-files should perform
    401397any necessary steps before and after invocation of @code{chicken}.
    402 On UNIX-compatible systems, a shell script named @code{chicken-config}
    403 is supplied that emits the correct options for the host system's C
    404 compiler. Enter
    405 
    406 @verbatim
    407 chicken-config -help
    408 @end verbatim
    409 
    410 on the command line for a list of available options. A program named @code{csc} provides a much simpler
     398A program named @code{csc} provides a much simpler
    411399interface to the Scheme- and C-compilers and linker. Enter
    412400
     
    444432@item -benchmark-mode
    445433
    446 Equivalent to @code{-debug-level 0 -optimize-level 3}
     434Equivalent to @code{-no-trace -no-lambda-info -optimize-level 3}
    447435@code{-fixnum-arithmetic -disable-interrupts -block -lambda-lift}.
    448436
     
    459447case sensitive (in violation of R5RS).  This option registers the @code{case-insensitive}
    460448feature identifier.
     449
     450@item -check-imports
     451Search for references to undefined global variables. For each library unit accessed
     452via @code{(declare (uses ...))}, the compiler will search a file named @code{UNITNAME.exports}
     453in the current include path and load its contents into the ``import-table'' (if found).
     454Also, export-information for extensions (accessed through @code{(require-extension ...)})
     455will be searched and stored in the import-table. If a required extensions does not
     456provide explicit exports-innformation and @code{.exports} file is searched
     457(as with used units). After the analysis phase of
     458the compiler, referenced toplevel variables for which no assignment was found will
     459generate a warning. Also, re-assignments of imported variables will trigger a warning.
    461460
    462461@item -check-syntax
     
    503502@item c
    504503print every expression before macro-expansion
    505 @item e
    506 lists all exported toplevel bindings
    507504@item u
    508505lists all unassigned global variable references
     
    549546@end table
    550547
    551 
    552548@item -debug-level LEVEL
    553549
    554550Selects amount of debug-information. @code{LEVEL} should be an integer.
    555551
    556 
     552 
    557553@itemize
    558 @item @code{-debug-level 0} is equivalent to @code{-no-trace}.
    559 @item @code{-debug-level 1} does nothing.
     554@item @code{-debug-level 0} is equivalent to @code{-no-trace -no-lambda-info}
     555@item @code{-debug-level 1} is equivalent to @code{-no-trace}
     556@item @code{-debug-level 2} does nothing (the default)
    560557@end itemize
     558 
    561559
    562560@item -disable-c-syntax-checks
     
    573571Disables detection of stack overflows. This is equivalent to running the compiled
    574572executable with the @code{-:o} runtime option.
     573
     574@item -disable-warning CLASS
     575Disables specific class of warnings, may be given multiple times. The following classes are
     576defined:
     577
     578@itemize
     579@item @code{usage}
     580warnings related to command-line arguments
     581@item @code{type}
     582warnings related to type-conversion
     583@item @code{ext}
     584warnings related to extension libraries
     585@item @code{var}
     586warnings related to variable- and syntax-definitions and use
     587@item @code{const}
     588warnings related to constant-definitions
     589@item @code{syntax}
     590syntax-related warnings
     591@item @code{redef}
     592warnings about redefinitions of standard- or extended-bindings
     593@item @code{call}
     594warnings related to known procedure calls
     595@item @code{ffi}
     596warnings related to the foreign function interface
     597@end itemize
    575598
    576599@item -dynamic
     
    583606@code{FILENAME} at the end of the compiled source file. The include-path
    584607is not searched. This option may be given multiple times.
     608
     609@item -emit-exports FILENAME
     610Write exported toplevel variables to @code{FILENAME}.
    585611
    586612@item -emit-external-prototypes-first
     
    604630extension-repository.
    605631
     632@item -extension
     633
     634Mostly equivalent to @code{-prelude '(define-extension <NAME>)'}, where
     635@code{<NAME>} is the basename of the currently compiled file.
     636Note that if you want to compile a file
     637as a normal (dynamically loadable) extension library, you should also pass the
     638@code{-shared} option.
     639
    606640@item -feature SYMBOL
    607641
     
    613647Parse C/C++ code and generate Scheme bindings. This is effectively
    614648equivalent to wrapping the code in @code{#>! ... <#}.
    615 
    616 @item -ffi-custom
    617 
    618 Parse C/C++ code and embed it into a @code{(foreign-parse/spec ...)}
    619 form. This is effectively equivalent to wrapping the code in @code{#>% ... <#}).
    620 Use the @code{-extend} or @code{-require-extension} options to provide
    621 a definition for the @code{foreign-parse/spec} macro.
    622649
    623650@item -ffi-parse
     
    702729Enable the optimization known as lambda-lifting.
    703730
     731@item -no-lambda-info
     732Don't emit additional information for each @code{lambda} expression (currently the argument-list,
     733after alpha-conversion/renaming).
     734
    704735@item -no-trace
    705736
     
    736767@item @code{-optimize-level 1} is equivalent to
    737768      @code{-optimize-leaf-routines}
    738 @item @code{-optimize-level 2} is equivalent to
    739       @code{-optimize-leaf-routines}
     769@item @code{-optimize-level 2} is currently the same as @code{-optimize-level 1}
    740770@item @code{-optimize-level 3} is equivalent to
    741771      @code{-optimize-leaf-routines -unsafe}
     
    775805timing information, if several entries for the same procedure calls exist.
    776806
     807@item -profile-name FILENAME
     808Specifies name of the generated profile information (which defaults to
     809@code{PROFILE}. Implies @code{-profile}.
     810
    777811@item -prologue FILENAME
    778812
     
    803837
    804838@item -split NUMBER
    805 Splits output into multiple C files that can be compiled seperately. The generated
     839Splits output into multiple C files that can be compiled separately. The generated
    806840C files will be named @code{filename0}, ..., @code{filename<NUMBER-1>} with as many
    807841files as given in @code{NUMBER}.
     
    891925@item -:d
    892926
    893 Prints some debug-information during startup.
     927Prints some debug-information at runtime.
     928
     929@item -:D
     930
     931Prints some more debug-information at runtime.
    894932
    895933@item -:hNUMBER
     
    936974finalization is forced.
    937975
     976@item -:aNUMBER
     977
     978Specifies the length of the buffer for recording a trace of the last
     979invoked procedures. Defaults to 16.
     980
    938981@item -:w
    939982
     
    944987
    945988Writes trace output to stderr. This option has no effect with
    946 in files compiled with the @code{-no-trace} or @code{-debug-level 0}
     989in files compiled with the @code{-no-trace}
    947990options.
    948991
     
    9921035@item Compile the file @code{foo.scm}
    9931036@verbatim
    994 % chicken foo.scm
    995 @end verbatim
    996 
    997 @item Compile the generated C file @code{foo.c}
    998 @verbatim
    999 % gcc foo.c -o foo `chicken-config -cflags -libs`
     1037% csc foo.scm
    10001038@end verbatim
    10011039
     
    10381076@end verbatim
    10391077
    1040 @item Compile the files @code{foo.scm} and @code{bar.scm}
    1041 @verbatim
    1042 % chicken foo.scm
    1043 % chicken bar.scm
    1044 @end verbatim
    1045 
    1046 @item Compile the generated C files @code{foo.c} and @code{bar.c}
    1047 @verbatim
    1048 % gcc -c foo.c `chicken-config -cflags`
    1049 % gcc -c bar.c `chicken-config -cflags`
    1050 @end verbatim
    1051 
    1052 @item Link the object files @code{foo.o} and @code{bar.o}
    1053 @verbatim
    1054 % gcc foo.o bar.o -o foo `chicken-config -libs`
     1078@item Compile and link the files @code{foo.scm} and @code{bar.scm}
     1079@verbatim
     1080% csc -c bar.scm
     1081% csc foo.scm bar.o -o foo
    10551082@end verbatim
    10561083
     
    11761203
    11771204Compiled to C, we get @code{hello.c}. We need the files @code{chicken.h} and
    1178 @code{runtime.c}, which contain the basic runtime system, plus @code{library.c},
    1179 the compiled form of @code{library.scm}, which contains the core library. Note
    1180 the use of the @code{-explicit-use -uses library} option in the invocation of @code{chicken} to make sure we
    1181 only link in the core library - the @code{eval} and @code{extras} library units are
    1182 not used in this example:
    1183 
    1184 @verbatim
    1185 % chicken hello.scm -explicit-use -uses hello.c -optimize-level 2 -debug-level 0
     1205@code{runtime.c}, which contain the basic runtime system, plus the three basic library
     1206files @code{library.c}, @code{eval.c} and @code{extras.c} which contain the same functionality as the
     1207library linked into a plain CHICKEN-compiled application, or which is available by default in the
     1208interpreter, @code{csi}:
     1209
     1210@verbatim
     1211% csc hello.scm -O2 -d1
    11861212@end verbatim
    11871213
     
    11911217# Makefile for UNIX systems
    11921218
    1193 hello: hello.o runtime.o library.o
    1194        $(CC) -o hello hello.o runtime.o library.o -lm
     1219hello: hello.o runtime.o library.o eval.o extras.o
     1220       $(CC) -o hello hello.o runtime.o library.o eval.o extras.o -lm
    11951221
    11961222hello.o: chicken.h
    11971223runtime.o: chicken.h
    11981224library.o: chicken.h
     1225eval.o: chicken.h
     1226extras.o: chicken.h
    11991227@end verbatim
    12001228
     
    12021230
    12031231@verbatim
    1204 % tar cf hello.tar Makefile hello.c runtime.c library.c chicken.h
     1232% tar cf hello.tar Makefile hello.c runtime.c library.c eval.c extras.c chicken.h
    12051233% gzip hello.tar
    12061234@end verbatim
     
    12101238more configuration- and build-time support. All this can be addressed using more
    12111239elaborate build-scripts, makefiles or by using autoconf/automake/libtool.
     1240
     1241Note also that the size of the application can still be reduced by removing @code{extras} and
     1242@code{eval} and compiling @code{hello.scm} with the @code{-explicit-use} option.
    12121243
    12131244For more information, study the CHICKEN source code
     
    13841415Show summary of available toplevel commands.
    13851416
    1386 @item ,l FILENAME
    1387 
    1388 Load file with given @code{FILENAME} (may be a symbol or string).
    1389 
    1390 @item ,ln FILENAME
    1391 
    1392 Load file and print result(s) of each top-level expression.
     1417@item ,l FILENAME ...
     1418
     1419Load files with given @code{FILENAME}s
     1420
     1421@item ,ln FILENAME ...
     1422
     1423Load files and print result(s) of each top-level expression.
    13931424
    13941425@item ,p EXP
     
    14081439Dump @code{N} bytes of the result of evaluated expression @code{EXP}.
    14091440
     1441@item ,exn
     1442
     1443Describes the last exception that occurred and adds it to the result history
     1444(it can be accessed using the @code{#} notation).
     1445
    14101446@item ,q
    14111447
     
    14161452Show system information.
    14171453
    1418 @item ,s STRING-OR-SYMBOL
     1454@item ,s TEXT ...
    14191455
    14201456Execute shell-command.
     
    14291465not evaluated).
    14301466
    1431 @end table
    1432 
    1433 @node Macros and procedures implemented in the interpreter
    1434 @section Macros and procedures implemented in the interpreter
    1435 
    1436 Additional macros and procedures available in the interpreter are:
    1437 
    1438 
    1439 @deffn {syntax} trace
    1440 @lisp
    1441 (trace NAME ...)
    1442 @end lisp
    1443 Switches tracing on for the procedures with the given names.
     1467@item ,tr SYMBOL ...
     1468
     1469Enables tracing of the toplevel procedures with the given names.
    14441470
    14451471@verbatim
    14461472#;1> (fac 10)                       ==> 3628800
    1447 #;2> (trace fac)
     1473#;2> ,tr fac
    14481474#;3> (fac 3)
    14491475|(fac 3)
     
    14551481| fac -> 2
    14561482|fac -> 6                          ==> 6
    1457 #;4> (untrace fac)
     1483#;4> ,utr fac
    14581484#;5> (fac 3)                        ==> 6
    14591485@end verbatim
    14601486
    1461 @end deffn
    1462 @deffn {syntax} untrace
    1463 @lisp
    1464 (untrace NAME ...)
    1465 @end lisp
    1466 Switches tracing of the given procedures off.
    1467 @end deffn
     1487@item ,utr SYMBOL ...
     1488
     1489Disables tracing of the given toplevel procedures.
     1490
     1491@item ,br SYMBOL ...
     1492
     1493Sets a breakpoint at the procedures named @code{SYMBOL ...}.
     1494
     1495Breakpoint can also be trigged using the @code{breakpoint} procedure.
     1496
     1497@item ,ubr SYMBOL ...
     1498
     1499Removes breakpoints.
     1500
     1501@item ,c
     1502
     1503Continues execution from the last invoked breakpoint.
     1504
     1505@item ,breakall
     1506
     1507Enable breakpoints for all threads (this is the default).
     1508
     1509@item ,breakonly THREAD
     1510
     1511Enable breakpoints only for the thread returned by the expression @code{THREAD}.
     1512
     1513@item ,what
     1514
     1515Lists traced procedures and breakpoints.
     1516
     1517@item ,step EXPR
     1518
     1519Evaluates @code{EXPR} in single-stepping mode. On each procedure call
     1520you will be presented with a menu that allows stepping to the next call,
     1521leaving single-stepping mode or triggering a breakpoint. Note that you will
     1522see some internal calls, and unsafe or heavily optimized compiled code
     1523might not be stepped at all. Single-stepping mode is also possible by
     1524invoking the @code{singlestep} procedure.
     1525
     1526@end table
     1527
     1528You can define your own toplevel commands using the @code{toplevel-command}
     1529procedure:
     1530
     1531@deffn {procedure} toplevel-command
     1532@lisp
     1533(toplevel-command SYMBOL PROC [HELPSTRING])
     1534@end lisp
     1535Defines or defines a toplevel interpreter command the can be invoked by entering
     1536@code{,SYMBOL}. @code{PROC} will be invoked when the command is entered and may
     1537read any required argument via @code{read} (or @code{read-line}). If the optional
     1538argument @code{HELPSTRING} is given, it will be listed by the @code{,?} command.
     1539@end deffn
     1540
     1541@node Macros and procedures implemented in the interpreter
     1542@section Macros and procedures implemented in the interpreter
     1543
     1544Additional macros and procedures available in the interpreter are:
     1545
    14681546
    14691547@deffn {read syntax} #[INDEX]
     
    14871565* Extensions to the standard:: 
    14881566* Non standard read syntax::   
    1489 * Non-standard macros and special forms:: 
     1567* Non-standard macros and special forms::
     1568* Pattern Matching::
    14901569* Declarations::               
    14911570* Parameters::                 
     
    15001579* Unit regex::                 
    15011580* Unit srfi-18::               
    1502 * Unit format::                 
    15031581* Unit posix::                 
    15041582* Unit utils::           
     
    15121590
    15131591[2] Identifiers are by default case-sensitive.
     1592
     1593[4.1.3] The maximal number of arguments that may be passed to a compiled
     1594procedure or macro is 120.  A macro-definition
     1595that has a single rest-parameter can have any number of arguments.
     1596
     1597If the @code{libffi} library is available on this platform, and if it
     1598is installed, then CHICKEN can take advantage
     1599of this. See the @code{README} file for more details.
     1600
     1601[4.3] @code{syntax-rules} macros are not provided but available separately.
     1602
     1603[6.2.4]  The runtime system uses the numerical string-conversion
     1604routines of the underlying C library and so does only understand standard
     1605(C-library) syntax for floating-point constants.
     1606
     1607[6.2.5] There is no built-in support for rationals, complex numbers or
     1608extended-precision integers (bignums).
     1609The routines @code{complex?}, @code{real?}
     1610and @code{rational?} are identical to the standard procedure
     1611@code{number?}. The procedures @code{numerator}, @code{denominator},
     1612@code{rationalize}, @code{make-rectangular} and @code{make-polar}
     1613are not implemented.
     1614
     1615Support for extended numbers is available as a separate package, provided
     1616the GNU multiprecision library is installed.
     1617
     1618[6.2.6] The procedure @code{string->number} does not obey read/write
     1619invariance on inexact numbers.
     1620
     1621[6.4] The maximum number of values that can be passed to continuations
     1622captured using @code{call-with-current-continuation} is 120.
     1623
     1624[6.5] Code evaluated in @code{scheme-report-environment} or
     1625@code{null-environment} still sees non-standard syntax.
     1626
     1627[6.6.2] The procedure @code{char-ready?} always returns
     1628@code{#t} for terminal ports.  The procedure @code{read} does not obey read/write
     1629invariance on inexact numbers.
     1630
     1631[6.6.3] The procedures @code{write} and @code{display} do not obey
     1632read/write invariance to inexact numbers.
     1633
     1634[6.6.4] The @code{transcript-on} and @code{transcript-off} procedures are
     1635not implemented.
     1636
     1637
     1638@node Extensions to the standard
     1639@section Extensions to the standard
     1640
     1641[2.1] Identifiers may contain special characters if delimited with
     1642@code{| ... |}.
     1643
     1644[2.3] The brackets @code{[ ... ]} are provided as an alternative syntax
     1645for @code{( ... )}.  A number of reader extensions is provided. See
     1646@ref{Non standard read syntax}.
     1647
     1648[4] Numerous non-standard macros are provided. See @ref{Non-standard
     1649macros and special forms} for more information.
    15141650
    15151651[4.1.4] Extended DSSSL style lambda lists are supported. DSSSL formal argument lists are defined by the following grammar:
     
    15341670@item Variables in required-formal-arguments are bound to successive actual arguments starting with the first actual argument. It shall be an error if there are fewer actual arguments than required-formal-arguments.
    15351671
    1536 @item Next, variables in optional-formal-arguments are bound to any remaining actual arguments. If there are fewer remaining actual arguments than optional-formal-arguments, then variables are bound to the result of the evaluation of initializer, if one was specified, and otherwise to @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound.
    1537 @item If there is a rest-formal-argument, then it is bound to a list of all remaining actual arguments. The remaining actual arguments are also eligible to be bound to keyword-formal-arguments. If there is no rest-formal-argument and there are no keyword-formal-arguments, the it shall be an error if there are any remaining actual arguments.
    1538 @item If @code{#!key} was specified in the formal-argument-list, there shall be an even number of remaining actual arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the argument name, and the second is the corresponding value. It shall be an error if the first member of a pair is not a keyword. It shall be an error if the argument name is not the same as a variable in a keyword-formal-argument, unless there is a rest-formal-argument. If the same argument name occurs more than once in the list of actual arguments, then the first value is used. If there is no actual argument for a particular keyword-formal-argument, then the variable is bound to the result of evaluating initializer if one was specified, and otherwise @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound.
     1672@item Next, variables in optional-formal-arguments are bound to any remaining actual arguments. If there are fewer remaining actual arguments than optional-formal-arguments, then variables are bound to the result of the evaluation of initializer, if one wed, and otherwise to @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound.
     1673@item If there is a rest-formal-argument, then it is bound to a list of all remaining actual arguments. The remaining actual arguments are also eligible to be bound to keyword-formal-arguments. If there is no rest-formal-argument and there are no keyword-uments, the it shall be an error if there are any remaining actual arguments.
     1674@item If @code{#!key} was specified in the formal-argument-list, there shall be an even number of remaining actual arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the argument name, and ths the corresponding value. It shall be an error if the first member of a pair is not a keyword. It shall be an error if the argument name is not the same as a variable in a keyword-formal-argument, unless there is a rest-formal-argument. If the same argument name occurs more than once in the list of actual arguments, then the first value is used. If there is no actual argument for a particular keyword-formal-argument, then the variable is bound to the result of evaluating initializer if one was spcfe,adohrise @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound.
    15391675@end enumerate
    15401676
     
    15521688@end verbatim
    15531689
    1554 [4.1.6] @code{set!} for unbound toplevel variables is allowed.
    1555 
    1556 [4.3] @code{syntax-rules} macros are not provided but available separately.
    1557 
    1558 [5.2] @code{define} with a single argument is allowed and initializes the toplevel or local binding
    1559 to an unspecified value. CHICKEN supports ``curried'' definitions, where the the variable name
    1560 may also be a list specifying a name and a nested lambda list. So
    1561 
    1562 @lisp
    1563 (define ((make-adder x) y) (+ x y))
    1564 @end lisp
    1565 
    1566 is equivalent to
    1567 
    1568 @lisp
    1569 (define (make-adder x) (lambda (y) (+ x y)))
    1570 @end lisp
    1571 
    1572 [6.2.4]  The runtime system uses the numerical string-conversion
    1573 routines of the underlying C library and so does only understand standard
    1574 (C-library) syntax for floating-point constants.
    1575 
    1576 [6.2.5]  The routines @code{complex?}, @code{real?}
    1577 and @code{rational?} are identical to the standard procedure
    1578 @code{number?}. The procedures @code{numerator}, @code{denominator}
    1579 and @code{rationalize} are not implemented.  Also not implemented are
    1580 all procedures related to complex numbers.
    1581 
    1582 [6.2.6] The procedure @code{string->number} does not obey read/write
    1583 invariance on inexact numbers.
    1584 
    1585 [6.5] Code evaluated in @code{scheme-report-environment} or
    1586 @code{null-environment} still sees non-standard syntax.
    1587 
    1588 [6.6.2] The procedure @code{char-ready?} always returns
    1589 @code{#t} for terminal ports.  The procedure @code{read} does not obey read/write
    1590 invariance on inexact numbers.
    1591 
    1592 [6.6.3] The procedures @code{write} and @code{display} do not obey
    1593 read/write invariance to inexact numbers.
    1594 
    1595 @node Extensions to the standard
    1596 @section Extensions to the standard
    1597 
    1598 [2.1] Identifiers may contain special characters if delimited with
    1599 @code{| ... |}.
    1600 
    1601 [2.3] The brackets @code{[ ... ]} are provided as an alternative syntax
    1602 for @code{( ... )}.  A number of reader extensions is provided. See
    1603 @ref{Non standard read syntax}.
    1604 
    1605 [4] Numerous non-standard macros are provided. See @ref{Non-standard
    1606 macros and special forms} for more information.
     1690[4.1.6] @code{set!} for unbound toplevel variables is allowed. @code{set! (PROCEDURE ...) ...)}
     1691is supported, as CHICKEN implements @uref{http://srfi.schemers.org/srfi-17/srfi-17.html, SRFI-17}.
     1692[4.2.1] The @code{cond} form supports @uref{http://srfi.schemers.org/srfi-61, SRFI-61}.
    16071693
    16081694[4.2.2] It is allowed for initialization values of bindings in a @code{letrec}
     
    16421728    (baz foo) ) )
    16431729@end verbatim
     1730
     1731[5.2] @code{define} with a single argument is allowed and initializes the toplevel or local binding
     1732to an unspecified value. CHICKEN supports ``curried'' definitions, where the the variable name
     1733may also be a list specifying a name and a nested lambda list. So
     1734
     1735@lisp
     1736(define ((make-adder x) y) (+ x y))
     1737@end lisp
     1738
     1739is equivalent to
     1740
     1741@lisp
     1742(define (make-adder x) (lambda (y) (+ x y)))
     1743@end lisp
    16441744
    16451745[6] CHICKEN provides numerous non-standard procedures. See the manual
     
    16641764backspace, ``\t'' TAB, ``\v'' vertical TAB, ``\a'' alarm, ``\f'' formfeed,
    16651765``\xXX'' a character with the code @code{XX} in hex and
    1666 ``\uXXXX'' (and ``\UXXXXXXXX'') a unicode character with the code @code{XXXX}, encoded in UTF-8 format.
     1766``\uXXXX'' (and ``\UXXXXXXXX'') a unicode character with the code @code{XXXX}.
     1767The latter is encoded in UTF-8 format.
    16671768
    16681769The third argument to @code{substring} is optional and defaults to the length
     
    17921893
    17931894@deffn {read syntax} #> ... <#
    1794 Abbreviation for @code{(declare (foreign-declare " ... "))}.
     1895Abbreviation for @code{foreign-declare " ... ")}.
    17951896@end deffn
    17961897
    17971898@deffn {read syntax} #>? ... <#
    1798 Abbreviation for @code{(declare (foreign-parse " ... "))}.
     1899Abbreviation for @code{(foreign-parse " ... ")}.
    17991900@end deffn
    18001901
    18011902@deffn {read syntax} #>! ... <#
    1802 Abbreviation for
    1803 
    1804 @verbatim
    1805 (declare
    1806   (foreign-declare " ... ")
    1807   (foreign-parse " ... ") )
    1808 @end verbatim
    1809 @end deffn
    1810 
    1811 @deffn {read syntax} #>$ ... <#
    1812 An abbreviation for
    1813 
    1814 @verbatim
    1815 (foreign-parse " ... ")
    1816 @end verbatim
    1817 @end deffn
    1818 
    1819 @deffn {read syntax} #>% ... <#
    1820 An abbreviation for
    1821 
    1822 @verbatim
    1823 (foreign-parse/spec " ... ")
    1824 @end verbatim
     1903Abbreviation for @code{(foreign-parse(declare " ... ")}.
    18251904@end deffn
    18261905
     
    18341913returned as normal symbols.
    18351914The special (self-evaluating) symbol @code{#!eof} is read as the end-of-file object.
     1915Note that if this constant appears at top-level in a loaded file, it is indistiguishable
     1916from normal end-of-file.
    18361917@end deffn
    18371918
     
    18421923@deffn {read syntax} #ci...
    18431924Read the next expression in case-insensitive mode (regardless of the current global setting).
     1925@end deffn
     1926
     1927@deffn {read syntax} #+FEATURE EXPR
     1928Equivalent to
     1929
     1930@lisp
     1931(cond-expand (FEATURE EXPR) (else))
     1932@end lisp
    18441933@end deffn
    18451934
     
    18821971@itemize
    18831972@item If @code{ID} names a built in features @code{chicken srfi-23 srfi-30 srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10
    1884 srfi-9}, then nothing is done.
    1885 @item If @code{ID} names one of syntactic extensions @code{chicken-match-macros chicken-more-macros chicken-default-entry-points
    1886  chicken-entry-points chicken-ffi-macros}, then this extension will be loaded.
     1973srfi-9 srfi-17 srfi-55}, then nothing is done.
     1974@item If @code{ID} names one of syntactic extensions @code{chicken-more-macros chicken-ffi-macros}, then this extension will be loaded.
    18871975@item If @code{ID} names one of the core library units shipped with CHICKEN, then a @code{(load-library 'ID)} will be performed.
    1888 If one of those libraries define specific syntax (@code{match srfi-13}), then the required source file defining the syntax
    1889 will be loaded.
    18901976@item If @code{ID} names an installed extension with the @code{syntax} or @code{require-at-runtime} attribute, then
    18911977the equivalent of @code{(require-for-syntax 'ID)} is performed.
     
    18971983@itemize
    18981984@item If @code{ID} names a built in features @code{chicken srfi-23 srfi-30 srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10
    1899  srfi-9}, then nothing is done.
    1900 @item If @code{ID} names one of syntactic extensions @code{chicken-match-macros chicken-more-macros chicken-default-entry-points
    1901  chicken-entry-points chicken-ffi-macros}, then this extension will be loaded
     1985 srfi-9 srfi-17 srfi-55}, then nothing is done.
     1986@item If @code{ID} names one of syntactic extensions @code{chicken-more-macros chicken-ffi-macros}, then this extension will be loaded
    19021987 at compile-time, making the syntactic extensions available in compiled code.
    19031988@item If @code{ID} names one of the core library units shipped with CHICKEN, then a @code{(declare (uses ID))} is generated.
    1904  If one of those libraries define specific syntax (@code{match srfi-13}), then the required source file defining the syntax
    1905  will be loaded at compile-time, making the syntactic extension available in compiled code.
    19061989@item If @code{ID} names an installed extension with the @code{syntax} or @code{require-at-runtime} attribute, then
    19071990 the equivalent of @code{(require-for-syntax 'ID)} is performed.
     
    19141997@code{ID} should be a pure extension name and should not contain any path prefixes (for example @code{dir/lib...}) is illegal).
    19151998
     1999@code{ID} may also be a list that designates an extension-specifier. Currently the following extension specifiers are
     2000defined:
     2001
     2002@itemize
     2003@item @code{(srfi NUMBER ...)} is required for SRFI-55 compatibility and is fully implemented
     2004@item @code{(version ID NUMBER)} is equivalent to @code{ID}, but checks at compile-time whether the extension named
     2005@code{ID} is installed and whether its version is equal or higher than @code{NUMBER}. @code{NUMBER} may be a string or a number,
     2006the comparison is done lexicographically (using @code{string>=?}).
     2007@end itemize
     2008
    19162009See also: @code{set-extension-specifier!}
    19172010
     
    19572050is also allowed and is identical to @code{(declare (export IDENTIFIER ...))} (unless the @code{define-extension} form
    19582051occurs in interpreted code, in with it is simply ignored).
     2052
     2053Note that the compiler option @code{-extension NAME} is equivalent to prefixing the
     2054compiled file with
     2055
     2056@lisp
     2057(define-extension NAME)
     2058@end lisp
    19592059@end deffn
    19602060
     
    20522152
    20532153@end deffn
     2154
     2155@deffn {syntax} rec
     2156@lisp
     2157(rec NAME EXPRESSION)
     2158(rec (NAME VARIABLE ...) BODY ...)
     2159@end lisp
     2160Allows simple definition of recursive definitions. @code{(rec NAME EXPRESSION)} is
     2161equivalent to @code{(letrec ((NAME EXPRESSION)) NAME)} and @code{(rec (NAME VARIABLE ...) BODY ...)}
     2162is the same as @code{(letrec ((NAME (lambda (VARIABLE ...) BODY ...))) NAME)}.
     2163@end deffn
     2164
    20542165@deffn {syntax} cut
    20552166@deffnx {syntax} cute
     
    22142325from @code{NAME2} to @code{NAME1}, creating an alias.
    22152326
    2216 @end deffn
    2217 
     2327Extended lambda list syntax (@code{#!optional}, etc.) can be used but note
     2328that arguments are source expressions and thus default values for optional
     2329or keyword arguments should take this into consideration.
     2330
     2331@end deffn
     2332
     2333@deffn {syntax} define-for-syntax
     2334@lisp
     2335(define-for-syntax (NAME VAR ... [. VAR]) EXP1 ...)
     2336(define-for-syntax NAME [VALUE])
     2337@end lisp
     2338Defines the toplevel variable @code{NAME} at macro-expansion time. This can
     2339be helpful when you want to define support procedures for use in macro-transformers,
     2340for example.
     2341@end deffn
    22182342
    22192343@node Conditional forms
     
    22652389@code{(NAME? STRUCT)} tests any object for being an instance of this
    22662390structure.  Slots are accessed via @code{(NAME-SLOTNAME STRUCT)}
    2267 and updated using @code{(NAME-SLOTNAME-set!} @code{STRUCT}
    2268 @code{VALUE)}.
     2391and updated using @code{(NAME-SLOTNAME-set!} @code{STRUCT} @code{VALUE)}.
    22692392
    22702393@verbatim
     
    23122435@end lisp
    23132436SRFI-9 record types. For more information see the documentation for
    2314 @uref{http://srfi.schemers.org/srfi-9/srfi-9.html, SRFI-9 }
     2437@uref{http://srfi.schemers.org/srfi-9/srfi-9.html, SRFI-9 }.
    23152438@end deffn
    23162439
     
    23252448(assert EXP [STRING ARG ...])
    23262449@end lisp
    2327 Signal error if @code{EXP} evaluates to false. An optional message
     2450Signals an error if @code{EXP} evaluates to false. An optional message
    23282451@code{STRING} and arguments @code{ARG ...} may be supplied to give a
    23292452more informative error-message.  If compiled in @emph{unsafe} mode (either
    23302453by specifying the @code{-unsafe} compiler option or by declaring
    23312454@code{(unsafe)}), then this expression expands to an unspecified value.
     2455The result is the value of @code{EXP}.
    23322456
    23332457@end deffn
     
    24192543(time EXP1 ...)
    24202544@end lisp
    2421 Evaluates @code{EXP1 ...} and print elapsed time and memory
    2422 information. The result of the last expression is returned.
    2423 @end deffn
     2545Evaluates @code{EXP1 ...} and prints elapsed time and some
     2546values about GC use, like time spent in major GCs, number of minor
     2547and major GCs.
     2548@end deffn
     2549
     2550
     2551@node Pattern Matching
     2552@section Pattern Matching
     2553
     2554(This description has been taken mostly from Andrew Wright's postscript
     2555document)
     2556
     2557Pattern matching allows complicated control decisions based on data
     2558structure to be expressed in a concise manner.  Pattern matching is
     2559found in several modern languages, notably Standard ML, Haskell and
     2560Miranda. These syntactic extensions internally use the @code{match}
     2561library unit.
     2562
     2563The basic form of pattern matching expression is:
     2564@lisp
     2565(match exp [pat body] ...)
     2566@end lisp
     2567
     2568where @code{exp} is an expression, @code{pat} is a pattern, and
     2569@code{body} is one or more expressions
     2570(like the body of a lambda-expression).
     2571The @code{match} form matches its first subexpression against a sequence
     2572of patterns, and branches to the @code{body}
     2573corresponding to the first pattern successfully matched.
     2574For example, the following code defines the usual @code{map} function:
     2575
     2576@lisp
     2577(define map
     2578  (lambda (f l)
     2579    (match l
     2580      [() ()]
     2581      [(x . y) (cons (f x) (map f y))])))
     2582@end lisp
     2583
     2584The first pattern @code{()} matches the empty list.  The second pattern
     2585@code{(x . y)} matches a pair, binding @code{x} to the first component of
     2586the pair and @code{y} to the second component of the pair.
     2587
     2588
     2589@subsection Pattern Matching Expressions
     2590
     2591The complete syntax of the pattern matching expressions follows:
     2592
     2593@verbatim
     2594exp ::= (match exp clause ...)
     2595     |  (match-lambda clause ...)
     2596     |  (match-lambda* clause ...)
     2597     |  (match-let ([pat exp] ...) body)
     2598     |  (match-let* ([pat exp] ...) body)
     2599     |  (match-letrec ([pat exp] ...) body)
     2600     |  (match-let var ([pat exp] ...) body)
     2601     |  (match-define pat exp)
     2602
     2603clause ::= [pat body]
     2604        |  [pat (=> identifier) body]
     2605
     2606pat ::= identifier           matches anything, and binds identifier as a variable
     2607     |  _                    anything
     2608     |  ()                   itself (the empty list)
     2609     |  #t                   itself
     2610     |  #f                   itself
     2611     |  string               an `equal?' string
     2612     |  number               an `equal?' number
     2613     |  character            an `equal?' character
     2614     |  's-expression        an `equal?' s-expression
     2615     |  (pat-1 ... pat-n)    a proper list of n elements
     2616     |  (pat-1 ... pat-n . pat-n+1) 
     2617                             a list of n or more elements
     2618     |  (pat-1 ... pat-n pat-n+1 ..k) 
     2619                             a proper list of n+k or more elements [1]
     2620     |  #(pat-1 ... pat-n)   a vector of n elements
     2621     |  #(pat-1 ... pat-n pat-n+1 ..k) 
     2622                             a vector of n+k or more elements
     2623     |  ($ struct pat-1 ... pat-n) 
     2624                             a structure
     2625     |  (= field pat)        a field of a structure
     2626     |  (and pat-1 ... pat-n) 
     2627                             if all of pat-1 through pat-n match
     2628     |  (or pat-1 ... pat-n)
     2629                             if any of pat-1 through pat-n match
     2630     |  (not pat-1 ... pat-n)
     2631                             if none of pat-1 through pat-n match
     2632     |  (? predicate pat-1 ... pat-n) 
     2633                             if predicate true and pat-1 through pat-n all match
     2634     |  (set! identifier)    anything, and binds identifier as a setter
     2635     |  (get! identifier)    anything, and binds identifier as a getter
     2636     |  `qp                  a quasipattern
     2637
     2638qp ::= ()                    itself (the empty list)
     2639    |  #t                    itself
     2640    |  #f                    itself
     2641    |  string                an `equal?' string
     2642    |  number                an `equal?' number
     2643    |  character             an `equal?' character
     2644    |  symbol                an `equal?' symbol
     2645    |  (qp-1 ... qp-n)       a proper list of n elements
     2646    |  (qp-1 ... qp-n . qp-n+1) 
     2647                             a list of n or more elements
     2648    |  (qp-1 ... qp-n qp-n+1 ..k) 
     2649                             a proper list of n+k or more elements
     2650    |  #(qp-1 ... qp-n)      a vector of n elements
     2651    |  #(qp-1 ... qp-n qp-n+1 ..k) 
     2652                             a vector of n+k or more elements
     2653    |  ,pat                  a pattern
     2654    |  ,@pat                 a pattern, spliced
     2655@end verbatim
     2656
     2657The notation @code{..k} denotes a keyword consisting of
     2658three consecutive dots (ie., ``@code{...}''),
     2659or two dots and an non-negative integer (eg., ``@code{..1}'', ``@code{..2}''),
     2660or three consecutive underscores (ie., ``@code{___}''),
     2661or two underscores and a non-negative integer.
     2662The keywords ``@code{..k}'' and ``@code{__ k}'' are equivalent.
     2663The keywords ``@code{...}'', ``@code{___}'', ``@code{..0}'', and ``@code{__0}''
     2664are equivalent.
     2665
     2666The next subsection describes the various patterns.
     2667
     2668The @code{match-lambda} and @code{match-lambda*} forms are convenient
     2669combinations of @code{match} and @code{lambda}, and can be explained
     2670as follows:
     2671
     2672@lisp
     2673(match-lambda [pat body] ...)   =  (lambda (x) (match x [pat body] ...))
     2674(match-lambda* [pat body] ...)  =  (lambda x (match x [pat body] ...))
     2675@end lisp
     2676
     2677where @code{x} is a unique variable.
     2678The @code{match-lambda} form is convenient when defining a single argument
     2679function that immediately destructures its argument.
     2680The @code{match-lambda*} form constructs a function that accepts any number
     2681of arguments; the patterns of @code{match-lambda*} should be lists.
     2682
     2683The @code{match-let}, @code{match-let*}, @code{match-letrec},
     2684and @code{match-define} forms generalize
     2685Scheme's @code{let}, @code{let*}, @code{letrec}, and @code{define}
     2686expressions to allow
     2687patterns in the binding position rather than just variables.
     2688For example, the following expression:
     2689
     2690@lisp
     2691(match-let ([(x y z) (list 1 2 3)]) body ...)
     2692@end lisp
     2693
     2694binds @code{x} to 1, @code{y} to 2, and @code{z} to 3 in @code{body ...}.
     2695These forms are convenient for destructuring the result
     2696of a function that returns multiple values as a list or vector.
     2697As usual for @code{letrec} and @code{define},
     2698pattern variables bound by @code{match-letrec} and @code{match-define}
     2699should not be used in computing the bound value.
     2700
     2701The @code{match}, @code{match-lambda}, and @code{match-lambda*} forms
     2702allow the optional syntax @code{(=> identifier)} between the pattern
     2703and the body of a clause.  When the pattern match for such a clause
     2704succeeds, the @code{identifier} is bound to a `failure
     2705procedure' of zero arguments within the @code{body}.  If this
     2706procedure is invoked, it jumps back to the pattern matching
     2707expression, and resumes the matching process as if the pattern had
     2708failed to match.  The @code{body} must not mutate the object being
     2709matched, otherwise unpredictable behavior may result.
     2710
     2711
     2712@subsection Patterns
     2713
     2714@code{identifier}: (excluding the reserved names
     2715@code{?}, @code{,}, @code{=}, @code{_}, @code{and}, @code{or}, @code{not}, @code{set!}, @code{get!}, @code{...}, and
     2716@code{..k} for non-negative integers @code{k})
     2717matches anything, and binds a variable of this name to
     2718the matching value in the @code{body}.
     2719
     2720@code{_}:
     2721matches anything, without binding any variables.
     2722
     2723@code{()}, @code{#t}, @code{#f}, @code{string}, @code{number},
     2724@code{character}, '@code{s-expression}:
     2725These constant patterns match themselves, i.e.,
     2726the corresponding value must be @code{equal?} to the pattern.
     2727
     2728@code{(pat-1 ... pat-n)}:
     2729matches a proper list of @code{n} elements
     2730that match @code{pat-1} through @code{pat-n}.
     2731
     2732@code{(pat-1 ... pat-n . pat-n+1)}:
     2733matches a (possibly improper) list of at least @code{n}
     2734elements that ends in
     2735something matching @code{pat-n+1}.
     2736
     2737@code{(pat-1 ... pat-n pat-n+1 ...)}:
     2738matches a proper list of @code{n} or more elements, where
     2739each element of the tail matches @code{pat-n+1}.  Each pattern variable in
     2740@code{pat-n+1} is bound to a list of the matching values.  For example,
     2741the expression:
     2742
     2743@lisp
     2744(match '(let ([x 1][y 2]) z)
     2745  [('let ((binding values) ...) exp)  body])
     2746@end lisp
     2747
     2748binds @code{binding} to the list @code{'(x y)},
     2749@code{values} to the list \@code{'(1 2)},
     2750and @code{exp} to @code{'z}
     2751in the body of the @code{match}-expression.
     2752For the special case where @code{pat-n+1} is a pattern variable, the list
     2753bound to that variable may share with the matched value.
     2754
     2755@code{(pat-1 ... pat-n pat-n+1 ___)}:
     2756This pattern means the same thing as the previous pattern.
     2757
     2758@code{(pat-1 ... pat-n pat-n+1 ..k)}:
     2759This pattern is similar to the previous pattern, but the tail must be
     2760at least @code{k} elements long.
     2761The pattern keywords @code{..0} and @code{...} are equivalent.
     2762
     2763@code{(pat-1 ... pat-n ~ pat-n+1 __k)}:
     2764This pattern means the same thing as the previous pattern.
     2765
     2766@code{#(pat-1 ... pat-n)}:
     2767matches a vector of length @code{n}, whose elements match
     2768@code{pat-1} through @code{pat-n}.
     2769
     2770@code{#(pat-1 ... pat-n pat-n+1 ...)}:
     2771matches a vector of length @code{n} or more, where each element
     2772beyond @code{n} matches @code{pat-n+1}.
     2773
     2774@code{#(pat-1 ... pat-n pat-n+1 ..k)}:
     2775matches a vector of length @code{n+k} or more, where each element
     2776beyond @code{n} matches @code{pat-n+1}.
     2777
     2778@code{($ struct pat-1 ... pat-n)}:
     2779matches a structure
     2780declared with @code{define-record} or @code{define-record-type}.
     2781
     2782@code{(= field pat)}:
     2783is intended for selecting a field from a structure.  ``field'' may be
     2784any expression; it is applied to the value being matched, and the
     2785result of this application is matched against @code{pat}.
     2786
     2787@code{(and pat-1 ... pat-n)}:
     2788matches if all of the subpatterns match.
     2789At least one subpattern must be present.
     2790This pattern is often used as @code{(and x pat)} to bind @code{x} to
     2791to the entire value that matches @code{pat}
     2792(cf. ``as-patterns'' in ML or Haskell).
     2793
     2794@code{(or pat-1 ... pat-n)}:
     2795matches if any of the subpatterns match.
     2796At least one subpattern must be present.
     2797All subpatterns must bind the same set of pattern variables.
     2798
     2799@code{(not pat-1 ... pat-n)}:
     2800matches if none of the subpatterns match.
     2801At least one subpattern must be present.
     2802The subpatterns may not bind any pattern variables.
     2803
     2804@code{(? predicate pat-1 ... pat-n)}:
     2805In this pattern,
     2806@code{predicate} must be an expression evaluating to a single argument
     2807function.
     2808This pattern matches if @code{predicate} applied to the corresponding value
     2809is true, and the subpatterns @code{pat-1 ... pat-n} all match.
     2810The @code{predicate} should not have side effects, as
     2811the code generated by the pattern matcher may invoke predicates repeatedly
     2812in any order.
     2813The @code{predicate} expression is bound in the same scope as the
     2814match expression, i.e.,
     2815free variables in @code{predicate} are not bound by pattern variables.
     2816
     2817@code{(set! identifier)}:
     2818matches anything, and binds @code{identifier}
     2819to a procedure of one argument that mutates the corresponding field of
     2820the matching value.
     2821This pattern must be nested within a pair, vector, box, or structure
     2822pattern. For example, the expression:
     2823
     2824@lisp
     2825(define x (list 1 (list 2 3)))
     2826(match x [(_ (_ (set! setit)))  (setit 4)])
     2827@end lisp
     2828
     2829mutates the @code{cadadr} of @code{x} to 4, so that @code{x} is
     2830@code{'(1 (2 4))}.
     2831
     2832@code{(get! identifier)}:
     2833matches anything, and binds @code{identifier}
     2834to a procedure of zero arguments that accesses the corresponding field of
     2835the matching value.  This pattern is the complement to @code{set!}.
     2836As with @code{set!},
     2837this pattern must be nested within a pair, vector, box, or structure
     2838pattern.
     2839
     2840@emph{Quasipatterns}:
     2841Quasiquote introduces a quasipattern, in which identifiers are considered
     2842to be symbolic constants.  Like Scheme's quasiquote for data,
     2843@code{unquote} (,) and @code{unquote-splicing} (,@@) escape back to
     2844normal patterns.
     2845
     2846
     2847@subsection Match Failure
     2848
     2849If no clause matches the value, the default action
     2850is to invoke the procedure @code{##sys#match-error}
     2851with the value that did not match.  The default definition of
     2852@code{##sys#match-error} calls @code{error} with an appropriate message:
     2853
     2854@verbatim
     2855#;1> (match 1 (2 2))
     2856
     2857Failed match:
     2858Error: no matching clause for : 1
     2859@end verbatim
     2860
     2861For most situations, this behavior is adequate, but it can be changed
     2862by altering the value of the parameter @code{match-error-control}:
     2863
     2864@deffn {procedure} match-error-control
     2865@lisp
     2866(match-error-control [MODE])
     2867@end lisp
     2868Selects a mode that specifies how @code{match...} macro forms are to
     2869be expanded.  With no argument this procedure returns the current mode. A
     2870single argument specifies the new mode that decides what should happen
     2871if no match-clause applies.  The following modes are supported:
     2872
     2873@table @code
     2874
     2875@item #:error
     2876
     2877Signal an error. This is the default.
     2878
     2879@item #:match
     2880
     2881Signal an error and output the offending form.
     2882
     2883@item #:fail
     2884
     2885Omits @code{pair?} tests when the consequence is to fail in @code{car}
     2886or @code{cdr} rather than to signal an error.
     2887
     2888@item #:unspecified
     2889
     2890Non-matching expressions will either fail in @code{car} or @code{cdr}
     2891or return an unspecified value.  This mode applies to files compiled
     2892with the @code{unsafe} option or declaration.
     2893
     2894@end table
     2895
     2896When an error is signalled, the raised exception will be of kind @code{(exn match)}.
     2897
     2898@end deffn
     2899
     2900
     2901Note: the @code{$} pattern handles native record structures and SRFI-9 records transparently.
     2902Currently it is required that SRFI-9 record predicates are named exactly like the record type
     2903name, followed by a @code{?} (question mark) character.
     2904
     2905
     2906@subsection Code Generation
     2907
     2908Pattern matching macros are compiled into @code{if}-expressions
     2909that decompose the value being matched with standard
     2910Scheme procedures, and test the components with standard predicates.
     2911Rebinding or lexically shadowing the names of any of these procedures
     2912will change the
     2913semantics of the @code{match} macros.  The names that should not be
     2914rebound or shadowed are:
     2915
     2916@lisp
     2917null? pair? number? string? symbol? boolean? char? procedure? vector? list?
     2918equal?
     2919car cdr cadr cdddr ...
     2920vector-length vector-ref
     2921reverse length call/cc
     2922@end lisp
     2923
     2924Additionally, the code generated to match a structure pattern like
     2925@code{($ Foo pat-1 ... pat-n)}
     2926refers to the name @code{Foo?}.
     2927This name also should not be shadowed.
    24242928
    24252929
     
    25123016@end deffn
    25133017
     3018@deffn {declaration-specifier} emit-exports
     3019@lisp
     3020(emit-exports STRING)
     3021@end lisp
     3022Write exported toplevel variables to file with name @code{STRING}.
     3023@end deffn
     3024
    25143025@deffn {declaration specifier} emit-external-prototypes-first
    25153026@lisp
     
    25213032@end deffn
    25223033
    2523 
    2524 @deffn {declaration specifier} foreign-declare
    2525 @lisp
    2526 (foreign-declare STRING ...)
    2527 @end lisp
    2528 Include given strings verbatim into header of generated file.
    2529 @end deffn
    2530 
    2531 @deffn {declaration specifier} foreign-parse
    2532 @lisp
    2533 (foreign-parse STRING ...)
    2534 @end lisp
    2535 Parse given strings and generate foreign-interface bindings. See @ref{The Easy Foreign Function Interface}
    2536 for more information.
    2537 @end deffn
    2538 
    25393034@deffn {declaration specifier} disable-interrupts
    25403035@lisp
     
    25443039Disable timer-interrupts checks in the compiled program. Threads can
    25453040not be preempted in main- or library-units that contain this declaration.
     3041@end deffn
     3042
     3043@deffn {declaration specifier} disable-warning
     3044@lisp
     3045(disable-warning CLASS ...)
     3046@end lisp
     3047Disable warnings of type @code{CLASS ...} (equivalent to the @code{-disable-warning CLASS}
     3048compiler option).
    25463049@end deffn
    25473050
     
    27703273
    27713274@end defvr
     3275
     3276@defvr {parameter} current-read-table
     3277A read-table object that holds read-procedures for special non-standard
     3278read-syntax (see @code{set-read-syntax!} for more information).
     3279@end defvr
     3280
    27723281@defvr {parameter} exit-handler
    27733282A procedure of a single optional argument. When @code{exit} is called,
     
    27923301A procedure of no arguments. When the last toplevel expression of the
    27933302program has executed, then the value of this parameter is called. The
    2794 default behaviour is to do nothing, or, if one or more entry-points
    2795 were defined (see: @ref{Entry points}) to enter a loop that waits for
    2796 callbacks from the host program.
     3303default behaviour is to invoke all pending finalizers.
    27973304
    27983305@end defvr
     
    28503357* The unspecified value::       
    28513358* Continuations::                     
     3359* Setters::
    28523360@end menu
    28533361
     
    29803488@end lisp
    29813489Returns @code{1} if @code{N} is positive, @code{-1} if @code{N}
    2982 is negative or @code{0} if @code{N} is zero.
     3490is negative or @code{0} if @code{N} is zero. @code{signum} is exactness preserving.
    29833491@end deffn
    29843492
     
    30523560(file-exists? STRING)
    30533561@end lisp
    3054 Returns @code{#t} if a file with the given pathname exists, or
     3562Returns @code{STRING} if a file with the given pathname exists, or
    30553563@code{#f} otherwise.
    30563564
    30573565@end deffn
    3058 @defvr {variable} pathname-directory-separator
    3059 Contains the directory-separator character for pathnames on this platform.
    3060 
    3061 @end defvr
    3062 @defvr {variable} pathname-extension-separator
    3063 Contains the extension-separator character for pathnames on this platform.
    3064 
    3065 @end defvr
    30663566@deffn {procedure} rename-file
    30673567@lisp
     
    31283628@end deffn
    31293629
    3130 @deffn {procedure} test-feature?
    3131 @lisp
    3132 (test-feature? ID ...)
     3630@deffn {procedure} feature?
     3631@lisp
     3632(feature? ID ...)
    31333633@end lisp
    31343634Returns @code{#t} if all features with the given feature-identifiers @code{ID ...}
     
    32573757@end deffn
    32583758
     3759@deffn {procedure} breakpoint
     3760@lisp
     3761(breakpoint [NAME])
     3762@end lisp
     3763Programmatically triggers a breakpoint (similar to the @code{,br} top-level csi command).
     3764@end deffn
    32593765
    32603766
     
    33083814
    33093815Signalled on syntax errors.
     3816
     3817@item (exn breakpoint)
     3818
     3819Signalled when a breakpoint is reached.
    33103820
    33113821@end table
     
    33173827@item Error-exceptions of the @code{exn} kind have additional
    33183828@code{arguments} and @code{location} properties that contain the
    3319 arguments passed to the error-handler and the name of the procedure
     3829arguments passed to the exception-handler and the name of the procedure
    33203830where the error occurred (if available).
    33213831
     
    33263836@item the procedure @code{condition-property-accessor} accepts an optional
    33273837third argument. If the condition does not have a value for the desired property
    3328 and if the optional argument is given and false, no error is signalled and
    3329 the accessor returns @code{#g}.
     3838and if the optional argument is given, no error is signalled and
     3839the accessor returns the third argument.
     3840
     3841@item In composite conditionss all properties are currently collected in a single
     3842property-list, so in the case that to conditions have the same named property, only
     3843one will be visible.
    33303844
    33313845@end itemize
     
    33693883gnu
    33703884metrowerks
     3885intel
     3886watcom
    33713887unknown
    33723888@end verbatim
     
    33973913
    33983914@end deffn
     3915
     3916@deffn {procedure} machine-byte-order
     3917@lisp
     3918(machine-byte-order)
     3919@end lisp
     3920Returns the symbol @code{little-endian} or @code{big-endian}, depending on the machine's byte-order.
     3921@end deffn
     3922
    33993923@deffn {procedure} machine-type
    34003924@lisp
     
    35124036@end deffn
    35134037
    3514 
     4038@deffn {procedure} current-gc-milliseconds
     4039@lisp
     4040(current-gc-milliseconds)
     4041@end lisp
     4042Returns the number of milliseconds spent in major garbage collections since
     4043the last call of @code{current-gc-milliseconds} and returns an exact
     4044integer.
     4045@end deffn
    35154046
    35164047
     
    35544085Prints error message, writes all extra arguments to the
    35554086value of @code{(current-error-port)} and invokes the
    3556 current value of @code{(error-handler)}.  This conforms to
     4087current exception-handler.  This conforms to
    35574088@uref{http://srfi.schemers.org/srfi-23/srfi-23.html, SRFI-23 }.
    35584089If @code{LOCATION} is given and a symbol, it specifies the ``location'' (the name
     
    35604091
    35614092@end deffn
    3562 @deffn {procedure} print-backtrace
    3563 @lisp
    3564 (print-backtrace [PORT])
     4093
     4094@deffn {procedure} get-call-chain
     4095@lisp
     4096(get-call-chain [START [THREAD]])
     4097@end lisp
     4098Returns a list with the call history. Backtrace information
     4099is only generated in code compiled without @code{-no-trace} and evaluated code.
     4100If the optional argument @code{START} is given, the backtrace starts
     4101at this offset, i.e. when @code{START} is 1, the next to last trace-entry
     4102is printed, and so on. If the optional argument @code{THREAD} is given, then
     4103the call-chain will only be constructed for calls performed by this thread.
     4104
     4105@end deffn
     4106
     4107@deffn {procedure} print-call-chain
     4108@lisp
     4109(print-call-chain [PORT [START [THREAD]]])
    35654110@end lisp
    35664111Prints a backtrace of the procedure call history to @code{PORT},
    3567 which defaults to @code{(current-error-port)}. Backtrace information
    3568 is only generated in compiled code, with a @code{-debug-level} >= 1.
     4112which defaults to @code{(current-output-port)}.
    35694113
    35704114@end deffn
     
    35744118@end lisp
    35754119Prints an appropriate error message to @code{PORT} (which defaults to the
    3576 value of @code{(current-error-port)} for the object @code{EXN}.
     4120value of @code{(current-output-port)} for the object @code{EXN}.
    35774121@code{EXN} may be a condition, a string or any other object.
    35784122If the optional argument @code{STRING} is given, it is printed before the
     
    35804124
    35814125@end deffn
     4126
     4127@deffn {procedure} procedure-information
     4128@lisp
     4129(procedure-information PROC)
     4130@end lisp
     4131Returns an s-expression with debug information for the procedure @code{PROC}, or
     4132@code{#f}, if @code{PROC} has no associated debug information.
     4133@end deffn
     4134
    35824135@deffn {procedure} reset
    35834136@lisp
     
    35874140@end deffn
    35884141
    3589 
     4142@deffn {procedure} warning
     4143@lisp
     4144(warning STRING EXP ...)
     4145@end lisp
     4146Displays a warning message (if warnings are enabled with @code{enable-warnings}) and
     4147continues execution.
     4148@end deffn
     4149
     4150@deffn {procedure} singlestep
     4151@lisp
     4152(singlestep THUNK)
     4153@end lisp
     4154Executes the code in the zero-procedure @code{THUNK} in single-stepping mode.
     4155@end deffn
    35904156
    35914157
     
    36674233@end deffn
    36684234
     4235@deffn {procedure} promise?
     4236@lisp
     4237(promise? X)
     4238@end lisp
     4239Returns @code{#t} if @code{X} is a promise returned by @code{delay}, or
     4240@code{#f} otherwise.
     4241@end deffn
    36694242
    36704243
     
    38364409
    38374410More information about this continuation API can be found in the paper
    3838 @uref{http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf ``A Better API for first class
    3839 Continuations''} by marc Feeley.
     4411@uref{http://repository.readscheme.org/ftp/papers/sw2001/feeley.pdf} ``A Better API for first class
     4412Continuations'' by Marc Feeley.
    38404413@end deffn
    38414414
     
    38684441    (lambda () (apply values vals)) ) )
    38694442@end lisp
     4443@end deffn
     4444
     4445
     4446@node Setters
     4447@subsection Setters
     4448
     4449SRFI-17 is fully implemented. For more information see: @uref{http://srfi.schemers.org/srfi-17/srfi-17.html, SRFI-17}
     4450
     4451@deffn {procedure} setter
     4452@lisp
     4453(setter PROCEDURE)
     4454@end lisp
     4455Returns the setter-procedure of @code{PROCEDURE}, or signals an error if @code{PROCEDURE}
     4456has no associated setter-procedure.
     4457
     4458Note that @code{(set! (setter PROC) ...)} for a procedure that has no associated setter procedure
     4459yet is a very slow operation (the old procedure is replaced by a modified copy, which involves a
     4460garbage collection).
     4461@end deffn
     4462
     4463@deffn {procedure} getter-with-setter
     4464@lisp
     4465(getter-with-setter GETTER SETTER)
     4466@end lisp
     4467Returns a copy of the procedure @code{GETTER} with the associated setter procedure @code{SETTER}.
     4468Contrary to the SRFI specification, the setter of the returned procedure may be changed.
    38704469@end deffn
    38714470
     
    39054504% cat x.scm
    39064505(define (hello) (print "Hello!"))
    3907 % chicken x.scm -quiet -dynamic
    3908 % gcc x.c -shared -fPIC `chicken-config -cflags -shared -libs` -o x.so
    3909 % csi -quiet
     4506% csc -s x.scm
     4507% csi -q
    39104508#;1> (load "x.so")
    39114509; loading x.so ...
     
    39164514
    39174515The second argument to @code{load} is ignored when loading compiled
    3918 code.  The same compiled object file can not be loaded more than once.
     4516code.
    39194517If source code is loaded from a port, then that port is closed after
    39204518all expressions have been read.
    39214519
    3922 @end deffn
    3923 @deffn {procedure} load-library
    3924 @lisp
    3925 (load-library UNIT [LIBRARYFILE])
    3926 @end lisp
    3927 On platforms that support dynamic loading, @code{load-library} loads
    3928 the compiled library unit @code{UNIT} (which should be a symbol). If the
    3929 string @code{LIBRARYFILE} is given, then the given shared library will
    3930 be loaded and the toplevel code of the contained unit will be executed.
    3931 If no @code{LIBRARYFILE} argument is given, then the following libraries
    3932 are checked for the required unit:
    3933 
    3934 @itemize
    3935 @item a file named ``@code{<UNIT>.so}''
    3936 
    3937 @item the files given in the parameter @code{dynamic-load-libraries}
    3938 
    3939 @end itemize
    3940 
    3941 If the unit is not found, an error is signaled.  When the library unit
    3942 can be successfully loaded, a feature-identifier named @code{UNIT}
    3943 is registered. If the feature is already registered before loading,
    3944 the @code{load-library} does nothing.
    3945 
    3946 @end deffn
     4520Compiled code can be re-loaded, but care has to be taken, if code
     4521from the replaced dynamically loaded module is still executing (i.e.
     4522if an active continuation refers to compiled code in the old module).
     4523
     4524Support for realoding compiled code dynamically is still experimental.
     4525   
     4526@end deffn
     4527@deffn {procedure} load-relative
     4528@lisp
     4529(load-relative FILE [EVALPROC])
     4530@end lisp
     4531Similar to @code{load}, but loads @code{FILE} relative to the path
     4532of the currently loaded file.
     4533@end deffn
     4534
    39474535@deffn {procedure} load-noisily
    39484536@lisp
     
    39594547@end deffn
    39604548
     4549@deffn {procedure} load-library
     4550@lisp
     4551(load-library UNIT [LIBRARYFILE])
     4552@end lisp
     4553On platforms that support dynamic loading, @code{load-library} loads
     4554the compiled library unit @code{UNIT} (which should be a symbol). If the
     4555string @code{LIBRARYFILE} is given, then the given shared library will
     4556be loaded and the toplevel code of the contained unit will be executed.
     4557If no @code{LIBRARYFILE} argument is given, then the following libraries
     4558are checked for the required unit:
     4559
     4560@itemize
     4561@item a file named ``@code{<UNIT>.so}''
     4562
     4563@item the files given in the parameter @code{dynamic-load-libraries}
     4564
     4565@end itemize
     4566
     4567If the unit is not found, an error is signaled.  When the library unit
     4568can be successfully loaded, a feature-identifier named @code{UNIT}
     4569is registered. If the feature is already registered before loading,
     4570the @code{load-library} does nothing.
     4571
     4572@end deffn
    39614573@deffn {procedure} set-dynamic-load-mode!
    39624574@lisp
     
    40024614Start a new read-eval-print loop. Sets the @code{reset-handler} so that
    40034615any invocation of @code{reset} restarts the read-eval-print loop. Also
    4004 changes the current @code{error-handler} to display a message, write
     4616changes the current exception-handler to display a message, write
    40054617any arguments to the value of @code{(current-error-port)} and reset.
    40064618@end deffn
     
    40804692@end deffn
    40814693
    4082 @deffn {procedure} extension-info
    4083 @lisp
    4084 (extension-info ID)
     4694@deffn {procedure} extension-information
     4695@lisp
     4696(extension-information ID)
    40854697@end lisp
    40864698If an extension with the name @code{ID} is installed and if it has a setup-information
    40874699list registered in the extension repository, then the info-list is returned. Otherwise
    4088 @code{extension-info} returns @code{#f}.
     4700@code{extension-information} returns @code{#f}.
    40894701@end deffn
    40904702
     
    41244736@item the current include path, which defaults to the pathnames
    41254737given in @code{CHICKEN_INCLUDE_PATH} and @code{CHICKEN_HOME}.
    4126 In case @code{ID} is a list, it is interpreted as a (relative)
    4127 pathname.
    41284738
    41294739@item the current directory
     
    41314741@end enumerate
    41324742
    4133 @code{ID} should be a symbol. The difference between @code{require} and
     4743@code{ID} should be a string or a symbol. The difference between @code{require} and
    41344744@code{require-for-syntax} is the the latter loads the extension library
    41354745at compile-time (the argument is still evaluated), while the former
     
    41834793@deffn {procedure} set-read-syntax!
    41844794@lisp
    4185 (set-read-syntax! PROC)
     4795(set-read-syntax! CHAR PROC)
    41864796@end lisp
    41874797When the reader is encounting the non-whitespace character @code{CHAR} while reading
     
    42024812; ==> (1 2 #(240 240 240) 3)
    42034813@end lisp
    4204 @end deffn
    4205 
    4206 @deffn {procedure} set-dispatch-read-syntax!
    4207 @lisp
    4208 (set-dispatch-read-syntax! PROC)
     4814
     4815You can undo special handling of read-syntax by passing @code{#f} as the second argument
     4816(if the syntax was previously defined via @code{set-read-syntax!}).
     4817
     4818Note that all of CHICKEN's special non-standard read-syntax is handled directly by the reader
     4819to disable built-in read-syntax, define a handler that triggers an error (for example).
     4820@end deffn
     4821
     4822@deffn {procedure} set-sharp-read-syntax!
     4823@lisp
     4824(set-sharp-read-syntax! CHAR PROC)
    42094825@end lisp
    42104826Similar to @code{set-read-syntax!}, but allows defining new @code{#<CHAR> ...} reader syntax.
     4827@end deffn
     4828
     4829
     4830@deffn {procedure} copy-read-table
     4831@lisp
     4832(copy-read-table READ-TABLE)
     4833@end lisp
     4834Returns a copy of the given read-table. You can access the currently active read-table
     4835with @code{(current-read-table)}.
    42114836@end deffn
    42124837
     
    44275052@deffnx {procedure} printf
    44285053@deffnx {procedure} sprintf
     5054@deffnx {procedure} format
    44295055@lisp
    44305056(fprintf PORT FORMATSTRING ARG ...)
    44315057(printf FORMATSTRING ARG)
    44325058(sprintf FORMATSTRING ARG ...)
     5059(format FORMATSTRING ARG ...)
    44335060@end lisp
    44345061Simple formatted output to a given port (@code{fprintf}), the
    44355062value of @code{(current-output-port) } (@code{printf}) or a string
    4436 (@code{sprintf}).  The @code{FORMATSTRING} can contain any sequence
     5063(@code{sprintf}/@code{format}).  The @code{FORMATSTRING} can contain any sequence
    44375064of characters. The character `~' prefixes special formatting directives:
    44385065
     
    44645091@end table
    44655092 
    4466 For more powerful output formatting, see the section about the @code{format} unit.
    44675093@end deffn
    44685094
     
    44735099@subsection Hash tables
    44745100
    4475 
    4476 @deffn {procedure} make-hash-table
    4477 @lisp
    4478 (make-hash-table [PRED [HASHFUNC [SIZE]]])
    4479 @end lisp
    4480 Creates and returns a hash-table with keys compared via @code{PRED},
    4481 which defaults to @code{eq?}. If @code{SIZE} is provided it specifies
    4482 the initial size of the hash-table.  If the hash-table fills above a
    4483 certain size it is automatically resized to accommodate more entries.
    4484 The @code{HASHFUNC} argument specifies the hashing function and defaults to
    4485 @code{hash}.
    4486 
    4487 @end deffn
    4488 @deffn {procedure} hash-table-ref
    4489 @lisp
    4490 (hash-table-ref HASH-TABLE KEY [DEFAULT])
    4491 @end lisp
    4492 Returns the entry in the given hash-table under @code{KEY}. If no
    4493 entry is stored in the table, @code{DEFAULT} is returned, or @code{#f} if @code{DEFAULT} is not given.
    4494 
    4495 @end deffn
    4496 @deffn {procedure} hash-table-set!
    4497 @lisp
    4498 (hash-table-set! HASH-TABLE KEY VALUE)
    4499 @end lisp
    4500 Adds or changes an entry in the given hash-table.
    4501 
    4502 @end deffn
    4503 
    4504 @deffn {procedure} hash-table-exists?
    4505 @lisp
    4506 (hash-table-exists? HASH-TABLE KEY)
    4507 @end lisp
    4508 Returns @code{#t} if @code{HASH-TABLE} has an entry for @code{KEY} or @code{#f} otherwise.
    4509 @end deffn
    4510 
    4511 @deffn {procedure} clear-hash-table!
    4512 @lisp
    4513 (clear-hash-table! HASH-TABLE)
    4514 @end lisp
    4515 Erases all entries in the hash-table @code{HASH-TABLE}.
    4516 
    4517 @end deffn
    4518 @deffn {procedure} hash-table?
    4519 @lisp
    4520 (hash-table? X)
    4521 @end lisp
    4522 Returns @code{#t} if the argument is a hash-table.
    4523 
    4524 @end deffn
    4525 @deffn {procedure} hash-table->alist
    4526 @lisp
    4527 (hash-table->list HASH-TABLE)
    4528 @end lisp
    4529 Converts @code{HASH-TABLE} into an association-list.
    4530 
    4531 @end deffn
    4532 @deffn {procedure} alist->hash-table
    4533 @lisp
    4534 (alist->hash-table ALIST [PRED [SIZE]])
    4535 @end lisp
    4536 Creates a hash-table (optionally specialized with comparison predicate @code{PRED}
    4537 and initial size @code{SIZE}) from the association-list @code{ALIST} where each
    4538 key and value created in the hash-table is taken from the car and cdr
    4539 of the elements in @code{ALIST}.
    4540 @end deffn
    4541 
    4542 @deffn {procedure} hash-table-keys
    4543 @deffnx {procedure} hash-table-values
    4544 @lisp
    4545 (hash-table-keys HAST-TABLE)
    4546 (hash-table-values HAST-TABLE)
    4547 @end lisp
    4548 Return a list of the keys/values contained in @code{HASH-TABLE}. The order of the
    4549 elements is unspecified.
    4550 @end deffn
    4551 
    4552 @deffn {procedure} hash-table-count
    4553 @lisp
    4554 (hash-table-count HASH-TABLE)
    4555 @end lisp
    4556 Returns the number of entries in the given hash-table.
    4557 
    4558 @end deffn
    4559 @deffn {procedure} hash-table-size
    4560 @lisp
    4561 (hash-table-size HASH-TABLE)
    4562 @end lisp
    4563 Returns the size of the hash-table (the actual size of the collection
    4564 containing the hash-buckets). If you want to retrieve the number of items
    4565 sotred, use @code{hash-table-count}.
    4566 
    4567 @end deffn
    4568 @deffn {procedure} hash-table-for-each
    4569 @lisp
    4570 (hash-table-for-each HASH-TABLE PROC)
    4571 @end lisp
    4572 Calls @code{PROC} which should expect two arguments. This procedure
    4573 is called for each entry in the hash-table with the key and the value
    4574 as parameters.
    4575 
    4576 @end deffn
    4577 @deffn {procedure} hash-table-remove!
    4578 @lisp
    4579 (hash-table-remove! HASH-TABLE KEY)
    4580 @end lisp
    4581 Removes an entry in the given hash-table.
    4582 
    4583 @end deffn
    4584 @deffn {procedure} hash-table-update!
    4585 @lisp
    4586 (hash-table-update! HASH-TABLE KEY PROC INIT)
    4587 @end lisp
    4588 If an entry with the given key exists in @code{HASH-TABLE}, replace it with @code{(PROC OLDVALUE)}.
    4589 If no such entry exists, add a new entry with @code{INIT} as the initial value.
    4590 @end deffn
    4591 
    4592 @deffn {procedure} hash
    4593 @lisp
    4594 (hash X [BOUND])
    4595 @end lisp
    4596 Returns a hash-value for the given data object @code{X} in the bounds specified in @code{BOUND}, which
    4597 defaults to some unspecified large fixnum.
    4598 @end deffn
    4599 
    4600 @deffn {procedure} get
    4601 @lisp
    4602 (get HASH-TABLE KEY PROP)
    4603 @end lisp
    4604 Returns the value of property @code{PROP} of the item @code{KEY}
    4605 in @code{HASH-TABLE }. This facility can be used as a kind of
    4606 ``disembodied'' property-list. If no entry named @code{KEY} is stored
    4607 in the hash-table or if no property @code{PROP} for that key exists,
    4608 @code{#f} is returned.
    4609 
    4610 @end deffn
    4611 
    4612 @deffn {procedure} put!
    4613 @lisp
    4614 (put! HASH-TABLE KEY PROP VALUE)
    4615 @end lisp
    4616 Stores @code{VALUE} as property @code{PROP} under the item
    4617 @code{KEY} in the given hash-table. Any previously existing value
    4618 is overwritten.
    4619 @end deffn
    4620 
    4621 
     5101CHICKEN implements SRFI-69. For more information,
     5102see @uref{http://srfi.schemers.org/srfi-69/srfi-69.html, SRFI-69 }.
     5103
     5104A setter for @code{hash-table-ref} is defined, so
     5105
     5106@verbatim
     5107(set! (hash-table-ref HT KEY) VAL)
     5108@end verbatim
     5109
     5110is equivalent to
     5111
     5112@verbatim
     5113(hash-table-set! HT KEY VAL)
     5114@end verbatim
    46225115
    46235116
     
    48185311@deffn {procedure} read-file
    48195312@lisp
    4820 (read-file [FILE-OR-PORT])
     5313(read-file [FILE-OR-PORT [READER [MAXCOUNT]]])
    48215314@end lisp
    48225315Returns a list containing all toplevel expressions
     
    48245317input is read from the port that is the current value of @code{(current-input-port)}.
    48255318After all expressions are read, and if the argument is a port, then the port will
    4826 not be closed.
     5319not be closed. The @code{READER} argument specifies the procedure used to read
     5320expressions from the given file or port and defaults to @code{read}. The reader
     5321procedure will be called with a single argument (an input port).
     5322If @code{MAXCOUNT} is given then only up to @code{MAXCOUNT} expressions will be read in.
    48275323
    48285324@end deffn
     
    48455341@end lisp
    48465342Read @code{MAX} or fewer lines from @code{PORT}. @code{PORT}
    4847 defaults to the value of @code{(current-input-port)}.
     5343defaults to the value of @code{(current-input-port)}. @code{PORT} may optionally be
     5344a string naming a file.
    48485345
    48495346@end deffn
     
    51075604
    51085605@end deffn
     5606
     5607@deffn {procedure} each
     5608@lisp
     5609(each PROC ...)
     5610@end lisp
     5611Returns a procedure that applies @code{PROC ...} to its arguments, and returns the result(s)
     5612of the last procedure application. For example
     5613@lisp
     5614(each pp eval)
     5615@end lisp
     5616is equivalent to
     5617@lisp
     5618(lambda args
     5619  (apply pp args)
     5620  (apply eval args) )
     5621@end lisp
     5622@code{(each PROC)} is equivalent to @code{PROC} and @code{(each)} is equivalent to
     5623@code{noop}.
     5624@end deffn
     5625
    51095626@deffn {procedure} flip
    51105627@lisp
     
    51295646(project N)
    51305647@end lisp
    5131 Returns a procedure that returns its @code{N}th argument.
     5648Returns a procedure that returns its @code{N}th argument (starting from 0).
    51325649
    51335650@end deffn
     
    52715788Creates a number vector of the same type as the argument vector with the elements at the positions @code{FROM} up to but
    52725789not including @code{TO}.
     5790
     5791SRFI-17 Setters for @code{XXXvector-ref} are defined.
    52735792@end deffn
    52745793
     
    53125831@section Unit match
    53135832
    5314 Andrew Wright's pattern matching package. Note that to use the macros in
     5833The runtime-support code for the Pattern Matching extensions. Note that to use the macros in
    53155834normal compiled code it is not required to declare this unit as used. Only
    53165835if forms containing these macros are to be expanded at runtime, this
    5317 is needed.
    5318 
    5319 
    5320 
    5321 @deffn {syntax} match
    5322 @deffnx {syntax} match-lambda
    5323 @deffnx {syntax} match-lambda*
    5324 @deffnx {syntax} match-let
    5325 @deffnx {syntax} match-let*
    5326 @deffnx {syntax} match-letrec
    5327 @deffnx {syntax} match-define
    5328 @lisp
    5329 (match EXP CLAUSE ...)
    5330 (match-lambda CLAUSE ...)
    5331 (match-lambda* CLAUSE ...)
    5332 (match-let ((PAT EXP) ...) BODY)
    5333 (match-let* ((PAT EXP) ...) BODY)
    5334 (match-letrec ((PAT EXP) ...) BODY)
    5335 (match-define PAT EXP)
    5336 @end lisp
    5337 Match expression or procedure arguments with pattern and
    5338 execute associated expressions.  A @uref{http://www.call-with-current-continuation.org/match.ps, Postscript manual} is
    5339 available .
    5340 
    5341 @end deffn
    5342 
    5343 @deffn {procedure} match-error-control
    5344 @lisp
    5345 (match-error-control [MODE])
    5346 @end lisp
    5347 Selects a mode that specifies how @code{match...} macro forms are to
    5348 be expanded.  With no argument this procedure returns the current mode. A
    5349 single argument specifies the new mode that decides what should happen
    5350 if no match-clause applies.  The following modes are supported:
    5351 
    5352 @table @code
    5353 
    5354 @item #:error
    5355 
    5356 Signal an error. This is the default.
    5357 
    5358 @item #:match
    5359 
    5360 Signal an error and output the offending form.
    5361 
    5362 @item #:fail
    5363 
    5364 Omits @code{pair?} tests when the consequence is to fail in @code{car}
    5365 or @code{cdr} rather than to signal an error.
    5366 
    5367 @item #:unspecified
    5368 
    5369 Non-matching expressions will either fail in @code{car} or @code{cdr}
    5370 or return an unspecified value.  This mode applies to files compiled
    5371 with the @code{unsafe} option or declaration.
    5372 
    5373 @end table
    5374 
    5375 
    5376 When an error is signalled, the raised exception will be of kind @code{(exn match)}.
    5377 
    5378 @end deffn
    5379 
    5380 
    5381 Note: the @code{$} pattern handles native record structures and SRFI-9 records transparently.
    5382 Currently it is required that SRFI-9 record predicates are named exactly like the record type
    5383 name, followed by a @code{?} (question mark) character.
    5384 The structure facility of the match package (@code{define-structure}) is not
    5385 available.
     5836is needed.
    53865837
    53875838
     
    54165867
    54175868@end deffn
    5418 @deffn {procedure} pattern->regexp
    5419 @lisp
    5420 (pattern->regexp PATTERN)
     5869@deffn {procedure} glob->regexp
     5870@lisp
     5871(glob->regexp PATTERN)
    54215872@end lisp
    54225873Converts the file-pattern @code{PATTERN} into a regular expression.
    54235874
    54245875@verbatim
    5425 (pattern->regexp "foo.*") ==> "foo\..*"
     5876(glob->regexp "foo.*") ==> "foo\..*"
    54265877@end verbatim
    54275878
     
    55165967@deffn {procedure} string-substitute
    55175968@lisp
    5518 (string-substitute REGEXP SUBST STRING [INDEX])
     5969(string-substitute REGEXP SUBST STRING [MODE])
    55195970@end lisp
    55205971Searches substrings in @code{STRING} that match @code{REGEXP}
     
    55235974@code{REGEXP} with the @code{\NUM} notation, where @code{NUM}
    55245975refers to the NUMth parenthesized expression. The optional argument
    5525 @code{INDEX} defaults to 1 and specifies the number of the match to
     5976@code{MODE} defaults to 1 and specifies the number of the match to
    55265977be substituted. Any non-numeric index specifies that all matches are to
    55275978be substituted.
     
    55365987@deffn {procedure} string-substitute*
    55375988@lisp
    5538 (string-substitute* STRING SMAP)
    5539 @end lisp
    5540 Substitutes elements of @code{STRING} according to @code{SMAP}.
     5989(string-substitute* STRING SMAP [MODE])
     5990@end lisp
     5991Substitutes elements of @code{STRING} with @code{string-substitute} according to @code{SMAP}.
    55415992@code{SMAP} should be an association-list where each element of the list
    55425993is a pair of the form @code{(MATCH . REPLACEMENT)}. Every occurrence of
     
    55506001==>  "Hello, world!"
    55516002@end verbatim
    5552 
    5553 Note that back-references like @code{\NUM} are currently not supported.
    55546003@end deffn
    55556004
     
    55656014@end verbatim
    55666015@end deffn
     6016
     6017Platform-specific notes:
     6018
     6019@itemize
     6020@item due to a bug in the @code{pregexp} library, character classes enclosed in @code{[ ... ]}
     6021may not begin with a hyphen (@code{-}). A workaround is either to precede the hyphen with a backslash
     6022or use the range @code{---}.
     6023@end itemize
    55676024
    55686025
     
    56176074
    56186075
    5619 @deffn {procedure} thread-deliver-signal!
    5620 @lisp
    5621 (thread-deliver-signal! THREAD X)
     6076@deffn {procedure} thread-signal!
     6077@lisp
     6078(thread-signal! THREAD X)
    56226079@end lisp
    56236080This will cause @code{THREAD} to signal the condition @code{X} once it is scheduled
     
    56396096@end lisp
    56406097Sets the quantum of @code{THREAD} to @code{QUANTUM}.
    5641 @end deffn
    5642 
    5643 
    5644 
    5645 
    5646 @node Unit format
    5647 @section Unit format
    5648 
    5649 
    5650 
    5651 @deffn {procedure} format
    5652 @lisp
    5653 (format DESTINATION FORMAT-STRING . ARGUMENTS)
    5654 @end lisp
    5655 An almost complete implementation of Common LISP format description
    5656 according to the CL reference book @b{Common LISP} from Guy L.
    5657 Steele, Digital Press. This code was originally part of SLIB. The author
    5658 is Dirk Lutzebaeck.
    5659 
    5660 Returns @code{#t}, @code{#f} or a string; has side effect of
    5661 printing according to @code{FORMAT-STRING}.  If @code{DESTINATION} is
    5662 @code{#t}, the output is to the current output port and @code{#t}
    5663 is returned.  If @code{DESTINATION} is @code{#f}, a formatted
    5664 string is returned as the result of the call.  If @code{DESTINATION}
    5665 is a string, @code{DESTINATION} is regarded as the format string;
    5666 @code{FORMAT-STRING} is then the first argument and the output
    5667 is returned as a string. If @code{DESTINATION} is a number, the
    5668 output is to the value of @code{(current-error-port)}.  Otherwise
    5669 @code{DESTINATION} must be an output port and @code{#t} is returned.
    5670 
    5671 @code{FORMAT-STRING} must be a string.  In case of a formatting
    5672 error format returns @code{#f} and prints a message on the value
    5673 of @code{(current-error-port)}.  Characters are output as if the
    5674 string were output by the @code{display} function with the exception
    5675 of those prefixed by a tilde (~).  For a detailed description of
    5676 the @code{FORMAT-STRING} syntax please consult a Common LISP format
    5677 reference manual. A list of all supported, non-supported and extended
    5678 directives can be found in @code{format.txt}.
    5679 
    5680 This unit uses definitions from the @code{extras} unit.
    5681 
    5682 @code{format} implements
    5683 @uref{http//srfi.schemers.org/srfi-28/srfi-28.html, SRFI-28 }
    56846098@end deffn
    56856099
     
    57126126* Environment access::         
    57136127* Memory mapped I/O::           
    5714 * Time routines::               
     6128* Date and time routines::               
    57156129* Raw exit::                   
    57166130* ERRNO values::               
    57176131* Finding files::               
    57186132* Getting the hostname and system information:: 
    5719 * Setting a files buffering mode:: 
     6133* Setting the file buffering mode:: 
    57206134* Terminal ports::             
    57216135* How Scheme procedures relate to UNIX C functions:: 
     
    57376151@deffn {procedure} current-directory
    57386152@lisp
    5739 (current-directory)
    5740 @end lisp
    5741 Returns the name of the current working directory.
     6153(current-directory [DIR])
     6154@end lisp
     6155Returns the name of the current working directory. If the optional argument @code{DIR} is given,
     6156then @code{(current-directory DIR)} is equivalent to @code{(change-directory DIR)}.
    57426157
    57436158@end deffn
     
    57596174@deffn {procedure} directory
    57606175@lisp
    5761 (directory PATHNAME)
    5762 @end lisp
    5763 Returns a list with all files that are contained in the directory with the name @code{PATHNAME}.
     6176(directory [PATHNAME [SHOW-DOTFILES?]])
     6177@end lisp
     6178Returns a list with all files that are contained in the directory with the name @code{PATHNAME}
     6179(which defaults to the value of @code{(current-directory)}). If @code{SHOW-DOTFILES?} is given
     6180and not @code{#f}, then files beginning with ``.'' are not included in the directory listing.
    57646181
    57656182@end deffn
     
    63886805@end lisp
    63896806If @code{GROUP} specifies a valid group-name or group-id, then this
    6390 procedure returns four values: the group-name, the encrypted group password,
     6807procedure returns a list of four values: the group-name, the encrypted group password,
    63916808the group ID and a list of the names of all group members. If no group with the
    63926809given name or ID exists, then @code{#f} is returned.
     
    66067023current values.
    66077024
    6608 Note: Under Mac OS X, this procedure always returns the empty list.
    6609 
    66107025@end deffn
    66117026@deffn {procedure} setenv
     
    66827097
    66837098
    6684 @node Time routines
    6685 @subsection Time routines
     7099@node Date and time routines
     7100@subsection Date and time routines
    66867101
    66877102
     
    67107125
    67117126@end deffn
     7127
     7128@deffn {procedure} local-time->seconds
     7129@lisp
     7130(local-time->seconds VECTOR)
     7131@end lisp
     7132Converts the ten-element vector @code{VECTOR} representing the time value relative to
     7133the current timezone into
     7134the number of seconds since the first of January, 1970 UTC.
     7135@end deffn
     7136
     7137@deffn {procedure} local-timezone-abbreviation
     7138@lisp
     7139(local-timezone-abbrevtiation)
     7140@end lisp
     7141Returns the abbreviation for the local timezone as a string.
     7142@end deffn
     7143
    67127144@deffn {procedure} seconds->string
    67137145@lisp
     
    67267158
    67277159@end deffn
     7160
     7161@deffn {procedure} utc-time->seconds
     7162@lisp
     7163(utc-time->seconds VECTOR)
     7164@end lisp
     7165Converts the ten-element vector @code{VECTOR} representing the UTC time value into
     7166the number of seconds since the first of January, 1970 UTC.
     7167@end deffn
     7168
    67287169@deffn {procedure} time->string
    67297170@lisp
     
    68397280(system-information)
    68407281@end lisp
    6841 Invokes the UNIX system call @code{uname()} and returns 5 values:
     7282Invokes the UNIX system call @code{uname()} and returns a list of 5 values:
    68427283system-name, node-name, OS release, OS version and machine.
    68437284@end deffn
     
    68467287
    68477288
    6848 @node Setting a files buffering mode
    6849 @subsection Setting a files buffering mode
     7289@node Setting the file buffering mode
     7290@subsection Setting the file buffering mode
    68507291
    68517292
     
    69697410@item initialize-groups
    69707411initgroups
     7412@item local-time->seconds
     7413mktime
     7414@item local-timezone-abbreviation
     7415localtime
    69717416@item map-file-to-memory
    69727417mmap
     
    70397484@item user-information
    70407485getpwnam/getpwuid
     7486@item utc-time->seconds
     7487timegm
    70417488@end table
    70427489
     
    70737520parent-process-id
    70747521set-root-directory!
     7522utc-time->seconds local-timezone-abbreviation
    70757523@end verbatim
    70767524
     
    72657713at a time into @code{PROCEDURE}.  The filename @code{-} is interpreted as
    72667714@code{(current-input-port)}.  If no arguments are given on the command line
    7267 it again uses the value of @code{(current-input-port)}.
     7715it again uses the value of @code{(current-input-port)}. During execution of
     7716@code{PROCEDURE}, the current input port will be correctly bound to
     7717the current input source.
    72687718
    72697719This code will act as a simple Unix cat(1) command:
     
    73327782(shift! lst)             ==> 1, lst is now (2 3)
    73337783@end lisp
     7784
     7785The list must at least contain 2 elements.
    73347786@end deffn
    73357787
     
    74387890machine that are connected over the socket associated with @code{PORT}. The returned addresses
    74397891are strings in @code{XXX.XXX.XXX.XXX} notation.
     7892
     7893@end deffn
     7894@deffn {procedure} tcp-port-numbers
     7895@lisp
     7896(tcp-port-numbers PORT)
     7897@end lisp
     7898Returns two values for the input- or output-port @code{PORT} (which should be a port returned
     7899by either @code{tcp-accept} or @code{tcp-connect}): the TCP port numbers of the local and the remote
     7900machine that are connected over the socket associated with @code{PORT}.
    74407901
    74417902@end deffn
     
    76608121@lisp
    76618122(pointer-u8-set! PTR N)
     8123(set! (pointer-u8-ref PTR) N)
    76628124@end lisp
    76638125Stores the unsigned byte @code{N} at the address designated by @code{PTR}.
     
    76678129@lisp
    76688130(pointer-s8-set! PTR N)
     8131(set! (pointer-s8-ref PTR) N)
    76698132@end lisp
    76708133Stores the signed byte @code{N} at the address designated by @code{PTR}.
     
    76748137@lisp
    76758138(pointer-u16-set! PTR N)
     8139(set! (pointer-u16-ref PTR) N)
    76768140@end lisp
    76778141Stores the unsigned 16-bit integer @code{N} at the address designated by @code{PTR}.
     
    76818145@lisp
    76828146(pointer-s16-set! PTR N)
     8147(set! (pointer-s16-ref PTR) N)
    76838148@end lisp
    76848149Stores the signed 16-bit integer @code{N} at the address designated by @code{PTR}.
     
    76888153@lisp
    76898154(pointer-u32-set! PTR N)
     8155(set! (pointer-u32-ref PTR) N)
    76908156@end lisp
    76918157Stores the unsigned 32-bit integer @code{N} at the address designated by @code{PTR}.
     
    76958161@lisp
    76968162(pointer-s32-set! PTR N)
     8163(set! (pointer-s32-ref PTR) N)
    76978164@end lisp
    76988165Stores the 32-bit integer @code{N} at the address designated by @code{PTR}.
     
    77028169@lisp
    77038170(pointer-f32-set! PTR N)
     8171(set! (pointer-f32-ref PTR) N)
    77048172@end lisp
    77058173Stores the 32-bit floating-point number @code{N} at the address designated by @code{PTR}.
     
    77098177@lisp
    77108178(pointer-f64-set! PTR N)
     8179(set! (pointer-f64-ref PTR) N)
    77118180@end lisp
    77128181Stores the 64-bit floating-point number @code{N} at the address designated by @code{PTR}.
     
    77878256(procedure-data PROCEDURE)
    77888257@end lisp
    7789 Returns the data object contained in the extended procedure
    7790 @code{PROCEDURE}.
     8258Returns the data object contained in the extended procedure @code{PROCEDURE},
     8259or @code{#f} if it is not an extended procedure.
    77918260
    77928261@end deffn
     
    78748343@lisp
    78758344(byte-vector-set! BYTE-VECTOR INDEX N)
     8345(set! (byte-vector-ref BYTE-VECTOR INDEX) N)
    78768346@end lisp
    78778347Sets the byte at the @code{INDEX}th position of @code{BYTE-VECTOR}
    78788348to the value of the exact integer @code{n}.
    7879 
    7880 @end deffn
    7881 @deffn {procedure} executable-byte-vector->procedure
    7882 @lisp
    7883 (executable-byte-vector->procedure PBYTE-VECTOR)
    7884 @end lisp
    7885 Returns a procedure that on invocation will execute the code
    7886 in @code{PBYTE-VECTOR}, which should have been allocated using
    7887 @code{make-executable-byte-vector}.  The procedure follows the native C
    7888 calling convention, and will be called as if declared with the following
    7889 prototype:
    7890 
    7891 @verbatim
    7892 void <procedure>(int argc, C_word closure, C_word k, C_word arg1, ...)
    7893 @end verbatim
    7894 
    7895 @itemize
    7896 @item @code{argc} contains the number of arguments @code{arg1, ...}
    7897 that are passed plus 2 (including @code{closure} and @code{k}).
    7898 
    7899 @item @code{closure} is the procedure object itself.
    7900 
    7901 @item @code{k} is a continuation closure that should be called when
    7902 the code is about to return.
    7903 
    7904 @verbatim
    7905 typedef void (*CONTINUATION)(int argc, C_word closure,
    7906                                        C_word result);
    7907 ((CONTINUATION)k[ 1 ])(2, k, result)
    7908 @end verbatim
    7909 
    7910 (@code{k} is a data object with the second word being the actual code
    7911 pointer)
    7912 
    7913 @end itemize
    7914 
    7915 
    7916 An example:
    7917 
    7918 @verbatim
    7919 (define x (make-executable-byte-vector 17))
    7920 (move-memory!
    7921  '#u8(#x8b #x44 #x24 #x0c  ; movl 12(%esp), %eax - `k'
    7922       #x8b #x5c #x24 #x10  ; movl 16(%esp), %ebx - `arg1'
    7923       #x53                 ; pushl %ebx          - push result
    7924       #x50                 ; pushl %eax          - push k
    7925       #x6a #x02            ; pushl $2            - push argument count
    7926       #x8b #x40 #x04       ; movl 4(%eax), %eax  - fetch code pointer
    7927       #xff #xd0)           ; call *%eax
    7928  x)
    7929 (define y (executable-byte-vector->procedure x))
    7930 (y 123)                                         ==> 123
    7931 @end verbatim
    7932 
    7933 
    7934 The result of calling @code{executable-byte-vector->procedure} with
    7935 a non-executable statically allocated byte-vector is undefined.
    7936 
    7937 @end deffn
    7938 @deffn {procedure} invoke-executable-byte-vector
    7939 @lisp
    7940 (invoke-executable-byte-vector PBYTE-VECTOR ARG1 ...)
    7941 @end lisp
    7942 Invokes the machine code stored in the executable byte-vector
    7943 @code{PBYTE-VECTOR}. The native C calling conventions are used, but
    7944 the invoked code is passed a single argument containing a pointer to an
    7945 array of the Scheme objects @code{ARG1 ...}.
    7946 
    7947 @verbatim
    7948 (define v (make-executable-byte-vector 7))
    7949 (move-memory!
    7950  '#u8(#x8b #x44 #x24 #x04        ; movl 4(%esp), %eax
    7951       #x8b #x00                  ; movl 0(%eax), %eax
    7952       #xc3)                      ; ret
    7953  v)
    7954 (invoke-executable-byte-vector v "hello!") ==> "hello!"
    7955 @end verbatim
    79568349
    79578350@end deffn
     
    79718364given, then it should be an exact integer with which every element of
    79728365the byte-vector is initialized.
    7973 
    7974 @end deffn
    7975 @deffn {procedure} make-executable-byte-vector
    7976 @lisp
    7977 (make-executable-byte-vector SIZE [INIT])
    7978 @end lisp
    7979 As @code{make-static-byte-vector}, but the code is suitable for
    7980 execution.  @b{Note:} this feature is currently only available on
    7981 @b{x86} platforms.
    7982 
    7983 Exceptions: @code{(exn bounds)}, @code{(exn runtime)}
    79848366
    79858367@end deffn
     
    80548436As @code{object-evict} but moves the object at the address pointed to by
    80558437the machine pointer @code{PTR}. If the number of copied bytes exceeds
    8056 the optional @code{LIMIT} then an error is signalled. Two values are
     8438the optional @code{LIMIT} then an error is signalled (specifically a composite
     8439condition of types @code{exn} and @code{evict}. The latter provides
     8440a @code{limit} property which holds the exceeded limit. Two values are
    80578441returned: the evicted object and a new pointer pointing to the first
    80588442free address after the evicted object.
     
    81188502@end lisp
    81198503Creates a locative that refers to the element of the non-immediate object @code{EXP}
    8120 at position @code{INDEX}. @code{EXP} may be a vector, symbol, pair, string, byte-vector,
     8504at position @code{INDEX}. @code{EXP} may be a vector, pair, string, byte-vector,
    81218505SRFI-4 number-vector, or record. @code{INDEX} should be a fixnum. @code{INDEX} defaults to 0.
    81228506
     
    81498533@lisp
    81508534(locative-set! LOC X)
     8535(set! (locative-ref LOC) X)
    81518536@end lisp
    81528537Changes the element to which the locative @code{LOC} refers to @code{X}.
     
    81878572If no variable under that name is bound, an error is signalled.
    81888573
     8574Note that it is not possible to access a toplevel binding with @code{global-ref} or
     8575@code{global-set!} if it has been hidden in compiled code via @code{(declare (hide ...))},
     8576or if the code has been compiled in @code{block} mode.
     8577
    81898578@end deffn
    81908579@deffn {procedure} global-set!
    81918580@lisp
    81928581(global-set! SYMBOL X)
     8582(set! (global-ref SYMBOL) X)
    81938583@end lisp
    81948584Sets the global variable named @code{SYMBOL} to the value @code{X}.
     
    82158605@lisp
    82168606(block-set! BLOCK INDEX X)
     8607(set! (block-ref BLOCK INDEX) X)
    82178608@end lisp
    82188609Sets the contents of the @code{INDEX}th slot of the object
     
    83078698
    83088699
    8309 
    8310 @deffn {procedure} invalid-procedure-call-handler
    8311 @lisp
    8312 (invalid-procedure-call-handler PROC)
     8700@deffn {procedure} set-invalid-procedure-call-handler!
     8701@lisp
     8702(set-invalid-procedure-call-handler! PROC)
    83138703@end lisp
    83148704Sets an internal hook that is invoked when a call to an object other than a procedure
     
    83198709;;; Access sequence-elements as in ARC:
    83208710
    8321 (invalid-procedure-call-handler
     8711(set-invalid-procedure-call-handler!
    83228712  (lambda (proc args)
    83238713    (cond [(string? proc) (apply string-ref proc args)]
     
    84818871If no generic function is defined under this name, then a fresh generic
    84828872function object is created and assigned to @code{NAME}.
     8873
    84838874Note that only @code{define-generic} expands into a valid definition,
    84848875so for internal lexically scoped definitions use @code{define-generic}.
     8876
     8877Currently methods defined with @code{define-method} should not be
     8878hidden (via @code{(declare (hide ...))}, nor should such files be compiled
     8879in @code{block} mode, unless the methods are exported.
    84858880@end deffn
    84868881
     
    85628957@lisp
    85638958(slot-set! INSTANCE SLOTNAME VALUE)
     8959(set! (slot-ref INSTANCE SLOTNAME) VALUE)
    85648960@end lisp
    85658961Sets the value of the slot @code{SLOTNAME} of the object
     
    88549250      &lt;f64vector&gt;
    88559251    &lt;structure&gt;
    8856       &lt;array&gt;
    88579252      &lt;char-set&gt;
    88589253      &lt;condition&gt;
     9254      &lt;condition-variable&gt;
    88599255      &lt;environment&gt;
    88609256      &lt;hash-table&gt;
    88619257      &lt;lock&gt;
    88629258      &lt;mmap&gt;
     9259      &lt;mutex&gt;
    88639260      &lt;promise&gt;
    88649261      &lt;queue&gt;
     9262      &lt;read-table&gt;
     9263      &lt;regexp&gt;
    88659264      &lt;tcp-listener&gt;
     9265      &lt;thread&gt;
    88669266      &lt;time&gt;
    88679267    &lt;end-of-file&gt;
     
    89109310      <f64vector>
    89119311    <structure>
    8912       <array>
    89139312      <char-set>
    89149313      <condition>
     9314      <condition-variable>
    89159315      <environment>
    89169316      <hash-table>
    89179317      <lock>
    89189318      <mmap>
     9319      <mutex>
    89199320      <promise>
    89209321      <queue>
     9322      <read-table>
     9323      <regexp>
    89219324      <tcp-listener>
     9325      <thread>
    89229326      <time>
    89239327    <end-of-file>
     
    90229426@end defvr
    90239427
     9428@defvr {class} <regexp>        @pointrightarrow{} <structure>
     9429The class of an object returned by @code{regexp}.
     9430@end defvr
     9431
    90249432@defvr {class} <c++-class>           @pointrightarrow{} <object>
    90259433The class of generated wrappers for C++ classes parsed by the ``easy''
     
    90309438
    90319439The CHICKEN distribution provides several examples in the file
    9032 @code{tinyclos-examples.scm}.
     9440@code{tests/tinyclos-examples.scm}.
    90339441
    90349442
     
    90399447* Accessing external objects:: 
    90409448* Foreign type specifiers::     
    9041 * Entry points::               
     9449* Embedding::               
    90429450* Callbacks::                   
    90439451* Locations::                   
     
    90639471@end verbatim
    90649472
     9473Code wrapped inside @code{foreign-code} may not invoke callbacks into Scheme.
     9474
    90659475@end deffn
    90669476@deffn {syntax} foreign-value
     
    90769486
    90779487@end deffn
     9488@deffn {syntax} foreign-declare
     9489@lisp
     9490(foreign-declare STRING ...)
     9491@end lisp
     9492Include given strings verbatim into header of generated file.
     9493@end deffn
     9494
     9495@deffn {syntax} foreign-parse
     9496@lisp
     9497(foreign-parse STRING ...)
     9498@end lisp
     9499Parse given strings and generate foreign-interface bindings. See @ref{The Easy Foreign Function Interface}
     9500for more information.
     9501@end deffn
     9502
     9503@deffn {syntax} foreign-parse/declare
     9504@lisp
     9505(foreign-parse/declare STRING ...)
     9506@end lisp
     9507Parse and include strings into the generated code.
     9508@end deffn
     9509
    90789510@deffn {syntax} define-foreign-type
    90799511@lisp
     
    91309562<#
    91319563
    9132 (define-macro (define-foreign-enum . items)
     9564(define-macro (define-simple-foreign-enum . items)
    91339565  `(begin
    91349566     ,@(map (match-lambda
     
    91379569     items) ) )
    91389570
    9139 (define-foreign-enum abc def ghi)
     9571(define-simple-foreign-enum abc def ghi)
    91409572
    91419573ghi                               ==> 5
     
    91459577@deffn {syntax} define-foreign-record
    91469578@lisp
    9147 (define-foreign-record NAME SLOT ...)
     9579(define-foreign-record NAME [DECL ...] SLOT ...)
    91489580@end lisp
    91499581Defines accessor procedures for a C structure definition. @code{NAME} should either be a symbol
     
    91929624struct (or union) and no setter will be generated.
    91939625
    9194 Note that no constructor or release procedure will be generated.
    9195 
    9196 
    9197 @end deffn
     9626Additionally, special record-declarations (@code{DECL ...}) may be given, where each declaration consists
     9627of a list of the form @code{(KEYWORD ARGUMENT ...)}. The available declarations are:
     9628
     9629@deffn {record declaration} constructor:
     9630@lisp
     9631(constructor: NAME)
     9632@end lisp
     9633Generate a constructor-procedure with no arguments that has the name @code{NAME} (a symbol) that returns a pointer to a structure of this
     9634type. The storage will be allocated with @code{malloc(3)}.
     9635@end deffn
     9636
     9637@deffn {record declaration} destructor:
     9638@lisp
     9639(destructor: NAME)
     9640@end lisp
     9641Generate a destructor function with the name @code{NAME} that takes a pointer to a structure of this
     9642type as its single argument and releases the storage with @code{free(3)}. If the argument is @code{#f},
     9643the destructor procedure does nothing.
     9644@end deffn
     9645
     9646@deffn {record declaration} rename:
     9647@lisp
     9648(rename: EXPRESSION)
     9649@end lisp
     9650Evaluates @code{EXPRESSION} at compile-/macro-expansion-time and applies the result, which should be
     9651a procedure, to the string-representation of the name of each accessor-procedure generated. Another (or the same)
     9652string should be returned, which in turn is taken as the actual name of the accessor.
     9653@end deffn
     9654
     9655An example:
     9656
     9657@lisp
     9658(require-for-syntax 'srfi-13)
     9659
     9660(define-foreign-record Some_Struct
     9661  (rename: (compose string-downcase (cut string-translate <> "_" "-")))
     9662  (constructor: make-some-struct)
     9663  (destructor: free-some-struct)
     9664  (int xCoord)
     9665  (int yCoord) )
     9666@end lisp
     9667
     9668will generate the following procedures:
     9669
     9670@verbatim
     9671(make-some-struct)              --> C-POINTER
     9672(free-some-struct C-POINTER)
     9673
     9674(some-struct-xcoord C-POINTER)  --> NUMBER
     9675(some-struct-ycoord C-POINTER)  --> NUMBER
     9676
     9677(some-struct-xcoord-set! C-POINTER NUMBER)
     9678(some-struct-ycoord-set! C-POINTER NUMBER)
     9679@end verbatim
     9680
     9681@end deffn
     9682
     9683@deffn {syntax} define-foreign-enum
     9684@lisp
     9685(define-foreign-enum TYPENAME ITEM ...)
     9686@end lisp
     9687Defines a foreign type (as with @code{define-foreign-type}) that maps
     9688the elements of a C/C++ enum (or a enum-like list of constants) to and
     9689from a set of symbols. @code{TYPENAME} names a foreign type that
     9690converts a symbol argument from the set @code{ITEM ...} into the
     9691appropriate enum value when passed as an argument to a foreign
     9692function.
     9693A list of symbols passed as an argument will be combined using
     9694@code{bitwise-ior}. An empty list will be passed as 0 (zero).
     9695Results of the enum type are automatically converted into a symbol
     9696(note that combinations are not supported in this case).
     9697@code{TYPENAME} may alternatively be a list of the form
     9698@code{(SCHEMENAME REALTYPE)} - in this case @code{REALTYPE} designates
     9699the native type used. The default native type is @code{"TYPENAME"}.
     9700
     9701Here a heavily contrived example:
     9702
     9703@verbatim
     9704#>
     9705enum foo { a_foo = 4, b_foo, c_foo };
     9706enum foo bar(enum foo x) { printf("%d\n", x); return b_foo; }
     9707<#
     9708
     9709(define-foreign-enum (foo (enum "foo")) a_foo b_foo (c c_foo))
     9710
     9711(define bar (foreign-lambda foo bar foo))
     9712
     9713(pp (bar '()))
     9714(pp (bar 'a_foo))
     9715(pp (bar '(b_foo c)))
     9716@end verbatim
     9717@end deffn
     9718
    91989719@deffn {syntax} foreign-lambda
    91999720@lisp
     
    92199740    "int n = 0;
    92209741     while(*(str++)) ++n;
    9221      return(n);") )
     9742     C_return(n);") )
    92229743
    92239744(my-strlen "one two three")             ==> 13
    92249745@end verbatim
    92259746
    9226 For obscure technical reasons any use of the @code{return} statement
    9227 should enclose the result value in parentheses. For the same reasons
    9228 @code{return} without an argument is not allowed.
     9747For obscure technical reasons you should use the @code{C_return} macro instead of the normal @code{return} statement
     9748to return a result from the foreign lambda body as some cleanup code has to be run before execution
     9749commences in the calling code.
    92299750@end deffn
    92309751
     
    92679788@end deffn
    92689789
     9790@deffn {syntax} $
     9791@lisp
     9792($ [RETURNTYPE] NAME (TYPE ARGUMENT) ...)
     9793@end lisp
     9794Invokes a C/C++ function by evaluating the
     9795arguments, performing the neccessary type-conversions for the foreign type-specifiers
     9796and calling @code{NAME} (which must be a symbol). If a return-type is given, then
     9797the result will be converted properly and returned. Callbacks into Scheme are not
     9798allowed inside the invoked foreign code. The type/argument lists may also be literal
     9799Scheme data or expressions of the form @code{(quote LITERAL)} or @code{(location ...)} - in this case the
     9800arguments are converted according to the type of the literal or are treated as a c-pointer, respectively.
     9801Booleans, characters,
     9802numbers, strings, SRFI-4 number vectors and symbols are converted, all other data is passed as being of
     9803type @code{scheme-object}, i.e. unconverted.
     9804
     9805@verbatim
     9806($ printf "%d times Hello, %s!\n" 1000 "world")
     9807
     9808(define f 99.2)
     9809
     9810(let-location ((double n))
     9811  (let ((f ($ double modf (double f) (location n))))
     9812    (cons n f) ) )
     9813@end verbatim
     9814
     9815If no return type is given, @code{void} is assumed. This macro expands into one
     9816of the @code{foreign-lambda*}, @code{foreign-code} or @code{foreign-value} forms.
     9817@end deffn
     9818
    92699819
    92709820@node Foreign type specifiers
     
    92989848
    92999849@item int unsigned-int
     9850@item int32 unsigned-int32
    93009851
    93019852An small integer number in fixnum range (at least 30 bit).
    93029853
    93039854@item integer unsigned-integer
    9304 
    9305 Either a fixnum or a flonum in the range of a (unsigned) machine ``int''.
     9855@item integer32 unsigned-integer32
     9856
     9857Either a fixnum or a flonum in the range of a (unsigned) machine ``int''
     9858or with 32 bit width.
    93069859
    93079860@item long unsigned-long
    93089861
    9309 Either a fixnum or a flonum in the range of a (unsigned) machine ``long''.
     9862Either a fixnum or a flonum in the range of a (unsigned) machine ``long''
     9863or with 32 bit width.
    93109864
    93119865@item float double
     
    93189872A floating-point number. Similar to @code{double}, but when used as a result
    93199873type, then either an exact integer or a floating-point number is returned, depending
    9320 on whether the result fits into an exact int or not.
     9874on whether the result fits into an exact integer or not.
    93219875
    93229876@item symbol
    93239877
    93249878A symbol, which will be passed to foreign code as a zero-terminated string.
    9325 When declared as the result of foreign code, the result is treated like a string and
    9326 a symbol with the same name will be interned in the symbol table.
     9879When declared as the result of foreign code, the result should be a string and
     9880a symbol with the same name will be interned in the symbol table (and returned
     9881to the caller).
    93279882
    93289883@item scheme-pointer
     
    93869941the pointer returned by the foreign code will be freed (using the
    93879942C-libraries @code{free()})
    9388 after copying.
    9389 @c @end deffn
     9943after copying. This type specifier is not valid as a result type
     9944for callbacks defined with @code{define-external}.
    93909945
    93919946@item void
     
    952710082
    952810083
    9529 @node Entry points
    9530 @section Entry points
    9531 
    9532 To simplify embedding compiled Scheme code into arbitrary programs, one
    9533 can define so called ``entry points'', which provide a uniform interface
    9534 and parameter conversion facilities. To use this facility, add
    9535 
    9536 @verbatim
    9537 (include "chicken-entry-points")
    9538 @end verbatim
    9539 
    9540 to the beginning of your code.
    9541 
    9542 
    9543 
    9544 @deffn {syntax} define-entry-point
    9545 @lisp
    9546 (define-entry-point INDEX ((VAR1 TYPE1) ...)
    9547                           (RTYPE1 ...)
    9548                           EXP1 EXP2 ...)
    9549 @end lisp
    9550 Defines a new entry-point with index @code{INDEX} which should evaluate
    9551 to an exact integer. During execution of the body @code{EXP1 EXP2 ...}
    9552 the variables @code{VAR1 ...} are bound to the parameters passed from
    9553 the host program to the invoked entry point. The parameters passed
    9554 are converted according to the foreign type specifiers @code{TYPE1
    9555 ...}. The expressions should return as many values as foreign type
    9556 specifiers are given in @code{RTYPE1 ...}, with the exception that if the list
    9557 of return types is empty, a single value is expected to be returned from the body
    9558 (there is no need to add a @code{(values)} form at the end).
    9559 The results are then transformed into values that can be used in the host program.
    9560 
    9561 @b{Note:} if one or more of the result types @code{RTYPE ...}
    9562 specify the type @code{c-string}, then the parameter types at the same
    9563 positions in @code{TYPE1 ...} have to be @code{c-string}s as well,
    9564 because the result strings are copied into the same area in memory.
    9565 You should also take care that the passed buffer is long enough to hold
    9566 the result string or unpredictable things will happen.
    9567 
    9568 If entry points were defined then the program will not terminate after
    9569 execution of the last toplevel expression, but instead it will enter a
    9570 loop that waits for the host to invoke one of the defined entry points.
    9571 
    9572 @end deffn
    9573 @deffn {syntax} define-embedded
    9574 @lisp
    9575 (define-embedded [QUALIFIER ... ] ([CCONV] NAME (TYPE1 VAR1) ...) RTYPE BODY ...)
    9576 @end lisp
    9577 Defines a named entry-point that can be accessed from external code with a normal C/C++ function call.
    9578 @code{QUALIFIER} may be a string for special function declarations (like @code{__declspec(dllexport)}
    9579 on Windows, for example) and @code{CCONV} may be a string designating a calling convention (like @code{__cdecl}).
    9580 During the execution of the @code{BODY} the variables @code{VAR1 ...} are bound to the arguments
    9581 passed to the function, which should be of types compatible to the type specifiers @code{TYPE1 ...}.
    9582 @code{RTYPE} specifies the result type of the entry-point. The return type specifiers @code{[nonnull-]c-string}
    9583 and @code{[nonnull-]c-string*} are handled specially: if the return type is @code{c-string}, a heap-allocated
    9584 pointer to a zero-terminated string will be returned, which will be valid until the next invocation
    9585 of an entry-point into the Scheme code. If the return type is @code{c-string*}, a buffer allocated
    9586 with @code{malloc} will be returned, and freeing the string is the responsibility of the caller.
    9587 
    9588 All entry-point definitions with @code{define-embedded} should be put into the same source file.
    9589 @code{define-embedded} expands into a @code{define-entry-point} form and the entry-point index is
    9590 provided by the macro (starting from 1). If @code{define-embedded} is used in multiple source files
    9591 then the index is counted from 1 in each of the files, resulting in multiple entry-points with the
    9592 same index.
    9593 @end deffn
    9594 
    9595 
    9596 
    9597 The following C functions and data types are provided:
    9598 
    9599 
     10084@node Embedding
     10085@section Embedding
     10086
     10087Compiled Scheme files can be linked with C code, provided the Scheme code was compiled
     10088in ``embedded'' mode by passing @code{-DC_EMBEDDED} to the C compiler (this will
     10089disable generation of a @code{main()} function). @code{csc} will do this, when given
     10090the @code{-embedded} option. Alternatively pass @code{-embedded} to @code{csc}.
     10091
     10092The following C API is available:
    960010093
    960110094@deftypefn {C function} void CHICKEN_parse_command_line (int argc, char *argv[], int *heap, int *stack int *symbols)
     
    961610109@code{toplevel} should be a pointer to the toplevel entry point
    961710110procedure. You should pass @code{C_toplevel} here. In any subsequent
    9618 call to @code{CHICKEN_run} or @code{CHICKEN_invoke} you can simply
     10111call to @code{CHICKEN_run} you can simply
    961910112pass @code{NULL}.
    962010113Calling this function more than once has no effect. If enough
     
    962310116@end deftypefn
    962410117
    9625 @deftypefn {C function} void CHICKEN_run (void **data, int *bytes, int *maxlen, void *toplevel)
    9626 Starts the Scheme program. @code{data, bytes} and @code{maxlen}
    9627 contain invocation parameters in raw form. Pass @code{NULL} here.
    9628 Call this function once to execute all toplevel expressions in your
     10118@deftypefn {C function} C_word CHICKEN_run (void *toplevel)
     10119Starts the Scheme program. Call this function once to execute all toplevel expressions in your
    962910120compiled Scheme program. If the runtime system was not initialized before,
    963010121then @code{CHICKEN_initialize} is called with default sizes.
    9631 @code{toplevel} is the toplevel entry-point procedure.
     10122@code{toplevel} is the toplevel entry-point procedure, you usually pass @code{C_toplevel} here.
     10123The result value is the continuation that can be used to re-invoke the Scheme code from the
     10124point after it called @code{return-to-host} (see below).
     10125
     10126If you just need a Scheme interpreter, you can also pass @code{CHICKEN_default_toplevel} as
     10127the toplevel procedure, which just uses the default library units.
    963210128@end deftypefn
    963310129
    9634 @deftypefn {C function} void CHICKEN_invoke (int index, C_parameter *params, int count, void *toplevel)
    9635 Invoke the entry point with index @code{index}. @code{count} should
    9636 contain the maximum number of arguments or results (whatever is higher). @code{params} is a pointer
    9637 to parameter data:
    9638 
    9639 @verbatim
    9640 typedef union
    9641 {
    9642   C_word x;           /* parameter type scheme-object */
    9643   long i;             /* parameter type bool, [unsigned] int/short/long */
    9644   long c;             /* parameter type [unsigned] char */
    9645   double f;           /* parameter type float/double */
    9646   void *p;            /* any pointer parameter type and C strings */
    9647 } C_parameter;
    9648 @end verbatim
    9649 
    9650 This function calls @code{CHICKEN_run} if it was not called at least
    9651 once before.
    9652 @end deftypefn
    9653 
    9654 @deftypefn {C function} int CHICKEN_is_running ()
    9655 Returns @code{1}, if called inside a dynamic context invoked via @code{CHICKEN_run}
    9656 or @code{CHICKEN_invoke} (i.e. if running inside a call from Scheme to C). If no
    9657 Scheme stack frame is currently active, then this function returns @code{0}.
    9658 @end deftypefn
    9659 
    9660 
    9661 
    9662 Here is a simple example (assuming a UNIX-like environment):
    9663 
    9664 @verbatim
    9665 % cat foo.c
    9666 #include <stdio.h>
    9667 #include "chicken.h"
    9668 
    9669 int main(void)
    9670 {
    9671   C_parameter p[ 3 ];
    9672   char str[ 32 ] = "hello!";  /* We need some space for the result string! */
    9673 
    9674   memset(p, 0, sizeof(p));
    9675   p[ 0 ].i = -99;
    9676   p[ 1 ].p = str;
    9677   p[ 2 ].f = 3.14;
    9678   CHICKEN_invoke(1, p, 3, C_toplevel);
    9679   printf("->\n%d\n%s\n", p[ 0 ].i, p[ 1 ].p);
    9680   return 0;
    9681 }
    9682 
    9683 % cat bar.scm
    9684 (include "chicken-entry-points")
    9685 
    9686 (define-entry-point 1
    9687     ((a integer) (b c-string) (c double))
    9688     (int c-string)
    9689   (print (list a b c))
    9690   (values 123 "good bye!") )
    9691 
    9692 % chicken bar.scm -quiet
    9693 % gcc foo.c bar.c -o foo `chicken-config -cflags -libs -embedded`
    9694 % foo
    9695 (-99 "hello!" 3.14)
    9696 ->
    9697 123
    9698 good bye!
    9699 @end verbatim
    9700 
    9701 Note the use of @code{-embedded}. We have to compile with additional compiler
    9702 options, because the host program provides the @code{main}
    9703 function.
    9704 
    9705 Here another example that uses named entry-points defined with @code{define-embedded}:
    9706 
    9707 @verbatim
    9708 % cat foo.c
    9709 extern int foo(int, char *);
    9710 extern unsigned int square(double);
    9711 
    9712 int main() { foo(square(9), "yo!"); return 0; }
    9713 
    9714 % cat bar.scm
    9715 (include "chicken-entry-points")
    9716 
    9717 (define-embedded (foo (int x) (c-string y)) int
    9718   (print x ": " y)
    9719   x)
    9720 
    9721 (define-embedded (square (double x)) unsigned-int
    9722   (* x x))
    9723 
    9724 % chicken bar.scm
    9725 compiling `bar.scm' ...
    9726 % gcc foo.c bar.c `chicken-config -cflags -libs -embedded`
    9727 % a.out
    9728 81: yo!
    9729 @end verbatim
    9730 
    9731 CHICKEN also provides ``boilerplate'' entry points, that simplify invoking Scheme
    9732 code embedded in a C or C++ application a lot. The include file @code{default-entry-points.scm}
    9733 will define entry-points for common usage patterns, like loading a file, evaluating an expression
    9734 or calling a procedure.
    9735 
    9736 
    9737 
    9738 @deftypefn {C macro} void CHICKEN_eval (C_word exp, C_word *result, int *status)
     10130Once @code{CHICKEN_run} has been called, Scheme code is executing until all toplevel
     10131expressions have been evaluated or until @code{return-to-host} is called inside the
     10132Scheme program.
     10133
     10134@deffn {procedure} return-to-host
     10135@lisp
     10136(return-to-host)
     10137@end lisp
     10138Exits the Scheme code and returns to the invoking context that called @code{CHICKEN_run}
     10139or @code{CHICKEN_continue}.
     10140@end deffn
     10141
     10142After @code{return-to-host} has been executed and once @code{CHICKEN_run} returns,
     10143you can invoke callbacks which have been defined with @code{define-external}.
     10144The @code{eval} library unit also provides ``boilerplate'' callbacks, that simplify invoking Scheme
     10145code embedded in a C or C++ application a lot.
     10146
     10147@deftypefn {C macro} int CHICKEN_eval (C_word exp, C_word *result)
    973910148Evaluates the Scheme object passed in @code{exp}, writing the result value to @code{result}.
    9740 @code{status} is set to 1 if the operation succeeded,
     10149The return value is 1 if the operation succeeded,
    974110150or 0 if an error occurred. Call @code{CHICKEN_get_error_message} to obtain a description
    974210151of the error.
    974310152@end deftypefn
    974410153
    9745 @deftypefn {C macro} void CHICKEN_eval_string (char *str, C_word *result, int *status)
     10154@deftypefn {C macro} int CHICKEN_eval_string (char *str, C_word *result)
    974610155Evaluates the Scheme expression passed in the string @code{str}, writing the result value to @code{result}.
    974710156@end deftypefn
    974810157
    9749 @deftypefn {C macro} void CHICKEN_eval_to_string (C_word exp, char *result, int size, int *status)
     10158@deftypefn {C macro} int CHICKEN_eval_to_string (C_word exp, char *result, int size)
    975010159Evaluates the Scheme expression passed in @code{exp}, writing a textual representation
    975110160of the result into @code{result}. @code{size} should specify the maximal size of the result string.
    975210161@end deftypefn
    975310162
    9754 @deftypefn {C macro} void CHICKEN_eval_string_to_string (char *str, char *result, int size, int *status)
     10163@deftypefn {C macro} int CHICKEN_eval_string_to_string (char *str, char *result, int size)
    975510164Evaluates the Scheme expression passed in the string @code{str}, writing a textual representation
    975610165of the result into @code{result}. @code{size} should specify the maximal size of the result string.
    975710166@end deftypefn
    975810167
    9759 @deftypefn {C macro} void CHICKEN_apply (C_word func, C_word args, C_word *result, int *status)
     10168@deftypefn {C macro} int CHICKEN_apply (C_word func, C_word args, C_word *result)
    976010169Applies the procedure passed in @code{func} to the list of arguments @code{args}, writing the result value to @code{result}.
    976110170@end deftypefn
    976210171
    9763 @deftypefn {C macro} void CHICKEN_apply_to_string (C_word func, C_word args, char *result, int size, int *status)
     10172@deftypefn {C macro} int CHICKEN_apply_to_string (C_word func, C_word args, char *result, int size)
    976410173Applies the procedure passed in @code{func} to the list of arguments @code{args}, writing a textual
    976510174representation of the result into @code{result}.
    976610175@end deftypefn
    976710176
    9768 @deftypefn {C macro} void CHICKEN_read (char *str, C_word *result, int *status)
     10177@deftypefn {C macro} int CHICKEN_read (char *str, C_word *result)
    976910178Reads a Scheme object from the string @code{str}, writing the result value to @code{result}.
    977010179@end deftypefn
    977110180
    9772 @deftypefn {C macro} void CHICKEN_load (char *filename, int *status)
     10181@deftypefn {C macro} int CHICKEN_load (char *filename)
    977310182Loads the Scheme file @code{filename} (either in source form or compiled).
    977410183@end deftypefn
     
    977810187@end deftypefn
    977910188
    9780 @deftypefn {C macro} void CHICKEN_yield (int *status)
     10189@deftypefn {C macro} int CHICKEN_yield (int *status)
    978110190If threads have been spawned during earlier invocations of embedded Scheme code, then this function
    978210191will run the next scheduled thread for one complete time-slice. This is useful, for example, inside
    9783 an ``idle'' handler in a GUI application with background Scheme threads.
     10192an ``idle'' handler in a GUI application with background Scheme threads. Note that the
     10193@code{srfi-18} library unit has to be linked in for this.
    978410194@end deftypefn
    978510195
     
    979110201;;; x.scm
    979210202
    9793 (include "chicken-default-entry-points")
    979410203(define (bar x) (gc) (* x x))
     10204
     10205(define-external (baz (int i)) double
     10206  (sqrt i)
    979510207
    979610208% cat y.c
     
    979910211#include "chicken.h"
    980010212#include <assert.h>
     10213
     10214extern double baz(int);
    980110215
    980210216int main() {
     
    980810222  data[ 0 ] = &val;
    980910223
    9810   CHICKEN_read("(bar 99)", &val, &status);
     10224  CHICKEN_run(C_toplevel);
     10225
     10226  status = CHICKEN_read("(bar 99)", &val);
    981110227  assert(status);
    981210228
     
    981510231  printf("data: %08x\n", val);
    981610232
    9817   CHICKEN_eval_string_to_string("(bar)", buffer, 255, &status);
     10233  status = CHICKEN_eval_string_to_string("(bar)", buffer, 255);
    981810234  assert(!status);
    981910235
     
    982110237  printf("ouch: %s\n", buffer);
    982210238
    9823   CHICKEN_eval_string_to_string("(bar 23)", buffer, 255, &status);
     10239  status = CHICKEN_eval_string_to_string("(bar 23)", buffer, 255);
    982410240  assert(status);
    982510241
     
    982710243  printf("data: %08x\n", val);
    982810244
    9829   CHICKEN_eval_to_string(val, buffer, 255, &status);
     10245  status = CHICKEN_eval_to_string(val, buffer, 255);
    983010246  assert(status);
    983110247  printf("-> %s\n", buffer);
     10248
     10249  printf("->` %g\n", baz(22));
     10250
     10251  return 0;
     10252}
     10253
     10254% csc x.scm y.c -embedded
     10255@end verbatim
     10256
     10257It is also possible to re-enter the computation following the call to @code{return-to-host} by calling
     10258@code{CHICKEN_continue}:
     10259
     10260@deftypefn {C function} C_word CHICKEN_continue (C_word k)
     10261Re-enters Scheme execution. @code{k} is the continuation received from the previous invocation
     10262of @code{CHICKEN_run} or @code{CHICKEN_continue}. When @code{return-to-host} is called again,
     10263this function returns another continuation that can be used to restart again.
     10264
     10265Note: if you invoke callbacks prior to calling @code{CHICKEN_continue}, make sure that the
     10266continuation is not reclaimed by garbage collection. This can be avoided by using @code{C_gc_protect}
     10267or gc-roots.
     10268@end deftypefn
     10269
     10270
     10271Another example:
     10272
     10273@verbatim
     10274% cat x.scm
     10275(require-extension srfi-18)
     10276
     10277(define m (make-mutex))
     10278
     10279(define (t)
     10280  (mutex-lock! m)
     10281  (thread-sleep! 1)
     10282  (print (thread-name (current-thread)))
     10283  (mutex-unlock! m)
     10284  (t) )
     10285
     10286(thread-start! (make-thread t 'PING!))
     10287(thread-start! (make-thread t 'PONG!))
     10288
     10289(let loop ()
     10290  (return-to-host)
     10291  (thread-yield!)
     10292  (loop) )
     10293
     10294% cat y.c
     10295#include "chicken.h"
     10296
     10297int main()
     10298{
     10299  C_word k = CHICKEN_run(C_toplevel);
     10300 
     10301  for(;;)
     10302    k = CHICKEN_continue(k);
    983210303
    983310304  return 0;
     
    988710358of arguments.  The second is to define an externally visible wrapper
    988810359function around a Scheme procedure with the @code{define-external}
    9889 or @code{foreign-safe-wrapper} forms.
     10360form.
    989010361
    989110362Note: the names of all functions, variables and macros exported by the
    989210363CHICKEN runtime system start with ``@code{C_}''. It is advisable to
    989310364use a different naming scheme for your own code to avoid name clashes.
    9894 Callbacks (either defined by @code{define-external} or @code{foreign-safe-wrapper}
     10365Callbacks (defined by @code{define-external})
    989510366do not capture the lexical environment.
    989610367
     
    991810389@end verbatim
    991910390
    9920 is equivalent to
    9921 
    9922 @verbatim
    9923 (define foo
    9924   (foreign-safe-wrapper int "foo"
    9925     (c-string) (lambda (x) (string-length x))))
    9926 @end verbatim
    9927 
    992810391The second form of @code{define-external} can be used to define
    992910392variables that are accessible from foreign code. It declares
     
    993710400(define-external foo int 42)
    993810401((foreign-lambda* int ()
    9939   "return(foo);"))           ==> 42
     10402  "C_return(foo);"))           ==> 42
    994010403@end verbatim
    994110404
     
    994610409statically allocated memory (for example by using @code{object-evict}).
    994710410
    9948 @end deffn
    9949 @deffn {syntax} foreign-safe-wrapper
    9950 @lisp
    9951 (foreign-safe-wrapper RETURNTYPE NAME [QUALIFIERS] (ARGUMENTTYPE1 ...) EXP)
    9952 @end lisp
    9953 Defines an externally callable wrapper around the procedure
    9954 @code{EXP}. @code{EXP} @b{must} be a lambda expression
    9955 of the form @code{(lambda @dots{})}. The wrapper will have the name
    9956 @code{NAME} and will have a signature as specified in the return- and
    9957 argument-types given in @code{RETURNTYPE} and @code{ARGUMENTTYPE1
    9958 ...}.  @code{QUALIFIERS} is a qualifier string for the function
    9959 definition (see @code{define-external}).
     10411Results of type @code{scheme-object} returned by @code{define-external}
     10412are always allocated in the secondary heap, that is, not in the stack.
     10413
     10414
    996010415@end deffn
    996110416
     
    996710422@end deftypefn
    996810423
     10424@deftypefn {C function} void C_callback_adjust_stack_limits (C_word *ptr)
     10425The runtime-system uses the stack as a special allocation area and
     10426internally holds pointers to estimated limits to distinguish between Scheme
     10427data objects inside the stack from objects outside of it.
     10428If you invoke callbacks at wildly differing stack-levels,
     10429these limits may shift from invocation to invocation. Callbacks defined
     10430with @code{define-external} will perform appropriate adjustments automatically,
     10431but if you invoke @code{C_callback} manually, you should perform a
     10432@code{C_callback_adjust_stack_limits} to make sure the internal limits are
     10433set properly. @code{ptr} should point to some data object on the stack. The
     10434call will make sure the limits are adjusted so that the value pointed to
     10435by @code{ptr} is located in the stack.
     10436@end deftypefn
    996910437
    997010438
     
    1007510543
    1007610544@verbatim
    10077 (declare
    10078   (foreign-declare "
     10545(foreign-declare "
    1007910546#include <math.h>
    1008010547
    1008110548#define my_pi 3.14
    1008210549")
    10083   (foreign-parse "extern double sin(double);") )
     10550
     10551(foreign-parse "extern double sin(double);")
    1008410552
    1008510553(print (sin 3.14))
     
    1008910557
    1009010558@verbatim
    10091 (declare
    10092   (foreign-declare "
     10559(foreign-declare "
    1009310560#include <math.h>
    1009410561
     
    1021510682* C notes::                     
    1021610683* C++ notes::
    10217 * Using the builtin parser::
    10218 * Specification grammar::                   
    1021910684@end menu
    1022010685
     
    1023210697
    1023310698@verbatim
    10234 (declare
    10235   (foreign-declare "...")
    10236   (foreign-parse "...") )
     10699(foreign-parse(declare "...")
    1023710700@end verbatim
    1023810701
     
    1024010703
    1024110704If @code{SPEC} is the @code{:} character, the text will be so it will be executed at the location where it appears.
    10242 
    10243 If @code{SPEC} is the @code{$} character, the text will be parsed and the generated Scheme code is returned
    10244 as a @code{(foreign-parse CODE}) form.
    10245 
    10246 If @code{SPEC} is the @code{%} character, the text will be parsed into an s-expression that specifies the
    10247 parsed entities, wrapped in a @code{(foreign-parse/spec ...)} form. See below for details of the specification format.
    1024810705
    1024910706If @code{SPEC} is a list of the form @code{(TAG ...)}, then each @code{TAG} (which should be a symbol)
     
    1025210709@table @code
    1025310710@item declare
    10254 (declare (foreign-declare "..."))
     10711(foreign-declare "...")
    1025510712@item parse
    10256 (declare (foreign-parse "..."))
     10713(foreign-parse "...")
    1025710714@item execute
    1025810715(foreign-code "...")
    10259 @item code
    10260 (foreign-parse "...")
    10261 @item spec
    10262 (foreign-parse/spec "...")
    1026310716@end table
    1026410717
    1026510718If any other character follows the @code{#>}, then the complete text will be included verbatim in the declaration
    10266 part of the generated file (as in a @code{foreign-declare} declaration).
     10719part of the generated file (as in a @code{foreign-declare} form).
    1026710720
    1026810721
     
    1029110744to the C compiler option @code{-DCHICKEN}).
    1029210745
    10293 Macro- and type-definitions are available in subsequent @code{foreign-parse} forms.
     10746Macro- and type-definitions are available in subsequent @code{foreign-parse} declarations.
    1029410747C variables declared generate a procedure with zero or one argument with the same name
    1029510748as the variable. When called with no arguments, the procedure returns the current value of the
     
    1030710760
    1030810761Constants (as declared by @code{#define} or @code{enum}) are not visible outside of the current
    10309 Compilation units unless the @code{export_constants} pseudo declaration has been used.
     10762Compilation units unless the @code{export_constants} pseudo declaration has been used.
     10763Only numeric or character constants are directly supported.
    1031010764
    1031110765When given the option @code{-ffi}, CHICKEN will compile a C/C++ file in ``Scheme'' mode, that is,
     
    1058111035Declares a name-substitution for all generated Scheme identifiers. The value for this
    1058211036declaration should be a string containing a regular expression and a replacement string
    10583 (seperated by the @code{;} character):
     11037(separated by the @code{;} character):
    1058411038
    1058511039@verbatim
     
    1063211086;;;; foreign type that converts to unicode (assumes 4-byte wchar_t):
    1063311087;
    10634 ; - Note: this is rather kludgy is only meant to demonstrate the `type'
     11088; - Note: this is rather kludgy and is only meant to demonstrate the `type'
    1063511089;         pseudo-declaration
    1063611090
     
    1069611150          | "#error" TOKEN ...
    1069711151          | "#include" INCLUDEFILE
     11152          | "#import" INCLUDEFILE
    1069811153          | "#pragma" TOKEN ...
    1069911154
     
    1074611201           | "mutable_fields"
    1074711202
    10748 ENUM = "enum" "{" ID ["=" NUMBER] "," ... "}"
     11203ENUM = "enum" "{" ID ["=" (NUMBER | ID)] "," ... "}"
    1074911204
    1075011205TYPEDEF = "typedef" TYPE ["*" ...] [ID]
     
    1077111226          | "___number"
    1077211227          | "___symbol"
     11228          | "___u32"
     11229          | "___s32"
    1077311230          | "struct" ID
    1077411231          | "union" ID
     
    1081211269@item [unsigned] long
    1081311270[unsigned-]long
     11271@item ___u32
     11272unsigned-integer32
     11273@item ___s32
     11274integer32
    1081411275@item float
    1081511276float
     
    1086411325@item TYPE *
    1086511326(pointer TYPE)
    10866 @item TYPE
    10867 &(ref TYPE)
     11327@item TYPE &
     11328(ref TYPE)
    1086811329@item TYPE<T1, ...>
    1086911330(template TYPE T1 ...)
     
    1088611347@item [unsigned] long
    1088711348[unsigned-]long
     11349@item ___u32
     11350unsigned-integer32
     11351@item ___s32
     11352integer32
    1088811353@item float
    1088911354float
     
    1090811373@item TYPE *
    1090911374(pointer TYPE)
    10910 @item TYPE
    10911 &(ref TYPE)
     11375@item TYPE &
     11376(ref TYPE)
    1091211377@item TYPE<T1, ...>
    1091311378(template TYPE T1 ...)
     
    1096711432
    1096811433
    10969 @node Using the builtin parser
    10970 @subsection Using the builtin parser
    10971 
    10972 There are two macros that can be used (in addition to the @code{#>$ ... <#} reader syntax) to
    10973 access the parsed C/C++ code directly. These macros are by default undefined. To perform custom
    10974 processing of the parsed Scheme code or FFI specification, define the macros as you please.
    10975 
    10976 @deffn foreign-parse {syntax}
    10977 @lisp
    10978 (foreign-parse EXP)
    10979 @end lisp
    10980 Should be defined to perform custom processing of Scheme code wrapped in a @code{#>$ ... <#} construct.
    10981 @end deffn
    10982 
    10983 @deffn foreign-parse/spec {syntax}
    10984 @lisp
    10985 (foreign-parse/spec EXP)
    10986 @end lisp
    10987 Should be defined to perform custom processing of an FFI specification wrapped in a @code{#>% ... <#} construct.
    10988 
    10989 For example:
    10990 
    10991 @verbatim
    10992 (define-macro (foreign-parse/spec x)
    10993   `(pp ',x) )
    10994 
    10995 #>%
    10996 int foo(double n) { return n * 2; }
    10997 
    10998 typedef short *mytype;
    10999 
    11000 class Bar: public Yo, Foo {
    11001 public:
    11002   Bar(int, char *);
    11003   ~Bar();
    11004 
    11005   void *myfun(mytype x);
    11006 };
    11007 <#
    11008 @end verbatim
    11009 
    11010 will expand into:
    11011 
    11012 @lisp
    11013 (pp '(begin
    11014        (function (foo "foo") integer double)
    11015        (class (<Bar> "Bar") (<c++-object>))
    11016        (destructor (<Bar> "Bar") destroy)
    11017        (constructor (<Bar> "Bar") integer c-string)
    11018        (imethod
    11019          (myfun "myfun")
    11020          (<Bar> "Bar")
    11021          (pointer void)
    11022          (<s16vector> s16vector))))
    11023 @end lisp
    11024 
    11025 @end deffn
    11026 
    11027 
    11028 @node Specification grammar
    11029 @subsection Specification grammar
    11030 
    11031 The following table describes the grammar of specifications parsed by the @code{#>% ... <#}
    11032 construct.
    11033 
    11034 @code{IDs} is a symbol, naming a Scheme identifier. @code{IDc}
    11035 is a string naming a C/C++ entity. @code{VALUE} is a Scheme numeric constant. @code{TYPE} is a
    11036 foreign type specifier. Most identifiers are given in pairs of the form @code{(IDs IDc)}, where
    11037 @code{IDs} is a version of the C identifier @code{IDc} with all renamings performed (and in the case
    11038 of class-names enclosed in in @code{<...>}).
    11039 
    11040 @table @code
    11041 @item (begin SPEC ...)
    11042 Contains zero or more specification items.
    11043 @item (alias (IDs IDc) TYPE)
    11044 Defines an alias of the name @code{IDs} for the C/C++ entity @code{IDc} (usually a variable) with
    11045 the type @code{TYPE}.
    11046 @item (constant IDs VALUE)
    11047 Defines a named constant.
    11048 @item (type IDs IDs [EXP1 [EXP2]]))
    11049 A user defined foreign type (just like @code{define-foreign-type}).
    11050 @item (variable (IDs IDc) TYPE)
    11051 A variable.
    11052 @item (cvariable (IDs IDc) TYPE)
    11053 A constant (immutable) variable.
    11054 @item (function (IDs IDc) TYPEr TYPEa ...)
    11055 A function with the result type @code{TYPEr} and the argument types @code{TYPEa ...}.
    11056 @item (function* (IDs IDc) TYPEr TYPEa ...)
    11057 A function that may invoke callbacks.
    11058 @item (method (IDs IDc) TYPEr (CLASS TYPEa) ...)
    11059 A generic function method. The corresponding TinyCLOS classes for each argument type are also provided.
    11060 @item (method* (IDs IDc) TYPEr (CLASS TYPEa) ...)
    11061 A generic function method that may invoke callbacks.
    11062 @item (imethod (ID1s ID1c) (ID1s ID1c) TYPEr (CLASS TYPEa) ...)
    11063 An instance method. The first identifier-pair names the method and the second names the class.
    11064 @item (class (IDs IDc) (IDs ...))
    11065 A class definition. The list @code{(IDs ...)} names the super-classes and defaults to @code{<c++-object>}.
    11066 @item (constructor (IDs IDc) TYPEa ...)
    11067 A class constructor with a given list of argument types.
    11068 @item (constructor* (IDs IDc) TYPEa ...)
    11069 A class constructor that should generate instances which are automatically finalized.
    11070 @item (destructor (IDs IDc) IDs)
    11071 A class destructor. The second identifier specifies how the destructor method should be named.
    11072 @item (export IDs)
    11073 Make the Scheme identifier @code{IDs} be globally visible (it is assumed constants and aliases are not
    11074 globally visible by default).
    11075 @item (struct-field IDc FIELDIDs TYPE GETTER [SETTER])
    11076 A structure field with the name @code{FIELDIDs} of the structure named @code{IDc} and with the type
    11077 @code{TYPE}. @code{GETTER} and @code{SETTER} (when given) specify the names of any accessor procedures.
    11078 @item (union-field IDc FIELDIDs TYPE GETTER [SETTER])
    11079 As above, but for a union field.
    11080 @item (struct-maker IDc CONSIDs (TYPE FIELDIDc) ...)
    11081 A structure constructor for the C struct @code{IDc} field the name @code{CONSIDs} and the
    11082 field-initializer arguments and types given in @code{(TYPE FIELDIDc) ...}.
    11083 @item (union-maker IDc CONSIDs (TYPE FIELDIDc) ...)
    11084 A union-constructor.
    11085 @end table
    11086 
    11087 
    1108811434@node C interface
    1108911435@section C interface
     
    1109511441
    1109611442
    11097 @deftypefn {C function} void C_save (C_word x)
     11443@deftypefn {C macro} void C_save (C_word x)
    1109811444Saves the Scheme data object @code{x} on the temporary stack.
     11445@end deftypefn
     11446
     11447@deftypefn {C macro} void C_restore
     11448Pops and returns the topmost value from the temporary stack.
    1109911449@end deftypefn
    1110011450
     
    1113411484collection is performed, so data allocated with @code{C_alloc}
    1113511485will already have moved to a safe place.
     11486
     11487Note that @code{C_alloc} is really just a wrapper around @code{alloca},
     11488and can also be simulated by declaring a stack-allocated array of
     11489@code{C_word}s:
    1113611490@end deftypefn
    1113711491
     
    1115611510@deftypefnx {C function} void* C_pointer_address (C_word pointer)
    1115711511These macros and functions can be used to convert Scheme data objects
    11158 back to C data.
     11512back to C data. Note that @code{C_c_string()} returns a pointer
     11513to the character buffer of the actual Scheme object and is not
     11514zero-terminated.
    1115911515@end deftypefn
    1116011516
     
    1119011546heap-generation), then the garbage collector will remember to handle the
    1119111547data appropriately. Assigning nursery-pointers directly will otherwise
    11192 result in lost data.
     11548result in lost data. Note that no copying takes place at the moment
     11549when @code{C_mutate} is called, but later - at the next (minor) garbage
     11550collection.
    1119311551@end deftypefn
    1119411552
    1119511553@deftypefn {C macro} C_word C_symbol_value (C_word symbol)
    11196 Returns the global value of the variable with the name @code{symbol}.
     11554Returns the global value of the variable with the name @code{symbol}. If the
     11555variable is unbound @code{C_SCHEME_UNBOUND} is returned. You can set a variable's
     11556value with @code{C_mutate(&C_symbol_value(SYMBOL), VALUE)}.
    1119711557@end deftypefn
    1119811558
     
    1120611566in @code{ptrs} to @code{C_SCHEME_UNDEFINED})
    1120711567@code{C_gc_protect} may not called before the runtime system has been
    11208 iniitalized (either by @code{CHICKEN_initialize}, @code{CHICKEN_run} or
     11568initialized (either by @code{CHICKEN_initialize}, @code{CHICKEN_run} or
    1120911569@code{CHICKEN_invoke}.
    1121011570
     
    1126111621}
    1126211622
    11263 % chicken foo.scm -quiet
    11264 % gcc foo.c bar.c -o foo `chicken-config -cflags -libs`
     11623% csc foo.scm bar.c -o foo
    1126511624% foo
    1126611625This is 'callout': 1, 2, 3
     
    1133411693loading compiled code at runtime is supported. Currently this are
    1133511694most UNIX-compatible platforms that provide the @code{libdl} functionality
    11336 like Linux, Solaris, BSD or Mac OS X. Windows with Cygwin is currently not supported.
     11695like Linux, Solaris, BSD or Mac OS X.
    1133711696Windows with the Microsoft tools is partially supported.
    1133811697
     
    1136311722installed files, and user-defined metadata is stored in the repository.
    1136411723
     11724If no extension name is given on the command-line, and if none of the
     11725options @code{-list}, @code{-version}, @code{-repository} (without argument),
     11726@code{-program-path} (without argument), @code{-fetch} or @code{-docindex}
     11727is given, then all @code{.setup} scripts in the current directory are
     11728processed.
     11729
    1136511730
    1136611731@node Creating extensions
    1136711732@section Creating extensions
    1136811733
    11369 Extensions can be created by creating an archive named @code{EXTENSION.egg}
     11734Extensions can be created by creating an (optionally gzipped) @code{tar}
     11735archive named @code{EXTENSION.egg}
    1137011736containing all needed files plus a @code{.setup} script in the root directory.
    1137111737After @code{chicken-setup} has extracted the files, the setup script will be
     
    1138711753by the @code{require-at-runtime} property.
    1138811754
     11755@code{FILELIST} may be a filename, a list of filenames, or a list of pairs of
     11756the form @code{(SOURCE DEST)} (if you want to copy into a particular sub-directory - the
     11757destination directory will be created as needed).
     11758
    1138911759The optional argument @code{INFOLIST} should be an association list that
    1139011760maps symbols to values, this list will be stored as @code{ID.setup} at the same
     
    1141411784@end deffn
    1141511785
     11786@deffn {property} documentation
     11787@lisp
     11788(documentation FILENAME)
     11789@end lisp
     11790The filename of a HTML document containing extension-specific documentation.
     11791This file should be given in the file-list passed to @code{install-extension} and
     11792a link to it will be automatically included in the index page (accessible via
     11793@code{chicken-setup -docindex}).
     11794@end deffn
     11795
     11796@deffn {property} exports
     11797@lisp
     11798(exports EXPORT ...)
     11799@end lisp
     11800Add export-information to the generated extension-information. @code{EXPORT} may be
     11801a symbol naming an exported toplevel variable or a string designating a file with
     11802exported variables, as generated by the @code{-emit-exports} option or the
     11803@code{emit-exports} declaration specifier.
     11804@end deffn
     11805
    1141611806All other properties are currently ignored. The @code{FILELIST} argument may also be a single
    1141711807string.
     
    1142911819@deffn {procedure} install-script
    1143011820@lisp
    11431 (install-program ID FILELIST [INFOLIST])
     11821(install-script ID FILELIST [INFOLIST])
    1143211822@end lisp
    1143311823Similar to @code{install-program}, but additionally changes the file permissions of all
     
    1147211862@end deffn
    1147311863
     11864@deffn {procedure} copy-file
     11865@lisp
     11866(copy-file FROM TO)
     11867@end lisp
     11868Copies the file or directory (recursively) given in the string @code{FROM} to the destination
     11869file or directory @code{TO}.
     11870@end deffn
     11871
     11872@deffn {procedure} move-file
     11873@lisp
     11874(move-file FROM TO)
     11875@end lisp
     11876Moves the file or directory (recursively) given in the string @code{FROM} to the destination
     11877file or directory @code{TO}.
     11878@end deffn
     11879
     11880@deffn {procedure} remove-file*
     11881@lisp
     11882(remove-file* PATH)
     11883@end lisp
     11884Removes the file or directory given in the string @code{PATH}.
     11885@end deffn
     11886
     11887
     11888@deffn {procedure} create-directory
     11889@lisp
     11890(create-directory PATH)
     11891@end lisp
     11892Creates the directory given in the string @code{PATH}, with all parent directories as needed.
     11893@end deffn
     11894
     11895
     11896
     11897@deffn {parameter} setup-root-directory
     11898Contains the path of the directory where @code{chicken-setup} was invoked.
     11899@end deffn
     11900
     11901@deffn {parameter} setup-build-directory
     11902Contains the path of the directory where the extension is built. This is not necessarily identical
     11903to @code{setup-root-directory}.
     11904@end deffn
     11905
    1147411906
    1147511907@node Examples for extensions
     
    1149211924
    1149311925at the shell prompt, the file @code{hello.scm} will be compiled into a dynamically loadable library,
    11494 with the default compiler options @code{-optimize-level 2 -debug-level 0 -shared}. If the
     11926with the default compiler options @code{-optimize-level 2 -no-trace -shared}. If the
    1149511927compilation succeeds, @code{hello.so} will be stored in the repository, together with a file named
    1149611928@code{hello.setup} (not to be confused with a setup script - this @code{.setup} file just contains
     
    1150011932
    1150111933@verbatim
    11502 $ csi -quiet
     11934$ csi -q
    1150311935#;1> (require-extension hello)
    1150411936; loading /usr/local/lib/chicken/hello.so ...
     
    1154711979@end verbatim
    1154811980
    11549 @code{chicken-setup} provides a @code{make} tool, so building operations can be of
     11981@code{chicken-setup} provides a @code{make} macro, so building operations can be of
    1155011982arbitrary complexity. When running @code{chicken-setup} with an argument @code{NAME},
    1155111983for which no associated file @code{NAME.setup}, @code{NAME.egg} or @code{NAME.scm}
     
    1155311985@code{http://www.call-with-current-continuation.org/eggs}. You can use the
    1155411986@code{-host} option to specify an alternative source location.
     11987
     11988If the given extension name contains a path prefix and the @code{-host} option
     11989is given, then @code{chicken-setup} can also download and install eggs from
     11990an arbitrary HTTP server. Alternatively you can pass a full URL (including the
     11991@code{http://} prefix. Note that no dependency checks are done when downloading
     11992eggs directly with the URL syntax.
    1155511993
    1155611994Finally a somewhat more complex example: We want to package a syntax extension with
     
    1162312061
    1162412062@verbatim
     12063$ chicken-setup glass
    1162512064$ csi -quiet
    1162612065#;1> (require-extension glass)
     
    1164012079
    1164112080@itemize
    11642 @item @code{-help}
     12081@item @code{-h  -help}
    1164312082Show usage information and exit.
    11644 @item @code{-version}
     12083@item @code{-V  -version}
    1164512084Display version and exit.
    11646 @item @code{-repository [PATHNAME]}
     12085@item @code{-R  -repository [PATHNAME]}
    1164712086When used without an argument, the path of the extension repository is displayed on standard
    1164812087output. When given an argument, the repository pathname (and the @code{repository-path} parameter)
     
    1165112090directory given in the environment variable @code{CHICKEN_REPOSITORY}.
    1165212091@code{PATHNAME} should be an absolute pathname.
    11653 @item @code{-program-path [PATHNAME]}
     12092@item @code{-P  -program-path [PATHNAME]}
    1165412093When used without an argument, the path for executables is displayed on standard output.
    1165512094When given an argument, the program path for installing executables and scripts will be set to
    1165612095@code{PATHNAME} for all subsequent operations.
    1165712096@code{PATHNAME} should be an absolute pathname.
    11658 @item @code{-host HOSTNAME[:PORT]}
     12097@item @code{-h  -host HOSTNAME[:PORT]}
    1165912098Specifies alternative host for downloading extensions, optionally with a TCP port number (which
    1166012099defaults to 80).
    11661 @item @code{-uninstall EXTENSION}
     12100@item @code{-u  -uninstall EXTENSION}
    1166212101Removes all files that were installed for @code{EXTENSION} from the file-system, together
    1166312102with any metadata that has been stored.
    11664 @item @code{-list}
    11665 List all installed extensions and exit.
    11666 @item @code{-run FILENAME}
     12103@item @code{-l  -list [NAME ...]}
     12104List all installed extensions or show extension information.
     12105@item @code{-r  -run FILENAME}
    1166712106Load and execute given file.
    11668 @item @code{-script FILENAME}
     12107@item @code{-s  -script FILENAME}
    1166912108Executes the given Scheme source file with all remaining arguments and exit. The ``she-bang''
    1167012109shell script header is recognized, so you can write Scheme scripts that use @code{chicken-setup}
    1167112110just as with @code{csi}.
    11672 @item @code{-verbose}
     12111@item @code{-e  -eval EXPRESSION}
     12112Evaluates the given expression(s).
     12113@item @code{-v  -verbose}
    1167312114Display additional debug information.
    11674 @item @code{-keep}
     12115@item @code{-k  -keep}
    1167512116Keep temporary files and directories.
    11676 @item @code{-csc-option OPTION}
     12117@item @code{-c  -csc-option OPTION}
    1167712118Passes @code{OPTION} as an extra argument to invocations of the compiler-driver (@code{csc}). This
    1167812119works only if @code{csc} is invoked as @code{(run (csc ...))}.
    11679 @item @code{-dont-ask}
     12120@item @code{-d  -dont-ask}
    1168012121Do not ask the user before trying to download required extensions.
    11681 @item @code{-no-install}
     12122@item @code{-n  -no-install}
    1168212123Do not install generated binaries and/or support files. Any invocations of @code{install-program},
    1168312124@code{install-extension} or @code{install-script} will be be no-ops.
     12125@item @code{-i  -docindex}
     12126Displays the path to the index-page of any installed extension-documentation. If the index page
     12127does not exist, it is created.
     12128@item @code{-check}
     12129Downloads the repository-index and lists locally installed extensions for which a newer
     12130release is available for download.
    1168412131@item @code{--}
    1168512132Ignore all following arguments.
     
    1171412161* chicken-more-macros.scm::     
    1171512162* chicken-ffi-macros.scm::     
    11716 * chicken-entry-points.scm::   
    11717 * chicken-default-entry-points.scm:: 
    1171812163@end menu
    1171912164
     
    1174412189and the definitions contained in this file are automatically made
    1174512190available in compiled code.
    11746 
    11747 
    11748 @node  chicken-entry-points.scm
    11749 @section @code{chicken-entry-points.scm}
    11750 
    11751 This file contains the definition of the macros @code{define-entry-point}
    11752 and @code{define-embedded}. See the section ``Entry points'' earlier in this manual.
    11753 
    11754 
    11755 @node  chicken-default-entry-points.scm
    11756 @section @code{chicken-default-entry-points.scm}
    11757 
    11758 This file contains boilerplate entry point definitions. See the section
    11759 ``Entry points''. This file automatically includes @code{entry-points.scm}.
    1176012191
    1176112192
     
    1190712338@item Compiling large files takes too much time.
    1190812339
    11909 @item There is no support for rationals, complex numbers or
    11910 extended-precision integers (bignums).
    11911 
    11912 @item The maximal number of arguments that may be passed to a compiled
    11913 procedure or macro is 126.  A macro-definition
    11914 that has a single rest-parameter can have any number of arguments.
    11915 If the @code{libffi} library is available on this platform, and if it
    11916 is installed, then CHICKEN can be configured at build time to take advantage
    11917 of this. See the @code{README} file for more details.
    11918 
    11919 @item The maximum number of values that can be passed to continuations
    11920 captured using @code{call-with-current-continuation} is 126.
    11921 
    11922 @item Some numeric procedures are missing since CHICKEN does not support
    11923 the full numeric tower. Support for extended numbers (bignums, exact
    11924 rationals and complex numbers) is available as a separate package, provided
    11925 the GNU multiprecision library is installed.
    11926 
    1192712340@item If a known procedure has unused arguments, but is always called
    1192812341without those parameters, then the optimizer ``repairs'' the procedure
     
    1193312346@item Leaf routine optimization can theoretically result in code that
    1193412347thrashes, if tight loops perform excessively many mutations.
    11935 
    11936 @item Building CHICKEN on RS/6000 systems under AIX is currently not
    11937 possible, due to strange assembler errors during compilation of the
    11938 compiler sources.
    11939 
    11940 @item @code{format} is not reentrant. This means that recursive invocation
    11941 of this procedure (either inside @code{print-object} methods or
    11942 record-printer defined with @code{define-record-printer} will
    11943 not work.
    11944 
    11945 @item User-defined types are currently not supported in the argument and result
    11946 specifications for entry-points defined with @code{define-entry-point}.
    1194712348
    1194812349@end itemize
     
    1205312454   You should always use maximum optimizations settings for your C compiler.
    1205412455   Good GCC compiler options on Pentium (and compatible) hardware are:
    12055    @code{-O3 -fomit-frame-pointer -f-nostrict-aliasing}
     12456   @code{-Os -fomit-frame-pointer -fno-strict-aliasing}
    1205612457   Some programs are very sensitive to the setting of the nursery (the first heap-generation). You
    1205712458   should experiment with different nursery settings (either by compiling with the @code{-nursery}
     
    1206712468
    1206812469@verbatim
    12069    % chicken program.scm -output-file program.c
    12070    % gcc program.c foo.o `chicken-config -cflags -libs` -o program
     12470   % csc program.scm foo.o -o program
    1207112471@end verbatim
    1207212472
     
    1207512475
    1207612476   This means you have compiled a library unit as an application. When a unit-declaration (as in @code{(declare (unit ...))})
    12077    is given, then this file has a specially named toplevel entry procedure (see Q23). Just remove the declaration,
     12477   is given, then this file has a specially named toplevel entry procedure. Just remove the declaration,
    1207812478   or compile this file to an object-module and link it to your application code.
    1207912479
     
    1212612526  @code{u16vector-ref}
    1212712527  @code{s16vector-ref}
     12528  @code{u32vector-ref}
     12529  @code{s32vector-ref}
     12530  @code{f32vector-ref}
     12531  @code{f64vector-ref}
    1212812532  @code{u8vector-set!}
    1212912533  @code{s8vector-set!}
     
    1213212536  @code{u32vector-set!}
    1213312537  @code{s32vector-set!}
     12538  @code{hash-table-ref}
    1213412539   @code{block-set!} @code{number-of-slots}
    1213512540    @code{first} @code{second} @code{third} @code{fourth} @code{null-pointer?} @code{pointer->object}
     
    1216412569(print #,(integer->char 33))
    1216512570@end lisp
    12166 
    12167 
    12168 @item Why does my program abort with an "out of memory" error when I compile with extended debug information?
    12169 
    12170 
    12171   The compiler instruments the source file with a lot of support code to provide things like arbitrary restarting/returning
    12172   from activation frames. This will transform calls in tail-position into non-tail calls in all situations but the most
    12173   trivial ones (@code{do} loops and named @code{let}). This will result in a much higher memory
    12174   usage for allocating continuation frames. Try passing the @code{-:hXXX} option when executing the program,
    12175   with a large value for @code{XXX}.
    1217612571
    1217712572
     
    1222312618
    1222412619
    12225 @item Why doesn't CHICKEN support the full numeric tower?
     12620@item Why doesn't CHICKEN support the full numeric tower by default?
     12621
     12622  The short answer:
     12623
     12624  @lisp
     12625  % chicken-setup numbers
     12626  % csi -q
     12627  #;1> (use numbers)
     12628  @end lisp
     12629
     12630  The long answer:
    1222612631
    1222712632  There are a number of reasons for this:
    12228  
    12229   - I haven't found a decent library for multiprecision arithmetic, yet (the GNU multiprecision
    12230    library is distributed under a different license than CHICKEN);
    1223112633 
    1223212634  - For most applications of Scheme fixnums (exact word-sized integers) and flonums (64-bit floating-point
    1223312635   numbers) are more than sufficient;
    1223412636 
    12235   -Interfacing to C is simpler;
     12637  - Interfacing to C is simpler;
    1223612638 
    12237   -Dispatching of arithmetic operations is more efficient.
     12639  - Dispatching of arithmetic operations is more efficient.
     12640
     12641  There is an extension based on the GNU Multiprecision Package that implements most of the full
     12642  numeric tower, see http://www.call-with-current-continuation.org/eggs/numbers.html.
    1223812643 
    1223912644
     
    1227612681
    1227712682
    12278 @item Why does a chicken have both dark and white meats?
    12279 
    12280 Short answer is chickens don't fly long distance. As a result the muscles
    12281 in the wings are designed for short bursts of activity and don't have as
    12282 many of the proteins that facilitate oxygen distribution in those
    12283 muscles. These proteins are coloured red and cause the dark colour of the
    12284 meat. Ducks fly a lot hand have dark meat in their wings. Chickens do
    12285 walk a lot so their leg and thighs are dark meat.
    12286  
    12287   (Thanks to Chris Double)
     12683@item Does CHICKEN support native threads?
     12684
     12685  Currently native threads are not supported. The runtime system is not reentrant, and the garbage-collection
     12686  algorithm would be made much more complicated, since the location of every object (whether it is allocated
     12687  on the stack or on the heap or completely outside the GC-able data space) has to be checked - this would
     12688  be rather complex and inefficient in a situation where multiple threads are involved.
     12689
    1228812690
    1228912691@end itemize
     
    1230212704   C:\> csc foo.scm -dll
    1230312705@end verbatim
    12304 
    12305    You can use the @code{define-entry-point} facility to interface to
    12306    the Scheme code.
    1230712706
    1230812707@item How do I generate a GUI application under Windows(tm)?
     
    1236812767  the main unit of the compiler (in the file @code{chicken.scm}) with an additional @code{uses}
    1236912768  declaration. Then link all compiler modules and your (compiled) extension to create a new version of
    12370   the compiler, like this (assuming a UNIX like environment and also assuming all sources are in the
     12769  the compiler, like this (assuming all sources are in the
    1237112770  current directory):
    1237212771
     
    1238612785              x2) ) ) ) )
    1238712786  ...
    12388   % chicken userpass.scm -output-file userpass.c -explicit-use -quiet
    12389   % chicken chicken.scm -output-file chicken-extended.c -quiet -postlude "(declare (uses userpass))"
    12390   % gcc -c userpass.c `chicken-config -cflags` -o userpass.o
    12391   % gcc -c chicken-extended.c `chicken-config -cflags` -o chicken-extended.o
     12787  % csc -c -x userpass.scm
     12788  % csc chicken.scm -c -o chicken-extended.o -uses userpass
    1239212789  % gcc chicken-extended.o support.o easyffi.o compiler.o optimizer.o batch-driver.o c-platform.o \
    12393     c-backend.o userpass.o `chicken-config -libs` -o chicken-extended
     12790    c-backend.o userpass.o `csc -ldflags -libs` -o chicken-extended
    1239412791@end verbatim
    1239512792
     
    1240312800
    1240412801@itemize
    12405 
    12406 @item Why does @code{(define-macro foo bar)} not work?
    12407 
    12408    Consider this code snippet:
    12409 
    12410 @verbatim
    12411    (define (double x) (list '* x x))
    12412 
    12413    (define-macro twice double)
    12414 @end verbatim
    12415 
    12416    Because the macro @code{twice} is defined at compile time (following forms may refer
    12417    to it), functions defined at runtime (as @code{double} in this case) are not available.
    12418    The alternative syntax of @code{define-macro}:
    12419 
    12420 @verbatim
    12421    (define-macro twice (lambda (x) (list '* x x)))
    12422 @end verbatim
    12423 
    12424    does just exist to make porting other Scheme code easier. It is not able to assign procedures
    12425    computed at runtime as macro expanders.
    1242612802
    1242712803@item Why doesn't my fancy macro work in compiled code?
     
    1244712823
    1244812824
    12449 Many thanks to:
    12450 
    12451 William Annis, Marc Baily, Peter Barabas, Jonah Beckford, Peter Bex, Dave Bodenstab, Fabian Böhlke, T. Kurt Bond,
    12452 Terence Brannon, Roy Bryant, Category 5, Taylor Campbell, Franklin Chen, Gian Paolo Ciceri, Grzegorz Chrupala,
     12825Many thanks to Sergey Khorev for maintaining the Windows port of CHICKEN and
     12826Brandon van Every for maintaining the @uref{http://www.cmake.org, CMake} build file
     12827
     12828Also many thanks to
     12829William Annis, Marc Baily, Peter Barabas, Jonah Beckford, Arto Bendiken, Peter Bex, Jean-Fran@,{c}ois Bignolles, Dave Bodenstab,
     12830Fabian B@"ohlke, T. Kurt Bond,
     12831Ashley Bone, Dominique Boucher,
     12832Terence Brannon, Roy Bryant, Adam Buchbinder, Hans Bulfone, Category 5, Taylor Campbell, Franklin Chen,
     12833Thomas Chust, Gian Paolo Ciceri,
     12834John Cowan, Grzegorz Chrupa@l{}a,
    1245312835James Crippen, Tollef Fog Heen, Alejandro Forero Cuervo, Linh Dang,
    12454 Brian Denheyer, Chris Double, Petter Egesund, Steve Elkins, Daniel B. Faken, Graham Fawcett, Fizzie, Kimura Fuyuki,
     12836Brian Denheyer, Chris Double, Jarod Eells, Petter Egesund, Steve Elkins, Daniel B. Faken, Graham Fawcett, Fizzie, Kimura Fuyuki,
    1245512837Tony Garnock-Jones, Martin Gasbichler,
    1245612838Joey Gibson,
    12457 Johannes Groedem, Andreas Gustafsson, Sven Hartrumpf,
    12458 Jun-ichiro itojun Hagino, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Bruce Hoult, Hans Hübner,
    12459 Christian Jaeger, Dale Jordan, Valentin Kamyshenko, Peter Keller,
    12460 Ron Kneusel, Matthias Koeppe, Krysztof Kowalczyk, Todd R. Kueny Sr, Micky Latowicki, Kirill Lisovsky,
    12461 Kon Lovett, Dennis Marti, Charles Martin, Alain Mellan,
     12839Johannes Gr@o{}dem, Damian Gryski, Mario Domenech Goulart, Andreas Gustafsson, Sven Hartrumpf,
     12840Jun-ichiro itojun Hagino, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Bill Hoffman, Bruce Hoult, Hans H@"ubner,
     12841David Janssens, Christian Jaeger, Dale Jordan, Valentin Kamyshenko, Daishi Kato, Peter Keller,
     12842Ron Kneusel, Matthias Koeppe, Krysztof Kowa@l{}czyk, Todd R. Kueny Sr, Goran Krampe, Micky Latowicki, John Lenz, Kirill Lisovsky,
     12843Kon Lovett, Dennis Marti, Charles Martin, Bob McIsaac, Alain Mellan,
    1246212844Eric Merrit, Perry Metzger,
    1246312845Scott G. Miller, Mikael, Bruce Mitchener, Chris Moline,
    12464 Eric E. Moore, Julian Morrison, Lars Nilsson, o.t., Davide Puricelli, Doug Quale,
    12465 Eric Raible, Joel Reymont, David Rush, Lars Rustemeier, Oskar Schirmer, Burton Samograd,
    12466 Reed Sheridan, Ronald Schr&ouml;der,
    12467 Spencer Schumann, Shmul, Jeffrey B. Siegal, Michele Simionato, Dorai Sitaram,
    12468 Robert Skeels, Jason Songhurst, Clifford Stein, Zbigniew Szadkowski, Mike Thomas, Christian Tismer,
    12469 Andre van Tonder, John Tobey,
     12846Eric E. Moore, Julian Morrison, Dan Muresan, Lars Nilsson, o.t., Gene Pavlovsky, Levi Pearson, Nicolas Pelletier, Carlos Pita,
     12847Pupeno, Davide Puricelli, Doug Quale,
     12848Eric Raible, Joel Reymont, Andreas Rottman, David Rush, Lars Rustemeier, Oskar Schirmer, Burton Samograd,
     12849Reed Sheridan, Ronald Schr@"oder,
     12850Spencer Schumann, Alex Shinn, Shmul, Jeffrey B. Siegal, Andrey Sidorenko, Michele Simionato, Volker Stolz, Dorai Sitaram,
     12851Robert Skeels, Jason Songhurst, Clifford Stein, Sunnan, Zbigniew Szadkowski, Mike Thomas, Christian Tismer,
     12852Andre van Tonder, John Tobey, Henrik Tramberend,
    1247012853Vladimir Tsichevsky,
    1247112854Neil van Dyke, Sander Vesik, Panagiotis Vossos, Shawn Wagner, Peter Wang,
    12472 Ed Watkeys, Thomas Weidner, Matthew Welland, Joerg Wittenberger, Mark Wutka,
     12855Ed Watkeys, Thomas Weidner, Matthew Welland, Joerg Wittenberger, Peter Wright, Mark Wutka,
    1247312856Richard Zidlicky and Houman Zolfaghari for bug-fixes, tips and suggestions.
    1247412857
    12475 Special thanks to Benedikt Rosenau for his continuous moral support.
     12858Special thanks to Benedikt Rosenau for constant encouragement.
    1247612859
    1247712860CHICKEN contains code from several people:
     
    1247912862@itemize
    1248012863@item Eli Barzilay: some performance tweaks used in TinyCLOS.
    12481 @item Anthony Carrico: the option parsing facility.
    1248212864@item Mikael Djurfeldt: topological sort used by compiler.
    1248312865@item Marc Feeley: pretty-printer.
    1248412866@item Aubrey Jaffer: implementation of @code{dynamic-wind}.
    1248512867@item Gregor Kiczales: original implementation of TinyCLOS.
    12486 @item Dirk Lutzebaeck: Common LISP @code{format}.
    1248712868@item Richard O'Keefe: sorting routines.
    1248812869@item Olin Shivers: implementation of @code{let-optionals[*]} and
    1248912870reference implementations of SRFI-1, SRFI-13 and SRFI-14.
    12490 @item Dorai Sitaram: the PREGEXP regular expression package and
    12491 TeX2page, which was used to generate the HTML documentation.
     12871@item Dorai Sitaram: the PREGEXP regular expression package
    1249212872@item Andrew Wilcox: queues.
    1249312873@item Andrew Wright: pattern matcher.
Note: See TracChangeset for help on using the changeset viewer.