File: chicken.texi

package info (click to toggle)
chicken 1.63-2
links: PTS
area: main
in suites: sarge
size: 27,072 kB
ctags: 39,156
sloc: ansic: 399,116; lisp: 50,264; sh: 8,206; makefile: 628
file content (12667 lines) | stat: -rw-r--r-- 372,262 bytes
\input texinfo @c -*-texinfo-*-
@setfilename chicken.info
@settitle CHICKEN - A practical and portable Scheme system. Version 1, Build 63

@ifnottex
@macro pointrightarrow
->
@end macro
@end ifnottex

@iftex
@macro pointrightarrow
@math{@rightarrow{}}
@end macro
@end iftex

@copying
@noindent
Copyright @copyright{} 2000-2004, Felix L. Winkelmann
All rights reserved.

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

@itemize
@item Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
@item 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.
@item 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.  
@end itemize

@
@

@noindent

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.

@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* CHICKEN: (chicken).          A pratical and portable Scheme system (Version 1, Build 63).
@end direntry

@titlepage
@title CHICKEN
@subtitle A practical and portable Scheme system
@subtitle User's Manual
@subtitle Version 1 Build 43
@author Felix L. Winkelmann
@end titlepage

@insertcopying
@contents

@syncodeindex vr fn


@ifnottex
@node Top
@top CHICKEN

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

(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::        
* Acknowledgements::            
* Bibliography::                
* Index::                       

@detailmenu
 --- 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::  

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 @emph{Easy} Foreign Function Interface

* #> ... <# Syntax::            
* General operation::           
* Pseudo declarations::         
* Grammar::                     
* C notes::                     
* C++ notes::                   

chicken-setup

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

Additional files

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

@code{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::  

@end detailmenu
@end menu

@end ifnottex

@node Introduction
@chapter 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 @cite{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, @code{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:
@itemize
@item SRFIs 0, 1, 2, 4, 6, 7, 8, 9, 10, 13, 14, 16, 18, 22, 23, 25, 28, 30, 37
 and 39.
@item @code{syntax-case} highlevel macros
@item Lightweight threads based on first-class continuations
@item Pattern matching with Andrew Wright's @code{match} package
@item Record structures
@item An object system with multiple inheritance, multimethods and a
                meta-object protocol
@item Extended comment- and string-literal syntaxes
@item Libraries for regular expressions, string handling, Common LISP
                style @code{format},
UNIX system calls and extended data structures
@item Create interpreted or compiled shell scripts written in Scheme
                for UNIX or Windows
@item Compiled C files can be easily distributed
@item Allows the creation of fully self-contained statically linked executables
@item On systems that support it, compiled code can be loaded dynamically
@end itemize

@node Basic mode of operation
@chapter 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 @emph{unit}s.  A unit is a single
compiled object module that contains a number of toplevel expressions that
are executed either when the unit is the @emph{main} unit or if the
unit is @emph{used}.  To use a unit, the unit has to be @emph{declare}ed
as used, like this:

@verbatim
(declare (uses UNITNAME))
@end verbatim

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

@verbatim
(declare (unit UNITNAME))
@end verbatim

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
@code{@b{unit}} declaration.

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

@verbatim
(include "FILENAME")
@end verbatim

One important thing: macro definitions are only available when processed
by @code{include} or @code{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 @code{@b{define-macro}} in @ref{Substitution forms and macros}).

On platforms that support dynamic loading of compiled code (like Windows and most ELF based
systems like Linux or BSD), it is not necessary to use unit declarations. Here
code can be compiled into a shared object (@code{.so}) and loaded dynamically into
a running application.


@node Using the compiler
@chapter Using the compiler

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

@verbatim
chicken-config -help
@end verbatim

on the command line for a list of available options.  On most UNIX
systems, a Scheme script named @code{csc} provides a much simpler
interface to the Scheme- and C-compilers and linker. Enter

@verbatim
csc -help
@end verbatim

on the command line for more information.  A batch-file (@code{csc.bat})
with the same functionality is also available for Windows platforms. The Windows
version of csc (@code{csc.bat}) does not accept more than 8 arguments.

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

@node Compiler command line format
@section Command line format 

@code{chicken FILENAME @{OPTION@}}

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

@table @code

@item -analyze-only

Stop compilation after first analysis pass.

@item -benchmark-mode

Equivalent to @code{-debug-level 0 -optimize-level 3}
@code{-fixnum-arithmetic -disable-interrupts -block -lambda-lift}.

@item -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
@code{eval} and unused toplevel bindings are removed.

@item -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 @code{case-insensitive}
feature identifier.

@item -check-syntax

Aborts compilation process after macro-expansion and syntax checks.

@item -compress-literals THRESHOLD

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

@item -debug MODES

Enables one or more compiler debugging modes. @code{MODES} is a string
of characters that select debugging information about the compiler that
will be printed to standard output.

@table @kbd
@item t
show time needed for compilation
@item b
show breakdown of time needed for each compiler pass
@item o
show performed optimizations
@item r
show invocation parameters
@item s
show program-size information and other statistics
@item a
show node-matching during simplification
@item p
show execution of compiler sub-passes
@item l
show lambda-lifting information
@item m
show GC statistics during compilation
@item n
print the line-number database 
@item c
print every expression before macro-expansion
@item e
lists all exported toplevel bindings
@item x
display information about experimental features
@item D
when printing nodes, use node-tree output
@item N
show the real-name mapping table
@item U
show expressions after the secondary user pass
@item 0
show database before lambda-lifting pass
@item L
show expressions after lambda-lifting
@item F
show output of ``easy'' FFI parser
@item P
show execution of outer partitioning
@item Q
show execution of middle partitioning
@item R
show execution of inner partitioning
@item 1
show source expressions
@item 2
show canonicalized expressions
@item 3
show expressions converted into CPS
@item 4
show database after each analysis pass
@item 5
show expressions after each optimization pass
@item 6
show expressions after each inlining pass
@item 7
show expressions after complete optimization
@item 8
show database after final analysis
@item 9
show expressions after closure conversion
@end table


@item -debug-level LEVEL

Selects amount of debug-information. @code{LEVEL} should be an integer.


@itemize
@item @code{-debug-level 0} is equivalent to @code{-no-trace}.
@item @code{-debug-level 1} does nothing.
@end itemize

@item -disable-c-syntax-checks

Disable basic syntax checking of embedded C code fragments.

@item -disable-interrupts

Equivalent to the @code{(disable-interrupts)} declaration. No
interrupt-checks are generated for compiled programs.

@item -disable-stack-overflow-checks

Disables detection of stack overflows. This is equivalent to running the compiled
executable with the @code{-:o} runtime option.

@item -dynamic

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

@item -epilogue FILENAME
 Includes the file named
@code{FILENAME} at the end of the compiled source file. The include-path
is not searched. This option may be given multiple times.

@item -explicit-use

Disables automatic use of the units @code{library, eval} and @code{extras}.
Use this option if compiling a library unit instead of an application
unit.

@item -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.

@item -feature SYMBOL

Registers @code{SYMBOL} to be a valid feature identifier for
@code{cond-expand}.

@item -ffi

Compile C/C++ code and generate Scheme bindings. This is effectively
equivalent to wrapping the code in @code{#>! ... <#}.

@item -ffi-define SYMBOL

Defines a macro that will be accessible in @code{foreign-parse}
declarations.

@item -ffi-include-path PATH

Set include path for ``easy'' FFI parser.

@item -fixnum-arithmetic

Equivalent to @code{(fixnum-arithmetic)} declaration. Assume all
mathematical operations use small integer arguments.

@item -heap-size NUMBER

Sets a fixed heap size of the generated executable to @code{NUMBER}
bytes. The parameter may be followed by a 
@code{M} (@code{m}) or @code{K} (@code{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.

@item -heap-initial-size NUMBER

Sets the size that the heap of the compiled application should have at
startup time.

@item -heap-growth PERCENTAGE

Sets the heap-growth rate for the compiled program at compile time
(see: @code{-:hg}).

@item -heap-shrinkage PERCENTAGE

Sets the heap-shrinkage rate for the compiled program at compile time
(see: @code{-:hs}).

@item -help

Print a summary of available options and the format of the command line
parameters and exit the compiler.

@item -syntax

@item -hygienic

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

@item -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 (@code{cond-expand}). To load all further macros, execute:

@verbatim
(require-extension chicken-more-macros)
@end verbatim

@item -include-path PATHNAME

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

@item -keyword-style STYLE

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

@item -lambda-lift

Enable the optimization known as lambda-lifting.

@item -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 @code{-no-trace}
is specified. With this option the generated
code is slightly faster.

@item -no-feature SYMBOL

Unregisters feature identifier @code{SYMBOL}.

@item -no-warnings

Disable generation of compiler warnings.

@item -nursery NUMBER -stack-size NUMBER

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

@item -optimize-leaf-routines

Enable leaf routine optimization.

@item -optimize-level LEVEL

Enables certain sets of optimization options. @code{LEVEL} should be
an integer.


@itemize
@item @code{-optimize-level 0} does nothing.
@item @code{-optimize-level 1} is equivalent to
      @code{-optimize-leaf-routines}
@item @code{-optimize-level 2} is equivalent to
      @code{-optimize-leaf-routines -usual-integrations}
@item @code{-optimize-level 3} is equivalent to
      @code{-optimize-leaf-routines -usual-integrations -unsafe}
@end itemize

@item -output-file FILENAME

Specifies the pathname of the generated C file. Default is @code{FILENAME.c}.

@item -postlude EXPRESSIONS

Add @code{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 @code{-epilogue}.

@item -prelude EXPRESSIONS

Add @code{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 @code{-prologue}.

@item -profile

Instruments the source code to count procedure calls and execution
times. After the program terminates (either via an explicit @code{exit}
or implicitly), profiling statistics are written to a file named
@code{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 @code{chicken-format-profile} program to display the profiling
information in a more user-friendly form. Enter @code{chicken-format-profile}
with no arguments at the command line to get a list of available options.

@item -prologue FILENAME

Includes the file named @code{FILENAME} at the start of the compiled
source file.  The include-path is not searched. This option may be given
multiple times.

@item -quiet

Disables output of compile information.

@item -require-for-syntax NAME

Loads the extension @code{NAME} before the compilation process
commences.

@item -r5rs

Equivalent to @code{-hygienic -strict}.

@item -run-time-macros

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

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

@item -split-level NUMBER
Specifies how hard the partitioning algorithm should work:

@itemize
@item 0 Exit after first iteration (quickest)
@item 1 Exit when cost does not decrease by at least one-half (the default)
@item 2 Exit when cost does not change 
@end itemize

@item -strict

Disable non-standard macros. This option registers the @code{strict}
feature identifier. Implies @code{-strict-letrec} and @code{-strict-reader}.

@item -strict-srfi-0

Disable non-standard macros except @code{cond-expand}.  This option
registers the @code{strict} feature identifier. Implies @code{-strict-letrec}
and @code{-strict-reader}.

@item -strict-reader

Disables non-standard read syntax. Implies @code{-case-insensitive}.

@item -strict-letrec

Enable fully R5RS compliant @code{letrec}. This generates slightly less
efficient code but preserves standard semantics.

@item -to-stdout

Write compiled code to standard output instead of creating a @code{.c} file.

@item -unit NAME

Compile this file as a library unit. Equivalent to 

@verbatim
-prelude "(declare (unit NAME))"
@end verbatim

@item -unsafe

Disable runtime safety checks.

@item -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.

@item -uses NAME

Use definitions from the library unit @code{NAME}. This is equivalent to

@verbatim
-prelude "(declare (uses NAME))"
@end verbatim

@item -usual-integrations

Specifies that standard procedures and certain internal procedures are
never redefined, and can be inlined. This is equivalent to declaring
@code{(usual-integrations)}.

@item -version

Prints the version and some copyright information and exit the compiler.

@item -verbose

Prints progress information to standard output during compilation.

@end table

The environment variable @code{CHICKEN_OPTIONS} can be set to a string
with default command-line options for the compiler.

@node Runtime options
@section 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:

@table @code
@item -:?

Shows a list of the available runtime options and exits the program.

@item -:c

Forces console mode. Currently this is only used in the interpreter
(@code{csi}) to force output of the @b{#;>} prompt even if stdin
is not a terminal (for example if running in an @code{emacs} buffer
under Windows).

@item -:d

Prints some debug-information during startup.

@item -:hNUMBER

Specifies fixed heap size

@item -:hiNUMBER

Specifies the initial heap size

@item -:hgPERCENTAGE

Sets the growth rate of the heap in percent. If the heap is exhausted,
then it will grow by @code{PERCENTAGE}.
The default is 200.

@item -:hmNUMBER

Specifies a maximal heap size. The default is (2GB - 15).

@item -:hsPERCENTAGE

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

@item -:o

Disables detection of stack overflows at run-time

@item -:sNUMBER

Specifies stack size

@item -:tNUMBER

Specifies symbol table size

@item -:w

Enables garbage collection of unused symbols. By default unused and
unbound symbols are not garbage collected.

@item -:r

Writes trace output to stdout. This option has no effect with
in files compiled with the @code{-no-trace} or @code{-debug-level 0}
options.

@end table

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


@node An example
@section An example

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

@itemize

@item Consider this Scheme source file, named @code{foo.scm}
@verbatim
  ;;; foo.scm

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

  (write (fac 10))
  (newline)
@end verbatim

@item Compile the file @code{foo.scm}
@verbatim
% chicken foo.scm
@end verbatim

@item Compile the generated C file @code{foo.c}
@verbatim
% gcc foo.c -o foo `chicken-config -cflags -libs`
@end verbatim

@item Start the compiled program
@verbatim
% foo
@end verbatim
@verbatim
3628800
@end verbatim

@end itemize


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: 

@itemize

@item Consider these two Scheme source files, named @code{foo.scm}
and @code{bar.scm}

@verbatim
  ;;; 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))) ) )
@end verbatim

@item Compile the files @code{foo.scm} and @code{bar.scm}
@verbatim
% chicken foo.scm
% chicken bar.scm
@end verbatim

@item Compile the generated C files @code{foo.c} and @code{bar.c}
@verbatim
% gcc -c foo.c `chicken-config -cflags`
% gcc -c bar.c `chicken-config -cflags`
@end verbatim

@item Link the object files @code{foo.o} and @code{bar.o}
@verbatim
% gcc foo.o bar.o -o foo `chicken-config -libs`
@end verbatim

@item Start the compiled program
@verbatim
% foo
3628800

@end verbatim

@end itemize


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 @code{foo.scm} is the main module, because it doesn't have a
@code{unit} declaration.


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


@node Extending the compiler
@section 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 @code{-extend} option are loaded
and evaluated.  The parameters @code{user-options-pass, user-read-pass,
user-preprocessor-pass, user-pass, user-pass-2} and @code{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: @ref{Parameters}.



@defvr {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 @code{-}
(hyphen) removed and are converted to symbols.  Note that this parameter
is invoked @b{before} processing of the @code{-extend} option,
and so can only be changed in compiled user passes.
@end defvr

@defvr {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 @code{-prelude}
options. The second argument is a list of source files including any files
specified by @code{-prologue} and @code{-epilogue}. The third argument
is a list of strings specified using @code{-postlude} options. The
procedure should return a list of toplevel Scheme expressions.
@end defvr

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

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

@defvr {parameter} user-pass-2
Holds a procedure of three arguments, which is called with the canonicalized
node-graph and the analysis database accessors as arguments (see below for an
explanation of the accessor arguments). The result is ignored,
so this pass has to mutate the node-structure to cause any effect.
@end defvr

@defvr {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 @code{#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.
@end defvr



Loaded code (via the @code{-extend} option) has access to the library
units @code{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 @code{user-preprocessor-pass} but by @code{user-pass}.


@node Distributing compiled C files
@section 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 (@code{runtime.c} and @code{chicken.h}), plus
the file @code{chicken-config.h}, which is generated by the build process. All
other modules of the runtime system and the extension libraries are just
compiled Scheme code. For more information, study the CHICKEN source code
and/or get in contact with the author.


@node Using the interpreter
@chapter Using the interpreter


CHICKEN provides an interpreter named @code{csi} for evaluating Scheme programs
and expressions.

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

@node Interpreter  command line format
@section Command line format

@verbatim
  csi {FILENAME|OPTION}
@end verbatim

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

@table @code

@item --

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

@item -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 @code{case-insensitive}
feature identifier.

@item -batch

Quit the interpreter after processing all command line options.

@item -eval EXPRESSIONS

Evaluate @code{EXPRESSIONS}.

@item -feature SYMBOL

Registers @code{SYMBOL} to be a valid feature identifier for
@code{cond-expand}.

@item -help

Write a summary of the available command line options to standard output
and exit.

@item -syntax

@item -hygienic

Load @b{syntax-case} macro package and enable high-level macros in
interpreted code.  This option registers the @code{hygienic-macros}
feature identifier.

@item -include-path PATHNAME

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

@item -keyword-style STYLE

Enables alternative keyword syntax, where @code{STYLE} may be either
@code{prefix} (as in Common Lisp) or @code{suffix} (as in DSSSL).
Any other value is ignored.

@item -no-feature SYMBOL

Unregisters feature identifier @code{SYMBOL}.

@item -no-init

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

@item -no-warnings

Disables any warnings that might be issued by the reader or evaluated code.

@item -quiet

Do not print a startup message.

@item -r5rs

Equivalent to @code{-hygienic -strict}.

@item -script PATHNAME

This is equivalent to @code{-batch -quiet -no-init
PATHNAME}. Arguments following @code{PATHNAME} are available by using
@code{command-line-arguments} and are not processed as interpreter
options.

@item -script-meta PATHNAME

This is similar to the @code{-script} option, but the file specified
by @code{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.

@item -strict

Disable non-standard macros. Implies @code{-strict-letrec} and @code{-strict-reader}.

@item -strict-srfi-0

Disable non-standard macros except @code{cond-expand}. Implies @code{-strict-letrec}
and @code{-strict-reader}.

@item -strict-reader

Disables non-standard read syntax. Implies @code{-case-insensitive}.

@item -strict-letrec

Enable fully R5RS compliant @code{letrec}. This generates slightly less
efficient code but preserves standard semantics.

@item -version

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

@end table

@node Writing Scheme scripts
@section Writing Scheme scripts

@itemize
@item Since UNIX shells use the @code{#!} notation for starting scripts,
the interpreter ignores the first line of a source file, if prefixed by @code{#!}.

The easiest way is to use the @code{-script} option like this:

@verbatim
% 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
@end verbatim

The parameter @code{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 @b{not} parse the extra arguments passed
to a script via the @code{-script-meta} option!

To overcome a limitation of UNIX that allows only a single argument to
scripts, the @code{-script-meta} options is provided:


@verbatim
% 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"
@end verbatim

@item CHICKEN implements SRFI-22 but provides no driver programs
(@code{scheme-r4rs, scheme-ieee-1178-1990, scheme-r5rs} and
@code{scheme-srfi-0}).  Scheme scripts can be
compiled, the compiler determines language dialect from the invocation
line:

@verbatim
% cat bar
#! /usr/bin/env scheme-r5rs
(define (main args)
  (write (list->string (reverse (string->list (cadr args)))))
  (newline)
  0)

% csi -script bar "one two three"
"eerht owt eno"
% chicken bar -quiet
% gcc bar.c `chicken-config -cflags -libs` -o cbar
% cbar "one two three"}
"eerht owt eno"
@end verbatim 

For more information, see the @uref{http://srfi.schemers.org/srfi-22/srfi-22.html, SRFI-22 document }

@item 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:

@verbatim
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
@end verbatim

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

@end itemize

@node Toplevel commands
@section Toplevel commands

The toplevel loop understands a number of special commands:

@table @code
@item ,?

Show summary of available toplevel commands.

@item ,NUM

Evaluate @code{NUM}th command in history-list

@item ,h

List history of last commands

@item ,l FILENAME

Load file with given @code{FILENAME} (may be a symbol or string).

@item ,ln FILENAME

Load file and print result(s) of each top-level expression.

@item ,p EXP

Pretty-print evaluated expression @code{EXP}.

@item ,d EXP

Describe result of evaluated expression @code{EXP}.

@item ,du EXP

Dump contents of the result of evaluated expression @code{EXP}.

@item ,dur EXP N

Dump @code{N} bytes of the result of evaluated expression @code{EXP}.

@item ,q

Quit the interpreter.

@item ,r

Show system information.

@item ,s STRING-OR-SYMBOL

Execute shell-command.

@item ,t EXP

Evaluate form and print elapsed time.

@item ,x EXP

Pretty-print macroexpanded expression @code{EXP} (the expression is
not evaluated).

@end table

@node Macros and procedures implemented in the interpreter
@section Macros and procedures implemented in the interpreter

Additional macros and procedures available in the interpreter are:



@deffn {syntax} advise
@lisp
(advise NAME MODE PROC)
@end lisp
Modifies the behavior of the procedures named @code{NAME}, according
to @code{MODE}:

@table @code
@item before

Call the procedure @code{PROC} before every invocation of @code{NAME},
with the same arguments.

@item after

Call the procedure @code{PROC} with the result value(s) of @code{NAME}.

@item around

Call the procedure @code{PROC} with the arguments passed to
@code{NAME}.  Additionally the (original) value of @code{NAME}
is passed as the first argument to @code{PROC}.

@end table

Only the @code{PROC} argument is evaluated. Note that multiple pieces
of advice on the same procedure are allowed.

@verbatim
#;> (define (fac n)
      (if (zero? n) 1 (* n (fac (sub1 n)))))
#;> (define count 0)
#;> (advise fac before (lambda _ (set! count (add1 count))))
#;> (fac 10)                           ==> 3628800
#;> count                              ==> 11
#;> (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))))
#;> (fac 3)
fac: 3
 fac: 2
  fac: 1
   fac: 0
   -> 1
  -> 1
 -> 2
-> 6                                   ==> 6
#;> count                              ==> 15
#;> (set! count 0)
#;> (unadvise fac)
#;> (fac 10)                           ==> 3628800
#;> count                              ==> 0
@end verbatim

@end deffn
@deffn {syntax} unadvise
@lisp
(unadvise NAME ...)
@end lisp
Removes all pieces of advice from the procedures @code{NAME ...}
and restores their original behavior.

@end deffn
@deffn {syntax} trace
@lisp
(trace NAME ...)
@end lisp
Switches tracing on for the procedures with the given names.

@verbatim
#;> (fac 10)                       ==> 3628800
#;> (trace fac)
#;> (fac 3)
|(fac 3)
| (fac 2)
|  (fac 1)
|   (fac 0)
|   fac -> 1 
|  fac -> 1 
| fac -> 2 
|fac -> 6                          ==> 6
#;> (untrace fac)
#;> (fac 3)                        ==> 6
@end verbatim

@end deffn
@deffn {syntax} untrace
@lisp
(untrace NAME ...)
@end lisp
Switches tracing of the given procedures off.
@end deffn

@deffn {procedure} $
@lisp
($ [INDEX])
@end lisp
Returns entry number @code{INDEX} in the history list.
@end deffn

@deffn {procedure} &
@lisp
(& [INDEX])
@end lisp
Returns result(s) of entry number @code{INDEX} in the history list.
@end deffn


@node Supported language
@chapter 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::               
@end menu

@node Deviations from the standard
@section 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:

@verbatim
<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>
@end verbatim

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

@enumerate
@item Variables in required-formal-arguments are bound to successive actual arguments starting with the first actual argument. It shall be an error if there are fewer actual arguments than required-formal-arguments.

@item Next, variables in optional-formal-arguments are bound to any remaining actual arguments. If there are fewer remaining actual arguments than optional-formal-arguments, then variables are bound to the result of the evaluation of initializer, if one was specified, and otherwise to @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound.
@item If there is a rest-formal-argument, then it is bound to a list of all remaining actual arguments. The remaining actual arguments are also eligible to be bound to keyword-formal-arguments. If there is no rest-formal-argument and there are no keyword-formal-arguments, the it shall be an error if there are any remaining actual arguments.
@item If @code{#!key} was specified in the formal-argument-list, there shall be an even number of remaining actual arguments. These are interpreted as a series of pairs, where the first member of each pair is a keyword specifying the argument name, and the second is the corresponding value. It shall be an error if the first member of a pair is not a keyword. It shall be an error if the argument name is not the same as a variable in a keyword-formal-argument, unless there is a rest-formal-argument. If the same argument name occurs more than once in the list of actual arguments, then the first value is used. If there is no actual argument for a particular keyword-formal-argument, then the variable is bound to the result of evaluating initializer if one was specified, and otherwise @code{#f}. The initializer is evaluated in an environment in which all previous formal arguments have been bound. 
@end enumerate

It shall be an error for an @code{<ident>} to appear more than once in a formal-argument-list.

Example:

@verbatim
((lambda (x y) 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)
@end verbatim

[4.1.6] @code{set!} for unbound toplevel variables is allowed.

[5.2] @code{define} with a single argument is allowed and initializes the toplevel or local binding
to an unspecified value.

[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 @code{complex?}, @code{real?}
and @code{rational?} are identical to the standard procedure
@code{number?}. The procedures @code{numerator}, @code{denominator}
and @code{rationalize} are not implemented.  Also not implemented are
all procedures related to complex numbers.

[6.2.6] The procedure @code{string->number} does not obey read/write
invariance on inexact numbers.

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

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

[6.6.3] The procedures @code{write} and @code{display} do not obey
read/write invariance to inexact numbers.

@node Extensions to the standard
@section Extensions to the standard

[2.1] Identifiers may contain special characters if delimited with
@code{| ... |}.

[2.3] The brackets @code{[ ... ]} are provided as an alternative syntax
for @code{( ... )}.  A number of reader extensions is provided. See
@ref{Non standard read syntax}.

[4] Numerous non-standard macros are provided. See @ref{Non-standard
macros and special forms} for more information.

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

@verbatim
(letrec ([foo 123]
         [bar foo] )
  bar)
@end verbatim

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

[4.2.3] @code{(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 @code{letrec} form enclosing all following expressions
in the body:

@verbatim
(let ([foo 123])
  (bar)
  (define foo 456)
  (baz foo) )
@end verbatim

expands into

@verbatim
(let ([foo 123])
  (bar)
  (letrec ([foo 456])
    (baz foo) ) )
@end verbatim

This extension to the standard semantics is not available in combination with
the hygienic (@code{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
@code{char-name} in @ref{User-defined named characters}.

[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 @code{XX} in hex.

The third argument to @code{substring} is optional and defaults to the length
of the string.

[6.4] @code{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 @code{dynamic-wind} form and
execute in the outer dynamic context of the @code{dynamic-wind} form.

[6.5] The second argument to @code{eval} is optional and
defaults to the value of @code{(interaction-environment)}.
@code{scheme-report-environment} and @code{null-environment} accept
an optional 2nd parameter: if not @code{#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 @code{current-input-port} and
@code{current-output-port} are called with an argument (which should
be a port), then that argument is selected as the new current input- and
output-port, respectively.  The procedures @code{open-input-file},
@code{open-output-file}, @code{with-input-from-file},
@code{with-output-to-file}, @code{call-with-input-file} and
@code{call-with-output-file} accept an optional second (or third)
argument which should be one or more keywords, if supplied. These
arguments specify the mode in which the file is opened. Possible
values are the keywords @code{#:text}, @code{#:binary} or
@code{#:append}.

@node Non standard read syntax
@section Non standard read syntax 



@deffn {read syntax} {#| @dots{} |#}
A multiline ``block'' comment. May be nested. Implements @uref{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30
})
@end deffn

@deffn {read syntax} {#;EXPRESSION}
Treats @code{EXPRESSION} as a comment.
@end deffn

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

@deffn {read syntax} {#'EXPRESSION}
An abbreviation for @code{(syntax EXPRESSION)}.
@end deffn

@deffn {read syntax} {#$EXPRESSION}
An abbreviation for @code{(location EXPRESSION)}.
@end deffn

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

@deffn {read syntax} {#<<TAG}
Specifies a multiline string constant. Anything up to a line equal to
@code{TAG} will be returned as a single string:

@ifhtml
@html
<pre>
(define msg #&lt;&lt;END
"Hello, world!", she said.
END
)
</pre>
@end html
@end ifhtml
@ifnothtml
@verbatim
(define msg #<<END
"Hello, world!", she said.
END
)
@end verbatim
@end ifnothtml

is equivalent to

@verbatim
(define msg "\"Hello, world!\", she said.")
@end verbatim
@end deffn

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

@verbatim
(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
)
@end verbatim

prints

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

@deffn {read syntax} #> ... <#
Abbreviation for @code{(declare (foreign-declare " ... "))}.
@end deffn

@deffn {read syntax} #>? ... <#
Abbreviation for @code{(declare (foreign-parse " ... "))}.
@end deffn

@deffn {read syntax} #>! ... <#
Abbreviation for

@verbatim
(declare
  (foreign-declare " ... ")
  (foreign-parse " ... ") )
@end verbatim
@end deffn

@deffn {read syntax} #%...
Reads like a normal symbol.
@end deffn

@deffn {read syntax} #!...
If occurring in the first line of an interpreted or compiled source file, then the @code{#!}
and everything following it are ignored. If occurring anywhere else, reads as a normal symbol.
The special (self-evaluating) symbol @code{#!eof} is read as the end-of-file object.
@end deffn




@node Non-standard macros and special forms
@section Non-standard macros and special forms 

@menu
* Making extra libraries and extensionsd available::
* Binding forms for optional arguments::  
* Other binding forms::         
* Substitution forms and macros::  
* Conditional forms::           
* Record structures::           
* Other forms::                 
@end menu


@node Making extra libraries and extensionsd available
@subsection Making extra libraries and extensionsd available


@deffn {syntax} require-extension
@deffnx {syntax} use
@lisp
(require-extension ID ...)
(use ID ...)
@end lisp
This form does all necessary steps to make the libraries or extensions given
in @code{ID ...} available. It loads syntactic extension, if needed and generates
code for loading/linking with core library modules or separately installed
extensions. @code{use} is just a shorter alias for @code{require-extension}.

During interpretation/evaluation @code{require-extension} performs one of the
following:

@itemize
@item If @code{ID} names a built in features @code{chicken srfi-22 srfi-23 srfi-30 srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10 
srfi-9}, then nothing is done.
@item If @code{ID} names one of syntactic extensions @code{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.
@item If @code{ID} names one of the core library units shipped with CHICKEN, then a @code{(load-library 'ID)} will be performed.
If one of those libraries define specific syntax (@code{match srfi-13}), then the required source file defining the syntax
will be loaded.
@item If @code{ID} names an installed extension with the @code{syntax} or @code{require-at-runtime} attribute, then
the equivalent of @code{(require-for-syntax 'ID)} is performed.
@item Otherwise @code{(require-extension ID)} is equivalent to @code{(require 'ID)}.
@end itemize

During compilation one of the following happens instead:

@itemize
@item If @code{ID} names a built in features @code{chicken srfi-22 srfi-23 srfi-30 srfi-39 srfi-8 srfi-6 srfi-2 srfi-0 srfi-10 
 srfi-9}, then nothing is done.
@item If @code{ID} names one of syntactic extensions @code{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.
@item If @code{ID} names one of the core library units shipped with CHICKEN, then a @code{(declare (uses ID))} is generated.
 If one of those libraries define specific syntax (@code{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.
@item If @code{ID} names an installed extension with the @code{syntax} or @code{require-at-runtime} attribute, then
 the equivalent of @code{(require-for-syntax 'ID)} is performed.
@item Otherwise @code{(require-extension ID)} is equivalent to @code{(require 'ID)}.
@end itemize

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

@end deffn


@node Binding forms for optional arguments
@subsection Binding forms for optional arguments



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

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

@end deffn
@deffn {syntax} case-lambda
@lisp
(case-lambda (LAMBDA-LIST1 EXP1 ...) ...)
@end lisp
SRFI-16. Expands into a lambda that invokes the body following the first
matching lambda-list.

@verbatim
(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
@end verbatim

For more information see the documentation for
@uref{http://srfi.schemers.org/srfi-16/srfi-16.html, SRFI-16 }

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

@verbatim
(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)
@end verbatim
@end deffn



@node Other binding forms
@subsection Other binding forms



@deffn {syntax} and-let*
@lisp
(and-let* (BINDING ...) EXP1 EXP2 ...)
@end lisp
SRFI-2. Bind sequentially and execute body. @code{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 @code{#f}, the @code{and-let*} form
evaluates to @code{#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 @code{and-let*} form. See also the documentation for
@uref{http://srfi.schemers.org/srfi-2/srfi-2.html, SRFI-2 }.

@end deffn
@deffn {syntax} cut
@deffnx {syntax} cute
@lisp
(cut SLOT ...)
(cute SLOT ...)
@end lisp
@uref{http://srfi.schemers.org/srfi-26/srfi-26.html, Syntactic sugar for specializing parameters.}

@end deffn
@deffn {syntax} define-values
@lisp
(define-values (NAME ...) EXP)
@end lisp
Defines several variables at once, with the result values of expression
@code{EXP}.

@end deffn
@deffn {syntax} fluid-let
@lisp
(fluid-let ((VAR1 X1) ...) BODY ...)
@end lisp
Binds the variables @code{VAR1 ...} dynamically to the values @code{X1 ...} 
during execution of @code{BODY ...}.

@end deffn
@deffn {syntax} let-values
@lisp
(let-values (((NAME ...) EXP) ...) BODY ...)
@end lisp
Binds multiple variables to the result values of @code{EXP ...}.
All variables are bound simultaneously.

@end deffn
@deffn {syntax} let*-values
@lisp
(let*-values (((NAME ...) EXP) ...) BODY ...)
@end lisp
Binds multiple variables to the result values of @code{EXP ...}.
The variables are bound sequentially.
@verbatim
(let*-values (((a b) (values 2 3))
              ((p) (+ a b)) )
  p)                               ==> 5
@end verbatim

@end deffn
@deffn {syntax} letrec-values
@lisp
(letrec-values (((NAME ...) EXP) ...) BODY ...)
@end lisp
Binds the result values of @code{EXP ...} to multiple variables at once.
All variables are mutually recursive.
@verbatim
(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
@end verbatim

@end deffn
@deffn {syntax} parameterize
@lisp
(parameterize ((PARAMETER1 X1) ...) BODY ...)
@end lisp
Binds the parameters @code{PARAMETER1 ...} dynamically to the values
@code{X1 ...} during execution of @code{BODY ...}.  (see also:
@code{make-parameter} in @ref{Parameters}). Note that @code{PARAMETER} may be any
expression that evaluates to a parameter procedure.

@end deffn
@deffn {syntax} receive
@lisp
(receive (NAME1 ... [. NAMEn]) VALUEEXP BODY ...)
(receive VALUEEXP)
@end lisp
SRFI-8. Syntactic sugar for @code{call-with-values}. Binds variables
to the result values of @code{VALUEEXP} and evaluates @code{BODY ...}.

The syntax 

@verbatim
(receive VALUEEXP)
@end verbatim

is equivalent to

@verbatim
(receive _ VALUEEXP _)
@end verbatim

@end deffn
@deffn {syntax} set!-values
@lisp
(set!-values (NAME ...) EXP)
@end lisp
Assigns the result values of expression @code{EXP} to multiple
variables.
@end deffn



@node Substitution forms and macros
@subsection Substitution forms and macros



@deffn {syntax} define-constant
@lisp
(define-constant NAME CONST)
@end lisp
Define a variable with a constant value, evaluated at compile-time. 
Any reference to such a
constant should appear textually @b{after} its definition. This
construct is equivalent to @code{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.
@code{CONST} may be any constant expression, and may also refer to
constants defined via @code{define-constant} previously.
This for should only be used at top-level.

@end deffn
@deffn {syntax} define-inline
@lisp
(define-inline (NAME VAR ... [. VAR]) BODY ...)
(define-inline NAME EXP)
@end lisp
Defines an inline procedure. Any occurrence of @code{NAME} will be
replaced by @code{EXP} or @code{(lambda (VAR ... [. VAR]) BODY ...)}. 
This is similar to a macro, but variable-names and -scope will
be correctly handled.  Inline substitutions take place @b{after}
macro-expansion.  @code{EXP} should be a lambda-expression. Any
reference to @code{NAME} should appear textually @b{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 @code{define} when evaluated or interpreted. Inline
definitions should only appear at toplevel.

@end deffn
@deffn {syntax} define-macro
@lisp
(define-macro (NAME VAR ... [. VAR]) EXP1 ...)
(define-macro NAME (lambda (VAR ... [. VAR]) EXP1 ...))
(define-macro NAME1 NAME2)
@end lisp
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 @code{eval} and the
declaration @code{run-time-macros} (or the command line option
@code{-run-time-macros}) has been used, then the
macro is visible in evaluated expressions during runtime. The second
possible syntax for @code{define-macro} is allowed for portability
purposes only. In this case the second argument @b{must} be a
lambda-expression or a macro name.  Only global macros can be defined using this form.
@code{(define-macro NAME1 NAME2)} simply copies the macro definition
from @code{NAME2} to @code{NAME1}, creating an alias.

This form is also available with the @code{syntax-case} macro
system.
@end deffn


@node Conditional forms
@subsection Conditional forms



@deffn {syntax} switch
@lisp
(switch EXP (KEY EXP1 ...) ... [(else EXPn ...)])
@end lisp
This is similar to @code{case}, but a) only a single key is allowed,
and b) the key is evaluated.

@end deffn
@deffn {syntax} unless
@lisp
(unless TEST EXP1 EXP2 ...)
@end lisp
Equivalent to: 
@verbatim
(if (not TEST) (begin EXP1 EXP2 ...))
@end verbatim

@end deffn
@deffn {syntax} when
@lisp
(when TEST EXP1 EXP2 ...)
@end lisp
Equivalent to:
@verbatim
(if TEST (begin EXP1 EXP2 ...))
@end verbatim
@end deffn



@node Record structures
@subsection Record structures



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

@verbatim
(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
@end verbatim

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

@verbatim
(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
@end verbatim

@code{define-record-printer} works also with SRFI-9 record types.

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



@node Other forms
@subsection Other forms



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

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

@end deffn
@deffn {syntax} critical-section
@lisp
(critical-section BODY ...)
@end lisp
Evaluate @code{BODY ...} with timer-interrupts temporarily disabled.

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

@end deffn
@deffn {syntax} eval-when
@lisp
(eval-when (SITUATION ...) EXP ...)
@end lisp
Controls evaluation/compilation of subforms. @code{SITUATION} should
be one of the symbols @code{eval}, @code{compile} or @code{load}.
When encountered in the evaluator, and the situation specifier
@code{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 @code{compile} is given, then this form is
evaluated at compile-time.  When encountered while compiling code, and the
situation specifier @code{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:

@multitable {compile} {evaluate at compile time} {In interpreted code}
@item                @tab in compiled code         @tab In interpreted code
@item @code{eval}    @tab ignore                   @tab evaluate 
@item @code{compile} @tab evaluate at compile time @tab ignore 
@item @code{load}    @tab compile as normal        @tab ignore 
@end multitable

Note: It is currently not possible to use @code{define-syntax} or
@code{define} inside @code{eval-when} forms when hygienic macros
are enabled.

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

@end deffn
@deffn {syntax} nth-value
@lisp
(nth-value N EXP)
@end lisp
Returns the @code{N}th value (counting from zero) of the values returned
by expression @code{EXP}.

@end deffn
@deffn {syntax} time
@lisp
(time EXP1 ...)
@end lisp
Evaluates @code{EXP1 ...} and print elapsed time and memory
information. The result of the last expression is returned.
@end deffn


@node Declarations
@section Declarations



@deffn {syntax} declare
@lisp
(declare DECLSPEC ...)
@end lisp
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. @code{DECLSPEC} may be any of the
following:



@deffn {declaration specifier} always-bound
@lisp
(always-bound SYMBOL ...)
@end lisp
Declares that the given variables are always bound and
accesses to those have not to be checked.
@end deffn

@deffn {declaration specifier} block
@lisp
(block)
@end lisp
Assume global variables are never redefined. This is the same as
specifying the @code{-block} option.
@end deffn

@deffn {declaration specifier} block-global
@deffnx {declaration specifier} hide
@lisp
(block-global SYMBOL ...)
(hide SYMBOL ...)
@end lisp
Declares that the toplevel bindings for @code{SYMBOL ...}
should not be accessible from code in other compilation units or by
@code{eval}. Access to toplevel bindings declared as block global is
also more efficient.
@end deffn

@deffn {declaration specifier} bound-to-procedure
@lisp
(bound-to-procedure SYMBOL ...)
@end lisp
Declares that the given identifiers are always bound to procedure values.
@end deffn

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

@deffn {declaration specifier} export
@lisp
(export SYMBOL ...)
@end lisp
The opposite of @code{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 (@code{syntax-case}) macro system is used, the exported identifier
may also have the form @code{(MODULE-NAME SYMBOL ...)}, which specifies identifiers to
be exported from a module as (undecorated) toplevel variables.
@end deffn

@deffn {declaration specifier} foreign-declare
@lisp
(foreign-declare STRING ...)
@end lisp
Include given strings verbatim into header of generated file.
@end deffn

@deffn {declaration specifier} foreign-parse
@lisp
(foreign-parse STRING ...)
@end lisp
Parse given strings and generate foreign-interface bindings. See @ref{The Easy Foreign Function Interface}
for more information.
@end deffn

@deffn {declaration specifier} interrupts-enabled
@lisp
(interrupts-enabled)
@end lisp
Enable timer-interrupts checks in the compiled program (the default).
@end deffn

@deffn {declaration specifier} disable-interrupts
@deffnx {declaration specifier} not
@lisp
(disable-interrupts)
(not interrupts-enabled)
@end lisp
Disable timer-interrupts checks in the compiled program. Threads can
not be preempted in main- or library-units that contain this declaration.
@end deffn

@deffn {declaration specifier} no-argc-checks
@lisp
(no-argc-checks)
@end lisp
Disables argument count checking.
@end deffn

@deffn {declaration specifier} no-bound-checks
@lisp
(no-bound-checks)
@end lisp
Disables the bound-checking of toplevel bindings.
@end deffn

@deffn {declaration specifier} no-procedure-checks
@lisp
(no-procedure-checks)
@end lisp
Disables checking of values in operator position for being of procedure type.
@end deffn

@deffn {declaration specifier} TYPE
@deffnx {declaration specifier} fixnum-arithmetic
@lisp
([number-type] TYPE)
(fixnum-arithmetic)
@end lisp
Declares that only numbers of the given type are used. @code{TYPE}
may be @code{fixnum} or @code{generic} (which is
the default).
@end deffn

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

@deffn {declaration specifier} standard-bindings
@lisp
([not] standard-bindings SYMBOL ...)
@end lisp
Declares that all given standard procedures (or all if no symbols are
specified) are never globally redefined.  If @code{not} is specified,
then all but the given standard bindings are assumed to be never
redefined.
@end deffn

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

@deffn {declaration specifier} usual-integrations
@lisp
([not] usual-integrations SYMBOL ...)
@end lisp
Declares that all given standard and extended bindings (or all if no
symbols are specified) are never globally redefined.  If @code{not}
is specified, then all but the given standard and extended bindings are
assumed to be never redefined.
@end deffn

@deffn {declaration specifier} unit
@lisp
(unit SYMBOL)
@end lisp
Specify compilation unit-name (if this is a library)
@end deffn

@deffn {declaration specifier} unsafe
@deffnx {declaration specifier} not
@lisp
(unsafe)
(not safe)
@end lisp
Do not generate safety-checks. This is the same as specifying the
@code{-unsafe} option.  Also implies

@verbatim
(declare (no-bound-checks) (no-procedure-checks) (no-argc-checks))
@end verbatim
@end deffn

@deffn {declaration specifier} uses
@lisp
(uses SYMBOL ...)
@end lisp
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 @code{cond-expand}
knows about them.
@end deffn


@end deffn



@node Parameters
@section 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:

@verbatim
(define foo (make-parameter 123))
(foo)                             ==> 123
(foo 99)
(foo)                             ==> 99
@end verbatim

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

CHICKEN implements @uref{http://srfi.schemers.org/srfi-39/srfi-39.html, SRFI-39}



@deffn {procedure} make-parameter
@lisp
(make-parameter VALUE [GUARD])
@end lisp
Returns a procedure that accepts zero or one argument. Invoking the
procedure with zero arguments returns @code{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). @code{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.

@end deffn
@defvr {parameter} case-sensitive
If true, then @code{read} reads symbols and identifiers in
case-sensitive mode and uppercase characters in symbols are printed
escaped. Defaults to @code{#t}.

@end defvr
@defvr {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 @code{load-library}.

@end defvr
@defvr {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 @code{-:})
removed.

@end defvr
@defvr {parameter} exit-handler
A procedure of a single optional argument. When @code{exit} is called,
then this procedure will be invoked with the exit-code as argument. The
default behavior is to terminate the program.

@end defvr
@defvr {parameter} eval-handler
A procedure of one or two arguments. When @code{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.

@end defvr
@defvr {parameter} force-finalizers
If true, force and execute all pending finalizers before exiting the
program (either explicitly by @code{exit} or implicitly when the last
toplevel expression has been executed). Default is @code{#t}.

@end defvr
@defvr {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: @ref{Entry points}) to enter a loop that waits for
callbacks from the host program.

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

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

@end defvr
@defvr {parameter} repl-prompt
A string that will be printed before reading interactive input from
the user in a read-eval-print loop. Defaults to @code{"#;> "}.

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

@end defvr
@defvr {parameter} strict-reader
If true, then most non-standard read syntax is disabled. Defaults to
@code{#f}.
@end defvr




@node Unit library
@section Unit library

This unit contains basic Scheme definitions. This unit is used by default, unless the program
is compiled with the @code{-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::                     
@end menu

@node Arithmetic
@subsection Arithmetic


@deffn {procedure} add1
@deffnx {procedure} sub1
@lisp
(add1 N)
(sub1 N)
@end lisp
Adds/subtracts 1 from @code{N}.

@end deffn
@deffn {procedure} bitwise-and
@deffnx {procedure} bitwise-ior
@deffnx {procedure} bitwise-xor
@deffnx {procedure} bitwise-not
@deffnx {procedure} arithmetic-shift
@lisp
(bitwise-and N1 ...)
(bitwise-ior N1 ...)
(bitwise-xor N1 ...)
(bitwise-not N)
(arithmetic-shift N1 N2)
@end lisp
Binary fixnum operations. @code{arithmetic-shift} shifts the argument
@code{N1} by @code{N2} bits to the left. If @code{N2} is negative,
than @code{N1} is shifted to the right.

@end deffn
@deffn {procedure} fixnum?
@lisp
(fixnum? X)
@end lisp
Returns @code{#t} if @code{X} is a fixnum, or @code{#f} otherwise.

@end deffn
@deffn {procedure} fx+
@deffnx {procedure} fx-
@deffnx {procedure} fx*
@deffnx {procedure} fx/
@deffnx {procedure} fxmod
@deffnx {procedure} fxneg
@deffnx {procedure} fxmin
@deffnx {procedure} fxmax
@deffnx {procedure} fx=
@deffnx {procedure} fx>
@deffnx {procedure} fx<
@deffnx {procedure} fx>=
@deffnx {procedure} fx<=
@lisp
(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)
@end lisp
Arithmetic fixnum operations. These procedures do not check their
arguments, so non-fixnum parameters will result in incorrect
results. @code{fxneg} negates its argument.

On division by zero, @code{fx/} and @code{fxmod} signal a condition of
kind @code{(exn arithmetic)}.

@end deffn
@deffn {procedure} signum
@lisp
(signum N)
@end lisp
Returns @code{1} if @code{N} is positive, @code{-1} if @code{N} 
is negative or @code{0} if @code{N} is zero.
@end deffn




@node File Input/Output
@subsection File Input/Output


@deffn {procedure} current-error-port
@lisp
(current-error-port [PORT])
@end lisp
Returns default error output port. If @code{PORT} is given, then that
port is selected as the new current error output port.

@end deffn
@deffn {procedure} end-of-file
@lisp
(end-of-file)
@end lisp
Returns the end-of-file object.

@end deffn
@deffn {procedure} flush-output
@lisp
(flush-output [PORT])
@end lisp
Write buffered output to the given output-port. @code{PORT} defaults
to the value of @code{(current-output-port)}.

@end deffn
@deffn {procedure} port-name
@lisp
(port-name PORT)
@end lisp
Fetch filename from @code{PORT}. This returns the filename that was
used to open this file.  Returns a special tag string, enclosed into
parentheses for non-file ports.

@end deffn
@deffn {procedure} port-position
@lisp
(port-position PORT)
@end lisp
Returns the current position of @code{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.

@end deffn
@deffn {procedure} set-port-name!
@lisp
(set-port-name! PORT STRING)
@end lisp
Sets the name of @code{PORT} to @code{STRING}.
@end deffn




@node Files
@subsection Files




@deffn {procedure} delete-file
@lisp
(delete-file STRING)
@end lisp
Deletes the file with the pathname @code{STRING}. If the file does
not exist, an error is signaled.

@end deffn
@deffn {procedure} file-exists?
@lisp
(file-exists? STRING)
@end lisp
Returns @code{#t} if a file with the given pathname exists, or
@code{#f} otherwise.

@end deffn
@defvr {variable} pathname-directory-separator
Contains the directory-separator character for pathnames on this platform.

@end defvr
@defvr {variable} pathname-extension-separator
Contains the extension-separator character for pathnames on this platform.

@end defvr
@deffn {procedure} rename-file
@lisp
(rename-file OLD NEW)
@end lisp
Renames the file or directory with the pathname @code{OLD} to
@code{NEW}. If the operation does not succeed, an error is signaled.
@end deffn



@node String ports
@subsection String ports




@deffn {procedure} get-output-string
@lisp
(get-output-string PORT)
@end lisp
Returns accumulated output of a port created with
@code{(open-output-string)}.

@end deffn
@deffn {procedure} open-input-string
@lisp
(open-input-string STRING)
@end lisp
Returns a port for reading from @code{STRING}.

@end deffn
@deffn {procedure} open-output-string
@lisp
(open-output-string)
@end lisp
Returns a port for accumulating output in a string.
@end deffn




@node Feature identifiers
@subsection Feature identifiers




@deffn {procedure} features
@lisp
(features)
@end lisp
Returns a list of all registered features that will be accepted as valid
feature-identifiers by @code{cond-expand}.

@end deffn
@deffn {procedure} register-feature!
@lisp
(register-feature! FEATURE ...)
@end lisp
Register one or more features that will be accepted as valid
feature-identifiers by @code{cond-expand}. @code{FEATURE ...} may
be a keyword, string or symbol.

@end deffn
@deffn {procedure} unregister-feature!
@lisp
(unregister-feature! FEATURE ...)
@end lisp
Unregisters the specified feature-identifiers. @code{FEATURE ...}
may be a keyword, string or symbol.
@end deffn




@node Keywords
@subsection Keywords

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



@deffn {procedure} get-keyword
@lisp
(get-keyword KEYWORD ARGLIST [THUNK])
@end lisp
Returns the argument from @code{ARGLIST} specified under the keyword
@code{KEYWORD}.  If the keyword is not found, then the zero-argument
procedure @code{THUNK} is invoked and the result value is returned. If
@code{THUNK} is not given, @code{#f} is returned.

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

Note: the @code{KEYWORD} may actually be any kind of object.

@end deffn
@deffn {procedure} keyword?
@lisp
(keyword? X)
@end lisp
Returns @code{#t} if @code{X} is a keyword symbol, or @code{#f}
otherwise.

@end deffn
@deffn {procedure} keyword->string
@lisp
(keyword->string KEYWORD)
@end lisp
Transforms @code{KEYWORD} into a string.

@end deffn
@deffn {procedure} string->keyword
@lisp
(string->keyword STRING)
@end lisp
Returns a keyword with the name @code{STRING}.
@end deffn




@node Exceptions
@subsection Exceptions


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



@deffn {syntax} condition-case
@lisp
(condition-case EXPRESSION CLAUSE ...)
@end lisp
Evaluates @code{EXPRESSION} and handles any exceptions that are covered by
@code{CLAUSE ...}, where @code{CLAUSE} should be of the following form:

@verbatim
CLAUSE = ([VARIABLE] (KIND ...) BODY ...)
@end verbatim

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

@verbatim
(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

@end verbatim
@end deffn



All error-conditions signalled by the system are of kind @code{exn}.
The following composite conditions are additionally defined:

@table @code

@item (exn arity)

Signalled when a procedure is called with the wrong number of arguments.

@item (exn type)

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

@item (exn arithmetic)

Signalled on arithmetic errors, like division by zero.

@item (exn i/o)

Signalled on input/output errors.

@item (exn i/o file)

Signalled on file-related errors.

@item (exn i/o net)

Signalled on network errors.

@item (exn bounds)

Signalled on errors caused by accessing non-existent elements of a collection.

@item (exn runtime)

Signalled on low-level runtime-system error-situations.

@item (exn runtime limit)

Signalled when an internal limit is exceeded (like running out of memory).

@item (exn match)

Signalled on errors raised by failed matches (see the section on @code{match}).

@item (exn syntax)

Signalled on syntax errors.

@end table

Notes:
@itemize
@item All error-exceptions (of the kind @code{exn}) are non-continuable.

@item Error-exceptions of the @code{exn} kind have additional
@code{arguments} and @code{location} properties that contain the
arguments passed to the error-handler and the name of the procedure
where the error occurred (if available).

@item When the @code{posix} unit is available and used, then a
user-interrupt (@code{signal/int}) signals an exception of the kind
@code{user-interrupt}. 

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

@end itemize


@node Environment information and system interface
@subsection Environment information and system interface



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

@end deffn
@deffn {procedure} exit
@lisp
(exit [CODE])
@end lisp
Exit the running process and return exit-code, which defaults to 0
(Invokes @code{exit-handler}).

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

@verbatim
djgpp
cygwin
msvc
mingw32
gnu
metrowerks
unknown
@end verbatim

@end deffn
@deffn {procedure} chicken-version
@lisp
(chicken-version)
@end lisp
Returns a string containing the version number of the CHICKEN runtime
system.

@end deffn
@deffn {procedure} errno
@lisp
(errno)
@end lisp
Returns the error code of the last system call.

@end deffn
@deffn {procedure} getenv
@lisp
(getenv STRING)
@end lisp
Returns the value of the environment variable @code{STRING} or
@code{#f} if that variable is not defined.

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

@verbatim
alpha
mips
hppa
ultrasparc
sparc
ppc
ia64
x86
x86-64
unknown
@end verbatim

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

@verbatim
msdos
windows
unix
macos
unknown
@end verbatim

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

@verbatim
linux
freebsd
netbsd
openbsd
macosx
hpux
solaris
sunos
unknown
@end verbatim

@end deffn
@deffn {procedure} system
@lisp
(system STRING)
@end lisp
Execute shell command. The functionality offered by this procedure
depends on the capabilities of the host shell.
@end deffn




@node Execution time
@subsection Execution time



@deffn {procedure} cpu-time
@lisp
(cpu-time)
@end lisp
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.

@end deffn
@deffn {procedure} current-milliseconds
@lisp
(current-milliseconds)
@end lisp
Returns the number of milliseconds since process- or machine startup.

@end deffn
@deffn {procedure} current-seconds
@lisp
(current-seconds)
@end lisp
Returns the number of seconds since midnight, Jan. 1, 1970.
@end deffn




@node Interrupts and error-handling
@subsection Interrupts and error-handling



@deffn {procedure} enable-interrupts
@deffnx {procedure} disable-interrupts
@lisp
(enable-interrupts)
(disable-interrupts)
@end lisp
Enables/disables processing of timer-interrupts and interrupts caused
by signals.

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

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

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

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

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

@end deffn
@deffn {procedure} reset
@lisp
(reset)
@end lisp
Reset program (Invokes @code{reset-handler}).
@end deffn




@node Garbage collection
@subsection Garbage collection



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

@deffn {procedure} memory-statistics
@lisp
(memory-statistics)
@end lisp
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.
@end deffn

@end deffn
@deffn {procedure} set-finalizer!
@lisp
(set-finalizer! X PROC)
@end lisp
Registers a procedure of one argument @code{PROC}, that will be
called as soon as the non-immediate data object @code{X} is about to
be garbage-collected (with that object as its argument).  Note that
the finalizer will @b{not} be called when interrupts are disabled.

@end deffn
@deffn {procedure} set-gc-report!
@lisp
(set-gc-report! FLAG)
@end lisp
Print statistics after every GC, depending on @code{FLAG}. A value of
@code{#t} shows statistics after every major GC. A true value different
from @code{#t} shows statistics after every minor GC. @code{#f}
switches statistics off.
@end deffn




@node Other control structures
@subsection Other control structures



@deffn {procedure} andmap
@lisp
(andmap PROC LIST1 ...)
@end lisp
Repeatedly calls @code{PROC} with arguments taken from @code{LIST1 ...}.  
If any invocation should return @code{#f}, the result of
@code{andmap} is @code{#f}. If all invocations return a true result,
then the result of @code{andmap} is @code{#t}.

@end deffn
@deffn {procedure} ormap
@lisp
(ormap PROC LIST1 ...)
@end lisp
Repeatedly calls @code{PROC} with arguments taken from @code{LIST1 ...}.  
If any invocation should return a value different from
@code{#f}, then this value is returned as the  result of
@code{ormap}. If all invocations return @b{#f},
then the result of @code{ormap} is @code{#f}.
@end deffn



@node String utilities
@subsection String utilities


@deffn {procedure} reverse-list->string
@lisp
(reverse-list->string LIST)
@end lisp
Returns a string with the characters in @code{LIST} in reverse order. This is equivalent to
@code{(list->string (reverse LIST))}, but much more efficient.
@end deffn


@node Generating uninterned symbols
@subsection Generating uninterned symbols



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

@end deffn
@deffn {procedure} string->uninterned-symbol
@lisp
(string->uninterned-symbol STRING)
@end lisp
Returns a newly created, unique symbol with the name @code{STRING}.
@end deffn




@node Standard Input/Output
@subsection Standard Input/Output

@deffn {procedure} port?
@lisp
(port? X)
@end lisp
Returns @code{#t} if @code{X} is a port object or @code{#f}
otherwise.

@end deffn
@deffn {procedure} print
@lisp
(print EXP1 EXP2 ...)
@end lisp
Outputs the arguments @code{EXP1 EXP2 ...} using @code{display}
and writes a newline character to the port that is the value of
@code{(current-output-port)}. Returns its first argument.

@end deffn
@deffn {procedure} print*
@lisp
(print* EXP1 ...)
@end lisp
Similar to @code{print}, but does not output a terminating newline
character.
@end deffn



@node User-defined named characters
@subsection User-defined named characters



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

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

@verbatim
(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
@end verbatim
@end deffn




@node Vectors
@subsection Vectors



@deffn {procedure} vector-copy!
@lisp
(vector-copy! VECTOR1 VECTOR2 [COUNT])
@end lisp
Copies contents of @code{VECTOR1} into @code{VECTOR2}. If the
argument @code{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: @code{(exn bounds)}

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




@node The unspecified value
@subsection The @emph{unspecified} value



@deffn {procedure} void
@lisp
(void)
@end lisp
Returns an unspecified value.
@end deffn




@node call/cc
@subsection call/cc



@deffn {procedure} call/cc
@lisp
(call/cc PROCEDURE)
@end lisp
An alias for @code{call-with-current-continuation}.
@end deffn




@node Unit eval
@section Unit eval

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

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

@node Loading code
@subsection Loading code



@deffn {procedure} load
@lisp
(load FILE [EVALPROC])
@end lisp
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
@code{EVALPROC} (which defaults to @code{eval}).  On platforms that
support it (currently Linux ELF and Solaris), @code{load} can be used
to load compiled programs:

@verbatim
% 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
#;> (load "x.so")
; loading x.so ...
#;> (hello)
Hello!
#;>
@end verbatim

The second argument to @code{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.

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

@itemize
@item a file named ``@code{<UNIT>.so}''

@item the files given in the parameter @code{dynamic-load-libraries}

@end itemize

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

@end deffn
@deffn {procedure} load-noisily
@lisp
(load-noisily FILE [EVALPROC])
@end lisp
As @code{load} but the result(s) of each evaluated toplevel-expression
is written to standard output.

@end deffn



@node Read-eval-print loop
@subsection Read-eval-print loop



@deffn {procedure} repl
@lisp
(repl)
@end lisp
Start a new read-eval-print loop. Sets the @code{reset-handler} so that
any invocation of @code{reset} restarts the read-eval-print loop. Also
changes the current @code{error-handler} to display a message, write
any arguments to the value of @code{(current-error-port)} and reset.
@end deffn




@node Macros
@subsection Macros




@deffn {procedure} get-line-number
@lisp
(get-line-number EXPR)
@end lisp
If @code{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 @code{#f} is returned.  Note that line-number information for
expressions is only available in the compiler.

@end deffn
@deffn {procedure} macro?
@lisp
(macro? SYMBOL)
@end lisp
Returns @code{#t} if there exists a macro-definition for @code{SYMBOL}.

@end deffn
@deffn {procedure} macroexpand
@lisp
(macroexpand X)
@end lisp
If @code{X} is a macro-form, expand the macro (and repeat expansion
until expression is a non-macro form).  Returns the resulting expression.

@end deffn
@deffn {procedure} macroexpand-1
@lisp
(macroexpand-1 X)
@end lisp
If @code{X} is a macro-form, expand the macro.  Returns the resulting
expression.

@end deffn
@deffn {procedure} undefine-macro!
@lisp
(undefine-macro! SYMBOL)
@end lisp
Remove the current macro-definition of the macro named @code{SYMBOL}.
@end deffn

@deffn {procedure} syntax-error
@lisp
(syntax-error [LOCATION] MESSAGE ARGUMENT ...)
@end lisp
Signals an exception of the kind @code{(exn syntax)}. Otherwise identical to 
@code{error}.
@end deffn


@node Loading extension libraries
@subsection 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.


@deffn {parameter} repository-path
Contains a string naming the path to the extension repository, which defaults to
either the value of the environment variable @code{CHICKEN_REPOSITORY}, the value
of the environment variable @code{CHICKEN_HOME} or the default library path
(usually @code{/usr/local/lib/chicken} on UNIX systems.
@end deffn

@deffn {procedure} extension-info
@lisp
(extension-info ID)
@end lisp
If an extension with the name @code{ID} is installed and if it has a setup-information
list registered in the extension repository, then the info-list is returned. Otherwise
@code{extension-info} returns @code{#f}.
@end deffn

@deffn {procedure} provide
@lisp
(provide ID ...)
@end lisp
Registers the extension IDs @code{ID ...} as loaded. This is mainly
intended to provide aliases for certain extension identifiers.

@end deffn
@deffn {procedure} provided?
@lisp
(provided? ID ...)
@end lisp
Returns @code{#t} if the extension with the IDs @code{ID @dots{}}
are currently loaded, or @code{#f} otherwise.
Works also for feature-ids.

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

@enumerate

@item the current directory

@item the current include path, which defaults to the pathnames
given in @code{CHICKEN_INCLUDE_PATH} and @code{CHICKEN_HOME}.
In case @code{ID} is a list, it is interpreted as a (relative)
pathname.

@end enumerate

@code{ID} may be a symbol, or a list of symbols.  See also:
@code{require-for-syntax}.
@end deffn





@node Reader extensions
@subsection Reader extensions



@deffn {procedure} define-reader-ctor
@lisp
(define-reader-ctor SYMBOL PROC)
@end lisp
Define new read-time constructor for @code{#,} read syntax. For further information, see
the documentation for @uref{http://srfi.schemers.org/srfi-10/srfi-10.html, SRFI-10 }.
@end deffn

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

@lisp
; 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 %e0e0e0 3)" read)
; ==> (1 2 #(240 240 240) 3)
@end lisp
@end deffn



@node Eval
@subsection Eval



@deffn {procedure} eval
@lisp
(eval EXP [ENVIRONMENT])
@end lisp
Evaluates @code{EXP} and returns the result of the evaluation. The second argument is optional
and defaults to the value of @code{(interaction-environment)}.
@end deffn




@node Unit extras
@section Unit extras


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


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

@node Lists
@subsection Lists


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

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

@end deffn
@deffn {procedure} butlast
@lisp
(butlast LIST)
@end lisp
Returns a fresh list with all elements but the last of @code{LIST}.

@end deffn
@deffn {procedure} chop
@lisp
(chop LIST N)
@end lisp
Returns a new list of sublists, where each sublist contains @code{N}
elements of @code{LIST}. If @code{LIST} has a length that is not
a multiple of @code{N}, then the last sublist contains the remaining
elements.

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

@end deffn
@deffn {procedure} compress
@lisp
(compress BLIST LIST)
@end lisp
Returns a new list with elements taken from @code{LIST} with
corresponding true values in the list @code{BLIST}.

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

@end deffn
@deffn {procedure} flatten
@lisp
(flatten LIST1 ...)
@end lisp
Returns @code{LIST1 @dots{}} concatenated together, with nested lists
removed (flattened).

@end deffn
@deffn {procedure} intersperse
@lisp
(intersperse LIST X)
@end lisp
Returns a new list with @code{X} placed between each element.

@end deffn
@deffn {procedure} join
@lisp
(join LISTOFLISTS [LIST])
@end lisp
Concatenates the lists in @code{LISTOFLISTS} with @code{LIST} placed
between each sublist. @code{LIST} defaults to the empty list.

@verbatim
(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)
@end verbatim

@end deffn
@deffn {procedure} shuffle
@lisp
(shuffle LIST)
@end lisp
Returns @code{LIST} with its elements sorted in a random order.


@code{join} could be implemented as follows:

@verbatim
(define (join lstoflsts . lst)
  (apply append (intersperse lstoflists (:optional lst '()))) )
@end verbatim

@end deffn
@deffn {procedure} tail?
@lisp
(tail? X LIST)
@end lisp
Returns true if @code{X} is one of the tails (cdr's) of @code{LIST}.
@end deffn




@node String-port extensions
@subsection String-port extensions




@deffn {procedure} call-with-input-string
@lisp
(call-with-input-string STRING PROC)
@end lisp
Calls the procedure @code{PROC} with a single argument that is a
string-input-port with the contents of @code{STRING}.

@end deffn
@deffn {procedure} call-with-output-string
@lisp
(call-with-output-string PROC)
@end lisp
Calls the procedure @code{PROC} with a single argument that is a
string-output-port.  Returns the accumulated output-string.

@end deffn
@deffn {procedure} with-input-from-string
@lisp
(with-input-from-string STRING THUNK)
@end lisp
Call procedure @code{THUNK} with the current input-port temporarily
bound to an input-string-port with the contents of @code{STRING}.

@end deffn
@deffn {procedure} with-output-to-string
@lisp
(with-output-to-string THUNK)
@end lisp
Call procedure @code{THUNK} with the current output-port temporarily
bound to a string-output-port and return the accumulated output string.
@end deffn




@node Formatted output
@subsection Formatted output




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

@table @code
@item ~%
write newline character
@item ~S
write the next argument
@item ~A
display the next argument
@item ~\n
skip all whitespace in the format-string until the next non-whitespace character
@item ~B
write the next argument as a binary number
@item ~O
write the next argument as an octal number
@item ~X
write the next argument as a hexadecimal number
@item ~C
write the next argument as a character
@item ~~
display `~'
@item ~!
flush all pending output
@item ~?
invoke formatted output routine recursively with the next two arguments as format-string and list of parameters
@end table
 
For more powerful output formatting, see the section about the @code{format} unit.
@end deffn




@node Hash tables
@subsection Hash tables




@deffn {procedure} clear-hash-table!
@lisp
(clear-hash-table! HASH-TABLE)
@end lisp
Erases all entries in the hash-table @code{HASH-TABLE}.

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

@end deffn
@deffn {procedure} hash-table?
@lisp
(hash-table? X)
@end lisp
Returns @code{#t} if the argument is a hash-table.

@end deffn
@deffn {procedure} hash-table->list
@lisp
(hash-table->list HASH-TABLE)
@end lisp
Converts @code{HASH-TABLE} into an association-list.

@end deffn
@deffn {procedure} hash-table-count
@lisp
(hash-table-count HASH-TABLE)
@end lisp
Returns the number of entries in the given hash-table.

@end deffn
@deffn {procedure} hash-table-size
@lisp
(hash-table-size HASH-TABLE)
@end lisp
Returns the size of the hash-table.

@end deffn
@deffn {procedure} hash-table-for-each
@lisp
(hash-table-for-each PROC HASH-TABLE)
@end lisp
Calls @code{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.

@end deffn
@deffn {procedure} hash-table-ref
@lisp
(hash-table-ref HASH-TABLE KEY [DEFAULT])
@end lisp
Returns the entry in the given hash-table under @code{KEY}. If no
entry is stored in the table, @code{#f} is returned.

@end deffn
@deffn {procedure} hash-table-remove!
@lisp
(hash-table-remove! HASH-TABLE KEY)
@end lisp
Removes an entry in the given hash-table.

@end deffn
@deffn {procedure} hash-table-set!
@lisp
(hash-table-set! HASH-TABLE KEY VALUE)
@end lisp
Adds or changes an entry in the given hash-table.

@end deffn
@deffn {procedure} make-hash-table
@lisp
(make-hash-table [PRED [SIZE]])
@end lisp
Creates and returns a hash-table with keys compared via @code{PRED},
which defaults to @code{eq?}. If @code{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.

@end deffn
@deffn {procedure} put!
@lisp
(put! HASH-TABLE KEY PROP VALUE)
@end lisp
Stores @code{VALUE} as property @code{PROP} under the item
@code{KEY} in the given hash-table. Any previously existing value
is overwritten.
@end deffn




@node Queues
@subsection Queues




@deffn {procedure} list->queue
@lisp
(list->queue LIST)
@end lisp
Returns @code{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.

@end deffn
@deffn {procedure} make-queue
@lisp
(make-queue)
@end lisp
Returns a newly created queue.

@end deffn
@deffn {procedure} queue?
@lisp
(queue? X)
@end lisp
Returns @code{#t} if @code{X} is a queue, or @code{#f} otherwise.

@end deffn
@deffn {procedure} queue->list
@lisp
(queue->list QUEUE)
@end lisp
Returns @code{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.

@end deffn
@deffn {procedure} queue-add!
@lisp
(queue-add! QUEUE X)
@end lisp
Adds @code{X} to the rear of @code{QUEUE}.

@end deffn
@deffn {procedure} queue-empty?
@lisp
(queue-empty? QUEUE)
@end lisp
Returns @code{#t} if @code{QUEUE} is empty, or @code{#f} otherwise.

@end deffn
@deffn {procedure} queue-first
@lisp
(queue-first QUEUE)
@end lisp
Returns the first element of @code{QUEUE}. If @code{QUEUE} is empty
an error is signaled

@end deffn
@deffn {procedure} queue-last
@lisp
(queue-last QUEUE)
@end lisp
Returns the last element of @code{QUEUE}. If @code{QUEUE} is empty
an error is signaled

@end deffn
@deffn {procedure} queue-remove!
@lisp
(queue-remove! QUEUE)
@end lisp
Removes and returns the first element of @code{QUEUE}. If @code{QUEUE}
is empty an error is signaled
@end deffn




@node Sorting
@subsection Sorting




@deffn {procedure} merge
@deffnx {procedure} merge!
@lisp
(merge LIST1 LIST2 LESS?)
(merge! LIST1 LIST2 LESS?)
@end lisp
Joins two lists in sorted order. @code{merge!} is the destructive
version of merge. @code{LESS?  } should be a procedure of two arguments,
that returns true if the first argument is to be ordered before the
second argument.

@end deffn
@deffn {procedure} sort
@deffnx {procedure} sort!
@lisp
(sort SEQUENCE LESS?)
(sort! SEQUENCE LESS?)
@end lisp
Sort @code{SEQUENCE}, which should be a list or a vector. @code{sort!}
is the destructive version of sort.

@end deffn
@deffn {procedure} sorted?
@lisp
(sorted? SEQUENCE LESS?)
@end lisp
Returns true if the list or vector @code{SEQUENCE} is already sorted.
@end deffn




@node Random numbers
@subsection Random numbers




@deffn {procedure} random
@lisp
(random N)
@end lisp
Returns an exact random integer from 0 to @code{N}-1.

@end deffn
@deffn {procedure} randomize
@lisp
(randomize [X])
@end lisp
Set random-number seed. If @code{X} is not supplied, the current time is used.
On startup (when the @code{extras} unit is initialized), the random number generator
is initialized with the current time.
@end deffn




@node Input/Output extensions
@subsection Input/Output extensions




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

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

@end deffn
@deffn {procedure} pretty-print
@deffnx {procedure} pp
@lisp
(pretty-print EXP [PORT])
(pp EXP [PORT])
@end lisp
Print expression nicely formatted. @code{PORT} defaults to the value
of @code{(current-output-port)}.

@end deffn
@defvr {parameter} pretty-print-width
Specifies the maximal line-width for pretty printing, after which line
wrap will occur.

@end defvr
@deffn {procedure} read-file
@lisp
(read-file [FILE-OR-PORT])
@end lisp
Returns a list containing all toplevel expressions
read from the file or port @code{FILE-OR-PORT}. If no argument is given,
input is read from the port that is the current value of @code{(current-input-port)}.
After all expressions are read, and if the argument is a port, then the port will
not be closed.

@end deffn
@deffn {procedure} read-line
@deffnx {procedure} write-line
@lisp
(read-line [PORT [LIMIT]])
(write-line STRING [PORT])
@end lisp
Line-input and -output. @code{PORT} defaults to the value of
@code{(current-input-port)} and @code{(current-output-port)},
respectively. if the optional argument @code{LIMIT} is given and
not @code{#f}, then @code{read-line} reads at most @code{LIMIT}
characters per line.

@end deffn
@deffn {procedure} read-lines
@lisp
(read-lines [PORT [MAX]])
@end lisp
Read @code{MAX} or fewer lines from @code{PORT}. @code{PORT}
defaults to the value of @code{(current-input-port)}.

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

@deffn {procedure} read-token
@lisp
(read-token PREDICATE [PORT])
@end lisp
Reads characters from @code{PORT} (which defaults to the value of @code{(current-input-port)})
and calls the procedure @code{PREDICATE} with each character until @code{PREDICATE} returns
false.
@end deffn

@deffn {procedure} with-error-output-to-port
@lisp
(with-error-output-to-port PORT THUNK)
@end lisp
Call procedure @code{THUNK} with the current error output-port
temporarily bound to @code{PORT}.

@end deffn
@deffn {procedure} with-input-from-port
@lisp
(with-input-from-port PORT THUNK)
@end lisp
Call procedure @code{THUNK} with the current input-port temporarily
bound to @code{PORT}.

@end deffn
@deffn {procedure} with-output-to-port
@lisp
(with-output-to-port PORT THUNK)
@end lisp
Call procedure @code{THUNK} with the current output-port temporarily
bound to @code{PORT}.
@end deffn



@node Strings
@subsection Strings


@deffn {procedure} conc
@lisp
(conc X ...)
@end lisp
Returns a string with the string-represenation of all arguments concatenated
together. @code{conc} could be implemented as

@verbatim
(define (conc . args)
  (apply string-append (map ->string args)) )
@end verbatim
@end deffn


@deffn {procedure} ->string
@lisp
(->string X)
@end lisp
Returns a string-representation of @code{X}.

@end deffn
@deffn {procedure} string-chop
@lisp
(string-chop STRING LENGTH)
@end lisp
Returns a list of substrings taken by ``chopping'' @code{STRING} every @code{LENGTH}
characters:

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

@end deffn
@deffn {procedure} string-compare3
@lisp
(string-compare3 STRING1 STRING2)
@end lisp
@end deffn
@deffn {procedure} string-compare3-ci
@lisp
(string-compare3-ci STRING1 STRING2)
@end lisp
Perform a three-way comparison between the @code{STRING1} and @code{STRING2},
returning either @code{-1} if @code{STRING1} is lexicographically less
than @code{STRING2}, @code{0} if it is equal, or @code{1} if it s greater.
@code{string-compare3-ci} performs a case-insensitive comparison.
@end deffn

@deffn {procedure} string-intersperse
@lisp
(string-intersperse LIST STRING)
@end lisp
Returns a string that contains all strings in @code{LIST} concatenated
together.  @code{STRING} is placed between each concatenated string.

@verbatim
(string-intersperse '("one" "two") "three")
@end verbatim

is equivalent to

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

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

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

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

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

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

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

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

@end deffn
@deffn {procedure} substring-index
@deffnx {procedure} substring-index-ci
@lisp
(substring-index WHICH WHERE [START])
(substring-index-ci WHICH WHERE [START])
@end lisp
Searches for first index in string @code{WHERE} where string
@code{WHICH} occurs.  If the optional argument @code{START} is given,
then the search starts at that index.  @code{substring-index-ci}
is a case-insensitive version of @code{substring-index}.
@end deffn




@node Combinators
@subsection Combinators


@deffn {procedure} constantly
@lisp
(constantly X ...)
@end lisp
Returns a procedure that always returns the values @code{X ...} regardless of the number and value of its arguments.

@verbatim
(constantly X) <=> (lambda args X)
@end verbatim

@end deffn
@deffn {procedure} complement
@lisp
(complement PROC)
@end lisp
Returns a procedure that returns the boolean inverse of @code{PROC}.
@verbatim
(complement PROC) <=> (lambda (x) (not (PROC x)))
@end verbatim

@end deffn
@deffn {procedure} compose
@lisp
(compose PROC1 PROC2 ...)
@end lisp
Returns a procedure that represents the composition of the
argument-procedures @code{PROC1 PROC2 ...}.

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

@end deffn
@deffn {procedure} conjoin
@lisp
(conjoin PRED ...)
@end lisp
Returns a procedure that returns @code{#t} if its argument satisfies the
predicates @code{PRED ...}.
@verbatim
((conjoin odd? positive?) 33)   ==>  #t
((conjoin odd? positive?) -33)  ==>  #f
@end verbatim

@end deffn
@deffn {procedure} disjoin
@lisp
(disjoin PRED ...)
@end lisp
Returns a procedure that returns @code{#t} if its argument satisfies any
predicate @code{PRED ...}.
@verbatim
((disjoin odd? positive?) 32)    ==>  #t
((disjoin odd? positive?) -32)   ==>  #f
@end verbatim

@end deffn
@deffn {procedure} flip
@lisp
(flip PROC)
@end lisp
Returns a two-argument procedure that calls @code{PROC} with its
arguments swapped:
@verbatim
(flip PROC) <=> (lambda (x y) (PROC y x))
@end verbatim

@end deffn
@deffn {procedure} identity
@lisp
(identity X)
@end lisp
Returns its sole argument @code{X}.

@end deffn
@deffn {procedure} project
@lisp
(project N)
@end lisp
Returns a procedure that returns its @code{N}th argument.

@end deffn
@deffn {procedure} list-of
@lisp
(list-of PRED)
@end lisp
Returns a procedure of one argument that returns @code{#t} when
applied to a list of elements that all satisfy the predicate procedure
@code{PRED}, or @code{#f} otherwise.

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




@node Binary searching
@subsection Binary searching



@deffn {procedure} binary-search
@lisp
(binary-search SEQUENCE PROC)
@end lisp
Performs a binary search in @code{SEQUENCE}, which should be a sorted
list or vector.  @code{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.
@end deffn




@node Unit srfi-1
@section Unit srfi-1

List library, see the documentation for
@uref{http://srfi.schemers.org/srfi-1/srfi-1.html, SRFI-1 }

@node Unit srfi-4
@section Unit srfi-4 

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


@deffn {procedure} u8vector->byte-vector
@deffnx {procedure} s8vector->byte-vector
@deffnx {procedure} u16vector->byte-vector
@deffnx {procedure} s16vector->byte-vector
@deffnx {procedure} u32vector->byte-vector
@deffnx {procedure} s32vector->byte-vector
@deffnx {procedure} f32vector->byte-vector
@deffnx {procedure} f64vector->byte-vector
@lisp
(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)
@end lisp
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 @b{Intel} processor). The returned
byte-vector shares memory with the contents of the vector.
@end deffn

@deffn {procedure} byte-vector->u8vector
@deffnx {procedure} byte-vector->s8vector
@deffnx {procedure} byte-vector->u16vector
@deffnx {procedure} byte-vector->s16vector
@deffnx {procedure} byte-vector->u32vector
@deffnx {procedure} byte-vector->s32vector
@deffnx {procedure} byte-vector->f32vector
@deffnx {procedure} byte-vector->f64vector
@lisp
(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)
@end lisp
Each of these procedures return a vector where the argument
@code{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.

@end deffn
@deffn {procedure} subu8vector
@deffnx {procedure} subu16vector
@deffnx {procedure} subu32vector
@deffnx {procedure} subs8vector
@deffnx {procedure} subs16vector
@deffnx {procedure} subs32vector
@deffnx {procedure} subf32vector
@deffnx {procedure} subf64vector
@lisp
(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)
@end lisp
Creates a number vector of the same type as the argument vector with the elements at the positions @code{FROM} up to but
not including @code{TO}.
@end deffn




@node Unit srfi-13
@section Unit srfi-13 


String library, see the documentation for
@uref{http://srfi.schemers.org/srfi-13/srfi-13.html, SRFI-13 }

The file @code{srfi-13-syntax.scm} contains macro definitions for
@code{let-string-start+end}.


On systems that support dynamic loading, the @code{srfi-13} unit can
be made available in the interpreter (@code{csi}) by entering

@verbatim
(require-extension srfi-13)
@end verbatim

@node Unit srfi-14
@section Unit srfi-14

Character set library, see the documentation for
@uref{http://srfi.schemers.org/srfi-14/srfi-14.html, SRFI-14 }

On systems that support dynamic loading, the @code{srfi-14} unit can
be made available in the interpreter (@code{csi}) by entering

@verbatim
(require-extension srfi-14)
@end verbatim

@itemize
@item This library provides only the Latin-1 character set.
@end itemize

@node Unit srfi-25
@section Unit srfi-25

Multi-dimensional array, see the documentation for
@uref{http://srfi.schemers.org/srfi-25/srfi-25.html, SRFI-25 }

On systems that support dynamic loading, the @code{srfi-25} unit can
be made available in the interpreter (@code{csi}) by entering

@verbatim
(require-extension srfi-25)
@end verbatim

@node Unit match
@section 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.



@deffn {syntax} match
@deffnx {syntax} match-lambda
@deffnx {syntax} match-lambda*
@deffnx {syntax} match-let
@deffnx {syntax} match-let*
@deffnx {syntax} match-letrec
@deffnx {syntax} match-define
@lisp
(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)
@end lisp
Match expression or procedure arguments with pattern and
execute associated expressions.  A @uref{http://www.call-with-current-continuation.org/match.ps, Postscript manual} is
available .

@end deffn
@deffn {syntax} define-structure
@deffnx {syntax} define-const-structure
@lisp
(define-structure (ID_0 ID_1 ... ID_N))
(define-structure (ID_0 ID_1 ... ID_N)
                  ((@math{ID_{N+1}} @math{EXP_1}) ...
                   (@math{ID_{N+M} EXP_M})))
(define-const-structure (@math{ID_0 ARG_1} ... @math{ARG_N}))
(define-const-structure @math{(ID_0 ARG_1 ... ARG_N)}
                        @math{((ARG_{N+1} EXP_1) ...}
                               @math{(ARG_{N+M} EXP_M))})
@end lisp
Macros for defining record structures that can be decomposed by @code{match}.

@end deffn

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

@table @code

@item #:error

Signal an error. This is the default.

@item #:match

Signal an error and output the offending form.

@item #:fail

Omits @code{pair?} tests when the consequence is to fail in @code{car}
or @code{cdr} rather than to signal an error.

@item #:unspecified

Non-matching expressions will either fail in @code{car} or @code{cdr}
or return an unspecified value.  This mode applies to files compiled
with the @code{unsafe} option or declaration.

@end table


When an error is signalled, the raised exception will be of kind @code{(exn match)}.

@end deffn


Note: @code{match:structure-control} is not available. Structures
defined by the macros provided in this unit are always implemented
as vectors.  @code{match:runtime-structures} is also not available.

To use the pattern matching macros with the highlevel (@code{syntax-case})
macro system @code{(require-extension match)}.


@node Unit regex
@section Unit regex

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

@itemize
@item On UNIX systems that have PCRE (the Perl Compatible Regular Expression package)
installed, PCRE is used.
@item If PCRE is not available, and the C library provides regular expressions, these
are used instead.
@item on Windows (or of PCRE and libc regexes are not available), Dorai Sitaram's
portable @code{pregexp} library is used.
@end itemize



@deffn {procedure} grep
@lisp
(grep REGEX LIST)
@end lisp
Returns all items of @code{LIST} that match the regular expression
@code{REGEX}.  This procedure could be defined as follows:

@verbatim
(define (grep regex lst)
  (filter (lambda (x) (string-match regex x)) lst) )
@end verbatim

@end deffn
@deffn {procedure} pattern->regexp
@lisp
(pattern->regexp PATTERN)
@end lisp
Converts the file-pattern @code{PATTERN} into a regular expression.

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

@end deffn
@deffn {procedure} regexp
@lisp
(regexp STRING)
@end lisp
Returns a precompiled regular expression object for @code{string}.

@end deffn
@deffn {procedure} regexp?
@lisp
(regexp? X)
@end lisp
Returns @code{#t} if @code{X} is a precompiled regular expression,
or @code{#f} otherwise.

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

@end deffn
@deffn {procedure} string-search
@deffnx {procedure} string-search-positions
@lisp
(string-search REGEXP STRING [START [RANGE]])
(string-search-positions REGEXP STRING [START [RANGE]])
@end lisp
Searches for the first match of the regular expression in
@code{REGEXP} with @code{STRING}. The search can be limited to
@code{RANGE} characters.

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

@end deffn
@deffn {procedure} string-substitute
@lisp
(string-substitute REGEXP SUBST STRING [INDEX])
@end lisp
Searches substrings in @code{STRING} that match @code{REGEXP}
and substitutes them with the string @code{SUBST}. The substitution
can contain references to subexpressions in 
@code{REGEXP} with the @code{\NUM} notation, where @code{NUM}
refers to the NUMth parenthesized expression. The optional argument
@code{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.

@verbatim
(string-substitute "([0-9]+) (eggs|chicks)"
                   "2 (1)" "99 eggs or 99 chicks" 2)
 ==> "99 eggs or chicks (99)"
@end verbatim

@end deffn
@deffn {procedure} string-substitute*
@lisp
(string-substitute* STRING SMAP)
@end lisp
Substitutes elements of @code{STRING} according to @code{SMAP}.
@code{SMAP} should be an association-list where each element of the list
is a pair of the form @code{(MATCH . REPLACEMENT)}. Every occurrence of
the regular expression @code{MATCH} in @code{STRING} will be replaced by the string
@code{REPLACEMENT}

@verbatim
(string-substitute* "<h1>Hello, world!</h1>"
                    '(("<[/A-Za-z0-9]+>" . ""))))

==>  "Hello, world!"
@end verbatim
@end deffn




@node Unit syntax-case
@section Unit syntax-case

Hieb's and Dybvig's hygienic macro package. Provides @code{syntax-case}
and @code{syntax-rules}. A postscript manual can be found here:
@uref{http://www.call-with-current-continuation.org/tr356.ps, Indiana University Computer Science Department, Technical Report #356}

@b{Notes:}
@itemize

@item The alternative form
@verbatim
(define-syntax (keyword var) ...)
@end verbatim
is allowed for @code{define-syntax}.

@item The module system described in the Chez Scheme Uses Manual is
supported (including separate compilation). When @code{import} or @code{import-only}
is used with an argument that names a module that is currently not defined, then
the current @code{include-path} (and the @code{repository-path} as well) is searched for a source-file 
of the same name (possibly with the extension @code{.scm}), which (if found)
will be ``visited'' (it's module- and syntax-definitions are processed) using the
procedure @code{visit}. Note that exported identifiers must be defined
via @code{define} or @code{define-syntax}. Other defining forms (like @code{define-values})
are not recognized as exporting definitions.

There are currently no built-in modules.

@item To use the macro-system in compiled or interpreted code, just give
the @code{-hygienic} option to the compiler or interpreter. The @code{syntax-case} unit has
only to be declared as used if compiled code invokes @code{macroexpand}
or @code{eval} with high-level macro syntax forms.

@item @code{define-syntax} can not be used inside an @code{eval-when} form.

@end itemize

Here is a small example that demonstrates separate compilation:

Let's say we have one file @code{foo.scm} that defines a module:

@lisp
(module foo (pr (bar baz))
  (define pr print)
  (define baz 99)
  (define-syntax bar
    (syntax-rules ()
      [(_ x) (list baz 'x)] ) ) )
@end lisp

and another that uses it (@code{use-foo.scm}):

@lisp
(load "foo.so")   ; (require 'foo) would also work

(import foo)
(pr (bar hello))
@end lisp

Compiling the files like this will lead to one dynamically loadable library
and a plain executable:

@verbatim
$ csc -s -hygienic foo.scm
$ csc -hygienic use-foo.scm
$ use-foo
$ (99 hello)
@end verbatim

The @code{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.

@deffn {procedure} visit
@lisp
(visit FILENAME)
@end lisp
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.
@end deffn

@node Unit srfi-18
@section Unit srfi-18

A simple multithreading package. This threading package follows largely
the specification of SRFI-18. For more information see the documentation
for @uref{http://srfi.schemers.org/srfi-18/srfi-18.html, SRFI-18 }

@b{Notes:}

@itemize

@item When an uncaught exception (i.e. an error) is signalled in a thread other than
the primordial thread and warnings are enabled (see: @code{enable-warnings}, then a warning 
message is written to the port that is the value of @code{(current-error-port)}.

@item Blocking I/O will block all threads, except for some socket operations
(see the section about the @code{tcp} unit).

@item It is generally not a good idea for one thread to call a
continuation created by another thread, if @code{dynamic-wind}
is involved.

@item When more than one thread compete for the current time-slice,
the thread that was waiting first will become the next runnable thread.

@item The dynamic environment of a thread consists of the following state:

 @itemize

 @item The current input-, output- and error-port

 @item The current exception handler

 @item The values of all current parameters (created by @code{make-parameter})

 @item Any pending @code{dynamic-wind} thunks.

 @end itemize

@end itemize

The following procedures are provided, in addition to the procedures defined in SRFI-18:



@deffn {procedure} thread-deliver-signal!
@lisp
(thread-deliver-signal! THREAD X)
@end lisp
This will cause @code{THREAD} to signal the condition @code{X} once it is scheduled
for execution. After signalling the condition, the thread continues with its normal
execution.

@end deffn
@deffn {procedure} thread-quantum
@lisp
(thread-quantum THREAD)
@end lisp
Returns the quantum of @code{THREAD}, which is an exact integer
specifying the approximate time-slice of the thread.

@end deffn
@deffn {procedure} thread-quantum-set!
@lisp
(thread-quantum-set! THREAD QUANTUM)
@end lisp
Sets the quantum of @code{THREAD} to @code{QUANTUM}.
@end deffn




@node Unit format
@section Unit format



@deffn {procedure} format
@lisp
(format DESTINATION FORMAT-STRING . ARGUMENTS)
@end lisp
An almost complete implementation of Common LISP format description
according to the CL reference book @b{Common LISP} from Guy L.
Steele, Digital Press. This code was originally part of SLIB. The author
is Dirk Lutzebaeck.

Returns @code{#t}, @code{#f} or a string; has side effect of
printing according to @code{FORMAT-STRING}.  If @code{DESTINATION} is
@code{#t}, the output is to the current output port and @code{#t}
is returned.  If @code{DESTINATION} is @code{#f}, a formatted
string is returned as the result of the call.  If @code{DESTINATION}
is a string, @code{DESTINATION} is regarded as the format string;
@code{FORMAT-STRING} is then the first argument and the output
is returned as a string. If @code{DESTINATION} is a number, the
output is to the value of @code{(current-error-port)}.  Otherwise
@code{DESTINATION} must be an output port and @code{#t} is returned.

@code{FORMAT-STRING} must be a string.  In case of a formatting
error format returns @code{#f} and prints a message on the value
of @code{(current-error-port)}.  Characters are output as if the
string were output by the @code{display} function with the exception
of those prefixed by a tilde (~).  For a detailed description of
the @code{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 @code{format.txt}.

This unit uses definitions from the @code{extras} unit.

@code{format} implements
@uref{http//srfi.schemers.org/srfi-28/srfi-28.html, SRFI-28 }
@end deffn



@node Unit posix
@section Unit posix

This unit provides services as used on many UNIX-like systems.  Note that
the following definitions are not available on non-UNIX systems like
Windows or DOS.

This unit uses the @code{regex} and @code{extras} units.

All errors related to failing file-operations will signal a condition
of kind @code{(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::  
@end menu

@node Directories
@subsection Directories



@deffn {procedure} change-directory
@lisp
(change-directory NAME)
@end lisp
Changes the current working directory to @code{NAME}.

@end deffn
@deffn {procedure} current-directory
@lisp
(current-directory)
@end lisp
Returns the name of the current working directory.

@end deffn
@deffn {procedure} create-directory
@lisp
(create-directory NAME)
@end lisp
Creates a directory with the pathname @code{NAME}.

@end deffn
@deffn {procedure} delete-directory
@lisp
(delete-directory NAME)
@end lisp
Deletes the directory with the pathname @code{NAME}. The directory has
to be empty.

@end deffn
@deffn {procedure} directory
@lisp
(directory PATHNAME)
@end lisp
Returns a list with all files that are contained in the directory with the name @code{PATHNAME}.

@end deffn
@deffn {procedure} directory?
@lisp
(directory? NAME)
@end lisp
Returns @code{#t} if there exists a file with the name @code{NAME}
and if that file is a directory, or @code{#f} otherwise.

@end deffn
@deffn {procedure} glob
@lisp
(glob PATTERN1 ...)
@end lisp
Returns a list of the pathnames of all existing files matching
@code{PATTERN1 ...}, which should be strings containing the usual
file-patterns (with @code{*} matching zero or more characters and
@code{?} matching zero or one character).
@end deffn



@node Pipes
@subsection Pipes



@deffn {procedure} call-with-input-pipe
@deffnx {procedure} call-with-output-pipe
@lisp
(call-with-input-pipe CMDLINE PROC [MODE])
(call-with-output-pipe CMDLINE PROC [MODE])
@end lisp
Call @code{PROC} with a single argument: a input- or output port
for a pipe connected to the subprocess named in @code{CMDLINE}. If
@code{PROC} returns normally, the pipe is closed and any result values
are returned.

@end deffn
@deffn {procedure} close-input-pipe
@deffnx {procedure} close-output-pipe
@lisp
(close-input-pipe PORT)
(close-output-pipe PORT)
@end lisp
Closes the pipe given in @code{PORT} and waits until the connected
subprocess finishes.

@end deffn
@deffn {procedure} create-pipe
@lisp
(create-pipe)
@end lisp
The fundamental pipe-creation operator. Calls the C function
@code{pipe()} and returns 2 values: the file-descriptors of the input-
and output-ends of the pipe.

@end deffn
@deffn {procedure} open-input-pipe
@lisp
(open-input-pipe CMDLINE [MODE])
@end lisp
Spawns a subprocess with the command-line string @code{CMDLINE} and
returns a port, from which the output of the process can be read. If
@code{MODE} is specified, it should be the keyword @code{#:text}
(the default) or @code{#:binary}.

@end deffn
@deffn {procedure} open-output-pipe
@lisp
(open-output-pipe CMDLINE [MODE])
@end lisp
Spawns a subprocess with the command-line string @code{CMDLINE} and
returns a port. Anything written to that port is treated as the input
for the process.  If @code{MODE} is specified, it should be the keyword
@code{#:text} (the default) or @code{#:binary}.

@end deffn
@defvr {limit} pipe/buf
This variable contains the maximal number of bytes that can be written
atomically into a pipe or FIFO.

@end defvr
@deffn {procedure} with-input-from-pipe
@deffnx {procedure} with-output-to-pipe
@lisp
(with-input-from-pipe CMDLINE THUNK [MODE])
(with-output-to-pipe CMDLINE THUNK [MODE])
@end lisp
Temporarily set the value of
@code{current-input-port/current-output-port} to a port for a
pipe connected to the subprocess named in @code{CMDLINE} and call
the procedure @code{THUNK} with no arguments. After @code{THUNK}
returns normally the pipe is closed and the standard input-/output port
is restored to its previous value and any result values are returned.

@verbatim
(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
) ) )
@end verbatim
@end deffn




@node Fifos
@subsection Fifos




@deffn {procedure} create-fifo
@lisp
(create-fifo FILENAME [MODE])
@end lisp
Creates a FIFO with the name @code{FILENAME} and the permission bits
@code{MODE}, which defaults to

@verbatim
(+ perm/irwxu perm/irwxg perm/irwxo)
@end verbatim

@end deffn
@deffn {procedure} fifo?
@lisp
(fifo? FILENAME)
@end lisp
Returns @code{#t} if the file with the name @code{FILENAME} names
a FIFO.
@end deffn




@node File descriptors and low-level I/O
@subsection File descriptors and low-level I/O




@deffn {procedure} duplicate-fileno
@lisp
(duplicate-fileno OLD [NEW])
@end lisp
If @code{NEW} is given, then the file-descriptor @code{NEW} is opened
to access the file with the file-descriptor @code{OLD}. Otherwise a
fresh file-descriptor accessing the same file as @code{OLD} is returned.

@end deffn
@deffn {procedure} file-close
@lisp
(file-close FILENO)
@end lisp
Closes the input/output file with the file-descriptor @code{FILENO}.

@end deffn
@deffn {procedure} file-open
@lisp
(file-open FILENAME FLAGS [MODE])
@end lisp
Opens the file specified with the string @code{FILENAME} and open-flags
@code{FLAGS} using the C function @code{open()}. On success a
file-descriptor for the opened file is returned.  @code{FLAGS}
should be a bitmask containing one or more of the @code{open/...}
values @b{or}ed together using @code{bitwise-ior} (or simply added
together).  The optional @code{MODE} should be a bitmask composed of one
or more permission values like @code{perm/irusr} and is only relevant
when a new file is created. The default mode is 
@code{perm/irwxu | perm/irgrp | perm/iroth}.

@end deffn
@deffn {procedure} file-mkstemp
@lisp
(file-mkstemp TEMPLATE-FILENAME)
@end lisp
Create a file based on the given @code{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
@code{mkstemp(3)} manual page for details on how this function
works.  The template string given is not modified.

Example usage:
@verbatim
(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)))
@end verbatim

@end deffn
@deffn {procedure} file-read
@lisp
(file-read FILENO SIZE [BUFFER])
@end lisp
Reads @code{SIZE} bytes from the file with the file-descriptor
@code{FILENO}.  If a string or bytevector is passed in the optional
argument @code{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.

@end deffn
@deffn {procedure} file-select
@lisp
(file-select READFDLIST WRITEFDLIST [TIMEOUT])
@end lisp
Waits until any of the file-descriptors given in the lists
@code{READFDLIST} and @code{WRITEFDLIST} is ready for input or
output, respectively. If the optional argument @code{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.
@code{READFDLIST} and @b{WRITEFDLIST} may also by file-descriptors
instead of lists.  In this case the returned values are booleans
indicating whether input/output is ready by @code{#t} or @code{#f}
otherwise.  You can also pass @code{#f} as @code{READFDLIST} or
@code{WRITEFDLIST} argument, which is equivalent to @code{()}.

@end deffn
@deffn {procedure} file-write
@lisp
(file-write FILENO BUFFER [SIZE])
@end lisp
Writes the contents of the string or bytevector @code{BUFFER} into
the file with the file-descriptor @code{FILENO}. If the optional
argument @code{SIZE} is given, then only the specified number of bytes
are written.
@end deffn

@defvr {file descriptor} fileno/stdin
@defvrx {file descriptor} fileno/stdout
@defvrx {file descriptor} fileno/stderr
These variables contain file-descriptors for the standard I/O files.
@end defvr

@defvr {flag} open/rdonly
@defvrx {flag} open/wronly
@defvrx {flag} open/rdwr
@defvrx {flag} open/read 
@defvrx {flag} open/write 
@defvrx {flag} open/creat
@defvrx {flag} open/append 
@defvrx {flag} open/excl
@defvrx {flag} open/noctty 
@defvrx {flag} open/nonblock 
@defvrx {flag} open/trunc
@defvrx {flag} open/sync
@defvrx {flag} open/fsync
@defvrx {flag} open/binary
@defvrx {flag} open/text
Flags for use with @code{file-open}.
@end defvr

@deffn {procedure} open-input-file*
@deffnx {procedure} open-output-file*
@lisp
(open-input-file* FILENO [OPENMODE])
(open-output-file* FILENO [OPENMODE])
@end lisp
Opens file for the file-descriptor @code{FILENO} for input or output
and returns a port.  @code{FILENO} should be a positive exact integer.
@code{OPENMODE} specifies an additional mode for opening the file
(currently only the keyword @code{#:append} is supported, which opens
an output-file for appending).
@end deffn

@deffn {procedure} port->fileno
@lisp
(port->fileno PORT)
@end lisp
If @code{PORT} is a file-port, then a file-descriptor is returned for
this port. Otherwise an error is signaled.
@end deffn




@node Retrieving file attributes
@subsection Retrieving file attributes




@deffn {procedure} file-modification-time
@lisp
(file-modification-time FILE)
@end lisp
Returns time (in seconds) of the last modification of @code{FILE}. @code{FILE}
may be a filename or a file-descriptor. If the file does not exist,
an error is signaled.

@end deffn
@deffn {procedure} file-position
@lisp
(file-position FILE)
@end lisp
Returns the current file position of @code{FILE}, which should be a
port or a file-descriptor.

@end deffn
@deffn {procedure} file-size
@lisp
(file-size FILENAME)
@end lisp
Returns the size of the file designated by @code{FILE}.  @code{FILE}
may be a filename or a file-descriptor.  If the file does not exist,
an error is signaled.
@end deffn




@node Changing file attributes
@subsection Changing file attributes




@deffn {procedure} file-truncate
@lisp
(file-truncate FILE OFFSET)
@end lisp
Truncates the file @code{FILE} to the length @code{OFFSET},
which should be an integer. If the file-size is smaller or equal to
@code{OFFSET} then nothing is done.  @code{FILE} should be a filename
or a file-descriptor.

@end deffn
@deffn {procedure} set-file-position!
@lisp
(set-file-position! FILE POSITION [WHENCE])
@end lisp
Sets the current read/write position of @code{FILE} to
@code{POSITION}, which should be an exact integer. @code{FILE}
should be a port or a file-descriptor.  @code{WHENCE} specifies
how the position is to interpreted and should be one of the values
@code{seek/set, seek/cur} and @code{seek/end}. It defaults to
@code{seek/set}.

Exceptions: @code{(exn bounds)}, @code{(exn i/o file)}
@end deffn




@node Processes
@subsection Processes




@deffn {procedure} current-process-id
@lisp
(current-process-id)
@end lisp
Returns the process ID of the current process.

@end deffn
@deffn {procedure} parent-process-id
@lisp
(parent-process-id)
@end lisp
Returns the process ID of the parent of the current process.

@end deffn
@deffn {procedure} process-execute
@lisp
(process-execute PATHNAME [LIST])
@end lisp
Creates a new child process and replaces the running process with it
using the UNIX system call @code{execv()}. If the optional argument
@code{LIST} is given, then it should contain a list of strings which
are passed as arguments to the subprocess.

@end deffn
@deffn {procedure} process-fork
@lisp
(process-fork [THUNK])
@end lisp
Creates a new child process with the UNIX system call
@code{fork()}. Returns either the PID of the child process or 0. If
@code{THUNK} is given, then the child process calls it as a procedure
with no arguments and terminates.

@end deffn
@deffn {procedure} process-run
@lisp
(process-run PATHNAME [LIST])
@end lisp
Creates a new child process using the UNIX system call @code{fork()}
that executes the program given by the string @code{PATHNAME} using
the UNIX system call @code{execv()}.  The PID of the new process is
returned. If @code{LIST} is not specified, then @code{PATHNAME}
is passed to a program named by the environment variable @code{SHELL}
(or @code{/bin/sh}, if the variable is not defined), so usual argument
expansion can take place.

@end deffn
@deffn {procedure} process-signal
@lisp
(process-signal PID [SIGNAL])
@end lisp
Sends @code{SIGNAL} to the process with the id @code{PID} using the
UNIX system call @code{kill()}. @code{SIGNAL} defaults to the value
of the variable @code{signal/term}.

@end deffn
@deffn {procedure} process-wait
@lisp
(process-wait [PID [NOHANG]])
@end lisp
Suspends the current process until the child process with
the id @code{PID} has terminated using the UNIX system call
@code{waitpid()}. If @code{PID} is not given, then this procedure
waits for any child process. If @code{NOHANG} is given and not
@code{#f} then the current process is not suspended.  This procedure
returns three values:
@end deffn

@itemize
@item @code{PID} or 0, if @code{NOHANG} is true and the child process
has not terminated yet;

@item @code{#t} if the process exited normally or @code{#f}
otherwise;

@item either the exit status, if the process terminated normally or the
signal number that terminated/stopped the process.
@end itemize

@deffn {procedure} process
@lisp
(process COMMANDLINE)
@end lisp
Passes the string @code{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. All I/O from/to ports
returned by @code{process} is fully nonblocking.

@end deffn
@deffn {procedure} sleep
@lisp
(sleep SECONDS)
@end lisp
Puts the process to sleep for @code{SECONDS}. Returns either 0 if
the time has completely elapsed, or the number of remaining seconds,
if a signal occurred.
@end deffn



@node Symbolic links
@subsection Symbolic links



@deffn {procedure} create-symbolic-link
@lisp
(create-symbolic-link OLDNAME NEWNAME)
@end lisp
Creates a symbolic link with the filename @code{NEWNAME} that points
to the file named @code{OLDNAME}.

@end deffn
@deffn {procedure} read-symbolic-link
@lisp
(read-symbolic-link FILENAME)
@end lisp
Returns the filename to which the symbolic link @code{FILENAME} points.
@end deffn




@node Permissions
@subsection Permissions, owners, users and groups




@deffn {procedure} file-owner
@lisp
(file-owner FILE)
@end lisp
Returns the user-id of @code{FILE}.  @code{FILE} may be a filename
or a file-descriptor.

@end deffn
@deffn {procedure} file-permissions
@lisp
(file-permissions FILE)
@end lisp
Returns the permission bits for @code{FILE}. You can test this value
by performing bitwise operations on the result and the @code{perm/@dots{}}
values.  @code{FILE} may be a filename or a file-descriptor.

@end deffn
@deffn {procedure} file-read-access?
@deffnx {procedure} file-write-access?
@deffnx {procedure} file-execute-access?
@lisp
(file-read-access? FILENAME)
(file-write-access? FILENAME)
(file-execute-access? FILENAME)
@end lisp
These procedures return @code{#t} if the current user has read,
write or execute permissions on the file named @code{FILENAME}.

@end deffn
@deffn {procedure} change-file-mode
@lisp
(change-file-mode FILENAME MODE)
@end lisp
Changes the current file mode of the file named @code{FILENAME}
to @code{MODE} using the @code{chmod()} system call.  The
@code{perm/...} variables contain the various permission bits and can
be combinded with the @code{bitwise-ior} procedure.

@end deffn
@deffn {procedure} change-file-owner
@lisp
(change-file-owner FILENAME UID GID)
@end lisp
Changes the owner information of the file named @code{FILENAME} to
the user- and group-ids @code{UID} and @code{GID} (which should be
exact integers) using the @code{chown()} system call.

@end deffn
@deffn {procedure} current-user-id
@deffnx {procedure} current-group-id
@deffnx {procedure} current-effective-user-id
@deffnx {procedure} current-effective-group-id
@lisp
(current-user-id)
(current-group-id)
(current-effective-user-id)
(current-effective-group-id)
@end lisp
Return the user- and group-ids of the current process.

@end deffn
@deffn {procedure} group-information
@lisp
(group-information GROUP)
@end lisp
If @code{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 @code{#f} is returned.
@end deffn

@deffn {procedure} get-groups
@lisp
(get-groups)
@end lisp
Returns a list with the supplementary group IDs of the current user.
@end deffn

@deffn {procedure} set-groups!
@lisp
(set-groups! GIDLIST)
@end lisp
Sets the supplementrary group IDs of the current user to the IDs given in the list @code{GIDLIST}.

Only the superuser may invoke this procedure.
@end deffn

@deffn {procedure} initialize-groups
@lisp
(initialize-groups USERNAME BASEGID)
@end lisp
Sets the supplementrary group IDs of the current user to the IDs from the user with name @code{USERNAME} 
(a string), including @code{BASEGID}.

Only the superuser may invoke this procedure.
@end deffn

@defvr {permission bits} perm/irusr
@defvrx {permission bits} perm/iwusr
@defvrx {permission bits} perm/ixusr
@defvrx {permission bits} perm/irgrp
@defvrx {permission bits} perm/iwgrp
@defvrx {permission bits} perm/ixgrp
@defvrx {permission bits} perm/iroth
@defvrx {permission bits} perm/iwoth
@defvrx {permission bits} perm/ixoth
@defvrx {permission bits} perm/irwxu
@defvrx {permission bits} perm/irwxg
@defvrx {permission bits} perm/irwxo
@defvrx {permission bits} perm/isvtx
@defvrx {permission bits} perm/isuid
@defvrx {permission bits} perm/isgid
These variables contain permission bits as used in @code{change-file-mode}.
@end defvr

@deffn {procedure} set-user-id!
@lisp
(set-user-id! UID)
@end lisp
Sets the effective user id of the current process to @code{UID},
which should be a positive integer.
@end deffn

@deffn {procedure} user-information
@lisp
(user-information USER)
@end lisp
If @code{USER} specifes a valid username (as a string) or user ID, then
the user database is consulted and a list of 7 values are returned: the user-name,
the encrypted password, the user ID, the group ID, a user-specific string,
the home directory and the default shell. If no user with this name or
ID can be found, then @code{#f} is returned.
@end deffn




@node Record locking
@subsection Record locking




@deffn {procedure} file-lock
@lisp
(file-lock PORT [START [LEN]])
@end lisp
Locks the file associated with @code{PORT} for reading or
writing (according to whether @code{PORT} is an input- or
output-port). @code{START} specifies the starting position in the
file to be locked and defaults to 0. @code{LEN} specifies the length
of the portion to be locked and defaults to @code{#t}, which means
the complete file. @code{file-lock} returns a ``lock''-object.

@end deffn
@deffn {procedure} file-lock/blocking
@lisp
(file-lock/blocking PORT [START [LEN]])
@end lisp
Similar to @code{file-lock}, but if a lock is held on the file,
the current process blocks (including all threads) until the lock is released.

@end deffn
@deffn {procedure} file-test-lock
@lisp
(file-test-lock PORT [START [LEN]])
@end lisp
Tests whether the file associated with @code{PORT} is locked for reading
or writing (according to whether @code{PORT} is an input- or output-port)
and returns either @code{#f} or the process-id of the locking process.

@end deffn
@deffn {procedure} file-unlock
@lisp
(file-unlock LOCK)
@end lisp
Unlocks the previously locked portion of a file given in @code{LOCK}.
@end deffn




@node Signal handling
@subsection Signal handling




@deffn {procedure} set-alarm!
@lisp
(set-alarm! SECONDS)
@end lisp
Sets an internal timer to raise the @code{signal/alrm}
after @code{SECONDS} are elapsed.  You can use the
@code{set-signal-handler!} procedure to write a handler for this signal.

@end deffn
@deffn {procedure} set-signal-handler!
@lisp
(set-signal-handler! SIGNUM PROC)
@end lisp
Establishes the procedure of one argument @code{PROC} as the handler
for the signal with the code @code{SIGNAL}. @code{PROC} is called
with the signal number as its sole argument. If the argument @code{PROC} is @code{#f}
then this signal will be ignored.

@end deffn
@deffn {procedure} set-signal-mask!
@lisp
(set-signal-mask! SIGLIST)
@end lisp
Sets the signal mask of the current process to block all signals given
in the list @code{SIGLIST}.  Signals masked in that way will not be
delivered to the current process.
@end deffn

@defvr {signal code} signal/term
@defvrx {signal code} signal/kill
@defvrx {signal code} signal/int
@defvrx {signal code} signal/hup
@defvrx {signal code} signal/fpe
@defvrx {signal code} signal/ill
@defvrx {signal code} signal/segv
@defvrx {signal code} signal/abrt
@defvrx {signal code} signal/trap
@defvrx {signal code} signal/quit
@defvrx {signal code} signal/alrm
@defvrx {signal code} signal/vtalrm
@defvrx {signal code} signal/prof
@defvrx {signal code} signal/io
@defvrx {signal code} signal/urg
@defvrx {signal code} signal/chld
@defvrx {signal code} signal/cont
@defvrx {signal code} signal/stop
@defvrx {signal code} signal/tstp
@defvrx {signal code} signal/pipe
@defvrx {signal code} signal/xcpu
@defvrx {signal code} signal/xfsz
@defvrx {signal code} signal/usr1
@defvrx {signal code} signal/usr2
@defvrx {signal code} signal/winch
These variables contain signal codes for use with @code{process-signal} 
or @code{set-signal-handler!}.
@end defvr




@node Environment access
@subsection Environment access




@deffn {procedure} current-environment
@lisp
(current-environment)
@end lisp
Returns a association list of the environment variables and their
current values. 

Note: Under Mac OS X, this procedure always returns the empty list.

@end deffn
@deffn {procedure} setenv
@lisp
(setenv VARIABLE VALUE)
@end lisp
Sets the environment variable named @code{VARIABLE} to
@code{VALUE}. Both arguments should be strings. If the variable is
not defined in the environment, a new definition is created.

@end deffn
@deffn {procedure} unsetenv
@lisp
(unsetenv VARIABLE)
@end lisp
Removes the definition of the environment variable @code{VARIABLE} from
the environment of the current process. If the variable is not defined,
nothing happens.
@end deffn




@node Memory mapped I/O
@subsection Memory mapped I/O




@deffn {procedure} map-file-to-memory
@lisp
(map-file-to-memory ADDRESS LEN PROTECTION FLAG FILENO [OFFSET])
@end lisp
Maps a section of a file to memory using the C function
@code{mmap()}.  @code{ADDRESS} should be a foreign pointer object
or @code{#f}; @code{LEN} specifies the size of the section to
be mapped; @code{PROTECTION} should be one or more of the flags
@code{prot/read, prot/write, prot/exec} or @code{prot/none}
@b{bitwise-ior}ed together; @code{FLAG} should be one or more of
the flags @code{map/fixed, map/shared, map/private, map/anonymous} or
@code{map/file}; @code{FILENO} should be the file-descriptor of the
mapped file. The optional argument @code{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
@code{move-memory!} can be used to access the mapped memory.

@end deffn
@deffn {procedure} memory-mapped-file-pointer
@lisp
(memory-mapped-file-pointer MMAP)
@end lisp
Returns a machine pointer to the start of the memory region to which
the file is mapped.

@end deffn
@deffn {procedure} unmap-file-from-memory
@lisp
(unmap-file-from-memory MMAP [LEN])
@end lisp
Unmaps the section of a file mapped to memory using the C function
@code{munmap()}.  @code{MMAP} should be a mapped file as returned
by the procedure @code{map-file-to-memory}.  The optional argument
@code{LEN} specifies the length of the section to be unmapped and
defaults to the complete length given when the file was mapped.
@end deffn



@node Time routines
@subsection Time routines



@deffn {procedure} seconds->local-time
@lisp
(seconds->local-time SECONDS)
@end lisp
Breaks down the time value represented in @code{SECONDS} into a 10
element vector of the form @code{#(seconds minutes hours mday month
year wday yday dstflag timezone)}, in the following format:

@itemize
@item seconds: the number of seconds after the minute (0 - 59)
@item minutes: the number of minutes after the hour (0 - 59)
@item hours: the number of hours past midnight (0 - 23)
@item mday: the day of the month (1 - 31)
@item month: the number of months since january (0 - 11)
@item year: the number of years since 1900
@item wday: the number of days since Sunday (0 - 6)
@item yday: the number of days since January 1 (0 - 365)
@item dstflag: a flag that is true if Daylight Saving Time is in effect at the time described.
@item timezone: the difference between UTC and the latest local standard
time, in seconds west of UTC.
@end itemize

@end deffn
@deffn {procedure} seconds->string
@lisp
(seconds->string SECONDS)
@end lisp
Converts the local time represented in @code{SECONDS} into a string
of the form @code{"Tue May 21 13:46:22 1991\n"}.

@end deffn
@deffn {procedure} seconds->utc-time
@lisp
(seconds->utc-time SECONDS)
@end lisp
Similar to @code{seconds->local-time}, but interpretes @code{SECONDS}
as UTC time.

@end deffn
@deffn {procedure} time->string
@lisp
(time->string VECTOR)
@end lisp
Converts the broken down time represented in the 10 element vector
@code{VECTOR} into a string of the form @code{"Tue May 21 13:46:22
1991\n"}.
@end deffn




@node Raw exit
@subsection @emph{Raw} exit



@deffn {procedure} _exit
@lisp
(_exit [CODE])
@end lisp
Exits the current process without flushing any buffered output (using
the C function @code{_exit}).  Note that the @code{exit-handler}
is not called when this procedure is invoked. The optional return-code
@code{CODE} defaults to @code{0}.
@end deffn




@node ERRNO values
@subsection ERRNO values



@defvr {error code} errno/perm
@defvrx {error code} errno/noent
@defvrx {error code} errno/srch
@defvrx {error code} errno/intr
@defvrx {error code} errno/io
@defvrx {error code} errno/noexec
@defvrx {error code} errno/badf
@defvrx {error code} errno/child
@defvrx {error code} errno/nomem
@defvrx {error code} errno/acces
@defvrx {error code} errno/fault
@defvrx {error code} errno/busy
@defvrx {error code} errno/notdir
@defvrx {error code} errno/isdir
@defvrx {error code} errno/inval
@defvrx {error code} errno/mfile
@defvrx {error code} errno/nospc
@defvrx {error code} errno/spipe
@defvrx {error code} errno/pipe
@defvrx {error code} errno/again
@defvrx {error code} errno/rofs
@defvrx {error code} errno/wouldblock
These variables contain error codes as returned by @code{errno}.
@end defvr




@node Finding files
@subsection Finding files



@deffn {procedure} find-files
@lisp
(find-files DIRECTORY PREDICATE [ACTION [IDENTITY [LIMIT]]])
@end lisp
Recursively traverses the contents of @code{DIRECTORY} (which should
be a string) and invokes the procedure @code{ACTION} for all files
for which the procedure @code{PREDICATE} is true.  @code{PREDICATE}
may me a procedure of one argument or a regular-expression string.
@code{ACTION} should be a procedure of two arguments: the currently
encountered file and the result of the previous invocation of
@code{ACTION}, or, if this is the first invocation, the value
of @code{IDENTITY}. @code{ACTION} defaults to @code{cons},
@code{IDENTITY} defaults to @code{()}.  @code{LIMIT} should a
procedure of one argument that is called for each nested directory
and which should return true, if that directory is to be traversed
recursively. @code{LIMIT} may also be an exact integer that
gives the maximum recursion depth. A depth of @code{0} means the
files in the specified directory are traversed but not any nested
directories. @code{LIMIT} may also be @code{#f} (the default),
which is equivalent to @code{(constantly #t)}.

Note that @code{ACTION} is called with the full pathname of each file,
including the directory prefix.
@end deffn




@node Getting the hostname and system information
@subsection Getting the hostname and system information



@deffn {procedure} get-host-name
@lisp
(get-host-name)
@end lisp
Returns the hostname of the machine that this process is running on.

@end deffn
@deffn {procedure} system-information
@lisp
(system-information)
@end lisp
Invokes the UNIX system call @code{uname()} and returns 5 values:
system-name, node-name, OS release, OS version and machine.
@end deffn




@node Setting a files buffering mode
@subsection Setting a files buffering mode



@deffn {procedure} set-buffering-mode!
@lisp
(set-buffering-mode! PORT MODE [BUFSIZE])
@end lisp
Sets the buffering-mode for the file associated with @code{PORT} to
@code{MODE}, which should be one of the keywords @code{#:full,
#:line} or @code{#:none}. If @code{BUFSIZE} is specified it
determines the size of the buffer to be used (if any).
@end deffn




@node Terminal ports
@subsection Terminal ports



@deffn {procedure} terminal-name
@lisp
(terminal-name PORT)
@end lisp
Returns the name of the terminal that is connected to @code{PORT}.

@end deffn
@deffn {procedure} terminal-port?
@lisp
(terminal-port? PORT)
@end lisp
Returns @code{#t} if @code{PORT} is connected to a terminal and
@code{#f} otherwise.
@end deffn




@node How Scheme procedures relate to UNIX C functions
@subsection How Scheme procedures relate to UNIX C functions

@c XXX Is there a better way to get rid of the  ?

@table @code
@item change-directory
chdir
@item change-file-mode
chmod
@item change-file-owner
chown
@item create-directory
mkdir
@item create-fifo
mkfifo
@item create-pipe
pipe
@item create-symbolic-link
link
@item current-directory
curdir
@item current-effective-groupd-id
getegid
@item current-effective-user-id
geteuid
@item current-group-id
getgid
@item current-parent-id
getppid
@item current-process-id
getpid
@item current-user-id
getuid
@item delete-directory
rmdir
@item duplicate-fileno
dup/dup2
@item _exit
_exit
@item file-close
close
@item file-execute-access?
access
@item file-open
open
@item file-lock
fcntl
@item file-position
ftell/lseek
@item file-read
read
@item file-read-access?
access
@item file-select
select
@item file-test-lock
fcntl
@item file-truncate
truncate/ftruncate
@item file-unlock
fcntl
@item file-write
write
@item file-write-access?
access
@item get-groups
getgroups
@item get-host-name
gethostname
@item initialize-groups
initgroups
@item map-file-to-memory
mmap
@item open-input-file*
fdopen
@item open-output-file*
fdopen
@item open-input-pipe
popen
@item open-output-pipe
popen
@item port->fileno
fileno
@item process-execute
execvp
@item process-fork
fork
@item process-signal
kill
@item process-wait
waitpid
@item close-input-pipe
pclose
@item close-output-pipe
pclose
@item read-symbolic-link
readlink
@item seconds->local-time
localtime
@item seconds->string
ctime
@item seconds->utc-time
gmtime
@item set-alarm!
alarm
@item set-buffering-mode!
setvbuf
@item set-file-position!
fseek/seek
@item set-groups!
setgroups
@item set-signal-mask!
sigprocmask
@item set-user-id!
setuid
@item setenv
setenv/putenv
@item sleep
sleep
@item system-information
uname
@item terminal-name
ttyname
@item terminal-port?
isatty
@item time->string
asctime
@item unsetenv
putenv
@item unmap-file-from-memory
munmap
@item user-information
getpwnam/getpwuid
@end table


@node Unit utils
@section Unit utils

This unit contains some utility procedures for Shell scripting and for
some file operations.

This unit uses the @code{extras} and @code{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::
@end menu

@node Pathname operations
@subsection Pathname operations




@deffn {procedure} absolute-pathname?
@lisp
(absolute-pathname? PATHNAME)
@end lisp
Returns @code{#t} if the string @code{PATHNAME} names an absolute
pathname, and returns @code{#f} otherwise.

@end deffn
@deffn {procedure} decompose-pathname
@lisp
(decompose-pathname PATHNAME)
@end lisp
Returns three values: the directory-, filename- and extension-components
of the file named by the string @code{PATHNAME}. For any component
that is not contained in @code{PATHNAME}, @code{#f} is returned.

@end deffn
@deffn {procedure} make-pathname
@deffnx {procedure} make-absolute-pathname
@lisp
(make-pathname DIRECTORY FILENAME [EXTENSION])
(make-absolute-pathname DIRECTORY FILENAME [EXTENSION])
@end lisp
Returns a string that names the file with the
components @code{DIRECTORY, FILENAME} and (optionally)
@code{EXTENSION}. @code{DIRECTORY} can be @code{#f} (meaning no
directory component), a string or a list of strings. @code{FILENAME}
and @code{EXTENSION} should be strings or @code{#f}.
@code{make-absolute-pathname} returns always an absolute pathname.
@end deffn

@deffn {procedure} pathname-directory
@lisp
(pathname-directory PATHNAME)
@end lisp
@end deffn
@deffn {procedure} pathname-file
@lisp
(pathname-file PATHNAME)
@end lisp
@end deffn
@deffn {procedure} pathname-extension
@lisp
(pathname-extension PATHNAME)
@end lisp
Accessors for the components of @code{PATHNAME}. If the pathname does
not contain the accessed component, then @code{#f} is returned.

@end deffn
@deffn {procedure} pathname-replace-directory
@lisp
(pathname-replace-directory PATHNAME DIRECTORY)
@end lisp
@end deffn
@deffn {procedure} pathname-replace-file
@lisp
(pathname-replace-file PATHNAME FILENAME)
@end lisp
@end deffn
@deffn {procedure} pathname-replace-extension
@lisp
(pathname-replace-extension PATHNAME EXTENSION)
@end lisp
Return a new pathname with the specified component of @code{PATHNAME}
replaced by a new value.

@end deffn
@deffn {procedure} pathname-strip-directory
@lisp
(pathname-strip-directory PATHNAME)
@end lisp
@end deffn
@deffn {procedure} pathname-strip-extension
@lisp
(pathname-strip-extension PATHNAME)
@end lisp
Return a new pathname with the specified component of @code{PATHNAME}
stripped.
@end deffn




@node Temporary files
@subsection Temporary files



@deffn {procedure} create-temporary-file
@lisp
(create-temporary-file [EXTENSION])
@end lisp
Creates an empty temporary file and returns its pathname. If
@code{EXTENSION} is not given, then @code{.tmp} is used. If the
environment variable @code{TMPDIR, TEMP} or @code{TMP} is set,
then the pathname names a file in that directory.

@end deffn



@node Deleting a file without signalling an error
@subsection Deleting a file without signalling an error



@deffn {procedure} delete-file*
@lisp
(delete-file* FILENAME)
@end lisp
If the file @code{FILENAME} exists, it is deleted and @code{#t}
is returned.  If the file does not exist, nothing happens and @code{#f}
is returned.
@end deffn




@node Iterating over input lines and files
@subsection Iterating over input lines and files



@deffn {procedure} for-each-line
@lisp
(for-each-line PROCEDURE [PORT])
@end lisp
Calls @code{PROCEDURE} for each line read from @code{PORT} (which defaults to the
value of @code{(current-input-port)}. The argument passed to @code{PORCEDURE}
is a string with the contents of the line, excluding any line-terminators.
When all input has been read from the port, @code{for-each-line} returns some unspecified value.

@end deffn
@deffn {procedure} for-each-argv-line
@lisp
(for-each-argv-line PROCEDURE)
@end lisp
 Opens each file listed on the command line in order, passing one line
at a time into @code{PROCEDURE}.  The filename @code{-} is interpreted as
@code{(current-input-port)}.  If no arguments are given on the command line
it again uses the value of @code{(current-input-port)}.

This code will act as a simple Unix cat(1) command:
 
@verbatim
(for-each-argv-line print)
@end verbatim
@end deffn




@node Executing shell commands with formatstring and error checking
@subsection Executing shell commands with formatstring and error checking



@deffn {procedure} system*
@lisp
(system* FORMATSTRING ARGUMENT1 ...)
@end lisp
Similar to @code{(system (sprintf FORMATSTRING ARGUMENT1 ...))},
but signals an error if the invoked program should return a nonzero
exit status.
@end deffn


@node Reading a file's contents
@subsection Reading a file's contents


@deffn {procedure} read-all
@lisp
(read-all [FILE-OR-PORT])
@end lisp
If @code{FILE-OR-PORT} is a string, then this procedure returns the contents of the file
as a string. If @code{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 @code{(current-input-port)}.
@end deffn


@node Unit tcp
@section 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 @code{extras} unit.

All errors related to failing network operations will raise a condition
of kind @code{(exn i/o network)}.



@deffn {procedure} tcp-listen
@lisp
(tcp-listen TCPPORT [BACKLOG [HOST]])
@end lisp
Creates and returns a TCP listener object that listens for connections on @code{TCPPORT}, which
should be an exact integer. @code{BACKLOG} specifies the number of maximally pending
connections (and defaults to 4). If the optional argument @code{HOST} is given and not
@code{#f}, then only incoming connections for the given host (or IP) are accepted.

@end deffn
@deffn {procedure} tcp-listener?
@lisp
(tcp-listener? X)
@end lisp
Returns @code{#t} if @code{X} is a TCP listener object, or @code{#f} otherwise.

@end deffn
@deffn {procedure} tcp-close
@lisp
(tcp-close LISTENER)
@end lisp
Reclaims any resources associated with @code{LISTENER}.

@end deffn
@deffn {procedure} tcp-accept
@lisp
(tcp-accept LISTENER)
@end lisp
Waits until a connection is established on the port on which @code{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.

@end deffn
@deffn {procedure} tcp-accept-ready?
@lisp
(tcp-accept-ready? LISTENER)
@end lisp
Returns @code{#t} if there are any connections pending on @code{LISTENER}, or @code{#f}
otherwise.

@end deffn
@deffn {procedure} tcp-listener-port
@lisp
(tcp-listener-port LISTENER)
@end lisp
Returns the port number assigned to @code{LISTENER} (If you pass @code{0} to @code{tcp-listen},
then the system will choose a port-number for you).

@end deffn
@deffn {procedure} tcp-connect
@lisp
(tcp-connect HOSTNAME [TCPPORT])
@end lisp
Establishes a client-side TCP connection to the machine with the name @code{HOSTNAME} (a string)
at @code{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.

@end deffn
@deffn {procedure} tcp-addresses
@lisp
(tcp-addresses PORT)
@end lisp
Returns two values for the input- or output-port @code{PORT} (which should be a port returned
by either @code{tcp-accept} or @code{tcp-connect}): the IP address of the local and the remote
machine that are connected over the socket associated with @code{PORT}. The returned addresses
are strings in @code{XXX.XXX.XXX.XXX} notation.

@end deffn
@deffn {procedure} tcp-abandon-port
@lisp
(tcp-abandon-port PORT)
@end lisp
Marks the socket port @code{PORT} as abandoned. This is mainly useful to close down a port
without breaking the connection.
@end deffn



A very simple example follows. Say we have the two files @code{client.scm}
and @code{server.scm}:

@verbatim
; client.scm
(define-values (i o) (tcp-connect "localhost" 4242))
(write-line "Good Bye!" o)
(print (read-line i))
@end verbatim

@verbatim
; 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!
@end verbatim


@node Unit srfi-37
@section 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 @code{-X[ARGUMENT]}
or long multicharacter ones of the form @code{--XXX[=ARGUMENT]}. Short
options may be coalesced. An argument of the form @code{--} stops
option processing.
For more information take a look at the @uref{http://srfi.schemers.org/srfi-37/srfi-37.html, SRFI-37 documentation }.

An example:

@verbatim
#!/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))
@end verbatim


@node Unit lolevel
@section Unit lolevel


This unit provides a number of handy low-level operations. @b{Use
at your own risk.}


This unit uses the @code{srfi-4} and @code{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::                       
@end menu

@node Foreign pointers
@subsection Foreign pointers




@deffn {procedure} address->pointer
@lisp
(address->pointer ADDRESS)
@end lisp
Creates a new foreign pointer object initialized to point to the address
given in the integer @code{ADDRESS}.

@end deffn
@deffn {procedure} allocate
@lisp
(allocate BYTES)
@end lisp
Returns a pointer to a freshly allocated region of static memory.
This procedure could be defined as follows:

@verbatim
(define allocate (foreign-lambda c-pointer "malloc" integer))
@end verbatim

@end deffn
@deffn {procedure} free
@lisp
(free POINTER)
@end lisp
Frees the memory pointed to by @code{POINTER}.  This procedure could
be defined as follows:

@verbatim
(define free (foreign-lambda c-pointer "free" integer))
@end verbatim

@end deffn
@deffn {procedure} null-pointer
@lisp
(null-pointer)
@end lisp
Another way to say @code{(address->pointer 0)}.

@end deffn
@deffn {procedure} null-pointer?
@lisp
(null-pointer? PTR)
@end lisp
Returns @code{#t} if @code{PTR} contains a @code{NULL} pointer,
or @code{#f} otherwise.

@end deffn
@deffn {procedure} object->pointer
@lisp
(object->pointer X)
@end lisp
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.

@end deffn
@deffn {procedure} pointer?
@lisp
(pointer? X)
@end lisp
Returns @code{#t} if @code{X} is a foreign pointer object, and
@code{#f} otherwise.

@end deffn
@deffn {procedure} pointer->address
@lisp
(pointer->address PTR)
@end lisp
Returns the address, to which the pointer @code{PTR} points.

@end deffn
@deffn {procedure} pointer->object
@lisp
(pointer->object PTR)
@end lisp
Returns the Scheme object pointed to by the pointer @code{PTR}.

@end deffn
@deffn {procedure} pointer-offset
@lisp
(pointer-offset PTR N)
@end lisp
Returns a new pointer representing the pointer @code{PTR} increased
by @code{N}.

@end deffn
@deffn {procedure} pointer-u8-ref
@lisp
(pointer-u8-ref PTR)
@end lisp
Returns the unsigned byte at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-s8-ref
@lisp
(pointer-s8-ref PTR)
@end lisp
Returns the signed byte at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-u16-ref
@lisp
(pointer-u16-ref PTR)
@end lisp
Returns the unsigned 16-bit integer at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-s16-ref
@lisp
(pointer-s16-ref PTR)
@end lisp
Returns the signed 16-bit integer at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-u32-ref
@lisp
(pointer-u32-ref PTR)
@end lisp
Returns the unsigned 32-bit integer at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-s32-ref
@lisp
(pointer-s32-ref PTR)
@end lisp
Returns the signed 32-bit integer at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-f32-ref
@lisp
(pointer-f32-ref PTR)
@end lisp
Returns the 32-bit float at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-f64-ref
@lisp
(pointer-f64-ref PTR)
@end lisp
Returns the 64-bit double at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-u8-set!
@lisp
(pointer-u8-set! PTR N)
@end lisp
Stores the unsigned byte @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-s8-set!
@lisp
(pointer-s8-set! PTR N)
@end lisp
Stores the signed byte @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-u16-set!
@lisp
(pointer-u16-set! PTR N)
@end lisp
Stores the unsigned 16-bit integer @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-s16-set!
@lisp
(pointer-s16-set! PTR N)
@end lisp
Stores the signed 16-bit integer @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-u32-set!
@lisp
(pointer-u32-set! PTR N)
@end lisp
Stores the unsigned 32-bit integer @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-s32-set!
@lisp
(pointer-s32-set! PTR N)
@end lisp
Stores the 32-bit integer @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-f32-set!
@lisp
(pointer-f32-set! PTR N)
@end lisp
Stores the 32-bit floating-point number @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} pointer-f64-set!
@lisp
(pointer-f64-set! PTR N)
@end lisp
Stores the 64-bit floating-point number @code{N} at the address designated by @code{PTR}.

@end deffn
@deffn {procedure} align-to-word
@lisp
(align-to-word PTR-OR-INT)
@end lisp
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.
@end deffn




@node Tagged pointers
@subsection Tagged pointers

``Tagged'' pointers are foreign pointer objects with an extra tag object.



@deffn {procedure} tag-pointer
@lisp
(tag-pointer PTR TAG)
@end lisp
Creates a new tagged pointer object from the foreign pointer @code{PTR} with the
tag @code{TAG}, which may an arbitrary Scheme object.

@end deffn
@deffn {procedure} tagged-pointer?
@lisp
(tagged-pointer? X TAG)
@end lisp
Returns @code{#t}, if @code{X} is a tagged pointer object with the tag @code{TAG}
(using an @code{eq?} comparison), or @code{#f} otherwise.

@end deffn
@deffn {procedure} pointer-tag
@lisp
(pointer-tag PTR)
@end lisp
If @code{PTR} is a tagged pointer object, its tag is returned. If @code{PTR} is a normal,
untagged foreign pointer object @code{#f} is returned. Otherwise an error is signalled.
@end deffn




@node Extending procedures with data
@subsection Extending procedures with data




@deffn {procedure} extend-procedure
@lisp
(extend-procedure PROCEDURE X)
@end lisp
Returns a copy of the procedure @code{PROCEDURE} which contains an
additional data slot initialized to @code{X}. If @code{PROCEDURE}
is already an extended procedure, then its data slot is changed to
contain @code{X} and the same procedure is returned.

@end deffn
@deffn {procedure} extended-procedure?
@lisp
(extended-procedure? PROCEDURE)
@end lisp
Returns @code{#t} if @code{PROCEDURE} is an extended procedure,
or @code{#f} otherwise.

@end deffn
@deffn {procedure} procedure-data
@lisp
(procedure-data PROCEDURE)
@end lisp
Returns the data object contained in the extended procedure
@code{PROCEDURE}.

@end deffn
@deffn {procedure} set-procedure-data!
@lisp
(set-procedure-data! PROCEDURE X)
@end lisp
Changes the data object contained in the extended procedure
@code{PROCEDURE} to @code{X}.

@verbatim
(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
@end verbatim
@end deffn




@node Bytevectors
@subsection Bytevectors




@deffn {procedure} byte-vector
@lisp
(byte-vector FIXNUM ...)
@end lisp
Returns a freshly allocated byte-vector with @code{FIXNUM ...} as its
initial contents.

@end deffn
@deffn {procedure} byte-vector?
@lisp
(byte-vector? X)
@end lisp
Returns @code{#t} if @code{X} is a byte-vector object, or
@code{#f} otherwise.

@end deffn
@deffn {procedure} byte-vector-fill!
@lisp
(byte-vector-fill! BYTE-VECTOR N)
@end lisp
Sets each element of @code{BYTE-VECTOR} to @code{N}, which should
be an exact integer.

@end deffn
@deffn {procedure} byte-vector->list
@lisp
(byte-vector->list BYTE-VECTOR)
@end lisp
Returns a list with elements taken from @code{BYTE-VECTOR}.

@end deffn
@deffn {procedure} byte-vector->string
@lisp
(byte-vector->string BYTE-VECTOR)
@end lisp
Returns a string with the contents of @code{BYTE-VECTOR}.

@end deffn
@deffn {procedure} byte-vector-length
@lisp
(byte-vector-length BYTE-VECTOR)
@end lisp
Returns the number of elements in @code{BYTE-VECTOR}.

@end deffn
@deffn {procedure} byte-vector-ref
@lisp
(byte-vector-ref BYTE-VECTOR INDEX)
@end lisp
Returns the byte at the @code{INDEX}th position of @code{BYTE-VECTOR}.

@end deffn
@deffn {procedure} byte-vector-set!
@lisp
(byte-vector-set! BYTE-VECTOR INDEX N)
@end lisp
Sets the byte at the @code{INDEX}th position of @code{BYTE-VECTOR}
to the value of the exact integer @code{n}.

@end deffn
@deffn {procedure} executable-byte-vector->procedure
@lisp
(executable-byte-vector->procedure PBYTE-VECTOR)
@end lisp
Returns a procedure that on invocation will execute the code
in @code{PBYTE-VECTOR}, which should have been allocated using
@code{make-executable-byte-vector}.  The procedure follows the native C
calling convention, and will be called as if declared with the following
prototype:

@verbatim
void <procedure>(int argc, C_word closure, C_word k, C_word arg1, ...)
@end verbatim

@itemize
@item @code{argc} contains the number of arguments @code{arg1, ...}
that are passed plus 2 (including @code{closure} and @code{k}).

@item @code{closure} is the procedure object itself.

@item @code{k} is a continuation closure that should be called when
the code is about to return.

@verbatim
typedef void (*CONTINUATION)(int argc, C_word closure,
                                       C_word result);
((CONTINUATION)k[ 1 ])(2, k, result)
@end verbatim

(@code{k} is a data object with the second word being the actual code
pointer)

@end itemize


An example:

@verbatim
(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
@end verbatim


The result of calling @code{executable-byte-vector->procedure} with
a non-executable statically allocated byte-vector is undefined.

@end deffn
@deffn {procedure} invoke-executable-byte-vector
@lisp
(invoke-executable-byte-vector PBYTE-VECTOR ARG1 ...)
@end lisp
Invokes the machine code stored in the executable byte-vector
@code{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 @code{ARG1 ...}.

@verbatim
(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!"
@end verbatim

@end deffn
@deffn {procedure} list->byte-vector
@lisp
(list->byte-vector LIST)
@end lisp
Returns a byte-vector with elements taken from @code{LIST}, where the
elements of @code{LIST} should be exact integers.

@end deffn
@deffn {procedure} make-byte-vector
@lisp
(make-byte-vector SIZE [INIT])
@end lisp
Creates a new byte-vector of size @code{SIZE}. If @code{INIT} is
given, then it should be an exact integer with which every element of
the byte-vector is initialized.

@end deffn
@deffn {procedure} make-executable-byte-vector
@lisp
(make-executable-byte-vector SIZE [INIT])
@end lisp
As @code{make-static-byte-vector}, but the code is suitable for
execution.  @b{Note:} this feature is currently only available on
@b{x86} platforms.

Exceptions: @code{(exn bounds)}, @code{(exn runtime)}

@end deffn
@deffn {procedure} make-static-byte-vector
@lisp
(make-static-byte-vector SIZE [INIT])
@end lisp
As @code{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 @code{object-release} explicitly.

Exceptions: @code{(exn bounds)}, @code{(exn runtime)}

@end deffn
@deffn {procedure} static-byte-vector->pointer
@lisp
(static-byte-vector->pointer PBYTE-VECTOR)
@end lisp
Returns a pointer object pointing to the data in the statically allocated
byte-vector @code{PBYTE-VECTOR}.

@end deffn
@deffn {procedure} string->byte-vector
@lisp
(string->byte-vector STRING)
@end lisp
Returns a byte-vector with the contents of @code{STRING}.
@end deffn




@node Data in unmanaged memory
@subsection Data in unmanaged memory




@deffn {procedure} object-evict
@lisp
(object-evict X [ALLOCATOR])
@end lisp
Copies the object @code{X} recursively into the memory pointed
to by the foreign pointer object returned by @code{ALLOCATOR},
which should be a procedure of a single argument (the number of bytes
to allocate). The freshly copied object is returned.  This facility
allows moving arbitrary objects into static memory, but care should be
taken when mutating evicted data: setting slots in evicted vector-like
objects to non-evicted data is not allowed. It @b{is} possible to
set characters/bytes in evicted strings or byte-vectors, though.  It is
advisable @b{not} to evict ports, because they might be mutated by
certain file-operations.  @code{object-evict} is able to handle circular and
shared structures, but evicted symbols are no longer unique: a fresh
copy of the symbol is created, so

@verbatim
(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
@end verbatim

The @code{ALLOCATOR} defaults to @code{allocate}.

@end deffn
@deffn {procedure} object-evict-to-location
@lisp
(object-evict-to-location X PTR [LIMIT])
@end lisp
As @code{object-evict} but moves the object at the address pointed to by
the machine pointer @code{PTR}. If the number of copied bytes exceeds
the optional @code{LIMIT} then an error is signalled. Two values are
returned: the evicted object and a new pointer pointing to the first
free address after the evicted object.

@end deffn
@deffn {procedure} object-evicted?
@lisp
(object-evicted? X)
@end lisp
Returns @code{#t} if @code{X} is a non-immediate evicted data object,
or @code{#f} otherwise.

@end deffn
@deffn {procedure} object-size
@lisp
(object-size X)
@end lisp
Returns the number of bytes that would be needed to evict the data
object @code{X}.

@end deffn
@deffn {procedure} object-release
@lisp
(object-release X [RELEASER])
@end lisp
Frees memory occupied by the evicted object @code{X} recursively.
@code{RELEASER} should be a procedure of a single argument (a foreign
pointer object to the static memory to be freed) and defaults to the
C-library @code{free()}.

@end deffn
@deffn {procedure} object-unevict
@lisp
(object-unevict X)
@end lisp
Copies the object @code{X} and nested objects back into the normal
Scheme heap.  Symbols are re-interned into the symbol table. Strings
and byte-vectors are @b{not} copied.
@end deffn




@node Locatives
@subsection Locatives


A @emph{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
@code{location->object} procedure.

Locatives may be passed to foreign procedures that expect pointer arguments.
The effect of creating locatives for evicted data (see @code{object-evict}) is undefined.



@deffn {procedure} make-locative
@lisp
(make-locative EXP [INDEX])
@end lisp
Creates a locative that refers to the element of the non-immediate object @code{EXP}
at position @code{INDEX}. @code{EXP} may be a vector, symbol, pair, string, byte-vector,
SRFI-4 number-vector, SRFI-25 array, or record. @code{INDEX} should be a fixnum,
or a valid index into
a SRFI-25 array. @code{INDEX} defaults to 0.

@end deffn
@deffn {procedure} make-weak-locative
@lisp
(make-weak-locative EXP [INDEX])
@end lisp
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.

@end deffn
@deffn {procedure} locative?
@lisp
(locative? X)
@end lisp
Returns @code{#t} if @code{X} is a locative, or @code{#f} otherwise.

@end deffn
@deffn {procedure} locative-ref
@lisp
(locative-ref LOC)
@end lisp
Returns the element to which the locative @code{LOC} refers. If the containing
object has been reclaimed by garbage collection, an error is signalled.

@end deffn
@deffn {procedure} locative-set!
@lisp
(locative-set! LOC X)
@end lisp
Changes the element to which the locative @code{LOC} refers to @code{X}.
If the containing
object has been reclaimed by garbage collection, an error is signalled.

@end deffn
@deffn {procedure} locative->object
@lisp
(locative->object LOC)
@end lisp
Returns the object that contains the element referred to by @code{LOC} or
@code{#f} if the container has been reclaimed by garbage collection.
@end deffn




@node Accessing toplevel variables
@subsection Accessing toplevel variables




@deffn {procedure} global-bound?
@lisp
(global-bound? SYMBOL)
@end lisp
Returns @code{#t}, if the global (``toplevel'') variable with the name @code{SYMBOL}
is bound to a value, or @code{#f} otherwise.

@end deffn
@deffn {procedure} global-ref
@lisp
(global-ref SYMBOL)
@end lisp
Returns the value of the global variable @code{SYMBOL}.
If no variable under that name is bound, an error is signalled.

@end deffn
@deffn {procedure} global-set!
@lisp
(global-set! SYMBOL X)
@end lisp
Sets the global variable named @code{SYMBOL} to the value @code{X}.
@end deffn




@node Low-level data access
@subsection Low-level data access



@deffn {procedure} block-ref
@lisp
(block-ref BLOCK INDEX)
@end lisp
Returns the contents of the @code{INDEX}th slot of the object
@code{BLOCK}.  @code{BLOCK} may be a vector, record structure,
pair or symbol.

@end deffn
@deffn {procedure} block-set!
@lisp
(block-set! BLOCK INDEX X)
@end lisp
Sets the contents of the @code{INDEX}th slot of the object
@code{BLOCK} to the value of @code{X}.  @code{BLOCK} may be a
vector, record structure, pair or symbol.

@end deffn
@deffn {procedure} object-copy
@lisp
(object-copy X)
@end lisp
Copies @code{X} recursively and returns the fresh copy. Objects
allocated in static memory are copied back into garbage collected storage.

@end deffn
@deffn {procedure} make-record-instance
@lisp
(make-record-instance SYMBOL ARG1 ...)
@end lisp
Returns a new instance of the record type @code{SYMBOL}, with its
slots initialized to @code{ARG1 ...}.  To illustrate:

@verbatim
(define-record point x y)
@end verbatim

expands into something quite similar to:

@verbatim
(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)) )
@end verbatim

@end deffn
@deffn {procedure} move-memory!
@lisp
(move-memory! FROM TO [BYTES])
@end lisp
Copies @code{BYTES} bytes of memory from @code{FROM} to @code{TO}.
@code{FROM} and @code{TO} may be strings, primitive byte-vectors,
SRFI-4 byte-vectors (see: @ref{Unit srfi-4}), memory mapped files, foreign
pointers (as obtained from a call to @code{foreign-lambda}, for
example) or locatives. if @code{BYTES} is not given and the size of the source
or destination operand is known then the maximal number of bytes will
be copied. Moving memory to the storage returned by locatives will cause havoc, 
if the locative refers to containers of non-immediate data, like vectors
or pairs.

@end deffn
@deffn {procedure} number-of-bytes
@lisp
(number-of-bytes BLOCK)
@end lisp
Returns the number of bytes that the object @code{BLOCK} contains.
@code{BLOCK} may be any non-immediate value.

@end deffn
@deffn {procedure} number-of-slots
@lisp
(number-of-slots BLOCK)
@end lisp
Returns the number of slots that the object @code{BLOCK} contains.
@code{BLOCK} may be a vector, record structure, pair or symbol.

@end deffn
@deffn {procedure} record-instance?
@lisp
(record-instance? X)
@end lisp
Returns @code{#t} if @code{X} is an instance of a record type.
See also: @code{make-record-instance}.
@end deffn

@deffn {procedure} record->vector
@lisp
(record->vector BLOCK)
@end lisp
Returns a new vector with the type and the elements of the record @code{BLOCK}.
@end deffn


@node Procedure-call- and variable reference hooks
@subsection Procedure-call- and variable reference hooks



@deffn {procedure} invalid-procedure-call-handler
@lisp
(invalid-procedure-call-handler PROC)
@end lisp
Sets an internal hook that is invoked when a call to an object other than a procedure
is executed at runtime. The procedure @code{PROC} will in that case be called
with two arguments: the object being called and a list of the passed arguments.

@verbatim
;;; 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
@end verbatim

This facility does not work in code compiled with the ``unsafe'' setting.

@end deffn
@deffn {procedure} unbound-variable-value
@lisp
(unbound-variable-value [X])
@end lisp
Defines the value that is returned for unbound variables. Normally an error
is signalled, use this procedure to override the check and return @code{X}
instead. To set the default behavior (of signalling an error), call
@code{unbound-variable-value} with no arguments.

This facility does not work in code compiled with the ``unsafe'' setting.
@end deffn




@node Magic
@subsection Magic



@deffn {procedure} object-become!
@lisp
(object-become! ALIST)
@end lisp
Changes the identity of the value of the car of each pair in
@code{ALIST} to the value of the cdr. Both values may not be immediate
(i.e. exact integers, characters, booleans or the empty list).

@verbatim
(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
@end verbatim

Note: this operation invokes a major garbage collection.

The effect of using @code{object-become!} on evicted data (see @code{object-evict})
is undefined.
@end deffn




@node Unit tinyclos
@section Unit tinyclos

This unit is a port of Gregor Kiczales @b{TinyCLOS} with numerous
modifications.

This unit uses the @code{extras} unit.


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

@node Defining forms
@subsection Defining forms




@deffn {syntax} define-class
@lisp
(define-class NAME (SUPERCLASS1 ...) (SLOTNAME1 ...) [METACLASS])
@end lisp
Sets the variable @code{NAME} to a new class (a new instance of
the class @code{<class>}). @code{SUPERCLASS1 ...} is a list of
superclasses of the newly created class. If no superclasses are given,
then @code{<object>} is assumed.  @code{SLOTNAME1 ...} are the names
of the direct slots of the class. if @code{METACLASS} is provided,
then the new class-instance is an instance of @code{METACLASS} instead
of @code{<class>}.

@verbatim
(define-class NAME (SUPER) (SLOT1 SLOT2) META)
@end verbatim 

is equivalent to

@verbatim
(define NAME
  (make META 
    'name 'NAME
    'direct-supers (list SUPER)
    'direct-slots (list 'SLOT1 'SLOT2)) )
@end verbatim

Note that slots-names are not required to be symbols, so the following
is perfectly valid:

@ifhtml
@html
<pre>
(define hidden-slot (list 'hidden))
(define &lt;myclass&gt;
  (make &lt;class&gt;
     'direct-supers (list &lt;object&gt;)
     'direct-slots (list hidden-slot) ) )
(define x1 (make &lt;myclass&gt;)
(slot-set! x1 hidden-slot 99)
@end html
@end ifhtml

@ifnothtml
@verbatim
(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)
@end verbatim
@end ifnothtml

@end deffn
@deffn {syntax} define-generic
@lisp
(define-generic NAME [CLASS])
@end lisp
Sets the variable @code{NAME} to contain a fresh generic function
object without associated methods. If the optional argument @code{CLASS}
is given, then the generic function will be an instance of that class.

@end deffn
@deffn {syntax} define-method
@lisp
(define-method (NAME (VARIABLE1 CLASS1) ... PARAMETERS ...) BODY ...)
@end lisp
Adds a new method with the code @code{BODY ...} to the generic function
that was assigned to the variable @code{name}.  @code{CLASS1 ...} is
a list if classes that specialize this particular method. The method can
have additional parameters @code{PARAMETERS}, which do not specialize
the method any further.  Inside the body of the method the identifier
@code{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 @code{NAME}.
Note that only @code{define-generic} expands into a valid definition,
so for internal lexically scoped definitions or for definitions for module
exports (see @code{syntax-case}) use @code{define-generic}.
@end deffn




@node Base language
@subsection Base language




@deffn {procedure} add-method
@lisp
(add-method GENERIC METHOD)
@end lisp
Adds the method object @code{METHOD} to the list of applicable methods
for the generic function @code{GENERIC}.

@end deffn
@deffn {procedure} instance?
@lisp
(instance? X)
@end lisp
Returns @code{#t} if @code{X} is an instance of a non-primitive
class.

@end deffn
@deffn {procedure} make
@lisp
(make CLASS INITARG ...)
@end lisp
Creates a new instance of @code{CLASS} and passes @code{INITARG ...}
to the @code{initialize} method of this class.

@end deffn
@deffn {procedure} make-class
@lisp
(make-class SUPERCLASSES SLOTNAMES)
@end lisp
Creates a new class object, where @code{SUPERCLASSES} should be the
list of direct superclass objects and @code{SLOTNAMES} should be a
list of symbols naming the slots of this class.

@end deffn
@deffn {procedure} make-generic
@lisp
(make-generic [NAME])
@end lisp
Creates a new generic function object. If @code{NAME} is specified,
then it should be a string.

@end deffn
@deffn {procedure} make-method
@lisp
(make-method SPECIALIZERS PROC)
@end lisp
Creates a new method object specialized to the list of classes in
@code{SPECIALIZERS}.

@verbatim
(define-method (foo (x <bar>)) 123)
   <=> (add-method foo
                   (make-method
                      (list <bar>)
                      (lambda (call-next-method x) 123)))
@end verbatim

@end deffn
@deffn {procedure} slot-ref
@lisp
(slot-ref INSTANCE SLOTNAME)
@end lisp
Returns the value of the slot @code{SLOTNAME} of the object
@code{INSTANCE}.

@end deffn
@deffn {procedure} slot-set!
@lisp
(slot-set! INSTANCE SLOTNAME VALUE)
@end lisp
Sets the value of the slot @code{SLOTNAME} of the object
@code{INSTANCE} to @code{VALUE}.
@end deffn




@node Introspection
@subsection Introspection




@deffn {procedure} class-cpl
@lisp
(class-cpl CLASS)
@end lisp
Returns the class-precedence-list of @code{CLASS} as a list of classes.

@end deffn
@deffn {procedure} class-direct-slots
@lisp
(class-direct-slots CLASS)
@end lisp
Returns the list of direct slots of @code{CLASS} as a list of lists,
where each sublist contains the name of the slot.

@end deffn
@deffn {procedure} class-direct-supers
@lisp
(class-direct-supers CLASS)
@end lisp
Returns the list of direct superclasses of @code{CLASS}.

@end deffn
@deffn {procedure} class-of
@lisp
(class-of X)
@end lisp
Returns the class that the object @code{X} is an instance of.

@end deffn
@deffn {procedure} class-name
@lisp
(class-name CLASS)
@end lisp
Returns name of @code{CLASS}.

@end deffn
@deffn {procedure} class-slots
@lisp
(class-slots CLASS)
@end lisp
Returns the list of all slots of @code{CLASS} and its superclasses
as a list of lists, where each sublist contains the name of the slot.

@end deffn
@deffn {procedure} generic-methods
@lisp
(generic-methods GENERIC)
@end lisp
Returns the list of all methods associated with the generic function
@code{GENERIC}.

@end deffn
@deffn {procedure} method-specializers
@lisp
(method-specializers METHOD)
@end lisp
Returns the list of classes that specialize @code{METHOD}.

@end deffn
@deffn {procedure} method-procedure
@lisp
(method-procedure METHOD)
@end lisp
Returns the procedure that contains the body of @code{METHOD}.

@end deffn
@deffn {procedure} subclass?
@lisp
(subclass? CLASS1 CLASS2)
@end lisp
Returns @code{#t} is @code{CLASS1} is a subclass of @code{CLASS2},
or @code{#f} otherwise. Note that the following holds:

@verbatim
(subclass? X X) ==> #t
@end verbatim
@end deffn




@node Intercessory protocol
@subsection Intercessory protocol

These definitions allow interfacing to the Meta Object Protocol
of TinyCLOS. For serious use, it is recommended to consult
the source code (@code{tinyclos.scm}).



@deffn {generic} allocate-instance
@lisp
(allocate-instance CLASS)
@end lisp
Allocates storage for an instance of @code{CLASS} and returns the
instance.

@end deffn
@deffn {generic} compute-apply-generic
@lisp
(compute-apply-generic GENERIC)
@end lisp
Returns a procedure that will be called to apply the generic function
methods to the arguments.

@end deffn
@deffn {generic} compute-apply-methods
@lisp
(compute-apply-methods GENERIC)
@end lisp
Returns a procedure of two arguments, a list of applicable methods
and a list of arguments and applies the methods.

@end deffn
@deffn {generic} compute-methods
@lisp
(compute-methods GENERIC)
@end lisp
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.

@end deffn
@deffn {generic} compute-cpl
@lisp
(compute-cpl CLASS)
@end lisp
Computes and returns the class-precedence-list of @code{CLASS}.

@end deffn
@deffn {generic} compute-getter-and-setter
@lisp
(compute-getter-and-setter CLASS SLOT ALLOCATOR)
@end lisp
Returns two values, the procedures that get and set the contents of the
slot @code{SLOT}.  @code{ALLOCATOR} is a procedure of one argument
@emph{(I currently don't know what it does)}.

@end deffn
@deffn {generic} compute-method-more-specific?
@lisp
(compute-method-more-specific? GENERIC)
@end lisp
Returns a procedure of three arguments (two methods and a list of
arguments) that returns @code{#t} if the first method is more specific
than the second one with respect to the list of arguments. Otherwise
the returned predicate returns @code{#f}.

@end deffn
@deffn {generic} compute-slots
@lisp
(compute-slots CLASS)
@end lisp
Computes and returns the list of slots of @code{CLASS}.

@end deffn
@deffn {generic} initialize
@lisp
(initialize INSTANCE INITARGS)
@end lisp
Initializes the object @code{INSTANCE}. @code{INITARGS} is the list of
initialization arguments that were passed to the @code{make} procedure.
@end deffn




@node Additional protocol
@subsection Additional protocol




@deffn {generic} describe-object
@lisp
(describe-object INSTANCE PORT)
@end lisp
Writes a description of @code{INSTANCE} to @code{PORT}.  Execution of
the interpreter command @code{,d} will invoke this generic function.

@end deffn
@deffn {generic} print-object
@lisp
(print-object INSTANCE PORT)
@end lisp
Writes a textual representation of @code{INSTANCE} to @code{PORT}.
Any output of an instance with @code{display, write} and @code{print}
will invoke this generic function.
@end deffn




@node Utility procedures
@subsection Utility procedures




@deffn {procedure} initialize-slots
@lisp
(initialize-slots INSTANCE INITARGS)
@end lisp
This procedure takes a sequence of alternating slot-names and
initialization values in @code{INITARGS} and initializes the
corresponding slots in @code{INSTANCE}.

@verbatim
(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))
@end verbatim
@end deffn




@node Builtin classes
@subsection Builtin classes


The class hierarchy of builtin classes looks like this:

@ifhtml
@html
<pre>
&lt;top&gt;
  &lt;object&gt;
    &lt;class&gt;
      &lt;procedure-class&gt;
        &lt;procedure&gt;
        &lt;entity-class&gt;
          &lt;generic&gt;
      &lt;primitive-class&gt;
    &lt;c++-object&gt;
  &lt;primitive&gt;
    &lt;void&gt;
    &lt;boolean&gt;
    &lt;symbol&gt;
    &lt;char&gt;
    &lt;vector&gt;
    &lt;pair&gt;
    &lt;number&gt;
      &lt;integer&gt;
        &lt;exact&gt;
      &lt;inexact&gt;
    &lt;string&gt;
    &lt;port&gt;
      &lt;input-port&gt;
      &lt;output-port&gt;
    &lt;pointer&gt;
      &lt;tagged-pointer&gt;
    &lt;locative&gt;
    &lt;byte-vector&gt;
      &lt;u8vector&gt;
      &lt;s8vector&gt;
      &lt;u16vector&gt;
      &lt;s16vector&gt;
      &lt;u32vector&gt;
      &lt;s32vector&gt;
      &lt;f32vector&gt;
      &lt;f64vector&gt;
    &lt;structure&gt;
      &lt;array&gt;
      &lt;char-set&gt;
      &lt;condition&gt;
      &lt;environment&gt;
      &lt;hash-table&gt;
      &lt;lock&gt;
      &lt;mmap&gt;
      &lt;promise&gt;
      &lt;queue&gt;
      &lt;tcp-listener&gt;
      &lt;time&gt;
    &lt;end-of-file&gt;
@end html
@end ifhtml

@ifnothtml
@verbatim
<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>
    <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>
@end verbatim
@end ifnothtml


@defvr {class} <primitive>           @pointrightarrow{} <top>
The parent class of the classes of all primitive Scheme objects.
@end defvr

@defvr {class} <boolean>             @pointrightarrow{} <primitive>
@defvrx {class} <symbol>              @pointrightarrow{} <primitive>
@defvrx {class} <char>                @pointrightarrow{} <primitive>
@defvrx {class} <vector>              @pointrightarrow{} <primitive>
@defvrx {class} <null>                @pointrightarrow{} <primitive>
@defvrx {class} <pair>                @pointrightarrow{} <primitive>
@defvrx {class} <number>              @pointrightarrow{} <primitive>
@defvrx {class} <integer>             @pointrightarrow{} <primitive>
@defvrx {class} <exact>               @pointrightarrow{} <integer>
@defvrx {class} <inexact>             @pointrightarrow{} <number>
@defvrx {class} <string>              @pointrightarrow{} <primitive>
@defvrx {class} <port>                @pointrightarrow{} <primitive>
@defvrx {class} <environment>         @pointrightarrow{} <structure>
@defvrx {class} <end-of-file>         @pointrightarrow{} <primitive>
@defvrx {class} <input-port>          @pointrightarrow{} <port>
@defvrx {class} <output-port>         @pointrightarrow{} <port>
@defvrx {class} <procedure>           @pointrightarrow{} <procedure-class>
The classes of primitive Scheme objects.
@end defvr

@defvr {class} <byte-vector>          @pointrightarrow{} <primitive>
@defvrx {class} <structure>           @pointrightarrow{} <primitive>
@defvrx {class} <hash-table>          @pointrightarrow{} <structure>
@defvrx {class} <queue>               @pointrightarrow{} <structure>
The classes of extended data types provided by the various library units.
@end defvr

@defvr {class} <class>               @pointrightarrow{} <object>
The parent class of all class objects.
@end defvr

@defvr {class} <entity-class>        @pointrightarrow{} <class>
The parent class of objects that can be invoked as a procedure and have slots.
@end defvr

@defvr {class} <generic>             @pointrightarrow{} <entity-class>
The parent class of generic function objects.
@end defvr

@defvr {class} <method>              @pointrightarrow{} <class>
The parent class of method objects.
@end defvr

@defvr {class} <object>              @pointrightarrow{} <class>
The parent class of all objects.
@end defvr

@defvr {class} <procedure-class>     @pointrightarrow{} <class>
The parent class of objects that can be invoked as a procedure.
@end defvr

@defvr {class} <condition>           @pointrightarrow{} <structure>
Class of condition objects.
@end defvr

@defvr {class} <array>               @pointrightarrow{} <structure>
@defvrx {class} <char-set>            @pointrightarrow{} <structure>
@defvrx {class} <time>                @pointrightarrow{} <structure>
@defvrx {class} <u8vector>            @pointrightarrow{} <byte-vector>
@defvrx {class} <s8vector>            @pointrightarrow{} <byte-vector>
@defvrx {class} <u16vector>           @pointrightarrow{} <byte-vector>
@defvrx {class} <s16vector>           @pointrightarrow{} <byte-vector>
@defvrx {class} <u32vector>           @pointrightarrow{} <byte-vector>
@defvrx {class} <s32vector>           @pointrightarrow{} <byte-vector>
@defvrx {class} <f32vector>           @pointrightarrow{} <byte-vector>
@defvrx {class} <f64vector>           @pointrightarrow{} <byte-vector>
The classes of data objects provided by the various supported SRFIs.
@end defvr

@defvr {class} <lock>                @pointrightarrow{} <structure>
@defvrx {class} <mmap>                @pointrightarrow{} <structure>
Classes of objects used in the @code{posix} library unit.
@end defvr

@defvr {class} <pointer>             @pointrightarrow{} <primitive>
@defvrx {class} <tagged-pointer>      @pointrightarrow{} <pointer>
A machine pointer (untagged, or tagged).
@end defvr

@defvr {class} <locative>            @pointrightarrow{} <primitive>
A locative.
@end defvr

@defvr {class} <promise>             @pointrightarrow{} <structure>
The class of objects returned by @code{delay}.
@end defvr

@defvr {class} <tcp-listener>        @pointrightarrow{} <structure>
The class of an object returned by @code{tcp-listen}.
@end defvr

@defvr {class} <c++-class>           @pointrightarrow{} <object>
The class of generated wrappers for C++ classes parsed by the ``easy''
Foreign Function interface.
@end defvr



The CHICKEN distribution provides several examples in the file
@code{tinyclos-examples.scm}.


@node Interface to external functions and variables
@chapter 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::                 
@end menu

@node Accessing external objects
@section Accessing external objects



@deffn {syntax} foreign-code
@lisp
(foreign-code STRING)
@end lisp
Executes the embedded C/C++ code @code{STRING}, which should
be a sequence of C statements, which are executed and return an unspecified result.

@verbatim
(foreign-code "doSomeInitStuff();")     =>  #<unspecified>
@end verbatim

@end deffn
@deffn {syntax} foreign-value
@lisp
(foreign-value STRING TYPE)
@end lisp
Evaluates the embedded C/C++ expression @code{STRING}, returning a value of type given
in the foreign-type specifier @code{TYPE}.

@verbatim
(print (foreign-value "my_version_string" c-string))
@end verbatim

@end deffn
@deffn {syntax} define-foreign-type
@lisp
(define-foreign-type NAME TYPE [ARGCONVERT [RETCONVERT]])
@end lisp
Defines an alias for @code{TYPE} with the name @code{NAME} (a symbol). 
@code{TYPE} may be a type-specifier
or a string naming a C type. The namespace of foreign type specifiers
is separate from the normal Scheme namespace.  The optional arguments
@code{ARGCONVERT} and @code{RETCONVERT} should evaluate to procedures
that map argument- and result-values to a value that can be transformed
to @code{TYPE}:

@verbatim
(require-extension extras)

(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)
@end verbatim                 

Foreign type-definitions are only visible in the compilation-unit in which
they are defined, so use @code{include} to use the same definitions
in multiple files.

@end deffn
@deffn {syntax} define-foreign-variable
@lisp
(define-foreign-variable NAME TYPE [STRING])
@end lisp
Defines a foreign variable of name @code{NAME} (a symbol). @code{STRING}
should be the real name of a foreign variable or parameterless macro. If
@code{STRING} is not given, then the variable name @code{NAME} will
be converted to a string and used instead. All references and assignments
(via @code{set!}) are modified to correctly convert values between
Scheme and C representation. This foreign variable can only be accessed
in the current compilation unit, but the name can be lexically shadowed.
Note that @code{STRING} can name an arbitrary C expression. If no
assignments are performed, then @code{STRING} doesn't even have to
specify an lvalue.

@verbatim
#>
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
@end verbatim

@end deffn
@deffn {syntax} define-foreign-record
@lisp
(define-foreign-record NAME SLOT ...)
@end lisp
Defines accessor procedures for a C structure definition. @code{NAME} should either be a symbol
or a list of the form @code{(TYPENAME FOREIGNNAME)}. If @code{NAME} is a symbol, then a C declaration
will be generated that defines a C struct named @code{struct NAME}. If @code{NAME} is a list, then
no struct declaration will be generated. 
A foreign-type specifier named @code{NAME} (or @code{TYPENAME}) will be defined as a pointer to
the given C structure.
A @code{SLOT} definition should be a list of one of the following forms:

@verbatim
(TYPE SLOTNAME)
@end verbatim

or

@verbatim
(TYPE SLOTNAME SIZE)
@end verbatim

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:



@deffn {procedure} TYPENAME-SLOTNAME
@lisp
(TYPENAME-SLOTNAME FOREIGN-RECORD-POINTER [INDEX])
@end lisp
A procedure of one argument (a pointer to a C structure), that returns
the slot value of the slot @code{SLOTNAME}. If a @code{SIZE} has been given in the slot definition, then
an additional argument @code{INDEX} is required that specifies the index of an array-element.
@end deffn

@deffn {procedure} TYPENAME-SLOTNAME-set!
@lisp
(TYPENAME-SLOTNAME-set! FOREIGN-RECORD-POINTER [INXDEX] VALUE)
@end lisp
A procedure of two arguments (a pointer to a C structure) and a value, that
sets the slot value of the slot @code{SLOTNAME} in the structure. If a @code{SIZE} has been given in
the slot definition, then an additional argument @code{INDEX} is required for the array index.
@end deffn



If a slot type is of the form @code{(const ...)}, then no setter procedure will be generated.
Slots of the types @code{(struct ...)} or @code{(union ...)} are accessed as pointers to the embedded
struct (or union) and no setter will be generated. 

@end deffn
@deffn {syntax} foreign-callback-lambda
@lisp
(foreign-callback-lambda RETURNTYPE NAME ARGTYPE ...)
@end lisp
This is similar to @code{foreign-lambda}, but also allows the called
function to call Scheme functions. See @ref{Callbacks}.

@end deffn
@deffn {syntax} foreign-callback-lambda*
@lisp
(foreign-callback-lambda* RETURNTYPE ((ARGTYPE VARIABLE)...) STRING ...)
@end lisp
This is similar to @code{foreign-lambda*}, but also allows the called
function to call Scheme functions. See @ref{Callbacks}.

@end deffn
@deffn {syntax} foreign-lambda
@lisp
(foreign-lambda RETURNTYPE NAME ARGTYPE ...)
@end lisp
Represents a
binding to an external routine. This form can be used in the position
of an ordinary @code{lambda} expression. @code{NAME} specifies the
name of the external procedure and should be a string or a symbol.

@end deffn
@deffn {syntax} foreign-lambda*
@lisp
(foreign-lambda* RETURNTYPE ((ARGTYPE VARIABLE) ...) STRING ...)
@end lisp
Similar to @code{foreign-lambda}, but instead of generating code to
call an external function, the body of the C procedure is directly given
in @code{STRING ...}:

@verbatim
(define my-strlen
  (foreign-lambda* int ((c-string str))
    "int n = 0;
     while(*(str++)) ++n;
     return(n);") )

(my-strlen "one two three")             ==> 13
@end verbatim

For obscure technical reasons any use of the @code{return} statement
should enclose the result value in parentheses. For the same reasons
@code{return} without an argument is not allowed.
@end deffn



@node Foreign type specifiers
@section Foreign type specifiers

Here is a list of valid foreign type specifiers:

@table @code

@item scheme-object

An arbitrary Scheme data object (immediate or non-immediate). 

@item bool

As argument: any value (@code{#f} is false, anything else is true).
As result: anything different from 0 and the @code{NULL}-pointer
is @code{#t}.

@item byte unsigned-byte

A byte.

@item char unsigned-char

A character.

@item short unsigned-short

A short integer number.

@item int unsigned-int

An small integer number in fixnum range (at least 30 bit).

@item integer unsigned-integer

Either a fixnum or a flonum in the range of a (unsigned) machine ``int''.

@item long unsigned-long

Either a fixnum or a flonum in the range of a (unsigned) machine ``long''.

@item float double

A floating-point number. If an exact integer is passed as an argument,
then it is automatically converted to a float.

@item pointer

An untyped pointer to the contents of a non-immediate Scheme object
(not allowed as return type).  The value @code{#f} is also allowed
and is passed as a @code{NULL} pointer. 

@item nonnull-pointer

As @code{pointer}, but guaranteed not to be @code{#f}.

@item c-pointer

An untyped operating-system pointer or a locative.  The value @code{#f} is also
allowed and is passed as a @code{NULL} pointer.  If uses as the type of
a return value, a @code{NULL} pointer will be returned as @code{#f}.

@item nonnull-c-pointer

As @code{c-pointer}, but guaranteed not to be @code{#f/NULL}.

@item [nonnull-] byte-vector
A byte-vector object, passed as a pointer to its contents. Arguments
of type @code{byte-vector} may optionally be @code{#f}, which is
passed as a NULL pointer.  This is not allowed as a return type.
@c @end deffn

@item  [nonnull-] u8vector
@itemx [nonnull-] u16vector
@itemx [nonnull-] u32vector
@itemx [nonnull-] s8vector
@itemx [nonnull-] s16vector
@itemx [nonnull-] s32vector
@itemx [nonnull-] f32vector
@itemx [nonnull-] f64vector
A SRFI-4 number-vector object, passed as a pointer to its
contents. Arguments of type @code{byte-vector} may optionally be
@code{#f}, which is passed as a NULL pointer.  These are not allowed
as return types.

@item c-string

A C string (zero-terminated). The value @code{#f}
is also allowed and is passed as a @code{NULL} pointer. If uses as
the type of a return value, a @code{NULL} pointer will be returned as
@code{#f}. 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.

@item nonnull-c-string

As @code{c-string}, but guaranteed not to be @code{#f/NULL}.

@item [nonnull-] c-string*
Similar to @code{[nonnull-]c-string}, but if used as a result-type,
the pointer returned by the foreign code will be freed (using the
C-libraries @code{free()})
after copying.
@c @end deffn

@item void

Specifies an undefined return value. Not allowed as argument type.

@item (const TYPE)

The foreign type @code{TYPE} with an additional @code{const} specifier.

@item (enum NAME)

An enumeration type. Handled internally as an @code{integer}.

@item (pointer TYPE)

@item (c-pointer TYPE)

An operating-system pointer or a locative to an object of @code{TYPE}.

@item (nonnull-pointer TYPE)

@item (nonnull-c-pointer TYPE)

As @code{(pointer TYPE)}, but guaranteed not to be @code{#f/NULL}.

@item (ref TYPE)

A C++ reference type. Reference types are handled the same way as pointers
inside Scheme code.

@item (struct NAME)

A struct of the name @code{NAME}, which should be a string. Structs
can not be directly passed as arguments to foreign function, neither
can they be result values. Pointers to structs are allowed, though.

@item (template TYPE ARGTYPE ...)

A C++ template type. For example @code{vector<int>} would be specified
as @code{(template "vector" int)}. Template types can not be directly passed
as arguments or returned as results.

@item (union NAME)

A union of the name @code{NAME}, which should be a string. Unions can
not be directly passed as arguments to foreign function, neither can
they be result values. Pointers to unions are allowed, though.

@item (instance CNAME SCHEMECLASS)

A pointer to a C++ class instance. @code{CNAME} should designate
the name of the C++ class, and @code{SCHEMECLASS} should be the class
that wraps the instance pointer. Normally @code{SCHEMECLASS}
should be a subclass of @code{<c++-object>}.

@item (function RESULTTYPE (ARGUMENTTYPE1 ... [...]) [CALLCONV])
A function pointer. @code{CALLCONV} specifies an optional calling
convention and should be a string. The meaning of this string is entirely
platform dependent.  The value @code{#f} is also allowed and is passed
as a @code{NULL} pointer.

@end table

Foreign types are mapped to C types in the following manner:

@c % XXX figure out  if this is the right way to do this...

@table @code
@item bool
int
@item [unsigned-]char
[unsigned] char
@item [unsigned-]short
[unsigned] short
@item [unsigned-]int
[unsigned] int
@item [unsigned-]integer
[unsigned] int
@item [unsigned-]long
[unsigned] long
@item float
float
@item double
double
@item [nonnull-]pointer
void *
@item [nonnull-]c-pointer
void *
@item [nonnull-]byte-vector
unsigned char *
@item [nonnull-]u8vector
unsigned char *
@item [nonnull-]s8vector
char *
@item [nonnull-]u16vector
unsigned short *
@item [nonnull-]s16vector
short *
@item [nonnull-]u32vector
uint32_t *
@item [nonnull-]s32vector
int32_t *
@item [nonnull-]f32vector
float *
@item [nonnull-]f64vector
double *
@item [nonnull-]c-string
char *
@item void
void
@item ([nonnull-]pointer TYPE)
TYPE *
@item (enum NAME)
enum NAME
@item (struct NAME)
struct NAME
@item (ref TYPE)
TYPE &
@item (template T1 T2 ...)
T1<T2, ...>
@item (union NAME)
union NAME
@item (function RTYPE (ATYPE ...) [CALLCONV])
[CALLCONV] RTYPE (*)(ATYPE, ...)
@end table


@node Entry points
@section 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

@verbatim
(include "chicken-entry-points")
@end verbatim

to the beginning of your code.



@deffn {syntax} define-entry-point
@lisp
(define-entry-point INDEX ((VAR1 TYPE1) ...)
                          (RTYPE1 ...)
                          EXP1 EXP2 ...)
@end lisp
Defines a new entry-point with index @code{INDEX} which should evaluate
to an exact integer. During execution of the body @code{EXP1 EXP2 ...}
the variables @code{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 @code{TYPE1
...}. The expressions should return as many values as foreign type
specifiers are given in @code{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 @code{(values)} form at the end).
The results are then transformed into values that can be used in the host program.

@b{Note:} if one or more of the result types @code{RTYPE ...}
specify the type @code{c-string}, then the parameter types at the same
positions in @code{TYPE1 ...} have to be @code{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.

@end deffn
@deffn {syntax} define-embedded
@lisp
(define-embedded [QUALIFIER ... ] ([CCONV] NAME (TYPE1 VAR1) ...) RTYPE BODY ...)
@end lisp
Defines a named entry-point that can be accessed from external code with a normal C/C++ function call.
@code{QUALIFIER} may be a string for special function declarations (like @code{__declspec(dllexport)}
on Windows, for example) and @code{CCONV} may be a string designating a calling convention (like @code{__cdecl}).
During the execution of the @code{BODY} the variables @code{VAR1 ...} are bound to the arguments
passed to the function, which should be of types compatible to the type specifiers @code{TYPE1 ...}.
@code{RTYPE} specifies the result type of the entry-point. The return type specifiers @code{[nonnull-]c-string}
and @code{[nonnull-]c-string*} are handled specially: if the return type is @code{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 @code{c-string*}, a buffer allocated
with @code{malloc} will be returned, and freeing the string is the responsibility of the caller.

All entry-point definitions with @code{define-embedded} should be put into the same source file. 
@code{define-embedded} expands into a @code{define-entry-point} form and the entry-point index is
provided by the macro (starting from 1). If @code{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.
@end deffn



The following C functions and data types are provided:



@deftypefn {C function} void CHICKEN_parse_command_line (int argc, char *argv[], int *heap, int *stack int *symbols)
Parse the programs command-line contained in @code{argc} and
@code{argv} and return the heap-, stack- and symbol table limits
given by runtime options of the form @code{-:...}, or choose default
limits. The library procedure @code{argv} can access the command-line
only if this function has been called by the containing application.
@end deftypefn

@deftypefn {C function} int CHICKEN_initialize (int heap, int stack, int symbols, void *toplevel)
Initializes the Scheme execution context and memory. @code{heap}
holds the number of bytes that are to be allocated for the secondary
heap. @code{stack} holds the number of bytes for the primary
heap. @code{symbols} contains the size of the symbol table. Passing
@code{0} to one or more of these parameters will select a default
size. 
@code{toplevel} should be a pointer to the toplevel entry point
procedure. You should pass @code{C_toplevel} here. In any subsequent
call to @code{CHICKEN_run} or @code{CHICKEN_invoke} you can simply
pass @code{NULL}.
Calling this function more than once has no effect. If enough
memory is available and initialization was successful, then @code{1}
is returned, otherwise this function returns @code{0}.
@end deftypefn

@deftypefn {C function} void CHICKEN_run (void **data, int *bytes, int *maxlen, void *toplevel)
Starts the Scheme program. @code{data, bytes} and @code{maxlen}
contain invocation parameters in raw form. Pass @code{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 @code{CHICKEN_initialize} is called with default sizes.
@code{toplevel} is the toplevel entry-point procedure.
@end deftypefn

@deftypefn {C function} void CHICKEN_invoke (int index, C_parameter *params, int count, void *toplevel)
Invoke the entry point with index @code{index}. @code{count} should
contain the maximum number of arguments or results (whatever is higher). @code{params} is a pointer
to parameter data:

@verbatim
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;
@end verbatim

This function calls @code{CHICKEN_run} if it was not called at least
once before.
@end deftypefn

@deftypefn {C function} int CHICKEN_is_running ()
Returns @code{1}, if called inside a dynamic context invoked via @code{CHICKEN_run}
or @code{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 @code{0}.
@end deftypefn



Here is a simple example (assuming a UNIX-like environment):

@verbatim
% 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!
@end verbatim

Note the use of @code{-embedded}. We have to compile with additional compiler
options, because the host program provides the @code{main}
function.

Here another example that uses named entry-points defined with @code{define-embedded}:

@verbatim
% 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!
@end verbatim

CHICKEN also provides ``boilerplate'' entry points, that simplify invoking Scheme
code embedded in a C or C++ application tremendously. The include file @code{default-entry-points.scm}
will define entry-points for common usage patterns, like loading a file, evaluating an expression
or calling a procedure.



@deftypefn {C macro} void CHICKEN_eval (C_word exp, C_word *result, int *status)
Evaluates the Scheme object passed in @code{exp}, writing the result value to @code{result}.
@code{status} is set to 1 if the operation succeeded,
or 0 if an error occurred. Call @code{CHICKEN_get_error_message} to obtain a description
of the error.
@end deftypefn

@deftypefn {C macro} void CHICKEN_eval_string (char *str, C_word *result, int *status)
Evaluates the Scheme expression passed in the string @code{str}, writing the result value to @code{result}.
@end deftypefn

@deftypefn {C macro} void CHICKEN_eval_to_string (C_word exp, char *result, int size, int *status)
Evaluates the Scheme expression passed in @code{exp}, writing a textual representation
of the result into @code{result}. @code{size} should specify the maximal size of the result string.
@end deftypefn

@deftypefn {C macro} void CHICKEN_eval_string_to_string (char *str, char *result, int size, int *status)
Evaluates the Scheme expression passed in the string @code{str}, writing a textual representation
of the result into @code{result}. @code{size} should specify the maximal size of the result string.
@end deftypefn

@deftypefn {C macro} void CHICKEN_apply (C_word func, C_word args, C_word *result, int *status)
Applies the procedure passed in @code{func} to the list of arguments @code{args}, writing the result value to @code{result}.
@end deftypefn

@deftypefn {C macro} void CHICKEN_apply_to_string (C_word func, C_word args, char *result, int size, int *status)
Applies the procedure passed in @code{func} to the list of arguments @code{args}, writing a textual 
representation of the result into @code{result}.
@end deftypefn

@deftypefn {C macro} void CHICKEN_read (char *str, C_word *result, int *status)
Reads a Scheme object from the string @code{str}, writing the result value to @code{result}.
@end deftypefn

@deftypefn {C macro} void CHICKEN_load (char *filename, int *status)
Loads the Scheme file @code{filename} (either in source form or compiled).
@end deftypefn

@deftypefn {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.
@end deftypefn

@deftypefn {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.
@end deftypefn


An example:

@verbatim
% 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
@end verbatim


A simpler interface For handling GC-safe references to Scheme data are the so called ``gc-roots'':

@deftypefn {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.
@end deftypefn

@deftypefn {C function} void CHICKEN_delete_gc_root (void *root)
Deletes the gc root.
@end deftypefn

@deftypefn {C macro} C_word CHICKEN_gc_root_ref (void *root)
Returns the value stored in the gc root.
@end deftypefn

@deftypefn {C macro} void CHICKEN_gc_root_set (void *root, C_word value)
Sets the content of the GC root to a new value.
@end deftypefn


Sometimes it is handy to access global variables from C code:

@deftypefn {C function} void* CHICKEN_global_lookup (char *name)
Returns a GC root that holds the global variable with the name @code{name}. If no such variable
exists, @code{NULL} is returned.
@end deftypefn

@deftypefn {C function} C_word CHICKEN_global_ref (void *global)
Returns the value of the global variable referenced by the GC root @code{global}.
@end deftypefn

@deftypefn {C function} void CHICKEN_global_set (void *global, C_word value)
Sets the value of the global variable referenced by the GC root @code{global} to @code{value}.
@end deftypefn


@node Callbacks
@section Callbacks 


To enable an external C function to call back to Scheme, the form
@code{foreign-callback-lambda} (or @code{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 @code{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 @code{define-external}
or @code{foreign-callback-wrapper} forms.

Note: the names of all functions, variables and macros exported by the
CHICKEN runtime system start with ``@code{C_}''. It is advisable to
use a different naming scheme for your own code to avoid name clashes.
Callbacks (either defined by @code{define-external} or @code{foreign-callback-wrapper}
do not capture the lexical environment.



@deffn {syntax} define-external
@lisp
(define-external [QUALIFIERS] (NAME (ARGUMENTTYPE1 VARIABLE1) ...) RETURNTYPE BODY ...)
(define-external NAME TYPE [INIT])
@end lisp
The first form defines an externally callable Scheme
procedure. @code{NAME} should be a symbol, which, when converted to a
string, represents a legal C identifier. @code{ARGUMENTTYPE1 ...} and
@code{RETURNTYPE} are foreign type specifiers for the argument variables
@code{VAR1 ...} and the result, respectively.  @code{QUALIFIERS}
is an optional qualifier for the foreign procedure definition, like
@code{__stdcall}.

@verbatim
(define-external (foo (c-string x)) int (string-length x))
@end verbatim

is equivalent to

@verbatim
(define foo 
  (foreign-callback-wrapper int "foo" 
    (c-string) (lambda (x) (string-length x))))
@end verbatim

The second form of @code{define-external} can be used to define
variables that are accessible from foreign code. It declares
a global variable named by the symbol @code{NAME} that
has the type @code{TYPE}. @code{INIT} can be an arbitrary
expression that is used to initialize the variable. @code{NAME} is
accessible from Scheme just like any other foreign variable defined by
@code{define-foreign-variable}.  

@verbatim
(define-external foo int 42)
((foreign-lambda* int ()
  "return(foo);"))           ==> 42
@end verbatim

@b{Note:} don't be tempted to
assign strings or bytevectors to external variables. Garbage collection
moves those objects around, so it is very bad idea to assign pointers
to heap-data. If you have to do so, then copy the data object into
statically allocated memory (for example by using @code{object-evict}).

@end deffn
@deffn {syntax} foreign-callback-wrapper
@lisp
(foreign-callback-wrapper RETURNTYPE NAME [QUALIFIERS] (ARGUMENTTYPE1 ...) EXP)
@end lisp
Defines an externally callable wrapper around the procedure
@code{EXP}. @code{EXP} @b{must} be a lambda expression
of the form @code{(lambda @dots{})}. The wrapper will have the name
@code{NAME} and will have a signature as specified in the return- and
argument-types given in @code{RETURNTYPE} and @code{ARGUMENTTYPE1
...}.  @code{QUALIFIERS} is a qualifier string for the function
definition (see @code{define-external}).
@end deffn

@deftypefn {C function} C_word C_callback (C_word closure, int argc)
This function can be used to invoke the Scheme procedure @code{closure}.
@code{argc} should contain the number of arguments that are passed to
the procedure on the temporary stack. Values are put onto the temporary
stack with the @code{C_save} macro.
@end deftypefn




@node Locations
@section Locations 


It is also possible to define variables containing unboxed C data,
so called @emph{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. 



@deffn {syntax} define-location
@lisp
(define-location NAME TYPE [INIT])
@end lisp
Identical to @code{(define-external NAME TYPE [INIT])}, but the variable
is not accessible from outside of the current compilation unit (it is 
declared @code{static}).

@end deffn
@deffn {syntax} let-location
@lisp
(let-location ((NAME TYPE [INIT]) ...) BODY ...)
@end lisp
Defines a lexically bound location.

@end deffn
@deffn {syntax} location
@lisp
(location NAME)
(location X)
NAME
define-external
@end lisp
or @code{let-location}.  This form returns a pointer object
that contains the address of the variable @code{NAME}. 
If the argument to @code{location} is not a location defined by @code{define-location},
@code{define-external} or @code{let-location}, then

@verbatim
(location X)
@end verbatim

is essentially equivalent to 

@verbatim
(make-locative X)
@end verbatim

(See the manual chapter or @code{locatives} for more information about
locatives.

Note that @code{(location X)} may be abbreviated as @code{#$X}.

@verbatim
(define-external foo int)
((foreign-lambda* void (((pointer int) ip)) "*ip = 123;") 
  (location foo))
foo                                                                               ==> 123
@end verbatim

This facility is especially useful in situations, where a C function
returns more than one result value:

@verbatim
#>
#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) ) )
@end verbatim
@end deffn



@code{location} returns a value of type @code{c-pointer}, when given
the name of a callback-procedure defined with @code{define-external}.

@node Other support procedures
@section Other support procedures


@deffn {procedure} argc+argv
@lisp
(argc+argv)
@end lisp
Returns two values: an integer and a foreign-pointer object representing the @code{argc}
and @code{argv} arguments passed to the current process.
@end deffn



@node The Easy Foreign Function Interface
@section The @emph{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
@code{foreign-parse}, which extracts binding information and generates
the necessary code. An example:

@verbatim
(declare 
  (foreign-declare "
#include <math.h>

#define my_pi 3.14
")
  (foreign-parse "extern double sin(double);") )

(print (sin 3.14))
@end verbatim

The parser would generate code that is equivalent to

@verbatim
(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))
@end verbatim

Note that the read syntax @code{#>[SPEC] ... <#}
provides a somewhat simpler way of using the parser. The example above could
alternatively be expressed as

@verbatim
#>!
#define my_pi 3.14

extern double sin(double);
<#

(print (sin 3.14))
@end verbatim

Another example, here using C++. Consider the following class:

@verbatim
// file: foo.h

class Foo {
 private:
  int x_;
 public:
  Foo(int x);
  void setX(int x);
  int getX();
};
@end verbatim

To generate a wrapper class that provides generic functions for the
constructor and the @code{setX} and @code{getX} methods, we
can use the following class definition:

@verbatim
; file: test-foo.scm

#>!
#include "Foo.h"
<#

(define x (make <Foo> 99))
(print (getX x))              ; prints ``99''
(setX x 42)
(print (getX x))              ; prints ``42''
(destroy x)
@end verbatim

Provided the file @code{foo.o} contains the implementation of the class @code{Foo}, the
given example could be compiled like this (assuming a UNIX like environment):

@verbatim
% csc test-foo.scm foo.o -c++
@end verbatim

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:

@verbatim
; compile like this: 
; csc hello.scm -c++ -C -IQTDIR/include -L "-LQTDIR/lib -lqt"

; 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)
@end verbatim


@menu
* #> ... <# Syntax::            
* General operation::           
* Pseudo declarations::         
* Grammar::                     
* C notes::                     
* C++ notes::                   
@end menu

@node #> ... <# Syntax
@subsection @code{#> ... <#} Syntax

Occurrences of the special read syntax @code{#>[SPEC ...] ...<#} will be handled according to
@code{SPEC}: 

If @code{SPEC} is the @code{?} character, the text following up to the next @code{<#}
will be processed as a @code{(declare (foreign-parse "..."))} declaration (the code will be processed
by the FFI parser described in this section).

If @code{SPEC} is the @code{!} character, the text will be embedded as 

@verbatim
(declare
  (foreign-declare "...")
  (foreign-parse "...") )
@end verbatim

It will be both included verbatim in the declaration section of the generated C/C++ file and processed by the FFI parser.

If @code{SPEC} is the @code{:} character the text will be embedded as a @code{(foreign-code "...")} form,
so it will be executed at the location where it appears.

If @code{SPEC} is a list of the form @code{(TAG ...)}, then each @code{TAG} (which should be a symbol)
specifies what should be done with the text: 

@table @code
@item declare
(declare (foreign-declare "..."))
@item parse
(declare (foreign-parse "..."))
@item execute
(foreign-code "...")
@end table


If any other character follows the @code{#>}, then the complete text will be included verbatim in the declaration
part of the generated file (as in a @code{foreign-declare} declaration). 


@node General operation
@subsection General operation

The parser will generally perform the following functions

1) Translate macro, enum-definitions and constants into @code{define-foreign-variable} or @code{define-constant} forms

2) Translate function prototypes into @code{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 @code{#define} is performed. The
preprocessor commands @code{#ifdef}, @code{#ifndef}, @code{#else}, @code{#endif}, @code{#undef} and @code{#error}
are handled. The preprocessor commands @code{#if} and @code{#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 @code{#pragma} is allowed but will be ignored.

During processing of @code{foreign-parse} declarations the macro @code{CHICKEN} is defined (similar
to the C compiler option @code{-DCHICKEN}).

Macro- and type-definitions are available in subsequent @code{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.
Structs are not supported. C and C++ style comments are supported. Variables declared as @code{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 @code{__callback}
qualifier, which marks the function as performing a callback into Scheme. If a wrapped function
calls back into Scheme code, and @code{__callback} has not been given very strange and hard to debug
problems will occur. Member functions prefixed with @code{__discard} and a result type that maps to
a Scheme string (@code{c-string}), will have their result type changed to @code{c-string*} instead.

Constants (as declared by @code{#define} or @code{enum}) are not visible outside of the current
Compilation units unless the @code{export_constants} pseudo declaration has been used.

When given the option @code{-ffi}, CHICKEN will compile a C/C++ file in ``Scheme'' mode, that is,
it wraps the C/C++ source inside @code{#>! ... <#} and compiles it while generating Scheme
bindings for exported definitions.

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.

@node Pseudo declarations
@subsection Pseudo declarations

Using the @code{__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.

@itemize

@item abstract [values: <string>]
Marks the C++ class given in @code{<string>} as being abstract, i.e. no constructor will
be defined. Alternatively, a class definition may be prefixed with @code{__abstract}.

@item class_finalizers [values: yes, no]
Automatically generates calls to @code{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.

@item destructor_name [values: <string>]
Specifies an alternative name for destructor methods (the default is @code{destroy}.

@item export_constants [values: yes, no]
Define a global variable for constant-declarations (as with @code{#define} or @code{enum}),
making the constant available outside the current compilation unit. Use the values
@code{yes}/@code{1} for switching constant export on, or @code{no}/@code{0} for switching
it off.

@item 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 @code{catch} forms that perform any actions 
that should be taken in case an exception is thrown by the wrapped member function:

@verbatim
#>!
__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))
@end verbatim

will print @code{<Foo>} and @code{#f}, respectively.

@item 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:

@table @code
@item char
<char>
@item bool
<bool>
@item c-string
<string>
@item unsigned-char
<exact>
@item byte
<exact>
@item unsigned-byte
<exact>
@item [unsigned-]int
<exact>
@item [unsigned-]short
<exact>
@item [unsigned-]long
<integer>
@item [unsigned-]integer
<integer>
@item float
<inexact>
@item double
<inexact>
@item (enum _)char
<exact>
@item (const T)char
(as T)
@item (function ...)
<pointer>
@item c-pointer
<pointer>
@item (pointer _)
<pointer>
@item (c-pointer _)
<pointer>
@item u8vector
<u8vector>
@item s8vector
<s8vector>
@item u16vector
<u16vector>
@item s16vector
<s16vector>
@item u32vector
<u32vector>
@item s32vector
<s32vector>
@item f32vector
<f32vector>
@item f64vector
<f64vector>
@end table


All other foreign types are specialized as @code{<top>}.

Full specialization can be enabled globally, or only for sections of code by
enclosing it in

@verbatim
__declare(full_specialization, yes)
...
int foo(int x);
int foo(char *x);
...
__declare(full_specialization, no)
@end verbatim

Alternatively, member function definitions may be prefixed by @code{__specialize} for specializing
only specific members.

@item prefix [values: <string>, no, 0]

Sets a prefix that should be be added to all generated Scheme identifiers. For example

@verbatim
__declare(prefix, "mylib:")
#define SOME_CONST     42
@end verbatim

would generate the following code:

@verbatim
(define-constant mylib:SOME_CONST 42)
@end verbatim

To switch prefixing off, use the values @code{no} or @code{0}.

@item rename [value: <string>]

Defines to what a certain C/C++ name should be renamed. The value for this declaration
should have the form @code{"<c-name>;<scheme-name>"}, where @code{<c-name>} specifies
the C/C++ identifier occurring in the parsed text and @code{<scheme-name>} gives
the name used in generated wrapper code.

@item scheme [value: <string>]

Embeds the Scheme expression @code{<string>} in the generated Scheme code.

@item 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 @code{;} character):

@verbatim
__declare(substitute, "^SDL_;sdl:")

extern void SDL_Quit();
@end verbatim

generates

@verbatim
(define sdl:Quit
  (foreign-lambda integer "SDL_Quit") )
@end verbatim

@item 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 @code{string-match}) and should return
a string with the desired transformations applied:

@verbatim
(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))
@end verbatim

@item type [value: <string>]

Declares a foreign type transformation, similar to @code{define-foreign-type}. 
The value should be a list of two to four items, separated by the @code{;} character:
a C typename, a Scheme foreign type specifier and optional argument- and result-value
conversion procedures.

@verbatim
;;;; 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!")
@end verbatim

@end itemize

@node Grammar
@subsection Grammar

The parser understand the following grammar:

@verbatim
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" ID
            | "__declare" "(" PSEUDODECL "," <tokens> ")"

INCLUDEFILE = "\"" ... "\""
            | "<" ... ">"

FUNCTION = {"__callback" | "__specialize" | "__discard"} [STORAGE] TYPE ID "(" TYPE [ID] "," ... ")" [CODE]
         | {"__callback" | "__specialize" | "__discard"} [STORAGE] TYPE ID "(" "void" ")" [CODE]

VARIABLE = [STORAGE] TYPE ID ["=" INITDATA]

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"

ENUM = "enum" "{" ID ["=" NUMBER] "," ... "}"

TYPEDEF = "typedef" TYPE ["*" ...] ID

TYPE = ["const"] BASICTYPE [("*" ... | "&" | "<" TYPE "," ... ">" | "(" "*" [ID] ")" "(" TYPE "," ... ")")]

BASICTYPE = ["unsigned" | "signed"] "int" 
          | ["unsigned" | "signed"] "char" 
          | ["unsigned" | "signed"] "short" 
          | ["unsigned" | "signed"] "long" 
          | ["unsigned" | "signed"] "__byte" 
          | "float"
          | "double"
          | "void"
          | "bool"
          | "__bool"
          | "__scheme_value"
          | "__fixnum"
          | "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 "(" TYPE [ID] "," ... ")" ["const"] ["=" "0"] [CODE]
               | {"__callback" | "static" | "__specialize" | "__discard"} TYPE ID "(" "void" ")" ["const"] ["=" "0"] [CODE]

CONSTRUCTOR = ["__callback"] ["explicit"] ID "(" TYPE [ID] "," ... ")" [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>
@end verbatim

The following table shows how argument-types are translated:


@table @code
@item [unsigned] char
char
@item [unsigned] short
[unsigned-]short
@item [unsigned] int
[unsigned-]integer
@item [unsigned] long
[unsigned-]long
@item float
float
@item double
double
@item bool
int
@item __bool
int
@item __fixnum
int
@item __scheme_value
scheme-object
@item char *
c-string
@item signed char *
s8vector
@item [signed] short *
s16vector
@item [signed] int *
s32vector
@item [signed] long *
s32vector
@item unsigned char *
u8vector
@item unsigned short *
u16vector
@item unsigned int *
u32vector
@item unsigned long *
u32vector
@item float *
f32vector
@item double *
f64vector
@item CLASS *
(instance CLASS <CLASS>)
@item TYPE *
(pointer TYPE)
@item TYPE 
&(ref TYPE)
@item TYPE<T1, ...>
(template TYPE T1 ...)
@item TYPE1 (*)(TYPE2, ...)
(function TYPE1 (TYPE2 ...))
@end table


The following table shows how result-types are translated:

@table @code
@item void
void
@item [unsigned] char
char
@item [unsigned] short
[unsigned-]short
@item [unsigned] int
[unsigned-]integer
@item [unsigned] long
[unsigned-]long
@item float
float
@item double
double
@item bool
bool
@item __bool
bool
@item __fixnum
int
@item __scheme_value
scheme-object
@item char *
c-string
@item CLASS *
(instance CLASS <CLASS>)
@item TYPE *
(pointer TYPE)
@item TYPE 
&(ref TYPE)
@item TYPE<T1, ...>
(template TYPE T1 ...)
@item TYPE1 (*)(TYPE2, ...)
(function TYPE1 (TYPE2 ...))
@end table


@node C notes
@subsection C notes

Foreign variable definitions for macros are not exported from the current compilation unit, but
definitions for C variables and functions are. 

@code{foreign-parse} does not embed the text into
the generated C file, use @code{foreign-declare} for that (or even better, use the @code{#>! ... <#} syntax
which does both).

Functions with variable number of arguments are not supported.

@node C++ notes
@subsection C++ notes

Each C++ class defines a TinyCLOS class, which is a subclass of @code{<c++-object>}. Instances of this class
contain a single slot named @code{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 (@code{<...>}).
TinyCLOS classes are not seen by C++ code.

The C++ constructor is invoked by the @code{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 @code{initialize}
generic will optionally accept an arguments list of the form @code{'this POINTER}, where @code{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 @code{destroy} generic
(the name can be changed by using the @code{destructor_name} pseudo declaration).

Static member functions are wrapped in a Scheme procedure named @code{<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.


@node C interface
@section C interface


The following functions and macros are available for C code that invokes
Scheme:



@deftypefn {C function} void C_save (C_word x)
Saves the Scheme data object @code{x} on the temporary stack.
@end deftypefn

@deftypefn {C macro} C_word C_fix (int integer)
@deftypefnx {C macro} C_word C_make_character (int char_code)
@deftypefnx {C macro} C_word C_SCHEME_END_OF_LIST
@deftypefnx {C macro} C_word C_SCHEME_END_OF_FILE
@deftypefnx {C macro} C_word C_SCHEME_FALSE
@deftypefnx {C macro} C_word C_SCHEME_TRUE
These macros return immediate Scheme data objects.
@end deftypefn

@deftypefn {C function} C_word C_string (C_word **ptr, int length, char *string)
@deftypefnx {C function} C_word C_string2 (C_word **ptr, char *zero_terminated_string)
@deftypefnx {C function} C_word C_intern2 (C_word **ptr, char *zero_terminated_string)
@deftypefnx {C function} C_word C_intern3 (C_word **ptr, char *zero_terminated_string, C_word initial_value)
@deftypefnx {C function} C_word C_pair (C_word **ptr, C_word car, C_word cdr)
@deftypefnx {C function} C_word C_flonum (C_word **ptr, double number)
@deftypefnx {C function} C_word C_int_to_num (C_word **ptr, int integer)
@deftypefnx {C function} C_word C_mpointer (C_word **ptr, void *pointer)
@deftypefnx {C function} C_word C_vector (C_word **ptr, int length, ...)
@deftypefnx {C function} C_word C_list (C_word **ptr, int length, ...)
These functions allocate memory from @code{ptr} and initialize a fresh
data object. The new data object is returned. @code{ptr} should be the
@b{address} of an allocation pointer created with @code{C_alloc}.
@end deftypefn

@deftypefn {C macro} C_word* C_alloc (int words)
Allocates memory from the C stack (@code{C_alloc}) and returns a pointer to
it. @code{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 @code{C_alloc}
will already have moved to a safe place.
@end deftypefn

@deftypefn {C macro} int C_SIZEOF_LIST (int length)
@deftypefnx {C macro} int C_SIZEOF_STRING (int length)
@deftypefnx {C macro} int C_SIZEOF_VECTOR (int length)
@deftypefnx {C macro} int C_SIZEOF_INTERNED_SYMBOL (int length)
@deftypefnx {C macro} int C_SIZEOF_PAIR
@deftypefnx {C macro} int C_SIZEOF_FLONUM
@deftypefnx {C macro} int C_SIZEOF_POINTER
@deftypefnx {C macro} int C_SIZEOF_LOCATIVE
@deftypefnx {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.
@end deftypefn

@deftypefn {C macro} int C_character_code (C_word character)
@deftypefnx {C macro} int C_unfix (C_word fixnum)
@deftypefnx {C macro} double C_flonum_magnitude (C_word flonum)
@deftypefnx {C function} char* C_c_string (C_word string)
@deftypefnx {C function} int C_num_to_int (C_word fixnum_or_flonum)
@deftypefnx {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.
@end deftypefn

@deftypefn {C macro} int C_header_size (C_word x)
@deftypefnx {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 @code{x}.
@end deftypefn

@deftypefn {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 @code{x}.  @code{index} specifies the index of the slot to
be fetched, starting at 0. Pairs have 2 slots, one for the @b{car}
and one for the @b{cdr}. Vectors have one slot for each element.
@end deftypefn

@deftypefn {C macro} void* C_data_pointer (C_word x)
Returns a pointer to the data-section of a non-immediate Scheme object.
@end deftypefn

@deftypefn {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.
@end deftypefn

@deftypefn {C function} C_word C_mutate (C_word *slot, C_word val)
Assign the Scheme value @code{val} to the location specified by
@code{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.
@end deftypefn

@deftypefn {C macro} C_word C_symbol_value (C_word symbol)
Returns the global value of the variable with the name @code{symbol}.
@end deftypefn

@deftypefn {C function} void C_gc_protect (C_word *ptrs[], int n)
Registers @code{n} variables at address @code{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 @code{C_mutate()}. The variables have to be initialized to sensible values
before the next garbage collection starts (when in doubt, set all locations
in @code{ptrs} to @code{C_SCHEME_UNDEFINED})
@code{C_gc_protect} may not called before the runtime system has been
iniitalized (either by @code{CHICKEN_initialize}, @code{CHICKEN_run} or
@code{CHICKEN_invoke}.
@end deftypefn

@deftypefn {C function} void C_gc_unprotect (int n)
Removes the last @code{n} registered variables from the set of
root variables.
@end deftypefn




An example:

@verbatim
% 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
@end verbatim


@b{Notes:}
@itemize

@item 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 @code{-nursery} option)
or when running the executable (using the @code{-:s} runtime option).

@item 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.

@item 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.

@item 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.

@item Calls from C to Scheme are never tail-recursive.

@item Continuations captured via @code{call-with-current-continuation}
and passed to C code can be invoked like any other Scheme procedure.

@end itemize


@node chicken-setup
@chapter chicken-setup

@menu
* Extension libraries::
* Installing extensions::
* Creating extensions::
* Procedures and macros available in setup scripts::
* Examples for extensions::
* @code{chicken-setup} reference::
@end menu


@node Extension libraries
@section 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 @code{libdl} functionality
like Linux, Solaris, BSD or Mac OS X. Windows with Cygwin is supported as well. 

Note: Extension may also be normal applications or shell scripts.


@node Installing extensions
@section Installing extensions

To install an extension library, run the @code{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
@emph{repository}. If it is an archive containing addition files, then
the files are extracted and the contained @emph{setup} script is
executed. This setup script is a normal Scheme source file, which
will be interpreted by @code{chicken-setup}. The complete language supported
by @code{csi} is available, and the library units 
@code{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
@code{install-extension}, @code{install-program} or @code{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.


@node Creating extensions
@section Creating extensions

Extensions can be created by creating an archive named @code{EXTENSION.egg}
containing all needed files plus a @code{.setup} script in the root directory.
After @code{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.


@node Procedures and macros available in setup scripts
@section Procedures and macros available in setup scripts

@deffn {procedure} install-extension
@lisp
(install-extension ID FILELIST [INFOLIST])
@end lisp
Installs extension library with the name @code{ID}. All files given in the list of strings
@code{FILELIST} will be copied to the extension repository.
The optional argument @code{INFOLIST} should be an association list that
maps symbols to values, this list will be stored as @code{ID.setup} at the same
location as the extension code. Currently the following properties are used:

@deffn {property} syntax
@lisp
(syntax)
@end lisp
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.
@end deffn

@deffn {property} require-at-runtime
@lisp
(require-at-runtime ID ...)
@end lisp
Specifies extensions that should be loaded (via @code{require}) at runtime. This is mostly
useful for syntax extensions that need additional support code at runtime.
@end deffn

@deffn {property} version
@lisp
(version STRING)
@end lisp
Specifies version string.
@end deffn

All other properties are currently ignored. The @code{FILELIST} argument may also be a single
string.

@end deffn

@deffn {procedure} install-program
@lisp
(install-program ID FILELIST [INFOLIST])
@end lisp
Similar to @code{install-extension}, but installs an executable program in the
executable path (usually @code{/usr/local/bin}.
@end deffn

@deffn {procedure} install-script
@lisp
(install-program ID FILELIST [INFOLIST])
@end lisp
Similar to @code{install-program}, but additionally changes the file permissions of all
files in @code{FILELIST} to executable (for installing shell-scripts).
@end deffn


@deffn {syntax} run
@lisp
(run FORM ...)
@end lisp
Runs the shell command @code{FORM}, which is wrapped in an implicit @code{quasiquote}. 
@end deffn

@deffn {syntax} make
@lisp
(make ((TARGET (DEPENDENT ...) COMMAND ...) ...) ARGUMENTS)
@end lisp
A ``make'' macro that executes the expressions @code{COMMAND ...}, when any of the dependents
@code{DEPENDENT ...} have changed, to build @code{TARGET}. This is the same as the @code{make}
extension, which is available separately. For more information, see
@uref{http://www.call-with-current-continuation.org/eggs/make.html, make}.
@end deffn

@deffn {procedure} patch
@lisp
(patch WHICH REGEX SUBST)
@end lisp
Replaces all occurrences of the regular expression @code{REGEX} with the string @code{SUBST},
in the file given in @code{WHICH}. If @code{WHICH} is a string, the file will be patched and
overwritten. If @code{WHICH} is a list of the form @code{OLD NEW}, then a different file named
@code{NEW} will be generated.
@end deffn


@node Examples for extensions
@section Examples for extensions

The simplest case is a single file that does not export any syntax. For example

@lisp
;;;; hello.scm

(define (hello name)
  (print "Hello, " name " !") )
@end lisp

After entering 

@verbatim
$ chicken-setup hello
@end verbatim

at the shell prompt, the file @code{hello.scm} will be compiled into a dynamically loadable library,
with the default compiler options @code{-optimize-level 2 -debug-level 0 -shared}. If the
compilation succeeds, @code{hello.so} will be stored in the repository, together with a file named
@code{hello.setup} (not to be confused with a setup script - this @code{.setup} file just contains
an a-list with metadata).

Use it like any other CHICKEN extension:

@verbatim
$ csi -quiet
#;> (require-extension hello)
; loading /usr/local/lib/chicken/hello.so ...
#;> (hello "me")
Hello, me!
#;>
@end verbatim

For more elaborate build operations, when installing applications or scripts, or when
additional metadata should be stored for an extension, a @code{setup} script is required
and the script and all additional files should be packaged in a gzipped @code{tar} archive.

Here we create a simple application:

@lisp
;;;; hello2.scm

(require-extension extras)  ; needed for `printf'

(print "Hello, ")
(for-each (lambda (x) (printf "~A " x)) (command-line-arguments))
(print "!")
@end lisp

We also need a setup script:

@lisp
;;;; hello2.setup

(run (csc hello2.scm))  ; compile `hello2'
(install-program 'hello2 "hello2") ; name of the extension and files to be installed
@end lisp

To use it, just run @code{chicken-setup} in the same directory:

@verbatim
$ chicken-setup hello2
@end verbatim

Now the program @code{hello2} will be installed in the same location as the other CHICKEN
tools (like @code{chicken}, @code{csi}, etc.), which will normally be @code{/usr/local/bin}.
Note that you need write-permissions for those locations.

Uninstallation is just as easy:

@verbatim
$ chicken-setup -uninstall hello2
@end verbatim

@code{chicken-setup} provides a @code{make} tool, so building operations can be of
arbitrary complexity. When running @code{chicken-setup} with an argument @code{NAME},
for which no associated file @code{NAME.setup}, @code{NAME.egg} or @code{NAME.scm}
exists will ask you to download the extension via HTTP from the default URL
@code{http://www.call-with-current-continuation.org/eggs}. You can use the 
@code{-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:

@lisp
;;;; 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) ) ) )
@end lisp

Here some support code that needs to be loaded at runtime:

@lisp
;;;; 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))
@end lisp

The setup script looks like this:

@lisp
(run (csc -s -O2 -d0 glass-support.scm))

(install-extension
  'glass
  '("glass.scm" "glass-support.so")
  '((syntax) (require-at-runtime glass-support)) )
@end lisp

The invocation of @code{install-extension} provides the files that
are to be copied into the extension repository, and a metadata list that
specifies that the extension @code{glass} is a syntax extension and that,
if it is declared to be used by other code (either with the @code{require-extension}
or @code{require-for-syntax} form), then client code should perform an implicit
@code{(require 'glass-support)} at startup.

This can be conveniently packaged as an ``egg'':

@verbatim
$ tar cfz glass.egg glass.setup glass.scm glass-support.scm
@end verbatim

And now we use it:

@verbatim
$ csi -quiet
#;> (require-extension glass)
; loading /usr/local/lib/chicken/glass.scm ...
; loading /usr/local/lib/chicken/glass-support.so ...
#;> (define foo (glass-lambda (x) (y) (+ x y)))
#;> (glass-lambda-set! foo 'y 99)
#;> (foo 33)
132
@end verbatim


@node @code{chicken-setup} reference
@section @code{chicken-setup} reference

Available options:

@itemize
@item @code{-help}
Show usage information and exit.
@item @code{-version}
Display version and exit.
@item @code{-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 @code{repository-path} parameter)
will be set to @code{PATHNAME} for all subsequent operations. The default repository path is
the installation library directory (usually @code{/usr/local/lib/chicken}), or (if set) the
directory given in the environment variable @code{CHICKEN_REPOSITORY}.
@item @code{-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
@code{PATHNAME} for all subsequent operations.
@item @code{-host HOSTNAME[:PORT]}
Specifies alternative host for downloading extensions, optionally with a TCP port number (which
defaults to 80).
@item @code{-uninstall EXTENSION}
Removes all files that were installed for @code{EXTENSION} from the file-system, together
with any metadata that has been stored.
@item @code{-list}
List all installed extensions and exit.
@item @code{-run FILENAME}
Load and execute given file.
@item @code{-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 @code{chicken-setup}
just as with @code{csi}.
@item @code{-verbose}
Display additional debug information.
@item @code{-keep}
Keep temporary files and directories.
@end itemize

Note that the options are processed exactly in the order in which they appear in the command-line.


@node Additional files
@chapter Additional files


In addition to library units the following files are provided. Use them
by including the file in your code with the @code{include} special form.


@menu
* srfi-13-syntax.scm::          
* chicken-highlevel-macros.scm::  
* chicken-more-macros.scm::     
* chicken-ffi-macros.scm::      
* chicken-entry-points.scm::    
* chicken-default-entry-points.scm::  
* test-infrastructure.scm::     
@end menu

@node  srfi-13-syntax.scm
@section @code{srfi-13-syntax.scm}

This file provides the @code{let-string-start+end} syntax defined
in SRFI-13. @xref{Unit srfi-13}.


@node  chicken-highlevel-macros.scm
@section @code{chicken-highlevel-macros.scm}

This file contains highlevel (@code{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 @code{-hygienic} option is used.

If you intend to make highlevel macros (R5RS and/or @code{syntax-case}) available
at run-time (for example, for evaluating code at runtime that contains highlevel macros),
declare the @code{syntax-case} unit as used and install the macro system by hand,
as in this example:

@verbatim
(require-extension syntax-case)

(install-highlevel-macro-system)
@end verbatim

(This is basically what the @code{-hygienic-at-run-time} option does, but this
procedure gives you a little more control.)



@deffn {procedure} install-highlevel-macro-system
@lisp
(install-highlevel-macro-system FEATURE ...)
@end lisp
Installs the highlevel (R5RS / @code{syntax-case}) macro system in the running
program. @code{FEATURE} should be a symbol and selects the amount of non-standard
macros being provided. Possible features are:

@itemize
@item @code{r5rs}

The R5RS standard derived syntax, and only those.
@item @code{srfi-0}

SRFI-0 (@code{cond-expand})
@item @code{extensions}

R5RS standard derived syntax and all non-standard extension provided in CHICKEN
@end itemize

If no feature is give, @code{'r5rs} is assumed.
@end deffn




@node  chicken-more-macros.scm
@section @code{chicken-more-macros.scm}

This file contains the definitions of all non-standard syntax forms.
You normally don't use this file directly.


@node  chicken-ffi-macros.scm
@section @code{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.


@node  chicken-entry-points.scm
@section @code{chicken-entry-points.scm}

This file contains the definition of the macros @code{define-entry-point}
and @code{define-embedded}. See the section ``Entry points'' earlier in this manual.


@node  chicken-default-entry-points.scm
@section @code{chicken-default-entry-points.scm}

This file contains boilerplate entry point definitions. See the section
``Entry points''. This file automatically includes @code{entry-points.scm}.


@node  test-infrastructure.scm
@section @code{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::  
@end menu

@node The Test Package Macro API
@subsection 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.


@deffn {macro} test-package
@lisp
(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)
@end lisp
@itemize
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{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.
@item @code{TERMNAME} is an unquoted symbol for an escape procedure
available in the body of the test package, usually, this escape
procedure is passed to @code{(terminate ...)} which calls it
for you and performs other tasks. It is not recommended to call the escape
procedure directly.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the test package. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{BINDINGS} are let-style bindings that you may create and exist in
the lexical scope of the test package.
@item @code{CLAUSES} are uses of @code{(test-case ...)} macros
along with @code{(gloss ...)}, @code{(todo ...)},
@code{(skip ...)}, and @code{(terminate ...)} macros. While
you may use the @code{(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.
@end itemize
@end deffn


@node The Test Case Macro API
@subsection The Test Case Macro API

This macro will evaluate in a left to right fashion the clauses inside
it @b{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 @b{NOT} nest.


@deffn {macro} test-case
@lisp
(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)
@end lisp
@itemize
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{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.
@item @code{TERMNAME} is an unquoted symbol for an escape procedure
available in the body of the test case, usually, this escape
procedure is passed to @code{(terminate ...)} which calls it
for you and performs other tasks. It is not recommended to call the escape
procedure directly.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the test case. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{BINDINGS} are let-style bindings that you may create and exist in
the lexical scope of the test case.
@item @code{CLAUSES} are uses of @code{(expect-* ...)} macros
along with @code{(gloss ...)}, @code{(todo ...)},
@code{(skip ...)}, and @code{(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.
@end itemize
@end deffn



@node The Expectation Macro API
@subsection 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.


@deffn {macro} expect-zero
@lisp
(expect-zero MESSAGE CLAUSE)
(expect-zero MESSAGE (warn MESSAGE) CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if the evaluated expression passed to it
is numerically equal to the exact integer zero.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{CLAUSE} is a single expression which should return a exact or
inexact integer.
@end itemize
@end deffn



@deffn {macro} expect-nonzero
@lisp
(expect-nonzero MESSAGE CLAUSE)
(expect-nonzero MESSAGE (warn MESSAGE) CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if the evaluated expression passed to it
is numerically not equal to the exact integer zero.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{CLAUSE} is a single expression which should return an exact or
inexact integer.
@end itemize
@end deffn



@deffn {macro} expect-true
@lisp
(expect-true MESSAGE CLAUSE)
(expect-true MESSAGE (warn MESSAGE) CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if the evaluated expression passed to it
is the value #t.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{CLAUSE} is a single expression which should return #t.
@end itemize
@end deffn



@deffn {macro} expect-false
@lisp
(expect-false MESSAGE CLAUSE)
(expect-false MESSAGE (warn MESSAGE) CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if the evaluated expression passed to it
is the value #f.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{CLAUSE} is a single expression which should return #t.
@end itemize
@end deffn



@deffn {macro} expect-eq?
@lisp
(expect-eq? MESSAGE EXPECTED CLAUSE)
(expect-eq? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if @code{(eq? EXPECTED CLAUSE)} is true.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{EXPECTED} is a single expression which is evaluated and represents
the value the @code{CLAUSE} @b{must} be eq? to in order for this
expectation to return a positive result.
@item @code{CLAUSE} is a single expression which, when evaluated must return
an object where an eq? of this result and the @code{EXPECTED} expression
is #t.
@item The result object this macro produce shall contain the unevaluated 
@code{CLAUSE} expression as a field, but not an unevaluated @code{EXPECTED}
expression.
@end itemize
@end deffn



@deffn {macro} expect-eqv?
@lisp
(expect-eqv? MESSAGE EXPECTED CLAUSE)
(expect-eqv? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if @code{(eqv? EXPECTED CLAUSE)} is 
true.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{EXPECTED} is a single expression which is evaluated and represents
the value the @code{CLAUSE} @b{must} be eqv? to in order for this
expectation to return a positive result.
@item @code{CLAUSE} is a single expression which, when evaluated must return
an object where an eqv? of this result and the @code{EXPECTED} expression
is #t.
@item The result object this macro produce shall contain the unevaluated 
@code{CLAUSE} expression as a field, but not an unevaluated @code{EXPECTED}
expression.
@end itemize
@end deffn



@deffn {macro} expect-equal?
@lisp
(expect-equal? MESSAGE EXPECTED CLAUSE)
(expect-equal? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if @code{(equal? EXPECTED CLAUSE)} is 
true.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{EXPECTED} is a single expression which is evaluated and represents
the value the @code{CLAUSE} @b{must} be equal? to in order for this
expectation to return a positive result.
@item @code{CLAUSE} is a single expression which, when evaluated must return
an object where an equal? of this result and the @code{EXPECTED} expression
is #t.
@item The result object this macro produce shall contain the unevaluated 
@code{CLAUSE} expression as a field, but not an unevaluated @code{EXPECTED}
expression.
@end itemize
@end deffn



@deffn {macro} expect-near?
@lisp
(expect-near? MESSAGE EXPECTED TOL CLAUSE)
(expect-near? MESSAGE (warn MESSAGE) EXPECTED TOL CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if 
@code{(< (abs (- EXPECTED CLAUSE)) TOL)))} is true.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{EXPECTED} is a single expression which is evaluated and represents
the value the @code{CLAUSE} @b{must} be ``near'' to in order for this
expectation to return a positive result.
@item @code{CLAUSE} is a single expression which should return an inexact or 
exact number.
@item @code{TOL} is a single expression which, when evaluated must return a
tolerance value(usually a small inexact number like .0001).
@item The result object this macro produce shall contain the unevaluated 
@code{CLAUSE} expression as a field, but not the unevaluated @code{EXPECTED}
or @code{TOL} expression.
@end itemize
@end deffn



@deffn {macro} expect-positive
@lisp
(expect-positive MESSAGE CLAUSE)
(expect-positive MESSAGE (warn MESSAGE) CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if the evaluated expression passed to it
is a positive value greater than zero.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{CLAUSE} is a single expression which should return an inexact or
exact number.
@end itemize
@end deffn



@deffn {macro} expect-negative
@lisp
(expect-negative MESSAGE CLAUSE)
(expect-negative MESSAGE (warn MESSAGE) CLAUSE)
@end lisp
@itemize
@item This expectation checks to see if the evaluated expression passed to it
is a negative value less than zero.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn MESSAGE)} allows you to specify a warning object, usually
a string, that gets associated with the expectation. The
@code{warn} function name is actually a syntax reserved word
in the macro.
@item @code{CLAUSE} is a single expression which should return an inexact or
exact number.
@end itemize
@end deffn


@node Result Object API
@subsection Result Object API

Expectations, test cases, test packages, and helper macros(@code{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.

@node Test Package Result Object API
@subsection Test Package Result Object API

If any of these API functions, except @b{test-package-result?},
are passed something that isn't a test package result object, they will
return 'not-a-test-package-result.



@deffn {procedure} test-package-result?
@lisp
(test-package-result? RESULT)
@end lisp
If @code{RESULT} is a result object from the invocation
of a test package macro, then this function will return
#t. Otherwise, it will return #f.
@end deffn

@deffn {procedure} test-package-result-result-ref
@lisp
(test-package-result-result-ref RESULT)
@end lisp
Returns the boolean result associated with the test package @code{RESULT}
object.
@end deffn

@deffn {procedure} test-package-result-message-ref
@lisp
(test-package-result-message-ref RESULT)
@end lisp
Returns the message object associated with the test package @code{RESULT}
object.
@end deffn

@deffn {procedure} test-package-result-exps-ref
@lisp
(test-package-result-exps-ref RESULT)
@end lisp
Returns the list of result objects associated with the test package 
@code{RESULT} object.
@end deffn

@deffn {procedure} test-package-result-warning?
@lisp
(test-package-result-warning? RESULT)
@end lisp
If a warning had been attached to this test package, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} test-package-result-warning-ref
@lisp
(test-package-result-warning-ref RESULT)
@end lisp
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 @b{'()}.
@end deffn



@node Test Case Result Object API
@subsection Test Case Result Object API

If any of these API functions, except @b{test-case-result?},
are passed something that isn't a test case result object, they will
return 'not-a-test-case-result.



@deffn {procedure} test-case-result?
@lisp
(test-case-result? RESULT)
@end lisp
If @code{RESULT} is a result object from the invocation
of a test case macro, then this function will return
#t. Otherwise, it will return #f.
@end deffn

@deffn {procedure} test-case-result-result-ref
@lisp
(test-case-result-result-ref RESULT)
@end lisp
Returns the boolean result associated with the test case @code{RESULT}
object.
@end deffn

@deffn {procedure} test-case-result-message-ref
@lisp
(test-case-result-message-ref RESULT)
@end lisp
Returns the message object associated with the test case @code{RESULT}
object.
@end deffn

@deffn {procedure} test-case-result-expectations-ref
@lisp
(test-case-result-expectations-ref RESULT)
@end lisp
Returns the list of expctation result objects associated with the test
case @code{RESULT} object.
@end deffn

@deffn {procedure} test-case-result-warning?
@lisp
(test-case-result-warning? RESULT)
@end lisp
If a warning had been attached to this test case, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} test-case-result-warning-ref
@lisp
(test-case-result-warning-ref RESULT)
@end lisp
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 @b{'()}.
@end deffn



@node Single Clause Style Expectation
@subsection 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 @b{expect-result?}, are passed something that
isn't a single clause style expectation result object, they will return
'not-an-expect-result.



@deffn {procedure} expect-result?
@lisp
(expect-result? RESULT)
@end lisp
If @code{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.
@end deffn

@deffn {procedure} expect-result-result-ref
@lisp
(expect-result-result-ref RESULT)
@end lisp
Returns the boolean result associated with the single clause
style expectation @code{RESULT} object.
@end deffn

@deffn {procedure} expect-result-specific-ref
@lisp
(expect-result-specific-ref RESULT)
@end lisp
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 @code{(expect-zero? "foobar" (- 1 1))}
expectation, then the ``specific'' field of the expectation
result object will be the string @b{"zero"}. Here is a
table describing what the ``specific'' fields are for each kind
of single clause style expectation:


@multitable {Single Clause Style Expectation} {Associated Specific String}
@item Single Clause Style Expectation @tab Associated Specific String
@item expect-zero                     @tab "zero" 
@item expect-nonzero                  @tab "nonzero" 
@item expect-true                     @tab "true" 
@item expect-false                    @tab "false" 
@item expect-positive                 @tab "positive" 
@item expect-negative                 @tab "negative"
@end multitable


@end deffn

@deffn {procedure} expect-result-message-ref
@lisp
(expect-result-message-ref RESULT)
@end lisp
Returns the message object associated with the single clause
style expectation @code{RESULT} object.
@end deffn

@deffn {procedure} expect-result-unevaled-ref
@lisp
(expect-result-unevaled-ref RESULT)
@end lisp
Returns the unevaluated expression supplied to a single clause style
expectation macro.
@end deffn

@deffn {procedure} expect-result-evaled-ref
@lisp
(expect-result-evaled-ref RESULT)
@end lisp
Returns the evaluated expression supplied to a single clause style
expectation macro.
@end deffn

@deffn {procedure} expect-result-warning?
@lisp
(expect-result-warning? RESULT)
@end lisp
If a warning had been attached to this expectation, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} expect-result-warning-ref
@lisp
(expect-result-warning-ref RESULT)
@end lisp
If a warning had been attached to this expectation, this function
will return the warning object supplied by the user, otherwise it 
shall return @b{'()}.
@end deffn



@node Equivalence Style Expectation
@subsection 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 @b{expect-equivalence-result?}, are passed
something that isn't a single clause style expectation result object,
they will return 'not-an-expect-equivalence-result.



@deffn {procedure} expect-equivalence-result?
@lisp
(expect-equivalence-result? RESULT)
@end lisp
If @code{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.
@end deffn

@deffn {procedure} expect-equivalence-result-result-ref
@lisp
(expect-equivalence-result-result-ref RESULT)
@end lisp
Returns the boolean result associated with the comparison style
expectation @code{RESULT} object.
@end deffn

@deffn {procedure} expect-equivalence-result-specific-ref
@lisp
(expect-equivalence-result-specific-ref RESULT)
@end lisp
This retrieves the ``specific'' field of a particular equivalence
style expectation. For example, if you had a result object from
an invocation of a @code{(expect-equal? "foobar" 0 (- 1 1))}
expectation, then the ``specific'' field of the expectation
result object will be the string @b{"equal"}. Here is a
table describing what the ``specific'' fields are for each kind
of equivalence style expectation:


@multitable {Equivalence Style Expectation} {Associated Specific String}
@item Equivalence Style Expectation @tab Associated Specific String
@item expect-eq                     @tab "eq" 
@item expect-eqv                    @tab "eqv" 
@item expect-equal                  @tab "equal"
@end multitable

@end deffn

@deffn {procedure} expect-equivalence-result-message-ref
@lisp
(expect-equivalence-result-message-ref RESULT)
@end lisp
Returns the message object associated with the equivalence
style expectation @code{RESULT} object.
@end deffn

@deffn {procedure} expect-equivalence-result-lhs-evaled-ref
@lisp
(expect-equivalence-result-lhs-evaled-ref RESULT)
@end lisp
Returns the evaluated ``left hand side'' expression supplied to 
an equivalence style expectation.
@end deffn

@deffn {procedure} expect-equivalence-result-rhs-unevaled-ref
@lisp
(expect-equivalence-result-rhs-unevaled-ref RESULT)
@end lisp
Returns the unevaluated ``right hand side'' expression supplied
to an equivalence style expectation.
@end deffn

@deffn {procedure} expect-equivalence-result-rhs-evaled-ref
@lisp
(expect-equivalence-result-rhs-evaled-ref RESULT)
@end lisp
Returns the evaluated ``right hand side'' expression supplied
to an equivalence style expectation.
@end deffn

@deffn {procedure} expect-equivalence-result-warning?
@lisp
(expect-equivalence-result-warning? RESULT)
@end lisp
If a warning had been attached to this expectation, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} expect-equivalence-result-warning-ref
@lisp
(expect-equivalence-result-warning-ref RESULT)
@end lisp
If a warning had been attached to this expectation, this function
will return the warning object supplied by the user, otherwise it 
shall return @b{'()}.
@end deffn



@node Tolerance Style Expectation
@subsection 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
@b{expect-tolerance-result?}, are passed something that isn't
a tolerance style expectation result object, they will return
'not-an-expect-tolerance-result.



@deffn {procedure} expect-tolerance-result?
@lisp
(expect-tolerance-result? RESULT)
@end lisp
If @code{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.
@end deffn

@deffn {procedure} expect-tolerance-result-result-ref
@lisp
(expect-tolerance-result-result-ref RESULT)
@end lisp
Returns the boolean result associated with the tolerance style
expectation @code{RESULT} object.
@end deffn

@deffn {procedure} expect-tolerance-result-specific-ref
@lisp
(expect-tolerance-result-specific-ref RESULT)
@end lisp
This retrieves the ``specific'' field of a particular tolerance
style expectation. For example, if you had a result object from
an invocation of a @code{(expect-near? "foobar" 100 .01 100.001)}
expectation, then the ``specific'' field of the expectation
result object will be the string @b{"near"}. Here is a
table describing what the ``specific'' fields are for each kind
of tolerance style expectation:


@multitable {Tolerance Style Expectation} {Associated Specific String}
@item Tolerance Style Expectation @tab Associated Specific String@
@item expect-near                 @tab "near"
@end multitable


@end deffn

@deffn {procedure} expect-tolerance-result-message-ref
@lisp
(expect-tolerance-result-message-ref RESULT)
@end lisp
Returns the message object associated with a tolerance
style expectation @code{RESULT} object.
@end deffn

@deffn {procedure} expect-tolerance-result-lhs-evaled-ref
@lisp
(expect-tolerance-result-lhs-evaled-ref RESULT)
@end lisp
Returns the evaluated ``left hand side'' expression supplied to 
a tolerance style expectation.
@end deffn

@deffn {procedure} expect-tolerance-result-lhs-tol-evaled-ref
@lisp
(expect-tolerance-result-lhs-tol-evaled-ref RESULT)
@end lisp
Returns the evaluated ``tolerance'' expression supplied to 
a tolerance style expectation.
@end deffn

@deffn {procedure} expect-tolerance-result-rhs-unevaled-ref
@lisp
(expect-tolerance-result-rhs-unevaled-ref RESULT)
@end lisp
Returns the unevaluated ``right hand side'' expression supplied
to a tolerance style expectation.
@end deffn

@deffn {procedure} expect-tolerance-result-rhs-evaled-ref
@lisp
(expect-tolerance-result-rhs-evaled-ref RESULT)
@end lisp
Returns the evaluated ``right hand side'' expression supplied
to a tolerance style expectation.
@end deffn

@deffn {procedure} expect-tolerance-result-warning?
@lisp
(expect-tolerance-result-warning? RESULT)
@end lisp
If a warning had been attached to this expectation, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} expect-tolerance-result-warning-ref
@lisp
(expect-tolerance-result-warning-ref RESULT)
@end lisp
If a warning had been attached to this expectation, this function
will return the warning object supplied by the user, otherwise it 
shall return @b{'()}.
@end deffn



@node Various Helper API
@subsection 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.

@node Termination API
@subsection 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.


@deffn {procedure} terminate
@lisp
(terminate TERMFUNC MESSAGE)
@end lisp
@itemize
@item This is the recommended termination method for a test case or a test
package.
@item @code{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.
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@end itemize
@end deffn

@deffn {procedure} terminate-result?
@lisp
(terminate-result? RESULT)
@end lisp
If @code{RESULT} is a termination result object from the
invocation of a termination function, then this function will
return #t. Otherwise, it will return #f.
@end deffn

@deffn {procedure} terminate-result-result-ref
@lisp
(terminate-result-result-ref RESULT)
@end lisp
Returns the boolean result associated with the termination
function @code{RESULT} object. This is currently hard coded to
be #f.
@end deffn

@deffn {procedure} terminate-result-scope-ref
@lisp
(terminate-result-scope-ref RESULT)
@end lisp
The ``scope'' of the termination result is exactly the @code{MESSAGE}
parameter supplied to the test case or test package associated with the
@code{TERMFUNC}.
@end deffn

@deffn {procedure} terminate-result-container-ref
@lisp
(terminate-result-container-ref RESULT)
@end lisp
The ``container'' of the termination result is going to be
either 'test-package or 'test-case depending upon which the
@code{TERMFUNC} was associated.
@end deffn

@deffn {procedure} terminate-result-message-ref
@lisp
(terminate-result-message-ref RESULT)
@end lisp
Returns the message object associated with the termination
@code{RESULT} object.
@end deffn



@node Destructor Object API
@subsection 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
@b{automatically} invoke the helper cleanup function specified in
the destructor object that removes the file.

@b{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 @b{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.



@deffn {procedure} destructor-atexit!
@lisp
(destructor-atexit! DESTNAME FUNC ARGS ...)
@end lisp
This will insert a promise to calculate the @code{FUNC} with the
supplied @code{ARGS ...} into a queue in the @code{DESTNAME}
destructor object. Multiple invocations of this API call will 
continue to queue up @code{(FUNC ARGS ...)} promises indefinitely.
This function returns a special @b{ignore} type that is ignored
by the test infrastructure system.
@end deffn

@deffn {procedure} destructor-activate!
@lisp
(destructor-activate! DESTNAME)
@end lisp
This function will call, in order of queueing, all the promises
embedded into this destructor object, and then delete the
queue. This function is @b{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 @code{clear} itself. This function returns
a special @b{ignore} type that is ignored by the test
infrastructure system.
@end deffn

@deffn {procedure} destructor-clear!
@lisp
(destructor-clear! DESTNAME)
@end lisp
This function completely removes all of the promises associated
with the destructor object @code{DESTNAME}. This function
returns a special @b{ignore} type that is ignored by the
test infrastructure system.
@end deffn

@deffn {procedure} destructor-dump
@lisp
(destructor-dump DESTNAME)
@end lisp
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 @b{ignore}
type that is ignored by the test infrastructure system.
@end deffn



@node Todo API
@subsection 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.


@deffn {macro} todo
@lisp
(todo MESSAGE)
(todo (warn WARNING) MESSAGE)
@end lisp
@itemize
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn WARNING)} allows you to specify a warning object, usually
a string, that gets associated with the todo. The @code{warn}
function name is actually a syntax reserved word in the macro.
@end itemize
@end deffn

@deffn {procedure} todo-result?
@lisp
(todo-result? RESULT)
@end lisp
If @code{RESULT} is a todo result object from the
invocation of a todo macro, then this function will
return #t. Otherwise, it will return #f.
@end deffn

@deffn {procedure} todo-result-message-ref
@lisp
(todo-result-message-ref RESULT)
@end lisp
Returns the message object associated with the todo
@code{RESULT} object.
@end deffn

@deffn {procedure} todo-result-warning?
@lisp
(todo-result-warning? RESULT)
@end lisp
If a warning had been attached to this todo, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} todo-result-warning-ref
@lisp
(todo-result-warning-ref RESULT)
@end lisp
If a warning had been attached to this todo, this function
will return the warning object supplied by the user, otherwise it 
shall return @b{'()}.
@end deffn



@node Gloss API
@subsection 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.


@deffn {macro} gloss
@lisp
(gloss MESSAGE)
(gloss (warn WARNING) MESSAGE)
@end lisp
@itemize
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn WARNING)} allows you to specify a warning object, usually
a string, that gets associated with the gloss. The @code{warn}
function name is actually a syntax reserved word in the macro.
@end itemize
@end deffn

@deffn {procedure} gloss-result?
@lisp
(gloss-result? RESULT)
@end lisp
If @code{RESULT} is a gloss result object from the
invocation of the gloss macro, then this function will
return #t. Otherwise, it will return #f.
@end deffn

@deffn {procedure} gloss-result-message-ref
@lisp
(gloss-result-message-ref RESULT)
@end lisp
Returns the message object associated with the gloss
@code{RESULT} object.
@end deffn

@deffn {procedure} gloss-result-warning?
@lisp
(gloss-result-warning? RESULT)
@end lisp
If a warning had been attached to this gloss, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} gloss-result-warning-ref
@lisp
(gloss-result-warning-ref RESULT)
@end lisp
If a warning had been attached to this gloss, this function
will return the warning object supplied by the user, otherwise it 
shall return @b{'()}.
@end deffn



@node Skip API
@subsection 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.


@deffn {macro} skip
@lisp
(skip MESSAGE CLAUSES)
(skip (warn WARNING) MESSAGE CLAUSES)
@end lisp
@itemize
@item @code{MESSAGE} can be any scheme object, though usually it is a string.
@item @code{(warn WARNING)} allows you to specify a warning object, usually
a string, that gets associated with the gloss. The @code{warn}
function name is actually a syntax reserved word in the macro.
@item @code{CLAUSES} can be more than one expression(as in a lambda form)
that does @b{NOT} get evaluated at any time.
@end itemize
@end deffn

@deffn {procedure} skip-result?
@lisp
(skip-result? RESULT)
@end lisp
If @code{RESULT} is a skip result object from the
invocation of the skip macro, then this function will
return #t. Otherwise, it will return #f.
@end deffn

@deffn {procedure} skip-result-message-ref
@lisp
(skip-result-message-ref RESULT)
@end lisp
Returns the message object associated with the skip
@code{RESULT} object. Hopefully, it was stated why this
set of clauses had been skipped.
@end deffn

@deffn {procedure} skip-result-warning?
@lisp
(skip-result-warning? RESULT)
@end lisp
If a warning had been attached to this skip, this function
will return #t, otherwise it will be #f.
@end deffn

@deffn {procedure} skip-result-warning-ref
@lisp
(skip-result-warning-ref RESULT)
@end lisp
If a warning had been attached to this skip, this function
will return the warning object supplied by the user, otherwise it 
shall return @b{'()}.
@end deffn



@node Side Effect API
@subsection 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 @code{(begin ...)} form, it
returns a result that is completely ignored by the system and unavailable
to the output analysis code.

@deffn {macro} side-effect
@lisp
(side-effect CLAUSES)
@end lisp
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
@code{(set! ...)} or with complicated situations where a lot of setup
work must happen for an expectation to be performed.
@end deffn

@node Miscellaneous API
@subsection Miscellaneous API

This section contains a few functions whose purpose is to simplify certain
kinds of manipulations of result objects.

@deffn {procedure} *-restult?
@lisp
(*-result? RESULTOBJ)
@end lisp
This function will return #t of @code{RESULTOBJ} is any kind of an
evaluated result object. Otherwise, it shall return #f.
@end deffn

@deffn {procedure} *-result-ref
@lisp
(*-result-ref RESULTOBJ)
@end lisp
This function will return the result of any kind of @code{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.
@end deffn

@deffn {procedure} all-testpackage-results-true?
@lisp
(all-testpackage-results-true? RESULTLIST)
@end lisp
This function takes the result of a call to 
@code{(test-package-result-result-ref PACKAGERESULTOBJ)} and returns
#t if every single contained result in that list had been true, or #f
otherwise.
@end deffn

@deffn {procedure} all-testcase-expectations-true?
@lisp
(all-testcase-expectations-true? RESULTLIST)
@end lisp
This function takes the result of a call to 
@code{(test-case-result-result-ref CASERESULTOBJ)} and returns
#t if every single contained result in that list had been true, or #f
otherwise.
@end deffn


@node Analysis of the Result Tree
@subsection 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.

@node Output Generation API
@subsection Output Generation API


@deffn {procedure} printnl
@lisp
(printnl CLAUSES)
@end lisp
This function will print all of the evaluated @code{CLAUSES}
in order with a newline at the end of it.
@end deffn

@deffn {procedure} printinl
@lisp
(printinl INDENT CLAUSES)
@end lisp
This function will @code{INDENT} a number of spaces and then
print all of the evaluated @code{CLAUSES} in order with a
newline at the end of it.
@end deffn

@deffn {procedure} output-style-human
@lisp
(output-style-human RESULTTREE)
@end lisp
This function will print out a human readable rendering of the
@code{RESULTTREE} and return the toplevel package result.
@end deffn


@node Example Usages of the Test Suite Infrastructure
@subsection Example Usages of the Test Suite Infrastructure

This section contains some simple examples of how to author test suites.

Here is a simple example:

@verbatim
(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))
@end verbatim

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 @code{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 @code{(output-style-human ...)} (it isn't large) in the
test-infrastructure.scm file to see an example of this.

The variables: @code{pe, e} are the escape functions you may use with the
@code{(terminate ...)} function call if you wish to abort the above code
somewhere.

The variables: @code{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 @code{(output-style-human ...)} might
generate with the above testing code:

@verbatim
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
@end verbatim


@node Data Representation
@chapter 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:

@itemize

@item @b{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).

@item @b{characters}, where the lowest four bits of machine words
containing characters are equal to @code{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.

@item @b{booleans}, where the lowest four bits of machine words
containing booleans are equal to @code{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.

@item other values: the empty list, void and end-of-file. The lowest
four bits of machine words containing these values are equal to
@code{C_SPECIAL_BITS}. Bits 5 to 8 contain an identifying
number for this type of object.  The following constants are
defined: @code{C_SCHEME_END_OF_LIST C_SCHEME_UNDEFINED
C_SCHEME_END_OF_FILE}

@end itemize

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

@itemize

@item 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.

@item bits 25 to 28 contain the type code of the object.

@item bits 29 to 32 contain miscellaneous flags used for garbage
collection or internal data type dispatching.
These flags are:
@table @code

@item C_GC_FORWARDING_BIT

Flag used for forwarding garbage collected object pointers.

@item C_BYTEBLOCK_BIT

Flag that specifies whether this data object contains raw bytes (a string
or byte-vector) or pointers to other data objects.

@item 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.

@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).

@end table

@end itemize


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:

@itemize

@item pairs: vector-like object (type bits @code{C_PAIR_TYPE}),
where the car and the cdr are contained in the first and second slots,
respectively.

@item vectors: vector object (type bits @code{C_VECTOR_TYPE}).

@item strings: byte-vector object (type bits @code{C_STRING_TYPE}).

@item procedures: special vector object (type bits
@code{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).

@item flonum: a byte-vector object (type bits
@code{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.

@item symbol: a vector object (type bits @code{C_SYMBOL_TYPE}). Slots
one and two contain the toplevel variable value and the print-name
(a string) of the symbol, respectively.

@item port: a special vector object (type bits
@code{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.

@item structure: a vector object (type bits
@code{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.

@item pointer: a special vector object (type bits
@code{C_POINTER_TYPE}). The single slot contains a machine pointer.

@item tagged pointer: similar to a pointer (type bits 
@code{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.

@end itemize


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 @code{chicken.h}.


@node Bugs and limitations
@chapter Bugs and limitations


@itemize

@item Compiling large files takes too much time.

@item There is no support for rationals, complex numbers or
extended-precision integers (bignums).

@item The maximal number of arguments that may be passed to a compiled
procedure or macro is 126 (or 1024 on x86 platforms).  A macro-definition
that has a single rest-parameter can have any number of arguments.

@item The maximum number of values that can be passed to continuations
captured using @code{call-with-current-continuation} is 126.

@item Some numeric procedures are missing since CHICKEN does not support
the full numeric tower.

@item 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.

@item @code{eval-when} doesn't allow toplevel definitions inside its
body in combination with hygienic macros.

@item @code{port-position} currently works only for input ports.

@item Leaf routine optimization can theoretically result in code that
thrashes, if tight loops perform excessively many mutations.

@item Building CHICKEN on RS/6000 systems under AIX is currently not
possible, due to strange assembler errors during compilation of the
compiler sources.

@item If @code{eval} is invoked with @code{scheme-report-environment}
or @code{null-environment} inside the interpreter, then non-standard
syntax is still visible, unless the interpreter has been started with
the @code{-strict} option.

@item When the highlevel macro system is used,
line number information is not properly maintained.

@item @code{format} is not reentrant. This means that recursive invocation
of this procedure (either inside @code{print-object} methods or
record-printer defined with @code{define-record-printer} will
not work.

@item User-defined types are currently not supported in the argument and result
specifications for entry-points defined with @code{define-entry-point}.

@end itemize


@node Acknowledgements
@chapter Acknowledgements

@itemize

@item Jonah Beckford added CHICKEN-support to @uref{http://www.swig.org, SWIG} and
provided support for shared libraries and dynamic loading under Windows.

@item ``Category 5'' ported CHICKEN to several BSD platforms and suggested a great many improvements.

@item Linh Dang translated the TeX manual into texinfo format and wrote the hen emacs mode.

@item Steve Elkins ported CHICKEN to OpenBSD.

@item Tollef Fog Heen and Thomas Weidner helped porting CHICKEN to the AMD-64 platform.

@item Tony Garnock-Jones ported CHICKEN to HP-UX and provided countless
fixes and improvements.

@item Sven Hartrumpf helped porting CHICKEN to the UltraSparc, suggested
many improvements and helped fixing numerous bugs.

@item Bruce Hoult fixed several bugs and pointed out performance improvements.

@item Dale Jordan pointed out several bugs, helped fixing problems on the
Cygwin platform and contributed the @code{calendar.scm} example script.

@item Peter Keller translated the manual from HTML into LaTeX and contributed
the testing infrastructure code.

@item Kirill Lisovsky found a couple of bugs while porting Oleg Kiselyov's
SSAX XML parser to CHICKEN.

@item Dennis Marti ported CHICKEN to Mac OS X.

@item Chris Moline and Bakul Shah helped porting CHICKEN to FreeBSD.

@item Davide Puricelli maintains the Debian package.

@item Doug Quale contributed the configuration scripts for installation
on UNIX-like systems, suggested numerous improvements and was generally
very helpful.

@item Benedikt Rosenau found several bugs and spent a lot of time testing
the system and pointing out improvements.

@item Michele Simionato discovered several bugs and provided numerous helpful suggestions.

@item Dorai Sitaram pointed out several improvements in the TeX manual.

@item Mike Thomas ported CHICKEN to the Mingw32 platform.

@item John Tobey ported CHICKEN to MIPS.

@item Panagiotis Vossos ported CHICKEN to Alpha/Linux.

@item Peter Wang produced countless bugfixes and helpful suggestions.

@item Jorg Wittenberger found and fixed countless bugs in the runtime system.


@item CHICKEN contains code from several people:
@itemize
@item Eli Barzilay: some performance tweaks used in TinyCLOS.
@item Anthony Carrico: the option parsing facility.
@item Mikael Djurfeldt: topological sort used by compiler.
@item Marc Feeley: pretty-printer.
@item Aubrey Jaffer: implementation of @code{dynamic-wind}.
@item R. Kent Dybvig, Oscar Waddel, Robert Hieb & Carl Bruggeman: @code{syntax-case} macro system.
@item Gregor Kiczales: original implementation of TinyCLOS.
@item Dirk Lutzebaeck: Common LISP @code{format}.
@item Richard O'Keefe: sorting routines.
@item Jussi Piitulainen: reference implementation for SRFI-25.
@item Olin Shivers: implementation of @code{let-optionals[*]} and
reference implementations of SRFI-1, SRFI-13 and SRFI-14.
@item Dorai Sitaram: the PREGEXP regular expression package and
TeX2page, which was used to generate the HTML documentation.
@item Andrew Wilcox: queues.
@item Andrew Wright: pattern matcher.
@end itemize

@end itemize


Thanks also to:

William Annis, Marc Baily, Peter Barabas, Peter Bex, Dave Bodenstab, T. Kurt Bond, Terence Brannon, Roy Bryant, Taylor Campbell, Franklin Chen, 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, Charles Martin, Alain Mellan, Perry Metzger,
Scott G. Miller, Mikael, Bruce Mitchener, Eric Merrit,
Eric E. Moore, o.t., 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, Matthew Welland, 
Richard Zidlicky and Houman Zolfaghari for bug-fixes, tips, suggestions and moral support.

@node Bibliography
@unnumbered Bibliography

@table @asis
@item Henry Baker: @emph{CONS Should Not CONS Its Arguments, Part II: Cheney on the M.T.A.}
@code{http://home.pipeline.com/\~hbaker1/CheneyMTA.html}
@item Revised^5 Report on the Algorithmic Language Scheme
@code{http://www.schemers.org/Documents/Standards/R5RS}
@end table

@node Index
@unnumbered Index
@printindex fn

@bye