\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename sizzle-ref.info
@settitle Sizzle Reference Manual
@iftex
@afourpaper
@end iftex
@c %**end of header

@set UPDATED 6 Dec 2000
@set EDITION 0.0.30
@set VERSION 0.0.30

@dircategory Sizzle Scheme Interpreter
@direntry
* sizzle-ref: (sizzle-ref).     Sizzle reference manual.
@end direntry

@ifinfo
This file documents the Sizzle Scheme interpreter.

Copyright (C) 1999, 2000 Martin Grabmueller

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@end ifinfo



@c --- title page starts here ---

@titlepage
@title Sizzle
@subtitle Reference Manual
@subtitle Version @value{VERSION}
@author Martin Grabmueller

@c  The following two commands
@c  start the copyright page.
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1999, 2000 Martin Grabmueller

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.
@end titlepage

@c --- title page ends here ---



@syncodeindex vr cp
@syncodeindex fn cp



@node Top, Introduction, (dir), (dir)
@comment  node-name,  next,  previous,  up

@ifinfo
This document describes how to use the Scheme interpreter Sizzle.

It applies to version @value{VERSION} of Sizzle.
@end ifinfo

@menu
* Introduction::                Introduction to Sizzle
* Using Sizzle::                How to use Sizzle
* Programming Scheme::          Programming in Scheme and Sizzle
* Predefined Variables::        Variables for controlling the interpreter
* Builtin Procedures::          All predefined procedures and forms
* Sizzle vs R5RS::              Comparison of Sizzle and Standard Scheme
* Glossary::                    The glossary
* Index::                       Function and variable index
@end menu



@node 	 Introduction, Using Sizzle, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Introduction

Sizzle is an interpreter for the Scheme programming language. It is
designed to be used as an embedded extension language and as a scripting
language for a wide variety of purposes.

Sizzle implements a subset of Scheme as described in the Revised 5
Report on the Algorithmic Language Scheme (referred to as R5RS in this
manual).  That means that Sizzle employs fully parenthesized prefix
notation (as known from Lisp), is statically scoped and handles builtin
and user defined procedures as first-class objects. It implements most
of Scheme as defined in R5RS, but it does not support complex numbers,
arbitrary precision numbers (bignums) or rational numbers.  In addition,
only outward continuations (a.k.a. escape procedures) are implemented.

That means that Sizzle is a quite powerful language and will (as least I
hope so) be useful for a lot of programming tasks.

Most of the text in the reference section of this manual is heavily
inspired by R5RS, especially the description of the standard syntactic
forms and standard procedures.  Some parts, especially documentation on
procedures compatible with Guile, have been taken from the Guile
documentation strings.

The chapter after this introduction describes Sizzle from the user's point
of view, you will learn how to start the interpreter and how to use it
interactively as well as how to use it to execute Scheme scripts.

After that, in the third chapter, I will show how to do basic
programming in the Scheme programming language and which data types are
available and how to make use of them.

The fourth chapter documents the builtin variables which can be used to
monitor and manipulate the interpreter's behaviour from Scheme.

The main reference section (chapter 5) documents all procedures as well
as the syntactic forms available in the interpreter.

The sixth chapter lists all (known) differences between the Scheme
implementation of Sizzle and the standard defined in R5RS.

The manual is closed by a a glossary and an index of all functions and
variables.

@menu
* Sizzle History::              How Sizzle became what it is now
* Sizzle Future::               Future changes planned
@end menu



@node 	 Sizzle History, Sizzle Future, Introduction, Introduction
@comment  node-name,  next,  previous,  up
@section Sizzle History

I started writing Sizzle simply because I was interested in compiler and
interpreter design.  A long time ago, I had been porting a lisp
interpreter called XLISP, which was written in C to Pascal.  Ever since
I was interested in parenthesized languages, and when I learned about
Scheme, I was immediately fascinated by its clear and beautiful design.
So I started writing small Scheme scripts and finally became more
interested and decided to build an interpreter.  It started out small,
as always, but soon I noticed that I was able to implement even a bit
more complicated features, so the interpreter grew.  Now the
distribution is more than half a meg big, and still grows.



@node 	 Sizzle Future,  , Sizzle History, Introduction
@comment  node-name,  next,  previous,  up
@section Sizzle Future

I hope that I will be able to make a more accurate and complete
documentation someday.  Also, there are a few features I would like to
see in the interpreter, such as bignum arithmetic, rationals, hygienic
macros, etc.  Some internal architectural changes seem desirable also,
for example for speeding up the reader. Some profiling for creating a
faster evaluator will be on the wishlist also, maybe more extensive
syntax rewriting may help with this.

I would like to see all (at least all sensible) SRFIs implemented.
Currently, only SRFI-1, SRFI-6 and SRFI-8 are implemented. SRFI-13 is
implemented partly.



@node Using Sizzle, Programming Scheme, Introduction, Top
@comment  node-name,  next,  previous,  up
@chapter Using Sizzle

Sizzle is an embedding language which can be easily integrated into
other programs written in C, but it also includes a command line program
which can be used to do calculations in an read-eval-print loop as well
as running scripts written in the Scheme language.

This chapter will explain how to make use of Sizzle as an interactive
program as well as how to execute script files.

@menu
* Starting Sizzle::             How to invoke Sizzle
* Interactive Usage::           Using Sizzle's read-eval-print loop
* Automatic Interactive Variable::  
* Command Line Editing::        Command lin editing and history
* Sizzle Scripts::              Using Sizzle to run scripts
* Startup Sequence::            What happens when Sizzle starts up?
* Environment Variables::       Environment variables used by Sizzle
* Building Sizzle::             
@end menu



@node Starting Sizzle, Interactive Usage, Using Sizzle, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Starting Sizzle

To start Sizzle, simply type @samp{sizzle} at the command line.  Sizzle
will then initialize and start reading expression from the terminal. It
will read and evaluate expressions and print them to the screen until
you terminate it by either pressing @samp{^D} at the prompt or entering
the expression @samp{(exit)}.

The command line interpreter understands the command line options shown
in the table below.

@table @code
@item -s, --script=@var{file}
Execute the Scheme source file @file{file}, and exit.
@item -c, --command=@var{expr}
Evaluate the Scheme expression @var{expr}, and exit.
@item --
Stop processing options and treat all following arguments as
non-options, even if they begin with a dash (@code{-}).
@item -l, --load=@var{file}
Load Scheme source code from @file{file}.
@item -e, --eval=@var{function}
After reading script given with @code{-s, --script=@var{file}}, apply
@var{function} to command line arguments.  This option also can be used
with @code{-c, --command=@var{expr}}.
@item -h, --help
Show a help message about program usage and terminate.
@item -v, --version
Show the version of the program and terminate.
@item -q, --no-init-file
Do not load the user's init file @file{~/.sizzle}.
@item -n, --no-system-init-file
Do not load the system init file.
@item -d, --debug
Increase the debugging level.  This option can be given more than once,
each occurence will turn on more debugging messages.
@end table

The command line option @code{-s, --script=@var{file}} has to be used
whenever a Scheme script is to be executed by Sizzle.  The file
@file{file} will be read and all Scheme expression contained in it will
be evaluated in order.  After evaluation is finished, Sizzle terminates.
For more details about Sizzle scripts see @ref{Sizzle Scripts}.

@code{-c, --command=@var{expr}} is similar, but instead of reading a file of
Scheme expressions, the Scheme expression @var{expr} will be evaluated.

Note that when using @code{-s} or @code{-c}, all remaining arguments on
the command line are ignored by Sizzle and are passed to the Scheme
script or the Scheme expression without interpretation and are available
via the primitive @code{command-line}, please see @ref{System interface
functions}.

The pseudo--option @code{--} will be discarded from the command line,
but all remaining parameters will be treated as normal arguments and not
as options, even if they begin with a dash (@code{-}).  This can be used
when passing options to a Sizzle script.

All file names given with the option @code{-l, --load=@var{file}} (which
can be given more than once) are loaded into the interpreter by
evaluating all expressions read from the files, but unlike @code{-s},
the interpreter will not terminate after evaluating the files, but
continue as normal.  That means, that without @code{-s} and @code{-c},
the interactive read--eval--print loop will start, otherwise the
appropriate action will be done, as described above.

@code{-e, --eval=@var{function}} is intended to be used with @code{-s},
when you are using Scheme files which can be used both as library files
and as executable scripts.  You can do this by placing library code in
the file and a function which serves as the main function.  When you use
@code{-s}, the file will simply be loaded, but the main function will
normally not get called.  This is exactly what @code{-e} is for.  Simply
pass the name of the main function to @code{-e} and this function will
then be applied to the remaining command line arguments after the script
file has been loaded.

@code{-h, --help} will print out a short helping message and then quit.

@code{-v, --version} prints out the version of the Sizzle interpreter
you have installed, and then terminate.  Use this command if you want to
complain about a bug in your version of Sizzle, in addition to as much
information about your system as possible.

Use the option @code{-q, --no-init-file} if you want to inhibit
automatic loading of your user's init file @file{~/.sizzle}.

Similarly the option @code{-n, --no-system-init-file} prevents the
system's init file from being loaded.  Note that with this option, some
common procedures will not be available in the interpreter.

With the option @code{-d, --debug}, Sizzle will print some debugging
messages while running.  Each occurence of @code{-d} increases the
debugging level and will cause more information to be printed out.  This
option will not be very interesting for normal users and is intended for
being used by the Sizzle developers.


@node Interactive Usage, Automatic Interactive Variable, Starting Sizzle, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Interactive Usage

When you have started the Sizzle interpreter, you can start right away
with typing in Scheme expressions and see how they evaluate.  I will
give some simple examples in this section.

Numbers, characters and strings can be entered in their read syntax and
evaluate to themselves.
@example
zzz: 1
1
zzz: "Hello World"
"Hello World"
zzz: #\H
#\H
@end example

Lists and vectors need to be quoted, because they do not evaluate to
themselves.  Lists are considered to be function calls and therefore
evaluate in a special way (see below).  The reason why vector constants
do not evaluate is not clear to me, but R5RS requires that. Strange...

@example
zzz: #(1 2)
exception: misc-error: vectors do not evaluate to themselves
no backtrace available
evaluate `(set! %save-backtrace% #t)' if you want backtraces
zzz: '#(1 2)
#(1 2)
@end example

@example
zzz: (1 2)
exception: misc-error: not a procedure: 1
zzz: '(1 2)
(1 2)
@end example

In the above two examples, error messages have been printed in response
to the user's input.  In an error message, the type of the error is
printed first: Here, it is an exception of type @code{misc-error}.  The
following is a description of the error.  In addition, we can see that
the first error shown to the user includes some more information: The
fact that currently backtraces are not available is noted and a tip how
to enable procedure backtraces.

Procedures are invoked by writing the function name as the first member
in a list.  Consider the function @code{+}, which adds all its
arguments.
@example
zzz: (+ 1 2)
3
zzz: (+ 1 2 -4)
-4
@end example


@node Automatic Interactive Variable, Command Line Editing, Interactive Usage, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Automatic Interactive Variable

When running the standalone interpreter, Sizzle defines automatically a
special variable to ease interactive usage.  The result of an evaluation
is automatically assigned to the top-level variable @var{$$}, which can
be used in following expressions.  Note that the value of this variable
is overwritten after each successul operation, so you have to save it
yourself if you want to use it later.

@example
zzz: 1
1
zzz: $$
1
zzz: "foobar"
"foobar"
zzz: (string-length $$)
6
@end example


@node Command Line Editing, Sizzle Scripts, Automatic Interactive Variable, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Command Line Editing

Note: Readline support has been removed from the Sizzle core, so you
have to install the additional package @file{sizzleopt} to make use of
it.

When available, Sizzle uses the @file{readline} library to provide
command line editing to the command line interpreter.

The @file{readline} library enables command line editing with the cursor
keys and some key sequences known from Emacs. Also, a command line
history is available, you can recall previously typed in lines with the
cursor-up key.  Tab-completion, known from the shell is supported, too.
When you type the beginning of a word and then hit the @key{TAB} key,
the word will be completed; when there are several possible matching
words, readline will complete as much as possible and then beep.  You
can then press the @key{TAB} once more to get a list of the matches.

Sizzle is a little bit context sensitive with tab-completion. When the
word you are completing comes directly (or only seperated by whitespace)
after an opening parentheses, only procedure names are completed, in all
other positions, variable names are also completed.

The command line history which is maintained by the @file{readline} can
be written to the file @file{.sizzle_history} when Sizzle exits and read
in when it starts again.  By default, this feature is disabled to avoid
filling the home directory of users who do not wish their programs to do
so.  You have to set the boolean variable @var{%write-history-file%} to
@code{#t} to enable command line history saving.  The best place to do
so is in the user initialization file @file{.sizzle} in the user's home
directory.


@node Sizzle Scripts, Startup Sequence, Command Line Editing, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Sizzle Scripts

Sizzle is not only suitable for interactive usage, but also for
programming Scheme scripts.  These scripts can manipulate text, can do
numeric calculations or can even be CGI scripts.  Sizzle scripts can
include code from the Sizzle library using the @code{load} procedure.

The Sizzle program runs in non-interactive mode if you invoke it with
the @samp{-s} option, like @samp{sizzle -s kewlt-scheme-program.scm}.

You can run Sizzle scripts without having to type the name of the Sizzle
executable if you include the following two lines at the top of your
script and making the script executable using the @file{chmod} program:

@example
#! /usr/local/bin/sizzle -s
!#
@end example
@noindent
Another possibility is to make the following lines the first ones in
your script.  This version has the advantage that it is independent on
the location of your Sizzle executable, but it is a little bit less
efficient because the operating system has to start a shell, which in
turn starts the Sizzle interpreter.  Normally, the performance
difference will not be noticable, though.

@example
#! /bin/sh
exec sizzle -s $0
!#
@end example

Scheme scripts can examine the arguments they were given by calling the
procedure @code{command-line}.  It returns a list of strings, each being
one command line argument.  The first member of the list is the name of
the interpreter, or (if you have a more sophisticated Unix flavour and
are using the @code{#!} notation for executing the interpreter) the name
of the script.



@node Startup Sequence, Environment Variables, Sizzle Scripts, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Startup Sequence

On startup, the file @file{init.scm} which was installed together with
the binaries and libraries is loaded before evaluating expressions from
source files or the command line, and before entering the
read-eval-print loop.  @file{init.scm} is stored in the directory
@file{$prefix/share/sizzle/$version/}, where @code{$prefix} is set
during configuration time (defaults to @file{/usr/local}) and
@code{$version} is the version of your installed Sizzle package.

In addition, the system init file loads the file @file{.sizzle}, if it
exists, from the user's home directory.  So if you like to customize
Sizzle's behaviour, this file is the right one to put Scheme
expressions.

Note that these startup files are loaded whenever the interpreter starts
up, no matter whether it runs interactively in the read-eval-print loop
or was started to run a Scheme script.

Loading of the initialization files can be suppressed by using the
command line options @code{-q, --no-init-file} and @code{-n,
--no-system-init-file}.  The former inhibits the loading of the user's
initialization file @file{~/.sizzle}, whereas the latter suppresses
loading of the system-wide initialization file.


@node Environment Variables, Building Sizzle, Startup Sequence, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Environment Variables

When Sizzle starts up, it examines the contents of the environment
variable @code{SIZZLE_LOAD_PATH}.  If it is set, it must contain a
colon-separated list of directory names.  Each of these path names is
then prepended to the global variable @var{%load-path}, in the order
they appear in the environment variable.  This environment variable
makes it possible to modify the locations where Sizzle searches for
files which are loaded via @code{load} or @code{primitive-load-path}, or
modules which are included with @code{use-modules}.


@node Building Sizzle,  , Environment Variables, Using Sizzle
@comment  node-name,  next,  previous,  up
@section Building Sizzle

Some notes on building the Sizzle library and interpreter.

First, you have to get a Sizzle archive. You should be able to get a
recent version from
@url{http://www.pintus.de/mgrabmue/sizzle/sizzle.html}.  Just follow the
@emph{Download} link and download an archive like
@file{sizzle-0.0.30.tar.gz}.  Replace the version number with the newest
available version.  You may also want to download the @emph{sizzleopt}
package, which includes some useful bindings, such as @file{readline}
support for the interpreter.

Unpack the distribution tarball to a directory of your choice:
@example
$ cd src
$ tar xzvf sizzle-0.0.30.tar.gz
sizzle-0.0.30/
sizzle-0.0.30/Makefile.in
...
@end example
Change to the newly created directory.
@example
$ cd sizzle-0.0.30
@end example

When compiling for Windoze using Micro$oft Visual C, you can use the
provided Project files.  Refer to the @file{README-Win32} file for
further information.

Now you have configure the package.  Most of the times, this just requires you to type
@example
./configure
@end example
but you may want to change the configuration to suit your needs.  Invoke
@file{configure} with the @code{--help} option to get a list of the
supported options.

Currently, the following configuration options besides the standard
options are supported:
@table @code
@item --enable-warnings
Switches on most compiler warnings.  This may be useful for the
maintainer only or people who want to hack on the package.  This is off
by default.
@item --enable-debug
Switch on debugging code.  This is on by default.
@item --enable-posix
Compile in Posix functions such as @code{getpid}, @code{fork} etc.
This is on by default.
@item --enable-regexp
Compile in support for Posix regular expressions.  This is on by
default.
@item --enable-maximum-functionality
This option controls inclusion of some code which may not be needed for
all users, such as networking support.
@item --enable-dl
Compile in dynamic linking code.  This will enable the library to load
extension modules without recompilation.  This is on by default.
@item --enable-uvector
Enable support for uniform vectors.  They are currently not compiled in
by default because I do not use them now, and they bloat up the library
unnecessarily.
@item --with-mingw=DIR
When compiling for Windoze, you can give the location of your MingW32
installation here.
@item --enable-shared
Enable the compilation of chared libraries.  On by default.
@item --enable-static
Enable the compilation of static libraries.  On by default.
@item --disable-nls
Switch off national language support.  You may want to use this if your
NLS is broken or you simply don't like localized messages.
@end table
Every @code{--enable} option has a @code{--disable} pendent to switch
off a particular feature.

After a while, the configuration is done and you can compile the package.
@example
$ make
@end example

When compiled, the package is ready for installation.  Note that only
the super-user may do this if you are installing to the default location
@file{/usr/local}.
@example
$ su
Password:
# make install
# exit
$
@end example

When everything worked well, you can now use the Sizzle interpreter.
@example
$ sizzle
zzz: (+ 1 2)
3
zzz:
@end example



@node Programming Scheme, Predefined Variables, Using Sizzle, Top
@comment  node-name,  next,  previous,  up
@chapter Programming Scheme

This chapter gives a quick introduction to programming in the Scheme
language.  It will also mention Sizzle limitations and features where
appropriate.

@menu
* General::                     Basics about Scheme programming
* Storage Model::               Storage model used by the Sizzle interpreter
* Data Types::                  Available data types and their usage
@end menu



@node General, Storage Model, Programming Scheme, Programming Scheme
@comment  node-name,  next,  previous,  up
@section General

Scheme uses fully parenthesized prefix notation, that means that all
procedure calls are enclosed in parentheses.  The first element in a
procedure call is the procedure which will be invoked and the other
elements are the arguments which will be passed to the procedure.  Note
that the procedure will be evaluated in the same way as the rest
parameters.

@example
zzz: (+ 1 2)
3
zzz: ((lambda (x) x) 1)
1
@end example
@noindent
All arguments in Scheme are passed by value, e.g evaluated before the
procedure is called.  Special forms like @code{if}, @code{define}
etc. do not follow that rule, they evaluate their arguments only when
needed.  There is no syntactic difference between a procedure call and
the application of a special form, so you need to know the names of all
special forms in order to tell how some given code will evaluate.

Variables are defined using the special form @code{define} and can be
modified lateron by using @code{set!}, which is another special form.

@example
zzz: (define a 1)
zzz: a
1
zzz: (set! a 2)
zzz: a
2
@end example
@noindent
Functions are either defined by defining a variable with the value of a
lambda expression or using a special form of @code{define}, which is
intended for defining procedures more easily.

@example
zzz: (define identity (lambda (x) x))
zzz: (identity 2)
2
zzz: (exit)
$ sizzle
zzz: (define (identity x) x)
zzz: (identity 3)
3
@end example
@noindent
When you define a variable more than once in an environment, the former
definition will be silently overwritten.


@node Storage Model, Data Types, General, Programming Scheme
@comment  node-name,  next,  previous,  up
@section Storage Model

The Sizzle core contains a garbage collector, so that the programmer is
not responsible to free objects which are not needed anymore.
Internally, the garbage collector is implemented as a conservative
collector which marks all objects as being used which are reachable
through global variables (known to the collector) or are reachable by
scanning the C stack.

At the moment, the garbage collector is a very simple, recursive
mark-and-sweep collector, without generations or incremental behaviour.
It has been sufficient for my needs, but maybe I will switch to a more
sophisticated algorithm later when a need for it apears.


@node Data Types,  , Storage Model, Programming Scheme
@comment  node-name,  next,  previous,  up
@section Data Types

Sizzle has a lot of useful data types already built in, and provides a
lot of procedures for manipulating values of various types.  For
detailed description of the available data manipulation functions please
refer to the Programming Reference chapter in this manual.

@menu
* Numbers::                     Numeric data types
* Booleans::                    Boolean data type
* Characters::                  Character data type
* Strings::                     String data type
* Symbols::                     Symbol data type
* Keywords::                    Keywords data type
* Cons Cells::                  Cells of two values
* Vectors::                     Vectors of values
* Homogenous numeric vectors::  Numeric vectors with type safety
* Hash tables::                 
* Procedures::                  Functions and syntactic forms
* Regular Expressions::         Regular expressions for matching text
* Multiple Values::             Returning multiple values from procedures
* Special values::              Special values in the interpreter
* Constants::                   Defined constants
* Ports::                       Input and output facilities
* Errors and Exceptions::       Sizzle error and exception concept
* Continuations::               Evaluation continuations
* Boxes::                       Box data type
* Pointers::                    Pointer data type
@end menu



@node Numbers, Booleans, Data Types, Data Types
@comment  node-name,  next,  previous,  up
@subsection Numbers

The Scheme standard defines the so-called @i{numeric tower}, a hierarchy
of numeric data types where every data type includes the values of the
data types lower in the hierarchy and which is defined as follows:

@table @code
@item number
All numbers belong to the data type @i{number}.
@item complex
@i{Complex} numbers consist of a real and an imaginary part.
@item real
@i{Real} numbers are all rational and irrational numbers.
@item rational
@i{Rational} numbers consist of a numerator and a denominator.
@item integer
@i{Integers} are all numbers without a fraction component.
@end table

Furthermore, Scheme makes a difference between @i{exact} and @i{inexact}
numbers.  @i{Exact} numbers are always precise whereas @i{inexact}
numbers are only an approximation.  The same differentiation is made for
operations on numbers.  For example, the addition of two exact numbers
always produces an exact result, but on the contrary, the division of
exact numbers may be inexact.

The read syntax for numbers is as follows: the number may starts with an
optional number of exactness and radix , followed by a number of digits
which must fit into the radix scheme which may be given with a radix
prefix.  Then a decimal point and another sequence of numbers may
follow, in decimal or scientific notation may follow.  A list of the
valid exactness and radix prefices is given in the following table.

@table @code
@item #e
Number is exact
@item #i
Number is inexact
@item #b
Binary number, radix 2
@item #o
Octal number, radix 8
@item #d
Decimal number, radix 10
@item #x
Hexadecimal number, radix 16
@end table

Integers are exact numbers with the same range as the C @code{long} data
type.

Examples of integer constants:
@example
42
-23
#xdead
#o755
#b100001010
#d42
@end example

Floats are floating point values, corresponding to @code{double} values
in C. Real number constants can start with a radix and exactness prefix,
but only the radix prefix @code{#d} is allowed. When using the exactness
prefix @code{#e} (exact number), the number must have a fraction of
zero.  Read syntax examples:

@example
3.1459
-10.1e2
#i1.0
#e1.0
@end example

Complex and rational numbers are not supported by Sizzle.  Maybe in the
future they will.  Also @i{bignums} (arbitrary precision numbers), as
known from other Scheme systems, are not (yet) supported.



@node Booleans, Characters, Numbers, Data Types
@comment  node-name,  next,  previous,  up
@subsection Booleans

Booleans are the truth values true and false, in Scheme written like
this: @code{#t} means true and @code{#f} means false.

In Scheme, @code{#f} is the only value that is considered false in
conditionals, neither @code{0} nor the empty list @code{'()} counts as
false.



@node Characters, Strings, Booleans, Data Types
@comment  node-name,  next,  previous,  up
@subsection Characters

Characters are denotated in the following form: first, a hash mark (@code{#}), then a backslash and then the literal character. Examples:
@table @code
@item #\j    
The character `j'
@item #\     
The space character
@end table

Scheme provides another notation for non-printable characters. A space
character can also be written like this @code{#\space} and a newline
like @code{#\newline}. Sizzle understands three additional symbolic names for characters. This table shows all of them:
@table @code
@item #\space
The space character
@item #\newline
The newline character
@item #\return
The carriage return character
@item #\tab
The tab character.
@item #\bell
The bell character.
@end table



@node Strings, Symbols, Characters, Data Types
@comment  node-name,  next,  previous,  up
@subsection Strings

Strings are sequences of characters. String constants are enclosed in
double quotes and can contain all characters from the ASCII set.  The
double quote character @code{"} and the backslash @code{\} have to be
quoted with a preceding backslash.  Some special non-printable characters can be included in string constants by denoting special backslash-character sequences. The following sequences are defined:
@table @code
@item \n     
Newline
@item \r
Carriage return
@item \t
Tab character
@item \v
Vertical tab
@item \b
Backspace
@item \a
Bell character
@end table

Strings can be mutable and immutable.  Immutable are those which were
literally entered from the input source.  They can not be used with
destructive procedures like @code{string-set!} or @code{string-fill!}.
Strings returned by functions like @code{string-copy} or @code{string}
are mutable and can be used with such strings.



@node Symbols, Keywords, Strings, Data Types
@comment  node-name,  next,  previous,  up
@subsection Symbols

Symbols are values with some special properties. They are written by
simply writing their name, without any quotes or special markup
characters.  The main difference between symbols and strings is that
symbols which have the same textual representation @b{are} in fact the
same object.  Additionally, symbols can have values associated to them,
then they act as variables.

When reading symbols, the Sizzle reader considers all characters which
do not explicitly end the symbol as part of the symbol. These ending
characters are @samp{(}, @samp{)}, @i{whitespace}, @samp{;} and
@samp{"}. It is even possible to include these characters into a symbol
name by preceeding it with a backslash.  Thus, these all are valid
symbol names:
@example
Hello
i-am-a-symbol
strange\ symbol
@end example

Of course, it is not too clever to use symbols with enclosed whitespace
or parentheses in program source code.  Their use can degrade
readability of programs considerably.


@node Keywords, Cons Cells, Symbols, Data Types
@comment  node-name,  next,  previous,  up
@subsection Keywords

Keywords are similar to symbols in that they are represented externally
by a character sequence and that keywords with the same external
representation are indeed the same objects internally.  The difference
between keywords and symbols is that symbols are normally bound to
locations containing values and that these values are retrieved when a
symbols is evaluated, whereas keywords evaluate to themselves.  Thus it
is not necessary to quote keywords on input.

Keywords are written like symbols, but are either prefixed with a colon
(@code{:}) or the sequence hashmark--colon (@code{#:}).  When comparing,
only the keyword name is significant, the prefix is ignored.

@example
zzz: #:keyword
#:keyword
zzz: :keyword
#:keyword
zzz: keyword
error: unbound variable: keyword
@end example

In the above example you can see how keywords evaluate to themselves and
that evaluating an unknown symbol signals an error.  Note also that
keywords are always printed in the @code{#:}--notation, regardless how
they were entered.



@node Cons Cells, Vectors, Keywords, Data Types
@comment  node-name,  next,  previous,  up
@subsection Cons Cells

Cons cells are cells which can hold two other values.  The first of the
value is called the @samp{car} of the cell and the second is called
@samp{cdr} (for historic reasons). In source files and on the
read-eval-print prompt you can create cons cell by using the @dfn{dotted
pair} syntax.
@example
'(foo . bar)
'(1 . 2)
@end example
@noindent
Another way to create cons cells is using the constructor function @code{cons}:
@example
zzz: (cons 1 2)
(1 . 2)
@end example

Lists, the main data structure in Sizzle are also made out of cons cells, but they can be typed in a more convenient way than
@example
(1 . (2 . (3 . '())))
@end example
@noindent
by simply writing
@example
(1 2 3)
@end example
@noindent
Both result in the same value.



@node Vectors, Homogenous numeric vectors, Cons Cells, Data Types
@comment  node-name,  next,  previous,  up
@subsection Vectors

Vectors are similar to arrays in other programming languages. You can
store a fixed count of values in a vector and can access them in
constant time, as opposed to the time for accessing elements of a list,
which is linear to the list length.  The difference to ordinary arrays
is that the elements of a vector can have different types.

Vectors are written like lists, but before the opening parentheses you have to put a hash mark.
@example
#(1 2 3 4 5 6 7)
#("Hello" #\  "World" \#!)
#(#(1 2) #())
@end example
@noindent
The last example shows that vectors may contain vectors and that vectors
may be empty.

Vectors can be mutable and immutable.  Immutable are those which were
literally entered from the input source.  They can not be used with
destructive procedures like @code{vector-set!} or @code{vector-fill}.
Vectors returned by functions like @code{make-vector} or @code{vector}
are mutable and can be used with such strings.

@node Homogenous numeric vectors, Hash tables, Vectors, Data Types
@comment  node-name,  next,  previous,  up
@subsection Homogenous numeric vectors

Note: Currently, homogenous numeric vectors are only available if
support for them has been explicitly enabled on configuration time for
the package.  See @ref{Building Sizzle} for how to enable the support if
your installed version lacks it and you need it.

Normal Scheme vectors are heterogenous datatypes.  You can store any
value in them, just as you can with lists.  Sizzle provides another kind
of vectors, so-called homogenous numeric datatypes, as defined in
SRFI-4.  These vectors are special, because it is only possible to store
numbers of a particular data type in there.  There are 10 different
types of those vectors, each for another numeric data type: signed 8-bit
values, unsigned 8-bit values, signed 16-bit values, unsigned 16-bit
values, signed 32-bit values, unsigned 32-bit values, signed 64-bit
values, unsigned 64-bit values, 32-bit floating point values and 64-bit
floating point values.  Only values of their type can be stored into
these vectors, so they provide additional type safety.  They are also
more space-efficient, because, for example, vectors of signed 8-bit
quantities need only to reserve 8 bits for each elements, whereas normal
vectors reserve at least 32 bit for eacht element, up to 160 bits.

Each of the data types has its own type prefix, which is used in all
procedures dealing with that type.  The following table defines the
prefixes.
@table @asis
@item s8
signed 8-bit values
@item u8
unsigned 8-bit values
@item s16
signed 16-bit values
@item u16
unsigned 16-bit values
@item s32
signed 32-bit values
@item u32
unsigned 32-bit values
@item s64
signed 64-bit values
@item u64
unsigned 64-bit values
@item f32
32-bit floating point values
@item f64
64-bit floating point values
@end table

Homogenous numeric vectors have a read (and print) syntax similar to
vectors, but between the hash mark and the opening parentheses the
prefix for the vector type must be inserted:

@example
#u8(1 2 3 4 5 6 7)
#s16(-42 23 2 0)
#f32(1.2 3.14159265)
@end example
@noindent
Similar to normal vectors, literally denoted homogenous vectors are
read-only and can not be modified using primitive procedures like
@code{u8vector-set!}.  Use procedures like @code{make-f64vector} to
create mutable vectors.


@node Hash tables, Procedures, Homogenous numeric vectors, Data Types
@comment  node-name,  next,  previous,  up
@subsection Hash tables

Hash tables (aka associative arrays) are very useful data structures,
when a non-trivial programming task is at hand.  Hash tables provide a
mapping from one object to another and are similar to @emph{association
lists}, but they are significantly faster when they grow large.

In Sizzle, hash tables can be written literally with a @code{#@{}
prefix, followed by key/value pairs separated by the arrow symbol
(@code{=>}), like this, terminated by a closing brace (@code{@}}):
@example
zzz: #@{Joe => "cool" Jim => "lame"@}
#@{Jim => "lame" Joe => "cool"@}
@end example
This is also the print syntax for hash tables.

Another possibility is to use the procedure @code{make-hash} which
constructs a hash table from its arguments.  All arguments must be pairs
which will be taken as key/value pairs and inserted in the new hash
table.
@example
zzz: (make-hash '(Joe . "cool") '(Jim . "lame"))
#@{Jim => "lame" Joe => "cool"@}
@end example

Note that the order of the key/value pairs depends on the size of the
data structure internally used to store the values and may differ for
the same input, when this size is not the same.  The size is either
chosen internally, depending on the number of pairs, or can be provided
as an optional first argument to @code{make-hash}:
@example
zzz: (make-hash '(Joe . "cool") '(Jim . "lame"))
#@{Jim => "lame" Joe => "cool"@}
zzz: (make-hash 32 '(Joe . "cool") '(Jim . "lame"))
#@{Joe => "cool" Jim => "lame"@}
@end example
The best choice for the size argument is a prime number not too near to
a power of 2 (so says Knuth).



@node Procedures, Regular Expressions, Hash tables, Data Types
@comment  node-name,  next,  previous,  up
@subsection Procedures

There are three kinds of procedures in Sizzle: Builtin procedures,
builtin syntactic forms and user-defined procedures (lambda
expressions, or closures).

The difference between builtin functions and syntactic forms is that
funtions evaluate their arguments before theu are called and arguments
to syntactic forms are only evaluated when needed.

Builtin functions and syntactic forms do not have any read syntax (that
would not make sense) and they print in the following way:
@example
zzz: set!
#<macro set!>
zzz: append
#<primitive-procedure append>
@end example

Closures print as a pair of the lambda expression they stand for and the
address of the environment the expression is closed over.
@example
zzz: (define (f n) n)
zzz: f
#<closure #<procedure f (n)> 0x401af072>
@end example



@node Regular Expressions, Multiple Values, Procedures, Data Types
@comment  node-name,  next,  previous,  up
@subsection Regular Expressions

Regular expressions are created using the primitive procedure
@code{make-regexp}.  The resulting regular expression object can then be
used in calls to @code{regexp-exec} in order to match the regular
expression against strings.  The format of the regular expression passed to @code{make-regexp} is the same as for the Posix regular expressions.  For more information, type
@example
man regex
@end example
@noindent
Regular expressions are not part of any Scheme standard, but the
procedures implemented in Sizzle are compatible to those used by Guile.

@example
zzz: (define rx (make-regexp "foo|bar"))
zzz: (regexp-exec rx "a-foo-baz")
#("a-foo" (2 . 5))
zzz: (regexp-exec rx "bar-o-matic")
#("bar" (0 . 3))
@end example

Due to limitations in the interface of Posix regular expressions,
regular expressions in Sizzle may not contain null bytes.  Pattern
strings are truncated at the first null byte on compilation.



@node Multiple Values, Special values, Regular Expressions, Data Types
@comment  node-name,  next,  previous,  up
@subsection Multiple Values

In Scheme, it is possible to return more than one value from a
procedure.  This is done by using the primitive procedure @code{values}
as the last expression in your procedure.  Handling those values when
returned from a procedure is a bit strange, since the only standard form
defined for that purpose is @code{call-with-values}.  The following
examples may (hopefully) clear up the whole mess.

@example
zzz: (values 1 2 3)
1
2
3
zzz: (call-with-values (lambda () (values 1 2)) (lambda (x y) (+ x y)))
3
@end example
@noindent
When multiple values are returned to the read-eval-print loop, they are
printed one after the other, every value on a new line.  The second
example shows the usage of @code{call-with-values}, where the first
lambda expression is evaluated (and returns multiple values) and the
values returned from the first procedure are passed to the second
procedure as normal arguments.


@node Special values, Constants, Multiple Values, Data Types
@comment  node-name,  next,  previous,  up
@subsection Special values

Some values which appear in the interpreter are different from all
others and cannot be assigned to one of the data types.  These values
are referred to as @dfn{Special Values} in this manual.  Examples of
these special values are the @code{end-of-file} object which indicates
an end-of-file condition, or the @code{unspecified} object used inside
of the interpreter.


@node Constants, Ports, Special values, Data Types
@comment  node-name,  next,  previous,  up
@subsection Constants

Sizzle supports a weird data type for constants.  They can represent any
Scheme object, but have the additional property that references to
constants are replaced by their value when they are evaluated in a
procedure body.  The result is faster execution, because the necessary
lookup step for variables is eliminated.  Constants are created with the
syntactic form @code{define-constant} and can be used by variable, once
they are defined.

Notice that due to the substitution feature, it is not possible to
redefine a constant.  But would it be a constant then?


@node Ports, Errors and Exceptions, Constants, Data Types
@comment  node-name,  next,  previous,  up
@subsection Ports

All input and output in Scheme is done using @dfn{ports}, which can be
regarded as data sources and sinks.  Ports are characterized by the fact
that they provide procedures for reading and writing data, telling and
setting file pointer positions (if they are built on top of files) and
various others.  Ports are either created explicitly by calls to
procedures like @code{open-input-file}, or implicitely when using
@code{with-output-to-string} and friends.  They have a print syntax, but
no read syntax.

@lisp
zzz: (current-input-port)  
#<rlport:open=1:read=1:write=0>
zzz: (current-output-port) 
#<fdport:open=1:read=0:write=1:fd=1>
@end lisp
The first port in this example is a readline port, which supports
command line editing, parentheses matching etc., the second is a normal
file descriptor port connected to the standard output file descriptor.

Note that readline ports are only available if you have installed the
@file{sizzleopt} package and used the readline module with
@code{(use-modules (readline readlie))}.

At the moment, Sizzle supports so-called @dfn{fdports}, which use an
underlying file descriptor, @dfn{fports} which use an underlying
@file{stdio} file structure, string ports which use an internal
character buffer for input and output, and rlports (readline ports) which
read from the terminal via the @file{readline} library.  The latter
provide fancy command line editing.

@node Errors and Exceptions, Continuations, Ports, Data Types
@comment  node-name,  next,  previous,  up
@subsection Errors and Exceptions

Errors and Exceptions are distinct data types in Sizzle.  Whenever an
error occurs (such as when you pass the wrong number of arguments to a
procedure), an error object is created and then propagated to the top
level, which may be either the read-eval-print loop or a procedure
evaluating a file.  There the error is displayed, using the information
in the error object.  In an error object, an error message is stored,
and if the error comes from the reader module, a file name and a line
and column number is also included.  Error objects can not explicitly
created, but they are created whenever you use the @code{error}
procedure to signal an error.

Exceptions are a bit different.  When raised, they also create objects
containing an error message, but they also contain a so-called
@i{exception tag}, which may be any atom.  Exceptions can be raised from
the Scheme code by calling the procedure @code{throw}.  Using the
exception tag for a particular exception or the catch-all exception tag
@code{#t}, the user can catch exceptions with the procedure
@code{catch}.  

The rule of thumb is that exceptions are raised when an error situation
allows continued evaluation, and errors are signalled on errors which
are too serious to continue.  An examples for exceptions is the
@code{file-not-found} exception, which is raised when a non-existent
file is opened; a quite common situation.  Errors are signalled on
syntax errors, invalid procedure application or typing errors.

Right now, the difference between exceptions and errors in the Sizzle
core is a bit half-baked.  Not all continuable error situations throw
exceptions, a lot of them unnecessarily signal errors.  This will be
changed in the future.  Currently, support for errors is slowly phased
out and all error--signalling places in the code are changed to throw
various types of exceptions instead.


@node Continuations, Boxes, Errors and Exceptions, Data Types
@comment  node-name,  next,  previous,  up
@subsection Continuations

Sizzle only supports continuations usable as escape procedures.  That
means that one cannot export a continuation from the defining context by
returning it from a procedure or storing it into a global variable, and
then try to invoke it.

@node Boxes, Pointers, Continuations, Data Types
@comment  node-name,  next,  previous,  up
@subsection Boxes

Boxes are a data type which are used to store other Scheme objects.  A
box simply contains another object and can be used to pass objects to
procedures in a style similar to call--by--reference calling semantics.

Boxes are created with a call to the procedure @code{make-box}, which
takes the object to store into the box.  The contained object can be
retrieved from a box with @code{box-ref} and set with @code{box-set!}.
The predicate @code{box?} is used to check whether a given object is
actually a box.  For more details on these procedures, see @ref{Box
Operations}.


@node Pointers,  , Boxes, Data Types
@comment  node-name,  next,  previous,  up
@subsection Pointers

Sizzle provides a special data type called @emph{pointer}.  Objects of
this type wrap so--called bounded pointers, that means that they contain
a pointer into the machine's address space together with the size of the
object pointed to.  These objects are used when interfacing to C library
functions which receive character buffers.  Pointer objects created with
the primitive procedure @code{make-pointer} allocate memory when created
and release the allocated memory when the pointer object gets
unreachable.  For more information about pointer procedures,
refer to @ref{Pointer Operations}.


@node Predefined Variables, Builtin Procedures, Programming Scheme, Top
@comment  node-name,  next,  previous,  up
@chapter Predefined Variables

In the Sizzle core, some variables are defined which can be used from
within Sizzle scripts to control and modify Sizzle's behaviour.

Variables labelled as @i{Library variables} are defined in the startup
file @file{init.scm} and thus are only present if the embedding
application has loaded that file on startup.
 
@c @defvar %command-line%
@c A list of all command line options given to the running process.  All
@c parameters not handled by the Sizzle main program are included in the
@c command line.
@c @end defvar

@defvar %load-path
A list of directory names to search when loading Scheme source files.
Initially, only the directories where the Sizzle startup file is located
and the directory for site-specific Scheme files is in the list.  The
user can add more directories if needed. Currently, only the @code{load}
library procedure from the system init file uses this variable.
@end defvar

@defvar %sizzle-version%
This is a string containing version information of the running
interpreter. It has the format @code{major.minor.patchlevel}, and looks
like this: @code{@value{VERSION}}.
@end defvar

@defvr {Library variable} %sizzle-major-version%
@defvrx {Library variable} %sizzle-minor-version%
@defvrx {Library variable} %sizzle-patchlevel%
These variables hold the components of @var{%sizzle-version%}, split up
at the dots and converted to integers.

These variables are not defined when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end defvr

@defvar %write-history-file%
Boolean variable which controls whether the readline history will be
written to the file @file{~/.sizzle_history} when the interpreter
terminates.  By default this is false.  A good place to set this
variable is in your @file{~/.sizzle} personal initialization file.

(Only available if the optional module @code{(readline readline)} was
used).
@end defvar

@c @defvar gc-count
@c Count of garbage collections since Sizzle started.  This is a read-only
@c variable.
@c @end defvar

@defvar gc-message
This is a boolean variable.  If set to @code{#t}, a message will be
printed whenever the garbage collection is invoked or the cell heap
grows.
@end defvar

@defvar %max-evaluate-stack%
Integer variable which holds the maximum evaluation stack size which is
allowed. When the current stack size exceeds this value, an error is
signalled. This variable can be set by user code to allow deeper
recursion, but be careful: when setting this variable to very high
values and performing heavy recursive evaluations Sizzle sometimes dumps
core, because it runs out of stack space.
@end defvar

@defvar %print-read%
Boolean variable which controls whether expressions read in are printed
before evaluating. Mostly for debugging purposes.
@end defvar

@defvar %print-result%
Boolean variable which controls whether expressions are printed after
evaluation even when loading script files. Mostly for debugging
purposes.
@end defvar

@defvar %print-memoized%
Boolean variable which controls the way memoized expressions are
printed.  If true, memoized global and local variables are printed in a
more verbose way; but then the output of @code{(backtrace)} is much less
readable, so this is false by default.
@end defvar

@defvar %print-func-bodies%
Boolean variable which controls whether user-define procedures are
printed with their procedure bodies or not.  If set to @code{#f}, only
the procedure name is printed and the formal parameter list.
@end defvar

@defvar %save-backtrace%
Boolean variable which controls whether a procedure call history is kept
which can be displayed for debugging purposes when errors occur. If you
set this to @code{#t}, the interpreter will consume a lot of memory if
your program is heavily recursive.
@end defvar

@defvar %print-backtrace%
Boolean variable which controls whether procedure call backtraces are
printed immediately after an error or an exception occurs.  If set to
@code{#t}, backtraces are only printed when the primitive
@code{backtrace} is called.
@end defvar

@defvar %print-backtrace-limit%
Integer variable which controls how many lines of backtrace are printed
when an error occurs.  You have to set both @code{eval-save-backtrace}
and @code{eval-print-backtrace} to @code{#t} if you want backtraces.
@end defvar

@defvar %eval-time-taken%
This integer variable holds the time in ticks which the last top-level
evaluation took.
@end defvar


@node Builtin Procedures, Sizzle vs R5RS, Predefined Variables, Top
@comment  node-name,  next,  previous,  up
@chapter Builtin Procedures

Sizzle comes with a large number of builtin functions and special
forms. The difference between these two is that the arguments to a
function are evaluated before the function is called, the arguments to a
special form are only evaluated when needed. This makes a difference for
forms like @code{set!}, because the first argument (a symbol) needs not
be to be quoted like it would have to if @code{set!}  was a
function. Also it is necessary for forms which evaluate their arguments
only when a certain condition holds. @code{if}, for example, only
evaluates its third argument if the first evaluates to the value
@code{#t}.

The provided procedures are grouped into two classes: primitive and
library.  Procedures which are labelled library are only available if
the library files, which are installed together with Sizzle, are loaded
on initialization.  This will be the case if you installed Sizzle
properly.

@menu
* Equality tests::              Testing values for equality
* Numerical operations::        Functions for dealing with numeric values
* Boolean operations::          Functions for dealing with boolean values
* Pair and list operations::    Functions for dealing with boolean values
* Hash table operations::       Functions for manipulating hash tables
* Symbol operations::           Functions for dealing with symbols
* Character operations::        Functions for dealing with characters
* String operations::           Functions for dealing with strings
* Vector operations::           Functions for dealing with vectors
* Homogenous Vector Operations::  Functions for dealing with uniform vectors
* Control flow operations::     Functions for controlling control flow
* Eval function::               Evaluating dynamically created expressions
* Debugging Support::           Support for chasing bugs
* Input and output::            Functions for interacting with the world
* Regular expression functions::  Functions for matching text
* System interface functions::  Functions for interfacing with the system
* Network Procedures::          Network programming support
* Module System::               Module definition and handling
* Dynamic Loading::             Dynamic loading of shared libraries.
* Macro functions::             Macro definition and expanding functions
* Runtime system::              Interfacing the Sizzle runtime system
* Self-Documentation::          Help and documentation utilities
* Box Operations::              Operations on box objects.
* Pointer Operations::          Operations on pointer objects
* Misc functions::              Unsorted functions
* Syntactic Forms::             if, lambda and friends
@end menu


@node Equality tests, Numerical operations, Builtin Procedures, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Equality tests

The following three procedures provide tests for three different degrees
of equality.  They are always available in the interpreter.

@deffn {Primitive procedure} eq? obj1 obj2
Returns @code{#t} if @var{obj1} and @var{obj2} are the same values, that
means if both are stored at the same location in memory.  Symbols with
the same textual representation pass this test, strings don't.  For
numbers, the result is not predictable, @code{(eq? 1 1)} @b{can} return
@code{#t}, but not necessarily. Use @code{eqv?} or @code{=} to test
numbers for equality. Strings can only compared using the predicate
@code{equal?} or one of the string comparison predicates.
@end deffn

@deffn {Primitive procedure} eqv? obj1 obj2
This is the same as @code{eq?} but differs as far as numbers are
concerned. That means that @code{(eqv? 1.0 1.0)} return @code{#t} in any
case.
@end deffn

@deffn {Primitive procedure} equal? obj1 obj2
Returns @code{#t} if the structure of @var{obj1} and @var{obj2} is the
same. You can use @code{equal?} to test lists, vectors and strings for
equality, these data structures are tested recursively.  If you want to
compare strings, use this procedure, or use the procedure
@code{string=?}.
@end deffn



@node Numerical operations, Boolean operations, Equality tests, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Numerical operations

The numerical operations documented in this section are available on all
platforms without needing additional modules.

@c FIXME: Split up numerical operations, maybe in predicates, logic functions,
@c trigonometric etc.

@deffn {Primitive procedure} number? obj
Returns @code{#t} if @var{obj} is a number, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} complex? obj
Returns @code{#t} if @var{obj} is a complex number, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} real? obj
Returns @code{#t} if @var{obj} is a inexact number in floating point
representation, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} rational? obj
Returns @code{#t} if @var{obj} is a rational number, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} integer? obj
Returns @code{#t} if @var{obj} is an exact integer number, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} long? obj
Returns @code{#t} if @var{obj} is an exact long integer number (a
non-immediate integer, not a bignum), @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} exact? obj
Returns @code{#t} if @var{obj} is an exact number, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} inexact? obj
Returns @code{#t} if @var{obj} is an inexact number, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} = z1 z2 z3 @dots{}
Returns @code{#t} if all arguments are numerically equal, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} != z1 z2 z3 @dots{}
Returns @code{#t} if all arguments after the first are not numerically
equal to the first argument, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} < z1 z2 z3 @dots{}
Returns @code{#t} if all arguments are strictly ordered in increasing
order.
@end deffn

@deffn {Primitive procedure} <= z1 z2 z3 @dots{}
Returns @code{#t} if all arguments are ordered in increasing order.
@end deffn

@deffn {Primitive procedure} > z1 z2 z3 @dots{}
Returns @code{#t} if all arguments are strictly ordered in decreasing
order.
@end deffn

@deffn {Primitive procedure} >= z1 z2 z3 @dots{}
Returns @code{#t} if all arguments are ordered in decreasing order.
@end deffn

@deffn {Primitive procedure} zero? obj
Returns @code{#t} if @var{obj} is equal to zero, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} positive? obj
Returns @code{#t} if @var{obj} is greater than zero, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} negative? obj
Returns @code{#t} if @var{obj} is less than zero, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} odd? obj
Returns @code{#t} if @var{obj} is an odd number, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} even? obj
Returns @code{#t} if @var{obj} is an even number, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} max x1 x2 @dots{}
Returns the maximum of its arguments.
@end deffn

@deffn {Primitive procedure} min x1 x2 @dots{}
Returns the minimum of its arguments.
@end deffn

@deffn {Primitive procedure} + z1 @dots{}
Adds all numbers in the argument list and returns the sum.  If called
without parameters, 0 is returned.
@end deffn

@deffn {Primitive procedure} * z1 @dots{}
Multiplies all argument values and returns the product. Returns 1 if
called without parameters.
@end deffn

@deffn {Primitive procedure} - z1 @dots{}
Takes the first argument and subtracts all remaining argument values one
after the other. At least one parameter is required, if called with
exactly one parameter, the negated value of the parameter is returned.
@end deffn

@deffn {Primitive procedure} / z1 @dots{}
Divides the first argument by all remaining arguments in turn. If called
with one parameter, the reciprocal of the argument is returned. Should
any of the remaining arguments be zero, a division-by-zero error is
signalled.
@end deffn

@deffn {Primitive procedure} abs x
Returns the absolute value of its argument.
@end deffn

@deffn {Primitive procedure} magnitude z
Returns the magnitude for @var{x}.  This is the same as @code{abs},
since Sizzle does not support complex numbers.
@end deffn

@deffn {Primitive procedure} angle z
Returns the angle of @var{x} in polar representation.  This is -PI for
negative numbers and 0 for positive numbers since Sizzle does not
support complex numbers.
@end deffn

@deffn {Primitive procedure} real-part z
Returns the real part of the number @var{z}.  In Sizzle, this returns @var{z}
itself, because complex numbers are not supported.
@end deffn

@deffn {Primitive procedure} imag-part z
Returns the imaginary part of the number @var{z}.  The Sizzle
implementation simply returns 0, because complex numbers are not
supported.
@end deffn

@deffn {Primitive procedure} numerator q
Returns the numerator of its argument @var{q}.  Currently, @var{q}
itself is returned because rational numbers are not supported.
@end deffn

@deffn {Primitive procedure} denominator q
Returns the denominator of its argument @var{q}.  Currently, 1 is
returned because rational numbers are not supported.
@end deffn

@deffn {Primitive procedure} quotient n1 n2
Performs an integer division operation on the two arguments. An
arithmetic overflow error is signalled if the second operand is equal to
zero.
@end deffn

@deffn {Primitive procedure} remainder n1 n2
Returns the rest of an integer division of its arguments. An arithmetic
overflow error is signalled if the second operand is equal to zero.
@end deffn

@deffn {Primitive procedure} modulo n1 n2
Returns the rest of an integer division of its arguments. An arithmetic
overflow error is signalled if the second operand is equal to zero. This
differs from @code{remainder} as far as negative operands ar concerned. 
@end deffn

@deffn {Primitive procedure} floor x
Returns the largest integer not larger than @var{x}.
@end deffn

@deffn {Primitive procedure} ceiling x
Returns the smallest integer not smaller than @var{x}.
@end deffn

@deffn {Primitive procedure} truncate x
Returns the closest integer to @var{x} whose absolute value is not
larger than the absolute value of @var{x}.
@end deffn

@deffn {Primitive procedure} round x
Returns the closest integer to @var{x} rounding it to even when @var{x}
is halfway between two integers.
@end deffn

@deffn {Primitive procedure} exp z
Implements the exponential function.
@end deffn

@deffn {Primitive procedure} log z
Returns the natural logarithm of @var{z}.
@end deffn

@deffn {Primitive procedure} sin z
Returns the sine of @var{z}.
@end deffn

@deffn {Primitive procedure} cos z
Returns the cosine of @var{z}.
@end deffn

@deffn {Primitive procedure} tan z
Returns the tangent of @var{z}.
@end deffn

@deffn {Primitive procedure} asin z
Returns the arcsine of @var{z}.
@end deffn

@deffn {Primitive procedure} acos z
Returns the arccosine of @var{z}.
@end deffn

@deffn {Primitive procedure} atan z
Returns the arctangent of @var{z}.
@end deffn

@deffn {Primitive procedure} atan y x
Returns the arctangent of the two variables @var{y} and @var{x}. It is
similar to computing the arctangent of @var{y} / @var{x}, except that
the signs of both arguments are used to determine the quadrant of the
result.
@end deffn

@deffn {Primitive procedure} sqrt x
Returns the square root of its argument. Since complex numbers are not
supported, @var{x} must be positive.
@end deffn

@deffn {Primitive procedure} expt z1 z2
Returns @var{z1} raised to the power of @var{z2}.
@end deffn

@deffn {Primitive procedure} exact->inexact z
Returns @var{z}, converted to an inexact value.
@end deffn

@deffn {Primitive procedure} inexact->exact z
Returns @var{z}, converted to an exact value. An error signalled if a
conversion is not possible without losing precision.
@end deffn

@deffn {Primitive procedure} number->string z
@deffnx {Primitive procedure} number->string z radix
Converts its argument to a string.  The radix @var{radix} is used if
given.
@end deffn

@deffn {Primitive procedure} string->number string
@deffnx {Primitive procedure} string->number string radix
Converts @var{string} to a number. When given, @var{radix} is used as
the default radix which can be overridden with an explicit radix prefix
in @var{string}. @code{#f} is returned if @var{string} is not properly
formatted.
@end deffn

@deffn {Primitive procedure} lognot n
Returns the bitwise negated value of the argument.
@end deffn

@deffn {Primitive procedure} logand n @dots{}
Performs a bitwise @emph{and} operation on all arguments and returns the
result. Returns a value with all bits set if called without arguments.
@end deffn

@deffn {Primitive procedure} logior n @dots{}
Performs a bitwise @emph{or} operation on all arguments and returns the
result. Returns a value with no bits set if called without arguments.
@end deffn

@deffn {Primitive procedure} logxor n @dots{}
Performs a bitwise @emph{exclusive or} operation on all arguments and
returns the result. Returns a value with no bits set if called without
arguments.
@end deffn

@deffn {Primitive procedure} lsh n1 n2
Shifts the integer @var{n1} left by @var{n2} bits if @var{n2} is not
less than zero, or shifts @var{n2} logically right by @var{-n2} bits if
@var{n2} is less than zero.
@end deffn

@deffn {Primitive procedure} ash n1 n2
Shifts the integer @var{n1} left by @var{n2} bits if @var{n2} is not
less than zero, or shifts @var{n2} arithmetically right by @var{-n2}
bits if @var{n2} is less than zero.
@end deffn

@deffn {Primitive procedure} gcd [n1 [n2]]
Returns the greatest common divisor of its arguments.  Without
arguments, 0 is returned, if only @var{n1} is given, @var{n1} is
returned.
@end deffn

@deffn {Primitive procedure} lcm [n1 [n2]]
Returns the least common multiple of its arguments.  Without arguments,
1 is returned, if only @var{n1} is given, @var{n1} is returned.
@end deffn

@deffn {Primitive procedure} signum x
Return -1 if @var{x} is less than zero, 0 if @var{x} is equal to zero
and 1 if @var{z} is greater than zero.
@end deffn

@node Boolean operations, Pair and list operations, Numerical operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Boolean operations

The boolean operations documented in this section are always available.

@deffn {Primitive procedure} boolean? obj
Returns @code{#t} if @var{obj} is a boolean value, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} not obj
Returns @code{#t} if @var{obj} is false, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} boolean->integer b
Return 0 if @var{b} is @code{#f}, 1 otherwise.
@end deffn

@deffn {Primitive procedure} integer->boolean i
Return @code{#f} if @var{i} is 0, @code{#t} otherwise.
@end deffn



@node Pair and list operations, Hash table operations, Boolean operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Pairs and lists

Sizzle implements all list and pair operations as defined in R5RS, plus
the list operations present in SRFI-1.  All procedures without a special remark
 are available at all times, whereas some procedures need inclusion of
the module @code{(core list-lib)} prior to usage.

@menu
* List constructors::           Creating lists.
* List predicates::             Examining lists.
* List selectors::              Accessing list elements.
* Miscellaneous list procedures::  length, append etc.
* Fold unfold and map::         Fundamental list iterators and constructors
* Filtering and partitioning::  Filtering lists
* List searching::              Searching in lists
* Association lists::           Association lists
* Deletion::                    Deletion of list elements
* Primitive side-effects::      Side-effecting pair manipulation
* Set operations on lists::     Procedures to handle set represented by lists
@end menu



@node List constructors, List predicates, Pair and list operations, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection List constructors

@deffn {Primitive procedure} cons obj1 obj2
Return a cons cell with a car of @var{obj1} and a cdr of @var{obj2}.
@end deffn

@deffn {Primitive procedure} list obj @dots{}
Returns a list whose elements are all arguments of the call to
@code{list}. With no arguments, the empty list @code{()} is returned.
@end deffn

@deffn {Primitive procedure} xcons obj1 obj2
Equivalent to @code{(cons obj2 obj1)}, and is of utility only as a value
to be conveniently passed to higher--order procedures. (@code{xcons}
stands for @i{exchanged cons}.)

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} cons* elt1 elt2 @dots{}
Like @code{list}, but the last argument provides the tail of the
constructed list.
@example
(cons* 1 2 3 4) => (1 2 3 . 4)
@end example

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} make-list n [fill]
Return an @var{n}-element list, whose elements are all the value
@var{fill}. If the @var{fill} argument is not given, the elements of the
list are unspecified.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} list-tabulate n init-proc
Returns an @var{n}-element list. Element @var{i} ofthe list, where 0 <=
@var{i} < @var{n}, is produced by calling @code{(init-proc i)}.  The
dynamic order in which @code{init-proc} is applied to the indices is not
specified.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} list-copy flist
Copies the spine of the argument list.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} circular-list elt1 elt2 @dots{}
Constructs a circular list of the elements.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} iota count [start step]
Returns a list containing the elements
@example
(start start+step @dots{} start+(count-1)*step)
@end example
The @var{start} and @var{step} parameters default to 0 and 1, respectively. This procedure takes its name from the APL primitive.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn



@node List predicates, List selectors, List constructors, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection List predicates

@deffn {Primitive procedure} list? obj
Return @code{#t} if @var{obj} is a list, @code{#f} otherwise. Only
finite lists pass this test, infinite lists return @code{#f} for this
predicate.
@end deffn

@deffn {Primitive procedure} proper-list? x
Return @code{#t} if @var{x} is a proper list -- a finite,
nil-terminated list.  Return @var{#f} for any other object.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} circular-list? x
Return @code{#t} if @var{x} is a circular list.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} dotted-list? x
Return @code{#t} if @var{x} is a finite, non-nil-terminated list.  This
includes non-pair, non-() values (e.g. symbols, numbers), which are
considered to be dotted lists of length 0.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} pair? obj
Returns @code{#t} if @var{obj} is a cons cell, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} null? obj
Returns @code{#t} if @var{obj} is the empty list, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} null-list? list
@var{list} is a proper or circular list.  Returns @code{#t} if the
argument is the empty list (), and @code{#f} otherwise.  It is an error
to pass this procedure a value which is not a proper or circular list.
This procedure is recommended as the termination condition for
list--processing procedures that are not defined on dotted lists.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} not-pair? x
Return @code{#t} if @var{x} is not a pair.  Provided as a procedure as
it can be useful as the termination condition for list-processing
procedures that wish to handle all lists, both proper and dotted.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} list= elt= list1 @dots{}
Determine list equality, given an element-equality procedure.  Proper
list @var{A} equals proper list @var{B} if they are of the same length
and their corresponding elements are equal, as determined by @var{elt=}.

It is an error to apply @code{list=} to anything except proper lists.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn



@node List selectors, Miscellaneous list procedures, List predicates, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection List selectors

@deffn {Primitive procedure} car pair
@var{pair} must be a cons cell. Return the car of the cons cell @var{pair}.
@end deffn

@deffn {Primitive procedure} cdr pair
@var{pair} must be a cons cell. Return the cdr of the cons cell @var{pair}.
@end deffn

@deffn {Primitive procedure} caar pair
@deffnx {Primitive procedure} cadr pair
@deffnx {Primitive procedure} @dots{}
@deffnx {Primitive procedure} cdddar pair
@deffnx {Primitive procedure} cddddr pair
These functions are compositions of @code{car} and @code{cdr}, where for example @code{caddr} could be defined by
@example
(define caddr (lambda (x) (car (cdr (cdr x)))))
@end example
There are twenty-eight of these functions defined.
@end deffn

@deffn {Primitive procedure} list-ref list k
Returns the @var{k}th element of @var{list}. An error is signalled if
@var{list} has fewer than @var{k} elements.
@end deffn

@deffn {Primitive procedure} list-tail list k
Returns the sublist of @var{list} obtained by omitting the first @var{k}
elements.  An error is signalled if @var{list} has fewer than @var{k}
elements.
@end deffn

@deffn {Primitive procedure} first pair
@deffnx {Primitive procedure} second pair
@deffnx {Primitive procedure} third pair
@deffnx {Primitive procedure} fourth pair
@deffnx {Primitive procedure} fifth pair
@deffnx {Primitive procedure} sixth pair
@deffnx {Primitive procedure} seventh pair
@deffnx {Primitive procedure} eighth pair
@deffnx {Primitive procedure} ninth pair
@deffnx {Primitive procedure} tenth pair
Synonyms for @code{car}, @code{cadr}, @code{caddr}, @dots{}

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} car+cdr pair
The fundamental pair deconstructor.  Return two values, the first being
the @i{car}, the second being the @i{cdr} of the pair.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} take list k
Return a list containing the first @var{k} elements of
@var{list}. Return @var{list} if @var{k} is larger then the length of
@var{list}.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} drop list k
Return a list containing the elements of @var{list}, but without the
first @var{k} elements. Return @var{list} if @var{k} is less or equal to
zero, returns the empty list if @var{k} is larger than the length of
@var{list}.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} take-right flist i
@deffnx {Primitive procedure} drop-right flist i
@code{take-right} returns the last @var{i} elements of @var{flist}.

@code{drop-right} returns all but the last @var{i} elements of
@var{flist}.  

The returned list may share a common tail with the argument list.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} take! x i
@deffnx {Primitive procedure} drop-right! x i
@code{take!} and @code{drop-right!} are destructive variants of
@code{take} and @code{drop-right}.  If @var{x} is circular, @code{take!}
may return a shorter-than-expected list.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} split-at x i
@deffnx {Primitive procedure} split-at! x i
@code{split-at} splits the list @var{x} at index @var{i}, returning two
values: a list of the first @var{i} elements and the remaining tail.

@code{split-at!} is the destructive variant of @code{split-at}.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} last pair
@deffnx {Primitive procedure} last-pair pair
@code{last} returns the last element of the non-empty, finite list
@var{pair}.  @code{last-pair} returns the last pair of the non-empty,
finite list @var{pair}.
@end deffn



@node Miscellaneous list procedures, Fold unfold and map, List selectors, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection Miscellaneous list procedures

@deffn {Primitive procedure} length list
@deffnx {Primitive procedure} length+ clist
Returns the length of @var{list}.  It is an error to pass anything but a
proper, nil-terminated list to @code{length}.

@code{length+}, on the other hand, will return @code{#f} when applied to
a circular list.

@code{length+} must be imported by using the module @code{(core
list-lib)}, whereas @code{length} is always available.
@end deffn

@deffn {Primitive procedure} append list @dots{}
Returns a list made out of the elements of all argument lists.  The last
argument may be an improper list, an improper list will be returned in
this case.
@end deffn

@deffn {Primitive procedure} append! list @dots{}
Destructive version of @code{append}.  The result of the operation is
the same as for @code{append}, but as a side effect, the parameter lists
are modified when performing the append operation.
@end deffn

@deffn {Primitive procedure} concatenate list-of-lists
@deffnx {Primitive procedure} concatenate! list-of-lists
These functions append the elements of their arguments together.
@code{concatenate!} may alter the cons cells of the passed lists.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} reverse list
Returns a newly allocated list with all elements of @var{list} in
reversed order.
@end deffn

@deffn {Primitive procedure} reverse! list
Destructive version of @code{reverse}.  The result of the operation is
the same as for @code{reverse}, but as a side effect, the parameter list
is modified when performing the reverse operation.
@end deffn

@deffn {Procedure procedure} append-reverse rev-head tail
@deffnx {Procedure procedure} append-reverse! rev-head tail
@code{append-reverse} returns @code{(append (reverse rev-head) tail)}.
It is provided because it is a common operation.

@code{append-reverse!} is just the destructive variant.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} zip clist1 clist2 @dots{}
If zip is passed @var{n} lists, it returns a list as long as the
shortest of these lists, each element of which is an @var{n}-element
lists comprised of the corresponding elements from the parameters lists.
At least one of the argument lists must be finite.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} unzip1 list
@deffnx {Library procedure} unzip2 list
@deffnx {Library procedure} unzip3 list
@deffnx {Library procedure} unzip4 list
@deffnx {Library procedure} unzip5 list
@code{unzip1} takes a list of lists, where every list must contain at
least one element, and returns a list containing the initial element of
each such list.  That is, it returns @code{(map car lists)}.

@code{unzip2} takes a list of lists, where every list must contain at
least two elements, and returns two values: a list of the first elements and a list of the second elements, @code{unzip3} does the same for the first three elements of the lists, and so forth.
@example
(unzip2 '((one 1) (two 2) (three 3))) =>
  (1 2 3)
  (one two three)
@end example

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} count pred clist1 clist2 @dots{}
@var{pred} is a procedure taking as many arguments as there are lists
and returning a single value.  It is applied element-wise to the
elements of the @var{lists}, and a count is tallied of the number of
elements that return a true value. This count is returned.  @code{count}
is iterative in that it is guarateed to apply @var{pred} to the
@var{list} elements in a left-to-right order.  The counting stops when
the shortest list expires.  At least one of the argument lists must be
finite.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@c @deffn {Primitive procedure} remq obj list
@c @deffnx {Primitive procedure} remv obj list
@c @deffnx {Primitive procedure} remove obj list
@c These procedures return lists which are identical to the parameter
@c @var{list}, but from which all occurences of @var{obj} are
@c removed. @code{remq} uses @code{eq?} for comparing the list elements
@c with @var{obj}, @code{remv} uses @code{eqv?} and @code{remove} uses
@c @code{equal?}.
@c @end deffn



@node Fold unfold and map, Filtering and partitioning, Miscellaneous list procedures, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection Fold, unfold and map

@deffn {Primitive procedure} fold kons knil clist1 clist2 @dots{}
The fundamental list iterator.

First, consider the single list-parameter case if clist1=(e1 e2 @dots{} en) then this procedure returns
@example
(kons en @dots{} (kons e1 (kons e1 knil)))
@end example
That is, it obeys the (tail) recursion
@example
(fold kons knil lis) = (fold kons (kons (car lis) knil) (cdr lis))
(fold kons knil '()) = knil
@end example
If @var{n} argument lists are provided, then the @var{kons} procedure
must take @var{n}+1 parameters: one element from each list, and the
``seed'' or fold state, which is initially @var{knil}.  The fold
operation terminates when the shortest list runs out of values.  At
least one of the arhument lists must be finite.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} pair-fold kons knil clist1 clist2 @dots{}
Analogous to @code{fold}, but @var{kons} is applied to successive
sublists of the lists, rather than successive elements -- that is,
@var{kons} is applied to the pairs making up the lists.

For finite lists, the @var{kons} function may reliably apply
@code{set-cdr!} to the pairs it is given without altering the sequence
of execution.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@c
@c FIXME: Document fold-right, pair-fold-right
@c

@deffn {Library procedure} reduce f ridentity list
@code{reduce} is a variant of @code{fold}.

@var{ridentity} should be a ``right identity'' of the procedure @var{f}
-- that is, for any value @var{x} acceptable to @var{f},
@example
(f x ridentity) = x
@end example
Note that @var{ridentity} is used @i{only} in the empty-list case. You
typically use @code{reduce} when applying @var{f} is expensive and you'd
like to avoid the extra application incurred when fol applies @var{f} to
the head of the @var{list} and the identity value, redundantly producing
the same value passed to @var{f}.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} reduce-right f ridentity list
@code{reduce-right} is the fold-right variant of @code{reduce}.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} unfold p f g seed [tail-gen]
@code{unfold} is defined as follows:
@example
(unfold p f g seed) =
  (if (p seed) (tail-gen seed)
               (cons (f seed)
                     (unfold p f g (g seed)))))
@end example
@table @var
@item p
Determines when to stop unfolding.
@item f
Maps each seed value to the corresponding list element.
@item g
Maps each seed value to the next seed value.
@item seed
The ``state'' value for the unfold.
@item tail-gen
Creates the tail of the list; defaults to @code{(lambda (x) '())}.
@end table
In other words, we use @var{g} to generate a sequence of seed values
seed, g(seed), g^2(seed), g^3(seed), @dots{}

These seed values are mapped to list elements by @var{f}, producing the
elements of the result list in a left-to-right order. @var{p} says when
to stop.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} unfold-right p f g seed [tail]
@code{unfold-right} constructs a list with the following loop:
@example
(let lp ((seed seed) (lis tail))
   (if (p seed) lis
                (lp (g seed) (cons (f seed) lis))))
@end example
@table @var
@item p
Determines when to stop unfolding.
@item f
Maps each seed value to the corresponding list element.
@item g
Maps each seed value to the next seed value.
@item seed
The ``state'' value for the unfold.
@item tail
List terminator, defaults to @code{'()}.
@end table

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} map proc list1 list2 @dots{}
The @var{lists} must be lists and @var{proc} must be a procedure taking
as many arguments as there are @var{lists} and returning a single
value. All @var{lists} must be of the same length. @code{map} applies
@var{proc} element-wise to the elements of the @var{lists} and returns a
list of the results, in order. The dynamic order in which @var{proc} is
applied to the elements of the @var{lists} is unspecified.
@end deffn

@deffn {Primitive procedure} for-each proc list1 list2 @dots{}
@var{proc} is applied to the elements of the @var{lists} as with
@code{map}, but in order. @code{for-each} is for its side effects of
@var{proc}, therefore the return value is unspecified.
@end deffn

@deffn {Library procedure} append-map f clist1 clist2 @dots{}
@deffnx {Library procedure} append-map! f clist1 clist2 @dots{}
Map @var{f} over the elements of the lists, just as the @code{map}
function.  However, the results of the applications are appended
together to make the final result.  @code{append-map} uses @code{append}
to append the results together; @code{append-map!} uses
@code{append!}. The dynamic order in which the various applications of
@var{f} are made is not specified.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} map! f list clist1 @dots{}
Destructive variant of @code{map}.  @code{map!} may be alter the cons
cells of list1 to construct the result list.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} map-in-order f clist1 clist2 @dots{}
A variant of the @code{map} procedure that guarantees to apply @var{f}
across the elements of the list arguments in a left-to-right order.
This is useful for mapping procedures that both have side effects and
return useful values.  At least one of the argument lists must be
finite.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} pair-for-each f clist1 clist2 @dots{}
Like @code{for-each}, but @var{f} is applied to successive sublists of
the argument lists.  That is, @var{f} is applied to the cons cells of
the lists, rather than the lists' elements.  These applications occur in
left-to-right order.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} filter-map f clist1 clist2 @dots{}
Like @code{map}, but only true values are saved.  The dynamic order in
which the various applications of @var{f} are made is not specified.  At
least one of the argument lists must be finite.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn



@node Filtering and partitioning, List searching, Fold unfold and map, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection Filtering and partitioning

@deffn {Library procedure} filter pred list
@deffnx {Library procedure} filter! pred list
Return all the elements of @var{list} that satisfy predicate @var{pred}.
The list is not disordered.  The returned list may share a common tail
with the argument list.  The dynamic order in which the various
applications of @var{pred} are made is not specified.

@code{filter!} is the destructive variant of @code{filter}.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} partition pred list
@deffnx {Library procedure} partition! pred list
Partitions the elements of @var{list} with predicate @var{pred}, and
returns two values: the list of in-elements and the list of
out-elements. The list is not disordered. The dynamic order in which the
various applications of @var{pred} are made is not specified. One of the
returned lists may share a common tail with the argument list.

@code{partition!} is the destructive variant of @code{partition}.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} remove pred list
@deffnx {Library procedure} remove! pred list
Returns @var{list} without the elements that satidfy the predicate
@var{pred}. The list is not disordered. The dynamic order in which the
various applications of @var{pred} are made is not specified. 

@code{remove!} is the destructive variant of @code{remove}.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn



@node List searching, Association lists, Filtering and partitioning, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection List searching

@deffn {Library procedure} find pred clist
Return the first element in @var{clist} that satisfies predicate
@var{pred}, @code{#f} if no element does.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} find-tail pred clist
Return the first pair of @var{clist} whose car satisfies predicate
@var{pred}, @code{#f} if no element does.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} take-while pred clist
@deffnx {Library procedure} take-while! pred clist
Return the longest initial prefix of @var{clist} whose elements all
satisfy the predicate @var{pred}.

@code{take-while!} is the destructive variant of @code{take-while}.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} drop-while pred clist
Drops the longest initial prefix of @var{clist} whose elements all
satisfy the predicate @var{pred}, and returns the rest of the list.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} span pred clist
@deffnx {Library procedure} span! pred clist
@deffnx {Library procedure} break pred clist
@deffnx {Library procedure} break! pred clist
@code{span} bsplits the list into the longest initial prefix whose
elements all satisfy @var{pred}, and the remaining tail.  @code{break}
inverts the sense of the predicate: the tail commences with the first
element of the input list that satisfies the predicate.

@code{span!} and @code{break!} are the destructive variants.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} any pred clist1 clist2 @dots{}
Applies the predicated accross the lists, returning true if the
predicate returns true on any application.  If there are @var{n}
arguments clist1 @dots{} clistn, then @var{pred} must be a procedure
taking @var{n} arguments and returning a boolean result.

The iteration stops when a true value is produced or one of the lists
runs out of values, in the latter case, @code{any} returns @code{#f}.

Note the difference between @code{find} and @code{any} -- @code{find}
returns the element that satisfied the predicate, @code{any} returns the
true value that the predicate produced.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} every pred clist1 clist2 @dots{}
Applies the predicate across the lists, returning true if the predicate
returns true on every application.  If there are @var{n}
arguments clist1 @dots{} clistn, then @var{pred} must be a procedure
taking @var{n} arguments and returning a boolean result.

Like @code{any}, @code{every}'s name does not end with a question mark
-- this is to indicate that it does return a general value, not only
@code{#t} or @code{#f}.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} list-index pred clist1 clist2 @dots{}
Return the index of the leftmost element that satisfies @var{pred}.  If
there are @var{n} arguments clist1 @dots{} clistn, then @var{pred} must
be a procedure taking @var{n} arguments and returning a boolean result.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} memq obj list
@deffnx {Primitive procedure} memv obj list
@deffnx {Primitive procedure} member obj list [=]
These functions return the first sublist of @var{list} whose car is
@var{obj}. @code{memq} uses @code{eq?} for comparing the values,
@code{memv} uses @code{eqv?} and @code{member} uses @code{equal?}.  If
@var{obj} does not occur in @var{list}, @code{#f} is returned.

@code{member} is extended from R5RS to allow the client to pass an
optional equality procedure @var{=} used to compare keys.
@end deffn



@node Association lists, Deletion, List searching, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection Association lists

@deffn {Primitive procedure} assq obj alist
@deffnx {Primitive procedure} assv obj alist
@deffnx {Primitive procedure} assoc obj alist [=]
@var{alist} (for association list) must be a list of pairs. These
procedures return the first pair in @var{alist} whose car field is
@var{obj}. If no pair in @var{alist} has @var{obj} as its car, then
@code{#f} is returned. @code{assq} uses @code{eq?} for comparing the
values, @code{assv} uses @code{eqv?} and @code{assoc} uses
@code{equal?}.

@code{assoc} is extended from R5RS to allow the client to pass in an
optional equality procedure @var{=} to compare keys.
@end deffn

@deffn {Primitive procedure} alist-cons key datum alist
Cons a new alist entry mapping from @var{key} to @var{datum} onto
@var{alist}.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} alist-copy alist
Make a fresh copy of @var{alist}.  This means copying each pair that
forms an association as well as the spine of the list.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} alist-delete key alist [=]
@deffnx {Primitive procedure} alist-delete! key alist [=]
@code{alist-delete} deletes all associations from @var{alist} with the
given @var{key}, using key-comparison procedure @var{=}, which defaults
to @code{equal?}.  The dynamic order in which the various applications
of @var{=} are made is not specified.

@code{alist-delete!} is the destructive variant of @code{alist-delete}.
It may modify its argument list in order to produce its result.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn



@node Deletion, Primitive side-effects, Association lists, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection Deletion

@deffn {Primitive procedure} delete x list [=]
@deffnx {Primitive procedure} delete! x list [=]
@code{delete} uses the comparison procedure @var{=}, which defaults to
@code{equal?}, to find all elements of @var{list} that are equal to
@var{x}, and deletes them from @var{list}.  The dymanic order in which
the various applications of @var{=} are made is not specified.
The list is not disordered -- elements that appear in the result list occur in the same order as they occur in the argument list.

@code{delete!} is the destructive variant of @code{delete}. It is
allowed to alter the cons cells in its argument list to construct the
result.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Primitive procedure} delete-duplicates list [=]
@deffnx {Primitive procedure} delete-duplicates! list [=]
@code{delete-duplicates} removes duplicate elements from the list
argument.  If there are multiple equal elements in the argument list,
the result list only contains the first or leftmost of these elements in
the result.  The order of the surviving elements is the same as in the
original list.

@code{delete-duplicates!} is the destructive variant of
@code{delete-duplicates}. It is allowed to alter the argument list to
produce the result.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn



@node Primitive side-effects, Set operations on lists, Deletion, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection Primitive side-effects

@deffn {Primitive procedure} set-car! pair obj
@var{pair} must be a cons cell. Sets the car of @var{pair} to
@var{obj}.  The return value is not specified.
@end deffn

@deffn {Primitive procedure} set-cdr! pair obj
@var{pair} must be a cons cell. Sets the cdr of @var{pair} to
@var{obj}.  The return value is not specified.
@end deffn



@node Set operations on lists,  , Primitive side-effects, Pair and list operations
@comment  node-name,  next,  previous,  up
@subsection Set operations on lists

@deffn {Library procedure} lset<= = list1 @dots{}
Returns true iff every @var{list_i} is a subset of @var{list_i+1}, using
@var{=} for the element-equality procedure.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset= = list1 @dots{}
Returns true iff every @var{list_i} is a set-equal of @var{list_i+1}, using
@var{=} for the element-equality procedure.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset-adjoin = list elt1 @dots{}
Adds the @var{elts} not already in the list parameter to the result
list.  The result shares a common tail with the list parameter.  The
@var{=} parameter is an equality procedure used to determine of an
@var{elt_i} is already a member of @var{list}.

The list parameter is always a suffix of the result -- even if the list
parameter contains repeated elements, these are not reduced.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset-union = list1 @dots{}
Returns the union of the lists, using @var{=} for the element-equality
procedure.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset-intersection = list1 @dots{}
Returns the intersection of the lists, using @var{=} for the
element-equality procedure.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset-difference = list1 list2 @dots{}
Returns the intersection of the lists, using @var{=} for the
element-equality procedure.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset-xor = list1 @dots{}
Returns the exclusive-or of the sets, using @var{=} for the
element-equality procedure.  The result is a list of all elements which
appear in an odd number of the parameter @var{lists}.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset-diff+intersection = list1 list2 @dots{}
Returns two values -- the difference and the intersection of the lists.

This procedure must be imported by using the module @code{(core
list-lib)}.
@end deffn

@deffn {Library procedure} lset-union! = list1 @dots{}
@deffnx {Library procedure} lset-intersection! = list1 list2 @dots{}
@deffnx {Library procedure} lset-difference! = list1 list2 @dots{}
@deffnx {Library procedure} lset-xor! = list1 @dots{}
@deffnx {Library procedure} lset-diff+intersection! = list1 list2 @dots{}
These are destructive variants of the pure functions.

These procedures must be imported by using the module @code{(core
list-lib)}.
@end deffn



@node Hash table operations, Symbol operations, Pair and list operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Hash tables

These procedures are always available.

@deffn {Primitive procedure} hashq obj n
@deffnx {Primitive procedure} hashv obj n
@deffnx {Primitive procedure} hash obj n
Determine a hash value for @var{obj} that is suitable for lookups in a
hash table of size @var{n}, where @code{eq?}, @code{eqv?} or
@code{equal?} (for @code{hashq}, @code{hashv}, @code{hash},
respectively) is used as the equality predicate.  The function returns
an integer in the range 0 to @var{n} - 1.  Note that these functions may
use internal addresses.  Thus two calls to the same function where the
keys are equal according to the sameness predicate used are not
guaranteed to deliver the same value if the key object @var{obj} gets
garbage collected in between.
@end deffn

@deffn {Primitive procedure} make-hash [capacity] pair @dots{}
Creates a hash table, initialized with values taken from the
@var{pairs}.  The car of each pair is taken as a hash key and the
corresponding cdr as the value.  If the first argument is not a pair, it 
must be an integer and will give the number of buckets to use for the
hash table.
@end deffn

@deffn {Primitive procedure} hashq-get-handle tab key
@deffnx {Primitive procedure} hashv-get-handle tab key
@deffnx {Primitive procedure} hash-get-handle tab key
These procedures are similar to their @code{-ref} cousins, but return
@dfn{handles} from the hash table rather than the value associated with
@var{key}.  By convention, a handle in a hash table is the pair which
associates a key with a value.  Where @code{hashq-ref tab key} returns
only a @code{value}, @code{hashq-get-handle table key} returns the pair
@code{(key . value)}.
@end deffn

@deffn {Primitive procedure} hashq-ref tab key [default]
@deffnx {Primitive procedure} hashv-ref tab key [default]
@deffnx {Primitive procedure} hash-ref tab key [default]
Look up @var{key} in the hash table @var{tab}, and return the value (if
any) associated with it.  If @var{key} is not found, return
@var{default} (or @code{#f} if no @var{default} argument is supplied).
@code{hashq-ref} uses @code{eq?} for equality testing, the other
functions use @code{eqv?} and @code{equal?}.
@end deffn

@deffn {Primitive procedure} hashq-create-handle! tab key value
@deffnx {Primitive procedure} hashv-create-handle! tab key value
@deffnx {Primitive procedure} hash-create-handle! tab key value
These functions look up @var{key} in @var{tab} and return its handle.
If @var{key} is not already present, a new handle is created which
associates @var{key} with @var{init}.
@end deffn

@deffn {Primitive procedure} hashq-set! tab key value
@deffnx {Primitive procedure} hashv-set! tab key value
@deffnx {Primitive procedure} hash-set! tab key value
Find the entry in @var{tab} associated with @var{key}, and store
@var{value} there. @code{hashq-set!} uses @code{eq?} for equality
testing, the other functions use @code{eqv?} and @code{equal?}.
All these procedures return the @var{value}.
@end deffn

@deffn {Primitive procedure} hashq-remove! tab key
@deffnx {Primitive procedure} hashv-remove! tab key
@deffnx {Primitive procedure} hash-remove! tab key
Remove @var{key} (and any value associated with it) from @var{tab}.
@code{hashq-remove!} uses @code{eq?} for equality testing, the other
functions use @code{eqv?} and @code{equal?}.  The procedures return the
handle (that is, the key--value pair) that was removed or @code{#f} if
the key was not found.
@end deffn

@deffn {Primitive procedure} hash-fold proc seed table
Iterate over the elements of the hash table @var{table}.  @var{proc} is
applied to every hash table element with the arguments @code{(proc key
value init)}, where on the first call @var{init} is the given
@var{seed}, and on subsequent calls @var{init} is the result of the
previous call.
@end deffn


@node Symbol operations, Character operations, Hash table operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Symbol operations

The procedures in this section do not need any modules to be loaded.

@deffn {Primitive procedure} symbol? obj
Returns @code{#t} if @var{obj} is a symbol, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} symbol->string symbol
Converts @var{symbol} to a string.
@end deffn

@deffn {Primitive procedure} string->symbol string
Converts @var{string} to a symbol.
@end deffn

@deffn {Primitive procedure} gensym [prefix]
Generate a new symbol, constructed from @var{prefix} and the value of a
counter which is incremented after each call.  @var{prefix} defaults to
@code{)gen}, if not given.
@end deffn


@node Character operations, String operations, Symbol operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Character operations

All of these procedures are available without loading additional
modules.

@deffn {Primitive procedure} char? obj
Returns @code{#t} if @var{obj} is a character value, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} char= char1 char2
Returns @code{#t} if @var{char1} is the same character as @var{char2},
@code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} char< char1 char2
Returns @code{#t} if @var{char1} has a smaller character value than
@var{char2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} char<= char1 char2
Returns @code{#t} if @var{char1} has a smaller or equal character value
than @var{char2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} char> char1 char2
Returns @code{#t} if @var{char1} has a greater character value than
@var{char2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} char>= char1 char2
Returns @code{#t} if @var{char1} has a greater or equal character value
than @var{char2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} char-ci= char1 char2
Returns @code{#t} if @var{char1} is the same character as @var{char2},
@code{#f} otherwise. This function ignores case when comparing.
@end deffn

@deffn {Primitive procedure} char-ci< char1 char2
Returns @code{#t} if @var{char1} has a smaller character value than
@var{char2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} char-ci<= char1 char2
Returns @code{#t} if @var{char1} has a smaller or equal character value
than @var{char2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} char-ci> char1 char2
Returns @code{#t} if @var{char1} has a greater character value than
@var{char2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} char-ci>= char1 char2
Returns @code{#t} if @var{char1} has a greater or equal character value
than @var{char2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} char-alphabetic? obj
Returns @code{#t} if @var{obj} is an alphabetic character.
@end deffn

@deffn {Primitive procedure} char-numeric? obj
Returns @code{#t} if @var{obj} is a numeric character.
@end deffn

@deffn {Primitive procedure} char-whitespace? obj
Returns @code{#t} if @var{obj} is whitespace character. The characters
space, tab, line feed, form feed and carriage return are considered to
be whitespace.
@end deffn

@deffn {Primitive procedure} char-upper-case? obj
Returns @code{#t} if @var{obj} is an upper case character.
@end deffn

@deffn {Primitive procedure} char-lower-case? obj
Returns @code{#t} if @var{obj} is a lower case character.
@end deffn

@deffn {Primitive procedure} char->integer char
Convert the character @var{char} to its ASCII value.
@end deffn

@deffn {Primitive procedure} integer->char n
Returns a character with ASCII value @var{i}.
@end deffn

@deffn {Primitive procedure} char-upcase char
Returns the upper case version of character @var{char} if @var{char} is
a lower case character and @var{char} otherwise.
@end deffn

@deffn {Primitive procedure} char-downcase char
Returns the lower case version of character @var{char} if @var{char} is
a upper case character and @var{char} otherwise.
@end deffn



@node String operations, Vector operations, Character operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section String operations

For convenient string handling, a lot of string primitives have been
included into the Sizzle core.  Unless otherwise noted, these procedures
do not need the inclusion of additional modules.

@menu
* String Predicates::           Testing strings
* String Constructors::         Creating strings
* String Accessors::            Accessing string components
* String Comparison::           Comparing strings
* String Searching::            Searching in strings
* String Decomposition::        Decompose strings into parts
* String Case Conversion::      Converting the case of strings
* String Trimming::             Trim strings
* String Padding::              Pad strings with characters
* String Pathname Operations::  Handling of pathnames
@end menu

@node String Predicates, String Constructors, String operations, String operations
@comment  node-name,  next,  previous,  up
@subsection String Predicates

@deffn {Primitive procedure} string? obj
Return @code{#t} if @var{obj} is a string, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} string-null? obj
Return @code{#t} if @var{obj} is a the empty string @code{""},
@code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} string-every pred s [start end]
Returns a true value, if the applications of @var{pred} to all of the
characters of @var{s} yield true values.  @var{start} and @var{end} may
be given to restrict operation to the characters of @var{s} between these
indices.
@end deffn

@deffn {Primitive procedure} string-any pred s [start end]
Returns a true value, if the application of @var{pred} to any of the
characters of @var{s} yields a true value.  @var{start} and @var{end}
may be given to restrict operation to the characters of @var{s} between
these indices.
@end deffn


@node String Constructors, String Accessors, String Predicates, String operations
@comment  node-name,  next,  previous,  up
@subsection String Constructors

@deffn {Primitive procedure} make-string k
@deffnx {Primitive procedure} make-string k char
Return a newly allocated string of length @var{k}. @var{char} is used to
initialize the string, if omitted, the contents of the string is
unspecified.
@end deffn

@deffn {Primitive procedure} string char @dots{}
Return a newly allocated string composed of its arguments, which all
must be characters.
@end deffn

@deffn {Primitive procedure} string-append string @dots{}
Return a string made out of the concatenation of all string arguments.
An empty string is returned if called without arguments.
@end deffn

@deffn {Primitive procedure} string->list string [start end]
Convert the string @var{string} to a list of all characters of
@var{string}.  @var{start} and @var{end} delimit the region of operation
and default to 0 and the length of @var{string}.
@end deffn

@deffn {Primitive procedure} list->string lst
Convert the list @var{list}, which must be made up from character
values, to a string.
@end deffn

@deffn {Primitive procedure} reverse-list->string lst
An efficient implementation of @code{(compose string->list reverse)}:
@code{(reverse-list->string '(#\a #\B #\c))} => @code{"cBa"}
@end deffn

@deffn {Primitive procedure} string-copy string [start end]
Returns a newly allocated string with the same contents as @var{string}.
@var{start} and @var{end} delimit the string to be copied, they default to
0 and the length of @var{string}.
@end deffn

@deffn {Primitive procedure} string-tabulate proc len
Create a string o length @var{len}, where each character is initialized
from the value returned by applying @var{proc} to the character index.
@end deffn

@deffn {Primitive procedure} string-join string-list delimiter grammar
@var{string-list} must be a list of strings, @var{delimiter} must be a
string and @var{grammar} must be any of the symbols infix, strict-infix,
prefix or suffix.  The strings from @var{string-list} are joined with
@var{delimiter} inbetween according to @var{grammar}.

This procedure will throw an exception if @var{string-list} is empty and
@var{grammar} is @code{string-infix}.
@end deffn

@deffn {Primitive procedure} string-reverse s [start end]
@deffnx {Primitive procedure} string-reverse! s [start end]
Reverse the string argument @var{s}.  @var{start} and @var{end} are
optional start and end indices and default to 0 and the length of
@var{s}, respectively.  @code{string-reverse} returns a reversed version
of @var{s}, whereas @code{string-reverse!} reverses @var{s} in place and
returns an unspecified value.
@end deffn

@node String Accessors, String Comparison, String Constructors, String operations
@comment  node-name,  next,  previous,  up
@subsection String Accessors

@deffn {Primitive procedure} string-length string
Return the number of characters in @var{string}.
@end deffn

@deffn {Primitive procedure} string-ref string k
Return the @var{k}th character of @var{string}. The index is
zero-based. @var{k} must be a valid index into @var{string}, or an error
will be signalled.
@end deffn

@deffn {Primitive procedure} string-set! string k char
Store @var{char} in element @var{k} of @var{string}. An error will be
signalled if @var{k} is not a valid index into @var{string}. The return
value of this function is unspecified.
@end deffn

@deffn {Primitive procedure} substring string start end
Return a string formed from the characters of @var{string} starting at
@var{start} (inclusive) and ending with @var{end} (exclusive).  An error
is signalled if the following equation is not satisfied: 0 <=
@var{start} <= @var{end} <= @code{(string-length} @var{string}@code{)}
@end deffn

@deffn {Primitive procedure} string-fill! string char [start end]
Stores the character @var{char} in all elements of @var{string}. The
return value is not specified.  @var{start} and @var{end} delimit the
region which is filled and default to 0 and the length of @var{string}.
@end deffn


@node String Comparison, String Searching, String Accessors, String operations
@comment  node-name,  next,  previous,  up
@subsection String Comparison

@deffn {Primitive procedure} string= string1 string2
Return @code{#t} if @var{string1} is the same string as @var{string2},
@code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} string<? string1 string2
Returns @code{#t} if @var{string1} is lexicographically less than
@var{string2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} string<=? string1 string2
Returns @code{#t} if @var{string1} is lexicographically less or equal to
@var{string2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} string>? string1 string2
Returns @code{#t} if @var{string1} is lexicographically greater than
@var{string2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} string>=? string1 string2
Returns @code{#t} if @var{string1} is lexicographically greater or equal
to @var{string2}, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} string-ci=? string1 string2
Returns @code{#t} if @var{string1} is the same string as @var{string2},
@code{#f} otherwise. This function ignores case when comparing.
@end deffn

@deffn {Primitive procedure} string-ci<? string1 string2
Returns @code{#t} if @var{string1} is lexicographically less than
@var{string2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} string-ci<=? string1 string2
Returns @code{#t} if @var{string1} is lexicographically less or equal to
@var{string2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} string-ci>? string1 string2
Returns @code{#t} if @var{string1} is lexicographically greater than
@var{string2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} string-ci>=? string1 string2
Returns @code{#t} if @var{string1} is lexicographically greater or equal
to @var{string2}, @code{#f} otherwise. This function ignores case when
comparing.
@end deffn

@deffn {Primitive procedure} string-prefix-length s1 s2 [start1 end1 start2 end2]
Return the length of the longest common prefix of the two strings.
@end deffn

@deffn {Primitive procedure} string-prefix-length-ci s1 s2 [start1 end1 start2 end2]
Return the length of the longest common prefix of the two strings.  When
comparing characters, case is ignored.
@end deffn

@deffn {Primitive procedure} string-suffix-length s1 s2 [start1 end1 start2 end2]
Return the length of the longest common suffix of the two strings.
@end deffn

@deffn {Primitive procedure} string-suffix-length-ci s1 s2 [start1 end1 start2 end2]
Return the length of the longest common suffix of the two strings.
Case is ignored when comparing characters.
@end deffn

@deffn {Primitive procedure} string-prefix? s1 s2 [start1 end1 start2 end2]
Return @code{#t} if @var{s1} is a prefix of @var{s2}.
@end deffn

@deffn {Primitive procedure} string-prefix-ci? s1 s2 [start1 end1 start2 end2]
Return @code{#t} if @var{s1} is a prefix of @var{s2}.  Case is ignored
when comparing characters.
@end deffn

@deffn {Primitive procedure} string-suffix? s1 s2 [start1 end1 start2 end2]
Return @code{#t} if @var{s1} is a suffix of @var{s2}.
@end deffn

@deffn {Primitive procedure} string-suffix-ci? s1 s2 [start1 end1 start2 end2]
Return @code{#t} if @var{s1} is a suffix of @var{s2}.  Case is ignored
when comparing characters.
@end deffn


@node String Searching, String Decomposition, String Comparison, String operations
@comment  node-name,  next,  previous,  up
@subsection String Searching

@deffn {Primitive procedure} string-index string ch/pred [start end]
Scans the string @var{string} for the leftmost appearance of character
@var{ch} and returns the index or @code{#f} if not found.  If the second
argument is a procedure, it must be a predicate which will be applied to
each character in @var{string}, and the index of the first character for
which the predicate yields true is returned.  @var{start} is the start
index and defaults to zero, @var{end} is the end index and defaults to
the length of @var{string} - 1.
@end deffn

@deffn {Primitive procedure} string-index-right string ch/pred [start end]
Scans the string @var{string} for the rightmost appearance of character
@var{ch} and returns the index or @code{#f} if not found.  If the second
argument is a procedure, it must be a predicate which will be applied to
each character in @var{string} from right to left, and the index of the
last character for which the predicate yields true is returned.
@var{start} is the start index and defaults to zero, @var{end} is the end
index and defatuls to the length of @var{string} - 1.  This function
searches from right to left, whereas @code{string-index} searches from
left to right.
@end deffn

@deffn {Primitive procedure} string-skip string ch/pred [start end]
Scans the string @var{string} for the leftmost appearance of a character
different to @var{ch} and returns the index or @code{#f} if not found.
If the second argument is a procedure, it must be a predicate which will
be applied to each character in @var{string}, and the index of the first
character for which the predicate yields false is returned.  @var{start}
is the start index and defaults to zero, @var{end} is the end index and
defaults to the length of @var{string} - 1.
@end deffn

@deffn {Primitive procedure} string-skip-right string ch/pred [start end]
Scans the string @var{string} for the rightmost appearance of a
character different from @var{ch} and returns the index or @code{#f} if
not found.  If the second argument is a procedure, it must be a
predicate which will be applied to each character in @var{string} from
right to left, and the index of the last character for which the
predicate yields false is returned.  @var{start} is the start index and
defaults to zero, @var{end} is the end index and defatuls to the length
of @var{string} - 1.  This function searches from right to left, whereas
@code{string-index} searches from left to right.
@end deffn

@deffn {Primitive procedure} string-count string ch/pred [start end]
Return a count of the number of characters in @var{string} that satisfy
the @var{ch/pred} argument.  If this argument is a procedure, it is
applied to all characters as a predicate; if it is a character, it is
used in a equality test.  @var{start} is the start index and defaults to
zero, @var{end} is the end index and defatuls to the length of
@var{string} - 1.
@end deffn

@deffn {Primitive procedure} string-contains string1 string2 [start1 end1 start2 end2]
Return the index in @var{string1} where @var{string2} occurs as a
substring, or @code{#f}.  The optional @var{start/end} indices restrict
the operation to the indicated substrings.  The returned index is in the
range [@var{start1}, @var{end1}).  A successful match must lie entirely
in the [@var{start1}, @var{end1}) range of @var{string1}.

Note: The current implementation uses the naivest possible algorithm and
is slow when @var{string1} is a long string.
@end deffn

@deffn {Primitive procedure} string-contains-ci string1 string2 [start1 end1 start2 end2]
Return the index in @var{string1} where @var{string2} occurs as a
substring, or @code{#f}.  The optional @var{start/end} indices restrict
the operation to the indicated substrings.  The returned index is in the
range [@var{start1}, @var{end1}).  A successful match must lie entirely
in the [@var{start1}, @var{end1}) range of @var{string1}.  Case is
ignored when comparing individual characters.

Note: The current implementation uses the naivest possible algorithm and
is slow when @var{string1} is a long string.
@end deffn

@deffn {Primitive procedure} string-hash s [bound start end]
Compute a hash value for the string @var{s}.  @var{bound} is either the
boolean constant @code{#t} or a positive integer, then the result of the
procedure will be in the range [0, @var{bound}).  @var{start} and
@var{end} are optional parameters delimiting the characters which are
used to calculate the hash value, they default to 0 and the length of
@var{s}.
@end deffn

@deffn {Primitive procedure} string-hash-ci s [bound start end]
Compute a hash value for the string @var{s}.  @var{bound} is either the
boolean constant @code{#t} or a positive integer, then the result of the
procedure will be in the range [0, @var{bound}).  @var{start} and
@var{end} are optional parameters delimiting the characters which are
used to calculate the hash value, they default to 0 and the length of
@var{s}.  The case of the characters in @var{s} is ignored when
computing the hash value.
@end deffn


@node String Decomposition, String Case Conversion, String Searching, String operations
@comment  node-name,  next,  previous,  up
@subsection String Decomposition

@deffn {Primitive procedure} string-split ch string
Splits the string @var{string} into pieces, using @var{ch} as the
delimiting character. Returns a list of strings, where the stings may be
empty if two or more delimiting characters are in @var{string} without
characters inbetween.
@end deffn

@deffn {Primitive procedure} string-take s nchars
Return the first @var{nchars} characters of @var{s}.
@end deffn

@deffn {Primitive procedure} string-take-right s nchars
Return the last @var{nchars} characters of @var{s}.
@end deffn

@deffn {Primitive procedure} string-drop s nchars
Return all but the first @var{nchars} characters of @var{s}.
@end deffn

@deffn {Primitive procedure} string-drop-right s nchars
Return all but the last @var{nchars} characters of @var{s}.
@end deffn


@node String Case Conversion, String Trimming, String Decomposition, String operations
@comment  node-name,  next,  previous,  up
@subsection String Case Conversion

@deffn {Primitive procedure} string-upcase! string [start end]
Convert all characters in @var{string} to upper case, modifying
@var{string} in-place.
@var{start} and @var{end} delimit the region of operation and default to
0 and the length of @var{string}.
@end deffn

@deffn {Primitive procedure} string-upcase string [start end]
Convert all characters in @var{string} to upper case, returning a newly
allocated string.
@var{start} and @var{end} delimit the region of operation and default to
0 and the length of @var{string}.
@end deffn

@deffn {Primitive procedure} string-downcase! string [start end]
Convert all characters in @var{string} to lower case, modifying
@var{string} in-place.
@var{start} and @var{end} delimit the region of operation and default to
0 and the length of @var{string}.
@end deffn

@deffn {Primitive procedure} string-downcase string [start end]
Convert all characters in @var{string} to lower case, returning a newly
allocated string.
@var{start} and @var{end} delimit the region of operation and default to
0 and the length of @var{string}.
@end deffn

@deffn {Primitive procedure} string-titlecase! string [start end]
Convert all characters in @var{string} which start words to upper case
and all other characters to lower case, modifying @var{string} in-place.
@var{start} and @var{end} delimit the region of operation and default to
0 and the length of @var{string}.
@end deffn

@deffn {Primitive procedure} string-titlecase string [start end]
Convert all characters in @var{string} which start words to upper case
and all other characters to lower case, returning a newly allocated
string.
@var{start} and @var{end} delimit the region of operation and default to
0 and the length of @var{string}.
@end deffn

@node String Trimming, String Padding, String Case Conversion, String operations
@comment  node-name,  next,  previous,  up
@subsection String Trimming

@deffn {Primitive procedure} string-trim string [char/pred start end]
Skip all characters matching the character @var{char} or passing
application of @var{pred} at the left of the string.  @var{start} and
@var{end} are optional parameters to restrict operation to the
characters between these indices.
@end deffn

@deffn {Primitive procedure} string-trim-right string [char/pred start end]
Skip all characters matching character @var{char} or passing application
of @var{pred} at the right of the string.  @var{start} and @var{end} are
optional parameters to restrict operation to the characters between
these indices.
@end deffn

@deffn {Primitive procedure} string-trim-both string [char/pred start end]
Skip all characters matching the character @var{char} or passing
application of @var{pred} at both ends of the string.  @var{start} and
@var{end} are optional parameters to restrict operation to the
characters between these indices.
@end deffn

@deffn {Primitive procedure} string-chop string
Return a newly allocated string with the contents of @var{string}, but
with all trailing newline characters removed.
@end deffn

@deffn {Library procedure} trim-whitespace string
Return @var{str}, but with all whitespace both at the beginning and at
the end removed.  The same characters are considered to be whitespace as
for the @code{char-whitespace?} primitive.

This procedure must be imported by using the module @code{core
string-lib}.

Note: This procedure has been deprecated.  Use @code{string-trim-both}
instead.
@end deffn

@node String Padding, String Pathname Operations, String Trimming, String operations
@comment  node-name,  next,  previous,  up
@subsection String Padding

@deffn {Primitive procedure} string-pad s len [char start end]
Build a string of length @var{len} comprised of @var{s} padded on the
left by as many occurences of the character @var{char} as needed.  If
@var{s} has more than @var{len} characters, it is truncated on the left
to length @var{len}.  @var{char} defaults to @code{#\space}.
@end deffn

@deffn {Primitive procedure} string-pad-right s len [char start end]
Build a string of length @var{len} comprised of @var{s} padded on the
rightt by as many occurences of the character @var{char} as needed.  If
@var{s} has more than @var{len} characters, it is truncated on the right
to length @var{len}.  @var{char} defaults to @code{#\space}.
@end deffn

@node String Pathname Operations,  , String Padding, String operations
@comment  node-name,  next,  previous,  up
@subsection String Pathname Operations

@deffn {Primitive procedure} basename name [suffix]
Removes any leading directory components from @var{name}; if
@var{suffix} is specified and is identical to the end of name, it is
removed from @var{name} as well. The resulting string is returned.
@end deffn

@deffn {Primitive procedure} dirname filename
Returns a string of all but the final slash-delimited component of
@var{filename}.  If @var{filename} is a single component, @code{dirname}
returns @code{.} (meaning the current directory).
@end deffn

@deffn {Primitive procedure} cleanup-filename filename
Clean the given @var{filename} up and convert it to a canonical form by
removing all appearences of parent directory references
(@code{/foo/..}), current directory marks (@code{./}), multiple slashes
(@code{//}) and trailing slashes. The root directory indicator @code{/}
is not deleted, though it is a trailing slash.
@end deffn

@deffn {Library procedure} tilde-expand string
Expand character sequences like @file{~} and @file{~username} in
@var{filename} like bash and Emacs do.  @var{filename} is unchanged if
it has the form @file{~username}, but the given user does not exist.

This procedure must be imported by using the module @code{core
string-lib}.
@end deffn


@node Vector operations, Homogenous Vector Operations, String operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Vector operations

Vectors are heterogenous data types, similar to lists.  That means that
any Scheme data type can be stored into vectors.  The main difference
between lists and vectors is that vectors are of fixed size and that
elements can be accessed in constant time, whereas lists require linear
time to access individual elements.

@menu
* Vector constructors::         Procedures for creating vectors.
* Vector predicates::           Procedure for examining vector objects.
* Vector selectors::            Accessing data from vectors.
* Vector conversion::           Converting from and to other data types.
* Vector modifying::            Changing vector content.
@end menu



@node Vector constructors, Vector predicates, Vector operations, Vector operations
@comment  node-name,  next,  previous,  up
@subsection Vector constructors

Vectors can be created by either entering them literally in the normal
Scheme vector syntax @code{#(...)}, or they can be created with one of
these functions.  See @ref{Vector conversion} for the procedure
@code{list->vector}, which is also a constructor function.

Vectors created with one of these procedures are mutable and can
therefore be passed to procedures like @code{vector-set!}.

@deffn {Primitive procedure} make-vector k
@deffnx {Primitive procedure} make-vector k fill
Return a newly allocated vector of length @var{k}. @var{fill} is used to
initialize the vector, if omitted the contents of the vector is
unspecified.
@end deffn

@deffn {Primitive procedure} vector obj @dots{}
Returns a newly allocated vector composed of its arguments.
@end deffn

@deffn {Library procedure} vector-tabulate count init-proc
Create a vector with @var{count} elements.  The vector is initialized by
setting the vector element at position @var{i} to the value returned by
applying @var{init-proc} to @var{i}.  The dynamic order in which
@var{init-proc} is applied is not specified.

This procedure must be imported by using the module @code{core
vector-lib}.
@end deffn

@deffn {Library procedure} vector-copy vec
Create a freshly allocated copy of the vector @var{vec}.

This procedure must be imported by using the module @code{core
vector-lib}.
@end deffn



@node Vector predicates, Vector selectors, Vector constructors, Vector operations
@comment  node-name,  next,  previous,  up
@subsection Vector predicates

@deffn {Primitive procedure} vector? obj
Returns @code{#t} if @var{obj} is a vector, @code{#f} otherwise.
@end deffn

@deffn {Library procedure} vector= elt= vec1 vec2 @dots{}
Returns true if all given vectors are equal.  Two vectors are equal if
they have the same length and if the elements at the corresponding
indices are equal according to the procedure @var{elt=}.

This procedure must be imported by using the module @code{core
vector-lib}.
@end deffn



@node Vector selectors, Vector conversion, Vector predicates, Vector operations
@comment  node-name,  next,  previous,  up
@subsection Vector selectors

Use one of these procedures to obtain information from a vector and to
access individual elements.

@deffn {Primitive procedure} vector-length vector
Returns the number of elements of @var{vector}.
@end deffn

@deffn {Primitive procedure} vector-ref vector k
Returns the @var{k}th element of @var{vector}. The index is
zero-based. @var{k} must be a valid index into @var{vector}, or an error
will be signalled.
@end deffn



@node Vector conversion, Vector modifying, Vector selectors, Vector operations
@comment  node-name,  next,  previous,  up
@subsection Vector conversion

@deffn {Primitive procedure} vector->list vector
Convert the vector @var{vector} to a list of all elements of
@var{vector}.
@end deffn

@deffn {Primitive procedure} list->vector lst
Convert the list @var{list} to a vector.
@end deffn



@node Vector modifying,  , Vector conversion, Vector operations
@comment  node-name,  next,  previous,  up
@subsection Vector modifying

The procedures in this section may only be used with mutable vectors.
Vectors literally entered may not be passed to these procedures.

@deffn {Primitive procedure} vector-set! vector k obj
Stores @var{obj} in element @var{k} of @var{vector}. An error will be
signalled if @var{k} is not a valid index into @var{vector}. The return
value of this function is unspecified.
@end deffn

@deffn {Primitive procedure} vector-fill! vector obj
Stores @var{obj} in all elements of @var{vector}. The return value is
not specified.
@end deffn

@node Homogenous Vector Operations, Control flow operations, Vector operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Homogenous Vector Operations

Homoenous vectors are different to normal Scheme vectors, because only
numeric values can be stored into those vectors, and all elements must
have the same type.

Please note that homogenous vectors are only available when they were
included on configuration time of the Sizzle library.  If you need these
data types and primitives, please @ref{Building Sizzle} and build the
library with enabled homogenous vectors.

In the following procedure descriptions, the placeholder @var{TAG} can
be replaced by any of the strings @code{s8}, @code{u8}, @code{s16},
@code{u16}, @code{s32}, @code{u32}, @code{s64}, @code{u64}, @code{f32}
and @code{f64}, depending on the data type the procedure should be used
for. Examples are: @code{s8vector?}, @code{make-u16vector} or
@code{f32vector-length}.

@deffn {Primitive procedure} @var{TAG}vector? obj
Returns @code{#t} if @var{obj} matches the type indicated by @var{TAG},
@code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} make-@var{TAG}vector n [fill]
Create a vector for holding values of the type @var{TAG}, which can hold
exactly @var{n} elements.  @var{fill} is used to initialize the vector
and defaults to 0, if not present.
@end deffn

@deffn {Primitive procedure} @var{TAG}vector-length vec
Returns the length of the homogenous vector @var{vec}, which must be of
type @var{TAG}.
@end deffn

@deffn {Primitive procedure} @var{TAG}vector obj1 @dots{}
Creates and returns a homogenous vector of type @var{TAG} and
initializes it with all parameters.  The resulting vector has as much
elements as there are @var{obj} parameters.
@end deffn

@deffn {Primitive procedure} @var{TAG}vector-ref vec n
Returns the element at position @var{n} in the homogenous vector @var{vec}.
@end deffn

@deffn {Primitive procedure} @var{TAG}vector-set! vec n obj
Stores the object @var{obj} at position @var{n} into the homogenous
vector @var{vec}.  @var{vec} must be of the vector type indicated by
@var{TAG}, and @var{obj} must match @var{TAG} also.
@end deffn

@deffn {Primitive procedure} @var{TAG}vector->list vec
Converts the homogenous vector @var{vec}, which must match the vector
type indicated by @var{TAG}, to a list of its elements.
@end deffn

@deffn {Primitive procedure} list->@var{TAG}vector list
Creates a homogenous vector which holds all elements of the list
@var{list}.  All elements must match the type @var{TAG}.
@end deffn

@deffn {Primitive procedure} @var{TAG}vector-fill!! vec fill
Stores the object @var{fill} into all slots of the homogenous vector
@var{vec}.  @var{vec} must match the vector type indicated by @var{TAG},
and @var{fill} must be of a type compatible with @var{TAG}.
@end deffn

@deffn {Primitive procedure} string->s8vector str
@deffnx {Primitive procedure} string->u8vector str
Convert the string @var{str} into a signed or unsigned 8-bit vector.
@end deffn

@deffn {Primitive procedure} s8vector->string vec
@deffnx {Primitive procedure} u8vector->string vec
Convert the signed of unsigned 8-bit vector @var{vec} to a string.
@end deffn


@node Control flow operations, Eval function, Homogenous Vector Operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Control flow operations

The following procedures can be used to maintain the flow of control in
Scheme programs.  The basic procedure @code{apply}, exception handling
using @code{catch} and @code{throw} and handling of multiple values with
@code{values}, @code{call-with-values} and @code{receive} are documented
in this section.

These procedures are always available in the Sizzle library except when
otherwise noted.

@deffn {Primitive procedure} procedure? obj
Returns @code{#t} if @var{obj} is a primitive or user-defined procedure,
@code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} primitive-procedure? obj
Returns @code{#t} if @var{obj} is a primitive procedure, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} closure? obj
Returns @code{#t} if @var{obj} is a user-defined procedure, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} form? obj
Returns @code{#t} if @var{obj} is a syntactic form, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} apply proc arg1 @dots{} args
@var{proc} must be a procedure and @var{args} must be a list. Calls
@var{proc} with the elements of the list @code{(append (list arg1 ...)
args)} as the actual arguments.
@end deffn

@deffn {Primitive procedure} force promise
Force the evaluation of @var{promise}, which must be created with a
prior call to @code{delay}.  The value of the promise is cached so that
a second force will return the cached value without evaluating it again.
@end deffn

@deffn {Primitive procedure} values obj @dots{}
Delivers all its arguments to its continuation. Used with
@code{call-with-values} (see below).
@end deffn

@deffn {Primitive procedure} call-with-values producer consumer
Calls its @var{producer} thunk and calls the @var{consumer} with
whatever values have been returned by @var{producer}.  @var{consumer}
must take as many arguments as @var{producer} has returned values.
@end deffn

@deffn {Library syntax} receive formals expression body
This is a more convenient way to handle multiple values.
@var{expression} is evaluated and the results are assigned to variables
named in @var{formals}, then @var{body} is evaluated.  @var{formals}
must be of the same form as allowed for specifying the formal parameters
of a lambda expression.

This syntax is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Primitive procedure} dynamic-wind before thunk after
Calls @var{thunk} without arguments, returning the result(s) of the
call.  @var{before} is called before @var{thunk} is called, and
@var{after} is called after @var{thunk}.  @code{dynamic-wind} can be
used for cleaning up, since @var{after} is called even if @var{thunk}
causes an error or an exception.
@end deffn

@deffn {Primitive procedure} signal no proc
Install a signal handler.  After installing a signal handler with this
function, @var{proc} is called whenever the signal @var{no} is sent to
the Sizzle process.  The signals defined for your system are available
as constants, on a normal GNU/Linux box the following signals are
predefined:
@table @code
@item SIGHUP
Hangup signal.
@item SIGINT
Interrupt, normally generated when the user types @key{C-c}.
@item SIGQUIT
Quit.
@item SIGILL
Illegal instruction.
@item SIGTRAP
Trap.
@item SIGABRT
Process abort.
@item SIGIOT
Input/output trap.
@item SIGBUS
Bus error.  Normally due to misaligned data access.
@item SIGFPE
Floating point exception.
@item SIGKILL
Kill signal. This cannot be caught.
@item SIGUSR1
First user-definable signal.
@item SIGUSR2
Second user-definable signal.
@item SIGSEGV
Segmentation fault.
@item SIGPIPE
Broken pipe. Generated when writing to a closed pipe.
@item SIGALRM
Alarm.
@item SIGTERM
Process termination.
@item SIGSTKFLT
Stack fault
@item SIGCLD
The same as @code{SIGCHLD}.
@item SIGCHLD
Child process terminated.
@item SIGCONT
Continue signal.
@item SIGSTOP
Stop signal.
@item SIGTSTP
Terminal stop.
@item SIGTTIN
Terminal input signal.
@item SIGTTOU
Terminal output signal.
@item SIGURG
Urgency signal.
@item SIGXCPU
CPU time exceeded.
@item SIGXFSZ
File limit exceeded.
@item SIGVTALRM
Virtual alarm.
@item SIPROF
Profiler signal.
@item SIGWINCH
Window configuration changed.
@item SIGPOLL
Poll signal.
@item SIGIO
Input/output signal.
@item SIGPWR
Power failure.
@end table

Note that this procedure is only available when the Un*x signals work
for the underlying platform.
@end deffn

@deffn {Primitive procedure} error obj @dots{}
Signal an error.  The current computation is aborted and the list of the
arguments which is passed to the top level together with the error is
displayed on the current standard error output port.
@end deffn

@deffn {Primitive procedure} throw symbol obj @dots{}
Raise an exception with the exception tag @var{tag} which will be passed
upward in the call chain until either a @code{catch} clause for the
@var{tag} exception tag catches the exception or the top level is
reached, where the exception will be displayed on the current standard
error output port.
@end deffn

@deffn {Primitive procedure} catch tag thunk handler
@code{catch} is used to implement exception handling. @var{thunk} is
evaluated but any exception which may be thrown by an expression
evaluated inside of @var{thunk} and is equal to the exception tag
@var{tag} (in the sense of @code{eq?}) is caught. Should no exception be
raised, the result of the last expression is returned.  Otherwise,
@var{handler} is called with the tag which was thrown to and additional
arguments which may be passed to throw as arguments and the result of
evaluating @var{handler} is returned.

If @var{tag} is @code{#t}, all exceptions are caught.

@example
zzz: (catch 'panic 
            (lambda () (throw 'panic "Help" "Me" "!" )) 
            (lambda (tag . rest) (display rest) (newline) #f))
(Help Me !)
#f
zzz: (catch #t 
            (lambda () (throw 'burgs)) 
            (lambda (tag . rest) #f))
#f
@end example
@end deffn

@deffn {Primitive procedure} toplevel
Return to the top level read-eval-print loop of the current Sizzle
session, or, if running non-interactively, returns to the top level file
loading loop.
@end deffn

@deffn {Primitive procedure} exit
@deffnx {Primitive procedure} exit n
Terminate the running Sizzle process, returning to the shell which
executed it.  @var{n} is the exit code of the process, if given,
otherwise the exit code is zero.
@end deffn

@deffn {Primitive procedure} call-with-current-continuation proc
@deffnx {Primitive procedure} call/cc proc
Calls @var{proc} with the current continuation as its argument.
@var{proc} may then call the passed continuation with a parameter to
deliver that value to the continuation.  The result of
@code{call-with-current-continuation} is either the result of @var{proc}
(if the continuation was not called) or the argument passed to the
continuation.

When calling a continuation with more then one parameter, all
parameters are delivered to the continuation as multiple values.

@code{call/cc} is synonym to @code{call-with-current-continuation}.

Note that Sizzle does not implement a full-featured @code{call/cc}. The
continuation passed to @var{proc} may only be used as an escape
procedure.  Storing it into a variable and using it from anywhere not in
the dynamic extent of @var{proc} is an error and will signal an
exception.
@end deffn

@deffn {Primitive procedure} primitive-load string
Loads and evaluates all Scheme expressions from the file named
@var{string}. Evaluation takes place in the toplevel environment. The
return value is unspecified.  Throws an @code{file-not-found} exception
if @var{string} does not refer to an existing file.  The return value is
unspecified.
@end deffn

@deffn {Primitive procedure} primitive-load-path string
Loads and evaluates all Scheme expressions from the file named
@var{string}. Evaluation takes place in the toplevel environment. The
return value is unspecified.  When @var{string} is not an absolute file
name, @code{primitive-load-path} tries to locate the file in the current
directory and then in all directories in the pathname list
@var{%load-path}.  Throws an @code{file-not-found} exception if
@var{string} does not refer to an existing file.  The return value is
unspecified.
@end deffn

@deffn {Primitive procedure} load string
Synonym to @code{primitive-load-path}.
@end deffn

@deffn {Primitive procedure} transcript-on filename
@deffnx {Primitive procedure} transcript-off
@var{filename} must be a string naming an output file to be created.
The effect of @code{transcript-on} is to open the named file for output,
and to cause a transcript of subsequent interaction between the user and
the Scheme system to be written to the file. The transcript is ended by
a call to @code{transcript-off}, which closes the transcript file.  Only
one transciript may be in progress at any time.  The values returned by
these procedures are unspecified.
@end deffn



@node Eval function, Debugging Support, Control flow operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Eval function

All of the following procedures are always defined in the Sizzle
interpreter.

@deffn {Primitive procedure} eval expression 
@deffnx {Primitive procedure} eval expression environment-specifier
Evaluate @var{expression} in the environment given by
@var{environment-specifier}. If omitted, the current environment is
used.  Enironment specifiers can only be obtained by using one of the
following three procedures.
@end deffn

@deffn {Primitive procedure} scheme-report-environment version
Return an environment with all bindings defined in R5RS to be used with
@code{eval}.  @var{version} must be an exact integer spcifying the
supported Scheme report version, currently this is 5.
@end deffn

@deffn {Primitive procedure} null-environment version
Return an empty environment to be used with @code{eval}.  @var{version}
must be an exact integer spcifying the supported Scheme report version,
currently this is 5.
@end deffn

@deffn {Primitive procedure} interaction-environment
Return the environment of the read-eval-print loop to be used with
@code{eval}.
@end deffn

@deffn {Primitive procedure} current-environment
Return the environment currently used to look up bindings to be used
with @code{eval}.
@end deffn

@deffn {Primitive procedure} safe-environment symbol-list
Create and return a @dfn{safe} environment, in which only the special
forms are defined.  Also, the current bindings for all symbols in
@var{symbol-list} are entered into the new environment.  This procedure
can be used to construct environments in which untrusted code can be
safely executed.  The executed code then only has access to the builtin
special forms and all bindings passed explicitly to
@code{safe-environment}, and is not able to affect any other
environments.
@end deffn

@node Debugging Support, Input and output, Eval function, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Debugging Support

The following procedures are always supported.

@deffn {Primitive procedure} backtrace
Prints a procedure backtrace for the last error signalled.  You have to
evaluate @code{(set! eval-save-backtrace #t)} prior to evaluating the
invalid expression or the backtrace will not be available.
@end deffn

@deffn {Primitive procedure} trace proc on/off
Note: Tracing is currently disabled because it slows down the
interpreter and was not too useful.  If you should need it, please
contact the author.

If @var{on/off} is true, start tracing procedure @var{proc}, otherwise,
switch tracing for @var{proc} off.

When a procedure is traced, a message will be printed to the current
error port whenever the procedure is called.  Given a procedure
@code{foo}, which receives one argument, the format of the message is
@example
+ foo <- (1)
@end example
That means that @code{foo} is entered (indicated by the @code{+}) with
the parameter list @code{(1)}.

When tracing primitive procedures, a message when exiting from the
procedure is also printed.  A call to the traced primitive @code{modulo}
with the parameter list @code{(3 2)} looks like this:
@example
+ modulo <- (3 2)
- modulo -> 1
@end example
The second line tells that the result of the function is @code{1}.

Currently, no exit message is printed for non-primitive procedures is
printed because of problems with tail calls.  With the current scheme,
it is not possible to tell easily when a procedure exits.  I hope to
change that behaviour in the future.
@end deffn

@deffn {Primitive procedure} symbol-table
Returns the global symbol table, in which all globally existing symbols
are stored.  The returned table is a vector of lists of symbols, which
can be examined if you are curious.  Be careful when using this
procedure and never modify the table or any data stored in it, or the
interpreter may heavily crash.
@end deffn

@deffn {Primitive procedure} keyword-table
Returns the global keyword table, in which all globally existing keywords
are stored.  The returned table is a vector of lists of keywords, which
can be examined if you are curious.  Be careful when using this
procedure and never modify the table or any data stored in it, or the
interpreter may heavily crash.
@end deffn


@node Input and output, Regular expression functions, Debugging Support, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Input and output

@c FIXME: This node is too long, we should split it.  Maybe in
@c string ports, file ports, general port operation etc.

The procedures in this section all deal with input and output of data
from and to various types of ports.  Unless otherwise noted, all the
procedures are always available in the interpreter.

@deffn {Primitive procedure} call-with-input-file string proc
Opens the file named @var{string} for input and calls @var{proc} with
the newly created input port as a single argument.
@end deffn

@deffn {Primitive procedure} call-with-output-file string proc
Opens the file named @var{string} for output and calls @var{proc} with
the newly created output port as a single argument.
@end deffn

@deffn {Primitive procedure} input-port? obj
Returns @code{#t} if @var{obj} is an input port, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} output-port? obj
Returns @code{#t} if @var{obj} is an output port, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} current-input-port
Returns the current default input port.
@end deffn

@deffn {Primitive procedure} current-output-port
Returns the current default output port.
@end deffn

@deffn {Primitive procedure} current-error-port
Returns the current default error output port.
@end deffn

@deffn {Primitive procedure} set-current-input-port port
Set @var{port} to be the value which subsequent calls to
@code{current-input-port} will return.
@end deffn

@deffn {Primitive procedure} set-current-output-port port
Set @var{port} to be the value which subsequent calls to
@code{current-output-port} will return.
@end deffn

@deffn {Primitive procedure} set-current-error-port port
Set @var{port} to be the value which subsequent calls to
@code{current-error-port} will return.
@end deffn

@deffn {Primitive procedure} with-input-from-file string thunk
Opens the file named @var{string} for input and makes it the current
default input port for the time @var{proc} is called.
@end deffn

@deffn {Primitive procedure} with-output-to-file string thunk
Opens the file named @var{string} for output and makes it the current
default output port for the time @var{proc} is called.
@end deffn

@deffn {Primitive procedure} with-error-to-file string thunk
Opens the file named @var{string} for output and makes it the current
default error port for the time @var{proc} is called.
@end deffn

@deffn {Primitive procedure} open-input-file filename
Returns an input port connected to the file named @var{filename}. An
error is signalled if the file cannot be opened.
@end deffn

@deffn {Primitive procedure} open-output-file filename
Returns an ouput port connected to the file named @var{filename}. An
error is signalled if the file cannot be opened. If a file with the same
name already exists, it will be overwritten.
@end deffn

@deffn {Primitive procedure} close-port port
Close the port @var{port}.
@end deffn

@deffn {Primitive procedure} close-input-port port
Close the input port @var{port}.  This is synonymous to
@code{close-port}, but is required by R5RS.
@end deffn

@deffn {Primitive procedure} close-output-port port
Close the output port @var{port}.  This is synonymous to
@code{close-port}, but is required by R5RS.
@end deffn

@deffn {Primitive procedure} force-output port
Force all buffered output to @var{port} to be actually written to the
underlying file.  If @var{port} is a string port, nothing happens.  The
return value is unspecified.
@end deffn

@deffn {Primitive procedure} read
@deffnx {Primitive procedure} read port
Read a scheme object from @var{port}.  @var{port} is omitted, the
current input port is used.
@end deffn

@deffn {Primitive procedure} read-char
@deffnx {Primitive procedure} read-char port
Reads a character from @var{port} and returns it.  @var{port} is
omitted, the current input port is used. Returns the end-of-file object
on end of file.
@end deffn

@deffn {Primitive procedure} unread-char char
@deffnx {Primitive procedure} unread-char char port
Put the character @var{char} back on the port @var{port}, so that it can
bea read again with @code{read-char}.  @var{port} defaults to the value
returned by @code{current-input-port}, if not given.
@end deffn

@deffn {Primitive procedure} peek-char
@deffnx {Primitive procedure} peek-char port
Reads a character from @var{port} and return its without removing it
from the port. A subsequent call to @code{read-char} on the same port
will return the character again.  @var{port} is omitted, the current
input port is used. Returns the end-of-file object on end of file.
@end deffn

@deffn {Primitive procedure} char-ready?
@deffnx {Primitive procedure} char-ready? port
Tests whether a character is available to be read from @var{port} and
returns @code{#t} if it is, @code{#f} otherwise.  If @var{port} is not
specified, the current input port is used.
@end deffn

@deffn {Library procedure} read-line [port [handle-delim]]
@code{read-line} reads a newline-terminated string from @var{port}.  The
return value depends on the value of @var{handle-delim}, which may be
one of the symbols @code{trim}, @code{concat}, @code{peek} and
@code{split}.  If it is @code{trim} (the default), the trailing newline
is removed and the string is returned.  If @code{concat}, the string is
returned with the trailing newline intact.  If @code{peek}, the newline
is left in the input port buffer and the string is returned.  If
@code{split}, the newline is split from the string and @code{read-line}
returns a pair consisting of the truncated string and the newline.

This procedure is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Primitive procedure} %read-delimited! delims buf gobble? [port start end]
Read characters from @var{port} into @var{buf} until one of the
characters in the @var{delims} string is encountered.  If @var{gobble?}
is true, store the delimiter character in @var{buf} as well; otherwise,
discard it.  If @var{port} is not specified, use the value returned by
@code{current-input-port}.  If @var{start} or @var{end} are specified,
store data only into the substring of @var{buf} bounded by @var{start}
and @var{end} (which default to the beginning and end of the buffer,
respectively).

Return a pair consisting of the delimiter that terminated the string and
the number of characters read.  If reading stopped at the end of file,
the delimiter returned is the @var{eof-object}; if the buffer was filled
without encountering a delimiter, this value is @var{#f}.
@end deffn

@deffn {Primitive procedure} write-line obj [port]
Display @var{obj} and a newline character to @var{port}.  If @var{port}
is not specified, @code{(current-output-port)} is used.  This function
is equivalent to:
@smalllisp
(display obj [port])
(newline [port])
@end smalllisp
@end deffn

@deffn {Primitive procedure} seek port offset whence
Change the position of the file pointer for @var{port}. @var{offset} is
used to calculate the new file offset, depending on @var{whence}.  Three
variable may be used for values to give as @var{whence}.
@table @code
@item SEEK_SET
@var{offset} is used as the new file offset.
@item SEEK_CUR
@var{offset} is added to the current offset to yield the new file offset.
@item SEEK_END
@var{offset} is subtracted from the file length to yield the new file
offset.
@end table
@var{port} may also be a string port, which means that the read/write
pointer for the string port will be modified.

The return value is the new offset of the file pointer.
@end deffn

@deffn {Primitive procedure} ftell port
Return the current offset of the file pointer of @var{port}, which may
be a file or string port.
@end deffn

@deffn {Primitive procedure} eof-object? obj
Returns @code{#t} if @var{obj} is the end-of-file object, @code{#f}
otherwise.
@end deffn

@deffn {Primitive procedure} port-closed? port
Returns @code{#t} if @var{port} is a closed port, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} display obj
@deffnx {Primitive procedure} display obj port
Print the textual representation of @var{obj} to @var{port}.  @var{obj}
is not quoted when printing. @code{display}'s return value is
unspecified. If @var{port} is omitted, the current output port is used.
@end deffn

@deffn {Primitive procedure} write obj
@deffnx {Primitive procedure} write obj port
Print the textual representation of @var{obj} to @var{port}.  @var{obj}
is quotedwhen printing. @code{write}'s return value is unspecified. If
@var{port} is omitted, the current output port is used.
@end deffn

@deffn {Primitive procedure} write-char char
@deffnx {Primitive procedure} write-char char port
Write @var{char} to @var{port}. The actual character code of @var{char}
is written, not its read syntax. @code{write-char}'s return value is
unspecified. If @var{port} is omitted, the current output port is used.
@end deffn

@deffn {Primitive procedure} newline
@deffnx {Primitive procedure} newline port
Simply prints a newline character to @var{port}, thus ending the current
output line.  The same can be achieved by printing a newline character
using the function @code{display}.  @code{newline}'s return value is
unspecified. If @var{port} is omitted, the current output port is used.
@end deffn

@deffn {Primitive procedure} call-with-input-string string proc
Create an input string port which will return the contents of
@var{string} and call @var{proc}, passing the newly created string port
as the argument.
@end deffn

@deffn {Primitive procedure} call-with-output-string proc
Call @var{proc} with a string port as the argument and return all data
which was written to the string port while @var{proc} was executing as a
string.
@end deffn

@deffn {Primitive procedure} with-input-from-string string thunk
Call @var{thunk} with the current input port connected to a string port
which delivers the contents of @var{string}.
@end deffn

@deffn {Primitive procedure} with-output-to-string thunk
Call @var{thunk} and return a string consisting of all data which was
written to the current output port during execution of @var{thunk}.
@end deffn

@deffn {Primitive procedure} with-error-to-string thunk
Call @var{thunk} and return a string consisting of all data which was
written to the current error port during execution of @var{thunk}.
@end deffn

@deffn {Primitive procedure} open-input-string string 
Takes @var{string} and returns an input port that delivers characters
from the string.  The port can be closed by @code{close-input-port},
though its storage will be reclaimed by the garbage collector if it
becomes inaccessible.
@end deffn

@deffn {Primitive procedure} open-output-string
Returns an output port that will accumulate characters for retrieval by
@code{get-output-string}.  The port can be closed by
@code{close-output-port}, though its storage will be reclaimed by the
garbage collector if it becomes inaccessible.
@end deffn

@deffn {Primitive procedure} get-output-string output-port
Given an output port created with @code{open-output-string}, returns a
string consisting of the characters that have been output to the port so
far.
@end deffn

@deffn {Primitive procedure} with-input-from-port port thunk
Call @var{thunk}, but while @var{thunk} is evaluating, redirect all
input from the input port @var{port}.
@end deffn

@deffn {Primitive procedure} with-output-to-port port thunk
Call @var{thunk} and redirect all output sent to the current output port
to @var{port} while @var{thunk} is evaluating.
@end deffn

@deffn {Primitive procedure} with-error-to-port port thunk
Call @var{thunk} and redirect all output sent to the current error port
to @var{port} while @var{thunk} is evaluating.
@end deffn

@deffn {Primitive procedure} port-line
@deffnx {Primitive procedure} port-line port
Return the current line number of the port @var{port}.  If
@var{port} is not specified, the current input port is used.
@end deffn

@deffn {Primitive procedure} set-port-line! port n
Set the current line number of the port @var{port} to the value of
@var{n}, which must be an integer value.  The return value is not
specified.
@end deffn

@deffn {Primitive procedure} port-column
@deffnx {Primitive procedure} port-column port
Return the current line column number of the port @var{port}.  If
@var{port} is not specified, the current input port is used.
@end deffn

@deffn {Primitive procedure} set-port-column! port n
Set the current column number of the port @var{port} to the value of
@var{n}, which must be an integer value.  The return value is not
specified.
@end deffn

@deffn {Primitive procedure} port-filename
@deffnx {Primitive procedure} port-filename port
Return the file name of the port @var{port}.  If @var{port} is not
specified, the current input port is used.
@end deffn

@deffn {Primitive procedure} set-port-filename! port s
Set the file name of the port @var{port} to the value of @var{s}, which
must be an string value.  The return value is not specified.
@end deffn

@deffn {Primitive procedure} isatty? [port]
Return @code{#t}, if @var{port} is a tty, @code{#f} otherwise.
@var{port} defaults to the current input port.
@end deffn

@deffn {Primitive procedure} object->string obj
Return a string with the characters @code{display} would produce when
printing @var{obj}.
@end deffn


@node Regular expression functions, System interface functions, Input and output, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Regular expression functions

Sizzle supports Posix regular expressions.  This section documents all
functions provided to match text using regular expressions.

Note that Posix regular expressions only support matching of strings
which do not include null bytes.

Regular expression operations are not available if the Sizzle library
was configured with the @code{--disable-regexp} option or if no usable
regular expression matching library was found on configuration time.

@deffn {Primitive procedure} regexp? obj
Returns @code{#t} if @var{obj} is a compiled regular expression object,
@code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} make-regexp string flags @dots{}
Create a compiled regular expression object which represents the string
@var{string}.  The following additional arguments can be passed to
control regular expression compilation:
@table @code
@item regexp/icase
The matching is performed case-insensitively.
@item regexp/extended
Support extended Posix regular expressions (this is the default).
@item regexp/basic
Do not support extended Posix regular expressions.
@item regexp/newline
Treat a newline in the matched string as beginning/end of the string as
far as the beginning-of-line and end-of-line operators are concerned.
@end table
@end deffn

@deffn {Primitive procedure} regexp-exec rx string [start [flags]]
Match the regular expression @var{rx} against @var{string}.  If
@var{start} is given, start matching at that position.  Flags may be a mask of the following constants:
@table @code
@item regexp/notbol
The match-beginning-of-line operator always fails to match.
@item regexp/noteol
The end-beginning-of-line operator always fails to match.
@end table
@end deffn



@node System interface functions, Network Procedures, Regular expression functions, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section System interface functions

@c FIXME: Split up, because this node is too long.

The Posix standard and many traditional Unix versions define a lot of
functions which are useful for systems programming.  Some of the most
useful functions have been included into Sizzle, so it can be used for
basic system programming tasks as well as all other uses.

Not all functionality documented in this section is available on all
platforms.  @code{fork}, for example cannot be implemented efficiently
under Windoze.  Primitives, which do not function properly on the system
Sizzle was compiled on, will throw a @code{not-available} exception when
called.

Except when otherwise noted, procedures in this section are not
available when Sizzle was configured with the @code{--disable-posix}
option.  You also need to perform a @code{(use-modules (core posix))}
call to make these procedures available.


@deffn {Primitive procedure} command-line
Returns a list containing the command line arguments passed to the
interpreter.  Note that if you invoke a Sizzle script with the @code{-s
SCRIPT} command line option, only the script name (as the first element
in the command line) and the arguments after @code{SCRIPT} are contained
in the command line list.

This procedure is always available.
@end deffn

@deffn {Primitive procedure} system [command]
Execute the command @var{command} using the command line shell and
return the exit code of the given command.  If no @var{command} is
given, return #t if a command processor is available and #f otherwise.
This function may raise a @code{system-error} exception if an error
occurs.  The return value is the exit code of the child process.
@end deffn

@deffn {Primitive procedure} getenv string
Returns the value of the environment variable called @var{string} if
defined, and @code{#f} otherwise.

This procedure is always available.
@end deffn

@deffn {Primitive procedure} putenv string
Insert the string @var{string} into the process environment.
@var{string} must be of the form @i{name=value}.  The return value is
not specified.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getcwd
Returns a string which denotes the current working directory.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} chdir string
Change the current working directory to @var{string}.  A
@code{system-error} exception will be raised if the directory
@var{string} cannot be changed to.  The return value is not specified.
@end deffn

@deffn {Primitive procedure} getpid
Returns the process identifier (pid) of the running Sizzle process.
@end deffn

@deffn {Primitive procedure} getppid
Returns the parent process identifier of the running Sizzle process.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getuid
Returns the user identifier (uid) of the user running the current Sizzle
process.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} setuid uid
Set the user identifier of the current Sizzle process to @var{uid}.
Only the superuser can do that.  This function may raise a
@code{system-error} exception if an error occurs.  The return value is
not specified.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} geteuid
Returns the effective user identifier of the running Sizzle process.  A
@code{system-error} exception may be raised if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} seteuid euid
Set the effective user identifier of the current Sizzle process to
@var{euid}.  This function may raise a @code{system-error} exception if
an error occurs.  The return value is not specified.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getgid
Returns the group identifier of the running Sizzle process.  A
@code{system-error} exception may be raised if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} setgid gid
Set the group identifier of the running Sizzle process to @var{gid}.  A
@code{system-error} exception may be raised if an error occurs.  The
return value is not specified.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getegid
Returns the effective group identifier of the running Sizzle process.  A
@code{system-error} exception may be raised if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} setegid egid
Set the effective group identifier of the running Sizzle process to
@var{egid}.  A @code{system-error} exception may be raised if an error
occurs. The return value is not specified.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getpgid pid
Returns the process group identifier of the process specified by
@var{pid}.  If @var{pid} is zero, the process identifier of the current
process is used.  This function may raise a @code{system-error}
exception if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getpgrp
This is equivalent to (getpgid 0).

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getpwnam name
Returns a vector containing the broken out fields of a line from
@file{/etc/passwd} for the entry that matches the user name
@var{name}. This function may raise a @code{system-error} exception if
an error occurs.  The returned vector contains the fields:
@table @code
@item username
Login name
@item password
Crypted password or @code{x} if using shadow passwords
@item uid
User identifier
@item gid
group identifier
@item gecos
Full name, maybe additional information
@item dir
Login directory
@item shell
Login shell
@end table

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} getpwuid uid
Returns a vector containing the broken out fields of a line from
@file{/etc/passwd} for the entry that matches the user identifier
@var{uid}.  This function may raise a @code{system-error} exception if an
error occurs.  The returned vector has the same format as for
@code{getpwnam}.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Library procedure} pw:name vec
@deffnx {Library procedure} pw:passwd vec
@deffnx {Library procedure} pw:uid vec
@deffnx {Library procedure} pw:gid vec
@deffnx {Library procedure} pw:gecos vec
@deffnx {Library procedure} pw:dir vec
@deffnx {Library procedure} pw:shell vec
Accessor procedures for the fields of the vector returned by
@code{getpwnam} and @code{getpwuid}.
@end deffn

@deffn {Primitive procedure} getgroups
Returns a vector containing all groups the current user belongs to.
This function may raise a @code{system-error} exception if an error
occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} stat filename
Returns information about the specified file.  You do not need any
access rights to the file to get this information but you need search
rights to all directories named in the path leading to the file.  This
function may raise a @code{system-error} exception if an error occurs.
The returned vector has the following fields:
@table @code
@item dev
Device the file is located on.
@item ino
Inode number of the file.
@item mode
The file mode and permissions.
@item nlink
Number of hard links to the file.
@item uid
User identifier of the file owner.
@item gid
Group identifier of the file owner
@item rdev
Device type (if inode device)
@item size
Total size in bytes
@item atime
Time of last access
@item mtime
Time of last modification
@item ctime
Time of last change
@item blksize
Block size for the filesystem the file is on
@item blocks
Number of blocks the file allocates
@item type
The type of the file as a symbol, which may be any of @code{regular},
@code{directory}, @code{symlink}, @code{block-special},
@code{char-special}, @code{fifo}, @code{socket} or @code{unknown}.
@item perms
Permissions of the file.  This is the file mode without the file type
bits.
@end table
The file mode is a bitset which can be tested by logically combining it
with one or more of the following constants:
@table @code
@item S_ISUID
Set user identifier
@item S_ISGID
Set group identifier
@item S_IRWXU
User (file owner) has read, write and execute permission
@item S_IRUSR
User has read permission
@item S_IWUSR
User has write permission
@item S_IXUSR
User has execute permission
@item S_IRWXG
Group has read, write and execute permission
@item S_IRGRP
Group has read permission
@item S_IWGRP
Group has write permission
@item S_IXGRP
Group has execute permission
@item S_IRWXO
Others have read, write and execute permission
@item S_IROTH
Others have read permission
@item S_IWOTH
Others have write permission
@item S_IXOTH
Others have execute permission
@end table

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} lstat filename
Like @code{stat}, but does not follow symbolic links.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Library procedure} stat:dev vec
@deffnx {Library procedure} stat:ino vec
@deffnx {Library procedure} stat:mode vec
@deffnx {Library procedure} stat:nlink vec
@deffnx {Library procedure} stat:uid vec
@deffnx {Library procedure} stat:gid vec
@deffnx {Library procedure} stat:rdev vec
@deffnx {Library procedure} stat:size vec
@deffnx {Library procedure} stat:atime vec
@deffnx {Library procedure} stat:mtime vec
@deffnx {Library procedure} stat:ctime vec
@deffnx {Library procedure} stat:blksize vec
@deffnx {Library procedure} stat:blocks vec
@deffnx {Library procedure} stat:type vec
@deffnx {Library procedure} stat:perms vec
These are accessor functions for extracting fields from the vectors
returned by @code{stat} and @code{lstat}.
@end deffn

@deffn {Primitive procedure} access? filename mode
Checks whether the process would be allowed to read, write or test for
existence of the file (or other file system object) whose name is
pathname.  If pathname is a symbolic link permissions of the file
referred to by this symbolic link are tested.  Returns @code{#t} if
access is permitted, @code{#f} otherwise.  This function may raise a
@code{system-error} exception if an error occurs.  @var{mode} is a mask
of one or more of the following constants:
@table @code
@item R_OK
Test for read permission
@item W_OK
Test for write permission
@item X_OK
Test for execute permission
@item F_OK
Test for file existence
@end table
@code{access?} is only successful if all permissions are granted.
@end deffn

@deffn {Primitive procedure} sys:pipe
Creates a pair of file descriptors, pointing to a pipe inode. The car of
the returned pair is a file descriptor for reading, the cdr is a file
descriptor for writing.  This function may raise a @code{system-error}
exception if an error occurs.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} open-fdes filename flags [mode]
Attempts to open the file called @var{filename} and returns a file
descriptor.  @var{flags} is a mask of one or more of the following:
@table @code
@item O_RDONLY
Open the file read only.
@item O_WRONLY
Open the file write only.
@item O_RDWR
Open the file for reading and writing.
@item O_CREAT
If the file does not exist it will be created.
@item O_EXCL
When used with @code{O_CREAT}, if the file already exists it is an error
and the open will fail.
@item O_NOCTTY
If pathname refers to a terminal device -- see tty(4) -- it will not
become the process's controlling terminal even if the process does not
have one.
@item O_TRUNC
If the file already exists it will be truncated.
@item O_APPEND
The file is opened in append mode.  Initially, and before each write, the
file pointer is positioned at the end of the file, as if with lseek.
@item O_NONBLOCK
Open the file in non-blocking mode, which means that operations on the
file do not wait for completion.
@item O_NDELAY
The same as @code{O_NONBLOCK}.
@item O_SYNC
Writes to the file will be immediately written to disk.
@end table
If @code{O_CREAT} is given and the file will be created, the additional
argument @var{mode} must be given, which denotes the file permission the
new file will have.  @var{mode} is a mask of the permission constants
listed in the description of @code{stat}.

This function may raise a @code{system-error} exception if an error
occurs.
@end deffn

@deffn {Primitive procedure} sys:creat mode
This is equivalent to @code{open} with flags equal to @code{(logior
O_CREAT O_WRONLY O_TRUNC)}.
@end deffn

@deffn {Primitive procedure} close fd
Closes a file descriptor, if @var{fd} is an integer, so that it no
longer refers to any file and may be reused, or simply closes @var{fd}
of it is a port.  This function may raise a @code{system-error}
exception if an error occurs.
@end deffn

@deffn {Primitive procedure} sys:write fd u8vec count
Write @var{count} bytes from the homogenous unsigned 8-bit vector
@var{u8vec} to the file referenced by the file descriptor @var{fd}.
Returns the number of bytes actually written.  This function may raise a
@code{system-error} exception if an error occurs.

This procedure is only available if homogenous vectors were enable on
configuration time.
@end deffn

@deffn {Primitive procedure} sys:read fd count
Read @var{count} bytes from the file referenced by the file descriptor
@var{fd} and returns a homogenous unsigned 8-bit vector containing those
bytes.  This function may raise a @code{system-error} exception if an
error occurs.

This procedure is only available if homogenous vectors were enable on
configuration time.
@end deffn

@deffn {Primitive procedure} sys:read! fd u8vec count
Read @var{count} bytes from the file referenced by the file descriptor
@var{fd} and stores them into the homogenous unsigned 8-bit vector
@var{u8vec}.  The return value is not specified.  This function may
raise a @code{system-error} exception if an error occurs.

This procedure is only available if homogenous vectors were enable on
configuration time.
@end deffn

@deffn {Primitive procedure} unlink filename
Deletes a name from the filesystem. If that name was the last link to a
file and no processes have the file open the file is deleted and the
space it was using is made available for reuse.  The return value is not
specified.  This function may raise a @code{system-error} exception if
an error occurs.
@end deffn

@deffn {Primitive procedure} link oldpath newpath
Creates a new link (also known as a hard link) to an existing file.  If
@var{newpath} exists it will not be overwritten.  The return value is
not specified.  This function may raise a @code{system-error} exception
if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} symlink oldpath newpath
Creates a new symbolic link to an existing file.  If @var{newpath}
exists it will not be overwritten.  The return value is not specified.
This function may raise a @code{system-error} exception if an error
occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} rename oldpath newpath
Renames a file, moving it between directories if required.
@var{oldpath} and @var{newpath} must refer to the same file system.  The
return value is not specified.  This function may raise a
@code{system-error} exception if an error occurs.
@end deffn

@deffn {Primitive procedure} readlink filename
Returns the name of the file the link @var{filename} is referring to.
This function may raise a @code{system-error} exception if an error
occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} chmod path mode
The mode of the file given by @var{path} is changed to @var{mode}.
@var{mode} is a mask made from the @code{S_I...} constants listed in the
description of @code{stat}.  This function may raise a
@code{system-error} exception if an error occurs.
@end deffn

@deffn {Primitive procedure} chown path uid gid
Set the user identifier and group identifier of the file @var{path} to
@var{uid} and @var{gid}.  If any of @var{uid} or @var{gid} is equal to
-1, that component of @var{path}'s ownership is not changed.  This
function may raise a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} primitive-exit [status]
Terminate the current process without performing any cleanup.  The exit
status is @var{status}, which defaults to 0 if not specified.  This
procedure has no return value, because it never returns.
@end deffn

@deffn {Primitive procedure} fork
Creates a child process that differs from the parent process only in its
process identifier and parent process identifier, and in the fact that
resource utilizations are set to 0.  File locks and pending signals
are not inherited.  This function may raise a @code{system-error}
exception if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} kill pid sig
Sends any signal to any process group or process.  If @var{pid} is
positive, then signal @var{sig} is sent to @var{pid}.

If @var{pid} equals 0, then @var{sig} is sent to every process in the
process group of the current process.  If @var{pid} equals -1, then
@var{sig} is sent to every process except for the first one, from higher
numbers in the process table to lower.  If @var{pid} is less than -1,
then @var{sig} is sent to every process in the process group -@var{pid}.
If @var{sig} is 0, then no signal is sent, but error checking is still
performed.

This function may raise a @code{system-error} exception if an error
occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} wait
Waits for any child process to terminate and returns a pair whose car is
the process id of the child and whose cdr is the exit code.  This
function may raise a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} waitpid pid [options]
Waits until child process @var{pid} has terminated.  For usage of the
@var{options} argument, refer to the @code{waitpid} man page.  This
function may raise a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} sleep n
Suspend the running process for @var{n} seconds, or until a signal wakes
up the process.  This function may raise a @code{system-error} exception
if an error occurs.
@end deffn

@deffn {Primitive procedure} execl filename args
Execute the file @var{filename}, passing the list @var{args} as command
line options.  This function may raise a @code{system-error} exception
if an error occurs.
@end deffn

@deffn {Primitive procedure} execlp filename args
Like @code{execl}, but search the path for @var{filename}.
@end deffn

@deffn {Primitive procedure} execle filename args env
Like @code{execl}, but pass the environment list @var{env} together with
the command line arguments @var{args} to the process.
@end deffn

@deffn {Primitive procedure} nice inc
Change the current process priority by amount @var{inc}.  You must be
the system administrator to pass a negative @var{inc}.  This function
may raise a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} sync
Force all dirty block from the cache of the operating system to be
written to the disks.  This function
may raise a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} uname
Return a vector containing information about the system. This function
may raise a @code{system-error} exception if an error occurs.  The
returned vector contains the following fields:
@table @code
@item sysname
The name of the operating system.
@item nodename
The name of the host.
@item release
The operating system release.
@item version
The operating system version.
@item machine
The machine architecture.
@end table

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} utime filename [timelist]
If @var{timelist} is omitted, set the access and modification time for
the file @var{filename} to the current time.  Otherwise, @var{timelist}
must be a list of two integer values, which will be used to set the
access and modification time of @var{filename}.  This function may raise
a @code{system-error} exception if an error occurs.
@end deffn

@deffn {Primitive procedure} tmpnam
The @code{tmpnam} procedure generates a unique temporary filename in the
standard directory for temporary files (normally @file{/tmp}).

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} tmpfile
The @code{tmpfile} procedure generates a unique temporary filename in
the standard directory for temporary files (normally @file{/tmp}) .  The
temporary file is then opened in binary read/write (w+b) mode.  The file
will be automatically deleted when it is closed or the program
terminates.  The return value is a port open for input and output.  This
function may raise a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} umask [mask]
@code{umask} sets the umask to @code{(logand mask #o777)}.  The umask is
used by open(2) to set initial file permissions on a newly-created file.
Specifically, permissions in the umask are turned off from the mode
argument to open(2) (so, for example, the common umask default value of
022 results in new files being created with permissions 0666 & ~022 =
0644 = rw-r--r-- in the usual case where the mode is specified as 0666).
If @var{mask} is not given, the current umask value is returned, without
changing the umask for the process.
@end deffn

@deffn {Primitive procedure} strftime format vec
Format the time-representing vector @var{vec} according to the format
specifier @var{format} to a string and return that string.  For details
of the format specified, have a look at @code{man strftime}.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} strptime format string
Parse the string @var{string} according to the format specifier
@var{format}.  Check out @code{man strptime} for the format
specification.  Returns a pair consisting of a time vector and the
number of characters of @var{string} which have been used up when
parsing.  This procedure is essentialy the counterpart of
@code{strftime}.

This procedure is only available if supported by the underlying C
library.
@end deffn

@deffn {Primitive procedure} gmtime x
Split up the time object @var{x}, which represents the current time in
standard Unix convention in seconds since January 1, 1970.  Returns a
vector with the split up fields of the time.  The times in the vector is
in Coordinated Universal Time. The result vector contains the following
fields:
@table @asis
@item seconds
@item minutes
@item hours
@item day of month
@item month
@item year
@item day of the week
@item day in the year
@item daylight saving time
@item time zone offset
@item time zone name or @code{#f} if not specified
@end table
@end deffn

@deffn {Primitive procedure} localtime x
Returns @var{x} converted to local time in a vector of the format
defined in the description of @code{gmtime}.

Bug: Right now time zone offset and time zone names are not correctly
set by @code{localtime}.
@end deffn

@deffn {Library procedure} tm:sec timevec
@deffnx {Library procedure} tm:min timevec
@deffnx {Library procedure} tm:hour timevec
@deffnx {Library procedure} tm:mday timevec
@deffnx {Library procedure} tm:month timevec
@deffnx {Library procedure} tm:year timevec
@deffnx {Library procedure} tm:wday timevec
@deffnx {Library procedure} tm:yday timevec
@deffnx {Library procedure} tm:isdst timevec
@deffnx {Library procedure} tm:zoff timevec
@deffnx {Library procedure} tm:zname timevec
These procedure return the fields their names stand for from the time
vector @var{timevec}, which must have the format documented in the
decription for @code{gmtime}.
@end deffn

@deffn {Primitive procedure} current-time
Return the current time in an integer, represented in the number of
seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal
Time (UTC).  The value returned by this procedure can be used in calls
to @code{gmtime} or @code{localtime}, which split up the time value into
its various parts.
@end deffn

@deffn {Primitive procedure} directory-files dirname
Return a list containing all files in the directory @var{dirname}.  This
procedure may throw a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} fcntl fdesc cmd [arg]
@code{fcnt} performs one of various operations on the file descriptor
@var{fd}.  The following commands are possible:
@table @code
@item F_DUPFD
Makes arg be a copy of fd, closing @var{fdesc} first if necessary.
@item F_GETFD
Read the close-on-exec flag.  If the low-order bit is 0, the file will
remain open across exec, otherwise it will be closed.
@item F_SETFD
Set the close-on-exec flag to the value specified by arg (only the least
significant bit is used).
@item F_GETFL
Read the descriptor's flags (all flags (as set by open(2)) are
returned).
@item F_SETFL
Set the descriptor's flags to the value specified by arg.  Only
@code{O_APPEND} and @code{O_NONBLOCK} may be set.  The flags are shared
between copies (made with dup etc.) of the same file descriptor.
@item F_GETLK, F_SETLK, F_SETLKW
Manage discretionary file locks.  This command is not properly
implemented in Sizzle right now.
@item F_GETLK
This command is not properly implemented in Sizzle right now.
@item F_SETLK
This command is not properly implemented in Sizzle right now.
@item F_SETLKW
This command is not properly implemented in Sizzle right now.
@item F_GETOWN
Get the process ID or process group currently receiving SIGIO and SIGURG
signals for events on file descriptor fd.  Process groups are returned
as negative values.
@item F_SETOWN
Set the process ID or process group that will receive @code{SIGIO} and
@code{SIGURG} signals for events on file descriptor @var{fd}.  Process
groups are specified using negative values.
@end table

This procedure is only available if supported by the underlying C
library and (limited) under Windows.
@end deffn

@deffn {Primitive procedure} fsync fdesc
@var{fdesc} must be either a valid file descripor or a file port.  All
pending output is written if @var{fdesc} is a file port.  The data
buffered for the underlying file descriptor is then forced to be written
to disk using the system call @code{fsync}.

This procedure is only available if the @code{fsync()} system call is
available and under Windows.
@end deffn

@deffn {Primitive procedure} copy-file oldfile newfile
Copy the file specified by @var{oldfile} to @var{newfile}.  The return
value is unspecified.
@end deffn

@deffn {Primitive procedure} directory-stream? obj
Return @code{#t} if @var{obj} is a directory stream, @code{#f} otherwise.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} opendir str
Open the directory called @var{str} and return a directory stream for
that directory, which can be used in calls to @code{readdir},
@code{closedir} and @code{rewinddir}.  This procedure may raise a
@code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} closedir stream
Close the directory stream @var{stream}.  The return value is not
specified.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} readdir stream
Return the next filename from the directory stream @var{stream}, or the
end-of-file object if all files have been read.  This procedure may
raise a @code{system-error} exception if an error occurs.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn

@deffn {Primitive procedure} rewinddir stream
Rewind the directory stream to the beginning, so that on the next call
to @code{readdir}, the first file from the stream will be read.  The
return value is not specified.

This procedure is only available if supported by the underlying C
library and under Windows.
@end deffn


@node Network Procedures, Module System, System interface functions, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Network Procedures

The procedures in this section are useful for network programming.  You
have to use the module @code{(core net)} in order to make them visible.

@defvr {Exception} network-error
This exception is thrown when an error occurs while using any of the
network functions.  The exception contains an error message obtained
with @code{strerror(errno)} or @code{herror()}, whatever is appropriate
for the specific error.
@end defvr

@deffn {Primitive procedure} socket domain type protocol
Creates a socket port using @var{domain}, @var{type} and @var{protocol}.
This is a direct wrapper to the C library function, so refer to the libc
documentation for details.  Normally you specify the @var{domain} as the
constant @code{AF_INET} and the @var{type} @code{SOCK_STREAM} for normal
internet sockets.  This procedure may raise a @code{system-error}
exception if an error occurs.  The following socket types are also defined:
@table @code
@item SOCK_STREAM
@item SOCK_DGRAM
@item SOCK_RAW
@item SOCK_SEQPACKET
@item SOCK_RDM
@end table
For the defined address family constants, refer to the documentation for
@code{bind}.
@end deffn

@deffn {Primitive procedure} shutdown sock how
Sockets can be closed simply by using @code{close-port}. The
@code{shutdown} procedure allows reception or transmission on a
connection to be shut down individually, according to the parameter
@var{how}:
@table @asis
@item 0
Stop receiving data for this socket.  If further data arrives, reject it.
@item 1
Stop trying to transmit data from this socket.  Discard any data waiting
to be sent.  Stop looking for acknowledgement of data already sent;
don't retransmit it if it is lost.
@item 2
Stop both reception and transmission.
@end table
The return value is unspecified.
@end deffn

@deffn {Primitive procedure} listen sock backlog
This procedure enables @var{sock} to accept connection requests.
@var{backlog} is an integer specifying the maximum length of the queue
for pending connections.  If the queue fills, new clients will fail to
connect until the server calls @code{accept} to accept a connection from
the queue.  The return value is unspecified.
@end deffn

@deffn {Primitive procedure} gethostbyname name
Returns the IPv4 address of the host named @var{name}.  @var{name} may
be either a string, which must represent a valid hostname, or an integer
value.  If it is an integer value, it is returned unchanged and not
validated, if it is a string, the IP address is looked up and returned.
This procedure may raise a @code{network-error} exception if an error
occurs.
@end deffn

@deffn {Primitive procedure} accept sock
Accepts a connection on a bound, listening socket @var{sock}.  If
there are no pending connections in the queue, it waits until one is
available unless the non-blocking option has been set on the socket.

The return value is a pair in which the @dfn{car} is a new socket port
for the connection and the @dfn{cdr} is an object with address
information about the client which initiated the connection.

If the address is not available then the @dfn{cdr} will be an empty
vector.  @var{sock} does not become part of the connection and will
continue to accept new requests.
@end deffn

@deffn {Primitive procedure} getsockname sock
Returns the address of @var{sock}, in the same form as the object
returned by @code{accept}.
@end deffn

@deffn {Primitive procedure} getpeername sock
Returns the address of the socket @var{sock} is connected to, in the
same form as the object returned by @code{accept}.
@end deffn

@deffn {Primitive procedure} ntohl n
Converts the 32 bit value @var{n} from network to host byte order.
@end deffn

@deffn {Primitive procedure} htonl n
Converts the 32 bit value @var{n} from host to network byte order.
@end deffn

@deffn {Primitive procedure} ntohs n
Converts the 16 bit value @var{n} from network to host byte order.
@end deffn

@deffn {Primitive procedure} htons n
Converts the 16 bit value @var{n} from host to network byte order.
@end deffn

@deffn {Primitive procedure} fileno port
Returns the file descriptor used for operations on @var{port}.
@var{port} must be a file descriptor port, or an error will be
signalled.
@end deffn

@deffn {Primitive procedure} connect hostname port
Establish a connection to the host identified by @var{hostname} on port
@var{port}.  @var{hostname} must be either a string naming the host or
an integer value which represents an IP address.  Currently, only IPv4
addresses are supported.  Returns a socket port which can be written to
and read from to communicate with the peer.  This procedure may raise
@code{network-error} and @code{system-error} exceptions.
@end deffn

@deffn {Primitive procedure} server-socket port
Returns a socket, which listens on the local IP address on port
@var{port}.  A port returned by this procedure may be used in calls to
@code{accept}.
@end deffn

@deffn {Primitive procedure} server-loop port proc
This procedure can be used to implement simple network applications.
@var{port} must be a port created by @code{server-socket} or any
equivalent calling sequence to @code{socket}, @code{bind} and
@code{listen}.  @code{server-loop} will wait for incoming connection
using @code{accept} and call @var{proc} when a connection is available.
@var{proc} must expect two parameters, the first one being an input port
connected to the accepted socket, the second an output port connected to
the socket.
@end deffn

@deffn {Primitive procedure} bind scheme-port family address port
Bind the port @var{scheme-port}, created with a call to @code{socket} to
the address specified by @var{family}, @var{address}, and the port
number @var{port}.  This procedure returns an unspecified value.

The following address families are defined:
@table @code
@item AF_UNIX
Unix sockets family.
@item AF_INET
Internet socket family.
@end table
If your system supports them, the following families are also defined:
@table @code
@item AF_ISO
@item AF_NS
@item AF_IMPLINK
@end table
@end deffn

@deffn {Primitive procedure} select rdfd wrfd exfd sec usec
Perform the @code{select} system call on the file descriptor sets
@var{rdfd}, @var{wrdf} and @var{exfd}.  The timeout value is calculated
from the seconds @var{sec} and the microseconds @var{usec}.  The number
of the highest file descriptor in any of the sets is returned as the
result.
@end deffn

@deffn {Primtitive procedure} gethostname
Get the host name of the local host.  The returned value is a string.
@end deffn

@deffn {Primitive procedure} sethostname name
Set the host name of the local host to @var{name}.  The return value is
not specified.
@end deffn

@deffn {Primitive procedure} getdomainname
Get the domain name of the local host.  The returned value is a string.
@end deffn

@deffn {Primitive procedure} setdomainname
Set the domain name of the local host to @var{name}.  The return value
is not specified.
@end deffn

@deffn {Primitive procedure} inet-aton addr
Convert the internet address @var{addr} from dotted decimal notation to
binary data.  The returned value is an integer.
@end deffn

@deffn {Primitive procedure} inet-ntoa addr
Convert the internet address @var{addr} from binary representation to a
string.  The returned value is a string.
@end deffn


@node Module System, Dynamic Loading, Network Procedures, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Module System

Scheme is suited for programming large programs, but it is very
inconvenient to implement modules with restricted exports using standard
techniques.  Therefore, a module system similar to Guile's has been
implemented.

In Sizzle, a module is a data structure with a private environment in
which all definitions local to the module are stored and an export list
which defines which of the defined symbols are to be exported to other
modules.  When a module is imported using the syntactic form
@code{use-modules}, the symbol bindings from the export list are
transferred to the environment of the importing module, thus making
visible the exports.  This works for procedures as well as for variables
and constants.

The syntax and procedures for modules are always available.

@deffn {Syntax} use-modules name0 name1 ...
Import all modules listed as @var{names}.  If any module is not yet
loaded, it will be loaded using the load path.  Modules imported by any
of the imported modules will be loaded recursively.
@end deffn

@deffn {Syntax} define-module name options ...
Define a module called @var{name} and switch to the context of the new
module, that means that all definitions made until the end of the file
will be made in the private environment of the module.  Definitions can
be made public using the syntactic form @code{export}, documented below.

Options may be one or more pair of a keyword and a value.  The following
keywords are presently defined:
@table @code
@item #:use-module
The value must be a module name (a list of symbols) which specifies a
module to be loaded for defining the new module.
@item #:export
The value must be a list of symbols listing the defines to be exported.
This is an alternative notation for the @code{export} syntactic form.
@end table
@end deffn

@deffn {Syntax} export symbol0 symbol1 ...
Add all @var{symbols} to the export list of the currently active module.
@end deffn

@deffn {Primitive procedure} module-list
Return a list of currently loaded modules.
@end deffn

@deffn {Primitive procedure} current-module
Return the module in which currently definitions take place.
@end deffn


@node Dynamic Loading, Macro functions, Module System, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Dynamic Loading

Sizzle support dynamic loading of shared libraries under Unix using the
dl interface.  The following procedures are not available if no usable
dynamic loading support was found for the underlying platform or when
disabled with the @code{--disable-dl} configuration option.

@defvr {Exception} dl-error
This exception is thrown when an error occurs while using the @file{dl}
library.  The exception contains an error message obtained with
@code{dlerror()}.
@end defvr

@deffn {Primitive procedure} load-library name [filename]
Load and initialize the shared object name.  If @var{filename} is
specified, the file named @var{filename} is @code{dlopen()}'ed,
otherwise the file name @code{lib@var{name}.so} is opened via
@code{dlopen()}.  When the loaded object exports a symbol called
@code{zzz_init_@var{name}()}, this function is called without arguments
and should initialize the library. 

This function may throw a @code{dl-error} exception if the file could
not be loaded or if the initialization function returned a value other
than @code{RESULT_SUCCESS}.
@end deffn

Besides the high-level procedure @code{load-library}, some low-level
procedures are provided which implement a wrapper around the @file{dl}
library.

@deffn {Primitive procedure} %dlopen filename [flags]
@code{dlopen()} the file @var{filename} and return a dynamic library
object for that file.  @var{flags} may be the bitwise or of the following
constants:
@table @code
@item RTLD_GLOBAL
Make the symbols in the loaded file available to other processes.
@item RTLD_LAZY
Relocate symbols when they are used.
@item RTLD_NOW
Relocate all symbols when the library is loaded.
@end table
@end deffn

@deffn {Primitive procedure} %dlclose lib
Take a dynamic library object @var{lib} and close it.  After that, calls
to @code{%dlsym} with the library @var{lib} will fail.
@end deffn

@deffn {Primitive procedure} %dlsym lib string
Return the address of the symbol @var{string} in the library specified
by the dynamic library object @var{lib}.  Throw a @code{dl-error}
exception if the dymbol could not be resolved.
@end deffn

@deffn {Primitive procedure} %dlcall address
Call the function specified by @var{address} (which must have been found
with a call to @code{%dlsym}) without arguments.  A @code{dl-error}
exception is thrown if the function returns a value other than
@code{RESULT_SUCCESS}.
@end deffn


@node Macro functions, Runtime system, Dynamic Loading, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Macro functions

Sizzle can handle macros defined using the primitive
@code{define-macro}.  The macro interface should be compatible to
Guile's, but I have not yet verified that completely.  The macro syntax
and procedures are always available.

@deffn Syntax define-macro (name arg @dots{}) body
Define a macro @var{name} which as many arguments as @var{args} are
given.  When the macro is expanded, the symbols in @var{args} are bound
to the actual parameters of the macro call and @var{body} is evaluated.
The result of evaluating the macro body expression is then substituted
for the macro call.  The return value is unspecified.

This is an example of a macro @code{writeln}, which prints all its
arguments using @code{display} and then advances to the next line using
@code{newline}.
@example
(define-macro (writeln . --x)
  `(begin (for-each display (list ,@@--x)) (newline)))
@end example

You have to be careful about the formal parameter names given with
@var{args}, because they may shadow variables visible when the macro is
called.
@end deffn

@deffn {Primitive procedure} expand-macro list
Expand the macro call represented by @var{list} and return the expanded
expression.  The @code{car} of the list must be a macro object.
@example
zzz: (define-macro (unless cond . body)
       `(if (not ,cond) (begin ,@@body)))
zzz: (expand-macro (list unless '(> x 0) '(display x)))
(if (not (> x 0)) (begin (display x)))
@end example
@end deffn

@deffn {Primitive procedure} apply-macro macro list
Apply the macro @var{macro}, which must have been created with
@code{define-macro} to the argument list @var{list}.  This will cause
the transformer procedure for @var{macro} to be applied to the arguments
in @var{list}.  The value returned by the macro transformer is returned.
@end deffn

@c  Sizzle also has some limited support for the macros from R5RS, but be
@c  careful when using them for the following reasons: The syntax is not
@c  fully implemented, especially substituting for vector patterns does not
@c  work.  Most important, because this is a major feature of R5RS macros,
@c  is the lacking of hygienic macros.  Variable shadowing and free variable
@c  capturing is very likely when using these macros in Sizzle.  Maybe you
@c  should not use them at all at the moment, but since they are somehow
@c  implemented and accessible, I decided to at least document their
@c  deficiencies.

@c  For more information about macros, have a look at the Sizzle startup
@c  file @file{init.scm}, located in the @file{data} subdirectory in the
@c  distribution, where some simple macros are defined.  Also refer to R5RS
@c  for more information about syntax and semantics of the macro definition
@c  commands.

@c  @deffn {Syntax} let-syntax ((variable syntax-rule) @dots{}) body
@c  Bind the syntax rules @var{syntax-rules}, which must be created using
@c  the syntactic form @code{syntax-rules} to the @var{variables} and evaluate
@c  @var{body}.  The defined syntactic forms will be visible in @var{body}
@c  only.  The return value is the return value of the last expression in
@c  @var{body}.
@c  @end deffn

@c  @deffn {Syntax} letrec-syntax ((variable syntax-rule) @dots{}) body
@c  Bind the syntax rules @var{syntax-rules}, which must be created using
@c  the syntactic form @code{syntax-rules} to the @var{variables} and evaluate
@c  @var{body}.  The defined syntactic forms will be visible in the
@c  @var{syntax-rule} statements and @var{body} only.  In contrast to
@c  @code{let-syntax}, syntax elements defined in the variable binding
@c  section can refer to each other recursively.  The return value is the
@c  return value of the last expression in @var{body}.
@c  @end deffn

@c  @deffn {Syntax} define-syntax name syntax-rule
@c  Bind the syntax rules @var{syntax-rule}, which must be created with
@c  @code{syntax-rules}, to @var{name} in the current environment.  The
@c  return value is unspecified.
@c  @end deffn

@c  @deffn {Syntax} syntax-rules (literals @dots{}) rule @dots{}
@c  Define a syntactic form.  @var{literals} is a list of symbols which are to
@c  be treated literally in the @var{rules}.  Each rule has the form
@c  @code{(@var{pattern} @var{templace})}, where each @var{templace} has the
@c  form @code{(@var{keyword} @var{pattern} @dots{})} and each @var{template}
@c  has the form @var{constant}, @var{symbol}, @code{(@var{template} @dots{})}
@c  or @code{#(@var{template} @dots{})}.
@c  @end deffn



@node Runtime system, Self-Documentation, Macro functions, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Runtime system

It is often necessary to access the runtime system for writing efficient
programs, but also for debugging purposes.  The procedures in this
section are provided for that task.  They are always available in the
interpreter.

@deffn {Primitive procedure} garbage-collect
Triggers immediate garbage collection.  The return value is unspecified.
@end deffn

@c  @deffn {Primitive procedure} autoload symbol filename
@c  Install an autoload association for @var{symbol}.  The result is
@c  unspecified.  Whenever an autoload association is encountered in
@c  procedure position when evaluating a procedure application, the file
@c  named @var{filename} is loaded using @code{primitive-load-path}.  The
@c  file mus define a procedure called @var{symbol}, or an error will be
@c  signalled.
@c  @end deffn

@node Self-Documentation, Box Operations, Runtime system, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Self-Documentation

Sizzle provides a mechanism to make using it more comfortable.  This is
some kind of self-documentation as known from programs like Emacs.  The
principle of this feature is that every procedure object, both primitive
and user-defined can have a documentation object attached.  Normally,
these objects are simply strings which tell how to use the procedure,
which parameters are expected and what value(s) is/are returned, as well
as a short description of the functionality.

The following procedures help to make use of the self-documentation
system.  They are always available in the interpreter.

@deffn {Primitive procedure} documentation obj
Returns the documentation object attached to @var{obj}.  Returns
@code{#f} if no wuch object is available.  For procedure objects,
@code{documentation} tries to load a documentation string from the file
@file{docstrings.txt}, which was installed with Sizzle.  Not all
primitives are documented in this file yet, so @code{#f} may be returned
for them, too.
@end deffn

@deffn {Primitive procedure} set-documentation! obj doc
Attach the documentation object @var{doc} to the Scheme object
@var{obj}.  @var{doc} will be returned when applying
@code{documentation} to @var{obj} after calling this procedure.  The
return value is unspecied.
@end deffn

@deffn {Primitive procedure} describe obj
Print a description of @var{obj} to the current output port.  This
description includes the type of @var{obj} and the documentation object
or documentation string attached to @var{obj}.  The return value is
unspecified.
@end deffn

@deffn {Primitive procedure} apropos string
Print a one-line description of all procedures with @var{string} their
names.  This can be used to get a list of procedure names, so that
@code{describe} can be used on the procedures to get more information
about them.  The return value of this procedure is not specifed.
@end deffn

@node Box Operations, Pointer Operations, Self-Documentation, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Box Operations

This section documents the procedures provided for handling boxes.  For
more information about boxes, refer to @ref{Boxes}.  All box primitives are
always available in the interpreter.

@deffn {Primitive procedure} box? obj
Return @code{#t} if @var{obj} is a box, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} make-box obj
Return a newly allocated box object which contains the object @var{obj}.
@end deffn

@deffn {Primitive procedure} box-ref b
Return the object contained in the box object @var{b}.
@end deffn

@deffn {Primitive procedure} box-set! b obj
Store the object @var{obj} into the box object @var{b}.  Return an
unspecified value.
@end deffn


@node Pointer Operations, Misc functions, Box Operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Pointer Operations

Sizzle provides pointer objects which are useful when interfacing to C
library procedures.  For more information, have a look at
@ref{Pointers}.  These procedures are always available.

@deffn {Primitive procedure} pointer? obj
Return @code{#t} if @var{obj} is a pointer object, @code{#f} otherwise.
@end deffn

@deffn {Primitive procedure} make-pointer n
Create a new pointer object.  @var{n} must be a non-negative integer,
and a memory block big enough to hold @var{n} bytes will be allocated
and the pointer will point to it.  If @var{n} is 0, then a null-pointer
will be returned.
@end deffn

@deffn {Primitive procedure} invalidate-pointer! p
Invalidate the pointer @var{p} by setting its @i{invalid} flag.
@end deffn


@node Misc functions, Syntactic Forms, Pointer Operations, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Misc functions

This section is a catch-all for all primitive procedures which do not
fit into any of the other categories.  They are always available in the
interpreter except when otherwise noted.

@deffn {Primitive procedure} gc-stats
Return an association list containing various information about the
state of the garbage collector.  The following elements are contained in
the list:
@table @code
@item used-cons-cells
Number of cons cells which are currently in use.
@item used-tagged-cells
Number of tagged cells which are currently in use.
@item allocated-cons-cells
Number of cons cells in the cons heap, both free cells and cells which
are in use.
@item allocated-tagged-cells
Number of tagged cells in the tagged heap, both free cells and cells
which are in use.
@item cons-heap-usage
Number of bytes currently allocated for the cons heap.
@item tagged-heap-usage
Number of bytes currently allocated for the tagged heap.
@item other-usage
Number of bytes currently allocated for other purposes, such as for
vector and string contents etc.
@item gc-count
Number of garbage collections since startup.
@item gc-time
Time spent in the garbage collector since the interpreter started.
@item gc-percent
Amount of the total running time which was spent in the garbage
collector since the interpreter started up.
@end table
@end deffn

@deffn {Primitive procedure} profile-stats
Return an association list containing various information about internal
profiling statistics.  The values in the returned association list are
only valid if profiling was enabled during compilation.  The following
elements are contained in the list:
@table @code
@item global-accesses
Variable accesses which required a complete variable lookup.
@item lloc-accesses
Variable access which went through an @code{lloc} object.
@item gloc-accesses
Variable access which went through a @code{gloc} object.
@item tail-calls
Procedure calls which were executed tail-recursively.
@item evaluate-calls
Calls to the function @code{zzz_evaluate()}.
@item closure-calls
Calls to closure objects (lambda applications).
@item primitive-calls
Calls to primitive procedures.
@item syntactic-calls
Executions of non-memoized syntactic forms.
@item immediate-calls
Executions of memoized syntactic forms.
@end table
@end deffn

@deffn {Primitive procedure} random n
Return a random number (an integer value) which is in the range
[0..@var{n}).  @code{random} returns always the same sequence of random
number, unless you have set the random seed using @code{srand}.
@end deffn

@deffn {Primitive procedure} srand n
Set the random seed for the procedure @code{random} to @var{n}.  The
return value is not specified.
@end deffn

@deffn {Library procedure} 1+ x
@deffnx {Library procedure} 1- x
@deffnx {Library procedure} add1 x
@deffnx {Library procedure} sub1 x
Handy helper functions.  @code{1+} and @code{add1} return their argument
plus 1, @code{1-} and @code{sub1} return their argument minus 1.  These
functions are often used in textbooks on Scheme, so I put them in.

These procedures are not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Library procedure} pretty-print obj [port]
Pretty-print the Scheme object @var{obj} to @var{port}, or to the
standard output port if @var{port} is omitted.  Pretty-printing means
that list and vector structures will be printed in a human-readable form
and with proper indentation.

You have to use the module @code{(core pprint)} to have access to this
procedure.
@end deffn


@node Syntactic Forms,  , Misc functions, Builtin Procedures
@comment  node-name,  next,  previous,  up
@section Syntactic Forms

There are two types of syntactic forms.  The forms labelled with
@i{Syntax} are builtin syntax, the forms labelled @i{Defined syntax} or
@i{Macro} are defined in the startup file @file{init.scm} and may be not
present if the embedding application does not load this init file.

Except when otherwise stated, all of these syntactic forms and
procedures are always available in the interpreter.

@deffn Syntax quote obj
Returns its argument @var{obj} unevaluated.  This is normally used to
type in symbols and is used so often that a shorthand form exists:
Instead of @samp{(quote foo)} you can write @samp{'foo}.
@end deffn

@deffn Syntax quasiquote obj
Works similar to @code{quote}, with the difference that expressions with
@code{unquote} or @code{unquote-splicing} are evaluated in
@var{obj}. Also has a shorthand form: @samp{`foo} has the same meaning
@samp{(quasiquote foo)}.
@end deffn

@deffn Syntax unquote obj
When used inside of a @code{quasiquote} expression, evaluates its
argument. Also has a shorthand form: @samp{,foo} has the same meaning
@samp{(unquote foo)}. @code{unquote} may only be used inside of
@code{quasiquote} expression, an error is signalled if used in another
context.
@end deffn

@deffn Syntax unquote-splicing obj
When used inside of a @code{quasiquote} expression, evaluates its
argument. The difference between @code{unquote} and
@code{unsuote-splicing} is that the latter requires its argument to
evaluate to a list which is then inserted at the current position with
one level of nesting removed. Also has a shorthand form: @samp{,@@foo}
has the same meaning @samp{(unquote-splicing
foo)}. @code{unquote-splicing} may only be used inside of
@code{quasiquote} expression, an error is signalled if used in another
context.
@end deffn

@deffn Syntax set! variable expression
Set the value of @var{variable} to the value of @var{expression}.  The
return value is not specified. You can only use @code{set!} on variables
which have been already defined by either @code{define} or one of the
@code{let}-constructs.
@end deffn

@deffn Syntax define variable expression
Define @var{variable} as a variable and set its value to the value of
@var{expression}.  The return value is not specified.
@end deffn

@deffn Syntax define (variable arg1 @dots{}) commands @dots{}
@deffnx Syntax define (variable arg1 @dots{} . argn) commands @dots{}
@deffnx Syntax define (variable . arg) commands @dots{}
Special form of @code{define} which is equivalent to
@example
(define variable (lambda (arg1 @dots{}) commands @dots{}
(define variable (lambda (arg1 @dots{} . argn) commands @dots{}
(define variable (lambda arg commands @dots{}
@end example
@end deffn

@deffn Syntax undefine symbol
Make the symbol @var{symbol} undefined.  After calling this special
form, any references to @var{symbol} will cause an
@code{unbound-variable} error.  The return value is not specified.
@end deffn

@deffn {Primitive procedure} defined? symbol
This is not a special form, but it fits best into this section together
with @code{define} and @code{undefine}.  @code{defined?} returns
@code{#t} if @var{symbol} is a defined variable and @code{#f} otherwise.
@end deffn

@deffn Syntax define-constant variable expression
Define @var{variable} as a variable and set its value to the value of
@var{expression}.  The return value is not specified.  The difference
between @code{define} and @code{define-constant} is that variables
created using @code{define-constant} are read-only and cannot be
modified with @code{set!}.  This enables runtime optimizations because
references to constant variables can be replaced by the variable's
value, eliminating symbol lookups.
@end deffn

@deffn Syntax if condition then [else]
Evaluates @var{condition} and then checks its return value.  If the
value is @code{#t}, @var{then} is evaluated and the result of that
evaluation is returned.  Otherwise, the behaviour depends on the
presence of the @var{else} expression.  If @var{else} is not provided,
the return value is unspecified, otherwise @var{else} is evaluated and
the result is returned.
@end deffn

@deffn Syntax cond clause1 clause2 @dots{}
Each @var{clause} is of the form
@example
(test expression1 ...)
@end example
Alternatively, a @var{clause} may be of the form
@example
(test => expression)
@end example
and the last @var{clause} may be an @i{else clause}, which has the form
@example
(else expression1 expression2 ...)
@end example
A @code{cond} expression is evaluated by evaluating the @var{test}
expressions of successive @var{clauses} in order until one of them
evaluates to a true values. The first @var{clause} whose @var{test}
evaluates to true is chosen and the @var{expressions} in the clause are
evaluated in order and the value of the last expression is returned as
the value of the @code{cond} expression. If the selected @var{clause}
has no @var{expressions}, the value of the @var{test} is returned. An
@var{else clause} is chosen and the following @var{expressions} are
evaluated if no other @var{test} evaluates to true.

If the selected @var{clause} has the @code{=>} form, the
@var{expression} following the arrow must evaluate to a procedure to
which the result of the @var{test} is applied to yield the result of the
@code{cond} expression.
@end deffn

@deffn Syntax case key clause1 clause2 @dots{}
@var{key} may be any expression. Each @var{clause} should have the form
@example
((datum1 ...) expression1 expression2 ...)
@end example
where each datum is an external representation of some object. The last @var{clause} may be of the form
@example
(else expression1 expression2 ...)
@end example

A @code{case} expression is evaluated by first evaluating the @var{key}.
The resulting value is compared against each of the @var{datums} using
the equality predicate @code{eqv?}, and if a match is found, the
@var{expression} following the matching @var{datum} is evaluated and the
result of the last @var{expression} is returned as the result of the
@code{case} expression.

Should no @var{clause} match and an @code{else} clause is present, that
clause is chosen and the @var{expressions} following the @code{else} are
evaluated in order to compute the result of the @code{case} expression.
@end deffn

@deffn Syntax do ((variable1 init1 step1) @dots{}) (test expression @dots{}) command @dots{}
@code{do} is an iteration construct. First, all @var{variables} are
bound to the values of their corresponding @var{init} values.  Then the
@var{test} expression is evaluated and if the value is false, the
@var{commands} are evaluated in order. After each iteration, the
@var{variables} are bound to the result of evaluating the corresponding
@var{step} expressions and the @var{test} is evaluated again. The loop
terminates as soon as the @var{test} evaluates to a true value. Then the
@var{expressions} after the @var{test} are evaluated in order and the
value of the last @var{expression} is returned as the value of the
@code{do} expression.
@end deffn

@deffn Syntax begin command @dots{}
@code{begin} accepts one or more expressions as its arguments. All
expressions are evaluated in the order they appear in the argument list
and the result of the last expression is returned. The result is
unspecified if no @var{command} is given.
@end deffn

@deffn Syntax let ((variable expression) @dots{}) command @dots{}
@code{let} creates a block in which all variables named in the first
argument list are redefined to the corresponding values.  The
expressions in the body are executed and afterwards all variables are
rebound to their original values. The result of the last evaluated
expression is returned. If no body expressions are given, the result is
unspecified. When using @code{let}, the @var{variables} are not visible
to @var{expressions}, because the variables are bound after all the
expressions are evaluated.
@end deffn

@deffn Syntax let variable ((variable1 expression) @dots{}) command @dots{}
The named-let construct is used to implement looping
constructs. @var{variable} is bound to a lambda expression which takes
the @var{variables} as its formal parameters and then calls the
expression with actual parameters set to the @var{expressions}. The body
of the let can than refer to @var{variable} by calling it recursively as
a function.
@end deffn

@deffn Syntax let* ((variable expression) @dots{}) command @dots{}
Works like @code{let}, but the @var{expressions} are evaluated in
left-to-right order where each @var{variable} is visible to the
expression on its right.
@end deffn

@deffn Syntax letrec ((variable expression) @dots{}) command @dots{}
Works like @code{let}, but the @var{variables} are visible to all
@var{expressions}, thus making possible mutual recursive procedures.
@end deffn

@deffn Syntax lambda (variable1 @dots{}) command @dots{}
@deffnx Syntax lambda (variable1 @dots{} . variablen) command @dots{}
@deffnx Syntax lambda variable command @dots{}
Lambda is used to define procedures. The @var{variables} are the formal
parameters to which actual parameters will be bount. When the procedure
is called, the actual parameters are bound and the @var{commands} are
evaluated in order. The three syntactic forms above differ in the way
parameters are bound.  The first lambda takes exactly as many actual
arguments as @var{variables} are given, the second takes at least as
many actual arguments as @var{arguments} before the dot are given and
binds @var{variablen} to a list of the rest of the arguments and the
third form takes any number of arguments which will then be bound to
@var{variable}.
@end deffn

@deffn Syntax and expression @dots{}
@code{and} evaluates all @var{expressions} in order, but stops
evaluation as soon as one of the @var{expressions} returns a false
value. Returns @code{#f} if any of the expressions returns @code{#f} and
returns the result of the last expression otherwise. When called without
arguments, @code{#t} is returned.
@end deffn

@deffn Syntax or expression @dots{}
@code{and} evaluates all @var{expressions} in order, but stops
evaluation as soon as one of the @var{expressions} returns a non-false
value. Returns @code{#f} if none of the expressions returns @code{#t}
and returns the result of the first expression returning a non-false
value otherwise.  When called without arguments, @code{#f} is returned.
@end deffn

@deffn Syntax delay expression
Delays the evaluation of expression. Returns a promise, which when later
forced by a call to @code{force} will evaluate @var{expression} and
return the result. Evaluation is performed in the same environment in
which the promise was created.
@end deffn

@deffn {Macro} when test body @dots{}
Evaluates all expressions in @var{body}, but only if @var{test}
evaluates to a true value.  If called without arguments, @code{#f} is
returned, if only called with a @var{test} argument, the value of the
@var{test} is returned, otherwise the value of the last expression in
@var{body} is returned.

This macro is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Macro} unless test body @dots{}
Evaluates all expressions in @var{body}, but only if @var{test}
evaluates to @code{#f}.  If called without arguments, @code{#f} is
returned, if only called with a @var{test} argument, the value of the
@var{test} is returned, otherwise the value of the last expression in
@var{body} is returned.

This macro is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Macro} false-if-exception expr
Evaluates @var{expr} and returns the result.  If an exception occurs
while evaluating @var{expr}, it is caught and @code{#f} is returned.

This macro is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Macro} while test body @dots{}
Evaluates the @var{body} expressions as long as @var{test} evaluates to
a true value.  @var{test} is always evaluated before the @var{body}
expressions.  Returns @code{#f} if no call to @code{break} occurs inside
of @var{body}, otherwise the value given to @code{break} is returned.

This macro is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Library procedure} break val
This is not a syntactic form, but is closely related to @code{while}, so
it was put in this section.  @code{break} is only defined inside of a
@code{while} body.  When called, it aborts the innermost @code{while}
loop and lets it return @var{val}.

This macro is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn

@deffn {Library procedure} continue
Like @code{break}, this is not a syntactic form, but is closely related
to @code{while}, so it was put in this section.  @code{continue} is only
defined inside of a @code{while} body.  When called, it restarts the
innermost while loop, starting with the test of the while condition.

This macro is not supported when the option @code{-n,
--no-system-init-file} is passed to the interpreter, or if the system
startup file is not found.
@end deffn



@node Sizzle vs R5RS, Glossary, Builtin Procedures, Top
@comment  node-name,  next,  previous,  up
@unnumbered Sizzle vs. R5RS

Sizzle is not a complete implementation of Scheme as defined in the
Revised 5 Report on the Algorithmic Language Scheme (R5RS), but most of
the standard procedures from that report and all data types except
complex and rational numbers are supported.  This chapter lists all
differences between Sizzle and standard Scheme.

First of all, Sizzle does only support non-hygienic macros at all, and
the high-level syntax definitions from R5RS are implemented a little bit
shaky.  @code{call-with-current-continuation} only works in upward
direction properly, general continuations can be compiled in, but are
buggy and will segfault in the current state.  Besides of that, Sizzle
is a quite useful language for embedding and higher-order functional
programming purposes.

@menu
* Standard Data Types::         Scheme's data types
* Standard Procedures::         Standard procedures and special forms
@end menu



@node Standard Data Types, Standard Procedures, Sizzle vs R5RS, Sizzle vs R5RS
@comment  node-name,  next,  previous,  up
@section Standard Data Types

@noindent
The following data types are implementd in Sizzle, including most standard procedures for manipulating objects of these types.

@table @var
@item Whole numbers
@item Real numbers
@item Lists
@item Vectors
@item Strings
@item Characters
@item Boolean values
@end table
@noindent
The numerical tower is not fully implemented, not available are the number types:
@table @var
@item Rational numbers
@item Complex numbers
@end table



@node Standard Procedures,  , Standard Data Types, Sizzle vs R5RS
@comment  node-name,  next,  previous,  up
@section Standard Procedures

These are the standard procedures defined in Sizzle.

@menu
* Supported Syntax::            Syntactic forms implemented in Sizzle.
* Supported Procedures::        Procedures implemented in Sizzle.
* Partly implemented::          Procedure only partly supported.
* Not supported::               All standard procedures not supported.
@end menu



@node Supported Syntax, Supported Procedures, Standard Procedures, Standard Procedures
@comment  node-name,  next,  previous,  up
@subsection Supported Syntax

quote, quasiquote, unquote, unquote-splicing, lambda, if, cond, case,
set!, and, or, do, let, let*, letrec, begin, define



@node Supported Procedures, Partly implemented, Supported Syntax, Standard Procedures
@comment  node-name,  next,  previous,  up
@subsection Supported Procedures

eqv?, eq?, equal?, number?, complex?, real?, rational?, integer?,
exact?, inexact?, zero?, positive?, negative?, odd?, even?, max, min, +,
*, -, /, abs, quotient, remainder, modulo, floor, ceiling, truncate,
round, exp, log, sin, cos, tan, asin, acos, atan, atan, sqrt, expt,
exact->inexact, inexact->exact, number->string, number->string,
string->number, string->number, gcd, lcm, not, boolean?, pair?, cons,
car, cdr, set-car!, set-cdr!, caar, cadr, @dots{}, cdddar, cddddr,
null?, list?, list, length, append, reverse, list-tail, list-ref, memq,
memv, member, assq, assv, assoc, symbol?, symbol->string,
string->symbol, char?, char=?, char<?, char>?, char<=?, char>=?,
char-ci=?, char-ci<?, char-ci>?, char-ci<=?, char-ci>=?,
char-alphabetic?, char-numeric?, char-whitespace?, char-upper-case?,
char-lower-case?, char->integer, integer->char, char-upcase char,
char-downcase, string?, make-string, make-string, string, string-length,
string-ref, string-set!, string=?, string<?, string>?, string<=?,
string>=?, string-ci=?, string-ci<?, string-ci>?, string-ci<=?,
string-ci>=?, substring, string-append, string->list, list->string,
string-copy, string->fill!, vector?, make-vector, make-vector, vector,
vector-length, vector-ref, vector-set!, vector->list, list->vector,
vector-fill!, procedure?, apply, map, for-each, eval,
interaction-environment, call-with-input-file, call-with-output-file,
with-input-from-file, with-output-to-file, input-port?, output-port?,
current-input-port, current-output-port, open-input-file,
open-output-file, close-input-port, close-output-port, read, read-char,
peek-char, write-char, eof-object?, write, display, newline, delay,
force, values, call-with-values, dynamic-wind, transcript-on,
transcript-off, null-environment, scheme-report-environment,
char-ready?



@node Partly implemented, Not supported, Supported Procedures, Standard Procedures
@comment  node-name,  next,  previous,  up
@subsection Partly implemented

@table @var
@item load
Implemented in the startup file @file{init.scm}, but Sizzle has a
builtin primitive procedure @code{primitive-load}, which works like
@code{load} as defined in R5RS.  The Scheme procedure @code{load} in
Sizzle searches all directories listed in the variable
@code{%load-path} as well as the current directory if the given
filename is not absolute.
@item real-part imag-part magnitude angle
These work for integers and reals only, because complex numbers are not
supported.
@item denominator numerator
These work for integers only, because rational numbers are not
supported.
@item call-with-current-continuation
Only for escape procedures.
@end table



@node Not supported,  , Partly implemented, Standard Procedures
@comment  node-name,  next,  previous,  up
@subsection Not supported

let-syntax letrec-syntax syntax-rules define-syntax, rationalize,
make-rectangular, make-polar



@node Glossary, Index, Sizzle vs R5RS, Top
@comment  node-name,  next,  previous,  up
@unnumbered Glossary

@table @var
@item application
When a function gets called with actual arguments, we say that the
function is applied to the arguments, or that it is an application of
the function to the arguments.
@item boolean
Data type. Boolean values can be either @code{#t} (true) or @code{#f}
(false).
@item box
Data type.  Can store another Scheme object and can be used to implement
call--by--reference procedures.
@item catch
Exceptions can be handled by catching them using the procedure
@code{catch}.
@item character
Data type. Characters are used to construct strings and are written like
this: @code{#\t}.
@item cons cell
Heap cell with one arbitrary value in both car and cdr.
@item dotted pair
A dotted pair is a pair of values, stored in the car and cdr fields of a
cons cell.  The read syntax for dotted pairs looks like this: @code{(a
. b)}.
@item environment
An environment is a mapping from symbols to values. A symbol that is
evaluated in a particular environment has its value retrieved from the
environment.
@item error
An error is signalled when an evaluation cannot be performed correctly.
@item exception
An excpeption is thrown when an evaluation cannot be performed
correctly.  The difference between errors and exceptions is that
exceptions can be handled using the @code{catch} form.
@item fixnum
An integer value which can be stored in a tagged pointer. 29-bit
two-complement value.
@item heap
Memory area where all non-immediate values are allocated.
@item heap cell
Cell on the heap of 8 bytes size which holds either two values (cons
cell) or a type tag and additional data (tagged cell).
@item integer
Data type. Numeric type which can hold exact integer values.
@item list
Data type. A list is made out of chained cons cells.
@item long int
Integer that does not fix into a fixnum.  Value range is the same as a C
int variable.
@item multiple values
Scheme supports returning multiple values from procedures.  Multiple
values are produced using the syntactic form @var{values}.
@item pointer
Data type.  Used to wrap machine pointers.
@item port
Object from which data can be read or to which data can be written. File
ports or string ports for example.
@item real number
A number with (possibly) infinite decimal places like pi or e.
@item regexp
Short for regular expression.
@item string
Data type. A string is a sequence of characters.
@item symbol
Data type. Symbols are values which can have a value attached.
@item syntactic form
Element of the syntax which looks like a function call but acts
differently.  The @code{if} or @code{lambda} forms are examples of
syntactic forms.
@item tagged cell
16 byte heap cell with a type tag in its first word and a three data
pointers to additional data in the other words.
@item thunk
A thunk is a procedure without arguments.
@item vector
Data type. Used to hold a fixed number of other values with constant
access time.
@end table



@node Index,  , Glossary, Top
@comment    node-name,         next,       previous, up
@unnumbered Index
     
@printindex cp

@contents

@bye
