contrl.tex

%Part{Contrl, Root = "CLM.MSS"}
%Chapter of Common Lisp Manual.  Copyright 1984, 1988, 1989 Guy L. Steele Jr.

\clearpage\def\pagestatus{ULTIMATE}

\ifx \rulang\Undef
\chapter{Control Structure}
\label{CONTRL}

Common Lisp provides a variety of special structures for organizing
programs.  Some have to do with flow of control (control structures),
while others control access to variables (environment structures).
Some of these features are implemented as special operators;
others are implemented as macros, which typically expand into
complex program fragments expressed in terms of special operators
or other macros.

Function application is the primary method for construction of Lisp
programs.  Operations are written as the application of a function
to its arguments.  Usually, Lisp programs are written as a large collection
of small functions, each of which implements a simple operation.
These functions operate by calling one another, and so larger
operations are defined in terms of smaller ones.
Lisp functions may call upon themselves recursively,
either directly or indirectly.

Locally defined functions (\cdf{flet}, \cdf{labels}) and macros (\cdf{macrolet})
are quite versatile.
The new symbol macro facility allows even more syntactic flexibility.

While the Lisp language
is more applicative in style than statement-oriented, it
nevertheless provides many operations that produce side effects and
consequently requires constructs for controlling the sequencing of
side effects.  The construct
\cdf{progn}, which is roughly equivalent to an Algol \textbf{begin}-\textbf{end}
block with all its semicolons, executes a number of forms sequentially,
discarding the values of all but the last.
Many Lisp control constructs
include sequencing implicitly, in which case they are said to
provide an ``implicit \cdf{progn}.''
\indexterm{implicit \cdf{progn}}
Other sequencing constructs include \cdf{prog1} and \cdf{prog2}.

For looping, Common Lisp provides the general iteration facility
\cdf{do} as well as a variety
of special-purpose iteration facilities for iterating or mapping
over various data structures.

Common Lisp provides the simple one-way conditionals \cdf{when} and \cdf{unless},
the simple two-way conditional \cdf{if}, and the more general multi-way
conditionals such as \cdf{cond} and \cdf{case}.  The choice of which form
to use in any particular situation is a matter of taste and
style.

Constructs for performing non-local exits with various scoping
disciplines are provided: \cdf{block}, \cdf{return},
\cdf{return-from},
\cdf{catch}, and \cdf{throw}.

The multiple-value constructs provide an efficient way for a function
to return more than one value; see \cdf{values}.

\section{Constants and Variables}
\label{FUNCTION-NAME-SECTION}

Because some Lisp data objects are used to represent programs,
one cannot always notate a constant data object in a program simply
by writing the notation for the object unadorned; it would be ambiguous
whether a constant object or a program fragment was intended.
The \cdf{quote} special operator resolves this ambiguity.

There are two kinds of variables in Common Lisp, in effect: ordinary
variables and function names.  There are some similarities between
the two kinds, and in a few cases there are similar functions for
dealing with them, for example \cdf{boundp} and \cdf{fboundp}.
However, for the most part the two kinds of variables are
used for very different purposes: one to name defined functions,
macros, and special operators, and the other to name data objects.

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to introduce the concept
of a \emph{function-name}, which may be either a symbol or a two-element list whose
first element is the symbol \cdf{setf} and whose second element is a symbol.
The primary purpose of this is to allow \cdf{setf} expander functions to be
CLOS generic functions with user-defined methods.
Many places in Common Lisp that used to require a symbol for a function
name are changed to allow 2-lists as well; for example, \cdf{defun}
is changed so that one may write \cd{(defun (setf~foo) ...)},
and the \cdf{function} special operator is changed to accept any function-name.
See also \cdf{fdefinition}.

By convention, any function named \cd{(setf \emph{f\/})} should return its first
argument as its only value, in order to preserve the specification that
\cdf{setf} returns its \emph{newvalue}.  See \cdf{setf}.

Implementations are free to extend the syntax of function-names to
include lists beginning with additional symbols other than \cdf{setf}
or \cdf{lambda}.
\end{newer}

\subsection{Reference}

The value of an ordinary variable
may be obtained simply by writing the name of the variable
as a form to be executed.  Whether this is treated as the name
of a special variable or a lexical variable is determined
by the presence or absence of an applicable \cdf{special} declaration;
see chapter~\ref{DECLAR}.

The following functions and special operators allow reference to the
values of constants and variables in other ways.

\begin{defspec}
quote object

\cd{(quote \emph{x})} simply returns \emph{x}.
The \emph{object} is not evaluated and may be any Lisp object whatsoever.
This construct allows any Lisp object to be written as a constant
value in a program.
For example:
\begin{lisp}
(setq a 43) \\
(list a (cons a 3)) \EV\ (43 (43 . 3)) \\
(list (quote a) (quote (cons a 3)) \EV\ (a (cons a 3))
\end{lisp}
Since \cdf{quote} forms are so frequently useful
but somewhat cumbersome to type, a standard abbreviation is defined for them:
any form \emph{f} preceded by a single quote (\cd{~'~}) character
is assumed to have \cd{(quote~~)} wrapped around it to
make \cd{(quote \emph{f})}.
For example:
\begin{lisp}
(setq x '(the magic quote hack))
\end{lisp}
is normally interpreted by \cdf{read} to mean
\begin{lisp}
(setq x (quote (the magic quote hack)))
\end{lisp}
See section~\ref{MACRO-CHARACTERS-SECTION}.

It is an error to destructively modify any object that appears as a constant
in executable code, whether within a \cdf{quote} special operator or as
a self-evaluating form.

See section~\ref{COMPILER-SECTION} for a discussion of how quoted constants
are treated by the compiler.

\begin{newer}
X3J13 voted in March 1989 \issue{QUOTE-SEMANTICS} to clarify that
\cdf{eval} and \cdf{compile} are not permitted either to copy or
to coalesce (``collapse'') constants (see \cdf{eq})
appearing in the code they process; the resulting
program behavior must refer to objects that are \cdf{eql} to the
corresponding objects in the source code.
Moreover, the constraints introduced by the votes on
issues \issue{CONSTANT-COMPILABLE-TYPES}
and \issue{CONSTANT-CIRCULAR-COMPILATION}
on what kinds of objects may appear
as constants apply only to \cdf{compile-file} (see section~\ref{COMPILER-SECTION}).
\end{newer}
\end{defspec}

\begin{defspec}
function fn

The value of \cdf{function} is always the functional interpretation
of \emph{fn}; \emph{fn} is interpreted as if it had appeared
in the functional position of a function invocation.
In particular,
if \emph{fn} is a symbol, the functional definition associated with
that symbol is returned; see \cdf{symbol-function}.
If \emph{fn} is a lambda-expression, then a
``lexical closure'' is returned, that is, a function that when invoked
will execute the body of the lambda-expression in such a way as to
observe the rules of lexical scoping properly.

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE}
to specify that the result of a \cdf{function} special operator is always
of type \cdf{function}.  This implies that a form \cd{(function~\emph{fn\/})}
may be interpreted as \cd{(the (function~\emph{fn\/}))}.

It is an error to use the \cdf{function} special operator on a
    symbol that does not denote a function in the lexical or global environment in
    which the special operator appears.  Specifically, it is an error to use the
    \cdf{function} special operator on a symbol that denotes a macro or special operator.
    Some implementations may choose not to signal this error for
        performance reasons, but implementations are forbidden
        to extend the semantics of \cdf{function} in this respect; that is, an
        implementation is not allowed to
        define the failure to signal an error to be a ``useful'' behavior.
\end{newer}

\cdf{function}
accepts any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION})
as well as lambda-expressions.
Thus one may write \cd{(function (setf cadr))} to refer to the \cdf{setf}
expansion function for \cdf{cadr}.

\indexterm{closure}
For example:
\begin{lisp}
(defun adder (x) (function (lambda (y) (+ x y))))
\end{lisp}
The result of \cd{(adder 3)} is a function that will add \cd{3} to its
argument:
\begin{lisp}
(setq add3 (adder 3)) \\
(funcall add3 5) \EV\ 8
\end{lisp}
This works because \cdf{function} creates a closure of
the inner lambda-expression that is able to refer to the value \cd{3}
of the variable \cd{x} even after control has returned from the
function \cdf{adder}.

More generally, a lexical closure in effect retains the ability to
refer to lexically visible \emph{bindings}, not just values.
Consider this code:
\begin{lisp}
(defun two-funs (x) \\
~~(list (function (lambda () x)) \\
~~~~~~~~(function (lambda (y) (setq x y))))) \\
(setq funs (two-funs 6)) \\
(funcall (car funs)) \EV\ 6 \\
(funcall (cadr funs) 43) \EV\ 43 \\
(funcall (car funs)) \EV\ 43
\end{lisp}
The function \cdf{two-funs} returns a list of two functions, each of which
refers to the \emph{binding} of the variable \cdf{x} created on entry to
the function \cdf{two-funs} when it was called with argument \cd{6}.
This binding has the value \cd{6} initially, but \cdf{setq} can alter
a binding.  The lexical closure created for the first lambda-expression
does not ``snapshot'' the value \cd{6} for \cdf{x} when the closure is created.
The second function can be used to alter the binding (to \cd{43}, in the
example), and this altered
value then becomes accessible to the first function.

In situations where a closure of a lambda-expression over the same set
of bindings may be produced more than once, the various resulting closures
may or may not be \cdf{eq}, at the discretion of the implementation.
For example:
\begin{lisp}
(let ((x 5) (funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(push \#'(lambda (z) \\*
~~~~~~~~~~~~~~(if (null z) (setq x 0) (+ x z))) \\*
~~~~~~~~~~funs)) \\*
~~funs)
\end{lisp}
The result of the above expression is a list of ten closures.
Each logically requires only the binding of \cdf{x}.
It is the same binding in each case,
so the ten closures may or may not be the same identical (\cdf{eq}) object.
On the other hand, the result of the expression
\begin{lisp}
(let ((funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(let ((x 5)) \\*
~~~~~~(push (function (lambda (z) \\*
~~~~~~~~~~~~~~~~~~~~~~~~(if (null z) (setq x 0) (+ x z)))) \\*
~~~~~~~~~~~~funs))) \\*
~~funs)
\end{lisp}
is also a list of ten closures.
However, in this case no two of the closures may be \cdf{eq}, because each
closure is over a distinct binding of \cdf{x}, and these bindings can
be behaviorally distinguished because of the use of \cdf{setq}.

The question of distinguishable behavior is important; the result of
the simpler expression
\begin{lisp}
(let ((funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(let ((x 5)) \\*
~~~~~~(push (function (lambda (z) (+ x z))) \\*
~~~~~~~~~~~~funs))) \\*
~~funs)
\end{lisp}
is a list of ten closures that \emph{may} be pairwise \cdf{eq}.  Although
one might think that a different binding of \cdf{x} is involved for
each closure (which is indeed the case), the bindings cannot be distinguished
because their values are identical and immutable, there being no occurrence
of \cdf{setq} on \cdf{x}.  A compiler would therefore be justified in
transforming the expression to
\begin{lisp}
(let ((funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(push (function (lambda (z) (+ 5 z))) \\*
~~~~~~~~~~funs)) \\*
~~funs)
\end{lisp}
where clearly the closures may be the same after all.
The general rule, then, is that the implementation is free to
have two distinct evaluations of the same \cdf{function} form
produce identical (\cdf{eq}) closures if it can prove that the
two conceptually distinct resulting closures must in fact be
behaviorally identical with respect to invocation.
This is merely a permitted optimization; a perfectly valid
implementation might simply cause every distinct evaluation of a \cdf{function}
form to produce a new closure object not \cdf{eq} to any other.

Frequently a compiler can deduce that a closure in fact does not
need to close over any variable bindings.  For example,
in the code fragment
\begin{lisp}
(mapcar (function (lambda (x) (+ x 2))) y)
\end{lisp}
the function \cd{(lambda (x) (+ x 2))} contains no references to any outside
entity.  In this important special case, the same ``closure'' may be used
as the value for all evaluations of the \cdf{function} special operator.
Indeed, this value need not be a closure object at all; it may
be a simple compiled function containing no environment information.
This example is simply a special case of the foregoing discussion and
is included as a hint to implementors familiar with previous methods
of implementing Lisp.  The distinction between closures and other
kinds of functions is somewhat pointless, actually, as Common Lisp defines
no particular representation for closures and no way to distinguish
between closures and non-closure functions.  All that matters is that
the rules of lexical scoping be obeyed.

Since \cdf{function} forms are so frequently useful
but somewhat cumbersome to type, a standard abbreviation is defined for them:
any form \emph{f} preceded by \cd{\#'} (\cd{\#} followed by an apostrophe)
is assumed to have \cd{(function  )} wrapped around it to make
\cd{(function \emph{f})}.  For example,
\begin{lisp}
(remove-if \#'numberp '(1 a b 3))
\end{lisp}
is normally interpreted by \cdf{read} to mean
\begin{lisp}
(remove-if (function numberp) '(1 a b 3))
\end{lisp}
See section~\ref{SHARP-SIGN-MACRO-CHARACTER-SECTION}.
\end{defspec}

\begin{defun}[Function]
symbol-value symbol

\cdf{symbol-value} returns the current value of the dynamic (special) variable
named by \emph{symbol}.
An error occurs if the symbol has no value; see \cdf{boundp}
and \cdf{makunbound}.
Note that constant symbols are really variables that cannot be changed,
and so \cdf{symbol-value} may be used to get the value of
a named constant.  In particular, \cdf{symbol-value} of a keyword
will return that keyword.

\cdf{symbol-value} cannot access the value of a lexical variable.

This function is particularly useful for implementing interpreters
for languages embedded in Lisp.
The corresponding assignment primitive is \cdf{set};
alternatively, \cdf{symbol-value} may be used with \cdf{setf}.
\end{defun}

\begin{defun}[Function]
symbol-function symbol

\cdf{symbol-function} returns the current global function definition
named by \emph{symbol}.  An error is signalled if the symbol has no function
definition; see \cdf{fboundp}.  Note that the definition may be a
function or may be an object representing a special operator or macro.
In the latter case, however, it is an error
to attempt to invoke the object as a function.
If it is desired to process macros, special operators, and functions
equally well, as when writing an interpreter,
it is best first to test the symbol with \cdf{macro-function}
and \cdf{special-operator-p}
and then to invoke the functional value only if these
two tests both yield false.

This function is particularly useful for implementing interpreters
for languages embedded in Lisp.

\cdf{symbol-function} cannot access the value of a lexical function name
produced by \cdf{flet} or \cdf{labels}; it can access only
the global function value.

The global function definition of a symbol may be altered
by using \cdf{setf} with \cdf{symbol-function}.
Performing this operation causes the symbol to have \emph{only} the
specified definition as its global function definition; any previous
definition, whether as a macro or as a function, is lost.
It is an error to attempt to redefine the name of a special
form (see table~\ref{SPECIAL-FORM-TABLE}).

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE} to clarify the behavior
of \cdf{symbol-function} in the light of the redefinition of the type \cdf{function}.
\begin{itemize}
\item It is permissible to call \cdf{symbol-function}
    on any symbol for which \cdf{fboundp} returns true.
 Note that \cdf{fboundp} must return true for a symbol naming a macro or
    a special operator.

\item If \cdf{fboundp} returns true for a symbol
        but the symbol denotes a macro or special operator,
        then the value returned by \cdf{symbol-function} is not well-defined
        but \cdf{symbol-function} will not signal an error. 

\item When \cdf{symbol-function} is used with \cdf{setf}
 the new value must be of type \cdf{function}.
	It is an error to set the \cdf{symbol-function} of a symbol to a
	symbol, a list, or the value returned by \cdf{symbol-function} on
	the name of a macro or a special operator.
\end{itemize}
\end{newer}
\end{defun}

\begin{defun}[Function]
fdefinition function-name

X3J13 voted in March 1989 \issue{FUNCTION-NAME} to add the function
\cdf{fdefinition} to the language.
It is exactly like \cdf{symbol-function}
except that its argument may be any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION});
it returns the current global function
definition named by the argument \emph{function-name}.
One may use \cdf{fdefinition} with \cdf{setf}
to change the current global function definition associated with
a function-name.
\end{defun}

\begin{defun}[Function]
boundp symbol

\cdf{boundp} is true if the dynamic (special) variable named by \emph{symbol}
has a value; otherwise, it returns {\false}.

See also \cdf{set} and \cdf{makunbound}.
\end{defun}

\begin{defun}[Function]
fboundp symbol

\cdf{fboundp} is true if the symbol has a global function definition.
Note that \cdf{fboundp} is true when the symbol names a special operator or
macro.  \cdf{macro-function} and \cdf{special-operator-p} may be used to test
for these cases.

Despite the tightening of the definition of the type \cdf{function},
\cdf{fboundp} must return true when the argument names a special operator or
macro.

See also \cdf{symbol-function} and \cdf{fmakunbound}.

\cdf{fboundp}
accepts any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write \cd{(fboundp '(setf cadr))} to determine whether a \cdf{setf}
expansion function has been globally defined for \cdf{cadr}.
\end{defun}

\begin{defun}[Function]
special-operator-p symbol

The function \cdf{special-operator-p} takes a symbol.  If the symbol
globally names a special operator,
then a non-{\false} value is returned; otherwise {\false} is returned.
A returned non-{\nil} value is typically a function
of implementation-dependent nature that can be used to
interpret (evaluate) the special operator.

It is possible for \emph{both} \cdf{special-operator-p} and \cdf{macro-function}
to be true of a symbol.  This is possible because an implementation is
permitted to implement any macro also as a special operator for speed.
On the other hand, the macro definition must be available
for use by programs that understand only the standard special operators
listed in table~\ref{SPECIAL-FORM-TABLE}.
\end{defun}

\subsection{Assignment}

The following facilities allow the value of a variable (more specifically,
the value associated with the current binding of the variable) to be altered.
Such alteration is different from establishing a new binding.
Constructs for establishing new bindings of variables are described
in section~\ref{VAR-BINDING-SECTION}.

\begin{defspec}
setq {var form}*

The special operator \cd{(setq \emph{var1} \emph{form1} \emph{var2} \emph{form2} ...)} is the
``simple variable assignment statement'' of Lisp.
First \emph{form1} is evaluated
and the result is stored in the variable \emph{var1}, then \emph{form2}
is evaluated and the result stored in \emph{var2}, and so forth.
The variables are represented as symbols, of course, and are interpreted
as referring to static or dynamic instances according to the usual rules.
Therefore \cdf{setq} may be used for assignment of both lexical
and special variables.

\cdf{setq} returns the last value assigned, that is, the result of the
evaluation of its last argument.
As a boundary case, the form \cd{(setq)} is legal and returns {\false}.
There must be an even number of argument forms.
For example, in
\begin{lisp}
(setq x (+ 3 2 1) y (cons x nil))
\end{lisp}
\cdf{x} is set to \cd{6}, \cdf{y} is set to \cd{(6)}, and the \cdf{setq}
returns \cd{(6)}.  Note that the first assignment is performed before
the second form is evaluated, allowing that form to
use the new value of \cdf{x}.

See also the description of \cdf{setf},
the Common Lisp ``general assignment statement'' that is capable of assigning
to variables, array elements, and other locations.

Some programmers choose to avoid
\cdf{setq} as a matter of style, always using \cdf{setf} for any kind of
structure modification.  Others use \cdf{setq} with simple variable names and
\cdf{setf} with all other generalized variables.

If any \emph{var}
refers not to an ordinary variable but to a binding made by
\cdf{symbol-macrolet}, then that \emph{var} is handled as
if \cdf{setf} had been used instead of \cdf{setq}.
\end{defspec}

\begin{defmac}
psetq {var form}*

A \cdf{psetq} form is just like a \cdf{setq} form, except
that the assignments happen in parallel.  First all of the forms
are evaluated, and then the variables are set to the resulting
values.  The value of the \cdf{psetq} form is {\false}.
For example:
\begin{lisp}
(setq a 1) \\
(setq b 2) \\
(psetq a b  b a) \\
a \EV\ 2 \\
b \EV\ 1
\end{lisp}
In this example, the values of \cdf{a} and \cdf{b} are exchanged by
using parallel assignment.
(If several variables are to be assigned in parallel in
the context of a loop, the \cdf{do} construct may be appropriate.)

See also the description of \cdf{psetf},
the Common Lisp ``general parallel assignment statement'' that
is capable of assigning
to variables, array elements, and other locations.

If any \emph{var}
refers not to an ordinary variable but to a binding made by
\cdf{symbol-macrolet}, then that \emph{var} is handled as
if \cdf{psetf} had been used instead of \cdf{psetq}.
\end{defmac}

\begin{defun}[Function]
set symbol value

\cdf{set} allows alteration of the value of a dynamic (special) variable.
\cdf{set} causes the dynamic variable named by \emph{symbol} to take on
\emph{value} as its value.

The \emph{value}
may be any Lisp datum whatsoever.

Only the value of the current dynamic binding is altered;
if there are no bindings in effect, the most global value is altered.
For example,
\begin{lisp}
(set (if (eq a b) 'c 'd) 'foo)
\end{lisp}
will either set \cdf{c} to \cdf{foo} or set \cdf{d} to \cdf{foo}, depending
on the outcome of the test \cd{(eq~a~b)}.

\cdf{set} returns \emph{value} as its result.

\cdf{set} cannot alter
the value of a local (lexically bound) variable.
The special operator \cdf{setq}
is usually used for altering the values of variables
(lexical or dynamic) in programs.
\cdf{set} is particularly useful for implementing interpreters for
languages embedded in Lisp.
See also \cdf{progv}, a construct that performs binding rather
than assignment of dynamic variables.
\end{defun}

\begin{defun}[Function]
makunbound symbol \\
fmakunbound symbol

\cdf{makunbound} causes the dynamic (special) variable named
by \emph{symbol} to become unbound (have no value).  \cdf{fmakunbound}
does the analogous thing for the global function definition named
by \emph{symbol}.
For example:
\begin{lisp}
(setq a 1) \\
a \EV\ 1 \\
(makunbound 'a) \\
a \EV\ \textrm{causes an error} \\
\\
(defun foo (x) (+ x 1)) \\
(foo 4) \EV\ 5 \\
(fmakunbound 'foo) \\
(foo 4) \EV\ \textrm{causes an error}
\end{lisp}
Both functions return \emph{symbol} as the result value.

\cdf{fmakunbound}
accepts any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write \cd{(fmakunbound '(setf cadr))} to remove any
global definition of a \cdf{setf} expansion function for \cdf{cadr}.
\end{defun}

\section{Generalized Variables}
\label{SETF-SECTION}
 
In Lisp, a variable can remember one piece of data,
that is, one Lisp object.
The main operations on a variable are to recover that object and
to alter the variable to remember a new object; these operations are
often called \emph{access} and \emph{update} operations.  The concept of
variables named by symbols can be generalized to any storage location
that can remember one piece of data, no matter how that location is
named.  Examples of such storage locations are the \emph{car} and \emph{cdr} of
a cons, elements of an array, and components of a structure.

For each kind of generalized variable, typically there are two functions
that implement the conceptual \emph{access} and \emph{update} operations.
For a variable, merely mentioning the name of the variable accesses it,
while the \cdf{setq} special operator can be used to update it.
The function \cdf{car} accesses the \emph{car} of a cons,
and the function \cdf{rplaca} updates it.
The function \cdf{symbol-value} accesses the dynamic value of a variable
named by a given symbol, and the function \cdf{set} updates it.

Rather than thinking about two distinct functions that respectively
access and update a storage location somehow deduced from their
arguments, we can instead simply think of a call to the access function
with given arguments as a \emph{name} for the storage location.  Thus, just
as \cdf{x} may be considered a name for a storage location (a variable), so
\cd{(car x)} is a name for the \emph{car} of some cons (which is in turn
named by \cdf{x}).  Now, rather than having to remember two functions for
each kind of generalized variable (having to remember, for example, that
\cdf{rplaca} corresponds to \cdf{car}), we adopt a uniform syntax for updating
storage locations named in this way, using the \cdf{setf} macro.
This is analogous to the way we use the \cdf{setq} special operator to convert
the name of a variable (which is also a form that accesses it) into a
form that updates it.  The uniformity of this approach is illustrated in
the following table.

\begin{flushleft}
\begin{tabular*}{\textwidth}{@{}l@{\extracolsep{\fill}}ll@{}}
\textrm{Access Function}&\textrm{Update Function}&\textrm{Update Using \cdf{setf}} \\
\hlinesp
\cd{x}&\cd{(setq x datum)}&\cd{(setf x datum)} \\
\cd{(car x)}&\cd{(rplaca x datum)}&\cd{(setf (car x) datum)} \\
\cd{(symbol-value x)}&\cd{(set x datum)}&\cd{(setf (symbol-value x) datum)} \\
\hline
\end{tabular*}
\end{flushleft}
\cdf{setf} is actually a macro that examines an access form and
produces a call to the corresponding update function.

Given the existence of \cdf{setf} in Common Lisp, it is not necessary to have
\cdf{setq}, \cdf{rplaca}, and \cdf{set}; they are redundant.  They
are retained in Common Lisp because of their historical importance in Lisp.
However, most other update functions (such as \cdf{putprop}, the update
function for \cdf{get}) have been eliminated from Common Lisp
in the expectation that \cdf{setf} will be uniformly used in their place.

\begin{defmac}
setf {place newvalue}*

\cd{(setf \emph{place} \emph{newvalue})} takes a form \emph{place} that when evaluated
\emph{accesses} a data object in some location and ``inverts''
it to produce a corresponding form to \emph{update} the location.
A call to the \cdf{setf} macro therefore
expands into an update form that stores the result of evaluating
the form \emph{newvalue} into the place referred to by the access form.

If more than one \emph{place}-\emph{newvalue} pair is specified,
the pairs are processed sequentially; that is,
\begin{lisp}
(setf \emph{place1} \emph{newvalue1} \\
~~~~~~\emph{place2} \emph{newvalue2}) \\
~~~~~~... \\
~~~~~~\emph{placen} \emph{newvaluen})
\end{lisp}
is precisely equivalent to
\begin{lisp}
(progn (setf \emph{place1} \emph{newvalue1}) \\
~~~~~~~(setf \emph{place2} \emph{newvalue2}) \\
~~~~~~~... \\
~~~~~~~(setf \emph{placen} \emph{newvaluen}))
\end{lisp}
For consistency, it is legal to write \cd{(setf)}, which simply returns {\nil}.

The form \emph{place} may be any one of the following:
\begin{itemize}
\item
The name of a variable (either lexical or dynamic).

\item
A function call form whose first element is the name of
any one of the following functions:

\begin{flushleft}
\begin{tabular}{@{}llll@{}}
\cdf{aref}&\cdf{car}&\cdf{svref}& \\
\cdf{nth}&\cdf{cdr}&\cdf{get}& \\
\cdf{elt}&\cdf{caar}&\cdf{getf}&\cdf{symbol-value} \\
\cdf{rest}&\cdf{cadr}&\cdf{gethash}&\cdf{symbol-function} \\
\cdf{first}&\cdf{cdar}&\cdf{documentation}&\cdf{symbol-plist} \\
\cdf{second}&\cdf{cddr}&\cdf{fill-pointer}&\cdf{macro-function} \\
\cdf{third}&\cdf{caaar}&\cdf{caaaar}&\cdf{cdaaar} \\
\cdf{fourth}&\cdf{caadr}&\cdf{caaadr}&\cdf{cdaadr} \\
\cdf{fifth}&\cdf{cadar}&\cdf{caadar}&\cdf{cdadar} \\
\cdf{sixth}&\cdf{caddr}&\cdf{caaddr}&\cdf{cdaddr} \\
\cdf{seventh}&\cdf{cdaar}&\cdf{cadaar}&\cdf{cddaar} \\
\cdf{eighth}&\cdf{cdadr}&\cdf{cadadr}&\cdf{cddadr} \\
\cdf{ninth}&\cdf{cddar}&\cdf{caddar}&\cdf{cdddar} \\
\cdf{tenth}&\cdf{cdddr}&\cdf{cadddr}&\cdf{cddddr} \\
\cdf{row-major-aref}&\cdf{compiler-macro-function}& & 
\end{tabular}
\end{flushleft}

This
rule applies only when the function name refers to a global function
definition and not to a locally defined function or macro.

\item
A function call form whose first element is the name of
a selector function constructed by \cdf{defstruct}.

This
rule applies only when the function name refers to a global function
definition and not to a locally defined function or macro.

\item
A function call form whose first element is the name of
any one of the following functions, provided that the new value

is of the specified type so that it can be used to
replace the specified ``location'' (which is in each of these cases
not truly a generalized variable):

\begin{obsolete}
\begin{flushleft}
\leavevmode
\begin{tabular}{@{}ll@{}}
Function Name&Required Type \\
\hlinesp
\cdf{char}&\cdf{string-char} \\
\cdf{schar}&\cdf{string-char} \\
\cdf{bit}&\cdf{bit} \\
\cdf{sbit}&\cdf{bit} \\
\cdf{subseq}&\cdf{sequence} \\
\hline
\end{tabular}
\end{flushleft}
\end{obsolete}

\begin{newer}
X3J13 voted in March 1989 \issue{CHARACTER-PROPOSAL}
to eliminate the type \cdf{string-char} and to redefine
\cdf{string} to be the union of one or more specialized vector
types, the types of whose elements are subtypes of the type \cdf{character}.
In the preceding table, the type \cdf{string-char} should be replaced
by some such phrase as ``the element-type of the argument vector.''
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to clarify that this
rule applies only when the function name refers to a global function
definition and not to a locally defined function or macro.
\end{newer}

In the case of \cdf{subseq}, the replacement value must be a sequence
whose elements may be contained by the sequence argument to \cdf{subseq}.
(Note that this is not so stringent as to require that the
replacement value be a sequence of the same type as the sequence
of which the subsequence is specified.)
If the length of the replacement value does not equal the length of
the subsequence to be replaced, then the shorter length determines
the number of elements to be stored, as for the function \cdf{replace}.

\item
A function call form whose first element is the name of
any one of the following functions, provided that the specified argument
to that function is in turn a \emph{place} form;
in this case the new \emph{place} has stored back into it the
result of applying the specified ``update'' function
(which is in each of these cases not a true update function):

\begin{flushleft}
\begin{tabular}{@{}lll@{}}
Function Name&Argument That Is a \emph{place}&Update Function Used \\
\hlinesp
\cdf{ldb}&second&\cdf{dpb} \\
\cdf{mask-field}&second&\cdf{deposit-field} \\
\hline
\end{tabular}
\end{flushleft}

This
rule applies only when the function name refers to a global function
definition and not to a locally defined function or macro.

\item
A \cdf{the} type declaration form, in which case the declaration is
transferred to the \emph{newvalue} form, and the resulting \cdf{setf} form is
analyzed.  For example,
\begin{lisp}
(setf (the integer (cadr x)) (+ y 3))
\end{lisp}
is processed as if it were
\begin{lisp}
(setf (cadr x) (the integer (+ y 3)))
\end{lisp}

\item
A call to \cdf{apply} where the first argument form is of the form
\cd{\#'\emph{name}}, that is, \cd{(function \emph{name})}, where \emph{name}
is the name of a function, calls to which are recognized as places by \cdf{setf}.
Suppose that the use of \cdf{setf} with \cdf{apply} looks like this:
\begin{lisp}
(setf (apply \#'\emph{name} \emph{x1} \emph{x2} ... \emph{xn} \emph{rest}) \emph{x0})
\end{lisp}
The \cdf{setf} method for the function \emph{name} must be such that
\begin{lisp}
(setf (\emph{name} \emph{z1} \emph{z2} ... \emph{zm}) \emph{z0})
\end{lisp}
expands into a store form
\begin{lisp}
(\emph{storefn} \emph{zi${}_1$} \emph{zi${}_2$} ... \emph{zi${}_k$} \emph{zm})
\end{lisp}
That is, it must expand into a function call such that all arguments but
the last may be any permutation or subset of the new value \emph{z0} and
the arguments of the access form, but the \emph{last} argument of the storing
call must be the same as the last argument of the access call.
See \cdf{define-setf-method} for more details on accessing
and storing forms.

Given this, the \cdf{setf}-of-\cdf{apply} form shown above expands into
\begin{lisp}
(apply \#'\emph{storefn} \emph{xi${}_1$} \emph{xi${}_2$} ... \emph{xi${}_k$} \emph{rest})
\end{lisp}
As an example, suppose that the variable \cdf{indexes} contains a list
of subscripts for a multidimensional array \emph{foo} whose rank is not
known until run time.  One may access the indicated
element of the array by writing
\begin{lisp}
(apply \#'aref foo indexes)
\end{lisp}
and one may alter the value of the indicated element to that
of \cdf{newvalue} by writing
\begin{lisp}
(setf (apply \#'aref foo indexes) newvalue)
\end{lisp}

This
rule applies only when the function name \cdf{apply} refers to the global function
definition and not to a locally defined function or macro named \cdf{apply}.

\item
A macro call, in which case \cdf{setf} expands the macro call and
then analyzes the resulting form.

This
step uses \cdf{macroexpand-1}, not \cdf{macroexpand}.  This allows the chance
to apply any of the rules preceding this one to any of the intermediate expansions.

\item
Any form for which a \cdf{defsetf}
or \cdf{define-setf-method} declaration has been made.

This
rule applies only when the function name in the form refers to a global function
definition and not to a locally defined function or macro.

\end{itemize}

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to add one more rule to
the preceding list, coming after all those listed above:
\begin{itemize}
\item  Any other list whose first element is a symbol (call it \emph{f\/}).
     In this case, the call to \cdf{setf} expands into a call to the function
     named by the
     list \cd{(setf~\emph{f\/})} (see section~\ref{FUNCTION-NAME-SECTION}).
     The first argument is the new value and the
     remaining arguments are the values of the remaining elements of
     \emph{place}.  This expansion occurs regardless of whether either \emph{f\/} or
     \cd{(setf \emph{f\/})} is defined as a function locally, globally, or not at
     all.  For example,
\begin{lisp}
(setf (\emph{f\/} \emph{arg1} \emph{arg2} ...) \emph{newvalue})
\end{lisp}
     expands into a form with the same effect and value as
\begin{lisp}
(let ((\#:temp1 \emph{arg1})~~~~~;\textrm{Force correct order of evaluation} \\*
~~~~~~(\#:temp2 \emph{arg2}) \\*
~~~~~~... \\*
~~~~~~(\#:temp0 newvalue)) \\*
~~(funcall (function (setf \emph{f\/})) \\*
~~~~~~~~~~~\#:temp0 \\*
~~~~~~~~~~~\#:temp1 \\*
~~~~~~~~~~~\#:temp2 ...))
\end{lisp}
By convention, any function named \cd{(setf \emph{f\/})} should return its first
argument as its only value, in order to preserve the specification that
\cdf{setf} returns its \emph{newvalue}.
\end{itemize}
\end{newer}

\begin{new}
X3J13 voted in March 1989
\issue{SYMBOL-MACROLET-SEMANTICS} to add this case as well:
\begin{itemize}
\item A variable reference that refers to a symbol macro definition made by
\cdf{symbol-macrolet}, in which case \cdf{setf} expands the reference and
then analyzes the resulting form.
\end{itemize}
\end{new}

\cdf{setf} carefully arranges to preserve the usual left-to-right
order in which the various subforms are evaluated.
On the other hand,
the exact expansion for any particular form is not guaranteed and
may even be implementation-dependent; all that is guaranteed is that
the expansion of a \cdf{setf} form will be an update form that works
for that particular implementation, and that the left-to-right evaluation
of subforms is preserved.

The ultimate result of evaluating a \cdf{setf} form is the value
of \emph{newvalue}.  Therefore \cd{(setf (car x) y)} does not expand
into precisely \cd{(rplaca x y)}, but into something more like
\begin{lisp}
(let ((G1 x) (G2 y)) (rplaca G1 G2) G2)
\end{lisp}
the precise expansion being implementation-dependent.

The user can define new \cdf{setf} expansions by using \cdf{defsetf}.

\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{setf} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.

A proposal was submitted to X3J13 in September 1989
to add a \cdf{setf} method for \cdf{values} so that one could
in fact write, for example,
\begin{lisp}
(setf (values quotient remainder) \\
~~~~~~(truncate linewidth tabstop))
\end{lisp}
but unless this proposal is accepted users will have to
define a \cdf{setf} method for \cdf{values} themselves (not a difficult task).
\end{newer}
\end{defmac}

\begin{defmac}
psetf {place newvalue}*

\cdf{psetf} is like \cdf{setf} except that if more than one \emph{place}-\emph{newvalue}
pair is specified, then the assignments of new values to places are
done in parallel.  More precisely, all subforms that are to be evaluated
are evaluated from left to right; after all evaluations have been performed,
all of the assignments are performed in an unpredictable order.
(The unpredictability matters only if more than one \emph{place} form
refers to the same place.)
\cdf{psetf} always returns {\false}.

\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{psetf} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.
\end{newer}
\end{defmac}

\begin{defmac}
shiftf {place}+ newvalue

Each \emph{place} form may be any form acceptable
as a generalized variable to \cdf{setf}.
In the form \cd{(shiftf \emph{place1} \emph{place2} ... \emph{placen} \emph{newvalue})},
the values in \emph{place1} through \emph{placen} are accessed and saved,
and \emph{newvalue} is evaluated, for a total of $\emph{n}+1$ values in all.
Values 2 through $\emph{n}+1$ are then stored into \emph{place1} through \emph{placen},
and value 1 (the original value of \emph{place1}) is returned.
It is as if all the places form a shift register; the \emph{newvalue}
is shifted in from the right, all values shift over to the left one place,
and the value shifted out of \emph{place1} is returned.  For example:
\begin{lisp}
(setq x (list 'a 'b 'c)) \EV\ (a b c) \\
 \\
(shiftf (cadr x) 'z) \EV\ b \\
~~~\textrm{and now} x \EV\ (a z c) \\
 \\
(shiftf (cadr x) (cddr x) 'q) \EV\ z \\
~~~\textrm{and now} x \EV\ (a (c) . q)
\end{lisp}
The effect of \cd{(shiftf \emph{place1} \emph{place2} ... \emph{placen} \emph{newvalue})}
is equivalent to
\begin{lisp}
(let ((\emph{var1} \emph{place1}) \\
~~~~~~(\emph{var2} \emph{place2}) \\
~~~~~~... \\
~~~~~~(\emph{varn} \emph{placen})) \\
~~(setf \emph{place1} \emph{var2}) \\
~~(setf \emph{place2} \emph{var3}) \\
~~... \\
~~(setf \emph{placen} \emph{newvalue}) \\
~~\emph{var1})
\end{lisp}
except that the latter would evaluate any subforms of each \emph{place} twice,
whereas \cdf{shiftf} takes care to evaluate them only once.
For example:
\begin{lisp}
(setq n 0) \\
(setq x '(a b c d)) \\
(shiftf (nth (setq n (+ n 1)) x) 'z) \EV\ b \\
~~~\textrm{and now} x \EV\ (a z c d) \\[4pt]
\emph{but} \\[4pt]
(setq n 0) \\
(setq x '(a b c d)) \\
(prog1 (nth (setq n (+ n 1)) x) \\*
~~~~~~~(setf (nth (setq n (+ n 1)) x) 'z)) \EV\ b \\
~~~\textrm{and now} x \EV\ (a b z d)
\end{lisp}
Moreover, for certain \emph{place} forms \cdf{shiftf} may be
significantly more efficient than the \cdf{prog1} version.

\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{shiftf} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.
\end{newer}

\beforenoterule
\begin{rationale}
\cdf{shiftf} and \cdf{rotatef} have been included in Common Lisp
as generalizations of two-argument versions formerly called \cdf{swapf}
and \cdf{exchf}.  The two-argument versions have been found to be
very useful, but the names were easily confused.  The generalization
to many argument forms and the change of names were both inspired
by the work of Suzuki \cite{SUZUKI-POINTER-ROTATION},
which indicates that use of these primitives can make certain complex
pointer-manipulation programs clearer and easier to prove correct.
\end{rationale}
\afternoterule
\end{defmac}

\begin{defmac}
rotatef {place}*

Each \emph{place} form may be any form acceptable
as a generalized variable to \cdf{setf}.
In the form \cd{(rotatef \emph{place1} \emph{place2} ... \emph{placen})},
the values in \emph{place1} through \emph{placen} are accessed and saved.
Values 2 through \emph{n} and value 1 are then stored into \emph{place1} through \emph{placen}.
It is as if all the places form an end-around shift register
that is rotated one place to the left, with the value of \emph{place1}
being shifted around the end to \emph{placen}.
Note that \cd{(rotatef \emph{place1} \emph{place2})} exchanges the contents
of \emph{place1} and \emph{place2}.

The effect of \cd{(rotatef \emph{place1} \emph{place2} ... \emph{placen})}
is roughly equivalent to
\begin{lisp}
(psetf \emph{place1} \emph{place2} \\
~~~~~~~\emph{place2} \emph{place3} \\
~~~~~~~... \\
~~~~~~~\emph{placen} \emph{place1})
\end{lisp}
except that the latter would evaluate any subforms of each \emph{place} twice,
whereas \cdf{rotatef} takes care to evaluate them only once.
Moreover, for certain \emph{place} forms \cdf{rotatef} may be
significantly more efficient.

\cdf{rotatef} always returns {\false}.

\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{rotatef} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.
\end{newer}
\end{defmac}

Other macros that manipulate generalized variables include
\cdf{getf}, \cdf{remf},
\cdf{incf}, \cdf{decf}, \cdf{push}, \cdf{pop},
\cdf{assert}, \cdf{ctypecase}, and \cdf{ccase}.

Macros that manipulate generalized variables must guarantee the ``obvious''
semantics:  subforms of generalized-variable references are
evaluated exactly as many times as they appear in the source program, and
they are evaluated in exactly the same order as they appear in the source
program.

In generalized-variable references such as \cdf{shiftf}, \cdf{incf}, \cdf{push},
and \cdf{setf} of \cdf{ldb}, the generalized variables are both read and
written in the same reference.   Preserving the source program order of
evaluation and the number of evaluations is particularly important.

As an example of these semantic rules, in the generalized-variable
reference \cd{(setf \emph{reference} \emph{value})} the \emph{value} form
must be evaluated \emph{after} all the subforms of the reference because
the \emph{value} form appears to the right of them.

The expansion of these macros must consist of code that follows these
rules or has the same effect as such code.  This is accomplished by
introducing temporary variables bound to the subforms of the reference.
As an optimization in the implementation,
temporary variables may be eliminated whenever it
can be proved that removing them has no effect on the semantics of the program.
For example, a constant need never be saved in a temporary variable.
A variable, or for that matter any form that does not have side effects, need not be
saved in a temporary variable if it can be proved that its value will
not change within the scope of the generalized-variable reference.

Common Lisp provides built-in facilities to take care of
these semantic complications and optimizations.  Since the required
semantics can be guaranteed by these facilities, the user does not
have to worry about writing correct code for them, especially in
complex cases.  Even experts can become confused and make mistakes
while writing this sort of code.

\begin{newer}
X3J13 voted in March 1988 \issue{PUSH-EVALUATION-ORDER}
to clarify the preceding discussion about the order of evaluation of
subforms in calls to \cdf{setf} and related macros.
The general intent is clear: evaluation
proceeds from left to right whenever possible. However, the left-to-right rule does not
remove the obligation on writers of macros and \cdf{define-setf-method} to work
to ensure left-to-right order of evaluation.

Let it be emphasized that, in the following discussion,
a \emph{form} is something whose syntactic use is such that it will
be evaluated.  A \emph{subform} means a form that is nested inside another form,
not merely any Lisp object nested inside a form regardless of syntactic context. 

The evaluation ordering of subforms within a generalized variable
reference is determined by the order specified by the second value returned by
\cdf{get-setf-method}.  For all predefined generalized variable references
(\cdf{getf}, \cdf{ldb}), this order of evaluation is exactly left-to-right.
When a generalized
variable reference is derived from a macro expansion, this rule is applied
\emph{after} the macro is expanded to find the appropriate generalized variable
reference. 

This is intended to make it clear that if the user writes a \cdf{defmacro} or
\cdf{define-setf-method} macro that doesn't preserve left-to-right
evaluation order, the order specified in the
user's code holds.  For example, given
\begin{lisp}
(defmacro wrong-order (x y) {\Xbq}(getf ,y ,x))
\end{lisp}
then
\begin{lisp}
(push \emph{value} (wrong-order \emph{place1} \emph{place2}))
\end{lisp}
will evaluate \emph{place2} first and then \emph{place1} because that is the order they
are evaluated in the macro expansion.
 
For the macros that manipulate generalized variables (\cdf{push}, \cdf{pushnew}, \cdf{getf},
\cdf{remf}, \cdf{incf}, \cdf{decf}, \cdf{shiftf}, \cdf{rotatef},
\cdf{psetf}, \cdf{setf}, \cdf{pop}, and those defined with
\cdf{define-modify-macro}) the subforms of the macro call are evaluated exactly once
in left-to-right order, with the subforms of the generalized variable
references evaluated in the order specified above.

Each of
\cdf{push}, \cdf{pushnew}, \cdf{getf}, \cdf{remf}, \cdf{incf}, \cdf{decf},
\cdf{shiftf}, \cdf{rotatef}, \cdf{psetf}, and \cdf{pop} evaluates
all subforms before modifying any of the generalized variable locations.  Moreover,
\cdf{setf} itself,
in the case when a call on it has more than two arguments, performs its
operation on each pair in sequence.  That is, in
\begin{lisp}
(setf \emph{place1} \emph{value1} \emph{place2} \emph{value2} ...)
\end{lisp}
the subforms of \emph{place1} and \emph{value1} are evaluated, the
location specified by \emph{place1} is modified to contain the value returned by
\emph{value1}, and then the rest of the \cdf{setf} form is processed in a like manner.

For the macros \cdf{check-type}, \cdf{ctypecase}, and \cdf{ccase}, subforms of the
generalized variable reference are evaluated once per test of a generalized
variable, but they may be
evaluated again if the type check fails (in the case of \cdf{check-type}) or if none of
the cases holds (in \cdf{ctypecase} or \cdf{ccase}).

For the macro \cdf{assert}, the order of evaluation of the generalized variable
references is not specified.
\end{newer}

Another reason for building in these functions is that the
appropriate optimizations will differ from implementation to
implementation.  In some implementations most of the optimization is
performed by the compiler, while in others a simpler compiler is used and
most of the optimization is performed in the macros.  The cost of
binding a temporary variable relative to the cost of other Lisp
operations may differ greatly between one implementation
and another, and some implementations may find it
best never to remove temporary variables except in the simplest cases.

A good example of the issues involved can be seen in the following
generalized-variable reference:
\begin{lisp}
(incf (ldb byte-field variable))
\end{lisp}
This ought to expand into something like
\begin{lisp}
(setq variable \\
~~~~~~(dpb (1+ (ldb byte-field variable)) \\
~~~~~~~~~~~byte-field \\
~~~~~~~~~~~variable))
\end{lisp}
In this expansion example we have
ignored the further complexity of returning the correct
value, which is the incremented byte, not the new value of \cdf{variable}.
Note that the variable \cdf{byte-field} is evaluated twice, and the
variable \cdf{variable} is referred to three times:
once as the location in which to store a value,
and twice during the computation of that value.

Now consider this expression:
\begin{lisp}
(incf (ldb (aref byte-fields (incf i)) \\
~~~~~~~~~~~(aref (determine-words-array) i)))
\end{lisp}
It ought to expand into something like this:
\begin{lisp}
(let ((temp1 (aref byte-fields (incf i))) \\
~~~~~~(temp2 (determine-words-array))) \\
~~(setf (aref temp2 i) \\
~~~~~~~~(dpb (1+ (ldb temp1 (aref temp2 i))) \\
~~~~~~~~~~~~~temp1 \\
~~~~~~~~~~~~~(aref temp2 i))))
\end{lisp}
Again we have ignored the complexity of returning the correct value.
What is important here is that the expressions \cd{(incf i)}
and \cd{(determine-words-array)}
must not be duplicated because each may have a side effect or
be affected by side effects.

\begin{newer}
X3J13 voted in January 1989 \issue{SETF-SUB-METHODS}
to specify more precisely the order of evaluation of subforms
when \cdf{setf} is used with an access function that itself
takes a \emph{place} as an argument, for example, \cdf{ldb}, \cdf{mask-field}, and
\cdf{getf}.  (The vote also discussed the function \cdf{char-bit},
but another vote \issue{CHARACTER-PROPOSAL} removed that function
from the language.)  The \cdf{setf} methods for such accessors produce expansions
that effectively require explicit calls to \cdf{get-setf-method}.

The code produced as the macro expansion of a \cdf{setf} form that
itself admits a generalized variable as an argument must essentially
do the following major steps:
\begin{itemize}
\item It evaluates the value-producing subforms, in left-to-right order, and 
     binds the temporary variables to them; this is called \emph{binding the temporaries}.

\item It reads the value from the generalized variable, using the supplied 
     accessing form, to get the old value;  this is called \emph{doing the
     access}.  Note that this is done after all the evaluations of the 
     preceding step, including any side effects they may have.

\item It binds the store variable to a new value, and then installs this
     new value into the generalized variable using the supplied storing 
     form; this is called \emph{doing the store}.
\end{itemize}
Doing the access for a generalized variable reference is not part of
the series of evaluations that must be done in left-to-right order. 

The place-specifier forms \cdf{ldb}, \cdf{mask-field}, and \cdf{getf} admit (other)
\emph{place} specifiers as arguments. During the \cdf{setf} expansion of these forms, it 
is necessary to call \cdf{get-setf-method} to determine how the inner, 
nested generalized variable must be treated.

    In a form such as
\begin{lisp}
(setf (ldb \emph{byte-spec} \emph{place-form}) \emph{newvalue-form})
\end{lisp}
    the place referred to by the \emph{place-form} must always be both accessed 
    and updated;  note that the update is to the generalized variable 
    specified by \emph{place-form}, not to any object of type \cdf{integer}.

    Thus this call to \cdf{setf} should generate code to do the following:
\begin{itemize}
    \item Evaluate \emph{byte-spec} and bind into a temporary
    \item Bind the temporaries for \emph{place-form}
    \item Evaluate \emph{newvalue-form} and bind into the store variable
    \item Do the access to \emph{place-form}
    \item Do the store into \emph{place-form} with the given bit-field of the
          accessed integer replaced with the value in the store variable
\end{itemize}
    If the evaluation of \emph{newvalue-form} alters what is found in the 
    given \emph{place}---such as setting a different bit-field of the
    integer---then the change of the bit-field denoted by
    \emph{byte-spec} will be to that 
    altered integer, because the access step must be done after the \emph{newvalue-form}
    evaluation.  Nevertheless, the 
    evaluations required for binding the temporaries are done before the
    evaluation of the \emph{newvalue-form}, thereby preserving
    the required left-to-right evaluation order.

The treatment of \cdf{mask-field} is similar to that of \cdf{ldb}.

    In a form such as:
\begin{lisp}
(setf (getf \emph{place-form} \emph{ind-form}) \emph{newvalue-form})
\end{lisp}
    the place referred to by the \emph{place-form} must always be both accessed 
    and updated;  note that the update is to the generalized variable 
    specified by \emph{place-form}, not necessarily to the particular list
    which is the property list in question.

    Thus this call to \cdf{setf} should generate code to do the following:
\begin{itemize}
    \item Bind the temporaries for \emph{place-form} 
    \item Evaluate \emph{ind-form} and bind into a temporary
    \item Evaluate the \emph{newvalue-form} and bind into the store variable
    \item Do the access to \emph{place-form}
    \item Do the store into \emph{place-form} with a possibly new property list
       obtained by combining the results of the evaluations and the access
\end{itemize}

    If the evaluation of \emph{newvalue-form} alters what is found in the 
    given \emph{place}---such as setting a different named property in the
    list---then the change of the property denoted by \emph{ind-form} will be to that 
    altered list, because the access step is done after the \emph{newvalue-form}
    evaluation.   Nevertheless, the 
    evaluations required for binding the temporaries are done before the
    evaluation of the \emph{newvalue-form}, thereby preserving
    the required left-to-right evaluation order.

    Note that the phrase ``possibly new property list'' treats the 
    implementation of property lists as a ``black box''; it can mean that 
    the former property list is somehow destructively re-used, or it can 
    mean partial or full copying of it.  A side effect may or may not occur;
    therefore \cdf{setf} must proceed as if the resultant property list
    were a different copy
    needing to be stored back into the generalized variable.
\end{newer}

The Common Lisp facilities provided to deal with these semantic issues include:
\begin{itemize}
\item
Built-in macros such as \cdf{setf} and \cdf{push} that follow the semantic rules.

\item
The \cdf{define-modify-macro} macro, which allows new generalized-variable
manipulating macros (of a certain restricted kind) to be defined easily.
It takes care of the semantic rules automatically.

\item
The \cdf{defsetf} macro, which allows new types of generalized-variable references
to be defined easily.  It takes care of the semantic rules automatically.

\item
The \cdf{define-setf-method} macro and the \cdf{get-setf-method} function, which
provide access to the internal mechanisms when it is necessary
to define a complicated new type of generalized-variable reference
or generalized-variable-manipulating macro.
\end{itemize}

\begin{newer}
Also important are the changes that allow lexical environments to be
used in appropriate ways in \cdf{setf} methods.
\end{newer}

\begin{defmac}
define-modify-macro name lambda-list function [doc-string]

This macro defines a read-modify-write macro
named \emph{name}.  An example of such a macro is \cdf{incf}.  The first
subform of the macro will be a generalized-variable reference.
The \emph{function} is literally the function to apply to the old contents of the
generalized-variable to get the new contents; it is not evaluated.
\emph{lambda-list} describes
the remaining arguments for the \emph{function}; these arguments come from
the remaining subforms of the macro after the generalized-variable reference.
\emph{lambda-list} may contain \cd{\&optional} and \cd{\&rest} markers.
(The \cd{\&key} marker is not permitted here; \cd{\&rest} suffices for the purposes
of \cdf{define-modify-macro}.)
\emph{doc-string} is documentation for the macro \emph{name} being defined.

The expansion of a \cdf{define-modify-macro} is equivalent to the following, except
that it generates code that follows the semantic rules outlined above.
\begin{lisp}
(defmacro \emph{name} (\emph{reference} . \emph{lambda-list}) \\
~~\emph{doc-string} \\
~~{\Xbq}(setf ,\emph{reference} \\
~~~~~~~~~(\emph{function} ,\emph{reference} ,\emph{arg1} ,\emph{arg2} ...)))
\end{lisp}
where \emph{arg1}, \emph{arg2}, ..., are the parameters appearing in \emph{lambda-list};
appropriate provision is made for a \cd{\&rest} parameter.

As an example, \cdf{incf} could have been defined by:
\begin{lisp}
(define-modify-macro incf (\&optional (delta 1)) +)
\end{lisp}

An example of a possibly useful macro not predefined in Common Lisp is
\begin{lisp}
(define-modify-macro unionf (other-set \&rest keywords) union)
\end{lisp}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to specify that \cdf{define-modify-macro} creates macros that
take \cd{\&environment} arguments and perform the
equivalent of correctly passing such lexical
environments to \cdf{get-setf-method} in order to correctly maintain 
lexical references.
\end{newer}
\end{defmac}

\begin{defmac}
defsetf access-fn {update-fn [doc-string] | lambda-list (store-variable) <{declaration}* | doc-string> {form}*}

This defines how to \cdf{setf} a generalized-variable reference
of the form \cd{(\emph{access-fn} ...)}.  The value of a generalized-variable
reference can always be obtained simply by evaluating it, so \emph{access-fn}
should be the name of a function or a macro.

The user of \cdf{defsetf} provides a description of how to store into the
generalized-variable reference and return the value that was stored (because
\cdf{setf} is defined to return this value).  The implementation
of \cdf{defsetf} takes care of
ensuring that subforms of the reference are evaluated exactly once and
in the proper left-to-right order.  In order to do this,
\cdf{defsetf} requires that \emph{access-fn} be a function or a macro
that evaluates its arguments, behaving like a function.
Furthermore, a \cdf{setf} of a call on \emph{access-fn} will also evaluate
all of \emph{access-fn}'s arguments; it cannot treat any of them specially.
This means that \cdf{defsetf} cannot be used to describe how to store into
a generalized variable that is a byte, such as \cd{(ldb field reference)}.
To handle situations that do not fit the restrictions imposed by \cdf{defsetf},
use \cdf{define-setf-method}, which gives the user additional control
at the cost of increased complexity.

A \cdf{defsetf} declaration may take one of two forms.
The simple form is
\begin{lisp}
(defsetf \emph{access-fn} \emph{update-fn} \Mopt{\emph{doc-string}})
\end{lisp}
The \emph{update-fn} must name a function (or macro) that takes one more argument
than \emph{access-fn} takes.  When \cdf{setf} is given a \emph{place}
that is a call on \emph{access-fn}, it expands into
a call on \emph{update-fn} that is given all the arguments to
\emph{access-fn} and also, as its last argument, the new value
(which must be returned by \emph{update-fn} as its value).
For example, the effect of
\begin{lisp}
(defsetf symbol-value set)
\end{lisp}
is built into the Common Lisp system.
This causes the expansion
\begin{lisp}
(setf (symbol-value foo) fu) \EX\ (set foo fu)
\end{lisp}
for example.  Note that
\begin{lisp}
(defsetf car rplaca)
\end{lisp}
would be incorrect because \cdf{rplaca} does not return its last argument.

The complex form of \cdf{defsetf} looks like
\begin{lisp}
(defsetf \emph{access-fn} \emph{lambda-list} (\emph{store-variable}) . \emph{body})
\end{lisp}
and resembles \cdf{defmacro}.  The \emph{body} must
compute the expansion of a \cdf{setf} of a call on \emph{access-fn}.

The \emph{lambda-list} describes the arguments of \emph{access-fn}.  \cd{\&optional},
\cd{\&rest}, and \cd{\&key} markers are permitted in \emph{lambda-list}.
Optional arguments may
have defaults and ``supplied-p'' flags.  The \emph{store-variable} describes the
value to be stored into the generalized-variable reference.

\beforenoterule
\begin{rationale}
The \emph{store-variable} is enclosed
in parentheses to provide for an extension
to multiple store variables that would
receive multiple values from the second subform of \cdf{setf}.
The rules given below for coding \cdf{setf} methods discuss
the proper handling of multiple store variables to allow for
the possibility that this extension may be incorporated into Common Lisp
in the future.
\end{rationale}
\afternoterule

The \emph{body} forms can be written as if the variables in the \emph{lambda-list}
were bound to subforms of the call on \emph{access-fn} and the
\emph{store-variable} were bound to the second subform of \cdf{setf}.
However, this is not actually the case.  During the evaluation of the
\emph{body} forms, these variables are bound to names of temporary variables,
generated as if by \cdf{gensym} or \cdf{gentemp},
that will be bound by the
expansion of \cdf{setf} to the values of those subforms.  This binding
permits the
\emph{body} forms to be written without regard for order-of-evaluation
issues.  \cdf{defsetf} arranges for the temporary variables to be
optimized out of the final result in cases where that is possible.  In
other words, an attempt is made by \cdf{defsetf} to generate
the best code possible in a particular implementation.

Note that the code generated by the \emph{body} forms must include provision
for returning the correct value (the value of \emph{store-variable}).  This is
handled by the \emph{body} forms rather than by \cdf{defsetf} because
in many cases this value can be returned at no extra cost, by calling a
function that simultaneously stores into the generalized variable and
returns the correct value.

An example of the use of the complex form of \cdf{defsetf}:
\begin{lisp}
(defsetf subseq (sequence start \&optional end) (new-sequence) \\
~~{\Xbq}(progn (replace ,sequence ,new-sequence \\
~~~~~~~~~~~~~~~~~~~:start1 ,start :end1 ,end) \\
~~~~~~~~~~,new-sequence))
\end{lisp}

\begin{newer}
X3J13 voted in March 1988 \issue{FLET-IMPLICIT-BLOCK}
to specify that the body of the expander function defined
by the complex form of \cdf{defsetf} is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the \emph{access-fn}.
Therefore \cdf{return-from} may be used to exit from the function.
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}
to clarify that, while defining forms normally appear at top level,
it is meaningful to place them in non-top-level contexts; the complex form of
\cdf{defsetf} must define the expander function
within the enclosing lexical environment, not within the global
environment.
\end{newer}
\end{defmac}

The underlying theory by which \cdf{setf} and related macros arrange to
conform to the semantic rules given above is that from any
generalized-variable reference one may derive its ``\cdf{setf} method,''
which describes how to store into that reference and which subforms of
it are evaluated.

Given knowledge of the subforms of the reference,
it is possible to avoid evaluating them multiple times or in the wrong
order.  A \cdf{setf} method for a given access form can be expressed as
five values:
\begin{itemize}
\item
A list of \emph{temporary variables}

\item
A list of \emph{value forms} (subforms of the given form)
to whose values the temporary variables are to be bound

\item
A second list of temporary variables, called \emph{store variables}

\item
A \emph{storing form}

\item
An \emph{accessing form}
\end{itemize}

The temporary variables will be bound to the values of
the value forms as if by \cdf{let*}; that is, the
value forms will be evaluated in the order given
and may refer to the values of earlier value forms
by using the corresponding variables.

The store variables are to be bound to the values of the \emph{newvalue} form,
that is, the values to be
stored into the generalized variable.  In almost all cases only a
single value is to be stored, and there is only one store variable.

The storing form and the accessing form may contain references to
the temporary variables (and also, in the case of the storing form,
to the store variables).  The accessing form returns the value of the
generalized variable.  The storing form modifies the value of the
generalized variable and guarantees to return the values of the
store variables as
its values; these are the correct values for \cdf{setf} to
return.  (Again, in most cases there is a single store variable
and thus a single value to be returned.)
The value returned by the accessing form is, of course,
affected by execution of the storing form, but either of these
forms may be evaluated any number of times and therefore should be
free of side effects (other than the storing action of the storing form).

The temporary variables and the store variables are generated names,
as if by \cdf{gensym} or \cdf{gentemp},
so that there is never any problem of name clashes among them, or
between them and other variables in the program.  This is necessary to
make the special operators that do more than one \cdf{setf} in parallel work
properly; these are \cdf{psetf}, \cdf{shiftf}, and \cdf{rotatef}.  Computation
of the \cdf{setf} method must always create new variable names; it may not return
the same ones every time.

Some examples of \cdf{setf} methods for particular forms:
\begin{itemize}
\item
For a variable \cdf{x}:
\begin{lisp}
() \\*
() \\*
(g0001) \\
(setq x g0001) \\*
x
\end{lisp}

\item
For \cd{(car \emph{exp})}:
\begin{lisp}
(g0002) \\*
(\emph{exp}) \\*
(g0003)  \\
(progn (rplaca g0002 g0003) g0003) \\*
(car g0002)
\end{lisp}

\item
For \cd{(subseq \emph{seq} \emph{s} \emph{e})}:
\begin{lisp}
(g0004 g0005 g0006) \\*
(\emph{seq} \emph{s} \emph{e}) \\*
(g0007) \\
(progn (replace g0004 g0007 :start1 g0005 :end1 g0006) \\*
~~~~~~~g0007) \\*
(subseq g0004 g0005 g0006)
\end{lisp}
\end{itemize}

\begin{defmac}
define-setf-method access-fn lambda-list <{declaration}* | doc-string> {form}*

This defines how
to \cdf{setf} a generalized-variable reference that is of the form
\cd{(\emph{access-fn}...)}.  The value of a generalized-variable reference can
always be obtained simply by evaluating it, so \emph{access-fn} should be the
name of a function or a macro.

The \emph{lambda-list} describes the subforms of the generalized-variable
reference, as with \cdf{defmacro}.  The result of evaluating the
\emph{forms} in the body must be five values representing
the \cdf{setf} method, as described
above.  Note that \cdf{define-setf-method} differs from the complex form of
\cdf{defsetf} in that while the body is being executed the variables in
\emph{lambda-list} are bound to parts of the generalized-variable reference,
not to temporary variables that will be bound to the values of such parts.
In addition, \cdf{define-setf-method} does not have \cdf{defsetf}'s
restriction that \emph{access-fn} must be a function or a function-like
macro; an arbitrary \cdf{defmacro} destructuring pattern is permitted in
\emph{lambda-list}.

By definition there are no good small examples of \cdf{define-setf-method}
because the easy cases can all be handled by \cdf{defsetf}.
A typical use is to define the \cdf{setf} method for \cdf{ldb}:
\begin{obsolete}
\begin{lisp}
;;; SETF method for the form (LDB bytespec int). \\*
;;; Recall that the int form must itself be suitable for SETF. \\
(define-setf-method ldb (bytespec int) \\*
~~(multiple-value-bind (temps vals stores \\*
~~~~~~~~~~~~~~~~~~~~~~~~store-form access-form) \\*
~~~~~~(get-setf-method int)~~~~~~~~~;Get SETF method for int \\
~~~~(let ((btemp (gensym))~~~~~~~~~~;Temp var for byte specifier \\*
~~~~~~~~~~(store (gensym))~~~~~~~~~~;Temp var for byte to store \\*
~~~~~~~~~~(stemp (first stores)))~~~;Temp var for int to store \\
~~~~~~;; Return the SETF method for LDB as five values. \\*
~~~~~~(values (cons btemp temps)~~~~;Temporary variables \\*
~~~~~~~~~~~~~~(cons bytespec vals)~~;Value forms \\*
~~~~~~~~~~~~~~(list store)~~~~~~~~~~;Store variables \\
~~~~~~~~~~~~~~{\Xbq}(let ((,stemp (dpb ,store ,btemp ,access-form))) \\*
~~~~~~~~~~~~~~~~~,store-form \\*
~~~~~~~~~~~~~~~~~,store)~~~~~~~~~~~~~~~~~~~~~;Storing form \\*
~~~~~~~~~~~~~~{\Xbq}(ldb ,btemp ,access-form)~~~~~;Accessing form \\*
~~~~~~~~~~~~~~))))
\end{lisp}
\end{obsolete}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to specify that the \cd{\&environment} lambda-list keyword may appear in the
\emph{lambda-list} in the same manner as for \cdf{defmacro} in order
to obtain the lexical environment of the call to the \cdf{setf} macro.
The preceding example should be modified to take advantage of
this new feature.  The \cdf{setf} method must accept an \cd{\&environment}
parameter, which will receive the lexical environment of the call to \cdf{setf};
this environment must then be given to \cdf{get-setf-method} in order
that it may correctly use any locally bound \cdf{setf} method that
might be applicable to the \emph{place} form that appears as the second
argument to \cdf{ldb} in the call to \cdf{setf}.

\begin{lisp}
;;; SETF method for the form (LDB bytespec int). \\*
;;; Recall that the int form must itself be suitable for SETF. \\*
;;; Note the use of an \&environment parameter to receive the \\*
;;; lexical environment of the call for use with GET-SETF-METHOD. \\*
(define-setf-method ldb (bytespec int \&environment env) \\*
~~(multiple-value-bind (temps vals stores \\*
~~~~~~~~~~~~~~~~~~~~~~~~store-form access-form) \\*
~~~~~~(get-setf-method int env)~~~~~;Get SETF method for int \\
~~~~(let ((btemp (gensym))~~~~~~~~~~;Temp var for byte specifier \\*
~~~~~~~~~~(store (gensym))~~~~~~~~~~;Temp var for byte to store \\*
~~~~~~~~~~(stemp (first stores)))~~~;Temp var for int to store \\
~~~~~~;; Return the SETF method for LDB as five values. \\*
~~~~~~(values (cons btemp temps)~~~~;Temporary variables \\*
~~~~~~~~~~~~~~(cons bytespec vals)~~;Value forms \\*
~~~~~~~~~~~~~~(list store)~~~~~~~~~~;Store variables \\
~~~~~~~~~~~~~~{\Xbq}(let ((,stemp (dpb ,store ,btemp ,access-form))) \\*
~~~~~~~~~~~~~~~~~,store-form \\*
~~~~~~~~~~~~~~~~~,store)~~~~~~~~~~~~~~~~~~~~~;Storing form \\*
~~~~~~~~~~~~~~{\Xbq}(ldb ,btemp ,access-form)~~~~~;Accessing form \\*
~~~~~~~~~~~~~~))))
\end{lisp}
\end{newer}

\begin{newer}
X3J13 voted in March 1988 \issue{FLET-IMPLICIT-BLOCK}
to specify that the body of the expander function defined
by \cdf{define-setf-method} is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the \emph{access-fn}.
Therefore \cdf{return-from} may be used to exit from the function.
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}
to clarify that, while defining forms normally appear at top level,
it is meaningful to place them in non-top-level contexts;
\cdf{define-setf-method} must define the expander function
within the enclosing lexical environment, not within the global
environment.
\end{newer}
\end{defmac}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to add an optional environment argument to \cdf{get-setf-method}.
The revised definition and example are as follows.

\begin{defun}[Function]
get-setf-method form &optional env

\cdf{get-setf-method} returns
five values constituting the \cdf{setf} method for \emph{form}.
The \emph{form} must be a
generalized-variable reference.
The \emph{env} must be an environment of the sort obtained through
the \cd{\&environment} lambda-list keyword; if \emph{env} is \cdf{nil} or omitted,
the null lexical environment is assumed.
\cdf{get-setf-method} takes care of
error checking and macro expansion and guarantees to return exactly one
store variable.

As an example, an extremely simplified version of \cdf{setf},
allowing no more and no fewer than two
subforms, containing no optimization to remove unnecessary variables, and
not allowing storing of multiple values, could be defined by:
\begin{lisp}
(defmacro setf (reference value \&environment env) \\*
~~(multiple-value-bind (vars vals stores store-form access-form) \\*
~~~~~~(get-setf-method reference env)~~~~~;\textrm{Note use of environment}\\
~~~~(declare (ignore access-form)) \\
~~~~{\Xbq}(let* ,(mapcar \#'list \\*
~~~~~~~~~~~~~~~~~~~~(append vars stores) \\*
~~~~~~~~~~~~~~~~~~~~(append vals (list value))) \\*
~~~~~~~,store-form)))
\end{lisp}
\end{defun}
\end{newer}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to add an optional environment argument to \cdf{get-setf-method}.
The revised definition is as follows.

\begin{defun}[Function]
get-setf-method-multiple-value form &optional env

\cdf{get-setf-method-multiple-value}
returns five values constituting the \cdf{setf} method for \emph{form}.
The \emph{form} must be a
generalized-variable reference.
The \emph{env} must be an environment of the sort obtained through
the \cd{\&environment} lambda-list keyword; if \emph{env} is \cdf{nil} or omitted,
the null lexical environment is assumed.

This is the same as \cdf{get-setf-method}
except that it does not check the number of store variables; use this
in cases that allow storing multiple values into a generalized variable.
There are no such cases in standard Common Lisp, but this function is provided
to allow for possible extensions.
\end{defun}

\end{newer}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to clarify that a \cdf{setf} method for a functional name is applicable
only when the global binding of that name is lexically visible.
If such a name has a local binding introduced by \cdf{flet}, \cdf{labels},
or \cdf{macrolet}, then global definitions of \cdf{setf} methods for
that name do not apply and are not visible.  All of the standard Common Lisp
macros that modify a \cdf{setf} \emph{place} (for example,
\cdf{incf}, \cdf{decf}, \cdf{pop}, and \cdf{rotatef}) obey this convention.
\end{newer}

\section{Function Invocation}

The most primitive form for function invocation in Lisp of course
has no name; any list that has no other interpretation
as a macro call or special operator is taken to be a function call.
Other constructs are provided for less common but
nevertheless frequently useful situations.

\begin{defun}[Function]
apply function arg &rest more-args

This applies \emph{function} to a list of arguments.
\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE} to allow the \emph{function}
to be only of type \cdf{symbol} or \cdf{function}; a lambda-expression
is no longer acceptable as a functional argument.  One must use the
\cdf{function} special operator or the abbreviation \cd{\#'} before
a lambda-expression that appears as an  explicit argument form.
\end{newer}
The arguments for the \emph{function} consist of the last argument
to \cdf{apply} appended to the end of a list of all the other
arguments to \cdf{apply} but the \emph{function} itself;
it is as if all the arguments to \cdf{apply} except the \emph{function}
were given to \cdf{list*} to create the argument list.
For example:
\begin{lisp}
(setq f '+) (apply f '(1 2)) \EV\ 3 \\
(setq f \#'-) (apply f '(1 2)) \EV\ -1 \\
(apply \#'max 3 5 '(2 7 3)) \EV\ 7 \\
(apply 'cons '((+ 2 3) 4)) {\EV} \\
~~~~~~~~((+ 2 3) . 4)	\emph{not} (5 . 4) \\
(apply \#'+ '()) \EV\ 0
\end{lisp}
Note that if the function takes keyword arguments, the
keywords as well as the corresponding values must appear in the argument
list:
\begin{lisp}
(apply \#'(lambda (\cd{\&key} a b) (list a b)) '(:b 3)) \EV\ ({\nil} 3)
\end{lisp}
This can be very useful in conjunction with the \cd{\&allow-other-keys} feature:
\begin{lisp}
(defun foo (size \cd{\&rest} keys \cd{\&key} double \cd{\&allow-other-keys}) \\
~~(let ((v (apply \#'make-array size :allow-other-keys t keys))) \\
~~~~(if double (concatenate (type-of v) v v) v))) \\
 \\
(foo 4 :initial-contents '(a b c d) :double t) \\
~~~\EV\ \#(a b c d a b c d)
\end{lisp}
\end{defun}

\begin{defun}[Function]
funcall fn &rest arguments

\cd{(funcall \emph{fn} \emph{a1} \emph{a2} ... \emph{an})}
applies the function \emph{fn} to the arguments
\emph{a1}, \emph{a2}, ..., \emph{an}.
The \emph{fn} may not
be a special operator or a macro; this would not be meaningful.

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE} to allow the \emph{fn}
to be only of type \cdf{symbol} or \cdf{function}; a lambda-expression
is no longer acceptable as a functional argument.  One must use the
\cdf{function} special operator or the abbreviation \cd{\#'} before
a lambda-expression that appears as an  explicit argument form.
\end{newer}

For example:
\begin{lisp}
(cons 1 2) \EV\ (1 . 2) \\
(setq cons (symbol-function '+)) \\
(funcall cons 1 2) \EV\ 3
\end{lisp}
The difference between \cdf{funcall} and an ordinary function call is that
the function is obtained by ordinary Lisp evaluation rather than
by the special interpretation of the function position that normally
occurs.
\end{defun}

\begin{defun}[Constant]
call-arguments-limit

The value of \cdf{call-arguments-limit} is a positive integer that is
the upper exclusive bound on the number of arguments that may
be passed to a function.  This bound depends on the implementation
but will not be smaller than 50.
(Implementors are encouraged to make this limit as large as practicable
without sacrificing performance.)
The value of \cdf{call-arguments-limit} must be at
least as great as that of \cdf{lambda-parameters-limit}.
See also \cdf{multiple-values-limit}.
\end{defun}

\section{Simple Sequencing}

Each of the constructs in this section simply evaluates all the
argument forms in order.  They differ only in what results
are returned.

\begin{defspec}
progn {form}*

The \cdf{progn} construct takes a number of forms and evaluates
them sequentially, in order, from left to right.  The values of all
the forms but the last are discarded; whatever the last form returns
is returned by the \cdf{progn} form.
One says that all the forms but the last are evaluated for \emph{effect},
because their execution is useful only for the side effects caused,
but the last form is executed for \emph{value}.

\cdf{progn} is the primitive control structure construct for ``compound
statements,'' such as \textbf{begin}-\textbf{end} blocks in
Algol-like languages.
Many Lisp constructs are ``implicit \cdf{progn}'' forms:
as part of their syntax each allows many forms to be written
that are to be evaluated sequentially, discarding the results
of all forms but the last and returning the results of the last form.

If the last form of the \cdf{progn} returns multiple values, then those
multiple values are returned by the \cdf{progn} form.  If there are no forms
for the \cdf{progn}, then the result is {\false}.  These rules generally hold for
implicit \cdf{progn} forms as well.
\end{defspec}

\begin{defmac}
prog1 first {form}*

\cdf{prog1} is similar to \cdf{progn}, but it returns the value of
its \emph{first} form.  All the argument forms are executed sequentially;
the value of the first form is saved while all the others are executed
and is then returned.

\cdf{prog1} is most commonly used to evaluate an expression with side
effects and to return a value that must be computed \emph{before} the side
effects happen.
For example:
\begin{lisp}
(prog1 (car x) (rplaca x 'foo))
\end{lisp}
alters the \emph{car} of \cdf{x} to be \cdf{foo} and returns the old \emph{car}
of \cdf{x}.

\cdf{prog1} always returns a single value, even if the first form
tries to return multiple values.
As a consequence,
\cd{(prog1 \emph{x})} and \cd{(progn \emph{x})} may behave differently
if \emph{x} can produce multiple values.  See \cdf{multiple-value-prog1}.
A point of style:
although \cdf{prog1} can be used to force exactly a single value to
be returned, it is conventional to use the
function \cdf{values} for this purpose.
\end{defmac}

\begin{defmac}
prog2 first second {form}*

\cdf{prog2} is similar to \cdf{prog1}, but it returns the value of
its \emph{second} form.  All the argument forms are executed sequentially;
the value of the second form
is saved while all the other forms are executed and is then returned.
\cdf{prog2} is provided mostly for historical compatibility.
\begin{lisp}
(prog2 \emph{a} \emph{b} \emph{c} ... \emph{z}) \EQ\ (progn \emph{a} (prog1 \emph{b} \emph{c} ... \emph{z}))
\end{lisp}
Occasionally it is desirable to perform one side effect, then a value-producing
operation, then another side effect.  In such a peculiar case, \cdf{prog2}
is fairly perspicuous.
For example:
\begin{lisp}
(prog2 (open-a-file) (process-the-file) (close-the-file)) \\
\`;\textrm{value is that of \cdf{process-the-file}}
\end{lisp}

\cdf{prog2}, like \cdf{prog1},
always returns a single value, even if the second form
tries to return multiple values.  As a consequence of this,
\cd{(prog2 \emph{x} \emph{y})} and \cd{(progn \emph{x} \emph{y})} may behave differently
if \emph{y} can produce multiple values.
\end{defmac}


\section{Establishing New Variable Bindings}
\label{VAR-BINDING-SECTION}

During the invocation of
a function represented by a lambda-expression (or a closure of
a lambda-expression, as produced by \cdf{function}),
new bindings are established for the variables that are the
parameters of the lambda-expression.  These bindings initially
have values determined by the parameter-binding protocol discussed
in section~\ref{LAMBDA-EXPRESSIONS-SECTION}.

The following constructs may also be used to establish bindings of variables,
both ordinary and functional.

\begin{defspec}
let ({var | (var [value])}*) {declaration}* {form}*

A \cdf{let} form can be used to execute a series of forms
with specified variables bound to specified values.

More precisely, the form
\begin{lisp}
(let ((\emph{var1} \emph{value1}) \\
~~~~~~(\emph{var2} \emph{value2}) \\
~~~~~~... \\
~~~~~~(\emph{varm} \emph{valuem})) \\
~~\emph{declaration1} \\
~~\emph{declaration2} \\
~~... \\
~~\emph{declarationp} \\
~~\emph{body1} \\
~~\emph{body2} \\
~~... \\
~~\emph{bodyn})
\end{lisp}
first evaluates the expressions \emph{value1}, \emph{value2}, and so on,
in that order, saving the resulting values.
Then all of the variables \emph{varj} are bound to the corresponding
values in parallel; each binding will be a lexical binding unless
there is a \cdf{special} declaration to the contrary.
The expressions \emph{bodyk} are then evaluated
in order; the values of all but the last are discarded
(that is, the body of a \cdf{let} form is an implicit \cdf{progn}).
The \cdf{let} form returns what evaluating \emph{bodyn} produces (if the
body is empty, which is fairly useless, \cdf{let} returns {\false} as its value).
The bindings of the variables have lexical scope and indefinite extent.

Instead of a list \cd{(\emph{varj} \emph{valuej})}, one may write simply
\emph{varj}.  In this case \emph{varj} is initialized to {\false}.  As a matter
of style, it is recommended that \emph{varj} be written only when that
variable will be stored into (such as by \cdf{setq}) before its first
use.  If it is important that the initial value be {\false} rather than
some undefined value, then it is clearer to write out
\cd{(\emph{varj} {\false})} if the initial value is intended to mean ``false,'' or
\cd{(\emph{varj} '{\emptylist})} if the initial value is intended to be an empty
list.  Note that the code
\begin{lisp}
(let (x) \\
~~(declare (integer x)) \\
~~(setq x (gcd y z)) \\
~~...)
\end{lisp}
is incorrect; although \cdf{x} is indeed set before it is used,
and is set to a value of the declared type \cdf{integer}, nevertheless
\cdf{x} momentarily takes on the value {\nil} in violation of the type
declaration.

Declarations may appear at the beginning of the body of a \cdf{let}.
See \cdf{declare}.

See also \cdf{destructuring-bind}.
\end{defspec}

\begin{defspec}
let* ({var | (var [value])}*) {declaration}* {form}*

\cdf{let*} is similar to \cdf{let}, but the bindings of variables
are performed sequentially rather than in parallel.  This allows
the expression for the value of a variable to refer to variables
previously bound in the \cdf{let*} form.

More precisely, the form
\begin{lisp}
(let* ((\emph{var1} \emph{value1}) \\
~~~~~~~(\emph{var2} \emph{value2}) \\
~~~~~~~... \\
~~~~~~~(\emph{varm} \emph{valuem})) \\
~~\emph{declaration1} \\
~~\emph{declaration2} \\
~~... \\
~~\emph{declarationp} \\
~~\emph{body1} \\
~~\emph{body2} \\
~~... \\
~~\emph{bodyn})
\end{lisp}
first evaluates the expression \emph{value1}, then binds the variable
\emph{var1} to that value; then it evaluates \emph{value2} and binds \emph{var2};
and so on.
The expressions \emph{bodyj} are then evaluated
in order; the values of all but the last are discarded
(that is, the body of a \cdf{let*} form is an implicit \cdf{progn}).
The \cdf{let*} form returns the results of evaluating \emph{bodyn} (if the
body is empty, which is fairly useless, \cdf{let*} returns {\false} as its value).
The bindings of the variables have lexical scope and indefinite extent.

Instead of a list \cd{(\emph{varj} \emph{valuej})}, one may write simply \emph{varj}.
In this case \emph{varj} is initialized to {\false}.  As a matter of style,
it is recommended that \emph{varj} be written only when that variable
will be stored into (such as by \cdf{setq}) before its first use.
If it is important that the initial value be {\nil} rather than
some undefined value, then it is clearer to write out
\cd{(\emph{varj} {\false})} if the initial value is intended to mean ``false,'' or
\cd{(\emph{varj} '{\emptylist})} if the initial value is intended to be an empty
list.

Declarations may appear at the beginning of the body of a \cdf{let*}.
See \cdf{declare}.
\end{defspec}

\begin{defspec}
progv symbols values {form}*

\cdf{progv} is a special operator that allows binding one or more dynamic
variables whose names may be determined at run time.  The sequence of
forms (an implicit \cdf{progn})
is evaluated with the dynamic variables whose names are in the list
\emph{symbols} bound to corresponding values from the list \emph{values}.
(If too few values are supplied, the remaining symbols are bound and then
made to have no value; see \cdf{makunbound}.  If too many values are
supplied, the excess values are ignored.)  The results of the \cdf{progv}
form are those of the last
\emph{form}.  The bindings of the dynamic variables are undone on
exit from the \cdf{progv} form.  The lists of symbols and values are
computed quantities; this is what makes \cdf{progv} different from, for
example, \cdf{let}, where the variable names are stated explicitly in
the program text.

\cdf{progv} is particularly useful for writing interpreters for languages
embedded in Lisp; it provides a handle on the mechanism for binding
dynamic variables.
\end{defspec}

\begin{defspec}
flet ({(name lambda-list
        <{declaration}* | doc-string> {form}*)}*)
     {declaration}* {form}* \\
labels ({(name lambda-list
          <{declaration}* | doc-string> {form}*)}*)
       {declaration}* {form}* \\
macrolet ({(name varlist
            <{declaration}* | doc-string> {form}*)}*)
         {declaration}* {form}*

\cdf{flet} may be used to define locally named functions.  Within the
body of the \cdf{flet} form, function names matching those defined
by the \cdf{flet} refer to the locally defined functions rather than to
the global function definitions of the same name.

Any number of functions may be simultaneously defined.  Each definition
is similar in format to a \cdf{defun} form: first a name,
then a parameter list (which may contain \cd{\&optional}, \cd{\&rest}, or \cd{\&key}
parameters), then optional declarations and documentation string,
and finally a body.
\begin{lisp}
(flet ((safesqrt (x) (sqrt (abs x)))) \\*
~~;; The safesqrt function is used in two places. \\*
~~(safesqrt (apply \#'+ (map 'list \#'safesqrt longlist))))
\end{lisp}

The \cdf{labels} construct is identical in form to the \cdf{flet} construct.
These constructs differ
in that the scope of the defined function names for \cdf{flet}
encompasses only the body, whereas for \cdf{labels} it encompasses the
function definitions themselves.  That is, \cdf{labels} can be used to
define mutually recursive functions, but \cdf{flet} cannot.  This
distinction is useful.  Using \cdf{flet} one can locally redefine a global
function name, and the new definition can refer to the global definition;
the same construction using \cdf{labels} would not have that effect.
\begin{lisp}
(defun integer-power (n k)~~~~~~~;A highly "bummed" integer \\*
~~(declare (integer n))~~~~~~~~~~; exponentiation routine \\*
~~(declare (type (integer 0 *) k)) \\
~~(labels ((expt0 (x k a) \\*
~~~~~~~~~~~~~(declare (integer x a) (type (integer 0 *) k)) \\*
~~~~~~~~~~~~~(cond ((zerop k) a) \\*
~~~~~~~~~~~~~~~~~~~((evenp k) (expt1 (* x x) (floor k 2) a)) \\*
~~~~~~~~~~~~~~~~~~~(t (expt0 (* x x) (floor k 2) (* x a))))) \\
~~~~~~~~~~~(expt1 (x k a) \\*
~~~~~~~~~~~~~(declare (integer x a) (type (integer 1 *) k)) \\*
~~~~~~~~~~~~~(cond ((evenp k) (expt1 (* x x) (floor k 2) a)) \\*
~~~~~~~~~~~~~~~~~~~(t (expt0 (* x x) (floor k 2) (* x a)))))) \\*
~~~~(expt0 n k 1)))
\end{lisp}

\cdf{macrolet} is similar in form to \cdf{flet} but defines local macros,
using the same format used by \cdf{defmacro}.
The names established by \cdf{macrolet} as names for macros are
lexically scoped.

\begin{new}
I have observed that, while most Common Lisp users pronounce \cdf{macrolet}
to rhyme with ``silhouette,'' a small but vocal minority pronounce it
to rhyme with ``Chevrolet.''  A very few extremists furthermore
adjust their pronunciation
of \cdf{flet} similarly: they say ``flay.''
Hey, hey!  \emph{Tr\`es outr\'e.}
\end{new}

Macros often must be expanded at ``compile time'' (more generally,
at a time before the program itself is executed), and so
the run-time values of variables are not available to macros
defined by \cdf{macrolet}.

\begin{newer}
X3J13 voted in March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}
to retract the previous sentence and specify that the macro-expansion
functions created by \cdf{macrolet} are defined in the lexical environment in which
the \cdf{macrolet} form appears, not in the null lexical environment.
Declarations, \cdf{macrolet} definitions, and \cdf{symbol-macrolet} definitions
affect code within the expansion functions in a \cdf{macrolet}, but the
consequences are undefined if such code attempts to refer to
any local variable or function bindings that are visible in that
lexical environment.
\end{newer}

However,
lexically scoped entities \emph{are} visible
within the body of the \cdf{macrolet} form and \emph{are} visible
to the code that is the expansion of a macro call.  The following example
should make this clear:
\begin{lisp}
;;; Example of scoping in macrolet. \\*
\\*
(defun foo (x flag) \\*
~~(macrolet ((fudge (z) \\*
~~~~~~~~~~~~~~~~;;\textrm{The parameters \cdf{x} and \cdf{flag} are not accessible} \\*
~~~~~~~~~~~~~~~~;; \textrm{at this point; a reference to \cdf{flag} would be to} \\*
~~~~~~~~~~~~~~~~;; \textrm{the global variable of that name.} \\*
~~~~~~~~~~~~~~~~{\Xbq}(if flag \\
~~~~~~~~~~~~~~~~~~~~~(* ,z ,z) \\
~~~~~~~~~~~~~~~~~~~~~,z))) \\
~~~~;;\textrm{The parameters \cdf{x} and \cdf{flag} are accessible here.} \\*
~~~~(+ x \\*
~~~~~~~(fudge x) \\*
~~~~~~~(fudge (+ x 1)))))
\end{lisp}
The body of the \cdf{macrolet} becomes
\begin{lisp}
(+ x \\*
~~~(if flag \\*
~~~~~~~(* x x) \\*
~~~~~~~x)) \\*
~~~(if flag \\*
~~~~~~~(* (+ x 1) (+ x 1)) \\*
~~~~~~~(+ x 1)))
\end{lisp}
after macro expansion.  The occurrences of \cdf{x} and \cdf{flag} legitimately
refer to the parameters of the function \cdf{foo} because those parameters are
visible at the site of the macro call which produced the expansion.

The body of each function or expander function defined
by \cdf{flet}, \cdf{labels}, or \cdf{macrolet}
is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the function.
Therefore \cdf{return-from} may be used to exit from the function.

\cdf{flet} and \cdf{labels}
accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}) as a \emph{name}
for a function to be locally defined.  In this way one can create local definitions
for \cdf{setf} expansion functions.  (X3J13 explicitly declined to extend
\cdf{macrolet} in the same manner.)

\begin{new}
X3J13 voted in March 1988
\issue{FLET-DECLARATIONS}
to change \cdf{flet}, \cdf{labels}, and \cdf{macrolet}
to allow declarations to appear before the body.
The new descriptions are therefore as follows:
\end{new}
\end{defspec}

\begin{defspec}
symbol-macrolet ({(var expansion)}*)
                {declaration}* {form}*

X3J13 voted in June 1988
\issue{CLOS}
to adopt the Common Lisp Object System.  Part of this proposal
is a general mechanism, \cdf{symbol-macrolet},
for treating certain variable names as if they were
parameterless macro calls.  This facility may be useful independent of CLOS.
X3J13 voted in March 1989
\issue{SYMBOL-MACROLET-SEMANTICS}
to modify the definition of \cdf{symbol-macrolet} substantially
and also voted
\issue{SYMBOL-MACROLET-DECLARE} to allow declarations before the body
of \cdf{symbol-macrolet} but with peculiar treatment of \cdf{special}
and type declarations.

The \emph{forms} are executed as an implicit \cdf{progn} in a lexical
environment that causes every reference to any defined \emph{var}
to be replaced by the corresponding \emph{expansion}.  It is as if
the reference to the \emph{var} were a parameterless macro call;
the \emph{expansion} is evaluated or otherwise processed
in place of the reference
\vadjust{\penalty-10000}%manual
(in particular, the expansion form is itself subject
to further expansion---this is one of the changes
\issue{SYMBOL-MACROLET-SEMANTICS}
from the
original definition in the CLOS proposal).  Note, however, that the names of
such symbol macros occupy the name space of variables, not the
name space of functions; just as one may have a function
(or macro, or special operator) and a variable
with the same name without interference, so one may have an ordinary
macro (or function, or special operator)
and a symbol macro with the same name.
The use of \cdf{symbol-macrolet} can therefore be shadowed by \cdf{let}
or other constructs that bind variables; \cdf{symbol-macrolet} does
not substitute for all occurrences of a \emph{var} as a variable
but only for those occurrences that would be construed as
references in the scope of a lexical binding of \emph{var} as
a variable.  For example:
\begin{lisp}
(symbol-macrolet ((pollyanna 'goody)) \\*
~~(list pollyanna (let ((pollyanna 'two-shoes)) pollyanna))) \\*
~{\EV} (goody two-shoes)\textrm{, \emph{not}} (goody goody)
\end{lisp}
% novel "Pollyanna" by Eleanor Porter, 1913
One might think that \cd{'goody} simply replaces all occurrences of
\cdf{pollyanna}, and so the value of the \cdf{let} would be
\cdf{goody}; but this is not so.  A little reflection shows that under
this incorrect interpretation the body in expanded form would be
\begin{lisp}
(list 'goody (let (('goody 'two-shoes)) 'goody))
\end{lisp}
which is syntactically malformed.  The correct expanded form is
\begin{lisp}
(list 'goody (let ((pollyanna 'two-shoes)) pollyanna))
\end{lisp}
because the rebinding of \cdf{pollyanna} by the \cdf{let} form
shadows the symbol macro definition.

The \emph{expansion} for each \emph{var} is not evaluated at binding time
but only after it has replaced a reference to the \emph{var}.
The \cdf{setf} macro allows a symbol macro to be used as a \emph{place},
in which case its expansion is used; moreover, \cdf{setq} of a variable
that is really a symbol macro will be treated as if \cdf{setf} had
been used.
The values of the last form are returned, or \cdf{nil} if there is no value.

See \cdf{macroexpand} and \cdf{macroexpand-1}; they will expand symbol
macros as well as ordinary macros.

Certain \emph{declarations} before the body are handled in a peculiar manner;
see section~\ref{DECLARE-SYNTAX-SECTION}.

%??? See the related CLOS features \cdf{with-accessors} and \cdf{with-slots}.
\end{defspec}

\begin{defmac}
define-symbol-macro symbol {form}

The \emph{symbol} will act as a macro call. A single form constitutes the body of the
expansion. The \emph{symbol} cannot already be a special variable.
\end{defmac}

\section{Conditionals}

The traditional conditional construct in Lisp is \cdf{cond}.
However, \cdf{if} is much simpler and is directly comparable
to conditional constructs in other programming languages,
so it is considered to be primitive in Common Lisp and is described first.
Common Lisp also provides the dispatching constructs \cdf{case} and \cdf{typecase},
which are often more convenient than \cdf{cond}.

\begin{defspec}
if test then [else]

The \cdf{if} special operator corresponds to the \textbf{if}-\textbf{then}-\textbf{else} construct
found in most algebraic programming languages.
First the form \emph{test} is evaluated.  If the result is not {\false},
then the form \emph{then} is selected; otherwise the form \emph{else} is selected.
Whichever form is selected is then evaluated, and \cdf{if} returns
whatever is returned by evaluation of the selected form.
\begin{lisp}
(if \emph{test} \emph{then} \emph{else}) \EQ\ (cond (\emph{test} \emph{then}) ({\true} \emph{else}))
\end{lisp}
but \cdf{if} is considered more readable in some situations.

The \emph{else} form may be omitted, in which case if the value of \emph{test}
is {\false} then nothing is done and the value of the \cdf{if} form is {\false}.
If the value of
the \cdf{if} form is important in this situation, then the \cdf{and}
construct may be stylistically preferable,
depending on the context.
If the value is not important, but only the effect, then the \cdf{when}
construct may be stylistically preferable.
\end{defspec}

\begin{defmac}
when test {form}*

\cd{(when \emph{test} \emph{form1} \emph{form2} ... )}
first evaluates \emph{test}.  If the result is {\false},
then no \emph{form} is evaluated, and {\false} is returned.
Otherwise the \emph{form}s constitute an implicit \cdf{progn}
and are evaluated sequentially from left to right,
and the value of the last one is returned.
\begin{lisp}
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (and \emph{p} (progn \emph{a} \emph{b} \emph{c})) \\
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (cond (\emph{p} \emph{a} \emph{b} \emph{c})) \\
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (if \emph{p} (progn \emph{a} \emph{b} \emph{c}) {\false}) \\
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (unless (not \emph{p}) \emph{a} \emph{b} \emph{c})
\end{lisp}
As a matter of style,
\cdf{when} is normally used to conditionally produce some side effects,
and the value of the \cdf{when} form is normally not used.
If the value is relevant, then it may be
stylistically more appropriate to use \cdf{and} or \cdf{if}.
\end{defmac}

\begin{defmac}
unless test {form}*

\cd{(unless \emph{test} \emph{form1} \emph{form2} ... )}
first evaluates \emph{test}.  If the result is \emph{not} {\false},
then the \emph{form}s are not evaluated, and {\false} is returned.
Otherwise the \emph{form}s constitute an implicit \cdf{progn}
and are evaluated sequentially from left to right,
and the value of the last one is returned.
\begin{lisp}
(unless \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (cond ((not \emph{p}) \emph{a} \emph{b} \emph{c})) \\
(unless \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (if \emph{p} {\false} (progn \emph{a} \emph{b} \emph{c})) \\
(unless \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (when (not \emph{p}) \emph{a} \emph{b} \emph{c})
\end{lisp}
As a matter of style,
\cdf{unless} is normally used to conditionally produce some side effects,
and the value of the \cdf{unless} form is normally not used.
If the value is relevant, then it may be
stylistically more appropriate to use \cdf{if}.
\end{defmac}

\begin{defmac}
cond {(test {form}*)}*

A \cdf{cond} form has a number (possibly zero) of
\emph{clauses}, which are lists of forms.
Each clause consists of a \emph{test} followed
by zero or more \emph{consequents}.
For example:
\begin{lisp}
(cond (\emph{test-1} \emph{consequent-1-1} \emph{consequent-1-2} ...) \\
~~~~~~(\emph{test-2}) \\
~~~~~~(\emph{test-3} \emph{consequent-3-1} ...) \\
~~~~~~... )
\end{lisp}

The first clause whose \emph{test} evaluates to non-{\false}
is selected; all other clauses are ignored, and the consequents
of the selected clause are evaluated in order (as an implicit \cdf{progn}).

More specifically, \cdf{cond} processes its clauses in order from left to
right.  For each clause, the \emph{test} is evaluated.  If the result is
{\false}, \cdf{cond} advances to the next clause.  Otherwise, the \emph{cdr} of
the clause is treated as a list of forms, or consequents; these forms are
evaluated in order from left to right, as an implicit \cdf{progn}.
After evaluating the consequents,
\cdf{cond} returns without inspecting any remaining clauses.
The \cdf{cond} special operator returns the results
of evaluating the last of the selected consequents;
if there were no consequents in
the selected clause,
then the single (and necessarily non-null) value of the \emph{test} is returned.
If \cdf{cond} runs out of clauses (every test produced {\false},
and therefore no clause was selected), the value of the \cdf{cond} form is
{\false}.

If it is desired to select the last clause unconditionally if all others
fail, the standard convention is to use {\true} for the \emph{test}.
As a matter of style, it is desirable to write a last clause
\cd{({\true} {\false})} if the value of the \cdf{cond} form is to be used
for something.  Similarly, it is in questionable
taste to let the last clause of
a \cdf{cond} be a ``singleton clause''; an explicit {\true} should be provided.
(Note moreover that \cd{(cond ... (\emph{x}))} may behave differently from
\cd{(cond ... ({\true} \emph{x}))} if \emph{x} might produce multiple values;
the former always returns a single value, whereas the latter returns whatever
values \emph{x} returns.  However, as a matter of style it is preferable
to obtain this behavior by writing \cd{(cond ... (t (values \emph{x})))},
using the \cdf{values} function explicitly to indicate the discarding
of any excess values.)
For example:
\begin{lisp}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\=\kill
(setq z (cond (a 'foo) (b 'bar)))\>;\textrm{Possibly confusing} \\*
(setq z (cond (a 'foo) (b 'bar) ({\true} {\false})))\>;\textrm{Better} \\
(cond (a b) (c d) (e))\>;\textrm{Possibly confusing} \\*
(cond (a b) (c d) ({\true} e))\>;\textrm{Better} \\*
(cond (a b) (c d) ({\true} (values e)))\>;\textrm{Better (if one value} \\*
                                       \>;~\textrm{needed)} \\
(cond (a b) (c))\>;\textrm{Possibly confusing} \\
(cond (a b) (t c))\>;\textrm{Better} \\*
(if a b c)\>;\textrm{Also better}
\end{lisp}
A Lisp \cdf{cond} form may be compared to a continued \textbf{if}-\textbf{then}-\textbf{else}
as found in many algebraic programming languages:
\begin{lisp}
~~~~~~~~~~~~~~~~~~~~\=~~~~~~~~~~~~~~~~~~~~~\=\kill
(cond (\emph{p} ...)\>\>\textbf{if} \emph{p} \textbf{then} ... \\
~~~~~~(\emph{q} ...)\>\textrm{roughly}\>\textbf{else} \textbf{if} \emph{q} \textbf{then} ... \\
~~~~~~(\emph{r} ...)\>\textrm{corresponds}\>\textbf{else} \textbf{if} \emph{r} \textbf{then} ... \\
~~~~~~...\>\textrm{to}\>... \\
~~~~~~({\true} ...))\>\>\textbf{else} ...
\end{lisp}
\end{defmac}

\begin{defmac}
case keyform {({({key}*) | key} {form}*)}*

\cdf{case} is a conditional that chooses one of its clauses to execute
by comparing a value to various constants, which are
typically keyword symbols, integers, or characters
(but may be any objects).  Its form is as follows:
\begin{lisp}
(case \emph{keyform} \\
~~(\emph{keylist-1} \emph{consequent-1-1} \emph{consequent-1-2} ...) \\
~~(\emph{keylist-2} \emph{consequent-2-1} ...) \\
~~(\emph{keylist-3} \emph{consequent-3-1} ...) \\
~~...)
\end{lisp}
Structurally \cdf{case} is much like \cdf{cond},
and it behaves like \cdf{cond}
in selecting one clause and then executing all consequents of that clause.
However, \cdf{case} differs in the mechanism of clause selection.

The first thing \cdf{case} does is to evaluate the form \emph{keyform}
to produce an object called the \emph{key object}.
Then \cdf{case} considers
each of the clauses in turn.  If \emph{key} is in the \emph{keylist}
(that is, is \cdf{eql} to any item in the \emph{keylist}) of a clause,
the consequents of that
clause are evaluated as an implicit \cdf{progn};
\cdf{case} returns what was returned by the last
consequent (or {\false} if there are no consequents in that clause).
If no clause is satisfied, \cdf{case} returns {\false}.

The keys in the keylists are \emph{not} evaluated; literal key values
must appear in the keylists.
It is an error for the same key to appear in more than one clause;
a consequence is that the order of the clauses does not affect
the behavior of the \cdf{case} construct.

Instead of a \emph{keylist}, one may write one of the symbols
{\true} and \cdf{otherwise}.  A clause with such a symbol
always succeeds and must be the last clause (this is an exception
to the order-independence of clauses).
See also \cdf{ecase} and \cdf{ccase}, each of which provides
an implicit \cdf{otherwise} clause to signal an error if no clause
is satisfied.

If there is only one key for a clause, then that key may be written
in place of a list of that key, provided that no ambiguity results.
Such a ``singleton key'' may not be {\nil} (which is confusable
with {\emptylist}, a list of no keys), {\true}, \cdf{otherwise}, or a cons.
\end{defmac}

\begin{defmac}
typecase keyform {(type {form}*)}*

\cdf{typecase} is a conditional that chooses one of its clauses by
examining the type of an object.
Its form is as follows:
\begin{lisp}
(typecase \emph{keyform} \\*
~~(\emph{type-1} \emph{consequent-1-1} \emph{consequent-1-2} ...) \\*
~~(\emph{type-2} \emph{consequent-2-1} ...) \\*
~~(\emph{type-3} \emph{consequent-3-1} ...) \\
~~...)
\end{lisp}
Structurally \cdf{typecase} is much like \cdf{cond} or \cdf{case},
and it behaves like them
in selecting one clause and then executing all consequents of that clause.
It differs in the mechanism of clause selection.

The first thing \cdf{typecase} does is to evaluate the form \emph{keyform}
to produce an object called the key object.
Then \cdf{typecase} considers
each of the clauses in turn.  The \emph{type} that appears
in each clause is a type specifier; it is not evaluated
but is a literal type specifier.
The first clause for which the key
is of that clause's specified \emph{type}
is selected, the consequents of this
clause are evaluated as an implicit \cdf{progn},
and \cdf{typecase} returns what was returned by the last
consequent (or {\false} if there are no consequents in that clause).
If no clause is satisfied, \cdf{typecase} returns {\false}.

As for \cdf{case}, the symbol {\true} or \cdf{otherwise} may be written
for \emph{type} to indicate that the clause should always be selected.
See also \cdf{etypecase} and \cdf{ctypecase}, each of which provides
an implicit \cdf{otherwise} clause to signal an error if no clause
is satisfied.

It is permissible for more than one clause to specify a given type,
particularly if one is a subtype of another; the earliest applicable
clause is chosen.  Thus for \cdf{typecase}, unlike \cdf{case}, the order
of the clauses may affect the behavior of the construct.
For example:
\begin{lisp}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\=\kill
(typecase an-object \\
~~~(string ...)\>;\textrm{This clause handles strings} \\
~~~((array t) ...)\>;\textrm{This clause handles general arrays} \\
~~~((array bit) ...)\>;\textrm{This clause handles bit arrays} \\
~~~(array ...)\>;\textrm{This handles all other arrays} \\
~~~((or list number) ...)\>;\textrm{This handles lists and numbers} \\
~~~(t ...))\>;\textrm{This handles all other objects}
\end{lisp}
A Common Lisp compiler may choose to issue a warning if
a clause cannot be selected because it is completely shadowed by
earlier clauses.
\end{defmac}

\section{Blocks and Exits}
\label{BLOCK-RETURN-SECTION}

The \cdf{block} and \cdf{return-from} constructs provide a structured lexical
non-local exit facility.  At any point lexically within a \cdf{block}
construct, a \cdf{return-from} with the same name may be used to
perform an immediate transfer of control that
exits from the \cdf{block}.  In the most common cases this mechanism is
more efficient than the dynamic non-local exit facility
provided by \cdf{catch} and \cdf{throw}, described in
section~\ref{CATCH-THROW-SECTION}.

\begin{defspec}
block name {form}*

The \cdf{block} construct executes each \emph{form} from left to right,
returning whatever is returned by the last \emph{form}.
If, however, a \cdf{return} or \cdf{return-from} form that specifies the
same \emph{name} is executed
during the execution of some \emph{form}, then the results
specified by the \cdf{return} or \cdf{return-from} are immediately
returned as the value of the \cdf{block} construct, and execution
proceeds as if the \cdf{block} had terminated normally.
In this, \cdf{block} differs from \cdf{progn}; the \cdf{progn} construct
has nothing to do with \cdf{return}.

The \emph{name} is not evaluated; it must be a symbol.
The scope of the \emph{name} is lexical; only a \cdf{return} or \cdf{return-from}
textually contained in some \emph{form} can exit from the block.
The extent of the name is dynamic.
Therefore it is only possible to exit from a given run-time incarnation of a
block once, either normally or by explicit return.

The \cdf{defun} form implicitly puts a \cdf{block} around the
body of the function defined; the \cdf{block} has the same name as the function.
Therefore one may use \cdf{return-from} to return
prematurely from a function defined by \cdf{defun}.

The lexical scoping of the block name
is fully general and has consequences that may be surprising
to users and implementors of other Lisp systems.
For example, the \cdf{return-from} in the following example actually does
work in Common Lisp as one might expect:
\begin{lisp}
(block loser \\
~~~(catch 'stuff \\
~~~~~~(mapcar \#'(lambda (x) (if (numberp x) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(hairyfun x) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(return-from loser {\nil}))) \\
~~~~~~~~~~~~~~items)))
\end{lisp}
Depending on the situation, a \cdf{return} in Common Lisp
may not be simple.
A \cdf{return} can break up catchers if necessary to get
to the block in question.
It is possible for a ``closure'' created by \cdf{function} for
a lambda-expression to refer to a block name as long as the name
is lexically apparent.
\end{defspec}

\begin{defspec}
return-from name [result]

\cdf{return-from}
is used to return from a \cdf{block} or from such constructs
as \cdf{do} and \cdf{prog} that implicitly establish a \cdf{block}.
The \emph{name} is not evaluated and must be a symbol.
A \cdf{block} construct with the same name must lexically
enclose the occurrence of \cdf{return-from};
whatever the evaluation of \emph{result} produces
is immediately returned from the block.
(If the \emph{result} form is omitted, it defaults to {\nil}.
As a matter of style, this form ought to be used to indicate that
the particular value returned doesn't matter.)

The \cdf{return-from} form itself never returns and cannot have a value;
it causes results to be returned from a \cdf{block} construct.
If the evaluation of \emph{result} produces multiple values,
those multiple values are returned by the construct exited.
\end{defspec}

\begin{defmac}
return [result]

\cd{(return \emph{form})} is identical in meaning
to \cd{(return-from {\nil} \emph{form})}; it returns from a block named {\nil}.
Blocks established implicitly by iteration constructs such
as \cdf{do} are named {\nil}, so that \cdf{return} will exit properly from
such a construct.
\end{defmac}

\section{Iteration}
\indexterm{iteration}

Common Lisp provides a number of iteration constructs.  The \cdf{loop}
construct provides a trivial iteration facility; it is little more
than a \cdf{progn} with a branch from the bottom back to the top.
The \cdf{do}
and \cdf{do*} constructs provide a general iteration facility
for controlling the variation of several variables on each cycle.
For specialized iterations
over the elements of a list or \emph{n} consecutive integers, \cdf{dolist} and
\cdf{dotimes} are provided.  The \cdf{tagbody} construct is the most
general, permitting arbitrary \cdf{go} statements within it.  (The
traditional \cdf{prog} construct is a synthesis of \cdf{tagbody},
\cdf{block}, and \cdf{let}.)
Most of the iteration constructs permit statically defined non-local exits
(see \cdf{return-from} and \cdf{return}).

\subsection{Indefinite Iteration}

The \cdf{loop} construct is the simplest iteration facility.
It controls no variables, and simply executes its body repeatedly.

\begin{defmac}
loop {form}*

Each \emph{form} is evaluated in turn from left to right.
When the last \emph{form} has been evaluated, then the first \emph{form}
is evaluated again, and so on, in a never-ending cycle.
The \cdf{loop} construct never returns a value.  Its execution must be terminated
explicitly, using \cdf{return} or \cdf{throw}, for example.

\cdf{loop}, like most iteration constructs,
establishes an implicit block named {\nil}.
Thus \cdf{return} may be used to exit from a \cdf{loop} with specified results.

There is an extension of \cdf{loop}.  See chapter~\ref{LOOP}.
\end{defmac}


\subsection{General Iteration}

In contrast to \cdf{loop}, \cdf{do} and \cdf{do*} provide a powerful
and general mechanism for repetitively recalculating many variables.

\begin{defmac}
do ({(var [init [step]])}*)
   (end-test {result}*)
   {declaration}* {tag | statement}* \\
do* ({(var [init [step]])}*)
    (end-test {result}*)
    {declaration}* {tag | statement}*

The \cdf{do} special operator provides a generalized iteration facility,
with an arbitrary number of ``index variables.''
These variables are bound within the iteration and stepped in parallel
in specified ways.  They may be used both to generate successive
values of interest (such as successive integers) or to accumulate results.
When an end condition is met, the iteration terminates with a specified value.

In general, a \cdf{do} loop looks like this:
\begin{lisp}
(do ((\emph{var1} \emph{init1} \emph{step1}) \\
~~~~~(\emph{var2} \emph{init2} \emph{step2}) \\
~~~~~... \\
~~~~~(\emph{varn} \emph{initn} \emph{stepn})) \\
~~~~(\emph{end-test} . \emph{result}) \\
~~\Mstar{\emph{declaration}} \\
~~. \emph{tagbody})
\end{lisp}
A \cdf{do*} loop looks exactly the same except that the name \cdf{do} is
replaced by \cdf{do*}.

The first item in the form is a list of zero or more index-variable
specifiers.  Each index-variable specifier is a list of the name of a
variable \emph{var}, an initial value \emph{init},
and a stepping form \emph{step}.
If \emph{init} is omitted, it defaults to {\false}.
If \emph{step} is omitted, the \emph{var} is not changed by the \cdf{do} construct
between repetitions (though code within the \cdf{do} is free to alter
the value of the variable by using \cdf{setq}).

An index-variable specifier can also be just the name of a variable.
In this case, the variable has an initial value of {\false} and is
not changed between repetitions.
As a matter
of style, it is recommended that an unadorned variable name
be written only when that
variable will be stored into (such as by \cdf{setq}) before its first
use.  If it is important that the initial value be {\false} rather than
some undefined value, then it is clearer to write out
\cd{(\emph{varj} {\false})} if the initial value is intended to mean ``false,'' or
\cd{(\emph{varj} '{\emptylist})} if the initial value is intended to be an empty
list.

\begin{new}
X3J13 voted in January 1989
\issue{VARIABLE-LIST-ASYMMETRY}
to regularize the binding formats for \cdf{do}, \cdf{do*}, \cdf{let},
\cdf{let*}, \cdf{prog}, \cdf{prog*}, and \cdf{compiler-let}.
In the case of \cdf{do} and \cdf{do*} the first edition was inconsistent;
the formal syntax fails to reflect the fact that a simple variable
name may appear, as described in the preceding paragraph.  The
definitions should read

\begin{defmac}
do ({var | (var [init [step]])}*)
   (end-test {result}*)
   {declaration}* {tag | statement}* \\
do* ({var | (var [init [step]])}*)
    (end-test {result}*)
    {declaration}* {tag | statement}*

for consistency with the reading of the first edition and the X3J13 vote.
\end{defmac}
\end{new}

Before the first iteration, all the \emph{init} forms are evaluated, and
each \emph{var} is bound to the value of its respective \emph{init}.
This is a binding, not an assignment; when the loop terminates,
the old values of those variables will be restored.
For \cdf{do}, \emph{all} of the \emph{init} forms are evaluated \emph{before} any \emph{var}
is bound; hence all the
\emph{init} forms may refer to the old bindings of all the variables
(that is, to the values visible before beginning execution of
the \cdf{do} construct).
For \cdf{do*}, the first \emph{init} form is evaluated, then the first
\emph{var} is bound to that value, then the second \emph{init} form
is evaluated, then the second \emph{var} is bound, and so on;
in general, the \emph{initj} form can refer to the \emph{new} binding \emph{vark}
if $k<j$, and otherwise to the \emph{old} binding of
\emph{vark}.

The second element of the loop is a list of an end-testing
predicate form \emph{end-test} and zero or more \emph{result} forms.
This resembles a \cdf{cond} clause.
At the beginning of each iteration, after processing the variables,
the \emph{end-test} is evaluated.  If the result is
{\false}, execution proceeds with the body of the \cdf{do} (or \cdf{do*}) form.
If the
result is not {\false}, the \emph{result} forms are evaluated in order
as an implicit \cdf{progn},
\indexterm{implicit \cdf{progn}}
and then \cdf{do} returns.  \cdf{do} returns the results of evaluating
the last \emph{result} form.
If there are no \emph{result} forms, the value of \cdf{do} is {\false}.
Note that this is not quite analogous to the treatment of
clauses in a \cdf{cond} form, because a \cdf{cond} clause
with no \emph{result} forms returns the (non-{\nil}) result of the test.

At the beginning of each iteration other than the first, the
index variables are updated as follows.  All the \emph{step} forms
are evaluated, from left to right, and the resulting values are
assigned to the respective index variables.
Any variable that has no associated \emph{step} form is not assigned to.
For \cdf{do}, all the \emph{step} forms are evaluated before any variable
is updated; the assignment of values to variables is done in parallel,
as if by \cdf{psetq}.
Because \emph{all} of the \emph{step} forms are evaluated before \emph{any}
of the variables are altered, a \emph{step} form when evaluated always has
access to the \emph{old} values of \emph{all} the index variables,
even if other \emph{step} forms precede it.
For \cdf{do*}, the first \emph{step} form is evaluated, then the
value is assigned to the first \emph{var}, then the second \emph{step} form
is evaluated, then the value is assigned to the second \emph{var}, and so on;
the assignment of values to variables is done sequentially,
as if by \cdf{setq}.
For either \cdf{do} or \cdf{do*},
after the variables have been updated,
the \emph{end-test} is evaluated as described above, and the iteration
continues.

If the \emph{end-test} of a \cdf{do} form is \cd{{\false}},
the test will never succeed.
Therefore this provides an idiom for ``do forever'':
the \emph{body} of the \cdf{do} is executed repeatedly, stepping variables
as usual.  (The \cdf{loop} construct performs
a ``do forever'' that steps no variables.)
The infinite loop can be terminated by the use of \cdf{return},
\cdf{return-from}, \cdf{go} to an outer level, or \cdf{throw}.
For example:
\begin{lisp}
(do ((j 0 (+ j 1))) \\
~~~~({\false})~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Do forever} \\
~~(format t "{\Xtilde}\%Input {\Xtilde}D:" j) \\
~~(let ((item (read))) \\
~~~~(if (null item) (return)~~~~~;\textrm{Process items until {\false} seen} \\
~~~~~~~~(format t "{\Xtilde}\&Output {\Xtilde}D: {\Xtilde}S" j (process item)))))
\end{lisp}

The remainder of the \cdf{do} form constitutes an implicit \cdf{tagbody}.
Tags may appear within the body of a \cdf{do} loop
for use by \cdf{go} statements appearing in the body (but such \cdf{go}
statements may not appear in the variable specifiers, the \emph{end-test},
or the \emph{result} forms).
When the end of a \cdf{do} body is reached, the next iteration cycle
(beginning with the evaluation of \emph{step} forms) occurs.

An implicit \cdf{block} named {\nil} surrounds the entire \cdf{do} form.
A \cdf{return} statement may be used at any point to exit the loop
immediately.

\cdf{declare} forms may appear at the beginning of a \cdf{do} body.
They apply to code in the \cdf{do} body, to the bindings of the \cdf{do}
variables, to the \emph{init} forms, to the \emph{step} forms,
to the \emph{end-test}, and to the \emph{result} forms.

Here are some examples of the use of \cdf{do}:
\begin{lisp}
(do ((i 0 (+ i 1))~~~~~;\textrm{Sets every null element of \cdf{a-vector} to zero} \\*
~~~~~(n (length a-vector))) \\*
~~~~((= i n)) \\
~~(when (null (aref a-vector i)) \\*
~~~~(setf (aref a-vector i) 0)))
\end{lisp}
The construction
\begin{lisp}
(do ((x e (cdr x)) \\*
~~~~~(oldx x x)) \\*
~~~~((null x)) \\*
~~\emph{body})
\end{lisp}
exploits parallel assignment to index variables.  On the first
iteration, the value of \cdf{oldx} is whatever value \cdf{x} had before
the \cdf{do} was entered.  On succeeding iterations, \cdf{oldx} contains
the value that \cdf{x} had on the previous iteration. 

Very often an iterative algorithm can be most clearly expressed entirely
in the \emph{step} forms of a \cdf{do}, and the \emph{body} is empty.
For example,
\begin{lisp}
(do ((x foo (cdr x)) \\*
~~~~~(y bar (cdr y)) \\*
~~~~~(z '{\emptylist} (cons (f (car x) (car y)) z))) \\
~~~~((or (null x) (null y)) \\*
~~~~~(nreverse z)))
\end{lisp}
does the same thing as \cd{(mapcar \#'f foo bar)}.  Note that the \emph{step}
computation for \cdf{z} exploits the fact that variables are stepped in parallel.
Also, the body of the loop is empty.  Finally, the use of \cdf{nreverse}
to put an accumulated \cdf{do} loop result into the correct order
is a standard idiom.  Another example:
\begin{lisp}
(defun list-reverse (list) \\*
~~~~~~~(do ((x list (cdr x)) \\*
~~~~~~~~~~~~(y '{\emptylist} (cons (car x) y))) \\*
~~~~~~~~~~~((endp x) y)))
\end{lisp}
Note the use of \cdf{endp} rather than \cdf{null} or \cdf{atom}
to test for the end of a list; this may result in more robust code.

As an example of nested loops, suppose that \cdf{env} holds a list
of conses.  The \emph{car} of each cons is a list of symbols,
and the \emph{cdr} of each cons is a list of equal length containing
corresponding values.  Such a data structure is similar to an association
list
but is divided into ``frames''; the overall structure resembles a rib cage.
A lookup function on such a data structure might be
\begin{lisp}
(defun ribcage-lookup (sym ribcage) \\*
~~~~~~~(do ((r ribcage (cdr r))) \\*
~~~~~~~~~~~((null r) {\false}) \\
~~~~~~~~~(do ((s (caar r) (cdr s)) \\*
~~~~~~~~~~~~~~(v (cdar r) (cdr v))) \\*
~~~~~~~~~~~~~((null s)) \\
~~~~~~~~~~~(when (eq (car s) sym) \\*
~~~~~~~~~~~~~(return-from ribcage-lookup (car v))))))
\end{lisp}
(Notice the use of indentation in the above example
to set off the bodies of the \cdf{do} loops.)

A \cdf{do} loop may be explained in terms of the more primitive constructs
\cdf{block}, \cdf{return}, \cdf{let}, \cdf{loop}, \cdf{tagbody},
and \cdf{psetq} as follows:
\begin{lisp}
(block nil \\*
~~(let ((\emph{var1} \emph{init1}) \\*
~~~~~~~~(\emph{var2} \emph{init2}) \\
~~~~~~~~... \\*
~~~~~~~~(\emph{varn} \emph{initn})) \\*
~~~~\Mstar{\emph{declaration}} \\
~~~~(loop (when \emph{end-test} (return (progn . \emph{result}))) \\*
~~~~~~~~~~(tagbody . \emph{tagbody}) \\*
~~~~~~~~~~(psetq \emph{var1} \emph{step1} \\*
~~~~~~~~~~~~~~~~~\emph{var2} \emph{step2} \\*
~~~~~~~~~~~~~~~~~... \\*
~~~~~~~~~~~~~~~~~\emph{varn} \emph{stepn}))))
\end{lisp}
\cdf{do*} is exactly like \cdf{do} except that the bindings and steppings
of the variables are performed sequentially rather than in parallel.
It is as if, in the above explanation,
\cdf{let} were replaced by \cdf{let*} and \cdf{psetq} were replaced
by \cdf{setq}.
\end{defmac}

\subsection{Simple Iteration Constructs}

The constructs \cdf{dolist} and \cdf{dotimes} execute a body of code
once for each value taken by a single variable.  They are expressible
in terms of \cdf{do}, but capture very common patterns of use.

Both \cdf{dolist} and \cdf{dotimes} perform
a body of statements repeatedly.  On each iteration a specified
variable is bound to an element of interest that the body may
examine.  \cdf{dolist} examines successive elements of a list,
and \cdf{dotimes} examines integers from 0 to $n-1$
for some specified positive integer \emph{n}.

The value of any of these constructs may be specified by an optional result
form, which if omitted defaults to the value {\false}.

The \cdf{return} statement may be used to return
immediately from a \cdf{dolist} or \cdf{dotimes} form,
discarding any following iterations
that might have been performed; in effect, a \cdf{block} named {\nil}
surrounds the construct.
The body of the loop is implicitly a \cdf{tagbody} construct;
it may contain tags to serve as the targets of \cdf{go} statements.
Declarations may appear before the body of the loop.

\begin{defmac}
dolist (var listform [resultform])
       {declaration}* {tag | statement}*

\cdf{dolist} provides straightforward iteration over the elements of a list.
First \cdf{dolist}
evaluates the form \emph{listform},
which should produce a list.  It then executes the body
once for each element in the list, in order, with
the variable \emph{var} bound to the element.
Then \emph{resultform} (a single form, \emph{not} an implicit \cdf{progn})
is evaluated, and the result is the value of the \cdf{dolist}
form.  (When the \emph{resultform} is evaluated, the control variable \emph{var}
is still bound and has the value {\nil}.)
If \emph{resultform} is omitted, the result is {\false}.

\begin{lisp}
(dolist (x '(a b c d)) (prin1 x) (princ " ")) \EV\ {\false} \\
~~~\textrm{after printing ``\cd{a b c d }'' (note the trailing space)}
\end{lisp}

An explicit \cdf{return} statement may be used to terminate the loop
and return a specified value.

\begin{new}
X3J13 voted in January 1989
\issue{MAPPING-DESTRUCTIVE-INTERACTION}
to restrict user side effects; see section~\ref{STRUCTURE-TRAVERSAL-SECTION}.
\end{new}
\end{defmac}

\begin{defmac}
dotimes (var countform [resultform])
        {declaration}* {tag | statement}*

\cdf{dotimes} provides straightforward iteration over a sequence of integers.
The expression
\cd{(dotimes (\emph{var} \emph{countform} \emph{resultform}) . \emph{progbody})}
evaluates the form \emph{countform}, which should produce an integer.  It then
performs \emph{progbody} once for each integer from zero (inclusive) to
\emph{count} (exclusive), in order, with the variable \emph{var} bound to the
integer; if the value of \emph{countform} is zero or negative,
then the \emph{progbody} is
performed zero times.  Finally, \emph{resultform} (a single form, \emph{not} an
implicit \cdf{progn}) is evaluated, and the result is the value of the
\cdf{dotimes} form.  (When the \emph{resultform} is evaluated, the control
variable \emph{var} is still bound and has as its value the number of times
the body was executed.)
If \emph{resultform} is omitted, the result is {\false}.

An explicit \cdf{return} statement may be used to terminate the loop
and return a specified value.

Here is an example of the use of \cdf{dotimes} in processing strings:
\begin{lisp}
;;; True if the specified subsequence of the string is a \\*
;;; palindrome (reads the same forwards and backwards). \\*
\\*
(defun palindromep (string \cd{\&optional} \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~(start 0) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~(end (length string))) \\
~~(dotimes (k (floor (- end start) 2) {\true}) \\*
~~~~(unless (char-equal (char string (+ start k)) \\*
~~~~~~~~~~~~~~~~~~~~~~~~(char string (- end k 1))) \\*
~~~~~~(return {\false})))) \\
\\
(palindromep "Able was I ere I saw Elba") \EV\ {\true} \\
 \\
(palindromep "A man, a plan, a canal--Panama!") \EV\ {\false} \\
 \\
(remove-if-not \#'alpha-char-p~~~~~;\textrm{Remove punctuation} \\*
~~~~~~~~~~~~~~~"A man, a plan, a canal--Panama!") \\*
~~~\EV\ "AmanaplanacanalPanama" \\
 \\
(palindromep \\*
~(remove-if-not \#'alpha-char-p \\*
~~~~~~~~~~~~~~~~"A man, a plan, a canal--Panama!")) \EV\ {\true} \\
 \\
(palindromep \\*
~(remove-if-not \\*
~~~\#'alpha-char-p \\*
~~~"Unremarkable was I ere I saw Elba Kramer, nu?")) \EV\ {\true} \\
 \\
(palindromep \\*
~(remove-if-not \\*
~~~\#'alpha-char-p \\*
~~~"A man, a plan, a cat, a ham, a yak, \\*
~~~~~~~~~~~~~~~~~~~a yam, a hat, a canal--Panama!")) \EV\ {\true}
\\
(palindromep \\*
~(remove-if-not \\*
~~~\#'alpha-char-p \\*
~~~"Ja-da, ja-da, ja-da ja-da jing jing jing")) \EV\ {\false}
\end{lisp}

Altering the value of \emph{var} in the body of the loop (by using \cdf{setq},
for example) will have unpredictable, possibly implementation-dependent
results.  A Common Lisp compiler may choose to issue a warning if such a variable
appears in a \cdf{setq}.
\end{defmac}

See also \cdf{do-symbols}, \cdf{do-external-symbols},
and \cdf{do-all-symbols}.

\subsection{Mapping}
\indexterm{mapping}

Mapping is a type of iteration in which a function is 
successively applied to pieces of one or more sequences.
The result of the iteration is a sequence containing the respective
results of the function applications.
There are several options for the way in which the pieces of the list are
chosen and for what is done with the results returned by the applications of
the function.

The function \cdf{map} may be used to map over any kind of sequence.
The following functions operate only on lists.

\begin{defun}[Function]
mapcar function list &rest more-lists \\
maplist function list &rest more-lists \\
mapc function list &rest more-lists \\
mapl function list &rest more-lists \\
mapcan function list &rest more-lists \\
mapcon function list &rest more-lists

For each of these mapping functions,
the first argument is a function and the rest must be lists.
The function must take as many arguments as there are lists.

\cdf{mapcar} operates on successive elements of the lists.
First the function is applied to the \emph{car} of each list,
then to the \emph{cadr} of each list, and so on.
(Ideally all the lists are the same length; if not,
the iteration terminates when the shortest list runs out,
and excess elements in other lists are ignored.)
The value returned by \cdf{mapcar} is a list of the
results of the successive calls to the function.
For example:
\begin{lisp}
(mapcar \#'abs '(3 -4 2 -5 -6)) \EV\ (3 4 2 5 6) \\
(mapcar \#'cons '(a b c) '(1 2 3)) \EV\ ((a . 1) (b . 2) (c . 3))
\end{lisp}

\cdf{maplist} is like \cdf{mapcar} except that the function is applied to
the lists and successive \emph{cdr}'s of those lists rather than to successive
elements of the lists.
For example:
\begin{lisp}
(maplist \#'(lambda (x) (cons 'foo x)) \\*
~~~~~~~~~'(a b c d)) \\*
~~~\EV\ ((foo a b c d) (foo b c d) (foo c d) (foo d))
\end{lisp}

\begin{lisp}
(maplist \#'(lambda (x) (if (member (car x) (cdr x)) 0 1))) \\*
~~~~~~~~~'(a b a c d b c)) \\*
~~~\EV\ (0 0 1 0 1 1 1) \\*
~~~;\textrm{An entry is \cd{1} if the corresponding element of the input} \\*
~~~;~\textrm{list was the last instance of that element in the input list.}
\end{lisp}

\cdf{mapl} and \cdf{mapc} are like \cdf{maplist} and \cdf{mapcar},
respectively, except that they do not accumulate the results
of calling the function.

These functions are used when the function is being called merely for its
side effects rather than for its returned values.
The value returned by \cdf{mapl} or \cdf{mapc} is the second argument,
that is, the first sequence argument.

\cdf{mapcan} and \cdf{mapcon} are like \cdf{mapcar} and \cdf{maplist}, respectively,
except that they combine the results of
the function using \cdf{nconc} instead of \cdf{list}.  That is,
\begin{lisp}
(mapcon \emph{f} \emph{x1} ... \emph{xn}) \\
~~~\EQ\ (apply \#'nconc (maplist \emph{f} \emph{x1} ... \emph{xn}))
\end{lisp}
and similarly for the relationship between \cdf{mapcan} and \cdf{mapcar}.
Conceptually, these functions allow the mapped function to return
a variable number of items to be put into the output list.
This is particularly useful for effectively returning zero or one item:
\begin{lisp}
(mapcan \#'(lambda (x) (and (numberp x) (list x))) \\
~~~~~~~~'(a 1 b c 3 4 d 5)) \\
~~~\EV\ (1 3 4 5)
\end{lisp}
In this case the function serves as a filter; this is a standard Lisp
idiom using \cdf{mapcan}.
(The function \cdf{remove-if-not} might have been useful in this
particular context, however.)
Remember that \cdf{nconc} is a destructive operation, and therefore
so are \cdf{mapcan} and \cdf{mapcon}; the lists returned by the \emph{function}
are altered in order to concatenate them.

Sometimes a \cdf{do} or a straightforward recursion is preferable to a
mapping operation;  however, the mapping functions should be used wherever they
naturally apply because this increases the clarity of the code.

The functional argument to a mapping function must be acceptable
to \cdf{apply}; it cannot be a macro or the name of a special operator.
Of course, there is nothing wrong with using a function that has \cd{\&optional}
and \cd{\&rest} parameters as the functional argument.

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE} to allow the \emph{function}
to be only of type \cdf{symbol} or \cdf{function}; a lambda-expression
is no longer acceptable as a functional argument.  One must use the
\cdf{function} special operator or the abbreviation \cd{\#'} before
a lambda-expression that appears as an  explicit argument form.
\end{newer}

\begin{new}
X3J13 voted in January 1989
\issue{MAPPING-DESTRUCTIVE-INTERACTION}
to restrict user side effects; see section~\ref{STRUCTURE-TRAVERSAL-SECTION}.
\end{new}
\end{defun}

\subsection{The ``Program Feature''}

Lisp implementations since Lisp 1.5 have had what was originally
called ``the program feature,'' as if it were impossible to write
programs without it!  The \cdf{prog} construct allows one to
write in an Algol-like or Fortran-like statement-oriented
style, using \cdf{go} statements that can refer to tags in the
body of the \cdf{prog}.  Modern Lisp programming style tends to use
\cdf{prog} rather infrequently.  The various iteration constructs,
such as \cdf{do}, have bodies with the characteristics of a \cdf{prog}.
(However, the ability to use \cdf{go} statements within iteration
constructs is very seldom called upon in practice.)

Three distinct operations are performed by \cdf{prog}: it binds local variables,
it permits use of the \cdf{return} statement, and it permits use of the \cdf{go}
statement.
In Common Lisp, these three operations have been separated into three
distinct constructs: \cdf{let}, \cdf{block}, and \cdf{tagbody}.
These three constructs may be used independently as building blocks
for other types of constructs.

\begin{defspec}
tagbody {tag | statement}*

The part of a \cdf{tagbody} after the variable list is called the \emph{body}.
An item in the body may be a symbol or an integer, in which case it is called a
\emph{tag}, or an item in the body may be a list, in which case it is called a 
\emph{statement}.

Each element of the body is processed from left to right.
A \emph{tag} is ignored; a \emph{statement}
is evaluated, and its results are discarded.  If the end of the body
is reached, the \cdf{tagbody} returns {\false}.

If \cd{(go \emph{tag})} is evaluated, control jumps to the part of the body
labelled with the \emph{tag}.

The scope of the tags established by a \cdf{tagbody} is lexical,
and the extent is dynamic.  Once a \cdf{tagbody} construct has
been exited, it is no longer legal to \cdf{go} to a \emph{tag} in its body.
It is permissible for a \cdf{go} to jump to a \cdf{tagbody} that is not
the innermost \cdf{tagbody} construct containing that \cdf{go};
the tags established by a \cdf{tagbody} will only shadow other tags
of like name.

The lexical scoping of the \cdf{go} targets named by tags is
fully general and has consequences that may be surprising
to users and implementors of other Lisp systems.
For example, the \cdf{go} in the following example actually does
work in Common Lisp as one might expect:
\begin{lisp}
(tagbody \\*
~~~(catch 'stuff \\*
~~~~~~(mapcar \#'(lambda (x) (if (numberp x) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(hairyfun x) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(go lose))) \\*
~~~~~~~~~~~~~~items)) \\
~~~(return) \\*
~lose \\*
~~~(error "I lost big!"))
\end{lisp}
Depending on the situation, a \cdf{go} in Common Lisp does not necessarily
correspond to a simple machine ``jump'' instruction.
A \cdf{go} can break up catchers if necessary to get
to the target.  It is possible for a ``closure'' created by \cdf{function} for
a lambda-expression to refer to a \cdf{go} target as long as the tag
is lexically apparent.  See chapter~\ref{SCOPE} for an elaborate
example of this.

\begin{new}
There are some holes in this specification (and that of \cdf{go}) that
leave some room for interpretation.  For example, there is no explicit
prohibition against the same tag appearing more than once in the same
\cdf{tagbody} body.  Every implementation I know of will complain
in the compiler, if not in the interpreter, if there is a \cdf{go} to
such a duplicated tag; but some implementors take the position
that duplicate tags are permitted provided there is no \cdf{go} to
such a tag.  (``If a tree falls in the forest, and there is no one
there to hear it, then no one needs to yell `Timber!'\thinspace'')
Also, some implementations allow objects other than symbols, integers,
and lists in the body and typically ignore them.
Consequently,
some programmers use redundant tags such as \cdf{---} for formatting purposes,
and strings as comments:
\begin{lisp}
(defun dining-philosopher (j) \\*
~~(tagbody --- \\*
~~~think~~~(unless (hungry) (go think)) \\*
~~~~~~~~~~~--- \\
~~~~~~~~~~~"Can't eat without chopsticks." \\*
~~~~~~~~~~~(snatch (chopstick j)) \\*
~~~~~~~~~~~(snatch (chopstick (mod (+ j 1) 5))) \\*
~~~~~~~~~~~--- \\
~~~eat~~~~~(when (hungry) \\*
~~~~~~~~~~~~~(mapc \#'gobble-down \\*
~~~~~~~~~~~~~~~~~~~'(twice-cooked-pork kung-pao-chi-ding \\*
~~~~~~~~~~~~~~~~~~~~~wu-dip-har orange-flavor-beef \\*
~~~~~~~~~~~~~~~~~~~~~two-side-yellow-noodles twinkies)) \\*
~~~~~~~~~~~~~(go eat)) \\*
~~~~~~~~~~~--- \\
~~~~~~~~~~~"Can't think with my neighbors' stomachs rumbling." \\*
~~~~~~~~~~~(relinquish (chopstick j)) \\*
~~~~~~~~~~~(relinquish (chopstick (mod (+ j 1) 5))) \\*
~~~~~~~~~~~--- \\*
~~~~~~~~~~~(if (happy) (go think) \\*
~~~~~~~~~~~~~~~(become insurance-salesman))))
\end{lisp}
In certain implementations of Common Lisp they get away with it.
Others abhor what they view as an abuse of unintended ambiguity
in the language specification.  For maximum portability, I advise
users to steer clear of these issues.  Similarly, it is best
to avoid using \cdf{nil} as a tag, even though it is a symbol, because
a few implementations treat \cdf{nil} as a list to be executed.
To be extra careful, avoid calling from within a \cdf{tagbody}
a macro whose expansion might not be a non-\cdf{nil} list; wrap such a 
call in \cd{(progn~...)}, or rewrite the macro to return \cd{(progn~...)}
if possible.
\end{new}
\end{defspec}

\begin{defmac}
prog ({var | (var [init])}*) {declaration}* {tag | statement}* \\
prog* ({var | (var [init])}*) {declaration}* {tag | statement}*

The \cdf{prog} construct is a synthesis of \cdf{let}, \cdf{block},
and \cdf{tagbody}, allowing bound variables and the use of \cdf{return} and \cdf{go}
within a single construct.  A typical \cdf{prog} construct looks like this:
\begin{lisp}
(prog (\emph{var1} \emph{var2} (\emph{var3} \emph{init3}) \emph{var4} (\emph{var5} \emph{init5})) \\*
~~~~~~\Mstar{\emph{declaration}} \\*
~~~~~~\emph{statement1} \\
~\emph{tag1} \\*
~~~~~~\emph{statement2} \\*
~~~~~~\emph{statement3} \\*
~~~~~~\emph{statement4} \\
~\emph{tag2} \\*
~~~~~~\emph{statement5} \\*
~~~~~~... \\*
~~~~~~)
\end{lisp}
The list after the keyword \cdf{prog} is a set of specifications for binding
\emph{var1}, \emph{var2}, etc.,
which are temporary variables bound locally to the \cdf{prog}.
This list is processed exactly as the list in a \cdf{let} statement:
first all the \emph{init} forms are evaluated from left to right
(where {\false} is used for
any omitted \emph{init} form), and then the variables are all bound in
parallel to the respective results.
Any \emph{declaration} appearing in the \cdf{prog} is used as if appearing
at the top of the \cdf{let} body.

The body of the \cdf{prog} is executed as if it were a \cdf{tagbody}
construct; the \cdf{go} statement may be used to transfer control
to a \emph{tag}.

A \cdf{prog} implicitly establishes a \cdf{block} named {\nil} around
the entire \cdf{prog} construct, so that \cdf{return} may be used
at any time to exit from the \cdf{prog} construct.

Here is a fine example of what can be done with \cdf{prog}:
\begin{lisp}
(defun king-of-confusion (w) \\
~~"Take a cons of two lists and make a list of conses. \\
~~~Think of this function as being like a zipper." \\
~~(prog (x y z)~~~~~;\textrm{Initialize \cdf{x}, \cdf{y}, \cdf{z} to {\false}} \\
~~~~~~~~(setq y (car w) z (cdr w)) \\
~~~loop \\
~~~~~~~~(cond ((null y) (return x)) \\
~~~~~~~~~~~~~~((null z) (go err))) \\
~~~rejoin \\
~~~~~~~~(setq x (cons (cons (car y) (car z)) x)) \\
~~~~~~~~(setq y (cdr y) z (cdr z)) \\
~~~~~~~~(go loop) \\
~~~err \\
~~~~~~~~(cerror "Will self-pair extraneous items" \\
~~~~~~~~~~~~~~~~"Mismatch - gleep!  ~S" y) \\
~~~~~~~~(setq z y) \\
~~~~~~~~(go rejoin)))
\end{lisp}
which is accomplished somewhat more perspicuously by
\begin{lisp}
(defun prince-of-clarity (w) \\
~~"Take a cons of two lists and make a list of conses. \\
~~~Think of this function as being like a zipper." \\
~~(do ((y (car w) (cdr y)) \\
~~~~~~~(z (cdr w) (cdr z)) \\
~~~~~~~(x '{\emptylist} (cons (cons (car y) (car z)) x))) \\
~~~~~~((null y) x) \\
~~~~(when (null z) \\
~~~~~~(cerror "Will self-pair extraneous items" \\
~~~~~~~~~~~~~~"Mismatch - gleep!  ~S" y) \\
~~~~~~(setq z y))))
\end{lisp}

The \cdf{prog} construct may be explained in terms of the simpler
constructs \cdf{block}, \cdf{let}, and \cdf{tagbody} as
follows:
\begin{lisp}
(prog \emph{variable-list} \Mstar{\emph{declaration}} . \emph{body}) \\
~~~\EQ\ (block nil (let \emph{variable-list} \Mstar{\emph{declaration}} (tagbody . \emph{body})))
\end{lisp}

The \cdf{prog*} special operator is almost the same as \cdf{prog}.  The only
difference is that the binding and initialization of the temporary
variables is done \emph{sequentially}, so that the \emph{init} form for each
one can use the values of previous ones.
Therefore \cdf{prog*} is to \cdf{prog} as \cdf{let*} is to \cdf{let}.
For example,
\begin{lisp}
(prog* ((y z) (x (car y))) \\
~~~~~~~(return x))
\end{lisp}
returns the \emph{car} of the value of \cdf{z}.

\begin{new}
I haven't seen \cdf{prog} used very much in the last several years.
Apparently splitting it into functional constituents
(\cdf{let}, \cdf{block}, \cdf{tagbody}) has been a success.  Common Lisp
programmers now tend to use whichever specific construct is appropriate.
\end{new}
\end{defmac}

\begin{defspec}
go tag

The \cd{(go \emph{tag})} special operator is used to do a ``go to'' within
a \cdf{tagbody} construct.  The \emph{tag} must be a symbol or an integer;
the \emph{tag} is not evaluated.
\cdf{go} transfers control to the point in the body labelled by a
tag \cdf{eql} to the one given.  If there is no such tag in the body, the
bodies of lexically containing \cdf{tagbody} constructs
(if any) are examined as well.
It is an error if there is no matching tag lexically visible
to the point of the \cdf{go}.

The \cdf{go} form does not ever return a value.

As a matter of style, it is recommended that the user think twice before
using a \cdf{go}.  Most purposes of \cdf{go} can be accomplished with one of
the iteration primitives, nested conditional forms, or
\cdf{return-from}.  If the use of \cdf{go} seems to be unavoidable,
perhaps the control structure implemented by \cdf{go} should be packaged
as a macro definition.
\end{defspec}

\section{Structure Traversal and Side Effects}
\label{STRUCTURE-TRAVERSAL-SECTION}

X3J13 voted in January 1989 \issue{MAPPING-DESTRUCTIVE-INTERACTION}
to restrict side effects during the course
of a built-in operation that can execute user-supplied code while
traversing a data structure.

Consider the following example:
\begin{lisp}
(let ((x '(apples peaches pumpkin pie))) \\*
~~(dolist (z x) \\*
~~~~(when (eq z 'peaches) \\*
~~~~~~(setf (cddr x) '(mango kumquat))) \\*
~~~~(format t "~S " (car z))))
\end{lisp}
Depending on the details of the implementation of \cdf{dolist},
this bit of code could easily print
\begin{lisp}
apples peaches mango kumquat
\end{lisp}
(which is perhaps what was intended), but it might as easily print
\begin{lisp}
apples peaches pumpkin pie
\end{lisp}
Here is a plausible implementation of \cdf{dolist} that
produces the first result:
\begin{lisp}
(defmacro dolist ((var listform \&optional (resultform ''nil)) \\*
~~~~~~~~~~~~~~~~~~\&body body) \\*
~~(let ((tailvar (gensym "DOLIST"))) \\*
~~~~{\Xbq}(do ((,tailvar ,listform (cdr ,tailvar))) \\*
~~~~~~~~~((null ,tailvar) ,resultform) \\*
~~~~~~~(let ((,var (car ,tailvar))) ,@body))
\end{lisp}
But here is a plausible implementation of \cdf{dolist} that
produces the second result:
\begin{lisp}
(defmacro dolist ((var listform \&optional (resultform ''nil)) \\*
~~~~~~~~~~~~~~~~~~\&body body) \\*
~~(let ((tailvar (gensym "DOLIST"))) \\*
~~~~{\Xbq}(do ((,tailvar ,listform)) \\*
~~~~~~~~~((null ,tailvar) ,resultform) \\*
~~~~~~~(let ((,var (pop ,tailvar))) ,@body))
\end{lisp}

The X3J13 recognizes and legitimizes varying implementation practices:
in general it is an error for code executed during a ``structure-traversing''
operation to destructively modify the structure in a way that might
affect the ongoing traversal operation.  The committee identified in particular
the following special cases.

For list traversal operations, the \emph{cdr} chain
may not be destructively modified.

For array traversal operations, the array may not be adjusted
(see \cdf{adjust-array}) and its fill pointer, if any, may not be modified.

For hash table operations (such as \cdf{with-hash-table-iterator}
and \cdf{maphash}), new entries may not be added or deleted,
\emph{except} that the very entry being processed by user code
may be changed or deleted.

For package symbol operations (for example, \cdf{with-package-iterator}
and \cdf{do-symbols}), new symbols may not be interned in,
nor symbols uninterned from, the packages being traversed or
any packages they use, \emph{except} that the very symbol
being processed by user code may be uninterned.

X3J13 noted that this vote is intended to clarify restrictions
on the use of structure traversal operations that are not themselves
inherently destructive; for example, it applies to \cdf{map} and \cdf{dolist}.
Destructive operators such as \cdf{delete} require even more complicated
restrictions and are addressed by a separate proposal.

The X3J13 vote did not specify a complete list of the operations to which these
restrictions apply.  Table~\ref{TRAVERSAL-OPERATIONS-TABLE}
shows what I believe to be a complete list of operations
that traverse structures and take user code as a body (in the case of
macros) or as a functional argument (in the case of functions).

In addition, note that user code should not modify list
structure that might be undergoing interpretation by the evaluator,
whether explicitly invoked via \cdf{eval} or implicitly invoked,
for example as in the case of a hook function (a \cdf{defstruct}
print function, the value of \cdf{*evalhook*} or \cdf{*applyhook*}, etc.)
that happens to be a closure of interpreted code.  Similarly, \cdf{defstruct}
print functions and other hooks should not perform side effects
on data structures being printed or being processed by \cdf{format}, or on a
string given to \cdf{make-string-input-stream}.  You get the idea;
be sensible.

Note that an operation such as \cdf{mapcar} or \cdf{dolist} traverses
not only \emph{cdr} pointers (in order to chase down the list)
but also \emph{car} pointers (in order to obtain the elements themselves).
The restriction against modification appears to apply to all these pointers.

\begin{table}[t]
\leavevmode

\caption{Structure Traversal Operations Subject to Side Effect Restrictions}
\label{TRAVERSAL-OPERATIONS-TABLE}

\begingroup
\cf \tabcolsep0pt\relax
\begin{tabular*}{\textwidth}{@{}l@{\extracolsep{\fill}}ll@{}}
adjoin & maphash & reduce \\
assoc & mapl & remove \\
assoc-if & maplist & remove-duplicates \\
assoc-if-not & member & remove-if \\
count & member-if & remove-if-not \\
count-if & member-if-not & search \\
count-if-not & merge & set-difference \\
delete & mismatch & set-exclusive-or \\
delete-duplicates & nintersection & some \\
delete-if & notany & sort \\
delete-if-not & notevery & stable-sort \\
do-all-symbols & nset-difference & sublis \\
do-external-symbols & nset-exclusive-or & subsetp \\
do-symbols & nsublis & subst \\
dolist & nsubst & subst-if \\
eval & nsubst-if & subst-if-not \\
every & nsubst-if-not & substitute \\
find & nsubstitute & substitute-if \\
find-if & nsubstitute-if & substitute-if-not \\
find-if-not & nsubstitute-if-not & tree-equal \\
intersection & nunion & union \\
\textrm{certain} loop \textrm{clauses} & position & with-hash-table-iterator \\
map & position-if & with-input-from-string \\
mapc & position-if-not & with-output-to-string \\
mapcan & rassoc & with-package-iterator \\
mapcar & rassoc-if \\
mapcon & rassoc-if-not
\end{tabular*}
\endgroup
\end{table}

\section{Multiple Values}
\indexterm{multiple values}

Ordinarily the result of calling a Lisp function is a single Lisp object.
Sometimes, however, it is convenient for a function to compute several
objects and return them.
Common Lisp provides a mechanism for handling multiple values directly.
This mechanism is cleaner and more efficient than the usual tricks
involving returning a list of results or stashing results in global
variables.

\subsection{Constructs for Handling Multiple Values}

Normally multiple values are not used.  Special operators are
required both to \emph{produce} multiple values and to \emph{receive} them.
If the caller of a function does not request multiple values,
but the called function produces multiple values, then the first
value is given to the caller and all others are discarded;
if the called function produces zero values, then the caller gets {\false}
as a value.

The primary primitive for producing multiple values is \cdf{values},
which takes any number of arguments and returns that many values.  If the
last form in the body of a function is a \cdf{values} with three arguments,
then a call to that function will return three values.  Other special
forms also produce multiple values, but they can be described in terms of
\cdf{values}.  Some built-in Common Lisp functions, such as \cdf{floor}, return
multiple values; those that do are so documented.

The special operators and macros for receiving multiple values are as follows:
\begin{lisp}
multiple-value-list \\
multiple-value-call \\
multiple-value-prog1 \\
multiple-value-bind \\
multiple-value-setq
\end{lisp}
These specify a form to evaluate and an indication of where to put
the values returned by that form.

\begin{defun}[Function]
values &rest args

All of the arguments are returned, in order, as values.
For example:
\begin{lisp}
(defun polar (x y) \\
~~(values (sqrt (+ (* x x) (* y y))) (atan y x))) \\
 \\
(multiple-value-bind (r theta) (polar 3.0 4.0) \\
~~(vector r theta)) \\
~~~\EV\ \#(5.0 0.9272952)
\end{lisp}

The expression \cd{(values)} returns zero values.  This is the standard idiom
for returning no values from a function.

Sometimes it is desirable to indicate explicitly that a function will return
exactly one value.  For example, the function
\begin{lisp}
(defun foo (x y) \\
~~(floor (+ x y) y))
\end{lisp}
will return two values because \cdf{floor} returns
two values.  It may be that the second value makes no sense,
or that for efficiency reasons it is desired not to compute the
second value.  The \cdf{values} function is the standard idiom
for indicating that only one value is to be returned,
as shown in the following example.
\begin{lisp}
(defun foo (x y) \\
~~(values (floor (+ x y) y)))
\end{lisp}
This works because \cdf{values} returns exactly \emph{one} value for each of
its argument forms; as for any function call,
if any argument form to \cdf{values} produces more than one value, all but the
first are discarded.

There is absolutely no way in Common Lisp for a caller to distinguish between
returning a single value in the ordinary manner and returning
exactly one ``multiple value.''  For example, the values returned
by the expressions \cd{(+~1~2)} and \cd{(values (+~1~2))} are identical
in every respect: the single value \cd{3}.
\end{defun}

\begin{defun}[Constant]
multiple-values-limit

The value of \cdf{multiple-values-limit} is a positive integer that is
the upper exclusive bound on the number of values that may
be returned from a function.  This bound depends on the implementation
but will not be smaller than 20.
(Implementors are encouraged to make this limit as large as practicable
without sacrificing performance.)
See \cdf{lambda-parameters-limit} and \cdf{call-arguments-limit}.
\end{defun}

\begin{defun}[Function]
values-list list

All of the elements of \emph{list} are returned as multiple values.
For example:
\begin{lisp}
(values-list (list a b c)) \EQ\ (values a b c)
\end{lisp}
In general,
\begin{lisp}
(values-list \emph{list}) \EQ\ (apply \#'values \emph{list})
\end{lisp}
but \cdf{values-list} may be clearer or more efficient.
\end{defun}

\begin{defmac}
multiple-value-list form

\cdf{multiple-value-list} evaluates \emph{form} and returns a list of
the multiple values it returned.
For example:
\begin{lisp}
(multiple-value-list (floor -3 4)) \EV\ (-1 1)
\end{lisp}
\cdf{multiple-value-list} and \cdf{values-list} are therefore inverses
of each other.
\end{defmac}

\begin{defspec}
multiple-value-call function {form}*

\cdf{multiple-value-call} first evaluates \emph{function} to obtain a function
and then evaluates all of the \emph{form\/}s.  All the values
of the \emph{form\/}s are gathered together (not just one value from each)
and are all given as arguments to the function.  The result of \cdf{multiple-value-call}
is whatever is returned by the function.
For example:
\begin{lisp}
(+ (floor 5 3) (floor 19 4)) \\
~~~\EQ\ (+ 1 4) \EV\ 5 \\
(multiple-value-call \#'+ (floor 5 3) (floor 19 4)) \\
~~~\EQ\ (+ 1 2 4 3) \EV\ 10 \\
(multiple-value-list \emph{form}) \EQ\ (multiple-value-call \#'list \emph{form})
\end{lisp}
\end{defspec}

\begin{defspec}
multiple-value-prog1 form {form}*

\cdf{multiple-value-prog1} evaluates the first \emph{form} and saves all the values
produced by that form.  It then evaluates the other \emph{form}s
from left to right, discarding their values.  The values produced
by the first \emph{form} are returned by \cdf{multiple-value-prog1}.  See \cdf{prog1},
which always returns a single value.
\end{defspec}

\begin{defmac}
multiple-value-bind ({var}*) values-form
                    {declaration}* {form}*

The \emph{values-form} is evaluated, and each of the variables \emph{var} is
bound to the respective value returned by that form.  If there are more
variables than values returned, extra values of {\false} are given to the
remaining variables.  If there are more values than variables, the excess
values are simply discarded.  The variables are bound to the values over
the execution of the forms, which make up an implicit \cdf{progn}.
For example:
\begin{lisp}
(multiple-value-bind (x) (floor 5 3) (list x)) \EV\ (1) \\
(multiple-value-bind (x y) (floor 5 3) (list x y)) \EV\ (1 2) \\
(multiple-value-bind (x y z) (floor 5 3) (list x y z)) \\
~~~\EV\ (1 2 {\false})
\end{lisp}
\end{defmac}

\begin{defmac}
multiple-value-setq variables form

The \emph{variables} must be a list of variables.  The \emph{form} is
evaluated, and the variables are \emph{set} (not bound) to the values
returned by that form.  If there are more variables than values returned,
extra values of {\false} are assigned to the remaining variables.  If there
are more values than variables, the excess values are simply discarded.

\cdf{multiple-value-setq} always returns a single value, which is the first
value returned by \emph{form}, or {\false} if \emph{form} produces zero values.

\begin{newer}
X3J13 voted in March 1989
\issue{SYMBOL-MACROLET-SEMANTICS} to specify that if any \emph{var}
refers not to an ordinary variable but to a binding made by
\cdf{symbol-macrolet}, then that \emph{var} is handled as
if \cdf{setq} were used to assign the appropriate value to it.
\end{newer}
\end{defmac}


\begin{new}
\begin{defmac}*
nth-value n form

X3J13 voted in January 1989
\issue{NTH-VALUE}
to add a new macro named \cdf{nth-value}.
The argument forms \emph{n} and \emph{form} are both evaluated.
The value of \emph{n} must be a non-negative integer,
and the \emph{form} may produce any number of values.
The integer \emph{n} is used as a zero-based index into the
list of values.
Value \emph{n} of the \emph{form} is returned as the
single value of the \cdf{nth-value} form; \cdf{nil} is returned if the
\emph{form} produces no more than \emph{n} values.

As an example, \cdf{mod} could be defined as
\begin{lisp}
(defun mod (number divisor) \\*
~~(nth-value 1 (floor number divisor)))
\end{lisp}
Value number 1 is the \emph{second} value returned by \cdf{floor},
the first value being value number 0.

One could define \cdf{nth-value} simply as
\begin{lisp}
(defmacro nth-value (n form) \\*
~~{\Xbq}(nth ,n (multiple-value-list form)))
\end{lisp}
but the clever implementor will doubtless find an implementation
technique for \cdf{nth-value} that avoids constructing an intermediate
list of all the values of the \emph{form}.
\end{defmac}
\end{new}

\subsection{Rules Governing the Passing of Multiple Values}

It is often the case that the value
of a special operator or macro call
is defined to be the value of one of its subforms.
For example, the
value of a \cdf{cond} is the value of the last form in the selected clause.

In most such cases, if the subform produces multiple values, then the original
form will also produce all of those values.
This \emph{passing back} of
multiple values of course has no effect unless eventually one of the
special operators for receiving multiple values is reached.

To be explicit, multiple values can result from a special operator
under precisely these circumstances:
\begin{flushdesc}
\item[\emph{Evaluation and application}]\leavevmode
\begin{itemize}
\item
\cdf{eval} returns multiple values if the form given it to
evaluate produces multiple values.

\item
\cdf{apply}, \cdf{funcall}, and \cdf{multiple-value-call}
pass back multiple values from the function applied or called.
\end{itemize}

\item[\emph{Implicit \cdf{progn} contexts}]\leavevmode
\begin{itemize}
\item
The special operator \cdf{progn}
passes back multiple values resulting from evaluation of the
last subform.  Other situations referred to as ``implicit \cdf{progn},''
where several forms are evaluated and the results of all but the last form
are discarded, also pass back multiple values from the last form.
These situations include the body of a lambda-expression,
in particular those constructed by \cdf{defun},
\cdf{defmacro}, and \cdf{deftype}.
Also included are bodies of the constructs
\cdf{eval-when},
\cdf{progv}, \cdf{let},
\cdf{let*}, \cdf{when}, \cdf{unless},
\cdf{block},
\cdf{multiple-value-bind}, and \cdf{catch},
as well as clauses in such conditional
constructs as
\cdf{case}, \cdf{typecase},
\cdf{ecase}, \cdf{etypecase}, \cdf{ccase}, and \cdf{ctypecase}.
\end{itemize}
\end{flushdesc}

\begin{new}
X3J13 has voted to add many new constructs to the language that contain
implicit \cdf{progn} contexts.  I won't attempt to list them all here.
Of particular interest, however, is \cdf{locally}, which may be regarded
as simply a version of \cdf{progn} that permits declarations before its
body.  This provides a useful building block for constructing macros
that permit declarations (but not documentation strings)
before their bodies and pass back any multiple values
produced by the last sub-form of a body.  (If a body can contain a documentation
string, most likely \cdf{lambda} is the correct building block to use.)
\end{new}

\begin{flushdesc}
\item[\emph{Conditional constructs}]\leavevmode
\begin{itemize}
\item
\cdf{if} passes back multiple values from whichever subform is selected
(the \emph{then} form or the \emph{else} form).

\item
\cdf{and} and \cdf{or} pass back multiple values from the last subform
but not from subforms other than the last.

\item
\cdf{cond} passes back multiple values from the last subform of
the implicit \cdf{progn} of the selected clause.
If, however, the clause selected is a singleton clause,
then only a single value (the non-{\false} predicate value)
is returned.  This is true even if the singleton clause is
the last clause of the \cdf{cond}.  It is \emph{not} permitted to
treat a final clause \cd{(x)} as being the same as \cd{(t x)}
for this reason; the latter passes back multiple values from the form \cdf{x}.
\end{itemize}

\item[\emph{Returning from a block}]\leavevmode
\begin{itemize}
\item
The \cdf{block} construct passes back multiple values from its last subform
when it exits normally.  If \cdf{return-from} (or \cdf{return}) is
used to terminate the \cdf{block} prematurely, then \cdf{return-from}
passes back multiple values from its subform as the values of the
terminated \cdf{block}.  Other constructs that create implicit blocks,
such as
\cdf{do}, \cdf{dolist}, \cdf{dotimes}, \cdf{prog}, and
\cdf{prog*}, also pass back multiple values specified by
\cdf{return-from} (or \cdf{return}).

\item
\cdf{do} passes back multiple values from
the last form of the exit clause, exactly as if the exit clause
were a \cdf{cond} clause.  Similarly, \cdf{dolist} and \cdf{dotimes}
pass back multiple values from the \emph{resultform} if that is executed.
These situations are all examples of implicit uses of \cdf{return-from}.
\end{itemize}

\item[\emph{Throwing out of a catch}]\leavevmode
\begin{itemize}
\item
The \cdf{catch} construct returns multiple values if
the result form in a \cdf{throw} exiting from
such a catch produces multiple values.
\end{itemize}

\item[\emph{Miscellaneous situations}]\leavevmode
\begin{itemize}
\item
\cdf{multiple-value-prog1} passes back multiple values from its first
subform.  However, \cdf{prog1} always returns a single value.

\item
\cdf{unwind-protect} returns multiple values if the form it protects
returns multiple values.

\item
\cdf{the} returns multiple values if the form it contains returns
multiple values.
\end{itemize}
\end{flushdesc}

Among special operators that \emph{never} pass back multiple values are
\cdf{prog1},
\cdf{prog2}, \cdf{setq}, and \cdf{multiple-value-setq}.
The conventional way to force only one value to be returned from a form \cdf{x}
is to write \cd{(values x)}.

The most important rule about multiple values is:
\textbf{No matter how many values a form produces,
if the form is an argument form in a function call,
then exactly one value (the first one) is used.}

For example, if you write \cd{(cons (floor x))}, then \cdf{cons} will always
receive \emph{exactly} one argument (which is of course an error),
even though \cdf{floor} returns two values.  To pass both values from \cdf{floor}
to \cdf{cons}, one must write something like
\cd{(multiple-value-call \#'cons (floor x))}.
In an ordinary function call,
each argument form produces exactly \emph{one} argument;  if such a form
returns zero values, {\false} is used for the argument, and if more than one
value, all but the first are discarded.
Similarly, conditional constructs such as \cdf{if} that test the value of a form
will use exactly one value, the first one, from that form and discard the rest;
such constructs will use {\false} as the test value if zero values are returned.

\section{Dynamic Non-Local Exits}
\label{CATCH-THROW-SECTION}
\indexterm{non-local exit}
\indexterm{dynamic exit}
%\indexterm{catch}
%\indexterm{throw}

Common Lisp provides a facility for exiting from a complex process
in a non-local, dynamically scoped manner.  There are two classes of
special operators for this purpose, called \emph{catch} forms and \emph{throw}
forms, or simply \emph{catches} and \emph{throws}.  A catch form evaluates some
subforms in such a way that, if a throw form is executed during such
evaluation, the evaluation is aborted at that point and the catch form
immediately returns a value specified by the throw.  Unlike \cdf{block}
and \cdf{return} (section~\ref{BLOCK-RETURN-SECTION}),
which allow for exiting a \cdf{block} form from any
point lexically within the body of the \cdf{block}, the catch/throw
mechanism works even if the throw form is not textually within the body
of the catch form.  The throw need only occur within the extent (time
span) of the evaluation of the body of the catch.  This is analogous to
the distinction between dynamically bound (special) variables and
lexically bound (local) variables.

\begin{defspec}
catch tag {form}*

The \cdf{catch} special operator serves as a target for transfer
of control by \cdf{throw}.
The form \emph{tag} is evaluated first to produce an object
that names the catch; it may be any Lisp object.
A catcher is then established with the object as the tag.
The \emph{form\/}s are evaluated as an implicit \cdf{progn},
and the results of the last form are returned,
except that if during the evaluation of the \emph{form\/}s
a throw should be executed such that the tag
of the throw matches (is \cdf{eq} to) the tag of the \cdf{catch}
and the catcher is the most recent outstanding catcher with that tag,
then the evaluation of the \emph{form\/}s is aborted and the results
specified by the throw
are immediately returned from the \cdf{catch} expression.
The catcher established by the \cdf{catch} expression is disestablished
just before the results are returned.

The tag is used to match throws with catches.
\cd{(catch 'foo \emph{form})} will catch a \cd{(throw 'foo \emph{form})} but
not a \cd{(throw 'bar \emph{form})}.  It is an error if \cdf{throw} is done
when there is no suitable \cdf{catch} ready to catch it.

Catch tags are compared using \cdf{eq},
not \cdf{eql}; therefore numbers and characters
should not be used as catch tags.
\end{defspec}

\indexterm{unwind protection}
\indexterm{cleanup handler}
\begin{defspec}
unwind-protect protected-form {cleanup-form}*

Sometimes it is necessary to evaluate a form and make sure that
certain side effects take place after the form is evaluated;
a typical example is
\begin{lisp}
(progn (start-motor) \\*
~~~~~~~(drill-hole) \\*
~~~~~~~(stop-motor))
\end{lisp}
The non-local exit facility of Common Lisp creates a situation in which
the above code won't work, however: if \cdf{drill-hole} should
do a throw to a catch that is outside of the \cdf{progn}
form (perhaps because the drill bit broke),
then \cd{(stop-motor)} will never be evaluated
(and the motor will presumably be left running).
This is particularly likely if \cdf{drill-hole} causes a Lisp error
and the user tells the error-handler to give up and abort
the computation.
(A possibly more practical example might be
\begin{lisp}
(prog2 (open-a-file) \\*
~~~~~~~(process-file) \\*
~~~~~~~(close-the-file))
\end{lisp}
where it is desired always to close the file when the computation
is terminated for whatever reason.  This case is so important
that Common Lisp provides the special operator \cdf{with-open-file} for
this purpose.)

In order to allow the example hole-drilling program to work, it can
be rewritten using \cdf{unwind-protect} as follows:
\begin{lisp}
;; Stop the motor no matter what (even if it failed to start). \\*
\\*
(unwind-protect \\*
~~(progn (start-motor) \\*
~~~~~~~~~(drill-hole)) \\*
~~(stop-motor))
\end{lisp}
If \cdf{drill-hole} does a throw that attempts to quit out of the
\cdf{unwind-protect}, then \cd{(stop-motor)} will be executed.

This example assumes that it is correct to call \cdf{stop-motor}
even if the motor has not yet been started.  Remember that
an error or interrupt may cause an exit even before any initialization
forms have been executed.  Any state restoration code
should operate correctly no matter where in the protected code an
exit occurred.  For example, the following code
is not correct:
\begin{lisp}
(unwind-protect \\*
~~(progn (incf *access-count*) \\*
~~~~~~~~~(perform-access)) \\*
~~(decf *access-count*))
\end{lisp}
If an exit occurs before completion of the \cdf{incf} operation
the \cdf{decf} operation will be executed anyway, resulting in an
incorrect value for \cd{*access-count*}.
The correct way to code this is as follows:
\begin{lisp}
(let ((old-count *access-count*)) \\
~~(unwind-protect \\
~~~~(progn (incf *access-count*) \\
~~~~~~~~~~~(perform-access)) \\
~~~~(setq *access-count* old-count)))
\end{lisp}

As a general rule, \cdf{unwind-protect} guarantees to execute
the \emph{cleanup-form\/}s before exiting, whether it terminates
normally or is aborted by a throw of some kind.
(If, however, an exit occurs during execution of the \emph{cleanup-form\/}s,
no special action is taken.  The \emph{cleanup-form\/}s of an \cdf{unwind-protect}
are not protected by that \cdf{unwind-protect}, though they may be
protected if that \cdf{unwind-protect} occurs within the protected
form of another \cdf{unwind-protect}.)
\cdf{unwind-protect} returns whatever results from evaluation of
the \emph{protected-form} and discards all the results
from the \emph{cleanup-form\/}s.

It should be emphasized that \cdf{unwind-protect} protects against
\emph{all} attempts to exit from the protected form,
including not only ``dynamic exit'' facilities such as \cdf{throw}
but also ``lexical exit'' facilities such as \cdf{go} and
\cdf{return-from}.  Consider this situation:
\begin{lisp}
(tagbody \\
~~(let ((x 3)) \\
~~~~(unwind-protect \\
~~~~~~(if (numberp x) (go out)) \\
~~~~~~(print x))) \\
~out \\
~~...)
\end{lisp}
When the \cdf{go} is executed, the call to \cdf{print} is executed first,
and then the transfer of control to the tag \cdf{out} is completed.

\begin{newer}
X3J13 voted in March 1989 \issue{EXIT-EXTENT} to clarify the interaction
of \cdf{unwind-protect} with constructs that perform exits.

Let an \emph{exit} be a point out of which control can be transferred.
For a \cdf{throw} the exit is the matching \cdf{catch}; for
a \cdf{return-from} the exit is the corresponding \cdf{block}.
For a \cdf{go} the exit is the statement within the \cdf{tagbody} (the one to which
the target tag belongs) which is being executed at the time the \cdf{go} is performed.

The extent of an exit is dynamic; it is not indefinite. The extent
of an exit begins when the corresponding form (\cdf{catch}, \cdf{block}, or \cdf{tagbody}
statement) is entered.  When the extent of an exit has ended, it is no
longer legal to return from it.

Note that the extent of an exit is not the same thing as the scope or extent of the
designator by which the exit is identified. For example, a \cdf{block}
name has lexical scope but the extent of its exit is dynamic.  The
extent of a \cdf{catch} tag could differ from the extent of the exit
associated with the \cdf{catch} (which is exactly what is at issue here).
The difference matters when there are transfers
of control from the cleanup clauses of an \cdf{unwind-protect}.

When a transfer of control out of an exit is initiated by \cdf{throw},
\cdf{return-from}, or \cdf{go},
a variety of events occur before the transfer of control is complete:
\begin{itemize}
\item The cleanup clauses of any intervening \cdf{unwind-protect} clauses
    are evaluated.
\item Intervening dynamic bindings of special variables and catch tags
    are undone.
\item Intervening exits are \emph{abandoned}, that is, their extent ends and it
    is no longer legal to attempt to transfer control from them.
\item The extent of the exit being invoked ends.
\item Control is finally passed to the target.
\end{itemize}
The first edition left the order of these events in some doubt.
The implementation note for \cdf{throw} hinted that the first two processes
are interwoven, but it was unclear whether it is permissible
for an implementation to abandon all 
intervening exits before processing any intervening \cdf{unwind-protect}
cleanup clauses.

The clarification adopted by X3J13 is as follows.
Intervening exits are abandoned as soon as the transfer of control is initiated;
in the case of a \cdf{throw}, this occurs at the beginning of the ``second pass''
mentioned in the implementation note.  It is an error to
attempt a transfer of control to an exit whose dynamic extent has
ended.

Next the evaluation of \cdf{unwind-protect} cleanup clauses and the
undoing of dynamic bindings and \cdf{catch} tags are performed together,
in the order corresponding to the reverse of the order
in which they were established.
The effect of this is that the cleanup clauses of an \cdf{unwind-protect}
will see the same dynamic bindings of variables and \cdf{catch} tags as were
visible when the \cdf{unwind-protect} was entered.  (However, some of those
\cdf{catch} tags may not be useable because they correspond to abandoned
exit points.)

Finally  control is transferred to
the originally invoked exit and simultaneously that exit is abandoned.

The effect of this specification is that once a program has attempted
to transfer control to a particular exit, an \cdf{unwind-protect} cleanup
form cannot
step in and decide to transfer control to a more recent (nested) exit,
blithely forgetting the original exit request.  However, a cleanup form
may restate the request to transfer to the same exit that started
the cleanup process.

Here is an example based on a nautical metaphor.  The function \cdf{gently}
moves an oar in the water with low force, but if an oar gets stuck, the caller
will catch a crab.  The function \cdf{row}
takes a boat, an oar-stroking function,
a stream, and a count; an oar is constructed for the boat and stream
and the oar-stroking function is called \cd{:count} times.
The function \cdf{life} rows a particular boat.
Merriment follows, except that if the oarsman is winded he must stop
to catch his breath.
\begin{lisp}
(defun gently (oar) \\*
~~(stroke oar :force 0.5) \\*
~~(when (stuck oar) \\*
~~~~(throw 'crab nil))) \\
\\
(defun row (boat stroke-fn stream \&key count) \\*
~~(let ((oar (make-oar boat stream))) \\*
~~~~(loop repeat count do (funcall stroke-fn oar)))) \\
\\
(defun life () \\*
~~(catch 'crab \\*
~~~~(catch 'breath \\*
~~~~~~(unwind-protect \\*
~~~~~~~~(row *your-boat* \#'gently *query-io* :count 3)) \\*
~~~~~~~~(when (winded) (throw 'breath nil))) \\*
~~~~~~(loop repeat 4 (set-mode :merry)) \\*
~~~~~~(dream))))
\end{lisp}
Suppose that the oar gets stuck, causing \cdf{gently} to call \cdf{throw}
with the tag \cdf{crab}.
The program is then committed to exiting from the outer \cdf{catch} (the one
with the tag \cdf{crab}).  As control breaks out of the \cdf{unwind-protect} form,
the \cdf{winded} test is executed.  Suppose it is true; then another call to \cdf{throw}
occurs, this time with the tag \cdf{breath}.  The inner \cdf{catch} (the one with
the tag \cdf{breath}) has been abandoned as a result of the first
\cdf{throw} operation (still in progress).  The clarification voted by X3J13
specifies that the program is in error for attempting to transfer control
to an abandoned exit point.  To put it in terms of the example: once you have
begun to catch
a crab, you cannot rely on being able to catch your breath.

Implementations may support longer extents for exits than is
required by this specification,
but portable programs may not rely on such extended extents.

(This specification is somewhat controversial.  An alternative proposal was
that the abandoning of exits should be lumped in with
the evaluation of \cdf{unwind-protect} cleanup clauses and the
undoing of dynamic bindings and \cdf{catch} tags, performing all
in reverse order of establishment.  X3J13 agreed that this approach is
theoretically cleaner and more elegant but also more stringent
and of little additional practical use.  There was some concern that
a more stringent specification might be a great added burden to some
implementors and would achieve only a small gain for users.)
\end{newer}
\end{defspec}

\begin{defspec}
throw tag result

The \cdf{throw} special operator transfers control to a matching
\cdf{catch} construct.
The \emph{tag} is evaluated first to produce an object
called the throw tag; then the \emph{result} form is evaluated,
and its results are saved (if the \emph{result} form produces
multiple values, then \emph{all} the values are saved).
The most recent outstanding catch whose tag matches the throw tag
is exited; the saved results are returned as the value(s) of the catch.
A \cdf{catch} matches only if the catch tag is \cdf{eq} to the throw tag.

In the process, dynamic variable
bindings are undone back to the point of the catch, and any intervening
\cdf{unwind-protect} cleanup code is executed.
The \emph{result} form is evaluated before the unwinding process commences,
and whatever results it produces are returned from the catch.

If there is no outstanding catcher whose tag matches the throw tag,
no unwinding of the stack is performed, and an error is signalled.
When the error is signalled, the outstanding catchers and the dynamic
variable bindings are those in force at the point of the throw.

\beforenoterule
\begin{implementation}
These requirements imply that throwing should typically
make two passes over the control stack.  In the first pass it simply
searches for a matching catch.  In this search every \cdf{catch}
must be considered, but every
\cdf{unwind-protect} should be ignored.  On the second pass the stack
is actually unwound, one frame at a time, undoing dynamic bindings
and outstanding \cdf{unwind-protect} constructs in reverse order of creation
until the matching catch is reached.
\end{implementation}
\afternoterule
\end{defspec}

%RUSSIAN
\else

\chapter{Управляющие конструкции}
\label{CONTRL}

Common Lisp предоставляет набор специальных структур для построения
программ. Некоторые из них связаны со порядком выполнения (управляющие
структуры), тогда как другие с управлением доступа к переменным (структурам
окружения).
Некоторые из этих возможностей реализованы как операторы;
другие как макросы, которые в свою очередь разворачиваются в совокупность
фрагментов программы, выраженных в терминах операторов или других
макросов.

Вызов функции (применение функции) является основным методом создания Lisp
программ. Операции записываются, как применение функции к её аргументам. Обычно
Lisp программы пишутся, как большая совокупность маленьких функции,
взаимодействующих с помощью вызовов одна другой, таким образом большие операции
определяются в терминах меньших.
Функции Lisp'а могут рекурсивно вызывать сами себя, как напрямую, так и косвенно.

Локально определённые функция (\cdf{flet}, \cdf{labels}) и макросы
(\cdf{macrolet}) достаточно универсальны.
Новая функциональность макросимволов позволяет использовать ещё больше синтаксической гибкости.

Несмотря на то, что язык Lisp более функциональный (applicative), чем императивный
(statement-oriented), он предоставляет много операций, имеющих побочные эффекты,
и следовательно требует конструкции для управления последовательностью вызовов с
побочными эффектами. Конструкция \cdf{progn}, которая является приблизительным
эквивалентом Algol'ному блоку \textbf{begin}-\textbf{end} с всеми его точками с
запятыми, последовательно выполняет некоторое количество форм, игнорируя все их
значения, кроме последней.
Много Lisp'овых управляющих конструкции неявно включают последовательное
выполнение форм, в таком случае говорится, что это <<неявный progn>>.
\indexterm{implicit \cdf{progn}}
Существуют также другие управляющие конструкции такие, как \cdf{prog1} и
\cdf{prog2}.

Для циклов Common Lisp предоставляет, как общую функцию для итераций \cdf{do},
так и набор более специализированных функций для итераций или отображений
(mapping) различных структур данных.

Common Lisp предоставляет простые одноветочные условные операторы \cdf{when} и
\cdf{unless}, простой двуветочный условный оператор \cdf{if} и более общие
многоветочные \cdf{cond} и \cdf{case}. Выбор одного из них для использования в
какой-либо ситуации зависит от стиля и вкуса.

Предоставляются конструкции выполнения нелокальных выходов с различными 
правилами областей видимости: \cdf{block}, \cdf{return}, \cdf{return-from},
\cdf{catch} и \cdf{throw}.

Конструкции multiple-value предоставляют удобный способ для возврата более одного
значения из функции, смотрите \cdf{values}.

\section{Константы и переменные}
\label{FUNCTION-NAME-SECTION}

Так как некоторые Lisp'овые объекты данных используются для отображения
программ, можно всегда обозначить константный объект данных с помощью записи
без приукрашательств формы данного объекта. Однако порождается двусмысленность:
константный это объект или фрагмент кода. Эту двусмысленность разрешает
оператор \cdf{quote}.

В Common Lisp'е присутствуют два вида переменных, а именно: обычные переменные и
имена функций. Между этими типами есть несколько сходств, и в некоторых случаях
для взаимодействия с ними используются похожие функции, например \cdf{boundp} и
\cdf{fboundp}. 
Однако для в большинстве случаев два вида переменных используются для совсем
разных целей: один указывает на функции, макросы и операторы, а другие
на объекты данных.

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to introduce the concept
of a \emph{function-name}, which may be either a symbol or a two-element list whose
first element is the symbol \cdf{setf} and whose second element is a symbol.
The primary purpose of this is to allow \cdf{setf} expander functions to be
CLOS generic functions with user-defined methods.
Many places in Common Lisp that used to require a symbol for a function
name are changed to allow 2-lists as well; for example, \cdf{defun}
is changed so that one may write \cd{(defun (setf~foo) ...)},
and the \cdf{function} special operator is changed to accept any function-name.
See also \cdf{fdefinition}.

By convention, any function named \cd{(setf \emph{f\/})} should return its first
argument as its only value, in order to preserve the specification that
\cdf{setf} returns its \emph{newvalue}.  See \cdf{setf}.

Implementations are free to extend the syntax of function-names to
include lists beginning with additional symbols other than \cdf{setf}
or \cdf{lambda}.
\end{newer}

\subsection{Ссылки на переменные}

Значение обычной переменной может быть получено просто с помощью записи его
имени как формы, которая будет выполнена. Будет ли данное имя распознано как имя
специальной или лексической переменной зависит от наличия или отсутствия
соответствующей декларации \cdf{special}. Смотрите главу~\ref{DECLAR}.

Следующие функции и операторы позволяют ссылаться на значения констант и
переменных.

\begin{defspec}
quote object

\cd{(quote \emph{x})} возвращает \emph{x}.
\emph{object} не выполняется и может быть любым объектом Lisp'а.
Конструкция позволяет записать в программе любой объект, как константное
значение.
Например:
\begin{lisp}
(setq a 43) \\
(list a (cons a 3)) \EV\ (43 (43 . 3)) \\
(list (quote a) (quote (cons a 3)) \EV\ (a (cons a 3))
\end{lisp}
Так как \cdf{quote} форма так полезна, но записывать её трудоёмко, для неё
определена стандартная аббревиатура:
любая форма \emph{f} с предшествующей одинарной кавычкой (\cd{~'~})
оборачивается формой \cd{(quote~~)} для создания \cd{(quote \emph{f})}.
Например:
\begin{lisp}
(setq x '(the magic quote hack))
\end{lisp}
обычно интерпретируется функцией \cdf{read}, как
\begin{lisp}
(setq x (quote (the magic quote hack)))
\end{lisp}
Смотрите раздел~\ref{MACRO-CHARACTERS-SECTION}.


It is an error to destructively modify any object that appears as a constant
in executable code, whether within a \cdf{quote} special operator or as
a self-evaluating form.

See section~\ref{COMPILER-SECTION} for a discussion of how quoted constants
are treated by the compiler.

Деструктивная модификация любого объекта, который представлен как константа в
выполняемом коде с помощью специального оператора \cdf{quote} или как
самовычисляемая форма, является ошибкой.

Смотрите раздел~\ref{COMPILER-SECTION} для обсуждения того, как заквоченные
константы обрабатываются компилятором.

\begin{newer}
X3J13 voted in March 1989 \issue{QUOTE-SEMANTICS} to clarify that
\cdf{eval} and \cdf{compile} are not permitted either to copy or
to coalesce (``collapse'') constants (see \cdf{eq})
appearing in the code they process; the resulting
program behavior must refer to objects that are \cdf{eql} to the
corresponding objects in the source code.
Moreover, the constraints introduced by the votes on
issues \issue{CONSTANT-COMPILABLE-TYPES}
and \issue{CONSTANT-CIRCULAR-COMPILATION}
on what kinds of objects may appear
as constants apply only to \cdf{compile-file} (see section~\ref{COMPILER-SECTION}).
\end{newer}
\end{defspec}

\begin{defspec}
function fn

Значением \cdf{function} всегда является функциональной интерпретацией
\emph{fn}. \emph{fn} интерпретируется как, если бы она была использована на
позиции функции в форме вызова функции.
В частности, если \emph{fn} является символом, возвращается определение функции,
связанное с этим символом, смотрите \cdf{symbol-function}.
Если \emph{fn} является лямбда-выражением, тогда возвращается <<лексическое
замыкание>>, это значит функция, которая при вызове выполняет тело
лямбда-выражения таким образом, чтобы правила лексического контекста выполнялись 
правильно.

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE}
to specify that the result of a \cdf{function} special operator is always
of type \cdf{function}.  This implies that a form \cd{(function~\emph{fn\/})}
may be interpreted as \cd{(the (function~\emph{fn\/}))}.

It is an error to use the \cdf{function} special operator on a
    symbol that does not denote a function in the lexical or global environment in
    which the special operator appears.  Specifically, it is an error to use the
    \cdf{function} special operator on a symbol that denotes a macro or special operator.
    Some implementations may choose not to signal this error for
        performance reasons, but implementations are forbidden
        to extend the semantics of \cdf{function} in this respect; that is, an
        implementation is not allowed to
        define the failure to signal an error to be a ``useful'' behavior.
\end{newer}

Функция \cdf{function}
принимает любое имя функции (символ или список,
\emph{car} элементы которого является \cdf{setf}---смотрите раздел~\ref{FUNCTION-NAME-SECTION})
Также принимает принимает лямбда-выражение.
Так можно записать \cd{(function (setf cadr))} для ссылки на функцию раскрытия
\cdf{setf} для \cdf{cadr}.

\indexterm{closure}
Например:
\begin{lisp}
(defun adder (x) (function (lambda (y) (+ x y))))
\end{lisp}
Результат \cd{(adder 3)} является функцией, которая добавляет \cd{3} к её
аргументу:
\begin{lisp}
(setq add3 (adder 3)) \\
(funcall add3 5) \EV\ 8
\end{lisp}
Это работает, потому что \cdf{function} создаёт замыкание над внутренним
лямбда-выражением, которое может ссылаться на значение \cd{3} переменной \cd{x}
даже после того, как выполнение вышло из функции \cd{adder}.

Если посмотреть глубже, то лексическое замыкание обладает возможностью ссылаться
на лексически видимые \emph{связывание}, а не просто на значения.
Рассмотрим такой код:
\begin{lisp}
(defun two-funs (x) \\
~~(list (function (lambda () x)) \\
~~~~~~~~(function (lambda (y) (setq x y))))) \\
(setq funs (two-funs 6)) \\
(funcall (car funs)) \EV\ 6 \\
(funcall (cadr funs) 43) \EV\ 43 \\
(funcall (car funs)) \EV\ 43
\end{lisp}
Функция \cdf{two-funs} возвращает список двух функций, каждая из которых
ссылается на \emph{связывание} переменной \cdf{x}, созданной в момент входа в
функцию \cd{two-funs}, когда она была вызвана с аргументом \cd{6}.
Это связывание сначала имеет значение \cd{6}, но \cdf{setq} может изменить
связывание. Лексическое замыкание для первого лямбда-выражения не является
<<создаёт снимок>> значения \cd{6} для \cd{x} при создании замыкания. Вторая
функция может использоваться для изменения связывания (на \cd{43} например), и
это изменённое значение станет доступным в первой функции.

В ситуации, когда замыкание лямбда-выражения над одним и тем же множеством
связываний может создаваться несколько раз, эти полученные разные замыкания
могут быть равны или не равны \cdf{eq} в зависимости от реализации.
Например:
\begin{lisp}
(let ((x 5) (funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(push \#'(lambda (z) \\*
~~~~~~~~~~~~~~(if (null z) (setq x 0) (+ x z))) \\*
~~~~~~~~~~funs)) \\*
~~funs)
\end{lisp}
Результат данного выражения является списком десяти замыканий.
Каждое логически требует только связывания \cd{x}.
В любом случае это одно и то же связывание, но десять замыканий могут быть равны
или не равны \cdf{eq} друг другу.
С другой стороны, результат выражения
\begin{lisp}
(let ((funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(let ((x 5)) \\*
~~~~~~(push (function (lambda (z) \\*
~~~~~~~~~~~~~~~~~~~~~~~~(if (null z) (setq x 0) (+ x z)))) \\*
~~~~~~~~~~~~funs))) \\*
~~funs)
\end{lisp}
также является списком из десяти замыканий.
Однако в этом случае, но одна из пар замыканий не будет равна \cdf{eq}, потому
что каждое замыкание имеет своё связывание \cd{x} отличное от
другого. Связывания отличаются, так как в замыкании используется \cdf{setq}.

Вопрос различного поведения важен, поэтому рассмотрим следующее простое выражение:
\begin{lisp}
(let ((funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(let ((x 5)) \\*
~~~~~~(push (function (lambda (z) (+ x z))) \\*
~~~~~~~~~~~~funs))) \\*
~~funs)
\end{lisp}
Результатом является десять замыканий, которые \emph{могут} быть равны \cdf{eq}
попарно. Однако, можно подумать что связывания \cd{x} для каждого замыкания разные, так
как создаются в цикле, но связывания не могут различаться, потому что их значения
идентичны и неизменяемы (иммутабельны), в замыканиях отсутствует \cdf{setq} для
\cd{x}.
Компилятор может в таких случаях оптимизировать выражение так:
\begin{lisp}
(let ((funs '())) \\*
~~(dotimes (j 10) \\*
~~~~(push (function (lambda (z) (+ 5 z))) \\*
~~~~~~~~~~funs)) \\*
~~funs)
\end{lisp}
после чего, в конце концов, замыкания точно могут быть равны.
Общее правило такое, что реализация может в двух различных случаях выполнения
формы \cdf{function} вернуть идентичные (\cdf{eq}) замыкания, если она может
доказать, что два концептуально различающихся замыкания по факту ведут себя
одинаково при одинаковых параметрах вызова.
Это просто разрешается для оптимизации. Полностью корректная реализация может
каждый раз при выполнении формы \cdf{function} возвращать новое замыкание не
равное \cdf{eq} другим.

Часто компилятор может сделать вывод, что замыкание по факту не нуждается в
замыкании над какими-либо связываниями переменных. Например,
в фрагменте кода
\begin{lisp}
(mapcar (function (lambda (x) (+ x 2))) y)
\end{lisp}
функция \cd{(lambda (x) (+ x 2))} не содержит ссылок на какие-либо внешние
сущности. В этом важном случае, одно и то же <<замыкание>> может
быть использовано в качестве результата всех выполнений оператора
\cdf{function}.
Несомненно, данное значение может и не быть объектом замыкания. Оно может быть
просто скомпилированной функцией, не содержащей информации об окружении.
Данный пример просто является частным случаем предыдущего разговора и включён в
качестве подсказки для разработчиков знакомых с предыдущими методами реализации
Lisp'а. Различие между замыканиями и другими видами функций слегка размыто,
Common Lisp не определяет отображения для замыканий и метода различия замыканий
и простых функций. Все что имеет значение, это соблюдение правил лексической
области видимости.

Так как форма \cdf{function} используются часто, но её запись длинная,
для неё определена стандартная аббревиатура: любая форма \emph{f} с
предшествующими \cf{\#'} разворачивается в форму \cd{(function \emph{f})}.
Например,
\begin{lisp}
(remove-if \#'numberp '(1 a b 3))
\end{lisp}
обычно интерпретируется функцией \cdf{read} как
\begin{lisp}
(remove-if (function numberp) '(1 a b 3))
\end{lisp}
Смотрите раздел~\ref{SHARP-SIGN-MACRO-CHARACTER-SECTION}.
\end{defspec}

\begin{defun}[Функция]
symbol-value symbol

\cdf{symbol-value} возвращает текущее значение динамической (специальной)
переменной с именем \emph{symbol}.
Если символ не имеет значения, возникает ошибка. Смотрите \cdf{boundp} и
\cdf{makunbound}. 
Следует отметить, что константные символы являются переменными, которые не могут
быть изменены, таким образом \cdf{symbol-value} может использоваться для
получения значения именованной константы. \cdf{symbol-value} от ключевого
символа будет возвращать этот ключевой символ.

\cdf{symbol-value} не может получить доступ к значению лексической переменной.

В частности, эта функция полезна для реализации интерпретаторов для встраиваемых
языков в Lisp'е.
Соответствующая функция присваивания \cdf{set}. Кроме того, можно пользоваться
конструкцией \cdf{setf} с \cdf{symbol-value}.
\end{defun}

\begin{defun}[Функция]
symbol-function symbol

\cdf{symbol-function} возвращает текущее глобальное определение функции с именем
\emph{symbol}. В случае если символ не имеет определения функции сигнализируется
ошибка, смотрите \cdf{fboundp}. Следует отметить что определение может быть
функцией или объектом отображающим оператор или макрос.
Однако, в последнем случае, попытка вызова объекта как функции будет является
ошибкой.
Лучше всего заранее проверить символ с помощью \cdf{macro-function} и
\cdf{special-operator-p} и только затем вызвать функциональное значение, если оба
предыдущих теста вернули ложь.

Эта функция полезна, в частности, для реализации интерпретаторов языков
встроенных в Lisp.

\cdf{symbol-function} не может получить доступ к значению имени лексической
функции, созданной с помощью \cdf{flet} или \cdf{labels}. Она может получать
только глобальное функциональное значение.

Глобальное определение функции для некоторого символа может быть изменено с
помощью \cdf{setf} и \cdf{symbol-function}.
При использовании этой операции символ будет иметь \emph{только} заданное определение в качестве своего
глобального функционального значения. Любое предыдущее определение, было ли оно
макросом или функцией, будет потеряно.
Попытка переопределения оператора (смотрите
таблицу~\ref{SPECIAL-FORM-TABLE}) будет является ошибкой.

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE} to clarify the behavior
of \cdf{symbol-function} in the light of the redefinition of the type \cdf{function}.
\begin{itemize}
\item It is permissible to call \cdf{symbol-function}
    on any symbol for which \cdf{fboundp} returns true.
 Note that \cdf{fboundp} must return true for a symbol naming a macro or
    a special operator.

\item If \cdf{fboundp} returns true for a symbol
        but the symbol denotes a macro or special operator,
        then the value returned by \cdf{symbol-function} is not well-defined
        but \cdf{symbol-function} will not signal an error. 

\item When \cdf{symbol-function} is used with \cdf{setf}
 the new value must be of type \cdf{function}.
	It is an error to set the \cdf{symbol-function} of a symbol to a
	symbol, a list, or the value returned by \cdf{symbol-function} on
	the name of a macro or a special operator.
\end{itemize}
\end{newer}
\end{defun}

\begin{defun}[Функция]
fdefinition function-name

Функция похожа на  \cdf{symbol-function}
за исключением того, что её аргументы может быть любым именем функции (символ
или списка, у которого \emph{car} элемент равен \cdf{setf}---смотрите раздел~\ref{FUNCTION-NAME-SECTION}).
Функция возвращает текущее глобальное значение определения функции с именем \emph{function-name}.
Можно использовать \cdf{fdefinition} вместе с \cdf{setf}
для изменения глобального определения функции связанной с переданным в параметре
именем.
\end{defun}

\begin{defun}[Функция]
boundp symbol

\cdf{boundp} является истиной, если динамическая (специальная) переменная с
именем \emph{symbol} имеет значение, иначе возвращает {\false}.

Смотрите также \cdf{set} и \cdf{makunbound}.
\end{defun}

\begin{defun}[Функция]
fboundp symbol

\cdf{fboundp} является истиной, если символ имеет глобальное
определение функции.  Следует отметить, что \cdf{fboundp} является
истиной, если символ указывает на оператор или
макрос. \cdf{macro-function} и \cdf{special-operator-p} могут
использоваться для проверки таких случаев.

Смотрите также \cdf{symbol-function} и \cdf{fmakunbound}.

Функция \cdf{fboundp}
принимает любое имя функции (символ или список,
\emph{car} элементы которого является \cdf{setf}---смотрите раздел~\ref{FUNCTION-NAME-SECTION})
Так можно записать \cd{(fboundp '(setf cadr))} для определения существует ли
функция \cdf{setf} для \cdf{cadr}.
\end{defun}

\begin{defun}[Функция]
special-operator-p symbol

Функция \cdf{special-operator-p} принимает символ. Если символ указывает на
оператор, тогда возвращается значение не-{\false}, иначе возвращается {\false}.
Возвращённое не-{\nil} значение является функцией,
которая может быть использована для интерпретации (вычисления) специальной
формы. FIXME

Возможно также то, что \emph{обе} функции \cdf{special-operator-p} и
\cdf{macro-function} будут истинными для одного и того же символа. Это потому,
что реализация может содержать любой макрос как оператор для увеличения скорости.
С другой стороны, определение макроса должно быть доступно для использования
программами, которые понимают только стандартные операторы,
перечисленные в таблице~\ref{SPECIAL-FORM-TABLE}. FIXME
\end{defun}

\subsection{Присваивание}

Следующая функциональность позволяет изменять значение переменной (если быть
точнее, значению соединённому с текущим связыванием переменной).
Такое изменение отличается от создания нового связывания.
Конструкции для создания новых связываний переменных описаны в
разделе~\ref{VAR-BINDING-SECTION}.

\begin{defspec}
setq {var form}*

Оператор \cd{(setq \emph{var1} \emph{form1} \emph{var2} \emph{form2}
  ...)} является <<конструкцией присваивания простых переменных>> Lisp'а.
Вычисляется первая форма \emph{form1} и результат сохраняется в переменной
\emph{var1}, затем вычисляется \emph{form2} и результат сохраняется в переменной
\emph{var2}, и так далее.
Переменные, конечно же, представлены символами, и интерпретируются как ссылки к
динамическим или статическим переменным в соответствии с обычными правилами.
Таким образов \cdf{setq} может быть использована для присваивания как
лексических, так и специальных переменных.

\cdf{setq} возвращает последнее присваиваемое значение, другими словами,
результат вычисления последнего аргумента.
В другом случае, форма \cd{(setq)} является корректной и возвращает {\false}.
В форме должно быть чётное количество форм аргументов.
Например, в 
\begin{lisp}
(setq x (+ 3 2 1) y (cons x nil))
\end{lisp}
\cd{x} устанавливается в \cd{6}, \cd{y} в \cd{(6)}, и \cdf{setq} возвращает
\cd{(6)}. Следует отметить, что первое присваивание выполняется перед тем, как
будет выполнено второе, тем самым каждое следующее присваивание может
использовать значение предыдущих.

Смотрите также описание \cdf{setf}, <<общая конструкция
присваивания>> Common Lisp'а, которая позволяет присваивать значения переменным,
элементам массива, и другим местам.

Некоторые программисты выбирают путь отречения от \cdf{setq}, и всегда используют
\cdf{setf}. Другие используют \cdf{setq} для простых переменных и \cdf{setf} для
всех остальных.

Если любая \emph{var} ссылается не на обычную переменную, а на связывание
сделанное с помощью \cdf{symbol-macrolet}, тогда \emph{var} обрабатывается как
если \cdf{psetf} использовалось вместо \cdf{setq}.
\end{defspec}

\begin{defmac}
psetq {var form}*

Форма \cdf{psetq} похожа на форму \cdf{setq} за исключением того, что выполняет
присваивание параллельно. Сначала выполняются все формы, а затем переменные
получают значения этих форм. Значение формы \cdf{psetq} {\false}.
Например:
\begin{lisp}
(setq a 1) \\
(setq b 2) \\
(psetq a b  b a) \\
a \EV\ 2 \\
b \EV\ 1
\end{lisp}
В этом примере, значения \cd{a} и \cd{b} меняются местами с помощью
параллельного присваивания.
(Если несколько переменных должны быть присвоены параллельно в рамках цикла,
целесообразнее использовать конструкцию \cdf{do}.)

Смотрите также описание \cdf{psetf}, <<общая конструкция параллельного
присваивания>> Common Lisp'а, которая позволяет присваивать переменным,
элементам массива, и другим местам.

Если любая \emph{var} ссылается не на обычную переменную, а на связывание
сделанное с помощью \cdf{symbol-macrolet}, тогда \emph{var} обрабатывается как
если \cdf{psetf} использовалось вместо \cdf{psetq}.
\end{defmac}

\begin{defun}[Функция]
set symbol value

\cdf{set} позволяет изменить значение динамической (специальной) переменной.
\cdf{set} устанавливает динамической переменной с именем \emph{symbol} значение
\emph{value}.

Изменено будет только значение текущего динамического связывания. Если такого
связывания нет, будет изменено наиболее глобальное значение.
Например,
\begin{lisp}
(set (if (eq a b) 'c 'd) 'foo)
\end{lisp}
установит значение \cd{с} в \cd{foo} или \cdf{do*} в \cd{foo}, в зависимости от
результата проверки \cd{(eq~a~b)}.

\cdf{set} в качестве результата возвращает значение \emph{value}.

\cdf{set} не может изменить значение локальной (лексически связанной)
переменной.
Обычно для изменения переменных (лексических или динамических) используется
оператор \cdf{setq}.
\cdf{set} полезна в частности для реализации интерпретаторов языков встроенных в
Lisp.
Смотрите также \cdf{progv}, конструкция, которая создаёт связывания, а не
присваивания динамических переменных.
\end{defun}

\begin{defun}[Функция]
makunbound symbol \\
fmakunbound symbol

\cdf{makunbound} упраздняет связывание динамической (специальной) переменной
заданной символом \emph{symbol} (упраздняет значение). \cdf{fmakunbound}
аналогично упраздняет связь символа с глобальным определением функции.
Например:
\begin{lisp}
(setq a 1) \\
a \EV\ 1 \\
(makunbound 'a) \\
a \EV\ \textrm{ошибка} \\
\\
(defun foo (x) (+ x 1)) \\
(foo 4) \EV\ 5 \\
(fmakunbound 'foo) \\
(foo 4) \EV\ \textrm{ошибка}
\end{lisp}
Обе функции возвращают символ \emph{symbol} в качестве результата.

Функция \cdf{fmakunbound}
принимает любое имя функции (символ или список,
\emph{car} элементы которого является \cdf{setf}---смотрите раздел~\ref{FUNCTION-NAME-SECTION})
Так можно записать \cd{(fmakunbound '(setf cadr))} для удаления функции
\cdf{setf} для \cdf{cadr}.
\end{defun}

\section{Обобщённые переменные}
\label{SETF-SECTION}

В Lisp'е, переменная может запомнить одну часть данных, а точнее, один Lisp
объект. 
Главные операции над переменной это получить её значение и задать ей другое
значение. Их часто называют операциями \emph{доступа} и
\emph{изменения}. Концепция переменных с именем в виде символа может быть
обобщена до того, что любое место может сохранять в себе части данных вне
зависимости от того, как данное место именуется. Примерами таких мест хранения
являются \emph{car} и \emph{cdr} элементы cons-ячейки, элементы массива, и
компоненты структуры.

Для каждого вида обобщённых переменных существуют две функции, которые
реализуют операции \emph{доступа} и \emph{изменения}.  Для переменных
это имя переменной для доступа, а для изменения оператор \cdf{setq}.
Функция \cdf{car} получает доступ к \emph{car} элементу cons-ячейки, а
функция \cdf{rplaca} изменяет этот элемент ячейки.  Функция
\cdf{symbol-value} получает динамическое значение переменной
именованной некоторым символом, а функция \cdf{set} изменяет эту
переменную.

Вместо того, чтобы думать о двух разных функциях, которые соответственно
получают доступ и изменяют некоторое место хранения в зависимости от своих
аргументов, мы может думать просто о вызове функции доступа с некоторыми
аргументами, как о \emph{имени} данного места хранения. Таким образом, просто
\cd{x} является именем места хранения (переменной), \cd{(car x)} имя для
\emph{car} элементы для некоторой cons-ячейки (которая в свою очередь именуется
символом \cd{x}). Теперь вместо того, чтобы запоминать по две функции для
каждого вида обобщённых переменных (например \cdf{rplaca} для \cdf{car}), мы
адаптировали единый синтаксис для изменения некоторого места хранения с помощью
макроса \cdf{setf}. Это аналогично способу, где мы используем специальную
форму \cdf{setq} для преобразования имени переменной (которая является также
формой для доступа к ней) в форму, которая изменяет переменную
FIXME. Эта универсальной отображения в следующей таблице.

\begin{flushleft}
\begin{tabular*}{\textwidth}{@{}l@{\extracolsep{\fill}}ll@{}}
\textrm{Функция доступа}&\textrm{Функция изменения}&\textrm{Изменения с помощью \cdf{setf}} \\
\hlinesp
\cd{x}&\cd{(setq x datum)}&\cd{(setf x datum)} \\
\cd{(car x)}&\cd{(rplaca x datum)}&\cd{(setf (car x) datum)} \\
\cd{(symbol-value x)}&\cd{(set x datum)}&\cd{(setf (symbol-value x) datum)} \\
\hline
\end{tabular*}
\end{flushleft}
\cdf{setf} это макрос, который анализирует форму доступа, и производит вызов
соответствующей функции изменения.

С появление в Common Lisp'е \cdf{setf}, необходимость в \cdf{setq}, \cdf{rplaca}
и \cdf{set} отпала. Они оставлены в Common Lisp из-за их исторической важности в
Lisp'е.
Однако, большинство других функций изменения (например \cdf{putprop}, функция
изменения для \cdf{get}) были устранены из Common Lisp'а в расчёте на то, что
везде на их месте будет использоваться \cdf{setf}.

\begin{defmac}
setf {place newvalue}*

\cd{(setf \emph{place} \emph{newvalue})} принимает форму \emph{place}, которая
при своём вычислении получает доступ к объекту в некотором месте хранения и
<<инвертирует>> эту форму в соответствующую форму \emph{изменения}.
Таким образом вызов макроса \cdf{setf} разворачивается в форму изменения, 
которая сохраняет результат вычисления формы \emph{newvalue} в место хранения,
на которое ссылалась форма доступа.

Если пар \emph{place}-\emph{newvalue} указано более одной, эти пары
обрабатываются последовательно. Таким образом:
\begin{lisp}
(setf \emph{place1} \emph{newvalue1} \\
~~~~~~\emph{place2} \emph{newvalue2}) \\
~~~~~~... \\
~~~~~~\emph{placen} \emph{newvaluen})
\end{lisp}
эквивалентно
\begin{lisp}
(setf \emph{place1} \emph{newvalue1} \\
~~~~~~\emph{place2} \emph{newvalue2}) \\
~~~~~~... \\
~~~~~~\emph{placen} \emph{newvaluen})
\end{lisp}
Следует отметить, что запись \cd{(setf)} является корректной и возвращает {\nil}.

Форма \emph{place} может быть одной из следующих:
\begin{itemize}

\item
Имя переменной (лексической и динамической).

\item
Формой вызова функции, у которой первый элемент принадлежит множеству указанному
в следующей таблице:

\begin{flushleft}
\begin{tabular}{@{}llll@{}}
\cdf{aref}&\cdf{car}&\cdf{svref}& \\
\cdf{nth}&\cdf{cdr}&\cdf{get}& \\
\cdf{elt}&\cdf{caar}&\cdf{getf}&\cdf{symbol-value} \\
\cdf{rest}&\cdf{cadr}&\cdf{gethash}&\cdf{symbol-function} \\
\cdf{first}&\cdf{cdar}&\cdf{documentation}&\cdf{symbol-plist} \\
\cdf{second}&\cdf{cddr}&\cdf{fill-pointer}&\cdf{macro-function} \\
\cdf{third}&\cdf{caaar}&\cdf{caaaar}&\cdf{cdaaar} \\
\cdf{fourth}&\cdf{caadr}&\cdf{caaadr}&\cdf{cdaadr} \\
\cdf{fifth}&\cdf{cadar}&\cdf{caadar}&\cdf{cdadar} \\
\cdf{sixth}&\cdf{caddr}&\cdf{caaddr}&\cdf{cdaddr} \\
\cdf{seventh}&\cdf{cdaar}&\cdf{cadaar}&\cdf{cddaar} \\
\cdf{eighth}&\cdf{cdadr}&\cdf{cadadr}&\cdf{cddadr} \\
\cdf{ninth}&\cdf{cddar}&\cdf{caddar}&\cdf{cdddar} \\
\cdf{tenth}&\cdf{cdddr}&\cdf{cadddr}&\cdf{cddddr} \\
\cdf{row-major-aref}&\cdf{compiler-macro-function}& & 
\end{tabular}
\end{flushleft}

Это правило применяется только тогда, когда имя функции ссылается глобальное
определение функции, и не ссылается на локальное определение или макрос.

\item
Формой вызова функции, у которой первый элемент является именем
функции-селектора созданной с помощью \cdf{defstruct}.

Это правило применяется только тогда, когда имя функции ссылается глобальное
определение функции, и не ссылается на локальное определение или макрос.

\item
Формой вызова функции, у которой первый элемент является именем одной из
следующих функции. В этом случае новое значение, указанного ниже типа, замещает
значение в указанном <<месте>> (которое не является обобщённой переменной в обычном
понимании этого термина).

\begin{flushleft}
\leavevmode
\begin{tabular}{@{}ll@{}}
Имя функции&Требуемый тип\\
\hlinesp
\cdf{bit}&\cdf{bit} \\
\cdf{sbit}&\cdf{bit} \\
\cdf{subseq}&\cdf{sequence} \\
\hline
\end{tabular}
\end{flushleft}

\begin{newer}
X3J13 voted in March 1989 \issue{CHARACTER-PROPOSAL}
to eliminate the type \cdf{string-char} and to redefine
\cdf{string} to be the union of one or more specialized vector
types, the types of whose elements are subtypes of the type \cdf{character}.
In the preceding table, the type \cdf{string-char} should be replaced
by some such phrase as ``the element-type of the argument vector.''
\end{newer}

Это правило применяется только когда имя функции ссылается на глобальное, а не
локальное определение функции.

В случае использования \cdf{subseq}, новое значение должно быть
последовательностью, элементы которой могут быть вставлены в последовательность
из аргумента для \cdf{subseq}.
Если длина нового значения не совпадает с длиной замещаемой последовательности,
тогда используется наименьшая указанная длина, как и для функции \cdf{replace}.

\item
Форма вызова функции, первый элемент которой является именем одной из
следующих функций при условии, что указанный аргумент этой функции в свою
очередь является формой \emph{place}. 
В этом случае новое значение \emph{place} сохраняется в то место, доступ к
которому был получен с помощью функци.

\begin{flushleft}
\begin{tabular}{@{}lll@{}}
Имя функции&Аргумент являющийся \emph{местом}&Функция изменения \\
\hlinesp
\cdf{ldb}&second&\cdf{dpb} \\
\cdf{mask-field}&second&\cdf{deposit-field} \\
\hline
\end{tabular}
\end{flushleft}

Это правило применяется только тогда, когда имя функции ссылается глобальное
определение функции, и не ссылается на локальное определение или макрос.

\item
Форма декларации типа \cdf{the}, в таком случае декларация переносится на форму
\emph{newvalue}, и анализируется результирующая \cdf{setf} форма. Например:
\begin{lisp}
(setf (the integer (cadr x)) (+ y 3))
\end{lisp}
будет обработана как
\begin{lisp}
(setf (cadr x) (the integer (+ y 3)))
\end{lisp}

\item 
Вызов функции \cdf{apply}, в которой первый аргумент является функцией, которая
может является \emph{местом} для \cdf{setf}.
То есть, \cd{(function \emph{name})}, где \emph{name} является именем функции,
вызов которой может рассматриваться как места для присваивания с помощью \cdf{setf}.

Использование \cdf{setf} с \cdf{apply} выглядит как:
\begin{lisp}
(setf (apply \#'\emph{name} \emph{x1} \emph{x2} ... \emph{xn} \emph{rest}) \emph{x0})
\end{lisp}
\cdf{setf} метод для функции \emph{name} должен быть такой
\begin{lisp}
(setf (\emph{name} \emph{z1} \emph{z2} ... \emph{zm}) \emph{z0})
\end{lisp}
чтобы разворачивается в форму сохранения значения
\begin{lisp}
(\emph{storefn} \emph{zi${}_1$} \emph{zi${}_2$} ... \emph{zi${}_k$} \emph{zm})
\end{lisp}
That is, it must expand into a function call such that all arguments but
the last may be any permutation or subset of the new value \emph{z0} and
the arguments of the access form, but the \emph{last} argument of the storing
call must be the same as the last argument of the access call.
See \cdf{define-setf-method} for more details on accessing
and storing forms.

Смотрите \cdf{define-setf-method} для подробного описания форм для доступа и
сохранения значений.

Таким образом форма \cdf{setf}-для-\cdf{apply}, показанная выше, разворачивается в
\begin{lisp}
(apply \#'\emph{storefn} \emph{xi${}_1$} \emph{xi${}_2$} ... \emph{xi${}_k$} \emph{rest})
\end{lisp}
В качестве примера, предположим, что переменная \cdf{indexes} содержит список
индексов для многомерного массива \emph{foo}, ранг которого известен только во
время выполнения. Для доступа к элементам массива можно использовать
\begin{lisp}
(apply \#'aref foo indexes)
\end{lisp}
и для изменения элемента на значение \cdf{newvalue} можно использовать
\begin{lisp}
(setf (apply \#'aref foo indexes) newvalue)
\end{lisp}

Это правило применяется только тогда, когда имя функции ссылается на глобальное
определение функции, и не ссылается на локальное определение или макрос.

\item 
Макровызов, в случае чего \cdf{setf} разворачивает макровызов и затем
анализирует полученную форму.

Этот шаг использует \cdf{macroexpand-1}, но не \cdf{macroexpand}.  Это
позволяет пременить какое-либо из предшествующих правил.

\item 
Любая форма, для которой было сделано определение с помощью \cdf{defsetf} или
\cdf{define-setf-method}.

Это правило применяется только тогда, когда имя функции ссылается глобальное
определение функции, и не ссылается на локальное определение или макрос.

\item
Любой другой список, первый элемент которого является символом (вызов некоторой
функции \emph{f}). В этом случае, вызов \cdf{setf} разворачивается в вызов
функции с именем в виде списка \cd{(setf~\emph{f\/})} (смотрите
раздел~\ref{FUNCTION-NAME-SECTION}). При этом первый передаваемый аргумент
является новым значением, а остальные --- теми, которые были указаны в
\emph{place}. Раскрытие осуществляется вне зависимости от того, что и \emph{f}
и \cd{(setf \emph{f\/})} определены как функции локально, глобально или не
определены вовсе. Например,

\begin{lisp}
(setf (\emph{f\/} \emph{arg1} \emph{arg2} ...) \emph{newvalue})
\end{lisp}
раскрывается в форму эквивалентную следующей
\begin{lisp}
(let ((\#:temp1 \emph{arg1})~~~~~;\textrm{Упорядоченное слева направо вычисление} \\*
~~~~~~(\#:temp2 \emph{arg2}) \\*
~~~~~~... \\*
~~~~~~(\#:temp0 newvalue)) \\*
~~(funcall (function (setf \emph{f\/})) \\*
~~~~~~~~~~~\#:temp0 \\*
~~~~~~~~~~~\#:temp1 \\*
~~~~~~~~~~~\#:temp2 ...))
\end{lisp}
По соглашению, любая функция с именем \cd{(setf \emph{f\/})} в качестве
единственного значения должна возвращать свой первый аргумент, для следования
спецификации функции \cdf{setf} о возврате аргумента \emph{newvalue}.

\item
Ссылка на переменную, которая ссылается на определение символьного макроса,
созданного с помощью \cdf{macrolet}. В этом случае \cdf{setf} раскрывается
данную ссылку и затем анализирует результат.
\end{itemize}

\cdf{setf} тщательно сохраняет обычный порядок выполнения подформ слева
направо.
С другой стороны, точное раскрытие для какой-нибудь частной формы не
гарантируется и может зависеть от реализации. Все, что гарантируется, это 
раскрытие \cdf{setf} формы в некоторую функцию изменения, используемую данной
реализацией, и выполнение подформ слева направо.

Конечным результатом вычисления формы \cdf{setf} является значение
\emph{newvalue}. Таким образом \cd{(setf (car x) y)} раскрывается не прямо в
\cd{(rplaca x y)}, а в что-то вроде
\begin{lisp}
(let ((G1 x) (G2 y)) (rplaca G1 G2) G2)
\end{lisp}
точное раскрытие зависит от реализации.

Пользователь может определить новое раскрытие для \cdf{setf} используя
\cdf{defsetf}.

\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{setf} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.

A proposal was submitted to X3J13 in September 1989
to add a \cdf{setf} method for \cdf{values} so that one could
in fact write, for example,
\begin{lisp}
(setf (values quotient remainder) \\
~~~~~~(truncate linewidth tabstop))
\end{lisp}
but unless this proposal is accepted users will have to
define a \cdf{setf} method for \cdf{values} themselves (not a difficult task).
\end{newer}
\end{defmac}

\begin{defmac}
psetf {place newvalue}*

\cdf{psetf} похожа на \cdf{setf} за исключением того, что если указано более одной 
пары
\emph{place}-\emph{newvalue} , то присваивание местам новых значений 
происходит параллельно. Если говорить точнее, то все подформы, которые должны 
быть вычислены, вычисляются слева направо. После выполнения всех вычислений,
выполняются все присваивания в неопределённом порядке.
(Неопределённый порядок влияет на поведение в случае, если более одной формы
\emph{place} ссылаются на одно и то же место.)
\cdf{psetf} всегда возвращает {\false}.

\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{psetf} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.
\end{newer}
\end{defmac}

\begin{defmac}
shiftf {place}+ newvalue

Каждая форма \emph{place} может быть любой обобщённой переменной, как для
\cdf{setf}. 
В форме \cd{(shiftf \emph{place1} \emph{place2} ... \emph{placen}
  \emph{newvalue})}, вычисляются и сохраняются значения с \emph{place1} по
\emph{placen} и вычисляется \emph{newvalue}, как значение с номером $\emph{n}+1$.
Значения с 2-го по $\emph{n}+1$ сохраняются в интервале с \emph{place1} по
\emph{placen} и возвращается 1-ое значение (оригинальное значение \emph{place1}).
Механизм работает как сдвиг регистров. \emph{newvalue} сдвигается с правой
стороны, все значения сдвигаются влево на одну позицию, и возвращается
сдвигаемое самое левое значение \emph{place1}. Например:
\begin{lisp}
(setq x (list 'a 'b 'c)) \EV\ (a b c) \\
 \\
(shiftf (cadr x) 'z) \EV\ b \\
~~~\textrm{and now} x \EV\ (a z c) \\
 \\
(shiftf (cadr x) (cddr x) 'q) \EV\ z \\
~~~\textrm{and now} x \EV\ (a (c) . q)
\end{lisp}
Эффект от \cd{(shiftf \emph{place1} \emph{place2} ... \emph{placen}
  \emph{newvalue})} эквивалентен
\begin{lisp}
(let ((\emph{var1} \emph{place1}) \\
~~~~~~(\emph{var2} \emph{place2}) \\
~~~~~~... \\
~~~~~~(\emph{varn} \emph{placen})) \\
~~(setf \emph{place1} \emph{var2}) \\
~~(setf \emph{place2} \emph{var3}) \\
~~... \\
~~(setf \emph{placen} \emph{newvalue}) \\
~~\emph{var1})
\end{lisp}
за исключением того, что последний вариант выполняет все подформы для каждого
\emph{place} дважды, тогда как \cdf{shiftf} выполняет только единожды.
Например:
\begin{lisp}
(setq n 0) \\
(setq x '(a b c d)) \\
(shiftf (nth (setq n (+ n 1)) x) 'z) \EV\ b \\
~~~\textrm{теперь} x \EV\ (a z c d) \\[4pt]
\emph{but} \\[4pt]
(setq n 0) \\
(setq x '(a b c d)) \\
(prog1 (nth (setq n (+ n 1)) x) \\*
~~~~~~~(setf (nth (setq n (+ n 1)) x) 'z)) \EV\ b \\
~~~\textrm{и теперь} x \EV\ (a b z d)
\end{lisp}
Более того, для заданных форм \emph{place} \cdf{shiftf} может быть более
производительной, чем версия с \cdf{prog1}.


\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{shiftf} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.
\end{newer}

\beforenoterule
\begin{rationale}
\cdf{shiftf} and \cdf{rotatef} have been included in Common Lisp
as generalizations of two-argument versions formerly called \cdf{swapf}
and \cdf{exchf}.  The two-argument versions have been found to be
very useful, but the names were easily confused.  The generalization
to many argument forms and the change of names were both inspired
by the work of Suzuki \cite{SUZUKI-POINTER-ROTATION},
which indicates that use of these primitives can make certain complex
pointer-manipulation programs clearer and easier to prove correct.
\end{rationale}
\afternoterule
\end{defmac}

\begin{defmac}
rotatef {place}*

Каждая \emph{place} может быть обобщённой переменной, как для \cdf{setf}.
В форме \cd{(rotatef \emph{place1} \emph{place2} ... \emph{placen})},
вычисляются и сохраняются значения c \emph{place1} по \emph{placen}.
Механизм действует как круговой сдвиг регистров влево, и значение
\emph{place1} сдвигается в конец на \emph{placen}.
Следует отметить, что \cd{(rotatef \emph{place1} \emph{place2})} меняет значения
между \emph{place1} и \emph{place2}.

Эффект от использования \cd{(rotatef \emph{place1} \emph{place2}
  ... \emph{placen})} эквивалентен
\begin{lisp}
(psetf \emph{place1} \emph{place2} \\
~~~~~~~\emph{place2} \emph{place3} \\
~~~~~~~... \\
~~~~~~~\emph{placen} \emph{place1})
\end{lisp}
за исключением того, что в последнем вычисление форм происходит дважды, тогда как \cdf{rotatef} выполняет только единожды.
Более того, для заданных форм \emph{place} \cdf{rotatef} может быть более
производительной, чем версия с \cdf{prog1}.

\cdf{rotatef} всегда возвращает {\false}.

\begin{newer}
X3J13 voted in June 1989 \issue{SETF-MULTIPLE-STORE-VARIABLES}
to extend the specification of \cdf{rotatef} to allow a \emph{place}
whose \cdf{setf} method has more than one store variable (see \cdf{define-setf-method}).
In such a case as many values are accepted from the \emph{newvalue} form
as there are store variables; extra values are ignored
and missing values default to \cdf{nil},
as is usual in situations involving multiple values.
\end{newer}
\end{defmac}

Другие макросы, которые управляют обобщёнными переменными, включают 
\cdf{getf}, \cdf{remf},
\cdf{incf}, \cdf{decf}, \cdf{push}, \cdf{pop},
\cdf{assert}, \cdf{ctypecase} и \cdf{ccase}.

Макросы, которые управляют обобщёнными переменными, должны гарантировать
<<явную>> семантику: подформы обобщённых переменных вычисляются точно столько
раз, сколько они встречаются в выражении, и в том же порядке, в котором
встречаются.

В ссылках на обобщённые переменные, как в \cdf{shiftf}, \cdf{incf}, \cdf{push} и
\cdf{setf} или \cdf{ldb}, обобщённые переменные считываются и записываются в
одну и ту же ссылку. Сохранение порядка выполнения исходной программы и
количества выполнений чрезвычайно важно.

В качестве примера этих семантических правил, в ссылке на обобщённую переменную
\cd{(setf \emph{reference} \emph{value})} форма \emph{value} должны быть
вычислена \emph{после} всех подформ данной ссылки, потому что форма \emph{value}
стоит правее всех.

The expansion of these macros must consist of code that follows these
rules or has the same effect as such code.  This is accomplished by
introducing temporary variables bound to the subforms of the reference.
As an optimization in the implementation,
temporary variables may be eliminated whenever it
can be proved that removing them has no effect on the semantics of the program.
For example, a constant need never be saved in a temporary variable.
A variable, or for that matter any form that does not have side effects, need not be
saved in a temporary variable if it can be proved that its value will
not change within the scope of the generalized-variable reference.

Common Lisp provides built-in facilities to take care of
these semantic complications and optimizations.  Since the required
semantics can be guaranteed by these facilities, the user does not
have to worry about writing correct code for them, especially in
complex cases.  Even experts can become confused and make mistakes
while writing this sort of code.

\begin{newer}
X3J13 voted in March 1988 \issue{PUSH-EVALUATION-ORDER}
to clarify the preceding discussion about the order of evaluation of
subforms in calls to \cdf{setf} and related macros.
The general intent is clear: evaluation
proceeds from left to right whenever possible. However, the left-to-right rule does not
remove the obligation on writers of macros and \cdf{define-setf-method} to work
to ensure left-to-right order of evaluation.

Let it be emphasized that, in the following discussion,
a \emph{form} is something whose syntactic use is such that it will
be evaluated.  A \emph{subform} means a form that is nested inside another form,
not merely any Lisp object nested inside a form regardless of syntactic context. 

The evaluation ordering of subforms within a generalized variable
reference is determined by the order specified by the second value returned by
\cdf{get-setf-method}.  For all predefined generalized variable references
(\cdf{getf}, \cdf{ldb}), this order of evaluation is exactly left-to-right.
When a generalized
variable reference is derived from a macro expansion, this rule is applied
\emph{after} the macro is expanded to find the appropriate generalized variable
reference. 

This is intended to make it clear that if the user writes a \cdf{defmacro} or
\cdf{define-setf-method} macro that doesn't preserve left-to-right
evaluation order, the order specified in the
user's code holds.  For example, given
\begin{lisp}
(defmacro wrong-order (x y) {\Xbq}(getf ,y ,x))
\end{lisp}
then
\begin{lisp}
(push \emph{value} (wrong-order \emph{place1} \emph{place2}))
\end{lisp}
will evaluate \emph{place2} first and then \emph{place1} because that is the order they
are evaluated in the macro expansion.
 
For the macros that manipulate generalized variables (\cdf{push}, \cdf{pushnew}, \cdf{getf},
\cdf{remf}, \cdf{incf}, \cdf{decf}, \cdf{shiftf}, \cdf{rotatef},
\cdf{psetf}, \cdf{setf}, \cdf{pop}, and those defined with
\cdf{define-modify-macro}) the subforms of the macro call are evaluated exactly once
in left-to-right order, with the subforms of the generalized variable
references evaluated in the order specified above.

Each of
\cdf{push}, \cdf{pushnew}, \cdf{getf}, \cdf{remf}, \cdf{incf}, \cdf{decf},
\cdf{shiftf}, \cdf{rotatef}, \cdf{psetf}, and \cdf{pop} evaluates
all subforms before modifying any of the generalized variable locations.  Moreover,
\cdf{setf} itself,
in the case when a call on it has more than two arguments, performs its
operation on each pair in sequence.  That is, in
\begin{lisp}
(setf \emph{place1} \emph{value1} \emph{place2} \emph{value2} ...)
\end{lisp}
the subforms of \emph{place1} and \emph{value1} are evaluated, the
location specified by \emph{place1} is modified to contain the value returned by
\emph{value1}, and then the rest of the \cdf{setf} form is processed in a like manner.

For the macros \cdf{check-type}, \cdf{ctypecase}, and \cdf{ccase}, subforms of the
generalized variable reference are evaluated once per test of a generalized
variable, but they may be
evaluated again if the type check fails (in the case of \cdf{check-type}) or if none of
the cases holds (in \cdf{ctypecase} or \cdf{ccase}).

For the macro \cdf{assert}, the order of evaluation of the generalized variable
references is not specified.
\end{newer}

Another reason for building in these functions is that the
appropriate optimizations will differ from implementation to
implementation.  In some implementations most of the optimization is
performed by the compiler, while in others a simpler compiler is used and
most of the optimization is performed in the macros.  The cost of
binding a temporary variable relative to the cost of other Lisp
operations may differ greatly between one implementation
and another, and some implementations may find it
best never to remove temporary variables except in the simplest cases.

A good example of the issues involved can be seen in the following
generalized-variable reference:
\begin{lisp}
(incf (ldb byte-field variable))
\end{lisp}
This ought to expand into something like
\begin{lisp}
(setq variable \\
~~~~~~(dpb (1+ (ldb byte-field variable)) \\
~~~~~~~~~~~byte-field \\
~~~~~~~~~~~variable))
\end{lisp}
In this expansion example we have
ignored the further complexity of returning the correct
value, which is the incremented byte, not the new value of \cdf{variable}.
Note that the variable \cdf{byte-field} is evaluated twice, and the
variable \cdf{variable} is referred to three times:
once as the location in which to store a value,
and twice during the computation of that value.

Now consider this expression:
\begin{lisp}
(incf (ldb (aref byte-fields (incf i)) \\
~~~~~~~~~~~(aref (determine-words-array) i)))
\end{lisp}
It ought to expand into something like this:
\begin{lisp}
(let ((temp1 (aref byte-fields (incf i))) \\
~~~~~~(temp2 (determine-words-array))) \\
~~(setf (aref temp2 i) \\
~~~~~~~~(dpb (1+ (ldb temp1 (aref temp2 i))) \\
~~~~~~~~~~~~~temp1 \\
~~~~~~~~~~~~~(aref temp2 i))))
\end{lisp}
Again we have ignored the complexity of returning the correct value.
What is important here is that the expressions \cd{(incf i)}
and \cd{(determine-words-array)}
must not be duplicated because each may have a side effect or
be affected by side effects.

\begin{newer}
X3J13 voted in January 1989 \issue{SETF-SUB-METHODS}
to specify more precisely the order of evaluation of subforms
when \cdf{setf} is used with an access function that itself
takes a \emph{place} as an argument, for example, \cdf{ldb}, \cdf{mask-field}, and
\cdf{getf}.  (The vote also discussed the function \cdf{char-bit},
but another vote \issue{CHARACTER-PROPOSAL} removed that function
from the language.)  The \cdf{setf} methods for such accessors produce expansions
that effectively require explicit calls to \cdf{get-setf-method}.

The code produced as the macro expansion of a \cdf{setf} form that
itself admits a generalized variable as an argument must essentially
do the following major steps:
\begin{itemize}
\item It evaluates the value-producing subforms, in left-to-right order, and 
     binds the temporary variables to them; this is called \emph{binding the temporaries}.

\item It reads the value from the generalized variable, using the supplied 
     accessing form, to get the old value;  this is called \emph{doing the
     access}.  Note that this is done after all the evaluations of the 
     preceding step, including any side effects they may have.

\item It binds the store variable to a new value, and then installs this
     new value into the generalized variable using the supplied storing 
     form; this is called \emph{doing the store}.
\end{itemize}
Doing the access for a generalized variable reference is not part of
the series of evaluations that must be done in left-to-right order. 

The place-specifier forms \cdf{ldb}, \cdf{mask-field}, and \cdf{getf} admit (other)
\emph{place} specifiers as arguments. During the \cdf{setf} expansion of these forms, it 
is necessary to call \cdf{get-setf-method} to determine how the inner, 
nested generalized variable must be treated.

    In a form such as
\begin{lisp}
(setf (ldb \emph{byte-spec} \emph{place-form}) \emph{newvalue-form})
\end{lisp}
    the place referred to by the \emph{place-form} must always be both accessed 
    and updated;  note that the update is to the generalized variable 
    specified by \emph{place-form}, not to any object of type \cdf{integer}.

    Thus this call to \cdf{setf} should generate code to do the following:
\begin{itemize}
    \item Evaluate \emph{byte-spec} and bind into a temporary
    \item Bind the temporaries for \emph{place-form}
    \item Evaluate \emph{newvalue-form} and bind into the store variable
    \item Do the access to \emph{place-form}
    \item Do the store into \emph{place-form} with the given bit-field of the
          accessed integer replaced with the value in the store variable
\end{itemize}
    If the evaluation of \emph{newvalue-form} alters what is found in the 
    given \emph{place}---such as setting a different bit-field of the
    integer---then the change of the bit-field denoted by
    \emph{byte-spec} will be to that 
    altered integer, because the access step must be done after the \emph{newvalue-form}
    evaluation.  Nevertheless, the 
    evaluations required for binding the temporaries are done before the
    evaluation of the \emph{newvalue-form}, thereby preserving
    the required left-to-right evaluation order.

The treatment of \cdf{mask-field} is similar to that of \cdf{ldb}.

    In a form such as:
\begin{lisp}
(setf (getf \emph{place-form} \emph{ind-form}) \emph{newvalue-form})
\end{lisp}
    the place referred to by the \emph{place-form} must always be both accessed 
    and updated;  note that the update is to the generalized variable 
    specified by \emph{place-form}, not necessarily to the particular list
    which is the property list in question.

    Thus this call to \cdf{setf} should generate code to do the following:
\begin{itemize}
    \item Bind the temporaries for \emph{place-form} 
    \item Evaluate \emph{ind-form} and bind into a temporary
    \item Evaluate the \emph{newvalue-form} and bind into the store variable
    \item Do the access to \emph{place-form}
    \item Do the store into \emph{place-form} with a possibly new property list
       obtained by combining the results of the evaluations and the access
\end{itemize}

    If the evaluation of \emph{newvalue-form} alters what is found in the 
    given \emph{place}---such as setting a different named property in the
    list---then the change of the property denoted by \emph{ind-form} will be to that 
    altered list, because the access step is done after the \emph{newvalue-form}
    evaluation.   Nevertheless, the 
    evaluations required for binding the temporaries are done before the
    evaluation of the \emph{newvalue-form}, thereby preserving
    the required left-to-right evaluation order.

    Note that the phrase ``possibly new property list'' treats the 
    implementation of property lists as a ``black box''; it can mean that 
    the former property list is somehow destructively re-used, or it can 
    mean partial or full copying of it.  A side effect may or may not occur;
    therefore \cdf{setf} must proceed as if the resultant property list
    were a different copy
    needing to be stored back into the generalized variable.
\end{newer}

The Common Lisp facilities provided to deal with these semantic issues include:
\begin{itemize}
\item
Built-in macros such as \cdf{setf} and \cdf{push} that follow the semantic rules.

\item
The \cdf{define-modify-macro} macro, which allows new generalized-variable
manipulating macros (of a certain restricted kind) to be defined easily.
It takes care of the semantic rules automatically.

\item
The \cdf{defsetf} macro, which allows new types of generalized-variable references
to be defined easily.  It takes care of the semantic rules automatically.

\item
The \cdf{define-setf-method} macro and the \cdf{get-setf-method} function, which
provide access to the internal mechanisms when it is necessary
to define a complicated new type of generalized-variable reference
or generalized-variable-manipulating macro.
\end{itemize}

\begin{newer}
Also important are the changes that allow lexical environments to be
used in appropriate ways in \cdf{setf} methods.
\end{newer}

\begin{defmac}
define-modify-macro name lambda-list function [doc-string]

This macro defines a read-modify-write macro
named \emph{name}.  An example of such a macro is \cdf{incf}.  The first
subform of the macro will be a generalized-variable reference.
The \emph{function} is literally the function to apply to the old contents of the
generalized-variable to get the new contents; it is not evaluated.
\emph{lambda-list} describes
the remaining arguments for the \emph{function}; these arguments come from
the remaining subforms of the macro after the generalized-variable reference.
\emph{lambda-list} may contain \cd{\&optional} and \cd{\&rest} markers.
(The \cd{\&key} marker is not permitted here; \cd{\&rest} suffices for the purposes
of \cdf{define-modify-macro}.)
\emph{doc-string} is documentation for the macro \emph{name} being defined.

The expansion of a \cdf{define-modify-macro} is equivalent to the following, except
that it generates code that follows the semantic rules outlined above.
\begin{lisp}
(defmacro \emph{name} (\emph{reference} . \emph{lambda-list}) \\
~~\emph{doc-string} \\
~~{\Xbq}(setf ,\emph{reference} \\
~~~~~~~~~(\emph{function} ,\emph{reference} ,\emph{arg1} ,\emph{arg2} ...)))
\end{lisp}
where \emph{arg1}, \emph{arg2}, ..., are the parameters appearing in \emph{lambda-list};
appropriate provision is made for a \cd{\&rest} parameter.

As an example, \cdf{incf} could have been defined by:
\begin{lisp}
(define-modify-macro incf (\&optional (delta 1)) +)
\end{lisp}

An example of a possibly useful macro not predefined in Common Lisp is
\begin{lisp}
(define-modify-macro unionf (other-set \&rest keywords) union)
\end{lisp}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to specify that \cdf{define-modify-macro} creates macros that
take \cd{\&environment} arguments and perform the
equivalent of correctly passing such lexical
environments to \cdf{get-setf-method} in order to correctly maintain 
lexical references.
\end{newer}
\end{defmac}

\begin{defmac}
defsetf access-fn {update-fn [doc-string] | lambda-list (store-variable) <{declaration}* | doc-string> {form}*}

This defines how to \cdf{setf} a generalized-variable reference
of the form \cd{(\emph{access-fn} ...)}.  The value of a generalized-variable
reference can always be obtained simply by evaluating it, so \emph{access-fn}
should be the name of a function or a macro.

The user of \cdf{defsetf} provides a description of how to store into the
generalized-variable reference and return the value that was stored (because
\cdf{setf} is defined to return this value).  The implementation
of \cdf{defsetf} takes care of
ensuring that subforms of the reference are evaluated exactly once and
in the proper left-to-right order.  In order to do this,
\cdf{defsetf} requires that \emph{access-fn} be a function or a macro
that evaluates its arguments, behaving like a function.
Furthermore, a \cdf{setf} of a call on \emph{access-fn} will also evaluate
all of \emph{access-fn}'s arguments; it cannot treat any of them specially.
This means that \cdf{defsetf} cannot be used to describe how to store into
a generalized variable that is a byte, such as \cd{(ldb field reference)}.
To handle situations that do not fit the restrictions imposed by \cdf{defsetf},
use \cdf{define-setf-method}, which gives the user additional control
at the cost of increased complexity.

A \cdf{defsetf} declaration may take one of two forms.
The simple form is
\begin{lisp}
(defsetf \emph{access-fn} \emph{update-fn} \Mopt{\emph{doc-string}})
\end{lisp}
The \emph{update-fn} must name a function (or macro) that takes one more argument
than \emph{access-fn} takes.  When \cdf{setf} is given a \emph{place}
that is a call on \emph{access-fn}, it expands into
a call on \emph{update-fn} that is given all the arguments to
\emph{access-fn} and also, as its last argument, the new value
(which must be returned by \emph{update-fn} as its value).
For example, the effect of
\begin{lisp}
(defsetf symbol-value set)
\end{lisp}
is built into the Common Lisp system.
This causes the expansion
\begin{lisp}
(setf (symbol-value foo) fu) \EX\ (set foo fu)
\end{lisp}
for example.  Note that
\begin{lisp}
(defsetf car rplaca)
\end{lisp}
would be incorrect because \cdf{rplaca} does not return its last argument.

The complex form of \cdf{defsetf} looks like
\begin{lisp}
(defsetf \emph{access-fn} \emph{lambda-list} (\emph{store-variable}) . \emph{body})
\end{lisp}
and resembles \cdf{defmacro}.  The \emph{body} must
compute the expansion of a \cdf{setf} of a call on \emph{access-fn}.

The \emph{lambda-list} describes the arguments of \emph{access-fn}.  \cd{\&optional},
\cd{\&rest}, and \cd{\&key} markers are permitted in \emph{lambda-list}.
Optional arguments may
have defaults and ``supplied-p'' flags.  The \emph{store-variable} describes the
value to be stored into the generalized-variable reference.

\beforenoterule
\begin{rationale}
The \emph{store-variable} is enclosed
in parentheses to provide for an extension
to multiple store variables that would
receive multiple values from the second subform of \cdf{setf}.
The rules given below for coding \cdf{setf} methods discuss
the proper handling of multiple store variables to allow for
the possibility that this extension may be incorporated into Common Lisp
in the future.
\end{rationale}
\afternoterule

The \emph{body} forms can be written as if the variables in the \emph{lambda-list}
were bound to subforms of the call on \emph{access-fn} and the
\emph{store-variable} were bound to the second subform of \cdf{setf}.
However, this is not actually the case.  During the evaluation of the
\emph{body} forms, these variables are bound to names of temporary variables,
generated as if by \cdf{gensym} or \cdf{gentemp},
that will be bound by the
expansion of \cdf{setf} to the values of those subforms.  This binding
permits the
\emph{body} forms to be written without regard for order-of-evaluation
issues.  \cdf{defsetf} arranges for the temporary variables to be
optimized out of the final result in cases where that is possible.  In
other words, an attempt is made by \cdf{defsetf} to generate
the best code possible in a particular implementation.

Note that the code generated by the \emph{body} forms must include provision
for returning the correct value (the value of \emph{store-variable}).  This is
handled by the \emph{body} forms rather than by \cdf{defsetf} because
in many cases this value can be returned at no extra cost, by calling a
function that simultaneously stores into the generalized variable and
returns the correct value.

An example of the use of the complex form of \cdf{defsetf}:
\begin{lisp}
(defsetf subseq (sequence start \&optional end) (new-sequence) \\
~~{\Xbq}(progn (replace ,sequence ,new-sequence \\
~~~~~~~~~~~~~~~~~~~:start1 ,start :end1 ,end) \\
~~~~~~~~~~,new-sequence))
\end{lisp}

\begin{newer}
X3J13 voted in March 1988 \issue{FLET-IMPLICIT-BLOCK}
to specify that the body of the expander function defined
by the complex form of \cdf{defsetf} is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the \emph{access-fn}.
Therefore \cdf{return-from} may be used to exit from the function.
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}
to clarify that, while defining forms normally appear at top level,
it is meaningful to place them in non-top-level contexts; the complex form of
\cdf{defsetf} must define the expander function
within the enclosing lexical environment, not within the global
environment.
\end{newer}
\end{defmac}

The underlying theory by which \cdf{setf} and related macros arrange to
conform to the semantic rules given above is that from any
generalized-variable reference one may derive its ``\cdf{setf} method,''
which describes how to store into that reference and which subforms of
it are evaluated.

Given knowledge of the subforms of the reference,
it is possible to avoid evaluating them multiple times or in the wrong
order.  A \cdf{setf} method for a given access form can be expressed as
five values:
\begin{itemize}
\item
A list of \emph{temporary variables}

\item
A list of \emph{value forms} (subforms of the given form)
to whose values the temporary variables are to be bound

\item
A second list of temporary variables, called \emph{store variables}

\item
A \emph{storing form}

\item
An \emph{accessing form}
\end{itemize}

The temporary variables will be bound to the values of
the value forms as if by \cdf{let*}; that is, the
value forms will be evaluated in the order given
and may refer to the values of earlier value forms
by using the corresponding variables.

The store variables are to be bound to the values of the \emph{newvalue} form,
that is, the values to be
stored into the generalized variable.  In almost all cases only a
single value is to be stored, and there is only one store variable.

The storing form and the accessing form may contain references to
the temporary variables (and also, in the case of the storing form,
to the store variables).  The accessing form returns the value of the
generalized variable.  The storing form modifies the value of the
generalized variable and guarantees to return the values of the
store variables as
its values; these are the correct values for \cdf{setf} to
return.  (Again, in most cases there is a single store variable
and thus a single value to be returned.)
The value returned by the accessing form is, of course,
affected by execution of the storing form, but either of these
forms may be evaluated any number of times and therefore should be
free of side effects (other than the storing action of the storing form).

The temporary variables and the store variables are generated names,
as if by \cdf{gensym} or \cdf{gentemp},
so that there is never any problem of name clashes among them, or
between them and other variables in the program.  This is necessary to
make the special operators that do more than one \cdf{setf} in parallel work
properly; these are \cdf{psetf}, \cdf{shiftf}, and \cdf{rotatef}.  Computation
of the \cdf{setf} method must always create new variable names; it may not return
the same ones every time.

Some examples of \cdf{setf} methods for particular forms:
\begin{itemize}
\item
For a variable \cdf{x}:
\begin{lisp}
() \\*
() \\*
(g0001) \\
(setq x g0001) \\*
x
\end{lisp}

\item
For \cd{(car \emph{exp})}:
\begin{lisp}
(g0002) \\*
(\emph{exp}) \\*
(g0003)  \\
(progn (rplaca g0002 g0003) g0003) \\*
(car g0002)
\end{lisp}

\item
For \cd{(subseq \emph{seq} \emph{s} \emph{e})}:
\begin{lisp}
(g0004 g0005 g0006) \\*
(\emph{seq} \emph{s} \emph{e}) \\*
(g0007) \\
(progn (replace g0004 g0007 :start1 g0005 :end1 g0006) \\*
~~~~~~~g0007) \\*
(subseq g0004 g0005 g0006)
\end{lisp}
\end{itemize}

\begin{defmac}
define-setf-method access-fn lambda-list <{declaration}* | doc-string> {form}*

This defines how
to \cdf{setf} a generalized-variable reference that is of the form
\cd{(\emph{access-fn}...)}.  The value of a generalized-variable reference can
always be obtained simply by evaluating it, so \emph{access-fn} should be the
name of a function or a macro.

The \emph{lambda-list} describes the subforms of the generalized-variable
reference, as with \cdf{defmacro}.  The result of evaluating the
\emph{forms} in the body must be five values representing
the \cdf{setf} method, as described
above.  Note that \cdf{define-setf-method} differs from the complex form of
\cdf{defsetf} in that while the body is being executed the variables in
\emph{lambda-list} are bound to parts of the generalized-variable reference,
not to temporary variables that will be bound to the values of such parts.
In addition, \cdf{define-setf-method} does not have \cdf{defsetf}'s
restriction that \emph{access-fn} must be a function or a function-like
macro; an arbitrary \cdf{defmacro} destructuring pattern is permitted in
\emph{lambda-list}.

By definition there are no good small examples of \cdf{define-setf-method}
because the easy cases can all be handled by \cdf{defsetf}.
A typical use is to define the \cdf{setf} method for \cdf{ldb}:
\begin{obsolete}
\begin{lisp}
;;; SETF method for the form (LDB bytespec int). \\*
;;; Recall that the int form must itself be suitable for SETF. \\
(define-setf-method ldb (bytespec int) \\*
~~(multiple-value-bind (temps vals stores \\*
~~~~~~~~~~~~~~~~~~~~~~~~store-form access-form) \\*
~~~~~~(get-setf-method int)~~~~~~~~~;Get SETF method for int \\
~~~~(let ((btemp (gensym))~~~~~~~~~~;Temp var for byte specifier \\*
~~~~~~~~~~(store (gensym))~~~~~~~~~~;Temp var for byte to store \\*
~~~~~~~~~~(stemp (first stores)))~~~;Temp var for int to store \\
~~~~~~;; Return the SETF method for LDB as five values. \\*
~~~~~~(values (cons btemp temps)~~~~;Temporary variables \\*
~~~~~~~~~~~~~~(cons bytespec vals)~~;Value forms \\*
~~~~~~~~~~~~~~(list store)~~~~~~~~~~;Store variables \\
~~~~~~~~~~~~~~{\Xbq}(let ((,stemp (dpb ,store ,btemp ,access-form))) \\*
~~~~~~~~~~~~~~~~~,store-form \\*
~~~~~~~~~~~~~~~~~,store)~~~~~~~~~~~~~~~~~~~~~;Storing form \\*
~~~~~~~~~~~~~~{\Xbq}(ldb ,btemp ,access-form)~~~~~;Accessing form \\*
~~~~~~~~~~~~~~))))
\end{lisp}
\end{obsolete}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to specify that the \cd{\&environment} lambda-list keyword may appear in the
\emph{lambda-list} in the same manner as for \cdf{defmacro} in order
to obtain the lexical environment of the call to the \cdf{setf} macro.
The preceding example should be modified to take advantage of
this new feature.  The \cdf{setf} method must accept an \cd{\&environment}
parameter, which will receive the lexical environment of the call to \cdf{setf};
this environment must then be given to \cdf{get-setf-method} in order
that it may correctly use any locally bound \cdf{setf} method that
might be applicable to the \emph{place} form that appears as the second
argument to \cdf{ldb} in the call to \cdf{setf}.

\begin{lisp}
;;; SETF method for the form (LDB bytespec int). \\*
;;; Recall that the int form must itself be suitable for SETF. \\*
;;; Note the use of an \&environment parameter to receive the \\*
;;; lexical environment of the call for use with GET-SETF-METHOD. \\*
(define-setf-method ldb (bytespec int \&environment env) \\*
~~(multiple-value-bind (temps vals stores \\*
~~~~~~~~~~~~~~~~~~~~~~~~store-form access-form) \\*
~~~~~~(get-setf-method int env)~~~~~;Get SETF method for int \\
~~~~(let ((btemp (gensym))~~~~~~~~~~;Temp var for byte specifier \\*
~~~~~~~~~~(store (gensym))~~~~~~~~~~;Temp var for byte to store \\*
~~~~~~~~~~(stemp (first stores)))~~~;Temp var for int to store \\
~~~~~~;; Return the SETF method for LDB as five values. \\*
~~~~~~(values (cons btemp temps)~~~~;Temporary variables \\*
~~~~~~~~~~~~~~(cons bytespec vals)~~;Value forms \\*
~~~~~~~~~~~~~~(list store)~~~~~~~~~~;Store variables \\
~~~~~~~~~~~~~~{\Xbq}(let ((,stemp (dpb ,store ,btemp ,access-form))) \\*
~~~~~~~~~~~~~~~~~,store-form \\*
~~~~~~~~~~~~~~~~~,store)~~~~~~~~~~~~~~~~~~~~~;Storing form \\*
~~~~~~~~~~~~~~{\Xbq}(ldb ,btemp ,access-form)~~~~~;Accessing form \\*
~~~~~~~~~~~~~~))))
\end{lisp}
\end{newer}

\begin{newer}
X3J13 voted in March 1988 \issue{FLET-IMPLICIT-BLOCK}
to specify that the body of the expander function defined
by \cdf{define-setf-method} is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the \emph{access-fn}.
Therefore \cdf{return-from} may be used to exit from the function.
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}
to clarify that, while defining forms normally appear at top level,
it is meaningful to place them in non-top-level contexts;
\cdf{define-setf-method} must define the expander function
within the enclosing lexical environment, not within the global
environment.
\end{newer}
\end{defmac}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to add an optional environment argument to \cdf{get-setf-method}.
The revised definition and example are as follows.

\begin{defun}[Function]
get-setf-method form &optional env

\cdf{get-setf-method} returns
five values constituting the \cdf{setf} method for \emph{form}.
The \emph{form} must be a
generalized-variable reference.
The \emph{env} must be an environment of the sort obtained through
the \cd{\&environment} lambda-list keyword; if \emph{env} is \cdf{nil} or omitted,
the null lexical environment is assumed.
\cdf{get-setf-method} takes care of
error checking and macro expansion and guarantees to return exactly one
store variable.

As an example, an extremely simplified version of \cdf{setf},
allowing no more and no fewer than two
subforms, containing no optimization to remove unnecessary variables, and
not allowing storing of multiple values, could be defined by:
\begin{lisp}
(defmacro setf (reference value \&environment env) \\*
~~(multiple-value-bind (vars vals stores store-form access-form) \\*
~~~~~~(get-setf-method reference env)~~~~~;\textrm{Note use of environment}\\
~~~~(declare (ignore access-form)) \\
~~~~{\Xbq}(let* ,(mapcar \#'list \\*
~~~~~~~~~~~~~~~~~~~~(append vars stores) \\*
~~~~~~~~~~~~~~~~~~~~(append vals (list value))) \\*
~~~~~~~,store-form)))
\end{lisp}
\end{defun}
\end{newer}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to add an optional environment argument to \cdf{get-setf-method}.
The revised definition is as follows.

\begin{defun}[Function]
get-setf-method-multiple-value form &optional env

\cdf{get-setf-method-multiple-value}
returns five values constituting the \cdf{setf} method for \emph{form}.
The \emph{form} must be a
generalized-variable reference.
The \emph{env} must be an environment of the sort obtained through
the \cd{\&environment} lambda-list keyword; if \emph{env} is \cdf{nil} or omitted,
the null lexical environment is assumed.

This is the same as \cdf{get-setf-method}
except that it does not check the number of store variables; use this
in cases that allow storing multiple values into a generalized variable.
There are no such cases in standard Common Lisp, but this function is provided
to allow for possible extensions.
\end{defun}

\end{newer}

\begin{newer}
X3J13 voted in March 1988 \issue{GET-SETF-METHOD-ENVIRONMENT}
to clarify that a \cdf{setf} method for a functional name is applicable
only when the global binding of that name is lexically visible.
If such a name has a local binding introduced by \cdf{flet}, \cdf{labels},
or \cdf{macrolet}, then global definitions of \cdf{setf} methods for
that name do not apply and are not visible.  All of the standard Common Lisp
macros that modify a \cdf{setf} \emph{place} (for example,
\cdf{incf}, \cdf{decf}, \cdf{pop}, and \cdf{rotatef}) obey this convention.
\end{newer}

\section{Вызов функции}

Наиболее примитивная форма вызова функции в Lisp'е, конечно, не имеет
имени. Любой список, который не интерпретируется как макровызов или вызов
оператора, рассматривается как вызов функции.
Другие конструкции предназначены для менее распространённых, но тем не менее
полезных ситуаций.

\begin{defun}[Функция]
apply function arg &rest more-args

Функция применяет функцию \emph{function} к списку аргументов.

Все аргументы, кроме \emph{function} передаются в применяемую функцию.
Если последний аргумент список, то он присоединяется в конец к списку первых
аргументов. Например:
\begin{lisp}
(setq f '+) (apply f '(1 2)) \EV\ 3 \\
(setq f \#'-) (apply f '(1 2)) \EV\ -1 \\
(apply \#'max 3 5 '(2 7 3)) \EV\ 7 \\
(apply 'cons '((+ 2 3) 4)) {\EV} \\
~~~~~~~~((+ 2 3) . 4)	\emph{not} (5 . 4) \\
(apply \#'+ '()) \EV\ 0
\end{lisp}
Следует отметить, что если функция принимает именованные аргументы, ключевые
символы должны быть перечислены в списке аргументов так же, как и обычные
значения:
\begin{lisp}
(apply \#'(lambda (\cd{\&key} a b) (list a b)) '(:b 3)) \EV\ ({\nil} 3)
\end{lisp}
Это бывает очень полезным в связке с возможностью \cd{\&allow-other-keys}:
\begin{lisp}
(defun foo (size \cd{\&rest} keys \cd{\&key} double \cd{\&allow-other-keys}) \\
~~(let ((v (apply \#'make-array size :allow-other-keys t keys))) \\
~~~~(if double (concatenate (type-of v) v v) v))) \\
 \\
(foo 4 :initial-contents '(a b c d) :double t) \\
~~~\EV\ \#(a b c d a b c d)
\end{lisp}
\end{defun}

\begin{defun}[Функция]
funcall fn &rest arguments

\cd{(funcall \emph{fn} \emph{a1} \emph{a2} ... \emph{an})}
применяет функцию \emph{fn} к аргументам 
\emph{a1}, \emph{a2}, ..., \emph{an}.
\emph{fn} не может быть оператором или макросом, это не имело бы
смысла. 

Например:
\begin{lisp}
(cons 1 2) \EV\ (1 . 2) \\
(setq cons (symbol-function '+)) \\
(funcall cons 1 2) \EV\ 3
\end{lisp}
Различие \cdf{funcall} и обычным вызовом функции в том, что функция
получается с помощью обычных Lisp вычислений, а не с помощью специальной
интерпретации первой позиции в списке формы.
\end{defun}

\begin{defun}[Константа]
call-arguments-limit

Значение \cdf{call-arguments-limit} положительное целое, которое отображает
невключительно максимальное количество аргументов, которые могут быть переданы в
функцию. Эта граница зависит от реализации, но не может быть меньше 50.
(Разработчикам предлагается сделать этот предел большим на сколько это возможно
без ущерба для производительности.)
Значение \cdf{call-argument-limit} должно, как минимум, равняться
\cdf{lambda-parameters-limit}.
Смотрите также \cdf{multiple-values-limit}.
\end{defun}

\section{Последовательное выполнение}

Все конструкции в данном разделе выполняют все формы аргументов в прямой
последовательности. Различие заключается только в возвращаемых ими результатах.

\begin{defspec}
progn {form}*

Конструкция \cdf{progn} принимает некоторое количество форм и последовательно
вычисляет их слева направо. Значения всех кроме последней формы
игнорируется. Результатом формы \cdf{progn} становиться то, что вернула
последняя форма.
Можно сказать, что все формы кроме последней выполняются для побочных эффектов,
а последняя форма для значения.

\cdf{progn} является примитивной управляющей структурой для <<составных
выражений>>, как блоки \textbf{begin}-\textbf{end} в Algol'ных языках.
Много Lisp'овых конструкций является <<неявным \cdf{progn}>>:
так как часть их синтаксиса допускает запись нескольких форм,
которые будут выполнены последовательно и возвращён будет результат последней
формы.

Если последняя форма \cdf{progn} возвращает несколько значение, тогда все они
будут возвращены из формы \cdf{progn}. Если форм в \cdf{progn} нет вообще, то
результатом будет {\false}. Эти правила сохраняются также и для неявного
\cdf{progn}.
\end{defspec}

\begin{defmac}
prog1 first {form}*

\cdf{prog1} похожа на \cdf{progn} за исключением того, что он возвращает
результат \emph{первой} формы. Все формы-аргументы выполняются
последовательно. Значение первой формы сохраняется, затем выполняются все формы,
и, наконец, возвращается сохранённое значение.

\cdf{prog1} чаще всего используется, когда необходимо вычислить выражение с
побочными эффектами и возвращаемое значение должно быть вычислено \emph{до}
побочных эффектов.
Например:
\begin{lisp}
(prog1 (car x) (rplaca x 'foo))
\end{lisp}
изменяет \emph{car} от \cd{x} на \cd{foo} и возвращает старое значение.

\cdf{prog1} всегда возвращает одно значение, даже если первая форма возвращает
несколько значений.
В следствие, \cd{(prog1 \emph{x})} и \cd{(progn \emph{x})} могут вести себя
по-разному, \emph{x} возвращает несколько значений. Смотрите \cdf{multiple-value-prog1}.
И хотя \cdf{prog1} может использоваться для явного указания возврата только
одного значения, для этих целей лучше использовать функцию \cdf{values}.
\end{defmac}

\begin{defmac}
prog2 first second {form}*

\cdf{prog2} похожа на \cdf{prog1}, но она возвращает значение её \emph{второй}
формы. Все формы-аргументы выполняются последовательно. Значение второй формы
сохраняется и возвращается после выполнения остальных форм.
\cdf{prog2} представлена по большей части по историческим причинам.
\begin{lisp}
(prog2 \emph{a} \emph{b} \emph{c} ... \emph{z}) \EQ\ (progn \emph{a} (prog1 \emph{b} \emph{c} ... \emph{z}))
\end{lisp}
Иногда необходимо получить один побочный эффект, затем полезный результат, затем
другой побочный эффекта. В таком случае \cdf{prog2} полезна.
Например:
\begin{lisp}
(prog2 (open-a-file) (process-the-file) (close-the-file)) \\
\`;\textrm{возвращаемое значение \cdf{process-the-file}}
\end{lisp}
\end{defmac}

\section{Установка новых связываний переменных}
\label{VAR-BINDING-SECTION}

В течение вызова функции представленной лямбда-выражением (или замыканием
лямбда-выражения возвращённым функцией \cdf{function}),
для переменных параметров лямбда-выражения устанавливаются новые связывания. Эти
связывания первоначально имеют значения установленные с помощью протокола
связывания параметров, описанного в~\ref{LAMBDA-EXPRESSIONS-SECTION}.

Для установки связываний переменных, обычных и функциональных, также полезны
следующие конструкции.

\begin{defspec}
let ({var | (var [value])}*) {declaration}* {form}*

Форма \cdf{let} может быть использована для связи множества переменных со
значениями соответствующего множества форм.

Если быть точнее, форма
\begin{lisp}
(let ((\emph{var1} \emph{value1}) \\
~~~~~~(\emph{var2} \emph{value2}) \\
~~~~~~... \\
~~~~~~(\emph{varm} \emph{valuem})) \\
~~\emph{declaration1} \\
~~\emph{declaration2} \\
~~... \\
~~\emph{declarationp} \\
~~\emph{body1} \\
~~\emph{body2} \\
~~... \\
~~\emph{bodyn})
\end{lisp}
сначала последовательно выполняет выражения \emph{value1}, \emph{value2} и т.д.,
сохраняя результаты.
Затем все переменные \emph{varj} параллельно привязываются к сохранённым
значениям. Каждое связывание будет является лексическим, кроме тех, для которых
указана декларация \cdf{special}.
Затем последовательно выполняются выражения \emph{bodyk}. Все из значения, кроме
последнего, игнорируются (другими словами, тело \cdf{let} является неявным
\cdf{progn}).
Форма \cdf{let} возвращает значение \emph{bodyn} (если тело пустое, что в
принципе бесполезно, то \cdf{let} возвращает {\false}).
Связывания переменных имеют лексическую область видимости и неограниченную
продолжительность.

Вместо списка \cd{(\emph{varj} \emph{valuej})}, можно записать просто
\emph{varj}. В таком случае \emph{varj} инициализируется значением {\false}.
В целях хорошего стиля рекомендуется, записывать \emph{varj} только, если в неё
будет что-нибудь записано (с помощью \cdf{setq} например), перед первым
использованием. 
Если важно, чтобы первоначальное значение было {\false}, вместо некоторого
неопределённого значения,
тогда будет лучше записать \cd{(\emph{varj} {\false})} или \cd{(\emph{varj}
  '{\emptylist})}, если значение должно обозначать пустой список. Обратите
внимание, что код
\begin{lisp}
(let (x) \\
~~(declare (integer x)) \\
~~(setq x (gcd y z)) \\
~~...)
\end{lisp}
неправильный. Так как \emph{x} объявлен без первоначального значения и также
объявлено, что \emph{x} это целое число, то произойдёт исключение, так как
\emph{x} при связывании получает {\nil} значение, которое не принадлежит
целочисленному типу.

Декларации могут использоваться в начале тела \cdf{let}. Смотрите \cdf{declare}.

Смотрите также \cdf{destructuring-bind}.
\end{defspec}

\begin{defspec}
let* ({var | (var [value])}*) {declaration}* {form}*

\cdf{let*} похожа на \cdf{let}, но связывания переменных осуществляются
последовательно, а не параллельно. Это позволяет выражениям для значений
переменных ссылаться на ранее связанные переменные.

Если точнее, форма
\begin{lisp}
(let* ((\emph{var1} \emph{value1}) \\
~~~~~~~(\emph{var2} \emph{value2}) \\
~~~~~~~... \\
~~~~~~~(\emph{varm} \emph{valuem})) \\
~~\emph{declaration1} \\
~~\emph{declaration2} \\
~~... \\
~~\emph{declarationp} \\
~~\emph{body1} \\
~~\emph{body2} \\
~~... \\
~~\emph{bodyn})
\end{lisp}
сначала вычисляет выражение \emph{value1}, затем с этим значением связывает
переменную \emph{var1}, затем вычисляет \emph{value2} и связывает с 
результатом переменную \emph{var2}, и так далее.
Затем последовательно вычисляются выражения \emph{bodyj}.
Значения всех выражений, кроме последнего, игнорируются. То есть тело формы
\cdf{let*} является неявным \cdf{progn}.
Форма \cdf{let*} возвращает результаты вычисления \emph{bodyn} (если тело
пустое, что, в принципе, бесполезно, \cdf{let*} возвращает {\false}).
Связывания переменных имеют лексическую область видимости и неограниченную продолжительность.

Вместо списка \cd{(\emph{varj} \emph{valuej})}, можно записать просто
\emph{varj}.
В таком случае \emph{varj} будет инициализирована в {\false}. В целях стиля,
рекомендуется записывать \emph{varj}, только ей будет что-нибудь присвоено с
помощью \cdf{setq} перед первым использованием.
Если необходимо инициализировать переменную значением {\nil}, а не
неопределённым, лучше писать \cd{(\emph{varj} {\false})} для инициализации
<<ложью>> или \cd{(\emph{varj} '{\emptylist})} для инициализации пустым
списком.

В начале тела \cd{let*} могут использоваться декларации. Смотрите \cdf{declare}.
\end{defspec}

\begin{defspec}
progv symbols values {form}*

\cdf{progv} является оператором, который позволяет создавать связывания
одной и более динамических переменных, чьи имена устанавливаются во время
выполнения. Последовательность форм (неявный \cdf{progn})
выполняется с динамическими переменными, что имена в списке \emph{symbols}
связаны с соответствующими значениями в списке \emph{values}.
(Если значений меньше, чем переменных, то соответствующие переменные получают
соответствующие значения, а оставшиеся остаются без значений. Смотрите
\cdf{makunbound}. Если значений больше, чем переменных, они игнорируются.)
Результатом \cdf{progv} является результат последней формы. Связывания
динамических переменных упраздняются при выходе из формы \cdf{progv}. Списки
переменных и значений это вычисляемые значения. Это то, что отличает \cdf{progv}
от, например, \cdf{let}, в которой имена переменных указываются явно в тексте
программы.

\cdf{progv} полезна, в частности, для написания интерпретаторов языков
встраиваемых в Lisp. Она предоставляет управление механизмом связывания
динамических переменных.
\end{defspec}

\begin{defmac}
flet ({(name lambda-list
        <{declaration}* | doc-string> {form}*)}*)
     {declaration}* {form}* \\
labels ({(name lambda-list
          <{declaration}* | doc-string> {form}*)}*)
       {declaration}* {form}* \\
macrolet ({(name varlist
            <{declaration}* | doc-string> {form}*)}*)
         {declaration}* {form}*

\cdf{flet} может быть использована для определения локальных именованных
функций. Внутри тела формы \cdf{flet}, имена функций, совпадающие с именами
определёнными в \cdf{flet}, ссылаются на локально определённые функции, а не на
глобальные определения функции с теми же именами.

Может быть определено любое количество функций. Каждое определение
осуществляется формате, как в форме \cdf{defun}: сначала имя, затем список
параметров (который может содержать \cd{\&optional}, \cd{\&rest} или \cd{\&key}
параметры), затем необязательные декларации и строка документации, и, наконец,
тело.
\begin{lisp}
(flet ((safesqrt (x) (sqrt (abs x)))) \\*
~~;; Функция safesqrt используется в двух местах. \\*
~~(safesqrt (apply \#'+ (map 'list \#'safesqrt longlist))))
\end{lisp}

Конструкция \cdf{labels} идентична по форме конструкции \cdf{flet}.
Эти конструкции различаются в том, что область видимости определённых функций
для \cdf{flet} заключена только в теле, тогда как видимость в \cdf{labels}
охватывает даже определения этих функций. Это значит, что \cdf{labels} может
быть использована для определения взаимно рекурсивных функций, а \cdf{flet} не
может. Это различие бывает полезно. Использование \cdf{flet} может локально
переопределить глобальную функцию, и новое определение может ссылаться на
глобальное. Однако такая же конструкция \cdf{labels} не будет обладать этим
свойством.
\begin{lisp}
(defun integer-power (n k)~~~~~~~; Быстрое возведение \\*
~~(declare (integer n))~~~~~~~~~~; целого числа в степень \\*
~~(declare (type (integer 0 *) k)) \\
~~(labels ((expt0 (x k a) \\*
~~~~~~~~~~~~~(declare (integer x a) (type (integer 0 *) k)) \\*
~~~~~~~~~~~~~(cond ((zerop k) a) \\*
~~~~~~~~~~~~~~~~~~~((evenp k) (expt1 (* x x) (floor k 2) a)) \\*
~~~~~~~~~~~~~~~~~~~(t (expt0 (* x x) (floor k 2) (* x a))))) \\
~~~~~~~~~~~(expt1 (x k a) \\*
~~~~~~~~~~~~~(declare (integer x a) (type (integer 1 *) k)) \\*
~~~~~~~~~~~~~(cond ((evenp k) (expt1 (* x x) (floor k 2) a)) \\*
~~~~~~~~~~~~~~~~~~~(t (expt0 (* x x) (floor k 2) (* x a)))))) \\*
~~~~(expt0 n k 1)))
\end{lisp}

\cdf{macrolet} похожа на форму \cdf{flet}, но определяет локальные макросы,
используя тот же формат записи, что и \cdf{defmacro}.
Имена для макросов, установленные с помощью \cdf{macrolet}, имеют лексическую
область видимости.

\begin{new}
I have observed that, while most Common Lisp users pronounce \cdf{macrolet}
to rhyme with ``silhouette,'' a small but vocal minority pronounce it
to rhyme with ``Chevrolet.''  A very few extremists furthermore
adjust their pronunciation
of \cdf{flet} similarly: they say ``flay.''
Hey, hey!  \emph{Tr\`es outr\'e.}
\end{new}

Макросы часто должны быть раскрыты во <<время компиляции>> (общими словами,
во время перед тем, как сама программа будет выполнена), таким образом, значения
переменных во время выполнения не доступны для макросов, определённых с помощью
\cdf{macrolet}.

\begin{newer}
X3J13 voted in March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}
to retract the previous sentence and specify that the macro-expansion
functions created by \cdf{macrolet} are defined in the lexical environment in which
the \cdf{macrolet} form appears, not in the null lexical environment.
Declarations, \cdf{macrolet} definitions, and \cdf{symbol-macrolet} definitions
affect code within the expansion functions in a \cdf{macrolet}, but the
consequences are undefined if such code attempts to refer to
any local variable or function bindings that are visible in that
lexical environment.
\end{newer}

Однако, сущности, имеющие лексическую область видимости, \emph{видны} внутри
тела формы \cdf{macrolet} и \emph{видны} в коде, который является результатом
раскрытия макровызова. Следующий пример должен помочь в понимании:
\begin{lisp}
;;; Пример macrolet. \\*
\\*
(defun foo (x flag) \\*
~~(macrolet ((fudge (z) \\*
~~~~~~~~~~~~~~~~;;\textrm{Параметры \cd{x} и \cdf{flag} в данной точке} \\*
~~~~~~~~~~~~~~~~;; \textrm{недоступны; ссылка на \cd{flag} была бы} \\*
~~~~~~~~~~~~~~~~;; \textrm{одноимённую глобальную переменную.} \\*
~~~~~~~~~~~~~~~~{\Xbq}(if flag \\
~~~~~~~~~~~~~~~~~~~~~(* ,z ,z) \\
~~~~~~~~~~~~~~~~~~~~~,z))) \\
~~~~;;\textrm{Параметры \cd{x} и \cd{flag} доступны здесь.} \\*
~~~~(+ x \\*
~~~~~~~(fudge x) \\*
~~~~~~~(fudge (+ x 1)))))
\end{lisp}
Тело данного примера после разворачивания макросов превращается в
\begin{lisp}
(+ x \\*
~~~(if flag \\*
~~~~~~~(* x x) \\*
~~~~~~~x)) \\*
~~~(if flag \\*
~~~~~~~(* (+ x 1) (+ x 1)) \\*
~~~~~~~(+ x 1)))
\end{lisp}
\cd{x} и \cd{flag} легитимно ссылаются на параметры функции
\cd{foo}, потому что эти параметры видимы в месте макровызова.

\begin{newer}
X3J13 voted in March 1988 \issue{FLET-IMPLICIT-BLOCK}
to specify that the body of each function or expander function defined
by \cdf{flet}, \cdf{labels}, or \cdf{macrolet}
is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the function.
Therefore \cdf{return-from} may be used to exit from the function.
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to extend \cdf{flet} and \cdf{labels}
to accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}) as a \emph{name}
for a function to be locally defined.  In this way one can create local definitions
for \cdf{setf} expansion functions.  (X3J13 explicitly declined to extend
\cdf{macrolet} in the same manner.)
\end{newer}

\begin{new}
X3J13 voted in March 1988
\issue{FLET-DECLARATIONS}
to change \cdf{flet}, \cdf{labels}, and \cdf{macrolet}
to allow declarations to appear before the body.
The new descriptions are therefore as follows:
\end{new}
\end{defmac}

\begin{defspec}
symbol-macrolet ({(var expansion)}*)
                {declaration}* {form}*

X3J13 проголосовал в июне 1988
\issue{CLOS}
адаптировать Common Lisp'овую систему объектов (CLOS). Часть этого является
общий механизм, \cdf{symbol-macrolet}, для обработки заданных имён переменным,
как если бы они были макровызовами без параметров. Эта функциональность
полезно независимо от CLOS.

Формы \emph{forms} выполняются как неявный \cdf{progn} в лексическом окружении,
в котором любая ссылка на обозначенную переменную \emph{var} будет заменена на
соответствующее выражение \emph{expansion}. Это происходит, как будто ссылка на
переменную \emph{var} является макровызовом без параметров.
Выражение \emph{expansion} вычисляется или обрабатывается в месте появления
ссылки. Однако, следует отметить, что имена таких макросимволов работает в
пространстве имен переменных, не в пространстве функций. 
Использование \cdf{symbol-macrolet} может быть в свою очередь перекрыто с
помощью \cdf{let} или другой конструкцией, связывающей переменные. Например:
\begin{lisp}
(symbol-macrolet ((pollyanna 'goody)) \\*
~~(list pollyanna (let ((pollyanna 'two-shoes)) pollyanna))) \\*
~{\EV} (goody two-shoes)\textrm{, \emph{not}} (goody goody)
\end{lisp}

Выражение \emph{expansion} для каждой переменной \emph{var} вычисляется не во
время связывания, а во время подстановки вместо ссылок на \emph{var}.
Конструкция возвращает значения последней вычисленной формы, или \cdf{nil}, если
таких значений не было.

Смотрите документация \cdf{macroexpand} и \cdf{macroexpand-1}. Они раскрывают
макросы символов, также как и обычные макросы.

Указанные декларации \emph{declarations} перед телом обрабатываются так как
описано в разделе~\ref{DECLARE-SYNTAX-SECTION}.
\end{defspec}


\begin{defmac}
define-symbol-macro symbol {form}

Символ \emph{symbol} выступает в качестве макровызова. Одинарная форма содержит
тело раскрытия. Символы не может являться определённой специальной переменной.
\end{defmac}


\section{Операторы условных переходов}

Традиционная условная конструкция в Lisp'е это \cdf{cond}.
Однако, \cdf{if} гораздо проще и очень похожа на условные конструкции в других
языках программирования. Она сделана примитивом в Common Lisp'е.
Common Lisp также предоставляет конструкции диспетчеризации (распределения)
\cdf{case} и \cdf{typecase}, которые часто более удобны, чем \cdf{cond}.

\begin{defspec}
if test then [else]

Оператор \cdf{if} обозначает то же, что и конструкция
\textbf{if}-\textbf{then}-\textbf{else} в большинстве других языках
программирования.
Сначала выполняется форма \emph{test}. Если результат не равен {\false}, тогда
выбирается форма \emph{then}. Иначе выбирается форма \emph{else}.
Выбранная ранее форма выполняется, и \cdf{if} возвращает то, что вернула это
форма.
\begin{lisp}
(if \emph{test} \emph{then} \emph{else}) \EQ\ (cond (\emph{test} \emph{then}) ({\true} \emph{else}))
\end{lisp}
Но в некоторых ситуациях \cdf{if} оказывается более читабельным.

Форма \emph{else} может быть опущена. В таком случае, если значение формы
\emph{test} является {\false}, тогда ничего не будет выполнено и возвращаемое
значение формы \cdf{if} будет {\false}.
Если в этой ситуации значение формы \cdf{if} важно, тогда в зависимости от
контекста стилистически удобнее использовать форму \cdf{and}.
Если значение не важно, тогда удобнее использовать конструкцию \cdf{when}.
\end{defspec}

\begin{defmac}
when test {form}*

\cd{(when \emph{test} \emph{form1} \emph{form2} ... )}
сначала выполняет \emph{test}. Если результат {\false}, тогда ничего не
выполняется и возвращается {\false}.
Иначе, последовательно выполняются формы \emph{form}
слева направо (как неявный \cdf{progn}), и возвращается значение последней
формы.
\begin{lisp}
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (and \emph{p} (progn \emph{a} \emph{b} \emph{c})) \\
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (cond (\emph{p} \emph{a} \emph{b} \emph{c})) \\
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (if \emph{p} (progn \emph{a} \emph{b} \emph{c}) {\false}) \\
(when \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (unless (not \emph{p}) \emph{a} \emph{b} \emph{c})
\end{lisp}
В целях хорошего стиля, \cdf{when} обычно используется для выполнения побочных
эффектов при некоторых условиях, и значение \cdf{when} не используется.
Если значение все-таки важно, тогда, может быть, стилистически функции
\cdf{and} или \cdf{if} более подходят.
\end{defmac}

\begin{defmac}
unless test {form}*

\cd{(unless \emph{test} \emph{form1} \emph{form2} ... )}
сначала выполняет \emph{test}. Если результат \emph{не} {\false}, тогда ничего не
выполняется и возвращается {\false}.
Иначе, последовательно выполняются формы \emph{form}
слева направо (как неявный \cdf{progn}), и возвращается значение последней
формы.
\begin{lisp}
(unless \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (cond ((not \emph{p}) \emph{a} \emph{b} \emph{c})) \\
(unless \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (if \emph{p} {\false} (progn \emph{a} \emph{b} \emph{c})) \\
(unless \emph{p} \emph{a} \emph{b} \emph{c}) \EQ\ (when (not \emph{p}) \emph{a} \emph{b} \emph{c})
\end{lisp}
В целях хорошего стиля, \cdf{unless} обычно используется для выполнения побочных
эффектов при некоторых условиях, и значение \cdf{unless} не используется.
Если значение все-таки важно, тогда может быть стилистически более подходящая
функция \cdf{if}.
\end{defmac}

\begin{defmac}
cond {(test {form}*)}*

Форма \cdf{cond} содержит некоторое (возможно нулевое) количество подвыражений,
которые является списками форм.
Каждое подвыражение содержит форму условия и ноль и более форм для выполнения.
Например:
\begin{lisp}
(cond (\emph{test-1} \emph{consequent-1-1} \emph{consequent-1-2} ...) \\
~~~~~~(\emph{test-2}) \\
~~~~~~(\emph{test-3} \emph{consequent-3-1} ...) \\
~~~~~~... )
\end{lisp}

Отбирается первое подвыражение, чья форма условия вычисляется в не-{\false}. Все
остальные подвыражения игнорируются. Формы отобранного подвыражения
последовательно выполняются (как неявный \cdf{progn}).

Если быть точнее, \cdf{cond} обрабатывает свои подвыражения слева направо. Для
каждого подвыражения, вычисляется форма условия. Если результат {\false},
\cdf{cond} переходит к следующему подвыражению. Если результат {\true},
\emph{cdr} подвыражения обрабатывается, как список форм. Этот список выполняется
слева направо, как неявный \cdf{progn}.
После выполнения списка форм, \cdf{cond} возвращает управление без обработки
оставшихся подвыражений.
Оператор \cdf{cond} возвращает результат выполнения последней формы из
списка. Если этот список пустой, тогда возвращается значение формы условия.
Если \cdf{cond} вернула управление без вычисления какой-либо ветки (все условные
формы вычислялись в {\false}), возвращается значение {\false}.

Для того, чтобы выполнить последнее подвыражение, в случае если раньше ничего не
выполнилось, можно использовать {\true} для формы условия.
В целях стиля, если значение \cdf{cond} будет для чего-то использоваться,
желательно записывать последнее выражение так: \cd{({\true} {\false})}.
Также вопросом вкуса является запись последнего подвыражения \cdf{cond} как
<<синглтон>>, в таком случае, используется неявный {\true}.
(Следует отметить, если \emph{x} может возвращать несколько значений, то
\cd{(cond ... (\emph{x}))} может вести себя отлично от 
\cd{(cond ... ({\true} \emph{x}))}. Первое выражение всегда возвращает одно
выражение, тогда как второе возвращает все то же, что и \emph{x}. В зависимости
от стиля, можно указывать поведение явно \cd{(cond ... (t (values \emph{x})))},
используя функцию \cdf{values} для явного указания возврата одного значения.)
Например:
\begin{lisp}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\=\kill
(setq z (cond (a 'foo) (b 'bar)))\>;\textrm{Возможна неопределённость} \\*
(setq z (cond (a 'foo) (b 'bar) ({\true} {\false})))\>;\textrm{Уже лучше} \\
(cond (a b) (c d) (e))\>;\textrm{Возможна неопределённость} \\*
(cond (a b) (c d) ({\true} e))\>;\textrm{Уже лучше} \\*
(cond (a b) (c d) ({\true} (values e)))\>;\textrm{Неплохо (если необходимо} \\*
                                       \>;~\textrm{одно значение)} \\
(cond (a b) (c))\>;\textrm{Возможна неопределённость} \\
(cond (a b) (t c))\>;\textrm{Уже лучше} \\*
(if a b c)\>;\textrm{Тоже неплохо}
\end{lisp}
Lisp'овая форма \cdf{cond} сравнима с последовательностью
\textbf{if}-\textbf{then}-\textbf{else}, используемой в большинстве
алгебраических языках программирования:
\begin{lisp}
~~~~~~~~~~~~~~~~~~~~\=~~~~~~~~~~~~~~~~~~~~~\=\kill
(cond (\emph{p} ...)\>\>\textbf{if} \emph{p} \textbf{тогда} ... \\
~~~~~~(\emph{q} ...)\>\textrm{roughly}\>\textbf{иначе} \textbf{если} \emph{q} \textbf{тогда} ... \\
~~~~~~(\emph{r} ...)\>\textrm{corresponds}\>\textbf{иначе} \textbf{если} \emph{r} \textbf{тогда} ... \\
~~~~~~...\>\textrm{to}\>... \\
~~~~~~({\true} ...))\>\>\textbf{иначе} ...
\end{lisp}
\end{defmac}

\begin{defmac}
case keyform {({({key}*) | key} {form}*)}*

\cdf{case} условный оператор, который выбирает ветку для выполнения, в
зависимости от равенства некоторой переменной некоторой константе. Константа
обычно представляет собой ключевой символ, целое число или буква (но
может быть и любой другой объект). Вот развёрнутая форма:
\begin{lisp}
(case \emph{keyform} \\
~~(\emph{keylist-1} \emph{consequent-1-1} \emph{consequent-1-2} ...) \\
~~(\emph{keylist-2} \emph{consequent-2-1} ...) \\
~~(\emph{keylist-3} \emph{consequent-3-1} ...) \\
~~...)
\end{lisp}
Структурно \cdf{case} очень похож на \cdf{cond}, и поведение такое же: выбрать
список форм и выполнить их.
Однако \cdf{case} отличается механизмом выбора подвыражения.

Сперва \cdf{case} вычисляет форму \emph{keyform} для получения объекта, который
называется \emph{ключевой объект}.
Затем \cdf{case} рассматривает все подвыражения. Если \emph{ключевой объект}
присутствует в списке \emph{keylist} (то есть, если \emph{ключевой объект} равен
\cdf{eql} хотя бы одному элементу из списка \emph{keylist}), то список форм
выбранного подвыражения вычисляется, как неявный \cdf{progn}.
\cdf{case} возвращает то же, что и последняя форма списка (или {\false} если
список форм был пустой).
Если ни одно подвыражение не удовлетворило условию, то \cdf{case} возвращает
{\false}.

Ключи в списке ключей \emph{keylist} \emph{не} выполняются. В данном списке
должны быть указаны литеральные ключи.
Если один ключ попадается более чем в одном подвыражении, это считается
ошибкой.
Следствием является то, что порядок этих подвыражений не влияет на поведение
конструкции \cdf{case}.

Вместо \emph{keylist} можно записать один из символов: {\true} или
\cdf{otherwise}. Подвыражение с одним из таких символов всегда удовлетворяет
условию выбора. Такое подвыражение должно быть последним (это исключение из
правила о произвольности положения подвыражений).
Смотрите также \cdf{ecase} и \cdf{ccase}, каждая из которых предоставляет
неявное \cdf{otherwise} подвыражение для сигнализирования об ошибке, если ни
одно подвыражение не удовлетворило условию.

Если в подвыражении только один ключ, тогда этот ключ может быть записан вместо
списка.
Такой <<синглтоновый ключ>> не может быть {\nil} (так как возникают конфликты с
{\emptylist}, который означает список без ключей), {\true}, \cdf{otherwise} или
cons-ячейкой.
\end{defmac}

\begin{defmac}
typecase keyform {(type {form}*)}*

\cdf{typecase} условный оператор, который выбирает подвыражение на основе типа
объекта.
Развёрнутая форма:
\begin{lisp}
(typecase \emph{keyform} \\*
~~(\emph{type-1} \emph{consequent-1-1} \emph{consequent-1-2} ...) \\*
~~(\emph{type-2} \emph{consequent-2-1} ...) \\*
~~(\emph{type-3} \emph{consequent-3-1} ...) \\
~~...)
\end{lisp}
Структура \cdf{typecase} похожа на \cdf{cond} или \cdf{case}. Поведение также
схоже в том, что выбирается подвыражение в зависимости от условия.
Различие заключается в механизме выбора подвыражения.

Сперва \cdf{typecase} вычисляет форму \emph{keyform} для создания объекта,
называемого ключевым объектом.
Далее \cdf{typecase} друг за другом рассматривает каждое подвыражение. Форма
\emph{type}, которая встречается в каждом подвыражении, является спецификатором
типа. Данный спецификатор не вычисляется, поэтому должен быть литеральным.
Когда ключевой объект принадлежит некоторый типу, то выделенный список форм
\emph{consequent} выполняется последовательно (как неявный
\cdf{progn}). \cdf{typecase} возвращает то, что вернула последняя форма из
списка (или {\false} если список был пуст).
Если не одно подвыражение не было выбрано, \cdf{typecase} возвращает {\false}.

Как и для \cdf{case} можно использовать {\true} или \cdf{otherwise} на позиции
\emph{типа} для задания подвыражений, которые будут выполняться, только если не
было выполнено других подвыражений.
Смотрите также \cdf{etypecase} и \cdf{ctypecase}, каждая из которых
предоставляет неявную ветку \cdf{otherwise} для сигнализирования об ошибке, что
ни одно подвыражение не удовлетворило условию.

Допустимо указывать более одного подвыражение, тип условия которого уже является
подтипом условия другого подвыражения. В таком случае будет выбрано первое
встретившееся подвыражение. Таким образом в \cdf{typecase}, в отличие от
\cdf{case}, порядок следования подвыражений влияет на поведение всей
конструкции.
\begin{lisp}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\=\kill
(typecase an-object \\
~~~(string ...)\>;\textrm{Подвыражение обрабатывает строки} \\
~~~((array t) ...)\>;\textrm{Подвыражение обрабатывает общие массивы} \\
~~~((array bit) ...)\>;\textrm{Подвыражение обрабатывает битовые массивы} \\
~~~(array ...)\>;\textrm{Обрабатывает все остальные массивы} \\
~~~((or list number) ...)\>;\textrm{Подвыражение обрабатывает списки и числа} \\
~~~(t ...))\>;\textrm{Подвыражение обрабатывает все остальные объекты}
\end{lisp}
\end{defmac}

\section{Блоки и выходы}
\label{BLOCK-RETURN-SECTION}

Конструкции \cdf{block} и \cdf{return-from} предоставляют функциональность для
структурированного лексического нелокального выхода. В любом месте лексически
внутри конструкции \cdf{block}, для мгновенного возврата управления из
\cdf{block} может быть использована \cdf{return-from} с тем же именем.
В большинстве случаев этот механизм более эффективный, чем функциональность
динамического нелокального выхода, предоставляемая формами \cdf{catch} и
\cdf{throw}, описанными в разделе~\ref{CATCH-THROW-SECTION}.

\begin{defspec}
block name {form}*

Конструкция \cdf{block} слева направо выполняет каждую форму \emph{form},
возвращая то, что возвращает последняя форма.
Если, однако, в процессе выполнения форм, будет выполнена \cdf{return} или
\cdf{return-from} с именем \emph{name}, тогда будет возвращён результат заданный
одной из этих форм, и поток выполнения немедленно выйдет из формы \cdf{block}.
Таким образом \cdf{block} отличается от \cdf{progn} тем, что последняя никак не
реагирует на \cdf{return}.

Имя блока не выполняется. Оно должно быть символом.
Область видимости имени блока лексическая. Из блока можно осуществить выход с
помощью \cdf{return} или \cdf{return-from}, только если они содержаться в тексте
в блоке. Продолжительность видимости имени динамическая.
Таким образом из блока во время выполнения можно выйти только один раз, обычно
или явно с помощью \cdf{return}.

Форма \cdf{defun} неявно помещает тело функции в одноимённый блок. 
Таким образом можно использовать \cdf{return-from} для преждевременного выхода
из функции в определении \cdf{defun}.

Лексическая область видимости имени блока полноценна и имеет последствия,
которые могут быть сюрпризом для пользователей и разработчиков других Lisp
систем.
Например, \cdf{return-from} в следующем примере в Common Lisp работает так как
и ожидается:
\begin{lisp}
(block loser \\
~~~(catch 'stuff \\
~~~~~~(mapcar \#'(lambda (x) (if (numberp x) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(hairyfun x) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(return-from loser {\nil}))) \\
~~~~~~~~~~~~~~items)))
\end{lisp}
В зависимости от ситуации, \cdf{return} в Common Lisp'е может быть не проста.
\cdf{return} может перескочить ловушки, если это необходимо, для
рассматриваемого блока.
Также возможно для <<замыкания>>, созданного с помощью \cdf{function} для
лямбда-выражения, ссылаться на имя блока на протяжении лексической доступности
этого блока.
\end{defspec}

\begin{defspec}
return-from name [result]

\cdf{return-from} используется для возврата из \cdf{block} или из таких
конструкций, как \cdf{do} и \cdf{prog}, которые неявно устанавливают
\cdf{block}.
Имя \emph{name} не выполняется и должно быть символом.
Конструкция \cdf{block} с этим именем должна лексически охватывать форму
\cdf{return-from}.
Каков бы ни был результат вычисления формы \emph{result}, управление немедленно
возвращается из блока.
(Если форма \emph{result} опущена, тогда используется значение {\nil}. В целях
стиля, эта форма обязана использоваться для указания того, что возвращаемое
значение не имеет ценности.)

Форма \cdf{return-from} сама по себе ничего и никогда не возвращает.
Она указывает на то, что результат выполнения будет возвращён из конструкции
\cdf{block}.
Если вычисление формы \emph{result} приводит к нескольким значениям, эти
несколько значений и будут возвращены и конструкции.
\end{defspec}

\begin{defmac}
return [result]

\cd{(return \emph{form})} идентично по смыслу 
\cd{(return-from {\nil} \emph{form})}. Она возвращает управление из блока с
именем {\nil}.
Такие блоки с именем {\nil} устанавливаются автоматически в конструкциях циклов,
таких как \cdf{do}, таким образом \cdf{return} будет производить корректный
выход из таких конструкций.
\end{defmac}

\section{Формы циклов}
\indexterm{iteration}

Common Lisp предоставляет некоторые конструкции для циклов. Конструкция
\cdf{loop} предоставляет простую функциональность. Она слегка больше, чем
\cdf{progn}, и имеет ветку для переноса управления снизу вверх.
Конструкции \cdf{do} и \cdf{do*} предоставляют общую функциональность для
управления на каждом цикле изменением нескольких переменных.
Для специализированных циклов над элементами списка или \emph{n}
последовательных чисел предоставляются формы \cdf{dolist} и \cdf{dotimes}.
Конструкция \cdf{tagbody} наиболее общая конструкция, которая внутри себя
позволяет использование выражений \cdf{go}. (Традиционная конструкция \cdf{prog}
--- это синтез \cdf{tagbody}, \cdf{block} и \cdf{let}.)
Большинство конструкций циклов позволяют определённые статически нелокальные
выходы (смотрите \cdf{return-from} и \cdf{return}).

\subsection{Бесконечный цикл}

Конструкция \cdf{loop} является наипростейшей функциональностью для итераций.
Она не управляет переменными, и просто циклично выполняет своё тело.

\begin{defmac}
loop {form}*

Каждая форма \emph{form} выполняется последовательно слева направо.
Когда вычислена последняя форма, тогда вычисляется первая форма и так далее,
в безостановочном цикле.
Конструкция \cdf{loop} никогда не возвращает значение. Её выполнение может быть
остановлено явно, с помощью \cdf{return} или \cdf{throw}, например.

\cdf{loop}, как и многие конструкции циклов, устанавливает неявный блок с именем
{\nil}.
Таким образом, \cdf{return} с заданным результатом может использоваться для
выхода и \cdf{loop}.
\end{defmac}

\subsection{Основные формы циклов}

В отличие от \cdf{loop}, \cdf{do} и \cdf{do*} предоставляют мощный механизм для
повторных вычислений большого количества переменных. 


\begin{defmac}
do ({var | (var [init [step]])}*)
   (end-test {result}*)
   {declaration}* {tag | statement}* \\
do* ({var | (var [init [step]])}*)
    (end-test {result}*)
    {declaration}* {tag | statement}*

Оператор \cdf{do} представляет общую функциональность цикла, с
произвольным количеством <<переменных-индексов>>.
Эти переменные связываются при входе в цикл и параллельно наращиваются, как это
было задано. Они могут быть использованы, как для генерации необходимых
последовательных чисел (как, например, последовательные целые числа), так и для
накопления результата.
Когда условие окончания цикла успешно выполнилось, тогда цикл завершается с
заданным значением.

В общем виде \cdf{do} выглядит так:
\begin{lisp}
(do ((\emph{var1} \emph{init1} \emph{step1}) \\
~~~~~(\emph{var2} \emph{init2} \emph{step2}) \\
~~~~~... \\
~~~~~(\emph{varn} \emph{initn} \emph{stepn})) \\
~~~~(\emph{end-test} . \emph{result}) \\
~~\Mstar{\emph{declaration}} \\
~~. \emph{tagbody})
\end{lisp}
Цикл \cdf{do*} выглядит также, кроме изменения имени с \cdf{do} на \cdf{do*}.

Первый элемент формы является списком нуля и более спецификаторов
переменных-индексов. Каждый спецификатор является списком из имени переменной
\emph{var}, первоначального значения \emph{init}, и форма приращения
\emph{step}.
Если \emph{init} опущен, используется первоначальное значение {\false}.
Если \emph{step} опущен, \emph{var} не изменяется на итерациях цикла (но может
изменяться в теле цикла с помощью формы \cdf{setq}).

Спецификатор переменной-индекса может также быть просто именем переменной.
В этом случае переменная будет иметь первоначальное значение {\false} и не будет
изменяться при итерациях цикла.
В целях стиля, использовать просто имя переменной рекомендуется, только если перед
первым использованием для неё устанавливается значение с помощью \cdf{setq}.
Если необходимо чтобы первоначальное значение было {\false}, а не
неопределённое, то лучше указывать это явно, если нужна ложь так:
\cd{(\emph{varj} {\false})}
или если нужен пустой список так:
\cd{(\emph{varj} '{\emptylist})}.

Перед первой итерацией вычисляются все формы \emph{init}, и каждая переменная
\emph{var} связывается с соответствующим результатом вычислений \emph{init}.
Используется именно связывание, а не присвоение. Когда цикл завершается, старые
значения этих переменных восстанавливаются.
Для \cdf{do}, \emph{все} формы \emph{init} вычисляется перед тем, как будут
связаны переменные \emph{var}. Таким образом все формы могут ссылаться на старые
связывания этих переменных
(то есть на значения, которые были видимы до начала выполнения конструкции
\cdf{do}).
Для \cdf{do*} вычисляется первая форма \emph{init}, затем первая переменная
связывается с результатом этих вычислений. Затем вычисляется вторая форма
\emph{init} и вторая переменная \emph{var} связывается с этим значением, и так
далее.
В целом, форма \emph{initj} может ссылаться на \emph{новые} связывания
\emph{vark}, если $k<j$, иначе ссылка происходит на \emph{старое} связывание.

Второй элемент конструкции цикла это список из формы предиката-выхода
\emph{end-test} и нуля и более форм результата \emph{result}.
Этот элемент напоминает подвыражение \cdf{cond}.
В начале каждой итерации, после обработки всех переменных, вычисляется форма
\emph{end-test}. Если результат {\false}, выполняется тело формы \cdf{do} (или
\cdf{do*}).
Если результат не {\false}, последовательно вычисляются формы \emph{result}, как
неявный \cdf{progn},
и затем \cdf{do} возвращает управление. \cdf{do} возвращает результаты
вычисления последней формы \emph{result}.
Если таких форм не быть, значением \cdf{do} становиться {\false}.
Следует отметить, что аналогия с подвыражениями \cdf{cond} не полная, так как
\cdf{cond} в этом случае возвращает результат формы условия.

Переменные-индексы изменяются в начале каждой непервой итерации так, как
написано далее. Слева направо вычисляются все формы \emph{step}, и затем
результаты присваиваются переменным-индексам.
Если такой формы \emph{step} для переменной указано не было, то переменная и не
изменяется.
Для \cdf{do}, все формы \emph{step} вычисляются перед там, как будут изменены
переменные. Присваивания переменным осуществляются параллельно, как в
\cdf{psetq}.
Так как \emph{все} формы \emph{step} вычисляются перед тем, как будет изменена
хоть одна переменных, форма \emph{step} при вычислении всегда ссылается на
старые значения \emph{всех} переменных-индексов, даже если другие формы
\emph{step} были выполнены.
Для \cdf{do*}, вычисляется первая форма \emph{step}, затем полученное значение
присваивается первой переменной-индексом, затем вычисляется вторая форма
\emph{step}, и полученное значение присваивается второй переменной, и так
далее. Присваивание происходит последовательно, как в \cdf{setq}.
И для \cdf{do}, и для \cdf{do*} после того как переменные были изменены,
вычисляется \emph{end-test} так, как уже было описано выше. Затем продолжаются
итерации.

Если \emph{end-test} формы \cdf{do} равен \cd{{\false}}, тогда предикат всегда
ложен.
Таким образом получается <<бесконечный цикл>>:
тело \emph{body} \cdf{do} выполняется циклично, переменные-индексы изменяются
как обычно. (Конструкция \cdf{loop} также является <<бесконечным циклом>>,
только без переменных-индексов.)
Бесконечный цикл может быть остановлен использованием \cdf{return},
\cdf{return-from}, \cdf{go} на более высокий уровень или \cdf{throw}.
Например:
\begin{lisp}
(do ((j 0 (+ j 1))) \\
~~~~({\false})~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Выполнять вечно} \\
~~(format t "{\Xtilde}\%Input {\Xtilde}D:" j) \\
~~(let ((item (read))) \\
~~~~(if (null item) (return)~~~~~;\textrm{Обрабатывать элементы пока не найден {\false}} \\
~~~~~~~~(format t "{\Xtilde}\&Output {\Xtilde}D: {\Xtilde}S" j (process item)))))
\end{lisp}

Оставшаяся часть \cdf{do} оборачивается в неявный \cdf{tagbody}.
Теги могут использоваться внутри тела цикла \cdf{do} для того, чтобы затем
использовать выражения \cdf{go}. На такие выражения \cdf{go} не могут
использоваться в спецификаторах переменных-индексов, в предикате
\emph{end-test} и в формах результата \emph{result}.
Когда управление достигает конца тела цикла \cdf{do}, наступает следующая
цикл итерации (начинающийся с вычисления форм \emph{step}).

Неявный \cdf{block} с именем {\nil} окружает всю форму \cdf{do}.
Выражение \cdf{return} может использоваться в любом месте для немедленного
выхода из цикла.

Формы \cdf{declare} могут использоваться в начала тела \cdf{do}.
Они применяются к коду внутри тела \cdf{do}, для связываний переменных-индексов,
для форм \emph{init}, для форм \emph{step}, для предиката \emph{end-test} и для
форм результата \emph{result}.

Вот парочка примеров использования \cdf{do}:
\begin{lisp}
(do ((i 0 (+ i 1))~~~~~;\textrm{Sets every null element of \cdf{a-vector} to zero} \\*
~~~~~(n (length a-vector))) \\*
~~~~((= i n)) \\
~~(when (null (aref a-vector i)) \\*
~~~~(setf (aref a-vector i) 0)))
\end{lisp}
Конструкция
\begin{lisp}
(do ((x e (cdr x)) \\*
~~~~~(oldx x x)) \\*
~~~~((null x)) \\*
~~\emph{body})
\end{lisp}
использует параллельное присваивание переменным-индексам. На первой итерации
значение \cdf{oldx} получает значение \cd{x}, которое было до входа в цикл.
При выходе из цикла \cd{oldx} будет содержать значение \cd{x}, которое было на
предыдущей итерации.

Очень часто алгоритм цикла может быть по большей части выражен в формах
\emph{step} и тело при этом останется пустым.
Например,
\begin{lisp}
(do ((x foo (cdr x)) \\*
~~~~~(y bar (cdr y)) \\*
~~~~~(z '{\emptylist} (cons (f (car x) (car y)) z))) \\
~~~~((or (null x) (null y)) \\*
~~~~~(nreverse z)))
\end{lisp}
делает то же, что и \cd{(mapcar \#'f foo bar)}. Следует отметить, что вычисление
\emph{step} для \cd{z} использует тот факт, что переменные переприсваиваются
параллельно.
Тело функции пустое. Наконец, использование \cdf{nreverse} в форме возврата
результата, переставляет элементы списка для правильного результата. Другой
пример:
\begin{lisp}
(defun list-reverse (list) \\*
~~~~~~~(do ((x list (cdr x)) \\*
~~~~~~~~~~~~(y '{\emptylist} (cons (car x) y))) \\*
~~~~~~~~~~~((endp x) y)))
\end{lisp}
Нужно заметить, что используется \cdf{endp} вместо \cdf{null} или \cdf{atom}
для проверки конца списка. Это даёт более надёжный алгоритм.

В качестве примера вложенных циклов, предположим что \cd{env} содержит список
cons-ячеек.
\emph{car} элемента каждой cons-ячейки является списком символов, и \emph{cdr}
каждой cons-ячейки является списком такой же длины с соответствующими
значениями.
Такая структура данных похожа на ассоциативный список, но она в отличие
разделена на <<кадры>>. Общая структура напоминает грудную клетку.
Функция поиска по такой структуре может быть такой:
\begin{lisp}
(defun ribcage-lookup (sym ribcage) \\*
~~~~~~~(do ((r ribcage (cdr r))) \\*
~~~~~~~~~~~((null r) {\false}) \\
~~~~~~~~~(do ((s (caar r) (cdr s)) \\*
~~~~~~~~~~~~~~(v (cdar r) (cdr v))) \\*
~~~~~~~~~~~~~((null s)) \\
~~~~~~~~~~~(when (eq (car s) sym) \\*
~~~~~~~~~~~~~(return-from ribcage-lookup (car v))))))
\end{lisp}
(Примечание, использование отступов в примере выше выделяет тела вложенных
циклов.) 

Цикл \cdf{do} может быть выражен в терминах более примитивных конструкций 
\cdf{block}, \cdf{return}, \cdf{let}, \cdf{loop}, \cdf{tagbody}
и \cdf{psetq}:
\begin{lisp}
(block nil \\*
~~(let ((\emph{var1} \emph{init1}) \\*
~~~~~~~~(\emph{var2} \emph{init2}) \\
~~~~~~~~... \\*
~~~~~~~~(\emph{varn} \emph{initn})) \\*
~~~~\Mstar{\emph{declaration}} \\
~~~~(loop (when \emph{end-test} (return (progn . \emph{result}))) \\*
~~~~~~~~~~(tagbody . \emph{tagbody}) \\*
~~~~~~~~~~(psetq \emph{var1} \emph{step1} \\*
~~~~~~~~~~~~~~~~~\emph{var2} \emph{step2} \\*
~~~~~~~~~~~~~~~~~... \\*
~~~~~~~~~~~~~~~~~\emph{varn} \emph{stepn}))))
\end{lisp}
\cdf{do*} почти то же, что и \cdf{do} за исключением того, что связывание и
наращение переменных происходит последовательно, а не параллельно.
Таким образом, в вышеприведённой конструкции, \cdf{let} будет заменена на
\cdf{let*} и \cdf{psetq} на \cdf{setq}.
\end{defmac}

\subsection{Простые формы циклов}

Конструкции \cdf{dolist} и \cdf{dotimes} для каждого значения взятого для одной
переменной выполняют тело один раз. Они хоть и выражаются в терминах \cdf{do},
но захватывают очень простые шаблоны использования.

И \cdf{dolist} и \cdf{dotimes} циклично выполняют тело. На каждой итерации
заданная переменная связывается с элементом, которая затем может использоваться
в теле. \cdf{dolist} использует элементы списка, и \cdf{dotimes} использует
целые числа от 0 по $n-1$, при некотором указанном положительном целом \emph{n}.

Результат двух этих конструкций может быть указан с помощью необязательной формы
результата. Если эта форма опущена результат равен {\false}.

Выражение \cdf{return} может быть использовано для немедленного возврата из форм
\cdf{dolist} или \cdf{dotimes}, игнорируя все оставшиеся итерации, которые
должны были быть выполнены. \cdf{block} с именем {\nil} окружает конструкцию.
Тело цикла неявно обернуто конструкцией \cdf{tagbody}.
Таким образом тело может содержать теги и \cdf{go} выражения.
Декларации могут быть указаны перед телом цикла.

\begin{defmac}
dolist (var listform [resultform])
       {declaration}* {tag | statement}*

\cdf{dolist} предоставляет прямой цикл по списку элементов.
Сначала \cdf{dolist}
вычисляет форму \emph{listform}, которая должна вернуть список.
Затем для каждого элемента вычисляется тело цикла. Данный элемент на каждой
итерации связывается с переменной \emph{var}.
Затем вычисляется \emph{resultform} (одна форма, \emph{не} неявный \cdf{progn}).
(Когда вычисляется \emph{resultform}, переменная \emph{var} все ещё связана, и
имеет значение {\nil}.)
Если \emph{resultform} опущена, то результат равен {\false}.
\begin{lisp}
(dolist (x '(a b c d)) (prin1 x) (princ " ")) \EV\ {\false} \\
~~~\textrm{вывод <<\cd{a b c d }>> (в том числе пробел в конце)}
\end{lisp}
Для завершения цикла и возврата заданного значения может использоваться явное
выражение \cdf{return}.

Пользователь ограничен в создании побочных действий так, как это описано в
разделе~\ref{STRUCTURE-TRAVERSAL-SECTION}
\end{defmac}

\begin{defmac}
dotimes (var countform [resultform])
        {declaration}* {tag | statement}*

\cdf{dotimes} предоставляет цикл над последовательностью целых чисел.
Выражение
\cd{(dotimes (\emph{var} \emph{countform} \emph{resultform}) . \emph{progbody})}
вычисляет форму \emph{countform}, которая должна вернуть целое число. Затем
тело цикла выполняется по порядку один раз для каждого число от нуля (включительно) до
\emph{count} (исключая). При этом переменная \emph{var} связывается с текущим
целым числом. Если значение \emph{countform} отрицательно или равно нулю, тогда
\emph{progbody} не выполняется ни разу. Наконец выполняется \emph{resultform} (одна форма,
\emph{не} неявный \cdf{progn}), и полученный результат возвращается из формы
цикла.
(Когда \emph{result} вычисляется, переменная-индекс \emph{var} все ещё связана и
содержит количество выполненных итераций.)
Если \emph{resultform} опущена, то результат равен {\false}.

Для завершения цикла и возврата заданного значения может использоваться
выражение \cdf{return}.

Пример использования \cdf{dotimes} для обработки строк:
\begin{lisp}
;;; True if the specified subsequence of the string is a \\*
;;; palindrome (reads the same forwards and backwards). \\*
\\*
(defun palindromep (string \cd{\&optional} \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~(start 0) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~(end (length string))) \\
~~(dotimes (k (floor (- end start) 2) {\true}) \\*
~~~~(unless (char-equal (char string (+ start k)) \\*
~~~~~~~~~~~~~~~~~~~~~~~~(char string (- end k 1))) \\*
~~~~~~(return {\false})))) \\
\\
(palindromep "Able was I ere I saw Elba") \EV\ {\true} \\
 \\
(palindromep "A man, a plan, a canal--Panama!") \EV\ {\false} \\
 \\
(remove-if-not \#'alpha-char-p~~~~~;\textrm{Удалить знаки препинания} \\*
~~~~~~~~~~~~~~~"A man, a plan, a canal--Panama!") \\*
~~~\EV\ "AmanaplanacanalPanama" \\
 \\
(palindromep \\*
~(remove-if-not \#'alpha-char-p \\*
~~~~~~~~~~~~~~~~"A man, a plan, a canal--Panama!")) \EV\ {\true} \\
 \\
(palindromep \\*
~(remove-if-not \\*
~~~\#'alpha-char-p \\*
~~~"Unremarkable was I ere I saw Elba Kramer, nu?")) \EV\ {\true} \\
 \\
(palindromep \\*
~(remove-if-not \\*
~~~\#'alpha-char-p \\*
~~~"A man, a plan, a cat, a ham, a yak, \\*
~~~~~~~~~~~~~~~~~~~a yam, a hat, a canal--Panama!")) \EV\ {\true}
\\
(palindromep \\*
~(remove-if-not \\*
~~~\#'alpha-char-p \\*
~~~"Ja-da, ja-da, ja-da ja-da jing jing jing")) \EV\ {\false}
\end{lisp}

Изменение значения переменной \emph{var} в теле цикла (с помощью \cdf{setq}
например) будет иметь непредсказуемые последствия, возможно зависящие от
реализации. Компилятор Common Lisp'а может вывести предупреждение о том, что
переменная-индекс используется в \cdf{setq}.
\end{defmac}

Смотрите также \cdf{do-symbols}, \cdf{do-external-symbols} и
\cdf{do-all-symbols}.

\subsection{Отображение}
\indexterm{mapping}

Отображение --- это тип цикла, в котором заданная функция применяется к частям
одной или более последовательностей. Результатом цикла является
последовательность, полученная из результатов выполнения это функции.
Существует несколько опции для указания того, какие части списка будут
использоваться в цикле, и что будет происходить с результатом применения
функции.

Функция \cdf{map} может быть использована для отображения любого типа
последовательности.
Следующие же функции оперируют только списками.

\begin{defun}[Функция]
mapcar function list &rest more-lists \\
maplist function list &rest more-lists \\
mapc function list &rest more-lists \\
mapl function list &rest more-lists \\
mapcan function list &rest more-lists \\
mapcon function list &rest more-lists

Для каждой из этих функций отображения,
первый аргумент является функцией и оставшиеся аргументы должны быть списками.
Функция в первом аргументе должно принимать столько аргументов, сколько было
передано списков в функцию отображения.

\cdf{mapcar} последовательно обрабатывает элементы списков.
Сначала функция применяется к \emph{car} элементу каждого списка,
затем к \emph{cadr} элементу, и так далее.
(Лучше всего, чтобы все переданные списки имели одинаковую длину. Если это не
так, то цикл завершиться, как только закончится самый короткий список, и все
оставшиеся элементы в других списках будут проигнорированы.)
Значение, возвращаемое \cdf{mapcar}, является списком результатов
последовательных вызовов функции из первого параметра.
Например:
\begin{lisp}
(mapcar \#'abs '(3 -4 2 -5 -6)) \EV\ (3 4 2 5 6) \\
(mapcar \#'cons '(a b c) '(1 2 3)) \EV\ ((a . 1) (b . 2) (c . 3))
\end{lisp}

\cdf{maplist} похожа на \cdf{mapcar} за исключением того, что функция
применяется к спискам и последующим \emph{cdr} элементам этих списков, а не
последовательно к элементам спискам.
Например:
\begin{lisp}
(maplist \#'(lambda (x) (cons 'foo x)) \\*
~~~~~~~~~'(a b c d)) \\*
~~~\EV\ ((foo a b c d) (foo b c d) (foo c d) (foo d))
\end{lisp}

\begin{lisp}
(maplist \#'(lambda (x) (if (member (car x) (cdr x)) 0 1))) \\*
~~~~~~~~~'(a b a c d b c)) \\*
~~~\EV\ (0 0 1 0 1 1 1) \\*
~~~;\textrm{Возвращается \cd{1}, если соответствующий элемент входящего списка} \\*
~~~;~\textrm{ появлялся последний раз в данном списке.}
\end{lisp}

\cdf{mapl} и \cdf{mapc} похожи на \cdf{maplist} и \cdf{mapcar}, соответственно,
за исключением того, что они не накапливают результаты вызова функций.

Эти функции используются, когда функция в первом параметре предназначена для
побочных эффектов, а не для возвращаемого значения.
Значение возвращаемое \cdf{mapl} или \cdf{mapc} является вторым аргументом, то
есть первой последовательностью для отображения.

\cdf{mapcan} и \cdf{mapcon} похожи на \cdf{mapcar} и \cdf{maplist}
соответственно, за исключением того, что результат создаётся с помощью функции
\cdf{nconc}, а не \cdf{list}. То есть, 
\begin{lisp}
(mapcon \emph{f} \emph{x1} ... \emph{xn}) \\
~~~\EQ\ (apply \#'nconc (maplist \emph{f} \emph{x1} ... \emph{xn}))
\end{lisp}
Такое же различие между \cdf{mapcan} и \cdf{mapcar}.
Концептуально, эти функции позволяют функции отображения возвращать переменное
количество элементов. Таким образом длина результата может быть не равна длине
входного списка.
Это, в частности, полезно для возврата нуля или одного элемента:
\begin{lisp}
(mapcan \#'(lambda (x) (and (numberp x) (list x))) \\
~~~~~~~~'(a 1 b c 3 4 d 5)) \\
~~~\EV\ (1 3 4 5)
\end{lisp}
В этом случае функция действует, как фильтр. Это стандартная Lisp'овая идиома
использования \cdf{mapcan}.
(Однако, в этом контексте функция \cdf{remove-if-not} также может быть полезна.)
Помните, что \cdf{nconc} деструктивная операция, следовательно и \cdf{mapcan} и
\cdf{mapcon} также деструктивны. Список возвращаемый функцией \emph{function}
изменяется для соединения и возврата результата.

Иногда \cdf{do} или прямая последовательная рекурсия удобнее, чем функции
отображения. Однако, функции отображения должны быть использованы везде, где они
действительно необходимы, так как они увеличивают ясность кода.

Функциональный аргумент функции отображения должен быть подходящим для функции
\cdf{apply}. Он не может быть макросом или именем оператора.
Кроме того, в качестве функционального аргумента можно использовать функцию,
имеющую \cd{\&optional} и \cd{\&rest} параметры.

Пользователь ограничен в создании побочных действий так, как это описано в
разделе~\ref{STRUCTURE-TRAVERSAL-SECTION}
\end{defun}

\subsection{Использование <<GOTO>>}

Реализации Lisp'а начиная с Lisp'а 1.5 содержат то, что изначально называлось
<<the program feature>>, как будто без этого невозможно писать программы!
Конструкция \cdf{prog} позволяет писать в Algol- или Fortran- императивном
стиле, используя выражения \cdf{go}, которые могут ссылаться на теги в теле
\cdf{prog}. Современный стиль программирования на Lisp'е стремится снизить
использование \cdf{prog}. Различные конструкции циклов, как \cdf{do}, имеют тела
с характеристиками \cdf{prog}.
(Тем не менее, возможность использовать выражения \cdf{go} внутри конструкции
цикла очень редко используется на практике.)

\cdf{prog} предоставляет три различные операции:
связывание локальный переменных,
использование выражения \cdf{return}
и использование выражения \cdf{go}.
В Common Lisp'е эти три операции были разделены на три конструкции:
\cdf{let}, \cdf{block} и \cdf{tagbody}.
Эти три конструкции могут использоваться независимо, как строительные кирпичики
для других типов конструкций.

\begin{defspec}
tagbody {tag | statement}*

Часть \cdf{tagbody} после списка переменные называется \emph{телом}.
Элемент тела может быть символов или целым числом, и называться в этом случае
\emph{тег}. Также элемент тела может быть списком, и называться в этом случае
\emph{выражением}.

Каждый элемент тела обрабатывается слева направо.
\emph{Теги} игнорируются. \emph{Выражения} вычисляются и их результаты
игнорируются. Если управление достигает конца тела, \cdf{tagbody} возвращает
{\false}.

Если вычисляется форма \cd{(go \emph{tag})}, управление перемещается на часть
тела, обозначенную \emph{тегом}.

Область видимости тегов, устанавливаемых в \cdf{tagbody}, является лексической. 
Продолжительность видимости тегов динамическая. Когда управление вышло из
конструкции \cdf{tagbody}, ссылка \cdf{go} на теги в её теле невозможны.
Существует возможность для \cdf{go} прыжка в \cdf{tagbody}, которая не находится
внутри конструкции \cdf{tagbody}, которая и содержала этот \cdf{go}. То есть
возможны прыжки в родительский \cdf{tagbody}.
Теги устанавливаемые \cdf{tagbody} будут только скрывать другие одноимённые
теги.

Лексическая область видимости для тегов (целей \cdf{go}) полностью полноправно и
последствия могут быть сюрпризом для пользователей и разработчиков других Lisp
систем.
Например, \cdf{go} в следующем примере, работает в Common Lisp так, как это и
ожидается:
\begin{lisp}
(tagbody \\*
~~~(catch 'stuff \\*
~~~~~~(mapcar \#'(lambda (x) (if (numberp x) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(hairyfun x) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(go lose))) \\*
~~~~~~~~~~~~~~items)) \\
~~~(return) \\*
~lose \\*
~~~(error "I lost big!"))
\end{lisp}
В зависимости от ситуации, \cdf{go} в Common Lisp'е не обязательно похож на
простую машинную инструкцию <<jump>>. Если необходимо, \cdf{go} может
перепрыгивать ловушки исключений. Возможно так, что <<замыкание>>, созданное с
помощью \cdf{function}, для лямбда-выражения ссылается на тег (цель \cdf{go})
так долго, сколько лексически доступен данный тег. Смотрите~\ref{SCOPE} для
понимания этого примера.
\end{defspec}

\begin{defmac}
prog ({var | (var [init])}*) {declaration}* {tag | statement}* \\
prog* ({var | (var [init])}*) {declaration}* {tag | statement}*

Конструкция \cdf{prog} является синтезом \cdf{let}, \cdf{block} и \cdf{tagbody},
позволяющая связывать переменные, использовать \cdf{return} и \cdf{go} в одной
конструкции. Обычно конструкция \cdf{prog} выглядит так:
\begin{lisp}
(prog (\emph{var1} \emph{var2} (\emph{var3} \emph{init3}) \emph{var4} (\emph{var5} \emph{init5})) \\*
~~~~~~\Mstar{\emph{declaration}} \\*
~~~~~~\emph{statement1} \\
~\emph{tag1} \\*
~~~~~~\emph{statement2} \\*
~~~~~~\emph{statement3} \\*
~~~~~~\emph{statement4} \\
~\emph{tag2} \\*
~~~~~~\emph{statement5} \\*
~~~~~~... \\*
~~~~~~)
\end{lisp}
Список после ключевого символа \cdf{prog} является множеством спецификаторов для
связывания переменных \emph{var1}, \emph{var2}.
Этот список обрабатывается так же, как и в выражении \cdf{let}:
сначала слева направо выполняются все формы \emph{init} (если формы нет, берётся
значение {\false}), и затем переменные параллельно связываются с полученными
ранее значениями. 
Возможно использовать \emph{декларации} в начале дела \cdf{prog} так же, как и в
\cdf{let}.

Тело \cdf{prog} выполняется, как обернутое в \cdf{tagbody}. Таким образом, для
перемещения управления к \emph{тегу} могут использоваться выражения \cdf{go}.

\cdf{prog} неявно устанавливает вокруг тела \cdf{block} с именем {\nil}. Это
значит, можно в любое время использовать \cdf{return} для выхода из конструкции \cdf{prog}.

Вот небольшой пример того, что можно сделать с помощью \cdf{prog}:
\begin{lisp}
(defun king-of-confusion (w) \\
~~"Take a cons of two lists and make a list of conses. \\
~~~Think of this function as being like a zipper." \\
~~(prog (x y z)~~~~~;\textrm{Инициализировать \cd{x}, \cd{y}, \cd{z} в {\false}} \\
~~~~~~~~(setq y (car w) z (cdr w)) \\
~~~loop \\
~~~~~~~~(cond ((null y) (return x)) \\
~~~~~~~~~~~~~~((null z) (go err))) \\
~~~rejoin \\
~~~~~~~~(setq x (cons (cons (car y) (car z)) x)) \\
~~~~~~~~(setq y (cdr y) z (cdr z)) \\
~~~~~~~~(go loop) \\
~~~err \\
~~~~~~~~(cerror "Will self-pair extraneous items" \\
~~~~~~~~~~~~~~~~"Mismatch - gleep!  ~S" y) \\
~~~~~~~~(setq z y) \\
~~~~~~~~(go rejoin)))
\end{lisp}
которые делает то же, что и:
\begin{lisp}
(defun prince-of-clarity (w) \\
~~"Take a cons of two lists and make a list of conses. \\
~~~Think of this function as being like a zipper." \\
~~(do ((y (car w) (cdr y)) \\
~~~~~~~(z (cdr w) (cdr z)) \\
~~~~~~~(x '{\emptylist} (cons (cons (car y) (car z)) x))) \\
~~~~~~((null y) x) \\
~~~~(when (null z) \\
~~~~~~(cerror "Will self-pair extraneous items" \\
~~~~~~~~~~~~~~"Mismatch - gleep!  ~S" y) \\
~~~~~~(setq z y))))
\end{lisp}

Конструкция \cdf{prog} может быть выражена в терминах более простых конструкций
\cdf{block}, \cdf{let} и \cdf{tagbody}:
\begin{lisp}
(prog \emph{variable-list} \Mstar{\emph{declaration}} . \emph{body}) \\
~~~\EQ\ (block nil (let \emph{variable-list} \Mstar{\emph{declaration}} (tagbody . \emph{body})))
\end{lisp}

Оператор \cdf{prog*} очень похож на \cdf{prog}. Одно отличие в том,
что связывание и инициализация переменных осуществляется \emph{последовательно},
тем самым форма \emph{init} использовать значения ранее связанных переменных.
Таким образом \cdf{prog*} относится к \cdf{prog}, как \cdf{let*} к \cdf{let}.
Например,
\begin{lisp}
(prog* ((y z) (x (car y))) \\
~~~~~~~(return x))
\end{lisp}
возвращает \emph{car} элемент значения \cd{z}.
\end{defmac}

\begin{defspec}
go tag

Оператор \cd{(go \emph{tag})} используется для применения <<goto>>
внутри конструкции \cdf{tagbody}. \emph{tag} должен быть символов или целым
числом. \emph{tag} не вычисляется.
\cdf{go} переносит управление на точку тела, которая была помечена тегом равным
\cdf{eql} заданному. Если такого тега в теле нет, поиск осуществляется в
лексически доступном теле другой конструкции \cdf{tagbody}.
Использоваться \cdf{go} с тегом, которого нет, является ошибкой.

Форма \cdf{go} никогда не возвращает значение.

В целях хорошего стиля, рекомендуется дважды подумать, прежде чем использовать
\cdf{go}. Большинство функций \cdf{go} могут быть заменены циклами, вложенными
условными формами или \cdf{return-from}. Если использование \cdf{go} неизбежно,
рекомендуется управляющую структуру реализованную с помощью \cdf{go} <<упаковать>>
в определении макроса. 
\end{defspec}

\section{Перечисление элементов структур данных и побочные эффекты}
\label{STRUCTURE-TRAVERSAL-SECTION}

В момент выполнения некоторых системных операций (функций, операторов), в
которых может вызываться пользовательский код (например, при использовании
\cdf{sort}), для этого кода запрещены побочные эффекты (действия).

Рассмотрим следующий пример:
\begin{lisp}
(let ((x '(apples peaches pumpkin pie))) \\*
~~(dolist (z x) \\*
~~~~(when (eq z 'peaches) \\*
~~~~~~(setf (cddr x) '(mango kumquat))) \\*
~~~~(format t "~S " (car z))))
\end{lisp}
В зависимости от особенностей реализации \cdf{dolist}, данный код может просто
вывести
\begin{lisp}
apples peaches mango kumquat
\end{lisp}
(что скорее всего и ожидается), но может также вывести и
\begin{lisp}
apples peaches pumpkin pie
\end{lisp}
Вот вероятная реализация \cdf{dolist} для первого варианта
\begin{lisp}
(defmacro dolist ((var listform \&optional (resultform ''nil)) \\*
~~~~~~~~~~~~~~~~~~\&body body) \\*
~~(let ((tailvar (gensym "DOLIST"))) \\*
~~~~{\Xbq}(do ((,tailvar ,listform (cdr ,tailvar))) \\*
~~~~~~~~~((null ,tailvar) ,resultform) \\*
~~~~~~~(let ((,var (car ,tailvar))) ,@body))
\end{lisp}
А вот вероятная реализация \cdf{dolist} для второго варианта
\begin{lisp}
(defmacro dolist ((var listform \&optional (resultform ''nil)) \\*
~~~~~~~~~~~~~~~~~~\&body body) \\*
~~(let ((tailvar (gensym "DOLIST"))) \\*
~~~~{\Xbq}(do ((,tailvar ,listform)) \\*
~~~~~~~~~((null ,tailvar) ,resultform) \\*
~~~~~~~(let ((,var (pop ,tailvar))) ,@body))
\end{lisp}

В общем случае, деструктивная модификация структуры, которая может нарушить
порядок перечисления элементов, запрещена. Частные случаи
перечислены ниже.

Для операций перечисления элементов списка, \emph{cdr} цепочка не может быть
деструктивно модифицирована.

Для операций, которые перечисляют элементы массива, данный массив не может быть
расширен (смотрите \cdf{adjust-array}) и, при наличии, не может быть изменен
указатель заполнения.

Для операций перечисления элементов хеш-таблицы (таких как
\cdf{with-hash-table-iterator} и \cdf{maphash}, в пользовательком коде не могут
добавляться в данную таблицу новые элементы.

Для операций перечисления символов пакета (например, \cdf{with-package-iterator}
и \cdf{do-symbols}) в пакет не могут интернироваться, дезинтернироваться новые
символы, которые относятся к данному пакету. Однако текущий обрабатываемый
символ может быть дезинтернирован.

Деструктивные операции, такие как \cdf{delete}, требуют более жёстких
ограничений и эти ограничения описаны отельно в каждой функции.

Таблица~\ref{TRAVERSAL-OPERATIONS-TABLE} содержит большинство операций и функций
запрещающих побочные эффекты в пользовательском коде, которые в них передаются в
качестве тела для исполнения или в виде функционального объекта.

Кроме того, следует отметить, что пользовательский код не должен модифицировать
структуру списка, которая интерпретируется вычислителем, который был вызван
неявно или явно с помощью \cdf{eval}. Например, как в случае функции-ловушки
(функция вывода \cdf{defstruct}, значение \cdf{*evalhook*} или
\cdf{*applyhook*}, и так далее), которая является замыканием интерпретируемого
кода.
Также, функции вывода \cdf{defstruct} и другие ловушки не должны выполнять
побочные действия над выводимыми структурами, или над строками переданными в
\cdf{make-string-input-stream}. В целом, будте бдительны.

Следует отметить, что такие операции как \cdf{mapcar} или \cdf{dolist} работают
не только с \emph{cdr} указателями (при прохождении к концу списка), но также и
с \emph{car} указателями (при обработке непосредственно элемента). Ограничения
побочных эффектов относятся и к одному, и ко второму указателям.

\begin{table}[t]
\leavevmode
\caption{Операции не допускающие побочных действий в пользовательском коде}
\label{TRAVERSAL-OPERATIONS-TABLE}

\begingroup\cf \tabcolsep0pt\relax
\begin{tabular*}{\textwidth}{@{}l@{\extracolsep{\fill}}ll@{}}
adjoin & maphash & reduce \\
assoc & mapl & remove \\
assoc-if & maplist & remove-duplicates \\
assoc-if-not & member & remove-if \\
count & member-if & remove-if-not \\
count-if & member-if-not & search \\
count-if-not & merge & set-difference \\
delete & mismatch & set-exclusive-or \\
delete-duplicates & nintersection & some \\
delete-if & notany & sort \\
delete-if-not & notevery & stable-sort \\
do-all-symbols & nset-difference & sublis \\
do-external-symbols & nset-exclusive-or & subsetp \\
do-symbols & nsublis & subst \\
dolist & nsubst & subst-if \\
eval & nsubst-if & subst-if-not \\
every & nsubst-if-not & substitute \\
find & nsubstitute & substitute-if \\
find-if & nsubstitute-if & substitute-if-not \\
find-if-not & nsubstitute-if-not & tree-equal \\
intersection & nunion & union \\
\textrm{некоторые} loop \textrm{выражения} & position & with-hash-table-iterator \\
map & position-if & with-input-from-string \\
mapc & position-if-not & with-output-to-string \\
mapcan & rassoc & with-package-iterator \\
mapcar & rassoc-if \\
mapcon & rassoc-if-not
\end{tabular*}
\endgroup
\end{table}

\section{Возврат и обработка нескольких значений}
\indexterm{multiple values}

Обычно результатом вызова Lisp'овой функции является один Lisp'овый объект.
Однако, иногда для функции удобно вычислить несколько объектов и вернуть их.
Common Lisp представляет механизм для прямой обработки нескольких значений.
Механизм удобнее и эффективнее, чем исполнение трюков со списками или
глобальными переменными.

\subsection{Конструкции для обработки нескольких значений}

Обычно не используется несколько значений. Для возврата и обработки
нескольких значений требуются операторы. Если вызывающий функцию код
не требует нескольких значений, однако вызываемая функция возвращает их
несколько, то для кода берётся только первое значение. Все оставшиеся
значения игнорируются.  Если вызываемая функция возвращает ноль
значений, вызывающий код в качестве значения получает {\false}.

\cdf{values} --- это главный примитив для возврата нескольких значений. Он
принимает любое количество аргументов и возвращает столько же значений. Если
последняя форма тела функции является \cdf{values} с тремя аргументами, то вызов
такой функции вернёт три значения.
Другие операторы также возвращают несколько значений, но они могут быть
описаны в терминах \cdf{values}. Некоторые встроенные Common Lisp функции, такая
как \cdf{floor}, возвращают несколько значений.

Операторы, обрабатывающие несколько значений, представлены ниже:
\begin{lisp}
multiple-value-list \\
multiple-value-call \\
multiple-value-prog1 \\
multiple-value-bind \\
multiple-value-setq
\end{lisp}
Они задают форму для вычисления и указывают куда поместить значения возвращаемые
данной формой.

\begin{defun}[Функция]
values &rest args

Все аргументы в таком же порядке возвращаются, как значения.
Например,
\begin{lisp}
(defun polar (x y) \\
~~(values (sqrt (+ (* x x) (* y y))) (atan y x))) \\
 \\
(multiple-value-bind (r theta) (polar 3.0 4.0) \\
~~(vector r theta)) \\
~~~\EV\ \#(5.0 0.9272952)
\end{lisp}

Выражение \cd{(values)} возвращает ноль значений. Это стандартная идиома для
возврата из функции нулевого количества значений.

Иногда необходимо указать явно, что функция будет возвращать только одно
значение. Например, функция
\begin{lisp}
(defun foo (x y) \\
~~(floor (+ x y) y))
\end{lisp}
будет возвращать два значения, потому что \cdf{floor} возвращает два
значения. Может быть второе значение не имеет смысла в данном контексте, или
есть причины не тратить время на вычисления второго значения. Функция
\cdf{values} является стандартной идиомой для указания того, что будет
возвращено только одно значение, как показано в следующем примере.
\begin{lisp}
(defun foo (x y) \\
~~(values (floor (+ x y) y)))
\end{lisp}
Это работает, потому что \cdf{values} возвращает только \emph{одно} значения для
каждой формы аргумента. Если форма аргумента возвращает несколько значений, то
используется только первое, а остальные игнорируются.

В Common Lisp'е для вызывающего кода нет возможности различить, было ли
возвращено просто одно значение или было возвращено только одно значение в с
помощью \cdf{values}. Например значения, возвращённые выражением \cd{(+~1~2)} и 
\cd{(values (+~1~2))}, идентичны во всех отношениях: они оба просто равны \cd{3}.
\end{defun}

\begin{defun}[Константа]
multiple-values-limit

Значение \cdf{multiple-values-limit} является положительным целым числом,
которое невключительно указывает наибольшее возможное количество возвращаемых
значений. Это значение зависит от реализации, но не может быть менее 20.
(Разработчики рекомендуется делать это ограничение как можно большим без потери
в производительности.)
Смотрите \cdf{lambda-parameters-limit} и \cdf{call-arguments-limit}.
\end{defun}

\begin{defun}[Функция]
values-list list

Все элементы списка \emph{list} будут возвращены как несколько значений.
Например:
\begin{lisp}
(values-list (list a b c)) \EQ\ (values a b c)
\end{lisp}
Можно обозначить так,
\begin{lisp}
(values-list \emph{list}) \EQ\ (apply \#'values \emph{list})
\end{lisp}
но \cdf{values-list} может быть более ясным или эффективным.
\end{defun}

\begin{defmac}
multiple-value-list form

\cdf{multiple-value-list} вычисляет форму \emph{form} и возвращает список из
того количества значений, которое было возвращено формой.
Например,
\begin{lisp}
(multiple-value-list (floor -3 4)) \EV\ (-1 1)
\end{lisp}
Таким образом, \cdf{multiple-value-list} и \cdf{values-list} являются
антиподами. FIXME
\end{defmac}

\begin{defspec}
multiple-value-call function {form}*

\cdf{multiple-value-call} сначала вычисляет \emph{function} для получения
функции и затем вычисляет все формы \emph{forms}. Все значения форм \emph{forms}
собираются вместе (все, а не только первые) и передаются как аргументы
функции. Результат \cdf{multiple-value-call} является тем, что вернула функция.
Например:
\begin{lisp}
(+ (floor 5 3) (floor 19 4)) \\
~~~\EQ\ (+ 1 4) \EV\ 5 \\
(multiple-value-call \#'+ (floor 5 3) (floor 19 4)) \\
~~~\EQ\ (+ 1 2 4 3) \EV\ 10 \\
(multiple-value-list \emph{form}) \EQ\ (multiple-value-call \#'list \emph{form})
\end{lisp}
\end{defspec}

\begin{defspec}
multiple-value-prog1 form {form}*

\cdf{multiple-value-prog1} вычисляет первую форму \emph{form} и сохраняет все
значения, возвращённые данной формой. Затем она слева направо вычисляет оставшиеся
\emph{формы}, игнорируя их значения. Значения, возвращённые первой формой,
становятся результатом всей формы \cdf{multiple-value-prog1}. Смотрите
\cdf{prog1}, которая всегда возвращает одно значение.
\end{defspec}

\begin{defmac}
multiple-value-bind ({var}*) values-form
                    {declaration}* {form}*

Вычисляется \emph{values-form} и каждое значение результата связывается
соответственно с переменными указанными в первом параметре.
Если переменных больше, чем возвращаемых значений, для оставшихся переменных
используется значение {\false}. Если значений больше, чем переменных, лишние
значения игнорируются. Переменные связываются со значениями только на время
выполнения форм тела, которое является неявным \cdf{progn}.
Например:
\begin{lisp}
(multiple-value-bind (x) (floor 5 3) (list x)) \EV\ (1) \\
(multiple-value-bind (x y) (floor 5 3) (list x y)) \EV\ (1 2) \\
(multiple-value-bind (x y z) (floor 5 3) (list x y z)) \\
~~~\EV\ (1 2 {\false})
\end{lisp}
\end{defmac}

\begin{defmac}
multiple-value-setq variables form

Аргумент \emph{variables} должен быть списком переменных. Вычисляется форма
\emph{form} и переменным \emph{присваиваются} (не связываются) значения,
возвращённые этой формой. Если переменных больше, чем значений, оставшимся
переменным присваивается {\false}. Если значений больше, чем переменных, лишние
значения игнорируются.

\cdf{multiple-value-setq} всегда возвращает одно значение, которое является
первым из возвращённых значений формы \emph{form}, или {\false}, если форма
\emph{form} вернула ноль значений.
\end{defmac}

\begin{defmac}*
nth-value n form

Формы аргументов \emph{n} и \emph{form} вычисляются.
Значение \emph{n} должно быть неотрицательным целым, и форма \emph{form} должна
возвращать любое количество значение.
Целое число \emph{n} используется, как индекс (начиная с нуля), для доступа к
списку значений.
Форма возвращает элемент в позиции \emph{n} из списка результатов вычисления
формы \emph{form}. Если позиции не существует, возвращается \cdf{nil}.

В качестве примера, \cdf{mod} мог бы быть определён так:
\begin{lisp}
(defun mod (number divisor) \\*
~~(nth-value 1 (floor number divisor)))
\end{lisp}
\end{defmac}

\subsection{Правила управления возвратом нескольких значений}

Часто случается так, что значение оператора или макроса определено как
значение одного из подвыражений.
Например, значение \cdf{cond} является значением последнего подвыражения в
исполняемой ветке.

В большинстве таких случаев, если подвыражение возвращает несколько значений,
тогда и оригинальная форма возвращает все эти значения. Эта \emph{передача
  значений}, конечно, не будет иметь место, если не была выполнена специальная
форма для обработки возврата нескольких значений.

Из операторов может быть неявно возвращено несколько значений в
соответствие со следующими правилами: 

\goodbreak
\begin{flushdesc}
\item[\emph{Вычисление и применение}]\leavevmode
\begin{itemize}

\item
\cdf{eval} возвращает несколько значений, если переданная ему форму при
вычислении вернула несколько значений.

\item
\cdf{apply}, \cdf{funcall} и \cdf{multiple-value-call} передают обратно
несколько значений из применяемой или вызываемой функции.
\end{itemize}

\item[\emph{В контексте неявного \cdf{progn}}]\leavevmode
\begin{itemize}

\item
Оператор \cdf{progn}
передаёт обратно несколько значений полученных при вычислении последней
подформы. В другие ситуациях, называемых <<неявный \cdf{progn}>>, в которых
вычисляется несколько форм и результаты всех, кроме последней формы,
игнорируются, также передаётся обратно несколько значений от формы.
Такие ситуации включают тело лямбда-выражения, в частности в \cdf{defun},
\cdf{defmacro} и \cdf{deftype}.
Также включаются тела конструкций
\cdf{eval-when},
\cdf{progv}, \cdf{let},
\cdf{let*}, \cdf{when}, \cdf{unless},
\cdf{block},
\cdf{multiple-value-bind} и \cdf{catch}.
И также включаются подвыражения условных конструкций 
\cdf{case}, \cdf{typecase},
\cdf{ecase}, \cdf{etypecase}, \cdf{ccase} и \cdf{ctypecase}.
\end{itemize}
\end{flushdesc}

\begin{flushdesc}
\item[\emph{Условные конструкции}]\leavevmode
\begin{itemize}

\item
\cdf{if} передаёт обратно несколько значений из любой выбранной подформы (ветки
\emph{then} или \emph{else}).

\item
\cdf{and} и \cdf{or} передают обратно несколько значений из последней подформы,
но ни из какой другой непоследней подформы.

\item
\cdf{cond} передаёт обратно несколько значений из последней подформы неявного
\cdf{progn} выделенного подвыражения.
Однако, если выделенное подвыражение является <<синглтоном>>, будет возвращено
только одно значение (не-{\false} значение предиката).
Это верно, даже если выражение <<синглтон>> является последним подвыражением
\cdf{cond}.
Нельзя рассматривать последнее подвыражение \cdf{(x)}, как будто оно \cd{(t
  x)}. Последнее подвыражение передаёт обратно несколько значений из формы
\cd{x}.
\end{itemize}

\item[\emph{Возврат из блока}]\leavevmode
\begin{itemize}

\item
При нормальном завершении конструкция \cdf{block} передаёт обратно несколько значений из её последней
подформы. Если для завершения использовалась \cdf{return-from} (или
\cdf{return}), тогда \cdf{return-from} передаёт обратно несколько значений из
своей подформы, как значения всей конструкции  \cdf{block}. Другие конструкции,
создающие неявные блоки, такие как 
\cdf{do}, \cdf{dolist}, \cdf{dotimes}, \cdf{prog} и
\cdf{prog*}, также передают обратно несколько значений, заданных с помощью 
\cdf{return-from} (или \cdf{return}).

\item
\cdf{do} передаёт обратно несколько значений из последней формы подвыражения
выхода, точно также, как если бы подвыражение выхода было подвыражение
\cdf{cond}.
Подобным образом действуют \cdf{dolist} и \cdf{dotimes}. Они возвращают
несколько значений из формы \emph{resultform}, если она была выполнена.
Эти ситуации также являются примерами явного использования \cdf{return-from}.
\end{itemize}

\item[\emph{Выход из ловушки исключения}]\leavevmode
\begin{itemize}

\item
Конструкция \cdf{catch} возвращает несколько значений, если результат формы в
\cdf{throw}, которая осуществляет выход из этого catch, возвращает несколько
значений.
\end{itemize}

\item[\emph{Остальные ситуации}]\leavevmode
\begin{itemize}

\item
\cdf{multiple-value-prog1} передаёт обратно несколько значений из его первой
подформы. Однако, \cdf{prog1} всегда возвращает одно значение.

\item
\cdf{unwind-protect} возвращает несколько значений, если форма, которую он
защищает, вернула несколько значений.

\item
\cdf{the} возвращает несколько значений, если в нем содержащаяся форма
возвращает несколько значений.
\end{itemize}
\end{flushdesc}

\cdf{prog1},
\cdf{prog2}, \cdf{setq} и \cdf{multiple-value-setq} --- это формы, которые
\emph{никогда} не передают обратно несколько значений.
Стандартный метод для явного указания возврата одного значения из формы \cd{x} 
является запись \cd{(values x)}.

Наиболее важное правило насчёт нескольких значений:
\textbf{Не важно сколько значений возвращает форма, если форма является
  аргументом в вызове функции, то будет использовано только одно значение
  (первое).} 

Например, если вы записали \cd{(cons (floor x))}, тогда \cdf{cons} всегда
получить \emph{только} один аргумент (что, конечно, является ошибкой), хотя и
\cdf{floor} возвращает два значения. Для того, чтобы поместить оба значения
\cdf{floor} в \cdf{cons}, можно записать что-то вроде этого:
\cd{(multiple-value-call \#'cons (floor x))}.
В обычном вызове функции, каждый форма аргумента предоставляется только
\emph{один} аргумент. Если такая форма возвращает ноль значение, в качестве
аргумента используется {\false}. А если возвращает более одного значения, все
они, кроме первого, игнорируются.
Также и условные конструкции, например \cdf{if}, которые проверяют значения
формы, используют только одно первое значение, остальные игнорируются.
Такие конструкции будут использовать {\false} если форма вернула ноль значений.

\section{Динамические нелокальные выходы}
\label{CATCH-THROW-SECTION}
\indexterm{non-local exit}
\indexterm{dynamic exit}
%\indexterm{catch}
%\indexterm{throw}

Common Lisp предоставляет функциональность для выхода из сложного процесса в
нелокальном, динамических ограниченном стиле. Для этих целей есть два вида
операторов, называемых \emph{catch} и \emph{throw}.
Форма catch выполняет некоторые подформы так, что если форма throw выполняется в
ходе этих вычислений, в данной точке вычисления прерываются и форма catch
немедленно возвращает значение указанное в throw. В отличие от \cdf{block} и
\cdf{return} (раздел~\ref{BLOCK-RETURN-SECTION}), которые позволяют выйти из
тела \cdf{block} из любой точки лексически, находящейся внутри тела, \cd{catch/throw}
механизм работает, даже если форма \cd{throw} по тексту не находится внутри тела
формы \cd{catch}.
Throw может использовать только в течение (продолжительности времени) выполнения
тела catch. Можно провести аналогию между ними, как между динамически
связываемыми переменными и лексически связываемыми.

\begin{defspec}
catch tag {form}*

Оператор \cdf{catch} служит мишенью для передачи управления с помощью
\cdf{throw}.
Первой выполняется форма \emph{tag} для создания объекта для имени catch.
Он может быть любым Lisp'овым объектом.
Затем устанавливается ловушка с тегом, в качестве которого используется этот
объект.
Формы \emph{form} выполняются как неявный \cdf{progn},
и возвращается результат последней формы.
Однако если во время вычислений будет выполнена форма \cdf{throw} с тегом,
который равен \cdf{eq} тегу catch, то управление немедленно прерывается и
возвращается результат указанный в форме throw.
Ловушка, устанавливаемая с помощью \cdf{catch}, упраздняется перед тем, как
будет возвращён результат.

Тег используется для соотнесения throws и catches.
\cd{(catch 'foo \emph{form})} будет перехватывать \cd{(throw 'foo \emph{form})},
но не будет \cd{(throw 'bar \emph{form})}. Если \cdf{throw} выполнен без
соответствующего \cdf{catch}, готового его обработать, то это является ошибкой.

Теги catch сравниваются с использованием \cdf{eq}, а не \cdf{eql}.
Таким образом числа и буквы не могут использоваться в качестве
тегов.
\end{defspec}

\indexterm{unwind protection}
\indexterm{cleanup handler}
\begin{defspec}
unwind-protect protected-form {cleanup-form}*

Иногда необходимо выполнить форму и быть уверенным, что некоторые побочные
эффекты выполняются после её завершения.
Например:
\begin{lisp}
(progn (start-motor) \\*
~~~~~~~(drill-hole) \\*
~~~~~~~(stop-motor))
\end{lisp}
Функциональность нелокальных выходов в Common Lisp создаёт ситуацию, в которой
однако данный код может не сработать правильно.
Если \cd{drill-hole} может бросить исключение в ловушку, находящуюся выше
данного \cdf{progn}, то \cd{(stop-motor)} никогда не выполниться.
Более удобный пример с открытием/закрытием файлов:
\begin{lisp}
(prog2 (open-a-file) \\*
~~~~~~~(process-file) \\*
~~~~~~~(close-the-file))
\end{lisp}
где закрытие файла может не произойти, по причине ошибки в функции
\cd{process-file}.

Для того, чтобы вышеприведённый код работал корректно, можно переписать его с
использованием \cdf{unwind-protect}:
\begin{lisp}
;; Stop the motor no matter what (even if it failed to start). \\*
\\*
(unwind-protect \\*
~~(progn (start-motor) \\*
~~~~~~~~~(drill-hole)) \\*
~~(stop-motor))
\end{lisp}
Если \cdf{drill-hole} бросит исключение, которое попытается выйти из блока
\cdf{unwind-protect}, то \cd{(stop-motor)} будет обязательно выполнена.

Этот пример допускает то, что вызов \cdf{stop-motor} корректен, даже если
мотор ещё не был запущен. Помните, что ошибка или прерывание может осуществить
выход перед тем, как будет проведена инициализация. Любой код по восстановлению
состояния должен правильно работать вне зависимости от того, где произошла
ошибка.
Например, следующий код неправильный:
\begin{lisp}
(unwind-protect \\*
~~(progn (incf *access-count*) \\*
~~~~~~~~~(perform-access)) \\*
~~(decf *access-count*))
\end{lisp}
Если выход случиться перед тем, как выполниться операция \cdf{incf}, то
выполнение \cdf{decf} приведён к некорректному значению в \cd{*access-count*}.
Правильно будет записать этот код так:
\begin{lisp}
(let ((old-count *access-count*)) \\
~~(unwind-protect \\
~~~~(progn (incf *access-count*) \\
~~~~~~~~~~~(perform-access)) \\
~~~~(setq *access-count* old-count)))
\end{lisp}

Как правило, \cdf{unwind-protect} гарантирует выполнение форм
\emph{cleanup-form} перед выходом, как в случае нормального выхода, так и в
случае генерации исключения.
(Если, однако, выход случился в ходе выполнения форм \emph{cleanup-form},
никакого специального действия не предпринимается. Формы \emph{cleanup-form} не
защищаются. Для этого необходимо использовать дополнительные
конструкции \cdf{unwind-protect}.)
\cdf{unwind-protect} возвращает результат выполнения защищённой формы
\emph{protected-form} и игнорирует все результаты выполнения форм чистки
\emph{cleanup-form}.

Следует подчеркнуть, что \cdf{unwind-protect} защищает против \emph{всех}
попыток выйти из защищённой формы, включая не только <<динамический выход>> с
помощью \cdf{throw}, но и также <<лексический выход>> с помощью \cdf{go} и
\cdf{return-from}. Рассмотрим следующую ситуацию:
\begin{lisp}
(tagbody \\
~~(let ((x 3)) \\
~~~~(unwind-protect \\
~~~~~~(if (numberp x) (go out)) \\
~~~~~~(print x))) \\
~out \\
~~...)
\end{lisp}
Когда выполнится \cdf{go}, то сначала выполнится \cdf{print}, а затем перенос управления
на тег \cd{out} будет завершён.
\end{defspec}

\begin{defspec}
throw tag result

Оператор \cdf{throw} переносит управление к соответствующей конструкции
\cdf{catch}.
Сначала выполняется \emph{tag} для вычисления объекта, называемого тег
throw. Затем вычисляется форма результата \emph{result}, и этот результат
сохраняется (если форма \emph{result} возвращает несколько значений, то
\emph{все} значения сохраняются).
Управление выходит и самого последнего установленного catch, тег которого
совпадает с тегом throw. Сохранённые результаты возвращаются, как значения
конструкции \cdf{catch}.
Теги catch и throw совпадают, только если они равны \cdf{eq}.

В процессе, связывания динамических переменных упраздняются до точки catch, и
выполнятся все формы очистки в конструкциях unwind-protect.
Форма \emph{result} вычисляется перед началом процесса раскручивания, и её
значение возвращается из блока catch.

Если внешний блок catch с совпадающим тегом не найден, раскрутка стека не
происходит и сигнализируется ошибка.
Когда ошибка сигнализируется, ловушки и динамические связывания переменных
являются теми, которые были в точке throw.
\end{defspec}
\fi