%% -*- LaTeX -*-

\chapter{Scheme Reference}
\label{scmref}

This chapter is a reference manual for the Scheme programming language.  Don't
read this chapter to learn Scheme, but turn to it when you need more detail
about the language than appears in {\em Structure and Interpretation of
Computer Programs}~\cite{SICP}.

\section{Notation and terminology}

This section describes the notation used in this chapter.  It also discusses
the lexical conventions for writing Scheme programs.

\subsection{Notation for this Chapter}
\label{typeconventions}

In this chapter, in text describing a procedure or special form, the names of
all formal parameters are {\it italicized}.  The names of Scheme procedures,
special forms, and variables appear in {\tt typewriter-style type}.
Throughout the chapter, whenever a formal parameter has one of the names
listed in the left column of the table below, it must be of the type listed in
the right column.  For example, a formal parameter refered to as \vrii{n} in
this chapter must be an integer.

\newcommand{\foo}[1]{\vr{#1}, \vri{#1}, $\ldots$ \vrj{#1}, $\ldots$}
$$
\begin{tabular}{ll}
\var{obj}&any object\\
\foo{x}&real number\\
\foo{y}&real number\\
\foo{n}&integer\\
\foo{k}&nonnegative integer\\
\end{tabular}
$$

\subsection{Evaluation}

The symbol ``\evalsto'' in these examples means ``evaluates to.''  For
example,

\begin{scheme}
(* 5 8)      \ev  40%
\end{scheme}

\noindent means that the expression {\tt(* 5 8)} evaluates to {\tt 40}.

\vest Where the value returned by an expression is marked {\em unspecified},
Scheme does not guarantee what the value will be.  For example,

\begin{scheme}
(set! x 3) \ev \unspecified
\end{scheme}

Feel free to experiment to determine what Scheme returns in any particular
case, but remember that a new version of Scheme might return a different
value.  Avoid writing programs that rely on unspecified values, particularly
when working on problem sets.

\subsection{Numbers}
\index{number}

Scheme numbers are expressed exactly as normal numbers, except that scientific
notation looks slightly different.  In Scheme scientific notation, the numbers
of the exponent are not raised, but instead are separated from the base number
by the letter {\tt e}.  For example,

\medskip

\noindent {\tt 123e10} is Scheme notation for $123 \times 10^{10}$, and

\noindent {\tt -123.45e-1} is Scheme notation for $-123.45 \times 10^{-1}$.

\subsection{Identifiers}
\label{identifiersyntax}

A Scheme identifier\mainindex{identifier} is a sequence of letters, digits,
and punctuation characters that is not a number.  Here are some identifiers:

\begin{scheme}
lambda           q        <=?
list->vector     soup     a34kTMNs
{+}                V17a     the-word-recursion-has-many-meanings%
\end{scheme}

\vest Upper and lower case forms of a letter are never distinguished
except within character and string constants.  For example, {\tt Foo}
is the same identifier as {\tt FOO}.

\vest Identifiers have several uses within Scheme programs:
\begin{itemize}
\item Certain identifiers are reserved for use as special forms, and cannot be
used as variables.\index{special form}  They are:

\begin{scheme}
and           else               or
begin         error              quote
cond          if                 sequence
cons-stream   lambda             set!
define        let                the-environment
delay         make-environment   unquote
\end{scheme}

\item Any identifier that does not refer to a special form may be used as a
variable\index{variable} (see section~\ref{variablesection}).

\item When an identifier appears as a quoted constant or within a quoted
constant, it denotes a {\em symbol} (see section~\ref{symbolsection}).

\end{itemize}

\subsection{Whitespace and Comments}

\defining{Whitespace} characters are spaces and line breaks ({\em newlines}).
Whitespace is used to improve readability and to separate \defining{tokens}
(identifiers and numbers) from each other.  Whitespace may also occur inside a
string value.

A semicolon starts a \defining{comment}, text which will be seen as whitespace
by Scheme.  The comment continues from the semicolon to the end of the line.
For example:

\begin{scheme}
;;; The FACT procedure computes the factorial
;;; of a nonnegative integer.
(define fact
  (lambda (n)
    (if (= n 0)
        1        ;Base case: return 1
        (* n (fact (- n 1))))))%
\end{scheme}

\subsection{Special Characters in Scheme Notations}

\newcommand{\inparagraph}[1]{\hbox{}\hfill\parbox[t]{0.95\linewidth}{#1}}

Here are the special characters used in Scheme notations:

\bigskip

%  _ = 5F   & = 26   ~ = 7E   ^ = 5E
\hbox{\tt * / < = > !\ ?\ :\ \$ \% \char"5F{} \char"26{} \char"7E{} \char"5E}
\inparagraph{These characters may be used in identifiers as if they were
letters.}

\noindent {\tt.\ + -} \\
\inparagraph{These appear in numbers and identifiers.  The period character is
also used in the notation for pairs (section~\ref{listsection}).}

\noindent {\tt( )} \\
\inparagraph{Parentheses surround expressions and lists
(section~\ref{listsection}).}

\noindent \singlequote \\
\inparagraph{The single quote character indicates literal data
(section~\ref{quote}).}

\noindent {\tt"} \\
\inparagraph{Double quote characters surround string values
(section~\ref{stringsection}).}

\noindent \backwhack \\
\inparagraph{Backslash is an escape character within string constants
(section~\ref{stringsection}).}

\hbox{\tt \char"5B{} \char"5D{} \char"7B{} \char"7D}
\inparagraph{Left and right square brackets and curly braces are reserved for
possible future extensions to the language.}

\noindent \schtrue{} \schfalse{} \\
\inparagraph{These are the boolean constants true and false
(section~\ref{booleansection}).}

\noindent \sharpsign\backwhack \\
\inparagraph{Represents the ASCII standard number representing the immediately
following character.}

\noindent {\tt \sharpsign(} \\
\inparagraph{Introduces a vector constant (section~\ref{vectorsection}).}

\section{Variables and bindings}
\label{variablesection}

\vest Any identifier that does not refer to a special
form\index{specialform} (see section~\ref{identifiersyntax}) may be
used as a variable.\index{identifier}\mainindex{variable} A variable
may name a location where a value can be stored.  A variable that does
so is said to be {\em bound} to the location.  The set of all
bindings\mainindex{binding} in effect at some point in a program is
the {\em environment}.

\vest Certain expressions create new locations and bind variables to them.
The most fundamental of these \defining{binding constructs}\mainindex{binding
construct} is the \lambdaexp{}\index{\lambdaexp{}}, because all other binding
constructs can be explained in terms of \lambdaexp{}s.  See
section~\ref{bindingconstructs}.

\vest Like Algol and Pascal, and unlike most other dialects of Lisp
except Common Lisp, Scheme is statically scoped and has block structure.  To
each place where a variable is bound in a program there corresponds a
\defining{region} of the program text within which the binding is effective.
The region is determined by the particular binding construct that establishes
the binding; if the binding is established by a \lambdaexp{}, for example,
then its region is the entire \lambdaexp{}.  Every reference to or assignment
of a variable refers to the binding of the variable that established the
innermost of the regions containing the use.  If there is no binding of the
variable whose region contains the use, then the use refers to the binding for
the variable in the top level environment; if there is no binding for the
identifier, it is said to be \defining{unbound}.\mainindex{bound}\index{top
level environment}


\section{Expressions}
\label{expressionchapter}

A Scheme expression is a piece of code that returns a value.  Types of
expressions include variable references, literals, procedure calls, and
special forms (see section~\ref{identifiersyntax}).  This section describes
all Scheme expression types except conditionals and logical operations, which
are described in section~\ref{booleansection}.

\subsection{Variable references}\unsection

\begin{entry}{%
\pproto{\hyper{variable}}{ \exprtype}}

An expression consisting of a variable\index{variable}
(section~\ref{variablesection}) is a variable reference.  The value of
the variable reference is the value stored in the location to which the
variable is bound.  It is an error to reference an
unbound\index{unbound} variable.

\begin{scheme}
(define x 28)
x   \ev  28%
\end{scheme}
\end{entry}

\subsection{Literals}\unsection
\label{literalsection}

\begin{entry}{%
\proto{quote}{ \hyper{datum}}{ \exprtype}
\pproto{\singlequote\hyper{datum}}{ \exprtype}
\pproto{\hyper{constant}}{ \exprtype}}

{\cf (quote \hyper{datum})} evaluates to \hyper{datum}.  \hyper{Datum}
may be any printed representation of a Scheme object.  This notation
is used to include literal constants in Scheme code.

\begin{scheme}%
(quote a)                     \ev  a
(quote \sharpsign(a b c))     \ev  \#(a b c)
(quote (+ 1 2))               \ev  (+ 1 2)%
\end{scheme}

{\cf (quote \hyper{datum})} may be abbreviated as
\singlequote\hyper{datum}.  The two notations are equivalent in all
respects.

\begin{scheme}
'a                   \ev  a
'\#(a b c)           \ev  \#(a b c)
'(+ 1 2)             \ev  (+ 1 2)
'(quote a)           \ev  (quote a)
''a                  \ev  (quote a)%
\end{scheme}

Numeric constants, string constants, character constants, and boolean
constants evaluate ``to themselves''; they need not be quoted.

\begin{scheme}
'"abc"     \ev  "abc"
"abc"      \ev  "abc"
'145932    \ev  145932
145932     \ev  145932
'\schtrue  \ev  \schtrue
\schtrue   \ev  \schtrue%
\end{scheme}

\end{entry}


\subsection{Procedure calls}\unsection

\begin{entry}{%
\pproto{(\hyper{operator} \hyperi{operand} \dotsfoo)}{ \exprtype}}

A procedure call is written by enclosing in parentheses
expressions for the procedure to be called and the arguments to be
passed to it.  The operator and operand expressions are evaluated (in an
indeterminate order) and the resulting procedure is passed the resulting
arguments.\mainindex{call}\mainindex{procedure call}
\begin{scheme}%
(+ 3 4)                          \ev  7
((if \schfalse + *) 3 4)         \ev  12%
\end{scheme}


Procedure calls are also called {\em combinations}.
\mainindex{combination}

\end{entry}


\subsection{Lambda expressions}\unsection
\label{lambda}

\begin{entry}{%
\proto{lambda}{ \hyper{formals} \hyper{body}}{ \exprtype}}

\syntax
\hyper{Formals} should be a formal arguments list as described below,
and \hyper{body} should be a sequence of one or more expressions.

\semantics
\vest A \lambdaexp{} evaluates to a procedure.  The environment in
effect when the \lambdaexp{} was evaluated is remembered as part of the
procedure.  When the procedure is later called with some actual
arguments, the environment in which the \lambdaexp{} was evaluated will
be extended by binding the variables in the formal argument list to
fresh locations, the corresponding actual argument values will be stored
in those locations, and the expressions in the body of the \lambdaexp{}
will be evaluated sequentially in the extended environment.  The result
of the last expression in the body will be returned as the result of
the procedure call.

\begin{scheme}
(lambda (x) (+ x x))      \ev  {\em{}a procedure}
((lambda (x) (+ x x)) 4)  \ev  8

(define reverse-subtract
  (lambda (x y) (- y x)))
(reverse-subtract 7 10)         \ev  3

(define foo
  (let ((x 4))
    (lambda (y) (+ x y))))
(foo 6)                         \ev  10%
\end{scheme}

\hyper{Formals} should have one of the following forms:

\begin{itemize}
\item {\tt(\hyperi{variable} \dotsfoo)}:
The procedure takes a fixed number of arguments; when the procedure is
called, the arguments will be stored in the bindings of the
corresponding variables.

\item \hyper{variable}:
The procedure takes any number of arguments; when the procedure is
called, the sequence of actual arguments is converted into a newly
allocated list, and the list is stored in the binding of the
\hyper{variable}.

\item {\tt(\hyperi{variable} \dotsfoo{} \hyper{variable$_{n-1}$} {\bf.}\
\hypern{variable})}:
If a period surrounded by spaces precedes the last variable, then the value
stored in the binding of the last variable will be a list of the actual
arguments left over after all the other actual arguments have been matched up
against the formal arguments.
\end{itemize}

\begin{scheme}
((lambda x x) 3 4 5 6)          \ev  (3 4 5 6)
((lambda (x y . z) z)
 3 4 5 6)                       \ev  (5 6)%
\end{scheme}

\end{entry}

\subsection{Binding constructs}
\label{bindingconstructs}

The binding construct \ide{let} gives Scheme a block structure, like Algol 60.
The syntax of the three constructs is identical, but they differ in the
regions\index{region} they establish for their variable bindings.  In a {\tt
let} expression, the initial values are computed before any of the variables
become bound.

\begin{entry}{%
\proto{let}{ \hyper{bindings} \hyper{body}}{\exprtype}}

\syntax
\hyper{Bindings} should have the form
\begin{scheme}
((\hyperi{variable} \hyperi{init}) \dotsfoo)\rm,%
\end{scheme}
where each \hyper{init} is an expression, and \hyper{body} should be a
sequence of one or more expressions.

\semantics
The \hyper{init}s are evaluated in the current environment (in some
unspecified order), the \hyper{variable}s are bound to fresh locations
holding the results, the \hyper{body} is evaluated in the extended
environment, and the value of the last expression of \hyper{body} is
returned.  Each binding of a \hyper{variable} has \hyper{body} as its
region.\index{region}

\begin{scheme}
(let ((x 2) (y 3))
  (* x y))                      \ev  6

(let ((x 2) (y 3))
  (let ((foo (lambda (z) (+ x y z)))
        (x 7))
    (foo 4)))                   \ev  9%
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{let}{ \hyper{variable} \hyper{bindings} \hyper{body}}{\exprtype}}

\label{namedlet}
This is an extension of the syntax of {\tt let}, called ``named
{\tt let}'' which provides a general looping construct and which may
also be used to express recursions.\index{named {\tt let}}

Named {\tt let} has the same syntax and semantics as ordinary {\tt let}
except that \hyper{variable} is bound within \hyper{body} to a procedure
whose formal arguments are the bound variables and whose body is
\hyper{body}.  Thus the execution of \hyper{body} may be repeated by
invoking the procedure named by \hyper{variable}.

%                                              |  <-- right margin
\begin{scheme}
(let loop ((numbers '(3 -2 1 6 -5))
           (nonneg '())
           (neg '()))
  (cond ((null? numbers) (list nonneg neg))
        ((>= (car numbers) 0)
         (loop (cdr numbers)
               (cons (car numbers) nonneg)
               neg))
        ((< (car numbers) 0)
         (loop (cdr numbers)
               nonneg
               (cons (car numbers) neg))))) %
  \lev  ((6 1 3) (-5 -2))%
\end{scheme}

\end{entry}


\subsection{Assignments}\unsection

\begin{entry}{%
\proto{set!}{ \hyper{variable} \hyper{expression}}{ \exprtype}}

\hyper{Expression} is evaluated, and the resulting value is stored in
the location to which \hyper{variable} is bound.  \hyper{Variable} must
be bound in some region\index{region} or at top level.  The result of
the {\tt set!} expression is unspecified.

\begin{scheme}
(define x 2)            \ev  \unspecified
(+ x 1)                 \ev  3
(set! x 4)              \ev  \unspecified
(+ x 1)                 \ev  5%
\end{scheme}

\end{entry}


\subsection{Sequencing}\unsection

\begin{entry}{%
\proto{sequence}{ \hyperi{expression} \hyperii{expression} \dotsfoo}{ \exprtype}}

The \hyper{expression}s are evaluated sequentially from left to right,
and the value of the last \hyper{expression} is returned.  This
expression type is used to sequence side effects such as input and
output.

\begin{scheme}
(sequence (set! x 5)
	  (+ x 1))                  \ev  6

(sequence (princ "4 plus 1 equals ")
	  (princ (+ 4 1)))      \ev  \unspecified
 \>{\em and prints}  4 plus 1 equals 5%
\end{scheme}

\begin{note}
{\tt Sequence} is a synonym for the {\tt begin} sequencing construct of the Scheme standard.
\end{note}

\end{entry}

\section{Definitions}

Definitions are used to establish bindings.  Definitions are not valid
in all contexts where expressions are allowed.  They are valid only at
the top level of a \hyper{program} and at the beginning of a
\hyper{body}.

A definition should have one of the following forms:\mainschindex{define}

\begin{itemize}

\item {\tt(define \hyper{variable} \hyper{expression})} \\

\item{\tt(define (\hyper{variable} \hyper{formals}) \hyper{body})} \\
\hyper{Formals} should be either a
sequence of zero or more variables, or a sequence of one or more variables
followed by a period surrounded by spaces and another variable (as in a lambda
expression).  This form is equivalent to
\begin{scheme}
(define \hyper{variable}
  (lambda (\hyper{formals}) \hyper{body}))\rm.%
\end{scheme}

\item{\tt(define (\hyper{variable} . \hyper{formal}) \hyper{body})} \\
\hyper{Formal} should be a single
variable.  This form is equivalent to
\begin{scheme}
(define \hyper{variable}
  (lambda \hyper{formal} \hyper{body}))\rm.%
\end{scheme}

\end{itemize}

\subsection{Top level definitions}

At the top level of a program, a definition
\begin{scheme}
(define \hyper{variable} \hyper{expression})%
\end{scheme}
\noindent
has essentially the same effect as the assignment expression
\begin{scheme}
(set! \hyper{variable} \hyper{expression})%
\end{scheme}
\noindent
if \hyper{variable} is bound.  If \hyper{variable} is not bound,
however, then the definition will bind \hyper{variable} to a new
location before performing the assignment, whereas it would be an error
to perform a {\tt set!}\ on an unbound\index{unbound} variable.

\begin{scheme}
(define add3
  (lambda (x) (+ x 3)))
(add3 3)                            \ev  6
(define first car)
(first '(1 2))                      \ev  1%
\end{scheme}

\subsection{Internal definitions}
\label{internaldefines}

Definitions are also permitted at the beginning of a \hyper{body} (that is,
the body of a {\tt lambda}, {\tt let}, or {\tt define} expression).  Such
definitions are known as {\em internal definitions} \mainindex{internal
definition} as opposed to the top level definitions described above.  The
variable defined by an internal definition is local to the
\hyper{body}.  That is, \hyper{variable} is bound rather than assigned,
and the region of the binding is the entire \hyper{body}.  For example,

\begin{scheme}
(let ((x 5))
  (define foo (lambda (y) (bar x y)))
  (define bar (lambda (a b) (+ (* a b) a)))
  (foo (+ x 3)))                \ev  45%
\end{scheme}


\section{Booleans and conditionals}
\label{booleansection}

The standard boolean objects for true and false are written as
\schtrue{} and \schfalse.\sharpindex{true}\sharpindex{false}  \ide{t} and
\ide{nil} are alternative ways of writing \schtrue{} and \schfalse,
respectively.  What really matters, though, are the objects that the Scheme
conditional expressions ({\tt if}, {\tt cond}, {\tt and}, {\tt or}) treat as
true\index{true} or false\index{false}.  The phrase ``a true value'' (or
sometimes just ``true'') means any object treated as true by the conditional
expressions, and the phrase ``a false value'' (or ``false'') means any object
treated as false by the conditional expressions.

\vest Of all the standard Scheme values, only \schfalse{} and the
empty list\index{empty list} () count as false in conditional expressions.
Everything else, including \schtrue, pairs, symbols, numbers, strings,
vectors, and procedures, counts as true.

\vest Boolean constants evaluate to themselves, so they don't need to be quoted
in programs.

\begin{scheme}
\schtrue         \ev  \schtrue
\schfalse        \ev  \schfalse
'\schfalse       \ev  \schfalse%
\end{scheme}

\begin{entry}{%
\vproto{true}{variable}
\vproto{false}{variable}}

The variables {\tt true} and {\tt false} are initially bound to the
values \schtrue{} and \schfalse{} respectively.  Note that these are
ordinary variables, whereas {\tt true} and {\tt false} are constants.

\begin{scheme}
true             \ev  \schtrue
false            \ev  \schfalse
'false           \ev  false
\end{scheme}

\end{entry}


\subsection{Boolean operations}

\begin{entry}{%
\proto{not}{ obj}{procedure}}

{\tt Not} returns \schtrue{} if \var{obj} is false, and returns
\schfalse{} otherwise.

\begin{scheme}
(not \schtrue)   \ev  \schfalse
(not 3)          \ev  \schfalse
(not (list 3))   \ev  \schfalse
(not \schfalse)  \ev  \schtrue
(not '())        \ev  \schtrue
(not (list))     \ev  \schtrue
\end{scheme}

\end{entry}



\begin{entry}{%
\proto{and}{ \hyperi{test} \dotsfoo}{\exprtype}}

The \hyper{test} expressions are all evaluated.  {\tt And} returns \schfalse{}
if any of its arguments is false, and \schtrue{} otherwise.

\begin{scheme}
(and (< 3 4) (> 6 5))	\ev  \schtrue
(and (> 3 4) (> 6 5))	\ev  \schfalse
(and)			\ev  \schtrue \hfill ; by convention
\end{scheme}

\end{entry}



\begin{entry}{%
\proto{or}{ \hyperi{test} \dotsfoo}{\exprtype}}

The \hyper{test} expressions are all evaluated.  {\tt Or} returns \schtrue{}
if any of its arguments is true, and \schfalse{} otherwise.

\begin{scheme}
(or (eq? 'x 'y) (eq? 'z 'y))	\ev  \schfalse
(or (> x 0) (= x 0) (< x 0))	\ev  \schtrue
(or)				\ev  \schfalse \hfill ; by convention
\end{scheme}

\end{entry}



\begin{entry}{%
\proto{conjunction}{ \hyperi{test} \dotsfoo}{\exprtype}}

The \hyper{test} expressions are evaluated from left to right, and the
value of the first expression that evaluates to a false value is
returned.  Any remaining expressions are not evaluated.  If all the
expressions evaluate to true values, the value of the last expression
is returned.  If there are no expressions then \schtrue{} is returned.

\begin{scheme}
(conjunction (= 2 2) (> 2 1))           \lev  \schtrue
(conjunction (= 2 2) (< 2 1))           \lev  \schfalse
(conjunction 1 2 'c '(f g))             \lev  (f g)
(conjunction)                           \lev  \schtrue%
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{disjunction}{ \hyperi{test} \dotsfoo}{\exprtype}}

The \hyper{test} expressions are evaluated from left to right, and the
value of the first expression that evaluates to a true value is
returned.  Any remaining expressions are not evaluated.  If all
expressions evaluate to false values, the (false) value of the last
expression is returned.  If there are no expressions then \schfalse{}
is returned.

\begin{scheme}
(disjunction (= 2 2) (> 2 1))		\lev  \schtrue
(disjunction (= 2 2) (< 2 1))		\lev  \schtrue
(disjunction \schfalse \schfalse \schfalse) \lev  \schfalse
(disjunction (memq 'b '(a b c)) 
	     (/ 3 0))			\lev  (b c)
(disjunction)				\lev \schfalse%
\end{scheme}

\end{entry}

\subsection{Conditionals}\unsection

\begin{entry}{%
\proto{if}{ \hyper{test} \hyper{consequent} \hyper{alternate}}{ \exprtype}
\proto{if}{ \hyper{test} \hyper{consequent}}{\exprtype}}  %\/ if hyper = italic

\syntax
\hyper{Test}, \hyper{consequent}, and \hyper{alternate} may be arbitrary
expressions.

\semantics
An {\tt if} expression is evaluated as follows: first,
\hyper{test} is evaluated.  If it yields a true value\index{true} (see
section~\ref{booleansection}), then \hyper{consequent} is evaluated and
its value is returned.  Otherwise \hyper{alternate} is evaluated and its
value is returned.  If \hyper{test} yields a false value and no
\hyper{alternate} is specified, then the result of the expression is
unspecified.

\begin{scheme}
(if (> 3 2) 'yes 'no)           \ev  yes
(if (> 2 3) 'yes 'no)           \ev  no
(if (> 3 2)
    (- 3 2)
    (+ 3 2))                    \ev  1%
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{cond}{ \hyperi{clause} \hyperii{clause} \dotsfoo}{ \exprtype}}

\syntax
Each \hyper{clause} should be of the form
\begin{scheme}
(\hyper{test} \hyper{expression} \dotsfoo)%
\end{scheme}
where \hyper{test} is any expression.  The last \hyper{clause} may be
an ``else clause,'' which has the form
\begin{scheme}
(else \hyperi{expression} \hyperii{expression} \dotsfoo)\rm.%
\end{scheme}
\mainschindex{else}
\mainschindex{=>}

\semantics
A {\tt cond} expression is evaluated by evaluating the \hyper{test}
expressions of successive \hyper{clause}s in order until one of them
evaluates to a true value\index{true} (see
section~\ref{booleansection}).  When a \hyper{test} evaluates to a true
value, then the remaining \hyper{expression}s in its \hyper{clause} are
evaluated in order, and the result of the last \hyper{expression} in the
\hyper{clause} is returned as the result of the entire {\tt cond}
expression.  If the selected \hyper{clause} contains only the
\hyper{test} and no \hyper{expression}s, then the value of the
\hyper{test} is returned as the result.  If all \hyper{test}s evaluate
to false values, and there is no else clause, then the result of
the conditional expression is unspecified; if there is an else
clause, then its \hyper{expression}s are evaluated, and the value of
the last one is returned.

\begin{scheme}
(cond ((> 3 2) 'greater)
      ((< 3 2) 'less))         \ev  greater%

(cond ((> 3 3) 'greater)
      ((< 3 3) 'less)
      (else 'equal))            \ev  equal%
\end{scheme}

\end{entry}


\subsection{Testing for equivalence}
\label{equivalencesection}

The three predicates described in this section are used to test
whether objects are ``the same''.  Of the three predicates, {\tt eq?}\
is the finest or most discriminating while {\tt equal?}\ is the
coarsest. {\tt Eqv?}\ is slightly less discriminating than {\tt eq?}.
In general, you should use {\tt equal?} to test the equivalence of
structures and {\tt eqv?} to test the equivalence of atomic objects.
See~\cite{RRRS} for a careful description of the rationale for these
three different predicates.

\begin{entry}{%
\proto{eq?}{ \vari{obj} \varii{obj}}{procedure}}

\ide{Eq?}\ is the primitive equivalence predicate.  It returns true if
\vari{obj} and \varii{obj} are the same object.  Unless you are rather
advanced, do not use \ide{eq?} to test identity of objects other than symbols.
In particular, two numbers which are equal in value may not be \ide{eq?}; use
\ide{=} or \ide{eqv?} to test numerical equality.  Also, two lists which have
the same elements and print the same may not be \ide{eq?}; use \ide{equal?} to
test if lists have the same elements.

For more advanced users only: Two structures are \ide{eq?} if any attempt to
modify one of them modifies the other in the same way; i.e., if the two
structures share the same location in memory (see chapter 3 of the 6.001 text).

\begin{scheme}
(define x '(a b))		\ev X
(define y '(a b))		\ev Y
(define z x)			\ev Z
(eq? x y)			\ev \schfalse
(eq? x z)			\ev \schtrue
(eq? y z)			\ev \schfalse
(set! x 'foo)			\ev \unspecified
(set! y 'foo)			\ev \unspecified
(set! z x)			\ev \unspecified
(eq? x y)			\ev \schtrue
(eq? x z)			\ev \schtrue
(eq? y z)			\ev \schtrue%
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{eqv?}{ \vari{obj} \varii{obj}}{procedure}}

\ide{Eqv?}\ returns \schtrue if \vari{obj} and \varii{obj} are: \ide{eq?} atoms,
\ide{=} numbers, or character strings containing the same characters in the
same order with the same capitalization.  Two lists are not in general 
\ide{eqv?} even if \ide{eq?} atom by atom.  \ide{Eqv?}\ is usually the correct
predicate for testing the equality of atoms.

\begin{scheme}
(eqv? "abc" "abc")		 \ev \schtrue
(eqv? '(a b c) '(a b c))	 \ev \schfalse
(eqv? 67000 67000)		 \ev \schtrue

(let ((a '(1 2 3)))
  (let ((b (cons a a)))
    (eqv? (car b) (cdr b))))     \ev  \schtrue

(eqv? (lambda () 1)
      (lambda () 1))              \ev  \schfalse

(let ((p (lambda () 1)))
  (eqv? p p))                     \ev  \schtrue%
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{equal?}{ \vari{obj} \varii{obj}}{procedure}}

\ide{Equal?}\ returns \schtrue\ if both arguments are \ide{eqv?} atoms,
numbers, or character strings.  \ide{Equal?} list structures are those whose
\ide{CAR}s are \ide{equal?} and whose \ide{CDR}s are \ide{equal?}.  As
illustrated below, \ide{eq?} and \ide{equal?} are quite different.

\begin{scheme}
(eq? '(a b) '(a b))		\ev \schfalse
(equal? '(a b) '(a b))		\ev \schtrue
(define x '(a b))		\ev X
(define y '(a b))		\ev Y
(equal? x y)			\ev \schtrue
(equal? 3 3)			\ev \schtrue
(equal? 67000 67000)		\ev \schtrue
(equal? "abc" "abc")		\ev \schtrue%
\end{scheme}

\end{entry}



\section{Pairs and lists}
\label{listsection}

A \defining{pair} is a structure with two fields called the car and cdr fields
(for historical reasons).  Pairs are constructed by the procedure \ide{cons}.
The car and cdr fields are accessed by procedures \ide{car} and \ide{cdr}, and
set by procedures \ide{set-car!} and \ide{set-cdr!}.

Pairs are used primarily to represent lists.  A \defining{list} is either
empty\index{empty list} or a pair whose car is the first element of the list,
and whose cdr is the rest of the list.  The length of a list is the number of
elements, which is the same as the number of pairs.

The empty list\mainindex{empty list} is a special object of its own type
(it is not a pair); it has no elements and its length is zero.

The most general notation for Scheme pairs is the ``dotted'' notation
\hbox{\cf (\vari{c} .\ \varii{c})} where \vari{c} is the value of the car
field and \varii{c} is the value of the cdr field.  For example {\cf (4 .\ 5)}
is a pair whose car is 4 and whose cdr is 5.  Note that {\cf (4 .\ 5)} is the
external representation of a pair, not an expression that evaluates to a pair.

A more streamlined notation can be used for lists: the elements of the
list are simply enclosed in parentheses and separated by spaces.  The
empty list\index{empty list} is written {\tt()} .  For example,

\begin{scheme}
(a b c d e)%
\end{scheme}

and

\begin{scheme}
(a . (b . (c . (d . (e . ())))))%
\end{scheme}

are both representations of a list of symbols.

A chain of pairs not ending in the empty list is called an
\defining{improper list}.  Note that an improper list is not a list.
The list and dotted notations can be combined to represent improper
lists:

\begin{scheme}
(a b c . d)%
\end{scheme}

is equivalent to

\begin{scheme}
(a . (b . (c . d)))%
\end{scheme}

Whether a given pair is a list depends upon what is stored in the cdr
field.  When the \ide{set-cdr!} procedure is used, an object can be a
list one moment and not the next:

\begin{scheme}
(define x (list 'a 'b 'c))
(define y x)
y                       \ev  (a b c)
(set-cdr! x 4)          \ev  \unspecified
x                       \ev  (a . 4)
(eqv? x y)              \ev  \schtrue
y                       \ev  (a . 4)%
\end{scheme}


\begin{entry}{%
\proto{atom?}{ obj}{procedure}}

Returns \schtrue{} if \var{obj} is an atom, and \schfalse{} otherwise.  An atom
is anything which cannot be further decomposed via \ide{car} or \ide{cdr}.  In
other words, anything that is not a pair is an atom.

\begin{scheme}
(atom? 3)		\ev \schtrue
(atom? 'car)		\ev \schtrue
(atom? car)		\ev \schtrue
(atom? '(a 3))		\ev \schfalse
(atom? '())		\ev \schtrue
(atom? nil)		\ev \schtrue
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{list?}{ obj}{procedure}}

Returns \schtrue{} if \var{obj} is a list, and \schfalse{} otherwise.

\begin{scheme}
(list? 'a)		\ev \schfalse
(list? '())		\ev \schtrue
(list? '(a b))		\ev \schtrue
(list? '(a . b))	\ev \schfalse
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{pair?}{ obj}{procedure}}

Returns \schtrue{} if \var{obj} is a pair, and \schfalse{} otherwise.  Note that
the empty list, \ide{'()}, is a list but not a pair.

\begin{scheme}
(pair? '(a . b))        \ev  \schtrue
(pair? '(a b c))        \ev  \schtrue
(pair? '())             \ev  \schfalse
(pair? '\#(a b))         \ev  \schfalse%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{cons}{ \vari{obj} \varii{obj}}{procedure}}

Returns a newly allocated pair whose car is \vari{obj} and whose cdr is
\varii{obj}.  The pair is guaranteed to be different (in the sense of
\ide{eqv?}) from every existing object.

\begin{scheme}
(cons 'a '())           \ev  (a)
(cons '(a) '(b c d))    \ev  ((a) b c d)
(cons "a" '(b c))       \ev  ("a" b c)
(cons 'a 3)             \ev  (a . 3)
(cons '(a b) 'c)        \ev  ((a b) . c)%
\end{scheme}
\end{entry}

\begin{entry}{%
\proto{car}{ pair}{procedure}}

\nodomain{\var{Pair} must be a pair.}
Returns the contents of the car field of \var{pair}.  Note that it is an
error to take the car of the empty list\index{empty list}.

\begin{scheme}
(car '(a b c))          \ev  a
(car '((a) b c d))      \ev  (a)
(car '(1 . 2))          \ev  1
(car '())               \ev  \scherror%
\end{scheme}
 
\end{entry}


\begin{entry}{%
\proto{cdr}{ pair}{procedure}}

\nodomain{\var{Pair} must be a pair.}
Returns the contents of the cdr field of \var{pair}.
Note that it is an error to take the cdr of the empty list.


\begin{scheme}
(cdr '((a) b c d))      \ev  (b c d)
(cdr '(1 . 2))          \ev  2
(cdr '())               \ev  \scherror%
\end{scheme}
 
\end{entry}

\begin{entry}{%
\proto{set-car!}{ pair obj}{procedure}}

\nodomain{\var{Pair} must be a pair.}  
Stores \var{obj} in the car field of \var{pair}.
The value returned by \ide{set-car!}\ is unspecified.

\end{entry}


\begin{entry}{%
\proto{set-cdr!}{ pair obj}{procedure}}

\nodomain{\var{Pair} must be a pair.}
Stores \var{obj} in the cdr field of \var{pair}.
The value returned by \ide{set-cdr!}\ is unspecified.  % <!>
%This procedure can be very confusing if used indiscriminately.

\end{entry}

\setbox0\hbox{\tt(cadr \var{pair})}
\setbox1\hbox{procedure}


\begin{entry}{%
\proto{caar}{ pair}{procedure}
\proto{cadr}{ pair}{procedure}
\pproto{\hbox to 1\wd0 {\hfil$\vdots$\hfil}}{\hbox to 1\wd1 {\hfil$\vdots$\hfil}}
\proto{cdddar}{ pair}{procedure}
\proto{cddddr}{ pair}{procedure}}

These procedures are compositions of \ide{car} and \ide{cdr}, where
for example \ide{caddr} could be defined by

\begin{scheme}
(define caddr (lambda (x) (car (cdr (cdr x))))){\rm.}%
\end{scheme}

Arbitrary compositions, up to four deep, are provided.  There are
twenty-eight of these procedures in all.

\end{entry}

\begin{entry}{%
\proto{first}{ pair}{procedure}
\proto{second}{ pair}{procedure}
\proto{third}{ pair}{procedure}
\proto{fourth}{ pair}{procedure}
\proto{fifth}{ pair}{procedure}
\proto{sixth}{ pair}{procedure}
\proto{seventh}{ pair}{procedure}
\proto{eighth}{ pair}{procedure}}

These procedures return the first, second, third, ..., eighth element of
\var{pair}, respectively, in exactly the same manner as would  \ide{car},
\ide{cadr}, \ide{caddr}, \ide{cadddr}, ....

\begin{scheme}
(first '((a b) c d))		\ev (a b)
(second '((a b) c d))		\ev c
(eighth '(a b c d e f g h))	\ev h
\end{scheme}

\end{entry}

\begin{entry}{%
\proto{null?}{ obj}{procedure}}

Returns \schtrue{} if \var{obj} is the empty list\index{empty list},
otherwise returns \schfalse.
 
\end{entry}


\begin{entry}{%
\proto{list}{ \vari{obj} \dotsfoo}{procedure}}

Returns a list of its arguments.

\begin{scheme}
(list 'a (+ 3 4) 'c)            \ev  (a 7 c)
(list)                          \ev  ()%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{list*}{ \vari{obj} \varii{obj} \dotsfoo}}

\ide{List*} \ide{cons}es together an arbitrary number of arguments.  It
constructs a pair whose \ide{car} is \vari{obj} and whose \ide{cdr} is
\hbox{\tt (list* \varii{obj} \dotsfoo)}.  When it has only two arguments,
\ide{list*} behaves in the same way as \ide{cons}.

\begin{scheme}
(list* 'a 'b 'c)		\ev (a b . c)
(list* '(a b) 'c '(d e))	\ev ((a b) c d e)
(list* 'a 'b)			\ev (a . b)
(list* 'a)			\ev a
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{length}{ list}{procedure}}

\nodomain{\var{List} must be a list.}
Returns the length of \var{list}.

\begin{scheme}
(length '(a b c))               \ev  3
(length '(a (b) (c d e)))       \ev  3
(length '())                    \ev  0%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{append}{ \vari{list} \varii{list}}{procedure}
\proto{append}{ list \dotsfoo}{procedure}}

\nodomain{All \var{list}s should be lists.}
Returns a list consisting of the elements of the first \var{list}
followed by the elements of the other \var{list}s.

\begin{scheme}
(append '(x) '(y))              \ev  (x y)
(append '(a) '(b c d))          \ev  (a b c d)
(append '(a (b)) '((c)))        \ev  (a (b) (c))%
\end{scheme}

The resulting list is always newly allocated, except that it shares
structure with the last \var{list} argument.  The last argument may
actually be any object; an improper list results if it is not a proper
list.  \todo{This is pretty awkward.  I should get Bartley to fix this.}

\begin{scheme}
(append '(a b) '(c . d))        \ev  (a b c . d)
(append '() 'a)                 \ev  a%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{reverse}{ list}{procedure}}

\nodomain{\var{List} must be a list.}
Returns a newly allocated list consisting of the elements of \var{list}
in reverse order.

\begin{scheme}
(reverse '(a b c))              \ev  (c b a)
(reverse '(a (b c) d (e (f))))  \lev  ((e (f)) d (b c) a)%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{list-tail}{ list \vr{k}}{procedure}
\proto{nthcdr}{ \vr{k} list}{procedure}}

Returns the sublist of \var{list} obtained by omitting the first \vr{k}
elements.

\ide{List-tail} could be defined by

\begin{scheme}
(define list-tail
  (lambda (x k)
    (if (zero? k)
        x
        (list-tail (cdr x) (- k 1)))))%
\end{scheme} 

For historical reasons, \hbox{\tt (nthcdr \vr{k} \var{list})} is the same as
\hbox{\tt (list-tail \var{list} \vr{k})}.

\begin{scheme}
(list-tail '(a b c d) 2)		\ev (c d)
(nthcdr 2 '(a b c d))			\ev (c d)
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{last}{ list}{procedure}}

Returns the last pair of \var{list}.

\begin{scheme}
(last '(a b c)) \ev (c)
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{list-ref}{ list \vr{k}}{procedure}
\proto{nth}{ \vr{k} list}{procedure}}

Both \ide{list-ref} and \ide{nth} return the \vr{k}th element of \var{list},
where numbering starts with zero.  (This is the same as the \ide{car} of
\hbox{\tt (list-tail \var{list} \vr{k})}.)

\begin{scheme}
(list-ref '(a b c d) 2)		\ev c
(nth 2 '(a b c d))		\ev c
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{member}{ obj list}{procedure}
\proto{memq}{ obj list}{procedure}
\proto{memv}{ obj list}{procedure}}

%Finds the first occurrence of \var{obj} in the list \var{list} and
Returns the first sublist of \var{list} whose car is \var{obj}.
If \var{obj} does not occur in \var{list}, returns \schfalse.
\ide{Memq} uses \ide{eq?}\ to compare \var{obj} with the elements of
\var{list}, while \ide{memv} uses \ide{eqv?}\ and \ide{member} uses
\ide{equal?}.

\begin{scheme}
(memq 'a '(a b c))              \ev  (a b c)
(memq 'b '(a b c))              \ev  (b c)
(memq 'a '(b c d))              \ev  \schfalse
(memq (list 'a) '(b (a) c))     \ev  \schfalse
(member (list 'a)
        '(b (a) c))             \ev  ((a) c)
(memq 101 '(100 101 102))       \ev  \unspecified
(memv 101 '(100 101 102))       \ev  (101 102)%
\end{scheme} 
 
\end{entry}


\begin{entry}{%
\proto{assoc}{ obj alist}{procedure}
\proto{assq}{ obj alist}{procedure}
\proto{assv}{ obj alist}{procedure}}

\domain{\var{Alist} (for ``association list'') must be a list of
pairs.}  Finds the first pair in \var{alist} whose car field is \var{obj}
and returns that pair.  If no pair in \var{alist} has \var{obj} as its
car, returns \schfalse.  \ide{Assq} uses \ide{eq?}\ to compare \var{obj}
with the car fields of the pairs in \var{alist}, while \ide{assv} uses
\ide{eqv?}\ and \ide{assoc} uses \ide{equal?}.

\begin{scheme}
(define e '((a 1) (b 2) (c 3)))
(assq 'a e)     \ev  (a 1)
(assq 'b e)     \ev  (b 2)
(assq 'd e)     \ev  \schfalse
(assq (list 'a) '(((a)) ((b)) ((c))))
                \ev  \schfalse
(assq 5 '((2 3) (5 7) (11 13)))    
                           \ev  \unspecified
(assv 5 '((2 3) (5 7) (11 13)))    
                           \ev  (5 7)
(assoc (list 'a) '(((a)) ((b)) ((c))))   
                           \ev  ((a))%
\end{scheme}


\begin{note}
Although they are ordinarily used as predicates,
\ide{memq}, \ide{memv}, \ide{member}, \ide{assq}, \ide{assv}, and \ide{assoc} do not
have question marks in their names because they return useful values rather
than just \schtrue{} or \schfalse.
\end{note}
\end{entry}


\section{Symbols}
\label{symbolsection}

Symbols are objects whose usefulness rests on the fact that two
symbols are identical (in the sense of \ide{eqv?}) if and only if
their names are spelled the same way.  The rules for writing a symbol
are exactly the same as the rules for writing an identifier; see
section~\ref{identifiersyntax}.

\begin{entry}{%
\proto{symbol?}{ obj}{procedure}}

Returns \schtrue{} if \var{obj} is a symbol, otherwise returns \schfalse.

\begin{scheme}
(symbol? 'foo)          \ev  \schtrue
(symbol? (car '(a b)))  \ev  \schtrue
(symbol? "bar")         \ev  \schfalse%
\end{scheme}
\end{entry}

\begin{entry}{%
\proto{alphaless?}{ \vari{symbol} \varii{symbol} }{procedure}}

Returns \schtrue{} or \schfalse{} according to whether the name of
\vari{symbol} alphabetically precedes the name of \varii{symbol}.

\begin{scheme}
(alphaless? 'ab 'b)	\ev     \schtrue
(alphaless? 'a 'a)	\ev     \schfalse
\end{scheme}
\end{entry}

\begin{entry}{%
\proto{explode}{ \var{symbol}}{procedure}}

Returns a list of one-character symbols or digits that are the letters
in the name of \var{symbol}.

\begin{scheme}
(explode 'gleep35)      \ev     (G L E E P 3 5)
\end{scheme}
\end{entry}

\begin{entry}{%
\proto{implode}{ \var{list}}{procedure}}

The argument must be a list of character symbols or integers.
\ide{Implode} returns a symbol whose name is the concatenation of the
names of elements in the list.

\begin{scheme}
(implode '(g l e e p 3 5))       \ev     GLEEP35
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{char}{ n}{procedure}}

Returns the ASCII character (symbol) whose ASCII code is \var{n}.

\begin{scheme}
(char 65) \ev A
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{ascii}{ symbol}{procedure}}

Returns the ASCII code of the single-character symbol \var{symbol}.  All
alphabetic characters are regarded as upper case, because symbols do not
retain the case in which they are typed.

\begin{scheme}
(ascii 'a) \ev 65
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{generate-uninterned-symbol}{ \var{symbol}}{procedure}}

Returns a symbol that is guaranteed to be different (not \ide{eqv?}) from any
other symbol.  The printed representation of the new symbol will begin with
the characters of \hyper{symbol}.

\begin{note}
The ``name'' of an uninterned symbol is convenience for the human
reader.  You cannot reference an uninterned symbol by quoting its
name.
\end{note}

\begin{scheme}
(define s (generate-uninterned-symbol 'fact)) 
                                      \ev   \unspecified
s                                     \ev   {\em something of the form} FACT342
(eqv? s s)                       \ev  \schtrue
(eqv? s 'FACT342)                \ev  \schfalse
\end{scheme}
\end{entry}

\section{Numbers}
\label{numbersection}
\index{number}

Section~\ref{typeconventions} lists the names used here to specify restriction
on the types of arguments these numerical procedures will accept.

\begin{entry}{%
\proto{number?}{ obj}{procedure}
\proto{integer?}{ obj}{procedure}}

These numerical type predicates can be applied to any kind of argument,
including non-numbers.
They return true if the object is of the named type.  In general, if a type
predicate is true of a number then all higher type predicates are also true
of that number.

\end{entry}


\begin{entry}{%
\proto{zero?}{ \vr{z}}{procedure}
\proto{positive?}{ \vr{x}}{procedure}
\proto{negative?}{ \vr{x}}{procedure}
\proto{odd?}{ \vr{n}}{procedure}
\proto{even?}{ \vr{n}}{procedure}}

These numerical predicates test a number for a particular property, returning
\schtrue{} or \schfalse.

\end{entry}


\begin{entry}{%
\proto{=}{ \vri{z} \vrii{z}}{procedure}
\proto{<}{ \vri{x} \vrii{x}}{procedure}
\proto{>}{ \vri{x} \vrii{x}}{procedure}
\proto{<=}{ \vri{x} \vrii{x}}{procedure}
\proto{>=}{ \vri{x} \vrii{x}}{procedure}}

These procedures return \schtrue{} if their
arguments are (respectively): numerically equal, monotonically
increasing, monotonically decreasing, monotonically nondecreasing, or
monotonically nonincreasing.

\end{entry}


\begin{entry}{%
\proto{max}{ \vri{x} \vrii{x}}{procedure}
\proto{max}{ \vri{x} \vrii{x} \dotsfoo}{procedure}
\proto{min}{ \vri{x} \vrii{x}}{procedure}
\proto{min}{ \vri{x} \vrii{x} \dotsfoo}{procedure}}

These procedures return the maximum or minimum of their arguments.
\end{entry}


\begin{entry}{%
\proto{+}{ \vri{z} \vrii{z}}{procedure}
\proto{+}{ \vri{z} \dotsfoo}{procedure}
\proto{*}{ \vri{z} \vrii{z}}{procedure}
\proto{*}{ \vri{z} \dotsfoo}{procedure}}

These procedures return the sum or product of their arguments.

\begin{scheme}
(+ 3 4)                 \ev  7
(+ 3)                   \ev  3
(+)                     \ev  0
(* 4)                   \ev  4
(*)                     \ev  1%
\end{scheme} 
 
\end{entry}


\begin{entry}{%
\proto{-}{ \vri{z} \vrii{z}}{procedure}
\proto{-}{ \vri{z} \vrii{z} \dotsfoo}{procedure}
\proto{/}{ \vri{z} \vrii{z}}{procedure}
\proto{/}{ \vri{z} \vrii{z} \dotsfoo}{procedure}}

With two or more arguments, these procedures return the difference or
quotient of their arguments, associating to the left.  With one argument,
however, they return the additive or multiplicative inverse of their argument.

\begin{scheme}
(- 3 4)                 \ev  -1
(- 3 4 5)               \ev  -6
(- 3)                   \ev  -3
(/ 3 4 5)               \ev  3/20
(/ 3)                   \ev  1/3%
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{1+}{ \var{z}}{procedure}}

This procedure returns a value one greater than its argument.

\begin{scheme}
(1+ 3)			\ev 4
\end{scheme}

\end{entry}

\begin{entry}{%
\proto{-1+}{ \var{z}}{proecedure}}

This procedure returns a value one less than its argument.

\begin{scheme}
(-1+ 3)			\ev 2
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{abs}{ z}{procedure}}

\ide{Abs} returns the magnitude of its argument.  
\begin{scheme}
(abs -7)                \ev  7
(abs -3+4i)             \ev  5%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{quotient}{ \vri{n} \vrii{n}}{procedure}
\proto{remainder}{ \vri{n} \vrii{n}}{procedure}
\proto{integer-divide}{ \vri{n} \vrii{n}}{procedure}}

These are intended to implement number-theoretic (integer)
division: For positive integers \vri{n} and \vrii{n}, if \vriii{n} and
\vriv{n} are integers such that $\vri{n}=\vrii{n}\vriii{n}+\vriv{n}$ and
$0\leq \vriv{n}<\vrii{n}$, then

\begin{scheme}
(quotient \vri{n} \vrii{n})        \ev  \vriii{n}
(remainder \vri{n} \vrii{n})       \ev  \vriv{n}
(integer-divide \vri{n} \vrii{n})  \ev  (\vriii{n} . \vriv{n})%
\end{scheme}

\ide{integer-divide} returns the \ide{cons} of what \ide{quotient} and
\ide{remainder} would return given the same arguments.

For all integers \vri{n} and \vrii{n} with \vrii{n} not equal to 0,

\begin{scheme}
(= \vri{n} (+ \=(* \vrii{n} (quotient \vri{n} \vrii{n}))
              \>(remainder \vri{n} \vrii{n})))
                                   \ev  \schtrue%
\end{scheme}


The value returned by \ide{quotient} always has the sign of the product of its
arguments.  \ide{Remainder} always has the sign of the dividend.

\begin{scheme}
(remainder 13 4)        \ev  1
(remainder -13 4)       \ev  -1
(remainder 13 -4)       \ev  1
(remainder -13 -4)      \ev  -1%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{gcd}{ \vri{n} \dotsfoo}{procedure}}

These procedures return the greatest common divisor or least common
multiple of their arguments. The result is always non-negative.

\begin{scheme}
(gcd 32 -36)            \ev  4
(gcd)                   \ev  0
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{floor}{ x}{procedure}
\proto{ceiling}{ x}{procedure}
\proto{truncate}{ x}{procedure}
\proto{round}{ x}{procedure}}

These procedures create integers and rationals.


\vest \ide{Floor} returns the largest integer not larger than \vr{x}.
\ide{Ceiling} returns the smallest integer not smaller than~\vr{x}.
\ide{Truncate} returns the integer of maximal absolute value not larger
than the absolute value of \vr{x}.  \ide{Round} returns the closest
integer to \vr{x}, rounding to even when \vr{x} is halfway between two
integers. 

\begin{note}
\ide{Round} rounds to even for consistency with the rounding
modes required by the IEEE floating point standard.
\end{note}

\end{entry}


\begin{entry}{%
\proto{exp}{ \vr{z}}{procedure}
\proto{log}{ \vr{z}}{procedure}
\proto{sin}{ \vr{z}}{procedure}
\proto{cos}{ \vr{z}}{procedure}
\proto{tan}{ \vr{z}}{procedure}
\proto{atan}{ \vr{y} \vr{x}}{procedure}}

\ide{Log} computes the natural logarithm of \vr{z} (not the base 10
logarithm).  \ide{Atan} returns the arctangent, in radians, of the quotient of
its arguments.

For nonzero $x$, the value of $\log x$ is defined to be the one whose
imaginary part lies in the range $-\pi$ (exclusive) to $\pi$ (inclusive).
\ide{(Log 0)} is undefined.
\end{entry}


\begin{entry}{%
\proto{sqrt}{ \vr{z}}{procedure}}

Returns the square root of \vr{z}.
\end{entry}


\begin{entry}{%
\proto{expt}{ \vri{z} \vrii{z}}{procedure}}

Returns \vri{z} raised to the power \vrii{z}:
$${z_1}^{z_2} = e^{z_2 \log {z_1}}$$
$0^0$ is defined to be equal to 1.
\end{entry}


\begin{entry}{%
\proto{random}{ \vr{k}}{procedure}}

Returns an integer chosen at random between 0 and $k-1$, inclusive.
The argument $k$ must be a positive integer.
\end{entry}

\section{Strings}
\label{stringsection}

Strings are sequences of characters.  Strings are written as sequences of
characters enclosed within double quotes ({\cf "}).  A double quote inside a
string is created by \backwhack {\cf "}, as in

\begin{scheme}
"The word \backwhack"recursion\backwhack" has many meanings."%
\end{scheme}

To type \backwhack\ on the Chipmunk keyboard, hold down \key{shift} and press
the \key{)} on the numeric keypad on the right side of the keyboard;
\key{shift} with \key{0} (zero) will {\em not} work.


\section{Vectors}
\label{vectorsection}

Vectors are structures whose elements are indexed by integers.  The first
element in a vector is indexed by zero, and the last element is indexed by one
less than the length of the vector.  The printed representation for vectors is
a \verb|#| followed by the sequence of elements, enclosed in parentheses.  For
example, a vector of length 3 containing the number zero in element 0, the
list {\cf(2 2 2 2)} in element 1, and the string {\cf "Anna"} in element 2 can
be written as following:

\begin{scheme}
\#(0 (2 2 2 2) "Anna")%
\end{scheme}

Note that this is the external representation, not an expression evaluating to
a vector.  Like lists, vector constants must be quoted:

\begin{scheme}
'\#(0 (2 2 2 2) "Anna")  \ev  \#(0 (2 2 2 2) "Anna")%
\end{scheme}

Vectors are created by the constructor procedures \ide{vector} and
\ide{vector-cons}.  The elements are accessed and assigned by the procedures
\ide{vector-ref} and \ide{vector-set!}.


\begin{entry}{%
\proto{vector?}{ obj}{procedure}}
 
Returns \schtrue{} if \var{obj} is a vector, otherwise returns \schfalse.
\end{entry}


\begin{entry}{%
\proto{vector-cons}{ size fill}{procedure}}

\ide{Vector-cons} returns a newly allocated vector of \var{size} elements,
each initialized to \var{fill}.
\end{entry}


\begin{entry}{%
\proto{vector}{ obj \dotsfoo}{procedure}}

Returns a newly allocated vector whose elements contain the given
arguments.  Analogous to \ide{list}.

\begin{scheme}
(vector 'a 'b 'c)               \ev  \#(a b c)%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{vector-size}{ vector}{procedure}}

Returns the number of elements in \var{vector}.
\end{entry}


\begin{entry}{%
\proto{vector-ref}{ vector k}{procedure}}

\domain{\vr{k} must be a nonnegative integer less than
{\cf(vector-length \var{vector})}.}
\ide{Vector-ref} returns the contents of element \vr{k} of
\var{vector}.

\begin{scheme}
(vector-ref '\#(1 1 2 3 5 8 13 21) 5)  \evalsto  8%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{vector-set!}{ vector k obj}{procedure}}

\domain{\vr{k} must be a nonnegative integer less than
{\cf(vector-length \var{vector})}.}
\ide{Vector-set!} stores \var{obj} in element \vr{k} of \var{vector}.
The value returned by \ide{vector-set!}\ is unspecified.  % <!>

\begin{scheme}
(let ((vec (vector 0 '(2 2 2 2) "Anna")))
  (vector-set! vec 1 '("Sue" "Sue"))
  vec)      \lev  \#(0 ("Sue" "Sue") "Anna")%
\end{scheme}
\end{entry}


\section{Control features}
 
This chapter describes various primitive procedures that control the
flow of program execution in special ways.

\begin{entry}{%
\proto{apply}{ proc args}{procedure}}

\domain{\var{Proc} must be a procedure and \var{args} must be a list.}
\ide{Apply} calls \var{proc} with the elements of
\var{args} as the actual arguments.

\begin{scheme}
(apply + (list 3 4))              \ev  7

(define compose
  (lambda (f g)
    (lambda args
      (f (apply g args)))))

((compose sqrt *) 12 75)              \ev  30%
\end{scheme}
\end{entry}


\begin{entry}{%
\proto{mapcar}{ proc \vari{list} \varii{list} \dotsfoo}{procedure}}

\domain{\var{Proc} must be a procedure of which takes as many arguments as
there are lists supplied to \ide{mapcar}.}
\ide{Mapcar} returns a list whose first element is \ide{proc} applied to the
first element of eachlist, whose second element is \ide{proc} applied to the
second element of the list, and so on.  \ide{Mapcar} stops when it reaches the
end of the shortest list.

\begin{scheme}
(mapcar length '((a b) (c d) (e (f g) h)))	\lev (2 2 3)
(mapcar + '(1 2 3) '(4 5 6))			\lev (5 7 9)
(mapcar * '(1 2) '(3 4 5) '(6 7 8 9))		\lev (18 56)
\end{scheme}

\end{entry}


\begin{entry}{%
\proto{mapc}{ proc \vari{list} \varii{list} \dotsfoo}{procedure}}

\domain{\var{Proc} must be a procedure which takes as many arguments as there
are lists supplied to \ide{mapc}.}
\ide{Mapc} applied \ide{proc} to the first element of ech list, to the second
element of each list, and so on.  The difference between \ide{mapc} and
\ide{mapcar} is that \ide{mapcar} returns a list of values, while \ide{mapc}
does not.  The procedure \ide{proc} is usually applied for effect, and the
value returned by \ide{mapc} should be ignored.

\end{entry}


\section{Streams and delayed evaluation}

A \defining{stream} is a structure with two fields called the head and
the tail.  Streams are created by \ide{cons-stream}.  The head and
tail are accessed using the procedures \ide{head} and
\ide{tail}.  Streams are used for representing sequences of elements,
which are retrieved as the heads of successive tails of the stream.
In this way, a stream is like a list.  The difference is that the
items in the stream are {\em delayed}, that is, they are computed when
they are accessed rather than when the stream is constructed.  The
empty stream\mainindex{empty stream} is stream that has no elements.
See chapter 3 of~\cite{SICP} for information on programming with
streams.

\begin{entry}{%
\proto{cons-stream}{ \vari{obj} \varii{obj}}{\exprtype}}

Returns a stream whose head is \vari{obj} and whose tail is
\varii{obj}.  \ide{Cons-stream} is syntax rather than a procedure
because it does not evaluate its second argument.
\end{entry}

\begin{entry}{%
\proto{head}{ \var{stream}}{procedure}}

Returns the head of the given \var{stream}.
\end{entry}


\begin{entry}{%
\proto{tail}{ \var{stream}}{procedure}}

Returns the tail of the given \var{stream}.
\end{entry}

\begin{entry}{%
\vproto{the-empty-stream}{variable}}

A variable initially bound to the empty stream.
\end{entry}

\begin{entry}{%
\proto{empty-stream?}{ \var{obj}}{procedure}}

Returns \schtrue{} or \schfalse{} depending on whether \var{obj} is
the empty steam.
\end{entry}

\begin{entry}{%
\proto{delay}{ \hyper{expression}}{\exprtype}}

The \ide{delay} construct, together with the procedure \ide{force},
implement \defining{lazy evaluation} or \defining{call by need}.
{\tt(delay \hyper{expression})} returns an object called a
\defining{promise} which at some point in the future may be asked (by
the \ide{force} procedure) to evaluate
\hyper{expression} and deliver the resulting value.

\end{entry}


\begin{entry}{%
\proto{force}{ promise}{procedure}}

Forces the value of \var{promise} (see \ide{delay}
above).\index{promise} If no value has been computed for the promise,
then a value is computed and returned.  The value of the promise is
cached (or ``memoized'') so that if it is forced a second time, the
previously computed value is returned without any recomputation.

\begin{scheme}
(force (delay (+ 1 2)))   \ev  3
(let ((p (delay (+ 1 2))))
  (list (force p) (force p)))  
                               \ev  (3 3)
\end{scheme}

\ide{Force} and \ide{delay} are mainly intended for programs written
using streams.  The following examples should not be considered to
illustrate good programming style, but they illustrate the property that
the value of a promise is computed at most once.

\begin{scheme}
(define count 0)
(define p (delay (sequence (set! count (+ count 1))
			   (* x 3))))
(define x 5)
count      \ev  0
p          \ev  {\it{}a promise}
(force p)  \ev  15
p          \ev  {\it{}a promise, still}
count      \ev  1
(force p)  \ev  15
count      \ev  1%
\end{scheme}

\end{entry}



\section{Input and output}

\subsection{General Terminal and File I/O}
\label{generalIO}

Several of the procedures described in this section accept optional arguments.
The optional argument \var{channel} is a channel objects, as returned by
\ide{open-reader-channel} or \ide{open-printer-channel}.  If the argument
\var{channel} is omitted, the channel is defaulted to the console.  For input
operations, the optional argument \var{eof} is returned on end of file.  If
\ide{eof} is omitted, an error is signaled on end of file.

\begin{entry}{%
\proto{read-from-keyboard}{}{procedure}}

This procedure is used when you want to give input to Scheme while
running under Edwin.  When you evaluate this procedure, the Scheme
interpreter waits to send it an expression, (e.g. by typing
\key{execute}) and then returns that expression.  While Scheme is waiting,
you can use all the Edwin commands normally used in editing.  In
particular, pressing the \key{abort} key will not cause Scheme to stop
waiting for input.  To force Scheme to stop waiting and return to top
level, send it the expression {\tt abort}.

\end{entry}

\begin{entry}{%
\proto{read}{}{procedure}
\proto{read}{ channel}{procedure}}

Returns the next object parsable from the given input \var{channel}, updating
\var{channel} to point to the first character past the end of the written
representation of the object.  If an end of file is encountered in the
input before any characters are found that can begin an object, then
the end of file object \var{eof} is returned.  This procedure should
not be used to get input from the keyboard while Scheme is running in
combination with Edwin---use {\tt read-from-keyboard} instead.
\end{entry}

\begin{entry}{%
\proto{newline}{}{procedure}
\proto{newline}{ channel}{procedure}}

Writes a carriage return and line feed to \var{channel}.  Returns an
unspecified value.
\end{entry}


\begin{entry}{%
\proto{print}{ obj}{procedure}
\proto{print}{ obj channel}{procedure}
\proto{prin1}{ obj}{procedure}
\proto{prin1}{ obj channel}{procedure}
\proto{princ}{ obj}{procedure}
\proto{princ}{ obj channel}{procedure}}

\ide{Print} prints the value of \var{obj} on the console, or \var{channel}, if
specified, preceding it with a carriage-return and line-feed.  If \var{obj} is
a string, it is output surrounded by double quotes.

\ide{Prin1} behaves exactly the same as \ide{print}, except that it does not
precede the output with a carriage-return and line-feed.

\ide{Princ} behaves exactly the same as \ide{prin1}, except that it does not
surround output strings with double quotes, and double quotes which are part
of the string are not displayed preceded by backslash ``\backwhack''.

\end{entry}


\begin{entry}{%
\proto{print-depth}{}{procedure}
\proto{print-depth}{ n}{procedure}}

Returns the depth to which nested list structures will be printed.  If null,
no restrictions are placed on print depth.  If given the argument \var{n},
\ide{print-depth} changes the print depth to \var{n}.
\end{entry}


\begin{entry}{%
\proto{print-breadth}{}{procedure}
\proto{print-breadth}{ n}{procedure}}

Returns the number of elements of list strcture that will be printed out.  If
null, no restrictions are placed on print breadth.  If given the argument
\var{n}, \ide{print-breadth} changes the print breadth to \var{n}.
\end{entry}



\subsection{Advanced Terminal and File I/O}
\label{advancedIO}

Several of the procedures described in this section accept optional arguments.
The optional argument \var{channel} is a channel object, as returned by
\ide{open-read-channel} or \ide{open-printer-channel}.  If the argument
\var{channel} is omitted, the channel is defaulted to the console.  For input
operations, the optional argument \var{eof} can be included.  On end of file,
the object \var{eof} will be returned as the value of the input operation.  If
omitted, an error is signaled on end of file.


\begin{entry}{%
\proto{close-channel}{ channel}{procedure}}

Closes an opened input or output channel.  \var{channel} is an object created
by \ide{open-reader-channel} or \ide{open-printer-channel}.
\end{entry}


\begin{entry}{%
\proto{delete-file}{ filename}{procedure}}

Deletes the file specified by character string \var{filename}.
\end{entry}


\begin{entry}{%
\proto{file-exists?}{ filename}{procedure}}

Returns \schtrue{} if a file named \var{filename} exists, and \schfalse{}
otherwise.  \var{Filename} is a character string.

\end{entry}


\begin{entry}{%
\proto{open-reader-channel}{ filename}{procedure}}

Returns a channel object which can be used for input from the file specified
by character string \var{filename}.  If the file does not exist, an error
occurs.
\end{entry}


\begin{entry}{%
\proto{open-printer-channel}{ filename}{procedure}}

Returns a channel object which can be used for output to the file specified by
character string \var{filename}.  If that file already exists, its previous
contents will be lost.
\end{entry}


\begin{entry}{%
\proto{tyi}{}{procedure}
\proto{tyi}{ channel}{procedure}
\proto{tyi}{ channel eof}{procedure}}

Reads a character from the terminal or specified reader \var{channel} and returns its
ASCII code, an integer.  The optional argument \var{eof} is an object which
will be returned by \ide{tyi} on end of file.
\end{entry}


\begin{entry}{%
\proto{tyo}{ n}{procedure}
\proto{tyo}{ n channel}{procedure}}

Outputs the character whose ASCII value is \var{n} on the console or specified
output \var{channel}.
\end{entry}


\begin{entry}{%
\proto{readch}{}{procedure}
\proto{readch}{ channel}{procedure}
\proto{readch}{ channel eof}{procedure}}

Reads the next character from the terminal or specified input \var{channel}
and returns it as a symbol.  \var{Eof} will be returned on end of file.
\end{entry}


\begin{entry}{%
\proto{peekch}{}{procedure}
\proto{peekch}{ channel}{procedure}
\proto{peekch}{ channel eof}{procedure}}

Peeks at the next character from the terminal or specified input \var{channel}
without actually reading it, and returns it as a symbol.  \var{Eof} will be
returned on end of file.
\end{entry}


\begin{entry}{%
\proto{tyipeek}{}{procedure}
\proto{tyipeek}{ channel}{procedure}
\proto{tyipeek}{ channel eof}{procedure}}

Peeks at the next character from the terminal or specified input \var{channel}
without actually reading it, and returns its ASCII code, an integer.
\var{Eof} will be returned on end of file.
\end{entry}


\begin{entry}{%
\proto{initialize-floppy}{ drive name}}

Formats a floppy disk for use.  \var{Drive} is either the symbol \ide{left} or
the symbol \ide{right}, specifying which floppy to format.  \var{Name} is a
character string specifying the name to give the floppy; it must be ten
characters or fewer and end with a colon ``:'' character.  Every floppy must
be initialized before it is used the first time, but Edwin automatically
formats your disk when you log in for the first time.

\begin{scheme}
(initialize-floppy 'right "FOO:")
\end{scheme}

\end{entry}

\begin{entry}{%
\proto{backup-floppy}{}}

Backs up a floppy disk.  When you run this command, you will be asked
to insert the source disk in one drive and a target disk in the other
drive.  The program will initialize the target disk if necessary.  Be
sure to follow the instructions carefully so as not to confuse the
source disk and the target disk.

\end{entry}


\section{Environments and evaluation}

An \defining{environment} is the set of bindings for variables that is
in effect at some point in a program.  (See
section~\ref{variablesection}.)  Environments in Scheme are
first-class objects.  That is, they may be named by variables, passed
as arguments to procedures, and returned as the values of procedures.
Scheme includes operations for capturing the environment in effect at
any point and for specifying that an expression should be evaluated
relative to a particular environment.

\begin{entry}{%
\proto{eval}{ exp env}{procedure}}

Returns the result of evaluating \var{exp} in the environment
\var{env}.
\end{entry}

\begin{entry}{%
\proto{the-environment}{}{\exprtype}}

Evaluating the form \ide{the-environment} returns the environment in
which the form is evaluated.

\begin{note}
Scheme's static-scoping semantics imply that \ide{the-environment} is
not a procedure.
\end{note}
\end{entry}

\begin{entry}{%
\proto{environment?}{ obj}{procedure}}

Returns \schtrue{} or \schfalse{} depending on whether \var{obj} is an
environment.
\end{entry}


\begin{entry}{%
\proto{make-environment}{ \vari{exp} \varii{exp} \dotsfoo}{\exprtype}}

\ide{Make-environment} constructs a new environment that is contained
in the environment in which this form is evaluated.  The expressions
\vari{exp}, \varii{exp}, \dotsfoo are evaluated sequentially in this
new environment, and the environment is returned.  The \var{exp$_i$}
are typically \ide{define} expressions.  A \ide{make-environment}
form is alternate syntax for
\begin{scheme}
(let () \vari{exp} \varii{exp} \dotsfoo (the-environment))
\end{scheme}
\end{entry}

\begin{entry}{%
\vproto{user-initial-environment}{variable}}

A variable that is initially bound to the environment in which
expressions entered from the console are evaluated when Scheme is
first run.
\end{entry}

\section{Miscellaneous}

\begin{entry}{%
\proto{applicable?}{ obj}{procedure}}

Returns \schtrue{} if \var{obj} can be applied, and \schfalse{} otherwise.
Primitive and compound procedures are applicable.

\end{entry}


\begin{entry}{%
\proto{object-type}{ obj}{procedure}}

Returns the primitive datatype of the object \var{obj}.  The following are the
data types that would be encountered in user code:

\begin{itemize}

\item \ide{character}
\item \ide{character-string}
\item \ide{delayed}
\item \ide{environment}
\item \ide{list}
\item \ide{null}
\item \ide{number}
\item \ide{primitive-procedure}
\item \ide{procedure}
\item \ide{symbol}
\item \ide{true}
\item \ide{vector}

\end{itemize}

\end{entry}


\section{Advanced Features}
\label{advanced features}

\begin{entry}{%
\proto{enable-language-features}{}{procedure}
\proto{disable-language-features}{}{procedure}}

The Scheme system includes many more built-in procedures and special forms
than are documented in this manual.  Most of these are for system programming
only.  When Scheme is initially loaded, only the procedures in this manual are
accessible from the initial user environment.  Evaluating
\ide{enable-language-features} makes the additional procedures accessible.
Evaluating \ide{disable-language-features}, in turn, disables these features.
\end{entry}

\section{Graphics}
\label{graphicssection}
\mainindex{graphics}

This section describes the basic graphics primitives available on the
Chipmunks.

Graphics on the Chipmunks is are displayed separately, but on the same screen
as, the standard alphanumeric output.  The graphics screen is made up of
points which are either on or off.  Each point is addressed by its $x$ and $y$
coordinates on the screen, the origin being the middle of the screen.  The $x$
direction is numbered from -256 (left) to 255 (right).  The $y$ direction is
numbers from 194 (top) to -195 (bottom).  Some of the graphics procedures deal
with a ``pen.''  The pen can be moved from its current position to another
point, either drawing a line or not.

\begin{entry}{%
\proto{clear-graphics}{}{procedure}}

Clears all graphics from the graphics screen and places the pen at point (0,0)
(i.e., the middle of the screen).
\end{entry}

\begin{entry}{%
\proto{draw-point}{ x y}{procedure}}

Plots the point at $(x,y)$.
\end{entry}

\begin{entry}{%
\proto{clear-point}{ x y}{procedure}}

Erases the point at $(x,y)$.
\end{entry}

\begin{entry}{%
\proto{position-pen}{ x y}{procedure}}

Moves the graphics pen to the point specified by the coordinates $(x,y)$.
\end{entry}

\begin{entry}{%
\proto{draw-line-to}{ x y}{procedure}}

Draws a line from the current pen position to $(x,y)$ and leaves the
pen positioned at $(x,y)$.
\end{entry}

\begin{entry}{%
\proto{store-graphics}{ filename}{procedure}}

Saves the image on the graphics screen in the designated file.
\end{entry}

\begin{entry}{%
\proto{load-graphics}{ filename}{procedure}}

Interprets the contents of the designated file as a graphics picture,
and displays this on the graphics screen.
\end{entry}

\begin{entry}{%
\proto{print-picture-file}{ filename}{procedure}}

Interprets the contents of the designated file as a graphics picture,
displays this on the graphics screen, and prints the image on an
attached graphics printer.  {\em Do not use this command if there is
no graphics printer attached to the Chipmunk!}
\end{entry}

