This is chicken.info, produced by makeinfo version 4.7 from
chicken.texi.

Copyright (C) 2000-2004, Felix L. Winkelmann All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   * Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

   * Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the
     distribution.

   * Neither the name of the author nor the names of its contributors
     may be used to endorse or promote products derived from this
     software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE,
DATA, OR PROFITS OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* CHICKEN: (chicken).          A pratical and portable Scheme system (Version 1, Build 89).
END-INFO-DIR-ENTRY

Copyright (C) 2000-2004, Felix L. Winkelmann All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:

   * Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.

   * Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the
     distribution.

   * Neither the name of the author nor the names of its contributors
     may be used to endorse or promote products derived from this
     software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES LOSS OF USE,
DATA, OR PROFITS OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


File: chicken.info,  Node: Top,  Next: Introduction,  Up: (dir)

CHICKEN
*******

CHICKEN - A practical and portable Scheme system User's manual (Version
1, Build 89)

   (c) 2000-2004, Felix L. Winkelmann All rights reserved. Translated
to LaTeX by Peter Keller. Translated to texinfo by Linh Dang.

* Menu:

* Introduction::
* Basic mode of operation::
* Using the compiler::
* Using the interpreter::
* Supported language::
* Interface to external functions and variables::
* chicken-setup::
* Additional files::
* Data Representation::
* Bugs and limitations::
* FAQ::
* Acknowledgements::
* Bibliography::
* Index::

 --- The Detailed Node Listing ---

Using the compiler

* Compiler command line format::
* Runtime options::
* An example::
* Extending the compiler::
* Distributing compiled C files::

Using the interpreter

* Interpreter  command line format::
* Writing Scheme scripts::
* Toplevel commands::
* Macros and procedures implemented in the interpreter::

Supported language

* Deviations from the standard::
* Extensions to the standard::
* Non standard read syntax::
* Non-standard macros and special forms::
* Declarations::
* Parameters::
* Unit library::
* Unit eval::
* Unit extras::
* Unit srfi-1::
* Unit srfi-4::
* Unit srfi-13::
* Unit srfi-14::
* Unit srfi-25::
* Unit match::
* Unit regex::
* Unit syntax-case::
* Unit srfi-18::
* Unit format::
* Unit posix::
* Unit utils::
* Unit tcp::
* Unit srfi-37::
* Unit lolevel::
* Unit tinyclos::

Non-standard macros and special forms

* Binding forms for optional arguments::
* Other binding forms::
* Substitution forms and macros::
* Conditional forms::
* Record structures::
* Other forms::

Unit library

* Arithmetic::
* File Input/Output::
* Files::
* String ports::
* Feature identifiers::
* Keywords::
* Exceptions::
* Environment information and system interface::
* Execution time::
* Interrupts and error-handling::
* Garbage collection::
* Other control structures::
* String utilities::
* Generating uninterned symbols::
* Standard Input/Output::
* User-defined named characters::
* Vectors::
* The unspecified value::
* call/cc::

Unit eval

* Loading code::
* Read-eval-print loop::
* Macros::
* Loading extension libraries::
* Reader extensions::
* Eval::

Unit extras

* Lists::
* String-port extensions::
* Formatted output::
* Hash tables::
* Queues::
* Sorting::
* Random numbers::
* Input/Output extensions::
* Strings::
* Combinators::
* Binary searching::

Unit posix

* Directories::
* Pipes::
* Fifos::
* File descriptors and low-level I/O::
* Retrieving file attributes::
* Changing file attributes::
* Processes::
* Symbolic links::
* Permissions::
* Record locking::
* Signal handling::
* Environment access::
* Memory mapped I/O::
* Time routines::
* Raw exit::
* ERRNO values::
* Finding files::
* Getting the hostname and system information::
* Setting a files buffering mode::
* Terminal ports::
* How Scheme procedures relate to UNIX C functions::
* Windows specific notes::

Unit utils

* Pathname operations::
* Temporary files::
* Deleting a file without signalling an error::
* Iterating over input lines and files::
* Executing shell commands with formatstring and error checking::

Unit lolevel

* Foreign pointers::
* Tagged pointers::
* Extending procedures with data::
* Bytevectors::
* Data in unmanaged memory::
* Locatives::
* Accessing toplevel variables::
* Low-level data access::
* Procedure-call- and variable reference hooks::
* Magic::

Unit tinyclos

* Defining forms::
* Base language::
* Introspection::
* Intercessory protocol::
* Additional protocol::
* Utility procedures::
* Builtin classes::

Interface to external functions and variables

* Accessing external objects::
* Foreign type specifiers::
* Entry points::
* Callbacks::
* Locations::
* Other support procedures::
* The Easy Foreign Function Interface::
* C interface::

The _Easy_ Foreign Function Interface

* #> ... <# Syntax::
* General operation::
* Pseudo declarations::
* Grammar::
* C notes::
* C++ notes::
* Using the builtin parser::
* Specification grammar::

chicken-setup

* Extension libraries::
* Installing extensions::
* Creating extensions::
* Procedures and macros available in setup scripts::

Additional files

* chicken-highlevel-macros.scm::
* chicken-more-macros.scm::
* chicken-ffi-macros.scm::
* chicken-entry-points.scm::
* chicken-default-entry-points.scm::
* test-infrastructure.scm::

`test-infrastructure.scm'

* The Test Package Macro API::
* The Test Case Macro API::
* The Expectation Macro API::
* Result Object API::
* Test Package Result Object API::
* Test Case Result Object API::
* Single Clause Style Expectation::
* Equivalence Style Expectation::
* Tolerance Style Expectation::
* Various Helper API::
* Termination API::
* Destructor Object API::
* Todo API::
* Gloss API::
* Skip API::
* Side Effect API::
* Miscellaneous API::
* Analysis of the Result Tree::
* Output Generation API::
* Example Usages of the Test Suite Infrastructure::


File: chicken.info,  Node: Introduction,  Next: Basic mode of operation,  Prev: Top,  Up: Top

1 Introduction
**************

CHICKEN is a compiler that translates Scheme source files into C, which
in turn can be fed to a C-compiler to generate a standalone executable.
This principle, which is used by several existing compilers, achieves
high portability because C is implemented on nearly all available
platforms.

   This package is distributed under the BSD license and as such is free
to use and modify. An interpreter is also available and can be used as
a scripting environment or for testing programs before compilation.

   The method of compilation and the design of the runtime-system follow
closely Henry Baker's `CONS Should Not CONS Its Arguments, Part II:
Cheney on the M.T.A.' paper and expose a number of interesting
properties: consing (creation of data on the heap) is relatively
inexpensive, because a generational garbage collection scheme is used,
in which short-lived data structures are reclaimed extremely quickly.
Moreover, `call-with-current-continuation' is practically for free and
CHICKEN does not suffer under any performance penalties if first-class
continuations are used in complex ways.  The generated C code is fully
tail-recursive.

   Some of the features supported by CHICKEN:
   * SRFIs 0, 1, 2, 4, 6, 7, 8, 9, 10, 13, 14, 16, 18, 23, 25, 28, 30,
     37, 39   and 55.

   * `syntax-case' highlevel macros

   * Lightweight threads based on first-class continuations

   * Pattern matching with Andrew Wright's `match' package

   * Record structures

   * An object system with multiple inheritance, multimethods and a
                meta-object protocol

   * Extended comment- and string-literal syntaxes

   * Libraries for regular expressions, string handling, Common LISP
                 style `format', UNIX system calls and extended data
     structures

   * Create interpreted or compiled shell scripts written in Scheme
                for UNIX or Windows

   * Compiled C files can be easily distributed

   * Allows the creation of fully self-contained statically linked
     executables

   * On systems that support it, compiled code can be loaded dynamically

   This manual is merely a reference for the CHICKEN system and assumes
a working knowledge of Scheme.


File: chicken.info,  Node: Basic mode of operation,  Next: Using the compiler,  Prev: Introduction,  Up: Top

2 Basic mode of operation
*************************

The compiler translates Scheme source code into fairly portable C that
can be compiled and linked with most available C compilers. CHICKEN
supports the generation of executables and libraries, linked either
statically or dynamically. Compiled Scheme code can be loaded
dynamically, or can be embedded in applications written in other
languages. Separate compilation of modules is fully supported.

   The most portable way of creating separately linkable entities is
supported by so-called _unit_s.  A unit is a single compiled object
module that contains a number of toplevel expressions that are executed
either when the unit is the _main_ unit or if the unit is _used_.  To
use a unit, the unit has to be _declare_ed as used, like this:


(declare (uses UNITNAME))

   The toplevel expressions of used units are executed in the order in
which the units appear in the `uses' declaration. Units may be used
multiple times and `uses' declarations may be circular (the unit is
initialized at most once).  To compile a file as a unit, add a `unit'
declaration:


(declare (unit UNITNAME))

   When compiling different object modules, make sure to have one main
unit. This unit is called initially and initializes all used units
before executing its toplevel expressions. The main-unit has no `unit'
declaration.

   Another method of using definitions in separate source files is to
_include_ them. This simply inserts the code in a given file into the
current file:


(include "FILENAME")

   Macro definitions are only available when processed by `include' or
`visit'.  Macro definitions in separate units are not available, since
they are defined at compile time, i.e the time when that other unit was
compiled (macros defined using the low-level macro system can
optionally be available at runtime, see `define-macro' in *Note
Substitution forms and macros::).

   On platforms that support dynamic loading of compiled code (like
Windows and most ELF based systems like Linux or BSD) code can be
compiled into a shared object (`.so') and loaded dynamically into a
running application.


File: chicken.info,  Node: Using the compiler,  Next: Using the interpreter,  Prev: Basic mode of operation,  Up: Top

3 Using the compiler
********************

The interface to `chicken' is intentionally simple.  System dependent
makefiles, shell-scripts or batch-files should perform any necessary
steps before and after invocation of `chicken'.  On UNIX-compatible
systems, a shell script named `chicken-config' is supplied that emits
the correct options for the host system's C compiler. Enter


chicken-config -help

   on the command line for a list of available options. A program named
`csc' provides a much simpler interface to the Scheme- and C-compilers
and linker. Enter


csc -help

   on the command line for more information.

* Menu:

* Compiler command line format::
* Runtime options::
* An example::
* Extending the compiler::
* Distributing compiled C files::


File: chicken.info,  Node: Compiler command line format,  Next: Runtime options,  Up: Using the compiler

3.1 Command line format
=======================

`chicken FILENAME {OPTION}'

   `FILENAME' is the complete pathname of the source file that is to be
translated into C. A filename argument of "`-'" specifies that the
source text should be read from standard input. Note that the filename
has to be the first argument to `chicken'.  Possible options are:

`-analyze-only'
     Stop compilation after first analysis pass.

`-benchmark-mode'
     Equivalent to `-debug-level 0 -optimize-level 3'
     `-fixnum-arithmetic -disable-interrupts -block -lambda-lift'.

`-block'
     Enable block-compilation. When this option is specified, the
     compiler assumes that global variables are not modified outside
     this compilation-unit.  Specifically, toplevel bindings are not
     seen by `eval' and unused toplevel bindings are removed.

`-case-insensitive'
     Enables the reader to read symbols case insensitive. The default
     is to read case sensitive (in violation of R5RS).  This option
     registers the `case-insensitive' feature identifier.

`-check-syntax'
     Aborts compilation process after macro-expansion and syntax checks.

`-compress-literals THRESHOLD'
     Compiles quoted literals that exceed the size `THRESHOLD' as
     strings and parse the strings at run-time. This reduces the size
     of the code and speeds up compile-times of the host C compiler,
     but has a small run-time performance penalty. The size of a
     literal is computed by counting recursively the objects in the
     literal, so a vector counts as 1 plus the count of the elements, a
     pair counts as the counts of the car and the cdr, respectively.
     All other objects count 1.

`-debug MODES'
     Enables one or more compiler debugging modes. `MODES' is a string
     of characters that select debugging information about the compiler
     that will be printed to standard output.

    `t'
          show time needed for compilation

    `b'
          show breakdown of time needed for each compiler pass

    `o'
          show performed optimizations

    `r'
          show invocation parameters

    `s'
          show program-size information and other statistics

    `a'
          show node-matching during simplification

    `p'
          show execution of compiler sub-passes

    `l'
          show lambda-lifting information

    `m'
          show GC statistics during compilation

    `n'
          print the line-number database

    `c'
          print every expression before macro-expansion

    `e'
          lists all exported toplevel bindings

    `x'
          display information about experimental features

    `D'
          when printing nodes, use node-tree output

    `N'
          show the real-name mapping table

    `U'
          show expressions after the secondary user pass

    `0'
          show database before lambda-lifting pass

    `L'
          show expressions after lambda-lifting

    `F'
          show output of "easy" FFI parser

    `P'
          show execution of outer partitioning

    `Q'
          show execution of middle partitioning

    `R'
          show execution of inner partitioning

    `1'
          show source expressions

    `2'
          show canonicalized expressions

    `3'
          show expressions converted into CPS

    `4'
          show database after each analysis pass

    `5'
          show expressions after each optimization pass

    `6'
          show expressions after each inlining pass

    `7'
          show expressions after complete optimization

    `8'
          show database after final analysis

    `9'
          show expressions after closure conversion

`-debug-level LEVEL'
     Selects amount of debug-information. `LEVEL' should be an integer.

        * `-debug-level 0' is equivalent to `-no-trace'.

        * `-debug-level 1' does nothing.

`-disable-c-syntax-checks'
     Disable basic syntax checking of embedded C code fragments.

`-disable-interrupts'
     Equivalent to the `(disable-interrupts)' declaration. No
     interrupt-checks are generated for compiled programs.

`-disable-stack-overflow-checks'
     Disables detection of stack overflows. This is equivalent to
     running the compiled executable with the `-:o' runtime option.

`-dynamic'
     This option should be used when compiling files intended to be
     loaded dynamically into a running Scheme program.

`-epilogue FILENAME'
     Includes the file named `FILENAME' at the end of the compiled
     source file. The include-path is not searched. This option may be
     given multiple times.

`-explicit-use'
     Disables automatic use of the units `library, eval' and `extras'.
     Use this option if compiling a library unit instead of an
     application unit.

`-extend FILENAME'
     Loads a Scheme source file or compiled Scheme program (on systems
     that support it) before compilation commences. This feature can be
     used to extend the compiler.  This option may be given multiple
     times.  The file is also searched in the current include path and
     in the extension-repository.

`-feature SYMBOL'
     Registers `SYMBOL' to be a valid feature identifier for
     `cond-expand'.

`-ffi'
     Parse C/C++ code and generate Scheme bindings. This is effectively
     equivalent to wrapping the code in `#>! ... <#'.

`-ffi-custom'
     Parse C/C++ code and embed it into a `(foreign-parse/spec ...)'
     form. This is effectively equivalent to wrapping the code in `#>%
     ... <#').  Use the `-extend' or `-require-for-synatx' options to
     provide a definition for the `foreign-parse/spec' macro.

`-ffi-parse'
     Parse C/C++ code and embed as if wrapped inside `#>? ... <#'.

`-ffi-define SYMBOL'
     Defines a macro that will be accessible in `foreign-parse'
     declarations.

`-ffi-include-path PATH'
     Set include path for "easy" FFI parser.

`-fixnum-arithmetic'
     Equivalent to `(fixnum-arithmetic)' declaration. Assume all
     mathematical operations use small integer arguments.

`-heap-size NUMBER'
     Sets a fixed heap size of the generated executable to `NUMBER'
     bytes. The parameter may be followed by a `M' (`m') or `K' (`k')
     suffix which stand for mega- and kilobytes, respectively.  The
     default heap size is 5 kilobytes. Note that only half of it is in
     use at every given time.

`-heap-initial-size NUMBER'
     Sets the size that the heap of the compiled application should
     have at startup time.

`-heap-growth PERCENTAGE'
     Sets the heap-growth rate for the compiled program at compile time
     (see: `-:hg').

`-heap-shrinkage PERCENTAGE'
     Sets the heap-shrinkage rate for the compiled program at compile
     time (see: `-:hs').

`-help'
     Print a summary of available options and the format of the command
     line parameters and exit the compiler.

`-syntax'

`-hygienic'
     Load "syntax-case" macro package and enable high-level macros in
     compiled code.  This option registers the `hygienic-macros'
     feature identifier.

`-hygienic-at-run-time'
     Makes hygienic ("syntax-case") macro system available at run-time.
     Note that this has a slight overhead, because the hygienic macro
     definitions have to be loaded. This will only install the standard
     R5RS macros, plus SRFI-0 (`cond-expand'). To load all further
     macros, execute:


     (require-extension chicken-more-macros)

`-include-path PATHNAME'
     Specifies an additional search path for files included via the
     `include' special form. This option may be given multiple times. If
     the environment variable `CHICKEN_INCLUDE_PATH' is set, it should
     contain a list of alternative include pathnames separated by
     "`;'". The environment variable `CHICKEN_HOME' is also considered
     as a search path.

`-keyword-style STYLE'
     Enables alternative keyword syntax, where `STYLE' may be either
     `prefix' (as in Common Lisp), `suffix' (as in DSSSL) or `none'.
     Any other value is ignored. The default is `suffix'.  If `-strict'
     or `-strict-reader' is specified, then the keyword style is set to
     `none'.

`-lambda-lift'
     Enable the optimization known as lambda-lifting.

`-no-trace'
     Disable generation of tracing information. If a compiled
     executable should halt due to a runtime error, then a list of the
     name and the line-number (if available) of the last procedure
     calls is printed, unless `-no-trace' is specified. With this
     option the generated code is slightly faster.

`-no-feature SYMBOL'
     Unregisters feature identifier `SYMBOL'.

`-no-warnings'
     Disable generation of compiler warnings.

`-nursery NUMBER'

`-stack-size NUMBER'
     Sets the size of the first heap-generation of the generated
     executable to `NUMBER' bytes. The parameter may be followed by a
     `M' (`m') or `K' (`k') suffix.  The default stack-size depends on
     the target platform.

`-optimize-leaf-routines'
     Enable leaf routine optimization.

`-optimize-level LEVEL'
     Enables certain sets of optimization options. `LEVEL' should be an
     integer.

        * `-optimize-level 0' does nothing.

        * `-optimize-level 1' is equivalent to
          `-optimize-leaf-routines'

        * `-optimize-level 2' is equivalent to
          `-optimize-leaf-routines'

        * `-optimize-level 3' is equivalent to
          `-optimize-leaf-routines -unsafe'

`-output-file FILENAME'
     Specifies the pathname of the generated C file. Default is
     `FILENAME.c'.

`-postlude EXPRESSIONS'
     Add `EXPRESSIONS' after all other toplevel expressions in the
     compiled file.  This option may be given multiple times.
     Processing of this option takes place after processing of
     `-epilogue'.

`-prelude EXPRESSIONS'
     Add `EXPRESSIONS' before all other toplevel expressions in the
     compiled file.  This option may be given multiple times.
     Processing of this option takes place before processing of
     `-prologue'.

`-profile'
     Instruments the source code to count procedure calls and execution
     times. After the program terminates (either via an explicit `exit'
     or implicitly), profiling statistics are written to a file named
     `PROFILE'. Each line of the generated file contains a list with
     the procedure name, the number of calls and the time spent
     executing it. Use the `chicken-format-profile' program to display
     the profiling information in a more user-friendly form. Enter
     `chicken-format-profile' with no arguments at the command line to
     get a list of available options.

`-prologue FILENAME'
     Includes the file named `FILENAME' at the start of the compiled
     source file.  The include-path is not searched. This option may be
     given multiple times.

`-quiet'
     Disables output of compile information.

`-raw'
     Disables the generation of any implicit code that uses the Scheme
     libraries (that is all runtime system files besides `runtime.c'
     and `chicken.h').

`-require-for-syntax NAME'
     Loads the extension `NAME' before the compilation process
     commences.

`-r5rs'
     Equivalent to `-hygienic -strict -no-usual-integrations'.

`-run-time-macros'
     Makes low-level macros (compiled without the `-hygienic' option)
     also available at run-time. By default low-level macros are not
     available at run-time. Note that highlevel-macros (`syntax-case')
     defined in compiled code are never available at run-time.

`-split NUMBER'
     Splits output into multiple C files that can be compiled
     seperately. The generated C files will be named `filename0', ...,
     `filename<NUMBER-1>' with as many files as given in `NUMBER'.

`-split-level NUMBER'
     Specifies how hard the partitioning algorithm should work:

        * 0 Exit after first iteration (quickest)

        * 1 Exit when cost does not decrease by at least one-half (the
          default)

        * 2 Exit when cost does not change

`-strict'
     Disable non-standard macros. This option registers the `strict'
     feature identifier. Implies `-strict-letrec' and `-strict-reader'.

`-strict-srfi-0'
     Disable non-standard macros except `cond-expand'.  This option
     registers the `strict' feature identifier. Implies `-strict-letrec'
     and `-strict-reader'.

`-strict-reader'
     Disables non-standard read syntax. Implies `-case-insensitive'.

`-strict-letrec'
     Enable fully R5RS compliant `letrec'. This generates slightly less
     efficient code but preserves standard semantics.

`-to-stdout'
     Write compiled code to standard output instead of creating a `.c'
     file.

`-unit NAME'
     Compile this file as a library unit. Equivalent to


     -prelude "(declare (unit NAME))"

`-unsafe'
     Disable runtime safety checks.

`-unsafe-libraries'
     Marks the generated file for being linked with the unsafe runtime
     system. This should be used when generating shared object files
     that are to be loaded dynamically. If the marker is present, any
     attempt to load code compiled with this option will signal an
     error.

`-uses NAME'
     Use definitions from the library unit `NAME'. This is equivalent to


     -prelude "(declare (uses NAME))"

`-no-usual-integrations'
     Specifies that standard procedures and certain internal procedures
     may be redefined, and can not be inlined. This is equivalent to
     declaring `(not usual-integrations)'.

`-version'
     Prints the version and some copyright information and exit the
     compiler.

`-verbose'
     Prints progress information to standard output during compilation.


   The environment variable `CHICKEN_OPTIONS' can be set to a string
with default command-line options for the compiler.


File: chicken.info,  Node: Runtime options,  Next: An example,  Prev: Compiler command line format,  Up: Using the compiler

3.2 Runtime options
===================

After successful compilation a C source file is generated and can be
compiled with a C compiler. Executables generated with CHICKEN (and the
compiler itself) accept a small set of runtime options:

`-:?'
     Shows a list of the available runtime options and exits the
     program.

`-:c'
     Forces console mode. Currently this is only used in the interpreter
     (`csi') to force output of the #;N> prompt even if stdin is not a
     terminal (for example if running in an `emacs' buffer under
     Windows).

`-:d'
     Prints some debug-information during startup.

`-:hNUMBER'
     Specifies fixed heap size

`-:hiNUMBER'
     Specifies the initial heap size

`-:hgPERCENTAGE'
     Sets the growth rate of the heap in percent. If the heap is
     exhausted, then it will grow by `PERCENTAGE'.  The default is 200.

`-:hmNUMBER'
     Specifies a maximal heap size. The default is (2GB - 15).

`-:hsPERCENTAGE'
     Sets the shrink rate of the heap in percent. If no more than a
     quarter of `PERCENTAGE' of the heap is used, then it will shrink to
     `PERCENTAGE'. The default is 50.  Note: If you want to make sure
     that the heap never shrinks, specify a value of `0'.  (this can be
     useful in situations where an optimal heap-size is known in
     advance).

`-:o'
     Disables detection of stack overflows at run-time

`-:sNUMBER'
     Specifies stack size

`-:tNUMBER'
     Specifies symbol table size

`-:w'
     Enables garbage collection of unused symbols. By default unused and
     unbound symbols are not garbage collected.

`-:r'
     Writes trace output to stdout. This option has no effect with in
     files compiled with the `-no-trace' or `-debug-level 0' options.

`-:x'
     Raises uncaught exceptions of separately spawned threads in
     primordial thread.  By default uncaught exceptions in separate
     threads are not handled, unless the primordial one explicitly
     joins them. When warnings are enabled (the default) and `-:x' is
     not given, a warning will be shown, though.


   The argument values may be given in bytes, in kilobytes (suffixed
with `K' or `k'), in megabytes (suffixed with `M' or `m'), or in
gigabytes (suffixed with `G' or `g'). Runtime options may be combined,
like `-:dc', but everything following a `NUMBER' argument is ignored. So
`-:wh64m' is OK, but `-:h64mw' will not enable GC of unused symbols.


File: chicken.info,  Node: An example,  Next: Extending the compiler,  Prev: Runtime options,  Up: Using the compiler

3.3 An example
==============

To compile a Scheme program (assuming a UNIX-like environment) perform
the following steps:

   * Consider this Scheme source file, named `foo.scm'
       ;;; foo.scm

       (define (fac n)
         (if (zero? n)
             1
             (* n (fac (- n 1))) ) )

       (write (fac 10))
       (newline)

   * Compile the file `foo.scm'
     % chicken foo.scm

   * Compile the generated C file `foo.c'
     % gcc foo.c -o foo `chicken-config -cflags -libs`

   * Start the compiled program
     % foo

     3628800


   If multiple bodies of Scheme code are to be combined into a single
executable, then we have to compile each file and link the resulting
object files together with the runtime system:

   * Consider these two Scheme source files, named `foo.scm' and
     `bar.scm'


       ;;; foo.scm

       (declare (uses bar))

       (write (fac 10)) (newline)


       ;;; bar.scm

       (declare (unit bar))

       (define (fac n)
         (if (zero? n)
             1
             (* n (fac (- n 1))) ) )

   * Compile the files `foo.scm' and `bar.scm'
     % chicken foo.scm
     % chicken bar.scm

   * Compile the generated C files `foo.c' and `bar.c'
     % gcc -c foo.c `chicken-config -cflags`
     % gcc -c bar.c `chicken-config -cflags`

   * Link the object files `foo.o' and `bar.o'
     % gcc foo.o bar.o -o foo `chicken-config -libs`

   * Start the compiled program
     % foo
     3628800


   The declarations specify which of the compiled files is the main
module, and which is the library module. An executable can only have
one main module, since a program has only a single entry-point. In this
case `foo.scm' is the main module, because it doesn't have a `unit'
declaration.

   Extensions to the basic CHICKEN runtime libraries are available in a
separate utility library (`libsrfi-chicken.[a|so]' and
`libstuffed-chicken.[a|so]' on UNIX-like platforms,
`libsrfi-chicken.lib' and `libstuffed-chicken.lib' on Windows systems).
Whenever you use one or more of the units `format, srfi-1, srfi-4,
srfi-13, srfi-14, srfi-18, srfi-25, srfi-37, posix, utils, lolevel,
tinyclos' or `regex', then you should add these library to the command
line of the C compiler or linker. The compiler driver `csc' and the
helper script `chicken-config' will do this automatically.


File: chicken.info,  Node: Extending the compiler,  Next: Distributing compiled C files,  Prev: An example,  Up: Using the compiler

3.4 Extending the compiler
==========================

The compiler supplies a couple of hooks to add user-level passes to the
compilation process. Before compilation commences any Scheme source
files or compiled code specified using the `-extend' option are loaded
and evaluated.  The parameters `user-options-pass, user-read-pass,
user-preprocessor-pass, user-pass, user-pass-2' and
`user-post-analysis-pass' can be set to procedures that are called to
perform certain compilation passes instead of the usual processing (for
more information about parameters see: *Note Parameters::.

 -- parameter: user-options-pass
     Holds a procedure that will be called with a list of command-line
     arguments and should return two values: the source filename and
     the actual list of options, where compiler switches have their
     leading `-' (hyphen) removed and are converted to symbols.  Note
     that this parameter is invoked before processing of the `-extend'
     option, and so can only be changed in compiled user passes.

 -- parameter: user-read-pass
     Holds a procedure of three arguments. The first argument is a list
     of strings with the code passed to the compiler via `-prelude'
     options. The second argument is a list of source files including
     any files specified by `-prologue' and `-epilogue'. The third
     argument is a list of strings specified using `-postlude' options.
     The procedure should return a list of toplevel Scheme expressions.

 -- parameter: user-preprocessor-pass
     Holds a procedure of one argument. This procedure is applied to
     each toplevel expression in the source file before
     macro-expansion. The result is macro-expanded and compiled in
     place of the original expression.

 -- parameter: user-pass
     Holds a procedure of one argument. This procedure is applied to
     each toplevel expression after macro-expansion.  The result of the
     procedure is then compiled in place of the original expression.

 -- parameter: user-pass-2
     Holds a procedure of three arguments, which is called with the
     canonicalized node-graph as its sole argument. The result is
     ignored, so this pass has to mutate the node-structure to cause
     any effect.

 -- parameter: user-post-analysis-pass
     Holds a procedure that will be called after the last performed
     program analysis. The procedure (when defined) will be called with
     three arguments: the program database, a getter and a
     setter-procedure which can be used to access and manipulate the
     program database, which holds various information about the
     compiled program. The getter procedure should be called with two
     arguments: a symbol representing the binding for which information
     should be retrieved, and a symbol that specifies the
     database-entry. The current value of the database entry will be
     returned or `#f', if no such entry is available. The setter
     procedure is called with three arguments: the symbol and key and
     the new value.

     For information about the contents of the program database contact
     the author.

   Loaded code (via the `-extend' option) has access to the library
units `extras, srfi-1, srfi-4, utils, regex' and the pattern matching
macros.  The highlevel macro-system and multithreading is not available.

   Note that the macroexpansion/canonicalization phase of the compiler
adds certain forms to the source program.  These extra expressions are
not seen by `user-preprocessor-pass' but by `user-pass'.


File: chicken.info,  Node: Distributing compiled C files,  Prev: Extending the compiler,  Up: Using the compiler

3.5 Distributing compiled C files
=================================

It is relatively easy to create distributions of Scheme projects that
have been compiled to C.  The runtime system of CHICKEN consists of only
two handcoded C files (`runtime.c' and `chicken.h'), plus the file
`chicken-config.h', which is generated by the build process. All other
modules of the runtime system and the extension libraries are just
compiled Scheme code. The following example shows a minimal
application, which should run without changes on the most frequent
operating systems, like Windows, Linux or FreeBSD:

   Let's take a simple "Hello, world!":


; hello.scm

(print "Hello, world!")

   Compiled to C, we get `hello.c'. We need the files `chicken.h' and
`runtime.c', which contain the basic runtime system, plus `library.c',
the compiled form of `library.scm', which contains the core library.
Note the use of the `-explicit-use -uses library' option in the
invocation of `chicken' to make sure we only link in the core library -
the `eval' and `extras' library units are not used in this example:


% chicken hello.scm -explicit-use -uses hello.c -optimize-level 2 -debug-level 0

   A simple makefile is needed as well:


# Makefile for UNIX systems

hello: hello.o runtime.o library.o
       $(CC) -o hello hello.o runtime.o library.o -lm

hello.o: chicken.h
runtime.o: chicken.h
library.o: chicken.h

   Now we have all files together, and can create an tarball containing
all the files:


% tar cf hello.tar Makefile hello.c runtime.c library.c chicken.h
% gzip hello.tar

   This is of naturally rather simplistic. Things like enabling dynamic
loading, estimating the optimal stack-size and selecting supported
features of the host system would need more configuration- and
build-time support. All this can be addressed using more elaborate
build-scripts, makefiles or by using autoconf/automake/libtool.

   For more information, study the CHICKEN source code and/or get in
contact with the author.


File: chicken.info,  Node: Using the interpreter,  Next: Supported language,  Prev: Using the compiler,  Up: Top

4 Using the interpreter
***********************

CHICKEN provides an interpreter named `csi' for evaluating Scheme
programs and expressions interactively.

* Menu:

* Interpreter  command line format::
* Writing Scheme scripts::
* Toplevel commands::
* Macros and procedures implemented in the interpreter::


File: chicken.info,  Node: Interpreter command line format,  Next: Writing Scheme scripts,  Up: Using the interpreter

4.1 Command line format
=======================


  csi {FILENAME|OPTION}

where `FILENAME' specifies a file with Scheme source-code.  If the
extension of the source file is `.scm', it may be omitted. The runtime
options described in *Note Compiler command line format:: are also
available for the interpreter.  If the environment variable
`CSI_OPTIONS' is set to a list of options, then these options are
additionally passed to every direct or indirect invocation of `csi'.
Please note that runtime options (like `-:...') can not be passed using
this method.  The options recognized by the interpreter are:

`--'
     Ignore everything on the command-line following this marker.
     Runtime options ("`-:...'") are still recognized.

`-case-insensitive'
     Enables the reader to read symbols case insensitive. The default
     is to read case sensitive (in violation of R5RS).  This option
     registers the `case-insensitive' feature identifier.

`-batch'
     Quit the interpreter after processing all command line options.

`-eval EXPRESSIONS'
     Evaluate `EXPRESSIONS'.

`-feature SYMBOL'
     Registers `SYMBOL' to be a valid feature identifier for
     `cond-expand'.

`-help'
     Write a summary of the available command line options to standard
     output and exit.

`-syntax'

`-hygienic'
     Load syntax-case macro package and enable high-level macros in
     interpreted code.  This option registers the `hygienic-macros'
     feature identifier.

`-include-path PATHNAME'
     Specifies an alternative search-path for files included via the
     `include' special form. This option may be given multiple times. If
     the environment variable `CHICKEN_INCLUDE_PATH' is set, it should
     contain a list of alternative include pathnames separated by ";".
     The environment variable `CHICKEN_HOME' is also considered as a
     search path.

`-keyword-style STYLE'
     Enables alternative keyword syntax, where `STYLE' may be either
     `prefix' (as in Common Lisp) or `suffix' (as in DSSSL).  Any other
     value is ignored.

`-no-feature SYMBOL'
     Unregisters feature identifier `SYMBOL'.

`-no-init'
     Do not load initialization-file. If this option is not given and
     the file `~/.csirc' exists, then it is loaded before the
     read-eval-print loop commences.

`-no-warnings'
     Disables any warnings that might be issued by the reader or
     evaluated code.

`-quiet'
     Do not print a startup message.

`-r5rs'
     Equivalent to `-hygienic -strict'.

`-script PATHNAME'
     This is equivalent to `-batch -quiet -no-init PATHNAME'. Arguments
     following `PATHNAME' are available by using
     `command-line-arguments' and are not processed as interpreter
     options. Extra options in the environment variable `CSI_OPTIONS'
     are ignored.

`-script-meta PATHNAME'
     This is similar to the `-script' option, but the file specified by
     `PATHNAME' is opened, the first line is treated as containing
     additional command line options and (after processing all the
     options) the code from the given file is loaded.

`-strict'
     Disable non-standard macros. Implies `-strict-letrec' and
     `-strict-reader'.

`-strict-srfi-0'
     Disable non-standard macros except `cond-expand'. Implies
     `-strict-letrec' and `-strict-reader'.

`-strict-reader'
     Disables non-standard read syntax. Implies `-case-insensitive'.

`-strict-letrec'
     Enable fully R5RS compliant `letrec'. This generates slightly less
     efficient code but preserves standard semantics.

`-version'
     Write the banner with version information to standard output and
     exit.



File: chicken.info,  Node: Writing Scheme scripts,  Next: Toplevel commands,  Prev: Interpreter command line format,  Up: Using the interpreter

4.2 Writing Scheme scripts
==========================

   * Since UNIX shells use the `#!' notation for starting scripts,
     anything following the characters `#!' is ignored, with the
     exception of the special symbols `#!optional, #!key, #!rest' and
     `#!eof'.

     The easiest way is to use the `-script' option like this:


     % cat foo
     #! /usr/local/bin/csi -script
     (print (eval (with-input-from-string
                     (car (command-line-arguments))
                      read)))

     % chmod +x foo
     % foo "(+ 3 4)"
     7

     The parameter `command-line-arguments' is set to a list of the
     parameters that were passed to the Scheme script.  Scripts can be
     compiled to standalone executables (don't forget to declare used
     library units).  Note that the compiler does not parse the extra
     arguments passed to a script via the `-script-meta' option!

     To overcome a limitation of UNIX that allows only a single
     argument to scripts, the `-script-meta' options is provided:


     % cat foo
     #! /usr/local/bin/csi -script-meta
     -case-insensitive
     (print (with-input-from-string (car (command-line-arguments)) read))

     % chmod +x foo
     % foo "FooBar"
     "foobar"

   * Windows and DOS:

     CHICKEN supports writing shell scripts in Scheme for these
     platforms as well, using a slightly different approach. The first
     example would look like this on Windows:


     C:>type foo.bat
     @;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
     (print (eval (with-input-from-string
                     (car (command-line-arguments))
                     read)))

     C:>foo "(+ 3 4)"
     7

     Like UNIX scripts, batch files can be compiled. Windows batch
     scripts do not accept more than 8 arguments.



File: chicken.info,  Node: Toplevel commands,  Next: Macros and procedures implemented in the interpreter,  Prev: Writing Scheme scripts,  Up: Using the interpreter

4.3 Toplevel commands
=====================

The toplevel loop understands a number of special commands:

`,?'
     Show summary of available toplevel commands.

`,l FILENAME'
     Load file with given `FILENAME' (may be a symbol or string).

`,ln FILENAME'
     Load file and print result(s) of each top-level expression.

`,p EXP'
     Pretty-print evaluated expression `EXP'.

`,d EXP'
     Describe result of evaluated expression `EXP'.

`,du EXP'
     Dump contents of the result of evaluated expression `EXP'.

`,dur EXP N'
     Dump `N' bytes of the result of evaluated expression `EXP'.

`,q'
     Quit the interpreter.

`,r'
     Show system information.

`,s STRING-OR-SYMBOL'
     Execute shell-command.

`,t EXP'
     Evaluate form and print elapsed time.

`,x EXP'
     Pretty-print macroexpanded expression `EXP' (the expression is not
     evaluated).



File: chicken.info,  Node: Macros and procedures implemented in the interpreter,  Prev: Toplevel commands,  Up: Using the interpreter

4.4 Macros and procedures implemented in the interpreter
========================================================

Additional macros and procedures available in the interpreter are:

 -- syntax: advise
          (advise NAME MODE PROC)
     Modifies the behavior of the procedures named `NAME', according to
     `MODE':

    `before'
          Call the procedure `PROC' before every invocation of `NAME',
          with the same arguments.

    `after'
          Call the procedure `PROC' with the result value(s) of `NAME'.

    `around'
          Call the procedure `PROC' with the arguments passed to
          `NAME'.  Additionally the (original) value of `NAME' is
          passed as the first argument to `PROC'.


     Only the `PROC' argument is evaluated. Note that multiple pieces
     of advice on the same procedure are allowed.


     #;1> (define (fac n)
            (if (zero? n) 1 (* n (fac (sub1 n)))))
     #;2> (define count 0)
     #;3> (advise fac before (lambda _ (set! count (add1 count))))
     #;4> (fac 10)                           ==> 3628800
     #;5> count                              ==> 11
     #;6> (advise fac around
            (let ((i 0))
              (define (indent)
                (do ((i i (sub1 i)))
                    ((zero? i))
                  (write-char #\space)))
            (lambda (f n)
              (indent)
              (print "fac: " n)
              (set! i (add1 i))
              (let ((x (f n)))
                (set! i (sub1 i))
                (indent)
                (print "-> " x)
                x))))
     #;7> (fac 3)
     fac: 3
      fac: 2
       fac: 1
        fac: 0
        -> 1
       -> 1
      -> 2
     -> 6                                   ==> 6
     #;8> count                              ==> 15
     #;9> (set! count 0)
     #;10> (unadvise fac)
     #;11> (fac 10)                           ==> 3628800
     #;12> count                              ==> 0


 -- syntax: unadvise
          (unadvise NAME ...)
     Removes all pieces of advice from the procedures `NAME ...' and
     restores their original behavior.


 -- syntax: trace
          (trace NAME ...)
     Switches tracing on for the procedures with the given names.


     #;1> (fac 10)                       ==> 3628800
     #;2> (trace fac)
     #;3> (fac 3)
     |(fac 3)
     | (fac 2)
     |  (fac 1)
     |   (fac 0)
     |   fac -> 1
     |  fac -> 1
     | fac -> 2
     |fac -> 6                          ==> 6
     #;4> (untrace fac)
     #;5> (fac 3)                        ==> 6


 -- syntax: untrace
          (untrace NAME ...)
     Switches tracing of the given procedures off.

 -- read syntax: #[INDEX]
          #
          #INDEX
     Returns the result of entry number `INDEX' in the history list. If
     the expression for that entry resulted in multiple values, the
     first result (or an unspecified value for no values) is returned.
     If no `INDEX' is given (and if a whitespace or closing paranthesis
     character follows the `#', then the result of the last expression
     is returned.  Note that this facility is a reader macro and is
     implicitly quoted.


File: chicken.info,  Node: Supported language,  Next: Interface to external functions and variables,  Prev: Using the interpreter,  Up: Top

5 Supported language
********************

* Menu:

* Deviations from the standard::
* Extensions to the standard::
* Non standard read syntax::
* Non-standard macros and special forms::
* Declarations::
* Parameters::
* Unit library::
* Unit eval::
* Unit extras::
* Unit srfi-1::
* Unit srfi-4::
* Unit srfi-13::
* Unit srfi-14::
* Unit srfi-25::
* Unit match::
* Unit regex::
* Unit syntax-case::
* Unit srfi-18::
* Unit format::
* Unit posix::
* Unit utils::
* Unit tcp::
* Unit srfi-37::
* Unit lolevel::
* Unit tinyclos::


File: chicken.info,  Node: Deviations from the standard,  Next: Extensions to the standard,  Up: Supported language

5.1 Deviations from the standard
================================

[2] Identifiers are by default case-sensitive.

   [4.1.4] Extended DSSSL style lambda lists are supported. DSSSL
formal argument lists are defined by the following grammar:


<formal-argument-list> ==> <required-formal-argument>*
                           [(#!optional <optional-formal-argument>*)]
                           [(#!rest <rest-formal-argument>)]
                           [(#!key <key-formal-argument>*)]
<required-formal-argument> ==> <ident>
<optional-formal-argument> ==> <ident>
                             | (<ident> <initializer>)
<rest-formal-argument> ==> <ident>
<key-formal-argument> ==> <ident>
                          | (<ident> <initializer>)
<initializer> ==> <expr>

   When a procedure is applied to a list of actual arguments, the
formal and actual arguments are processed from left to right as follows:

  1. 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.

  2. 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 `#f'. The initializer is evaluated in
     an environment in which all previous formal arguments have been
     bound.

  3. 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.

  4. If `#!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 `#f'. The initializer is evaluated in an environment in
     which all previous formal arguments have been bound.

   It shall be an error for an `<ident>' to appear more than once in a
formal-argument-list.

   Example:


((lambda x x) 3 4 5 6)       => (3 4 5 6)
((lambda (x y #!rest z) z)
 3 4 5 6)                    => (5 6)
((lambda (x y #!optional z #!rest r #!key i (j 1))
    (list x y z i: i j: j))
 3 4 5 i: 6 i: 7)            => (3 4 5 i: 6 j: 1)

   [4.1.6] `set!' for unbound toplevel variables is allowed.

   [5.2] `define' with a single argument is allowed and initializes the
toplevel or local binding to an unspecified value. CHICKEN supports
"curried" definitions, where the the variable name may also be a list
specifying a name and a nested lambda list. So

     (define ((make-adder x) y) (+ x y))

   is equivalent to

     (define (make-adder x) (lambda (y) (+ x y)))

   [6.2.4]  The runtime system uses the numerical string-conversion
routines of the underlying C library and so does only understand
standard (C-library) syntax for floating-point constants.

   [6.2.5]  The routines `complex?', `real?' and `rational?' are
identical to the standard procedure `number?'. The procedures
`numerator', `denominator' and `rationalize' are not implemented.  Also
not implemented are all procedures related to complex numbers.

   [6.2.6] The procedure `string->number' does not obey read/write
invariance on inexact numbers.

   [6.5] Code evaluated in `scheme-report-environment' or
`null-environment' still sees non-standard syntax unless running under
the interpreter (`csi') invoked with the `-strict' option.

   [6.6.2] The procedure `char-ready?' is handling terminal input ports
only under DJGPP correctly. On other platforms it returns always `#t'.
The procedure `read' does not obey read/write invariance on inexact
numbers.

   [6.6.3] The procedures `write' and `display' do not obey read/write
invariance to inexact numbers.


File: chicken.info,  Node: Extensions to the standard,  Next: Non standard read syntax,  Prev: Deviations from the standard,  Up: Supported language

5.2 Extensions to the standard
==============================

[2.1] Identifiers may contain special characters if delimited with `|
... |'.

   [2.3] The brackets `[ ... ]' are provided as an alternative syntax
for `( ... )'.  A number of reader extensions is provided. See *Note
Non standard read syntax::.

   [4] Numerous non-standard macros are provided. See *Note
Non-standard macros and special forms:: for more information.

   [4.2.2] It is allowed for initialization values of bindings in a
`letrec' construct to refer to previous variables in the same set of
bindings, so


(letrec ([foo 123]
         [bar foo] )
  bar)

   is allowed and returns `123'. This extension is not available when
strict R5RS `letrec' semantics have been selected (by using the
`-strict', `-strict-srfi-0' or `-strict-letrec' option).

   [4.2.3] `(begin)' is allowed in non-toplevel contexts and evaluates
to an unspecified value.

   [4.2.5] Delayed expressions may return multiple values.

   [5.2.2] CHICKEN extends standard semantics by allowing internal
definitions everywhere, and not only at the beginning of a body. A set
of internal definitions is equivalent to a `letrec' form enclosing all
following expressions in the body:


(let ([foo 123])
  (bar)
  (define foo 456)
  (baz foo) )

   expands into


(let ([foo 123])
  (bar)
  (letrec ([foo 456])
    (baz foo) ) )

   This extension to the standard semantics is not available in
combination with the hygienic (`syntax-case') macro system. Under the
hygienic macro system an error will be signalled when internal
definitions occur at a position that is not at the beginning of a body.

   [6] CHICKEN provides numerous non-standard procedures. See the manual
sections on library units for more information.

   [6.3.4] User defined character names are supported. See `char-name'
in *Note User-defined named characters::. Characters can be given in
hexadecimal notation using the "#\xXX" syntax where "XX" specifies the
character code. Character codes above 255 are supported and can be read
(and are written) using the "#\uXXXX" notation.

   [6.3.5]  CHICKEN supports special characters preceded with a
backslash "\" in quoted string constants. "\n" denotes the
newline-character, "\r" carriage return, "\b" backspace, "\t" TAB and
"\xXX" a character with the code `XX' in hex.

   The third argument to `substring' is optional and defaults to the
length of the string.

   [6.4] `force' called with an argument that is not a promise returns
that object unchanged.  Captured continuations can be safely invoked
inside before- and after-thunks of a `dynamic-wind' form and execute in
the outer dynamic context of the `dynamic-wind' form.

   [6.5] The second argument to `eval' is optional and defaults to the
value of `(interaction-environment)'.  `scheme-report-environment' and
`null-environment' accept an optional 2nd parameter: if not `#f' (which
is the default), toplevel bindings to standard procedures are mutable
and new toplevel bindings may be introduced.

   [6.6.1] if the procedures `current-input-port' and
`current-output-port' are called with an argument (which should be a
port), then that argument is selected as the new current input- and
output-port, respectively.  The procedures `open-input-file',
`open-output-file', `with-input-from-file', `with-output-to-file',
`call-with-input-file' and `call-with-output-file' accept an optional
second (or third) argument which should be one or more keywords, if
supplied. These arguments specify the mode in which the file is opened.
Possible values are the keywords `#:text', `#:binary' or `#:append'.


File: chicken.info,  Node: Non standard read syntax,  Next: Non-standard macros and special forms,  Prev: Extensions to the standard,  Up: Supported language

5.3 Non standard read syntax
============================

 -- read syntax: #| ... |#
     A multiline "block" comment. May be nested. Implements SRFI-30
     (http://srfi.schemers.org/srfi-30/srfi-30.html))

 -- read syntax: #;EXPRESSION
     Treats `EXPRESSION' as a comment.

 -- read syntax: #,(CONSTRUCTORNAME DATUM ...)
     Allows user-defined extension of external representations.  (For
     more information see the documentation for SRFI-10
     (http://srfi.schemers.org/srfi-10/srfi-10.html))

 -- read syntax: #'EXPRESSION
     An abbreviation for `(syntax EXPRESSION)'.

 -- read syntax: #$EXPRESSION
     An abbreviation for `(location EXPRESSION)'.

 -- read syntax: #:SYMBOL
     Syntax for keywords. Keywords are symbols that evaluate to
     themselves, and as such don't have to be quoted.

 -- read syntax: #<<TAG
     Specifies a multiline string constant. Anything up to a line equal
     to `TAG' will be returned as a single string:


     (define msg #<<END
     "Hello, world!", she said.
     END
     )

     is equivalent to


     (define msg "\"Hello, world!\", she said.")

 -- read syntax: #<#TAG
     Similar to `#<<', but allows substitution of embedded Scheme
     expressions prefixed with `#' and optionally enclosed in `{ ...
     }'.  Two consecutive `#'s are translated to a single `#':


     (define three 3)
     (display #<#EOF
     This is a simple string with an embedded `##' character
     and substituted expressions: (+ three 99) ==> #(+ three 99)
     (three is "#{three}")
     EOF
     )

     prints


     This is a simple string with an embedded `#' character
     and substituted expressions: (+ three 99) ==> 102
     (three is "3")

 -- read syntax: #> ... <#
     Abbreviation for `(declare (foreign-declare " ... "))'.

 -- read syntax: #>? ... <#
     Abbreviation for `(declare (foreign-parse " ... "))'.

 -- read syntax: #>! ... <#
     Abbreviation for


     (declare
       (foreign-declare " ... ")
       (foreign-parse " ... ") )

 -- read syntax: #>$ ... <#
     An abbreviation for


     (foreign-parse " ... ")

 -- read syntax: #>% ... <#
     An abbreviation for


     (foreign-parse/spec " ... ")

 -- read syntax: #%...
     Reads like a normal symbol.

 -- read syntax: #!...
     Treated as a commment and ignores everything up the end of the
     current line.  The keywords `#!optional, #!rest' and `#!key' are
     handled separately and returned as normal symbols.  The special
     (self-evaluating) symbol `#!eof' is read as the end-of-file object.


File: chicken.info,  Node: Non-standard macros and special forms,  Next: Declarations,  Prev: Non standard read syntax,  Up: Supported language

5.4 Non-standard macros and special forms
=========================================

* Menu:

* Making extra libraries and extensions available::
* Binding forms for optional arguments::
* Other binding forms::
* Substitution forms and macros::
* Conditional forms::
* Record structures::
* Other forms::


File: chicken.info,  Node: Making extra libraries and extensions available,  Next: Binding forms for optional arguments,  Up: Non-standard macros and special forms

5.4.1 Making extra libraries and extensions available
-----------------------------------------------------

 -- syntax: require-extension
 -- syntax: use
          (require-extension ID ...)
          (use ID ...)
     This form does all necessary steps to make the libraries or
     extensions given in `ID ...' available. It loads syntactic
     extension, if needed and generates code for loading/linking with
     core library modules or separately installed extensions. `use' is
     just a shorter alias for `require-extension'.  This implementation
     of `require-extension' is compliant to SRFI-55 (see SRFI-55
     (http://srfi.schemers.org/srfi-16/srfi-16.html) for more
     information).

     During interpretation/evaluation `require-extension' performs one
     of the following:

        * If `ID' names a built in features `chicken srfi-23 srfi-30
          srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10 srfi-9', then
          nothing is done.

        * If `ID' names one of syntactic extensions
          `chicken-match-macros chicken-more-macros
          chicken-default-entry-points  chicken-highlevel-macros
          test-infrastructure chicken-entry-points chicken-ffi-macros',
          then this extension will be loaded.

        * If `ID' names one of the core library units shipped with
          CHICKEN, then a `(load-library 'ID)' will be performed.  If
          one of those libraries define specific syntax (`match
          srfi-13'), then the required source file defining the syntax
          will be loaded.

        * If `ID' names an installed extension with the `syntax' or
          `require-at-runtime' attribute, then the equivalent of
          `(require-for-syntax 'ID)' is performed.

        * Otherwise `(require-extension ID)' is equivalent to `(require
          'ID)'.

     During compilation one of the following happens instead:

        * If `ID' names a built in features `chicken srfi-23 srfi-30
          srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10  srfi-9', then
          nothing is done.

        * If `ID' names one of syntactic extensions
          `chicken-match-macros chicken-more-macros
          chicken-default-entry-points  chicken-highlevel-macros
          test-infrastructure chicken-entry-points chicken-ffi-macros',
          then this extension will be loaded  at compile-time, making
          the syntactic extensions available in compiled code.

        * If `ID' names one of the core library units shipped with
          CHICKEN, then a `(declare (uses ID))' is generated.   If one
          of those libraries define specific syntax (`match srfi-13'),
          then the required source file defining the syntax  will be
          loaded at compile-time, making the syntactic extension
          available in compiled code.

        * If `ID' names an installed extension with the `syntax' or
          `require-at-runtime' attribute, then  the equivalent of
          `(require-for-syntax 'ID)' is performed.

        * Otherwise `(require-extension ID)' is equivalent to `(require
          'ID)'.

     To make long matters short - just use `require-extension' and it
     will normally figure everything out for dynamically loadable
     extensions and core library units.

     See also: `set-extension-specifier!'



File: chicken.info,  Node: Binding forms for optional arguments,  Next: Other binding forms,  Prev: Making extra libraries and extensions available,  Up: Non-standard macros and special forms

5.4.2 Binding forms for optional arguments
------------------------------------------

 -- syntax: :optional
          (:optional ARGS DEFAULT)
     Use this form for procedures that take a single optional argument.
     If `ARGS' is the empty list `DEFAULT' is evaluated and returned,
     otherwise the first element of the list `ARGS'. It is an error if
     `ARGS' contains more than one value.


     (define (incr x . i) (+ x (:optional i 1)))
     (incr 10)                                   ==> 11
     (incr 12 5)                                 ==> 17


 -- syntax: case-lambda
          (case-lambda (LAMBDA-LIST1 EXP1 ...) ...)
     SRFI-16. Expands into a lambda that invokes the body following the
     first matching lambda-list.


     (define plus
       (case-lambda
         (() 0)
         ((x) x)
         ((x y) (+ x y))
         ((x y z) (+ (+ x y) z))
         (args (apply + args))))

     (plus)                      ==> 9
     (plus 1)                    ==> 1
     (plus 1 2 3)                ==> 6

     For more information see the documentation for SRFI-16
     (http://srfi.schemers.org/srfi-16/srfi-16.html)


 -- syntax: let-optionals
 -- syntax: let-optionals*
          (let-optionals ARGS ((VAR1 DEFAULT1) ...) BODY ...)
          (let-optionals* ARGS ((VAR1 DEFAULT1) ... [RESTVAR]) BODY ...)
     Binding constructs for optional procedure arguments. `ARGS' should
     be a rest-parameter taken from a lambda-list. `let-optionals'
     binds `VAR1 ...' to available arguments in parallel, or to
     `DEFAULT1 ...' if not enough arguments were provided.
     `let-optionals*' binds `VAR1 ...' sequentially, so every variable
     sees the previous ones. If a single variable `RESTVAR' is given,
     then it is bound to any remaining arguments, otherwise it is an
     error if any excess arguments are provided.


     (let-optionals '(one two) ((a 1) (b 2) (c 3))
       (list a b c) )                               ==> (one two 3)
     (let-optionals* '(one two) ((a 1) (b 2) (c a))
       (list a b c) )                               ==> (one two one)


File: chicken.info,  Node: Other binding forms,  Next: Substitution forms and macros,  Prev: Binding forms for optional arguments,  Up: Non-standard macros and special forms

5.4.3 Other binding forms
-------------------------

 -- syntax: and-let*
          (and-let* (BINDING ...) EXP1 EXP2 ...)
     SRFI-2. Bind sequentially and execute body. `BINDING' can be a
     list of a variable and an expression, a list with a single
     expression, or a single variable. If the value of an expression
     bound to a variable is `#f', the `and-let*' form evaluates to `#f'
     (and the subsequent bindings and the body are not executed).
     Otherwise the next binding is performed. If all
     bindings/expressions evaluate to a true result, the body is
     executed normally and the result of the last expression is the
     result of the `and-let*' form. See also the documentation for
     SRFI-2 (http://srfi.schemers.org/srfi-2/srfi-2.html).


 -- syntax: cut
 -- syntax: cute
          (cut SLOT ...)
          (cute SLOT ...)
     Syntactic sugar for specializing parameters.
     (http://srfi.schemers.org/srfi-26/srfi-26.html)


 -- syntax: define-values
          (define-values (NAME ...) EXP)
     Defines several variables at once, with the result values of
     expression `EXP'.


 -- syntax: fluid-let
          (fluid-let ((VAR1 X1) ...) BODY ...)
     Binds the variables `VAR1 ...' dynamically to the values `X1 ...'
     during execution of `BODY ...'.


 -- syntax: let-values
          (let-values (((NAME ...) EXP) ...) BODY ...)
     Binds multiple variables to the result values of `EXP ...'.  All
     variables are bound simultaneously.


 -- syntax: let*-values
          (let*-values (((NAME ...) EXP) ...) BODY ...)
     Binds multiple variables to the result values of `EXP ...'.  The
     variables are bound sequentially.
     (let*-values (((a b) (values 2 3))
                   ((p) (+ a b)) )
       p)                               ==> 5


 -- syntax: letrec-values
          (letrec-values (((NAME ...) EXP) ...) BODY ...)
     Binds the result values of `EXP ...' to multiple variables at once.
     All variables are mutually recursive.
     (letrec-values (((odd even)
                        (values
                          (lambda (n) (if (zero? n) #f (even (sub1 n))))
                          (lambda (n) (if (zero? n) #t (odd (sub1 n)))) ) ) )
       (odd 17) )                           ==> #t


 -- syntax: parameterize
          (parameterize ((PARAMETER1 X1) ...) BODY ...)
     Binds the parameters `PARAMETER1 ...' dynamically to the values
     `X1 ...' during execution of `BODY ...'.  (see also:
     `make-parameter' in *Note Parameters::). Note that `PARAMETER' may
     be any expression that evaluates to a parameter procedure.


 -- syntax: receive
          (receive (NAME1 ... [. NAMEn]) VALUEEXP BODY ...)
          (receive VALUEEXP)
     SRFI-8. Syntactic sugar for `call-with-values'. Binds variables to
     the result values of `VALUEEXP' and evaluates `BODY ...'.

     The syntax


     (receive VALUEEXP)

     is equivalent to


     (receive _ VALUEEXP _)


 -- syntax: set!-values
          (set!-values (NAME ...) EXP)
     Assigns the result values of expression `EXP' to multiple
     variables.


File: chicken.info,  Node: Substitution forms and macros,  Next: Conditional forms,  Prev: Other binding forms,  Up: Non-standard macros and special forms

5.4.4 Substitution forms and macros
-----------------------------------

 -- syntax: define-constant
          (define-constant NAME CONST)
     Define a variable with a constant value, evaluated at compile-time.
     Any reference to such a constant should appear textually after its
     definition. This construct is equivalent to `define' when
     evaluated or interpreted.  Constant definitions should only appear
     at toplevel. Note that constants are local to the current
     compilation unit and are not available outside of the source file
     in which they are defined. Names of constants still exist in the
     Scheme namespace and can be lexically shadowed.  If the value is
     mutable, then the compiler is careful to preserve its identity.
     `CONST' may be any constant expression, and may also refer to
     constants defined via `define-constant' previously.  This for
     should only be used at top-level.


 -- syntax: define-inline
          (define-inline (NAME VAR ... [. VAR]) BODY ...)
          (define-inline NAME EXP)
     Defines an inline procedure. Any occurrence of `NAME' will be
     replaced by `EXP' or `(lambda (VAR ... [. VAR]) BODY ...)'.  This
     is similar to a macro, but variable-names and -scope will be
     correctly handled.  Inline substitutions take place after
     macro-expansion.  `EXP' should be a lambda-expression. Any
     reference to `NAME' should appear textually after its definition.
     Note that inline procedures are local to the current compilation
     unit and are not available outside of the source file in which
     they are defined. Names of inline procedures still exist in the
     Scheme namespace and can be lexically shadowed.  This construct is
     equivalent to `define' when evaluated or interpreted. Inline
     definitions should only appear at toplevel.


 -- syntax: define-macro
          (define-macro (NAME VAR ... [. VAR]) EXP1 ...)
          (define-macro NAME (lambda (VAR ... [. VAR]) EXP1 ...))
          (define-macro NAME1 NAME2)
     Define a globally visible macro special form. The macro is
     available as soon as it is defined, i.e. it is registered at
     compile-time. If the file containing this definition invokes
     `eval' and the declaration `run-time-macros' (or the command line
     option `-run-time-macros') has been used, then the macro is
     visible in evaluated expressions during runtime. The second
     possible syntax for `define-macro' is allowed for portability
     purposes only. In this case the second argument must be a
     lambda-expression or a macro name.  Only global macros can be
     defined using this form.  `(define-macro NAME1 NAME2)' simply
     copies the macro definition from `NAME2' to `NAME1', creating an
     alias.

     This form is also available with the `syntax-case' macro system.


File: chicken.info,  Node: Conditional forms,  Next: Record structures,  Prev: Substitution forms and macros,  Up: Non-standard macros and special forms

5.4.5 Conditional forms
-----------------------

 -- syntax: switch
          (switch EXP (KEY EXP1 ...) ... [(else EXPn ...)])
     This is similar to `case', but a) only a single key is allowed,
     and b) the key is evaluated.


 -- syntax: unless
          (unless TEST EXP1 EXP2 ...)
     Equivalent to:
     (if (not TEST) (begin EXP1 EXP2 ...))


 -- syntax: when
          (when TEST EXP1 EXP2 ...)
     Equivalent to:
     (if TEST (begin EXP1 EXP2 ...))


File: chicken.info,  Node: Record structures,  Next: Other forms,  Prev: Conditional forms,  Up: Non-standard macros and special forms

5.4.6 Record structures
-----------------------

 -- syntax: define-record
          (define-record NAME SLOTNAME ...)
     Defines a record type. Call `make-NAME' to create an instance of
     the structure (with one initialization-argument for each slot).
     `(NAME? STRUCT)' tests any object for being an instance of this
     structure.  Slots are accessed via `(NAME-SLOTNAME STRUCT)' and
     updated using `(NAME-SLOTNAME-set!' `STRUCT' `VALUE)'.


     (define-record point x y)
     (define p1 (make-point 123 456))
     (point? p1)                      ==> #t
     (point-x p1)                     ==> 123
     (point-y-set! p1 99)
     (point-y p1)                     ==> 99


 -- syntax: define-record-printer
          (define-record-printer (NAME RECORDVAR PORTVAR) BODY ...)
          (define-record-printer NAME PROCEDURE)
     Defines a printing method for record of the type `NAME' by
     associating a procedure with the record type. When a record of this
     type is written using `display, write' or `print', then the
     procedure is called with two arguments: the record to be printed
     and an output-port.


     (define-record foo x y z)
     (define f (make-foo 1 2 3))
     (define-record-printer (foo x out)
       (fprintf out "#,(foo ~S ~S ~S)"
                (foo-x x) (foo-y x) (foo-z x)) )
     (define-reader-ctor 'foo make-foo)
     (define s (with-output-to-string
                   (lambda () (write f))))
     s                                   ==> "#,(foo 1 2 3)"
     (equal? f (with-input-from-string
                   s read)))             ==> #t

     `define-record-printer' works also with SRFI-9 record types.


 -- syntax: define-record-type
          (define-record-type NAME (CONSTRUCTOR TAG ...) PREDICATE
                              (FIELD ACCESSOR [MODIFIER]) ...)
     SRFI-9 record types. For more information see the documentation for
     SRFI-9 (http://srfi.schemers.org/srfi-9/srfi-9.html)


File: chicken.info,  Node: Other forms,  Prev: Record structures,  Up: Non-standard macros and special forms

5.4.7 Other forms
-----------------

 -- syntax: assert
          (assert EXP [STRING ARG ...])
     Signal error if `EXP' evaluates to false. An optional message
     `STRING' and arguments `ARG ...' may be supplied to give a more
     informative error-message.  If compiled in _unsafe_ mode (either
     by specifying the `-unsafe' compiler option or by declaring
     `(unsafe)'), then this expression expands to an unspecified value.


 -- syntax: cond-expand
          (cond-expand FEATURE-CLAUSE ...)
     SRFI-0. Expands by selecting feature clauses. Predefined
     feature-identifiers are `srfi-0', `srfi-2', `srfi-6', `srfi-8',
     `srfi-9', `srfi-10',  and `chicken'. In `strict-srfi-0' mode only
     `srfi-0' and `chicken' are defined.  If the source file containing
     this form is currently compiled, the feature `compiling' is
     defined.  For further information, see the documentation for
     SRFI-0 (http://srfi.schemers.org/srfi-0/srfi-0.html) This form is
     allowed to appear in non-toplevel expressions.


 -- syntax: critical-section
          (critical-section BODY ...)
     Evaluate `BODY ...' with timer-interrupts temporarily disabled.


 -- syntax: ensure
          (ensure PREDICATE EXP [ARGUMENTS ...])
     Evaluates the expression `EXP' and applies the one-argument
     procedure `PREDICATE' to the result. If the predicate returns `#f'
     an error is signaled, otherwise the result of `EXP' is returned.
     If compiled in _unsafe_ mode (either by specifying the `-unsafe'
     compiler option or by declaring `(unsafe)'), then this expression
     expands to an unspecified value.  If specified, the optional
     `ARGUMENTS' are used as arguments to the invocation of the
     error-signalling code, as in `(error ARGUMENTS ...)'. If no
     `ARGUMENTS' are given, a generic error message is displayed with
     the offending value and `PREDICATE' expression.


 -- syntax: eval-when
          (eval-when (SITUATION ...) EXP ...)
     Controls evaluation/compilation of subforms. `SITUATION' should be
     one of the symbols `eval', `compile' or `load'.  When encountered
     in the evaluator, and the situation specifier `eval' is not given,
     then this form is not evaluated and an unspecified value is
     returned.  When encountered while compiling code, and the
     situation specifier `compile' is given, then this form is
     evaluated at compile-time.  When encountered while compiling code,
     and the situation specifier `load' is not given, then this form is
     ignored and an expression resulting into an unspecified value is
     compiled instead.

     The following table should make this clearer:

               in compiled code           In interpreted code
     `eval'    ignore                     evaluate
     `compile' evaluate at compile time   ignore
     `load'    compile as normal          ignore

     The situation specifiers `compile-time' and `run-time' are also
     defined and have the same meaning as `compile' and `load',
     respectively.

     Note: It is currently not possible to use `define-syntax' or
     `define' inside `eval-when' forms when hygienic macros are enabled.


 -- syntax: include
          (include STRING)
     Include toplevel-expressions from the given source file in the
     currently compiled/interpreted program.  If the included file has
     the extension `.scm', then it may be omitted.  The file is
     searched in the current directory and, if not found, in all
     directories specified in the `-include-path' option.


 -- syntax: nth-value
          (nth-value N EXP)
     Returns the `N'th value (counting from zero) of the values returned
     by expression `EXP'.


 -- syntax: time
          (time EXP1 ...)
     Evaluates `EXP1 ...' and print elapsed time and memory
     information. The result of the last expression is returned.


File: chicken.info,  Node: Declarations,  Next: Parameters,  Prev: Non-standard macros and special forms,  Up: Supported language

5.5 Declarations
================

 -- syntax: declare
          (declare DECLSPEC ...)
     Process declaration specifiers. Declarations always override any
     command-line settings.  Declarations are valid for the whole
     compilation-unit (source file), the position of the declaration in
     the source file can be arbitrary. Declarations are ignored in the
     interpreter but not in code evaluated at compile-time (by
     `eval-when' or in syntax extensions loaded via `require-extension'
     or `require-for-syntax'.  `DECLSPEC' may be any of the following:

      -- declaration specifier: always-bound
               (always-bound SYMBOL ...)
          Declares that the given variables are always bound and
          accesses to those have not to be checked.

      -- declaration specifier: block
               (block)
          Assume global variables are never redefined. This is the same
          as specifying the `-block' option.

      -- declaration specifier: block-global
      -- declaration specifier: hide
               (block-global SYMBOL ...)
               (hide SYMBOL ...)
          Declares that the toplevel bindings for `SYMBOL ...' should
          not be accessible from code in other compilation units or by
          `eval'. Access to toplevel bindings declared as block global
          is also more efficient.

      -- declaration specifier: bound-to-procedure
               (bound-to-procedure SYMBOL ...)
          Declares that the given identifiers are always bound to
          procedure values.

      -- declaration specifier: c-options
               (c-options STRING ...)
          Declares additional C/C++ compiler options that are to be
          passed to the subsequent compilation pass that translates C
          to machine code. This declaration will only work if the
          source file is compiled with the `csc' compiler driver.

      -- declaration specifier: compress-literals
               (compress-literals [THRESHOLD [INITIALIZER]])
          The same as the `-compress-literals' compiler option.  The
          threshold argument defaults to 50. If the optional argument
          `INITIALIZER' is given, then the literals will not be created
          at module startup, but when the procedure with this name will
          be called.

      -- declaration specifier: export
               (export SYMBOL ...)
          The opposite of `hide'. All given identifiers will be
          exported and all toplevel variables not listed will be hidden
          and not be accessible outside of this compilation unit.  When
          the hygienic (`syntax-case') macro system is used, the
          exported identifier may also have the form `(MODULE-NAME
          SYMBOL ...)', which specifies identifiers to be exported from
          a module as (undecorated) toplevel variables.

      -- declaration specifier: foreign-declare
               (foreign-declare STRING ...)
          Include given strings verbatim into header of generated file.

      -- declaration specifier: foreign-parse
               (foreign-parse STRING ...)
          Parse given strings and generate foreign-interface bindings.
          See *Note The Easy Foreign Function Interface:: for more
          information.

      -- declaration specifier: interrupts-enabled
               (interrupts-enabled)
          Enable timer-interrupts checks in the compiled program (the
          default).

      -- declaration specifier: disable-interrupts
      -- declaration specifier: not
               (disable-interrupts)
               (not interrupts-enabled)
          Disable timer-interrupts checks in the compiled program.
          Threads can not be preempted in main- or library-units that
          contain this declaration.

      -- declaration specifier: link-options
               (link-options STRING ...)
          Declares additional linker compiler options that are to be
          passed to the subsequent compilation pass that links the
          generated code into an executable or library.  This
          declaration will only work if the source file is compiled
          with the `csc' compiler driver.

      -- declaration specifier: no-argc-checks
               (no-argc-checks)
          Disables argument count checking.

      -- declaration specifier: no-bound-checks
               (no-bound-checks)
          Disables the bound-checking of toplevel bindings.

      -- declaration specifier: no-procedure-checks
               (no-procedure-checks)
          Disables checking of values in operator position for being of
          procedure type.

      -- declaration specifier: post-process
               (post-process STRING ...)
          Arranges for the shell commands `STRING ...' to be invoked
          after the current file has been translated to C. Any
          occurrences of the substring `$@' in the strings given for
          this declaration will be replaced by the pathname of the
          currently compiled file, without the file-extension.  This
          declaration will only work if the source file is compiled
          with the `csc' compiler driver.

      -- declaration specifier: TYPE
      -- declaration specifier: fixnum-arithmetic
               ([number-type] TYPE)
               (fixnum-arithmetic)
          Declares that only numbers of the given type are used. `TYPE'
          may be `fixnum' or `generic' (which is the default).

      -- declaration specifier: run-time-macros
               (run-time-macros)
          Equivalent to the compiler option of the same name - low-level
          macros defined in the compiled code are also made available at
          runtime.

      -- declaration specifier: standard-bindings
               ([not] standard-bindings SYMBOL ...)
          Declares that all given standard procedures (or all if no
          symbols are specified) are never globally redefined.  If
          `not' is specified, then all but the given standard bindings
          are assumed to be never redefined.

      -- declaration specifier: extended-bindings
               ([not] extended-bindings SYMBOL ...)
          Declares that all given non-standard and CHICKEN-specific
          procedures (or all if no symbols are specified) are never
          globally redefined.  If `not' is specified, then all but the
          given extended bindings are assumed to be never redefined.

      -- declaration specifier: usual-integrations
               ([not] usual-integrations SYMBOL ...)
          Declares that all given standard and extended bindings (or
          all if no symbols are specified) are never globally
          redefined.  If `not' is specified, then all but the given
          standard and extended bindings are assumed to be never
          redefined. Note that this is the default behaviour, unless
          the `-no-usual-integrations' option has been given.

      -- declaration specifier: unit
               (unit SYMBOL)
          Specify compilation unit-name (if this is a library)

      -- declaration specifier: unsafe
      -- declaration specifier: not
               (unsafe)
               (not safe)
          Do not generate safety-checks. This is the same as specifying
          the `-unsafe' option.  Also implies


          (declare (no-bound-checks) (no-procedure-checks) (no-argc-checks))

      -- declaration specifier: uses
               (uses SYMBOL ...)
          Gives a list of used library-units. Before the
          toplevel-expressions of the main-module are executed, all
          used units evaluate their toplevel-expressions in the order
          in which they appear in this declaration. If a library unit A
          uses another unit B, then B's toplevel expressions are
          evaluated before A's.  Furthermore, the used symbols are
          registered as features during compile-time, so `cond-expand'
          knows about them.



File: chicken.info,  Node: Parameters,  Next: Unit library,  Prev: Declarations,  Up: Supported language

5.6 Parameters
==============

Certain behavior of the interpreter and compiled programs can be
customized via 'parameters', where a parameter is a procedure of zero
or one arguments. To retrieve the value of a parameter call the
parameter-procedure with zero arguments. To change the setting of the
parameter, call the parameter-procedure with the new value as argument:


(define foo (make-parameter 123))
(foo)                             ==> 123
(foo 99)
(foo)                             ==> 99

   Parameters are fully thread-local, each thread of execution owns a
local copy of a parameters' value.

   CHICKEN implements SRFI-39
(http://srfi.schemers.org/srfi-39/srfi-39.html)

 -- procedure: make-parameter
          (make-parameter VALUE [GUARD])
     Returns a procedure that accepts zero or one argument. Invoking the
     procedure with zero arguments returns `VALUE'. Invoking the
     procedure with one argument changes its value to the value of that
     argument (subsequent invocations with zero parameters return the
     new value). `GUARD' should be a procedure of a single argument. Any
     new values of the parameter (even the initial value) are passed to
     this procedure. The guard procedure should check the value and/or
     convert it to an appropriate form.


 -- parameter: case-sensitive
     If true, then `read' reads symbols and identifiers in
     case-sensitive mode and uppercase characters in symbols are printed
     escaped. Defaults to `#t'.


 -- parameter: dynamic-load-libraries
     A list of strings containing shared libraries that should be
     checked for explicitly loaded library units (this facility is not
     available on all platforms). See `load-library'.


 -- parameter: command-line-arguments
     Contains the list of arguments passed to this program, with the
     name of the program and any runtime options (all options starting
     with `-:') removed.


 -- parameter: exit-handler
     A procedure of a single optional argument. When `exit' is called,
     then this procedure will be invoked with the exit-code as
     argument. The default behavior is to terminate the program.


 -- parameter: eval-handler
     A procedure of one or two arguments. When `eval' is invoked, it
     calls the value of this parameter with the same arguments. The
     default behavior is to evaluate the argument expression and to
     ignore the second parameter.


 -- parameter: force-finalizers
     If true, force and execute all pending finalizers before exiting
     the program (either explicitly by `exit' or implicitly when the
     last toplevel expression has been executed). Default is `#t'.


 -- parameter: implicit-exit-handler
     A procedure of no arguments. When the last toplevel expression of
     the program has executed, then the value of this parameter is
     called. The default behaviour is to do nothing, or, if one or more
     entry-points were defined (see: *Note Entry points::) to enter a
     loop that waits for callbacks from the host program.


 -- parameter: keyword-style
     Enables alternative keyword syntax, where `STYLE' may be either
     `#:prefix' (as in Common Lisp) or `#:suffix' (as in DSSSL).  Any
     other value disables the alternative syntaxes.


 -- parameter: load-verbose
     A boolean indicating whether loading of source files, compiled code
     (if available) and compiled libraries should display a message.


 -- parameter: repl-prompt
     A procedure that should evaluate to a string that will be printed
     before reading interactive input from the user in a
     read-eval-print loop. Defaults to `(lambda () "#;N> ")'.


 -- parameter: reset-handler
     A procedure of zero arguments that is called via `reset'. The
     default behavior in compiled code is to invoke the value of
     `(exit-handler)'. The default behavior in the interpreter is to
     abort the current computation and to restart the read-eval-print
     loop.


 -- parameter: strict-reader
     If true, then most non-standard read syntax is disabled. Defaults
     to `#f'.


File: chicken.info,  Node: Unit library,  Next: Unit eval,  Prev: Parameters,  Up: Supported language

5.7 Unit library
================

This unit contains basic Scheme definitions. This unit is used by
default, unless the program is compiled with the `-explicit-use' option.

* Menu:

* Arithmetic::
* File Input/Output::
* Files::
* String ports::
* Feature identifiers::
* Keywords::
* Exceptions::
* Environment information and system interface::
* Execution time::
* Interrupts and error-handling::
* Garbage collection::
* Other control structures::
* String utilities::
* Generating uninterned symbols::
* Standard Input/Output::
* User-defined named characters::
* Vectors::
* The unspecified value::
* call/cc::


File: chicken.info,  Node: Arithmetic,  Next: File Input/Output,  Up: Unit library

5.7.1 Arithmetic
----------------

 -- procedure: add1
 -- procedure: sub1
          (add1 N)
          (sub1 N)
     Adds/subtracts 1 from `N'.


 -- procedure: bitwise-and
 -- procedure: bitwise-ior
 -- procedure: bitwise-xor
 -- procedure: bitwise-not
 -- procedure: arithmetic-shift
          (bitwise-and N1 ...)
          (bitwise-ior N1 ...)
          (bitwise-xor N1 ...)
          (bitwise-not N)
          (arithmetic-shift N1 N2)
     Binary integer operations. `arithmetic-shift' shifts the argument
     `N1' by `N2' bits to the left. If `N2' is negative, than `N1' is
     shifted to the right.  These operations only accept exact integers
     or inexact integers in word range (32 bit signed on 32-bit
     platforms, or 64 bit signed on 64-bit platforms).


 -- procedure: fixnum?
          (fixnum? X)
     Returns `#t' if `X' is a fixnum, or `#f' otherwise.


 -- procedure: fx+
 -- procedure: fx-
 -- procedure: fx*
 -- procedure: fx/
 -- procedure: fxmod
 -- procedure: fxneg
 -- procedure: fxmin
 -- procedure: fxmax
 -- procedure: fx=
 -- procedure: fx>
 -- procedure: fx<
 -- procedure: fx>=
 -- procedure: fx<=
 -- procedure: fxand
 -- procedure: fxior
 -- procedure: fxxor
 -- procedure: fxnot
 -- procedure: fxshl
 -- procedure: fxshr
          (fx+ N1 N2)
          (fx- N1 N2)
          (fx* N1 N2)
          (fx/ N1 N2)
          (fxmod N1 N2)
          (fxneg N)
          (fxmin N1 N2)
          (fxmax N1 N2)
          (fx= N1 N2)
          (fx> N1 N2)
          (fx< N1 N2)
          (fx>= N1 N2)
          (fx<= N1 N2)
          (fxand N1 N2)
          (fxior N1 N2)
          (fxxor N1 N2)
          (fxnot N)
          (fxshl N1 N2)
          (fxshr N1 N2)
     Arithmetic fixnum operations. These procedures do not check their
     arguments, so non-fixnum parameters will result in incorrect
     results. `fxneg' negates its argument.

     On division by zero, `fx/' and `fxmod' signal a condition of kind
     `(exn arithmetic)'.

     `fxshl' and `fxshr' perform arithmetic shift left and right,
     respectively.


 -- procedure: fp+
 -- procedure: fp-
 -- procedure: fp*
 -- procedure: fp/
 -- procedure: fpneg
 -- procedure: fpmin
 -- procedure: fpmax
 -- procedure: fp=
 -- procedure: fp>
 -- procedure: fp<
 -- procedure: fp>=
 -- procedure: fp<=
          (fp+ N1 N2)
          (fp- N1 N2)
          (fp* N1 N2)
          (fp/ N1 N2)
          (fpneg N)
          (fpmin N1 N2)
          (fpmax N1 N2)
          (fp= N1 N2)
          (fp> N1 N2)
          (fp< N1 N2)
          (fp>= N1 N2)
          (fp<= N1 N2)
     Arithmetic floating-point operations. These procedures do not
     check their arguments, so non-flonum parameters will result in
     incorrect results.  On division by zero, `fp/' signals a condition
     of kind `(exn arithmetic)'.


 -- procedure: signum
          (signum N)
     Returns `1' if `N' is positive, `-1' if `N' is negative or `0' if
     `N' is zero.


File: chicken.info,  Node: File Input/Output,  Next: Files,  Prev: Arithmetic,  Up: Unit library

5.7.2 File Input/Output
-----------------------

 -- procedure: current-error-port
          (current-error-port [PORT])
     Returns default error output port. If `PORT' is given, then that
     port is selected as the new current error output port.


 -- procedure: end-of-file
          (end-of-file)
     Returns the end-of-file object.


 -- procedure: flush-output
          (flush-output [PORT])
     Write buffered output to the given output-port. `PORT' defaults to
     the value of `(current-output-port)'.


 -- procedure: port-name
          (port-name PORT)
     Fetch filename from `PORT'. This returns the filename that was
     used to open this file.  Returns a special tag string, enclosed
     into parentheses for non-file ports.


 -- procedure: port-position
          (port-position PORT)
     Returns the current position of `PORT' as two values: row and
     column number.  If the port does not support such an operation an
     error is signaled. This procedure is currently only available for
     input ports.


 -- procedure: set-port-name!
          (set-port-name! PORT STRING)
     Sets the name of `PORT' to `STRING'.


File: chicken.info,  Node: Files,  Next: String ports,  Prev: File Input/Output,  Up: Unit library

5.7.3 Files
-----------

 -- procedure: delete-file
          (delete-file STRING)
     Deletes the file with the pathname `STRING'. If the file does not
     exist, an error is signaled.


 -- procedure: file-exists?
          (file-exists? STRING)
     Returns `#t' if a file with the given pathname exists, or `#f'
     otherwise.


 -- variable: pathname-directory-separator
     Contains the directory-separator character for pathnames on this
     platform.


 -- variable: pathname-extension-separator
     Contains the extension-separator character for pathnames on this
     platform.


 -- procedure: rename-file
          (rename-file OLD NEW)
     Renames the file or directory with the pathname `OLD' to `NEW'. If
     the operation does not succeed, an error is signaled.


File: chicken.info,  Node: String ports,  Next: Feature identifiers,  Prev: Files,  Up: Unit library

5.7.4 String ports
------------------

 -- procedure: get-output-string
          (get-output-string PORT)
     Returns accumulated output of a port created with
     `(open-output-string)'.


 -- procedure: open-input-string
          (open-input-string STRING)
     Returns a port for reading from `STRING'.


 -- procedure: open-output-string
          (open-output-string)
     Returns a port for accumulating output in a string.


File: chicken.info,  Node: Feature identifiers,  Next: Keywords,  Prev: String ports,  Up: Unit library

5.7.5 Feature identifiers
-------------------------

CHICKEN maintains a global list of "features" naming functionality
available int the current system. Additionally the `cond-expand' form
accesses this feature list to infer what features are provided.
Predefined features are `chicken', and the SRFIs (Scheme Request For
Implementation) provided by the base system: `srfi-23, srfi-30,
srfi-39'. If the `eval' unit is used (the default), the features
`srfi-0, srfi-2, srfi-6, srfi-8, srfi-9' and `srfi-10' are defined.
When compiling code (during compile-time) the feature `compiling' is
registered. When evaluating code in the interpreter (csi), the feature
`csi' is registered. When evaluating or compiling code using the
highlevel (syntax-case) macro system, the feauture `hygienic-macros' is
defined.

 -- procedure: features
          (features)
     Returns a list of all registered features that will be accepted as
     valid feature-identifiers by `cond-expand'.

 -- procedure: test-feature?
          (test-feature? ID ...)
     Returns `#t' if all features with the given feature-identifiers
     `ID ...' are registered.


 -- procedure: register-feature!
          (register-feature! FEATURE ...)
     Register one or more features that will be accepted as valid
     feature-identifiers by `cond-expand'. `FEATURE ...' may be a
     keyword, string or symbol.


 -- procedure: unregister-feature!
          (unregister-feature! FEATURE ...)
     Unregisters the specified feature-identifiers. `FEATURE ...' may
     be a keyword, string or symbol.


File: chicken.info,  Node: Keywords,  Next: Exceptions,  Prev: Feature identifiers,  Up: Unit library

5.7.6 Keywords
--------------

Keywords are special symbols prefixed with `#:' that evaluate to
themselves.  Procedures can use keywords to accept optional named
parameters in addition to normal required parameters.  Assignment to
and bindings of keyword symbols is not allowed.  The parameter
`keyword-style' and the compiler/interpreter option `-keyword-style'
can be used to allow an additional keyword syntax, either compatible to
Common LISP, or to DSSSL.

 -- procedure: get-keyword
          (get-keyword KEYWORD ARGLIST [THUNK])
     Returns the argument from `ARGLIST' specified under the keyword
     `KEYWORD'.  If the keyword is not found, then the zero-argument
     procedure `THUNK' is invoked and the result value is returned. If
     `THUNK' is not given, `#f' is returned.


     (define (increase x . args)
       (+ x (get-keyword #:amount args (lambda () 1))) )
     (increase 123)                                      ==> 124
     (increase 123 #:amount 10)                          ==> 133

     Note: the `KEYWORD' may actually be any kind of object.


 -- procedure: keyword?
          (keyword? X)
     Returns `#t' if `X' is a keyword symbol, or `#f' otherwise.


 -- procedure: keyword->string
          (keyword->string KEYWORD)
     Transforms `KEYWORD' into a string.


 -- procedure: string->keyword
          (string->keyword STRING)
     Returns a keyword with the name `STRING'.


File: chicken.info,  Node: Exceptions,  Next: Environment information and system interface,  Prev: Keywords,  Up: Unit library

5.7.7 Exceptions
----------------

CHICKEN implements the (currently withdrawn) SRFI-12 exception system.
For more information, see the SRFI-12 document
(http://srfi.schemers.org/srfi-12/srfi-12.html)

 -- syntax: condition-case
          (condition-case EXPRESSION CLAUSE ...)
     Evaluates `EXPRESSION' and handles any exceptions that are covered
     by `CLAUSE ...', where `CLAUSE' should be of the following form:


     CLAUSE = ([VARIABLE] (KIND ...) BODY ...)

     If provided, `VARIABLE' will be bound to the signalled exception
     object. `BODY ...' is executed when the exception is a property-
     or composite condition with the kinds given `KIND ...'
     (unevaluated).  If no clause applies, the exception is
     re-signalled in the same dynamic context as the `condition-case'
     form.


     (define (check thunk)
       (condition-case (thunk)
         [(exn file) (print "file error")]
         [(exn) (print "other error")]
         [var () (print "something else")] ) )

     (check (lambda () (open-input-file "")))   ; -> "file error"
     (check (lambda () some-unbound-variable))  ; -> "othererror"
     (check (lambda () (signal 99)))            ; -> "something else"

     (condition-case some-unbound-variable
       [(exn file) (print "ignored)] )      ; -> signals error

   All error-conditions signalled by the system are of kind `exn'.  The
following composite conditions are additionally defined:

`(exn arity)'
     Signalled when a procedure is called with the wrong number of
     arguments.

`(exn type)'
     Signalled on type-mismatch errors, for example when an argument of
     the wrong type is passed to a builtin procedure.

`(exn arithmetic)'
     Signalled on arithmetic errors, like division by zero.

`(exn i/o)'
     Signalled on input/output errors.

`(exn i/o file)'
     Signalled on file-related errors.

`(exn i/o net)'
     Signalled on network errors.

`(exn bounds)'
     Signalled on errors caused by accessing non-existent elements of a
     collection.

`(exn runtime)'
     Signalled on low-level runtime-system error-situations.

`(exn runtime limit)'
     Signalled when an internal limit is exceeded (like running out of
     memory).

`(exn match)'
     Signalled on errors raised by failed matches (see the section on
     `match').

`(exn syntax)'
     Signalled on syntax errors.


   Notes:
   * All error-exceptions (of the kind `exn') are non-continuable.

   * Error-exceptions of the `exn' kind have additional `arguments' and
     `location' properties that contain the arguments passed to the
     error-handler and the name of the procedure where the error
     occurred (if available).

   * When the `posix' unit is available and used, then a user-interrupt
     (`signal/int') signals an exception of the kind `user-interrupt'.

   * the procedure `condition-property-accessor' accepts an optional
     third argument. If the condition does not have a value for the
     desired property and if the optional argument is given and false,
     no error is signalled and the accessor returns `#g'.



File: chicken.info,  Node: Environment information and system interface,  Next: Execution time,  Prev: Exceptions,  Up: Unit library

5.7.8 Environment information and system interface
--------------------------------------------------

 -- procedure: argv
          (argv)
     Return a list of all supplied command-line arguments. The first
     item in the list is a string containing the name of the executing
     program. The other items are the arguments passed to the
     application. This list is freshly created on every invocation of
     `(argv)'.  It depends on the host-shell whether arguments are
     expanded ('globbed') or not.


 -- procedure: exit
          (exit [CODE])
     Exit the running process and return exit-code, which defaults to 0
     (Invokes `exit-handler').


 -- procedure: build-platform
          (build-platform)
     Returns a symbol specifying the toolset which has been used for
     building the executing system, which is one of the following:


     djgpp
     cygwin
     msvc
     mingw32
     gnu
     metrowerks
     unknown


 -- procedure: chicken-version
          (chicken-version)
     Returns a string containing the version number of the CHICKEN
     runtime system.


 -- procedure: errno
          (errno)
     Returns the error code of the last system call.


 -- procedure: getenv
          (getenv STRING)
     Returns the value of the environment variable `STRING' or `#f' if
     that variable is not defined.


 -- procedure: machine-type
          (machine-type)
     Returns a symbol specifying the processor on which this process is
     currently running, which is one of the following:


     alpha
     mips
     hppa
     ultrasparc
     sparc
     ppc
     ia64
     x86
     x86-64
     unknown


 -- procedure: software-type
          (software-type)
     Returns a symbol specifying the operating system on which this
     process is currently running, which is one of the following:


     msdos
     windows
     unix
     macos
     unknown


 -- procedure: software-version
          (software-version)
     Returns a symbol specifying the operating system version on which
     this process is currently running, which is one of the following:


     linux
     freebsd
     netbsd
     openbsd
     macosx
     hpux
     solaris
     sunos
     unknown


 -- procedure: c-runtime
          (c-runtime)
     Returns a symbol that designates what kind of C runtime library
     has been linked with this version of the Chicken libraries.
     Possible return values are `static', `dynamic' or `unknown'. On
     systems not compiled with the Microsoft C compiler, `c-runtime'
     always returns `unknown'.

 -- procedure: chicken-home
          (chicken-home)
     Returns a string given the installation directory (usually
     `/usr/local/share/chicken' on UNIX-like systems).  If the
     environment variable `CHICKEN_HOME' is set, then its value will be
     returned.

 -- procedure: system
          (system STRING)
     Execute shell command. The functionality offered by this procedure
     depends on the capabilities of the host shell.


File: chicken.info,  Node: Execution time,  Next: Interrupts and error-handling,  Prev: Environment information and system interface,  Up: Unit library

5.7.9 Execution time
--------------------

 -- procedure: cpu-time
          (cpu-time)
     Returns the used CPU time of the current process in milliseconds as
     two values: the time spent in user code, and the time spent in
     system code. On platforms where user and system time can not be
     differentiated, system time will be always be 0.


 -- procedure: current-milliseconds
          (current-milliseconds)
     Returns the number of milliseconds since process- or machine
     startup.


 -- procedure: current-seconds
          (current-seconds)
     Returns the number of seconds since midnight, Jan. 1, 1970.


File: chicken.info,  Node: Interrupts and error-handling,  Next: Garbage collection,  Prev: Execution time,  Up: Unit library

5.7.10 Interrupts and error-handling
------------------------------------

 -- procedure: enable-interrupts
 -- procedure: disable-interrupts
          (enable-interrupts)
          (disable-interrupts)
     Enables/disables processing of timer-interrupts and interrupts
     caused by signals.


     (disable-interrupts)
     (disable-interrupts)
     (enable-interrupts)
     ; <interrupts still disabled - call enable-interrupts once more>


 -- procedure: enable-warnings
          (enable-warnings [BOOL])
     Enables or disables warnings, depending on wether `BOOL' is true
     or false.  If called with no arguments, this procedure returns
     `#t' if warnings are currently enabled, or `#f' otherwise. Note
     that this is not a parameter.  The current state (wether warnings
     are enabled or disabled) is global and not thread-local.


 -- procedure: error
          (error [LOCATION] STRING EXP ...)
     Prints error message, writes all extra arguments to the value of
     `(current-error-port)' and invokes the current value of
     `(error-handler)'.  This conforms to SRFI-23
     (http://srfi.schemers.org/srfi-23/srfi-23.html).  If `LOCATION' is
     given and a symbol, it specifies the "location" (the name of the
     procedure) where the error occurred.


 -- procedure: print-backtrace
          (print-backtrace [PORT])
     Prints a backtrace of the procedure call history to `PORT', which
     defaults to `(current-error-port)'. Backtrace information is only
     generated in compiled code, with a `-debug-level' >= 1.


 -- procedure: print-error-message
          (print-error-message EXN [PORT [STRING]])
     Prints an appropriate error message to `PORT' (which defaults to
     the value of `(current-error-port)' for the object `EXN'.  `EXN'
     may be a condition, a string or any other object.  If the optional
     argument `STRING' is given, it is printed before the
     error-message. `STRING' defaults to `"Error:"'.


 -- procedure: reset
          (reset)
     Reset program (Invokes `reset-handler').


File: chicken.info,  Node: Garbage collection,  Next: Other control structures,  Prev: Interrupts and error-handling,  Up: Unit library

5.7.11 Garbage collection
-------------------------

 -- procedure: gc
          (gc [FLAG])
     Invokes a garbage-collection and returns the number of free bytes
     in the heap. The flag specifies whether a minor (`#f') or major
     (`#t') GC is to be triggered. If no argument is given, `#t' is
     assumed. When the argument is `#t', all pending finalizers are
     executed.

      -- procedure: memory-statistics
               (memory-statistics)
          Performs a major garbage collection and returns a three
          element vector containing the total heap size in bytes, the
          number of bytes currently used and the size of the nursery
          (the first heap generation). Note that the actual heap is
          actually twice the size given in the heap size, because
          CHICKEN uses a copying semi-space collector.


 -- procedure: set-finalizer!
          (set-finalizer! X PROC)
     Registers a procedure of one argument `PROC', that will be called
     as soon as the non-immediate data object `X' is about to be
     garbage-collected (with that object as its argument).  Note that
     the finalizer will not be called when interrupts are disabled.
     This procedure returns `X'.


 -- procedure: set-gc-report!
          (set-gc-report! FLAG)
     Print statistics after every GC, depending on `FLAG'. A value of
     `#t' shows statistics after every major GC. A true value different
     from `#t' shows statistics after every minor GC. `#f' switches
     statistics off.


File: chicken.info,  Node: Other control structures,  Next: String utilities,  Prev: Garbage collection,  Up: Unit library

5.7.12 Other control structures
-------------------------------

 -- procedure: andmap
          (andmap PROC LIST1 ...)
     Repeatedly calls `PROC' with arguments taken from `LIST1 ...'.  If
     any invocation should return `#f', the result of `andmap' is `#f'.
     If all invocations return a true result, then the result of
     `andmap' is `#t'.


 -- procedure: ormap
          (ormap PROC LIST1 ...)
     Repeatedly calls `PROC' with arguments taken from `LIST1 ...'.  If
     any invocation should return a value different from `#f', then
     this value is returned as the  result of `ormap'. If all
     invocations return #f, then the result of `ormap' is `#f'.


File: chicken.info,  Node: String utilities,  Next: Generating uninterned symbols,  Prev: Other control structures,  Up: Unit library

5.7.13 String utilities
-----------------------

 -- procedure: reverse-list->string
          (reverse-list->string LIST)
     Returns a string with the characters in `LIST' in reverse order.
     This is equivalent to `(list->string (reverse LIST))', but much
     more efficient.


File: chicken.info,  Node: Generating uninterned symbols,  Next: Standard Input/Output,  Prev: String utilities,  Up: Unit library

5.7.14 Generating uninterned symbols
------------------------------------

 -- procedure: gensym
          (gensym [STRING-OR-SYMBOL])
     Returns a newly created uninterned symbol. If an argument is
     provided, the new symbol is prefixed with that argument.


 -- procedure: string->uninterned-symbol
          (string->uninterned-symbol STRING)
     Returns a newly created, unique symbol with the name `STRING'.


File: chicken.info,  Node: Standard Input/Output,  Next: User-defined named characters,  Prev: Generating uninterned symbols,  Up: Unit library

5.7.15 Standard Input/Output
----------------------------

 -- procedure: port?
          (port? X)
     Returns `#t' if `X' is a port object or `#f' otherwise.


 -- procedure: print
          (print EXP1 EXP2 ...)
     Outputs the arguments `EXP1 EXP2 ...' using `display' and writes a
     newline character to the port that is the value of
     `(current-output-port)'. Returns its first argument.


 -- procedure: print*
          (print* EXP1 ...)
     Similar to `print', but does not output a terminating newline
     character and performes a `flush-outout' after writing its
     arguments.


File: chicken.info,  Node: User-defined named characters,  Next: Vectors,  Prev: Standard Input/Output,  Up: Unit library

5.7.16 User-defined named characters
------------------------------------

 -- procedure: char-name
          (char-name SYMBOL-OR-CHAR [CHAR])
     This procedure can be used to inquire about character names or to
     define new ones. With a single argument the behavior is as follows:
     If `SYMBOL-OR-CHAR' is a symbol, then `char-name' returns the
     character with this name, or `#f' if no character is defined under
     this name.  If `SYMBOL-OR-CHAR' is a character, then the name of
     the character is returned as a symbol, or `#f' if the character
     has no associated name.

     If the optional argument `CHAR' is provided, then `SYMBOL-OR-CHAR'
     should be a symbol that will be the new name of the given
     character.  If multiple names designate the same character, then
     the `write' will use the character name that was defined last.


     (char-name 'space)                  ==> #\space
     (char-name #\space)                 ==> space
     (char-name 'bell)                   ==> #f
     (char-name (integer->char 7))       ==> #f
     (char-name 'bell (integer->char 7))
     (char-name 'bell)                   ==> #\bell
     (char->integer (char-name 'bell))   ==> 7


File: chicken.info,  Node: Vectors,  Next: The unspecified value,  Prev: User-defined named characters,  Up: Unit library

5.7.17 Vectors
--------------

 -- procedure: vector-copy!
          (vector-copy! VECTOR1 VECTOR2 [COUNT])
     Copies contents of `VECTOR1' into `VECTOR2'. If the argument
     `COUNT' is given, it specifies the maximal number of elements to
     be copied. If not given, the minimum of the lengths of the
     argument vectors is copied.

     Exceptions: `(exn bounds)'


 -- procedure: vector-resize
          (vector-resize VECTOR N [INIT])
     Creates and returns a new vector with the contents of `VECTOR' and
     length `N'.  If `N' is greater than the original length of
     `VECTOR', then all additional items are initialized to `INIT'. If
     `INIT' is not specified, the contents are initialized to some
     unspecified value.


File: chicken.info,  Node: The unspecified value,  Next: call/cc,  Prev: Vectors,  Up: Unit library

5.7.18 The _unspecified_ value
------------------------------

 -- procedure: void
          (void)
     Returns an unspecified value.


File: chicken.info,  Node: call/cc,  Prev: The unspecified value,  Up: Unit library

5.7.19 call/cc
--------------

 -- procedure: call/cc
          (call/cc PROCEDURE)
     An alias for `call-with-current-continuation'.


File: chicken.info,  Node: Unit eval,  Next: Unit extras,  Prev: Unit library,  Up: Supported language

5.8 Unit eval
=============

This unit has support for evaluation and macro-handling. This unit is
used by default, unless the program is compiled with the `-explicit-use'
option.

* Menu:

* Loading code::
* Read-eval-print loop::
* Macros::
* Loading extension libraries::
* Reader extensions::
* Eval::


File: chicken.info,  Node: Loading code,  Next: Read-eval-print loop,  Up: Unit eval

5.8.1 Loading code
------------------

 -- procedure: load
          (load FILE [EVALPROC])
     Loads and evaluates expressions from the given source file, which
     may be either a string or an input port.  Each expression read is
     passed to `EVALPROC' (which defaults to `eval').  On platforms that
     support it (currently Linux ELF and Solaris), `load' can be used
     to load compiled programs:


     % cat x.scm
     (define (hello) (print "Hello!"))
     % chicken x.scm -quiet -dynamic
     % gcc x.c -shared -fPIC `chicken-config -cflags -shared -libs` -o x.so
     % csi -quiet
     #;1> (load "x.so")
     ; loading x.so ...
     #;2> (hello)
     Hello!
     #;3>

     The second argument to `load' is ignored when loading compiled
     code.  The same compiled object file can not be loaded more than
     once.  If source code is loaded from a port, then that port is
     closed after all expressions have been read.


 -- procedure: load-library
          (load-library UNIT [LIBRARYFILE])
     On platforms that support dynamic loading, `load-library' loads
     the compiled library unit `UNIT' (which should be a symbol). If the
     string `LIBRARYFILE' is given, then the given shared library will
     be loaded and the toplevel code of the contained unit will be
     executed.  If no `LIBRARYFILE' argument is given, then the
     following libraries are checked for the required unit:

        * a file named "`<UNIT>.so'"

        * the files given in the parameter `dynamic-load-libraries'


     If the unit is not found, an error is signaled.  When the library
     unit can be successfully loaded, a feature-identifier named `UNIT'
     is registered. If the feature is already registered before loading,
     the `load-library' does nothing.


 -- procedure: load-noisily
          (load-noisily FILE #!key EVALUATOR TIME PRINTER)
     As `load' but the result(s) of each evaluated toplevel-expression
     is written to standard output. If `EVALUATOR' is given and not
     `#f', then each expression is evaluated by calling this argument
     with the read expression as argument. If `TIME' is given and not
     false, then the execution time of each expression is shown (as
     with the `time' macro).  If `PRINTER' is given and not false, then
     each expression is printed before evaluation by applying the
     expression to the value of this argument, which should be a
     one-argument procedure.



File: chicken.info,  Node: Read-eval-print loop,  Next: Macros,  Prev: Loading code,  Up: Unit eval

5.8.2 Read-eval-print loop
--------------------------

 -- procedure: repl
          (repl)
     Start a new read-eval-print loop. Sets the `reset-handler' so that
     any invocation of `reset' restarts the read-eval-print loop. Also
     changes the current `error-handler' to display a message, write
     any arguments to the value of `(current-error-port)' and reset.


File: chicken.info,  Node: Macros,  Next: Loading extension libraries,  Prev: Read-eval-print loop,  Up: Unit eval

5.8.3 Macros
------------

 -- procedure: get-line-number
          (get-line-number EXPR)
     If `EXPR' is a pair with the car being a symbol, and line-number
     information is available for this expression, then this procedure
     returns the associated line number. If line-number information is
     not available, then `#f' is returned.  Note that line-number
     information for expressions is only available in the compiler.


 -- procedure: macro?
          (macro? SYMBOL)
     Returns `#t' if there exists a macro-definition for `SYMBOL'.


 -- procedure: macroexpand
          (macroexpand X)
     If `X' is a macro-form, expand the macro (and repeat expansion
     until expression is a non-macro form).  Returns the resulting
     expression.


 -- procedure: macroexpand-1
          (macroexpand-1 X)
     If `X' is a macro-form, expand the macro.  Returns the resulting
     expression.


 -- procedure: undefine-macro!
          (undefine-macro! SYMBOL)
     Remove the current macro-definition of the macro named `SYMBOL'.

 -- procedure: syntax-error
          (syntax-error [LOCATION] MESSAGE ARGUMENT ...)
     Signals an exception of the kind `(exn syntax)'. Otherwise
     identical to `error'.


File: chicken.info,  Node: Loading extension libraries,  Next: Reader extensions,  Prev: Macros,  Up: Unit eval

5.8.4 Loading extension libraries
---------------------------------

This functionality is only available on platforms that support dynamic
loading of compiled code. Currently Linux, BSD, Solaris, Windows (with
Cygwin) and HP/UX are supported.

 -- parameter: repository-path
     Contains a string naming the path to the extension repository,
     which defaults to either the value of the environment variable
     `CHICKEN_REPOSITORY', the value of the environment variable
     `CHICKEN_HOME' or the default library path (usually
     `/usr/local/lib/chicken' on UNIX systems).

 -- procedure: extension-info
          (extension-info ID)
     If an extension with the name `ID' is installed and if it has a
     setup-information list registered in the extension repository,
     then the info-list is returned. Otherwise `extension-info' returns
     `#f'.

 -- procedure: provide
          (provide ID ...)
     Registers the extension IDs `ID ...' as loaded. This is mainly
     intended to provide aliases for certain extension identifiers.


 -- procedure: provided?
          (provided? ID ...)
     Returns `#t' if the extension with the IDs `ID ...' are currently
     loaded, or `#f' otherwise.  Works also for feature-ids.


 -- procedure: require
          (require ID ...)
     If the extension library `ID' is not already loaded into the
     system, then `require' will lookup the location of the shared
     extension library and load it. If `ID' names a library-unit of the
     base system, then it is loaded via `load-library'.  If no
     extension library is available for the given ID, then an attempt is
     made to load the file `ID.so' or `ID.scm' (in that order) from one
     of the following locations:

       1. the current directory

       2. the current include path, which defaults to the pathnames
          given in `CHICKEN_INCLUDE_PATH' and `CHICKEN_HOME'.  In case
          `ID' is a list, it is interpreted as a (relative) pathname.


     `ID' may be a symbol, or a list of symbols.  See also:
     `require-for-syntax'.

 -- procedure: set-extension-specifier!
          (set-extension-specifier! SYMBOL PROC)
     Registers the handler-procedure `PROC' as a extension-specifier
     with the name `SYMBOL'. This facility allows extending the set of
     valid extension specifiers to be used with `require-extension'.
     When `register-extension' is called with an extension specifier of
     the form `(SPEC ...)' and `SPEC' has been registered with
     `set-extension-specifier!', then `PROC' will be called with two
     arguments: the specifier and the previously installed handler (or
     `#f' if no such handler was defined). The handler should return a
     new specifier that will be processed recursively. If the handler
     returns a vector, then each element of the vector will be
     processed recursively.  Alternatively the handler may return a
     string which specifies a file to be loaded:

          (eval-when (compile eval)
            (set-extension-specifier!
              'my-package
              (lambda (spec old)
                (make-pathname my-package-directory (->string (cadr spec))) ) ) )

          (require-extension (my-package stuff))     ; --> expands into '(load "my-package-dir/stuff")

     Note that the handler has to be registered at compile time, if it
     is to be visible in compiled code.


File: chicken.info,  Node: Reader extensions,  Next: Eval,  Prev: Loading extension libraries,  Up: Unit eval

5.8.5 Reader extensions
-----------------------

 -- procedure: define-reader-ctor
          (define-reader-ctor SYMBOL PROC)
     Define new read-time constructor for `#,' read syntax. For further
     information, see the documentation for SRFI-10
     (http://srfi.schemers.org/srfi-10/srfi-10.html).

 -- procedure: set-read-syntax!
          (set-read-syntax! CHAR PROC)
     When the reader is encounting the non-whitespace character `CHAR'
     while reading an expression from a given port, then the procedure
     `PROC' will be called with that port as its argument. The
     procedure should return a value that will be returned to the
     reader:

          ; A simple RGB color syntax:

          (set-read-syntax! #\%
            (lambda (port)
              (apply vector
                (map (cut string->number <> 16)
                     (string-chop (read-string 6 port) 2) ) ) ) )

          (with-input-from-string "(1 2 %f0f0f0 3)" read)
          ; ==> (1 2 #(240 240 240) 3)


File: chicken.info,  Node: Eval,  Prev: Reader extensions,  Up: Unit eval

5.8.6 Eval
----------

 -- procedure: eval
          (eval EXP [ENVIRONMENT])
     Evaluates `EXP' and returns the result of the evaluation. The
     second argument is optional and defaults to the value of
     `(interaction-environment)'.


File: chicken.info,  Node: Unit extras,  Next: Unit srfi-1,  Prev: Unit eval,  Up: Supported language

5.9 Unit extras
===============

This unit contains a collection of useful utility definitions.  This
unit is used by default, unless the program is compiled with the
`-explicit-use' option.

* Menu:

* Lists::
* String-port extensions::
* Formatted output::
* Hash tables::
* Queues::
* Sorting::
* Random numbers::
* Input/Output extensions::
* Strings::
* Combinators::
* Binary searching::


File: chicken.info,  Node: Lists,  Next: String-port extensions,  Up: Unit extras

5.9.1 Lists
-----------

 -- procedure: alist-ref
          (alist-ref KEY ALIST [TEST [DEFAULT]])
     Looks up `KEY' in `ALIST' using `TEST' as the comparison function
     (or `eqv?' if no test was given) and returns the cdr of the found
     pair, or `DEFAULT' (which defaults to `#f').

 -- procedure: alist-update!
          (alist-update! KEY VALUE ALIST [TEST])
     If the list `ALIST' contains a pair of the form `(KEY . X)', then
     this procedure replaces `X' with `VALUE' and returns `ALIST'. If
     `ALIST' contains no such item, then `alist-update!' returns `((KEY
     . VALUE) . ALIST)'. The optional argument `TEST' specifies the
     comparison procedure to search a matching pair in `ALIST' and
     defaults to `eqv?'.

 -- procedure: atom?
          (atom? X)
     Returns `#t' if `X' is a not list (`X' is not a pair nor the empty
     list).

 -- procedure: rassoc
          (rassoc KEY LIST [TEST])
     Similar to `assoc', but compares `KEY' with the `cdr' of each pair
     in `LIST' using `TEST' as the comparison procedures (which
     defaults to `eqv?'.


 -- procedure: butlast
          (butlast LIST)
     Returns a fresh list with all elements but the last of `LIST'.


 -- procedure: chop
          (chop LIST N)
     Returns a new list of sublists, where each sublist contains `N'
     elements of `LIST'. If `LIST' has a length that is not a multiple
     of `N', then the last sublist contains the remaining elements.


     (chop '(1 2 3 4 5 6) 2) ==> ((1 2) (3 4) (5 6))
     (chop '(a b c d) 3)     ==> ((a b c) (d))


 -- procedure: compress
          (compress BLIST LIST)
     Returns a new list with elements taken from `LIST' with
     corresponding true values in the list `BLIST'.


     (define nums '(99 100 110 401 1234))
     (compress (map odd? nums) nums)      ==> (99 401)


 -- procedure: flatten
          (flatten LIST1 ...)
     Returns `LIST1 ...' concatenated together, with nested lists
     removed (flattened).


 -- procedure: intersperse
          (intersperse LIST X)
     Returns a new list with `X' placed between each element.


 -- procedure: join
          (join LISTOFLISTS [LIST])
     Concatenates the lists in `LISTOFLISTS' with `LIST' placed between
     each sublist. `LIST' defaults to the empty list.


     (join '((a b) (c d) (e)) '(x y)) ==> (a b x y c d x y e)
     (join '((p q) () (r (s) t)) '(-))  ==> (p q - - r (s) t)


 -- procedure: shuffle
          (shuffle LIST)
     Returns `LIST' with its elements sorted in a random order.

     `join' could be implemented as follows:


     (define (join lstoflsts #!optional (lst '()))
       (apply append (intersperse lstoflists lst)) )


 -- procedure: tail?
          (tail? X LIST)
     Returns true if `X' is one of the tails (cdr's) of `LIST'.


File: chicken.info,  Node: String-port extensions,  Next: Formatted output,  Prev: Lists,  Up: Unit extras

5.9.2 String-port extensions
----------------------------

 -- procedure: call-with-input-string
          (call-with-input-string STRING PROC)
     Calls the procedure `PROC' with a single argument that is a
     string-input-port with the contents of `STRING'.


 -- procedure: call-with-output-string
          (call-with-output-string PROC)
     Calls the procedure `PROC' with a single argument that is a
     string-output-port.  Returns the accumulated output-string.


 -- procedure: with-input-from-string
          (with-input-from-string STRING THUNK)
     Call procedure `THUNK' with the current input-port temporarily
     bound to an input-string-port with the contents of `STRING'.


 -- procedure: with-output-to-string
          (with-output-to-string THUNK)
     Call procedure `THUNK' with the current output-port temporarily
     bound to a string-output-port and return the accumulated output
     string.


File: chicken.info,  Node: Formatted output,  Next: Hash tables,  Prev: String-port extensions,  Up: Unit extras

5.9.3 Formatted output
----------------------

 -- procedure: fprintf
 -- procedure: printf
 -- procedure: sprintf
          (fprintf PORT FORMATSTRING ARG ...)
          (printf FORMATSTRING ARG)
          (sprintf FORMATSTRING ARG ...)
     Simple formatted output to a given port (`fprintf'), the value of
     `(current-output-port) ' (`printf') or a string (`sprintf').  The
     `FORMATSTRING' can contain any sequence of characters. The
     character `~' prefixes special formatting directives:

    `~%'
          write newline character

    `~S'
          write the next argument

    `~A'
          display the next argument

    `~\n'
          skip all whitespace in the format-string until the next
          non-whitespace character

    `~B'
          write the next argument as a binary number

    `~O'
          write the next argument as an octal number

    `~X'
          write the next argument as a hexadecimal number

    `~C'
          write the next argument as a character

    `~~'
          display `~'

    `~!'
          flush all pending output

    `~?'
          invoke formatted output routine recursively with the next two
          arguments as format-string and list of parameters

     For more powerful output formatting, see the section about the
     `format' unit.


File: chicken.info,  Node: Hash tables,  Next: Queues,  Prev: Formatted output,  Up: Unit extras

5.9.4 Hash tables
-----------------

 -- procedure: clear-hash-table!
          (clear-hash-table! HASH-TABLE)
     Erases all entries in the hash-table `HASH-TABLE'.


 -- procedure: get
          (get HASH-TABLE KEY PROP)
     Returns the value of property `PROP' of the item `KEY' in
     `HASH-TABLE '. This facility can be used as a kind of
     "disembodied" property-list. If no entry named `KEY' is stored in
     the hash-table or if no property `PROP' for that key exists, `#f'
     is returned.


 -- procedure: hash-table?
          (hash-table? X)
     Returns `#t' if the argument is a hash-table.


 -- procedure: hash-table->list
          (hash-table->list HASH-TABLE)
     Converts `HASH-TABLE' into an association-list.


 -- procedure: hash-table-count
          (hash-table-count HASH-TABLE)
     Returns the number of entries in the given hash-table.


 -- procedure: hash-table-size
          (hash-table-size HASH-TABLE)
     Returns the size of the hash-table.


 -- procedure: hash-table-for-each
          (hash-table-for-each PROC HASH-TABLE)
     Calls `PROC' which should expect two arguments. This procedure is
     called for each entry in the hash-table with the key and the value
     as parameters.


 -- procedure: hash-table-ref
          (hash-table-ref HASH-TABLE KEY [DEFAULT])
     Returns the entry in the given hash-table under `KEY'. If no entry
     is stored in the table, `#f' is returned.


 -- procedure: hash-table-remove!
          (hash-table-remove! HASH-TABLE KEY)
     Removes an entry in the given hash-table.


 -- procedure: hash-table-set!
          (hash-table-set! HASH-TABLE KEY VALUE)
     Adds or changes an entry in the given hash-table.


 -- procedure: make-hash-table
          (make-hash-table [PRED [SIZE]])
     Creates and returns a hash-table with keys compared via `PRED',
     which defaults to `eq?'. If `SIZE' is provided it specifies the
     initial size of the hash-table.  If the hash-table fills above a
     certain size it is automatically resized to accommodate more
     entries.


 -- procedure: put!
          (put! HASH-TABLE KEY PROP VALUE)
     Stores `VALUE' as property `PROP' under the item `KEY' in the
     given hash-table. Any previously existing value is overwritten.


File: chicken.info,  Node: Queues,  Next: Sorting,  Prev: Hash tables,  Up: Unit extras

5.9.5 Queues
------------

 -- procedure: list->queue
          (list->queue LIST)
     Returns `LIST' converted into a queue, where the first element of
     the list is the same as the first element of the queue. The
     resulting queue may share memory with the list and the list should
     not be modified after this operation.


 -- procedure: make-queue
          (make-queue)
     Returns a newly created queue.


 -- procedure: queue?
          (queue? X)
     Returns `#t' if `X' is a queue, or `#f' otherwise.


 -- procedure: queue->list
          (queue->list QUEUE)
     Returns `QUEUE' converted into a list, where the first element of
     the list is the same as the first element of the queue. The
     resulting list may share memory with the queue object and should
     not be modified.


 -- procedure: queue-add!
          (queue-add! QUEUE X)
     Adds `X' to the rear of `QUEUE'.


 -- procedure: queue-empty?
          (queue-empty? QUEUE)
     Returns `#t' if `QUEUE' is empty, or `#f' otherwise.


 -- procedure: queue-first
          (queue-first QUEUE)
     Returns the first element of `QUEUE'. If `QUEUE' is empty an error
     is signaled


 -- procedure: queue-last
          (queue-last QUEUE)
     Returns the last element of `QUEUE'. If `QUEUE' is empty an error
     is signaled


 -- procedure: queue-remove!
          (queue-remove! QUEUE)
     Removes and returns the first element of `QUEUE'. If `QUEUE' is
     empty an error is signaled


File: chicken.info,  Node: Sorting,  Next: Random numbers,  Prev: Queues,  Up: Unit extras

5.9.6 Sorting
-------------

 -- procedure: merge
 -- procedure: merge!
          (merge LIST1 LIST2 LESS?)
          (merge! LIST1 LIST2 LESS?)
     Joins two lists in sorted order. `merge!' is the destructive
     version of merge. `LESS?  ' should be a procedure of two arguments,
     that returns true if the first argument is to be ordered before the
     second argument.


 -- procedure: sort
 -- procedure: sort!
          (sort SEQUENCE LESS?)
          (sort! SEQUENCE LESS?)
     Sort `SEQUENCE', which should be a list or a vector. `sort!' is
     the destructive version of sort.


 -- procedure: sorted?
          (sorted? SEQUENCE LESS?)
     Returns true if the list or vector `SEQUENCE' is already sorted.


File: chicken.info,  Node: Random numbers,  Next: Input/Output extensions,  Prev: Sorting,  Up: Unit extras

5.9.7 Random numbers
--------------------

 -- procedure: random
          (random N)
     Returns an exact random integer from 0 to `N'-1.


 -- procedure: randomize
          (randomize [X])
     Set random-number seed. If `X' is not supplied, the current time
     is used.  On startup (when the `extras' unit is initialized), the
     random number generator is initialized with the current time.


File: chicken.info,  Node: Input/Output extensions,  Next: Strings,  Prev: Random numbers,  Up: Unit extras

5.9.8 Input/Output extensions
-----------------------------

 -- procedure: make-input-port
          (make-input-port READ READY? CLOSE [PEEK])
     Returns a custom input port. Common operations on this port are
     handled by the given parameters, which should be procedures of no
     arguments. `READ' is called when the next character is to be read
     and should return a character or the value of `(end-of-file)'.
     `READY?' is called when `char-ready?' is called on this port and
     should return `#t' or `#f'.  `CLOSE' is called when the port is
     closed. `PEEK' is called when `peek-char' is called on this port
     and should return a character or the value of `(end-of-file)'.  if
     the argument `PEEK' is not given, then `READ' is used instead and
     the created port object handles peeking automatically (by calling
     `READ' and buffering the character).


 -- procedure: make-output-port
          (make-output-port WRITE CLOSE [FLUSH])
     Returns a custom output port. Common operations on this port are
     handled by the given parameters, which should be procedures.
     `WRITE' is called when output is sent to the port and receives a
     single argument, a string.  `CLOSE' is called when the port is
     closed and should be a procedure of no arguments. `FLUSH' (if
     provided) is called for flushing the output port.


 -- procedure: pretty-print
 -- procedure: pp
          (pretty-print EXP [PORT])
          (pp EXP [PORT])
     Print expression nicely formatted. `PORT' defaults to the value of
     `(current-output-port)'.


 -- parameter: pretty-print-width
     Specifies the maximal line-width for pretty printing, after which
     line wrap will occur.


 -- procedure: read-file
          (read-file [FILE-OR-PORT])
     Returns a list containing all toplevel expressions read from the
     file or port `FILE-OR-PORT'. If no argument is given, input is
     read from the port that is the current value of
     `(current-input-port)'.  After all expressions are read, and if
     the argument is a port, then the port will not be closed.


 -- procedure: read-line
 -- procedure: write-line
          (read-line [PORT [LIMIT]])
          (write-line STRING [PORT])
     Line-input and -output. `PORT' defaults to the value of
     `(current-input-port)' and `(current-output-port)', respectively.
     if the optional argument `LIMIT' is given and not `#f', then
     `read-line' reads at most `LIMIT' characters per line.


 -- procedure: read-lines
          (read-lines [PORT [MAX]])
     Read `MAX' or fewer lines from `PORT'. `PORT' defaults to the
     value of `(current-input-port)'.


 -- procedure: read-string
 -- procedure: write-string
          (read-string [NUM [PORT]])
          (write-string STRING [NUM [PORT]]
     Read or write `NUM' characters from/to `PORT', which defaults to
     the value of `(current-input-port)' or `(current-output-port)',
     respectively.  If `NUM' is `#f' or not given, then all data up to
     the end-of-file is read, or, in the case of `write-string' the
     whole string is written. If no more input is available,
     `read-string' returns the empty string.

 -- procedure: read-token
          (read-token PREDICATE [PORT])
     Reads characters from `PORT' (which defaults to the value of
     `(current-input-port)') and calls the procedure `PREDICATE' with
     each character until `PREDICATE' returns false. Returns a string
     with the accumulated characters.

 -- procedure: with-error-output-to-port
          (with-error-output-to-port PORT THUNK)
     Call procedure `THUNK' with the current error output-port
     temporarily bound to `PORT'.


 -- procedure: with-input-from-port
          (with-input-from-port PORT THUNK)
     Call procedure `THUNK' with the current input-port temporarily
     bound to `PORT'.


 -- procedure: with-output-to-port
          (with-output-to-port PORT THUNK)
     Call procedure `THUNK' with the current output-port temporarily
     bound to `PORT'.


File: chicken.info,  Node: Strings,  Next: Combinators,  Prev: Input/Output extensions,  Up: Unit extras

5.9.9 Strings
-------------

 -- procedure: conc
          (conc X ...)
     Returns a string with the string-represenation of all arguments
     concatenated together. `conc' could be implemented as


     (define (conc . args)
       (apply string-append (map ->string args)) )

 -- procedure: ->string
          (->string X)
     Returns a string-representation of `X'.


 -- procedure: string-chop
          (string-chop STRING LENGTH)
     Returns a list of substrings taken by "chopping" `STRING' every
     `LENGTH' characters:


     (string-chop "one two three" 4)  ==>  ("one " "two " "thre" "e")


 -- procedure: string-compare3
          (string-compare3 STRING1 STRING2)

 -- procedure: string-compare3-ci
          (string-compare3-ci STRING1 STRING2)
     Perform a three-way comparison between the `STRING1' and `STRING2',
     returning either `-1' if `STRING1' is lexicographically less than
     `STRING2', `0' if it is equal, or `1' if it s greater.
     `string-compare3-ci' performs a case-insensitive comparison.

 -- procedure: string-intersperse
          (string-intersperse LIST [STRING])
     Returns a string that contains all strings in `LIST' concatenated
     together.  `STRING' is placed between each concatenated string and
     defaults to `" "'.


     (string-intersperse '("one" "two") "three")

     is equivalent to


     (apply string-append (intersperse '("one" "two") "three"))


 -- procedure: string-split
          (string-split STRING [DELIMITER-STRING [KEEPEMPTY]])
     Split string into substrings separated by the given delimiters. If
     no delimiters are specified, a string comprising the tab, newline
     and space characters is assumed. If the parameter `KEEPEMPTY' is
     given and not `#f', then empty substrings are retained:


     (string-split "one  two  three") ==> ("one" "two" "three")
     (string-split "foo:bar::baz:" ":" #t) ==> ("foo" "bar" "" "baz" "")


 -- procedure: string-translate
          (string-translate STRING FROM [TO])
     Returns a fresh copy of `STRING' with characters matching `FROM'
     translated to `TO'.  If `TO' is omitted, then matching characters
     are removed. `FROM' and `TO' may be a character, a string or a
     list. If both `FROM' and `TO' are strings, then the character at
     the same position in `TO' as the matching character in `FROM' is
     substituted.


 -- procedure: string-translate*
          (string-translate* STRING SMAP)
     Substitutes elements of `STRING' according to `SMAP'.  `SMAP'
     should be an association-list where each element of the list is a
     pair of the form `(MATCH \. REPLACEMENT)'. Every occurrence of the
     string `MATCH' in `STRING' will be replaced by the string
     `REPLACEMENT':


     (string-translate*
       "<h1>this is a \"string\"</h1>"
       '(("<" . "&lt:") (">" . "&gt;") ("\"" . "&quot;")) )

     ==>  "&lt;h1&gt;this is a &quot;string&quot;&lt;/ht&gt;"


 -- procedure: substring=?
 -- procedure: substring-ci=?
          (substring=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
          (substring-ci=? STRING1 STRING2 [START1 [START2 [LENGTH]]])
     Returns `#t' if the strings `STRING1' and `STRING2' are equal, or
     `#f' otherwise.  The comparison starts at the positions `START1'
     and `START2' (which default to 0), comparing `LENGTH' characters
     (which defaults to the minimum of the remaining length of both
     strings).


 -- procedure: substring-index
 -- procedure: substring-index-ci
          (substring-index WHICH WHERE [START])
          (substring-index-ci WHICH WHERE [START])
     Searches for first index in string `WHERE' where string `WHICH'
     occurs.  If the optional argument `START' is given, then the
     search starts at that index.  `substring-index-ci' is a
     case-insensitive version of `substring-index'.


File: chicken.info,  Node: Combinators,  Next: Binary searching,  Prev: Strings,  Up: Unit extras

5.9.10 Combinators
------------------

 -- procedure: constantly
          (constantly X ...)
     Returns a procedure that always returns the values `X ...'
     regardless of the number and value of its arguments.


     (constantly X) <=> (lambda args X)


 -- procedure: complement
          (complement PROC)
     Returns a procedure that returns the boolean inverse of `PROC'.
     (complement PROC) <=> (lambda (x) (not (PROC x)))


 -- procedure: compose
          (compose PROC1 PROC2 ...)
     Returns a procedure that represents the composition of the
     argument-procedures `PROC1 PROC2 ...'.


     (compose F G) <=> (lambda args
                           (call-with-values
                              (lambda () (apply G args))
                              F))


 -- procedure: conjoin
          (conjoin PRED ...)
     Returns a procedure that returns `#t' if its argument satisfies the
     predicates `PRED ...'.
     ((conjoin odd? positive?) 33)   ==>  #t
     ((conjoin odd? positive?) -33)  ==>  #f


 -- procedure: disjoin
          (disjoin PRED ...)
     Returns a procedure that returns `#t' if its argument satisfies any
     predicate `PRED ...'.
     ((disjoin odd? positive?) 32)    ==>  #t
     ((disjoin odd? positive?) -32)   ==>  #f


 -- procedure: flip
          (flip PROC)
     Returns a two-argument procedure that calls `PROC' with its
     arguments swapped:
     (flip PROC) <=> (lambda (x y) (PROC y x))


 -- procedure: identity
          (identity X)
     Returns its sole argument `X'.


 -- procedure: project
          (project N)
     Returns a procedure that returns its `N'th argument.


 -- procedure: list-of
          (list-of PRED)
     Returns a procedure of one argument that returns `#t' when applied
     to a list of elements that all satisfy the predicate procedure
     `PRED', or `#f' otherwise.


     ((list-of even?) '(1 2 3))   ==> #f
     ((list-of number?) '(1 2 3)) ==> #t

 -- procedure: noop
          (noop X ...)
     Ignores it's arguments, does nothing and returns an unspecified
     value.


File: chicken.info,  Node: Binary searching,  Prev: Combinators,  Up: Unit extras

5.9.11 Binary searching
-----------------------

 -- procedure: binary-search
          (binary-search SEQUENCE PROC)
     Performs a binary search in `SEQUENCE', which should be a sorted
     list or vector.  `PROC' is called to compare items in the sequence,
     should accept a single argument and return an exact integer: zero
     if the searched value is equal to the current item, negative if
     the searched value is "less" than the current item, and positive
     otherwise.


File: chicken.info,  Node: Unit srfi-1,  Next: Unit srfi-4,  Prev: Unit extras,  Up: Supported language

5.10 Unit srfi-1
================

List library, see the documentation for SRFI-1
(http://srfi.schemers.org/srfi-1/srfi-1.html)


File: chicken.info,  Node: Unit srfi-4,  Next: Unit srfi-13,  Prev: Unit srfi-1,  Up: Supported language

5.11 Unit srfi-4
================

Homogeneous numeric vectors, see the documentation for SRFI-4
(http://srfi.schemers.org/srfi-4/srfi-4.html) In addition to that, the
following procedures are also provided:

 -- procedure: u8vector->byte-vector
 -- procedure: s8vector->byte-vector
 -- procedure: u16vector->byte-vector
 -- procedure: s16vector->byte-vector
 -- procedure: u32vector->byte-vector
 -- procedure: s32vector->byte-vector
 -- procedure: f32vector->byte-vector
 -- procedure: f64vector->byte-vector
          (u8vector->byte-vector U8VECTOR)
          (s8vector->byte-vector S8VECTOR)
          (u16vector->byte-vector U16VECTOR)
          (s16vector->byte-vector S16VECTOR)
          (u32vector->byte-vector U32VECTOR)
          (s32vector->byte-vector S32VECTOR)
          (f32vector->byte-vector F32VECTOR)
          (f64vector->byte-vector F64VECTOR)
     Each of these procedures return the contents of the given vector
     as a 'packed' byte-vector. The byte order in that vector is
     platform-dependent (for example little-endian on an Intel
     processor). The returned byte-vector shares memory with the
     contents of the vector.

 -- procedure: byte-vector->u8vector
 -- procedure: byte-vector->s8vector
 -- procedure: byte-vector->u16vector
 -- procedure: byte-vector->s16vector
 -- procedure: byte-vector->u32vector
 -- procedure: byte-vector->s32vector
 -- procedure: byte-vector->f32vector
 -- procedure: byte-vector->f64vector
          (byte-vector->u8vector BYTE-VECTOR)
          (byte-vector->s8vector BYTE-VECTOR)
          (byte-vector->u16vector BYTE-VECTOR)
          (byte-vector->s16vector BYTE-VECTOR)
          (byte-vector->u32vector BYTE-VECTOR)
          (byte-vector->s32vector BYTE-VECTOR)
          (byte-vector->f32vector BYTE-VECTOR)
          (byte-vector->f64vector BYTE-VECTOR)
     Each of these procedures return a vector where the argument
     `BYTE-VECTOR' is taken as a 'packed' representation of the contents
     of the vector. The argument-byte-vector shares memory with the
     contents of the vector.


 -- procedure: subu8vector
 -- procedure: subu16vector
 -- procedure: subu32vector
 -- procedure: subs8vector
 -- procedure: subs16vector
 -- procedure: subs32vector
 -- procedure: subf32vector
 -- procedure: subf64vector
          (subu8vector U8VECTOR FROM TO)
          (subu16vector U16VECTOR FROM TO)
          (subu32vector U32VECTOR FROM TO)
          (subs8vector S8VECTOR FROM TO)
          (subs16vector S16VECTOR FROM TO)
          (subs32vector S32VECTOR FROM TO)
          (subf32vector F32VECTOR FROM TO)
          (subf64vector F64VECTOR FROM TO)
     Creates a number vector of the same type as the argument vector
     with the elements at the positions `FROM' up to but not including
     `TO'.


File: chicken.info,  Node: Unit srfi-13,  Next: Unit srfi-14,  Prev: Unit srfi-4,  Up: Supported language

5.12 Unit srfi-13
=================

String library, see the documentation for SRFI-13
(http://srfi.schemers.org/srfi-13/srfi-13.html)

   On systems that support dynamic loading, the `srfi-13' unit can be
made available in the interpreter (`csi') by entering


(require-extension srfi-13)


File: chicken.info,  Node: Unit srfi-14,  Next: Unit srfi-25,  Prev: Unit srfi-13,  Up: Supported language

5.13 Unit srfi-14
=================

Character set library, see the documentation for SRFI-14
(http://srfi.schemers.org/srfi-14/srfi-14.html)

   On systems that support dynamic loading, the `srfi-14' unit can be
made available in the interpreter (`csi') by entering


(require-extension srfi-14)

   * This library provides only the Latin-1 character set.


File: chicken.info,  Node: Unit srfi-25,  Next: Unit match,  Prev: Unit srfi-14,  Up: Supported language

5.14 Unit srfi-25
=================

Multi-dimensional array, see the documentation for SRFI-25
(http://srfi.schemers.org/srfi-25/srfi-25.html)

   On systems that support dynamic loading, the `srfi-25' unit can be
made available in the interpreter (`csi') by entering


(require-extension srfi-25)


File: chicken.info,  Node: Unit match,  Next: Unit regex,  Prev: Unit srfi-25,  Up: Supported language

5.15 Unit match
===============

Andrew Wright's pattern matching package. Note that to use the macros in
normal compiled code it is not required to declare this unit as used.
Only if forms containing these macros are to be expanded at runtime,
this is needed.

 -- syntax: match
 -- syntax: match-lambda
 -- syntax: match-lambda*
 -- syntax: match-let
 -- syntax: match-let*
 -- syntax: match-letrec
 -- syntax: match-define
          (match EXP CLAUSE ...)
          (match-lambda CLAUSE ...)
          (match-lambda* CLAUSE ...)
          (match-let ((PAT EXP) ...) BODY)
          (match-let* ((PAT EXP) ...) BODY)
          (match-letrec ((PAT EXP) ...) BODY)
          (match-define PAT EXP)
     Match expression or procedure arguments with pattern and execute
     associated expressions.  A Postscript manual
     (http://www.call-with-current-continuation.org/match.ps) is
     available .


 -- procedure: match-error-control
          (match-error-control [MODE])
     Selects a mode that specifies how `match...' macro forms are to be
     expanded.  With no argument this procedure returns the current
     mode. A single argument specifies the new mode that decides what
     should happen if no match-clause applies.  The following modes are
     supported:

    `#:error'
          Signal an error. This is the default.

    `#:match'
          Signal an error and output the offending form.

    `#:fail'
          Omits `pair?' tests when the consequence is to fail in `car'
          or `cdr' rather than to signal an error.

    `#:unspecified'
          Non-matching expressions will either fail in `car' or `cdr'
          or return an unspecified value.  This mode applies to files
          compiled with the `unsafe' option or declaration.


     When an error is signalled, the raised exception will be of kind
     `(exn match)'.


   Note: the `$' pattern handles native record structures and SRFI-9
records transparently.  The structure facility of the match package
(`define-structure') is not available.

   To use the pattern matching macros with the highlevel (`syntax-case')
macro system `(require-extension match)'.


File: chicken.info,  Node: Unit regex,  Next: Unit syntax-case,  Prev: Unit match,  Up: Supported language

5.16 Unit regex
===============

This library unit provides support for regular expressions. The flavor
depends on the particular installation platform:

   * On UNIX systems that have PCRE (the Perl Compatible Regular
     Expression package) installed, PCRE is used.

   * If PCRE is not available, and the C library provides regular
     expressions, these are used instead.

   * on Windows (or of PCRE and libc regexes are not available), Dorai
     Sitaram's portable `pregexp' library is used.

 -- procedure: grep
          (grep REGEX LIST)
     Returns all items of `LIST' that match the regular expression
     `REGEX'.  This procedure could be defined as follows:


     (define (grep regex lst)
       (filter (lambda (x) (string-search regex x)) lst) )


 -- procedure: pattern->regexp
          (pattern->regexp PATTERN)
     Converts the file-pattern `PATTERN' into a regular expression.


     (pattern->regexp "foo.*") ==> "foo\..*"


 -- procedure: regexp
          (regexp STRING [IGNORECASE [IGNORESPACE [UTF8]]])
     Returns a precompiled regular expression object for `string'.  The
     optional arguments `IGNORECASE', `IGNORESPACE' and `UTF8' specify
     whether the regular expression should be matched with case- or
     whitespace-differences ignored, or whether the string should be
     treated as containing UTF-8 encoded characters, respectively.

     Notes:

        * regex doesn't allow (?: ) cloisters (non-capturing groups)
          Currently this means if you use utf8 matching, individual "."
             matching will return extra submatches.

        * pregexp doesn't allow a # comment w/o a trailing newline.


 -- procedure: regexp?
          (regexp? X)
     Returns `#t' if `X' is a precompiled regular expression, or `#f'
     otherwise.


 -- procedure: string-match
 -- procedure: string-match-positions
          (string-match REGEXP STRING [START])
          (string-match-positions REGEXP STRING [START])
     Matches the regular expression in `REGEXP' (a string or a
     precompiled regular expression) with `STRING' and returns either
     `#f' if the match failed, or a list of matching groups, where the
     first element is the complete match. If the optional argument
     `START' is supplied, it specifies the starting position in
     `STRING'.  For each matching group the result-list contains
     either: `#f' for a non-matching but optional group; a list of
     start- and end-position of the match in `STRING' (in the case of
     `string-match-positions'); or the matching substring (in the case
     of `string-match'). Note that the exact string is matched. For
     searching a pattern inside a string, see below.


 -- procedure: string-search
 -- procedure: string-search-positions
          (string-search REGEXP STRING [START [RANGE]])
          (string-search-positions REGEXP STRING [START [RANGE]])
     Searches for the first match of the regular expression in `REGEXP'
     with `STRING'. The search can be limited to `RANGE' characters.


 -- procedure: string-split-fields
          (string-split-fields REGEXP STRING [MODE [START]])
     Splits `STRING' into a list of fields according to `MODE', where
     `MODE' can be the keyword `#:infix' (`REGEXP' matches field
     separator), the keyword `#:suffix' (`REGEXP' matches field
     terminator) or `#t' (`REGEXP' matches field), which is the default.

          (define s "this is a string 1, 2, 3,")

          (string-split-fields "[^ ]+" s)

            => ("this" "is" "a" "string" "1," "2," "3,")

          (string-split-fields " " s #:infix)

            => ("this" "is" "a" "string" "1," "2," "3,")

          (string-split-fields "," s #:suffix))

            => ("this is a string 1" " 2" " 3")


 -- procedure: string-substitute
          (string-substitute REGEXP SUBST STRING [INDEX])
     Searches substrings in `STRING' that match `REGEXP' and
     substitutes them with the string `SUBST'. The substitution can
     contain references to subexpressions in `REGEXP' with the `\NUM'
     notation, where `NUM' refers to the NUMth parenthesized
     expression. The optional argument `INDEX' defaults to 1 and
     specifies the number of the match to be substituted. Any
     non-numeric index specifies that all matches are to be substituted.


     (string-substitute "([0-9]+) (eggs|chicks)"
                        "2 (1)" "99 eggs or 99 chicks" 2)
      ==> "99 eggs or chicks (99)"


 -- procedure: string-substitute*
          (string-substitute* STRING SMAP)
     Substitutes elements of `STRING' according to `SMAP'.  `SMAP'
     should be an association-list where each element of the list is a
     pair of the form `(MATCH . REPLACEMENT)'. Every occurrence of the
     regular expression `MATCH' in `STRING' will be replaced by the
     string `REPLACEMENT'


     (string-substitute* "<h1>Hello, world!</h1>"
                         '(("<[/A-Za-z0-9]+>" . ""))))

     ==>  "Hello, world!"


File: chicken.info,  Node: Unit syntax-case,  Next: Unit srfi-18,  Prev: Unit regex,  Up: Supported language

5.17 Unit syntax-case
=====================

Hieb's and Dybvig's hygienic macro package. Provides `syntax-case' and
`syntax-rules'. A postscript manual can be found here: Technical Report
#356

   Notes:
   * The alternative form
     (define-syntax (keyword var)
       (syntax-case var (...) ...) )
      is allowed for `define-syntax'.

   * The module system described in the Chez Scheme Uses Manual is
     supported (including separate compilation). When `import' or
     `import-only' is used with an argument that names a module that is
     currently not defined, then the current `include-path' (and the
     `repository-path' as well) is searched for a source-file of the
     same name (possibly with the extension `.scm'), which (if found)
     will be "visited" (it's module- and syntax-definitions are
     processed) using the procedure `visit'.  There are currently no
     built-in modules.

   * To use the macro-system in compiled or interpreted code, just give
     the `-hygienic' option to the compiler or interpreter. The
     `syntax-case' unit has only to be declared as used if compiled
     code invokes `macroexpand' or `eval' with high-level macro syntax
     forms.

   * `define-syntax' can not be used inside an `eval-when' form.


   Here is a small example that demonstrates separate compilation:

   Let's say we have one file `foo.scm' that defines a module:

     (module foo (pr (bar baz))
       (define pr print)
       (define baz 99)
       (define-syntax bar
         (syntax-rules ()
           [(_ x) (list baz 'x)] ) ) )

   and another that uses it (`use-foo.scm'):

     (load "foo.so")   ; (require 'foo) would also work

     (import foo)
     (pr (bar hello))

   Compiling the files like this will lead to one dynamically loadable
library and a plain executable:


$ csc -s -hygienic foo.scm
$ csc -hygienic use-foo.scm
$ use-foo
$ (99 hello)

   The `export' declaration can be used to export identifiers exported
from modules defined in a given source file. These exports will then be
visible as normal toplevel variables in external code that loads or
links with this file. The rationale behind this is to make it possible
to create libraries and extensions that use modules internally, but
still can be used in client code that doesn't use modules.

 -- procedure: visit
          (visit FILENAME)
     Reads all toplevel expressions from the given file and expands all
     syntax, extracting module- and syntax-information to be
     subsequently used during the current compilation or interpretation
     of modules.

 -- procedure: debug-expand
          (debug-expand EXP)
     Macro-expands the expression `EXP' and shows each expansion step,
     giving a choice of expanding the expression completely, advance to
     the next expansion step or aborting the expansion. This might be a
     useful tool for debugging complex macros.


File: chicken.info,  Node: Unit srfi-18,  Next: Unit format,  Prev: Unit syntax-case,  Up: Supported language

5.18 Unit srfi-18
=================

A simple multithreading package. This threading package follows largely
the specification of SRFI-18. For more information see the documentation
for SRFI-18 (http://srfi.schemers.org/srfi-18/srfi-18.html)

   Notes:

   * `thread-start!' accepts a thunk (a zero argument procedure) as
     argument, which is equivalent to `(thread-start! (make-thread
     THUNK))'.

   * When an uncaught exception (i.e. an error) is signalled in a
     thread other than the primordial thread and warnings are enabled
     (see: `enable-warnings', then a warning message is written to the
     port that is the value of `(current-error-port)'.

   * Blocking I/O will block all threads, except for some socket
     operations (see the section about the `tcp' unit). An exception is
     the read-eval-print loop on UNIX platforms: waiting for input will
     not block other threads, provided the current input port reads
     input from a console.

   * It is generally not a good idea for one thread to call a
     continuation created by another thread, if `dynamic-wind' is
     involved.

   * When more than one thread compete for the current time-slice, the
     thread that was waiting first will become the next runnable thread.

   * The dynamic environment of a thread consists of the following
     state:

        * The current input-, output- and error-port

        * The current exception handler

        * The values of all current parameters (created by
          `make-parameter')

        * Any pending `dynamic-wind' thunks.



   The following procedures are provided, in addition to the procedures
defined in SRFI-18:

 -- procedure: thread-deliver-signal!
          (thread-deliver-signal! THREAD X)
     This will cause `THREAD' to signal the condition `X' once it is
     scheduled for execution. After signalling the condition, the
     thread continues with its normal execution.


 -- procedure: thread-quantum
          (thread-quantum THREAD)
     Returns the quantum of `THREAD', which is an exact integer
     specifying the approximate time-slice of the thread.


 -- procedure: thread-quantum-set!
          (thread-quantum-set! THREAD QUANTUM)
     Sets the quantum of `THREAD' to `QUANTUM'.


File: chicken.info,  Node: Unit format,  Next: Unit posix,  Prev: Unit srfi-18,  Up: Supported language

5.19 Unit format
================

 -- procedure: format
          (format DESTINATION FORMAT-STRING . ARGUMENTS)
     An almost complete implementation of Common LISP format description
     according to the CL reference book Common LISP from Guy L.
     Steele, Digital Press. This code was originally part of SLIB. The
     author is Dirk Lutzebaeck.

     Returns `#t', `#f' or a string; has side effect of printing
     according to `FORMAT-STRING'.  If `DESTINATION' is `#t', the
     output is to the current output port and `#t' is returned.  If
     `DESTINATION' is `#f', a formatted string is returned as the
     result of the call.  If `DESTINATION' is a string, `DESTINATION'
     is regarded as the format string; `FORMAT-STRING' is then the
     first argument and the output is returned as a string. If
     `DESTINATION' is a number, the output is to the value of
     `(current-error-port)'.  Otherwise `DESTINATION' must be an output
     port and `#t' is returned.

     `FORMAT-STRING' must be a string.  In case of a formatting error
     format returns `#f' and prints a message on the value of
     `(current-error-port)'.  Characters are output as if the string
     were output by the `display' function with the exception of those
     prefixed by a tilde (~).  For a detailed description of the
     `FORMAT-STRING' syntax please consult a Common LISP format
     reference manual. A list of all supported, non-supported and
     extended directives can be found in `format.txt'.

     This unit uses definitions from the `extras' unit.

     `format' implements SRFI-28
     (http//srfi.schemers.org/srfi-28/srfi-28.html)


File: chicken.info,  Node: Unit posix,  Next: Unit utils,  Prev: Unit format,  Up: Supported language

5.20 Unit posix
===============

This unit provides services as used on many UNIX-like systems.  Note
that the following definitions are not all available on non-UNIX
systems like Windows or DOS. See below for Windows specific notes.

   This unit uses the `regex', `scheduler', `extras' and `utils' units.

   All errors related to failing file-operations will signal a condition
of kind `(exn i/o file)'.

* Menu:

* Directories::
* Pipes::
* Fifos::
* File descriptors and low-level I/O::
* Retrieving file attributes::
* Changing file attributes::
* Processes::
* Symbolic links::
* Permissions::
* Record locking::
* Signal handling::
* Environment access::
* Memory mapped I/O::
* Time routines::
* Raw exit::
* ERRNO values::
* Finding files::
* Getting the hostname and system information::
* Setting a files buffering mode::
* Terminal ports::
* How Scheme procedures relate to UNIX C functions::
* Windows specific notes::


File: chicken.info,  Node: Directories,  Next: Pipes,  Up: Unit posix

5.20.1 Directories
------------------

 -- procedure: change-directory
          (change-directory NAME)
     Changes the current working directory to `NAME'.


 -- procedure: current-directory
          (current-directory)
     Returns the name of the current working directory.


 -- procedure: create-directory
          (create-directory NAME)
     Creates a directory with the pathname `NAME'.


 -- procedure: delete-directory
          (delete-directory NAME)
     Deletes the directory with the pathname `NAME'. The directory has
     to be empty.


 -- procedure: directory
          (directory PATHNAME)
     Returns a list with all files that are contained in the directory
     with the name `PATHNAME'.


 -- procedure: directory?
          (directory? NAME)
     Returns `#t' if there exists a file with the name `NAME' and if
     that file is a directory, or `#f' otherwise.


 -- procedure: glob
          (glob PATTERN1 ...)
     Returns a list of the pathnames of all existing files matching
     `PATTERN1 ...', which should be strings containing the usual
     file-patterns (with `*' matching zero or more characters and `?'
     matching zero or one character).

 -- procedure: set-root-directory!
          (set-root-directory! STRING)
     Sets the root directory for the current process to the path given
     in `STRING' (using the `chroot' function).  If the current process
     has no root permissions, the operation will fail.


File: chicken.info,  Node: Pipes,  Next: Fifos,  Prev: Directories,  Up: Unit posix

5.20.2 Pipes
------------

 -- procedure: call-with-input-pipe
 -- procedure: call-with-output-pipe
          (call-with-input-pipe CMDLINE PROC [MODE])
          (call-with-output-pipe CMDLINE PROC [MODE])
     Call `PROC' with a single argument: a input- or output port for a
     pipe connected to the subprocess named in `CMDLINE'. If `PROC'
     returns normally, the pipe is closed and any result values are
     returned.


 -- procedure: close-input-pipe
 -- procedure: close-output-pipe
          (close-input-pipe PORT)
          (close-output-pipe PORT)
     Closes the pipe given in `PORT' and waits until the connected
     subprocess finishes.


 -- procedure: create-pipe
          (create-pipe)
     The fundamental pipe-creation operator. Calls the C function
     `pipe()' and returns 2 values: the file-descriptors of the input-
     and output-ends of the pipe.


 -- procedure: open-input-pipe
          (open-input-pipe CMDLINE [MODE])
     Spawns a subprocess with the command-line string `CMDLINE' and
     returns a port, from which the output of the process can be read.
     If `MODE' is specified, it should be the keyword `#:text' (the
     default) or `#:binary'.


 -- procedure: open-output-pipe
          (open-output-pipe CMDLINE [MODE])
     Spawns a subprocess with the command-line string `CMDLINE' and
     returns a port. Anything written to that port is treated as the
     input for the process.  If `MODE' is specified, it should be the
     keyword `#:text' (the default) or `#:binary'.


 -- limit: pipe/buf
     This variable contains the maximal number of bytes that can be
     written atomically into a pipe or FIFO.


 -- procedure: with-input-from-pipe
 -- procedure: with-output-to-pipe
          (with-input-from-pipe CMDLINE THUNK [MODE])
          (with-output-to-pipe CMDLINE THUNK [MODE])
     Temporarily set the value of
     `current-input-port/current-output-port' to a port for a pipe
     connected to the subprocess named in `CMDLINE' and call the
     procedure `THUNK' with no arguments. After `THUNK' returns
     normally the pipe is closed and the standard input-/output port is
     restored to its previous value and any result values are returned.


     (with-output-to-pipe
       "gs -dNOPAUSE -sDEVICE=jpeg -dBATCH -sOutputFile=signballs.jpg -g600x600 -q -"
       (lambda ()
         (print #<<EOF
     %!IOPSC-1993 %%Creator: HAYAKAWA Takashi<xxxxxxxx@xx.xxxxxx.xx.xx>
     /C/neg/d/mul/R/rlineto/E/exp/H{{cvx def}repeat}def/T/dup/g/gt/r/roll/J/ifelse 8
     H/A/copy(z&v4QX&93r9AxYQOZomQalxS2w!!O&vMYa43d6r93rMYvx2dca!D&cjSnjSnjjS3o!v&6A
     X&55SAxM1CD7AjYxTTd62rmxCnTdSST0g&12wECST!&!J0g&D1!&xM0!J0g!l&544dC2Ac96ra!m&3A
     F&&vGoGSnCT0g&wDmlvGoS8wpn6wpS2wTCpS1Sd7ov7Uk7o4Qkdw!&Mvlx1S7oZES3w!J!J!Q&7185d
     Z&lx1CS9d9nE4!k&X&MY7!&1!J!x&jdnjdS3odS!N&mmx1C2wEc!G&150Nx4!n&2o!j&43r!U&0777d
     ]&2AY2A776ddT4oS3oSnMVC00VV0RRR45E42063rNz&v7UX&UOzF!F!J![&44ETCnVn!a&1CDN!Y&0M
     V1c&j2AYdjmMdjjd!o&1r!M){( )T 0 4 3 r put T(/)g{T(9)g{cvn}{cvi}J}{($)g[]J}J
     cvx}forall/moveto/p/floor/w/div/S/add 29 H[{[{]setgray fill}for Y}for showpage
     EOF
     ) ) )


File: chicken.info,  Node: Fifos,  Next: File descriptors and low-level I/O,  Prev: Pipes,  Up: Unit posix

5.20.3 Fifos
------------

 -- procedure: create-fifo
          (create-fifo FILENAME [MODE])
     Creates a FIFO with the name `FILENAME' and the permission bits
     `MODE', which defaults to


     (+ perm/irwxu perm/irwxg perm/irwxo)


 -- procedure: fifo?
          (fifo? FILENAME)
     Returns `#t' if the file with the name `FILENAME' names a FIFO.


File: chicken.info,  Node: File descriptors and low-level I/O,  Next: Retrieving file attributes,  Prev: Fifos,  Up: Unit posix

5.20.4 File descriptors and low-level I/O
-----------------------------------------

 -- procedure: duplicate-fileno
          (duplicate-fileno OLD [NEW])
     If `NEW' is given, then the file-descriptor `NEW' is opened to
     access the file with the file-descriptor `OLD'. Otherwise a fresh
     file-descriptor accessing the same file as `OLD' is returned.


 -- procedure: file-close
          (file-close FILENO)
     Closes the input/output file with the file-descriptor `FILENO'.


 -- procedure: file-open
          (file-open FILENAME FLAGS [MODE])
     Opens the file specified with the string `FILENAME' and open-flags
     `FLAGS' using the C function `open()'. On success a
     file-descriptor for the opened file is returned.  `FLAGS' should
     be a bitmask containing one or more of the `open/...' values ored
     together using `bitwise-ior' (or simply added together).  The
     optional `MODE' should be a bitmask composed of one or more
     permission values like `perm/irusr' and is only relevant when a
     new file is created. The default mode is `perm/irwxu | perm/irgrp
     | perm/iroth'.


 -- procedure: file-mkstemp
          (file-mkstemp TEMPLATE-FILENAME)
     Create a file based on the given `TEMPLATE-FILENAME', in which the
     six last characters must be "XXXXXX".  These will be replaced with
     a string that makes the filename unique.  The file descriptor of
     the created file and the generated filename is returned.  See the
     `mkstemp(3)' manual page for details on how this function works.
     The template string given is not modified.

     Example usage:
     (let-values (((fd temp-path) (file-mkstemp "/tmp/mytemporary.XXXXXX")))
       (let ((temp-port (open-output-file* fd)))
         (format temp-port "This file is ~A.~%" temp-path)
         (close-output-port temp-port)))


 -- procedure: file-read
          (file-read FILENO SIZE [BUFFER])
     Reads `SIZE' bytes from the file with the file-descriptor
     `FILENO'.  If a string or bytevector is passed in the optional
     argument `BUFFER', then this string will be destructively modified
     to contain the read data. This procedure returns a list with two
     values: the buffer containing the data and the number of bytes
     read.


 -- procedure: file-select
          (file-select READFDLIST WRITEFDLIST [TIMEOUT])
     Waits until any of the file-descriptors given in the lists
     `READFDLIST' and `WRITEFDLIST' is ready for input or output,
     respectively. If the optional argument `TIMEOUT' is given and not
     false, then it should specify the number of seconds after which
     the wait is to be aborted. This procedure returns two values: the
     lists of file-descriptors ready for input and output, respectively.
     `READFDLIST' and WRITEFDLIST may also by file-descriptors instead
     of lists.  In this case the returned values are booleans
     indicating whether input/output is ready by `#t' or `#f'
     otherwise.  You can also pass `#f' as `READFDLIST' or
     `WRITEFDLIST' argument, which is equivalent to `()'.


 -- procedure: file-write
          (file-write FILENO BUFFER [SIZE])
     Writes the contents of the string or bytevector `BUFFER' into the
     file with the file-descriptor `FILENO'. If the optional argument
     `SIZE' is given, then only the specified number of bytes are
     written.

 -- file descriptor: fileno/stdin
 -- file descriptor: fileno/stdout
 -- file descriptor: fileno/stderr
     These variables contain file-descriptors for the standard I/O
     files.

 -- flag: open/rdonly
 -- flag: open/wronly
 -- flag: open/rdwr
 -- flag: open/read
 -- flag: open/write
 -- flag: open/creat
 -- flag: open/append
 -- flag: open/excl
 -- flag: open/noctty
 -- flag: open/nonblock
 -- flag: open/trunc
 -- flag: open/sync
 -- flag: open/fsync
 -- flag: open/binary
 -- flag: open/text
     Flags for use with `file-open'.

 -- procedure: open-input-file*
 -- procedure: open-output-file*
          (open-input-file* FILENO [OPENMODE])
          (open-output-file* FILENO [OPENMODE])
     Opens file for the file-descriptor `FILENO' for input or output
     and returns a port.  `FILENO' should be a positive exact integer.
     `OPENMODE' specifies an additional mode for opening the file
     (currently only the keyword `#:append' is supported, which opens
     an output-file for appending).

 -- procedure: port->fileno
          (port->fileno PORT)
     If `PORT' is a file-port, then a file-descriptor is returned for
     this port. Otherwise an error is signaled.


File: chicken.info,  Node: Retrieving file attributes,  Next: Changing file attributes,  Prev: File descriptors and low-level I/O,  Up: Unit posix

5.20.5 Retrieving file attributes
---------------------------------

 -- procedure: file-access-time
 -- procedure: file-change-time
 -- procedure: file-modification-time
          (file-access-time FILE)
          (file-change-time FILE)
          (file-modification-time FILE)
     Returns time (in seconds) of the last acces, modification or
     change of `FILE'. `FILE' may be a filename or a file-descriptor.
     If the file does not exist, an error is signaled.

 -- procedure: file-stat
          (file-stat FILE)
     Returns a 9-element vector with the following contents:
     inode-number, mode (as with `file-permissions'), number of hard
     links, uid of owner (as with `file-owner'), gid of owner, size (as
     with `file-size') and access-, change- and modification-time (as
     with `file-access-time', `file-change-time' and
     `file-modification-time').


 -- procedure: file-position
          (file-position FILE)
     Returns the current file position of `FILE', which should be a
     port or a file-descriptor.


 -- procedure: file-size
          (file-size FILENAME)
     Returns the size of the file designated by `FILE'.  `FILE' may be
     a filename or a file-descriptor.  If the file does not exist, an
     error is signaled.


File: chicken.info,  Node: Changing file attributes,  Next: Processes,  Prev: Retrieving file attributes,  Up: Unit posix

5.20.6 Changing file attributes
-------------------------------

 -- procedure: file-truncate
          (file-truncate FILE OFFSET)
     Truncates the file `FILE' to the length `OFFSET', which should be
     an integer. If the file-size is smaller or equal to `OFFSET' then
     nothing is done.  `FILE' should be a filename or a file-descriptor.


 -- procedure: set-file-position!
          (set-file-position! FILE POSITION [WHENCE])
     Sets the current read/write position of `FILE' to `POSITION',
     which should be an exact integer. `FILE' should be a port or a
     file-descriptor.  `WHENCE' specifies how the position is to
     interpreted and should be one of the values `seek/set, seek/cur'
     and `seek/end'. It defaults to `seek/set'.

     Exceptions: `(exn bounds)', `(exn i/o file)'


File: chicken.info,  Node: Processes,  Next: Symbolic links,  Prev: Changing file attributes,  Up: Unit posix

5.20.7 Processes
----------------

 -- procedure: current-process-id
          (current-process-id)
     Returns the process ID of the current process.


 -- procedure: parent-process-id
          (parent-process-id)
     Returns the process ID of the parent of the current process.


 -- procedure: process-execute
          (process-execute PATHNAME [LIST])
     Creates a new child process and replaces the running process with
     it using the UNIX system call `execv()'. If the optional argument
     `LIST' is given, then it should contain a list of strings which
     are passed as arguments to the subprocess.


 -- procedure: process-fork
          (process-fork [THUNK])
     Creates a new child process with the UNIX system call `fork()'.
     Returns either the PID of the child process or 0. If `THUNK' is
     given, then the child process calls it as a procedure with no
     arguments and terminates.


 -- procedure: process-run
          (process-run PATHNAME [LIST])
     Creates a new child process using the UNIX system call `fork()'
     that executes the program given by the string `PATHNAME' using the
     UNIX system call `execv()'.  The PID of the new process is
     returned. If `LIST' is not specified, then `PATHNAME' is passed to
     a program named by the environment variable `SHELL' (or `/bin/sh',
     if the variable is not defined), so usual argument expansion can
     take place.


 -- procedure: process-signal
          (process-signal PID [SIGNAL])
     Sends `SIGNAL' to the process with the id `PID' using the UNIX
     system call `kill()'. `SIGNAL' defaults to the value of the
     variable `signal/term'.


 -- procedure: process-wait
          (process-wait [PID [NOHANG]])
     Suspends the current process until the child process with the id
     `PID' has terminated using the UNIX system call `waitpid()'. If
     `PID' is not given, then this procedure waits for any child
     process. If `NOHANG' is given and not `#f' then the current
     process is not suspended.  This procedure returns three values:

   * `PID' or 0, if `NOHANG' is true and the child process has not
     terminated yet;

   * `#t' if the process exited normally or `#f' otherwise;

   * either the exit status, if the process terminated normally or the
     signal number that terminated/stopped the process.

 -- procedure: process
          (process COMMANDLINE)
     Passes the string `COMMANDLINE' to the host-system's shell that is
     invoked as a subprocess and returns three values: an input port
     from which data written by the sub-process can be read, an output
     port from which any data written to will be received as input in
     the sub-process and the process-id of the started sub-process.
     Blocking reads and writes to or from the ports returned by
     `process' only block the current thread, not other threads
     executing concurrently.


 -- procedure: sleep
          (sleep SECONDS)
     Puts the process to sleep for `SECONDS'. Returns either 0 if the
     time has completely elapsed, or the number of remaining seconds,
     if a signal occurred.


File: chicken.info,  Node: Symbolic links,  Next: Permissions,  Prev: Processes,  Up: Unit posix

5.20.8 Symbolic links
---------------------

 -- procedure: create-symbolic-link
          (create-symbolic-link OLDNAME NEWNAME)
     Creates a symbolic link with the filename `NEWNAME' that points to
     the file named `OLDNAME'.


 -- procedure: read-symbolic-link
          (read-symbolic-link FILENAME)
     Returns the filename to which the symbolic link `FILENAME' points.


File: chicken.info,  Node: Permissions,  Next: Record locking,  Prev: Symbolic links,  Up: Unit posix

5.20.9 Permissions, owners, users and groups
--------------------------------------------

 -- procedure: file-owner
          (file-owner FILE)
     Returns the user-id of `FILE'.  `FILE' may be a filename or a
     file-descriptor.


 -- procedure: file-permissions
          (file-permissions FILE)
     Returns the permission bits for `FILE'. You can test this value by
     performing bitwise operations on the result and the `perm/...'
     values.  `FILE' may be a filename or a file-descriptor.


 -- procedure: file-read-access?
 -- procedure: file-write-access?
 -- procedure: file-execute-access?
          (file-read-access? FILENAME)
          (file-write-access? FILENAME)
          (file-execute-access? FILENAME)
     These procedures return `#t' if the current user has read, write
     or execute permissions on the file named `FILENAME'.


 -- procedure: change-file-mode
          (change-file-mode FILENAME MODE)
     Changes the current file mode of the file named `FILENAME' to
     `MODE' using the `chmod()' system call.  The `perm/...' variables
     contain the various permission bits and can be combinded with the
     `bitwise-ior' procedure.


 -- procedure: change-file-owner
          (change-file-owner FILENAME UID GID)
     Changes the owner information of the file named `FILENAME' to the
     user- and group-ids `UID' and `GID' (which should be exact
     integers) using the `chown()' system call.


 -- procedure: current-user-id
 -- procedure: current-group-id
 -- procedure: current-effective-user-id
 -- procedure: current-effective-group-id
          (current-user-id)
          (current-group-id)
          (current-effective-user-id)
          (current-effective-group-id)
     Return the user- and group-ids of the current process.

      -- procedure: process-group-id
               (process-group-id PID)
          Returns the process group ID of the process specified by
          `PID'.


 -- procedure: group-information
          (group-information GROUP)
     If `GROUP' specifies a valid group-name or group-id, then this
     procedure returns four values: the group-name, the encrypted group
     password, the group ID and a list of the names of all group
     members. If no group with the given name or ID exists, then `#f'
     is returned.

 -- procedure: get-groups
          (get-groups)
     Returns a list with the supplementary group IDs of the current
     user.

 -- procedure: set-groups!
          (set-groups! GIDLIST)
     Sets the supplementrary group IDs of the current user to the IDs
     given in the list `GIDLIST'.

     Only the superuser may invoke this procedure.

 -- procedure: initialize-groups
          (initialize-groups USERNAME BASEGID)
     Sets the supplementrary group IDs of the current user to the IDs
     from the user with name `USERNAME' (a string), including `BASEGID'.

     Only the superuser may invoke this procedure.

 -- permission bits: perm/irusr
 -- permission bits: perm/iwusr
 -- permission bits: perm/ixusr
 -- permission bits: perm/irgrp
 -- permission bits: perm/iwgrp
 -- permission bits: perm/ixgrp
 -- permission bits: perm/iroth
 -- permission bits: perm/iwoth
 -- permission bits: perm/ixoth
 -- permission bits: perm/irwxu
 -- permission bits: perm/irwxg
 -- permission bits: perm/irwxo
 -- permission bits: perm/isvtx
 -- permission bits: perm/isuid
 -- permission bits: perm/isgid
     These variables contain permission bits as used in
     `change-file-mode'.

 -- procedure: set-user-id!
          (set-user-id! UID)
     Sets the effective user id of the current process to `UID', which
     should be a positive integer.

 -- procedure: set-group-id!
          (set-group-id! GID)
     Sets the effective group id of the current process to `GID', which
     should be a positive integer.

 -- procedure: set-process-group-id!
          (set-user-id! PID PGID)
     Sets the process group ID of the process specifed by `PID' to
     `PGID'.

 -- procedure: user-information
          (user-information USER)
     If `USER' specifes a valid username (as a string) or user ID, then
     the user database is consulted and a list of 7 values are
     returned: the user-name, the encrypted password, the user ID, the
     group ID, a user-specific string, the home directory and the
     default shell. If no user with this name or ID can be found, then
     `#f' is returned.

 -- procedure: create-session
          (create-session)
     Creates a new session if the calling process is not a process
     group leader and returns the session ID.


File: chicken.info,  Node: Record locking,  Next: Signal handling,  Prev: Permissions,  Up: Unit posix

5.20.10 Record locking
----------------------

 -- procedure: file-lock
          (file-lock PORT [START [LEN]])
     Locks the file associated with `PORT' for reading or writing
     (according to whether `PORT' is an input- or output-port). `START'
     specifies the starting position in the file to be locked and
     defaults to 0. `LEN' specifies the length of the portion to be
     locked and defaults to `#t', which means the complete file.
     `file-lock' returns a "lock"-object.


 -- procedure: file-lock/blocking
          (file-lock/blocking PORT [START [LEN]])
     Similar to `file-lock', but if a lock is held on the file, the
     current process blocks (including all threads) until the lock is
     released.


 -- procedure: file-test-lock
          (file-test-lock PORT [START [LEN]])
     Tests whether the file associated with `PORT' is locked for reading
     or writing (according to whether `PORT' is an input- or
     output-port) and returns either `#f' or the process-id of the
     locking process.


 -- procedure: file-unlock
          (file-unlock LOCK)
     Unlocks the previously locked portion of a file given in `LOCK'.


File: chicken.info,  Node: Signal handling,  Next: Environment access,  Prev: Record locking,  Up: Unit posix

5.20.11 Signal handling
-----------------------

 -- procedure: set-alarm!
          (set-alarm! SECONDS)
     Sets an internal timer to raise the `signal/alrm' after `SECONDS'
     are elapsed.  You can use the `set-signal-handler!' procedure to
     write a handler for this signal.


 -- procedure: set-signal-handler!
          (set-signal-handler! SIGNUM PROC)
     Establishes the procedure of one argument `PROC' as the handler
     for the signal with the code `SIGNAL'. `PROC' is called with the
     signal number as its sole argument. If the argument `PROC' is `#f'
     then this signal will be ignored.


 -- procedure: set-signal-mask!
          (set-signal-mask! SIGLIST)
     Sets the signal mask of the current process to block all signals
     given in the list `SIGLIST'.  Signals masked in that way will not
     be delivered to the current process.

 -- signal code: signal/term
 -- signal code: signal/kill
 -- signal code: signal/int
 -- signal code: signal/hup
 -- signal code: signal/fpe
 -- signal code: signal/ill
 -- signal code: signal/segv
 -- signal code: signal/abrt
 -- signal code: signal/trap
 -- signal code: signal/quit
 -- signal code: signal/alrm
 -- signal code: signal/vtalrm
 -- signal code: signal/prof
 -- signal code: signal/io
 -- signal code: signal/urg
 -- signal code: signal/chld
 -- signal code: signal/cont
 -- signal code: signal/stop
 -- signal code: signal/tstp
 -- signal code: signal/pipe
 -- signal code: signal/xcpu
 -- signal code: signal/xfsz
 -- signal code: signal/usr1
 -- signal code: signal/usr2
 -- signal code: signal/winch
     These variables contain signal codes for use with `process-signal'
     or `set-signal-handler!'.


File: chicken.info,  Node: Environment access,  Next: Memory mapped I/O,  Prev: Signal handling,  Up: Unit posix

5.20.12 Environment access
--------------------------

 -- procedure: current-environment
          (current-environment)
     Returns a association list of the environment variables and their
     current values.

     Note: Under Mac OS X, this procedure always returns the empty list.


 -- procedure: setenv
          (setenv VARIABLE VALUE)
     Sets the environment variable named `VARIABLE' to `VALUE'. Both
     arguments should be strings. If the variable is not defined in the
     environment, a new definition is created.


 -- procedure: unsetenv
          (unsetenv VARIABLE)
     Removes the definition of the environment variable `VARIABLE' from
     the environment of the current process. If the variable is not
     defined, nothing happens.


File: chicken.info,  Node: Memory mapped I/O,  Next: Time routines,  Prev: Environment access,  Up: Unit posix

5.20.13 Memory mapped I/O
-------------------------

 -- pocedure: memory-mapped-file?
          (memory-mapped-file? X)
     Returns `#t', if `X' is an object representing a memory mapped
     file, or `#f' otherwise.

 -- procedure: map-file-to-memory
          (map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])
     Maps a section of a file to memory using the C function `mmap()'.
     `ADDRESS' should be a foreign pointer object or `#f'; `LEN'
     specifies the size of the section to be mapped; `PROTECTION'
     should be one or more of the flags `prot/read, prot/write,
     prot/exec' or `prot/none' bitwise-iored together; `FLAG' should be
     one or more of the flags `map/fixed, map/shared, map/private,
     map/anonymous' or `map/file'; `FILENO' should be the
     file-descriptor of the mapped file. The optional argument `OFFSET'
     gives the offset of the section of the file to be mapped and
     defaults to 0. This procedure returns an object representing the
     mapped file section.  The procedure `move-memory!' can be used to
     access the mapped memory.


 -- procedure: memory-mapped-file-pointer
          (memory-mapped-file-pointer MMAP)
     Returns a machine pointer to the start of the memory region to
     which the file is mapped.


 -- procedure: unmap-file-from-memory
          (unmap-file-from-memory MMAP [LEN])
     Unmaps the section of a file mapped to memory using the C function
     `munmap()'.  `MMAP' should be a mapped file as returned by the
     procedure `map-file-to-memory'.  The optional argument `LEN'
     specifies the length of the section to be unmapped and defaults to
     the complete length given when the file was mapped.


File: chicken.info,  Node: Time routines,  Next: Raw exit,  Prev: Memory mapped I/O,  Up: Unit posix

5.20.14 Time routines
---------------------

 -- procedure: seconds->local-time
          (seconds->local-time SECONDS)
     Breaks down the time value represented in `SECONDS' into a 10
     element vector of the form `#(seconds minutes hours mday month
     year wday yday dstflag timezone)', in the following format:

        * seconds: the number of seconds after the minute (0 - 59)

        * minutes: the number of minutes after the hour (0 - 59)

        * hours: the number of hours past midnight (0 - 23)

        * mday: the day of the month (1 - 31)

        * month: the number of months since january (0 - 11)

        * year: the number of years since 1900

        * wday: the number of days since Sunday (0 - 6)

        * yday: the number of days since January 1 (0 - 365)

        * dstflag: a flag that is true if Daylight Saving Time is in
          effect at the time described.

        * timezone: the difference between UTC and the latest local
          standard time, in seconds west of UTC.


 -- procedure: seconds->string
          (seconds->string SECONDS)
     Converts the local time represented in `SECONDS' into a string of
     the form `"Tue May 21 13:46:22 1991\n"'.


 -- procedure: seconds->utc-time
          (seconds->utc-time SECONDS)
     Similar to `seconds->local-time', but interpretes `SECONDS' as UTC
     time.


 -- procedure: time->string
          (time->string VECTOR)
     Converts the broken down time represented in the 10 element vector
     `VECTOR' into a string of the form `"Tue May 21 13:46:22 1991\n"'.


File: chicken.info,  Node: Raw exit,  Next: ERRNO values,  Prev: Time routines,  Up: Unit posix

5.20.15 _Raw_ exit
------------------

 -- procedure: _exit
          (_exit [CODE])
     Exits the current process without flushing any buffered output
     (using the C function `_exit').  Note that the `exit-handler' is
     not called when this procedure is invoked. The optional return-code
     `CODE' defaults to `0'.


File: chicken.info,  Node: ERRNO values,  Next: Finding files,  Prev: Raw exit,  Up: Unit posix

5.20.16 ERRNO values
--------------------

 -- error code: errno/perm
 -- error code: errno/noent
 -- error code: errno/srch
 -- error code: errno/intr
 -- error code: errno/io
 -- error code: errno/noexec
 -- error code: errno/badf
 -- error code: errno/child
 -- error code: errno/nomem
 -- error code: errno/acces
 -- error code: errno/fault
 -- error code: errno/busy
 -- error code: errno/notdir
 -- error code: errno/isdir
 -- error code: errno/inval
 -- error code: errno/mfile
 -- error code: errno/nospc
 -- error code: errno/spipe
 -- error code: errno/pipe
 -- error code: errno/again
 -- error code: errno/rofs
 -- error code: errno/wouldblock
     These variables contain error codes as returned by `errno'.


File: chicken.info,  Node: Finding files,  Next: Getting the hostname and system information,  Prev: ERRNO values,  Up: Unit posix

5.20.17 Finding files
---------------------

 -- procedure: find-files
          (find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])
     Recursively traverses the contents of `DIRECTORY' (which should be
     a string) and invokes the procedure `ACTION' for all files for
     which the procedure `PREDICATE' is true.  `PREDICATE' may me a
     procedure of one argument or a regular-expression string.
     `ACTION' should be a procedure of two arguments: the currently
     encountered file and the result of the previous invocation of
     `ACTION', or, if this is the first invocation, the value of
     `IDENTITY'. `ACTION' defaults to `cons', `IDENTITY' defaults to
     `()'.  `LIMIT' should a procedure of one argument that is called
     for each nested directory and which should return true, if that
     directory is to be traversed recursively. `LIMIT' may also be an
     exact integer that gives the maximum recursion depth. A depth of
     `0' means the files in the specified directory are traversed but
     not any nested directories. `LIMIT' may also be `#f' (the default),
     which is equivalent to `(constantly #t)'.

     Note that `ACTION' is called with the full pathname of each file,
     including the directory prefix.


File: chicken.info,  Node: Getting the hostname and system information,  Next: Setting a files buffering mode,  Prev: Finding files,  Up: Unit posix

5.20.18 Getting the hostname and system information
---------------------------------------------------

 -- procedure: get-host-name
          (get-host-name)
     Returns the hostname of the machine that this process is running
     on.


 -- procedure: system-information
          (system-information)
     Invokes the UNIX system call `uname()' and returns 5 values:
     system-name, node-name, OS release, OS version and machine.


File: chicken.info,  Node: Setting a files buffering mode,  Next: Terminal ports,  Prev: Getting the hostname and system information,  Up: Unit posix

5.20.19 Setting a files buffering mode
--------------------------------------

 -- procedure: set-buffering-mode!
          (set-buffering-mode! PORT MODE [BUFSIZE])
     Sets the buffering-mode for the file associated with `PORT' to
     `MODE', which should be one of the keywords `#:full, #:line' or
     `#:none'. If `BUFSIZE' is specified it determines the size of the
     buffer to be used (if any).


File: chicken.info,  Node: Terminal ports,  Next: How Scheme procedures relate to UNIX C functions,  Prev: Setting a files buffering mode,  Up: Unit posix

5.20.20 Terminal ports
----------------------

 -- procedure: terminal-name
          (terminal-name PORT)
     Returns the name of the terminal that is connected to `PORT'.


 -- procedure: terminal-port?
          (terminal-port? PORT)
     Returns `#t' if `PORT' is connected to a terminal and `#f'
     otherwise.


File: chicken.info,  Node: How Scheme procedures relate to UNIX C functions,  Next: Windows specific notes,  Prev: Terminal ports,  Up: Unit posix

5.20.21 How Scheme procedures relate to UNIX C functions
--------------------------------------------------------

`change-directory'
     chdir

`change-file-mode'
     chmod

`change-file-owner'
     chown

`create-directory'
     mkdir

`create-fifo'
     mkfifo

`create-pipe'
     pipe

`create-session'
     setsid

`create-symbolic-link'
     link

`current-directory'
     curdir

`current-effective-groupd-id'
     getegid

`current-effective-user-id'
     geteuid

`current-group-id'
     getgid

`current-parent-id'
     getppid

`current-process-id'
     getpid

`current-user-id'
     getuid

`delete-directory'
     rmdir

`duplicate-fileno'
     dup/dup2

`_exit'
     _exit

`file-close'
     close

`file-access-time'
     stat

`file-change-time'
     stat

`file-modification-time'
     stat

`file-execute-access?'
     access

`file-open'
     open

`file-lock'
     fcntl

`file-position'
     ftell/lseek

`file-read'
     read

`file-read-access?'
     access

`file-select'
     select

`file-stat'
     stat

`file-test-lock'
     fcntl

`file-truncate'
     truncate/ftruncate

`file-unlock'
     fcntl

`file-write'
     write

`file-write-access?'
     access

`get-groups'
     getgroups

`get-host-name'
     gethostname

`initialize-groups'
     initgroups

`map-file-to-memory'
     mmap

`open-input-file*'
     fdopen

`open-output-file*'
     fdopen

`open-input-pipe'
     popen

`open-output-pipe'
     popen

`port->fileno'
     fileno

`process-execute'
     execvp

`process-fork'
     fork

`process-group-id'
     getpgid

`process-signal'
     kill

`process-wait'
     waitpid

`close-input-pipe'
     pclose

`close-output-pipe'
     pclose

`read-symbolic-link'
     readlink

`seconds->local-time'
     localtime

`seconds->string'
     ctime

`seconds->utc-time'
     gmtime

`set-alarm!'
     alarm

`set-buffering-mode!'
     setvbuf

`set-file-position!'
     fseek/seek

`set-groups!'
     setgroups

`set-signal-mask!'
     sigprocmask

`set-group-id!'
     setgid

`set-process-group-id!'
     setpgid

`set-user-id!'
     setuid

`set-root-directory!'
     chroot

`setenv'
     setenv/putenv

`sleep'
     sleep

`system-information'
     uname

`terminal-name'
     ttyname

`terminal-port?'
     isatty

`time->string'
     asctime

`unsetenv'
     putenv

`unmap-file-from-memory'
     munmap

`user-information'
     getpwnam/getpwuid


File: chicken.info,  Node: Windows specific notes,  Prev: How Scheme procedures relate to UNIX C functions,  Up: Unit posix

5.20.22 Windows specific notes
------------------------------

The following definitions are not supported for native Windows builds
(compiled with the Microsoft tools or with MingW):


open/noctty  open/nonblock  open/fsync  open/sync
perm/isvtx  perm/isuid  perm/isgid
file-select
signal/...
set-signal-handler!  set-signal-mask!
user-information  group-information  get-groups  set-groups!  initialize-groups
errno/wouldblock
change-file-owner
current-user-id  current-group-id  current-effective-user-id  current-effective-groupd-id
set-user-id!  set-group-id!
create-session
process-group-id  set-process-group-id!
create-symbolic-link  read-symbolic-link
file-truncate
file-lock  file-lock/blocking  file-unlock  file-test-lock
create-fifo  fifo?
prot/...
map/...
map-file-to-memory  unmap-file-from-memory  memory-mapped-file-pointer  memory-mapped-file?
set-alarm!
terminal-port?  terminal-name
process-fork  process-signal
parent-process-id
set-root-directory!

   Additionally, the following definitions are only available for
Windows:

 -- spawn mode: spawn/overlay
 -- spawn mode: spawn/wait
 -- spawn mode: spawn/nowait
 -- spawn mode: spawn/nowaito
 -- spawn mode: spawn/detach
     These variables contains special flags that specify the exact
     semantics of `process-spawn': `spawn/overlay' replaces the current
     process with the new one.  `spawn/wait' suspends execution of the
     current process until the spawned process returns.  `spawn/nowait'
     does the opposite (`spawn/nowaito' is identical, according to the
     Microsoft documentation) and runs the process asynchronously.
     `spawn/detach' runs the new process in the background, without
     being attached to a console.

 -- procedure: process-spawn
          (process-spawn MODE FILENAME ARGUMENT ...)
     Creates and runs a new process with the given filename and
     command-line arguments. `MODE' specifies how exactly the process
     should be executed and must be one or more of the `spawn/...'
     flags defined above.


File: chicken.info,  Node: Unit utils,  Next: Unit tcp,  Prev: Unit posix,  Up: Supported language

5.21 Unit utils
===============

This unit contains some utility procedures for Shell scripting and for
some file operations.

   This unit uses the `extras' and `regex' units.

* Menu:

* Pathname operations::
* Temporary files::
* Deleting a file without signalling an error::
* Iterating over input lines and files::
* Executing shell commands with formatstring and error checking::
* Reading a file's contents::
* Miscellaneous handy things::


File: chicken.info,  Node: Pathname operations,  Next: Temporary files,  Up: Unit utils

5.21.1 Pathname operations
--------------------------

 -- procedure: absolute-pathname?
          (absolute-pathname? PATHNAME)
     Returns `#t' if the string `PATHNAME' names an absolute pathname,
     and returns `#f' otherwise.


 -- procedure: decompose-pathname
          (decompose-pathname PATHNAME)
     Returns three values: the directory-, filename- and
     extension-components of the file named by the string `PATHNAME'.
     For any component that is not contained in `PATHNAME', `#f' is
     returned.


 -- procedure: make-pathname
 -- procedure: make-absolute-pathname
          (make-pathname DIRECTORY FILENAME [EXTENSION])
          (make-absolute-pathname DIRECTORY FILENAME [EXTENSION])
     Returns a string that names the file with the components
     `DIRECTORY, FILENAME' and (optionally) `EXTENSION'. `DIRECTORY'
     can be `#f' (meaning no directory component), a string or a list
     of strings. `FILENAME' and `EXTENSION' should be strings or `#f'.
     `make-absolute-pathname' returns always an absolute pathname.

 -- procedure: pathname-directory
          (pathname-directory PATHNAME)

 -- procedure: pathname-file
          (pathname-file PATHNAME)

 -- procedure: pathname-extension
          (pathname-extension PATHNAME)
     Accessors for the components of `PATHNAME'. If the pathname does
     not contain the accessed component, then `#f' is returned.


 -- procedure: pathname-replace-directory
          (pathname-replace-directory PATHNAME DIRECTORY)

 -- procedure: pathname-replace-file
          (pathname-replace-file PATHNAME FILENAME)

 -- procedure: pathname-replace-extension
          (pathname-replace-extension PATHNAME EXTENSION)
     Return a new pathname with the specified component of `PATHNAME'
     replaced by a new value.


 -- procedure: pathname-strip-directory
          (pathname-strip-directory PATHNAME)

 -- procedure: pathname-strip-extension
          (pathname-strip-extension PATHNAME)
     Return a new pathname with the specified component of `PATHNAME'
     stripped.


File: chicken.info,  Node: Temporary files,  Next: Deleting a file without signalling an error,  Prev: Pathname operations,  Up: Unit utils

5.21.2 Temporary files
----------------------

 -- procedure: create-temporary-file
          (create-temporary-file [EXTENSION])
     Creates an empty temporary file and returns its pathname. If
     `EXTENSION' is not given, then `.tmp' is used. If the environment
     variable `TMPDIR, TEMP' or `TMP' is set, then the pathname names a
     file in that directory.   


File: chicken.info,  Node: Deleting a file without signalling an error,  Next: Iterating over input lines and files,  Prev: Temporary files,  Up: Unit utils

5.21.3 Deleting a file without signalling an error
--------------------------------------------------

 -- procedure: delete-file*
          (delete-file* FILENAME)
     If the file `FILENAME' exists, it is deleted and `#t' is returned.
     If the file does not exist, nothing happens and `#f' is returned.


File: chicken.info,  Node: Iterating over input lines and files,  Next: Executing shell commands with formatstring and error checking,  Prev: Deleting a file without signalling an error,  Up: Unit utils

5.21.4 Iterating over input lines and files
-------------------------------------------

 -- procedure: for-each-line
          (for-each-line PROCEDURE [PORT])
     Calls `PROCEDURE' for each line read from `PORT' (which defaults
     to the value of `(current-input-port)'. The argument passed to
     `PORCEDURE' is a string with the contents of the line, excluding
     any line-terminators.  When all input has been read from the port,
     `for-each-line' returns some unspecified value.


 -- procedure: for-each-argv-line
          (for-each-argv-line PROCEDURE)
      Opens each file listed on the command line in order, passing one
     line at a time into `PROCEDURE'.  The filename `-' is interpreted
     as `(current-input-port)'.  If no arguments are given on the
     command line it again uses the value of `(current-input-port)'.

     This code will act as a simple Unix cat(1) command:


     (for-each-argv-line print)


File: chicken.info,  Node: Executing shell commands with formatstring and error checking,  Next: Reading a file's contents,  Prev: Iterating over input lines and files,  Up: Unit utils

5.21.5 Executing shell commands with formatstring and error checking
--------------------------------------------------------------------

 -- procedure: system*
          (system* FORMATSTRING ARGUMENT1 ...)
     Similar to `(system (sprintf FORMATSTRING ARGUMENT1 ...))', but
     signals an error if the invoked program should return a nonzero
     exit status.


File: chicken.info,  Node: Reading a file's contents,  Next: Miscellaneous handy things,  Prev: Executing shell commands with formatstring and error checking,  Up: Unit utils

5.21.6 Reading a file's contents
--------------------------------

 -- procedure: read-all
          (read-all [FILE-OR-PORT])
     If `FILE-OR-PORT' is a string, then this procedure returns the
     contents of the file as a string. If `FILE-OR-PORT' is a port, all
     remaining input is read and returned as a string. The port is not
     closed. If no argument is provided, input will be read from the
     port that is the current value of `(current-input-port)'.


File: chicken.info,  Node: Miscellaneous handy things,  Prev: Reading a file's contents,  Up: Unit utils

5.21.7 Miscellaneous handy things
---------------------------------

 -- procedure: shift!
          (shift! LIST [DEFAULT])
     Returns the car of `LIST' (or `DEFAULT' if `LIST' is empty) and
     replaces the car of `LIST' with it's cadr and the cdr with the
     cddr. If `DEFAULT' is not given, and the list is empty, `#f' is
     returned. An example might be clearer, here:

          (define lst '(1 2 3))
          (shift! lst)             ==> 1, lst is now (2 3)

 -- procedure: unshift!
          (unshift! X PAIR)
     Sets the car of `PAIR' to `X' and the cdr to its cddr. Returns
     `PAIR':

          (define lst '(2))
          (unshift! 99 lst)      ; lst is now (99 2)


File: chicken.info,  Node: Unit tcp,  Next: Unit srfi-37,  Prev: Unit utils,  Up: Supported language

5.22 Unit tcp
=============

This unit provides basic facilities for communicating over TCP sockets.
The socket interface should be mostly compatible to the one found in
PLT Scheme.

   This unit uses the `extras' unit.

   All errors related to failing network operations will raise a
condition of kind `(exn i/o network)'.

 -- procedure: tcp-listen
          (tcp-listen TCPPORT [BACKLOG [HOST]])
     Creates and returns a TCP listener object that listens for
     connections on `TCPPORT', which should be an exact integer.
     `BACKLOG' specifies the number of maximally pending connections
     (and defaults to 4). If the optional argument `HOST' is given and
     not `#f', then only incoming connections for the given host (or
     IP) are accepted.


 -- procedure: tcp-listener?
          (tcp-listener? X)
     Returns `#t' if `X' is a TCP listener object, or `#f' otherwise.


 -- procedure: tcp-close
          (tcp-close LISTENER)
     Reclaims any resources associated with `LISTENER'.


 -- procedure: tcp-accept
          (tcp-accept LISTENER)
     Waits until a connection is established on the port on which
     `LISTENER' is listening and returns two values: an input- and
     output-port that can be used to communicate with the remote
     process.

     Note: this operation and any I/O on the ports returned will not
     block other running threads.


 -- procedure: tcp-accept-ready?
          (tcp-accept-ready? LISTENER)
     Returns `#t' if there are any connections pending on `LISTENER',
     or `#f' otherwise.


 -- procedure: tcp-listener-port
          (tcp-listener-port LISTENER)
     Returns the port number assigned to `LISTENER' (If you pass `0' to
     `tcp-listen', then the system will choose a port-number for you).


 -- procedure: tcp-connect
          (tcp-connect HOSTNAME [TCPPORT])
     Establishes a client-side TCP connection to the machine with the
     name `HOSTNAME' (a string) at `TCPPORT' (an exact integer) and
     returns two values: an input- and output-port for communicating
     with the remote process.

     Note: any I/O on the ports returned will not block other running
     threads.


 -- procedure: tcp-addresses
          (tcp-addresses PORT)
     Returns two values for the input- or output-port `PORT' (which
     should be a port returned by either `tcp-accept' or
     `tcp-connect'): the IP address of the local and the remote machine
     that are connected over the socket associated with `PORT'. The
     returned addresses are strings in `XXX.XXX.XXX.XXX' notation.


 -- procedure: tcp-abandon-port
          (tcp-abandon-port PORT)
     Marks the socket port `PORT' as abandoned. This is mainly useful
     to close down a port without breaking the connection.

   A very simple example follows. Say we have the two files `client.scm'
and `server.scm':


; client.scm
(define-values (i o) (tcp-connect "localhost" 4242))
(write-line "Good Bye!" o)
(print (read-line i))


; server.scm
(define l (tcp-listen 4242))
(define-values (i o) (tcp-accept l))
(write-line "Hello!" o)
(print (read-line i))
(close-input-port i)
(close-output-port o)

% csi -script server.scm &
[1] 1409
% csi -script client.scm
Good Bye!
Hello!


File: chicken.info,  Node: Unit srfi-37,  Next: Unit lolevel,  Prev: Unit tcp,  Up: Supported language

5.23 Unit srfi-37
=================

Copyright (c) 2002 Anthony Carrico

   A simple and flexible command-line option parsing facility. Options
may be either short one-character options of the form `-X[ARGUMENT]' or
long multicharacter ones of the form `--XXX[=ARGUMENT]'. Short options
may be coalesced. An argument of the form `--' stops option processing.
For more information take a look at the SRFI-37 documentation
(http://srfi.schemers.org/srfi-37/srfi-37.html).

   An example:


#!/usr/local/bin/csi -script
;;;; secho - display command-line arguments

(define nl 1)

(define help
  (option
   '(#\h "help") #f #f
   (lambda _
     (print "Usage: secho [OPTION] ARG ...
  -h  --help          show this text
  -n  --newline N     add N newline characters (default: 1)")
     (exit) ) ) )

(define newlines
  (option
   '(#\n "newline") #t #f
   (lambda (o n x vals)
     (set! nl (string->number x))
     vals) ) )

(for-each
 (lambda (x) (print* x #\space))
 (reverse
  (args-fold
   (command-line-arguments)
   (list help newlines)
   (lambda (o n x vals)
     (error "unrecognized option" n) )
   cons
   '() ) ) )

(display (make-string nl #\newline))


File: chicken.info,  Node: Unit lolevel,  Next: Unit tinyclos,  Prev: Unit srfi-37,  Up: Supported language

5.24 Unit lolevel
=================

This unit provides a number of handy low-level operations. Use at your
own risk.

   This unit uses the `srfi-4' and `extras' units.

* Menu:

* Foreign pointers::
* Tagged pointers::
* Extending procedures with data::
* Bytevectors::
* Data in unmanaged memory::
* Locatives::
* Accessing toplevel variables::
* Low-level data access::
* Procedure-call- and variable reference hooks::
* Magic::


File: chicken.info,  Node: Foreign pointers,  Next: Tagged pointers,  Up: Unit lolevel

5.24.1 Foreign pointers
-----------------------

 -- procedure: address->pointer
          (address->pointer ADDRESS)
     Creates a new foreign pointer object initialized to point to the
     address given in the integer `ADDRESS'.


 -- procedure: allocate
          (allocate BYTES)
     Returns a pointer to a freshly allocated region of static memory.
     This procedure could be defined as follows:


     (define allocate (foreign-lambda c-pointer "malloc" integer))


 -- procedure: free
          (free POINTER)
     Frees the memory pointed to by `POINTER'.  This procedure could be
     defined as follows:


     (define free (foreign-lambda c-pointer "free" integer))


 -- procedure: null-pointer
          (null-pointer)
     Another way to say `(address->pointer 0)'.


 -- procedure: null-pointer?
          (null-pointer? PTR)
     Returns `#t' if `PTR' contains a `NULL' pointer, or `#f' otherwise.


 -- procedure: object->pointer
          (object->pointer X)
     Returns a pointer pointing to the Scheme object X, which should be
     a non-immediate object.  Note that data in the garbage collected
     heap moves during garbage collection.


 -- procedure: pointer?
          (pointer? X)
     Returns `#t' if `X' is a foreign pointer object, and `#f'
     otherwise.

      -- procedure: pointer=?
               (pointer=? PTR1 PTR2)
          Returns `#t' if the pointer-like objects `PTR1' and `PTR2'
          point to the same address.


 -- procedure: pointer->address
          (pointer->address PTR)
     Returns the address, to which the pointer `PTR' points.


 -- procedure: pointer->object
          (pointer->object PTR)
     Returns the Scheme object pointed to by the pointer `PTR'.


 -- procedure: pointer-offset
          (pointer-offset PTR N)
     Returns a new pointer representing the pointer `PTR' increased by
     `N'.


 -- procedure: pointer-u8-ref
          (pointer-u8-ref PTR)
     Returns the unsigned byte at the address designated by `PTR'.


 -- procedure: pointer-s8-ref
          (pointer-s8-ref PTR)
     Returns the signed byte at the address designated by `PTR'.


 -- procedure: pointer-u16-ref
          (pointer-u16-ref PTR)
     Returns the unsigned 16-bit integer at the address designated by
     `PTR'.


 -- procedure: pointer-s16-ref
          (pointer-s16-ref PTR)
     Returns the signed 16-bit integer at the address designated by
     `PTR'.


 -- procedure: pointer-u32-ref
          (pointer-u32-ref PTR)
     Returns the unsigned 32-bit integer at the address designated by
     `PTR'.


 -- procedure: pointer-s32-ref
          (pointer-s32-ref PTR)
     Returns the signed 32-bit integer at the address designated by
     `PTR'.


 -- procedure: pointer-f32-ref
          (pointer-f32-ref PTR)
     Returns the 32-bit float at the address designated by `PTR'.


 -- procedure: pointer-f64-ref
          (pointer-f64-ref PTR)
     Returns the 64-bit double at the address designated by `PTR'.


 -- procedure: pointer-u8-set!
          (pointer-u8-set! PTR N)
     Stores the unsigned byte `N' at the address designated by `PTR'.


 -- procedure: pointer-s8-set!
          (pointer-s8-set! PTR N)
     Stores the signed byte `N' at the address designated by `PTR'.


 -- procedure: pointer-u16-set!
          (pointer-u16-set! PTR N)
     Stores the unsigned 16-bit integer `N' at the address designated
     by `PTR'.


 -- procedure: pointer-s16-set!
          (pointer-s16-set! PTR N)
     Stores the signed 16-bit integer `N' at the address designated by
     `PTR'.


 -- procedure: pointer-u32-set!
          (pointer-u32-set! PTR N)
     Stores the unsigned 32-bit integer `N' at the address designated
     by `PTR'.


 -- procedure: pointer-s32-set!
          (pointer-s32-set! PTR N)
     Stores the 32-bit integer `N' at the address designated by `PTR'.


 -- procedure: pointer-f32-set!
          (pointer-f32-set! PTR N)
     Stores the 32-bit floating-point number `N' at the address
     designated by `PTR'.


 -- procedure: pointer-f64-set!
          (pointer-f64-set! PTR N)
     Stores the 64-bit floating-point number `N' at the address
     designated by `PTR'.


 -- procedure: align-to-word
          (align-to-word PTR-OR-INT)
     Accepts either a machine pointer or an integer as argument and
     returns a new pointer or integer aligned to the native word size
     of the host platform.


File: chicken.info,  Node: Tagged pointers,  Next: Extending procedures with data,  Prev: Foreign pointers,  Up: Unit lolevel

5.24.2 Tagged pointers
----------------------

"Tagged" pointers are foreign pointer objects with an extra tag object.

 -- procedure: tag-pointer
          (tag-pointer PTR TAG)
     Creates a new tagged pointer object from the foreign pointer `PTR'
     with the tag `TAG', which may an arbitrary Scheme object.


 -- procedure: tagged-pointer?
          (tagged-pointer? X TAG)
     Returns `#t', if `X' is a tagged pointer object with the tag `TAG'
     (using an `eq?' comparison), or `#f' otherwise.


 -- procedure: pointer-tag
          (pointer-tag PTR)
     If `PTR' is a tagged pointer object, its tag is returned. If `PTR'
     is a normal, untagged foreign pointer object `#f' is returned.
     Otherwise an error is signalled.


File: chicken.info,  Node: Extending procedures with data,  Next: Bytevectors,  Prev: Tagged pointers,  Up: Unit lolevel

5.24.3 Extending procedures with data
-------------------------------------

 -- procedure: extend-procedure
          (extend-procedure PROCEDURE X)
     Returns a copy of the procedure `PROCEDURE' which contains an
     additional data slot initialized to `X'. If `PROCEDURE' is already
     an extended procedure, then its data slot is changed to contain
     `X' and the same procedure is returned.


 -- procedure: extended-procedure?
          (extended-procedure? PROCEDURE)
     Returns `#t' if `PROCEDURE' is an extended procedure, or `#f'
     otherwise.


 -- procedure: procedure-data
          (procedure-data PROCEDURE)
     Returns the data object contained in the extended procedure
     `PROCEDURE'.


 -- procedure: set-procedure-data!
          (set-procedure-data! PROCEDURE X)
     Changes the data object contained in the extended procedure
     `PROCEDURE' to `X'.


     (define foo
       (letrec ((f (lambda () (procedure-data x)))
                (x #f) )
         (set! x (extend-procedure f 123))
         x) )
     (foo)                                         ==> 123
     (set-procedure-data! foo 'hello)
     (foo)                                         ==> hello


File: chicken.info,  Node: Bytevectors,  Next: Data in unmanaged memory,  Prev: Extending procedures with data,  Up: Unit lolevel

5.24.4 Bytevectors
------------------

 -- procedure: byte-vector
          (byte-vector FIXNUM ...)
     Returns a freshly allocated byte-vector with `FIXNUM ...' as its
     initial contents.


 -- procedure: byte-vector?
          (byte-vector? X)
     Returns `#t' if `X' is a byte-vector object, or `#f' otherwise.


 -- procedure: byte-vector-fill!
          (byte-vector-fill! BYTE-VECTOR N)
     Sets each element of `BYTE-VECTOR' to `N', which should be an
     exact integer.


 -- procedure: byte-vector->list
          (byte-vector->list BYTE-VECTOR)
     Returns a list with elements taken from `BYTE-VECTOR'.


 -- procedure: byte-vector->string
          (byte-vector->string BYTE-VECTOR)
     Returns a string with the contents of `BYTE-VECTOR'.


 -- procedure: byte-vector-length
          (byte-vector-length BYTE-VECTOR)
     Returns the number of elements in `BYTE-VECTOR'.


 -- procedure: byte-vector-ref
          (byte-vector-ref BYTE-VECTOR INDEX)
     Returns the byte at the `INDEX'th position of `BYTE-VECTOR'.


 -- procedure: byte-vector-set!
          (byte-vector-set! BYTE-VECTOR INDEX N)
     Sets the byte at the `INDEX'th position of `BYTE-VECTOR' to the
     value of the exact integer `n'.


 -- procedure: executable-byte-vector->procedure
          (executable-byte-vector->procedure PBYTE-VECTOR)
     Returns a procedure that on invocation will execute the code in
     `PBYTE-VECTOR', which should have been allocated using
     `make-executable-byte-vector'.  The procedure follows the native C
     calling convention, and will be called as if declared with the
     following prototype:


     void <procedure>(int argc, C_word closure, C_word k, C_word arg1, ...)

        * `argc' contains the number of arguments `arg1, ...' that are
          passed plus 2 (including `closure' and `k').

        * `closure' is the procedure object itself.

        * `k' is a continuation closure that should be called when the
          code is about to return.


          typedef void (*CONTINUATION)(int argc, C_word closure,
                                                 C_word result);
          ((CONTINUATION)k[ 1 ])(2, k, result)

          (`k' is a data object with the second word being the actual
          code pointer)


     An example:


     (define x (make-executable-byte-vector 17))
     (move-memory!
      '#u8(#x8b #x44 #x24 #x0c  ; movl 12(%esp), %eax - `k'
           #x8b #x5c #x24 #x10  ; movl 16(%esp), %ebx - `arg1'
           #x53                 ; pushl %ebx          - push result
           #x50                 ; pushl %eax          - push k
           #x6a #x02            ; pushl $2            - push argument count
           #x8b #x40 #x04       ; movl 4(%eax), %eax  - fetch code pointer
           #xff #xd0)           ; call *%eax
      x)
     (define y (executable-byte-vector->procedure x))
     (y 123)                                         ==> 123

     The result of calling `executable-byte-vector->procedure' with a
     non-executable statically allocated byte-vector is undefined.


 -- procedure: invoke-executable-byte-vector
          (invoke-executable-byte-vector PBYTE-VECTOR ARG1 ...)
     Invokes the machine code stored in the executable byte-vector
     `PBYTE-VECTOR'. The native C calling conventions are used, but the
     invoked code is passed a single argument containing a pointer to an
     array of the Scheme objects `ARG1 ...'.


     (define v (make-executable-byte-vector 7))
     (move-memory!
      '#u8(#x8b #x44 #x24 #x04        ; movl 4(%esp), %eax
           #x8b #x00                  ; movl 0(%eax), %eax
           #xc3)                      ; ret
      v)
     (invoke-executable-byte-vector v "hello!") ==> "hello!"


 -- procedure: list->byte-vector
          (list->byte-vector LIST)
     Returns a byte-vector with elements taken from `LIST', where the
     elements of `LIST' should be exact integers.


 -- procedure: make-byte-vector
          (make-byte-vector SIZE [INIT])
     Creates a new byte-vector of size `SIZE'. If `INIT' is given, then
     it should be an exact integer with which every element of the
     byte-vector is initialized.


 -- procedure: make-executable-byte-vector
          (make-executable-byte-vector SIZE [INIT])
     As `make-static-byte-vector', but the code is suitable for
     execution.  Note: this feature is currently only available on x86
     platforms.

     Exceptions: `(exn bounds)', `(exn runtime)'


 -- procedure: make-static-byte-vector
          (make-static-byte-vector SIZE [INIT])
     As `make-byte-vector', but allocates the byte-vector in storage
     that is not subject to garbage collection.  To free the allocated
     memory, one has to call `object-release' explicitly.

     Exceptions: `(exn bounds)', `(exn runtime)'


 -- procedure: static-byte-vector->pointer
          (static-byte-vector->pointer PBYTE-VECTOR)
     Returns a pointer object pointing to the data in the statically
     allocated byte-vector `PBYTE-VECTOR'.


 -- procedure: string->byte-vector
          (string->byte-vector STRING)
     Returns a byte-vector with the contents of `STRING'.


File: chicken.info,  Node: Data in unmanaged memory,  Next: Locatives,  Prev: Bytevectors,  Up: Unit lolevel

5.24.5 Data in unmanaged memory
-------------------------------

 -- procedure: object-evict
          (object-evict X [ALLOCATOR])
     Copies the object `X' recursively into the memory pointed to by
     the foreign pointer object returned by `ALLOCATOR', which should
     be a procedure of a single argument (the number of bytes to
     allocate). The freshly copied object is returned.  This facility
     allows moving arbitrary objects into static memory, but care
     should be taken when mutating evicted data: setting slots in
     evicted vector-like objects to non-evicted data is not allowed. It
     is possible to set characters/bytes in evicted strings or
     byte-vectors, though.  It is advisable not to evict ports, because
     they might be mutated by certain file-operations.  `object-evict'
     is able to handle circular and shared structures, but evicted
     symbols are no longer unique: a fresh copy of the symbol is
     created, so


     (define x 'foo)
     (define y (object-evict 'foo))
     y                              ==> foo
     (eq? x y)                      ==> #f
     (define z (object-evict '(bar bar)))
     (eq? (car z) (cadr z))         ==> #t

     The `ALLOCATOR' defaults to `allocate'.


 -- procedure: object-evict-to-location
          (object-evict-to-location X PTR [LIMIT])
     As `object-evict' but moves the object at the address pointed to by
     the machine pointer `PTR'. If the number of copied bytes exceeds
     the optional `LIMIT' then an error is signalled. Two values are
     returned: the evicted object and a new pointer pointing to the
     first free address after the evicted object.


 -- procedure: object-evicted?
          (object-evicted? X)
     Returns `#t' if `X' is a non-immediate evicted data object, or
     `#f' otherwise.


 -- procedure: object-size
          (object-size X)
     Returns the number of bytes that would be needed to evict the data
     object `X'.


 -- procedure: object-release
          (object-release X [RELEASER])
     Frees memory occupied by the evicted object `X' recursively.
     `RELEASER' should be a procedure of a single argument (a foreign
     pointer object to the static memory to be freed) and defaults to
     the C-library `free()'.


 -- procedure: object-unevict
          (object-unevict X)
     Copies the object `X' and nested objects back into the normal
     Scheme heap.  Symbols are re-interned into the symbol table.
     Strings and byte-vectors are not copied.


File: chicken.info,  Node: Locatives,  Next: Accessing toplevel variables,  Prev: Data in unmanaged memory,  Up: Unit lolevel

5.24.6 Locatives
----------------

A _locative_ is an object that points to an element of a containing
object, much like a "pointer" in low-level, imperative programming
languages like "C". The element can be accessed and changed indirectly,
by performing access or change operations on the locative. The
container object can be computed by calling the `location->object'
procedure.

   Locatives may be passed to foreign procedures that expect pointer
arguments.  The effect of creating locatives for evicted data (see
`object-evict') is undefined.

 -- procedure: make-locative
          (make-locative EXP [INDEX])
     Creates a locative that refers to the element of the non-immediate
     object `EXP' at position `INDEX'. `EXP' may be a vector, symbol,
     pair, string, byte-vector, SRFI-4 number-vector, SRFI-25 array, or
     record. `INDEX' should be a fixnum, or a valid index into a
     SRFI-25 array. `INDEX' defaults to 0.


 -- procedure: make-weak-locative
          (make-weak-locative EXP [INDEX])
     Creates a "weak" locative. Even though the locative refers to an
     element of a container object, the container object will still be
     reclaimed by garbage collection if no other references to it exist.


 -- procedure: locative?
          (locative? X)
     Returns `#t' if `X' is a locative, or `#f' otherwise.


 -- procedure: locative-ref
          (locative-ref LOC)
     Returns the element to which the locative `LOC' refers. If the
     containing object has been reclaimed by garbage collection, an
     error is signalled.


 -- procedure: locative-set!
          (locative-set! LOC X)
     Changes the element to which the locative `LOC' refers to `X'.  If
     the containing object has been reclaimed by garbage collection, an
     error is signalled.


 -- procedure: locative->object
          (locative->object LOC)
     Returns the object that contains the element referred to by `LOC'
     or `#f' if the container has been reclaimed by garbage collection.


File: chicken.info,  Node: Accessing toplevel variables,  Next: Low-level data access,  Prev: Locatives,  Up: Unit lolevel

5.24.7 Accessing toplevel variables
-----------------------------------

 -- procedure: global-bound?
          (global-bound? SYMBOL)
     Returns `#t', if the global ("toplevel") variable with the name
     `SYMBOL' is bound to a value, or `#f' otherwise.


 -- procedure: global-ref
          (global-ref SYMBOL)
     Returns the value of the global variable `SYMBOL'.  If no variable
     under that name is bound, an error is signalled.


 -- procedure: global-set!
          (global-set! SYMBOL X)
     Sets the global variable named `SYMBOL' to the value `X'.


File: chicken.info,  Node: Low-level data access,  Next: Procedure-call- and variable reference hooks,  Prev: Accessing toplevel variables,  Up: Unit lolevel

5.24.8 Low-level data access
----------------------------

 -- procedure: block-ref
          (block-ref BLOCK INDEX)
     Returns the contents of the `INDEX'th slot of the object `BLOCK'.
     `BLOCK' may be a vector, record structure, pair or symbol.


 -- procedure: block-set!
          (block-set! BLOCK INDEX X)
     Sets the contents of the `INDEX'th slot of the object `BLOCK' to
     the value of `X'.  `BLOCK' may be a vector, record structure, pair
     or symbol.


 -- procedure: object-copy
          (object-copy X)
     Copies `X' recursively and returns the fresh copy. Objects
     allocated in static memory are copied back into garbage collected
     storage.


 -- procedure: make-record-instance
          (make-record-instance SYMBOL ARG1 ...)
     Returns a new instance of the record type `SYMBOL', with its slots
     initialized to `ARG1 ...'.  To illustrate:


     (define-record point x y)

     expands into something quite similar to:


     (begin
       (define (make-point x y)
         (make-record-instance 'point x y) )
       (define (point? x)
         (and (record-instance? x)
              (eq? 'point (block-ref x 0)) ) )
       (define (point-x p) (block-ref p 1))
       (define (point-x-set! p x) (block-set! p 1 x))
       (define (point-y p) (block-ref p 2))
       (define (point-y-set! p y) (block-set! p 1 y)) )


 -- procedure: move-memory!
          (move-memory! FROM TO [BYTES])
     Copies `BYTES' bytes of memory from `FROM' to `TO'.  `FROM' and
     `TO' may be strings, primitive byte-vectors, SRFI-4 byte-vectors
     (see: *Note Unit srfi-4::), memory mapped files, foreign pointers
     (as obtained from a call to `foreign-lambda', for example) or
     locatives. if `BYTES' is not given and the size of the source or
     destination operand is known then the maximal number of bytes will
     be copied. Moving memory to the storage returned by locatives will
     cause havoc, if the locative refers to containers of non-immediate
     data, like vectors or pairs.


 -- procedure: number-of-bytes
          (number-of-bytes BLOCK)
     Returns the number of bytes that the object `BLOCK' contains.
     `BLOCK' may be any non-immediate value.


 -- procedure: number-of-slots
          (number-of-slots BLOCK)
     Returns the number of slots that the object `BLOCK' contains.
     `BLOCK' may be a vector, record structure, pair or symbol.


 -- procedure: record-instance?
          (record-instance? X)
     Returns `#t' if `X' is an instance of a record type.  See also:
     `make-record-instance'.

 -- procedure: record->vector
          (record->vector BLOCK)
     Returns a new vector with the type and the elements of the record
     `BLOCK'.


File: chicken.info,  Node: Procedure-call- and variable reference hooks,  Next: Magic,  Prev: Low-level data access,  Up: Unit lolevel

5.24.9 Procedure-call- and variable reference hooks
---------------------------------------------------

 -- procedure: invalid-procedure-call-handler
          (invalid-procedure-call-handler PROC)
     Sets an internal hook that is invoked when a call to an object
     other than a procedure is executed at runtime. The procedure
     `PROC' will in that case be called with two arguments: the object
     being called and a list of the passed arguments.


     ;;; Access sequence-elements as in ARC:

     (invalid-procedure-call-handler
       (lambda (proc args)
         (cond [(string? proc) (apply string-ref proc args)]
               [(vector? proc) (apply vector-ref proc args)]
               [else (error "call of non-procedure" proc)] ) ) )

     ("hello" 4)    ==>  #\o

     This facility does not work in code compiled with the "unsafe"
     setting.


 -- procedure: unbound-variable-value
          (unbound-variable-value [X])
     Defines the value that is returned for unbound variables. Normally
     an error is signalled, use this procedure to override the check
     and return `X' instead. To set the default behavior (of signalling
     an error), call `unbound-variable-value' with no arguments.

     This facility does not work in code compiled with the "unsafe"
     setting.


File: chicken.info,  Node: Magic,  Prev: Procedure-call- and variable reference hooks,  Up: Unit lolevel

5.24.10 Magic
-------------

 -- procedure: object-become!
          (object-become! ALIST)
     Changes the identity of the value of the car of each pair in
     `ALIST' to the value of the cdr. Both values may not be immediate
     (i.e. exact integers, characters, booleans or the empty list).


     (define x "i used to be a string")
     (define y '#(and now i am a vector))
     (object-become! (list (cons x y)))
     x                                    ==> #(and now i am a vector)
     y                                    ==> #(and now i am a vector)
     (eq? x y)                            ==> #t

     Note: this operation invokes a major garbage collection.

     The effect of using `object-become!' on evicted data (see
     `object-evict') is undefined.


File: chicken.info,  Node: Unit tinyclos,  Prev: Unit lolevel,  Up: Supported language

5.25 Unit tinyclos
==================

This unit is a port of Gregor Kiczales TinyCLOS with numerous
modifications.

   This unit uses the `extras' unit.

* Menu:

* Defining forms::
* Base language::
* Introspection::
* Intercessory protocol::
* Additional protocol::
* Utility procedures::
* Builtin classes::


File: chicken.info,  Node: Defining forms,  Next: Base language,  Up: Unit tinyclos

5.25.1 Defining forms
---------------------

 -- syntax: define-class
          (define-class NAME (SUPERCLASS1 ...) (SLOTNAME1 ...) [METACLASS])
     Sets the variable `NAME' to a new class (a new instance of the
     class `<class>'). `SUPERCLASS1 ...' is a list of superclasses of
     the newly created class. If no superclasses are given, then
     `<object>' is assumed.  `SLOTNAME1 ...' are the names of the
     direct slots of the class. if `METACLASS' is provided, then the
     new class-instance is an instance of `METACLASS' instead of
     `<class>'.


     (define-class NAME (SUPER) (SLOT1 SLOT2) META)

     is equivalent to


     (define NAME
       (make META
         'name 'NAME
         'direct-supers (list SUPER)
         'direct-slots (list 'SLOT1 'SLOT2)) )

     Note that slots-names are not required to be symbols, so the
     following is perfectly valid:


     (define hidden-slot (list 'hidden))
     (define <myclass>
       (make <class>
          'direct-supers (list <object>)
          'direct-slots (list hidden-slot) ) )
     (define x1 (make <myclass>)
     (slot-set! x1 hidden-slot 99)


 -- syntax: define-generic
          (define-generic NAME [CLASS])
     Sets the variable `NAME' to contain a fresh generic function
     object without associated methods. If the optional argument `CLASS'
     is given, then the generic function will be an instance of that
     class.


 -- syntax: define-method
          (define-method (NAME (VARIABLE1 CLASS1) ... PARAMETERS ...) BODY ...)
     Adds a new method with the code `BODY ...' to the generic function
     that was assigned to the variable `name'.  `CLASS1 ...' is a list
     if classes that specialize this particular method. The method can
     have additional parameters `PARAMETERS', which do not specialize
     the method any further.  Inside the body of the method the
     identifier `call-next-method' names a procedure of zero arguments
     that can be invoked to call the next applicable method with the
     same arguments.  If no generic function is defined under this
     name, then a fresh generic function object is created and assigned
     to `NAME'.  Note that only `define-generic' expands into a valid
     definition, so for internal lexically scoped definitions or for
     definitions for module exports (see `syntax-case') use
     `define-generic'.


File: chicken.info,  Node: Base language,  Next: Introspection,  Prev: Defining forms,  Up: Unit tinyclos

5.25.2 Base language
--------------------

 -- procedure: add-method
          (add-method GENERIC METHOD)
     Adds the method object `METHOD' to the list of applicable methods
     for the generic function `GENERIC'.


 -- procedure: instance?
          (instance? X)
     Returns `#t' if `X' is an instance of a non-primitive class.


 -- procedure: make
          (make CLASS INITARG ...)
     Creates a new instance of `CLASS' and passes `INITARG ...' to the
     `initialize' method of this class.


 -- procedure: make-class
          (make-class SUPERCLASSES SLOTNAMES)
     Creates a new class object, where `SUPERCLASSES' should be the
     list of direct superclass objects and `SLOTNAMES' should be a list
     of symbols naming the slots of this class.


 -- procedure: make-generic
          (make-generic [NAME])
     Creates a new generic function object. If `NAME' is specified,
     then it should be a string.


 -- procedure: make-method
          (make-method SPECIALIZERS PROC)
     Creates a new method object specialized to the list of classes in
     `SPECIALIZERS'.


     (define-method (foo (x <bar>)) 123)
        <=> (add-method foo
                        (make-method
                           (list <bar>)
                           (lambda (call-next-method x) 123)))


 -- procedure: slot-ref
          (slot-ref INSTANCE SLOTNAME)
     Returns the value of the slot `SLOTNAME' of the object `INSTANCE'.


 -- procedure: slot-set!
          (slot-set! INSTANCE SLOTNAME VALUE)
     Sets the value of the slot `SLOTNAME' of the object `INSTANCE' to
     `VALUE'.


File: chicken.info,  Node: Introspection,  Next: Intercessory protocol,  Prev: Base language,  Up: Unit tinyclos

5.25.3 Introspection
--------------------

 -- procedure: class-cpl
          (class-cpl CLASS)
     Returns the class-precedence-list of `CLASS' as a list of classes.


 -- procedure: class-direct-slots
          (class-direct-slots CLASS)
     Returns the list of direct slots of `CLASS' as a list of lists,
     where each sublist contains the name of the slot.


 -- procedure: class-direct-supers
          (class-direct-supers CLASS)
     Returns the list of direct superclasses of `CLASS'.


 -- procedure: class-of
          (class-of X)
     Returns the class that the object `X' is an instance of.


 -- procedure: class-name
          (class-name CLASS)
     Returns name of `CLASS'.


 -- procedure: class-slots
          (class-slots CLASS)
     Returns the list of all slots of `CLASS' and its superclasses as a
     list of lists, where each sublist contains the name of the slot.


 -- procedure: generic-methods
          (generic-methods GENERIC)
     Returns the list of all methods associated with the generic
     function `GENERIC'.


 -- procedure: method-specializers
          (method-specializers METHOD)
     Returns the list of classes that specialize `METHOD'.


 -- procedure: method-procedure
          (method-procedure METHOD)
     Returns the procedure that contains the body of `METHOD'.


 -- procedure: subclass?
          (subclass? CLASS1 CLASS2)
     Returns `#t' is `CLASS1' is a subclass of `CLASS2', or `#f'
     otherwise. Note that the following holds:


     (subclass? X X) ==> #t


File: chicken.info,  Node: Intercessory protocol,  Next: Additional protocol,  Prev: Introspection,  Up: Unit tinyclos

5.25.4 Intercessory protocol
----------------------------

These definitions allow interfacing to the Meta Object Protocol of
TinyCLOS. For serious use, it is recommended to consult the source code
(`tinyclos.scm').

 -- generic: allocate-instance
          (allocate-instance CLASS)
     Allocates storage for an instance of `CLASS' and returns the
     instance.


 -- generic: compute-apply-generic
          (compute-apply-generic GENERIC)
     Returns a procedure that will be called to apply the generic
     function methods to the arguments.


 -- generic: compute-apply-methods
          (compute-apply-methods GENERIC)
     Returns a procedure of two arguments, a list of applicable methods
     and a list of arguments and applies the methods.


 -- generic: compute-methods
          (compute-methods GENERIC)
     Returns a procedure of one argument. The procedure is called with
     the list of actual arguments passed to the generic function and
     should return a list of applicable methods, sorted by precedence.


 -- generic: compute-cpl
          (compute-cpl CLASS)
     Computes and returns the class-precedence-list of `CLASS'.


 -- generic: compute-getter-and-setter
          (compute-getter-and-setter CLASS SLOT ALLOCATOR)
     Returns two values, the procedures that get and set the contents
     of the slot `SLOT'.  `ALLOCATOR' is a procedure of one argument
     _(I currently don't know what it does)_.


 -- generic: compute-method-more-specific?
          (compute-method-more-specific? GENERIC)
     Returns a procedure of three arguments (two methods and a list of
     arguments) that returns `#t' if the first method is more specific
     than the second one with respect to the list of arguments.
     Otherwise the returned predicate returns `#f'.


 -- generic: compute-slots
          (compute-slots CLASS)
     Computes and returns the list of slots of `CLASS'.


 -- generic: initialize
          (initialize INSTANCE INITARGS)
     Initializes the object `INSTANCE'. `INITARGS' is the list of
     initialization arguments that were passed to the `make' procedure.


File: chicken.info,  Node: Additional protocol,  Next: Utility procedures,  Prev: Intercessory protocol,  Up: Unit tinyclos

5.25.5 Additional protocol
--------------------------

 -- generic: describe-object
          (describe-object INSTANCE PORT)
     Writes a description of `INSTANCE' to `PORT'.  Execution of the
     interpreter command `,d' will invoke this generic function.


 -- generic: print-object
          (print-object INSTANCE PORT)
     Writes a textual representation of `INSTANCE' to `PORT'.  Any
     output of an instance with `display, write' and `print' will
     invoke this generic function.


File: chicken.info,  Node: Utility procedures,  Next: Builtin classes,  Prev: Additional protocol,  Up: Unit tinyclos

5.25.6 Utility procedures
-------------------------

 -- procedure: initialize-slots
          (initialize-slots INSTANCE INITARGS)
     This procedure takes a sequence of alternating slot-names and
     initialization values in `INITARGS' and initializes the
     corresponding slots in `INSTANCE'.


     (define-class <pos> () (x y))

     (define-method (initialize (pos <pos>) initargs)
       (call-next-method)
       (initialize-slots pos initargs))

     (define p1 (make <pos> 'x 1 'y 2))
     (define p2 (make <pos> 'x 3 'y 5))


File: chicken.info,  Node: Builtin classes,  Prev: Utility procedures,  Up: Unit tinyclos

5.25.7 Builtin classes
----------------------

The class hierarchy of builtin classes looks like this:


<top>
  <object>
    <class>
      <procedure-class>
        <procedure>
        <entity-class>
          <generic>
      <primitive-class>
    <c++-object>
  <primitive>
    <void>
    <boolean>
    <symbol>
    <char>
    <vector>
    <pair>
    <number>
      <integer>
        <exact>
      <inexact>
    <string>
    <port>
      <input-port>
      <output-port>
    <pointer>
      <tagged-pointer>
      <swig-pointer>
    <locative>
    <byte-vector>
      <u8vector>
      <s8vector>
      <u16vector>
      <s16vector>
      <u32vector>
      <s32vector>
      <f32vector>
      <f64vector>
    <structure>
      <array>
      <char-set>
      <condition>
      <environment>
      <hash-table>
      <lock>
      <mmap>
      <promise>
      <queue>
      <tcp-listener>
      <time>
    <end-of-file>

 -- class: <primitive> -> <top>
     The parent class of the classes of all primitive Scheme objects.

 -- class: <boolean> -> <primitive>
 -- class: <symbol> -> <primitive>
 -- class: <char> -> <primitive>
 -- class: <vector> -> <primitive>
 -- class: <null> -> <primitive>
 -- class: <pair> -> <primitive>
 -- class: <number> -> <primitive>
 -- class: <integer> -> <primitive>
 -- class: <exact> -> <integer>
 -- class: <inexact> -> <number>
 -- class: <string> -> <primitive>
 -- class: <port> -> <primitive>
 -- class: <environment> -> <structure>
 -- class: <end-of-file> -> <primitive>
 -- class: <input-port> -> <port>
 -- class: <output-port> -> <port>
 -- class: <procedure> -> <procedure-class>
     The classes of primitive Scheme objects.

 -- class: <byte-vector> -> <primitive>
 -- class: <structure> -> <primitive>
 -- class: <hash-table> -> <structure>
 -- class: <queue> -> <structure>
     The classes of extended data types provided by the various library
     units.

 -- class: <class> -> <object>
     The parent class of all class objects.

 -- class: <entity-class> -> <class>
     The parent class of objects that can be invoked as a procedure and
     have slots.

 -- class: <generic> -> <entity-class>
     The parent class of generic function objects.

 -- class: <method> -> <class>
     The parent class of method objects.

 -- class: <object> -> <class>
     The parent class of all objects.

 -- class: <procedure-class> -> <class>
     The parent class of objects that can be invoked as a procedure.

 -- class: <condition> -> <structure>
     Class of condition objects.

 -- class: <array> -> <structure>
 -- class: <char-set> -> <structure>
 -- class: <time> -> <structure>
 -- class: <u8vector> -> <byte-vector>
 -- class: <s8vector> -> <byte-vector>
 -- class: <u16vector> -> <byte-vector>
 -- class: <s16vector> -> <byte-vector>
 -- class: <u32vector> -> <byte-vector>
 -- class: <s32vector> -> <byte-vector>
 -- class: <f32vector> -> <byte-vector>
 -- class: <f64vector> -> <byte-vector>
     The classes of data objects provided by the various supported
     SRFIs.

 -- class: <lock> -> <structure>
 -- class: <mmap> -> <structure>
     Classes of objects used in the `posix' library unit.

 -- class: <pointer> -> <primitive>
 -- class: <tagged-pointer> -> <pointer>
 -- class: <swig-pointer> -> <pointer>
     A machine pointer (untagged, tagged or pointing to SWIG-wrapped
     data).

 -- class: <locative> -> <primitive>
     A locative.

 -- class: <promise> -> <structure>
     The class of objects returned by `delay'.

 -- class: <tcp-listener> -> <structure>
     The class of an object returned by `tcp-listen'.

 -- class: <c++-class> -> <object>
     The class of generated wrappers for C++ classes parsed by the
     "easy" Foreign Function interface.

   The CHICKEN distribution provides several examples in the file
`tinyclos-examples.scm'.


File: chicken.info,  Node: Interface to external functions and variables,  Next: chicken-setup,  Prev: Supported language,  Up: Top

6 Interface to external functions and variables
***********************************************

* Menu:

* Accessing external objects::
* Foreign type specifiers::
* Entry points::
* Callbacks::
* Locations::
* Other support procedures::
* The Easy Foreign Function Interface::
* C interface::


File: chicken.info,  Node: Accessing external objects,  Next: Foreign type specifiers,  Up: Interface to external functions and variables

6.1 Accessing external objects
==============================

 -- syntax: foreign-code
          (foreign-code STRING)
     Executes the embedded C/C++ code `STRING', which should be a
     sequence of C statements, which are executed and return an
     unspecified result.


     (foreign-code "doSomeInitStuff();")     =>  #<unspecified>


 -- syntax: foreign-value
          (foreign-value STRING TYPE)
     Evaluates the embedded C/C++ expression `STRING', returning a
     value of type given in the foreign-type specifier `TYPE'.


     (print (foreign-value "my_version_string" c-string))


 -- syntax: define-foreign-type
          (define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])
     Defines an alias for `TYPE' with the name `NAME' (a symbol).
     `TYPE' may be a type-specifier or a string naming a C type. The
     namespace of foreign type specifiers is separate from the normal
     Scheme namespace.  The optional arguments `ARGCONVERT' and
     `RETCONVERT' should evaluate to procedures that map argument- and
     result-values to a value that can be transformed to `TYPE':


     (define-foreign-type char-vector
       nonnull-c-string
       (compose list->string vector->list)
       (compose list->vector string->list) )

     (define strlen
       (foreign-lambda int "strlen" char-vector) )

     (strlen '#(#\a #\b #\c))                      ==> 3

     (define memset
       (foreign-lambda char-vector "memset" char-vector char int) )

     (memset '#(#_ #_ #_) #\X 3)                ==> #(#\X #\X #\X)

     Foreign type-definitions are only visible in the compilation-unit
     in which they are defined, so use `include' to use the same
     definitions in multiple files.


 -- syntax: define-foreign-variable
          (define-foreign-variable NAME TYPE [STRING])
     Defines a foreign variable of name `NAME' (a symbol). `STRING'
     should be the real name of a foreign variable or parameterless
     macro. If `STRING' is not given, then the variable name `NAME' will
     be converted to a string and used instead. All references and
     assignments (via `set!') are modified to correctly convert values
     between Scheme and C representation. This foreign variable can
     only be accessed in the current compilation unit, but the name can
     be lexically shadowed.  Note that `STRING' can name an arbitrary C
     expression. If no assignments are performed, then `STRING' doesn't
     even have to specify an lvalue.


     #>
     enum { abc=3, def, ghi };
     <#

     (define-macro (define-foreign-enum . items)
       `(begin
          ,@(map (match-lambda
                   [(name realname) `(define-foreign-variable ,name int ,realname)]
                   [name `(define-foreign-variable ,name int)] )
          items) ) )

     (define-foreign-enum abc def ghi)

     ghi                               ==> 5


 -- syntax: define-foreign-record
          (define-foreign-record NAME SLOT ...)
     Defines accessor procedures for a C structure definition. `NAME'
     should either be a symbol or a list of the form `(TYPENAME
     FOREIGNNAME)'. If `NAME' is a symbol, then a C declaration will be
     generated that defines a C struct named `struct NAME'. If `NAME'
     is a list, then no struct declaration will be generated.  A
     foreign-type specifier named `NAME' (or `TYPENAME') will be
     defined as a pointer to the given C structure.  A `SLOT'
     definition should be a list of one of the following forms:


     (TYPE SLOTNAME)

     or


     (TYPE SLOTNAME SIZE)

     The latter form defines an array of SIZE elements of the type TYPE
     embedded in the structure.  For every slot, the following accessor
     procedures will be generated:

      -- procedure: TYPENAME-SLOTNAME
               (TYPENAME-SLOTNAME FOREIGN-RECORD-POINTER [INDEX])
          A procedure of one argument (a pointer to a C structure),
          that returns the slot value of the slot `SLOTNAME'. If a
          `SIZE' has been given in the slot definition, then an
          additional argument `INDEX' is required that specifies the
          index of an array-element.

      -- procedure: TYPENAME-SLOTNAME-set!
               (TYPENAME-SLOTNAME-set! FOREIGN-RECORD-POINTER [INXDEX] VALUE)
          A procedure of two arguments (a pointer to a C structure) and
          a value, that sets the slot value of the slot `SLOTNAME' in
          the structure. If a `SIZE' has been given in the slot
          definition, then an additional argument `INDEX' is required
          for the array index.

     If a slot type is of the form `(const ...)', then no setter
     procedure will be generated.  Slots of the types `(struct ...)' or
     `(union ...)' are accessed as pointers to the embedded struct (or
     union) and no setter will be generated.

     Note that no constructor or release procedure will be generated.


 -- syntax: foreign-callback-lambda
          (foreign-callback-lambda RETURNTYPE NAME ARGTYPE ...)
     This is similar to `foreign-lambda', but also allows the called
     function to call Scheme functions. See *Note Callbacks::.


 -- syntax: foreign-callback-lambda*
          (foreign-callback-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)
     This is similar to `foreign-lambda*', but also allows the called
     function to call Scheme functions. See *Note Callbacks::.


 -- syntax: foreign-lambda
          (foreign-lambda RETURNTYPE NAME ARGTYPE ...)
     Represents a binding to an external routine. This form can be used
     in the position of an ordinary `lambda' expression. `NAME'
     specifies the name of the external procedure and should be a
     string or a symbol.


 -- syntax: foreign-lambda*
          (foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)
     Similar to `foreign-lambda', but instead of generating code to
     call an external function, the body of the C procedure is directly
     given in `STRING ...':


     (define my-strlen
       (foreign-lambda* int ((c-string str))
         "int n = 0;
          while(*(str++)) ++n;
          return(n);") )

     (my-strlen "one two three")             ==> 13

     For obscure technical reasons any use of the `return' statement
     should enclose the result value in parentheses. For the same
     reasons `return' without an argument is not allowed.


File: chicken.info,  Node: Foreign type specifiers,  Next: Entry points,  Prev: Accessing external objects,  Up: Interface to external functions and variables

6.2 Foreign type specifiers
===========================

Here is a list of valid foreign type specifiers:

`scheme-object'
     An arbitrary Scheme data object (immediate or non-immediate).

`bool'
     As argument: any value (`#f' is false, anything else is true).  As
     result: anything different from 0 and the `NULL'-pointer is `#t'.

`byte unsigned-byte'
     A byte.

`char unsigned-char'
     A character.

`short unsigned-short'
     A short integer number.

`int unsigned-int'
     An small integer number in fixnum range (at least 30 bit).

`integer unsigned-integer'
     Either a fixnum or a flonum in the range of a (unsigned) machine
     "int".

`long unsigned-long'
     Either a fixnum or a flonum in the range of a (unsigned) machine
     "long".

`float double'
     A floating-point number. If an exact integer is passed as an
     argument, then it is automatically converted to a float.

`number'
     A floating-point number. Similar to `double', but when used as a
     result type, then either an exact integer or a floating-point
     number is returned, depending on whether the result fits into an
     exact int or not.

`symbol'
     A symbol, which will be passed to foreign code as a
     zero-terminated string.  When declared as the result of foreign
     code, the result is treated like a string and a symbol with the
     same name will be interned in the symbol table.

`pointer'
     An untyped pointer to the contents of a non-immediate Scheme object
     (not allowed as return type).  The value `#f' is also allowed and
     is passed as a `NULL' pointer.

`nonnull-pointer'
     As `pointer', but guaranteed not to be `#f'.

`c-pointer'
     An untyped operating-system pointer or a locative.  The value `#f'
     is also allowed and is passed as a `NULL' pointer.  If uses as the
     type of a return value, a `NULL' pointer will be returned as `#f'.

`nonnull-c-pointer'
     As `c-pointer', but guaranteed not to be `#f/NULL'.

`[nonnull-] byte-vector'
     A byte-vector object, passed as a pointer to its contents.
     Arguments of type `byte-vector' may optionally be `#f', which is
     passed as a NULL pointer.  This is not allowed as a return type.

`[nonnull-] u8vector'
`[nonnull-] u16vector'
`[nonnull-] u32vector'
`[nonnull-] s8vector'
`[nonnull-] s16vector'
`[nonnull-] s32vector'
`[nonnull-] f32vector'
`[nonnull-] f64vector'
     A SRFI-4 number-vector object, passed as a pointer to its
     contents. Arguments of type `byte-vector' may optionally be `#f',
     which is passed as a NULL pointer.  These are not allowed as
     return types.

`c-string'
     A C string (zero-terminated). The value `#f' is also allowed and
     is passed as a `NULL' pointer. If uses as the type of a return
     value, a `NULL' pointer will be returned as `#f'. Note that the
     string is copied (with a zero-byte appended) when passed as an
     argument to a foreign function. Also a return value of this type
     is copied into garbage collected memory.

`nonnull-c-string'
     As `c-string', but guaranteed not to be `#f/NULL'.

`[nonnull-] c-string*'
     Similar to `[nonnull-]c-string', but if used as a result-type, the
     pointer returned by the foreign code will be freed (using the
     C-libraries `free()') after copying.

`void'
     Specifies an undefined return value. Not allowed as argument type.

`(const TYPE)'
     The foreign type `TYPE' with an additional `const' specifier.

`(enum NAME)'
     An enumeration type. Handled internally as an `integer'.

`(pointer TYPE)'

`(c-pointer TYPE)'
     An operating-system pointer or a locative to an object of `TYPE'.

`(nonnull-pointer TYPE)'

`(nonnull-c-pointer TYPE)'
     As `(pointer TYPE)', but guaranteed not to be `#f/NULL'.

`(ref TYPE)'
     A C++ reference type. Reference types are handled the same way as
     pointers inside Scheme code.

`(struct NAME)'
     A struct of the name `NAME', which should be a string. Structs can
     not be directly passed as arguments to foreign function, neither
     can they be result values. Pointers to structs are allowed, though.

`(template TYPE ARGTYPE ...)'
     A C++ template type. For example `vector<int>' would be specified
     as `(template "vector" int)'. Template types can not be directly
     passed as arguments or returned as results.

`(union NAME)'
     A union of the name `NAME', which should be a string. Unions can
     not be directly passed as arguments to foreign function, neither
     can they be result values. Pointers to unions are allowed, though.

`(instance CNAME SCHEMECLASS)'
     A pointer to a C++ class instance. `CNAME' should designate the
     name of the C++ class, and `SCHEMECLASS' should be the class that
     wraps the instance pointer. Normally `SCHEMECLASS' should be a
     subclass of `<c++-object>'.

`(instance-ref CNAME SCHEMECLASS)'
     A reference to a C++ class instance.

`(function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])'
     A function pointer. `CALLCONV' specifies an optional calling
     convention and should be a string. The meaning of this string is
     entirely platform dependent.  The value `#f' is also allowed and
     is passed as a `NULL' pointer.


   Foreign types are mapped to C types in the following manner:

`bool'
     int

`[unsigned-]char'
     [unsigned] char

`[unsigned-]short'
     [unsigned] short

`[unsigned-]int'
     [unsigned] int

`[unsigned-]integer'
     [unsigned] int

`[unsigned-]long'
     [unsigned] long

`float'
     float

`double'
     double

`number'
     double

`[nonnull-]pointer'
     void *

`[nonnull-]c-pointer'
     void *

`[nonnull-]byte-vector'
     unsigned char *

`[nonnull-]u8vector'
     unsigned char *

`[nonnull-]s8vector'
     char *

`[nonnull-]u16vector'
     unsigned short *

`[nonnull-]s16vector'
     short *

`[nonnull-]u32vector'
     uint32_t *

`[nonnull-]s32vector'
     int32_t *

`[nonnull-]f32vector'
     float *

`[nonnull-]f64vector'
     double *

`[nonnull-]c-string'
     char *

`symbol'
     char *

`void'
     void

`([nonnull-]pointer TYPE)'
     TYPE *

`(enum NAME)'
     enum NAME

`(struct NAME)'
     struct NAME

`(ref TYPE)'
     TYPE &

`(template T1 T2 ...)'
     T1<T2, ...>

`(union NAME)'
     union NAME

`(function RTYPE (ATYPE ...) [CALLCONV])'
     [CALLCONV] RTYPE (*)(ATYPE, ...)

`(instance CNAME SNAME)'
     CNAME *

`(instance-ref CNAME SNAME)'
     CNAME &


File: chicken.info,  Node: Entry points,  Next: Callbacks,  Prev: Foreign type specifiers,  Up: Interface to external functions and variables

6.3 Entry points
================

To simplify embedding compiled Scheme code into arbitrary programs, one
can define so called "entry points", which provide a uniform interface
and parameter conversion facilities. To use this facility, add


(include "chicken-entry-points")

   to the beginning of your code.

 -- syntax: define-entry-point
          (define-entry-point INDEX ((VAR1 TYPE1) ...)
                                    (RTYPE1 ...)
                                    EXP1 EXP2 ...)
     Defines a new entry-point with index `INDEX' which should evaluate
     to an exact integer. During execution of the body `EXP1 EXP2 ...'
     the variables `VAR1 ...' are bound to the parameters passed from
     the host program to the invoked entry point. The parameters passed
     are converted according to the foreign type specifiers `TYPE1
     ...'. The expressions should return as many values as foreign type
     specifiers are given in `RTYPE1 ...', with the exception that if
     the list of return types is empty, a single value is expected to
     be returned from the body (there is no need to add a `(values)'
     form at the end).  The results are then transformed into values
     that can be used in the host program.

     Note: if one or more of the result types `RTYPE ...' specify the
     type `c-string', then the parameter types at the same positions in
     `TYPE1 ...' have to be `c-string's as well, because the result
     strings are copied into the same area in memory.  You should also
     take care that the passed buffer is long enough to hold the result
     string or unpredictable things will happen.

     If entry points were defined then the program will not terminate
     after execution of the last toplevel expression, but instead it
     will enter a loop that waits for the host to invoke one of the
     defined entry points.


 -- syntax: define-embedded
          (define-embedded [QUALIFIER ... ] ([CCONV] NAME (TYPE1 VAR1) ...) RTYPE BODY ...)
     Defines a named entry-point that can be accessed from external
     code with a normal C/C++ function call.  `QUALIFIER' may be a
     string for special function declarations (like
     `__declspec(dllexport)' on Windows, for example) and `CCONV' may
     be a string designating a calling convention (like `__cdecl').
     During the execution of the `BODY' the variables `VAR1 ...' are
     bound to the arguments passed to the function, which should be of
     types compatible to the type specifiers `TYPE1 ...'.  `RTYPE'
     specifies the result type of the entry-point. The return type
     specifiers `[nonnull-]c-string' and `[nonnull-]c-string*' are
     handled specially: if the return type is `c-string', a
     heap-allocated pointer to a zero-terminated string will be
     returned, which will be valid until the next invocation of an
     entry-point into the Scheme code. If the return type is
     `c-string*', a buffer allocated with `malloc' will be returned,
     and freeing the string is the responsibility of the caller.

     All entry-point definitions with `define-embedded' should be put
     into the same source file.  `define-embedded' expands into a
     `define-entry-point' form and the entry-point index is provided by
     the macro (starting from 1). If `define-embedded' is used in
     multiple source files then the index is counted from 1 in each of
     the files, resulting in multiple entry-points with the same index.

   The following C functions and data types are provided:

 -- C function: void CHICKEN_parse_command_line (int argc, char
          *argv[], int *heap, int *stack int *symbols)
     Parse the programs command-line contained in `argc' and `argv' and
     return the heap-, stack- and symbol table limits given by runtime
     options of the form `-:...', or choose default limits. The library
     procedure `argv' can access the command-line only if this function
     has been called by the containing application.

 -- C function: int CHICKEN_initialize (int heap, int stack, int
          symbols, void *toplevel)
     Initializes the Scheme execution context and memory. `heap' holds
     the number of bytes that are to be allocated for the secondary
     heap. `stack' holds the number of bytes for the primary heap.
     `symbols' contains the size of the symbol table. Passing `0' to
     one or more of these parameters will select a default size.
     `toplevel' should be a pointer to the toplevel entry point
     procedure. You should pass `C_toplevel' here. In any subsequent
     call to `CHICKEN_run' or `CHICKEN_invoke' you can simply pass
     `NULL'.  Calling this function more than once has no effect. If
     enough memory is available and initialization was successful, then
     `1' is returned, otherwise this function returns `0'.

 -- C function: void CHICKEN_run (void **data, int *bytes, int *maxlen,
          void *toplevel)
     Starts the Scheme program. `data, bytes' and `maxlen' contain
     invocation parameters in raw form. Pass `NULL' here.  Call this
     function once to execute all toplevel expressions in your compiled
     Scheme program. If the runtime system was not initialized before,
     then `CHICKEN_initialize' is called with default sizes.
     `toplevel' is the toplevel entry-point procedure.

 -- C function: void CHICKEN_invoke (int index, C_parameter *params,
          int count, void *toplevel)
     Invoke the entry point with index `index'. `count' should contain
     the maximum number of arguments or results (whatever is higher).
     `params' is a pointer to parameter data:


     typedef union
     {
       C_word x;           /* parameter type scheme-object */
       long i;             /* parameter type bool, [unsigned] int/short/long */
       long c;             /* parameter type [unsigned] char */
       double f;           /* parameter type float/double */
       void *p;            /* any pointer parameter type and C strings */
     } C_parameter;

     This function calls `CHICKEN_run' if it was not called at least
     once before.

 -- C function: int CHICKEN_is_running ()
     Returns `1', if called inside a dynamic context invoked via
     `CHICKEN_run' or `CHICKEN_invoke' (i.e. if running inside a call
     from Scheme to C). If no Scheme stack frame is currently active,
     then this function returns `0'.

   Here is a simple example (assuming a UNIX-like environment):


% cat foo.c
#include <stdio.h>
#include "chicken.h"

int main(void)
{
  C_parameter p[ 3 ];
  char str[ 32 ] = "hello!";  /* We need some space for the result string! */

  memset(p, 0, sizeof(p));
  p[ 0 ].i = -99;
  p[ 1 ].p = str;
  p[ 2 ].f = 3.14;
  CHICKEN_invoke(1, p, 3, C_toplevel);
  printf("->\n%d\n%s\n", p[ 0 ].i, p[ 1 ].p);
  return 0;
}

% cat bar.scm
(include "chicken-entry-points")

(define-entry-point 1
    ((a integer) (b c-string) (c double))
    (int c-string)
  (print (list a b c))
  (values 123 "good bye!") )

% chicken bar.scm -quiet
% gcc foo.c bar.c -o foo `chicken-config -cflags -libs -embedded`
% foo
(-99 "hello!" 3.14)
->
123
good bye!

   Note the use of `-embedded'. We have to compile with additional
compiler options, because the host program provides the `main' function.

   Here another example that uses named entry-points defined with
`define-embedded':


% cat foo.c
extern int foo(int, char *);
extern unsigned int square(double);

int main() { foo(square(9), "yo!"); return 0; }

% cat bar.scm
(include "chicken-entry-points")

(define-embedded (foo (int x) (c-string y)) int
  (print x ": " y)
  x)

(define-embedded (square (double x)) unsigned-int
  (* x x))

% chicken bar.scm
compiling `bar.scm' ...
% gcc foo.c bar.c `chicken-config -cflags -libs -embedded`
% a.out
81: yo!

   CHICKEN also provides "boilerplate" entry points, that simplify
invoking Scheme code embedded in a C or C++ application tremendously.
The include file `default-entry-points.scm' will define entry-points
for common usage patterns, like loading a file, evaluating an expression
or calling a procedure.

 -- C macro: void CHICKEN_eval (C_word exp, C_word *result, int *status)
     Evaluates the Scheme object passed in `exp', writing the result
     value to `result'.  `status' is set to 1 if the operation
     succeeded, or 0 if an error occurred. Call
     `CHICKEN_get_error_message' to obtain a description of the error.

 -- C macro: void CHICKEN_eval_string (char *str, C_word *result, int
          *status)
     Evaluates the Scheme expression passed in the string `str',
     writing the result value to `result'.

 -- C macro: void CHICKEN_eval_to_string (C_word exp, char *result, int
          size, int *status)
     Evaluates the Scheme expression passed in `exp', writing a textual
     representation of the result into `result'. `size' should specify
     the maximal size of the result string.

 -- C macro: void CHICKEN_eval_string_to_string (char *str, char
          *result, int size, int *status)
     Evaluates the Scheme expression passed in the string `str',
     writing a textual representation of the result into `result'.
     `size' should specify the maximal size of the result string.

 -- C macro: void CHICKEN_apply (C_word func, C_word args, C_word
          *result, int *status)
     Applies the procedure passed in `func' to the list of arguments
     `args', writing the result value to `result'.

 -- C macro: void CHICKEN_apply_to_string (C_word func, C_word args,
          char *result, int size, int *status)
     Applies the procedure passed in `func' to the list of arguments
     `args', writing a textual representation of the result into
     `result'.

 -- C macro: void CHICKEN_read (char *str, C_word *result, int *status)
     Reads a Scheme object from the string `str', writing the result
     value to `result'.

 -- C macro: void CHICKEN_load (char *filename, int *status)
     Loads the Scheme file `filename' (either in source form or
     compiled).

 -- C macro: void CHICKEN_get_error_message (char *result, int size)
     Returns a textual description, in case an error occurred while
     invoking embedded Scheme code.

 -- C macro: void CHICKEN_yield (int *status)
     If threads have been spawned during earlier invocations of
     embedded Scheme code, then this function will run the next
     scheduled thread for one complete time-slice. This is useful, for
     example, inside an "idle" handler in a GUI application with
     background Scheme threads.

   An example:


% cat x.scm
;;; x.scm

(include "chicken-default-entry-points")
(define (bar x) (gc) (* x x))

% cat y.c
/* y.c */

#include "chicken.h"
#include <assert.h>

int main() {
  char buffer[ 256 ];
  int status;
  C_word val = C_SCHEME_UNDEFINED;
  C_word *data[ 1 ];

  data[ 0 ] = &val;

  CHICKEN_read("(bar 99)", &val, &status);
  assert(status);

  C_gc_protect(data, 1);

  printf("data: %08x\n", val);

  CHICKEN_eval_string_to_string("(bar)", buffer, 255, &status);
  assert(!status);

  CHICKEN_get_error_message(buffer, 255);
  printf("ouch: %s\n", buffer);

  CHICKEN_eval_string_to_string("(bar 23)", buffer, 255, &status);
  assert(status);

  printf("-> %s\n", buffer);
  printf("data: %08x\n", val);

  CHICKEN_eval_to_string(val, buffer, 255, &status);
  assert(status);
  printf("-> %s\n", buffer);

  return 0;
}

% csc x.scm y.c -embedded

   A simpler interface For handling GC-safe references to Scheme data
are the so called "gc-roots":

 -- C function: void* CHICKEN_new_gc_root ()
     Returns a pointer to a "GC root", which is an object that holds a
     reference to a Scheme value that will always be valid, even after
     a garbage collection. The content of the gc root is initialized to
     an unspecified value.

 -- C function: void CHICKEN_delete_gc_root (void *root)
     Deletes the gc root.

 -- C macro: C_word CHICKEN_gc_root_ref (void *root)
     Returns the value stored in the gc root.

 -- C macro: void CHICKEN_gc_root_set (void *root, C_word value)
     Sets the content of the GC root to a new value.

   Sometimes it is handy to access global variables from C code:

 -- C function: void* CHICKEN_global_lookup (char *name)
     Returns a GC root that holds the global variable with the name
     `name'. If no such variable exists, `NULL' is returned.

 -- C function: C_word CHICKEN_global_ref (void *global)
     Returns the value of the global variable referenced by the GC root
     `global'.

 -- C function: void CHICKEN_global_set (void *global, C_word value)
     Sets the value of the global variable referenced by the GC root
     `global' to `value'.


File: chicken.info,  Node: Callbacks,  Next: Locations,  Prev: Entry points,  Up: Interface to external functions and variables

6.4 Callbacks
=============

To enable an external C function to call back to Scheme, the form
`foreign-callback-lambda' (or `foreign-callback-lambda*') has to be
used. This generates special code to save and restore important state
information during execution of C code. There are two ways of calling
Scheme procedures from C: the first is to invoke the runtime function
`C_callback' with the closure to be called and the number of arguments.
The second is to define an externally visible wrapper function around
a Scheme procedure with the `define-external' or
`foreign-callback-wrapper' forms.

   Note: the names of all functions, variables and macros exported by
the CHICKEN runtime system start with "`C_'". It is advisable to use a
different naming scheme for your own code to avoid name clashes.
Callbacks (either defined by `define-external' or
`foreign-callback-wrapper' do not capture the lexical environment.

   Non-local exits leaving the scope of the invocation of a callback
from Scheme into C will not remove the C call-frame from the stack (and
will result in a memory leak).

 -- syntax: define-external
          (define-external [QUALIFIERS] (NAME (ARGUMENTTYPE1 VARIABLE1) ...) RETURNTYPE BODY ...)
          (define-external NAME TYPE [INIT])
     The first form defines an externally callable Scheme procedure.
     `NAME' should be a symbol, which, when converted to a string,
     represents a legal C identifier. `ARGUMENTTYPE1 ...' and
     `RETURNTYPE' are foreign type specifiers for the argument variables
     `VAR1 ...' and the result, respectively.  `QUALIFIERS' is an
     optional qualifier for the foreign procedure definition, like
     `__stdcall'.


     (define-external (foo (c-string x)) int (string-length x))

     is equivalent to


     (define foo
       (foreign-callback-wrapper int "foo"
         (c-string) (lambda (x) (string-length x))))

     The second form of `define-external' can be used to define
     variables that are accessible from foreign code. It declares a
     global variable named by the symbol `NAME' that has the type
     `TYPE'. `INIT' can be an arbitrary expression that is used to
     initialize the variable. `NAME' is accessible from Scheme just
     like any other foreign variable defined by
     `define-foreign-variable'.


     (define-external foo int 42)
     ((foreign-lambda* int ()
       "return(foo);"))           ==> 42

     Note: don't be tempted to assign strings or bytevectors to
     external variables. Garbage collection moves those objects around,
     so it is very bad idea to assign pointers to heap-data. If you
     have to do so, then copy the data object into statically allocated
     memory (for example by using `object-evict').


 -- syntax: foreign-callback-wrapper
          (foreign-callback-wrapper RETURNTYPE NAME [QUALIFIERS] (ARGUMENTTYPE1 ...) EXP)
     Defines an externally callable wrapper around the procedure `EXP'.
     `EXP' must be a lambda expression of the form `(lambda ...)'. The
     wrapper will have the name `NAME' and will have a signature as
     specified in the return- and argument-types given in `RETURNTYPE'
     and `ARGUMENTTYPE1 ...'.  `QUALIFIERS' is a qualifier string for
     the function definition (see `define-external').

 -- C function: C_word C_callback (C_word closure, int argc)
     This function can be used to invoke the Scheme procedure `closure'.
     `argc' should contain the number of arguments that are passed to
     the procedure on the temporary stack. Values are put onto the
     temporary stack with the `C_save' macro.


File: chicken.info,  Node: Locations,  Next: Other support procedures,  Prev: Callbacks,  Up: Interface to external functions and variables

6.5 Locations
=============

It is also possible to define variables containing unboxed C data, so
called _locations_. It should be noted that locations may only contain
simple data, that is: everything that fits into a machine word, and
double-precision floating point values.

 -- syntax: define-location
          (define-location NAME TYPE [INIT])
     Identical to `(define-external NAME TYPE [INIT])', but the variable
     is not accessible from outside of the current compilation unit (it
     is declared `static').


 -- syntax: let-location
          (let-location ((NAME TYPE [INIT]) ...) BODY ...)
     Defines a lexically bound location.


 -- syntax: location
          (location NAME)
          (location X)
     This form returns a pointer object that contains the address of
     the variable `NAME'.  If the argument to `location' is not a
     location defined by `define-location', `define-external' or
     `let-location', then


     (location X)

     is essentially equivalent to


     (make-locative X)

     (See the manual chapter or `locatives' for more information about
     locatives.

     Note that `(location X)' may be abbreviated as `#$X'.


     (define-external foo int)
     ((foreign-lambda* void (((pointer int) ip)) "*ip = 123;")
       (location foo))
     foo                                                                               ==> 123

     This facility is especially useful in situations, where a C
     function returns more than one result value:


     #>
     #include <math.h>
     <#

     (define modf
       (foreign-lambda double "modf" double (pointer double)) )

     (let-location ([i double])
       (let ([f (modf 1.99 (location i))])
         (print "i=" i ", f=" f) ) )

   `location' returns a value of type `c-pointer', when given the name
of a callback-procedure defined with `define-external'.


File: chicken.info,  Node: Other support procedures,  Next: The Easy Foreign Function Interface,  Prev: Locations,  Up: Interface to external functions and variables

6.6 Other support procedures
============================

 -- procedure: argc+argv
          (argc+argv)
     Returns two values: an integer and a foreign-pointer object
     representing the `argc' and `argv' arguments passed to the current
     process.


File: chicken.info,  Node: The Easy Foreign Function Interface,  Next: C interface,  Prev: Other support procedures,  Up: Interface to external functions and variables

6.7 The _Easy_ Foreign Function Interface
=========================================

The compiler contains a builtin parser for a restricted subset of C and
C++ that allows the easy generation of foreign variable declarations,
procedure bindings and C++ class wrappers. The parser is invoked via
the declaration-specifier `foreign-parse', which extracts binding
information and generates the necessary code. An example:


(declare
  (foreign-declare "
#include <math.h>

#define my_pi 3.14
")
  (foreign-parse "extern double sin(double);") )

(print (sin 3.14))

   The parser would generate code that is equivalent to


(declare
  (foreign-declare "
#include <math.h>

#define my_pi 3.14
")

(define-foreign-variable my_pi float "my_pi")
(define sin (foreign-lambda double "sin" double))

   Note that the read syntax `#>[SPEC] ... <#' provides a somewhat
simpler way of using the parser. The example above could alternatively
be expressed as


#>!
#define my_pi 3.14

extern double sin(double);
<#

(print (sin 3.14))

   Another example, here using C++. Consider the following class:


// file: foo.h

class Foo {
 private:
  int x_;
 public:
  Foo(int x);
  void setX(int x);
  int getX();
};

   To generate a wrapper class that provides generic functions for the
constructor and the `setX' and `getX' methods, we can use the following
class definition:


; file: test-foo.scm

(require-extension tinyclos)

#>!
#include "Foo.h"
<#

(define x (make <Foo> 99))
(print (getX x))              ; prints ``99''
(setX x 42)
(print (getX x))              ; prints ``42''
(destroy x)

   Provided the file `foo.o' contains the implementation of the class
`Foo', the given example could be compiled like this (assuming a UNIX
like environment):


% csc test-foo.scm foo.o -c++

   Here is another example, a minimal "Hello world" application for QT.
We can see the three different ways of embedding C/C++ code in Scheme:


; compile like this:
; csc hello.scm -c++ -C -IQTDIR/include -L "-LQTDIR/lib -lqt"

(require-extension tinyclos)

; Include into generated code, but don't parse:
#>
#include <qapplication.h>
#include <qpushbutton.h>
<#

; Parse but don't embed: we only want wrappers for a few classes:
#>?
class QWidget
{
public:
  void resize(int, int);
  void show();
};

class QApplication
{
public:
  QApplication(int, char **);
  ~QApplication();
  void setMainWidget(QWidget *);
  void exec();
};

class QPushButton : public QWidget
{
public:
  QPushButton(char *, QWidget *);
  ~QPushButton();
}
<#

(define a (apply make <QApplication> (receive (argc+argv))))
(define hello (make <QPushButton> "hello world!" #f))
(resize hello 100 30)
(setMainWidget a hello)
(show hello)
(exec a)
(destroy hello)
(destroy a)

* Menu:

* #> ... <# Syntax::
* General operation::
* Pseudo declarations::
* Grammar::
* C notes::
* C++ notes::
* Using the builtin parser::
* Specification grammar::


File: chicken.info,  Node: #> ... <# Syntax,  Next: General operation,  Up: The Easy Foreign Function Interface

6.7.1 `#> ... <#' Syntax
------------------------

Occurrences of the special read syntax `#>[SPEC ...] ...<#' will be
handled according to `SPEC':

   If `SPEC' is the `?' character, the text following up to the next
`<#' will be processed as a `(declare (foreign-parse "..."))'
declaration (the code will be processed by the FFI parser described in
this section).

   If `SPEC' is the `!' character, the text will be embedded as


(declare
  (foreign-declare "...")
  (foreign-parse "...") )

   It will be both included verbatim in the declaration section of the
generated C/C++ file and processed by the FFI parser.

   If `SPEC' is the `:' character, the text will be so it will be
executed at the location where it appears.

   If `SPEC' is the `$' character, the text will be parsed and the
generated Scheme code is returned as a `(foreign-parse CODE') form.

   If `SPEC' is the `%' character, the text will be parsed into an
s-expression that specifies the parsed entities, wrapped in a
`(foreign-parse/spec ...)' form. See below for details of the
specification format.

   If `SPEC' is a list of the form `(TAG ...)', then each `TAG' (which
should be a symbol) specifies what should be done with the text:

`declare'
     (declare (foreign-declare "..."))

`parse'
     (declare (foreign-parse "..."))

`execute'
     (foreign-code "...")

`code'
     (foreign-parse "...")

`spec'
     (foreign-parse/spec "...")

   If any other character follows the `#>', then the complete text will
be included verbatim in the declaration part of the generated file (as
in a `foreign-declare' declaration).


File: chicken.info,  Node: General operation,  Next: Pseudo declarations,  Prev: #> ... <# Syntax,  Up: The Easy Foreign Function Interface

6.7.2 General operation
-----------------------

The parser will generally perform the following functions

   1) Translate macro, enum-definitions and constants into
`define-foreign-variable' or `define-constant' forms

   2) Translate function prototypes into `foreign-lambda' forms

   3) Translate variable declarations into accessor procedures

   4) Handle basic preprocessor operations

   5) Translate simple C++ class definitions into TinyCLOS wrapper
classes and methods

   Basic token-substitution of macros defined via `#define' is
performed. The preprocessor commands `#ifdef', `#ifndef', `#else',
`#endif', `#undef' and `#error' are handled. The preprocessor commands
`#if' and `#elif' are not supported and will signal an error when
encountered by the parser, because C expressions (even if constant) are
not parsed.  The preprocessor command `#pragma' is allowed but will be
ignored.

   During processing of `foreign-parse' declarations the macro
`CHICKEN' is defined (similar to the C compiler option `-DCHICKEN').

   Macro- and type-definitions are available in subsequent
`foreign-parse' forms.  C variables declared generate a procedure with
zero or one argument with the same name as the variable. When called
with no arguments, the procedure returns the current value of the
variable. When called with an argument, then the variable is set to the
value of that argument.  C and C++ style comments are supported.
Variables declared as `const' will generate normal Scheme variables,
bound to the initial value of the variable.

   Function-, member-function and constructor/destructor definitions
may be preceded by the `___callback' qualifier, which marks the
function as performing a callback into Scheme. If a wrapped function
calls back into Scheme code, and `___callback' has not been given very
strange and hard to debug problems will occur. Functions and member
functions prefixed with `___discard' and a result type that maps to a
Scheme string (`c-string'), will have their result type changed to
`c-string*' instead.

   Constants (as declared by `#define' or `enum') are not visible
outside of the current Compilation units unless the `export_constants'
pseudo declaration has been used.

   When given the option `-ffi', CHICKEN will compile a C/C++ file in
"Scheme" mode, that is, it wraps the C/C++ source inside `#>! ... <#'
and compiles it while generating Scheme bindings for exported
definitions.

   Function-arguments may be preceded by `___in', `___out' and
`___inout' qualifiers to specify values that are passed by reference to
a function, or returned by reference. Only basic types (numbers and
characters) can be passed using this method.  During the call a pointer
to a temporary piece of storage will be allocated and passed to the
wrapped function. This piece of storage is subject to garbage
collection and will move, should a callback into Scheme occur that
triggers a garbage collection. Multiple `__out' and `___inout'
parameters will be returned as multiple values, preceded by the normal
return value of thhe function (if not `void'). Here is a simpl example:


#>!
#ifndef CHICKEN
#include <math.h>
#endif

double modf(double x, ___out double *iptr);
<#

(let-values ([(frac int) (modf 33.44)])
  ...)

   Structure and union definitions containing actual field declarations
generate getter procedures (and setter procedures when declared
`___mutable' or the `mutable_fields' pseudo declaration has been used)
The names of these procedures are computed by concatenating the struct
(or union) name, a hyphen (`"-"') and the field name, and the string
`"-set!"', in the case of setters. Structure definitions with fields
may not be used in positions where a type specifier is normally
expected. The field accessors operate on struct/union pointers only.
Additionally a zero-argument procedure named `make-<structname>' will
be generated that allocates enough storage to hold an instance of the
structure (or union).  Prefixing the definition with `___abstract' will
omit the creation procedure.


#>!
struct My_struct { int x; ___mutable float y; };

typedef struct My_struct My_struct;

My_struct *make_struct(int x, float y)
{
  My_struct *s = (My_struct *)malloc(sizeof(My_struct));
  s->x = x;
  s->y = y;
  return s;
}
<#

   will generate the following definitions:

     (make-My_struct) -> PTR
     (My_struct-x PTR) -> INT
     (My_struct-y PTR) -> FLOAT
     (My_struct-y-set! PTR FLOAT)
     (make_struct INT FLOAT) -> PTR

   Nested structs or unions are not supported (but pointers to nested
structs/unions are).

   All specially handled tokens preceded with `___' are defined as C
macros in the headerfile `chicken.h' and will usually expand into
nothing, so they don't invalidate the processed source code.

   C++ `namespace' declarations of the form `namespace NAME { ... }'
recognized but will be completely ignored.

   Keep in mind that this is not a fully general C/C++ parser. Taking
an arbitrary headerfile and feeding it to CHICKEN will in most cases
not work or generate riduculuous amounts of code. This FFI facility is
for carefully written headerfiles, and for declarations directly
embedded into Scheme code.


File: chicken.info,  Node: Pseudo declarations,  Next: Grammar,  Prev: General operation,  Up: The Easy Foreign Function Interface

6.7.3 Pseudo declarations
-------------------------

Using the `___declare(DECL, VALUE)' form, pseudo declarations can be
embedded into processed C/C++ code to provide additional control over
the wrapper generation. Pseudo declarations will be ignored when
processed by the system's C/C++ compiler.

   * abstract [values: <string>] Marks the C++ class given in
     `<string>' as being abstract, i.e. no constructor will be defined.
     Alternatively, a class definition may be prefixed with
     `___abstract'.

   * class_finalizers [values: yes, no] Automatically generates calls
     to `set-finalizer!' so that any unused references to instances of
     subsequently defined C++ class wrappers will be destroyed. This
     should be used with care: if the embedded C++ object which is
     represented by the reclaimed TinyCLOS instance is still in use in
     foreign code, then unpredictable things will happen.

   * mutable_fields [values: yes, no] Specifies that all struct or
     union fields should generate setter procedures (the default is to
     generate only setter procedures for fields declared `___mutable').

   * destructor_name [values: <string>] Specifies an alternative name
     for destructor methods (the default is `destroy'.

   * export_constants [values: yes (default), no] Define a global
     variable for constant-declarations (as with `#define' or `enum'),
     making the constant available outside the current compilation
     unit. Use the values `yes'/`1' for switching constant export on,
     or `no'/`0' for switching it off.

   * exception_handler [values: <string>] Defines C++ code to be
     executed when an exception is triggered inside a C++ class member
     function. The code should be one or more `catch' forms that
     perform any actions that should be taken in case an exception is
     thrown by the wrapped member function:


     #>!
     ___declare(exception_handler, "catch(...) { return 0; }")

     class Foo {
      public:
       Foo *bar(bool f) { if(f) throw 123; else return this; }
     };
     <#

     (define f1 (make <Foo>))
     (print (bar f1 #f))
     (print (bar f1 #t))

     will print `<Foo>' and `#f', respectively.

   * full_specialization [values: yes, no] Enables "full
     specialization" mode. In this mode all wrappers for functions,
     member functions and static member functions are created as fully
     specialized TinyCLOS methods. This can be used to handle
     overloaded C++ functions properly. Only a certain set of foreign
     argument types can be mapped to TinyCLOS classes, as listed in the
     following table:

    `char'
          <char>

    `bool'
          <bool>

    `c-string'
          <string>

    `unsigned-char'
          <exact>

    `byte'
          <exact>

    `unsigned-byte'
          <exact>

    `[unsigned-]int'
          <exact>

    `[unsigned-]short'
          <exact>

    `[unsigned-]long'
          <integer>

    `[unsigned-]integer'
          <integer>

    `float'
          <inexact>

    `double'
          <inexact>

    `number'
          <number>

    `(enum _)char'
          <exact>

    `(const T)char'
          (as T)

    `(function ...)'
          <pointer>

    `c-pointer'
          <pointer>

    `(pointer _)'
          <pointer>

    `(c-pointer _)'
          <pointer>

    `u8vector'
          <u8vector>

    `s8vector'
          <s8vector>

    `u16vector'
          <u16vector>

    `s16vector'
          <s16vector>

    `u32vector'
          <u32vector>

    `s32vector'
          <s32vector>

    `f32vector'
          <f32vector>

    `f64vector'
          <f64vector>

     All other foreign types are specialized as `<top>'.

     Full specialization can be enabled globally, or only for sections
     of code by enclosing it in


     ___declare(full_specialization, yes)
     ...
     int foo(int x);
     int foo(char *x);
     ...
     ___declare(full_specialization, no)

     Alternatively, member function definitions may be prefixed by
     `___specialize' for specializing only specific members.

   * prefix [values: <string>]

     Sets a prefix that should be be added to all generated Scheme
     identifiers. For example


     ___declare(prefix, "mylib:")
     #define SOME_CONST     42

     would generate the following code:


     (define-constant mylib:SOME_CONST 42)

     To switch prefixing off, use the values `no' or `0'. Prefixes are
     not applied to Class names.

   * rename [value: <string>]

     Defines to what a certain C/C++ name should be renamed. The value
     for this declaration should have the form
     `"<c-name>;<scheme-name>"', where `<c-name>' specifies the C/C++
     identifier occurring in the parsed text and `<scheme-name>' gives
     the name used in generated wrapper code.

   * scheme [value: <string>]

     Embeds the Scheme expression `<string>' in the generated Scheme
     code.

   * substitute [value: <string>]

     Declares a name-substitution for all generated Scheme identifiers.
     The value for this declaration should be a string containing a
     regular expression and a replacement string (seperated by the `;'
     character):


     ___declare(substitute, "^SDL_;sdl:")

     extern void SDL_Quit();

     generates


     (define sdl:Quit
       (foreign-lambda integer "SDL_Quit") )

   * transform [values: <string>]

     Defines an arbitrary transformation procedure for names that match
     a given regular expression.  The value should be a string
     containing a regular expression and a Scheme expression that
     evaluates to a procedure of one argument. If the regex matches,
     the procedure will be called at compile time with the match-result
     (as returned by `string-match') and should return a string with
     the desired transformations applied:


     (require-for-syntax 'srfi-13)

     #>!
     ___declare(transform, "([A-Z]+)_(.*);(lambda (x) (string-append (cadr x) \"-\" (string-downcase (caddr x))))")

     void FOO_Bar(int x) { return x * 2; }
     <#

     (print (FOO-bar 33))

   * type [value: <string>]

     Declares a foreign type transformation, similar to
     `define-foreign-type'.  The value should be a list of two to four
     items, separated by the `;' character: a C typename, a Scheme
     foreign type specifier and optional argument- and result-value
     conversion procedures.


     ;;;; foreign type that converts to unicode (assumes 4-byte wchar_t):
     ;
     ; - Note: this is rather kludgy is only meant to demonstrate the `type'
     ;         pseudo-declaration

     (require-extension srfi-4)

     (define mbstowcs (foreign-lambda int "mbstowcs" nonnull-u32vector c-string int))

     (define (str->ustr str)
       (let* ([len (string-length str)]
              [us (make-u32vector (add1 len) 0)] )
         (mbstowcs us str len)
         us) )

     #>!
     ___declare(type, "unicode;nonnull-u32vector;str->ustr")

     static void foo(unicode ws)
     {
       printf("\"%ls\"\n", ws);
     }
     <#

     (foo "this is a test!")



File: chicken.info,  Node: Grammar,  Next: C notes,  Prev: Pseudo declarations,  Up: The Easy Foreign Function Interface

6.7.4 Grammar
-------------

The parser understand the following grammar:


PROGRAM = PPCOMMAND
        | DECLARATION ";"

PPCOMMAND = "#define" ID [TOKEN ...]
          | "#ifdef" ID
          | "#ifndef" ID
          | "#else"
          | "#endif"
          | "#undef" ID
          | "#error" TOKEN ...
          | "#include" INCLUDEFILE
          | "#pragma" TOKEN ...

DECLARATION = FUNCTION
            | VARIABLE
            | ENUM
            | TYPEDEF
            | CLASS
            | CONSTANT
            | STRUCT
            | NAMESPACE
            | "___declare" "(" PSEUDODECL "," <tokens> ")"

STRUCT = ("struct" | "union") ID ["{" {["___mutable"] TYPE {"*"} ID {"," {"*"} ID}} "}]

NAMESPACE = "namespace" ID "{" DECLARATION ... "}"

INCLUDEFILE = "\"" ... "\""
            | "<" ... ">"

FUNCTION = {"___callback" | "___specialize" | "___discard"} [STORAGE] TYPE ID "(" ARGTYPE "," ... ")" [CODE]
         | {"___callback" | "___specialize" | "___discard"} [STORAGE] TYPE ID "(" "void" ")" [CODE]

ARGTYPE = [IOQUALIFIER] TYPE [ID ["[" ... "]"]]

IOQUALIFIER = "___in" | "___out" | "___inout"

VARIABLE = [STORAGE] ENTITY ["=" INITDATA]

ENTITY = TYPE ID ["[" ... "]"]

STORAGE = "extern" | "static" | "volatile" | "inline"

CONSTANT = "const" TYPE ID "=" INITDATA

PSEUDODECL = "export_constants"
           | "prefix"
           | "substitute"
           | "abstract"
           | "type"
           | "scheme"
           | "rename"
           | "transform"
           | "full_specialization"
           | "destructor_name"
           | "class_finalizers"
           | "exception_handler"
           | "mutable_fields"

ENUM = "enum" "{" ID ["=" NUMBER] "," ... "}"

TYPEDEF = "typedef" TYPE ["*" ...] [ID]

TYPE = ["const"] BASICTYPE [("*" ... | "&" | "<" TYPE "," ... ">" | "(" "*" [ID] ")" "(" TYPE "," ... ")")]

BASICTYPE = ["unsigned" | "signed"] "int"
          | ["unsigned" | "signed"] "char"
          | ["unsigned" | "signed"] "short" ["int"]
          | ["unsigned" | "signed"] "long" ["int"]
          | ["unsigned" | "signed"] "___byte"
          | "float"
          | "double"
          | "void"
          | "bool"
          | "___bool"
          | "___scheme_value"
          | "___fixnum"
          | "___number"
          | "___symbol"
          | "struct" ID
          | "union" ID
          | "enum" ID
          | ID

CLASS = ["___abstract"] "class" ID [":" [QUALIFIER] ID "," ...] "{" MEMBER ... "}"

MEMBER = [QUALIFIER ":"] ["virtual"] (MEMBERVARIABLE | CONSTRUCTOR | DESTRUCTOR | MEMBERFUNCTION)

MEMBERVARIABLE = TYPE ID ["=" INITDATA]

MEMBERFUNCTION = {"___callback" | "static" | "___specialize" | "___discard"} TYPE ID "(" ARGTYPE "," ... ")" ["const"] ["=" "0"] [CODE]
               | {"___callback" | "static" | "___specialize" | "___discard"} TYPE ID "(" "void" ")" ["const"] ["=" "0"] [CODE]

CONSTRUCTOR = ["___callback"] ["explicit"] ID "(" ARGTYPE "," ... ")" [BASECONSTRUCTORS] [CODE]

DESTRUCTOR = ["___callback"] "~" ID "(" ["void"] ")" [CODE]

QUALIFIER = ("public" | "private" | "protected")

NUMBER = <a C integer or floating-point number, in decimal, octal or hexadecimal notation>

INITDATA = <everything up to end of chunk>

BASECONSTRUCTORS = <everything up to end of chunk>

CODE = <everything up to end of chunk>

   The following table shows how argument-types are translated:

`[unsigned] char'
     char

`[unsigned] short'
     [unsigned-]short

`[unsigned] int'
     [unsigned-]integer

`[unsigned] long'
     [unsigned-]long

`float'
     float

`double'
     double

`bool'
     int

`___bool'
     int

`___fixnum'
     int

`___number'
     number

`___symbol'
     symbol

`___scheme_value'
     scheme-object

`char *'
     c-string

`signed char *'
     s8vector

`[signed] short *'
     s16vector

`[signed] int *'
     s32vector

`[signed] long *'
     s32vector

`unsigned char *'
     u8vector

`unsigned short *'
     u16vector

`unsigned int *'
     u32vector

`unsigned long *'
     u32vector

`float *'
     f32vector

`double *'
     f64vector

`CLASS *'
     (instance CLASS <CLASS>)

`CLASS &'
     (instance-ref CLASS <CLASS>)

`TYPE *'
     (pointer TYPE)

`TYPE'
     &(ref TYPE)

`TYPE<T1, ...>'
     (template TYPE T1 ...)

`TYPE1 (*)(TYPE2, ...)'
     (function TYPE1 (TYPE2 ...))

   The following table shows how result-types are translated:

`void'
     void

`[unsigned] char'
     char

`[unsigned] short'
     [unsigned-]short

`[unsigned] int'
     [unsigned-]integer

`[unsigned] long'
     [unsigned-]long

`float'
     float

`double'
     double

`bool'
     bool

`___bool'
     bool

`___fixnum'
     int

`___number'
     number

`___symbol'
     symbol

`___scheme_value'
     scheme-object

`char *'
     c-string

`TYPE *'
     (pointer TYPE)

`TYPE'
     &(ref TYPE)

`TYPE<T1, ...>'
     (template TYPE T1 ...)

`TYPE1 (*)(TYPE2, ...)'
     (function TYPE1 (TYPE2 ...))

`CLASS *'
     (instance CLASS <CLASS>)

`CLASS &'
     (instance-ref CLASS <CLASS>)


File: chicken.info,  Node: C notes,  Next: C++ notes,  Prev: Grammar,  Up: The Easy Foreign Function Interface

6.7.5 C notes
-------------

Foreign variable definitions for macros are not exported from the
current compilation unit, but definitions for C variables and functions
are.

   `foreign-parse' does not embed the text into the generated C file,
use `foreign-declare' for that (or even better, use the `#>! ... <#'
syntax which does both).

   Functions with variable number of arguments are not supported.


File: chicken.info,  Node: C++ notes,  Next: Using the builtin parser,  Prev: C notes,  Up: The Easy Foreign Function Interface

6.7.6 C++ notes
---------------

Each C++ class defines a TinyCLOS class, which is a subclass of
`<c++-object>'. Instances of this class contain a single slot named
`this', which holds a pointer to a heap-allocated C++ instance.  The
name of the TinyCLOS class is obtained by putting the C++ classname
between angled brackets (`<...>').  TinyCLOS classes are not seen by
C++ code.

   The C++ constructor is invoked by the `initialize' generic, which
accepts as many arguments as the constructor. If no constructor is
defined, a default-constructor will be provided taking no arguments.
To allow creating class instances from pointers created in foreign
code, the `initialize' generic will optionally accept an arguments list
of the form `'this POINTER', where `POINTER' is a foreign pointer
object. This will create a TinyCLOS instance for the given C++ object.

   To release the storage allocated for a C++ instance invoke the
`destroy' generic (the name can be changed by using the
`destructor_name' pseudo declaration).

   Static member functions are wrapped in a Scheme procedure named
`<class>::<member>'.

   Member variables and non-public member functions are ignored.

   Virtual member functions are not seen by C++ code. Overriding a
virtual member function with a TinyCLOS method will not work when the
member function is called by C++.

   Operator functions and default arguments are not supported.

   Exceptions must be explicitly handled by user code and may not be
thrown beyond an invocation of C++ by Scheme code.


File: chicken.info,  Node: Using the builtin parser,  Next: Specification grammar,  Prev: C++ notes,  Up: The Easy Foreign Function Interface

6.7.7 Using the builtin parser
------------------------------

There are two macros that can be used (in addition to the `#>$ ... <#'
reader syntax) to access the parsed C/C++ code directly. These macros
are by default undefined. To perform custom processing of the parsed
Scheme code or FFI specification, define the macros as you please.

 -- foreign-parse: syntax
          (foreign-parse EXP)
     Should be defined to perform custom processing of Scheme code
     wrapped in a `#>$ ... <#' construct.

 -- foreign-parse/spec: syntax
          (foreign-parse/spec EXP)
     Should be defined to perform custom processing of an FFI
     specification wrapped in a `#>% ... <#' construct.

     For example:


     (define-macro (foreign-parse/spec x)
       `(pp ',x) )

     #>%
     int foo(double n) { return n * 2; }

     typedef short *mytype;

     class Bar: public Yo, Foo {
     public:
       Bar(int, char *);
       ~Bar();

       void *myfun(mytype x);
     };
     <#

     will expand into:

          (pp '(begin
                 (function (foo "foo") integer double)
                 (class (<Bar> "Bar") (<c++-object>))
                 (destructor (<Bar> "Bar") destroy)
                 (constructor (<Bar> "Bar") integer c-string)
                 (imethod
                   (myfun "myfun")
                   (<Bar> "Bar")
                   (pointer void)
                   (<s16vector> s16vector))))



File: chicken.info,  Node: Specification grammar,  Prev: Using the builtin parser,  Up: The Easy Foreign Function Interface

6.7.8 Specification grammar
---------------------------

The following table describes the grammar of specifications parsed by
the `#>% ... <#' construct.

   `IDs' is a symbol, naming a Scheme identifier. `IDc' is a string
naming a C/C++ entity. `VALUE' is a Scheme numeric constant. `TYPE' is a
foreign type specifier. Most identifiers are given in pairs of the form
`(IDs IDc)', where `IDs' is a version of the C identifier `IDc' with
all renamings performed (and in the case of class-names enclosed in in
`<...>').

`(begin SPEC ...)'
     Contains zero or more specification items.

`(alias (IDs IDc) TYPE)'
     Defines an alias of the name `IDs' for the C/C++ entity `IDc'
     (usually a variable) with the type `TYPE'.

`(constant IDs VALUE)'
     Defines a named constant.

`(type IDs IDs [EXP1 [EXP2]]))'
     A user defined foreign type (just like `define-foreign-type').

`(variable (IDs IDc) TYPE)'
     A variable.

`(cvariable (IDs IDc) TYPE)'
     A constant (immutable) variable.

`(function (IDs IDc) TYPEr TYPEa ...)'
     A function with the result type `TYPEr' and the argument types
     `TYPEa ...'.

`(function* (IDs IDc) TYPEr TYPEa ...)'
     A function that may invoke callbacks.

`(method (IDs IDc) TYPEr (CLASS TYPEa) ...)'
     A generic function method. The corresponding TinyCLOS classes for
     each argument type are also provided.

`(method* (IDs IDc) TYPEr (CLASS TYPEa) ...)'
     A generic function method that may invoke callbacks.

`(imethod (ID1s ID1c) (ID1s ID1c) TYPEr (CLASS TYPEa) ...)'
     An instance method. The first identifier-pair names the method and
     the second names the class.

`(class (IDs IDc) (IDs ...))'
     A class definition. The list `(IDs ...)' names the super-classes
     and defaults to `<c++-object>'.

`(constructor (IDs IDc) TYPEa ...)'
     A class constructor with a given list of argument types.

`(constructor* (IDs IDc) TYPEa ...)'
     A class constructor that should generate instances which are
     automatically finalized.

`(destructor (IDs IDc) IDs)'
     A class destructor. The second identifier specifies how the
     destructor method should be named.

`(export IDs)'
     Make the Scheme identifier `IDs' be globally visible (it is
     assumed constants and aliases are not globally visible by default).

`(struct-field IDc FIELDIDs TYPE GETTER [SETTER])'
     A structure field with the name `FIELDIDs' of the structure named
     `IDc' and with the type `TYPE'. `GETTER' and `SETTER' (when given)
     specify the names of any accessor procedures.

`(union-field IDc FIELDIDs TYPE GETTER [SETTER])'
     As above, but for a union field.

`(struct-maker IDc CONSIDs (TYPE FIELDIDc) ...)'
     A structure constructor for the C struct `IDc' field the name
     `CONSIDs' and the field-initializer arguments and types given in
     `(TYPE FIELDIDc) ...'.

`(union-maker IDc CONSIDs (TYPE FIELDIDc) ...)'
     A union-constructor.


File: chicken.info,  Node: C interface,  Prev: The Easy Foreign Function Interface,  Up: Interface to external functions and variables

6.8 C interface
===============

The following functions and macros are available for C code that invokes
Scheme or foreign procedures that are called by Scheme:

 -- C function: void C_save (C_word x)
     Saves the Scheme data object `x' on the temporary stack.

 -- C macro: C_word C_fix (int integer)
 -- C macro: C_word C_make_character (int char_code)
 -- C macro: C_word C_SCHEME_END_OF_LIST
 -- C macro: C_word C_SCHEME_END_OF_FILE
 -- C macro: C_word C_SCHEME_FALSE
 -- C macro: C_word C_SCHEME_TRUE
     These macros return immediate Scheme data objects.

 -- C function: C_word C_string (C_word **ptr, int length, char *string)
 -- C function: C_word C_string2 (C_word **ptr, char
          *zero_terminated_string)
 -- C function: C_word C_intern2 (C_word **ptr, char
          *zero_terminated_string)
 -- C function: C_word C_intern3 (C_word **ptr, char
          *zero_terminated_string, C_word initial_value)
 -- C function: C_word C_pair (C_word **ptr, C_word car, C_word cdr)
 -- C function: C_word C_flonum (C_word **ptr, double number)
 -- C function: C_word C_int_to_num (C_word **ptr, int integer)
 -- C function: C_word C_mpointer (C_word **ptr, void *pointer)
 -- C function: C_word C_vector (C_word **ptr, int length, ...)
 -- C function: C_word C_list (C_word **ptr, int length, ...)
     These functions allocate memory from `ptr' and initialize a fresh
     data object. The new data object is returned. `ptr' should be the
     address of an allocation pointer created with `C_alloc'.

 -- C macro: C_word* C_alloc (int words)
     Allocates memory from the C stack (`C_alloc') and returns a
     pointer to it. `words' should be the number of words needed for
     all data objects that are to be created in this function.  Note
     that stack-allocated data objects have to be passed to Scheme
     callback functions, or they will not be seen by the garbage
     collector. This is really only usable for callback procedure
     invocations, make sure not to use it in normal code, because the
     allocated memory will be re-used after the foreign procedure
     returns. When invoking Scheme callback procedures a minor garbage
     collection is performed, so data allocated with `C_alloc' will
     already have moved to a safe place.

 -- C macro: int C_SIZEOF_LIST (int length)
 -- C macro: int C_SIZEOF_STRING (int length)
 -- C macro: int C_SIZEOF_VECTOR (int length)
 -- C macro: int C_SIZEOF_INTERNED_SYMBOL (int length)
 -- C macro: int C_SIZEOF_PAIR
 -- C macro: int C_SIZEOF_FLONUM
 -- C macro: int C_SIZEOF_POINTER
 -- C macro: int C_SIZEOF_LOCATIVE
 -- C macro: int C_SIZEOF_TAGGED_POINTER
     These are macros that return the size in words needed for a data
     object of a given type.

 -- C macro: int C_character_code (C_word character)
 -- C macro: int C_unfix (C_word fixnum)
 -- C macro: double C_flonum_magnitude (C_word flonum)
 -- C function: char* C_c_string (C_word string)
 -- C function: int C_num_to_int (C_word fixnum_or_flonum)
 -- C function: void* C_pointer_address (C_word pointer)
     These macros and functions can be used to convert Scheme data
     objects back to C data.

 -- C macro: int C_header_size (C_word x)
 -- C macro: int C_header_bits (C_word x)
     Return the number of elements and the type-bits of the
     non-immediate Scheme data object `x'.

 -- C macro: C_word C_block_item (C_word x, int index)
     This macro can be used to access slots of the non-immediate Scheme
     data object `x'.  `index' specifies the index of the slot to be
     fetched, starting at 0. Pairs have 2 slots, one for the car and
     one for the cdr. Vectors have one slot for each element.

 -- C macro: void* C_data_pointer (C_word x)
     Returns a pointer to the data-section of a non-immediate Scheme
     object.

 -- C macro: C_word C_make_header (C_word bits, C_word size)
     A macro to build a Scheme object header from its bits and size
     parts.

 -- C function: C_word C_mutate (C_word *slot, C_word val)
     Assign the Scheme value `val' to the location specified by `slot'.
     If the value points to data inside the nursery (the first
     heap-generation), then the garbage collector will remember to
     handle the data appropriately. Assigning nursery-pointers directly
     will otherwise result in lost data.

 -- C macro: C_word C_symbol_value (C_word symbol)
     Returns the global value of the variable with the name `symbol'.

 -- C function: void C_gc_protect (C_word *ptrs[], int n)
     Registers `n' variables at address `ptrs' to be garbage collection
     roots.  The locations should not contain pointers to data
     allocated in the nursery, only immediate values or pointers to
     heap-data are valid. Any assignment of potential nursery data into
     a root-array should be done via `C_mutate()'. The variables have
     to be initialized to sensible values before the next garbage
     collection starts (when in doubt, set all locations in `ptrs' to
     `C_SCHEME_UNDEFINED') `C_gc_protect' may not called before the
     runtime system has been iniitalized (either by
     `CHICKEN_initialize', `CHICKEN_run' or `CHICKEN_invoke'.

 -- C function: void C_gc_unprotect (int n)
     Removes the last `n' registered variables from the set of root
     variables.

 -- C Variable: void (*C_post_gc_hook)(int mode)
     If not `NULL', the function pointed to by this variable will be
     called after each garbage collection with a flag indicating what
     kind of collection was performed (either `0' for a minor
     collection or `1' for a major collection). Minor collections
     happen very frequently, so the hook function should not consume
     too much time. The hook function may not invoke Scheme callbacks.

   An example:


% cat foo.scm
#>
extern int callout(int, int, int);
<#

(define callout (foreign-callback-lambda int "callout" int int int))

(define-external (callin (scheme-object xyz)) int
  (print "This is 'callin': " xyz)
  123)

(print (callout 1 2 3))

% cat bar.c
#include <stdio.h>
#include "chicken.h"

extern int callout(int, int, int);
extern int callin(C_word x);

int callout(int x, int y, int z)
{
  C_word *ptr = C_alloc(C_SIZEOF_LIST(3));
  C_word lst;

  printf("This is 'callout': %d, %d, %d\n", x, y, z);
  lst = C_list(&ptr, 3, C_fix(x), C_fix(y), C_fix(z));
  return callin(lst);  /* Note: `callin' will have GC'd the data in `ptr' */
}

% chicken foo.scm -quiet
% gcc foo.c bar.c -o foo `chicken-config -cflags -libs`
% foo
This is 'callout': 1, 2, 3
This is 'callin': (1 2 3)
123

   Notes:
   * Scheme procedures can call C functions, and C functions can call
     Scheme procedures, but for every pending C stack frame, the
     available size of the first heap generation (the "nursery") will
     be decreased, because the C stack is identical to the nursery. On
     systems with a small nursery this might result in thrashing, since
     the C code between the invocation of C from Scheme and the actual
     calling back to Scheme might build up several stack-frames or
     allocates large amounts of stack data.  To prevent this it is
     advisable to increase the default nursery size, either when
     compiling the file (using the `-nursery' option) or when running
     the executable (using the `-:s' runtime option).

   * Calls to Scheme/C may be nested arbitrarily, and Scheme
     continuations can be invoked as usual, but keep in mind that C
     stack frames will not be recovered, when a Scheme procedure call
     from C does not return normally.

   * When multiple threads are running concurrently, and control
     switches from one thread to another, then the continuation of the
     current thread is captured and saved. Any pending C stack frame
     still active from a callback will remain on the stack until the
     threads is re-activated again. This means that in a multithreading
     situation, when C callbacks are involved, the available nursery
     space can be smaller than expected.  So doing many nested
     Scheme->C->Scheme calls can reduce the available memory up to the
     point of thrashing. It is advisable to have only a single thread
     with pending C stack-frames at any given time.

   * Pointers to Scheme data objects should not be stored in local or
     global variables while calling back to Scheme.  Any Scheme object
     not passed back to Scheme will be reclaimed or moved by the
     garbage collector.

   * Calls from C to Scheme are never tail-recursive.

   * Continuations captured via `call-with-current-continuation' and
     passed to C code can be invoked like any other Scheme procedure.



File: chicken.info,  Node: chicken-setup,  Next: Additional files,  Prev: Interface to external functions and variables,  Up: Top

7 chicken-setup
***************

* Menu:

* Extension libraries::
* Installing extensions::
* Creating extensions::
* Procedures and macros available in setup scripts::
* Examples for extensions::
* `chicken-setup' reference::
* Windows notes::


File: chicken.info,  Node: Extension libraries,  Next: Installing extensions,  Up: chicken-setup

7.1 Extension libraries
=======================

Extension libraries are extensions to the core functionality provided
by the basic CHICKEN system, to be built and installed separately.  The
mechanism for loading compiled extensions is based on dynamically
loadable code and as such is only available on systems on which loading
compiled code at runtime is supported. Currently this are most
UNIX-compatible platforms that provide the `libdl' functionality like
Linux, Solaris, BSD or Mac OS X. Windows with Cygwin is supported as
well.  Windows with the Microsoft tools is partially supported.

   Note: Extension may also be normal applications or shell scripts.


File: chicken.info,  Node: Installing extensions,  Next: Creating extensions,  Prev: Extension libraries,  Up: chicken-setup

7.2 Installing extensions
=========================

To install an extension library, run the `chicken-setup' program with
the extension name as argument. If the extension consists of a single
Scheme file, then it is compiled and installed in the extension
_repository_. If it is an archive containing addition files, then the
files are extracted and the contained _setup_ script is executed. This
setup script is a normal Scheme source file, which will be interpreted
by `chicken-setup'. The complete language supported by `csi' is
available, and the library units `srfi-1 regex utils posix tcp' are
loaded. Additional libraries can of course be loaded at run-time.

   The setup script should perform all necessary steps to build the new
library (or application). After a successful build, the extension can
be installed by invoking one of the procedures `install-extension',
`install-program' or `install-script'.  These procedures will copy a
number of given files into the extension repository or in the path
where the CHICKEN executables are located (in the case of executable
programs or scripts). Additionally the list of installed files, and
user-defined metadata is stored in the repository.


File: chicken.info,  Node: Creating extensions,  Next: Procedures and macros available in setup scripts,  Prev: Installing extensions,  Up: chicken-setup

7.3 Creating extensions
=======================

Extensions can be created by creating an archive named `EXTENSION.egg'
containing all needed files plus a `.setup' script in the root
directory.  After `chicken-setup' has extracted the files, the setup
script will be invoked. There are no additional constraints on the
structure of the archive, but the setup script has to be in the root
path of the archive.


File: chicken.info,  Node: Procedures and macros available in setup scripts,  Next: Examples for extensions,  Prev: Creating extensions,  Up: chicken-setup

7.4 Procedures and macros available in setup scripts
====================================================

 -- procedure: install-extension
          (install-extension ID FILELIST [INFOLIST])
     Installs extension library with the name `ID'. All files given in
     the list of strings `FILELIST' will be copied to the extension
     repository.  The optional argument `INFOLIST' should be an
     association list that maps symbols to values, this list will be
     stored as `ID.setup' at the same location as the extension code.
     Currently the following properties are used:

      -- property: syntax
               (syntax)
          Marks the extension as syntax-only. No code is compiled, the
          extension is intended as a file containing macros to be
          loaded at compile/macro-expansion time.

      -- property: require-at-runtime
               (require-at-runtime ID ...)
          Specifies extensions that should be loaded (via `require') at
          runtime. This is mostly useful for syntax extensions that
          need additional support code at runtime.

      -- property: version
               (version STRING)
          Specifies version string.

     All other properties are currently ignored. The `FILELIST'
     argument may also be a single string.


 -- procedure: install-program
          (install-program ID FILELIST [INFOLIST])
     Similar to `install-extension', but installs an executable program
     in the executable path (usually `/usr/local/bin').

 -- procedure: install-script
          (install-program ID FILELIST [INFOLIST])
     Similar to `install-program', but additionally changes the file
     permissions of all files in `FILELIST' to executable (for
     installing shell-scripts).

 -- syntax: run
          (run FORM ...)
     Runs the shell command `FORM', which is wrapped in an implicit
     `quasiquote'.

 -- syntax: make
          (make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)
     A "make" macro that executes the expressions `COMMAND ...', when
     any of the dependents `DEPENDENT ...' have changed, to build
     `TARGET'. This is the same as the `make' extension, which is
     available separately. For more information, see make
     (http://www.call-with-current-continuation.org/eggs/make.html).

 -- procedure: patch
          (patch WHICH REGEX SUBST)
     Replaces all occurrences of the regular expression `REGEX' with
     the string `SUBST', in the file given in `WHICH'. If `WHICH' is a
     string, the file will be patched and overwritten. If `WHICH' is a
     list of the form `OLD NEW', then a different file named `NEW' will
     be generated.


File: chicken.info,  Node: Examples for extensions,  Next: `chicken-setup' reference,  Prev: Procedures and macros available in setup scripts,  Up: chicken-setup

7.5 Examples for extensions
===========================

The simplest case is a single file that does not export any syntax. For
example

     ;;;; hello.scm

     (define (hello name)
       (print "Hello, " name " !") )

   After entering


$ chicken-setup hello

   at the shell prompt, the file `hello.scm' will be compiled into a
dynamically loadable library, with the default compiler options
`-optimize-level 2 -debug-level 0 -shared'. If the compilation
succeeds, `hello.so' will be stored in the repository, together with a
file named `hello.setup' (not to be confused with a setup script - this
`.setup' file just contains an a-list with metadata).

   Use it like any other CHICKEN extension:


$ csi -quiet
#;1> (require-extension hello)
; loading /usr/local/lib/chicken/hello.so ...
#;2> (hello "me")
Hello, me!
#;3>

   For more elaborate build operations, when installing applications or
scripts, or when additional metadata should be stored for an extension,
a `setup' script is required and the script and all additional files
should be packaged in a gzipped `tar' archive.

   Here we create a simple application:

     ;;;; hello2.scm

     (print "Hello, ")
     (for-each (lambda (x) (printf "~A " x)) (command-line-arguments))
     (print "!")

   We also need a setup script:

     ;;;; hello2.setup

     (run (csc hello2.scm))  ; compile `hello2'
     (install-program 'hello2 "hello2") ; name of the extension and files to be installed

   To use it, just run `chicken-setup' in the same directory:


$ chicken-setup hello2

   Now the program `hello2' will be installed in the same location as
the other CHICKEN tools (like `chicken', `csi', etc.), which will
normally be `/usr/local/bin'.  Note that you need write-permissions for
those locations.

   Uninstallation is just as easy:


$ chicken-setup -uninstall hello2

   `chicken-setup' provides a `make' tool, so building operations can
be of arbitrary complexity. When running `chicken-setup' with an
argument `NAME', for which no associated file `NAME.setup', `NAME.egg'
or `NAME.scm' exists will ask you to download the extension via HTTP
from the default URL
`http://www.call-with-current-continuation.org/eggs'. You can use the
`-host' option to specify an alternative source location.

   Finally a somewhat more complex example: We want to package a syntax
extension with additional support code that is to be loaded at run-time
of any Scheme code that uses that extension. We create a "glass"
lambda, a procedure with free variables that can be manipulated from
outside:

     ;;;; glass.scm

     (define-macro (glass-lambda llist vars . body)
       ;; Low-level macros are fun!
       (let ([lvar (gensym)]
     	[svar (gensym)]
     	[x (gensym)]
     	[y (gensym)]
     	[yn (gensym)] )
         `(let ,(map (lambda (v) (list v #f)) vars)
            (define (,svar ,x . ,y)
     	 (let* ([,yn (pair? ,y)]
     		[,y (and ,yn (car ,y))] )
     	   (case ,x
     	     ,@(map (lambda (v)
     		      `([,v] (if ,yn
     				 (set! ,v ,y)
     				 ,v) ) )
     		    vars)
     	     (else (error "variable not found" ,x)) ) ) )
            (define ,lvar (lambda ,llist ,@body))
            (extend-procedure ,lvar ,svar) ) ) )

   Here some support code that needs to be loaded at runtime:

     ;;;; glass-support.scm

     (require-extension lolevel)

     (define glass-lambda-accessor procedure-data)
     (define (glass-lambda-ref gl v) ((procedure-data gl) v))
     (define (glass-lambda-set! gl v x) ((procedure-data gl) v x))

   The setup script looks like this:

     (run (csc -s -O2 -d0 glass-support.scm))

     (install-extension
       'glass
       '("glass.scm" "glass-support.so")
       '((syntax) (require-at-runtime glass-support)) )

   The invocation of `install-extension' provides the files that are to
be copied into the extension repository, and a metadata list that
specifies that the extension `glass' is a syntax extension and that, if
it is declared to be used by other code (either with the
`require-extension' or `require-for-syntax' form), then client code
should perform an implicit `(require 'glass-support)' at startup.

   This can be conveniently packaged as an "egg":


$ tar cfz glass.egg glass.setup glass.scm glass-support.scm

   And now we use it:


$ csi -quiet
#;1> (require-extension glass)
; loading /usr/local/lib/chicken/glass.scm ...
; loading /usr/local/lib/chicken/glass-support.so ...
#;2> (define foo (glass-lambda (x) (y) (+ x y)))
#;3> (glass-lambda-set! foo 'y 99)
#;4> (foo 33)
132


File: chicken.info,  Node: `chicken-setup' reference,  Next: Windows notes,  Prev: Examples for extensions,  Up: chicken-setup

7.6 `chicken-setup' reference
=============================

Available options:

   * `-help' Show usage information and exit.

   * `-version' Display version and exit.

   * `-repository [PATHNAME]' When used without an argument, the path
     of the extension repository is displayed on standard output. When
     given an argument, the repository pathname (and the
     `repository-path' parameter) will be set to `PATHNAME' for all
     subsequent operations. The default repository path is the
     installation library directory (usually `/usr/local/lib/chicken'),
     or (if set) the directory given in the environment variable
     `CHICKEN_REPOSITORY'.  `PATHNAME' should be an absolute pathname.

   * `-program-path [PATHNAME]' When used without an argument, the path
     for executables is displayed on standard output.  When given an
     argument, the program path for installing executables and scripts
     will be set to `PATHNAME' for all subsequent operations.
     `PATHNAME' should be an absolute pathname.

   * `-host HOSTNAME[:PORT]' Specifies alternative host for downloading
     extensions, optionally with a TCP port number (which defaults to
     80).

   * `-uninstall EXTENSION' Removes all files that were installed for
     `EXTENSION' from the file-system, together with any metadata that
     has been stored.

   * `-list' List all installed extensions and exit.

   * `-run FILENAME' Load and execute given file.

   * `-script FILENAME' Executes the given Scheme source file with all
     remaining arguments and exit. The "she-bang" shell script header
     is recognized, so you can write Scheme scripts that use
     `chicken-setup' just as with `csi'.

   * `-verbose' Display additional debug information.

   * `-keep' Keep temporary files and directories.

   * `-csc-option OPTION' Passes `OPTION' as an extra argument to
     invocations of the compiler-driver (`csc'). This works only if
     `csc' is invoked as `(run (csc ...))'.

   * `-dont-ask' Do not ask the user before trying to download required
     extensions.

   * `-no-install' Do not install generated binaries and/or support
     files. Any invocations of `install-program', `install-extension'
     or `install-script' will be be no-ops.

   * `--' Ignore all following arguments.

   Note that the options are processed exactly in the order in which
they appear in the command-line.


File: chicken.info,  Node: Windows notes,  Prev: `chicken-setup' reference,  Up: chicken-setup

7.7 Windows notes
=================

`chicken-setup' works on Windows, when compiled with Visual C++, but
depends on the `tar' and `gunzip' tools to extract the contents of an
egg. The best way is to download an egg either manually (or with
`chicken-setup -fetch') and extract its contents with a separate program
(like `winzip'). the `CHICKEN_REPOSITORY' environment variable has to
be set (in addition to `CHICKEN_HOME') to a directory where your
compiled extensions should be located.

   The `.setup' scripts will not always work under Windows, and the
extensions may require libraries that are not provided for Windows or
work differently. Under these circumstances it is recommended to
perform the required steps to build an extension manually.


File: chicken.info,  Node: Additional files,  Next: Data Representation,  Prev: chicken-setup,  Up: Top

8 Additional files
******************

In addition to library units the following files are provided. Use them
by including the file in your code with the `include' special form.

* Menu:

* chicken-highlevel-macros.scm::
* chicken-more-macros.scm::
* chicken-ffi-macros.scm::
* chicken-entry-points.scm::
* chicken-default-entry-points.scm::
* test-infrastructure.scm::


File: chicken.info,  Node: chicken-highlevel-macros.scm,  Next: chicken-more-macros.scm,  Up: Additional files

8.1 `chicken-highlevel-macros.scm'
==================================

This file contains highlevel (`syntax-case') macro definitions for all
non-standard macros CHICKEN provides. Normally you don't directly use
this file, since it is loaded automatically by the compiler or
interpreter, when the `-hygienic' option is used.

   If you intend to make highlevel macros (R5RS and/or `syntax-case')
available at run-time (for example, for evaluating code at runtime that
contains highlevel macros), declare the `syntax-case' unit as used and
install the macro system by hand, as in this example:


(require-extension syntax-case)

(install-highlevel-macro-system)

   (This is basically what the `-hygienic-at-run-time' option does, but
this procedure gives you a little more control.)

 -- procedure: install-highlevel-macro-system
          (install-highlevel-macro-system FEATURE ...)
     Installs the highlevel (R5RS / `syntax-case') macro system in the
     running program. `FEATURE' should be a symbol and selects the
     amount of non-standard macros being provided. Possible features
     are:

        * `r5rs'

          The R5RS standard derived syntax, and only those.

        * `srfi-0'

          SRFI-0 (`cond-expand')

        * `extensions'

          R5RS standard derived syntax and all non-standard extension
          provided in CHICKEN

     If no feature is give, `'r5rs' is assumed.


File: chicken.info,  Node: chicken-more-macros.scm,  Next: chicken-ffi-macros.scm,  Prev: chicken-highlevel-macros.scm,  Up: Additional files

8.2 `chicken-more-macros.scm'
=============================

This file contains the definitions of all non-standard syntax forms.
You normally don't use this file directly, unless you have the following
situation: you use non-standard macros at run-time (in evaluated code)
in a compiled program and you want non-standard syntax to be available.
In this case, add

     (require-extension chicken-more-macros)

   to your code. This will load the definitions for non-standard macros
available in code evaluated by the program.

   See also the FAQ for a discussion about the different macro systems
and their ideosyncrasies.


File: chicken.info,  Node: chicken-ffi-macros.scm,  Next: chicken-entry-points.scm,  Prev: chicken-more-macros.scm,  Up: Additional files

8.3 `chicken-ffi-macros.scm'
============================

This file contains the definitions of macros for interfacing to foreign
code, and the definitions contained in this file are automatically made
available in compiled code.


File: chicken.info,  Node: chicken-entry-points.scm,  Next: chicken-default-entry-points.scm,  Prev: chicken-ffi-macros.scm,  Up: Additional files

8.4 `chicken-entry-points.scm'
==============================

This file contains the definition of the macros `define-entry-point'
and `define-embedded'. See the section "Entry points" earlier in this
manual.


File: chicken.info,  Node: chicken-default-entry-points.scm,  Next: test-infrastructure.scm,  Prev: chicken-entry-points.scm,  Up: Additional files

8.5 `chicken-default-entry-points.scm'
======================================

This file contains boilerplate entry point definitions. See the section
"Entry points". This file automatically includes `entry-points.scm'.


File: chicken.info,  Node: test-infrastructure.scm,  Prev: chicken-default-entry-points.scm,  Up: Additional files

8.6 `test-infrastructure.scm'
=============================

This file provides a macro based unit testing facility based upon
expectations concerning evaluations of expressions. These functions
return tagged lists which contain the results of the test package, test
case, or expectations evaluated(there are a few other types of results
dealing with the gloss, todo, and skip macros detailed below). These
result lists are wired together during evaluation to form a large
hierarchical tree in memory.  This result tree is then passed to either
user defined functions which traverse the tree manipulating it in any
way desired, or passed to a supplied (read: defined already in
test-infrastructure.scm) function which manipulates it in a simple way
usually producing human readable or html generated output. API
functions to deal with the result types are supplied and the
representation of the result is black boxed to the user. It is a
violation of encapsulation to inspect the representation directly, and
it may change unpredictably in the future.

* Menu:

* The Test Package Macro API::
* The Test Case Macro API::
* The Expectation Macro API::
* Result Object API::
* Test Package Result Object API::
* Test Case Result Object API::
* Single Clause Style Expectation::
* Equivalence Style Expectation::
* Tolerance Style Expectation::
* Various Helper API::
* Termination API::
* Destructor Object API::
* Todo API::
* Gloss API::
* Skip API::
* Side Effect API::
* Miscellaneous API::
* Analysis of the Result Tree::
* Output Generation API::
* Example Usages of the Test Suite Infrastructure::


File: chicken.info,  Node: The Test Package Macro API,  Next: The Test Case Macro API,  Up: test-infrastructure.scm

8.6.1 The Test Package Macro API
--------------------------------

This macro will evaluate in a left to right fashion the clauses inside
it. Clauses can only be certain things, detailed below. All of the
clauses are executed, except of course if you bail out of the test
package with the escape procedure mechanism.  Test packages may nest
indefinitely.

 -- macro: test-package
          (test-package MESSAGE DESTNAME TERMNAME CLAUSES)
          (test-package MESSAGE DESTNAME TERMNAME (BINDINGS) CLAUSES)
          (test-package MESSAGE DESTNAME TERMNAME (warn MESSAGE) CLAUSES)
          (test-package MESSAGE DESTNAME TERMNAME (warn MESSAGE) (BINDINGS) CLAUSES)

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `DESTNAME' is an unquoted symbol for an automatic destructor
          object that gets called when the test package completes for
          any reason.  This symbol is bound to a destructor object and
          is available to you in the CLAUSES section of the test
          package. See below for the description of the destructor
          object interface.

        * `TERMNAME' is an unquoted symbol for an escape procedure
          available in the body of the test package, usually, this
          escape procedure is passed to `(terminate ...)' which calls it
          for you and performs other tasks. It is not recommended to
          call the escape procedure directly.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the test package.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `BINDINGS' are let-style bindings that you may create and
          exist in the lexical scope of the test package.

        * `CLAUSES' are uses of `(test-case ...)' macros along with
          `(gloss ...)', `(todo ...)', `(skip ...)', and `(terminate
          ...)' macros. While you may use the `(expect-* ...)' style
          macros directly in a test package, doing so is not
          recommended. If the expectation fails, the test package macro
          will continue evaluating until all clauses are evaluated or
          the escape procedure mechanism is activated. This is
          different than a test-case macro where upon discovery of a
          failed expectation, evaluation stops immediately.


File: chicken.info,  Node: The Test Case Macro API,  Next: The Expectation Macro API,  Prev: The Test Package Macro API,  Up: test-infrastructure.scm

8.6.2 The Test Case Macro API
-----------------------------

This macro will evaluate in a left to right fashion the clauses inside
it stopping at the first failed expectation. Clauses can only be
certain things as detailed below. You may also stop the execution of
expectations if you bail out of the test case with the escape procedure
mechanism.  Test cases may NOT nest.

 -- macro: test-case
          (test-case MESSAGE DESTNAME TERMNAME CLAUSES)
          (test-case MESSAGE DESTNAME TERMNAME (BINDINGS) CLAUSES)
          (test-case MESSAGE DESTNAME TERMNAME (warn MESSAGE) CLAUSES)
          (test-case MESSAGE DESTNAME TERMNAME (warn MESSAGE) (BINDINGS) CLAUSES)

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `DESTNAME' is an unquoted symbol for an automatic destructor
          object that gets called when the test case completes for any
          reason.  This symbol is bound to a destructor object and is
          available to you in the CLAUSES section of the test package.
          See below for the description of the destructor object
          interface.

        * `TERMNAME' is an unquoted symbol for an escape procedure
          available in the body of the test case, usually, this escape
          procedure is passed to `(terminate ...)' which calls it for
          you and performs other tasks. It is not recommended to call
          the escape procedure directly.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the test case. The
          `warn' function name is actually a syntax reserved word in
          the macro.

        * `BINDINGS' are let-style bindings that you may create and
          exist in the lexical scope of the test case.

        * `CLAUSES' are uses of `(expect-* ...)' macros along with
          `(gloss ...)', `(todo ...)', `(skip ...)', and `(terminate
          ...)' macros. It is important to note that upon discovery of
          a failed expectation, the test case stops its evaluation and
          returns with the previous successful, and including the
          failed, expectations.


File: chicken.info,  Node: The Expectation Macro API,  Next: Result Object API,  Prev: The Test Case Macro API,  Up: test-infrastructure.scm

8.6.3 The Expectation Macro API
-------------------------------

An expectation at its core simply evaluates its arguments and check to
see if it matches the expectation. The positive or negative result is
encapsulated, along with other things such as the unevaluated
expressions being checked and some messages supplied with each
expectation into a particular type of black box object that one can
query with the appropriate API calls(detailed below).

   Expectations all have a descriptive message that can be bound to
them, along with an optional warning syntax detailed below. A design
decision was made to supply expectation macros for the usual types of
expectations a user needs because this reduced the abstractness of an
expectation into something more manageable. In a future release
however, I will supply a special expectation macro where you may supply
any predicate you wish along with a "type tag" of the predicate.

 -- macro: expect-zero
          (expect-zero MESSAGE CLAUSE)
          (expect-zero MESSAGE (warn MESSAGE) CLAUSE)

        * This expectation checks to see if the evaluated expression
          passed to it is numerically equal to the exact integer zero.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `CLAUSE' is a single expression which should return a exact or
          inexact integer.

 -- macro: expect-nonzero
          (expect-nonzero MESSAGE CLAUSE)
          (expect-nonzero MESSAGE (warn MESSAGE) CLAUSE)

        * This expectation checks to see if the evaluated expression
          passed to it is numerically not equal to the exact integer
          zero.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `CLAUSE' is a single expression which should return an exact
          or inexact integer.

 -- macro: expect-true
          (expect-true MESSAGE CLAUSE)
          (expect-true MESSAGE (warn MESSAGE) CLAUSE)

        * This expectation checks to see if the evaluated expression
          passed to it is the value #t.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `CLAUSE' is a single expression which should return #t.

 -- macro: expect-false
          (expect-false MESSAGE CLAUSE)
          (expect-false MESSAGE (warn MESSAGE) CLAUSE)

        * This expectation checks to see if the evaluated expression
          passed to it is the value #f.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `CLAUSE' is a single expression which should return #t.

 -- macro: expect-eq?
          (expect-eq? MESSAGE EXPECTED CLAUSE)
          (expect-eq? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)

        * This expectation checks to see if `(eq? EXPECTED CLAUSE)' is
          true.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `EXPECTED' is a single expression which is evaluated and
          represents the value the `CLAUSE' must be eq? to in order for
          this expectation to return a positive result.

        * `CLAUSE' is a single expression which, when evaluated must
          return an object where an eq? of this result and the
          `EXPECTED' expression is #t.

        * The result object this macro produce shall contain the
          unevaluated `CLAUSE' expression as a field, but not an
          unevaluated `EXPECTED' expression.

 -- macro: expect-eqv?
          (expect-eqv? MESSAGE EXPECTED CLAUSE)
          (expect-eqv? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)

        * This expectation checks to see if `(eqv? EXPECTED CLAUSE)' is
          true.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `EXPECTED' is a single expression which is evaluated and
          represents the value the `CLAUSE' must be eqv? to in order
          for this expectation to return a positive result.

        * `CLAUSE' is a single expression which, when evaluated must
          return an object where an eqv? of this result and the
          `EXPECTED' expression is #t.

        * The result object this macro produce shall contain the
          unevaluated `CLAUSE' expression as a field, but not an
          unevaluated `EXPECTED' expression.

 -- macro: expect-equal?
          (expect-equal? MESSAGE EXPECTED CLAUSE)
          (expect-equal? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)

        * This expectation checks to see if `(equal? EXPECTED CLAUSE)'
          is true.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `EXPECTED' is a single expression which is evaluated and
          represents the value the `CLAUSE' must be equal? to in order
          for this expectation to return a positive result.

        * `CLAUSE' is a single expression which, when evaluated must
          return an object where an equal? of this result and the
          `EXPECTED' expression is #t.

        * The result object this macro produce shall contain the
          unevaluated `CLAUSE' expression as a field, but not an
          unevaluated `EXPECTED' expression.

 -- macro: expect-near?
          (expect-near? MESSAGE EXPECTED TOL CLAUSE)
          (expect-near? MESSAGE (warn MESSAGE) EXPECTED TOL CLAUSE)

        * This expectation checks to see if `(< (abs (- EXPECTED
          CLAUSE)) TOL)))' is true.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `EXPECTED' is a single expression which is evaluated and
          represents the value the `CLAUSE' must be "near" to in order
          for this expectation to return a positive result.

        * `CLAUSE' is a single expression which should return an
          inexact or exact number.

        * `TOL' is a single expression which, when evaluated must
          return a tolerance value(usually a small inexact number like
          .0001).

        * The result object this macro produce shall contain the
          unevaluated `CLAUSE' expression as a field, but not the
          unevaluated `EXPECTED' or `TOL' expression.

 -- macro: expect-positive
          (expect-positive MESSAGE CLAUSE)
          (expect-positive MESSAGE (warn MESSAGE) CLAUSE)

        * This expectation checks to see if the evaluated expression
          passed to it is a positive value greater than zero.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `CLAUSE' is a single expression which should return an
          inexact or exact number.

 -- macro: expect-negative
          (expect-negative MESSAGE CLAUSE)
          (expect-negative MESSAGE (warn MESSAGE) CLAUSE)

        * This expectation checks to see if the evaluated expression
          passed to it is a negative value less than zero.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn MESSAGE)' allows you to specify a warning object,
          usually a string, that gets associated with the expectation.
          The `warn' function name is actually a syntax reserved word
          in the macro.

        * `CLAUSE' is a single expression which should return an
          inexact or exact number.


File: chicken.info,  Node: Result Object API,  Next: Test Package Result Object API,  Prev: The Expectation Macro API,  Up: test-infrastructure.scm

8.6.4 Result Object API
-----------------------

Expectations, test cases, test packages, and helper macros(`gloss,
todo, etc') all return an object that contains the results and other
various aspects of the action performed which ultimately get wired
together to form the result tree. This collection of functions forming
the rest of the test infrastructure API allows manipulation of these
results in an abstracted way as to allow changing of the representation
in the future.


File: chicken.info,  Node: Test Package Result Object API,  Next: Test Case Result Object API,  Prev: Result Object API,  Up: test-infrastructure.scm

8.6.5 Test Package Result Object API
------------------------------------

If any of these API functions, except test-package-result?, are passed
something that isn't a test package result object, they will return
'not-a-test-package-result.

 -- procedure: test-package-result?
          (test-package-result? RESULT)
     If `RESULT' is a result object from the invocation of a test
     package macro, then this function will return #t. Otherwise, it
     will return #f.

 -- procedure: test-package-result-result-ref
          (test-package-result-result-ref RESULT)
     Returns the boolean result associated with the test package
     `RESULT' object.

 -- procedure: test-package-result-message-ref
          (test-package-result-message-ref RESULT)
     Returns the message object associated with the test package
     `RESULT' object.

 -- procedure: test-package-result-exps-ref
          (test-package-result-exps-ref RESULT)
     Returns the list of result objects associated with the test package
     `RESULT' object.

 -- procedure: test-package-result-warning?
          (test-package-result-warning? RESULT)
     If a warning had been attached to this test package, this function
     will return #t, otherwise it will be #f.

 -- procedure: test-package-result-warning-ref
          (test-package-result-warning-ref RESULT)
     If a warning had been attached to this test package, this function
     will return the warning object supplied by the user, otherwise it
     shall return '().


File: chicken.info,  Node: Test Case Result Object API,  Next: Single Clause Style Expectation,  Prev: Test Package Result Object API,  Up: test-infrastructure.scm

8.6.6 Test Case Result Object API
---------------------------------

If any of these API functions, except test-case-result?, are passed
something that isn't a test case result object, they will return
'not-a-test-case-result.

 -- procedure: test-case-result?
          (test-case-result? RESULT)
     If `RESULT' is a result object from the invocation of a test case
     macro, then this function will return #t. Otherwise, it will
     return #f.

 -- procedure: test-case-result-result-ref
          (test-case-result-result-ref RESULT)
     Returns the boolean result associated with the test case `RESULT'
     object.

 -- procedure: test-case-result-message-ref
          (test-case-result-message-ref RESULT)
     Returns the message object associated with the test case `RESULT'
     object.

 -- procedure: test-case-result-expectations-ref
          (test-case-result-expectations-ref RESULT)
     Returns the list of expctation result objects associated with the
     test case `RESULT' object.

 -- procedure: test-case-result-warning?
          (test-case-result-warning? RESULT)
     If a warning had been attached to this test case, this function
     will return #t, otherwise it will be #f.

 -- procedure: test-case-result-warning-ref
          (test-case-result-warning-ref RESULT)
     If a warning had been attached to this test case, this function
     will return the warning object supplied by the user, otherwise it
     shall return '().


File: chicken.info,  Node: Single Clause Style Expectation,  Next: Equivalence Style Expectation,  Prev: Test Case Result Object API,  Up: test-infrastructure.scm

8.6.7 Expect Result Object API: Single Clause Style Expectation
---------------------------------------------------------------

These expectations all take the form of passing a single expression to
them to see if they match some a priori expectation.  If any of these
API functions, except expect-result?, are passed something that isn't a
single clause style expectation result object, they will return
'not-an-expect-result.

 -- procedure: expect-result?
          (expect-result? RESULT)
     If `RESULT' is a single clause style result object from the
     invocation of an expectation macro, then this function will return
     #t. Otherwise, it will return #f.

 -- procedure: expect-result-result-ref
          (expect-result-result-ref RESULT)
     Returns the boolean result associated with the single clause style
     expectation `RESULT' object.

 -- procedure: expect-result-specific-ref
          (expect-result-specific-ref RESULT)
     This retrieves the "specific" field of a particular single clause
     style expectation.  For example, if you had a result object from
     an invocation of a `(expect-zero? "foobar" (- 1 1))' expectation,
     then the "specific" field of the expectation result object will be
     the string "zero". Here is a table describing what the "specific"
     fields are for each kind of single clause style expectation:

     Single Clause Style Expectation   Associated Specific String
     expect-zero                       "zero"
     expect-nonzero                    "nonzero"
     expect-true                       "true"
     expect-false                      "false"
     expect-positive                   "positive"
     expect-negative                   "negative"


 -- procedure: expect-result-message-ref
          (expect-result-message-ref RESULT)
     Returns the message object associated with the single clause style
     expectation `RESULT' object.

 -- procedure: expect-result-unevaled-ref
          (expect-result-unevaled-ref RESULT)
     Returns the unevaluated expression supplied to a single clause
     style expectation macro.

 -- procedure: expect-result-evaled-ref
          (expect-result-evaled-ref RESULT)
     Returns the evaluated expression supplied to a single clause style
     expectation macro.

 -- procedure: expect-result-warning?
          (expect-result-warning? RESULT)
     If a warning had been attached to this expectation, this function
     will return #t, otherwise it will be #f.

 -- procedure: expect-result-warning-ref
          (expect-result-warning-ref RESULT)
     If a warning had been attached to this expectation, this function
     will return the warning object supplied by the user, otherwise it
     shall return '().


File: chicken.info,  Node: Equivalence Style Expectation,  Next: Tolerance Style Expectation,  Prev: Single Clause Style Expectation,  Up: test-infrastructure.scm

8.6.8 Expect Result Object API: Equivalence Style Expectation
-------------------------------------------------------------

These expectations all take the form of passing a two expressions, the
"left hand side" and the "right hand side" to them to see if they match
some a priori equivalence.  The left hand side is that which you expect
the right hand side to be equivalent. If any of these API functions,
except expect-equivalence-result?, are passed something that isn't a
single clause style expectation result object, they will return
'not-an-expect-equivalence-result.

 -- procedure: expect-equivalence-result?
          (expect-equivalence-result? RESULT)
     If `RESULT' is a comparison style result object from the
     invocation of an expectation macro, then this function will return
     #t. Otherwise, it will return #f.

 -- procedure: expect-equivalence-result-result-ref
          (expect-equivalence-result-result-ref RESULT)
     Returns the boolean result associated with the comparison style
     expectation `RESULT' object.

 -- procedure: expect-equivalence-result-specific-ref
          (expect-equivalence-result-specific-ref RESULT)
     This retrieves the "specific" field of a particular equivalence
     style expectation. For example, if you had a result object from an
     invocation of a `(expect-equal? "foobar" 0 (- 1 1))' expectation,
     then the "specific" field of the expectation result object will be
     the string "equal". Here is a table describing what the "specific"
     fields are for each kind of equivalence style expectation:

     Equivalence Style Expectation   Associated Specific String
     expect-eq                       "eq"
     expect-eqv                      "eqv"
     expect-equal                    "equal"


 -- procedure: expect-equivalence-result-message-ref
          (expect-equivalence-result-message-ref RESULT)
     Returns the message object associated with the equivalence style
     expectation `RESULT' object.

 -- procedure: expect-equivalence-result-lhs-evaled-ref
          (expect-equivalence-result-lhs-evaled-ref RESULT)
     Returns the evaluated "left hand side" expression supplied to an
     equivalence style expectation.

 -- procedure: expect-equivalence-result-rhs-unevaled-ref
          (expect-equivalence-result-rhs-unevaled-ref RESULT)
     Returns the unevaluated "right hand side" expression supplied to
     an equivalence style expectation.

 -- procedure: expect-equivalence-result-rhs-evaled-ref
          (expect-equivalence-result-rhs-evaled-ref RESULT)
     Returns the evaluated "right hand side" expression supplied to an
     equivalence style expectation.

 -- procedure: expect-equivalence-result-warning?
          (expect-equivalence-result-warning? RESULT)
     If a warning had been attached to this expectation, this function
     will return #t, otherwise it will be #f.

 -- procedure: expect-equivalence-result-warning-ref
          (expect-equivalence-result-warning-ref RESULT)
     If a warning had been attached to this expectation, this function
     will return the warning object supplied by the user, otherwise it
     shall return '().


File: chicken.info,  Node: Tolerance Style Expectation,  Next: Various Helper API,  Prev: Equivalence Style Expectation,  Up: test-infrastructure.scm

8.6.9 Expect Result Object API: Tolerance Style Expectation
-----------------------------------------------------------

This is a specialized expectation which accepts three expressions and
checks to see if the "right hand side" is within a "tolerance" of the
"left hand side". There is only one expectation in the tolerance style
currently.  If any of these API functions, except
expect-tolerance-result?, are passed something that isn't a tolerance
style expectation result object, they will return
'not-an-expect-tolerance-result.

 -- procedure: expect-tolerance-result?
          (expect-tolerance-result? RESULT)
     If `RESULT' is a tolerance style result object from the invocation
     of an expectation macro, then this function will return #t.
     Otherwise, it will return #f.

 -- procedure: expect-tolerance-result-result-ref
          (expect-tolerance-result-result-ref RESULT)
     Returns the boolean result associated with the tolerance style
     expectation `RESULT' object.

 -- procedure: expect-tolerance-result-specific-ref
          (expect-tolerance-result-specific-ref RESULT)
     This retrieves the "specific" field of a particular tolerance
     style expectation. For example, if you had a result object from an
     invocation of a `(expect-near? "foobar" 100 .01 100.001)'
     expectation, then the "specific" field of the expectation result
     object will be the string "near". Here is a table describing what
     the "specific" fields are for each kind of tolerance style
     expectation:

     Tolerance Style Expectation   Associated Specific String
     expect-near                   "near"


 -- procedure: expect-tolerance-result-message-ref
          (expect-tolerance-result-message-ref RESULT)
     Returns the message object associated with a tolerance style
     expectation `RESULT' object.

 -- procedure: expect-tolerance-result-lhs-evaled-ref
          (expect-tolerance-result-lhs-evaled-ref RESULT)
     Returns the evaluated "left hand side" expression supplied to a
     tolerance style expectation.

 -- procedure: expect-tolerance-result-lhs-tol-evaled-ref
          (expect-tolerance-result-lhs-tol-evaled-ref RESULT)
     Returns the evaluated "tolerance" expression supplied to a
     tolerance style expectation.

 -- procedure: expect-tolerance-result-rhs-unevaled-ref
          (expect-tolerance-result-rhs-unevaled-ref RESULT)
     Returns the unevaluated "right hand side" expression supplied to a
     tolerance style expectation.

 -- procedure: expect-tolerance-result-rhs-evaled-ref
          (expect-tolerance-result-rhs-evaled-ref RESULT)
     Returns the evaluated "right hand side" expression supplied to a
     tolerance style expectation.

 -- procedure: expect-tolerance-result-warning?
          (expect-tolerance-result-warning? RESULT)
     If a warning had been attached to this expectation, this function
     will return #t, otherwise it will be #f.

 -- procedure: expect-tolerance-result-warning-ref
          (expect-tolerance-result-warning-ref RESULT)
     If a warning had been attached to this expectation, this function
     will return the warning object supplied by the user, otherwise it
     shall return '().


File: chicken.info,  Node: Various Helper API,  Next: Termination API,  Prev: Tolerance Style Expectation,  Up: test-infrastructure.scm

8.6.10 Various Helper API
-------------------------

These upcoming macros and functions allow the author of the test suite
to better control both the execution flow of the test suite and
"decoration" of the test suite with important information like things
yet to do, or just plain documentation.


File: chicken.info,  Node: Termination API,  Next: Destructor Object API,  Prev: Various Helper API,  Up: test-infrastructure.scm

8.6.11 Termination API
----------------------

When executing in a test package or a test case, one might discover some
catastrophic failure of such proportions that it is utterly impossible
to continue executing the test case or test package. When that happens
you can use the termination facility to exit the test case or test
package. Of course, no more expressions will be evaluated in the scope
of the termination. It is recommended that you use this method of
terminating the test case or test package evaluation since it wraps
some contextual information up into the termination result so you can
figure out what happened(and where) later when analyzing the result
tree.

   When using the manipulation API for a terminate result, if you pass a
result to one of these function that is not a terminate result, it will
return 'not-a-terminate-result.

 -- procedure: terminate
          (terminate TERMFUNC MESSAGE)

        * This is the recommended termination method for a test case or
          a test package.

        * `TERMFUNC' is the name of the termination procedure that you
          specified in a test case or test package. You may pass any
          test package or test case termination function available to
          you in the lexical scope in which you call this function. The
          termination will take effect in the scope of the created
          termination function.

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

 -- procedure: terminate-result?
          (terminate-result? RESULT)
     If `RESULT' is a termination result object from the invocation of
     a termination function, then this function will return #t.
     Otherwise, it will return #f.

 -- procedure: terminate-result-result-ref
          (terminate-result-result-ref RESULT)
     Returns the boolean result associated with the termination
     function `RESULT' object. This is currently hard coded to be #f.

 -- procedure: terminate-result-scope-ref
          (terminate-result-scope-ref RESULT)
     The "scope" of the termination result is exactly the `MESSAGE'
     parameter supplied to the test case or test package associated
     with the `TERMFUNC'.

 -- procedure: terminate-result-container-ref
          (terminate-result-container-ref RESULT)
     The "container" of the termination result is going to be either
     'test-package or 'test-case depending upon which the `TERMFUNC'
     was associated.

 -- procedure: terminate-result-message-ref
          (terminate-result-message-ref RESULT)
     Returns the message object associated with the termination
     `RESULT' object.


File: chicken.info,  Node: Destructor Object API,  Next: Todo API,  Prev: Termination API,  Up: test-infrastructure.scm

8.6.12 Destructor Object API
----------------------------

The destructor object allows for you to create helper functions which
clean up for you usually in case of aborting of a test case or package.
For example, suppose you are testing whether or not file writing to a
file works correctly in a test case, so, you'd perform an expectation
to open the file, and then queue a function in the destructor to remove
the file, and then perform the expectation of the write. If the
write(or subsequent) expectation fails, then the test case will
automatically invoke the helper cleanup function specified in the
destructor object that removes the file.

   NOTE: This API is still a little experimental in the sense that
eventually he destructor object should return a typed result that
contains the success of the individual destructor calls. But for now,
it is functional for what it does. Also, be VERY CAREFUL that you
specify the arguments to these API calls correctly since due to lambda
functions not being comparable, this API cannot garuantee that a true
destructor object name had been passed to it. So if you call one of the
following API calls incorrectly, the behavior will be undefined.

 -- procedure: destructor-atexit!
          (destructor-atexit! DESTNAME FUNC ARGS ...)
     This will insert a promise to calculate the `FUNC' with the
     supplied `ARGS ...' into a queue in the `DESTNAME' destructor
     object. Multiple invocations of this API call will continue to
     queue up `(FUNC ARGS ...)' promises indefinitely.  This function
     returns a special ignore type that is ignored by the test
     infrastructure system.

 -- procedure: destructor-activate!
          (destructor-activate! DESTNAME)
     This function will call, in order of queueing, all the promises
     embedded into this destructor object, and then delete the queue.
     This function is ALWAYS called at the completion of a test package
     or test case; so be careful that the destructor object doesn't
     contain anything harmful.  However, you may call it yourself and
     if you do, it will execute all of the queued promises and then
     `clear' itself. This function returns a special ignore type that
     is ignored by the test infrastructure system.

 -- procedure: destructor-clear!
          (destructor-clear! DESTNAME)
     This function completely removes all of the promises associated
     with the destructor object `DESTNAME'. This function returns a
     special ignore type that is ignored by the test infrastructure
     system.

 -- procedure: destructor-dump
          (destructor-dump DESTNAME)
     This function, mostly used for debugging purposes, prints out a
     simple representation of the queued atexit functions to the
     current port.  This function returns a special ignore type that is
     ignored by the test infrastructure system.


File: chicken.info,  Node: Todo API,  Next: Gloss API,  Prev: Destructor Object API,  Up: test-infrastructure.scm

8.6.13 Todo API
---------------

The purpose of the todo API is to allow the author of a test suite the
ability to record into the result tree for later analysis that something
still needs to be done. This way you can count/manipulate this
information at a later date.  Todo macro invocations can occur inside
of test cases or test packages.

 -- macro: todo
          (todo MESSAGE)
          (todo (warn WARNING) MESSAGE)

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn WARNING)' allows you to specify a warning object,
          usually a string, that gets associated with the todo. The
          `warn' function name is actually a syntax reserved word in
          the macro.

 -- procedure: todo-result?
          (todo-result? RESULT)
     If `RESULT' is a todo result object from the invocation of a todo
     macro, then this function will return #t. Otherwise, it will
     return #f.

 -- procedure: todo-result-message-ref
          (todo-result-message-ref RESULT)
     Returns the message object associated with the todo `RESULT'
     object.

 -- procedure: todo-result-warning?
          (todo-result-warning? RESULT)
     If a warning had been attached to this todo, this function will
     return #t, otherwise it will be #f.

 -- procedure: todo-result-warning-ref
          (todo-result-warning-ref RESULT)
     If a warning had been attached to this todo, this function will
     return the warning object supplied by the user, otherwise it shall
     return '().


File: chicken.info,  Node: Gloss API,  Next: Skip API,  Prev: Todo API,  Up: test-infrastructure.scm

8.6.14 Gloss API
----------------

The purpose of the gloss API is to allow the author of a test suite the
ability to record messages into the result tree purely for documentation
purposes.  Gloss macro invocations can occur inside of test cases or
test packages.

 -- macro: gloss
          (gloss MESSAGE)
          (gloss (warn WARNING) MESSAGE)

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn WARNING)' allows you to specify a warning object,
          usually a string, that gets associated with the gloss. The
          `warn' function name is actually a syntax reserved word in
          the macro.

 -- procedure: gloss-result?
          (gloss-result? RESULT)
     If `RESULT' is a gloss result object from the invocation of the
     gloss macro, then this function will return #t. Otherwise, it will
     return #f.

 -- procedure: gloss-result-message-ref
          (gloss-result-message-ref RESULT)
     Returns the message object associated with the gloss `RESULT'
     object.

 -- procedure: gloss-result-warning?
          (gloss-result-warning? RESULT)
     If a warning had been attached to this gloss, this function will
     return #t, otherwise it will be #f.

 -- procedure: gloss-result-warning-ref
          (gloss-result-warning-ref RESULT)
     If a warning had been attached to this gloss, this function will
     return the warning object supplied by the user, otherwise it shall
     return '().


File: chicken.info,  Node: Skip API,  Next: Side Effect API,  Prev: Gloss API,  Up: test-infrastructure.scm

8.6.15 Skip API
---------------

The purpose of the skip API is to allow the author of a test suite to
completely skip evaluation of a set of expresssions.  Skip macro
invocations can occur inside of test cases or test packages.

 -- macro: skip
          (skip MESSAGE CLAUSES)
          (skip (warn WARNING) MESSAGE CLAUSES)

        * `MESSAGE' can be any scheme object, though usually it is a
          string.

        * `(warn WARNING)' allows you to specify a warning object,
          usually a string, that gets associated with the gloss. The
          `warn' function name is actually a syntax reserved word in
          the macro.

        * `CLAUSES' can be more than one expression(as in a lambda form)
          that does NOT get evaluated at any time.

 -- procedure: skip-result?
          (skip-result? RESULT)
     If `RESULT' is a skip result object from the invocation of the
     skip macro, then this function will return #t. Otherwise, it will
     return #f.

 -- procedure: skip-result-message-ref
          (skip-result-message-ref RESULT)
     Returns the message object associated with the skip `RESULT'
     object. Hopefully, it was stated why this set of clauses had been
     skipped.

 -- procedure: skip-result-warning?
          (skip-result-warning? RESULT)
     If a warning had been attached to this skip, this function will
     return #t, otherwise it will be #f.

 -- procedure: skip-result-warning-ref
          (skip-result-warning-ref RESULT)
     If a warning had been attached to this skip, this function will
     return the warning object supplied by the user, otherwise it shall
     return '().


File: chicken.info,  Node: Side Effect API,  Next: Miscellaneous API,  Prev: Skip API,  Up: test-infrastructure.scm

8.6.16 Side Effect API
----------------------

This section of the API just contains a single macro currently since it
is considered a little experimental for now.  The side effecting
evaluates all of its arguments as in a `(begin ...)' form, it returns a
result that is completely ignored by the system and unavailable to the
output analysis code.

 -- macro: side-effect
          (side-effect CLAUSES)
     This macro expands into a begin form the clauses in order and when
     it finishes evaluating them, returns a result that is silently
     ignored by the testing infrastructure system. Usually this is used
     in conjunction with `(set! ...)' or with complicated situations
     where a lot of setup work must happen for an expectation to be
     performed.


File: chicken.info,  Node: Miscellaneous API,  Next: Analysis of the Result Tree,  Prev: Side Effect API,  Up: test-infrastructure.scm

8.6.17 Miscellaneous API
------------------------

This section contains a few functions whose purpose is to simplify
certain kinds of manipulations of result objects.

 -- procedure: *-restult?
          (*-result? RESULTOBJ)
     This function will return #t of `RESULTOBJ' is any kind of an
     evaluated result object. Otherwise, it shall return #f.

 -- procedure: *-result-ref
          (*-result-ref RESULTOBJ)
     This function will return the result of any kind of `RESULTOBJ'
     passed to it if it is indeed a true result object. Otherwise, it
     shall emit an error to the current port, and return #f.

 -- procedure: all-testpackage-results-true?
          (all-testpackage-results-true? RESULTLIST)
     This function takes the result of a call to
     `(test-package-result-result-ref PACKAGERESULTOBJ)' and returns #t
     if every single contained result in that list had been true, or #f
     otherwise.

 -- procedure: all-testcase-expectations-true?
          (all-testcase-expectations-true? RESULTLIST)
     This function takes the result of a call to
     `(test-case-result-result-ref CASERESULTOBJ)' and returns #t if
     every single contained result in that list had been true, or #f
     otherwise.


File: chicken.info,  Node: Analysis of the Result Tree,  Next: Output Generation API,  Prev: Miscellaneous API,  Up: test-infrastructure.scm

8.6.18 Analysis of the Result Tree
----------------------------------

Once a result tree has been evaluated and constructed in memory, what
do you do with it? Well, you can do anything you want with it if you
choose to write the analysis or output generation functions and pass it
the evaluated result tree, and this is, in fact, encouraged. However,
usually you just want to print out the tree in a human readable format
so you can check things before the serious analysis code gets written.
So, to save work for the test suite designer, a tiny API has been
written to produce human readable output given a tree of results rooted
in a single test package. Of course the single test package may have
many other test packages and test cases embedded within it.


File: chicken.info,  Node: Output Generation API,  Next: Example Usages of the Test Suite Infrastructure,  Prev: Analysis of the Result Tree,  Up: test-infrastructure.scm

8.6.19 Output Generation API
----------------------------

 -- procedure: printnl
          (printnl CLAUSES)
     This function will print all of the evaluated `CLAUSES' in order
     with a newline at the end of it.

 -- procedure: printinl
          (printinl INDENT CLAUSES)
     This function will `INDENT' a number of spaces and then print all
     of the evaluated `CLAUSES' in order with a newline at the end of
     it.

 -- procedure: output-style-human
          (output-style-human RESULTTREE)
     This function will print out a human readable rendering of the
     `RESULTTREE' and return the toplevel package result.


File: chicken.info,  Node: Example Usages of the Test Suite Infrastructure,  Prev: Output Generation API,  Up: test-infrastructure.scm

8.6.20 Example Usages of the Test Suite Infrastructure
------------------------------------------------------

This section contains some simple examples of how to author test suites.

   Here is a simple example:


(let ((result
        ;; output-style-human function requires a single test package
        ;; to encapsulate everything.
        (test-package "Arithmetic Operators" pd pe

                (test-case "Testing '+'" d e
                        (expect-equal "Adding two positive numbers" 2 (+ 1 1))
                        (expect-equal "Adding two negative numbers" -2 (+ -1 -1))
                        (expect-zero "Adding positive and negative" (+ -1 1)))

                (test-case "Testing '-'" d e
                        (expect-zero "Subtracting two positive numbers" (- 1 1))
                        (expect-zero "Subtracting two negative numbers" (- -1 -1))
                        (expect-equal "Subtracting positive and negative" -2 (- -1 1))))))
        (output-style-human result))

   The above example, when evaluated, will produce some human readable
output and the a #t value as the result of the top level package. The
`result' variable contains the tree of evaluated expectations, test
cases, and the package arranged in a hierarchy extremely similar to the
nesting of the above macros. If you desire to manipulate the result
tree yourself, you may use the various APIs to manipulate the various
results. Please see the implementation of `(output-style-human ...)'
(it isn't large) in the test-infrastructure.scm file to see an example
of this.

   The variables: `pe, e' are the escape functions you may use with the
`(terminate ...)' function call if you wish to abort the above code
somewhere.

   The variables: `pd, d' allow use of a "destructor" object which
allows you to run side effecting functions at the "finishing" point of
the evaluation of the test case or test package. These functions are
run no matter if the code succeeded correctly or not, so be careful to
manage the destructor object carefully so you don't perform unwanted
side effects. The names of the destructor objects you supply are
lexically scoped in the bodies of the test case or test package.

   Now, here is some example output that `(output-style-human ...)'
might generate with the above testing code:


Begin Package: Arithmetic Operators
  Begin Test Case: Testing '+'
    Begin Expectation: Adding two positive numbers
    Expect equal
      Expected Value:
      2
      Unevaluated:
      (+ 1 1)
      Evaluated:
      2
    Result: #t
    End Expectation: Adding two positive numbers

    Begin Expectation: Adding two negative numbers
    Expect equal
      Expected Value:
      -2
      Unevaluated:
      (+ -1 -1)
      Evaluated:
      -2
    Result: #t
    End Expectation: Adding two negative numbers

    Begin Expectation: Adding positive and negative
    Expect zero
      Unevaluated:
      (+ -1 1)
      Evaluated:
      0
    Result: #t
    End Expectation: Adding positive and negative

  Result: #t
  End Test Case: Testing '+'

  Begin Test Case: Testing '-'
    Begin Expectation: Subtracting two positive numbers
    Expect zero
      Unevaluated:
      (- 1 1)
      Evaluated:
      0
    Result: #t
    End Expectation: Subtracting two positive numbers

    Begin Expectation: Subtracting two negative numbers
    Expect zero
      Unevaluated:
      (- -1 -1)
      Evaluated:
      0
    Result: #t
    End Expectation: Subtracting two negative numbers

    Begin Expectation: Subtracting positive and negative
    Expect equal
      Expected Value:
      -2
      Unevaluated:
      (- -1 1)
      Evaluated:
      -2
    Result: #t
    End Expectation: Subtracting positive and negative

  Result: #t
  End Test Case: Testing '-'

Result: #t
End Package: Arithmetic Operators

#t


File: chicken.info,  Node: Data Representation,  Next: Bugs and limitations,  Prev: Additional files,  Up: Top

9 Data Representation
*********************

There exist two different kinds of data objects in the CHICKEN system:
immediate and non-immediate objects. Immediate objects are represented
by a tagged machine word, which is usually of 32 bits length (64 bits
on 64-bit architectures). The immediate objects come in four different
flavors:

   * fixnums, that is, small exact integers, distinguished by the
     lowest order bit in the machine word set to 1. This gives fixnums
     a range of 31 bits for the actual numeric value (63 bit on 64 bit
     architectures).

   * characters, where the lowest four bits of machine words containing
     characters are equal to `C_CHARACTER_BITS'. The ASCII code of the
     character is encoded in bits 9 to 16, counting from 1 and starting
     at the lowest order position.

   * booleans, where the lowest four bits of machine words containing
     booleans are equal to `C_BOOLEAN_BITS'. Bit 5 (counting from 0 and
     starting at the lowest order position) is one if the boolean
     designates true, or 0 if it is false.

   * other values: the empty list, void and end-of-file. The lowest
     four bits of machine words containing these values are equal to
     `C_SPECIAL_BITS'. Bits 5 to 8 contain an identifying number for
     this type of object.  The following constants are defined:
     `C_SCHEME_END_OF_LIST C_SCHEME_UNDEFINED C_SCHEME_END_OF_FILE'


   Non-immediate objects are blocks of data represented by a pointer
into the heap. The first word of the data block contains a header,
which gives information about the type of the object. The header has
the size of a machine word, usually 32 bits (64 bits on 64 bit
architectures).

   * bits 1 to 24 (starting at the lowest order position) contain the
     length of the data object, which is either the number of bytes in a
     string (or byte-vector) or the the number of elements for a vector
     or for a structure type.

   * bits 25 to 28 contain the type code of the object.

   * bits 29 to 32 contain miscellaneous flags used for garbage
     collection or internal data type dispatching.  These flags are:
    `C_GC_FORWARDING_BIT'
          Flag used for forwarding garbage collected object pointers.

    `C_BYTEBLOCK_BIT'
          Flag that specifies whether this data object contains raw
          bytes (a string or byte-vector) or pointers to other data
          objects.

    `C_SPECIALBLOCK_BIT'
          Flag that specifies whether this object contains a "special"
          non-object pointer value in its first slot. An example for
          this kind of objects are closures, which are a vector-type
          object with the code-pointer as the first item.

    `C_8ALIGN_BIT'
          Flag that specifies whether the data area of this block
          should be aligned on an 8-byte boundary (floating-points
          numbers, for example).



   The actual data follows immediately after the header. Note that
block-addresses are always aligned to the native machine-word boundary.
Scheme data objects map to blocks in the following manner:

   * pairs: vector-like object (type bits `C_PAIR_TYPE'), where the car
     and the cdr are contained in the first and second slots,
     respectively.

   * vectors: vector object (type bits `C_VECTOR_TYPE').

   * strings: byte-vector object (type bits `C_STRING_TYPE').

   * procedures: special vector object (type bits `C_CLOSURE_TYPE').
     The first slot contains a pointer to a compiled C function. Any
     extra slots contain the free variables (since a flat closure
     representation is used).

   * flonum: a byte-vector object (type bits `C_FLONUM_BITS'). Slots
     one and two (or a single slot on 64 bit architectures) contain a
     64-bit floating-point number, in the representation used by the
     host systems C compiler.

   * symbol: a vector object (type bits `C_SYMBOL_TYPE'). Slots one and
     two contain the toplevel variable value and the print-name (a
     string) of the symbol, respectively.

   * port: a special vector object (type bits `C_PORT_TYPE'). The first
     slot contains a pointer to a file- stream, if this is a
     file-pointer, or NULL if not. The other slots contain housekeeping
     data used for this port.

   * structure: a vector object (type bits `C_STRUCTURE_TYPE'). The
     first slot contains a symbol that specifies the kind of structure
     this record is an instance of. The other slots contain the actual
     record items.

   * pointer: a special vector object (type bits `C_POINTER_TYPE'). The
     single slot contains a machine pointer.

   * tagged pointer: similar to a pointer (type bits
     `C_TAGGED_POINTER_TYPE'), but the object contains an additional
     slot with a tag (an arbitrary data object) that identifies the type
     of the pointer.


   Data objects may be allocated outside of the garbage collected heap,
as long as their layout follows the above mentioned scheme. But care
has to be taken not to mutate these objects with heap-data (i.e.
non-immediate objects), because this will confuse the garbage collector.

   For more information see the header file `chicken.h'.


File: chicken.info,  Node: Bugs and limitations,  Next: FAQ,  Prev: Data Representation,  Up: Top

10 Bugs and limitations
***********************

   * Compiling large files takes too much time.

   * There is no support for rationals, complex numbers or
     extended-precision integers (bignums).

   * The maximal number of arguments that may be passed to a compiled
     procedure or macro is 126.  A macro-definition that has a single
     rest-parameter can have any number of arguments.

   * The maximum number of values that can be passed to continuations
     captured using `call-with-current-continuation' is 126.

   * Some numeric procedures are missing since CHICKEN does not support
     the full numeric tower.

   * If a known procedure has unused arguments, but is always called
     without those parameters, then the optimizer "repairs" the
     procedure in certain situations and removes the parameter from the
     lambda-list.

   * `eval-when' doesn't allow toplevel definitions inside its body in
     combination with hygienic macros.

   * `port-position' currently works only for input ports.

   * Leaf routine optimization can theoretically result in code that
     thrashes, if tight loops perform excessively many mutations.

   * Building CHICKEN on RS/6000 systems under AIX is currently not
     possible, due to strange assembler errors during compilation of the
     compiler sources.

   * If `eval' is invoked with `scheme-report-environment' or
     `null-environment' inside the interpreter, then non-standard
     syntax is still visible, unless the interpreter has been started
     with the `-strict' option.

   * When the highlevel macro system is used, line number information
     is not properly maintained.

   * `format' is not reentrant. This means that recursive invocation of
     this procedure (either inside `print-object' methods or
     record-printer defined with `define-record-printer' will not work.

   * User-defined types are currently not supported in the argument and
     result specifications for entry-points defined with
     `define-entry-point'.



File: chicken.info,  Node: FAQ,  Next: Acknowledgements,  Prev: Bugs and limitations,  Up: Top

11 FAQ
******

11.1 General
============

   * Why yet another Scheme implementation?

     Since Scheme is a relatively simple language, a large number of
     implementations exist and    each has its specific advantages and
     disadvantages. Some are fast, some provide a rich    programming
     environment. Some are free, others are tailored to specific
     domains, and so on. The reasons    for the existance of CHICKEN
     are:

     CHICKEN is portable because it generates C code that runs on a
     large number of platforms.

     CHICKEN is extendable, since its code generation scheme and
     runtime system/garbage collector fits    neatly into a C
     environment.

     CHICKEN is free and can be freely distributed, including its
     source code.

     CHICKEN offers better performance than nearly all interpreter
     based implementations, but still    provides full Scheme semantics.

     As far as I know, CHICKEN is the first implementation of Scheme
     that uses Henry Baker's      "Cheney on the M.T.A" concept.

   * What is the meaning of the `-hygienic' option?

     The high-level macro system adds some startup overhead to the
     system.     Using this options evaluates some standard
     macro-definitions and will    slow down the startup-times of the
     compiler and the interpreter.     For many situations the simple
     `define-macro' style macro-system is    sufficient, and so the use
     of the extended macro system is optional.     If you prefer that
     the compiler or interpreter use the syntax-case macro-    system
     by default, consider setting the environment variables
     `CHICKEN_OPTIONS'    and/or `CSI_OPTIONS' to `-hygienic'.

   * What to do if I find a bug?

     Send e-mail to `felix@call-with-current-continuation.org'    with
     some hints about the problem, like    version/build of the
     compiler, platform, system configuration, code that    causes the
     bug, etc.

   * Why are values defined with `define-foreign-variable' or
     `define-constant' or `define-inline' not seen outside of the
     containing source file?

     Accesses to foreign variables are translated directly into C
     constructs that access the variable,   so the Scheme name given to
     that variable does only exist during compile-time.    The same
     goes for constant- and inline-definitions: The name is only there
     to tell the compiler   that this reference is to be replaced with
     the actual value.

   * How does `cond-expand' know which features are registered in used
     units?

     Each unit used via `(declare (uses ...))' is registered as a
     feature and    so a symbol with the unit-name can be tested by
     `cond-expand' during macro-expansion-time.     Features registered
     using the `register-feature!' procedure are only    available
     during run-time of the compiled file. You can use the `eval-when'
     form    to register features at compile time.

   * How can I cut down the size of an executable?

     If you don't need `eval' or the stuff in the `extras' library unit,
       you can just use the `library' unit:


     	(declare (uses library))
     	(display "Hello, world!\n")

     (Don't forget to compile with the `-explicit-use' option)
     Compiled with Visual C++ this generates an excutable of around 240
     kilobytes.     It is theoretically possible to compile something
     without the library, but    a program would have to implement
     quite a lot of support code on its own.

   * Why does a loop that doesn't `cons' still trigger garbage
     collections?

     Under CHICKENs implementation policy, tail recursion is achieved
     simply by avoiding to    return from a function call. Since the
     programs is CPS converted, a continuous    sequence of nested
     procedure calls is performed. At some stage the stack-space    has
     to run out and the current procedure and its parameters (including
     the current continuation) are stored somewhere    in the runtime
     system. Now a minor garbage collection occurs and rescues all live
       data from the stack (the first heap generation) and moves it
     into the the second heap generation. Than the stack is cleared
     (using    a `longjmp') and execution can continue from the saved
     state.     With this method arbitrary recursion (in tail- or
     non-tail position) can happen,    provided the application doesn't
     run out of heap-space.     (The difference between a tail- and a
     non-tail call is that the tail-call has no    live data after it
     invokes its continuation - and so the amount of heap-space needed
     stays constant)

   * How can I obtain faster executables?

     There are a number of declaration specifiers that should be used
     to speed up    compiled files: declaring `(standard-bindings)' is
     mandatory, since this enables    most optimizations. Even if some
     standard procedures should be redefined, you can    list untouched
     bindings in the declaration.     Declaring `(extended-bindings)'
     lets the compiler choose faster versions of certain    internal
     library functions. This might give another speedup. You can also
     use the    the `usual-integrations' declaration, which is
     identical to declaring    `standard-bindings' and
     `extended-bindings'    (note that `usual-integrations' is set by
     default).     Declaring `(block)' tells the compiler that global
     procedures are not changed    outside the current compilation
     unit, this gives the compiler some more    opportunities for
     optimization.     If no floating point arithmetic is required,
     then declaring `(number-type fixnum)'    can give a big
     performance improvement, because the compiler can now inline
     most arithmetic operations.     Declaring `(unsafe)' will switch
     off most safety checks.     If threads are not used, you can
     declare `(disable-interrupts)'.     You should always use maximum
     optimizations settings for your C compiler.     Good GCC compiler
     options on Pentium (and compatible) hardware are:    `-O3
     -fomit-frame-pointer -f-nostrict-aliasing'    Some programs are
     very sensitive to the setting of the nursery (the first
     heap-generation). You    should experiment with different nursery
     settings (either by compiling with the `-nursery'    option or by
     using the `-:s...' runtime option).

   * Why does the linker complain about a missing function
     `_C_..._toplevel'?

     This message indicates that your program uses a library-unit, but
     that the    object-file or library was not supplied to the linker.
     If you have the unit    `foo', which is contained in `foo.o' than
     you have to supply it to the    linker like this (assuming a GCC
     environment):


        % chicken program.scm -output-file program.c
        % gcc program.c foo.o `chicken-config -cflags -libs` -o program

     The CHICKEN runtime library (`libchicken.so' or `libchicken.lib')
      already contains the units `library', `eval'    and
     `syntax-case', plus the internally used units `profiler>' and
     `scheduler'.     The extras library (`libstuffed-chicken.so' or
     `libstuffed-chicken.lib')    contains the units `extras', `format',
       `lolevel', `tinyclos',    `regex', `tcp' and `posix' (if
     available).     The SRFI library (`libsrfi-chicken.so' or
     `libsrfi-chicken.lib')    contains the units `srfi-1', `srfi-4',
     `srfi-13',    `srfi-14', `srfi-18', `srfi-25' and    `srfi-37'.

   * Why does the linker complain about a missing function
     `_C_toplevel'?

     This means you have compiled a library unit as an application.
     When a unit-declaration (as in `(declare (unit ...))')    is
     given, then this file has a specially named toplevel entry
     procedure (see Q23). Just remove the declaration,    or compile
     this file to an object-module and link it to your application code.

   * Why are constants defined by `define-constant' not honoured in
     `case' constructs?

     `case' expands into a cascaded `if' expression, where the first
     item in each arm    is treated as a quoted list. So the `case'
     macro can not infer wether    a symbol is to be treated as a
     constant-name (defined via `define-constant') or    a literal
     symbol.

   * When I compile a file with `-unsafe' or unsafe declarations, it
     crashes during execution.

     The compiler option `-unsafe' or the declaration `(declare
     (unsafe))' disable    certain safety-checks to improve
     performance, so code that would normally    trigger an error will
     work unexpectedly or even crash the running application.     It is
     advisable to develop and debug a program in safe mode (without
     unsafe    declarations) and use this feature only if the
     application works properly.

   * Which non-standard procedures are treated specially when the
     `extended-bindings' or `usual-integrations' declaration or
     compiler option is used?

     The following extended bindings are handled specially:

     `bitwise-and' `bitwise-ior' `bitwise-xor' `bitwise-not' `add1'
     `sub1'  `fx+' `fx-' `fx*' `fx/' `fxmod'   `fx=' `fx>' `fx>='
     `fixnum?' `fxneg' `fxmax' `fxmin' `fxand' `fxior' `fxxor' `fxnot'
     `fxshl' `fxshr' `fp+' `fp-' `fp*' `fp/' `atom?'   `fp=' `fp>'
     `fp>=' `fpneg' `fpmax' `fpmin'   `arithmetic-shift' `signum'
     `flush-output' `thread-specific' `thread-specific-set!'
     `not-pair?' `null-list?' `print' `print*' `u8vector->bytevector'
     `s8vector->bytevector' `u16vector->bytevector'
     `s16vector->bytevector'   `u32vector->bytevector'
     `s32vector->bytevector' `f32vector->bytevector'
     `f64vector->bytevector' `block-ref'   `byte-vector-length'
     `u8vector-length'   `s8vector-length'   `u16vector-length'
     `s16vector-length'   `u32vector-length'   `s32vector-length'
     `f32vector-length'   `f64vector-length'   `u8vector-ref'
     `s8vector-ref'   `u16vector-ref'   `s16vector-ref'
     `u8vector-set!'    `s8vector-set!'   `u16vector-set!'
     `s16vector-set!'   `u32vector-set!'   `s32vector-set!'
     `block-set!' `number-of-slots'     `first' `second' `third'
     `fourth' `null-pointer?' `pointer->object'
     `make-record-instance'    `locative-ref' `locative-set!'
     `locative?' `locative->object' `identity'     `cpu-time' `error'
     `call/cc'

   * Why does `define-reader-ctor' not work in my compiled program?

     The following piece of code does not work as expected:

          (eval-when (compile)
            (define-reader-ctor 'integer->char integer->char) )
          (print #,(integer->char 33))

     The problem is that the compiler reads the complete source-file
     before doing any processing on it,   so the sharp-comma form is
     encountered before the reader-ctor is defined. A possible solution
     is to include   the file containing the sharp-comma form, like
     this:

          (eval-when (compile)
            (define-reader-ctor 'integer->char integer->char) )

          (include "other-file")

          ;;; other-file.scm:
          (print #,(integer->char 33))

   * Why does my program abort with an "out of memory" error when I
     compile with extended debug information?

     The compiler instruments the source file with a lot of support
     code to provide things like arbitrary restarting/returning   from
     activation frames. This will transform calls in tail-position into
     non-tail calls in all situations but the most   trivial ones (`do'
     loops and named `let'). This will result in a much higher memory
     usage for allocating continuation frames. Try passing the `-:hXXX'
     option when executing the program,   with a large value for `XXX'.

   * Why do I get a warning when I define a global variable named
     `match'?

     Even when the `match' unit is not used, the macros from that
     package are visible in the compiler.    The reason for this is
     that macros can not be accessed from library units (only when
     explicitly evaluated in running   code). To speed up
     macro-expansion time, the compiler and the interpreter both
     already provide the compiled   `match-...' macro definitions.
     Macros shadowed lexically are no problem, but global definitions
     of variables named identically to (global) macros are useless -
     the macro definition shadows the global   variable.    This
     problem can be solved in one of three ways:

     - Use a different name

     - Undefine the macro, like this:

          (eval-when (compile eval) (undefine-macro! 'match))

   * How can I enable case sensitive reading/writing in user code?

     To enable the `read' procedure to read symbols and identifiers
     case sensitive, you can set the   parameter `case-sensitivity' to
     `#t'.

   * When I use callback functions (from Scheme to C and back to Scheme
     again), I get weird crashes.

     There are two reasons why code involving callbacks can crash out
     of know apparent reason. The first is that it is   important to
     use `foreign-callback-lambda/foreign-callback-lambda*' for the C
     code that is   to call back into Scheme. If this is not done than
     sooner or later the available stack space will be exhausted.
     The second reason is that if the C code uses a large amount of
     stack storage, or if Scheme-to-C-to-Scheme calls are   nested
     deeply, then the available nursery space on the stack will run
     low. To avoid this it might be advisable   to run the compiled
     code with a larger nursery setting, i.e. run the code with
     `-:s...' and a larger   value than the default (for example
     `-:s300k'), or use the `-nursery' compiler option.    Note that
     this can decrease runtime performance on some platforms.

   * How can I change `match-error-control' during compilation?

     Use `eval-when', like this:

            (eval-when (compile)
              (match-error-control #:unspecified) )

   * Why doesn't CHICKEN support the full numeric tower?

     There are a number of reasons for this:

     - I haven't found a decent library for multiprecision arithmetic,
     yet (the GNU multiprecision    library is distributed under a
     different license than CHICKEN);

     - For most applications of Scheme fixnums (exact word-sized
     integers) and flonums (64-bit floating-point    numbers) are more
     than sufficient;

     -Interfacing to C is simpler;

     -Dispatching of arithmetic operations is more efficient.

   * How can I put toplevel definitions inside `eval-when' in
     combination with the highlevel macro system?

     `eval-when' expands into an internal special form, which
     effectively puts the contained body into   a non-toplevel context
     with the `syntax-case' macro system. An ugly but working solution
     is to use `set!' instead of `define'.

   * Toplevel-continuations captured in interpreted code don't seem to
     work.

     Consider the following piece of code:

            (define k (call-with-current-continuation (lambda (k) k)))
            (k k)

     When compiled, this will loop endlessly. But when interpreted, `(k
     k)' will return   to the read-eval-print loop! This happens
     because the continuation captured will eventually read the   next
     toplevel expression from the standard-input (or an input-file if
     loading from a file). At the moment   `k' was defined, the next
     expression was `(k k)'. But when `k'   is invoked, the next
     expression will be whatever follows after `(k k)'.    In other
     words, invoking a captured continuation will not rewind the
     file-position of the input source.    A solution is to wrap the
     whole code into a `(begin ...)' expression, so all toplevel
     expressions will be loaded together.

   * How can I specialize a generic function method to match instances
     of every class?

     Specializing a method on `<object>' doesn't work on primitive data
     objects like   numbers, strings, etc. so for example

            (define-method (foo (x <my-class>)) ...)
            (define-method (foo (x <object>)) ...)
            (foo 123)

     will signal an error, because to applicable method can be found.
     To specialize a method for primitive   objects, use `<top>':

            (define-method (foo (x <top>)) ...)

   * Why does a chicken have both dark and white meats?

     Short answer is chickens don't fly long distance. As a result the
     muscles in the wings are designed for short bursts of activity and
     don't have as many of the proteins that facilitate oxygen
     distribution in those muscles. These proteins are coloured red and
     cause the dark colour of the meat. Ducks fly a lot hand have dark
     meat in their wings. Chickens do walk a lot so their leg and
     thighs are dark meat.

     (Thanks to Chris Double)


11.2 Platform specific
======================

   * How do I generate a DLL under MS Windows (tm) ?

     Use `csc' in combination with the `-dll' option:


        C:\> csc foo.scm -dll

     You can use the `define-entry-point' facility to interface to
     the Scheme code.

   * How do I generate a GUI application under Windows(tm)?

     Invoke `csc' with the `-windows' option. Or pass the
     `-DC_WINDOWS_GUI'    option to the C compiler and link with the
     GUI version of the runtime system (that's
     `libchicken-gui[-static].lib'.     The GUI runtime displays error
     messages in a message box and does some rudimentary command-line
     parsing.

   * Compiling very large files under Windows with the Microsoft C
     compiler fails with a message indicating insufficient heap space.

     It seems that the Microsoft C compiler can only handle files up to
     a certain size, and it doesn't utilize virtual memory as   well as
     the GNU C compiler, for example. Try closing running applications.
     If that fails, try to break up the Scheme code   into several
     library units.

   * When I run `csi' inside an emacs buffer under Windows, nothing
     happens.

     Invoke `csi' with the `-:c' runtime option. Under Windows the
     interpreter thinks it   is not running under control of a terminal
     and doesn't print the prompt and does not flush the output stream
     properly.


11.3 Customization
==================

   * How do I run custom startup code before the runtime-system is
     invoked?

     When you invoke the C compiler for your translated Scheme source
     program, add the C compiler option    `-DC_EMBEDDED', or pass
     `-embedded' to the `csc'    driver program, so no entry-point
     function will be generated (`main()').     When your are finished
     with your startup processing, invoke:


        CHICKEN_main(argc, argv, C_toplevel);

     where `C_toplevel' is the entry-point into the compiled Scheme
     code. You   should add the following  declarations at the head of
     your code:


       #include "chicken.h"
       extern void C_toplevel(C_word,C_word,C_word) C_noret;

   * How can I add compiled user passes?

     To add a compiled user pass instead of an interpreted one, create
     a library unit and recompile   the main unit of the compiler (in
     the file `chicken.scm') with an additional `uses'   declaration.
     Then link all compiler modules and your (compiled) extension to
     create a new version of   the compiler, like this (assuming a UNIX
     like environment and also assuming all sources are in the
     current directory):


       % cat userpass.scm
       ;;;; userpass.scm - My very own compiler pass

       (declare (unit userpass))

       ;; Perhaps more user passes/extensions are added:
       (let ([old (user-pass)])
         (user-pass
           (lambda (x)
             (let ([x2 (do-something-with x)])
     	  (if old
     	      (old x2)
     	      x2) ) ) ) )
       ...
       % chicken userpass.scm -output-file userpass.c -explicit-use -quiet
       % chicken chicken.scm -output-file chicken-extended.c -quiet -postlude "(declare (uses userpass))"
       % gcc -c userpass.c `chicken-config -cflags` -o userpass.o
       % gcc -c chicken-extended.c `chicken-config -cflags` -o chicken-extended.o
       % gcc chicken-extended.o support.o easyffi.o compiler.o optimizer.o batch-driver.o c-platform.o \
         c-backend.o userpass.o `chicken-config -libs` -o chicken-extended

     On platforms that support it (Linux ELF, Solaris, Windows + VC++),
     compiled code can be loaded via `-extend'   just like source files
     (see `load' in the User's Manual).


11.4 Macros
===========

   * Why does `(define-macro foo bar)' not work?

     Consider this code snippet:


        (define (double x) (list '* x x))

        (define-macro twice double)

     Because the macro `twice' is defined at compile time (following
     forms may refer    to it), functions defined at runtime (as
     `double' in this case) are not available.     The alternative
     syntax of `define-macro':


        (define-macro twice (lambda (x) (list '* x x)))

     does just exist to make porting other Scheme code easier. It is
     not able to assign procedures    computed at runtime as macro
     expanders.

   * Why doesn't my fancy macro work in compiled code?

     Macro bodies that are defined and used in a compiled source-file
     are    evaluated during compilation and so have no access to
     definitions in the    compiled file. Note also that during
     compile-time macros are only available in    the same source file
     in which they are defined. Files included via `include'    are
     considered part of the containing file.

   * Why are macros not visible outside of the compilation unit in
     which they are defined?

     Macros are defined during compile time, so when a file has been
     compiled, the definitions are gone. An exception    to this rule
     are macros defined with `define-macro', which are also visible at
     run-time, i.e.     in `eval'. To use macros defined in other
     files, use the `include' special    form.

   * What's all this about two different macro systems and why is
     everything so complicated?

     CHICKEN provides two macro systems: a low-level Lisp-style macro
     system that is not hygienic and not referentially    transparent,
     where a macro expander simply returns source code to be executed
     or compiled instead of the original    form and second, a port of
     R. Kent Dybvig's `syntax-case' macro system, which provides fully
      R5RS compatible hygienic and referentially transparent macros in
     addition to a powerful framework with nearly the    same control
     as low-level macros, while still being hygienic. The integration
     of the latter macro system with    CHICKEN is not perfect - the
     syntax-case code is complex and is not perfectly suited for a
     batch compiler.     The low-level macro system is more
     lightweight, and may for many people more than sufficient. So the
     decision    has been made to have both, and accept the necesseray
     inconsistencies that this causes.

     Here is an attempt to explain the different possible situations
     that may come up and how to address them:

     1) Running the interpreter with low-level macros: this is the
     default.

     2) Running the interpreter with `syntax-case' macros: add the
     `-hygienic' or `-syntax' option. If you    are writing a shell
     ("She-bang") script, consider using `-script-meta' to add the
     `-hygienic' option to    the options with which the script will be
     executed.

     3) Compiling code with low-level macros, the code does not do any
     evaluation of Scheme expressions (for example by    using `eval'
     or `load') at run-time, or if it does, it doesn't evaluate code
     with non-standard Scheme    syntax: this is the default. If the
     compiled program uses the `syntax-case' macro system, add the
     `-hygienic'    or `-symtax' options to the compiler invocation.

     4) Compiling code with low-level macros, the code evaluates Scheme
     expressions at run-time, and needs non-standard    syntax (like
     `unless' or other macros that are normally provided in the CHICKEN
     system): add the following    line to your code:

             (require-extension chicken-more-macros)

     This will load the non-standard macro definitions when the program
     is executed.     If the compiled program uses the `syntax-case'
     macro system, add the `-hygienic'    or `-syntax' options to the
     compiler invocation.

     5) Should you prefer to have the `syntax-case' macro system
     available at run-time, compile your code    with the
     `-hygienic-at-run-time' option. This will add all necessary code
     to load and install    the high-level macro expander at run-time.
     To have the non-standard macros available at run-time, you still
     need

             (require-extension chicken-more-macros)



File: chicken.info,  Node: Acknowledgements,  Next: Bibliography,  Prev: FAQ,  Up: Top

12 Acknowledgements
*******************

   * Jonah Beckford added CHICKEN-support to SWIG (http://www.swig.org)
     and provided support for shared libraries and dynamic loading
     under Windows.

   * "Category 5" ported CHICKEN to several BSD platforms and suggested
     a great many improvements.

   * Linh Dang translated the TeX manual into texinfo format and wrote
     the hen emacs mode.

   * Steve Elkins ported CHICKEN to OpenBSD.

   * Tollef Fog Heen and Thomas Weidner helped porting CHICKEN to the
     AMD-64 platform.

   * Tony Garnock-Jones ported CHICKEN to HP-UX and provided countless
     fixes and improvements.

   * Sven Hartrumpf helped porting CHICKEN to the UltraSparc, suggested
     many improvements and helped fixing numerous bugs.

   * Bruce Hoult fixed several bugs and pointed out performance
     improvements.

   * Dale Jordan pointed out several bugs, helped fixing problems on the
     Cygwin platform and contributed the `calendar.scm' example script.

   * Peter Keller translated the manual from HTML into LaTeX and
     contributed the testing infrastructure code.

   * Sergey Khorev ported a large part of the POSIX library to Windows.

   * Kirill Lisovsky found a couple of bugs while porting Oleg
     Kiselyov's SSAX XML parser to CHICKEN.

   * Dennis Marti ported CHICKEN to Mac OS X.

   * Chris Moline and Bakul Shah helped porting CHICKEN to FreeBSD.

   * Davide Puricelli maintains the Debian package.

   * Doug Quale contributed the configuration scripts for installation
     on UNIX-like systems, suggested numerous improvements and was
     generally very helpful.

   * Benedikt Rosenau found several bugs and spent a lot of time testing
     the system and pointing out improvements.

   * Michele Simionato discovered several bugs and provided numerous
     helpful suggestions.

   * Dorai Sitaram pointed out several improvements in the TeX manual.

   * Mike Thomas ported CHICKEN to the Mingw32 platform.

   * John Tobey ported CHICKEN to MIPS.

   * Panagiotis Vossos ported CHICKEN to Alpha/Linux.

   * Peter Wang produced countless bugfixes and helpful suggestions.

   * Jorg Wittenberger found and fixed many bugs in the runtime system.

   * CHICKEN contains code from several people:
        * Eli Barzilay: some performance tweaks used in TinyCLOS.

        * Anthony Carrico: the option parsing facility.

        * Mikael Djurfeldt: topological sort used by compiler.

        * Marc Feeley: pretty-printer.

        * Aubrey Jaffer: implementation of `dynamic-wind'.

        * R. Kent Dybvig, Oscar Waddel, Robert Hieb & Carl Bruggeman:
          `syntax-case' macro system.

        * Gregor Kiczales: original implementation of TinyCLOS.

        * Dirk Lutzebaeck: Common LISP `format'.

        * Richard O'Keefe: sorting routines.

        * Jussi Piitulainen: reference implementation for SRFI-25.

        * Olin Shivers: implementation of `let-optionals[*]' and
          reference implementations of SRFI-1, SRFI-13 and SRFI-14.

        * Dorai Sitaram: the PREGEXP regular expression package and
          TeX2page, which was used to generate the HTML documentation.

        * Andrew Wilcox: queues.

        * Andrew Wright: pattern matcher.


   Thanks also to:

   William Annis, Marc Baily, Peter Barabas, Peter Bex, Dave Bodenstab,
Fabian Böhlke, T. Kurt Bond, Terence Brannon, Roy Bryant, Taylor
Campbell, Franklin Chen, Gian Paolo Ciceri, Grzegorz Chrupala, James
Crippen, Alejandro Forero Cuervo, Brian Denheyer, Chris Double, Petter
Egesund, Daniel B. Faken, Fizzie, Kimura Fuyuki, Martin Gasbichler,
Joey Gibson, Johannes Groedem, Andreas Gustafsson, Jun-ichiro itojun
Hagino, Matthias Heiler, Karl M. Hegbloom, William P. Heinemann, Dale
Jordan, Valentin Kamyshenko, Ron Kneusel, Matthias Koeppe, Todd R.
Kueny Sr, Micky Latowicki, Charles Martin, Alain Mellan, Perry Metzger,
Scott G. Miller, Mikael, Bruce Mitchener, Eric Merrit, Eric E. Moore,
Lars Nilsson, o.t., Eric Raible, Joel Reymont, David Rush, Lars
Rustemeier, Oskar Schirmer, Burton Samograd, Ronald Schroder, Spencer
Schumann, Shmul, Jeffrey B. Siegal, Robert Skeels, Jason Songhurst,
Clifford Stein, Christian Tismer, Vladimir Tsichevsky, Neil van Dyke,
Sander Vesik, Shawn Wagner, Ed Watkeys, Matthew Welland, Richard
Zidlicky and Houman Zolfaghari for bug-fixes, tips, suggestions and
moral support.


File: chicken.info,  Node: Bibliography,  Next: Index,  Prev: Acknowledgements,  Up: Top

Bibliography
************

Henry Baker: _CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A._
     `http://home.pipeline.com/\~hbaker1/CheneyMTA.html'

Revised^5 Report on the Algorithmic Language Scheme
     `http://www.schemers.org/Documents/Standards/R5RS'


File: chicken.info,  Node: Index,  Prev: Bibliography,  Up: Top

Index
*****

[index]
* Menu:

* #:                                     Macros and procedures implemented in the interpreter.
                                                              (line  98)
* #!...:                                 Non standard read syntax.
                                                              (line  94)
* #$EXPRESSION:                          Non standard read syntax.
                                                              (line  22)
* #%...:                                 Non standard read syntax.
                                                              (line  91)
* #'EXPRESSION:                          Non standard read syntax.
                                                              (line  19)
* #,(CONSTRUCTORNAME DATUM ...):         Non standard read syntax.
                                                              (line  14)
* #:SYMBOL:                              Non standard read syntax.
                                                              (line  25)
* #;EXPRESSION:                          Non standard read syntax.
                                                              (line  11)
* #<#TAG:                                Non standard read syntax.
                                                              (line  44)
* #<<TAG:                                Non standard read syntax.
                                                              (line  29)
* #>:                                    Non standard read syntax.
                                                              (line  65)
* #>!:                                   Non standard read syntax.
                                                              (line  71)
* #>$:                                   Non standard read syntax.
                                                              (line  79)
* #>%:                                   Non standard read syntax.
                                                              (line  85)
* #>?:                                   Non standard read syntax.
                                                              (line  68)
* #| ... |#:                             Non standard read syntax.
                                                              (line   7)
* (:                                     C interface.         (line 117)
* *-restult?:                            Miscellaneous API.   (line  10)
* *-result-ref:                          Miscellaneous API.   (line  15)
* ->string:                              Strings.             (line  16)
* :optional:                             Binding forms for optional arguments.
                                                              (line   7)
* <array>:                               Builtin classes.     (line 112)
* <boolean>:                             Builtin classes.     (line  64)
* <byte-vector>:                         Builtin classes.     (line  83)
* <c++-class>:                           Builtin classes.     (line 145)
* <char-set>:                            Builtin classes.     (line 113)
* <char>:                                Builtin classes.     (line  66)
* <class>:                               Builtin classes.     (line  90)
* <condition>:                           Builtin classes.     (line 109)
* <end-of-file>:                         Builtin classes.     (line  77)
* <entity-class>:                        Builtin classes.     (line  93)
* <environment>:                         Builtin classes.     (line  76)
* <exact>:                               Builtin classes.     (line  72)
* <f32vector>:                           Builtin classes.     (line 121)
* <f64vector>:                           Builtin classes.     (line 122)
* <generic>:                             Builtin classes.     (line  97)
* <hash-table>:                          Builtin classes.     (line  85)
* <inexact>:                             Builtin classes.     (line  73)
* <input-port>:                          Builtin classes.     (line  78)
* <integer>:                             Builtin classes.     (line  71)
* <locative>:                            Builtin classes.     (line 136)
* <lock>:                                Builtin classes.     (line 126)
* <method>:                              Builtin classes.     (line 100)
* <mmap>:                                Builtin classes.     (line 127)
* <null>:                                Builtin classes.     (line  68)
* <number>:                              Builtin classes.     (line  70)
* <object>:                              Builtin classes.     (line 103)
* <output-port>:                         Builtin classes.     (line  79)
* <pair>:                                Builtin classes.     (line  69)
* <pointer>:                             Builtin classes.     (line 130)
* <port>:                                Builtin classes.     (line  75)
* <primitive>:                           Builtin classes.     (line  61)
* <procedure-class>:                     Builtin classes.     (line 106)
* <procedure>:                           Builtin classes.     (line  80)
* <promise>:                             Builtin classes.     (line 139)
* <queue>:                               Builtin classes.     (line  86)
* <s16vector>:                           Builtin classes.     (line 118)
* <s32vector>:                           Builtin classes.     (line 120)
* <s8vector>:                            Builtin classes.     (line 116)
* <string>:                              Builtin classes.     (line  74)
* <structure>:                           Builtin classes.     (line  84)
* <swig-pointer>:                        Builtin classes.     (line 132)
* <symbol>:                              Builtin classes.     (line  65)
* <tagged-pointer>:                      Builtin classes.     (line 131)
* <tcp-listener>:                        Builtin classes.     (line 142)
* <time>:                                Builtin classes.     (line 114)
* <u16vector>:                           Builtin classes.     (line 117)
* <u32vector>:                           Builtin classes.     (line 119)
* <u8vector>:                            Builtin classes.     (line 115)
* <vector>:                              Builtin classes.     (line  67)
* _exit:                                 Raw exit.            (line   7)
* absolute-pathname?:                    Pathname operations. (line   7)
* add-method:                            Base language.       (line   7)
* add1:                                  Arithmetic.          (line   7)
* address->pointer:                      Foreign pointers.    (line   7)
* advise:                                Macros and procedures implemented in the interpreter.
                                                              (line   9)
* align-to-word:                         Foreign pointers.    (line 164)
* alist-ref:                             Lists.               (line   7)
* alist-update!:                         Lists.               (line  13)
* all-testcase-expectations-true?:       Miscellaneous API.   (line  28)
* all-testpackage-results-true?:         Miscellaneous API.   (line  21)
* allocate:                              Foreign pointers.    (line  13)
* allocate-instance:                     Intercessory protocol.
                                                              (line  11)
* always-bound:                          Declarations.        (line  17)
* and-let*:                              Other binding forms. (line   7)
* andmap:                                Other control structures.
                                                              (line   7)
* argc+argv:                             Other support procedures.
                                                              (line   7)
* argv:                                  Environment information and system interface.
                                                              (line   7)
* arithmetic-shift:                      Arithmetic.          (line  18)
* assert:                                Other forms.         (line   7)
* atom?:                                 Lists.               (line  22)
* binary-search:                         Binary searching.    (line   7)
* bitwise-and:                           Arithmetic.          (line  14)
* bitwise-ior:                           Arithmetic.          (line  15)
* bitwise-not:                           Arithmetic.          (line  17)
* bitwise-xor:                           Arithmetic.          (line  16)
* block:                                 Declarations.        (line  22)
* block-global:                          Declarations.        (line  27)
* block-ref:                             Low-level data access.
                                                              (line   7)
* block-set!:                            Low-level data access.
                                                              (line  13)
* bound-to-procedure:                    Declarations.        (line  36)
* build-platform:                        Environment information and system interface.
                                                              (line  23)
* butlast:                               Lists.               (line  34)
* byte-vector:                           Bytevectors.         (line   7)
* byte-vector->f32vector:                Unit srfi-4.         (line  39)
* byte-vector->f64vector:                Unit srfi-4.         (line  40)
* byte-vector->list:                     Bytevectors.         (line  24)
* byte-vector->s16vector:                Unit srfi-4.         (line  36)
* byte-vector->s32vector:                Unit srfi-4.         (line  38)
* byte-vector->s8vector:                 Unit srfi-4.         (line  34)
* byte-vector->string:                   Bytevectors.         (line  29)
* byte-vector->u16vector:                Unit srfi-4.         (line  35)
* byte-vector->u32vector:                Unit srfi-4.         (line  37)
* byte-vector->u8vector:                 Unit srfi-4.         (line  33)
* byte-vector-fill!:                     Bytevectors.         (line  18)
* byte-vector-length:                    Bytevectors.         (line  34)
* byte-vector-ref:                       Bytevectors.         (line  39)
* byte-vector-set!:                      Bytevectors.         (line  44)
* byte-vector?:                          Bytevectors.         (line  13)
* c-options:                             Declarations.        (line  41)
* c-runtime:                             Environment information and system interface.
                                                              (line 103)
* C_alloc:                               C interface.         (line  38)
* C_block_item:                          C interface.         (line  77)
* C_c_string:                            C interface.         (line  66)
* C_callback:                            Callbacks.           (line  77)
* C_character_code:                      C interface.         (line  63)
* C_data_pointer:                        C interface.         (line  83)
* C_fix:                                 C interface.         (line  13)
* C_flonum:                              C interface.         (line  29)
* C_flonum_magnitude:                    C interface.         (line  65)
* C_gc_protect:                          C interface.         (line 101)
* C_gc_unprotect:                        C interface.         (line 113)
* C_header_bits:                         C interface.         (line  73)
* C_header_size:                         C interface.         (line  72)
* C_int_to_num:                          C interface.         (line  30)
* C_intern2:                             C interface.         (line  25)
* C_intern3:                             C interface.         (line  27)
* C_list:                                C interface.         (line  33)
* C_make_character:                      C interface.         (line  14)
* C_make_header:                         C interface.         (line  87)
* C_mpointer:                            C interface.         (line  31)
* C_mutate:                              C interface.         (line  91)
* C_num_to_int:                          C interface.         (line  67)
* C_pair:                                C interface.         (line  28)
* C_pointer_address:                     C interface.         (line  68)
* C_save:                                C interface.         (line  10)
* C_SCHEME_END_OF_FILE:                  C interface.         (line  16)
* C_SCHEME_END_OF_LIST:                  C interface.         (line  15)
* C_SCHEME_FALSE:                        C interface.         (line  17)
* C_SCHEME_TRUE:                         C interface.         (line  18)
* C_SIZEOF_FLONUM:                       C interface.         (line  56)
* C_SIZEOF_INTERNED_SYMBOL:              C interface.         (line  54)
* C_SIZEOF_LIST:                         C interface.         (line  51)
* C_SIZEOF_LOCATIVE:                     C interface.         (line  58)
* C_SIZEOF_PAIR:                         C interface.         (line  55)
* C_SIZEOF_POINTER:                      C interface.         (line  57)
* C_SIZEOF_STRING:                       C interface.         (line  52)
* C_SIZEOF_TAGGED_POINTER:               C interface.         (line  59)
* C_SIZEOF_VECTOR:                       C interface.         (line  53)
* C_string:                              C interface.         (line  21)
* C_string2:                             C interface.         (line  23)
* C_symbol_value:                        C interface.         (line  98)
* C_unfix:                               C interface.         (line  64)
* C_vector:                              C interface.         (line  32)
* call-with-input-pipe:                  Pipes.               (line   7)
* call-with-input-string:                String-port extensions.
                                                              (line   7)
* call-with-output-pipe:                 Pipes.               (line   8)
* call-with-output-string:               String-port extensions.
                                                              (line  13)
* call/cc:                               call/cc.             (line   7)
* case-lambda:                           Binding forms for optional arguments.
                                                              (line  20)
* case-sensitive:                        Parameters.          (line  37)
* change-directory:                      Directories.         (line   7)
* change-file-mode:                      Permissions.         (line  30)
* change-file-owner:                     Permissions.         (line  38)
* char-name:                             User-defined named characters.
                                                              (line   7)
* chicken-home:                          Environment information and system interface.
                                                              (line 111)
* chicken-version:                       Environment information and system interface.
                                                              (line  38)
* CHICKEN_apply:                         Entry points.        (line 226)
* CHICKEN_apply_to_string:               Entry points.        (line 231)
* CHICKEN_delete_gc_root:                Entry points.        (line 315)
* CHICKEN_eval:                          Entry points.        (line 202)
* CHICKEN_eval_string:                   Entry points.        (line 209)
* CHICKEN_eval_string_to_string:         Entry points.        (line 220)
* CHICKEN_eval_to_string:                Entry points.        (line 214)
* CHICKEN_gc_root_ref:                   Entry points.        (line 318)
* CHICKEN_gc_root_set:                   Entry points.        (line 321)
* CHICKEN_get_error_message:             Entry points.        (line 244)
* CHICKEN_global_lookup:                 Entry points.        (line 326)
* CHICKEN_global_ref:                    Entry points.        (line 330)
* CHICKEN_global_set:                    Entry points.        (line 334)
* CHICKEN_initialize:                    Entry points.        (line  82)
* CHICKEN_invoke:                        Entry points.        (line 105)
* CHICKEN_is_running:                    Entry points.        (line 123)
* CHICKEN_load:                          Entry points.        (line 240)
* CHICKEN_new_gc_root:                   Entry points.        (line 309)
* CHICKEN_parse_command_line:            Entry points.        (line  74)
* CHICKEN_read:                          Entry points.        (line 236)
* CHICKEN_run:                           Entry points.        (line  96)
* CHICKEN_yield:                         Entry points.        (line 248)
* chop:                                  Lists.               (line  39)
* class-cpl:                             Introspection.       (line   7)
* class-direct-slots:                    Introspection.       (line  12)
* class-direct-supers:                   Introspection.       (line  18)
* class-name:                            Introspection.       (line  28)
* class-of:                              Introspection.       (line  23)
* class-slots:                           Introspection.       (line  33)
* clear-hash-table!:                     Hash tables.         (line   7)
* close-input-pipe:                      Pipes.               (line  17)
* close-output-pipe:                     Pipes.               (line  18)
* command-line-arguments:                Parameters.          (line  49)
* complement:                            Combinators.         (line  16)
* compose:                               Combinators.         (line  22)
* compress:                              Lists.               (line  50)
* compress-literals:                     Declarations.        (line  48)
* compute-apply-generic:                 Intercessory protocol.
                                                              (line  17)
* compute-apply-methods:                 Intercessory protocol.
                                                              (line  23)
* compute-cpl:                           Intercessory protocol.
                                                              (line  36)
* compute-getter-and-setter:             Intercessory protocol.
                                                              (line  41)
* compute-method-more-specific?:         Intercessory protocol.
                                                              (line  48)
* compute-methods:                       Intercessory protocol.
                                                              (line  29)
* compute-slots:                         Intercessory protocol.
                                                              (line  56)
* conc:                                  Strings.             (line   7)
* cond-expand:                           Other forms.         (line  16)
* condition-case:                        Exceptions.          (line  11)
* conjoin:                               Combinators.         (line  34)
* constantly:                            Combinators.         (line   7)
* cpu-time:                              Execution time.      (line   7)
* create-directory:                      Directories.         (line  17)
* create-fifo:                           Fifos.               (line   7)
* create-pipe:                           Pipes.               (line  25)
* create-session:                        Permissions.         (line 130)
* create-symbolic-link:                  Symbolic links.      (line   7)
* create-temporary-file:                 Temporary files.     (line   7)
* critical-section:                      Other forms.         (line  28)
* current-directory:                     Directories.         (line  12)
* current-effective-group-id:            Permissions.         (line  48)
* current-effective-user-id:             Permissions.         (line  47)
* current-environment:                   Environment access.  (line   7)
* current-error-port:                    File Input/Output.   (line   7)
* current-group-id:                      Permissions.         (line  46)
* current-milliseconds:                  Execution time.      (line  15)
* current-process-id:                    Processes.           (line   7)
* current-seconds:                       Execution time.      (line  21)
* current-user-id:                       Permissions.         (line  45)
* cut:                                   Other binding forms. (line  21)
* cute:                                  Other binding forms. (line  22)
* debug-expand:                          Unit syntax-case.    (line  77)
* declare:                               Declarations.        (line   7)
* decompose-pathname:                    Pathname operations. (line  13)
* define-class:                          Defining forms.      (line   7)
* define-constant:                       Substitution forms and macros.
                                                              (line   7)
* define-embedded:                       Entry points.        (line  45)
* define-entry-point:                    Entry points.        (line  16)
* define-external:                       Callbacks.           (line  27)
* define-foreign-record:                 Accessing external objects.
                                                              (line  86)
* define-foreign-type:                   Accessing external objects.
                                                              (line  26)
* define-foreign-variable:               Accessing external objects.
                                                              (line  56)
* define-generic:                        Defining forms.      (line  42)
* define-inline:                         Substitution forms and macros.
                                                              (line  23)
* define-location:                       Locations.           (line  12)
* define-macro:                          Substitution forms and macros.
                                                              (line  40)
* define-method:                         Defining forms.      (line  50)
* define-reader-ctor:                    Reader extensions.   (line   7)
* define-record:                         Record structures.   (line   7)
* define-record-printer:                 Record structures.   (line  24)
* define-record-type:                    Record structures.   (line  49)
* define-values:                         Other binding forms. (line  29)
* delete-directory:                      Directories.         (line  22)
* delete-file:                           Files.               (line   7)
* delete-file*:                          Deleting a file without signalling an error.
                                                              (line   7)
* describe-object:                       Additional protocol. (line   7)
* destructor-activate!:                  Destructor Object API.
                                                              (line  35)
* destructor-atexit!:                    Destructor Object API.
                                                              (line  26)
* destructor-clear!:                     Destructor Object API.
                                                              (line  46)
* destructor-dump:                       Destructor Object API.
                                                              (line  53)
* directory:                             Directories.         (line  28)
* directory?:                            Directories.         (line  34)
* disable-interrupts <1>:                Interrupts and error-handling.
                                                              (line   8)
* disable-interrupts:                    Declarations.        (line  81)
* disjoin:                               Combinators.         (line  42)
* duplicate-fileno:                      File descriptors and low-level I/O.
                                                              (line   7)
* dynamic-load-libraries:                Parameters.          (line  43)
* enable-interrupts:                     Interrupts and error-handling.
                                                              (line   7)
* enable-warnings:                       Interrupts and error-handling.
                                                              (line  21)
* end-of-file:                           File Input/Output.   (line  13)
* ensure:                                Other forms.         (line  33)
* errno:                                 Environment information and system interface.
                                                              (line  44)
* errno/acces:                           ERRNO values.        (line  16)
* errno/again:                           ERRNO values.        (line  26)
* errno/badf:                            ERRNO values.        (line  13)
* errno/busy:                            ERRNO values.        (line  18)
* errno/child:                           ERRNO values.        (line  14)
* errno/fault:                           ERRNO values.        (line  17)
* errno/intr:                            ERRNO values.        (line  10)
* errno/inval:                           ERRNO values.        (line  21)
* errno/io:                              ERRNO values.        (line  11)
* errno/isdir:                           ERRNO values.        (line  20)
* errno/mfile:                           ERRNO values.        (line  22)
* errno/noent:                           ERRNO values.        (line   8)
* errno/noexec:                          ERRNO values.        (line  12)
* errno/nomem:                           ERRNO values.        (line  15)
* errno/nospc:                           ERRNO values.        (line  23)
* errno/notdir:                          ERRNO values.        (line  19)
* errno/perm:                            ERRNO values.        (line   7)
* errno/pipe:                            ERRNO values.        (line  25)
* errno/rofs:                            ERRNO values.        (line  27)
* errno/spipe:                           ERRNO values.        (line  24)
* errno/srch:                            ERRNO values.        (line   9)
* errno/wouldblock:                      ERRNO values.        (line  28)
* error:                                 Interrupts and error-handling.
                                                              (line  30)
* eval:                                  Eval.                (line   7)
* eval-handler:                          Parameters.          (line  61)
* eval-when:                             Other forms.         (line  47)
* executable-byte-vector->procedure:     Bytevectors.         (line  50)
* exit:                                  Environment information and system interface.
                                                              (line  17)
* exit-handler:                          Parameters.          (line  55)
* expect-eq?:                            The Expectation Macro API.
                                                              (line  93)
* expect-equal?:                         The Expectation Macro API.
                                                              (line 147)
* expect-equivalence-result-lhs-evaled-ref: Equivalence Style Expectation.
                                                              (line  46)
* expect-equivalence-result-message-ref: Equivalence Style Expectation.
                                                              (line  41)
* expect-equivalence-result-result-ref:  Equivalence Style Expectation.
                                                              (line  21)
* expect-equivalence-result-rhs-evaled-ref: Equivalence Style Expectation.
                                                              (line  56)
* expect-equivalence-result-rhs-unevaled-ref: Equivalence Style Expectation.
                                                              (line  51)
* expect-equivalence-result-specific-ref: Equivalence Style Expectation.
                                                              (line  26)
* expect-equivalence-result-warning-ref: Equivalence Style Expectation.
                                                              (line  66)
* expect-equivalence-result-warning?:    Equivalence Style Expectation.
                                                              (line  61)
* expect-equivalence-result?:            Equivalence Style Expectation.
                                                              (line  15)
* expect-eqv?:                           The Expectation Macro API.
                                                              (line 120)
* expect-false:                          The Expectation Macro API.
                                                              (line  76)
* expect-near?:                          The Expectation Macro API.
                                                              (line 174)
* expect-negative:                       The Expectation Macro API.
                                                              (line 222)
* expect-nonzero:                        The Expectation Macro API.
                                                              (line  40)
* expect-positive:                       The Expectation Macro API.
                                                              (line 204)
* expect-result-evaled-ref:              Single Clause Style Expectation.
                                                              (line  52)
* expect-result-message-ref:             Single Clause Style Expectation.
                                                              (line  42)
* expect-result-result-ref:              Single Clause Style Expectation.
                                                              (line  19)
* expect-result-specific-ref:            Single Clause Style Expectation.
                                                              (line  24)
* expect-result-unevaled-ref:            Single Clause Style Expectation.
                                                              (line  47)
* expect-result-warning-ref:             Single Clause Style Expectation.
                                                              (line  62)
* expect-result-warning?:                Single Clause Style Expectation.
                                                              (line  57)
* expect-result?:                        Single Clause Style Expectation.
                                                              (line  13)
* expect-tolerance-result-lhs-evaled-ref: Tolerance Style Expectation.
                                                              (line  45)
* expect-tolerance-result-lhs-tol-evaled-ref: Tolerance Style Expectation.
                                                              (line  50)
* expect-tolerance-result-message-ref:   Tolerance Style Expectation.
                                                              (line  40)
* expect-tolerance-result-result-ref:    Tolerance Style Expectation.
                                                              (line  21)
* expect-tolerance-result-rhs-evaled-ref: Tolerance Style Expectation.
                                                              (line  60)
* expect-tolerance-result-rhs-unevaled-ref: Tolerance Style Expectation.
                                                              (line  55)
* expect-tolerance-result-specific-ref:  Tolerance Style Expectation.
                                                              (line  26)
* expect-tolerance-result-warning-ref:   Tolerance Style Expectation.
                                                              (line  70)
* expect-tolerance-result-warning?:      Tolerance Style Expectation.
                                                              (line  65)
* expect-tolerance-result?:              Tolerance Style Expectation.
                                                              (line  15)
* expect-true:                           The Expectation Macro API.
                                                              (line  59)
* expect-zero:                           The Expectation Macro API.
                                                              (line  22)
* export:                                Declarations.        (line  56)
* extend-procedure:                      Extending procedures with data.
                                                              (line   7)
* extended-bindings:                     Declarations.        (line 140)
* extended-procedure?:                   Extending procedures with data.
                                                              (line  15)
* extension-info:                        Loading extension libraries.
                                                              (line  18)
* f32vector->byte-vector:                Unit srfi-4.         (line  17)
* f64vector->byte-vector:                Unit srfi-4.         (line  18)
* features:                              Feature identifiers. (line  20)
* fifo?:                                 Fifos.               (line  16)
* file-access-time:                      Retrieving file attributes.
                                                              (line   7)
* file-change-time:                      Retrieving file attributes.
                                                              (line   8)
* file-close:                            File descriptors and low-level I/O.
                                                              (line  14)
* file-execute-access?:                  Permissions.         (line  22)
* file-exists?:                          Files.               (line  13)
* file-lock:                             Record locking.      (line   7)
* file-lock/blocking:                    Record locking.      (line  17)
* file-mkstemp:                          File descriptors and low-level I/O.
                                                              (line  32)
* file-modification-time:                Retrieving file attributes.
                                                              (line   9)
* file-open:                             File descriptors and low-level I/O.
                                                              (line  19)
* file-owner:                            Permissions.         (line   7)
* file-permissions:                      Permissions.         (line  13)
* file-position:                         Retrieving file attributes.
                                                              (line  27)
* file-read:                             File descriptors and low-level I/O.
                                                              (line  48)
* file-read-access?:                     Permissions.         (line  20)
* file-select:                           File descriptors and low-level I/O.
                                                              (line  58)
* file-size:                             Retrieving file attributes.
                                                              (line  33)
* file-stat:                             Retrieving file attributes.
                                                              (line  17)
* file-test-lock:                        Record locking.      (line  24)
* file-truncate:                         Changing file attributes.
                                                              (line   7)
* file-unlock:                           Record locking.      (line  32)
* file-write:                            File descriptors and low-level I/O.
                                                              (line  73)
* file-write-access?:                    Permissions.         (line  21)
* fileno/stderr:                         File descriptors and low-level I/O.
                                                              (line  82)
* fileno/stdin:                          File descriptors and low-level I/O.
                                                              (line  80)
* fileno/stdout:                         File descriptors and low-level I/O.
                                                              (line  81)
* find-files:                            Finding files.       (line   7)
* fixnum-arithmetic:                     Declarations.        (line 121)
* fixnum?:                               Arithmetic.          (line  31)
* flatten:                               Lists.               (line  60)
* flip:                                  Combinators.         (line  50)
* fluid-let:                             Other binding forms. (line  35)
* flush-output:                          File Input/Output.   (line  18)
* for-each-argv-line:                    Iterating over input lines and files.
                                                              (line  16)
* for-each-line:                         Iterating over input lines and files.
                                                              (line   7)
* force-finalizers:                      Parameters.          (line  68)
* foreign-callback-lambda:               Accessing external objects.
                                                              (line 133)
* foreign-callback-lambda*:              Accessing external objects.
                                                              (line 139)
* foreign-callback-wrapper:              Callbacks.           (line  68)
* foreign-code:                          Accessing external objects.
                                                              (line   7)
* foreign-declare:                       Declarations.        (line  66)
* foreign-lambda:                        Accessing external objects.
                                                              (line 145)
* foreign-lambda*:                       Accessing external objects.
                                                              (line 153)
* foreign-parse:                         Declarations.        (line  70)
* foreign-value:                         Accessing external objects.
                                                              (line  17)
* format:                                Unit format.         (line   7)
* fp*:                                   Arithmetic.          (line  87)
* fp+:                                   Arithmetic.          (line  85)
* fp-:                                   Arithmetic.          (line  86)
* fp/:                                   Arithmetic.          (line  88)
* fp<:                                   Arithmetic.          (line  94)
* fp<=:                                  Arithmetic.          (line  96)
* fp=:                                   Arithmetic.          (line  92)
* fp>:                                   Arithmetic.          (line  93)
* fp>=:                                  Arithmetic.          (line  95)
* fpmax:                                 Arithmetic.          (line  91)
* fpmin:                                 Arithmetic.          (line  90)
* fpneg:                                 Arithmetic.          (line  89)
* fprintf:                               Formatted output.    (line   7)
* free:                                  Foreign pointers.    (line  22)
* fx*:                                   Arithmetic.          (line  38)
* fx+:                                   Arithmetic.          (line  36)
* fx-:                                   Arithmetic.          (line  37)
* fx/:                                   Arithmetic.          (line  39)
* fx<:                                   Arithmetic.          (line  46)
* fx<=:                                  Arithmetic.          (line  48)
* fx=:                                   Arithmetic.          (line  44)
* fx>:                                   Arithmetic.          (line  45)
* fx>=:                                  Arithmetic.          (line  47)
* fxand:                                 Arithmetic.          (line  49)
* fxior:                                 Arithmetic.          (line  50)
* fxmax:                                 Arithmetic.          (line  43)
* fxmin:                                 Arithmetic.          (line  42)
* fxmod:                                 Arithmetic.          (line  40)
* fxneg:                                 Arithmetic.          (line  41)
* fxnot:                                 Arithmetic.          (line  52)
* fxshl:                                 Arithmetic.          (line  53)
* fxshr:                                 Arithmetic.          (line  54)
* fxxor:                                 Arithmetic.          (line  51)
* gc:                                    Garbage collection.  (line   7)
* generic-methods:                       Introspection.       (line  39)
* gensym:                                Generating uninterned symbols.
                                                              (line   7)
* get:                                   Hash tables.         (line  12)
* get-groups:                            Permissions.         (line  69)
* get-host-name:                         Getting the hostname and system information.
                                                              (line   7)
* get-keyword:                           Keywords.            (line  15)
* get-line-number:                       Macros.              (line   7)
* get-output-string:                     String ports.        (line   7)
* getenv:                                Environment information and system interface.
                                                              (line  49)
* glob:                                  Directories.         (line  40)
* global-bound?:                         Accessing toplevel variables.
                                                              (line   7)
* global-ref:                            Accessing toplevel variables.
                                                              (line  13)
* global-set!:                           Accessing toplevel variables.
                                                              (line  19)
* gloss:                                 Gloss API.           (line  12)
* gloss-result-message-ref:              Gloss API.           (line  30)
* gloss-result-warning-ref:              Gloss API.           (line  40)
* gloss-result-warning?:                 Gloss API.           (line  35)
* gloss-result?:                         Gloss API.           (line  24)
* grep:                                  Unit regex.          (line  19)
* group-information:                     Permissions.         (line  61)
* hash-table->list:                      Hash tables.         (line  26)
* hash-table-count:                      Hash tables.         (line  31)
* hash-table-for-each:                   Hash tables.         (line  41)
* hash-table-ref:                        Hash tables.         (line  48)
* hash-table-remove!:                    Hash tables.         (line  54)
* hash-table-set!:                       Hash tables.         (line  59)
* hash-table-size:                       Hash tables.         (line  36)
* hash-table?:                           Hash tables.         (line  21)
* hide:                                  Declarations.        (line  28)
* identity:                              Combinators.         (line  57)
* implicit-exit-handler:                 Parameters.          (line  74)
* include:                               Other forms.         (line  75)
* initialize:                            Intercessory protocol.
                                                              (line  61)
* initialize-groups:                     Permissions.         (line  81)
* initialize-slots:                      Utility procedures.  (line   7)
* install-extension:                     Procedures and macros available in setup scripts.
                                                              (line   7)
* install-highlevel-macro-system:        chicken-highlevel-macros.scm.
                                                              (line  25)
* install-program:                       Procedures and macros available in setup scripts.
                                                              (line  36)
* install-script:                        Procedures and macros available in setup scripts.
                                                              (line  41)
* instance?:                             Base language.       (line  13)
* interrupts-enabled:                    Declarations.        (line  76)
* intersperse:                           Lists.               (line  66)
* invalid-procedure-call-handler:        Procedure-call- and variable reference hooks.
                                                              (line   7)
* invoke-executable-byte-vector:         Bytevectors.         (line  98)
* join:                                  Lists.               (line  71)
* keyword->string:                       Keywords.            (line  36)
* keyword-style:                         Parameters.          (line  82)
* keyword?:                              Keywords.            (line  31)
* let*-values:                           Other binding forms. (line  47)
* let-location:                          Locations.           (line  19)
* let-optionals:                         Binding forms for optional arguments.
                                                              (line  42)
* let-optionals*:                        Binding forms for optional arguments.
                                                              (line  43)
* let-values:                            Other binding forms. (line  41)
* letrec-values:                         Other binding forms. (line  56)
* link-options:                          Declarations.        (line  89)
* list->byte-vector:                     Bytevectors.         (line 115)
* list->queue:                           Queues.              (line   7)
* list-of:                               Combinators.         (line  67)
* load:                                  Loading code.        (line   7)
* load-library:                          Loading code.        (line  33)
* load-noisily:                          Loading code.        (line  53)
* load-verbose:                          Parameters.          (line  88)
* location:                              Locations.           (line  24)
* locative->object:                      Locatives.           (line  53)
* locative-ref:                          Locatives.           (line  39)
* locative-set!:                         Locatives.           (line  46)
* locative?:                             Locatives.           (line  34)
* machine-type:                          Environment information and system interface.
                                                              (line  55)
* macro?:                                Macros.              (line  16)
* macroexpand:                           Macros.              (line  21)
* macroexpand-1:                         Macros.              (line  28)
* make <1>:                              Procedures and macros available in setup scripts.
                                                              (line  52)
* make:                                  Base language.       (line  18)
* make-absolute-pathname:                Pathname operations. (line  22)
* make-byte-vector:                      Bytevectors.         (line 121)
* make-class:                            Base language.       (line  24)
* make-executable-byte-vector:           Bytevectors.         (line 128)
* make-generic:                          Base language.       (line  31)
* make-hash-table:                       Hash tables.         (line  64)
* make-input-port:                       Input/Output extensions.
                                                              (line   7)
* make-locative:                         Locatives.           (line  18)
* make-method:                           Base language.       (line  37)
* make-output-port:                      Input/Output extensions.
                                                              (line  22)
* make-parameter:                        Parameters.          (line  25)
* make-pathname:                         Pathname operations. (line  21)
* make-queue:                            Queues.              (line  15)
* make-record-instance:                  Low-level data access.
                                                              (line  27)
* make-static-byte-vector:               Bytevectors.         (line 137)
* make-weak-locative:                    Locatives.           (line  27)
* map-file-to-memory:                    Memory mapped I/O.   (line  12)
* match:                                 Unit match.          (line  12)
* match-define:                          Unit match.          (line  18)
* match-error-control:                   Unit match.          (line  32)
* match-lambda:                          Unit match.          (line  13)
* match-lambda*:                         Unit match.          (line  14)
* match-let:                             Unit match.          (line  15)
* match-let*:                            Unit match.          (line  16)
* match-letrec:                          Unit match.          (line  17)
* memory-mapped-file-pointer:            Memory mapped I/O.   (line  28)
* memory-mapped-file?:                   Memory mapped I/O.   (line   7)
* memory-statistics:                     Garbage collection.  (line  15)
* merge:                                 Sorting.             (line   7)
* merge!:                                Sorting.             (line   8)
* method-procedure:                      Introspection.       (line  50)
* method-specializers:                   Introspection.       (line  45)
* move-memory!:                          Low-level data access.
                                                              (line  50)
* no-argc-checks:                        Declarations.        (line  97)
* no-bound-checks:                       Declarations.        (line 101)
* no-procedure-checks:                   Declarations.        (line 105)
* noop:                                  Combinators.         (line  77)
* not:                                   Declarations.        (line  82)
* nth-value:                             Other forms.         (line  84)
* null-pointer:                          Foreign pointers.    (line  31)
* null-pointer?:                         Foreign pointers.    (line  36)
* number-of-bytes:                       Low-level data access.
                                                              (line  63)
* number-of-slots:                       Low-level data access.
                                                              (line  69)
* object->pointer:                       Foreign pointers.    (line  41)
* object-become!:                        Magic.               (line   7)
* object-copy:                           Low-level data access.
                                                              (line  20)
* object-evict:                          Data in unmanaged memory.
                                                              (line   7)
* object-evict-to-location:              Data in unmanaged memory.
                                                              (line  34)
* object-evicted?:                       Data in unmanaged memory.
                                                              (line  43)
* object-release:                        Data in unmanaged memory.
                                                              (line  55)
* object-size:                           Data in unmanaged memory.
                                                              (line  49)
* object-unevict:                        Data in unmanaged memory.
                                                              (line  63)
* open-input-file*:                      File descriptors and low-level I/O.
                                                              (line 103)
* open-input-pipe:                       Pipes.               (line  32)
* open-input-string:                     String ports.        (line  13)
* open-output-file*:                     File descriptors and low-level I/O.
                                                              (line 104)
* open-output-pipe:                      Pipes.               (line  40)
* open-output-string:                    String ports.        (line  18)
* open/append:                           File descriptors and low-level I/O.
                                                              (line  92)
* open/binary:                           File descriptors and low-level I/O.
                                                              (line  99)
* open/creat:                            File descriptors and low-level I/O.
                                                              (line  91)
* open/excl:                             File descriptors and low-level I/O.
                                                              (line  93)
* open/fsync:                            File descriptors and low-level I/O.
                                                              (line  98)
* open/noctty:                           File descriptors and low-level I/O.
                                                              (line  94)
* open/nonblock:                         File descriptors and low-level I/O.
                                                              (line  95)
* open/rdonly:                           File descriptors and low-level I/O.
                                                              (line  86)
* open/rdwr:                             File descriptors and low-level I/O.
                                                              (line  88)
* open/read:                             File descriptors and low-level I/O.
                                                              (line  89)
* open/sync:                             File descriptors and low-level I/O.
                                                              (line  97)
* open/text:                             File descriptors and low-level I/O.
                                                              (line 100)
* open/trunc:                            File descriptors and low-level I/O.
                                                              (line  96)
* open/write:                            File descriptors and low-level I/O.
                                                              (line  90)
* open/wronly:                           File descriptors and low-level I/O.
                                                              (line  87)
* ormap:                                 Other control structures.
                                                              (line  15)
* output-style-human:                    Output Generation API.
                                                              (line  18)
* parameterize:                          Other binding forms. (line  67)
* parent-process-id:                     Processes.           (line  12)
* patch:                                 Procedures and macros available in setup scripts.
                                                              (line  60)
* pathname-directory:                    Pathname operations. (line  31)
* pathname-directory-separator:          Files.               (line  19)
* pathname-extension:                    Pathname operations. (line  37)
* pathname-extension-separator:          Files.               (line  24)
* pathname-file:                         Pathname operations. (line  34)
* pathname-replace-directory:            Pathname operations. (line  43)
* pathname-replace-extension:            Pathname operations. (line  49)
* pathname-replace-file:                 Pathname operations. (line  46)
* pathname-strip-directory:              Pathname operations. (line  55)
* pathname-strip-extension:              Pathname operations. (line  58)
* pattern->regexp:                       Unit regex.          (line  29)
* perm/irgrp:                            Permissions.         (line  91)
* perm/iroth:                            Permissions.         (line  94)
* perm/irusr:                            Permissions.         (line  88)
* perm/irwxg:                            Permissions.         (line  98)
* perm/irwxo:                            Permissions.         (line  99)
* perm/irwxu:                            Permissions.         (line  97)
* perm/isgid:                            Permissions.         (line 102)
* perm/isuid:                            Permissions.         (line 101)
* perm/isvtx:                            Permissions.         (line 100)
* perm/iwgrp:                            Permissions.         (line  92)
* perm/iwoth:                            Permissions.         (line  95)
* perm/iwusr:                            Permissions.         (line  89)
* perm/ixgrp:                            Permissions.         (line  93)
* perm/ixoth:                            Permissions.         (line  96)
* perm/ixusr:                            Permissions.         (line  90)
* pipe/buf:                              Pipes.               (line  48)
* pointer->address:                      Foreign pointers.    (line  59)
* pointer->object:                       Foreign pointers.    (line  64)
* pointer-f32-ref:                       Foreign pointers.    (line 109)
* pointer-f32-set!:                      Foreign pointers.    (line 152)
* pointer-f64-ref:                       Foreign pointers.    (line 114)
* pointer-f64-set!:                      Foreign pointers.    (line 158)
* pointer-offset:                        Foreign pointers.    (line  69)
* pointer-s16-ref:                       Foreign pointers.    (line  91)
* pointer-s16-set!:                      Foreign pointers.    (line 135)
* pointer-s32-ref:                       Foreign pointers.    (line 103)
* pointer-s32-set!:                      Foreign pointers.    (line 147)
* pointer-s8-ref:                        Foreign pointers.    (line  80)
* pointer-s8-set!:                       Foreign pointers.    (line 124)
* pointer-tag:                           Tagged pointers.     (line  21)
* pointer-u16-ref:                       Foreign pointers.    (line  85)
* pointer-u16-set!:                      Foreign pointers.    (line 129)
* pointer-u32-ref:                       Foreign pointers.    (line  97)
* pointer-u32-set!:                      Foreign pointers.    (line 141)
* pointer-u8-ref:                        Foreign pointers.    (line  75)
* pointer-u8-set!:                       Foreign pointers.    (line 119)
* pointer=?:                             Foreign pointers.    (line  53)
* pointer?:                              Foreign pointers.    (line  48)
* port->fileno:                          File descriptors and low-level I/O.
                                                              (line 113)
* port-name:                             File Input/Output.   (line  24)
* port-position:                         File Input/Output.   (line  31)
* port?:                                 Standard Input/Output.
                                                              (line   7)
* post-process:                          Declarations.        (line 110)
* pp:                                    Input/Output extensions.
                                                              (line  33)
* pretty-print:                          Input/Output extensions.
                                                              (line  32)
* pretty-print-width:                    Input/Output extensions.
                                                              (line  40)
* print:                                 Standard Input/Output.
                                                              (line  12)
* print*:                                Standard Input/Output.
                                                              (line  19)
* print-backtrace:                       Interrupts and error-handling.
                                                              (line  40)
* print-error-message:                   Interrupts and error-handling.
                                                              (line  47)
* print-object:                          Additional protocol. (line  13)
* printf:                                Formatted output.    (line   8)
* printinl:                              Output Generation API.
                                                              (line  12)
* printnl:                               Output Generation API.
                                                              (line   7)
* procedure-data:                        Extending procedures with data.
                                                              (line  21)
* process:                               Processes.           (line  67)
* process-execute:                       Processes.           (line  17)
* process-fork:                          Processes.           (line  25)
* process-group-id:                      Permissions.         (line  55)
* process-run:                           Processes.           (line  33)
* process-signal:                        Processes.           (line  44)
* process-spawn:                         Windows specific notes.
                                                              (line  53)
* process-wait:                          Processes.           (line  51)
* project:                               Combinators.         (line  62)
* provide:                               Loading extension libraries.
                                                              (line  25)
* provided?:                             Loading extension libraries.
                                                              (line  31)
* put!:                                  Hash tables.         (line  73)
* queue->list:                           Queues.              (line  25)
* queue-add!:                            Queues.              (line  33)
* queue-empty?:                          Queues.              (line  38)
* queue-first:                           Queues.              (line  43)
* queue-last:                            Queues.              (line  49)
* queue-remove!:                         Queues.              (line  55)
* queue?:                                Queues.              (line  20)
* random:                                Random numbers.      (line   7)
* randomize:                             Random numbers.      (line  12)
* rassoc:                                Lists.               (line  27)
* read-all:                              Reading a file's contents.
                                                              (line   7)
* read-file:                             Input/Output extensions.
                                                              (line  45)
* read-line:                             Input/Output extensions.
                                                              (line  54)
* read-lines:                            Input/Output extensions.
                                                              (line  64)
* read-string:                           Input/Output extensions.
                                                              (line  70)
* read-symbolic-link:                    Symbolic links.      (line  13)
* read-token:                            Input/Output extensions.
                                                              (line  81)
* receive:                               Other binding forms. (line  75)
* record->vector:                        Low-level data access.
                                                              (line  80)
* record-instance?:                      Low-level data access.
                                                              (line  75)
* regexp:                                Unit regex.          (line  37)
* regexp?:                               Unit regex.          (line  54)
* register-feature!:                     Feature identifiers. (line  31)
* rename-file:                           Files.               (line  29)
* repl:                                  Read-eval-print loop.
                                                              (line   7)
* repl-prompt:                           Parameters.          (line  93)
* repository-path:                       Loading extension libraries.
                                                              (line  11)
* require:                               Loading extension libraries.
                                                              (line  37)
* require-at-runtime:                    Procedures and macros available in setup scripts.
                                                              (line  22)
* require-extension:                     Making extra libraries and extensions available.
                                                              (line   7)
* reset:                                 Interrupts and error-handling.
                                                              (line  56)
* reset-handler:                         Parameters.          (line  99)
* reverse-list->string:                  String utilities.    (line   7)
* run:                                   Procedures and macros available in setup scripts.
                                                              (line  47)
* run-time-macros:                       Declarations.        (line 127)
* s16vector->byte-vector:                Unit srfi-4.         (line  14)
* s32vector->byte-vector:                Unit srfi-4.         (line  16)
* s8vector->byte-vector:                 Unit srfi-4.         (line  12)
* seconds->local-time:                   Time routines.       (line   7)
* seconds->string:                       Time routines.       (line  36)
* seconds->utc-time:                     Time routines.       (line  42)
* set!-values:                           Other binding forms. (line  92)
* set-alarm!:                            Signal handling.     (line   7)
* set-buffering-mode!:                   Setting a files buffering mode.
                                                              (line   7)
* set-extension-specifier!:              Loading extension libraries.
                                                              (line  57)
* set-file-position!:                    Changing file attributes.
                                                              (line  14)
* set-finalizer!:                        Garbage collection.  (line  25)
* set-gc-report!:                        Garbage collection.  (line  34)
* set-group-id!:                         Permissions.         (line 111)
* set-groups!:                           Permissions.         (line  74)
* set-port-name!:                        File Input/Output.   (line  39)
* set-procedure-data!:                   Extending procedures with data.
                                                              (line  27)
* set-process-group-id!:                 Permissions.         (line 116)
* set-read-syntax!:                      Reader extensions.   (line  13)
* set-root-directory!:                   Directories.         (line  47)
* set-signal-handler!:                   Signal handling.     (line  14)
* set-signal-mask!:                      Signal handling.     (line  22)
* set-user-id!:                          Permissions.         (line 106)
* setenv:                                Environment access.  (line  15)
* shift!:                                Miscellaneous handy things.
                                                              (line   7)
* shuffle:                               Lists.               (line  81)
* side-effect:                           Side Effect API.     (line  13)
* signal/abrt:                           Signal handling.     (line  35)
* signal/alrm:                           Signal handling.     (line  38)
* signal/chld:                           Signal handling.     (line  43)
* signal/cont:                           Signal handling.     (line  44)
* signal/fpe:                            Signal handling.     (line  32)
* signal/hup:                            Signal handling.     (line  31)
* signal/ill:                            Signal handling.     (line  33)
* signal/int:                            Signal handling.     (line  30)
* signal/io:                             Signal handling.     (line  41)
* signal/kill:                           Signal handling.     (line  29)
* signal/pipe:                           Signal handling.     (line  47)
* signal/prof:                           Signal handling.     (line  40)
* signal/quit:                           Signal handling.     (line  37)
* signal/segv:                           Signal handling.     (line  34)
* signal/stop:                           Signal handling.     (line  45)
* signal/term:                           Signal handling.     (line  28)
* signal/trap:                           Signal handling.     (line  36)
* signal/tstp:                           Signal handling.     (line  46)
* signal/urg:                            Signal handling.     (line  42)
* signal/usr1:                           Signal handling.     (line  50)
* signal/usr2:                           Signal handling.     (line  51)
* signal/vtalrm:                         Signal handling.     (line  39)
* signal/winch:                          Signal handling.     (line  52)
* signal/xcpu:                           Signal handling.     (line  48)
* signal/xfsz:                           Signal handling.     (line  49)
* signum:                                Arithmetic.          (line 115)
* skip:                                  Skip API.            (line  11)
* skip-result-message-ref:               Skip API.            (line  32)
* skip-result-warning-ref:               Skip API.            (line  43)
* skip-result-warning?:                  Skip API.            (line  38)
* skip-result?:                          Skip API.            (line  26)
* sleep:                                 Processes.           (line  79)
* slot-ref:                              Base language.       (line  50)
* slot-set!:                             Base language.       (line  55)
* software-type:                         Environment information and system interface.
                                                              (line  73)
* software-version:                      Environment information and system interface.
                                                              (line  86)
* sort:                                  Sorting.             (line  17)
* sort!:                                 Sorting.             (line  18)
* sorted?:                               Sorting.             (line  25)
* spawn/detach:                          Windows specific notes.
                                                              (line  43)
* spawn/nowait:                          Windows specific notes.
                                                              (line  41)
* spawn/nowaito:                         Windows specific notes.
                                                              (line  42)
* spawn/overlay:                         Windows specific notes.
                                                              (line  39)
* spawn/wait:                            Windows specific notes.
                                                              (line  40)
* sprintf:                               Formatted output.    (line   9)
* standard-bindings:                     Declarations.        (line 133)
* static-byte-vector->pointer:           Bytevectors.         (line 146)
* strict-reader:                         Parameters.          (line 107)
* string->byte-vector:                   Bytevectors.         (line 152)
* string->keyword:                       Keywords.            (line  41)
* string->uninterned-symbol:             Generating uninterned symbols.
                                                              (line  13)
* string-chop:                           Strings.             (line  21)
* string-compare3:                       Strings.             (line  30)
* string-compare3-ci:                    Strings.             (line  33)
* string-intersperse:                    Strings.             (line  40)
* string-match:                          Unit regex.          (line  60)
* string-match-positions:                Unit regex.          (line  61)
* string-search:                         Unit regex.          (line  77)
* string-search-positions:               Unit regex.          (line  78)
* string-split:                          Strings.             (line  55)
* string-split-fields:                   Unit regex.          (line  85)
* string-substitute:                     Unit regex.          (line 107)
* string-substitute*:                    Unit regex.          (line 123)
* string-translate:                      Strings.             (line  67)
* string-translate*:                     Strings.             (line  77)
* sub1:                                  Arithmetic.          (line   8)
* subclass?:                             Introspection.       (line  55)
* subf32vector:                          Unit srfi-4.         (line  61)
* subf64vector:                          Unit srfi-4.         (line  62)
* subs16vector:                          Unit srfi-4.         (line  59)
* subs32vector:                          Unit srfi-4.         (line  60)
* subs8vector:                           Unit srfi-4.         (line  58)
* substring-ci=?:                        Strings.             (line  94)
* substring-index:                       Strings.             (line 104)
* substring-index-ci:                    Strings.             (line 105)
* substring=?:                           Strings.             (line  93)
* subu16vector:                          Unit srfi-4.         (line  56)
* subu32vector:                          Unit srfi-4.         (line  57)
* subu8vector:                           Unit srfi-4.         (line  55)
* switch:                                Conditional forms.   (line   7)
* syntax <1>:                            Procedures and macros available in setup scripts.
                                                              (line  16)
* syntax:                                Using the builtin parser.
                                                              (line  12)
* syntax-error:                          Macros.              (line  38)
* system:                                Environment information and system interface.
                                                              (line 118)
* system*:                               Executing shell commands with formatstring and error checking.
                                                              (line   7)
* system-information:                    Getting the hostname and system information.
                                                              (line  13)
* tag-pointer:                           Tagged pointers.     (line   9)
* tagged-pointer?:                       Tagged pointers.     (line  15)
* tail?:                                 Lists.               (line  92)
* tcp-abandon-port:                      Unit tcp.            (line  79)
* tcp-accept:                            Unit tcp.            (line  36)
* tcp-accept-ready?:                     Unit tcp.            (line  47)
* tcp-addresses:                         Unit tcp.            (line  70)
* tcp-close:                             Unit tcp.            (line  31)
* tcp-connect:                           Unit tcp.            (line  59)
* tcp-listen:                            Unit tcp.            (line  16)
* tcp-listener-port:                     Unit tcp.            (line  53)
* tcp-listener?:                         Unit tcp.            (line  26)
* terminal-name:                         Terminal ports.      (line   7)
* terminal-port?:                        Terminal ports.      (line  12)
* terminate:                             Termination API.     (line  22)
* terminate-result-container-ref:        Termination API.     (line  55)
* terminate-result-message-ref:          Termination API.     (line  61)
* terminate-result-result-ref:           Termination API.     (line  44)
* terminate-result-scope-ref:            Termination API.     (line  49)
* terminate-result?:                     Termination API.     (line  38)
* test-case:                             The Test Case Macro API.
                                                              (line  13)
* test-case-result-expectations-ref:     Test Case Result Object API.
                                                              (line  27)
* test-case-result-message-ref:          Test Case Result Object API.
                                                              (line  22)
* test-case-result-result-ref:           Test Case Result Object API.
                                                              (line  17)
* test-case-result-warning-ref:          Test Case Result Object API.
                                                              (line  37)
* test-case-result-warning?:             Test Case Result Object API.
                                                              (line  32)
* test-case-result?:                     Test Case Result Object API.
                                                              (line  11)
* test-feature?:                         Feature identifiers. (line  25)
* test-package:                          The Test Package Macro API.
                                                              (line  13)
* test-package-result-exps-ref:          Test Package Result Object API.
                                                              (line  27)
* test-package-result-message-ref:       Test Package Result Object API.
                                                              (line  22)
* test-package-result-result-ref:        Test Package Result Object API.
                                                              (line  17)
* test-package-result-warning-ref:       Test Package Result Object API.
                                                              (line  37)
* test-package-result-warning?:          Test Package Result Object API.
                                                              (line  32)
* test-package-result?:                  Test Package Result Object API.
                                                              (line  11)
* thread-deliver-signal!:                Unit srfi-18.        (line  52)
* thread-quantum:                        Unit srfi-18.        (line  59)
* thread-quantum-set!:                   Unit srfi-18.        (line  65)
* time:                                  Other forms.         (line  90)
* time->string:                          Time routines.       (line  48)
* todo:                                  Todo API.            (line  13)
* todo-result-message-ref:               Todo API.            (line  31)
* todo-result-warning-ref:               Todo API.            (line  41)
* todo-result-warning?:                  Todo API.            (line  36)
* todo-result?:                          Todo API.            (line  25)
* trace:                                 Macros and procedures implemented in the interpreter.
                                                              (line  74)
* TYPE:                                  Declarations.        (line 120)
* TYPENAME-SLOTNAME:                     Accessing external objects.
                                                              (line 109)
* TYPENAME-SLOTNAME-set!:                Accessing external objects.
                                                              (line 117)
* u16vector->byte-vector:                Unit srfi-4.         (line  13)
* u32vector->byte-vector:                Unit srfi-4.         (line  15)
* u8vector->byte-vector:                 Unit srfi-4.         (line  11)
* unadvise:                              Macros and procedures implemented in the interpreter.
                                                              (line  68)
* unbound-variable-value:                Procedure-call- and variable reference hooks.
                                                              (line  29)
* undefine-macro!:                       Macros.              (line  34)
* unit:                                  Declarations.        (line 156)
* unless:                                Conditional forms.   (line  13)
* unmap-file-from-memory:                Memory mapped I/O.   (line  34)
* unregister-feature!:                   Feature identifiers. (line  38)
* unsafe:                                Declarations.        (line 160)
* unsetenv:                              Environment access.  (line  22)
* unshift!:                              Miscellaneous handy things.
                                                              (line  17)
* untrace:                               Macros and procedures implemented in the interpreter.
                                                              (line  94)
* use:                                   Making extra libraries and extensions available.
                                                              (line   8)
* user-information:                      Permissions.         (line 121)
* user-options-pass:                     Extending the compiler.
                                                              (line  16)
* user-pass:                             Extending the compiler.
                                                              (line  38)
* user-pass-2:                           Extending the compiler.
                                                              (line  43)
* user-post-analysis-pass:               Extending the compiler.
                                                              (line  49)
* user-preprocessor-pass:                Extending the compiler.
                                                              (line  32)
* user-read-pass:                        Extending the compiler.
                                                              (line  24)
* uses:                                  Declarations.        (line 170)
* usual-integrations:                    Declarations.        (line 147)
* vector-copy!:                          Vectors.             (line   7)
* vector-resize:                         Vectors.             (line  17)
* version:                               Procedures and macros available in setup scripts.
                                                              (line  28)
* visit:                                 Unit syntax-case.    (line  70)
* void:                                  The unspecified value.
                                                              (line   7)
* when:                                  Conditional forms.   (line  19)
* with-error-output-to-port:             Input/Output extensions.
                                                              (line  88)
* with-input-from-pipe:                  Pipes.               (line  53)
* with-input-from-port:                  Input/Output extensions.
                                                              (line  94)
* with-input-from-string:                String-port extensions.
                                                              (line  19)
* with-output-to-pipe:                   Pipes.               (line  54)
* with-output-to-port:                   Input/Output extensions.
                                                              (line 100)
* with-output-to-string:                 String-port extensions.
                                                              (line  25)
* write-line:                            Input/Output extensions.
                                                              (line  55)
* write-string:                          Input/Output extensions.
                                                              (line  71)



Tag Table:
Node: Top3299
Node: Introduction8280
Node: Basic mode of operation10605
Node: Using the compiler12858
Node: Compiler command line format13742
Node: Runtime options27592
Node: An example30138
Node: Extending the compiler32589
Node: Distributing compiled C files36264
Node: Using the interpreter38379
Node: Interpreter command line format38804
Node: Writing Scheme scripts42554
Node: Toplevel commands44493
Node: Macros and procedures implemented in the interpreter45530
Node: Supported language48819
Node: Deviations from the standard49491
Node: Extensions to the standard54348
Node: Non standard read syntax58124
Node: Non-standard macros and special forms60826
Node: Making extra libraries and extensions available61279
Node: Binding forms for optional arguments64755
Node: Other binding forms67046
Node: Substitution forms and macros70328
Node: Conditional forms73341
Node: Record structures73963
Node: Other forms76065
Node: Declarations80054
Node: Parameters88160
Node: Unit library92351
Node: Arithmetic93076
Node: File Input/Output96101
Node: Files97355
Node: String ports98244
Node: Feature identifiers98783
Node: Keywords100455
Node: Exceptions101975
Node: Environment information and system interface105191
Node: Execution time108324
Node: Interrupts and error-handling109109
Node: Garbage collection111293
Node: Other control structures112953
Node: String utilities113755
Node: Generating uninterned symbols114176
Node: Standard Input/Output114730
Node: User-defined named characters115479
Node: Vectors116816
Node: The unspecified value117687
Node: call/cc117926
Node: Unit eval118150
Node: Loading code118563
Node: Read-eval-print loop121105
Node: Macros121582
Node: Loading extension libraries122923
Node: Reader extensions126434
Node: Eval127548
Node: Unit extras127867
Node: Lists128367
Node: String-port extensions131242
Node: Formatted output132280
Node: Hash tables133707
Node: Queues136075
Node: Sorting137649
Node: Random numbers138468
Node: Input/Output extensions138981
Node: Strings143112
Node: Combinators147059
Node: Binary searching149234
Node: Unit srfi-1149807
Node: Unit srfi-4150043
Node: Unit srfi-13152938
Node: Unit srfi-14153338
Node: Unit srfi-25153806
Node: Unit match154214
Node: Unit regex156473
Node: Unit syntax-case161546
Node: Unit srfi-18164556
Node: Unit format166922
Node: Unit posix168682
Node: Directories169721
Node: Pipes171253
Node: Fifos174482
Node: File descriptors and low-level I/O174950
Node: Retrieving file attributes179644
Node: Changing file attributes181060
Node: Processes181992
Node: Symbolic links185228
Node: Permissions185710
Node: Record locking190390
Node: Signal handling191657
Node: Environment access193466
Node: Memory mapped I/O194344
Node: Time routines196169
Node: Raw exit197841
Node: ERRNO values198266
Node: Finding files199087
Node: Getting the hostname and system information200482
Node: Setting a files buffering mode201072
Node: Terminal ports201633
Node: How Scheme procedures relate to UNIX C functions202110
Node: Windows specific notes204657
Node: Unit utils206809
Node: Pathname operations207359
Node: Temporary files209503
Node: Deleting a file without signalling an error210018
Node: Iterating over input lines and files210487
Node: Executing shell commands with formatstring and error checking211634
Node: Reading a file's contents212188
Node: Miscellaneous handy things212837
Node: Unit tcp213635
Node: Unit srfi-37216948
Node: Unit lolevel218219
Node: Foreign pointers218764
Node: Tagged pointers223255
Node: Extending procedures with data224126
Node: Bytevectors225449
Node: Data in unmanaged memory230742
Node: Locatives233363
Node: Accessing toplevel variables235498
Node: Low-level data access236192
Node: Procedure-call- and variable reference hooks239075
Node: Magic240524
Node: Unit tinyclos241407
Node: Defining forms241810
Node: Base language244274
Node: Introspection245982
Node: Intercessory protocol247627
Node: Additional protocol249864
Node: Utility procedures250487
Node: Builtin classes251148
Node: Interface to external functions and variables255062
Node: Accessing external objects255493
Node: Foreign type specifiers262000
Node: Entry points268587
Node: Callbacks281366
Node: Locations285093
Node: Other support procedures287110
Node: The Easy Foreign Function Interface287537
Node: #> ... <# Syntax290600
Node: General operation292322
Node: Pseudo declarations297661
Node: Grammar304857
Node: C notes309952
Node: C++ notes310471
Node: Using the builtin parser312140
Node: Specification grammar313718
Node: C interface316770
Node: chicken-setup325545
Node: Extension libraries325924
Node: Installing extensions326690
Node: Creating extensions328021
Node: Procedures and macros available in setup scripts328588
Node: Examples for extensions331412
Node: `chicken-setup' reference336116
Node: Windows notes338649
Node: Additional files339499
Node: chicken-highlevel-macros.scm339978
Node: chicken-more-macros.scm341502
Node: chicken-ffi-macros.scm342273
Node: chicken-entry-points.scm342646
Node: chicken-default-entry-points.scm343007
Node: test-infrastructure.scm343379
Node: The Test Package Macro API345101
Node: The Test Case Macro API347636
Node: The Expectation Macro API349973
Node: Result Object API359520
Node: Test Package Result Object API360151
Node: Test Case Result Object API361814
Node: Single Clause Style Expectation363449
Node: Equivalence Style Expectation366354
Node: Tolerance Style Expectation369691
Node: Various Helper API373056
Node: Termination API373494
Node: Destructor Object API376270
Node: Todo API379271
Node: Gloss API380931
Node: Skip API382519
Node: Side Effect API384276
Node: Miscellaneous API385166
Node: Analysis of the Result Tree386538
Node: Output Generation API387444
Node: Example Usages of the Test Suite Infrastructure388251
Node: Data Representation392227
Node: Bugs and limitations397499
Node: FAQ399626
Node: Acknowledgements424798
Node: Bibliography429270
Node: Index429637

End Tag Table
