Sizzle

Reference Manual

Version 0.0.30

Martin Grabmueller


Table of Contents


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.

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.

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.

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.

Starting Sizzle

To start Sizzle, simply type `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 `^D' at the prompt or entering the expression `(exit)'.

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

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

The command line option -s, --script=file has to be used whenever a Scheme script is to be executed by Sizzle. The 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 section Sizzle Scripts.

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

Note that when using -s or -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 command-line, please see section System interface functions.

The pseudo--option -- 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 (-). This can be used when passing options to a Sizzle script.

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

-e, --eval=function is intended to be used with -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 -s, the file will simply be loaded, but the main function will normally not get called. This is exactly what -e is for. Simply pass the name of the main function to -e and this function will then be applied to the remaining command line arguments after the script file has been loaded.

-h, --help will print out a short helping message and then quit.

-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 -q, --no-init-file if you want to inhibit automatic loading of your user's init file `~/.sizzle'.

Similarly the option -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 -d, --debug, Sizzle will print some debugging messages while running. Each occurence of -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.

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.

zzz: 1
1
zzz: "Hello World"
"Hello World"
zzz: #\H
#\H

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

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)
zzz: (1 2)
exception: misc-error: not a procedure: 1
zzz: '(1 2)
(1 2)

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 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 +, which adds all its arguments.

zzz: (+ 1 2)
3
zzz: (+ 1 2 -4)
-4

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 $$, 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.

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

Command Line Editing

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

When available, Sizzle uses the `readline' library to provide command line editing to the command line interpreter.

The `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 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 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 `readline' can be written to the 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 %write-history-file% to #t to enable command line history saving. The best place to do so is in the user initialization file `.sizzle' in the user's home directory.

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 load procedure.

The Sizzle program runs in non-interactive mode if you invoke it with the `-s' option, like `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 `chmod' program:

#! /usr/local/bin/sizzle -s
!#

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.

#! /bin/sh
exec sizzle -s $0
!#

Scheme scripts can examine the arguments they were given by calling the procedure 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 #! notation for executing the interpreter) the name of the script.

Startup Sequence

On startup, the 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. `init.scm' is stored in the directory `$prefix/share/sizzle/$version/', where $prefix is set during configuration time (defaults to `/usr/local') and $version is the version of your installed Sizzle package.

In addition, the system init file loads the 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 -q, --no-init-file and -n, --no-system-init-file. The former inhibits the loading of the user's initialization file `~/.sizzle', whereas the latter suppresses loading of the system-wide initialization file.

Environment Variables

When Sizzle starts up, it examines the contents of the environment variable 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 %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 load or primitive-load-path, or modules which are included with use-modules.

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 http://www.pintus.de/mgrabmue/sizzle/sizzle.html. Just follow the Download link and download an archive like `sizzle-0.0.30.tar.gz'. Replace the version number with the newest available version. You may also want to download the sizzleopt package, which includes some useful bindings, such as `readline' support for the interpreter.

Unpack the distribution tarball to a directory of your choice:

$ cd src
$ tar xzvf sizzle-0.0.30.tar.gz
sizzle-0.0.30/
sizzle-0.0.30/Makefile.in
...

Change to the newly created directory.

$ cd sizzle-0.0.30

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

Now you have configure the package. Most of the times, this just requires you to type

./configure

but you may want to change the configuration to suit your needs. Invoke `configure' with the --help option to get a list of the supported options.

Currently, the following configuration options besides the standard options are supported:

--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.
--enable-debug
Switch on debugging code. This is on by default.
--enable-posix
Compile in Posix functions such as getpid, fork etc. This is on by default.
--enable-regexp
Compile in support for Posix regular expressions. This is on by default.
--enable-maximum-functionality
This option controls inclusion of some code which may not be needed for all users, such as networking support.
--enable-dl
Compile in dynamic linking code. This will enable the library to load extension modules without recompilation. This is on by default.
--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.
--with-mingw=DIR
When compiling for Windoze, you can give the location of your MingW32 installation here.
--enable-shared
Enable the compilation of chared libraries. On by default.
--enable-static
Enable the compilation of static libraries. On by default.
--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.

Every --enable option has a --disable pendent to switch off a particular feature.

After a while, the configuration is done and you can compile the package.

$ make

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 `/usr/local'.

$ su
Password:
# make install
# exit
$

When everything worked well, you can now use the Sizzle interpreter.

$ sizzle
zzz: (+ 1 2)
3
zzz:

Programming Scheme

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

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.

zzz: (+ 1 2)
3
zzz: ((lambda (x) x) 1)
1

All arguments in Scheme are passed by value, e.g evaluated before the procedure is called. Special forms like if, 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 define and can be modified lateron by using set!, which is another special form.

zzz: (define a 1)
zzz: a
1
zzz: (set! a 2)
zzz: a
2

Functions are either defined by defining a variable with the value of a lambda expression or using a special form of define, which is intended for defining procedures more easily.

zzz: (define identity (lambda (x) x))
zzz: (identity 2)
2
zzz: (exit)
$ sizzle
zzz: (define (identity x) x)
zzz: (identity 3)
3

When you define a variable more than once in an environment, the former definition will be silently overwritten.

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.

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.

Numbers

The Scheme standard defines the so-called 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:

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

Furthermore, Scheme makes a difference between exact and inexact numbers. Exact numbers are always precise whereas 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.

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

Integers are exact numbers with the same range as the C long data type.

Examples of integer constants:

42
-23
#xdead
#o755
#b100001010
#d42

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

3.1459
-10.1e2
#i1.0
#e1.0

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

Booleans

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

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

Characters

Characters are denotated in the following form: first, a hash mark (#), then a backslash and then the literal character. Examples:

#\j
The character `j'
#\
The space character

Scheme provides another notation for non-printable characters. A space character can also be written like this #\space and a newline like #\newline. Sizzle understands three additional symbolic names for characters. This table shows all of them:

#\space
The space character
#\newline
The newline character
#\return
The carriage return character
#\tab
The tab character.
#\bell
The bell character.

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 " and the backslash \ 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:

\n
Newline
\r
Carriage return
\t
Tab character
\v
Vertical tab
\b
Backspace
\a
Bell character

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 string-set! or string-fill!. Strings returned by functions like string-copy or string are mutable and can be used with such strings.

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 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 `(', `)', whitespace, `;' and `"'. 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:

Hello
i-am-a-symbol
strange\ symbol

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.

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 (:) or the sequence hashmark--colon (#:). When comparing, only the keyword name is significant, the prefix is ignored.

zzz: #:keyword
#:keyword
zzz: :keyword
#:keyword
zzz: keyword
error: unbound variable: keyword

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 #:--notation, regardless how they were entered.

Cons Cells

Cons cells are cells which can hold two other values. The first of the value is called the `car' of the cell and the second is called `cdr' (for historic reasons). In source files and on the read-eval-print prompt you can create cons cell by using the dotted pair syntax.

'(foo . bar)
'(1 . 2)

Another way to create cons cells is using the constructor function cons:

zzz: (cons 1 2)
(1 . 2)

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

(1 . (2 . (3 . '())))

by simply writing

(1 2 3)

Both result in the same value.

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.

#(1 2 3 4 5 6 7)
#("Hello" #\  "World" \#!)
#(#(1 2) #())

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 vector-set! or vector-fill. Vectors returned by functions like make-vector or vector are mutable and can be used with such strings.

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

s8
signed 8-bit values
u8
unsigned 8-bit values
s16
signed 16-bit values
u16
unsigned 16-bit values
s32
signed 32-bit values
u32
unsigned 32-bit values
s64
signed 64-bit values
u64
unsigned 64-bit values
f32
32-bit floating point values
f64
64-bit floating point values

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:

#u8(1 2 3 4 5 6 7)
#s16(-42 23 2 0)
#f32(1.2 3.14159265)

Similar to normal vectors, literally denoted homogenous vectors are read-only and can not be modified using primitive procedures like u8vector-set!. Use procedures like make-f64vector to create mutable vectors.

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 association lists, but they are significantly faster when they grow large.

In Sizzle, hash tables can be written literally with a #{ prefix, followed by key/value pairs separated by the arrow symbol (=>), like this, terminated by a closing brace (}):

zzz: #{Joe => "cool" Jim => "lame"}
#{Jim => "lame" Joe => "cool"}

This is also the print syntax for hash tables.

Another possibility is to use the procedure 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.

zzz: (make-hash '(Joe . "cool") '(Jim . "lame"))
#{Jim => "lame" Joe => "cool"}

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 make-hash:

zzz: (make-hash '(Joe . "cool") '(Jim . "lame"))
#{Jim => "lame" Joe => "cool"}
zzz: (make-hash 32 '(Joe . "cool") '(Jim . "lame"))
#{Joe => "cool" Jim => "lame"}

The best choice for the size argument is a prime number not too near to a power of 2 (so says Knuth).

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:

zzz: set!
#<macro set!>
zzz: append
#<primitive-procedure append>

Closures print as a pair of the lambda expression they stand for and the address of the environment the expression is closed over.

zzz: (define (f n) n)
zzz: f
#<closure #<procedure f (n)> 0x401af072>

Regular Expressions

Regular expressions are created using the primitive procedure make-regexp. The resulting regular expression object can then be used in calls to regexp-exec in order to match the regular expression against strings. The format of the regular expression passed to make-regexp is the same as for the Posix regular expressions. For more information, type

man regex

Regular expressions are not part of any Scheme standard, but the procedures implemented in Sizzle are compatible to those used by Guile.

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))

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.

Multiple Values

In Scheme, it is possible to return more than one value from a procedure. This is done by using the primitive procedure 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 call-with-values. The following examples may (hopefully) clear up the whole mess.

zzz: (values 1 2 3)
1
2
3
zzz: (call-with-values (lambda () (values 1 2)) (lambda (x y) (+ x y)))
3

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

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 Special Values in this manual. Examples of these special values are the end-of-file object which indicates an end-of-file condition, or the unspecified object used inside of the interpreter.

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 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?

Ports

All input and output in Scheme is done using 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 open-input-file, or implicitely when using with-output-to-string and friends. They have a print syntax, but no read syntax.

zzz: (current-input-port)  
#<rlport:open=1:read=1:write=0>
zzz: (current-output-port) 
#<fdport:open=1:read=0:write=1:fd=1>

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 `sizzleopt' package and used the readline module with (use-modules (readline readlie)).

At the moment, Sizzle supports so-called fdports, which use an underlying file descriptor, fports which use an underlying `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 `readline' library. The latter provide fancy command line editing.

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 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 exception tag, which may be any atom. Exceptions can be raised from the Scheme code by calling the procedure throw. Using the exception tag for a particular exception or the catch-all exception tag #t, the user can catch exceptions with the procedure 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 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.

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.

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 Library variables are defined in the startup file `init.scm' and thus are only present if the embedding application has loaded that file on startup.

Variable: %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 load library procedure from the system init file uses this variable.

Variable: %sizzle-version%
This is a string containing version information of the running interpreter. It has the format major.minor.patchlevel, and looks like this: 0.0.30.

Library variable: %sizzle-major-version%
Library variable: %sizzle-minor-version%
Library variable: %sizzle-patchlevel%
These variables hold the components of %sizzle-version%, split up at the dots and converted to integers.

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

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

(Only available if the optional module (readline readline) was used).

Variable: gc-message
This is a boolean variable. If set to #t, a message will be printed whenever the garbage collection is invoked or the cell heap grows.

Variable: %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.

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

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

Variable: %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 (backtrace) is much less readable, so this is false by default.

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

Variable: %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 #t, the interpreter will consume a lot of memory if your program is heavily recursive.

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

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

Variable: %eval-time-taken%
This integer variable holds the time in ticks which the last top-level evaluation took.

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 set!, because the first argument (a symbol) needs not be to be quoted like it would have to if set! was a function. Also it is necessary for forms which evaluate their arguments only when a certain condition holds. if, for example, only evaluates its third argument if the first evaluates to the value #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.

Equality tests

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

Primitive procedure: eq? obj1 obj2
Returns #t if obj1 and 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, (eq? 1 1) can return #t, but not necessarily. Use eqv? or = to test numbers for equality. Strings can only compared using the predicate equal? or one of the string comparison predicates.

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

Primitive procedure: equal? obj1 obj2
Returns #t if the structure of obj1 and obj2 is the same. You can use 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 string=?.

Numerical operations

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

Primitive procedure: number? obj
Returns #t if obj is a number, #f otherwise.

Primitive procedure: complex? obj
Returns #t if obj is a complex number, #f otherwise.

Primitive procedure: real? obj
Returns #t if obj is a inexact number in floating point representation, #f otherwise.

Primitive procedure: rational? obj
Returns #t if obj is a rational number, #f otherwise.

Primitive procedure: integer? obj
Returns #t if obj is an exact integer number, #f otherwise.

Primitive procedure: long? obj
Returns #t if obj is an exact long integer number (a non-immediate integer, not a bignum), #f otherwise.

Primitive procedure: exact? obj
Returns #t if obj is an exact number, #f otherwise.

Primitive procedure: inexact? obj
Returns #t if obj is an inexact number, #f otherwise.

Primitive procedure: = z1 z2 z3 ...
Returns #t if all arguments are numerically equal, #f otherwise.

Primitive procedure: != z1 z2 z3 ...
Returns #t if all arguments after the first are not numerically equal to the first argument, #f otherwise.

Primitive procedure: < z1 z2 z3 ...
Returns #t if all arguments are strictly ordered in increasing order.

Primitive procedure: <= z1 z2 z3 ...
Returns #t if all arguments are ordered in increasing order.

Primitive procedure: > z1 z2 z3 ...
Returns #t if all arguments are strictly ordered in decreasing order.

Primitive procedure: >= z1 z2 z3 ...
Returns #t if all arguments are ordered in decreasing order.

Primitive procedure: zero? obj
Returns #t if obj is equal to zero, #f otherwise.

Primitive procedure: positive? obj
Returns #t if obj is greater than zero, #f otherwise.

Primitive procedure: negative? obj
Returns #t if obj is less than zero, #f otherwise.

Primitive procedure: odd? obj
Returns #t if obj is an odd number, #f otherwise.

Primitive procedure: even? obj
Returns #t if obj is an even number, #f otherwise.

Primitive procedure: max x1 x2 ...
Returns the maximum of its arguments.

Primitive procedure: min x1 x2 ...
Returns the minimum of its arguments.

Primitive procedure: + z1 ...
Adds all numbers in the argument list and returns the sum. If called without parameters, 0 is returned.

Primitive procedure: * z1 ...
Multiplies all argument values and returns the product. Returns 1 if called without parameters.

Primitive procedure: - z1 ...
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.

Primitive procedure: / z1 ...
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.

Primitive procedure: abs x
Returns the absolute value of its argument.

Primitive procedure: magnitude z
Returns the magnitude for x. This is the same as abs, since Sizzle does not support complex numbers.

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

Primitive procedure: real-part z
Returns the real part of the number z. In Sizzle, this returns z itself, because complex numbers are not supported.

Primitive procedure: imag-part z
Returns the imaginary part of the number z. The Sizzle implementation simply returns 0, because complex numbers are not supported.

Primitive procedure: numerator q
Returns the numerator of its argument q. Currently, q itself is returned because rational numbers are not supported.

Primitive procedure: denominator q
Returns the denominator of its argument q. Currently, 1 is returned because rational numbers are not supported.

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.

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.

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 remainder as far as negative operands ar concerned.

Primitive procedure: floor x
Returns the largest integer not larger than x.

Primitive procedure: ceiling x
Returns the smallest integer not smaller than x.

Primitive procedure: truncate x
Returns the closest integer to x whose absolute value is not larger than the absolute value of x.

Primitive procedure: round x
Returns the closest integer to x rounding it to even when x is halfway between two integers.

Primitive procedure: exp z
Implements the exponential function.

Primitive procedure: log z
Returns the natural logarithm of z.

Primitive procedure: sin z
Returns the sine of z.

Primitive procedure: cos z
Returns the cosine of z.

Primitive procedure: tan z
Returns the tangent of z.

Primitive procedure: asin z
Returns the arcsine of z.

Primitive procedure: acos z
Returns the arccosine of z.

Primitive procedure: atan z
Returns the arctangent of z.

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

Primitive procedure: sqrt x
Returns the square root of its argument. Since complex numbers are not supported, x must be positive.

Primitive procedure: expt z1 z2
Returns z1 raised to the power of z2.

Primitive procedure: exact->inexact z
Returns z, converted to an inexact value.

Primitive procedure: inexact->exact z
Returns z, converted to an exact value. An error signalled if a conversion is not possible without losing precision.

Primitive procedure: number->string z
Primitive procedure: number->string z radix
Converts its argument to a string. The radix radix is used if given.

Primitive procedure: string->number string
Primitive procedure: string->number string radix
Converts string to a number. When given, radix is used as the default radix which can be overridden with an explicit radix prefix in string. #f is returned if string is not properly formatted.

Primitive procedure: lognot n
Returns the bitwise negated value of the argument.

Primitive procedure: logand n ...
Performs a bitwise and operation on all arguments and returns the result. Returns a value with all bits set if called without arguments.

Primitive procedure: logior n ...
Performs a bitwise or operation on all arguments and returns the result. Returns a value with no bits set if called without arguments.

Primitive procedure: logxor n ...
Performs a bitwise exclusive or operation on all arguments and returns the result. Returns a value with no bits set if called without arguments.

Primitive procedure: lsh n1 n2
Shifts the integer n1 left by n2 bits if n2 is not less than zero, or shifts n2 logically right by -n2 bits if n2 is less than zero.

Primitive procedure: ash n1 n2
Shifts the integer n1 left by n2 bits if n2 is not less than zero, or shifts n2 arithmetically right by -n2 bits if n2 is less than zero.

Primitive procedure: gcd [n1 [n2]]
Returns the greatest common divisor of its arguments. Without arguments, 0 is returned, if only n1 is given, n1 is returned.

Primitive procedure: lcm [n1 [n2]]
Returns the least common multiple of its arguments. Without arguments, 1 is returned, if only n1 is given, n1 is returned.

Primitive procedure: signum x
Return -1 if x is less than zero, 0 if x is equal to zero and 1 if z is greater than zero.

Boolean operations

The boolean operations documented in this section are always available.

Primitive procedure: boolean? obj
Returns #t if obj is a boolean value, #f otherwise.

Primitive procedure: not obj
Returns #t if obj is false, #f otherwise.

Primitive procedure: boolean->integer b
Return 0 if b is #f, 1 otherwise.

Primitive procedure: integer->boolean i
Return #f if i is 0, #t otherwise.

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 (core list-lib) prior to usage.

List constructors

Primitive procedure: cons obj1 obj2
Return a cons cell with a car of obj1 and a cdr of obj2.

Primitive procedure: list obj ...
Returns a list whose elements are all arguments of the call to list. With no arguments, the empty list () is returned.

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

This procedure must be imported by using the module (core list-lib).

Primitive procedure: cons* elt1 elt2 ...
Like list, but the last argument provides the tail of the constructed list.
(cons* 1 2 3 4) => (1 2 3 . 4)

This procedure must be imported by using the module (core list-lib).

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

This procedure must be imported by using the module (core list-lib).

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

This procedure must be imported by using the module (core list-lib).

Primitive procedure: list-copy flist
Copies the spine of the argument list.

This procedure must be imported by using the module (core list-lib).

Primitive procedure: circular-list elt1 elt2 ...
Constructs a circular list of the elements.

This procedure must be imported by using the module (core list-lib).

Primitive procedure: iota count [start step]
Returns a list containing the elements
(start start+step ... start+(count-1)*step)

The start and 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 (core list-lib).

List predicates

Primitive procedure: list? obj
Return #t if obj is a list, #f otherwise. Only finite lists pass this test, infinite lists return #f for this predicate.

Primitive procedure: proper-list? x
Return #t if x is a proper list -- a finite, nil-terminated list. Return #f for any other object.

This procedure must be imported by using the module (core list-lib).

Primitive procedure: circular-list? x
Return #t if x is a circular list.

This procedure must be imported by using the module (core list-lib).

Primitive procedure: dotted-list? x
Return #t if 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 (core list-lib).

Primitive procedure: pair? obj
Returns #t if obj is a cons cell, #f otherwise.

Primitive procedure: null? obj
Returns #t if obj is the empty list, #f otherwise.

Primitive procedure: null-list? list
list is a proper or circular list. Returns #t if the argument is the empty list (), and #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 (core list-lib).

Primitive procedure: not-pair? x
Return #t if 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 (core list-lib).

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

It is an error to apply list= to anything except proper lists.

This procedure must be imported by using the module (core list-lib).

List selectors

Primitive procedure: car pair
pair must be a cons cell. Return the car of the cons cell pair.

Primitive procedure: cdr pair
pair must be a cons cell. Return the cdr of the cons cell pair.

Primitive procedure: caar pair
Primitive procedure: cadr pair
Primitive procedure: ...
Primitive procedure: cdddar pair
Primitive procedure: cddddr pair
These functions are compositions of car and cdr, where for example caddr could be defined by
(define caddr (lambda (x) (car (cdr (cdr x)))))

There are twenty-eight of these functions defined.

Primitive procedure: list-ref list k
Returns the kth element of list. An error is signalled if list has fewer than k elements.

Primitive procedure: list-tail list k
Returns the sublist of list obtained by omitting the first k elements. An error is signalled if list has fewer than k elements.

Primitive procedure: first pair
Primitive procedure: second pair
Primitive procedure: third pair
Primitive procedure: fourth pair
Primitive procedure: fifth pair
Primitive procedure: sixth pair
Primitive procedure: seventh pair
Primitive procedure: eighth pair
Primitive procedure: ninth pair
Primitive procedure: tenth pair
Synonyms for car, cadr, caddr, ...

These procedures must be imported by using the module (core list-lib).

Primitive procedure: car+cdr pair
The fundamental pair deconstructor. Return two values, the first being the car, the second being the cdr of the pair.

This procedure must be imported by using the module (core list-lib).

Primitive procedure: take list k
Return a list containing the first k elements of list. Return list if k is larger then the length of list.

This procedure must be imported by using the module (core list-lib).

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

This procedure must be imported by using the module (core list-lib).

Primitive procedure: take-right flist i
Primitive procedure: drop-right flist i
take-right returns the last i elements of flist.

drop-right returns all but the last i elements of flist.

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

These procedures must be imported by using the module (core list-lib).

Primitive procedure: take! x i
Primitive procedure: drop-right! x i
take! and drop-right! are destructive variants of take and drop-right. If x is circular, take! may return a shorter-than-expected list.

These procedures must be imported by using the module (core list-lib).

Primitive procedure: split-at x i
Primitive procedure: split-at! x i
split-at splits the list x at index i, returning two values: a list of the first i elements and the remaining tail.

split-at! is the destructive variant of split-at.

These procedures must be imported by using the module (core list-lib).

Primitive procedure: last pair
Primitive procedure: last-pair pair
last returns the last element of the non-empty, finite list pair. last-pair returns the last pair of the non-empty, finite list pair.

Miscellaneous list procedures

Primitive procedure: length list
Primitive procedure: length+ clist
Returns the length of list. It is an error to pass anything but a proper, nil-terminated list to length.

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

length+ must be imported by using the module (core list-lib), whereas length is always available.

Primitive procedure: append list ...
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.

Primitive procedure: append! list ...
Destructive version of append. The result of the operation is the same as for append, but as a side effect, the parameter lists are modified when performing the append operation.

Library procedure: concatenate list-of-lists
Library procedure: concatenate! list-of-lists
These functions append the elements of their arguments together. concatenate! may alter the cons cells of the passed lists.

This procedure must be imported by using the module (core list-lib).

Primitive procedure: reverse list
Returns a newly allocated list with all elements of list in reversed order.

Primitive procedure: reverse! list
Destructive version of reverse. The result of the operation is the same as for reverse, but as a side effect, the parameter list is modified when performing the reverse operation.

Library procedure: append-reverse rev-head tail
Library procedure: append-reverse! rev-head tail
append-reverse returns (append (reverse rev-head) tail). It is provided because it is a common operation.

append-reverse! is just the destructive variant.

These procedures must be imported by using the module (core list-lib).

Library procedure: zip clist1 clist2 ...
If zip is passed n lists, it returns a list as long as the shortest of these lists, each element of which is an 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 (core list-lib).

Library procedure: unzip1 list
Library procedure: unzip2 list
Library procedure: unzip3 list
Library procedure: unzip4 list
Library procedure: unzip5 list
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 (map car lists).

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, unzip3 does the same for the first three elements of the lists, and so forth.

(unzip2 '((one 1) (two 2) (three 3))) =>
  (1 2 3)
  (one two three)

These procedures must be imported by using the module (core list-lib).

Primitive procedure: count pred clist1 clist2 ...
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 lists, and a count is tallied of the number of elements that return a true value. This count is returned. count is iterative in that it is guarateed to apply pred to the 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 (core list-lib).

Fold, unfold and map

Primitive procedure: fold kons knil clist1 clist2 ...
The fundamental list iterator.

First, consider the single list-parameter case if clist1=(e1 e2 ... en) then this procedure returns

(kons en ... (kons e1 (kons e1 knil)))

That is, it obeys the (tail) recursion

(fold kons knil lis) = (fold kons (kons (car lis) knil) (cdr lis))
(fold kons knil '()) = knil

If n argument lists are provided, then the kons procedure must take n+1 parameters: one element from each list, and the "seed" or fold state, which is initially 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 (core list-lib).

Primitive procedure: pair-fold kons knil clist1 clist2 ...
Analogous to fold, but kons is applied to successive sublists of the lists, rather than successive elements -- that is, kons is applied to the pairs making up the lists.

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

This procedure must be imported by using the module (core list-lib).

Library procedure: reduce f ridentity list
reduce is a variant of fold.

ridentity should be a "right identity" of the procedure f -- that is, for any value x acceptable to f,

(f x ridentity) = x

Note that ridentity is used only in the empty-list case. You typically use reduce when applying f is expensive and you'd like to avoid the extra application incurred when fol applies f to the head of the list and the identity value, redundantly producing the same value passed to f.

This procedure must be imported by using the module (core list-lib).

Library procedure: reduce-right f ridentity list
reduce-right is the fold-right variant of reduce.

This procedure must be imported by using the module (core list-lib).

Library procedure: unfold p f g seed [tail-gen]
unfold is defined as follows:
(unfold p f g seed) =
  (if (p seed) (tail-gen seed)
               (cons (f seed)
                     (unfold p f g (g seed)))))
p
Determines when to stop unfolding.
f
Maps each seed value to the corresponding list element.
g
Maps each seed value to the next seed value.
seed
The "state" value for the unfold.
tail-gen
Creates the tail of the list; defaults to (lambda (x) '()).

In other words, we use g to generate a sequence of seed values seed, g(seed), g^2(seed), g^3(seed), ...

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

This procedure must be imported by using the module (core list-lib).

Library procedure: unfold-right p f g seed [tail]
unfold-right constructs a list with the following loop:
(let lp ((seed seed) (lis tail))
   (if (p seed) lis
                (lp (g seed) (cons (f seed) lis))))
p
Determines when to stop unfolding.
f
Maps each seed value to the corresponding list element.
g
Maps each seed value to the next seed value.
seed
The "state" value for the unfold.
tail
List terminator, defaults to '().

This procedure must be imported by using the module (core list-lib).

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

Primitive procedure: for-each proc list1 list2 ...
proc is applied to the elements of the lists as with map, but in order. for-each is for its side effects of proc, therefore the return value is unspecified.

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

These procedures must be imported by using the module (core list-lib).

Library procedure: map! f list clist1 ...
Destructive variant of map. map! may be alter the cons cells of list1 to construct the result list.

This procedure must be imported by using the module (core list-lib).

Library procedure: map-in-order f clist1 clist2 ...
A variant of the map procedure that guarantees to apply 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 (core list-lib).

Library procedure: pair-for-each f clist1 clist2 ...
Like for-each, but f is applied to successive sublists of the argument lists. That is, 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 (core list-lib).

Library procedure: filter-map f clist1 clist2 ...
Like map, but only true values are saved. The dynamic order in which the various applications of 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 (core list-lib).

Filtering and partitioning

Library procedure: filter pred list
Library procedure: filter! pred list
Return all the elements of list that satisfy predicate 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 pred are made is not specified.

filter! is the destructive variant of filter.

These procedures must be imported by using the module (core list-lib).

Library procedure: partition pred list
Library procedure: partition! pred list
Partitions the elements of list with predicate 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 pred are made is not specified. One of the returned lists may share a common tail with the argument list.

partition! is the destructive variant of partition.

These procedures must be imported by using the module (core list-lib).

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

remove! is the destructive variant of remove.

These procedures must be imported by using the module (core list-lib).

List searching

Library procedure: find pred clist
Return the first element in clist that satisfies predicate pred, #f if no element does.

This procedure must be imported by using the module (core list-lib).

Library procedure: find-tail pred clist
Return the first pair of clist whose car satisfies predicate pred, #f if no element does.

This procedure must be imported by using the module (core list-lib).

Library procedure: take-while pred clist
Library procedure: take-while! pred clist
Return the longest initial prefix of clist whose elements all satisfy the predicate pred.

take-while! is the destructive variant of take-while.

These procedures must be imported by using the module (core list-lib).

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

This procedure must be imported by using the module (core list-lib).

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

span! and break! are the destructive variants.

This procedure must be imported by using the module (core list-lib).

Library procedure: any pred clist1 clist2 ...
Applies the predicated accross the lists, returning true if the predicate returns true on any application. If there are n arguments clist1 ... clistn, then pred must be a procedure taking 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, any returns #f.

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

This procedure must be imported by using the module (core list-lib).

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

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

This procedure must be imported by using the module (core list-lib).

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

This procedure must be imported by using the module (core list-lib).

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

member is extended from R5RS to allow the client to pass an optional equality procedure = used to compare keys.

Association lists

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

assoc is extended from R5RS to allow the client to pass in an optional equality procedure = to compare keys.

Primitive procedure: alist-cons key datum alist
Cons a new alist entry mapping from key to datum onto alist.

This procedure must be imported by using the module (core list-lib).

Primitive procedure: alist-copy alist
Make a fresh copy of 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 (core list-lib).

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

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

This procedure must be imported by using the module (core list-lib).

Deletion

Primitive procedure: delete x list [=]
Primitive procedure: delete! x list [=]
delete uses the comparison procedure =, which defaults to equal?, to find all elements of list that are equal to x, and deletes them from list. The dymanic order in which the various applications of = 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.

delete! is the destructive variant of 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 (core list-lib).

Primitive procedure: delete-duplicates list [=]
Primitive procedure: delete-duplicates! list [=]
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.

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

These procedures must be imported by using the module (core list-lib).

Primitive side-effects

Primitive procedure: set-car! pair obj
pair must be a cons cell. Sets the car of pair to obj. The return value is not specified.

Primitive procedure: set-cdr! pair obj
pair must be a cons cell. Sets the cdr of pair to obj. The return value is not specified.

Set operations on lists

Library procedure: lset<= = list1 ...
Returns true iff every list_i is a subset of list_i+1, using = for the element-equality procedure.

This procedure must be imported by using the module (core list-lib).

Library procedure: lset= = list1 ...
Returns true iff every list_i is a set-equal of list_i+1, using = for the element-equality procedure.

This procedure must be imported by using the module (core list-lib).

Library procedure: lset-adjoin = list elt1 ...
Adds the elts not already in the list parameter to the result list. The result shares a common tail with the list parameter. The = parameter is an equality procedure used to determine of an elt_i is already a member of 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 (core list-lib).

Library procedure: lset-union = list1 ...
Returns the union of the lists, using = for the element-equality procedure.

This procedure must be imported by using the module (core list-lib).

Library procedure: lset-intersection = list1 ...
Returns the intersection of the lists, using = for the element-equality procedure.

This procedure must be imported by using the module (core list-lib).

Library procedure: lset-difference = list1 list2 ...
Returns the intersection of the lists, using = for the element-equality procedure.

This procedure must be imported by using the module (core list-lib).

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

This procedure must be imported by using the module (core list-lib).

Library procedure: lset-diff+intersection = list1 list2 ...
Returns two values -- the difference and the intersection of the lists.

This procedure must be imported by using the module (core list-lib).

Library procedure: lset-union! = list1 ...
Library procedure: lset-intersection! = list1 list2 ...
Library procedure: lset-difference! = list1 list2 ...
Library procedure: lset-xor! = list1 ...
Library procedure: lset-diff+intersection! = list1 list2 ...
These are destructive variants of the pure functions.

These procedures must be imported by using the module (core list-lib).

Hash tables

These procedures are always available.

Primitive procedure: hashq obj n
Primitive procedure: hashv obj n
Primitive procedure: hash obj n
Determine a hash value for obj that is suitable for lookups in a hash table of size n, where eq?, eqv? or equal? (for hashq, hashv, hash, respectively) is used as the equality predicate. The function returns an integer in the range 0 to 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 obj gets garbage collected in between.

Primitive procedure: make-hash [capacity] pair ...
Creates a hash table, initialized with values taken from the 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.

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

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

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

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

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

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

Symbol operations

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

Primitive procedure: symbol? obj
Returns #t if obj is a symbol, #f otherwise.

Primitive procedure: symbol->string symbol
Converts symbol to a string.

Primitive procedure: string->symbol string
Converts string to a symbol.

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

Character operations

All of these procedures are available without loading additional modules.

Primitive procedure: char? obj
Returns #t if obj is a character value, #f otherwise.

Primitive procedure: char= char1 char2
Returns #t if char1 is the same character as char2, #f otherwise.

Primitive procedure: char< char1 char2
Returns #t if char1 has a smaller character value than char2, #f otherwise.

Primitive procedure: char<= char1 char2
Returns #t if char1 has a smaller or equal character value than char2, #f otherwise.

Primitive procedure: char> char1 char2
Returns #t if char1 has a greater character value than char2, #f otherwise.

Primitive procedure: char>= char1 char2
Returns #t if char1 has a greater or equal character value than char2, #f otherwise.

Primitive procedure: char-ci= char1 char2
Returns #t if char1 is the same character as char2, #f otherwise. This function ignores case when comparing.

Primitive procedure: char-ci< char1 char2
Returns #t if char1 has a smaller character value than char2, #f otherwise. This function ignores case when comparing.

Primitive procedure: char-ci<= char1 char2
Returns #t if char1 has a smaller or equal character value than char2, #f otherwise. This function ignores case when comparing.

Primitive procedure: char-ci> char1 char2
Returns #t if char1 has a greater character value than char2, #f otherwise. This function ignores case when comparing.

Primitive procedure: char-ci>= char1 char2
Returns #t if char1 has a greater or equal character value than char2, #f otherwise. This function ignores case when comparing.

Primitive procedure: char-alphabetic? obj
Returns #t if obj is an alphabetic character.

Primitive procedure: char-numeric? obj
Returns #t if obj is a numeric character.

Primitive procedure: char-whitespace? obj
Returns #t if obj is whitespace character. The characters space, tab, line feed, form feed and carriage return are considered to be whitespace.

Primitive procedure: char-upper-case? obj
Returns #t if obj is an upper case character.

Primitive procedure: char-lower-case? obj
Returns #t if obj is a lower case character.

Primitive procedure: char->integer char
Convert the character char to its ASCII value.

Primitive procedure: integer->char n
Returns a character with ASCII value i.

Primitive procedure: char-upcase char
Returns the upper case version of character char if char is a lower case character and char otherwise.

Primitive procedure: char-downcase char
Returns the lower case version of character char if char is a upper case character and char otherwise.

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.

String Predicates

Primitive procedure: string? obj
Return #t if obj is a string, #f otherwise.

Primitive procedure: string-null? obj
Return #t if obj is a the empty string "", #f otherwise.

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

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

String Constructors

Primitive procedure: make-string k
Primitive procedure: make-string k char
Return a newly allocated string of length k. char is used to initialize the string, if omitted, the contents of the string is unspecified.

Primitive procedure: string char ...
Return a newly allocated string composed of its arguments, which all must be characters.

Primitive procedure: string-append string ...
Return a string made out of the concatenation of all string arguments. An empty string is returned if called without arguments.

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

Primitive procedure: list->string lst
Convert the list list, which must be made up from character values, to a string.

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

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

Primitive procedure: string-tabulate proc len
Create a string o length len, where each character is initialized from the value returned by applying proc to the character index.

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

This procedure will throw an exception if string-list is empty and grammar is string-infix.

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

String Accessors

Primitive procedure: string-length string
Return the number of characters in string.

Primitive procedure: string-ref string k
Return the kth character of string. The index is zero-based. k must be a valid index into string, or an error will be signalled.

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

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

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

String Comparison

Primitive procedure: string= string1 string2
Return #t if string1 is the same string as string2, #f otherwise.

Primitive procedure: string<? string1 string2
Returns #t if string1 is lexicographically less than string2, #f otherwise.

Primitive procedure: string<=? string1 string2
Returns #t if string1 is lexicographically less or equal to string2, #f otherwise.

Primitive procedure: string>? string1 string2
Returns #t if string1 is lexicographically greater than string2, #f otherwise.

Primitive procedure: string>=? string1 string2
Returns #t if string1 is lexicographically greater or equal to string2, #f otherwise.

Primitive procedure: string-ci=? string1 string2
Returns #t if string1 is the same string as string2, #f otherwise. This function ignores case when comparing.

Primitive procedure: string-ci<? string1 string2
Returns #t if string1 is lexicographically less than string2, #f otherwise. This function ignores case when comparing.

Primitive procedure: string-ci<=? string1 string2
Returns #t if string1 is lexicographically less or equal to string2, #f otherwise. This function ignores case when comparing.

Primitive procedure: string-ci>? string1 string2
Returns #t if string1 is lexicographically greater than string2, #f otherwise. This function ignores case when comparing.

Primitive procedure: string-ci>=? string1 string2
Returns #t if string1 is lexicographically greater or equal to string2, #f otherwise. This function ignores case when comparing.

Primitive procedure: string-prefix-length s1 s2 [start1 end1 start2 end2]
Return the length of the longest common prefix of the two strings.

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.

Primitive procedure: string-suffix-length s1 s2 [start1 end1 start2 end2]
Return the length of the longest common suffix of the two strings.

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.

Primitive procedure: string-prefix? s1 s2 [start1 end1 start2 end2]
Return #t if s1 is a prefix of s2.

Primitive procedure: string-prefix-ci? s1 s2 [start1 end1 start2 end2]
Return #t if s1 is a prefix of s2. Case is ignored when comparing characters.

Primitive procedure: string-suffix? s1 s2 [start1 end1 start2 end2]
Return #t if s1 is a suffix of s2.

Primitive procedure: string-suffix-ci? s1 s2 [start1 end1 start2 end2]
Return #t if s1 is a suffix of s2. Case is ignored when comparing characters.

String Searching

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

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

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

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

Primitive procedure: string-count string ch/pred [start end]
Return a count of the number of characters in string that satisfy the 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. start is the start index and defaults to zero, end is the end index and defatuls to the length of string - 1.

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

Note: The current implementation uses the naivest possible algorithm and is slow when string1 is a long string.

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

Note: The current implementation uses the naivest possible algorithm and is slow when string1 is a long string.

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

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

String Decomposition

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

Primitive procedure: string-take s nchars
Return the first nchars characters of s.

Primitive procedure: string-take-right s nchars
Return the last nchars characters of s.

Primitive procedure: string-drop s nchars
Return all but the first nchars characters of s.

Primitive procedure: string-drop-right s nchars
Return all but the last nchars characters of s.

String Case Conversion

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

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

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

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

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

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

String Trimming

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

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

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

Primitive procedure: string-chop string
Return a newly allocated string with the contents of string, but with all trailing newline characters removed.

Library procedure: trim-whitespace string
Return 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 char-whitespace? primitive.

This procedure must be imported by using the module core string-lib.

Note: This procedure has been deprecated. Use string-trim-both instead.

String Padding

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

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

String Pathname Operations

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

Primitive procedure: dirname filename
Returns a string of all but the final slash-delimited component of filename. If filename is a single component, dirname returns . (meaning the current directory).

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

Library procedure: tilde-expand string
Expand character sequences like `~' and `~username' in filename like bash and Emacs do. filename is unchanged if it has the form `~username', but the given user does not exist.

This procedure must be imported by using the module core string-lib.

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.

Vector constructors

Vectors can be created by either entering them literally in the normal Scheme vector syntax #(...), or they can be created with one of these functions. See section Vector conversion for the procedure 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 vector-set!.

Primitive procedure: make-vector k
Primitive procedure: make-vector k fill
Return a newly allocated vector of length k. fill is used to initialize the vector, if omitted the contents of the vector is unspecified.

Primitive procedure: vector obj ...
Returns a newly allocated vector composed of its arguments.

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

This procedure must be imported by using the module core vector-lib.

Library procedure: vector-copy vec
Create a freshly allocated copy of the vector vec.

This procedure must be imported by using the module core vector-lib.

Vector predicates

Primitive procedure: vector? obj
Returns #t if obj is a vector, #f otherwise.

Library procedure: vector= elt= vec1 vec2 ...
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 elt=.

This procedure must be imported by using the module core vector-lib.

Vector selectors

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

Primitive procedure: vector-length vector
Returns the number of elements of vector.

Primitive procedure: vector-ref vector k
Returns the kth element of vector. The index is zero-based. k must be a valid index into vector, or an error will be signalled.

Vector conversion

Primitive procedure: vector->list vector
Convert the vector vector to a list of all elements of vector.

Primitive procedure: list->vector lst
Convert the list list to a vector.

Vector modifying

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

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

Primitive procedure: vector-fill! vector obj
Stores obj in all elements of vector. The return value is not specified.

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 section Building Sizzle and build the library with enabled homogenous vectors.

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

Primitive procedure: TAGvector? obj
Returns #t if obj matches the type indicated by TAG, #f otherwise.

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

Primitive procedure: TAGvector-length vec
Returns the length of the homogenous vector vec, which must be of type TAG.

Primitive procedure: TAGvector obj1 ...
Creates and returns a homogenous vector of type TAG and initializes it with all parameters. The resulting vector has as much elements as there are obj parameters.

Primitive procedure: TAGvector-ref vec n
Returns the element at position n in the homogenous vector vec.

Primitive procedure: TAGvector-set! vec n obj
Stores the object obj at position n into the homogenous vector vec. vec must be of the vector type indicated by TAG, and obj must match TAG also.

Primitive procedure: TAGvector->list vec
Converts the homogenous vector vec, which must match the vector type indicated by TAG, to a list of its elements.

Primitive procedure: list->TAGvector list
Creates a homogenous vector which holds all elements of the list list. All elements must match the type TAG.

Primitive procedure: TAGvector-fill!! vec fill
Stores the object fill into all slots of the homogenous vector vec. vec must match the vector type indicated by TAG, and fill must be of a type compatible with TAG.

Primitive procedure: string->s8vector str
Primitive procedure: string->u8vector str
Convert the string str into a signed or unsigned 8-bit vector.

Primitive procedure: s8vector->string vec
Primitive procedure: u8vector->string vec
Convert the signed of unsigned 8-bit vector vec to a string.

Control flow operations

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

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

Primitive procedure: procedure? obj
Returns #t if obj is a primitive or user-defined procedure, #f otherwise.

Primitive procedure: primitive-procedure? obj
Returns #t if obj is a primitive procedure, #f otherwise.

Primitive procedure: closure? obj
Returns #t if obj is a user-defined procedure, #f otherwise.

Primitive procedure: form? obj
Returns #t if obj is a syntactic form, #f otherwise.

Primitive procedure: apply proc arg1 ... args
proc must be a procedure and args must be a list. Calls proc with the elements of the list (append (list arg1 ...) args) as the actual arguments.

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

Primitive procedure: values obj ...
Delivers all its arguments to its continuation. Used with call-with-values (see below).

Primitive procedure: call-with-values producer consumer
Calls its producer thunk and calls the consumer with whatever values have been returned by producer. consumer must take as many arguments as producer has returned values.

Library syntax: receive formals expression body
This is a more convenient way to handle multiple values. expression is evaluated and the results are assigned to variables named in formals, then body is evaluated. 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 -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

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

Primitive procedure: signal no proc
Install a signal handler. After installing a signal handler with this function, proc is called whenever the signal 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:
SIGHUP
Hangup signal.
SIGINT
Interrupt, normally generated when the user types C-c.
SIGQUIT
Quit.
SIGILL
Illegal instruction.
SIGTRAP
Trap.
SIGABRT
Process abort.
SIGIOT
Input/output trap.
SIGBUS
Bus error. Normally due to misaligned data access.
SIGFPE
Floating point exception.
SIGKILL
Kill signal. This cannot be caught.
SIGUSR1
First user-definable signal.
SIGUSR2
Second user-definable signal.
SIGSEGV
Segmentation fault.
SIGPIPE
Broken pipe. Generated when writing to a closed pipe.
SIGALRM
Alarm.
SIGTERM
Process termination.
SIGSTKFLT
Stack fault
SIGCLD
The same as SIGCHLD.
SIGCHLD
Child process terminated.
SIGCONT
Continue signal.
SIGSTOP
Stop signal.
SIGTSTP
Terminal stop.
SIGTTIN
Terminal input signal.
SIGTTOU
Terminal output signal.
SIGURG
Urgency signal.
SIGXCPU
CPU time exceeded.
SIGXFSZ
File limit exceeded.
SIGVTALRM
Virtual alarm.
SIPROF
Profiler signal.
SIGWINCH
Window configuration changed.
SIGPOLL
Poll signal.
SIGIO
Input/output signal.
SIGPWR
Power failure.

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

Primitive procedure: error obj ...
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.

Primitive procedure: throw symbol obj ...
Raise an exception with the exception tag tag which will be passed upward in the call chain until either a catch clause for the 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.

Primitive procedure: catch tag thunk handler
catch is used to implement exception handling. thunk is evaluated but any exception which may be thrown by an expression evaluated inside of thunk and is equal to the exception tag tag (in the sense of eq?) is caught. Should no exception be raised, the result of the last expression is returned. Otherwise, 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 handler is returned.

If tag is #t, all exceptions are caught.

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

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.

Primitive procedure: exit
Primitive procedure: exit n
Terminate the running Sizzle process, returning to the shell which executed it. n is the exit code of the process, if given, otherwise the exit code is zero.

Primitive procedure: call-with-current-continuation proc
Primitive procedure: call/cc proc
Calls proc with the current continuation as its argument. proc may then call the passed continuation with a parameter to deliver that value to the continuation. The result of call-with-current-continuation is either the result of 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.

call/cc is synonym to call-with-current-continuation.

Note that Sizzle does not implement a full-featured call/cc. The continuation passed to 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 proc is an error and will signal an exception.

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

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

Primitive procedure: load string
Synonym to primitive-load-path.

Primitive procedure: transcript-on filename
Primitive procedure: transcript-off
filename must be a string naming an output file to be created. The effect of 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 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.

Eval function

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

Primitive procedure: eval expression
Primitive procedure: eval expression environment-specifier
Evaluate expression in the environment given by environment-specifier. If omitted, the current environment is used. Enironment specifiers can only be obtained by using one of the following three procedures.

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

Primitive procedure: null-environment version
Return an empty environment to be used with eval. version must be an exact integer spcifying the supported Scheme report version, currently this is 5.

Primitive procedure: interaction-environment
Return the environment of the read-eval-print loop to be used with eval.

Primitive procedure: current-environment
Return the environment currently used to look up bindings to be used with eval.

Primitive procedure: safe-environment symbol-list
Create and return a safe environment, in which only the special forms are defined. Also, the current bindings for all symbols in 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 safe-environment, and is not able to affect any other environments.

Debugging Support

The following procedures are always supported.

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

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 on/off is true, start tracing procedure proc, otherwise, switch tracing for 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 foo, which receives one argument, the format of the message is

+ foo <- (1)

That means that foo is entered (indicated by the +) with the parameter list (1).

When tracing primitive procedures, a message when exiting from the procedure is also printed. A call to the traced primitive modulo with the parameter list (3 2) looks like this:

+ modulo <- (3 2)
- modulo -> 1

The second line tells that the result of the function is 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.

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.

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.

Input and output

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.

Primitive procedure: call-with-input-file string proc
Opens the file named string for input and calls proc with the newly created input port as a single argument.

Primitive procedure: call-with-output-file string proc
Opens the file named string for output and calls proc with the newly created output port as a single argument.

Primitive procedure: input-port? obj
Returns #t if obj is an input port, #f otherwise.

Primitive procedure: output-port? obj
Returns #t if obj is an output port, #f otherwise.

Primitive procedure: current-input-port
Returns the current default input port.

Primitive procedure: current-output-port
Returns the current default output port.

Primitive procedure: current-error-port
Returns the current default error output port.

Primitive procedure: set-current-input-port port
Set port to be the value which subsequent calls to current-input-port will return.

Primitive procedure: set-current-output-port port
Set port to be the value which subsequent calls to current-output-port will return.

Primitive procedure: set-current-error-port port
Set port to be the value which subsequent calls to current-error-port will return.

Primitive procedure: with-input-from-file string thunk
Opens the file named string for input and makes it the current default input port for the time proc is called.

Primitive procedure: with-output-to-file string thunk
Opens the file named string for output and makes it the current default output port for the time proc is called.

Primitive procedure: with-error-to-file string thunk
Opens the file named string for output and makes it the current default error port for the time proc is called.

Primitive procedure: open-input-file filename
Returns an input port connected to the file named filename. An error is signalled if the file cannot be opened.

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

Primitive procedure: close-port port
Close the port port.

Primitive procedure: close-input-port port
Close the input port port. This is synonymous to close-port, but is required by R5RS.

Primitive procedure: close-output-port port
Close the output port port. This is synonymous to close-port, but is required by R5RS.

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

Primitive procedure: read
Primitive procedure: read port
Read a scheme object from port. port is omitted, the current input port is used.

Primitive procedure: read-char
Primitive procedure: read-char port
Reads a character from port and returns it. port is omitted, the current input port is used. Returns the end-of-file object on end of file.

Primitive procedure: unread-char char
Primitive procedure: unread-char char port
Put the character char back on the port port, so that it can bea read again with read-char. port defaults to the value returned by current-input-port, if not given.

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

Primitive procedure: char-ready?
Primitive procedure: char-ready? port
Tests whether a character is available to be read from port and returns #t if it is, #f otherwise. If port is not specified, the current input port is used.

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

This procedure is not supported when the option -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

Primitive procedure: %read-delimited! delims buf gobble? [port start end]
Read characters from port into buf until one of the characters in the delims string is encountered. If gobble? is true, store the delimiter character in buf as well; otherwise, discard it. If port is not specified, use the value returned by current-input-port. If start or end are specified, store data only into the substring of buf bounded by start and 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 eof-object; if the buffer was filled without encountering a delimiter, this value is #f.

Primitive procedure: write-line obj [port]
Display obj and a newline character to port. If port is not specified, (current-output-port) is used. This function is equivalent to:
(display obj [port])
(newline [port])

Primitive procedure: seek port offset whence
Change the position of the file pointer for port. offset is used to calculate the new file offset, depending on whence. Three variable may be used for values to give as whence.
SEEK_SET
offset is used as the new file offset.
SEEK_CUR
offset is added to the current offset to yield the new file offset.
SEEK_END
offset is subtracted from the file length to yield the new file offset.

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.

Primitive procedure: ftell port
Return the current offset of the file pointer of port, which may be a file or string port.

Primitive procedure: eof-object? obj
Returns #t if obj is the end-of-file object, #f otherwise.

Primitive procedure: port-closed? port
Returns #t if port is a closed port, #f otherwise.

Primitive procedure: display obj
Primitive procedure: display obj port
Print the textual representation of obj to port. obj is not quoted when printing. display's return value is unspecified. If port is omitted, the current output port is used.

Primitive procedure: write obj
Primitive procedure: write obj port
Print the textual representation of obj to port. obj is quotedwhen printing. write's return value is unspecified. If port is omitted, the current output port is used.

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

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

Primitive procedure: call-with-input-string string proc
Create an input string port which will return the contents of string and call proc, passing the newly created string port as the argument.

Primitive procedure: call-with-output-string proc
Call proc with a string port as the argument and return all data which was written to the string port while proc was executing as a string.

Primitive procedure: with-input-from-string string thunk
Call thunk with the current input port connected to a string port which delivers the contents of string.

Primitive procedure: with-output-to-string thunk
Call thunk and return a string consisting of all data which was written to the current output port during execution of thunk.

Primitive procedure: with-error-to-string thunk
Call thunk and return a string consisting of all data which was written to the current error port during execution of thunk.

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

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

Primitive procedure: get-output-string output-port
Given an output port created with open-output-string, returns a string consisting of the characters that have been output to the port so far.

Primitive procedure: with-input-from-port port thunk
Call thunk, but while thunk is evaluating, redirect all input from the input port port.

Primitive procedure: with-output-to-port port thunk
Call thunk and redirect all output sent to the current output port to port while thunk is evaluating.

Primitive procedure: with-error-to-port port thunk
Call thunk and redirect all output sent to the current error port to port while thunk is evaluating.

Primitive procedure: port-line
Primitive procedure: port-line port
Return the current line number of the port port. If port is not specified, the current input port is used.

Primitive procedure: set-port-line! port n
Set the current line number of the port port to the value of n, which must be an integer value. The return value is not specified.

Primitive procedure: port-column
Primitive procedure: port-column port
Return the current line column number of the port port. If port is not specified, the current input port is used.

Primitive procedure: set-port-column! port n
Set the current column number of the port port to the value of n, which must be an integer value. The return value is not specified.

Primitive procedure: port-filename
Primitive procedure: port-filename port
Return the file name of the port port. If port is not specified, the current input port is used.

Primitive procedure: set-port-filename! port s
Set the file name of the port port to the value of s, which must be an string value. The return value is not specified.

Primitive procedure: isatty? [port]
Return #t, if port is a tty, #f otherwise. port defaults to the current input port.

Primitive procedure: object->string obj
Return a string with the characters display would produce when printing obj.

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 --disable-regexp option or if no usable regular expression matching library was found on configuration time.

Primitive procedure: regexp? obj
Returns #t if obj is a compiled regular expression object, #f otherwise.

Primitive procedure: make-regexp string flags ...
Create a compiled regular expression object which represents the string string. The following additional arguments can be passed to control regular expression compilation:
regexp/icase
The matching is performed case-insensitively.
regexp/extended
Support extended Posix regular expressions (this is the default).
regexp/basic
Do not support extended Posix regular expressions.
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.

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

System interface functions

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. 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 not-available exception when called.

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

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 -s SCRIPT command line option, only the script name (as the first element in the command line) and the arguments after SCRIPT are contained in the command line list.

This procedure is always available.

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

Primitive procedure: getenv string
Returns the value of the environment variable called string if defined, and #f otherwise.

This procedure is always available.

Primitive procedure: putenv string
Insert the string string into the process environment. string must be of the form name=value. The return value is not specified.

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

Primitive procedure: getcwd
Returns a string which denotes the current working directory.

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

Primitive procedure: chdir string
Change the current working directory to string. A system-error exception will be raised if the directory string cannot be changed to. The return value is not specified.

Primitive procedure: getpid
Returns the process identifier (pid) of the running Sizzle process.

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.

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.

Primitive procedure: setuid uid
Set the user identifier of the current Sizzle process to uid. Only the superuser can do that. This function may raise a 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.

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

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

Primitive procedure: seteuid euid
Set the effective user identifier of the current Sizzle process to euid. This function may raise a 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.

Primitive procedure: getgid
Returns the group identifier of the running Sizzle process. A system-error exception may be raised if an error occurs.

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

Primitive procedure: setgid gid
Set the group identifier of the running Sizzle process to gid. A 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.

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

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

Primitive procedure: setegid egid
Set the effective group identifier of the running Sizzle process to egid. A 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.

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

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

Primitive procedure: getpgrp
This is equivalent to (getpgid 0).

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

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

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

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

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

Library procedure: pw:name vec
Library procedure: pw:passwd vec
Library procedure: pw:uid vec
Library procedure: pw:gid vec
Library procedure: pw:gecos vec
Library procedure: pw:dir vec
Library procedure: pw:shell vec
Accessor procedures for the fields of the vector returned by getpwnam and getpwuid.

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

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

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 system-error exception if an error occurs. The returned vector has the following fields:
dev
Device the file is located on.
ino
Inode number of the file.
mode
The file mode and permissions.
nlink
Number of hard links to the file.
uid
User identifier of the file owner.
gid
Group identifier of the file owner
rdev
Device type (if inode device)
size
Total size in bytes
atime
Time of last access
mtime
Time of last modification
ctime
Time of last change
blksize
Block size for the filesystem the file is on
blocks
Number of blocks the file allocates
type
The type of the file as a symbol, which may be any of regular, directory, symlink, block-special, char-special, fifo, socket or unknown.
perms
Permissions of the file. This is the file mode without the file type bits.

The file mode is a bitset which can be tested by logically combining it with one or more of the following constants:

S_ISUID
Set user identifier
S_ISGID
Set group identifier
S_IRWXU
User (file owner) has read, write and execute permission
S_IRUSR
User has read permission
S_IWUSR
User has write permission
S_IXUSR
User has execute permission
S_IRWXG
Group has read, write and execute permission
S_IRGRP
Group has read permission
S_IWGRP
Group has write permission
S_IXGRP
Group has execute permission
S_IRWXO
Others have read, write and execute permission
S_IROTH
Others have read permission
S_IWOTH
Others have write permission
S_IXOTH
Others have execute permission

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

Primitive procedure: lstat filename
Like stat, but does not follow symbolic links.

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

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

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 #t if access is permitted, #f otherwise. This function may raise a system-error exception if an error occurs. mode is a mask of one or more of the following constants:
R_OK
Test for read permission
W_OK
Test for write permission
X_OK
Test for execute permission
F_OK
Test for file existence

access? is only successful if all permissions are granted.

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 system-error exception if an error occurs.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: open-fdes filename flags [mode]
Attempts to open the file called filename and returns a file descriptor. flags is a mask of one or more of the following:
O_RDONLY
Open the file read only.
O_WRONLY
Open the file write only.
O_RDWR
Open the file for reading and writing.
O_CREAT
If the file does not exist it will be created.
O_EXCL
When used with O_CREAT, if the file already exists it is an error and the open will fail.
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.
O_TRUNC
If the file already exists it will be truncated.
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.
O_NONBLOCK
Open the file in non-blocking mode, which means that operations on the file do not wait for completion.
O_NDELAY
The same as O_NONBLOCK.
O_SYNC
Writes to the file will be immediately written to disk.

If O_CREAT is given and the file will be created, the additional argument mode must be given, which denotes the file permission the new file will have. mode is a mask of the permission constants listed in the description of stat.

This function may raise a system-error exception if an error occurs.

Primitive procedure: sys:creat mode
This is equivalent to open with flags equal to (logior O_CREAT O_WRONLY O_TRUNC).

Primitive procedure: close fd
Closes a file descriptor, if fd is an integer, so that it no longer refers to any file and may be reused, or simply closes fd of it is a port. This function may raise a system-error exception if an error occurs.

Primitive procedure: sys:write fd u8vec count
Write count bytes from the homogenous unsigned 8-bit vector u8vec to the file referenced by the file descriptor fd. Returns the number of bytes actually written. This function may raise a system-error exception if an error occurs.

This procedure is only available if homogenous vectors were enable on configuration time.

Primitive procedure: sys:read fd count
Read count bytes from the file referenced by the file descriptor fd and returns a homogenous unsigned 8-bit vector containing those bytes. This function may raise a system-error exception if an error occurs.

This procedure is only available if homogenous vectors were enable on configuration time.

Primitive procedure: sys:read! fd u8vec count
Read count bytes from the file referenced by the file descriptor fd and stores them into the homogenous unsigned 8-bit vector u8vec. The return value is not specified. This function may raise a system-error exception if an error occurs.

This procedure is only available if homogenous vectors were enable on configuration time.

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 system-error exception if an error occurs.

Primitive procedure: link oldpath newpath
Creates a new link (also known as a hard link) to an existing file. If newpath exists it will not be overwritten. The return value is not specified. This function may raise a system-error exception if an error occurs.

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

Primitive procedure: symlink oldpath newpath
Creates a new symbolic link to an existing file. If newpath exists it will not be overwritten. The return value is not specified. This function may raise a system-error exception if an error occurs.

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

Primitive procedure: rename oldpath newpath
Renames a file, moving it between directories if required. oldpath and newpath must refer to the same file system. The return value is not specified. This function may raise a system-error exception if an error occurs.

Primitive procedure: readlink filename
Returns the name of the file the link filename is referring to. This function may raise a system-error exception if an error occurs.

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

Primitive procedure: chmod path mode
The mode of the file given by path is changed to mode. mode is a mask made from the S_I... constants listed in the description of stat. This function may raise a system-error exception if an error occurs.

Primitive procedure: chown path uid gid
Set the user identifier and group identifier of the file path to uid and gid. If any of uid or gid is equal to -1, that component of path's ownership is not changed. This function may raise a system-error exception if an error occurs.

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

Primitive procedure: primitive-exit [status]
Terminate the current process without performing any cleanup. The exit status is status, which defaults to 0 if not specified. This procedure has no return value, because it never returns.

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 system-error exception if an error occurs.

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

Primitive procedure: kill pid sig
Sends any signal to any process group or process. If pid is positive, then signal sig is sent to pid.

If pid equals 0, then sig is sent to every process in the process group of the current process. If pid equals -1, then sig is sent to every process except for the first one, from higher numbers in the process table to lower. If pid is less than -1, then sig is sent to every process in the process group -pid. If sig is 0, then no signal is sent, but error checking is still performed.

This function may raise a system-error exception if an error occurs.

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

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 system-error exception if an error occurs.

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

Primitive procedure: waitpid pid [options]
Waits until child process pid has terminated. For usage of the options argument, refer to the waitpid man page. This function may raise a system-error exception if an error occurs.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: sleep n
Suspend the running process for n seconds, or until a signal wakes up the process. This function may raise a system-error exception if an error occurs.

Primitive procedure: execl filename args
Execute the file filename, passing the list args as command line options. This function may raise a system-error exception if an error occurs.

Primitive procedure: execlp filename args
Like execl, but search the path for filename.

Primitive procedure: execle filename args env
Like execl, but pass the environment list env together with the command line arguments args to the process.

Primitive procedure: nice inc
Change the current process priority by amount inc. You must be the system administrator to pass a negative inc. This function may raise a system-error exception if an error occurs.

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

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 system-error exception if an error occurs.

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

Primitive procedure: uname
Return a vector containing information about the system. This function may raise a system-error exception if an error occurs. The returned vector contains the following fields:
sysname
The name of the operating system.
nodename
The name of the host.
release
The operating system release.
version
The operating system version.
machine
The machine architecture.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: utime filename [timelist]
If timelist is omitted, set the access and modification time for the file filename to the current time. Otherwise, timelist must be a list of two integer values, which will be used to set the access and modification time of filename. This function may raise a system-error exception if an error occurs.

Primitive procedure: tmpnam
The tmpnam procedure generates a unique temporary filename in the standard directory for temporary files (normally `/tmp').

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

Primitive procedure: tmpfile
The tmpfile procedure generates a unique temporary filename in the standard directory for temporary files (normally `/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 system-error exception if an error occurs.

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

Primitive procedure: umask [mask]
umask sets the umask to (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 mask is not given, the current umask value is returned, without changing the umask for the process.

Primitive procedure: strftime format vec
Format the time-representing vector vec according to the format specifier format to a string and return that string. For details of the format specified, have a look at man strftime.

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

Primitive procedure: strptime format string
Parse the string string according to the format specifier format. Check out man strptime for the format specification. Returns a pair consisting of a time vector and the number of characters of string which have been used up when parsing. This procedure is essentialy the counterpart of strftime.

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

Primitive procedure: gmtime x
Split up the time object 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:
seconds
minutes
hours
day of month
month
year
day of the week
day in the year
daylight saving time
time zone offset
time zone name or #f if not specified

Primitive procedure: localtime x
Returns x converted to local time in a vector of the format defined in the description of gmtime.

Bug: Right now time zone offset and time zone names are not correctly set by localtime.

Library procedure: tm:sec timevec
Library procedure: tm:min timevec
Library procedure: tm:hour timevec
Library procedure: tm:mday timevec
Library procedure: tm:month timevec
Library procedure: tm:year timevec
Library procedure: tm:wday timevec
Library procedure: tm:yday timevec
Library procedure: tm:isdst timevec
Library procedure: tm:zoff timevec
Library procedure: tm:zname timevec
These procedure return the fields their names stand for from the time vector timevec, which must have the format documented in the decription for gmtime.

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 gmtime or localtime, which split up the time value into its various parts.

Primitive procedure: directory-files dirname
Return a list containing all files in the directory dirname. This procedure may throw a system-error exception if an error occurs.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: fcntl fdesc cmd [arg]
fcnt performs one of various operations on the file descriptor fd. The following commands are possible:
F_DUPFD
Makes arg be a copy of fd, closing fdesc first if necessary.
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.
F_SETFD
Set the close-on-exec flag to the value specified by arg (only the least significant bit is used).
F_GETFL
Read the descriptor's flags (all flags (as set by open(2)) are returned).
F_SETFL
Set the descriptor's flags to the value specified by arg. Only O_APPEND and O_NONBLOCK may be set. The flags are shared between copies (made with dup etc.) of the same file descriptor.
F_GETLK, F_SETLK, F_SETLKW
Manage discretionary file locks. This command is not properly implemented in Sizzle right now.
F_GETLK
This command is not properly implemented in Sizzle right now.
F_SETLK
This command is not properly implemented in Sizzle right now.
F_SETLKW
This command is not properly implemented in Sizzle right now.
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.
F_SETOWN
Set the process ID or process group that will receive SIGIO and SIGURG signals for events on file descriptor fd. Process groups are specified using negative values.

This procedure is only available if supported by the underlying C library and (limited) under Windows.

Primitive procedure: fsync fdesc
fdesc must be either a valid file descripor or a file port. All pending output is written if 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 fsync.

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

Primitive procedure: copy-file oldfile newfile
Copy the file specified by oldfile to newfile. The return value is unspecified.

Primitive procedure: directory-stream? obj
Return #t if obj is a directory stream, #f otherwise.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: opendir str
Open the directory called str and return a directory stream for that directory, which can be used in calls to readdir, closedir and rewinddir. This procedure may raise a system-error exception if an error occurs.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: closedir stream
Close the directory stream stream. The return value is not specified.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: readdir stream
Return the next filename from the directory stream stream, or the end-of-file object if all files have been read. This procedure may raise a system-error exception if an error occurs.

This procedure is only available if supported by the underlying C library and under Windows.

Primitive procedure: rewinddir stream
Rewind the directory stream to the beginning, so that on the next call to 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.

Network Procedures

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 strerror(errno) or herror(), whatever is appropriate for the specific error.

Primitive procedure: socket domain type protocol
Creates a socket port using domain, type and protocol. This is a direct wrapper to the C library function, so refer to the libc documentation for details. Normally you specify the domain as the constant AF_INET and the type SOCK_STREAM for normal internet sockets. This procedure may raise a system-error exception if an error occurs. The following socket types are also defined:
SOCK_STREAM
SOCK_DGRAM
SOCK_RAW
SOCK_SEQPACKET
SOCK_RDM

For the defined address family constants, refer to the documentation for bind.

Primitive procedure: shutdown sock how
Sockets can be closed simply by using close-port. The shutdown procedure allows reception or transmission on a connection to be shut down individually, according to the parameter how:
0
Stop receiving data for this socket. If further data arrives, reject it.
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.
2
Stop both reception and transmission.

The return value is unspecified.

Primitive procedure: listen sock backlog
This procedure enables sock to accept connection requests. 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 accept to accept a connection from the queue. The return value is unspecified.

Primitive procedure: gethostbyname name
Returns the IPv4 address of the host named name. 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 network-error exception if an error occurs.

Primitive procedure: accept sock
Accepts a connection on a bound, listening socket 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 car is a new socket port for the connection and the cdr is an object with address information about the client which initiated the connection.

If the address is not available then the cdr will be an empty vector. sock does not become part of the connection and will continue to accept new requests.

Primitive procedure: getsockname sock
Returns the address of sock, in the same form as the object returned by accept.

Primitive procedure: getpeername sock
Returns the address of the socket sock is connected to, in the same form as the object returned by accept.

Primitive procedure: ntohl n
Converts the 32 bit value n from network to host byte order.

Primitive procedure: htonl n
Converts the 32 bit value n from host to network byte order.

Primitive procedure: ntohs n
Converts the 16 bit value n from network to host byte order.

Primitive procedure: htons n
Converts the 16 bit value n from host to network byte order.

Primitive procedure: fileno port
Returns the file descriptor used for operations on port. port must be a file descriptor port, or an error will be signalled.

Primitive procedure: connect hostname port
Establish a connection to the host identified by hostname on port port. 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 network-error and system-error exceptions.

Primitive procedure: server-socket port
Returns a socket, which listens on the local IP address on port port. A port returned by this procedure may be used in calls to accept.

Primitive procedure: server-loop port proc
This procedure can be used to implement simple network applications. port must be a port created by server-socket or any equivalent calling sequence to socket, bind and listen. server-loop will wait for incoming connection using accept and call proc when a connection is available. 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.

Primitive procedure: bind scheme-port family address port
Bind the port scheme-port, created with a call to socket to the address specified by family, address, and the port number port. This procedure returns an unspecified value.

The following address families are defined:

AF_UNIX
Unix sockets family.
AF_INET
Internet socket family.

If your system supports them, the following families are also defined:

AF_ISO
AF_NS
AF_IMPLINK

Primitive procedure: select rdfd wrfd exfd sec usec
Perform the select system call on the file descriptor sets rdfd, wrdf and exfd. The timeout value is calculated from the seconds sec and the microseconds usec. The number of the highest file descriptor in any of the sets is returned as the result.

Primtitive procedure: gethostname
Get the host name of the local host. The returned value is a string.

Primitive procedure: sethostname name
Set the host name of the local host to name. The return value is not specified.

Primitive procedure: getdomainname
Get the domain name of the local host. The returned value is a string.

Primitive procedure: setdomainname
Set the domain name of the local host to name. The return value is not specified.

Primitive procedure: inet-aton addr
Convert the internet address addr from dotted decimal notation to binary data. The returned value is an integer.

Primitive procedure: inet-ntoa addr
Convert the internet address addr from binary representation to a string. The returned value is a string.

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

Syntax: use-modules name0 name1 ...
Import all modules listed as 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.

Syntax: define-module name options ...
Define a module called 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 export, documented below.

Options may be one or more pair of a keyword and a value. The following keywords are presently defined:

#: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.
#:export
The value must be a list of symbols listing the defines to be exported. This is an alternative notation for the export syntactic form.

Syntax: export symbol0 symbol1 ...
Add all symbols to the export list of the currently active module.

Primitive procedure: module-list
Return a list of currently loaded modules.

Primitive procedure: current-module
Return the module in which currently definitions take place.

Dynamic Loading

Sizzle support dynamic loading of shared libraries under Unix using the dl interface.

Exception: dl-error
This exception is thrown when an error occurs while using the `dl' library. The exception contains an error message obtained with dlerror().

Primitive procedure: load-library name [filename]
Load and initialize the shared object name. If filename is specified, the file named filename is dlopen()'ed, otherwise the file name libname.so is opened via dlopen(). When the loaded object exports a symbol called zzz_init_name(), this function is called without arguments and should initialize the library.

This function may throw a dl-error exception if the file could not be loaded or if the initialization function returned a value other than RESULT_SUCCESS.

Besides the high-level procedure load-library, some low-level procedures are provided which implement a wrapper around the `dl' library.

Primitive procedure: %dlopen filename [flags]
dlopen() the file filename and return a dynamic library object for that file. flags may be the bitwise or of the following constants:
RTLD_GLOBAL
Make the symbols in the loaded file available to other processes.
RTLD_LAZY
Relocate symbols when they are used.
RTLD_NOW
Relocate all symbols when the library is loaded.

Primitive procedure: %dlclose lib
Take a dynamic library object lib and close it. After that, calls to %dlsym with the library lib will fail.

Primitive procedure: %dlsym lib string
Return the address of the symbol string in the library specified by the dynamic library object lib. Throw a dl-error exception if the dymbol could not be resolved.

Primitive procedure: %dlcall address
Call the function specified by address (which must have been found with a call to %dlsym) without arguments. A dl-error exception is thrown if the function returns a value other than RESULT_SUCCESS.

Macro functions

Sizzle can handle macros defined using the primitive define-macro. The macro interface should be compatible to Guile's, but I have not yet verified that completely.

Syntax: define-macro (name arg ...) body
Define a macro name which as many arguments as args are given. When the macro is expanded, the symbols in args are bound to the actual parameters of the macro call and 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 writeln, which prints all its arguments using display and then advances to the next line using newline.

(define-macro (writeln . --x)
  `(begin (for-each display (list ,@--x)) (newline)))

You have to be careful about the formal parameter names given with args, because they may shadow variables visible when the macro is called.

Primitive procedure: expand-macro list
Expand the macro call represented by list and return the expanded expression. The car of the list must be a macro object.
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)))

Primitive procedure: apply-macro macro list
Apply the macro macro, which must have been created with define-macro to the argument list list. This will cause the transformer procedure for macro to be applied to the arguments in list. The value returned by the macro transformer is returned.

Sizzle also has some limited support for the macros from R5RS, but be careful when using them for the following reasons: The syntax is not fully implemented, especially substituting for vector patterns does not work. Most important, because this is a major feature of R5RS macros, is the lacking of hygienic macros. Variable shadowing and free variable capturing is very likely when using these macros in Sizzle. Maybe you should not use them at all at the moment, but since they are somehow implemented and accessible, I decided to at least document their deficiencies.

For more information about macros, have a look at the Sizzle startup file `init.scm', located in the `data' subdirectory in the distribution, where some simple macros are defined. Also refer to R5RS for more information about syntax and semantics of the macro definition commands.

Syntax: let-syntax ((variable syntax-rule) ...) body
Bind the syntax rules syntax-rules, which must be created using the syntactic form syntax-rules to the variables and evaluate body. The defined syntactic forms will be visible in body only. The return value is the return value of the last expression in body.

Syntax: letrec-syntax ((variable syntax-rule) ...) body
Bind the syntax rules syntax-rules, which must be created using the syntactic form syntax-rules to the variables and evaluate body. The defined syntactic forms will be visible in the syntax-rule statements and body only. In contrast to let-syntax, syntax elements defined in the variable binding section can refer to each other recursively. The return value is the return value of the last expression in body.

Syntax: define-syntax name syntax-rule
Bind the syntax rules syntax-rule, which must be created with syntax-rules, to name in the current environment. The return value is unspecified.

Syntax: syntax-rules (literals ...) rule ...
Define a syntactic form. literals is a list of symbols which are to be treated literally in the rules. Each rule has the form (pattern templace), where each templace has the form (keyword pattern ...) and each template has the form constant, symbol, (template ...) or #(template ...).

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.

Primitive procedure: garbage-collect
Triggers immediate garbage collection. The return value is unspecified.

Primitive procedure: autoload symbol filename
Install an autoload association for symbol. The result is unspecified. Whenever an autoload association is encountered in procedure position when evaluating a procedure application, the file named filename is loaded using primitive-load-path. The file mus define a procedure called symbol, or an error will be signalled.

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.

Primitive procedure: documentation obj
Returns the documentation object attached to obj. Returns #f if no wuch object is available. For procedure objects, documentation tries to load a documentation string from the file `docstrings.txt', which was installed with Sizzle. Not all primitives are documented in this file yet, so #f may be returned for them, too.

Primitive procedure: set-documentation! obj doc
Attach the documentation object doc to the Scheme object obj. doc will be returned when applying documentation to obj after calling this procedure. The return value is unspecied.

Primitive procedure: describe obj
Print a description of obj to the current output port. This description includes the type of obj and the documentation object or documentation string attached to obj. The return value is unspecified.

Primitive procedure: apropos string
Print a one-line description of all procedures with string their names. This can be used to get a list of procedure names, so that describe can be used on the procedures to get more information about them. The return value of this procedure is not specifed.

Misc functions

This section is a catch-all for all primitive procedures which do not fit into any of the other categories.

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:
used-cons-cells
Number of cons cells which are currently in use.
used-tagged-cells
Number of tagged cells which are currently in use.
allocated-cons-cells
Number of cons cells in the cons heap, both free cells and cells which are in use.
allocated-tagged-cells
Number of tagged cells in the tagged heap, both free cells and cells which are in use.
cons-heap-usage
Number of bytes currently allocated for the cons heap.
tagged-heap-usage
Number of bytes currently allocated for the tagged heap.
other-usage
Number of bytes currently allocated for other purposes, such as for vector and string contents etc.
gc-count
Number of garbage collections since startup.
gc-time
Time spent in the garbage collector since the interpreter started.
gc-percent
Amount of the total running time which was spent in the garbage collector since the interpreter started up.

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:
global-accesses
Variable accesses which required a complete variable lookup.
lloc-accesses
Variable access which went through an lloc object.
gloc-accesses
Variable access which went through a gloc object.
tail-calls
Procedure calls which were executed tail-recursively.
evaluate-calls
Calls to the function zzz_evaluate().
closure-calls
Calls to closure objects (lambda applications).
primitive-calls
Calls to primitive procedures.
syntactic-calls
Executions of non-memoized syntactic forms.
immediate-calls
Executions of memoized syntactic forms.

Primitive procedure: random n
Return a random number (an integer value) which is in the range [0..n). random returns always the same sequence of random number, unless you have set the random seed using srand.

Primitive procedure: srand n
Set the random seed for the procedure random to n. The return value is not specified.

Library procedure: 1+ x
Library procedure: 1- x
Library procedure: add1 x
Library procedure: sub1 x
Handy helper functions. 1+ and add1 return their argument plus 1, 1- and 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 -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

Library procedure: pretty-print obj [port]
Pretty-print the Scheme object obj to port, or to the standard output port if 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 (core pprint) to have access to this procedure.

Syntactic Forms

There are two types of syntactic forms. The forms labelled with Syntax are builtin syntax, the forms labelled Defined syntax are defined in the startup file `init.scm' and may be not present if the embedding application does not load this init file.

Syntax: quote obj
Returns its argument obj unevaluated. This is normally used to type in symbols and is used so often that a shorthand form exists: Instead of `(quote foo)' you can write `'foo'.

Syntax: quasiquote obj
Works similar to quote, with the difference that expressions with unquote or unquote-splicing are evaluated in obj. Also has a shorthand form: ``foo' has the same meaning `(quasiquote foo)'.

Syntax: unquote obj
When used inside of a quasiquote expression, evaluates its argument. Also has a shorthand form: `,foo' has the same meaning `(unquote foo)'. unquote may only be used inside of quasiquote expression, an error is signalled if used in another context.

Syntax: unquote-splicing obj
When used inside of a quasiquote expression, evaluates its argument. The difference between unquote and 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: `,@foo' has the same meaning `(unquote-splicing foo)'. unquote-splicing may only be used inside of quasiquote expression, an error is signalled if used in another context.

Syntax: set! variable expression
Set the value of variable to the value of expression. The return value is not specified. You can only use set! on variables which have been already defined by either define or one of the let-constructs.

Syntax: define variable expression
Define variable as a variable and set its value to the value of expression. The return value is not specified.

Syntax: define (variable arg1 ...) commands ...
Syntax: define (variable arg1 ... . argn) commands ...
Syntax: define (variable . arg) commands ...
Special form of define which is equivalent to
(define variable (lambda (arg1 ...) commands ...
(define variable (lambda (arg1 ... . argn) commands ...
(define variable (lambda arg commands ...

Syntax: undefine symbol
Make the symbol symbol undefined. After calling this special form, any references to symbol will cause an unbound-variable error. The return value is not specified.

Primitive procedure: defined? symbol
This is not a special form, but it fits best into this section together with define and undefine. defined? returns #t if symbol is a defined variable and #f otherwise.

Syntax: define-constant variable expression
Define variable as a variable and set its value to the value of expression. The return value is not specified. The difference between define and define-constant is that variables created using define-constant are read-only and cannot be modified with set!. This enables runtime optimizations because references to constant variables can be replaced by the variable's value, eliminating symbol lookups.

Syntax: if condition then [else]
Evaluates condition and then checks its return value. If the value is #t, then is evaluated and the result of that evaluation is returned. Otherwise, the behaviour depends on the presence of the else expression. If else is not provided, the return value is unspecified, otherwise else is evaluated and the result is returned.

Syntax: cond clause1 clause2 ...
Each clause is of the form
(test expression1 ...)

Alternatively, a clause may be of the form

(test => expression)

and the last clause may be an else clause, which has the form

(else expression1 expression2 ...)

A cond expression is evaluated by evaluating the test expressions of successive clauses in order until one of them evaluates to a true values. The first clause whose test evaluates to true is chosen and the expressions in the clause are evaluated in order and the value of the last expression is returned as the value of the cond expression. If the selected clause has no expressions, the value of the test is returned. An else clause is chosen and the following expressions are evaluated if no other test evaluates to true.

If the selected clause has the => form, the expression following the arrow must evaluate to a procedure to which the result of the test is applied to yield the result of the cond expression.

Syntax: case key clause1 clause2 ...
key may be any expression. Each clause should have the form
((datum1 ...) expression1 expression2 ...)

where each datum is an external representation of some object. The last clause may be of the form

(else expression1 expression2 ...)

A case expression is evaluated by first evaluating the key. The resulting value is compared against each of the datums using the equality predicate eqv?, and if a match is found, the expression following the matching datum is evaluated and the result of the last expression is returned as the result of the case expression.

Should no clause match and an else clause is present, that clause is chosen and the expressions following the else are evaluated in order to compute the result of the case expression.

Syntax: do ((variable1 init1 step1) ...) (test expression ...) command ...
do is an iteration construct. First, all variables are bound to the values of their corresponding init values. Then the test expression is evaluated and if the value is false, the commands are evaluated in order. After each iteration, the variables are bound to the result of evaluating the corresponding step expressions and the test is evaluated again. The loop terminates as soon as the test evaluates to a true value. Then the expressions after the test are evaluated in order and the value of the last expression is returned as the value of the do expression.

Syntax: begin command ...
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 command is given.

Syntax: let ((variable expression) ...) command ...
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 let, the variables are not visible to expressions, because the variables are bound after all the expressions are evaluated.

Syntax: let variable ((variable1 expression) ...) command ...
The named-let construct is used to implement looping constructs. variable is bound to a lambda expression which takes the variables as its formal parameters and then calls the expression with actual parameters set to the expressions. The body of the let can than refer to variable by calling it recursively as a function.

Syntax: let* ((variable expression) ...) command ...
Works like let, but the expressions are evaluated in left-to-right order where each variable is visible to the expression on its right.

Syntax: letrec ((variable expression) ...) command ...
Works like let, but the variables are visible to all expressions, thus making possible mutual recursive procedures.

Syntax: lambda (variable1 ...) command ...
Syntax: lambda (variable1 ... . variablen) command ...
Syntax: lambda variable command ...
Lambda is used to define procedures. The variables are the formal parameters to which actual parameters will be bount. When the procedure is called, the actual parameters are bound and the 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 variables are given, the second takes at least as many actual arguments as arguments before the dot are given and binds 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 variable.

Syntax: and expression ...
and evaluates all expressions in order, but stops evaluation as soon as one of the expressions returns a false value. Returns #f if any of the expressions returns #f and returns the result of the last expression otherwise. When called without arguments, #t is returned.

Syntax: or expression ...
and evaluates all expressions in order, but stops evaluation as soon as one of the expressions returns a non-false value. Returns #f if none of the expressions returns #t and returns the result of the first expression returning a non-false value otherwise. When called without arguments, #f is returned.

Syntax: delay expression
Delays the evaluation of expression. Returns a promise, which when later forced by a call to force will evaluate expression and return the result. Evaluation is performed in the same environment in which the promise was created.

Macro: when test body ...
Evaluates all expressions in body, but only if test evaluates to a true value. If called without arguments, #f is returned, if only called with a test argument, the value of the test is returned, otherwise the value of the last expression in body is returned.

This macro is not supported when the option -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

Macro: unless test body ...
Evaluates all expressions in body, but only if test evaluates to #f. If called without arguments, #f is returned, if only called with a test argument, the value of the test is returned, otherwise the value of the last expression in body is returned.

This macro is not supported when the option -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

Macro: false-if-exception expr
Evaluates expr and returns the result. If an exception occurs while evaluating expr, it is caught and #f is returned.

This macro is not supported when the option -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

Macro: while test body ...
Evaluates the body expressions as long as test evaluates to a true value. test is always evaluated before the body expressions. Returns #f if no call to break occurs inside of body, otherwise the value given to break is returned.

This macro is not supported when the option -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

Library procedure: break val
This is not a syntactic form, but is closely related to while, so it was put in this section. break is only defined inside of a while body. When called, it aborts the innermost while loop and lets it return val.

This macro is not supported when the option -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

Library procedure: continue
Like break, this is not a syntactic form, but is closely related to while, so it was put in this section. continue is only defined inside of a 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 -n, --no-system-init-file is passed to the interpreter, or if the system startup file is not found.

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

Standard Data Types

The following data types are implementd in Sizzle, including most standard procedures for manipulating objects of these types.

Whole numbers
Real numbers
Lists
Vectors
Strings
Characters
Boolean values

The numerical tower is not fully implemented, not available are the number types:

Rational numbers
Complex numbers

Standard Procedures

These are the standard procedures defined in Sizzle.

Supported Syntax

quote, quasiquote, unquote, unquote-splicing, lambda, if, cond, case, set!, and, or, do, let, let*, letrec, begin, define

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, ..., 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?

Partly implemented

load
Implemented in the startup file `init.scm', but Sizzle has a builtin primitive procedure primitive-load, which works like load as defined in R5RS. The Scheme procedure load in Sizzle searches all directories listed in the variable %load-path as well as the current directory if the given filename is not absolute.
real-part imag-part magnitude angle
These work for integers and reals only, because complex numbers are not supported.
denominator numerator
These work for integers only, because rational numbers are not supported.
let-syntax letrec-syntax syntax-rules define-syntax
These are implemented, but are only usable for simple pattern-based macro substitution because they are not hygienic. Also vector patterns/templates are not allowed.
call-with-current-continuation
Only for escape procedures.

Not supported

rationalize, make-rectangular, make-polar

Glossary

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.
boolean
Data type. Boolean values can be either #t (true) or #f (false).
catch
Exceptions can be handled by catching them using the procedure catch.
character
Data type. Characters are used to construct strings and are written like this: #\t.
cons cell
Heap cell with one arbitrary value in both car and cdr.
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: (a . b).
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.
error
An error is signalled when an evaluation cannot be performed correctly.
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 catch form.
fixnum
An integer value which can be stored in a tagged pointer. 29-bit two-complement value.
heap
Memory area where all non-immediate values are allocated.
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).
integer
Data type. Numeric type which can hold exact integer values.
list
Data type. A list is made out of chained cons cells.
long int
Integer that does not fix into a fixnum. Value range is the same as a C int variable.
multiple values
Scheme supports returning multiple values from procedures. Multiple values are produced using the syntactic form values.
port
Object from which data can be read or to which data can be written. File ports or string ports for example.
real number
A number with (possibly) infinite decimal places like pi or e.
regexp
Short for regular expression.
string
Data type. A string is a sequence of characters.
symbol
Data type. Symbols are values which can have a value attached.
syntactic form
Element of the syntax which looks like a function call but acts differently. The if or lambda forms are examples of syntactic forms.
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.
thunk
A thunk is a procedure without arguments.
vector
Data type. Used to hold a fixed number of other values with constant access time.

Index

Jump to: ! - % - * - + - - - . - / - 1 - < - = - > - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v - w - x - z

!

  • !=
  • %

  • %dlcall
  • %dlclose
  • %dlopen
  • %dlsym
  • %eval-time-taken%
  • %load-path
  • %max-evaluate-stack%
  • %print-backtrace%
  • %print-backtrace-limit%
  • %print-func-bodies%
  • %print-memoized%
  • %print-read%
  • %print-result%
  • %read-delimited!
  • %save-backtrace%
  • %sizzle-major-version%
  • %sizzle-minor-version%
  • %sizzle-patchlevel%
  • %sizzle-version%
  • %write-history-file%
  • *

  • *
  • +

  • +
  • -

  • -
  • .

  • ...
  • /

  • /
  • 1

  • 1+
  • 1-
  • <

  • <
  • <=
  • =

  • =
  • >

  • >
  • >=
  • a

  • abs
  • accept
  • access?
  • acos
  • add1
  • alist-cons
  • alist-copy
  • alist-delete
  • alist-delete!
  • and
  • angle
  • any
  • append
  • append!
  • append-map
  • append-map!
  • append-reverse
  • append-reverse!
  • apply
  • apply-macro
  • apropos
  • ash
  • asin
  • assoc
  • assq
  • assv
  • atan, atan
  • autoload
  • b

  • backtrace
  • basename
  • begin
  • bind
  • boolean->integer
  • boolean?
  • break, break
  • break!
  • c

  • caar
  • cadr
  • call-with-current-continuation
  • call-with-input-file
  • call-with-input-string
  • call-with-output-file
  • call-with-output-string
  • call-with-values
  • call/cc
  • car
  • car+cdr
  • case
  • catch
  • cdddar
  • cddddr
  • cdr
  • ceiling
  • char->integer
  • char-alphabetic?
  • char-ci<
  • char-ci<=
  • char-ci=
  • char-ci>
  • char-ci>=
  • char-downcase
  • char-lower-case?
  • char-numeric?
  • char-ready?, char-ready?
  • char-upcase
  • char-upper-case?
  • char-whitespace?
  • char<
  • char<=
  • char=
  • char>
  • char>=
  • char?
  • chdir
  • chmod
  • chown
  • circular-list
  • circular-list?
  • cleanup-filename
  • close
  • close-input-port
  • close-output-port
  • close-port
  • closedir
  • closure?
  • command-line
  • complex?
  • concatenate
  • concatenate!
  • cond
  • connect
  • cons
  • cons*
  • continue
  • copy-file
  • cos
  • count
  • current-environment
  • current-error-port
  • current-input-port
  • current-module
  • current-output-port
  • current-time
  • d

  • define, define, define, define
  • define-constant
  • define-macro
  • define-module
  • define-syntax
  • defined?
  • delay
  • delete
  • delete!
  • delete-duplicates
  • delete-duplicates!
  • denominator
  • describe
  • directory-files
  • directory-stream?
  • dirname
  • display, display
  • dl-error
  • do
  • documentation
  • dotted-list?
  • drop
  • drop-right
  • drop-right!
  • drop-while
  • dynamic-wind
  • e

  • eighth
  • eof-object?
  • eq?
  • equal?
  • eqv?
  • error
  • eval, eval
  • even?
  • every
  • exact->inexact
  • exact?
  • execl
  • execle
  • execlp
  • exit, exit
  • exp
  • expand-macro
  • export
  • expt
  • f

  • false-if-exception
  • fcntl
  • fifth
  • fileno
  • filter
  • filter!
  • filter-map
  • find
  • find-tail
  • first
  • floor
  • fold
  • for-each
  • force
  • force-output
  • fork
  • form?
  • fourth
  • fsync
  • ftell
  • g

  • garbage-collect
  • gc-message
  • gc-stats
  • gcd
  • gensym
  • get-output-string
  • getcwd
  • getdomainname
  • getegid
  • getenv
  • geteuid
  • getgid
  • getgroups
  • gethostbyname
  • gethostname
  • getpeername
  • getpgid
  • getpgrp
  • getpid
  • getppid
  • getpwnam
  • getpwuid
  • getsockname
  • getuid
  • gmtime
  • h

  • hash
  • hash-create-handle!
  • hash-fold
  • hash-get-handle
  • hash-ref
  • hash-remove!
  • hash-set!
  • hashq
  • hashq-create-handle!
  • hashq-get-handle
  • hashq-ref
  • hashq-remove!
  • hashq-set!
  • hashv
  • hashv-create-handle!
  • hashv-get-handle
  • hashv-ref
  • hashv-remove!
  • hashv-set!
  • htonl
  • htons
  • i

  • if
  • imag-part
  • inet-aton
  • inet-ntoa
  • inexact->exact
  • inexact?
  • input-port?
  • integer->boolean
  • integer->char
  • integer?
  • interaction-environment
  • iota
  • isatty?
  • k

  • keyword-table
  • kill
  • l

  • lambda, lambda, lambda
  • last
  • last-pair
  • lcm
  • length
  • length+
  • let, let
  • let*
  • let-syntax
  • letrec
  • letrec-syntax
  • link
  • list
  • list->string
  • list->TAGvector
  • list->vector
  • list-copy
  • list-index
  • list-ref
  • list-tabulate
  • list-tail
  • list=
  • list?
  • listen
  • load
  • load-library
  • localtime
  • log
  • logand
  • logior
  • lognot
  • logxor
  • long?
  • lset-adjoin
  • lset-diff+intersection
  • lset-diff+intersection!
  • lset-difference
  • lset-difference!
  • lset-intersection
  • lset-intersection!
  • lset-union
  • lset-union!
  • lset-xor
  • lset-xor!
  • lset<=
  • lset=
  • lsh
  • lstat
  • m

  • magnitude
  • make-hash
  • make-list
  • make-regexp
  • make-string, make-string
  • make-TAGvector
  • make-vector, make-vector
  • map
  • map!
  • map-in-order
  • max
  • member
  • memq
  • memv
  • min
  • module-list
  • modulo
  • n

  • negative?
  • network-error
  • newline, newline
  • nice
  • ninth
  • not
  • not-pair?
  • ntohl
  • ntohs
  • null-environment
  • null-list?
  • null?
  • number->string, number->string
  • number?
  • numerator
  • o

  • object->string
  • odd?
  • open-fdes
  • open-input-file
  • open-input-string
  • open-output-file
  • open-output-string
  • opendir
  • or
  • output-port?
  • p

  • pair-fold
  • pair-for-each
  • pair?
  • partition
  • partition!
  • peek-char, peek-char
  • port-closed?
  • port-column, port-column
  • port-filename, port-filename
  • port-line, port-line
  • positive?
  • pretty-print
  • primitive-exit
  • primitive-load
  • primitive-load-path
  • primitive-procedure?
  • procedure?
  • profile-stats
  • proper-list?
  • putenv
  • pw:dir
  • pw:gecos
  • pw:gid
  • pw:name
  • pw:passwd
  • pw:shell
  • pw:uid
  • q

  • quasiquote
  • quote
  • quotient
  • r

  • random
  • rational?
  • read, read
  • read-char, read-char
  • read-line
  • readdir
  • readlink
  • real-part
  • real?
  • receive
  • reduce
  • reduce-right
  • regexp-exec
  • regexp?
  • remainder
  • remove
  • remove!
  • rename
  • reverse
  • reverse!
  • reverse-list->string
  • rewinddir
  • round
  • s

  • s8vector->string
  • safe-environment
  • scheme-report-environment
  • second
  • seek
  • select
  • server-loop
  • server-socket
  • set!
  • set-car!
  • set-cdr!
  • set-current-error-port
  • set-current-input-port
  • set-current-output-port
  • set-documentation!
  • set-port-column!
  • set-port-filename!
  • set-port-line!
  • setdomainname
  • setegid
  • seteuid
  • setgid
  • sethostname
  • setuid
  • seventh
  • shutdown
  • signal
  • signum
  • sin
  • sixth
  • sleep
  • socket
  • span
  • span!
  • split-at
  • split-at!
  • sqrt
  • srand
  • stat
  • stat:atime
  • stat:blksize
  • stat:blocks
  • stat:ctime
  • stat:dev
  • stat:gid
  • stat:ino
  • stat:mode
  • stat:mtime
  • stat:nlink
  • stat:perms
  • stat:rdev
  • stat:size
  • stat:type
  • stat:uid
  • strftime
  • string
  • string->list
  • string->number, string->number
  • string->s8vector
  • string->symbol
  • string->u8vector
  • string-any
  • string-append
  • string-chop
  • string-ci<=?
  • string-ci<?
  • string-ci=?
  • string-ci>=?
  • string-ci>?
  • string-contains
  • string-contains-ci
  • string-copy
  • string-count
  • string-downcase
  • string-downcase!
  • string-drop
  • string-drop-right
  • string-every
  • string-fill!
  • string-hash
  • string-hash-ci
  • string-index
  • string-index-right
  • string-join
  • string-length
  • string-null?
  • string-pad
  • string-pad-right
  • string-prefix-ci?
  • string-prefix-length
  • string-prefix-length-ci
  • string-prefix?
  • string-ref
  • string-reverse
  • string-reverse!
  • string-set!
  • string-skip
  • string-skip-right
  • string-split
  • string-suffix-ci?
  • string-suffix-length
  • string-suffix-length-ci
  • string-suffix?
  • string-tabulate
  • string-take
  • string-take-right
  • string-titlecase
  • string-titlecase!
  • string-trim
  • string-trim-both
  • string-trim-right
  • string-upcase
  • string-upcase!
  • string<=?
  • string<?
  • string=
  • string>=?
  • string>?
  • string?
  • strptime
  • sub1
  • substring
  • symbol->string
  • symbol-table
  • symbol?
  • symlink
  • sync
  • syntax-rules
  • sys:creat
  • sys:pipe
  • sys:read
  • sys:read!
  • sys:write
  • system
  • t

  • TAGvector
  • TAGvector->list
  • TAGvector-fill!!
  • TAGvector-length
  • TAGvector-ref
  • TAGvector-set!
  • TAGvector?
  • take
  • take!
  • take-right
  • take-while
  • take-while!
  • tan
  • tenth
  • third
  • throw
  • tilde-expand
  • tm:hour
  • tm:isdst
  • tm:mday
  • tm:min
  • tm:month
  • tm:sec
  • tm:wday
  • tm:yday
  • tm:year
  • tm:zname
  • tm:zoff
  • tmpfile
  • tmpnam
  • toplevel
  • trace
  • transcript-off
  • transcript-on
  • trim-whitespace
  • truncate
  • u

  • u8vector->string
  • umask
  • uname
  • undefine
  • unfold
  • unfold-right
  • unless
  • unlink
  • unquote
  • unquote-splicing
  • unread-char, unread-char
  • unzip1
  • unzip2
  • unzip3
  • unzip4
  • unzip5
  • use-modules
  • utime
  • v

  • values
  • vector
  • vector->list
  • vector-copy
  • vector-fill!
  • vector-length
  • vector-ref
  • vector-set!
  • vector-tabulate
  • vector=
  • vector?
  • w

  • wait
  • waitpid
  • when
  • while
  • with-error-to-file
  • with-error-to-port
  • with-error-to-string
  • with-input-from-file
  • with-input-from-port
  • with-input-from-string
  • with-output-to-file
  • with-output-to-port
  • with-output-to-string
  • write, write
  • write-char, write-char
  • write-line
  • x

  • xcons
  • z

  • zero?
  • zip

  • This document was generated on 6 December 2000 using texi2html 1.56k.