macro.tex

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

\clearpage\def\pagestatus{ULTIMATE}

\ifx \rulang\Undef

\chapter{Macros}
\label{MACROS}

The Common Lisp macro facility allows the user to define arbitrary
functions that convert certain Lisp forms into different forms before
evaluating or compiling them.  This is done at the expression level,
not at the character-string level as in most other languages.  Macros
are important in the writing of good code: they make it possible to
write code that is clear and elegant at the user level but that is
converted to a more complex or more efficient internal form for
execution.

When \cdf{eval} is given a list whose \emph{car} is a symbol, it looks
for local definitions of that symbol (by \cdf{flet}, \cdf{labels},
and \cdf{macrolet}); if that fails, it looks for a global definition.
If the definition is a macro definition, then the original
list is said to be a \emph{macro call}.  Associated with the definition
will be a function of two arguments, called the \emph{expansion function}.
This function is called with the entire macro call as its first argument
(the second argument is a lexical environment);
it must return some new Lisp form, called the \emph{expansion} of the
macro call.  (Actually, a more general mechanism is involved;
see \cdf{macroexpand}.)
This expansion is then evaluated in place of the original
form.

When a function is being compiled, any macros it contains are expanded
at compilation time.  This means that a macro definition must be seen by the
compiler before the first use of the macro.

More generally, an implementation of Common Lisp has great latitude in deciding
exactly when to expand macro calls within a program.  For example,
it is acceptable for the \cdf{defun} special operator to expand all macro
calls within its body at the time the \cdf{defun} form is executed
and record the fully expanded body as the body of the function
being defined.
(An implementation might even choose always to compile functions defined
by \cdf{defun}, even when operating in an ``interpretive'' mode.)

Macros should be written so as to depend as little as possible
on the execution environment to produce a correct expansion.  To ensure
consistent behavior, it is best to ensure that all macro definitions are
available, whether to the interpreter or compiler, before any code
containing calls to those macros is introduced.

In Common Lisp, macros are not functions.
In particular, macros cannot be used as
functional arguments to such functions as \cdf{apply}, \cdf{funcall},
or \cdf{map}; in such situations, the list representing the ``original macro
call'' does not exist, and cannot exist, because in some sense the arguments
have already been evaluated.

\section{Macro Definition}

The function \cdf{macro-function} determines whether a given symbol
is the name of a macro.  The \cdf{defmacro} construct provides
a convenient way to define new macros.

\begin{defun}[Function]
macro-function symbol &optional env

The first argument must be a symbol.  If the symbol has a function definition
that is a macro definition, whether a local one established in the
environment \emph{env} by \cdf{macrolet} or a global one established as
if by \cdf{defmacro},
then the expansion function
(a function of two arguments, the macro-call form and an environment)
is returned.
If the symbol has no function definition, or has a definition
as an ordinary function or as a special operator but not as a macro, then
{\false} is returned.  The function \cdf{macroexpand} or \cdf{macroexpand-1}
is the best way to invoke the expansion function.

It is possible for \emph{both} \cdf{macro-function} and \cdf{special-operator-p}
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}.

\cdf{setf} may be used with \cdf{macro-function} to install
a macro as a symbol's global function definition:
\begin{lisp}
(setf (macro-function \emph{symbol}) \emph{fn})
\end{lisp}
The value installed must be a function that accepts two arguments,
an entire macro call and an environment, and computes the expansion for that call.
Performing this operation causes the symbol to have \emph{only} that
macro definition as its global function definition; any previous
definition, whether as a macro or as a function, is lost.
One cannot use \cdf{setf} to establish a local macro definition;
it is an error to supply a second argument to \cdf{macro-function}
when using it with \cdf{setf}.
It is an error to attempt to redefine the name of a special operator.

See also \cdf{compiler-macro-function}.
\end{defun}

\begin{defmac}
defmacro name lambda-list <{declaration}* | doc-string> {form}*

\cdf{defmacro} is a macro-defining macro that
arranges to decompose the macro-call form in an elegant and useful way.
\cdf{defmacro} has essentially the same syntax as \cdf{defun}: \emph{name} is the
symbol whose macro definition we are creating, \emph{lambda-list} is similar in
form to a lambda-list, and
the \emph{form\/}s constitute the body of the expander function.
The \cdf{defmacro} construct arranges to install this expander function,
as the global macro definition of \emph{name}.

While defining forms normally appear at top level,
it is meaningful to place them in non-top-level contexts.
Furthermore, \cdf{defmacro} should define the expander function
within the enclosing lexical environment, not within the global
environment.

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

The \emph{name} is returned
as the value of the \cdf{defmacro} form.

If we view the 
macro call as a list containing a function name and some argument forms,
in effect the expander function and the list of (unevaluated) argument
forms is given to \cdf{apply}.
The parameter specifiers are processed as for any lambda-expression,
using the macro-call argument forms as the arguments.
Then the body forms are evaluated
as an implicit \cdf{progn}, and the value of the last form
is returned as the expansion of the macro call.

If the optional documentation string \emph{doc-string} is present (if not
followed by a declaration, it may be
present only if at least one \emph{form} is also specified, as it is
otherwise taken to be a \emph{form}), then it is attached to the \emph{name}
as a documentation string of type \cdf{function}; see \cdf{documentation}.

These three markers are now allowed in other constructs as well.
\begin{indentdesc}{6pc}
\item[\cd{\&body}]
This is identical in function to \cd{\&rest}, but it informs certain
output-formatting and editing functions that the remainder of the form is
treated as a body and should be indented accordingly.
(Only one of \cd{\&body} or \cd{\&rest} may be used.)

\item[\cd{\&whole}]
This is followed by a single variable that is bound to the
entire macro-call form; this is the value that the macro definition function
receives as its single argument.
\cd{\&whole} and the following variable should appear first in the lambda-list,
before any other parameter or lambda-list keyword.

\item[\cd{\&environment}]
This is followed by a single variable that is bound
to an environment representing the lexical environment in which the
macro call is to be interpreted.   This environment may not be the
complete lexical environment; it should be used only with
the function \cdf{macroexpand} for the sake of any local
macro definitions that the \cdf{macrolet} construct may have
established within that lexical environment.  This is useful primarily
in the rare cases where a macro definition must explicitly expand any macros
in a subform of the macro call before computing its own expansion.
\end{indentdesc}
See \cdf{lambda-list-keywords}.

\begin{newer}
X3J13 voted in March 1989 \issue{MACRO-ENVIRONMENT-EXTENT}
to specify that macro environment objects received with the \cd{\&environment}
argument of a macro function
have only dynamic extent.  The consequences are undefined if such objects are
referred to outside the dynamic extent of that particular
invocation of the macro function.
This allows implementations to use somewhat more efficient techniques
for representing environment objects. 
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{DEFMACRO-LAMBDA-LIST} to clarify the permitted
uses of \cd{\&body}, \cd{\&whole}, and \cd{\&environment}:
\begin{itemize}
\item \cd{\&body} may appear at any level of a \cdf{defmacro} lambda-list.
\item \cd{\&whole} may appear at any level of a \cdf{defmacro} lambda-list.
At inner levels a \cd{\&whole} variable is bound to that part of the argument
that matches the sub-lambda-list in which \cd{\&whole} appears.  No matter where
\cd{\&whole} is used, other parameters or lambda-list keywords may follow it.
\item \cd{\&environment} may occur only at the outermost level of a \cdf{defmacro}
lambda-list, and it may occur at most once, but it may occur anywhere within
that lambda-list, even before an occurrence of \cd{\&whole}.
\end{itemize}
\end{newer}

\cdf{defmacro}, unlike any other Common Lisp construct that has a lambda-list
as part of its syntax, provides an additional facility known as
\emph{destructuring}.

See \cdf{destructuring-bind}, which provides the destructuring facility separately.

Anywhere in the lambda-list where a parameter
name may appear, and where ordinary lambda-list syntax (as described
in section~\ref{LAMBDA-EXPRESSIONS-SECTION}) does not
otherwise allow a list, a lambda-list may appear in place
of the parameter name.  When this is done, then the argument form
that would match the parameter is treated as a (possibly dotted) list,
to be used as an argument forms list for satisfying the
parameters in the embedded lambda-list.
As an example, one could write the macro definition
for \cdf{dolist} in this manner:
\begin{lisp}
(defmacro dolist ((var listform \cd{\&optional} resultform) \\
~~~~~~~~~~~~~~~~~~\&rest body) \\
~~...)
\end{lisp}
More examples of embedded lambda-lists in \cdf{defmacro} are shown below.

Another destructuring rule is that \cdf{defmacro} allows any lambda-list
(whether top-level or embedded) to be dotted, ending
in a parameter name.  This situation is treated exactly as if the
parameter name that ends the list had appeared preceded by \cd{\&rest}.
For example, the definition skeleton for \cdf{dolist} shown above could
instead have been written
\begin{lisp}
(defmacro dolist ((var listform \&optional resultform) \\
~~~~~~~~~~~~~~~~~~. body) \\
~~...)
\end{lisp}

If the compiler encounters a \cdf{defmacro},
the new macro is added to the compilation
environment, and a compiled form of the expansion function is also added
to the output file so that the new macro will be operative at run time.
If this is not the desired effect, the \cdf{defmacro} form can be wrapped
in an \cdf{eval-when} construct.

It is permissible to use \cdf{defmacro} to redefine a macro
(for example, to install
a corrected version of an incorrect definition), or to redefine
a function as a macro.
It is an error to attempt to redefine the name of a special
form (see table~\ref{SPECIAL-FORM-TABLE}) as a macro.
See \cdf{macrolet}, which establishes macro
definitions over a restricted lexical scope.

\begin{newer}
See also \cdf{define-compiler-macro}.
\end{newer}

Suppose, for the sake of example, that it were desirable
to implement a conditional construct analogous to the
Fortran arithmetic IF statement.  (This of course requires a certain
stretching of the imagination and suspension of disbelief.)
The construct should accept four forms: a \emph{test-value},
a \emph{neg-form}, a \emph{zero-form}, and a \emph{pos-form}.
One of the last three forms is chosen to be executed according
to whether the value of the \emph{test-form} is positive, negative,
or zero.
Using \cdf{defmacro}, a definition for such a construct
might look like this:
\begin{lisp}
(defmacro arithmetic-if (test neg-form zero-form pos-form) \\
~~(let ((var (gensym))) \\
~~~~{\Xbq}(let ((,var ,test)) \\
~~~~~~~(cond ((< ,var 0) ,neg-form) \\
~~~~~~~~~~~~~((= ,var 0) ,zero-form) \\
~~~~~~~~~~~~~(t ,pos-form)))))
\end{lisp}
Note the use of the backquote facility in this definition
(see section~\ref{MACRO-CHARACTERS-SECTION}).
Also note the use of \cdf{gensym} to generate a new variable name.
This is necessary to avoid conflict with any variables that might
be referred to in \emph{neg-form}, \emph{zero-form}, or \emph{pos-form}.

If the form is executed by the interpreter, it will cause the
function definition of the symbol \cdf{arithmetic-if}
to be a macro associated with which is
a two-argument expansion function roughly equivalent to
\begin{lisp}
(lambda (calling-form environment) \\
~~(declare (ignore environment)) \\
~~(let ((var (gensym))) \\
~~~~(list 'let \\
~~~~~~~~~~(list (list 'var (cadr calling-form))) \\
~~~~~~~~~~(list 'cond \\
~~~~~~~~~~~~~~~~(list (list '< var '0) (caddr calling-form)) \\
~~~~~~~~~~~~~~~~(list (list '= var '0) (cadddr calling-form)) \\
~~~~~~~~~~~~~~~~(list 't (fifth calling-form))))))
\end{lisp}
The lambda-expression is produced by the \cdf{defmacro} declaration.
The calls to \cdf{list} are the (hypothetical) result of the backquote (\cd{{\Xbq}})
macro character and its associated commas.
The precise macro expansion function may depend on the implementation,
for example providing some degree of explicit error checking on the number
of argument forms in the macro call.

Now, if \cdf{eval} encounters
\begin{lisp}
(arithmetic-if (- x 4.0) \\
~~~~~~~~~~~~~~~(- x) \\
~~~~~~~~~~~~~~~(error "Strange zero") \\
~~~~~~~~~~~~~~~x)
\end{lisp}
this will be expanded into something like
\begin{lisp}
(let ((g407 (- x 4.0))) \\
~~(cond ((< g407 0) (- x)) \\
~~~~~~~~((= g407 0) (error "Strange zero")) \\
~~~~~~~~(t x)))
\end{lisp}
and \cdf{eval} tries again on this new form.
(It should be clear now that the backquote facility
is very useful in writing macros, since the form to be returned is
normally a complex list structure, typically consisting of a
mostly constant template with a few evaluated forms here and there.
The backquote template provides a ``picture'' of the resulting
code, with places to be filled in indicated by preceding commas.)

To expand on this example, stretching credibility to its limit,
we might allow the \emph{pos-form}
and \emph{zero-form} to be omitted, allowing their values to default to {\nil},
in much the same way that the \emph{else} form of a Common Lisp \cdf{if} construct
may be omitted:
\begin{lisp}
(defmacro arithmetic-if (test neg-form \\*
~~~~~~~~~~~~~~~~~~~~~~~~~\cd{\&optional} zero-form pos-form) \\*
~~(let ((var (gensym))) \\*
~~~~{\Xbq}(let ((,var ,test)) \\*
~~~~~~~(cond ((< ,var 0) ,neg-form) \\*
~~~~~~~~~~~~~((= ,var 0) ,zero-form) \\*
~~~~~~~~~~~~~(t ,pos-form)))))
\end{lisp}
Then one could write
\begin{lisp}
(arithmetic-if (- x 4.0) (print x))
\end{lisp}
which would be expanded into something like
\begin{lisp}
(let ((g408 (- x 4.0))) \\*
~~(cond ((< g408 0) (print x)) \\*
~~~~~~~~((= g408 0) nil) \\*
~~~~~~~~(t nil)))
\end{lisp}
The resulting code is correct but rather silly-looking.
One might rewrite the macro definition to produce better code
when \emph{pos-form} and possibly \emph{zero-form} are omitted,
or one might simply rely on the Common Lisp implementation to provide
a compiler smart enough to improve the code itself.

Destructuring is a very powerful facility that allows
the \cdf{defmacro} lambda-list to express the structure of
a complicated macro-call syntax.  If no lambda-list keywords
appear, then the \cdf{defmacro} lambda-list is simply a list,
nested to some extent, containing parameter names at the leaves.
The macro-call form must have the same list structure.
For example, consider this macro definition:
\begin{lisp}
(defmacro halibut ((mouth eye1 eye2) \\*
~~~~~~~~~~~~~~~~~~~((fin1 length1) (fin2 length2)) \\*
~~~~~~~~~~~~~~~~~~~tail) \\*
~~...)
\end{lisp}
Now consider this macro call:
\begin{lisp}
(halibut (m (car eyes) (cdr eyes)) \\*
~~~~~~~~~((f1 (count-scales f1)) (f2 (count-scales f2))) \\*
~~~~~~~~~my-favorite-tail)
\end{lisp}
This would cause the expansion function to receive the following
values for its parameters:
\begin{flushleft}
\cf
\begin{tabular}{@{}ll@{}}
\textrm{Parameter}&\textrm{Value} \\
\hlinesp
mouth&m \\
eye1&(car eyes) \\
eye2&(cdr eyes) \\
fin1&f1 \\
length1&(count-scales f1) \\
fin2&f2 \\
length2&(count-scales f2) \\
tail&my-favorite-tail \\
\hline
\end{tabular}
\end{flushleft}
The following macro call would be in error because there would be no
argument form to match the parameter \cd{length1}:
\begin{lisp}
(halibut (m (car eyes) (cdr eyes)) \\
~~~~~~~~~((f1) (f2 (count-scales f2))) \\
~~~~~~~~~my-favorite-tail)
\end{lisp}
The following macro call would be in error because a symbol appears
in the call where the structure of the lambda-list requires a list.
\begin{lisp}
(halibut my-favorite-head \\
~~~~~~~~~((f1 (count-scales f1)) (f2 (count-scales f2))) \\
~~~~~~~~~my-favorite-tail)
\end{lisp}
The fact that the value of the variable \cdf{my-favorite-head}
might happen to be a list is irrelevant here.  It is the macro call
itself whose structure must match that of the \cdf{defmacro} lambda-list.

The use of lambda-list keywords adds even greater flexibility.
For example, suppose it is convenient within the expansion
function for \cdf{halibut} to be able to refer to the list
whose components are called \cd{mouth}, \cd{eye1}, and \cd{eye2} as \cd{head}.
One may write this:
\begin{lisp}
(defmacro halibut ((\cd{\&whole} head mouth eye1 eye2) \\
~~~~~~~~~~~~~~~~~~~((fin1 length1) (fin2 length2)) \\
~~~~~~~~~~~~~~~~~~~tail)
\end{lisp}
Now consider the same valid macro call as before:
\begin{lisp}
(halibut (m (car eyes) (cdr eyes)) \\
~~~~~~~~~((f1 (count-scales f1)) (f2 (count-scales f2))) \\
~~~~~~~~~my-favorite-tail)
\end{lisp}
This would cause the expansion function to receive the same
values for its parameters and also a value for the parameter \cdf{head}:
\begin{flushleft}
\cf
\begin{tabular}{@{}ll@{}}
\textrm{Parameter}&\textrm{Value} \\
\hlinesp
head&(m (car eyes) (cdr eyes)) \\
\hline
\end{tabular}
\end{flushleft}

The stipulation that
an embedded lambda-list is permitted only
where ordinary lambda-list syntax would permit a parameter name
but not a list is made to prevent ambiguity.  For example,
one may not write
\begin{lisp}
(defmacro loser (x \cd{\&optional} (a b \cd{\&rest} c) \cd{\&rest} z) \\
~~...)
\end{lisp}
because ordinary lambda-list syntax does permit a list following \cd{\&optional};
the list \cd{(a b \cd{\&rest} c)} would be interpreted as describing an
optional parameter named \cdf{a} whose default value is that of the
form \cdf{b}, with a supplied-p parameter named \cd{\&rest} (not legal),
and an extraneous symbol \cdf{c} in the list (also not legal).  An almost
correct way to express this is
\begin{lisp}
(defmacro loser (x \cd{\&optional} ((a b \cd{\&rest} c)) \cd{\&rest} z) \\
~~...)
\end{lisp}
The extra set of parentheses removes the ambiguity.  However, the
definition is now incorrect because a macro call such as \cd{(loser (car pool))}
would not provide any argument form for the lambda-list \cd{(a b \cd{\&rest} c)},
and so the default value against which to match the lambda-list would be
{\nil} because no explicit default value was specified.  This is in error
because {\nil} is an empty list; it does not have forms to satisfy the
parameters \cdf{a} and \cdf{b}.  The fully correct definition would be either
\begin{lisp}
(defmacro loser (x \cd{\&optional} ((a b \cd{\&rest} c) '(nil nil)) \cd{\&rest} z) \\
~~...)
\end{lisp}
or
\begin{lisp}
(defmacro loser (x \cd{\&optional} ((\cd{\&optional} a b \cd{\&rest} c)) \cd{\&rest} z) \\
~~...)
\end{lisp}
These differ slightly: the first requires that if the macro call
specifies \cdf{a} explicitly then it must also specify \cdf{b} explicitly,
whereas the second does not have this requirement.  For example,
\begin{lisp}
(loser (car pool) ((+ x 1)))
\end{lisp}
would be a valid call for the second definition but not for the first.
\end{defmac}

\section{Macro Expansion}

The \cdf{macroexpand} function is the conventional means for
expanding a macro call.  A hook is provided for a user function
to gain control during the expansion process.

\begin{defun}[Function]
macroexpand form &optional env \\
macroexpand-1 form &optional env

If \emph{form} is a macro call, then \cdf{macroexpand-1} will expand the macro
call \emph{once} and return two values: the expansion and \cdf{t}.
If \emph{form} is not a macro call, then the two values \emph{form} and {\nil} are
returned.

A \emph{form} is considered to be a macro call only if it is a cons whose
\emph{car} is a symbol that names a macro.  The environment \emph{env} is similar
to that used within the evaluator (see \cdf{evalhook});
it defaults to a null environment.
Any local macro definitions established within \emph{env} by
\cdf{macrolet} will be considered.  If only \emph{form} is given as an
argument, then the environment is effectively null,
and only global macro definitions
(as established by \cdf{defmacro}) will be considered.

Macro expansion is carried out as follows.  Once \cdf{macroexpand-1} has
determined that a symbol names a macro, it obtains the expansion
function for that macro.  The value of the variable
\cdf{*macroexpand-hook*} is then called as a function of three arguments:
the expansion function, the \emph{form}, and the environment \emph{env}.
The value returned from
this call is taken to be the expansion of the macro call.
The initial value of \cdf{*macroexpand-hook*} is \cdf{funcall},
and the net effect is to invoke the expansion function, giving
it \emph{form} and \emph{env} as its two arguments.

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE} to specify
that the value of \cdf{*macroexpand-hook*} is first coerced to a
function before being called as the expansion interface hook.
Therefore its value may be a symbol, a lambda-expression, or any
object of type \cdf{function}.
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{MACRO-ENVIRONMENT-EXTENT}
to specify that macro environment objects received
by a \cdf{*macroexpand-hook*} function
have only dynamic extent.  The consequences are undefined if such objects are
referred to outside the dynamic extent of that particular invocation of the hook
function.  This allows implementations to use somewhat more efficient techniques
for representing environment objects. 
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{MACRO-CACHING} to clarify that, while
\cdf{*macroexpand-hook*} may be useful for debugging purposes, despite
the original design intent there is
currently no correct portable way to use it for caching macro expansions.
\begin{itemize}
\item
 Caching by displacement (performing a side effect on the
 macro-call form) won't work because the same (\cdf{eq}) macro-call
 form may appear in distinct lexical contexts.  In addition, the macro-call
 form may be a read-only constant (see \cdf{quote} and also
 section~\ref{COMPILER-SECTION}).
\item
 Caching by table lookup won't work because such a table would have to
 be keyed by both the macro-call form and the environment,
 but X3J13 voted in March 1989 \issue{MACRO-ENVIRONMENT-EXTENT}
 to permit macro environments to have only dynamic extent.
\item
 Caching by storing macro-call forms and expansions within the
 environment object itself would work, but there are no portable
 primitives that would allow users to do this.
\end{itemize}
X3J13 also noted that, although there seems to be no correct portable way to use
\cdf{*macroexpand-hook*} to cache macro expansions, there is no
requirement that an implementation call the macro expansion
function more than once for a given form and lexical environment.
\end{newer}

\begin{new}
X3J13 voted in March 1989
\issue{SYMBOL-MACROLET-SEMANTICS}
to specify that \cdf{macroexpand-1} will also expand symbol macros
defined by \cdf{symbol-macrolet}; therefore a \emph{form} may also be
a macro call if it is a symbol.  The vote did not address the interaction
of this feature with the \cdf{*macroexpand-hook*} function.  An obvious
implementation choice is that the hook function is indeed called
and given a special expansion function that, when applied to the
\emph{form} (a symbol) and \emph{env}, will produce the expansion,
just as for an ordinary macro; but this is only my suggestion.
\end{new}

The evaluator expands macro calls as if through the use of \cdf{macroexpand-1};
the point is that \cdf{eval} also uses \cdf{*macroexpand-hook*}.

\cdf{macroexpand} is similar to \cdf{macroexpand-1},
but repeatedly expands \emph{form} until it is no longer a macro call.
(In effect, \cdf{macroexpand} simply calls \cdf{macroexpand-1} repeatedly
until the second value returned is {\nil}.)
A second value of \cdf{t} or {\nil} is returned as for \cdf{macroexpand-1},
indicating whether the original \emph{form} was a macro call.
\end{defun}

\begin{defun}[Variable]
*macroexpand-hook*

The value of \cdf{*macroexpand-hook*} is used as the expansion
interface hook by \cdf{macroexpand-1}.
\end{defun}

\section{Destructuring}

\begin{defmac}
destructuring-bind lambda-list expression {declaration}* {form}*

   This macro binds the variables specified in \emph{lambda-list} to the corresponding
   values in the tree structure resulting from evaluating the \emph{expression},
   then executes the \emph{form\/}s as an implicit \cdf{progn}.

A \cdf{destructuring-bind} \emph{lambda-list} may contain
the lambda-list keywords \cd{\&optional}, \cd{\&rest}, \cd{\&key},
\cd{\&allow-other-keys}, and \cd{\&aux}; \cd{\&body} and \cd{\&whole}
may also be used as they are in \cdf{defmacro}, but \cd{\&environment} may
\emph{not} be used.  Nested and dotted lambda-lists are also permitted
as for \cdf{defmacro}.
The idea is that a \cdf{destructuring-bind} \emph{lambda-list}
has the same format as inner levels of a \cdf{defmacro} lambda-list.

   If the result of evaluating the \emph{expression} does not match the 
   destructuring pattern, an error should be signaled.
\end{defmac}

\section{Compiler Macros}

X3J13 voted in June 1989 \issue{DEFINE-COMPILER-MACRO}
to add a facility for defining \emph{compiler macros} that
take effect only when compiling code, not when interpreting it.

The purpose of this facility is to permit selective source-code
transformations only when the compiler is processing the code.
When the compiler is about to compile a non-atomic form, it first calls
\cd{compiler-macroexpand-1} repeatedly until there is no more expansion
(there might not be any to begin with).  Then it continues its
remaining processing, which may include calling \cdf{macroexpand-1} and so on.

The compiler is required to expand compiler macros.  It is unspecified
whether the interpreter does so.  The intention is that only the
compiler will do so, but the range of possible ``compiled-only''
implementation strategies precludes any firm specification.


\begin{defmac}
define-compiler-macro name lambda-list
                      {declaration | doc-string}* {form}*

  This is just like \cdf{defmacro} except the definition is not stored in the
  symbol function cell of \emph{name} and is not seen by \cdf{macroexpand-1}.
  It is, however, seen by \cd{compiler-macroexpand-1}.  As with \cdf{defmacro}, the
  \emph{lambda-list} may include \cd{\&environment} and \cd{\&whole}
  and may include destructuring.  The definition is
  global.  (There is no provision for defining local compiler
  macros in the way that \cdf{macrolet} defines local macros.)

  A top-level call to \cdf{define-compiler-macro} in a file being compiled by
  \cdf{compile-file} has an effect on the compilation environment similar to
  that of a call to \cdf{defmacro}, except it is noticed as a
  compiler macro (see section~\ref{COMPILER-SECTION}).

Note that compiler macro definitions do not appear in information returned by
\cdf{function-information}; they are global, and their interaction
with other lexical and global definitions can be reconstructed by
\cdf{compiler-macro-function}.  It is up to code-walking programs to decide
whether to invoke compiler macro expansion.


\begin{newer}
X3J13 voted in March 1988 \issue{FLET-IMPLICIT-BLOCK}
to specify that the body of the expander function defined
by \cdf{defmacro} is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the defined macro;
presumably this applies also to \cdf{define-compiler-macro}.
Therefore \cdf{return-from} may be used to exit from the function.
\end{newer}

\end{defmac}

\begin{defun}[Function]
compiler-macro-function name &optional env

  The \emph{name} must be a symbol.
  If it has been defined as a compiler macro, then
  \cdf{compiler-macro-function} returns the macro expansion
  function; otherwise it returns \cdf{nil}.  The
  lexical environment \emph{env} may override any global definition for \emph{name}
  by defining a local function or local macro (such as by \cdf{flet}, \cdf{labels}, or
  \cdf{macrolet}) in which case \cdf{nil} is returned.

  \cdf{setf} may be used with \cdf{compiler-macro-function} to install a function as
  the expansion function for the compiler macro \emph{name}, in the same manner as for
  \cdf{macro-function}.  Storing the value \cdf{nil} removes any existing
  compiler macro definition.  As with \cdf{macro-function}, a non-\cdf{nil} stored value
  must be a function of two arguments, the entire macro call and 
  the environment.  The second argument to \cdf{compiler-macro-function} must
  be omitted when it is used with \cdf{setf}.
\end{defun}

\begin{defun}[Function]
compiler-macroexpand form &optional env \\
compiler-macroexpand-1 form &optional env

  These are just like \cdf{macroexpand} and \cdf{macroexpand-1}
  except that the expander function is obtained as if by a call to
  \cdf{compiler-macro-function} on the \emph{car} of the \emph{form} rather than by a call to
  \cdf{macro-function}.
  Note that \cdf{compiler-macroexpand} performs repeated expansion
  but \cd{compiler-macroexpand-1} performs at most one expansion.
  Two values are returned, the expansion (or the original \emph{form})
  and a value that is true if any expansion occurred and \cdf{nil} otherwise.

  There are three cases where no expansion happens:
  \begin{itemize}
    \item There is no compiler macro definition for the \emph{car} of \emph{form}.
    \item There is such a definition but there is also a \cdf{notinline}
        declaration, either globally or in the lexical environment \emph{env}.
    \item A global compiler macro definition is shadowed by a local
        function or macro definition (such as by \cdf{flet}, \cdf{labels}, or
        \cdf{macrolet}).
  \end{itemize}
  Note that if there is no expansion, the original \emph{form} is returned as
  the first value, and \cdf{nil} as the second value.
  
  Any macro expansion performed by the function \cdf{compiler-macroexpand}
  or by the function \cd{compiler-macroexpand-1} is carried out
  by calling the function that is the value of \cdf{*macroexpand-hook*}.

A compiler macro may decline to provide any expansion merely
by returning the original form. This is useful when using the facility
to put ``compiler optimizers'' on various function names.  For example,
here is a compiler macro that ``optimizes'' (one would hope)
the zero-argument and one-argument cases of
a function called \cdf{plus}:
\begin{lisp}
(define-compiler-macro plus (\&whole form \&rest args) \\*
~~(case (length args) \\*
~~~~(0 0) \\*
~~~~(1 (car args)) \\*
~~~~(t form)))
\end{lisp}
\end{defun}

\section{Environments}

X3J13 voted in June 1989 \issue{SYNTACTIC-ENVIRONMENT-ACCESS} to add some facilities for obtaining information
from environment objects of the kind received as arguments
by macro expansion functions, \cdf{*macroexpand-hook*} functions,
and \cdf{*evalhook*} functions.
There is a minimal set of accessors (\cdf{variable-information},
\cdf{function-information}, and \cdf{declaration-information}) and a constructor
(\cdf{augment-environment}) for environments.

All of the standard declaration specifiers, with the exception of \cdf{special},
can be defined fairly easily using \cdf{define-declaration}.  It also
seems to be able to handle most extended declarations.

The function \cdf{parse-macro} is provided so that
users don't have to write their
  own code to destructure macro arguments.
This function is not entirely necessary since X3J13 voted
in March 1989 \issue{DESTRUCTURING-BIND}
to add \cdf{destructuring-bind} to the language.
  However, \cdf{parse-macro} is worth having anyway, since any program-analyzing
  program is going to need to define it, and the implementation isn't completely
  trivial even with \cdf{destructuring-bind} to build upon.

  The function \cdf{enclose} allows expander functions to be defined in a non-null
  lexical environment, as required by the vote of X3J13 in
  March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}.  It
  also provides a mechanism by which a program processing
  the body of an \cd{(eval-when (:compile-toplevel)~...)} form
  can execute it in the enclosing environment (see issue
  \issue{EVAL-WHEN-NON-TOP-LEVEL}).

In all of these functions the argument named \emph{env} is an environment
object.  (It is not required that implementations
 provide a distinguished representation for such objects.)  Optional \emph{env}
 arguments default to \cdf{nil}, which represents the local null lexical environment
 (containing only global definitions and proclamations that are present in the
 run-time environment).  All of these functions should signal an error of type
 \cdf{type-error} if the value of an environment argument is not a syntactic
 environment object.

 The accessor functions \cdf{variable-information}, \cdf{function-information}, and
 \cdf{declaration-information} retrieve information about
 declarations that are in
 effect in the environment.  Since implementations are permitted to ignore
 declarations (except for \cdf{special} declarations and \cd{optimize safety}
 declarations if they ever compile unsafe code), these accessors are required
 only to return information about declarations that were explicitly added to
 the environment using \cdf{augment-environment}.  They might also return
 information about declarations recognized and added to the environment by the
 interpreter or the compiler, but that is at the discretion of the
 implementor.  Implementations are also permitted to canonicalize
 declarations, so the information returned by the accessors might not be
 identical to the information that was passed to \cdf{augment-environment}.

\begin{defun}[Function]
variable-information variable &optional env

  This function returns information about the interpretation of the symbol
  \emph{variable} when it appears as a variable within the lexical environment \emph{env}.
  Three values are returned.

  The first value indicates the type of definition or binding for \emph{variable}
  in \emph{env\/}:
\begin{indentdesc}{7pc}
\item[\cdf{nil}]
There is no apparent definition or binding for \emph{variable}.

\item[\cd{:special}]
The \emph{variable} refers to a special variable, either declared or proclaimed. 

\item[\cd{:lexical}]
The \emph{variable} refers to a lexical variable.

\item[\cd{:symbol-macro}]
The \emph{variable} refers to a \cdf{symbol-macrolet} binding.

\item[\cd{:constant}]
Either the \emph{variable} refers to a named constant defined by
\cdf{defconstant} or the \emph{variable} is a keyword symbol.
\end{indentdesc}

  The second value indicates whether there is a local binding of the name.  If
  the name is locally bound, the second value is true; otherwise, the second value
  is \cdf{nil}.

  The third value is an a-list containing information about declarations
  that apply to the apparent binding of the \emph{variable}.  The keys in the a-list
  are symbols that name declaration specifiers, and the format of the
  corresponding value in the \emph{cdr} of each pair depends on the particular 
  declaration name involved.  The standard declaration names
  that might appear as keys in this a-list are:
\begin{indentdesc}{7pc}
\item[\cdf{dynamic-extent}]
A non-\cdf{nil} value indicates that the \emph{variable} has been
                declared \cdf{dynamic-extent}. If the value is \cdf{nil}, the pair
                might be omitted.

\item[\cdf{ignore}]
A non-\cdf{nil} value indicates that the \emph{variable} has been declared
                \cdf{ignore}. If the value is \cdf{nil}, the pair might be omitted.

\item[\cdf{type}]
The value is a type specifier associated with the \emph{variable} by a \cdf{type}
                declaration or an abbreviated declaration such as
                \cd{(fixnum \emph{variable})}.
                If no explicit association exists, either by \cdf{proclaim} or
                \cdf{declare}, then the type specifier is \cdf{t}.  It is permissible for
                implementations to use a type specifier that is equivalent
                to or a supertype of the one appearing in the original
                declaration.  If the value is \cdf{t}, the pair might be
                omitted.
\end{indentdesc}
  If an implementation supports additional declaration specifiers that
  apply to variable bindings, those declaration names might also
  appear in the a-list.  However, the corresponding key must not
  be a symbol that is external in any package defined in the standard
  or that is otherwise accessible in the \cdf{common-lisp-user} package.

  The a-list might contain multiple entries for a given key.
  The consequences of destructively modifying the list
  structure of this a-list or its elements (except for values that 
  appear in the a-list as a result of \cdf{define-declaration}) are undefined.

  Note that the global binding might differ from the
  local one and can be retrieved by calling \cdf{variable-information}
  with a null lexical environment.
\end{defun}

\begin{defun}[Function]
function-information function &optional env

  This function returns information about the interpretation of the function-name
  \emph{function} when it appears in a functional position within lexical 
  environment \emph{env}.  Three values are returned.

  The first value indicates the type of definition or binding of the function-name
  which is apparent in \emph{env}:
\begin{indentdesc}{7pc}
\item[\cdf{nil}] There is no apparent definition for \emph{function}.

\item[\cd{:function}] The \emph{function} refers to a function.

\item[\cd{:macro}] The \emph{function} refers to a macro.

\item[\cd{:special-form}] The \emph{function} refers to a special operator.
\end{indentdesc}
  Some function-names can refer to both a global macro and a global special
  form.  In such a case the macro takes precedence and \cd{:macro} is returned as
  the first value.

  The second value specifies whether the definition is local or global.  If
  local, the second value is true; it is \cdf{nil} when the definition is
  global.

  The third value is an a-list containing information about declarations
  that apply to the apparent binding of the function.  The keys in the a-list
  are symbols that name declaration specifiers, and the format of the
  corresponding values in the \emph{cdr} of each pair depends on the particular 
  declaration name involved.  The standard declaration names
  that might appear as keys in this a-list are:
\begin{indentdesc}{7pc}
\item[\cdf{dynamic-extent}]
A non-\cdf{nil} value indicates that the function has been
                declared \cdf{dynamic-extent}.  If the value is \cdf{nil}, the pair
                might be omitted.

\item[\cdf{inline}]
The value is one of the symbols \cdf{inline}, \cdf{notinline}, or \cdf{nil} to indicate
                whether the function-name has been declared \cdf{inline},
                declared \cdf{notinline}, or neither, respectively.
                If the value is \cdf{nil}, the pair might be omitted.

\item[\cdf{ftype}]
The value is the type specifier associated with the function-name in the
                environment, or the symbol \cdf{function} if there is no functional
                type declaration or proclamation associated with the function-name.
                This value might not include all the apparent \cdf{ftype}
                declarations for the function-name.  It is permissible for
                implementations to use a type specifier that is equivalent
                to or a supertype of the one that appeared in the original
                declaration.  If the value is \cdf{function}, the pair might be
                omitted. 
\end{indentdesc}
  If an implementation supports additional declaration specifiers that
  apply to function bindings, those declaration names might also
  appear in the a-list.  However, the corresponding key must not be
  a symbol that is external in any package defined in the standard or
  that is otherwise accessible in the \cdf{common-lisp-user} package.

  The a-list might contain multiple entries for a given key.
  In this case the value associated with the first entry has
  precedence.  The consequences of destructively modifying the list
  structure of this a-list or its elements (except for values
  that appear in the a-list as a result of \cdf{define-declaration}) are 
  undefined.

  Note that the global binding might differ from the local
  one and can be retrieved by calling \cdf{function-information} with a null
  lexical environment.
\end{defun}

\begin{defun}[Function]
declaration-information decl-name &optional env

  This function returns information about declarations named by the
  symbol \emph{decl-name} that are in force in the environment \emph{env}.
  Only declarations that do not apply to function or variable bindings
  can be accessed with this function.  The format of the information
  that is returned depends on the \emph{decl-name} involved.

  It is required that this function recognize \cdf{optimize} and \cdf{declaration} as
  \emph{decl-name\/}s.  The values returned for these two cases are as follows:
\begin{indentdesc}{7pc}
\item[\cdf{optimize}]
A single value is returned,
a list whose entries are of the form \cd{(\emph{quality} \emph{value})}, where
                \emph{quality} is one of the standard optimization qualities
                (\cdf{speed}, \cdf{safety}, \cdf{compilation-speed}, \cdf{space}, \cdf{debug})
                or some implementation-specific optimization quality, and
                \emph{value} is an integer in the range 0 to 3 (inclusive).
                The returned list
                always contains an entry for each of the standard qualities and
                for each of the implementation-specific qualities.  In the
                absence of any previous declarations, the associated values are
                implementation-dependent.  The list might contain multiple
                entries for a quality, in which case the first such entry
                specifies the current value.
                The consequences of destructively modifying this list or
		its elements are undefined.
                

\item[\cdf{declaration}]
A single value is returned,
a list of the declaration names that have been proclaimed as
                valid through the use of the \cdf{declaration} proclamation.
                The consequences of destructively modifying this list or
		its elements are undefined.
\end{indentdesc}
  If an implementation is extended to recognize additional
  declaration specifiers in \cdf{declare} or \cdf{proclaim}, it is required that
  either the \cdf{declaration-information} function should recognize those
  declarations also or the implementation should provide a similar accessor that is
  specialized for that declaration specifier.  If \cdf{declaration-information}
  is used to return the information, the corresponding \emph{decl-name} must not
  be a symbol that is external in any package defined in the standard or
  that is otherwise accessible in the \cdf{common-lisp-user} package.
\end{defun}

\begin{defun}[Function]
augment-environment env &key :variable :symbol-macro :function :macro :declare

  This function returns a new environment containing the information present in
  \emph{env} augmented with the information provided by the keyword arguments.  It is
  intended to be used by program analyzers that perform a code walk.

  The arguments are supplied as follows.
\begin{flushdesc}
\item[\cd{:variable}]
     The argument is a list of symbols that will be visible as bound variables in
                the new environment.  Whether each binding is to be interpreted
                as special or lexical depends on \cdf{special} declarations recorded
                in the environment or provided in the \cd{:declare} argument.

\item[\cd{:symbol-macro}]
 The argument is a list of symbol macro definitions, each of the form
                \cd{(\emph{name} \emph{definition})}; that is, the argument is
                in the same format as the
                \emph{cadr} of a \cdf{symbol-macrolet} special operator.  The new environment
                will have local symbol-macro bindings of each symbol to the
                corresponding expansion, so that \cdf{macroexpand} will be able to
                expand them properly.  A type declaration in the \cd{:declare}
                argument that refers to a name in this list implicitly
                modifies the definition associated with the name.  The effect
                is to wrap a \cdf{the} form mentioning the type around the
                definition.

\item[\cd{:function}]
     The argument is a list of function-names that will be visible as local
                function bindings in the new environment.

\item[\cd{:macro}]
        The argument is a list of local macro definitions, 
        each of the form \cd{(\emph{name} \emph{definition})}.
        Note that the argument is \emph{not}
                in the same format as the
                \emph{cadr} of a \cdf{macrolet} special operator.
                Each \emph{definition} must be a function of two
                arguments (a form and an environment).  The new environment
                will have local macro bindings of each name to the
                corresponding expander function, which will be returned by
                \cdf{macro-function} and used by \cdf{macroexpand}.

\item[\cd{:declare}]
      The argument is a list of declaration specifiers.
      Information about these declarations can
                be retrieved from the resulting environment using
                \cdf{variable-information}, \cdf{function-information}, and
                \cdf{declaration-information}.
\end{flushdesc}
  The consequences of subsequently
  destructively modifying the list
  structure of any of the arguments to this function are undefined.

  An error is signaled if any of the symbols naming a symbol macro in the
  \cd{:symbol-macro} argument is also included in the \cd{:variable} argument.
  An error is
  signaled if any symbol naming a symbol macro in the \cd{:symbol-macro} argument is
  also included in a \cdf{special} declaration specifier in the \cd{:declare} argument.
  An error is
  signaled if any symbol naming a macro in the \cd{:macro} argument is also included
  in the \cd{:function} argument.
  The condition type of each of these errors is \cdf{program-error}.

  The extent of the returned environment is the same as the extent of the
  argument environment \emph{env}.  The result might share structure with \emph{env}
  but \emph{env} is not modified.

  While an environment argument received by an \cdf{*evalhook*}
  function is permitted to be used as the
  environment argument to \cdf{augment-environment}, the consequences are undefined if an
  attempt is made to use the result of \cdf{augment-environment} as the environment
  argument for \cdf{evalhook}.  The environment
  returned by \cdf{augment-environment} can be used only for syntactic analysis, that is,
  as an argument to
  the functions defined in this section and functions such as \cdf{macroexpand}.
\end{defun}

\begin{defmac}
define-declaration decl-name lambda-list {form}*

  This macro defines a handler for the named declaration.  It is the mechanism by which
  \cdf{augment-environment} is extended to support additional declaration
  specifiers.  The function defined by this macro will be called with two
  arguments, a declaration specifier whose \emph{car} is \emph{decl-name}
  and the \emph{env} argument to
  \cdf{augment-environment}.  This function must return two values.  The
  first value must be one of the following keywords:
\begin{indentdesc}{7pc}
\item[\cd{:variable}]     The declaration applies to variable bindings.
\item[\cd{:function}]     The declaration applies to function bindings.
\item[\cd{:declare}]      The declaration does not apply to bindings.
\end{indentdesc}
If the first value is \cd{:variable} or \cd{:function}
then the second value must be a list, the elements of which are lists of the
  form \cd{(\emph{binding-name} \emph{key} \emph{value})}.  If the corresponding information
  function (either \cdf{variable-information} or \cdf{function-information}) is applied to
  the \emph{binding-name} and the augmented environment, the a-list returned
  by the information function as its third value will contain the \emph{value}
  under the specified \emph{key}.

  If the first value is \cd{:declare}, the second value must be a cons
  of the form \cd{(\emph{key}~.~\emph{value})}.  The function
  \cdf{declaration-information} will return \emph{value} when applied to the
  \emph{key} and the augmented environment.

  \cdf{define-declaration} causes \emph{decl-name} to be proclaimed to be a
  declaration; it is as if its expansion included a call \cd{(proclaim
  '(declaration \emph{decl-name}))}.  As is the case with standard
  declaration specifiers, the evaluator and compiler are permitted,
  but not required, to add information about declaration specifiers
  defined with \cdf{define-declaration} to the macro expansion and \cdf{*evalhook*}
  environments.

  The consequences are undefined if \emph{decl-name} is a symbol that can
  appear as the \emph{car} of any standard declaration specifier.

  The consequences are also undefined if the return value from a 
  declaration handler defined with \cdf{define-declaration} includes a \emph{key} name
  that is used by the corresponding accessor to return information about
  any standard declaration specifier.  (For example, if
  the first return value from the handler is \cd{:variable}, the second return
  value may not use the symbols \cdf{dynamic-extent}, \cdf{ignore}, or \cdf{type}
  as \emph{key} names.)

  The \cdf{define-declaration} macro does not have any special compile-time
  side effects (see section~\ref{COMPILER-SECTION}).
\end{defmac}

\begin{defun}[Function]
parse-macro name lambda-list body &optional env

  This function is used to process a macro definition in the same way
  as \cdf{defmacro} and \cdf{macrolet}.  It returns a lambda-expression that accepts
  two arguments, a form and an environment.  The \emph{name}, \emph{lambda-list},
  and \emph{body} arguments correspond to the parts of a \cdf{defmacro} or \cdf{macrolet}
  definition.

  The \emph{lambda-list} argument may include \cd{\&environment} and \cd{\&whole}
  and may include destructuring.
  The \emph{name}
  argument is used to enclose the \emph{body} in an implicit \cdf{block} and might also
  be used for implementation-dependent purposes (such as including the name of
  the macro in error messages if the form does not match the \emph{lambda-list}).
\end{defun}

\begin{defun}[Function]
enclose lambda-expression &optional env

  This function returns an object of type \cdf{function} that is equivalent to what
  would be obtained by evaluating \cd{{\Xbq}(function ,\emph{lambda-expression})}
  in a syntactic
  environment \emph{env}.  The \emph{lambda-expression} is permitted to reference only the
  parts of the environment argument \emph{env} that are relevant only to syntactic
  processing, specifically declarations and the definitions of macros and
  symbol macros.  The consequences are undefined if the \emph{lambda-expression}
  contains any references to variable or function bindings that are 
  lexically visible in \emph{env}, any \cdf{go} to a tag that is lexically visible in 
  \emph{env}, or any \cdf{return-from} mentioning a block name that is lexically 
  visible in \emph{env}.
\end{defun}

%RUSSIAN
\else

\chapter{Макросы}
\label{MACROS}

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

Когда \cdf{eval} получает список, у которого \emph{car} элемент является
символом, она ищет локальные определения для этого символа (\cdf{flet},
\cdf{labels} и \cdf{macrolet}). Если поиски не увенчались успехом, она ищет
глобальное определение. Если это глобальное определение является макросом, тогда
исходный список называется \emph{макровызовом}. С определением будет
ассоциирована функция двух аргументов, называемая \emph{функцией раскрытия}. 
Эта функция вызывается с макровызовом в качестве первого аргумента и лексическим
окружением в качестве второго. Функция должна вернуть новую Lisp'овую форму,
называемую \emph{раскрытием} макровызова. (На самом деле участвует более общий
механизм, смотрите \cdf{macroexpand}.)
Затем это раскрытие выполняется по месту оригинальной (исходной) формы.

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

В целом, реализация Common Lisp'а имеет большую свободу в выборе того, когда в
программе раскрываются макровызовы.
Например, допускается для оператора \cdf{defun} раскрытие всех
внутренних макровызовов в время выполнения формы \cdf{defun} и записи полностью
раскрытого тела функции, как определение данной функции для дальнейшего
использования.
(Реализация может даже выбрать путь, все время компилировать функции
определённые с помощью \cdf{defun}, даже в режиме <<интерпретации>>.)

Для правильного раскрытия макросы должны быть написаны так, чтобы иметь
наименьшие зависимости от выполняемого окружения. Лучше всего удостовериться,
что все определения макросов доступны перед тем, как компилятор или
интерпретатор будет обрабатывает код, содержащий макровызовы к ним. 

В Common Lisp, макросы не являются функциями.
В частности, макросы не могут использоваться, как функциональные аргументы к
таким функциям, как \cdf{apply}, \cdf{funcall} или \cdf{map}. В таких ситуациях
список, отображающий <<первоначальный макровызов>> не существует и не может
существовать, потому что в некотором смысле аргументы уже были вычислены.

\section{Определение макроса}

Функция \cdf{macro-function} определяет, является ли данный символ именем
макроса. Конструкция \cdf{defmacro} предоставляет удобный способ определить
новый макрос.

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

Первый аргумент должен быть символом. Если символ содержит определение функции,
то есть определение макроса, локально созданное в окружении \emph{env} с помощью
\cdf{macrolet} или глобально созданное с помощью \cdf{defmacro}, тогда
возвращается функция раскрытия (функция двух аргументов, первый форма
макровызова и второй --- окружение).
Если символ не содержит определение функции, или это определение обычной функции
или это оператор, но не макрос, тогда возвращается {\false}. 
Наилучший способ вызвать функцию раскрытия использовать
\cdf{macroexpand} или \cdf{macroexpand-1}.

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

\cdf{setf} может быть использована с \cdf{macro-function} для установки в символ
глобального определения макроса:
\begin{lisp}
(setf (macro-function \emph{symbol}) \emph{fn})
\end{lisp}
Устанавливаемое значение должно быть функцией, которая принимает два аргументы,
список макровызова и окружение, и вычислять раскрытие этого макровызова. 
Выполнение этой операции указывает на то, что символ будет содержать \emph{только} это
определение макроса в качестве определения глобальной функции. Предыдущее
определение функции или макроса утрачивается. С помощью \cdf{setf} невозможно
установить локальное определение макроса. При использовании \cdf{setf} указание
второго параметра (окружение) является ошибкой.
Переопределение оператора также является ошибкой.

Смотрите также \cdf{compiler-macro-function}.
\end{defun}

\begin{defmac}
defmacro name lambda-list <{declaration}* | doc-string> {form}*

\cdf{defmacro} является макросом определяющим макросы, которые преобразуют формы
макровызовов.
\cdf{defmacro} имеет почти такой же синтаксис, как и \cdf{defun}:
\emph{name} является символом, для которого создаётся макрос,
\emph{lambda-list} похож на список параметров лямбда-выражения и 
\emph{form} содержит тело функции раскрытия.
Конструкция \emph{defmacro} устанавливает функцию раскрытия, как глобальное
определение макроса для символа \emph{name}.
FIXME

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

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

Форма \cdf{defmacro} возвращает в качестве значение \emph{name}.

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

Если указана необязательная строка документации \emph{doc-string}, тогда она
присоединяется к символу \emph{name}, как строка документации типа
\cdf{function}. Смотрите \cdf{documentation}.
Если в определении макроса представлена только строка документации, и после неё
нет ни одной формы, ни деклараций, ни просто для тела, то данная строка сама
становиться формой, и тело считается состоящим из одной формы --- этой строки.

Следующие три дополнительных маркера доступны в определении лямбда-списка.
\begin{indentdesc}{6pc}
\item[\cd{\&body}]
Данный маркер эквивалентен \cd{\&rest} маркеру, но дополнительно сообщает для
функций вывода-форматирования и редактирования, что оставшаяся часть формы
рассматривается как тело и должна быть правильно отформатирована.
(Можно использовать исключительно один маркер или \cd{\&body}, или \cd{\&rest})

\item[\cd{\&whole}]
За данным маркером указывается одна переменная, которая будет связана со всей
формой макровызова. Это значение, которое получает функция определения макроса в
качестве своего первого аргумента.
\cd{\&whole} и следующая переменная должны указываться на первой позиции в
лямбда-списке, перед другими параметрами или маркерами.

\item[\cd{\&environment}]
За данным маркером указывается одна переменная, которая будет связана с
окружением, отображающим лексическое окружение, в котором произошёл
макровызов. Это окружение может не быть полным лексическим окружением. Оно
должно использоваться только с функцией \cdf{macroexpand} ради любых локальных
определений макросов, которые могли быть установлены с помощью \cdf{macrolet}
конструкции внутри этого лексического окружения. Этот функционал полезен крайне
редко, когда определение макроса должно явно раскрыть другие макросы в процессе
своего раскрытия.
\end{indentdesc}
Смотрите \cdf{lambda-list-keywords}.

\begin{newer}
X3J13 voted in March 1989 \issue{MACRO-ENVIRONMENT-EXTENT}
to specify that macro environment objects received with the \cd{\&environment}
argument of a macro function
have only dynamic extent.  The consequences are undefined if such objects are
referred to outside the dynamic extent of that particular
invocation of the macro function.
This allows implementations to use somewhat more efficient techniques
for representing environment objects. 
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{DEFMACRO-LAMBDA-LIST} to clarify the permitted
uses of \cd{\&body}, \cd{\&whole}, and \cd{\&environment}:
\begin{itemize}
\item \cd{\&body} may appear at any level of a \cdf{defmacro} lambda-list.
\item \cd{\&whole} may appear at any level of a \cdf{defmacro} lambda-list.
At inner levels a \cd{\&whole} variable is bound to that part of the argument
that matches the sub-lambda-list in which \cd{\&whole} appears.  No matter where
\cd{\&whole} is used, other parameters or lambda-list keywords may follow it.
\item \cd{\&environment} may occur only at the outermost level of a \cdf{defmacro}
lambda-list, and it may occur at most once, but it may occur anywhere within
that lambda-list, even before an occurrence of \cd{\&whole}.
\end{itemize}
\end{newer}

\cdf{defmacro}, в отличие от любых других конструкций Common Lisp'а, имеющих
лямбда-списки в своём синтаксисе, предоставляет дополнительную функциональность
известную как \emph{деструктуризация}.

Смотрите \cdf{destructuring-bind}, которая отдельно предоставляет эту функциональность.

В любом месте, где могло бы стоять имя параметра, и где по синтаксису не
ожидается использование списка (как описано в
разделе~\ref{LAMBDA-EXPRESSIONS-SECTION}), можно использовать ещё один
встроенный лямбда-список. Когда использован такой приём, при передаче форм
аргументов для встроенного лямбда-списка, необходимо обернуть эти формы в
отдельный список.
В качестве примера, определение макроса для \cdf{dolist} можно записать в таком
стиле:
\begin{lisp}
(defmacro dolist ((var listform \cd{\&optional} resultform) \\
~~~~~~~~~~~~~~~~~~\&rest body) \\
~~...)
\end{lisp}
Ниже будет больше примеров использования встраиваемых лямбда-списков в
\cdf{defmacro}.

Следующим правилом деструктуризации является то, что \cdf{defmacro} позволяет
любому лямбда-списку (верхнего уровня или встроенному) быть dotted,
заканчивающимся именем параметра. Такая ситуация обрабатывается так, как будто
имя параметра в конце списка, стоит после неявного маркера \cd{\&rest}.
Например, уже показанное определение \cdf{dolist} может быть записано так:
\begin{lisp}
(defmacro dolist ((var listform \&optional resultform) \\
~~~~~~~~~~~~~~~~~~. body) \\
~~...)
\end{lisp}

Если компилятор встречает \cdf{defmacro}, он добавляет новый макрос в окружение
компиляции, и также функция раскрытия добавляется в выходной файл. Таким образом
новый макрос будет более быстрым во время выполнения.
Если необходимо избежать такого механизма, можно использовать \cdf{defmacro}
внутри конструкции \cdf{eval-when}.

\cdf{defmacro} может также использоваться для переопределения макроса
(например, для установки корректной версии определения вместо некорректной), или
для переопределения функции в макрос.
Переопределение оператора (смотрите таблицу~\ref{SPECIAL-FORM-TABLE})
не допускается.
Смотрите \cdf{macrolet}, которая устанавливает определение макроса в замкнутом
лексическом области видимости.

Допустим, для примера, что необходимо реализовать условную конструкцию
аналогичную Fortran'овскому арифметическому выражению IF. (Это конечно требует
определённого расширения воображения и приостановки неверия.)
Конструкция должна принимать четыре формы:
\emph{test-value},
\emph{neg-form},
\emph{zero-form} и
\emph{pos-form}.
В зависимости от того, является ли \emph{test-form} отрицательным, нулём или
положительным числом, для выполнения будет выбрана одна из трёх последних форм.
С использованием \cdf{defmacro}, определение этой конструкции может выглядеть
так:
\begin{lisp}
(defmacro arithmetic-if (test neg-form zero-form pos-form) \\
~~(let ((var (gensym))) \\
~~~~{\Xbq}(let ((,var ,test)) \\
~~~~~~~(cond ((< ,var 0) ,neg-form) \\
~~~~~~~~~~~~~((= ,var 0) ,zero-form) \\
~~~~~~~~~~~~~(t ,pos-form)))))
\end{lisp}
Необходимо отметить, что в данном определении используется функциональность
обратной кавычки (смотрите раздел~\ref{MACRO-CHARACTERS-SECTION}).
Также необходимо заметить, что используется \cdf{gensym} для создания нового
имени переменной.
Это необходимо для избежания конфликтов с другими переменными, которые могут
использоваться в формах \emph{neg-form}, \emph{zero-form} или \emph{pos-form}.

Если форма выполняется интерпретатором, то определение функции для символа
\cd{arithmetic-if} будет является макросом, с которым ассоциирована функция двух
аргументом эквивалентная данной
\begin{lisp}
(lambda (calling-form environment) \\
~~(declare (ignore environment)) \\
~~(let ((var (gensym))) \\
~~~~(list 'let \\
~~~~~~~~~~(list (list 'var (cadr calling-form))) \\
~~~~~~~~~~(list 'cond \\
~~~~~~~~~~~~~~~~(list (list '< var '0) (caddr calling-form)) \\
~~~~~~~~~~~~~~~~(list (list '= var '0) (cadddr calling-form)) \\
~~~~~~~~~~~~~~~~(list 't (fifth calling-form))))))
\end{lisp}
Лямбда-выражение является результатом выполнения декларации \cdf{defmacro}.
Вызов \cdf{list} является (гипотетически) результатом макросимвола обратной
кавычки (\cd{{\Xbq}}) и связанной с ним запятой.
Конкретная функция раскрытия макроса может зависеть от реализации, например, она
также может содержать проверку на корректность входных аргументов в макровызове.

Теперь, если \cdf{eval} встретит
\begin{lisp}
(arithmetic-if (- x 4.0) \\
~~~~~~~~~~~~~~~(- x) \\
~~~~~~~~~~~~~~~(error "Strange zero") \\
~~~~~~~~~~~~~~~x)
\end{lisp}
то раскроет эту форму в
\begin{lisp}
(let ((g407 (- x 4.0))) \\
~~(cond ((< g407 0) (- x)) \\
~~~~~~~~((= g407 0) (error "Strange zero")) \\
~~~~~~~~(t x)))
\end{lisp}
и \cdf{eval} выполнит полученную форму.
(Сейчас должно быть понятно, что функциональность обратной кавычки очень полезна
для написания макросов. Она используется для построения шаблона, возвращаемой
формы, с константными частями и частями для выполнения. Шаблон представляет
собой <<картину>> кода, с местами для заполнения выделенными запятыми.)

Для улучшения примера мы можем сделать так, чтобы \emph{pos-form} и
\emph{zero-form} могли быть заменены на {\nil} в результате раскрытия макроса.
Таким же образом действует и \cdf{if} опуская ветку \emph{else} в случае
истинности условия.
\begin{lisp}
(defmacro arithmetic-if (test neg-form \\*
~~~~~~~~~~~~~~~~~~~~~~~~~\cd{\&optional} zero-form pos-form) \\*
~~(let ((var (gensym))) \\*
~~~~{\Xbq}(let ((,var ,test)) \\*
~~~~~~~(cond ((< ,var 0) ,neg-form) \\*
~~~~~~~~~~~~~((= ,var 0) ,zero-form) \\*
~~~~~~~~~~~~~(t ,pos-form)))))
\end{lisp}
Тогда можно записать
\begin{lisp}
(arithmetic-if (- x 4.0) (print x))
\end{lisp}
и это раскроется в что-то вроде
\begin{lisp}
(let ((g408 (- x 4.0))) \\*
~~(cond ((< g408 0) (print x)) \\*
~~~~~~~~((= g408 0) nil) \\*
~~~~~~~~(t nil)))
\end{lisp}
Результирующий код корректен, но некрасиво выглядит.
Можно переписать определение макроса для генерации лучшего кода, когда
\emph{pos-form} и \emph{zero-form} могут быть вообще опущены.
Или же можно положиться на реализацию Common Lisp'а, которая возможно
оптимизирует этот код.

Деструктуризация является очень мощной функциональностью, которая позволяет
лямбда-списку в \cdf{defmacro} выразить сложную структуру макровызова. Если
не использовались ключевые символы лямбда-списка, то он представляет собой
просто список с некоторой степенью вложенности и параметрами в качестве
листьев. Структура макровызова должна иметь такую же структуру списка.
Например, рассмотрим следующее определение макроса:
\begin{lisp}
(defmacro halibut ((mouth eye1 eye2) \\*
~~~~~~~~~~~~~~~~~~~((fin1 length1) (fin2 length2)) \\*
~~~~~~~~~~~~~~~~~~~tail) \\*
~~...)
\end{lisp}
Теперь давайте рассмотрим макровызов:
\begin{lisp}
(halibut (m (car eyes) (cdr eyes)) \\*
~~~~~~~~~((f1 (count-scales f1)) (f2 (count-scales f2))) \\*
~~~~~~~~~my-favorite-tail)
\end{lisp}
Все это приведёт к тому, что функция раскрытия получит следующие значения для её
параметров:
\begin{flushleft}
\begin{tabular}{@{}ll@{}}
\textrm{Параметр}&\textrm{Значение} \\
mouth&m \\
eye1&(car eyes) \\
eye2&(cdr eyes) \\
fin1&f1 \\
length1&(count-scales f1) \\
fin2&f2 \\
length2&(count-scales f2) \\
tail&my-favorite-tail \\
\end{tabular}
\end{flushleft}
Следующий макровызов ошибочный, так как аргумента для параметра \cd{length1} не
представлено:
\begin{lisp}
(halibut (m (car eyes) (cdr eyes)) \\
~~~~~~~~~((f1) (f2 (count-scales f2))) \\
~~~~~~~~~my-favorite-tail)
\end{lisp}
Следующий макровызов также ошибочный, так как на месте предполагаемого списка
указан символ.
\begin{lisp}
(halibut my-favorite-head \\
~~~~~~~~~((f1 (count-scales f1)) (f2 (count-scales f2))) \\
~~~~~~~~~my-favorite-tail)
\end{lisp}
Тот факт, что значение переменной \cd{my-favorite-head} может быть списком, не
имеет здесь значения. В макровызове структура должна совпадать с лямбда-списком
в определении.

Использование ключевых символов лямбда-списка предоставляет ещё большую
гибкость.
Например, предположим, что удобно будет в функции раскрытия обращаться к
элементам списка, называемым cd{mouth}, \cd{eye1}, and \cd{eye2}, как к
\cd{head}.
Можно записать так:
\begin{lisp}
(defmacro halibut ((\cd{\&whole} head mouth eye1 eye2) \\
~~~~~~~~~~~~~~~~~~~((fin1 length1) (fin2 length2)) \\
~~~~~~~~~~~~~~~~~~~tail)
\end{lisp}
Теперь рассмотрим такой же, как раньше, корректный макровызов:
\begin{lisp}
(halibut (m (car eyes) (cdr eyes)) \\
~~~~~~~~~((f1 (count-scales f1)) (f2 (count-scales f2))) \\
~~~~~~~~~my-favorite-tail)
\end{lisp}
Это приведёт к тому, что функции раскрытия получит те же значения для своих
параметров, а также значение для параметра \cd{head}:
\begin{flushleft}
\cf
\begin{tabular}{@{}ll@{}}
\textrm{Параметр}&\textrm{Значение} \\
\hlinesp
head&(m (car eyes) (cdr eyes)) \\
\end{tabular}
\end{flushleft}

Существует условие для деструктуризации, встроенный лямбда-список разрешён
только на позиции, где синтаксис лямбда-списка предусматривает имя параметра, но
не список. Это защищает от двусмысленности. Например, нельзя записать
\begin{lisp}
(defmacro loser (x \cd{\&optional} (a b \cd{\&rest} c) \cd{\&rest} z) \\
~~...)
\end{lisp}
потому что синтаксис лямбда-списка не позволяет использовать списки после
\cd{\&optional}. Список \cd{(a b \cd{\&rest} c)} был бы интерпретирован как
необязательный параметр \cd{a}, у которого значение по умолчанию \cd{b}, и
supplied-p параметр с некорректным именем \cd{\&rest}, и дополнительным символом
\cd{c}, также некорректным. Было бы правильнее выразить это так:
\begin{lisp}
(defmacro loser (x \cd{\&optional} ((a b \cd{\&rest} c)) \cd{\&rest} z) \\
~~...)
\end{lisp}
Дополнительные круглые скобки устраняют двусмысленность. Однако, такой
макровызов, как \cd{(loser (car pool))} не предоставляет никакой формы аргумента
для лямбда-списка  \cd{(a b \cd{\&rest} c)}, значит значение по умолчанию для
него будет {\nil}. А так как {\nil} является пустым списком, то этот макровызов
ошибочен. Полностью корректное определение выглядит так:
\begin{lisp}
(defmacro loser (x \cd{\&optional} ((a b \cd{\&rest} c) '(nil nil)) \cd{\&rest} z) \\
~~...)
\end{lisp}
или так
\begin{lisp}
(defmacro loser (x \cd{\&optional} ((\cd{\&optional} a b \cd{\&rest} c)) \cd{\&rest} z) \\
~~...)
\end{lisp}
Они слегка отличаются: первое определение требует, что если макровызов явно
указывает \cd{a}, тогда он должен указать явно и \cd{b}, тогда как второе
определение не содержит такого требования. Например,
\begin{lisp}
(loser (car pool) ((+ x 1)))
\end{lisp}
будет корректным макровызовом для второго определения, но не для первого.
\end{defmac}

\section{Раскрытие макроса}

Функция \cdf{macroexpand} служит для раскрытия макровызовов. Также
предоставляется ловушка для пользовательской функции для управления процессом
раскрытия.

\begin{defun}[Функция]
macroexpand form &optional env \\
macroexpand-1 form &optional env

Если форма \emph{form} является макровызовом, тогда \cdf{macroexpand-1} раскроет
макровызов только на \emph{один} уровень и вернёт два значения:
раскрытие и \cdf{t}.
Если форма \emph{form} не является макровызовом, тогда будут возвращены два
значения: \emph{form} и {\nil}.

Форма \emph{form} рассматривается как макровызов, только если она является
cons-ячейкой, у которой \emph{car} элемент является символом имени макроса. 
Окружение \emph{env} похоже на то, что используется внутри вычислителя (смотрите
\cdf{evalhook}). По-умолчанию равно нулевому окружению.
Если окружение указано будут рассмотрены все установленные внутри \emph{env} с
помощью \cdf{macrolet} локальные определения макросов. Если в качестве аргумента
указана только форма \emph{form}, то берётся нулевое окружение, и будут
рассматриваться только глобальные определения макросов (установленные с помощью
\cdf{defmacro}).

Раскрытие макросов происходит следующим образом. Когда \cdf{macroexpand-1}
устанавливает, что символ в форме указывает на макрос, тогда она получает
функцию раскрытия для этого макроса. Затем вызывается значение переменной
\cdf{*macroexpand-hook*}, как функция трёх аргументов с параметрами:
функция раскрытия,
форма \emph{form} и
окружение \emph{env}.
Значение, возвращённое этим вызовом, расценивается, как раскрытие макровызова.
Значение переменной \cdf{*macroexpand-hook*} по-умолчанию \cdf{funcall}, которая
следовательно просто запускает функцию раскрытия с двумя параметрами: формой
\emph{form} и окружением \emph{env}.

\begin{newer}
X3J13 voted in June 1988 \issue{FUNCTION-TYPE} to specify
that the value of \cdf{*macroexpand-hook*} is first coerced to a
function before being called as the expansion interface hook.
Therefore its value may be a symbol, a lambda-expression, or any
object of type \cdf{function}.
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{MACRO-ENVIRONMENT-EXTENT}
to specify that macro environment objects received
by a \cdf{*macroexpand-hook*} function
have only dynamic extent.  The consequences are undefined if such objects are
referred to outside the dynamic extent of that particular invocation of the hook
function.  This allows implementations to use somewhat more efficient techniques
for representing environment objects. 
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{MACRO-CACHING} to clarify that, while
\cdf{*macroexpand-hook*} may be useful for debugging purposes, despite
the original design intent there is
currently no correct portable way to use it for caching macro expansions.
\begin{itemize}
\item
 Caching by displacement (performing a side effect on the
 macro-call form) won't work because the same (\cdf{eq}) macro-call
 form may appear in distinct lexical contexts.  In addition, the macro-call
 form may be a read-only constant (see \cdf{quote} and also
 section~\ref{COMPILER-SECTION}).
\item
 Caching by table lookup won't work because such a table would have to
 be keyed by both the macro-call form and the environment,
 but X3J13 voted in March 1989 \issue{MACRO-ENVIRONMENT-EXTENT}
 to permit macro environments to have only dynamic extent.
\item
 Caching by storing macro-call forms and expansions within the
 environment object itself would work, but there are no portable
 primitives that would allow users to do this.
\end{itemize}
X3J13 also noted that, although there seems to be no correct portable way to use
\cdf{*macroexpand-hook*} to cache macro expansions, there is no
requirement that an implementation call the macro expansion
function more than once for a given form and lexical environment.
\end{newer}

\begin{new}
X3J13 voted in March 1989
\issue{SYMBOL-MACROLET-SEMANTICS}
to specify that \cdf{macroexpand-1} will also expand symbol macros
defined by \cdf{symbol-macrolet}; therefore a \emph{form} may also be
a macro call if it is a symbol.  The vote did not address the interaction
of this feature with the \cdf{*macroexpand-hook*} function.  An obvious
implementation choice is that the hook function is indeed called
and given a special expansion function that, when applied to the
\emph{form} (a symbol) and \emph{env}, will produce the expansion,
just as for an ordinary macro; but this is only my suggestion.
\end{new}

Вычислитель раскрывает макровызовы, как если бы использовал
\cdf{macroexpand-1}. Таким образом \cdf{eval} также использует
\cdf{*macroexpand-hook*}.

\cdf{macroexpand} похожа на \cdf{macroexpand-1}, однако циклично раскрывает форму
\emph{form}, пока в ней не останется макровызовов.
(А точнее, \cdf{macroexpand} просто циклично вызывает \cdf{macroexpand-1}, пока
последняя не вернёт {\nil} во втором значении.)
Второе возвращаемое значение функции \cdf{macroexpand-1} (\cdf{t} или {\nil})
указывает на то, являлась ли форма \emph{form} макровызовом.
\end{defun}

\begin{defun}[Переменная]
*macroexpand-hook*

Значение \cdf{*macroexpand-hook*} используется как интерфейс раскрытия для
\cdf{macroexpand-1}.
\end{defun}

\section{Деструктуризация}

\begin{defmac}
destructuring-bind lambda-list expression {declaration}* {form}*

   Данный макрос связывает переменные указанные в \emph{лямбда-списке} с
   соответствующими значениями в древовидной структуре, являющейся результатом
   вычисления \emph{выражения}, а затем выполняет \emph{формы} как неявный \cdf{progn}.

Лямбда-список может содержать ключевые символы \cd{\&optional}, \cd{\&rest}, \cd{\&key}
\cd{\&allow-other-keys}, and \cd{\&aux}.
\cd{\&body} и \cd{\&whole} также могут использоваться как и в \cdf{defmacro},
однако \cd{\&environment} использоваться \emph{не} может.
Идея в том, что лямбда-список \cdf{destructuring-bind} имеет тот же формат, что
и внутренние уровни лямбда-списка \cdf{defmacro}.

Если результат выполнения \emph{выражения} не совпадает с шаблоном
деструктуризации, то должна быть сигнализирована ошибка.
\end{defmac}

\section{Compiler Macros}

X3J13 voted in June 1989 \issue{DEFINE-COMPILER-MACRO}
to add a facility for defining \emph{compiler macros} that
take effect only when compiling code, not when interpreting it.

The purpose of this facility is to permit selective source-code
transformations only when the compiler is processing the code.
When the compiler is about to compile a non-atomic form, it first calls
\cd{compiler-macroexpand-1} repeatedly until there is no more expansion
(there might not be any to begin with).  Then it continues its
remaining processing, which may include calling \cdf{macroexpand-1} and so on.

The compiler is required to expand compiler macros.  It is unspecified
whether the interpreter does so.  The intention is that only the
compiler will do so, but the range of possible ``compiled-only''
implementation strategies precludes any firm specification.


\begin{defmac}
define-compiler-macro name lambda-list
                      {declaration | doc-string}* {form}*

  This is just like \cdf{defmacro} except the definition is not stored in the
  symbol function cell of \emph{name} and is not seen by \cdf{macroexpand-1}.
  It is, however, seen by \cd{compiler-macroexpand-1}.  As with \cdf{defmacro}, the
  \emph{lambda-list} may include \cd{\&environment} and \cd{\&whole}
  and may include destructuring.  The definition is
  global.  (There is no provision for defining local compiler
  macros in the way that \cdf{macrolet} defines local macros.)

  A top-level call to \cdf{define-compiler-macro} in a file being compiled by
  \cdf{compile-file} has an effect on the compilation environment similar to
  that of a call to \cdf{defmacro}, except it is noticed as a
  compiler macro (see section~\ref{COMPILER-SECTION}).

Note that compiler macro definitions do not appear in information returned by
\cdf{function-information}; they are global, and their interaction
with other lexical and global definitions can be reconstructed by
\cdf{compiler-macro-function}.  It is up to code-walking programs to decide
whether to invoke compiler macro expansion.


\begin{newer}
X3J13 voted in March 1988 \issue{FLET-IMPLICIT-BLOCK}
to specify that the body of the expander function defined
by \cdf{defmacro} is implicitly enclosed in a \cdf{block} construct
whose name is the same as the \emph{name} of the defined macro;
presumably this applies also to \cdf{define-compiler-macro}.
Therefore \cdf{return-from} may be used to exit from the function.
\end{newer}

\end{defmac}

\begin{defun}[Function]
compiler-macro-function name &optional env

  The \emph{name} must be a symbol.
  If it has been defined as a compiler macro, then
  \cdf{compiler-macro-function} returns the macro expansion
  function; otherwise it returns \cdf{nil}.  The
  lexical environment \emph{env} may override any global definition for \emph{name}
  by defining a local function or local macro (such as by \cdf{flet}, \cdf{labels}, or
  \cdf{macrolet}) in which case \cdf{nil} is returned.

  \cdf{setf} may be used with \cdf{compiler-macro-function} to install a function as
  the expansion function for the compiler macro \emph{name}, in the same manner as for
  \cdf{macro-function}.  Storing the value \cdf{nil} removes any existing
  compiler macro definition.  As with \cdf{macro-function}, a non-\cdf{nil} stored value
  must be a function of two arguments, the entire macro call and 
  the environment.  The second argument to \cdf{compiler-macro-function} must
  be omitted when it is used with \cdf{setf}.
\end{defun}

\begin{defun}[Function]
compiler-macroexpand form &optional env \\
compiler-macroexpand-1 form &optional env

  These are just like \cdf{macroexpand} and \cdf{macroexpand-1}
  except that the expander function is obtained as if by a call to
  \cdf{compiler-macro-function} on the \emph{car} of the \emph{form} rather than by a call to
  \cdf{macro-function}.
  Note that \cdf{compiler-macroexpand} performs repeated expansion
  but \cd{compiler-macroexpand-1} performs at most one expansion.
  Two values are returned, the expansion (or the original \emph{form})
  and a value that is true if any expansion occurred and \cdf{nil} otherwise.

  There are three cases where no expansion happens:
  \begin{itemize}
    \item There is no compiler macro definition for the \emph{car} of \emph{form}.
    \item There is such a definition but there is also a \cdf{notinline}
        declaration, either globally or in the lexical environment \emph{env}.
    \item A global compiler macro definition is shadowed by a local
        function or macro definition (such as by \cdf{flet}, \cdf{labels}, or
        \cdf{macrolet}).
  \end{itemize}
  Note that if there is no expansion, the original \emph{form} is returned as
  the first value, and \cdf{nil} as the second value.
  
  Any macro expansion performed by the function \cdf{compiler-macroexpand}
  or by the function \cd{compiler-macroexpand-1} is carried out
  by calling the function that is the value of \cdf{*macroexpand-hook*}.

A compiler macro may decline to provide any expansion merely
by returning the original form. This is useful when using the facility
to put ``compiler optimizers'' on various function names.  For example,
here is a compiler macro that ``optimizes'' (one would hope)
the zero-argument and one-argument cases of
a function called \cdf{plus}:
\begin{lisp}
(define-compiler-macro plus (\&whole form \&rest args) \\*
~~(case (length args) \\*
~~~~(0 0) \\*
~~~~(1 (car args)) \\*
~~~~(t form)))
\end{lisp}
\end{defun}

\section{Environments}

X3J13 voted in June 1989 \issue{SYNTACTIC-ENVIRONMENT-ACCESS} to add some facilities for obtaining information
from environment objects of the kind received as arguments
by macro expansion functions, \cdf{*macroexpand-hook*} functions,
and \cdf{*evalhook*} functions.
There is a minimal set of accessors (\cdf{variable-information},
\cdf{function-information}, and \cdf{declaration-information}) and a constructor
(\cdf{augment-environment}) for environments.

All of the standard declaration specifiers, with the exception of \cdf{special},
can be defined fairly easily using \cdf{define-declaration}.  It also
seems to be able to handle most extended declarations.

The function \cdf{parse-macro} is provided so that
users don't have to write their
  own code to destructure macro arguments.
This function is not entirely necessary since X3J13 voted
in March 1989 \issue{DESTRUCTURING-BIND}
to add \cdf{destructuring-bind} to the language.
  However, \cdf{parse-macro} is worth having anyway, since any program-analyzing
  program is going to need to define it, and the implementation isn't completely
  trivial even with \cdf{destructuring-bind} to build upon.

  The function \cdf{enclose} allows expander functions to be defined in a non-null
  lexical environment, as required by the vote of X3J13 in
  March 1989 \issue{DEFINING-MACROS-NON-TOP-LEVEL}.  It
  also provides a mechanism by which a program processing
  the body of an \cd{(eval-when (:compile-toplevel)~...)} form
  can execute it in the enclosing environment (see issue
  \issue{EVAL-WHEN-NON-TOP-LEVEL}).

In all of these functions the argument named \emph{env} is an environment
object.  (It is not required that implementations
 provide a distinguished representation for such objects.)  Optional \emph{env}
 arguments default to \cdf{nil}, which represents the local null lexical environment
 (containing only global definitions and proclamations that are present in the
 run-time environment).  All of these functions should signal an error of type
 \cdf{type-error} if the value of an environment argument is not a syntactic
 environment object.

 The accessor functions \cdf{variable-information}, \cdf{function-information}, and
 \cdf{declaration-information} retrieve information about
 declarations that are in
 effect in the environment.  Since implementations are permitted to ignore
 declarations (except for \cdf{special} declarations and \cd{optimize safety}
 declarations if they ever compile unsafe code), these accessors are required
 only to return information about declarations that were explicitly added to
 the environment using \cdf{augment-environment}.  They might also return
 information about declarations recognized and added to the environment by the
 interpreter or the compiler, but that is at the discretion of the
 implementor.  Implementations are also permitted to canonicalize
 declarations, so the information returned by the accessors might not be
 identical to the information that was passed to \cdf{augment-environment}.

\begin{defun}[Function]
variable-information variable &optional env

  This function returns information about the interpretation of the symbol
  \emph{variable} when it appears as a variable within the lexical environment \emph{env}.
  Three values are returned.

  The first value indicates the type of definition or binding for \emph{variable}
  in \emph{env\/}:
\begin{indentdesc}{7pc}
\item[\cdf{nil}]
There is no apparent definition or binding for \emph{variable}.

\item[\cd{:special}]
The \emph{variable} refers to a special variable, either declared or proclaimed. 

\item[\cd{:lexical}]
The \emph{variable} refers to a lexical variable.

\item[\cd{:symbol-macro}]
The \emph{variable} refers to a \cdf{symbol-macrolet} binding.

\item[\cd{:constant}]
Either the \emph{variable} refers to a named constant defined by
\cdf{defconstant} or the \emph{variable} is a keyword symbol.
\end{indentdesc}

  The second value indicates whether there is a local binding of the name.  If
  the name is locally bound, the second value is true; otherwise, the second value
  is \cdf{nil}.

  The third value is an a-list containing information about declarations
  that apply to the apparent binding of the \emph{variable}.  The keys in the a-list
  are symbols that name declaration specifiers, and the format of the
  corresponding value in the \emph{cdr} of each pair depends on the particular 
  declaration name involved.  The standard declaration names
  that might appear as keys in this a-list are:
\begin{indentdesc}{7pc}
\item[\cdf{dynamic-extent}]
A non-\cdf{nil} value indicates that the \emph{variable} has been
                declared \cdf{dynamic-extent}. If the value is \cdf{nil}, the pair
                might be omitted.

\item[\cdf{ignore}]
A non-\cdf{nil} value indicates that the \emph{variable} has been declared
                \cdf{ignore}. If the value is \cdf{nil}, the pair might be omitted.

\item[\cdf{type}]
The value is a type specifier associated with the \emph{variable} by a \cdf{type}
                declaration or an abbreviated declaration such as
                \cd{(fixnum \emph{variable})}.
                If no explicit association exists, either by \cdf{proclaim} or
                \cdf{declare}, then the type specifier is \cdf{t}.  It is permissible for
                implementations to use a type specifier that is equivalent
                to or a supertype of the one appearing in the original
                declaration.  If the value is \cdf{t}, the pair might be
                omitted.
\end{indentdesc}
  If an implementation supports additional declaration specifiers that
  apply to variable bindings, those declaration names might also
  appear in the a-list.  However, the corresponding key must not
  be a symbol that is external in any package defined in the standard
  or that is otherwise accessible in the \cdf{common-lisp-user} package.

  The a-list might contain multiple entries for a given key.
  The consequences of destructively modifying the list
  structure of this a-list or its elements (except for values that 
  appear in the a-list as a result of \cdf{define-declaration}) are undefined.

  Note that the global binding might differ from the
  local one and can be retrieved by calling \cdf{variable-information}
  with a null lexical environment.
\end{defun}

\begin{defun}[Function]
function-information function &optional env

  This function returns information about the interpretation of the function-name
  \emph{function} when it appears in a functional position within lexical 
  environment \emph{env}.  Three values are returned.

  The first value indicates the type of definition or binding of the function-name
  which is apparent in \emph{env}:
\begin{indentdesc}{7pc}
\item[\cdf{nil}] There is no apparent definition for \emph{function}.

\item[\cd{:function}] The \emph{function} refers to a function.

\item[\cd{:macro}] The \emph{function} refers to a macro.

\item[\cd{:special-form}] The \emph{function} refers to a special operator.
\end{indentdesc}
  Some function-names can refer to both a global macro and a global special
  form.  In such a case the macro takes precedence and \cd{:macro} is returned as
  the first value.

  The second value specifies whether the definition is local or global.  If
  local, the second value is true; it is \cdf{nil} when the definition is
  global.

  The third value is an a-list containing information about declarations
  that apply to the apparent binding of the function.  The keys in the a-list
  are symbols that name declaration specifiers, and the format of the
  corresponding values in the \emph{cdr} of each pair depends on the particular 
  declaration name involved.  The standard declaration names
  that might appear as keys in this a-list are:
\begin{indentdesc}{7pc}
\item[\cdf{dynamic-extent}]
A non-\cdf{nil} value indicates that the function has been
                declared \cdf{dynamic-extent}.  If the value is \cdf{nil}, the pair
                might be omitted.

\item[\cdf{inline}]
The value is one of the symbols \cdf{inline}, \cdf{notinline}, or \cdf{nil} to indicate
                whether the function-name has been declared \cdf{inline},
                declared \cdf{notinline}, or neither, respectively.
                If the value is \cdf{nil}, the pair might be omitted.

\item[\cdf{ftype}]
The value is the type specifier associated with the function-name in the
                environment, or the symbol \cdf{function} if there is no functional
                type declaration or proclamation associated with the function-name.
                This value might not include all the apparent \cdf{ftype}
                declarations for the function-name.  It is permissible for
                implementations to use a type specifier that is equivalent
                to or a supertype of the one that appeared in the original
                declaration.  If the value is \cdf{function}, the pair might be
                omitted. 
\end{indentdesc}
  If an implementation supports additional declaration specifiers that
  apply to function bindings, those declaration names might also
  appear in the a-list.  However, the corresponding key must not be
  a symbol that is external in any package defined in the standard or
  that is otherwise accessible in the \cdf{common-lisp-user} package.

  The a-list might contain multiple entries for a given key.
  In this case the value associated with the first entry has
  precedence.  The consequences of destructively modifying the list
  structure of this a-list or its elements (except for values
  that appear in the a-list as a result of \cdf{define-declaration}) are 
  undefined.

  Note that the global binding might differ from the local
  one and can be retrieved by calling \cdf{function-information} with a null
  lexical environment.
\end{defun}

\begin{defun}[Function]
declaration-information decl-name &optional env

  This function returns information about declarations named by the
  symbol \emph{decl-name} that are in force in the environment \emph{env}.
  Only declarations that do not apply to function or variable bindings
  can be accessed with this function.  The format of the information
  that is returned depends on the \emph{decl-name} involved.

  It is required that this function recognize \cdf{optimize} and \cdf{declaration} as
  \emph{decl-name\/}s.  The values returned for these two cases are as follows:
\begin{indentdesc}{7pc}
\item[\cdf{optimize}]
A single value is returned,
a list whose entries are of the form \cd{(\emph{quality} \emph{value})}, where
                \emph{quality} is one of the standard optimization qualities
                (\cdf{speed}, \cdf{safety}, \cdf{compilation-speed}, \cdf{space}, \cdf{debug})
                or some implementation-specific optimization quality, and
                \emph{value} is an integer in the range 0 to 3 (inclusive).
                The returned list
                always contains an entry for each of the standard qualities and
                for each of the implementation-specific qualities.  In the
                absence of any previous declarations, the associated values are
                implementation-dependent.  The list might contain multiple
                entries for a quality, in which case the first such entry
                specifies the current value.
                The consequences of destructively modifying this list or
		its elements are undefined.
                

\item[\cdf{declaration}]
A single value is returned,
a list of the declaration names that have been proclaimed as
                valid through the use of the \cdf{declaration} proclamation.
                The consequences of destructively modifying this list or
		its elements are undefined.
\end{indentdesc}
  If an implementation is extended to recognize additional
  declaration specifiers in \cdf{declare} or \cdf{proclaim}, it is required that
  either the \cdf{declaration-information} function should recognize those
  declarations also or the implementation should provide a similar accessor that is
  specialized for that declaration specifier.  If \cdf{declaration-information}
  is used to return the information, the corresponding \emph{decl-name} must not
  be a symbol that is external in any package defined in the standard or
  that is otherwise accessible in the \cdf{common-lisp-user} package.
\end{defun}

\begin{defun}[Function]
augment-environment env &key :variable :symbol-macro :function :macro :declare

  This function returns a new environment containing the information present in
  \emph{env} augmented with the information provided by the keyword arguments.  It is
  intended to be used by program analyzers that perform a code walk.

  The arguments are supplied as follows.
\begin{flushdesc}
\item[\cd{:variable}]
     The argument is a list of symbols that will be visible as bound variables in
                the new environment.  Whether each binding is to be interpreted
                as special or lexical depends on \cdf{special} declarations recorded
                in the environment or provided in the \cd{:declare} argument.

\item[\cd{:symbol-macro}]
 The argument is a list of symbol macro definitions, each of the form
                \cd{(\emph{name} \emph{definition})}; that is, the argument is
                in the same format as the
                \emph{cadr} of a \cdf{symbol-macrolet} special operator.  The new environment
                will have local symbol-macro bindings of each symbol to the
                corresponding expansion, so that \cdf{macroexpand} will be able to
                expand them properly.  A type declaration in the \cd{:declare}
                argument that refers to a name in this list implicitly
                modifies the definition associated with the name.  The effect
                is to wrap a \cdf{the} form mentioning the type around the
                definition.

\item[\cd{:function}]
     The argument is a list of function-names that will be visible as local
                function bindings in the new environment.

\item[\cd{:macro}]
        The argument is a list of local macro definitions, 
        each of the form \cd{(\emph{name} \emph{definition})}.
        Note that the argument is \emph{not}
                in the same format as the
                \emph{cadr} of a \cdf{macrolet} special operator.
                Each \emph{definition} must be a function of two
                arguments (a form and an environment).  The new environment
                will have local macro bindings of each name to the
                corresponding expander function, which will be returned by
                \cdf{macro-function} and used by \cdf{macroexpand}.

\item[\cd{:declare}]
      The argument is a list of declaration specifiers.
      Information about these declarations can
                be retrieved from the resulting environment using
                \cdf{variable-information}, \cdf{function-information}, and
                \cdf{declaration-information}.
\end{flushdesc}
  The consequences of subsequently
  destructively modifying the list
  structure of any of the arguments to this function are undefined.

  An error is signaled if any of the symbols naming a symbol macro in the
  \cd{:symbol-macro} argument is also included in the \cd{:variable} argument.
  An error is
  signaled if any symbol naming a symbol macro in the \cd{:symbol-macro} argument is
  also included in a \cdf{special} declaration specifier in the \cd{:declare} argument.
  An error is
  signaled if any symbol naming a macro in the \cd{:macro} argument is also included
  in the \cd{:function} argument.
  The condition type of each of these errors is \cdf{program-error}.

  The extent of the returned environment is the same as the extent of the
  argument environment \emph{env}.  The result might share structure with \emph{env}
  but \emph{env} is not modified.

  While an environment argument received by an \cdf{*evalhook*}
  function is permitted to be used as the
  environment argument to \cdf{augment-environment}, the consequences are undefined if an
  attempt is made to use the result of \cdf{augment-environment} as the environment
  argument for \cdf{evalhook}.  The environment
  returned by \cdf{augment-environment} can be used only for syntactic analysis, that is,
  as an argument to
  the functions defined in this section and functions such as \cdf{macroexpand}.
\end{defun}

\begin{defmac}
define-declaration decl-name lambda-list {form}*

  This macro defines a handler for the named declaration.  It is the mechanism by which
  \cdf{augment-environment} is extended to support additional declaration
  specifiers.  The function defined by this macro will be called with two
  arguments, a declaration specifier whose \emph{car} is \emph{decl-name}
  and the \emph{env} argument to
  \cdf{augment-environment}.  This function must return two values.  The
  first value must be one of the following keywords:
\begin{indentdesc}{7pc}
\item[\cd{:variable}]     The declaration applies to variable bindings.
\item[\cd{:function}]     The declaration applies to function bindings.
\item[\cd{:declare}]      The declaration does not apply to bindings.
\end{indentdesc}
If the first value is \cd{:variable} or \cd{:function}
then the second value must be a list, the elements of which are lists of the
  form \cd{(\emph{binding-name} \emph{key} \emph{value})}.  If the corresponding information
  function (either \cdf{variable-information} or \cdf{function-information}) is applied to
  the \emph{binding-name} and the augmented environment, the a-list returned
  by the information function as its third value will contain the \emph{value}
  under the specified \emph{key}.

  If the first value is \cd{:declare}, the second value must be a cons
  of the form \cd{(\emph{key}~.~\emph{value})}.  The function
  \cdf{declaration-information} will return \emph{value} when applied to the
  \emph{key} and the augmented environment.

  \cdf{define-declaration} causes \emph{decl-name} to be proclaimed to be a
  declaration; it is as if its expansion included a call \cd{(proclaim
  '(declaration \emph{decl-name}))}.  As is the case with standard
  declaration specifiers, the evaluator and compiler are permitted,
  but not required, to add information about declaration specifiers
  defined with \cdf{define-declaration} to the macro expansion and \cdf{*evalhook*}
  environments.

  The consequences are undefined if \emph{decl-name} is a symbol that can
  appear as the \emph{car} of any standard declaration specifier.

  The consequences are also undefined if the return value from a 
  declaration handler defined with \cdf{define-declaration} includes a \emph{key} name
  that is used by the corresponding accessor to return information about
  any standard declaration specifier.  (For example, if
  the first return value from the handler is \cd{:variable}, the second return
  value may not use the symbols \cdf{dynamic-extent}, \cdf{ignore}, or \cdf{type}
  as \emph{key} names.)

  The \cdf{define-declaration} macro does not have any special compile-time
  side effects (see section~\ref{COMPILER-SECTION}).
\end{defmac}

\begin{defun}[Function]
parse-macro name lambda-list body &optional env

  This function is used to process a macro definition in the same way
  as \cdf{defmacro} and \cdf{macrolet}.  It returns a lambda-expression that accepts
  two arguments, a form and an environment.  The \emph{name}, \emph{lambda-list},
  and \emph{body} arguments correspond to the parts of a \cdf{defmacro} or \cdf{macrolet}
  definition.

  The \emph{lambda-list} argument may include \cd{\&environment} and \cd{\&whole}
  and may include destructuring.
  The \emph{name}
  argument is used to enclose the \emph{body} in an implicit \cdf{block} and might also
  be used for implementation-dependent purposes (such as including the name of
  the macro in error messages if the form does not match the \emph{lambda-list}).
\end{defun}

\begin{defun}[Function]
enclose lambda-expression &optional env

  This function returns an object of type \cdf{function} that is equivalent to what
  would be obtained by evaluating \cd{{\Xbq}(function ,\emph{lambda-expression})}
  in a syntactic
  environment \emph{env}.  The \emph{lambda-expression} is permitted to reference only the
  parts of the environment argument \emph{env} that are relevant only to syntactic
  processing, specifically declarations and the definitions of macros and
  symbol macros.  The consequences are undefined if the \emph{lambda-expression}
  contains any references to variable or function bindings that are 
  lexically visible in \emph{env}, any \cdf{go} to a tag that is lexically visible in 
  \emph{env}, or any \cdf{return-from} mentioning a block name that is lexically 
  visible in \emph{env}.
\end{defun}

\fi