declar.tex

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

\clearpage\def\pagestatus{ULTIMATE}

\ifx \rulang\Undef

\chapter{Declarations}
\label{DECLAR}

Declarations allow you to specify extra information about your program
to the Lisp system.  With one exception,
declarations are completely optional
and correct declarations do not affect the meaning
of a correct program.  The exception is that
\cdf{special} declarations \emph{do} affect the interpretation of variable
bindings and references and so \emph{must} be specified where appropriate.
All other declarations are of an advisory nature, and may be used
by the Lisp system to aid the programmer by performing extra error checking
or producing more efficient compiled code.  Declarations are also
a good way to add documentation to a program.

Note that it is considered an error for a program to violate a
declaration (such as a \cdf{type} declaration), but an implementation is
not required to detect such errors (though such detection, where
feasible, is to be encouraged).

\section{Declaration Syntax}
\label{DECLARE-SYNTAX-SECTION}

The \cdf{declare} construct is used for embedding declarations within
executable code.  Global declarations and declarations that are computed
by a program are established by the \cdf{proclaim} construct.

Macro \cdf{declaim}, which is guaranteed
to be recognized appropriately by the compiler, is often more convenient
than \cdf{proclaim} for establishing global declarations.

\begin{defspec}
declare {decl-spec}*

A \cdf{declare} form is known as a \emph{declaration}.
Declarations may occur only at the beginning of the bodies of
certain special operators;
that is, a declaration may occur only as a statement
of such a special operator, and all statements preceding it (if any) must
also be \cdf{declare} forms (or possibly documentation strings, in some cases).
Declarations may occur in lambda-expressions and in the forms listed here.
\begin{lisp}
\hskip 12pc\=\kill
\cdf{define-setf-method}\>\cdf{labels} \\*
\cdf{defmacro}\>\cdf{let} \\*
\cdf{defsetf}\>\cdf{let*} \\*
\cdf{deftype}\>\cdf{locally} \\
\cdf{defun}\>\cdf{macrolet} \\
\cdf{do}\>\cdf{multiple-value-bind} \\
\cdf{do*}\>\cdf{prog} \\
\cdf{do-all-symbols}\>\cdf{prog*} \\
\cdf{do-external-symbols}\>\cdf{with-input-from-string} \\
\cdf{do-symbols}\>\cdf{with-open-file} \\
\cdf{dolist}\>\cdf{with-open-stream} \\*
\cdf{dotimes}\>\cdf{with-output-to-string} \\*
\cdf{flet}\>\cdf{with-conditions-restarts} \\
\cdf{print-unreadable-object}\>\cdf{with-standard-io-syntax}
\end{lisp}
 
\begin{lisp}
\hskip 12pc\=\kill
\cdf{defgeneric}\>\cdf{generic-function} \\*
\cdf{define-method-combination}\>\cdf{generic-labels} \\*
\cdf{defmethod} %\>\cdf{with-added-methods} \\*
%\cdf{generic-flet}
\end{lisp}

\begin{lisp}
\hskip 12pc\=\kill
\cdf{symbol-macrolet}\>\cdf{with-slots} \\*
\cdf{with-accessors}
\end{lisp}

It is an error to attempt to evaluate a declaration.
Those special operators that permit declarations to appear
perform explicit checks for their presence.

It is permissible for a macro call to expand into a declaration
and be recognized as such, provided that the macro call
appears where a declaration may legitimately appear.
(However, a macro call may not appear in place of a \emph{decl-spec}.)

A declaration is recognized only as such if
it appears explicitly, as a list whose \emph{car} is the symbol \cdf{declare},
in the body of a relevant special operator.  (Note, however, that it
is still possible for a macro to expand into a call to the \cdf{proclaim}
function.)

Each \emph{decl-spec} is a list whose \emph{car} is a symbol
specifying the kind of declaration to be made.  Declarations may be
divided into two classes: those that concern the bindings of variables,
and those that do not. (The \cdf{special} declaration is the sole
exception: it effectively falls into both classes, as explained below.)
Those that concern variable bindings apply
only to the bindings made by the form at the head of whose body they
appear.  For example, in
\begin{lisp}
(defun foo (x) \\
~~(declare (type float x)) ... \\
~~(let ((x 'a)) ...) \\
~~...)
\end{lisp}
the \cdf{type} declaration applies only to the outer binding of \cdf{x},
and not to the binding made in the \cdf{let}.

Declarations that do not concern themselves with variable bindings are
pervasive, affecting all code in the body of the special operator.
As an example of a pervasive declaration,
\begin{lisp}
(defun foo (x y) (declare (notinline floor)) ...)
\end{lisp}
advises that everywhere within the body of \cdf{foo} the function
\cdf{floor} should not be open-coded but called as an out-of-line subroutine.

Some special operators contain pieces of code that, properly speaking,
are not part of the body of the special operator.  Examples of this
are initialization forms that provide values for bound variables,
and the result forms of iteration constructs.
In all cases such additional code is within the scope of any pervasive
declarations appearing before the body of the special operator.
Non-pervasive declarations have no effect on such code, except (of course)
in those situations where the code is defined to be within the scope
of the variables affected by such non-pervasive declarations.
For example:
\begin{lisp}
(defun few (x \cd{\&optional} (y *print-circle*)) \\*
~~(declare (special *print-circle*)) \\*
~~...)
\end{lisp}
The reference to \cdf{*print-circle*} in the first line of this example is special
because of the declaration in the second line.
\begin{lisp}
(defun nonsense (k x z) \\*
~~(foo z x)~~~~~~~~~~~~~~~;\textrm{First call to \cdf{foo}} \\*
~~(let ((j (foo k x))~~~~~;\textrm{Second call to \cdf{foo}} \\*
~~~~~~~~(x (* k k))) \\*
~~~~(declare (inline foo) (special x z)) \\*
~~~~(foo x j z)))~~~~~~~~~;\textrm{Third call to \cdf{foo}}
\end{lisp}
In this rather nonsensical example,
the \cdf{inline} declaration applies to the
second and third calls to \cdf{foo}, but not to the first one.
The \cdf{special} declaration of \cdf{x} causes the \cdf{let} form
to make a special binding for \cdf{x} and causes the reference to \cdf{x}
in the body of the \cdf{let} to be a special reference.
The reference to \cdf{x} in the second call to \cdf{foo} is also a special
reference.
The reference to \cdf{x} in the first call to \cdf{foo} is a local
reference, not a special one.  The \cdf{special} declaration of \cdf{z}
causes the reference to \cdf{z} in the call
to \cdf{foo} to be a special reference; it will not
refer to the parameter to \cdf{nonsense} named \cdf{z}, because that
parameter binding has not been declared to be \cdf{special}.
(The \cdf{special} declaration of \cdf{z} does not appear in the body
of the \cdf{defun}, but in an inner construct, and therefore does not
affect the binding of the parameter.)

\begin{new}
X3J13 voted in January 1989
\issue{DECLARATION-SCOPE}
to replace the rules concerning the scope of
declarations occurring at the head of a special operator or lambda-expression:
\begin{itemize}
\item The scope of a declaration always includes the body forms, as well as any
``stepper'' or ``result'' forms (which are logically part of the body), of the
special operator or lambda-expression.

\item If the declaration applies to a name binding, then the scope of the
declaration also includes the scope of the name binding.
\end{itemize}
Note that
the distinction between pervasive and non-pervasive
declarations is eliminated.  An important change
from the first edition is that ``initialization''
forms are specifically \emph{not} included as part of the body under the first
rule; on the other hand, in many cases initialization forms may fall
within the scope of certain declarations under the second rule.
\end{new}

\begin{new}
X3J13 also voted in January 1989
\issue{DECLARE-TYPE-FREE}
to change the interpretation
of \cdf{type} declarations (see section \ref{DECLARATION-SPECIFIERS-SECTION}).
\end{new}

\begin{new}
These changes affect the interpretation of some of the examples from the
first edition.
\begin{lisp}
(defun foo (x) \\*
~~(declare (type float x)) ... \\*
~~(let ((x 'a)) ...) \\*
~~...)
\end{lisp}
Under the interpretation approved by X3J13, the type
declaration applies to \emph{both} bindings of \cdf{x}.
More accurately, the type declaration is considered to apply to
variable references rather than bindings, and the type declaration refers
to every reference in the body of \cdf{foo} to a variable named \cdf{x},
no matter to what binding it may refer.
\begin{lisp}
(defun foo (x y) (declare (notinline floor)) ...)
\end{lisp}
This example of the use of \cdf{notinline} stands unchanged, but the following
slight extension of it would change:
\begin{lisp}
(defun foo (x \&optional (y (floor x))) \\*
~~(declare (notinline floor)) ...)
\end{lisp}
Under first edition rules, the \cdf{notinline} declaration would be
considered to apply to the call to \cdf{floor} in the initialization
form for \cdf{y}.  Under the interpretation approved by X3J13, the
\cdf{notinline} would \emph{not} apply to that particular call to \cdf{floor}.
Instead the user must write something like
\begin{lisp}
(defun foo (x \&optional (y (locally (declare (notinline floor)) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(floor x)))) \\*
~~(declare (notinline floor)) ...)
\end{lisp}
or perhaps
\begin{lisp}
(locally (declare (notinline floor)) \\*
~~(defun foo (x \&optional (y (floor x))) ...))
\end{lisp}
Similarly, the \cdf{special} declaration in
\begin{lisp}
(defun few (x \cd{\&optional} (y *print-circle*)) \\*
~~(declare (special *print-circle*)) \\*
~~...)
\end{lisp}
is not considered to apply to the reference in the initialization form
for \cdf{y} in \cdf{few}.  As for the \cdf{nonsense} example,
\begin{lisp}
(defun nonsense (k x z) \\*
~~(foo z x)~~~~~~~~~~~~~~~;\textrm{First call to \cdf{foo}} \\*
~~(let ((j (foo k x))~~~~~;\textrm{Second call to \cdf{foo}} \\*
~~~~~~~~(x (* k k))) \\*
~~~~(declare (inline foo) (special x z)) \\*
~~~~(foo x j z)))~~~~~~~~~;\textrm{Third call to \cdf{foo}}
\end{lisp}
under the interpretation approved by X3J13, the \cdf{inline}
declaration is no longer considered to apply to the second
call to \cdf{foo}, because it is in an initialization form, which is
no longer considered in the scope of the declaration.  Similarly,
the reference to \cdf{x} in that second call to \cdf{foo} is no longer
taken to be a special reference, but a local reference to the second
parameter of \cdf{nonsense}.
\end{new}
\end{defspec}

\cdf{locally} executes the \emph{form\/}s as an implicit
\cdf{progn} and returns the value(s) of the last \emph{form}.

\begin{defspec}
locally {declaration}* {form}*

This change was made to accommodate the new compilation model for top-level forms
in a file (see section~\ref{COMPILER-SECTION}).
When a \cdf{locally} operator appears at top level, the forms in its body are
processed as top-level forms.  This means that one may, for example, meaningfully use
\cdf{locally} to wrap declarations around a \cdf{defun} or \cdf{defmacro} form:
\begin{lisp}
(locally \\*
~~(declare (optimize (safety 3) (space 3) (debug 3) (speed 1))) \\*
~~(defun foo (x \&optional (y (abs x)) (z (sqrt y))) \\*
~~~~(bar x y z)))
\end{lisp}
Without assurance that this works
one must write something cumbersome such as
\begin{lisp}
 \\*
(defun foo (x \&optional (y (locally \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(declare (optimize (safety 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(space 3) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(debug 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(speed 1))) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(abs x))) \\
~~~~~~~~~~~~~~~~~~~~~~~~~(z (locally \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(declare (optimize (safety 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(space 3) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(debug 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(speed 1))) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(sqrt y)))) \\
~~(locally \\*
~~~~(declare (optimize (safety 3) (space 3) (debug 3) (speed 1))) \\*
~~~~(bar x y z)))
\end{lisp}
\end{defspec}

\begin{defun}[Function]
proclaim decl-spec

The function \cdf{proclaim} takes a \emph{decl-spec} as its
argument and puts it into effect globally.  (Such a global
declaration is called a \emph{proclamation}.)
Because \cdf{proclaim} is a function, its argument is always evaluated.
This allows a program to compute a declaration and then put
it into effect by calling \cdf{proclaim}.

Any variable names
mentioned are assumed to refer to the dynamic values of the
variable.  For example, the proclamation
\begin{lisp}
(proclaim '(type float tolerance))
\end{lisp}
once executed,
specifies that the dynamic value of \cdf{tolerance} should always
be a floating-point number.
Similarly, any function-names mentioned are assumed to refer to
the global function definition.

A proclamation constitutes a universal declaration, always in force
unless locally shadowed.  For example,
\begin{lisp}
(proclaim '(inline floor))
\end{lisp}
advises that \cdf{floor} should normally be open-coded in-line by the
compiler (but in the situation
\begin{lisp}
(defun foo (x y) (declare (notinline floor)) ...)
\end{lisp}
it will be compiled out-of-line anyway in the body of \cdf{foo},
because of the shadowing local declaration to that effect).

\begin{newer}
X3J13 voted in January 1989 \issue{SPECIAL-TYPE-SHADOWING}
to clarify that such shadowing does not occur in the case of type declarations.
If there is a local type declaration for a special variable and there is also a global
proclamation for that same variable, then the value of the variable within the scope
of the local declaration must be a member of the intersection of the two
declared types.
This is consistent with the treatment of nested local type declarations
on which X3J13 also voted in January 1989 \issue{DECLARE-TYPE-FREE}.
\end{newer}

As a special case (so to speak), \cdf{proclaim} treats a \cdf{special}
\emph{decl-spec} as applying to all bindings as well as to
all references of the mentioned variables.
\begin{new}%CORR
\emph{Notice of correction.}
In the first edition, this sentence referred to a ``\cdf{special}
\emph{declaration-form}.''  That was incorrect; \cdf{proclaim} accepts
only a \emph{decl-spec}, not a \emph{declaration-form}.
\end{new}

For example, after
\begin{lisp}
(proclaim '(special x))
\end{lisp}
in a function definition such as
\begin{lisp}
(defun example (x) ...)
\end{lisp}
the parameter \cdf{x} will be bound as a special (dynamic) variable
rather than as a lexical (static) variable.  This facility should
be used with caution.  The usual way to define a globally special
variable is with \cdf{defvar} or \cdf{defparameter}.
\end{defun}

\begin{defmac}
declaim {decl-spec}*

This macro is syntactically like \cdf{declare} and semantically
like \cdf{proclaim}.  It is an executable form and may be used
anywhere \cdf{proclaim} may be called.  However, each \emph{decl-spec}
is not evaluated.

If a call to this macro appears at top level in a file
being processed by the file compiler, the proclamations are also
made at compile time.  As with other defining macros, it is 
unspecified whether or not the compile-time side effects of a 
\cdf{declaim} persist after the file has been compiled
(see section~\ref{COMPILER-SECTION}).
\end{defmac}

\section{Declaration Specifiers}
\label{DECLARATION-SPECIFIERS-SECTION}

Here is a list of valid declaration specifiers for use in
\cdf{declare}.  A construct is said to be ``affected'' by a declaration
if it occurs within the scope of a declaration.

\begin{flushdesc}
\item[\cdf{special}]
\cd{(special \emph{var1} \emph{var2} ...)} specifies that all of
the variables named are to be considered \emph{special}.
This specifier affects variable bindings but also pervasively
affects references.
All variable bindings affected are made to be dynamic bindings,
and affected variable references refer to the current dynamic binding
rather than to the current local binding.
For example:
\begin{lisp}
(defun hack (thing *mod*)~~~~~~~;\textrm{The binding of the parameter} \\
~~(declare (special *mod*))~~~~~; \textrm{\cd{*mod*} is visible to \cd{hack1},} \\
~~(hack1 (car thing)))~~~~~~~~~~; \textrm{but not that of \cdf{thing}} \\
 \\
(defun hack1 (arg) \\
~~(declare (special *mod*))~~~~~;\textrm{Declare references to \cd{*mod*}} \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~; \textrm{within \cd{hack1} to be special} \\
~~(if (atom arg) *mod* \\
~~~~~~(cons (hack1 (car arg)) (hack1 (cdr arg)))))
\end{lisp}
Note that it is conventional, though not required, to give special
variables names that begin and end with an asterisk.	

A \cdf{special} declaration does \emph{not} affect bindings pervasively.
Inner bindings of a variable implicitly shadow
a \cdf{special} declaration and must be explicitly re-declared to
be special.
(However, a \cdf{special} proclamation \emph{does} pervasively affect bindings;
this exception is made for reasons of
convenience and compatibility with MacLisp.)
For example:
\begin{lisp}
(proclaim '(special x))~~~~~;\textrm{\cdf{x} is always special} \\
 \\
(defun example (x y) \\
~~(declare (special y)) \\
~~(let ((y 3) (x (* x 2))) \\
~~~~(print (+ y (locally (declare (special y)) y))) \\
~~~~(let ((y 4)) (declare (special y)) (foo x))))
\end{lisp}
In the contorted code above, the outermost and innermost bindings of
\cdf{y} are special and therefore dynamically scoped, but the middle
binding is lexically scoped.  The two arguments to \cdf{+} are different,
one being the value, which is \cd{3}, of the lexically bound variable
\cdf{y}, and the other being the value of the special variable named \cdf{y}
(a binding of which happens, coincidentally, to lexically surround it at
an outer level).  All the bindings of \cdf{x} and references to \cdf{x}
are special, however, because of the proclamation that \cdf{x} is
always \cdf{special}.

As a matter of style, use of \cdf{special} proclamations should be
avoided.  The \cdf{defvar} and \cdf{defparameter} macros
are the conventional means for proclaiming special variables
in a program.

\item[\cdf{type}]
\cd{(type \emph{type} \emph{var1} \emph{var2} ...)} affects
only variable bindings and specifies that the
variables mentioned will take on values only of the specified type.
In particular, values assigned to the variables by \cdf{setq},
as well as the initial values of the variables, must be of
the specified type.

\begin{new}
X3J13 voted in January 1989
\issue{DECLARE-TYPE-FREE}
to alter the interpretation of type declarations.
They are not to be construed to affect ``only variable bindings.''
The new rule for a declaration of a variable to
have a specified type is threefold:
\begin{itemize}
\item It is an error if, during the execution
of any reference to that variable within the scope of the declaration,
the value of the variable is not of the declared type.
\item It is an error if, during the execution
of a \cdf{setq} of that variable within the scope of the declaration,
the new value for the variable is not of the declared type.
\item It is an error if, at any moment that execution enters the scope
of the declaration, the value of the variable is not of the
declared type.
\end{itemize}
One may think of a type declaration \cd{(declare (type face bodoni))}
as implicitly changing every reference to \cdf{bodoni} within the scope
of the declaration to \cd{(the~face bodoni)}; changing every expression
\emph{exp} assigned to \cdf{bodoni} within the scope of the declaration
to \cd{(the~face \emph{exp})}; and implicitly executing \cd{(the~face bodoni)}
every time execution enters the scope of the declaration.

These new rules make type declarations much more useful.  Under first
edition rules, a type declaration was useless if not associated with
a variable binding; declarations such as in
\begin{lisp}
(locally \\*
~~(declare (type (byte 8) x y)) \\*
~~(+ x y))
\end{lisp}
at best had no effect and at worst were erroneous, depending on one's
interpretation of the first edition.  Under the interpretation approved
by X3J13, such declarations have ``the obvious natural interpretation.''

X3J13 noted that if nested type declarations refer to the same variable,
then all of them have effect; the value of the variable must be a member of the
intersection of the declared types.

Nested type declarations could occur as a result of either macro expansion
or carefully crafted code.  There are three cases.  First,
the inner type might be a subtype of the outer one:
\begin{lisp}
(defun compare (apples oranges) \\*
~~(declare (type number apples oranges)) \\
~~(cond ((typep apples 'fixnum) \\*
~~~~~~~~~;; The programmer happens to know that, thanks to \\*
~~~~~~~~~;; constraints imposed by the caller, if APPLES \\*
~~~~~~~~~;; is a fixnum, then ORANGES will be also, and \\*
~~~~~~~~~;; therefore wishes to avoid the unnecessary cost \\*
~~~~~~~~~;; of checking ORANGES.~~Nevertheless the compiler \\*
~~~~~~~~~;; should be informed to allow it to optimize code. \\
~~~~~~~~~(locally (declare (type fixnum apples oranges))) \\*
~~~~~~~~~~~~~~~~~~;; Maybe the compiler could have figured \\*
~~~~~~~~~~~~~~~~~~;; out by flow analysis that APPLES must \\*
~~~~~~~~~~~~~~~~~~;; be a fixnum here, but it doesn't hurt \\*
~~~~~~~~~~~~~~~~~~;; to say it explicitly. \\*
~~~~~~~~~~~(< apples oranges))) \\
~~~~~~~~((or (complex apples) \\*
~~~~~~~~~~~~~(complex oranges)) \\*
~~~~~~~~~(error "Not yet implemented.~~Sorry.")) \\*
~~~~~~~~...))
\end{lisp}
This is the case most likely to arise in code written completely by hand.

Second, the outer type might be a subtype of the inner one.  In this
case the inner declaration has no additional practical effect, but
it is harmless.  This is
likely to occur if code declares a variable to be of a very specific type
and then passes it to a macro that then declares it to be of a less
specific type.

Third, the inner and outer declarations might be for types that
overlap, neither being a subtype of the other.  This is likely to occur
only as a result of macro expansion.  For example, user code might
declare a variable to be of type \cdf{integer}, and a macro might
later declare it to be of type \cd{(or fixnum package)}; in this case
a compiler could intersect the two types to determine that in this
instance the variable may hold only fixnums.

The reader should note that the following code fragment is,
perhaps astonishingly, \emph{not in error} under the interpretation approved by
X3J13:
\begin{lisp}
(let ((james .007) \\*
~~~~~~(maxwell 86)) \\*
~~(flet ((spy-swap () \\*
~~~~~~~~~~~(rotatef james maxwell))) \\*
~~~~(locally (declare (integer maxwell)) \\*
~~~~~~(spy-swap) \\*
~~~~~~(view-movie "The Sound of Music") \\*
~~~~~~(spy-swap) \\*
~~~~~~maxwell))) \\*
~\EV\ 86~~\textrm{(after a couple of hours of Julie Andrews)}
\end{lisp}
The variable \cdf{maxwell} is declared to be an integer over the \emph{scope}
of the type declaration, not over its \emph{extent}.  Indeed \cdf{maxwell}
takes on the non-integer value \cd{.007} while the Trapp family make their
escape, but because no
reference to \cdf{maxwell} within the scope of the declaration
ever produces a non-integer value, the code
is correct.

Now the assignment to \cdf{maxwell} during the first call
to \cdf{spy-swap}, and the reference to \cdf{maxwell} during the second call,
\emph{do} involve non-integer values, but they occur within the body of
\cdf{spy-swap}, which is \emph{not} in the scope of the type declaration!
One could put the declaration in a different place so as to include
\cdf{spy-swap} in the scope:
\begin{lisp}
(let ((james .007) \\*
~~~~~~(maxwell 86)) \\*
~~(locally (declare (integer maxwell)) \\*
~~~~(flet ((spy-swap () \\*
~~~~~~~~~~~~~(rotatef james maxwell))) \\*
~~~~~~(spy-swap)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Bug!}\\*
~~~~~~(view-movie "The Sound of Music") \\*
~~~~~~(spy-swap) \\*
~~~~~~maxwell)))
\end{lisp}
and then the code is indeed in error.
\end{new}

\begin{new}
X3J13 also voted in January 1989
\issue{FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS}
to alter the meaning of the
\cdf{function} type specifier when used in \cdf{type} declarations
(see section~\ref{SPECIALIZED-TYPE-SPECIFIER-SECTION}).
\end{new}

\item[\emph{type}]
\cd{(\emph{type} \emph{var1} \emph{var2} ...)}
is an abbreviation for
\cd{(type \emph{type} \emph{var1} \emph{var2} ...)},
provided that \emph{type} is one of the symbols appearing
in table~\ref{TYPE-SYMBOLS-TABLE}.

\begin{new}
Observe that this covers the particularly common case of declaring
numeric variables:
\begin{lisp}
(declare (single-float mass dx dy dz) \\*
~~~~~~~~~(double-float acceleration sum))
\end{lisp}
In many implementations there is also some advantage to declaring variables
to have certain specialized vector types such as \cdf{base-string}.
\end{new}

\item[\cdf{ftype}]
\cd{(ftype \emph{type} \emph{function-name-1} \emph{function-name-2} ...)}
specifies that the named functions will be of the functional type
\emph{type}, an example of which follows.
For example:
\begin{lisp}
(declare (ftype (function (integer list) t) nth) \\*
~~~~~~~~~(ftype (function (number) float) sin cos))
\end{lisp}
Note that rules of lexical scoping are observed; if one of the functions
mentioned has a lexically apparent local definition
(as made by \cdf{flet} or \cdf{labels}), then the declaration
applies to that local definition and not to the global function definition.

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to extend \cdf{ftype}
declaration specifiers
to accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write
\begin{lisp}
(declaim (ftype (function (list) t) (setf cadr)))
\end{lisp}
to indicate the type of the \cdf{setf} expansion function for \cdf{cadr}.
\end{newer}

\begin{new}
X3J13 voted in January 1989
\issue{FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS}
to alter the meaning of the
\cdf{function} type specifier when used in \cdf{ftype} declarations
(see section~\ref{SPECIALIZED-TYPE-SPECIFIER-SECTION}).
\end{new}
\end{flushdesc}

\begin{new}
X3J13 voted in January 1989
\issue{DECLARE-FUNCTION-AMBIGUITY}
to remove this interpretation
of the \cdf{function} declaration specifier from the language.
Instead, a declaration specifier
\begin{lisp}
(function \emph{var1} \emph{var2} ...)
\end{lisp}
is to be treated simply as an abbreviation for
\begin{lisp}
(type function \emph{var1} \emph{var2} ...)
\end{lisp}
just as for all other symbols appearing in table~\ref{TYPE-SYMBOLS-TABLE}.

X3J13 noted that although \cdf{function} appears in
table~\ref{TYPE-SYMBOLS-TABLE}, the first edition also discussed it
explicitly, with a different meaning,
without noting whether the differing
interpretation was to replace or augment the
interpretation regarding table~\ref{TYPE-SYMBOLS-TABLE}.  Unfortunately
there is an ambiguous case: the declaration
\begin{lisp}
(declare (function foo nil string))
\end{lisp}
can be construed to abbreviate either
\begin{lisp}
(declare (ftype (function () string) foo))
\end{lisp}
or
\begin{lisp}
(declare (type function foo nil string))
\end{lisp}
The latter could perhaps be rejected on semantic grounds: it would be an
error to declare \cdf{nil}, a constant, to be of type \cdf{function}.
In any case, X3J13 determined that the ice was too thin here;
the possibility of confusion is not worth the convenience of
an abbreviation for \cdf{ftype} declarations.
The change also makes the language more consistent.
\end{new}

\begin{flushdesc}
\item[\cdf{inline}]
\cd{(inline \emph{function1} \emph{function2} ...)} specifies that
it is desirable for the compiler to open-code
calls to the specified functions; that is, the code for a specified function
should be integrated into the calling routine, appearing in-line
in place of a procedure call.  This may achieve
extra speed at the expense of debuggability (calls to functions
compiled in-line cannot be traced, for example).
This declaration is pervasive.
Remember that
a compiler is free to ignore this declaration.

Note that rules of lexical scoping are observed; if one of the functions
mentioned has a lexically apparent local definition
(as established by \cdf{flet} or \cdf{labels}), then the declaration
applies to that local definition and not to the global function definition.

\begin{newer}
X3J13 voted in October 1988 \issue{PROCLAIM-INLINE-WHERE}
to clarify that during compilation the \cdf{inline} declaration specifier
serves two distinct purposes: it indicates not only that affected calls
to the specified functions should be expanded in-line, but also that
affected definitions of the specified functions must be recorded for
possible use in performing such expansions.

Looking at it the other way,
the compiler is not required to save function definitions against the
possibility of future expansions unless the functions have already been
proclaimed to be \cdf{inline}.  If a function is proclaimed (or declaimed)
\cdf{inline}
before some call to that function but the current definition of that
function was established before the proclamation was processed,
it is implementation-dependent whether that call will be expanded in-line.
(Of course, it is implementation-dependent anyway, because a compiler
is always free to ignore \cdf{inline} declaration specifiers.
However, the intent of the committee is clear: for best results,
the user is advised to put any \cdf{inline} proclamation of
a function before any definition of or call to that function.)

Consider these examples:
\begin{lisp}
(defun huey (x) (+ x 100))~~~~~~~~~;\textrm{Compiler need not remember this} \\*
(declaim (inline huey dewey)) \\*
(defun dewey (y) (huey (sqrt y)))~~;\textrm{Call to \cdf{huey} unlikely to be expanded} \\*
(defun louie (z) (dewey (/ z)))~~~~;\textrm{Call to \cdf{dewey} likely to be expanded}
\end{lisp}
\goodbreak

X3J13 voted in March 1989 \issue{FUNCTION-NAME} to extend \cdf{inline}
declaration specifiers
to accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write \cd{(declare (inline (setf cadr)))} to indicate
that the \cdf{setf}
expansion function for \cdf{cadr} should be compiled in-line.
\end{newer}

\item[\cdf{notinline}]
\cd{(notinline \emph{function1} \emph{function2} ...)} specifies that it is
\emph{undesirable} to compile the specified functions in-line.
This declaration is pervasive.
A compiler is \emph{not} free to ignore this declaration.

Note that rules of lexical scoping are observed; if one of the functions
mentioned has a lexically apparent local definition
(as made by \cdf{flet} or \cdf{labels}), then the declaration
applies to that local definition and not to the global function definition.

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to extend \cdf{notinline}
declaration specifiers
to accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write \cd{(declare (notinline (setf cadr)))} to indicate
that the \cdf{setf}
expansion function for \cdf{cadr} should not be compiled in-line.
\end{newer}

\begin{new}
X3J13 voted in January 1989
\issue{ALLOW-LOCAL-INLINE}
to clarify that the proper way to define a function \cdf{gnards}
that is not \cdf{inline} by default, but for which a local
declaration \cd{(declare (inline~gnards))} has half a chance of
actually compiling \cdf{gnards} in-line, is as follows:
\begin{lisp}
(declaim (inline gnards)) \\*
\\*
(defun gnards ...) \\*
\\*
(declaim (notinline gnards))
\end{lisp}
The point is that the first declamation informs the compiler that
the definition of \cdf{gnards} may be needed later for in-line expansion,
and the second declamation prevents any expansions unless and until it is
overridden.

While an implementation is never required to perform in-line expansion,
many implementations that do support such expansion will not
process \cdf{inline} requests successfully unless definitions are
written with these proclamations in the manner shown above.
\end{new}

\item[\cdf{ignore}]
\cd{(ignore \emph{var1} \emph{var2} ... \emph{varn})} affects only variable bindings
and specifies that the bindings
of the specified variables are never used. It is desirable for a compiler
to issue a warning if a variable so declared is ever referred to
or is also declared special, or if a variable is lexical, never referred to,
and not declared to be ignored.

\item[\cdf{optimize}]
\cd{(optimize (\emph{quality1} \emph{value1}) (\emph{quality2} \emph{value2})...)}
advises the compiler that each \emph{quality} should be given attention
according to the specified corresponding \emph{value}.
A quality is a symbol; standard qualities
include \cdf{speed} (of the object code), \cdf{space} (both code size and
run-time space), \cdf{safety} (run-time error checking),
and \cdf{compilation-speed} (speed of the compilation process).
\begin{newer}
X3J13 voted in October 1988 \issue{OPTIMIZE-DEBUG-INFO} to add
the standard quality \cdf{debug} (ease of debugging).
\end{newer}
Other qualities may be recognized by particular implementations.
A \emph{value} should be a non-negative integer, normally in the range
\cd{0} to \cd{3}.  The value \cd{0} means that the quality is totally
unimportant, and \cd{3} that the quality is extremely important;
\cd{1} and \cd{2} are intermediate values, with \cd{1} the ``normal''
or ``usual'' value.
One may abbreviate \cd{(\emph{quality} 3)} to simply \emph{quality}.
This declaration is pervasive.
For example:
\begin{lisp}
(defun often-used-subroutine (x y) \\*
~~(declare (optimize (safety 2))) \\*
~~(error-check x y) \\*
~~(hairy-setup x) \\
~~(do ((i 0 (+ i 1)) \\*
~~~~~~~(z x (cdr z))) \\*
~~~~~~((null z) i) \\
~~~~;; This inner loop really needs to burn. \\*
~~~~(declare (optimize speed)) \\*
~~~~(declare (fixnum i)) \\*
~~~~)))
\end{lisp}

\item[\cdf{declaration}]
\cd{(declaration \emph{name1} \emph{name2} ...)} advises the compiler
that each \emph{namej} is a valid but non-standard declaration name.
The purpose of this is to tell one compiler not to issue warnings
for declarations meant for another compiler or other program processor.

The \cdf{declaration} declaration specifier may be used with \cdf{declaim}
as well as \cdf{proclaim}.  The preceding examples would be better written
using \cdf{declaim}, to ensure that the compiler will process them properly.

\begin{lisp}
(declaim (declaration author \\*
~~~~~~~~~~~~~~~~~~~~~~target-language \\*
~~~~~~~~~~~~~~~~~~~~~~target-machine)) \\
 \\
(declaim (target-language ada) \\*
~~~~~~~~~(target-machine IBM-650)) \\
 \\
(defun strangep (x) \\*
~~(declare (author "Harry Tweeker")) \\*
~~(member x '(strange weird odd peculiar)))
\end{lisp}

\item[\cdf{dynamic-extent}]

\cd{(dynamic-extent \emph{item1} \emph{item2} ... \emph{itemn})} declares that
certain variables or function-names refer to data objects whose extents may be
regarded as dynamic; that is, the declaration may be construed as a guarantee on
the part of the programmer that the program will behave correctly even if the
data objects have only dynamic extent rather than the usual indefinite extent.

Each \emph{item} may be either a variable name or \cd{(function \emph{f\/})}
where \emph{f} is a function-name (see section~\ref{FUNCTION-NAME-SECTION}).
(Of course, \cd{(function \emph{f\/})} may be abbreviated in the usual way as
\cd{\#'\emph{f}}.)

  It is permissible for an implementation simply to ignore this declaration.  In
implementations that do not ignore it, the compiler (or interpreter) is free to
make whatever optimizations are appropriate given this information; the most
common optimization is to stack-allocate the initial value of the object. The
data types that can be optimized in this manner may vary from implementation to
implementation.

The meaning of this declaration can be stated more precisely.  We say that
object \emph{x} is an \emph{otherwise inaccessible part} of \emph{y} if and only
if making \emph{y} inaccessible would make \emph{x} inaccessible.  (Note that
every object is an otherwise inaccessible part of itself.)  Now suppose that
construct \emph{c} contains a \cdf{dynamic-extent} declaration for variable (or
function) \emph{v} (which need not be bound by \emph{c}).  Consider the values
$\emph{w}_1, \ldots, \emph{w}_{n}$ taken on by \emph{v}
during the course of some execution of \emph{c}.  The declaration asserts that
if some object \emph{x} is an otherwise inaccessible part of
$\emph{w}_{j}$ whenever $\emph{w}_{j}$ becomes the value of \emph{v}, then just
after execution of $c$ terminates \emph{x} will be either inaccessible or still
an otherwise inaccessible part of the value of \emph{v}.  If this assertion is
ever violated, the consequences are undefined.

  In some implementations, it is possible to allocate data structures in a way
that will make them easier to reclaim than by general-purpose garbage collection
(for example, on the stack or in some temporary area).  The \cdf{dynamic-extent}
declaration is designed to give the implementation the information necessary to
exploit such techniques.

For example, in the code fragment
\begin{lisp} (let ((x (list 'a1 'b1 'c1)) \\* ~~~~~~(y (cons 'a2 (cons 'b2 (cons
'c2 'd2))))) \\* ~~(declare (dynamic-extent x y)) \\* ~~...)
\end{lisp} it is not difficult to prove that the otherwise inaccessible parts of
\cdf{x} include the three conses constructed by \cdf{list}, and that the
otherwise inaccessible parts of \cdf{y} include three other conses manufactured
by the three calls to \cdf{cons}.  Given the presence of the
\cdf{dynamic-extent} declaration, a compiler would be justified in
stack-allocating these six conses and reclaiming their storage on exit from the
\cdf{let} form.

  Since stack allocation of the initial value entails knowing at the object's
creation time that the object can be stack-allocated, it is not generally useful
to declare \cdf{dynamic-extent} for variables that have no lexically apparent
initial value. For example,
\begin{lisp} (defun f () \\* ~~(let ((x (list 1 2 3))) \\* ~~~~(declare
(dynamic-extent x)) \\* ~~~~...))
\end{lisp} would permit a compiler to stack-allocate the list in
\cdf{x}. However,
\begin{lisp} (defun g (x) (declare (dynamic-extent x)) ...) \\* (defun f () (g
(list 1 2 3)))
\end{lisp} could not typically permit a similar optimization in \cdf{f} because
of the possibility of later redefinition of \cdf{g}.  Only an implementation
careful enough to recompile \cdf{f} if the definition of \cdf{g} were to change
incompatibly could stack-allocate the list argument to \cdf{g} in \cdf{f}.

  Other interesting cases are
\begin{lisp} (declaim (inline g)) \\* (defun g (x) (declare (dynamic-extent x))
...) \\* (defun f () (g (list 1 2 3)))
\end{lisp} and
\begin{lisp} (defun f () \\* ~~(flet ((g (x) (declare (dynamic-extent x)) ...))
\\* ~~~~(g (list 1 2 3))))
\end{lisp} In each case some compilers might realize the optimization is
possible and others might not.

  An interesting variant of this is the so-called \emph{stack-allocated rest
list}, which can be achieved (in implementations supporting the optimization) by
\begin{lisp} (defun f (\&rest x) \\* ~~(declare (dynamic-extent x)) \\* ~~...)
\end{lisp} Note here that although the initial value of \cdf{x} is not
explicitly present, nevertheless in the usual implementation strategy the
function \cdf{f} is responsible for assembling the list for \cdf{x} from the
passed arguments, so the \cdf{f} function can be optimized by a compiler to
construct a stack-allocated list instead of a heap-allocated list.

Some Common Lisp functions take other functions as arguments; frequently the
argument function is a so-called \emph{downward funarg}, that is, a functional
argument that is passed only downward and whose extent may therefore be dynamic.
\begin{lisp} (flet ((gd (x) (atan (sinh x)))) \\* ~~(declare (dynamic-extent
\#'gd))~~~~~;\textrm{\cdf{mapcar} won't hang on to \cdf{gd}}\\* ~~(mapcar \#'gd
my-list-of-numbers))
\end{lisp}


The following three examples are in error, since in each case the value of
\cdf{x} is used outside of its extent.
\begin{lisp} (length (let ((x (list 1 2 3))) \\* ~~~~~~~~~~(declare
(dynamic-extent x)) \\*
~~~~~~~~~~x))~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Wrong}
\end{lisp} The preceding code is obviously incorrect, because the cons cells
making up the list in \cdf{x} might be deallocated (thanks to the declaration)
before \cdf{length} is called.
\begin{lisp} (length (list (let ((x (list 1 2 3))) \\* ~~~~~~~~~~~~~~~~(declare
(dynamic-extent x)) \\*
~~~~~~~~~~~~~~~~x)))~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Wrong}
\end{lisp} In this second case it is less obvious that the code is incorrect,
because one might argue that the cons cells making up the list in \cdf{x} have
no effect on the result to be computed by \cdf{length}.  Nevertheless the code
briefly violates the assertion implied by the declaration and is therefore
incorrect.  (It is not difficult to imagine a perfectly sensible implementation
of a garbage collector that might become confused by a cons cell containing a
dangling pointer to a list that was once stack-allocated but then deallocated.)
\begin{lisp} (progn (let ((x (list 1 2 3))) \\* ~~~~~~~~~(declare
(dynamic-extent x)) \\*
~~~~~~~~~x)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Wrong} \\*
~~~~~~~(print "Six dollars is your change have a nice day NEXT!"))
\end{lisp} In this third case it is even less obvious that the code is
incorrect, because the value of \cdf{x} returned from the \cdf{let} construct is
discarded right away by the \cdf{progn}.  Indeed it is, but ``right away'' isn't
fast enough.  The code briefly violates the assertion implied by the declaration
and is therefore incorrect.  (If the code is being interpreted, the interpreter
might hang on to the value returned by the \cdf{let} for some time before it is
eventually discarded.)

Here is one last example, one that has little practical import but is
theoretically quite instructive.
\begin{lisp} (dotimes (j 10) \\* ~~(declare (dynamic-extent j)) \\* ~~(setq foo
3)~~~~~~~~~~~~~~~~~~~~~;\textrm{Correct} \\* ~~(setq foo
j))~~~~~~~~~~~~~~~~~~~~;\textrm{Erroneous---but why? (see text)}
\end{lisp} Since \cdf{j} is an integer by the definition of \cdf{dotimes}, but
\cdf{eq} and \cdf{eql} are not necessarily equivalent for integers, what are the
otherwise inaccessible parts of \cdf{j}, which this declaration requires the
body of the \cdf{dotimes} not to ``save''?  If the value of \cdf{j} is \cd{3},
and the body does \cd{(setq foo~3)}, is that an error?  The answer is no, but
the interesting thing is that it depends on the implementation-dependent
behavior of \cdf{eq} on numbers.  In an implementation where \cdf{eq} and
\cdf{eql} are equivalent for \cd{3}, then \cd{3} is not an otherwise
inaccessible part because \cd{(eq~j (+~2~1))} is true, and therefore there is
another way to access the object besides going through \cdf{j}.  On the other
hand, in an implementation where \cdf{eq} and \cdf{eql} are not equivalent for
\cd{3}, then the particular \cd{3} that is the value of \cdf{j} is an otherwise
inaccessible part, but any other \cd{3} is not.  Thus \cd{(setq foo~3)} is valid
but \cd{(setq foo~j)} is erroneous.  Since \cd{(setq foo~j)} is erroneous in
some implementations, it is erroneous in all portable programs, but some other
implementations may not be able to detect the error.  (If this conclusion seems
strange, it may help to replace \cd{3} everywhere in the preceding argument with
some obvious bignum such as \cd{375374638837424898243} and to replace \cd{10}
with some even larger bignum.)

  The \cdf{dynamic-extent} declaration should be used with great care.  It makes
possible great performance improvements in some situations, but if the user
misdeclares something and consequently the implementation returns a pointer into
the stack (or stores it in the heap), an undefined situation may result and the
integrity of the Lisp storage mechanism may be compromised. Debugging these
situations may be tricky.  Users who have asked for this feature have indicated
a willingness to deal with such problems; nevertheless, I do not encourage
casual users to use this declaration.
\end{flushdesc}

An implementation is free to support other (implementation-dependent)
declaration specifiers as well.
On the other hand, a Common Lisp compiler is free to
ignore entire classes of declaration specifiers (for example,
implementation-dependent declaration specifiers
not supported by that compiler's
implementation), except for the \cdf{declaration} declaration specifier.
Compiler implementors are encouraged, however, to
program the compiler to issue by default a warning if the compiler finds
a declaration specifier of a kind it never uses.  Such a warning is required
in any case
if a declaration specifier is not one of those defined above and has not been
declared in a \cdf{declaration} declaration.

\section{Type Declaration for Forms}

Frequently it is useful to declare that the value produced
by the evaluation of some form will be of a particular type.
Using \cdf{declare} one can declare the type of the value
held by a bound variable, but there is no easy way to declare
the type of the value of an unnamed form.  For this purpose the \cdf{the}
special operator is defined; \cd{(the \emph{type} \emph{form})} means
that the value of \emph{form} is declared to be of type \emph{type}.

\begin{defspec}
the value-type form

The \emph{form} is evaluated; whatever it produces is returned by
the \cdf{the} form.  In addition, it is an error if what is produced
by the \emph{form} does not conform to the data type specified by \emph{value-type}
(which is not evaluated).  (A given implementation may or may not
actually check for this error.  Implementations are encouraged to make an
explicit error check when running interpretively.)  In effect, this
declares that the user undertakes to guarantee that the values of
the form will always be of the specified type.
For example:
\begin{lisp}
(the string (copy-seq x))~~~~~;\textrm{The result will be a string} \\
(the integer (+ x 3))~~~~~~~~~;\textrm{The result of \cdf{+} will be an integer} \\
(+ (the integer x) 3)~~~~~~~~~;\textrm{The value of \cdf{x} will be an integer} \\
(the (complex rational) (* z 3)) \\
(the (unsigned-byte 8) (logand x mask))
\end{lisp}
The \cdf{values} type specifier may be used to indicate the types
of multiple values:
\begin{lisp}
(the (values integer integer) (floor x y)) \\
(the (values string t) \\
~~~~~(gethash the-key the-string-table))
\end{lisp}

\emph{value-type} may be any valid type specifier whatsoever.
The point is that a type specifier need not be one suitable for
discrimination but only for declaration.

In the case that the \emph{form} produces exactly one value and \emph{value-type}
is not a \cdf{values} type specifier, one may describe a \cdf{the} form
as being entirely equivalent to
\begin{lisp}
(let ((\#1=\#:temp \emph{form})) (declare (type \emph{value-type} \#1\#)) \#1\#)
\end{lisp}
A more elaborate expression could be written to describe the case where
\emph{value-type} is a \cdf{values} type specifier.
\end{defspec}

%RUSSIAN
\else

\chapter{Декларации}
\label{DECLAR}

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

Следует отметить, что нарушение декларации рассматривается, как ошибка (как,
например, для декларации \cdf{type}), но реализация может не замечать этих
ошибок (хотя их обнаружение, где это возможно, поощряется).

\section{Синтаксис декларации}
\label{DECLARE-SYNTAX-SECTION}

Конструкция \cdf{declare} используется для встраивания деклараций внутрь
выполняемого кода. Глобальные декларации и декларации, вычисленные программой,
устанавливаются конструкцией \cdf{proclaim}.

Для установки глобальных деклараций часто бывает удобен макрос
\cdf{declaim}, он в отличии от \cdf{proclaim} не вычисляет свои
аргументы.

\begin{defspec}
declare {decl-spec}*

Форма \cdf{declare} известна как \emph{декларация}.
Декларации могут использоваться только в начале тел соответствующих специальных
форм. То есть декларация может использоваться в этом оператора, как
выражение, и все предыдущие  выражение (если есть) также должны быть формами
\cdf{declare} (или, в некоторых случаях, строками документации).
Декларации могут использоваться в лямбда-выражениях и перечисленных ниже формах.
\begin{lisp}
\hskip 12pc\=\kill
\cdf{define-setf-method}\>\cdf{labels} \\*
\cdf{defmacro}\>\cdf{let} \\*
\cdf{defsetf}\>\cdf{let*} \\*
\cdf{deftype}\>\cdf{locally} \\
\cdf{defun}\>\cdf{macrolet} \\
\cdf{do}\>\cdf{multiple-value-bind} \\
\cdf{do*}\>\cdf{prog} \\
\cdf{do-all-symbols}\>\cdf{prog*} \\
\cdf{do-external-symbols}\>\cdf{with-input-from-string} \\
\cdf{do-symbols}\>\cdf{with-open-file} \\
\cdf{dolist}\>\cdf{with-open-stream} \\*
\cdf{dotimes}\>\cdf{with-output-to-string} \\*
\cdf{flet}\>\cdf{with-condition-restarts} \\
\cdf{print-unreadable-object}\>\cdf{with-standard-io-syntax}
\end{lisp}

\begin{lisp}
\hskip 12pc\=\kill
\cdf{defgeneric}\>\cdf{generic-function} \\*
\cdf{define-method-combination}%\>\cdf{generic-labels}
\\*
\cdf{defmethod}%\>\cdf{with-added-methods} \\*
%\cdf{generic-flet}
\end{lisp}

\begin{lisp}
\hskip 12pc\=\kill
\cdf{symbol-macrolet}\>\cdf{with-slots} \\*
\cdf{with-accessors}
\end{lisp}

Вычисление декларации является ошибкой. Операторы, которые позволяют
использовать декларации, явно проверяют их наличие.

Макровызовы могут раскрываться в декларации, при условии, что макровызов указан
в том месте, где могут быть указаны декларации.
(Однако, макровызов не может использоваться в форме declare на месте
\emph{decl-spec}.)

Декларация может использовать только явно в теле соответсвтующего специального
оператора в виде списка, \emph{car} которого равен символу \cdf{declare}.

Каждая форма \emph{decl-spec} является списком, у которого \emph{car} элемент
это символ, указывающий на тип декларации. Декларации могут быть разделены на
два класса: одни относятся к связыванию переменных, другие нет.
(Декларация \cdf{special} является исключением, она попадает в оба класса, это
будет описано ниже.) 
Те, которые касаются связываний переменных, применяются только к связываниям,
созданным в форме, в которой они используются. Например, в 
\begin{lisp}
(defun foo (x) \\
~~(declare (type float x)) ... \\
~~(let ((x 'a)) ...) \\
~~...)
\end{lisp}
декларация \cdf{type} применяется только для внешнего связывания \cd{x}, а не
для связывания, созданного в \cdf{let}.

Декларации, которые не воздействуют на связывания переменных, воздействуют на
весь код тела в оператора.
Например,
\begin{lisp}
(defun foo (x y) (declare (notinline floor)) ...)
\end{lisp}
рекомендует, что везде внутри тела функции \cd{foo}, \cdf{floor} должна быть
вызвана как отдельная подпрограмма, а не встроена в код.

Некоторые операторы содержат части кода, которые, правильнее говоря,
не являются телом этого оператора. Это например код инициализации
переменных и форма результата для циклов.  Во всех случаях, такой
дополнительный код оказывается под воздействием всеобъемлемых
деклараций, которые указаны перед телом оператора.
Невсеобъемлемые декларации не оказывают воздействия на этот код, за
исключением (конечно) ситуаций, когда код находится в области действия
переменной, для которой использовалась декларация.  Например:
\begin{lisp}
(defun few (x \cd{\&optional} (y *print-circle*)) \\*
~~(declare (special *print-circle*)) \\*
~~...)
\end{lisp}
Ссылка на \cdf{*print-circle*} в первой строке примера является специальной, так
как указана соответствующая декларация.
\begin{lisp}
(defun nonsense (k x z) \\*
~~(foo z x)~~~~~~~~~~~~~~~;\textrm{Первый вызов \cdf{foo}} \\*
~~(let ((j (foo k x))~~~~~;\textrm{Второй вызов \cdf{foo}} \\*
~~~~~~~~(x (* k k))) \\*
~~~~(declare (inline foo) (special x z)) \\*
~~~~(foo x j z)))~~~~~~~~~;\textrm{Третий вызов \cdf{foo}}
\end{lisp}
В этом примере, декларация \cdf{inline} применяется только ко второму и третьему вызову
\cd{foo}.
Декларация \cdf{special} для переменной \cd{x} указывает, что форма \cdf{let}
создаст специальное связывание для \cd{x} и тем самым ссылки в теле формы также
будут специальными.
Ссылка на \cd{x} во втором вызове \cd{foo} является специальной.
Ссылка на \cd{x} в первом вызове \cd{foo} является локальной, а не специальной.
Декларация \cdf{special} для \cd{z} указывает на то, что ссылка в вызове
\cd{foo} будет специальной. Это значит ссылка не будет указывать на параметр
функции \cd{nonsense}, так как для параметра декларации \cdf{special} не
указано.
(Декларация \cdf{special} переменной \cd{z} указывается не в теле \cdf{defun}, а
в теле внутренней конструкции \cdf{let}. Таким образом она не воздействует на
связывание параметра функции.)
\begin{new}
X3J13 voted in January 1989
\issue{DECLARATION-SCOPE}
to replace the rules concerning the scope of
declarations occurring at the head of a special operator or lambda-expression:
\begin{itemize}
\item The scope of a declaration always includes the body forms, as well as any
``stepper'' or ``result'' forms (which are logically part of the body), of the
special operator or lambda-expression.

\item If the declaration applies to a name binding, then the scope of the
declaration also includes the scope of the name binding.
\end{itemize}
Note that
the distinction between pervasive and non-pervasive
declarations is eliminated.  An important change
from the first edition is that ``initialization''
forms are specifically \emph{not} included as part of the body under the first
rule; on the other hand, in many cases initialization forms may fall
within the scope of certain declarations under the second rule.
\end{new}

\begin{new}
X3J13 also voted in January 1989
\issue{DECLARE-TYPE-FREE}
to change the interpretation
of \cdf{type} declarations (see section \ref{DECLARATION-SPECIFIERS-SECTION}).
\end{new}

\begin{new}
These changes affect the interpretation of some of the examples from the
first edition.
\begin{lisp}
(defun foo (x) \\*
~~(declare (type float x)) ... \\*
~~(let ((x 'a)) ...) \\*
~~...)
\end{lisp}
Under the interpretation approved by X3J13, the type
declaration applies to \emph{both} bindings of \cdf{x}.
More accurately, the type declaration is considered to apply to
variable references rather than bindings, and the type declaration refers
to every reference in the body of \cdf{foo} to a variable named \cdf{x},
no matter to what binding it may refer.
\begin{lisp}
(defun foo (x y) (declare (notinline floor)) ...)
\end{lisp}
This example of the use of \cdf{notinline} stands unchanged, but the following
slight extension of it would change:
\begin{lisp}
(defun foo (x \&optional (y (floor x))) \\*
~~(declare (notinline floor)) ...)
\end{lisp}
Under first edition rules, the \cdf{notinline} declaration would be
considered to apply to the call to \cdf{floor} in the initialization
form for \cdf{y}.  Under the interpretation approved by X3J13, the
\cdf{notinline} would \emph{not} apply to that particular call to \cdf{floor}.
Instead the user must write something like
\begin{lisp}
(defun foo (x \&optional (y (locally (declare (notinline floor)) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(floor x)))) \\*
~~(declare (notinline floor)) ...)
\end{lisp}
or perhaps
\begin{lisp}
(locally (declare (notinline floor)) \\*
~~(defun foo (x \&optional (y (floor x))) ...))
\end{lisp}
Similarly, the \cdf{special} declaration in
\begin{lisp}
(defun few (x \cd{\&optional} (y *print-circle*)) \\*
~~(declare (special *print-circle*)) \\*
~~...)
\end{lisp}
is not considered to apply to the reference in the initialization form
for \cdf{y} in \cdf{few}.  As for the \cdf{nonsense} example,
\begin{lisp}
(defun nonsense (k x z) \\*
~~(foo z x)~~~~~~~~~~~~~~~;\textrm{First call to \cdf{foo}} \\*
~~(let ((j (foo k x))~~~~~;\textrm{Second call to \cdf{foo}} \\*
~~~~~~~~(x (* k k))) \\*
~~~~(declare (inline foo) (special x z)) \\*
~~~~(foo x j z)))~~~~~~~~~;\textrm{Third call to \cdf{foo}}
\end{lisp}
under the interpretation approved by X3J13, the \cdf{inline}
declaration is no longer considered to apply to the second
call to \cdf{foo}, because it is in an initialization form, which is
no longer considered in the scope of the declaration.  Similarly,
the reference to \cdf{x} in that second call to \cdf{foo} is no longer
taken to be a special reference, but a local reference to the second
parameter of \cdf{nonsense}.
\end{new}
\end{defspec}

\cdf{locally} выполняет формы \emph{form} как неявный \cdf{progn} и возвращает
одно или несколько значений последней формы.

\begin{defspec}
locally {declaration}* {form}*

Когда оператор \cdf{locally} используется на верхнем уровне, тогда формы в его
теле выполняются как формы верхнего уровня. Это означает что, например,
\cdf{locally} можно использовать для оборачивания деклараций вокруг форм
\cdf{defun} или \cdf{defmacro}.
\begin{lisp}
(locally \\*
~~(declare (optimize (safety 3) (space 3) (debug 3) (speed 1))) \\*
~~(defun foo (x \&optional (y (abs x)) (z (sqrt y))) \\*
~~~~(bar x y z)))
\end{lisp}
Без уверенности, что это работает, можно записать что-то вроде этого:
\begin{lisp}
 \\*
(defun foo (x \&optional (y (locally \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(declare (optimize (safety 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(space 3) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(debug 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(speed 1))) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(abs x))) \\
~~~~~~~~~~~~~~~~~~~~~~~~~(z (locally \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(declare (optimize (safety 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(space 3) \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(debug 3) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(speed 1))) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(sqrt y)))) \\
~~(locally \\*
~~~~(declare (optimize (safety 3) (space 3) (debug 3) (speed 1))) \\*
~~~~(bar x y z)))
\end{lisp}
\end{defspec}

\begin{defun}[Функция]
proclaim decl-spec

Функция \cdf{proclaim} в качестве аргумента принимает \emph{decl-spec}, и
применяет указания в глобальном пространстве. (Такие глобальные декларации
называются \emph{прокламации}.)
Так как \cdf{proclaim} является функцией, то её аргумент вычисляется всегда.
Это позволяет программам вычислять декларацию и затем для применения помещать её
в вызов \cdf{proclaim}.

Любые упоминаемые имена переменных указывают на значения
динамических переменных. Например, выполненная прокламация
\begin{lisp}
(proclaim '(type float tolerance))
\end{lisp}
указывает на то, что динамическое значение \cd{tolerance} должно быть всегда
числом с плавающей точкой.
Подобным образом, любые упоминаемые имена функций указывают на глобальные
определения функций.

Прокламации содержат универсальные декларации, которые всегда действуют, кроме
случаев сокрытия их локальными декларациями. Например,
\begin{lisp}
(proclaim '(inline floor))
\end{lisp}
рекомендует то, что \cdf{floor} должна быть встроена в места её вызова. Но в
ситуации 
\begin{lisp}
(defun foo (x y) (declare (notinline floor)) ...)
\end{lisp}
\cdf{floor} будет вызываться как отдельная функция, так как локальная декларация
скрыла прокламацию.

\begin{newer}
X3J13 voted in January 1989 \issue{SPECIAL-TYPE-SHADOWING}
to clarify that such shadowing does not occur in the case of type declarations.
If there is a local type declaration for a special variable and there is also a global
proclamation for that same variable, then the value of the variable within the scope
of the local declaration must be a member of the intersection of the two
declared types.
This is consistent with the treatment of nested local type declarations
on which X3J13 also voted in January 1989 \issue{DECLARE-TYPE-FREE}.
\end{newer}

Специальный случай, когда \cdf{proclaim} обрабатывает \cdf{special}, то
\emph{decl-spec} применяется ко всем связываниям и ссылкам на упомянутую 
переменную.
Например, после
\begin{lisp}
(proclaim '(special x))
\end{lisp}
в определении функции
\begin{lisp}
(defun example (x) ...)
\end{lisp}
параметр \cd{x} будет связан, как специальная (динамическая) переменная, а не
лексическая (статическая). Такой приём должен использоваться аккуратно. Обычный
способ определить глобальную специальную переменную это использовать
\cdf{defvar} или \cdf{defparameter}.
\end{defun}

\begin{defmac}
declaim {decl-spec}*

Этот макрос синтаксически похож на \cdf{declare} и семантически на
\cdf{proclaim}. Это выполняемая форма и она может использоваться везде, где
может \cdf{proclaim}. Однако, формы \emph{decl-spec} не вычисляются.

Если вызов этого макроса произошёл на верхнем уровне в файле, обрабатываемом
компилятором, то прокламации также будут выполнены во время компиляции. 
As with other defining macros, it is 
unspecified whether or not the compile-time side effects of a 
\cdf{declaim} persist after the file has been compiled
(see section~\ref{COMPILER-SECTION}). FIXME
\end{defmac}

\section{Спецификаторы деклараций}
\label{DECLARATION-SPECIFIERS-SECTION}

Ниже представлен список спецификаторов деклараций для использования в
\cdf{declare}.

\begin{flushdesc}
\item[\cdf{special}]
\cd{(special \emph{var1} \emph{var2} ...)} указывает на то, что все указанные
переменные должны рассматриваться как \emph{специальные}.
Данный спецификатор воздействует как на связывания переменных, так и на ссылки
на эти переменные в коде.
Все указанные связывания переменных будут динамическими, и ссылки будут
осуществляться на эти связывания, а не на связывания определённые локально.
Например:
\begin{lisp}
(defun hack (thing *mod*)~~~~~~~;\textrm{Связывание параметра} \\
~~(declare (special *mod*))~~~~~; \textrm{\cd{*mod*} доступно для \cd{hack1},} \\
~~(hack1 (car thing)))~~~~~~~~~~; \textrm{но связывание \cdf{thing} нет} \\
 \\
(defun hack1 (arg) \\
~~(declare (special *mod*))~~~~~;\textrm{Декларируем что ссылка на \cd{*mod*}} \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~; \textrm{внутри \cd{hack1} будет специальной} \\
~~(if (atom arg) *mod* \\
~~~~~~(cons (hack1 (car arg)) (hack1 (cdr arg)))))
\end{lisp}
Следует отметить, что по правилам хорошего тона, имена специальных переменных
окружаются звёздочками.

Декларация \cdf{special} \emph{не} охватывает все связывания.
Внутренние связывания переменных неявно скрывают декларацию \cdf{special} и
должны быть явно передекларированы в специальные.
(Однако прокламация \cdf{special} имеет глобальный эффект. Это сделано для
совместимости с MacLisp'ом.)
Например:
\begin{lisp}
(proclaim '(special x))~~~~~;\textrm{\cdf{x} всегда специальная} \\
 \\
(defun example (x y) \\
~~(declare (special y)) \\
~~(let ((y 3) (x (* x 2))) \\
~~~~(print (+ y (locally (declare (special y)) y))) \\
~~~~(let ((y 4)) (declare (special y)) (foo x))))
\end{lisp}
В приведенном выше коде, внешние и внутренние связывания переменной \cd{y}
являются специальными и, таким образом, действуют в динамической области
видимости. Однако среднее связывание действует в лексической области
видимости. Два аргумента \cdf{+} различаются, один содержит значение \cd{3}
лексически связанной переменной \cd{y}, другой содержит значение специальной
переменной \cd{y}.
Все связывания и переменной \cd{x} и ссылки на неё является специальными,
так как в коде использовалась прокламация \cdf{special}.

В целях стиля, необходимо избегать использование прокламаций \cdf{special}. Для
объявления специальных переменных предназначены макросы \cdf{defvar} и
\cdf{defparameter}.

\item[\cdf{type}]
\cd{(type \emph{type} \emph{var1} \emph{var2} ...)} применяются только для
связываний переменный и указывает на то, что переменные будут принимать значения
только указанного типа.
В частности, значения присваиваемые переменным с помощью \cdf{setq}, как и
первоначальные значения, должны быть заданного типа.

\begin{new}
X3J13 voted in January 1989
\issue{DECLARE-TYPE-FREE}
to alter the interpretation of type declarations.
They are not to be construed to affect ``only variable bindings.''
The new rule for a declaration of a variable to
have a specified type is threefold:
\begin{itemize}
\item It is an error if, during the execution
of any reference to that variable within the scope of the declaration,
the value of the variable is not of the declared type.
\item It is an error if, during the execution
of a \cdf{setq} of that variable within the scope of the declaration,
the new value for the variable is not of the declared type.
\item It is an error if, at any moment that execution enters the scope
of the declaration, the value of the variable is not of the
declared type.
\end{itemize}
One may think of a type declaration \cd{(declare (type face bodoni))}
as implicitly changing every reference to \cdf{bodoni} within the scope
of the declaration to \cd{(the~face bodoni)}; changing every expression
\emph{exp} assigned to \cdf{bodoni} within the scope of the declaration
to \cd{(the~face \emph{exp})}; and implicitly executing \cd{(the~face bodoni)}
every time execution enters the scope of the declaration.

These new rules make type declarations much more useful.  Under first
edition rules, a type declaration was useless if not associated with
a variable binding; declarations such as in
\begin{lisp}
(locally \\*
~~(declare (type (byte 8) x y)) \\*
~~(+ x y))
\end{lisp}
at best had no effect and at worst were erroneous, depending on one's
interpretation of the first edition.  Under the interpretation approved
by X3J13, such declarations have ``the obvious natural interpretation.''

X3J13 noted that if nested type declarations refer to the same variable,
then all of them have effect; the value of the variable must be a member of the
intersection of the declared types.

Nested type declarations could occur as a result of either macro expansion
or carefully crafted code.  There are three cases.  First,
the inner type might be a subtype of the outer one:
\begin{lisp}
(defun compare (apples oranges) \\*
~~(declare (type number apples oranges)) \\
~~(cond ((typep apples 'fixnum) \\*
~~~~~~~~~;; The programmer happens to know that, thanks to \\*
~~~~~~~~~;; constraints imposed by the caller, if APPLES \\*
~~~~~~~~~;; is a fixnum, then ORANGES will be also, and \\*
~~~~~~~~~;; therefore wishes to avoid the unnecessary cost \\*
~~~~~~~~~;; of checking ORANGES.~~Nevertheless the compiler \\*
~~~~~~~~~;; should be informed to allow it to optimize code. \\
~~~~~~~~~(locally (declare (type fixnum apples oranges))) \\*
~~~~~~~~~~~~~~~~~~;; Maybe the compiler could have figured \\*
~~~~~~~~~~~~~~~~~~;; out by flow analysis that APPLES must \\*
~~~~~~~~~~~~~~~~~~;; be a fixnum here, but it doesn't hurt \\*
~~~~~~~~~~~~~~~~~~;; to say it explicitly. \\*
~~~~~~~~~~~(< apples oranges))) \\
~~~~~~~~((or (complex apples) \\*
~~~~~~~~~~~~~(complex oranges)) \\*
~~~~~~~~~(error "Not yet implemented.~~Sorry.")) \\*
~~~~~~~~...))
\end{lisp}
This is the case most likely to arise in code written completely by hand.

Second, the outer type might be a subtype of the inner one.  In this
case the inner declaration has no additional practical effect, but
it is harmless.  This is
likely to occur if code declares a variable to be of a very specific type
and then passes it to a macro that then declares it to be of a less
specific type.

Third, the inner and outer declarations might be for types that
overlap, neither being a subtype of the other.  This is likely to occur
only as a result of macro expansion.  For example, user code might
declare a variable to be of type \cdf{integer}, and a macro might
later declare it to be of type \cd{(or fixnum package)}; in this case
a compiler could intersect the two types to determine that in this
instance the variable may hold only fixnums.

The reader should note that the following code fragment is,
perhaps astonishingly, \emph{not in error} under the interpretation approved by
X3J13:
\begin{lisp}
(let ((james .007) \\*
~~~~~~(maxwell 86)) \\*
~~(flet ((spy-swap () \\*
~~~~~~~~~~~(rotatef james maxwell))) \\*
~~~~(locally (declare (integer maxwell)) \\*
~~~~~~(spy-swap) \\*
~~~~~~(view-movie "The Sound of Music") \\*
~~~~~~(spy-swap) \\*
~~~~~~maxwell))) \\*
~\EV\ 86~~\textrm{(after a couple of hours of Julie Andrews)}
\end{lisp}
The variable \cdf{maxwell} is declared to be an integer over the \emph{scope}
of the type declaration, not over its \emph{extent}.  Indeed \cdf{maxwell}
takes on the non-integer value \cd{.007} while the Trapp family make their
escape, but because no
reference to \cdf{maxwell} within the scope of the declaration
ever produces a non-integer value, the code
is correct.

Now the assignment to \cdf{maxwell} during the first call
to \cdf{spy-swap}, and the reference to \cdf{maxwell} during the second call,
\emph{do} involve non-integer values, but they occur within the body of
\cdf{spy-swap}, which is \emph{not} in the scope of the type declaration!
One could put the declaration in a different place so as to include
\cdf{spy-swap} in the scope:
\begin{lisp}
(let ((james .007) \\*
~~~~~~(maxwell 86)) \\*
~~(locally (declare (integer maxwell)) \\*
~~~~(flet ((spy-swap () \\*
~~~~~~~~~~~~~(rotatef james maxwell))) \\*
~~~~~~(spy-swap)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Bug!}\\*
~~~~~~(view-movie "The Sound of Music") \\*
~~~~~~(spy-swap) \\*
~~~~~~maxwell)))
\end{lisp}
and then the code is indeed in error.
\end{new}

\begin{new}
X3J13 also voted in January 1989
\issue{FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS}
to alter the meaning of the
\cdf{function} type specifier when used in \cdf{type} declarations
(see section~\ref{SPECIALIZED-TYPE-SPECIFIER-SECTION}).
\end{new}

\item[\emph{type}]
\cd{(\emph{type} \emph{var1} \emph{var2} ...)}
является аббревиатурой для \cd{(type \emph{type} \emph{var1} \emph{var2} ...)},
при условии, что \emph{type} один из символов из таблицы~\ref{TYPE-SYMBOLS-TABLE}.

\begin{new}
Observe that this covers the particularly common case of declaring
numeric variables:
\begin{lisp}
(declare (single-float mass dx dy dz) \\*
~~~~~~~~~(double-float acceleration sum))
\end{lisp}
In many implementations there is also some advantage to declaring variables
to have certain specialized vector types such as \cdf{base-string}.
\end{new}

\item[\cdf{ftype}]
\cd{(ftype \emph{type} \emph{function-name-1} \emph{function-name-2} ...)}
указывает но то, что именованная функция будет принимать и возвращать заданный
типы, как в следующем примере:
\begin{lisp}
(declare (ftype (function (integer list) t) nth) \\*
~~~~~~~~~(ftype (function (number) float) sin cos))
\end{lisp}
Следует отметить, что соблюдаются правила лексической области видимости. Если
одна из указанных функций лексически ограничена (с помощью \cdf{flet} или
\cdf{labels}), то декларация применится для локального определения, а не для глобального.

\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to extend \cdf{ftype}
declaration specifiers
to accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write
\begin{lisp}
(declaim (ftype (function (list) t) (setf cadr)))
\end{lisp}
to indicate the type of the \cdf{setf} expansion function for \cdf{cadr}.
\end{newer}

\begin{new}
X3J13 voted in January 1989
\issue{FUNCTION-TYPE-ARGUMENT-TYPE-SEMANTICS}
to alter the meaning of the
\cdf{function} type specifier when used in \cdf{ftype} declarations
(see section~\ref{SPECIALIZED-TYPE-SPECIFIER-SECTION}).
\end{new}


\begin{new}
X3J13 voted in January 1989
\issue{DECLARE-FUNCTION-AMBIGUITY}
to remove this interpretation
of the \cdf{function} declaration specifier from the language.
Instead, a declaration specifier
\begin{lisp}
(function \emph{var1} \emph{var2} ...)
\end{lisp}
is to be treated simply as an abbreviation for
\begin{lisp}
(type function \emph{var1} \emph{var2} ...)
\end{lisp}
just as for all other symbols appearing in table~\ref{TYPE-SYMBOLS-TABLE}.

X3J13 noted that although \cdf{function} appears in
table~\ref{TYPE-SYMBOLS-TABLE}, the first edition also discussed it
explicitly, with a different meaning,
without noting whether the differing
interpretation was to replace or augment the
interpretation regarding table~\ref{TYPE-SYMBOLS-TABLE}.  Unfortunately
there is an ambiguous case: the declaration
\begin{lisp}
(declare (function foo nil string))
\end{lisp}
can be construed to abbreviate either
\begin{lisp}
(declare (ftype (function () string) foo))
\end{lisp}
or
\begin{lisp}
(declare (type function foo nil string))
\end{lisp}
The latter could perhaps be rejected on semantic grounds: it would be an
error to declare \cdf{nil}, a constant, to be of type \cdf{function}.
In any case, X3J13 determined that the ice was too thin here;
the possibility of confusion is not worth the convenience of
an abbreviation for \cdf{ftype} declarations.
The change also makes the language more consistent.
\end{new}

\item[\cdf{inline}]
\cd{(inline \emph{function1} \emph{function2} ...)}  указывает, что \emph{было бы
  неплохо} встроить код указанных функций непосредственно в место вызова.
Это может ускорить работу программы, но затруднить отладку (например, вызовы
встроенных функций не могут быть протрассированы).
Помните, компилятор может игнорировать эту декларацию.

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

\begin{newer}
X3J13 voted in October 1988 \issue{PROCLAIM-INLINE-WHERE}
to clarify that during compilation the \cdf{inline} declaration specifier
serves two distinct purposes: it indicates not only that affected calls
to the specified functions should be expanded in-line, but also that
affected definitions of the specified functions must be recorded for
possible use in performing such expansions.

Looking at it the other way,
the compiler is not required to save function definitions against the
possibility of future expansions unless the functions have already been
proclaimed to be \cdf{inline}.  If a function is proclaimed (or declaimed)
\cdf{inline}
before some call to that function but the current definition of that
function was established before the proclamation was processed,
it is implementation-dependent whether that call will be expanded in-line.
(Of course, it is implementation-dependent anyway, because a compiler
is always free to ignore \cdf{inline} declaration specifiers.
However, the intent of the committee is clear: for best results,
the user is advised to put any \cdf{inline} proclamation of
a function before any definition of or call to that function.)

Consider these examples:
\begin{lisp}
(defun huey (x) (+ x 100))~~~~~~~~~;\textrm{Compiler need not remember this} \\*
(declaim (inline huey dewey)) \\*
(defun dewey (y) (huey (sqrt y)))~~;\textrm{Call to \cdf{huey} unlikely to be expanded} \\*
(defun louie (z) (dewey (/ z)))~~~~;\textrm{Call to \cdf{dewey} likely to be expanded}
\end{lisp}
\goodbreak

X3J13 voted in March 1989 \issue{FUNCTION-NAME} to extend \cdf{inline}
declaration specifiers
to accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write \cd{(declare (inline (setf cadr)))} to indicate
that the \cdf{setf}
expansion function for \cdf{cadr} should be compiled in-line.
\end{newer}

\item[\cdf{notinline}]
\cd{(notinline \emph{function1} \emph{function2} ...)} 
указывает на то, что встраивать код указанных функций в место вызова \emph{не
  нужно}.
Эта декларация обязательна.
Компилятор \emph{не} может её игнорировать.

Следует отметить, что соблюдаются правила лексической области видимости. Если
одна из указанных функций лексически ограничена (с помощью \cdf{flet} или
\cdf{labels}), то декларация применится для локального определения, а не для
глобального.
\begin{newer}
X3J13 voted in March 1989 \issue{FUNCTION-NAME} to extend \cdf{notinline}
declaration specifiers
to accept any function-name (a symbol or a list
whose \emph{car} is \cdf{setf}---see section~\ref{FUNCTION-NAME-SECTION}).
Thus one may write \cd{(declare (notinline (setf cadr)))} to indicate
that the \cdf{setf}
expansion function for \cdf{cadr} should not be compiled in-line.
\end{newer}

\begin{new}
X3J13 voted in January 1989
\issue{ALLOW-LOCAL-INLINE}
to clarify that the proper way to define a function \cdf{gnards}
that is not \cdf{inline} by default, but for which a local
declaration \cd{(declare (inline~gnards))} has half a chance of
actually compiling \cdf{gnards} in-line, is as follows:
\begin{lisp}
(declaim (inline gnards)) \\*
\\*
(defun gnards ...) \\*
\\*
(declaim (notinline gnards))
\end{lisp}
The point is that the first declamation informs the compiler that
the definition of \cdf{gnards} may be needed later for in-line expansion,
and the second declamation prevents any expansions unless and until it is
overridden.

While an implementation is never required to perform in-line expansion,
many implementations that do support such expansion will not
process \cdf{inline} requests successfully unless definitions are
written with these proclamations in the manner shown above.
\end{new}

\item[\cdf{ignore}]
\cd{(ignore \emph{var1} \emph{var2} ... \emph{varn})} применяется только для
связываний переменных и указывает на то, что связывания указанных переменных
никогда не используются. Желательно, чтобы компилятор выдавал предупреждение, если
переменная не используется и не задекларирована игнорироваться.

\item[\cdf{optimize}]
\cd{(optimize (\emph{quality1} \emph{value1}) (\emph{quality2}
  \emph{value2})...)}
рекомендует компилятору использовать указанные значения для свойств компилятора.
Свойство компилятора является символом. Стандартные свойства включают 
\cdf{speed} (скомпилированного кода), \cdf{space} (и размер кода и run-time
space), \cdf{safety} (проверка ошибок во время выполнения) и
\cdf{compilation-speed} (скорость процесса компиляции).

\begin{newer}
X3J13 voted in October 1988 \issue{OPTIMIZE-DEBUG-INFO} to add
the standard quality \cdf{debug} (ease of debugging).
\end{newer}

Также реализацией могут представляться другие свойства. \emph{value} должно быть
неотрицательным целым числом, обычно на интервале \cd{0} и \cd{3}. Значение
\cd{0} означает, что свойство полностью не важно, и \cd{3}, что свойство
полностью важно.
\cd{1} и \cd{2} промежуточные значение, \cd{1} <<нормальный>> или <<обычный>>
уровень.
Для наизначимого уровня существует аббревиатура, то есть \cd{(\emph{quality} 3)}
можно записать, как просто \emph{quality}.
Например:
\begin{lisp}
(defun often-used-subroutine (x y) \\*
~~(declare (optimize (safety 2))) \\*
~~(error-check x y) \\*
~~(hairy-setup x) \\
~~(do ((i 0 (+ i 1)) \\*
~~~~~~~(z x (cdr z))) \\*
~~~~~~((null z) i) \\
~~~~;; This inner loop really needs to burn. \\*
~~~~(declare (optimize speed)) \\*
~~~~(declare (fixnum i)) \\*
~~~~)))
\end{lisp}

\item[\cdf{declaration}]
\cd{(declaration \emph{name1} \emph{name2} ...)} сообщается компилятору, что
каждая \emph{namej} является нестандартным именем декларации.
Целью является указать одному компилятор не создавать предупреждений для
деклараций, которые используются для другого компилятора.


The \cdf{declaration} declaration specifier may be used with \cdf{declaim}
as well as \cdf{proclaim}.  The preceding examples would be better written
using \cdf{declaim}, to ensure that the compiler will process them properly.

\begin{lisp}
(declaim (declaration author \\*
~~~~~~~~~~~~~~~~~~~~~~target-language \\*
~~~~~~~~~~~~~~~~~~~~~~target-machine)) \\
 \\
(declaim (target-language ada) \\*
~~~~~~~~~(target-machine IBM-650)) \\
 \\
(defun strangep (x) \\*
~~(declare (author "Harry Tweeker")) \\*
~~(member x '(strange weird odd peculiar)))
\end{lisp}

\item[\cdf{dynamic-extent}]

\cd{(dynamic-extent \emph{item1} \emph{item2} ... \emph{itemn})} declares that
certain variables or function-names refer to data objects whose extents may be
regarded as dynamic; that is, the declaration may be construed as a guarantee on
the part of the programmer that the program will behave correctly even if the
data objects have only dynamic extent rather than the usual indefinite extent.

Each \emph{item} may be either a variable name or \cd{(function \emph{f\/})}
where \emph{f} is a function-name (see section~\ref{FUNCTION-NAME-SECTION}).
(Of course, \cd{(function \emph{f\/})} may be abbreviated in the usual way as
\cd{\#'\emph{f}}.)

  It is permissible for an implementation simply to ignore this declaration.  In
implementations that do not ignore it, the compiler (or interpreter) is free to
make whatever optimizations are appropriate given this information; the most
common optimization is to stack-allocate the initial value of the object. The
data types that can be optimized in this manner may vary from implementation to
implementation.

The meaning of this declaration can be stated more precisely.  We say that
object \emph{x} is an \emph{otherwise inaccessible part} of \emph{y} if and only
if making \emph{y} inaccessible would make \emph{x} inaccessible.  (Note that
every object is an otherwise inaccessible part of itself.)  Now suppose that
construct \emph{c} contains a \cdf{dynamic-extent} declaration for variable (or
function) \emph{v} (which need not be bound by \emph{c}).  Consider the values
$\emph{w}_1, \ldots, \emph{w}_{n}$ taken on by \emph{v}
during the course of some execution of \emph{c}.  The declaration asserts that
if some object \emph{x} is an otherwise inaccessible part of
$\emph{w}_{j}$ whenever $\emph{w}_{j}$ becomes the value of \emph{v}, then just
after execution of $c$ terminates 
\emph{x} will be either inaccessible or still an otherwise inaccessible part of
the value of \emph{v}.  If this assertion is ever violated, the consequences are
undefined.

  In some implementations, it is possible to allocate data structures in a way
that will make them easier to reclaim than by general-purpose garbage collection
(for example, on the stack or in some temporary area).  The \cdf{dynamic-extent}
declaration is designed to give the implementation the information necessary to
exploit such techniques.

For example, in the code fragment
\begin{lisp} (let ((x (list 'a1 'b1 'c1)) \\* ~~~~~~(y (cons 'a2 (cons 'b2 (cons
'c2 'd2))))) \\* ~~(declare (dynamic-extent x y)) \\* ~~...)
\end{lisp} it is not difficult to prove that the otherwise inaccessible parts of
\cdf{x} include the three conses constructed by \cdf{list}, and that the
otherwise inaccessible parts of \cdf{y} include three other conses manufactured
by the three calls to \cdf{cons}.  Given the presence of the
\cdf{dynamic-extent} declaration, a compiler would be justified in
stack-allocating these six conses and reclaiming their storage on exit from the
\cdf{let} form.

  Since stack allocation of the initial value entails knowing at the object's
creation time that the object can be stack-allocated, it is not generally useful
to declare \cdf{dynamic-extent} for variables that have no lexically apparent
initial value. For example,
\begin{lisp} (defun f () \\* ~~(let ((x (list 1 2 3))) \\* ~~~~(declare
(dynamic-extent x)) \\* ~~~~...))
\end{lisp} would permit a compiler to stack-allocate the list in
\cdf{x}. However,
\begin{lisp} (defun g (x) (declare (dynamic-extent x)) ...) \\* (defun f () (g
(list 1 2 3)))
\end{lisp} could not typically permit a similar optimization in \cdf{f} because
of the possibility of later redefinition of \cdf{g}.  Only an implementation
careful enough to recompile \cdf{f} if the definition of \cdf{g} were to change
incompatibly could stack-allocate the list argument to \cdf{g} in \cdf{f}.

  Other interesting cases are
\begin{lisp} (declaim (inline g)) \\* (defun g (x) (declare (dynamic-extent x))
...) \\* (defun f () (g (list 1 2 3)))
\end{lisp} and
\begin{lisp} (defun f () \\* ~~(flet ((g (x) (declare (dynamic-extent x)) ...))
\\* ~~~~(g (list 1 2 3))))
\end{lisp} In each case some compilers might realize the optimization is
possible and others might not.

  An interesting variant of this is the so-called \emph{stack-allocated rest
list}, which can be achieved (in implementations supporting the optimization) by
\begin{lisp} (defun f (\&rest x) \\* ~~(declare (dynamic-extent x)) \\* ~~...)
\end{lisp} Note here that although the initial value of \cdf{x} is not
explicitly present, nevertheless in the usual implementation strategy the
function \cdf{f} is responsible for assembling the list for \cdf{x} from the
passed arguments, so the \cdf{f} function can be optimized by a compiler to
construct a stack-allocated list instead of a heap-allocated list.

Some Common Lisp functions take other functions as arguments; frequently the
argument function is a so-called \emph{downward funarg}, that is, a functional
argument that is passed only downward and whose extent may therefore be dynamic.
\begin{lisp} (flet ((gd (x) (atan (sinh x)))) \\* ~~(declare (dynamic-extent
\#'gd))~~~~~;\textrm{\cdf{mapcar} won't hang on to \cdf{gd}}\\* ~~(mapcar \#'gd
my-list-of-numbers))
\end{lisp}


The following three examples are in error, since in each case the value of
\cdf{x} is used outside of its extent.
\begin{lisp} (length (let ((x (list 1 2 3))) \\* ~~~~~~~~~~(declare
(dynamic-extent x)) \\*
~~~~~~~~~~x))~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Wrong}
\end{lisp} The preceding code is obviously incorrect, because the cons cells
making up the list in \cdf{x} might be deallocated (thanks to the declaration)
before \cdf{length} is called.
\begin{lisp} (length (list (let ((x (list 1 2 3))) \\* ~~~~~~~~~~~~~~~~(declare
(dynamic-extent x)) \\*
~~~~~~~~~~~~~~~~x)))~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Wrong}
\end{lisp} In this second case it is less obvious that the code is incorrect,
because one might argue that the cons cells making up the list in \cdf{x} have
no effect on the result to be computed by \cdf{length}.  Nevertheless the code
briefly violates the assertion implied by the declaration and is therefore
incorrect.  (It is not difficult to imagine a perfectly sensible implementation
of a garbage collector that might become confused by a cons cell containing a
dangling pointer to a list that was once stack-allocated but then deallocated.)
\begin{lisp} (progn (let ((x (list 1 2 3))) \\* ~~~~~~~~~(declare
(dynamic-extent x)) \\*
~~~~~~~~~x)~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Wrong} \\*
~~~~~~~(print "Six dollars is your change have a nice day NEXT!"))
\end{lisp} In this third case it is even less obvious that the code is
incorrect, because the value of \cdf{x} returned from the \cdf{let} construct is
discarded right away by the \cdf{progn}.  Indeed it is, but ``right away'' isn't
fast enough.  The code briefly violates the assertion implied by the declaration
and is therefore incorrect.  (If the code is being interpreted, the interpreter
might hang on to the value returned by the \cdf{let} for some time before it is
eventually discarded.)

Here is one last example, one that has little practical import but is
theoretically quite instructive.
\begin{lisp} (dotimes (j 10) \\* ~~(declare (dynamic-extent j)) \\* ~~(setq foo
3)~~~~~~~~~~~~~~~~~~~~~;\textrm{Correct} \\* ~~(setq foo
j))~~~~~~~~~~~~~~~~~~~~;\textrm{Erroneous---but why? (see text)}
\end{lisp} Since \cdf{j} is an integer by the definition of \cdf{dotimes}, but
\cdf{eq} and \cdf{eql} are not necessarily equivalent for integers, what are the
otherwise inaccessible parts of \cdf{j}, which this declaration requires the
body of the \cdf{dotimes} not to ``save''?  If the value of \cdf{j} is \cd{3},
and the body does \cd{(setq foo~3)}, is that an error?  The answer is no, but
the interesting thing is that it depends on the implementation-dependent
behavior of \cdf{eq} on numbers.  In an implementation where \cdf{eq} and
\cdf{eql} are equivalent for \cd{3}, then \cd{3} is not an otherwise
inaccessible part because \cd{(eq~j (+~2~1))} is true, and therefore there is
another way to access the object besides going through \cdf{j}.  On the other
hand, in an implementation where \cdf{eq} and \cdf{eql} are not equivalent for
\cd{3}, then the particular \cd{3} that is the value of \cdf{j} is an otherwise
inaccessible part, but any other \cd{3} is not.  Thus \cd{(setq foo~3)} is valid
but \cd{(setq foo~j)} is erroneous.  Since \cd{(setq foo~j)} is erroneous in
some implementations, it is erroneous in all portable programs, but some other
implementations may not be able to detect the error.  (If this conclusion seems
strange, it may help to replace \cd{3} everywhere in the preceding argument with
some obvious bignum such as \cd{375374638837424898243} and to replace \cd{10}
with some even larger bignum.)

  The \cdf{dynamic-extent} declaration should be used with great care.  It makes
possible great performance improvements in some situations, but if the user
misdeclares something and consequently the implementation returns a pointer into
the stack (or stores it in the heap), an undefined situation may result and the
integrity of the Lisp storage mechanism may be compromised. Debugging these
situations may be tricky.  Users who have asked for this feature have indicated
a willingness to deal with such problems; nevertheless, I do not encourage
casual users to use this declaration.
\end{flushdesc}

Реализация может поддерживать другие спецификаторы деклараций (специфичные для
неё).
С другой стороны, компилятор Common Lisp может игнорировать некоторые виды
деклараций (например, неподдерживаемые компилятором), за исключением
спецификатора декларации \cdf{declaration}.
Однако, разработчики компиляторов поощряются в том, чтобы выдавать
предупреждение об использовании неизвестных деклараций.

\section{Декларация типов для форм}

Часто бывает полезно задекларировать, что значение, возвращаемое некоторой
формой будет принадлежать определённому типу.
Использование \cdf{declare} может применяться только к значениям связанным с
переменной, но не для безымянных форм. Для этих целей определена специальная
форма \cdf{the}.  \cd{(the \emph{type} \emph{form})} означает, что значение
формы \emph{form} будет принадлежать типу \emph{type}.

\begin{defspec}
the value-type form

Вычисляется форма \emph{form}. То, что будет вычислено, будет возвращено из
формы \emph{the}. Дополнительно будет осуществлена проверка на принадлежность
возвращённого значения типу \emph{value-type} (его форма не выполняется) и в
случае несовпадения выдана ошибка. (Реализация может и не осуществлять эту
проверку. Однако такая проверка поощряется при работе в интерпретаторе.) В целом
эта форма декларирует, что пользователь гарантирует, что значение формы всегда
принадлежит заданному типу.
Например:
\begin{lisp}
(the string (copy-seq x))~~~~~;\textrm{Результат будет строкой} \\
(the integer (+ x 3))~~~~~~~~~;\textrm{Результат \cdf{+} будет целым числом} \\
(+ (the integer x) 3)~~~~~~~~~;\textrm{Значением \cdf{x} будет целое число} \\
(the (complex rational) (* z 3)) \\
(the (unsigned-byte 8) (logand x mask))
\end{lisp}

\emph{value-type} может быть любым спецификатором типа. Весь смысл в
том, что это декларация, а не точное описание типа.

В случае если \emph{form} возвращает только одно значение и
\emph{value-type} не принадлежит спецификатору \cdf{values},
конструкцию \cdf{the} можно заменить следующей:
\begin{lisp}
(let ((\#1=\#:temp \emph{form})) (declare (type \emph{value-type} \#1\#)) \#1\#)
\end{lisp}
В случае возврата нескольких значений, конструкция может быть записана
более точно, используя, например, \cdf{multiple-value-bind}.
\end{defspec}

\fi