.tr ~
.ds s \fIChez Scheme\fP
.if t .ds c caf\o'\'e'
.if n .ds c cafe
.ds ]W V50794
.TH SCHEME 1 "1/94 Cadence Research Systems"
.SH NAME
\fIChez Scheme\fP \- an incrementally-compiled Scheme system
.SH SYNOPSIS
\fBscheme\fP [ -h \fIfile\fP ] [ -s\fIn\fP \fIfile\fP ] [ \fIfile\fP ... ]
.SH DESCRIPTION
\*s is an implementation of Scheme, a lexically-scoped, applicative-order
dialect of Lisp.  It supports first-class procedures and first-class
continuations.  Tail calls are treated as jumps,
eliminating the need for restrictive special purpose looping constructs.
\*s has a rich set of built-in datatypes including
arbitrary-precision integer and rational numbers, floating point
numbers, complex numbers, characters, strings, lists, vectors, and symbols.
Data objects are allocated in a heap and are automatically reclaimed by the
\*s storage manager.  \*s compiles source expressions \fIincrementally\fP,
providing the speed of compiled code in an interactive system.
.LP
Scheme is normally used interactively.  The system prompts
the user with a right angle bracket (\*(lq>\*(rq) at the beginning of each
input line.  Any Scheme expression may be entered.  The system evaluates
the expression and prints the result.  After printing
the result, the system prompts again for more input.
.LP
The file names on the command line (except for the arguments
to the \*(lq-h\*(rq and \*(lq-s\*(rq switches) are
visited before \*s begins interacting with the user.  Each of the
expressions in the visited files is executed just as if it were
typed by the user in response to a prompt.  If you wish to load a
set of definitions each time, consider setting up a shell script to
load the file \*(lq.schemerc\*(rq from your home directory:
.br
.sp
     scheme ${HOME}/.schemerc $*
.sp
.br
If you have a 
substantial number of definitions to load each time, it might
be worthwhile to compile the .schemerc file (that is, compile
the definitions and name the resulting object file .schemerc)
or to save the definitions in a heap file (see below).
.LP
Typically, a Scheme programmer creates a source file of procedure
definitions and other expressions using an editor (such as
\fIvi\fP(1)) and loads the file into Scheme to test them.  The
conventional filename extension for \*s source files
is \fI.ss\fP.  Such a file may be loaded during a session by typing
(load~\*(lq\fIfilename\fP\*(rq), or by specifying the filename on
the command line as mentioned above.  Any expression that may be
typed interactively may be placed in a file to be loaded.
.LP
\*s compiles source expressions as it sees them.  In
order to speed loading of a large file, the file may be compiled
with the output placed in an object file.
(compile-file~\*(lqfoo\*(rq) compiles the expressions in the file
\*(lqfoo.ss\*(rq and places the resulting object code on the file
\*(lqfoo.so\*(rq. Loading a pre-compiled file is no different from
loading the source file, except that loading is much faster since
compilation is already done.  
.LP
If the \*(lq-s\*(rq option is present and \*s exits normally
(see \fIexit\fP, below), it will save the \fIheap\fP on the
specified file.
The heap contains the entire state of the
system, so that any procedures or other objects created during a
session are retained.  The \*(lq-h\*(rq option specifies the file \*s
will load as the initial heap; it may be used to reload a
previously saved heap.  Saved heaps provide an alternative to
the .schemerc file for customizing the scheme system, as well as
allowing suspension of a session to return to at a later time.
.LP
The digit immediately following the \*(lq-s\*(rq option determines the
heap level; a level zero heap contains the entire heap, a level one heap
contains only those portions that have changed since the level zero heap
was created, and so on.
A level one heap may be created in a session in which a level zero heap has
been loaded, and the level one heap must be loaded with an additional
\*(lq-h\*(rq option:
.br
.sp
     scheme -h ${HOME}/.heap -s1 ${HOME}/.heap.1 $*
     scheme -h ${HOME}/.heap -h ${HOME}/.heap.1 $*
.sp
.br
.LP
In some installations, the \*s executable is a shell script that
automatically loads a level 0 heap containing the base system.
In this case, one would normally choose to save a level 1 heap
rather than a (larger) level 0 heap.
If a level 0 heap is saved, however, a modified version of the
executable shell script that reflects the location of the new heap must
be used to load in the heap.
.LP
It may be useful to use a shell script that always
loads from and saves to a heap file in the home directory.
.br
.sp
     scheme -h ${HOME}/.heap -s0 ${HOME}/.heap $*
.sp
.br
On systems that automatically load a level 0 heap containing the base
system, \*(lq-s1\*(rq should be used in place of \*(lq-s0\*(rq.
The file ${HOME}/.heap must be created prior to the first time
this script is used.
You should be careful to retain the source for important definitions,
since future releases of \*s will not be compatible with existing heaps
or compiled object files.
.LP
You can exit the system by typing the end-of-file character
(normally Control-D) or by using the procedure \fIexit\fP.
Typing Control-D is equivalent to (exit), (exit (void)), or
(exit 0), each of which is considered a \*(lqnormal exit\*(rq.
If the \*(lq-s\*(rq option
is present (see above), a normal exit causes the
system to save the heap in the given file.
.LP
Interaction of the system with the user is performed
by a Scheme program called a \fIwaiter\fP, running in a
program state called a \fI\*c\fP.  The waiter
merely prompts, reads, evaluates, prints and loops
back for more.  It is possible to open up a chain of \*s
\*cs by invoking the \fInew-cafe\fP procedure with no arguments.
New-cafe is also one of the options when an interrupt
occurs.  Each \*c has its own reset and exit procedures.
Exiting from one \*c in the chain returns you to the next one
back, and so on, until the entire chain closes and you leave the
system altogether.  Sometimes it is useful to
interrupt a long computation by typing the interrupt character,
enter a new \*c to execute something (perhaps to check a status
variable set by computation), and exit the \*c back to the old
computation.
.LP
You can tell what level you are at by the number of angle brackets
in the prompt, one for level one, two for level two, and so on.
Three angle brackets in the prompt means you would have to exit from
three \*cs to get out of \*s.  If you wish to abort
from \*s and you are several \*cs deep, the procedure
\fIabort\fP leaves the system directly.
.LP
Running programs may be interrupted by typing the interrupt
character (normally DEL, BREAK or Control-C).   In response, the
system enters a debug handler, which prompts for input with a
\*(lqdebug>\*(rq prompt.
Several commands may be issued to the debug handler, including
\*(lqe\*(rq to exit from the handler and continue,
\*(lqr\*(rq to reset to the current \*c,
\*(lqa\*(rq to abort \*s,
\*(lqn\*(rq to enter a new \*c,
\*(lqi\*(rq to inspect the current continuation, and
\*(lqs\*(rq to display statistics about the interrupted program.
While typing an expression to the waiter, the interrupt character
simply resets to the current \*c.
.LP
When an error occurs, the system prints an error message and
resets.
Typing (debug) after an error occurs places you into the
debug handler, where you can inspect the current continuation (control
stack) to help determine the cause of the problem.
.LP
Complete documentation for \*s is available in two parts:
\fIThe SCHEME Programming Language\fP by R. Kent Dybvig, and
\fIThe Chez Scheme System Manual\fP.
.LP
Several example Scheme programs, ranging from a simple factorial procedure
to a somewhat complex unification algorithm, are in the examples directory
(see FILES below).  Looking at and trying out example programs is a good way
to start learning Scheme.
.SH FILES
.if 0 COMMENT: put the longest path from below in the tab computation:
.ta \w'/usr/local/lib/scheme  'u+1i
/usr/local/bin/scheme	executable file
.br
/usr/local/lib/scheme	example program library
.SH SEE ALSO
.in +5
.br
.ti -5
R. Kent Dybvig,
\fIThe SCHEME Programming Language\fP,
Prentice-Hall (1987).
.br
.ti -5
Cadence Research Systems,
\fIChez Scheme System Manual\fP,
Revision 2.3 (1992).
.br
.ti -5
IEEE Computer Society,
\fIIEEE Standard for the Scheme Programming Language,\fP
IEEE Std 1178-1990 (1991).
.br
.ti -5
Daniel P. Friedman and Matthias Felleisen,
\fIThe Little LISPer\fP, trade edition,
MIT Press (1987).
.br
.ti -5
Harold Abelson and Gerald J. Sussman with Julie Sussman,
\fIStructure and Interpretation  of Computer Programs\fP,
MIT press (1984).
.br
.ti -5
Will Clinger and Jonathan Rees, eds.,
.if t \*(lqRevised\u4\d Report on the Algorithmic Language Scheme,\*(rq
.if n \*(lqRevised^4 Report on the Algorithmic Language Scheme,\*(rq
Lisp Pointers vol. 4, no. 3, 1991.
.in -5
.SH AUTHOR
Cadence Research Systems, Bloomington Indiana