This is gcl.info, produced by makeinfo version 6.7 from gcl.texi.

This is a Texinfo GNU Common Lisp Manual based on the draft ANSI
standard for Common Lisp.

   Copyright 1994 William F. Schelter

INFO-DIR-SECTION GNU Common Lisp
START-INFO-DIR-ENTRY
* gcl: (gcl.info). GNU Common Lisp Manual
END-INFO-DIR-ENTRY


File: gcl.info,  Node: Notes about the Implementation of Compiler Macros,  Next: Minimal Compilation,  Prev: When Compiler Macros Are Used,  Up: Compilation Semantics

3.2.2.5 Notes about the Implementation of Compiler Macros
.........................................................

Although it is technically permissible, as described above, for eval to
treat compiler macros in the same situations as compiler might, this is
not necessarily a good idea in interpreted implementations.

   Compiler macros exist for the purpose of trading compile-time speed
for run-time speed.  Programmers who write compiler macros tend to
assume that the compiler macros can take more time than normal functions
and macros in order to produce code which is especially optimal for use
at run time.  Since eval in an interpreted implementation might perform
semantic analysis of the same form multiple times, it might be
inefficient in general for the implementation to choose to call compiler
macros on every such evaluation.

   Nevertheless, the decision about what to do in these situations is
left to each implementation.


File: gcl.info,  Node: Minimal Compilation,  Next: Semantic Constraints,  Prev: Notes about the Implementation of Compiler Macros,  Up: Compilation Semantics

3.2.2.6 Minimal Compilation
...........................

Minimal compilation is defined as follows:

*
     All compiler macro calls appearing in the source code being
     compiled are expanded, if at all, at compile time; they will not be
     expanded at run time.

*
     All macro and symbol macro calls appearing in the source code being
     compiled are expanded at compile time in such a way that they will
     not be expanded again at run time.  macrolet

     and symbol-macrolet

     are effectively replaced by forms corresponding to their bodies in
     which calls to macros are replaced by their expansions.

*
     The first argument in a load-time-value

     form in source code processed by compile

     is evaluated at compile time; in source code processed by
     compile-file , the compiler arranges for it to be evaluated at load
     time.  In either case, the result of the evaluation is remembered
     and used later as the value of the load-time-value form at
     execution time.


File: gcl.info,  Node: Semantic Constraints,  Prev: Minimal Compilation,  Up: Compilation Semantics

3.2.2.7 Semantic Constraints
............................

All conforming programs must obey the following constraints, which are
designed to minimize the observable differences between compiled and
interpreted programs:

*
     Definitions of any referenced macros must be present in the
     compilation environment.  Any form that is a list beginning with a
     symbol that does not name a special operator or a macro defined in
     the compilation environment is treated by the compiler as a
     function call.

*
     Special proclamations for dynamic variables must be made in the
     compilation environment.  Any binding for which there is no special
     declaration or proclamation in the compilation environment is
     treated by the compiler as a lexical binding.

*
     The definition of a function that is defined and declared inline in
     the compilation environment must be the same at run time.

*
     Within a function named F, the compiler may (but is not required
     to) assume that an apparent recursive call to a function named F
     refers to the same definition of F, unless that function has been
     declared notinline.  The consequences of redefining such a
     recursively defined function F while it is executing are undefined.

*
     A call within a file to a named function that is defined in the
     same file refers to that function, unless that function has been
     declared notinline.  The consequences are unspecified if functions
     are redefined individually at run time or multiply defined in the
     same file.

*
     The argument syntax and number of return values for all functions
     whose ftype is declared at compile time must remain the same at run
     time.

*
     Constant variables defined in the compilation environment must have
     a similar value at run time.  A reference to a constant variable in
     source code is equivalent to a reference to a literal object that
     is the value of the constant variable.

*
     Type definitions made with deftype or defstruct in the compilation
     environment must retain the same definition at run time.  Classes
     defined by defclass in the compilation environment must be defined
     at run time to have the same superclasses and same metaclass.

     This implies that subtype/supertype relationships of type
     specifiers must not change between compile time and run time.

*
     Type declarations present in the compilation environment must
     accurately describe the corresponding values at run time;
     otherwise, the consequences are undefined.  It is permissible for
     an unknown type to appear in a declaration at compile time, though
     a warning might be signaled in such a case.

*
     Except in the situations explicitly listed above, a function
     defined in the evaluation environment is permitted to have a
     different definition or a different signature at run time, and the
     run-time definition prevails.

   Conforming programs should not be written using any additional
assumptions about consistency between the run-time environment and the
startup, evaluation, and compilation environments.

   Except where noted, when a compile-time and a run-time definition are
different, one of the following occurs at run time:

*
     an error of type error is signaled
*
     the compile-time definition prevails
*
     the run-time definition prevails

   If the compiler processes a function form whose operator is not
defined at compile time, no error is signaled at compile time.


File: gcl.info,  Node: File Compilation,  Next: Literal Objects in Compiled Files,  Prev: Compilation Semantics,  Up: Compilation

3.2.3 File Compilation
----------------------

The function compile-file performs compilation of forms in a file
following the rules specified in *note Compilation Semantics::, and
produces an output file that can be loaded by using load.

   Normally, the top level forms appearing in a file compiled with
compile-file are evaluated only when the resulting compiled file is
loaded, and not when the file is compiled.  However, it is typically the
case that some forms in the file need to be evaluated at compile time so
the remainder of the file can be read and compiled correctly.

   The eval-when special form can be used to control whether a top level
form is evaluated at compile time, load time, or both.  It is possible
to specify any of three situations with eval-when, denoted by the
symbols :compile-toplevel, :load-toplevel, and :execute.  For top level
eval-when forms, :compile-toplevel specifies that the compiler must
evaluate the body at compile time, and :load-toplevel specifies that the
compiler must arrange to evaluate the body at load time.  For non-top
level eval-when forms, :execute specifies that the body must be executed
in the run-time environment.

   The behavior of this form can be more precisely understood in terms
of a model of how compile-file processes forms in a file to be compiled.
There are two processing modes, called "not-compile-time" and
"compile-time-too".

   Successive forms are read from the file by compile-file and processed
in not-compile-time mode; in this mode, compile-file arranges for forms
to be evaluated only at load time and not at compile time.  When
compile-file is in compile-time-too mode, forms are evaluated both at
compile time and load time.

* Menu:

* Processing of Top Level Forms::
* Processing of Defining Macros::
* Constraints on Macros and Compiler Macros::


File: gcl.info,  Node: Processing of Top Level Forms,  Next: Processing of Defining Macros,  Prev: File Compilation,  Up: File Compilation

3.2.3.1 Processing of Top Level Forms
.....................................

Processing of top level forms in the file compiler is defined as
follows:

1.
     If the form is a compiler macro form (not disabled by a notinline
     declaration), the implementation might or might not choose to
     compute the compiler macro expansion of the form and, having
     performed the expansion, might or might not choose to process the
     result as a top level form in the same processing mode
     (compile-time-too or not-compile-time).  If it declines to obtain
     or use the expansion, it must process the original form.

2.
     If the form is a macro form, its macro expansion is computed and
     processed as a top level form in the same processing mode
     (compile-time-too or not-compile-time).

3.
     If the form is a progn form, each of its body forms is sequentially
     processed as a top level form in the same processing mode.

4.
     If the form is a locally, macrolet, or symbol-macrolet,
     compile-file establishes the appropriate bindings and processes the
     body forms as top level forms with those bindings in effect in the
     same processing mode.  (Note that this implies that the lexical
     environment in which top level forms are processed is not
     necessarily the null lexical environment.)

5.
     If the form is an eval-when form, it is handled according to Figure
     3-7.

     plus .5 fil \offinterlineskip
       CT   LT   E    Mode  Action    New Mode          
       _________________________________________________
       Yes  Yes  --  --   Process   compile-time-too  
       No   Yes  Yes   CTT  Process   compile-time-too  
       No   Yes  Yes   NCT  Process   not-compile-time  
       No   Yes  No   --   Process   not-compile-time  
       Yes  No   --  --   Evaluate  --               
       No   No   Yes   CTT  Evaluate  --               
       No   No   Yes   NCT  Discard   --               
       No   No   No   --   Discard   --               

       Figure 3-7: EVAL-WHEN processing

     Column CT indicates whether :compile-toplevel is specified.  Column
     LT indicates whether :load-toplevel is specified.  Column E
     indicates whether :execute is specified.  Column Mode indicates the
     processing mode; a dash (--) indicates that the processing mode is
     not relevant.

     The Action column specifies one of three actions:

     
          Process: process the body as top level forms in the specified
          mode.

     
          Evaluate: evaluate the body in the dynamic execution context
          of the compiler, using the evaluation environment as the
          global environment and the lexical environment in which the
          eval-when appears.

     
          Discard: ignore the form.

     The New Mode column indicates the new processing mode.  A dash (--)
     indicates the compiler remains in its current mode.

6.
     Otherwise, the form is a top level form that is not one of the
     special cases.  In compile-time-too mode, the compiler first
     evaluates the form in the evaluation environment and then minimally
     compiles it.  In not-compile-time mode, the form is simply
     minimally compiled.  All subforms are treated as non-top-level
     forms.

     Note that top level forms are processed in the order in which they
     textually appear in the file and that each top level form read by
     the compiler is processed before the next is read.  However, the
     order of processing (including macro expansion) of subforms that
     are not top level forms and the order of further compilation is
     unspecified as long as Common Lisp semantics are preserved.

   eval-when forms cause compile-time evaluation only at top level.
Both :compile-toplevel and :load-toplevel situation specifications are
ignored for non-top-level forms.  For non-top-level forms, an eval-when
specifying the :execute situation is treated as an implicit progn
including the forms in the body of the eval-when form; otherwise, the
forms in the body are ignored.


File: gcl.info,  Node: Processing of Defining Macros,  Next: Constraints on Macros and Compiler Macros,  Prev: Processing of Top Level Forms,  Up: File Compilation

3.2.3.2 Processing of Defining Macros
.....................................

Defining macros (such as defmacro or defvar) appearing within a file
being processed by compile-file normally have compile-time side effects
which affect how subsequent forms in the same file are compiled.  A
convenient model for explaining how these side effects happen is that
the defining macro expands into one or more eval-when forms, and that
the calls which cause the compile-time side effects to happen appear in
the body of an (eval-when (:compile-toplevel) ...) form.

   The compile-time side effects may cause information about the
definition to be stored differently than if the defining macro had been
processed in the 'normal' way (either interpretively or by loading the
compiled file).

   In particular, the information stored by the defining macros at
compile time might or might not be available to the interpreter (either
during or after compilation), or during subsequent calls to the
compiler.  For example, the following code is nonportable because it
assumes that the compiler stores the macro definition of foo where it is
available to the interpreter:

      (defmacro foo (x) `(car ,x))
      (eval-when (:execute :compile-toplevel :load-toplevel)
        (print (foo '(a b c))))

   A portable way to do the same thing would be to include the macro
definition inside the eval-when form, as in:

      (eval-when (:execute :compile-toplevel :load-toplevel)
        (defmacro foo (x) `(car ,x))
        (print (foo '(a b c))))

   Figure 3-8 lists macros that make definitions available both in the
compilation and run-time environments.  It is not specified whether
definitions made available in the compilation environment are available
in the evaluation environment, nor is it specified whether they are
available in subsequent compilation units or subsequent invocations of
the compiler.  As with eval-when, these compile-time side effects happen
only when the defining macros appear at top level.

  declaim                define-modify-macro   defsetf    
  defclass               define-setf-expander  defstruct  
  defconstant            defmacro              deftype    
  define-compiler-macro  defpackage            defvar     
  define-condition       defparameter                     

  Figure 3-8: Defining Macros That Affect the Compile-Time Environment



File: gcl.info,  Node: Constraints on Macros and Compiler Macros,  Prev: Processing of Defining Macros,  Up: File Compilation

3.2.3.3 Constraints on Macros and Compiler Macros
.................................................

Except where explicitly stated otherwise, no macro defined in the Common
Lisp standard produces an expansion that could cause any of the subforms
of the macro form to be treated as top level forms.  If an
implementation also provides a special operator definition of a Common
Lisp macro, the special operator definition must be semantically
equivalent in this respect.

   Compiler macro expansions must also have the same top level
evaluation semantics as the form which they replace.  This is of concern
both to conforming implementations and to conforming programs.


File: gcl.info,  Node: Literal Objects in Compiled Files,  Next: Exceptional Situations in the Compiler,  Prev: File Compilation,  Up: Compilation

3.2.4 Literal Objects in Compiled Files
---------------------------------------

The functions eval and compile are required to ensure that literal
objects referenced within the resulting interpreted or compiled code
objects are the same as the corresponding objects in the source code.
compile-file, on the other hand, must produce a compiled file that, when
loaded with load, constructs the objects defined by the source code and
produces references to them.

   In the case of compile-file, objects constructed by load of the
compiled file cannot be spoken of as being the same as the objects
constructed at compile time, because the compiled file may be loaded
into a different Lisp image than the one in which it was compiled.  This
section defines the concept of similarity which relates objects in the
evaluation environment to the corresponding objects in the run-time
environment.

   The constraints on literal objects described in this section apply
only to compile-file; eval and compile do not copy or coalesce
constants.

* Menu:

* Externalizable Objects::
* Similarity of Literal Objects::
* Similarity of Aggregate Objects::
* Definition of Similarity::
* Extensions to Similarity Rules::
* Additional Constraints on Externalizable Objects::


File: gcl.info,  Node: Externalizable Objects,  Next: Similarity of Literal Objects,  Prev: Literal Objects in Compiled Files,  Up: Literal Objects in Compiled Files

3.2.4.1 Externalizable Objects
..............................

The fact that the file compiler represents literal objects externally in
a compiled file and must later reconstruct suitable equivalents of those
objects when that file is loaded imposes a need for constraints on the
nature of the objects that can be used as literal objects in code to be
processed by the file compiler.

   An object that can be used as a literal object in code to be
processed by the file compiler is called an externalizable object .

   We define that two objects are similar if they satisfy a two-place
conceptual equivalence predicate (defined below), which is independent
of the Lisp image so that the two objects in different Lisp images can
be understood to be equivalent under this predicate.  Further, by
inspecting the definition of this conceptual predicate, the programmer
can anticipate what aspects of an object are reliably preserved by file
compilation.

   The file compiler must cooperate with the loader in order to assure
that in each case where an externalizable object is processed as a
literal object, the loader will construct a similar object.

   The set of objects that are externalizable objects are those for
which the new conceptual term "similar" is defined, such that when a
compiled file is loaded, an object can be constructed which can be shown
to be similar to the original object which existed at the time the file
compiler was operating.


File: gcl.info,  Node: Similarity of Literal Objects,  Next: Similarity of Aggregate Objects,  Prev: Externalizable Objects,  Up: Literal Objects in Compiled Files

3.2.4.2 Similarity of Literal Objects
.....................................


File: gcl.info,  Node: Similarity of Aggregate Objects,  Next: Definition of Similarity,  Prev: Similarity of Literal Objects,  Up: Literal Objects in Compiled Files

3.2.4.3 Similarity of Aggregate Objects
.......................................

Of the types over which similarity is defined, some are treated as
aggregate objects.  For these types, similarity is defined recursively.
We say that an object of these types has certain "basic qualities" and
to satisfy the similarity relationship, the values of the corresponding
qualities of the two objects must also be similar.


File: gcl.info,  Node: Definition of Similarity,  Next: Extensions to Similarity Rules,  Prev: Similarity of Aggregate Objects,  Up: Literal Objects in Compiled Files

3.2.4.4 Definition of Similarity
................................

Two objects S (in source code) and C (in compiled code) are defined to
be similar if and only if they are both of one of the types listed here
(or defined by the implementation) and they both satisfy all additional
requirements of similarity indicated for that type.

number
     Two numbers S and C are similar if they are of the same type and
     represent the same mathematical value.

character
     Two simple characters S and C are similar if they have similar code
     attributes.

     Implementations providing additional, implementation-defined
     attributes must define whether and how non-simple characters can be
     regarded as similar.

symbol
     Two apparently uninterned symbols S and C are similar if their
     names are similar.

     Two interned symbols S and C are similar if their names are
     similar, and if either S is accessible in the current package at
     compile time and C is accessible in the current package at load
     time, or C is accessible in the package that is similar to the home
     package of S.

     (Note that similarity of symbols is dependent on neither the
     current readtable nor how the function read would parse the
     characters in the name of the symbol.)

package
     Two packages S and C are similar if their names are similar.

     Note that although a package object is an externalizable object,
     the programmer is responsible for ensuring that the corresponding
     package is already in existence when code referencing it as a
     literal object is loaded.  The loader finds the corresponding
     package object as if by calling find-package with that name as an
     argument.  An error is signaled by the loader if no package exists
     at load time.

random-state
     Two random states S and C are similar if S would always produce the
     same sequence of pseudo-random numbers as a copy_5 of C when given
     as the random-state argument to the function random, assuming
     equivalent limit arguments in each case.

     (Note that since C has been processed by the file compiler, it
     cannot be used directly as an argument to random because random
     would perform a side effect.)

cons
     Two conses, S and C, are similar if the car_2 of S is similar to
     the car_2 of C, and the cdr_2 of S is similar to the cdr_2 of C.

array
     Two one-dimensional arrays, S and C, are similar if the length of S
     is similar to the length of C, the actual array element type of S
     is similar to the actual array element type of C, and each active
     element of S is similar to the corresponding element of C.

     Two arrays of rank other than one, S and C, are similar if the rank
     of S is similar to the rank of C, each dimension_1 of S is similar
     to the corresponding dimension_1 of C, the actual array element
     type of S is similar to the actual array element type of C, and
     each element of S is similar to the corresponding element of C.

     In addition, if S is a simple array, then C must also be a simple
     array.  If S is a displaced array, has a fill pointer, or is
     actually adjustable, C is permitted to lack any or all of these
     qualities.

hash-table
     Two hash tables S and C are similar if they meet the following
     three requirements:

     1.
          They both have the same test (e.g., they are both eql hash
          tables).

     2.
          There is a unique one-to-one correspondence between the keys
          of the two hash tables, such that the corresponding keys are
          similar.

     3.
          For all keys, the values associated with two corresponding
          keys are similar.

     If there is more than one possible one-to-one correspondence
     between the keys of S and C, the consequences are unspecified.  A
     conforming program cannot use a table such as S as an
     externalizable constant.

pathname
     Two pathnames S and C are similar if all corresponding pathname
     components are similar.

function

     Functions are not externalizable objects.

structure-object and standard-object

     A general-purpose concept of similarity does not exist for
     structures and standard objects.  However, a conforming program is
     permitted to define a make-load-form method for any class K defined
     by that program that is a subclass of either structure-object or
     standard-object.  The effect of such a method is to define that an
     object S of type K in source code is similar to an object C of type
     K in compiled code if C was constructed from code produced by
     calling make-load-form on S.


File: gcl.info,  Node: Extensions to Similarity Rules,  Next: Additional Constraints on Externalizable Objects,  Prev: Definition of Similarity,  Up: Literal Objects in Compiled Files

3.2.4.5 Extensions to Similarity Rules
......................................

Some objects, such as streams, readtables, and methods are not
externalizable objects under the definition of similarity given above.
That is, such objects may not portably appear as literal objects in code
to be processed by the file compiler.

   An implementation is permitted to extend the rules of similarity, so
that other kinds of objects are externalizable objects for that
implementation.

   If for some kind of object, similarity is neither defined by this
specification nor by the implementation, then the file compiler must
signal an error upon encountering such an object as a literal constant.


File: gcl.info,  Node: Additional Constraints on Externalizable Objects,  Prev: Extensions to Similarity Rules,  Up: Literal Objects in Compiled Files

3.2.4.6 Additional Constraints on Externalizable Objects
........................................................

If two literal objects appearing in the source code for a single file
processed with the file compiler are the identical, the corresponding
objects in the compiled code must also be the identical.

   With the exception of symbols and packages, any two literal objects
in code being processed by the file compiler may be coalesced if and
only if they are similar; if they are either both symbols or both
packages, they may only be coalesced if and only if they are identical.

   Objects containing circular references can be externalizable objects.
The file compiler is required to preserve eqlness of substructures
within a file.  Preserving eqlness means that subobjects that are the
same in the source code must be the same in the corresponding compiled
code.

   In addition, the following are constraints on the handling of literal
objects by the file compiler:

     array: If an array in the source code is a simple array, then the
     corresponding array in the compiled code will also be a simple
     array.  If an array in the source code is displaced, has a fill
     pointer, or is actually adjustable, the corresponding array in the
     compiled code might lack any or all of these qualities.  If an
     array in the source code has a fill pointer, then the corresponding
     array in the compiled code might be only the size implied by the
     fill pointer.

     packages: The loader is required to find the corresponding package
     object as if by calling find-package with the package name as an
     argument.  An error of type package-error is signaled if no package
     of that name exists at load time.

     random-state: A constant random state object cannot be used as the
     state argument to the function random because random modifies this
     data structure.

     structure, standard-object: Objects of type structure-object and
     standard-object may appear in compiled constants if there is an
     appropriate make-load-form method defined for that type.

     The file compiler calls make-load-form on any object that is
     referenced as a literal object if the object is a generalized
     instance of standard-object, structure-object, condition, or any of
     a (possibly empty) implementation-dependent set of other classes.
     The file compiler only calls make-load-form once for any given
     object within a single file.

     symbol: In order to guarantee that compiled files can be loaded
     correctly, users must ensure that the packages referenced in those
     files are defined consistently at compile time and load time.
     Conforming programs must satisfy the following requirements:

     1.
          The current package when a top level form in the file is
          processed by compile-file must be the same as the current
          package when the code corresponding to that top level form in
          the compiled file is executed by load.  In particular:

          a.
               Any top level form in a file that alters the current
               package must change it to a package of the same name both
               at compile time and at load time.

          b.
               If the first non-atomic top level form in the file is not
               an in-package form, then the current package at the time
               load is called must be a package with the same name as
               the package that was the current package at the time
               compile-file was called.

     2.
          For all symbols appearing lexically within a top level form
          that were accessible in the package that was the current
          package during processing of that top level form at compile
          time, but whose home package was another package, at load time
          there must be a symbol with the same name that is accessible
          in both the load-time current package and in the package with
          the same name as the compile-time home package.

     3.
          For all symbols represented in the compiled file that were
          external symbols in their home package at compile time, there
          must be a symbol with the same name that is an external symbol
          in the package with the same name at load time.

     If any of these conditions do not hold, the package in which the
     loader looks for the affected symbols is unspecified.
     Implementations are permitted to signal an error or to define this
     behavior.


File: gcl.info,  Node: Exceptional Situations in the Compiler,  Prev: Literal Objects in Compiled Files,  Up: Compilation

3.2.5 Exceptional Situations in the Compiler
--------------------------------------------

compile and compile-file are permitted to signal errors and warnings,
including errors due to compile-time processing of (eval-when
(:compile-toplevel) ...) forms, macro expansion, and conditions signaled
by the compiler itself.

   Conditions of type error might be signaled by the compiler in
situations where the compilation cannot proceed without intervention.

   In addition to situations for which the standard specifies that
conditions of type warning must or might be signaled, warnings might be
signaled in situations where the compiler can determine that the
consequences are undefined or that a run-time error will be signaled.
Examples of this situation are as follows: violating type declarations,
altering or assigning the value of a constant defined with defconstant,
calling built-in Lisp functions with a wrong number of arguments or
malformed keyword argument lists, and using unrecognized declaration
specifiers.

   The compiler is permitted to issue warnings about matters of
programming style as conditions of type style-warning.  Examples of this
situation are as follows: redefining a function using a different
argument list, calling a function with a wrong number of arguments, not
declaring ignore of a local variable that is not referenced, and
referencing a variable declared ignore.

   Both compile and compile-file are permitted (but not required) to
establish a handler for conditions of type error.  For example, they
might signal a warning, and restart compilation from some
implementation-dependent point in order to let the compilation proceed
without manual intervention.

   Both compile and compile-file return three values, the second two
indicating whether the source code being compiled contained errors and
whether style warnings were issued.

   Some warnings might be deferred until the end of compilation.  See
with-compilation-unit.


File: gcl.info,  Node: Declarations,  Next: Lambda Lists,  Prev: Compilation,  Up: Evaluation and Compilation

3.3 Declarations
================

Declarations provide a way of specifying information for use by program
processors, such as the evaluator or the compiler.

   Local declarations

   can be embedded in executable code using declare.  Global
declarations , or proclamations , are established by proclaim or
declaim.

   The the special form provides a shorthand notation for making a local
declaration about the type of the value of a given form.

   The consequences are undefined if a program violates a declaration or
a proclamation.

* Menu:

* Minimal Declaration Processing Requirements::
* Declaration Specifiers::
* Declaration Identifiers::
* Declaration Scope::


File: gcl.info,  Node: Minimal Declaration Processing Requirements,  Next: Declaration Specifiers,  Prev: Declarations,  Up: Declarations

3.3.1 Minimal Declaration Processing Requirements
-------------------------------------------------

In general, an implementation is free to ignore declaration specifiers
except for the declaration , notinline , safety , and special
declaration specifiers.

   A declaration declaration must suppress warnings about unrecognized
declarations of the kind that it declares.  If an implementation does
not produce warnings about unrecognized declarations, it may safely
ignore this declaration.

   A notinline declaration must be recognized by any implementation that
supports inline functions or compiler macros in order to disable those
facilities.  An implementation that does not use inline functions or
compiler macros may safely ignore this declaration.

   A safety declaration that increases the current safety level must
always be recognized.  An implementation that always processes code as
if safety were high may safely ignore this declaration.

   A special declaration must be processed by all implementations.


File: gcl.info,  Node: Declaration Specifiers,  Next: Declaration Identifiers,  Prev: Minimal Declaration Processing Requirements,  Up: Declarations

3.3.2 Declaration Specifiers
----------------------------

A declaration specifier is an expression that can appear at top level of
a declare expression or a declaim form, or as the argument to proclaim.
It is a list whose car is a declaration identifier, and whose cdr is
data interpreted according to rules specific to the declaration
identifier.


File: gcl.info,  Node: Declaration Identifiers,  Next: Declaration Scope,  Prev: Declaration Specifiers,  Up: Declarations

3.3.3 Declaration Identifiers
-----------------------------

Figure 3-9 shows a list of all declaration identifiers

   defined by this standard.

  declaration     ignore     special  
  dynamic-extent  inline     type     
  ftype           notinline           
  ignorable       optimize            

  Figure 3-9: Common Lisp Declaration Identifiers


   An implementation is free to support other (implementation-defined)
declaration identifiers as well.  A warning might be issued if a
declaration identifier is not among those defined above, is not defined
by the implementation, is not a type name, and has not been declared in
a declaration proclamation.

* Menu:

* Shorthand notation for Type Declarations::


File: gcl.info,  Node: Shorthand notation for Type Declarations,  Prev: Declaration Identifiers,  Up: Declaration Identifiers

3.3.3.1 Shorthand notation for Type Declarations
................................................

A type specifier can be used as a declaration identifier.
(type-specifier {var}*) is taken as shorthand for (type type-specifier
{var}*).


File: gcl.info,  Node: Declaration Scope,  Prev: Declaration Identifiers,  Up: Declarations

3.3.4 Declaration Scope
-----------------------

Declarations can be divided into two kinds: those that apply to the
bindings of variables or functions; and those that do not apply to
bindings.

   A declaration that appears at the head of a binding form and applies
to a variable or function binding made by that form is called a bound
declaration ; such a declaration affects both the binding and any
references within the scope of the declaration.

   Declarations that are not bound declarations are called free
declarations .

   A free declaration in a form F1 that applies to a binding for a name
N established by some form F2 of which F1 is a subform affects only
references to N within F1; it does not to apply to other references to N
outside of F1, nor does it affect the manner in which the binding of N
by F2 is established.

   Declarations that do not apply to bindings can only appear as free
declarations.

   The scope of a bound declaration is the same as the lexical scope of
the binding to which it applies; for special variables, this means the
scope that the binding would have had had it been a lexical binding.

   Unless explicitly stated otherwise, the scope of a free declaration
includes only the body subforms of the form at whose head it appears,
and no other subforms.  The scope of free declarations specifically does
not include initialization forms for bindings established by the form
containing the declarations.

   Some iteration forms include step, end-test, or result subforms that
are also included in the scope of declarations that appear in the
iteration form.  Specifically, the iteration forms and subforms involved
are:

*
     do, do*: step-forms, end-test-form, and result-forms.
*
     dolist, dotimes: result-form
*
     do-all-symbols, do-external-symbols, do-symbols: result-form

* Menu:

* Examples of Declaration Scope::


File: gcl.info,  Node: Examples of Declaration Scope,  Prev: Declaration Scope,  Up: Declaration Scope

3.3.4.1 Examples of Declaration Scope
.....................................

Here is an example illustrating the scope of bound declarations.

      (let ((x 1))                ;[1] 1st occurrence of x
        (declare (special x))     ;[2] 2nd occurrence of x
        (let ((x 2))              ;[3] 3rd occurrence of x
          (let ((old-x x)         ;[4] 4th occurrence of x
                (x 3))            ;[5] 5th occurrence of x
            (declare (special x)) ;[6] 6th occurrence of x
            (list old-x x))))     ;[7] 7th occurrence of x
     =>  (2 3)

   The first occurrence of x establishes a dynamic binding of x because
of the special declaration for x in the second line.  The third
occurrence of x establishes a lexical binding of x (because there is no
special declaration in the corresponding let form).  The fourth
occurrence of x x is a reference to the lexical binding of x established
in the third line.  The fifth occurrence of x establishes a dynamic
binding of x for the body of the let form that begins on that line
because of the special declaration for x in the sixth line.  The
reference to x in the fourth line is not affected by the special
declaration in the sixth line because that reference is not within the
"would-be lexical scope" of the variable x in the fifth line.  The
reference to x in the seventh line is a reference to the dynamic binding
of x established in the fifth line.

   Here is another example, to illustrate the scope of a free
declaration.  In the following:

      (lambda (&optional (x (foo 1))) ;[1]
        (declare (notinline foo))     ;[2]
        (foo x))                      ;[3]

   the call to foo in the first line might be compiled inline even
though the call to foo in the third line must not be.  This is because
the notinline declaration for foo in the second line applies only to the
body on the third line.  In order to suppress inlining for both calls,
one might write:

      (locally (declare (notinline foo)) ;[1]
        (lambda (&optional (x (foo 1)))  ;[2]
          (foo x)))                      ;[3]

   or, alternatively:

      (lambda (&optional                               ;[1]
                 (x (locally (declare (notinline foo)) ;[2]
                      (foo 1))))                       ;[3]
        (declare (notinline foo))                      ;[4]
        (foo x))                                       ;[5]

   Finally, here is an example that shows the scope of declarations in
an iteration form.

      (let ((x  1))                     ;[1]
        (declare (special x))           ;[2]
          (let ((x 2))                  ;[3]
            (dotimes (i x x)            ;[4]
              (declare (special x)))))  ;[5]
     =>  1

   In this example, the first reference to x on the fourth line is to
the lexical binding of x established on the third line.  However, the
second occurrence of x on the fourth line lies within the scope of the
free declaration on the fifth line (because this is the result-form of
the dotimes) and therefore refers to the dynamic binding of x.


File: gcl.info,  Node: Lambda Lists,  Next: Error Checking in Function Calls,  Prev: Declarations,  Up: Evaluation and Compilation

3.4 Lambda Lists
================

A lambda list is a list that specifies a set of parameters (sometimes
called lambda variables) and a protocol for receiving values for those
parameters.

   There are several kinds of lambda lists.

 Context                                     Kind of Lambda List                             
 defun form                                  ordinary lambda list                            
 defmacro form                               macro lambda list                               
 lambda expression                           ordinary lambda list                            
 flet local function definition              ordinary lambda list                            
 labels local function definition            ordinary lambda list                            
 handler-case clause specification           ordinary lambda list                            
 restart-case clause specification           ordinary lambda list                            
 macrolet local macro definition             macro lambda list                               
 define-method-combination                   ordinary lambda list                            
 define-method-combination :arguments option define-method-combination arguments lambda list 
 defstruct :constructor option               boa lambda list                                 
 defgeneric form                             generic function lambda list                    
 defgeneric method clause                    specialized lambda list                         
 defmethod form                              specialized lambda list                         
 defsetf form                                defsetf lambda list                             
 define-setf-expander form                   macro lambda list                               
 deftype form                                deftype lambda list                             
 destructuring-bind form                     destructuring lambda list                       
 define-compiler-macro form                  macro lambda list                               
 define-modify-macro form                    define-modify-macro lambda list                 

                         Figure 3-10: What Kind of Lambda Lists to Use                       


   Figure 3-11 lists some defined names that are applicable to lambda
lists.

  lambda-list-keywords  lambda-parameters-limit    

  Figure 3-11: Defined names applicable to lambda lists


* Menu:

* Ordinary Lambda Lists::
* Generic Function Lambda Lists::
* Specialized Lambda Lists::
* Macro Lambda Lists::
* Destructuring Lambda Lists::
* Boa Lambda Lists::
* Defsetf Lambda Lists::
* Deftype Lambda Lists::
* Define-modify-macro Lambda Lists::
* Define-method-combination Arguments Lambda Lists::
* Syntactic Interaction of Documentation Strings and Declarations::


File: gcl.info,  Node: Ordinary Lambda Lists,  Next: Generic Function Lambda Lists,  Prev: Lambda Lists,  Up: Lambda Lists

3.4.1 Ordinary Lambda Lists
---------------------------

An ordinary lambda list is used to describe how a set of arguments is
received by an ordinary function.  The defined names in Figure 3-12 are
those which use ordinary lambda lists:

  define-method-combination  handler-case  restart-case  
  defun                      labels                      
  flet                       lambda                      

  Figure 3-12: Standardized Operators that use Ordinary Lambda Lists


   An ordinary lambda list can contain the lambda list keywords shown in
Figure 3-13.

  &allow-other-keys  &key       &rest  
  &aux               &optional         

  Figure 3-13: Lambda List Keywords used by Ordinary Lambda Lists


   Each element of a lambda list is either a parameter specifier or a
lambda list keyword.  Implementations are free to provide additional
lambda list keywords.  For a list of all lambda list keywords used by
the implementation, see lambda-list-keywords.

   The syntax for ordinary lambda lists is as follows:

   lambda-list ::=({var}*
                 [&optional {var | 		       (var [init-form [supplied-p-parameter ]])}*]
                 [&rest var]
                 [&key {var | 		          	 ({var |  					       (keyword-name var)} 				 	[init-form [supplied-p-parameter]])}* pt [&allow-other-keys]]
                 [&aux {var | (var [init-form])}*])                

   A var or supplied-p-parameter must be a symbol that is not the name
of a constant variable.

   An init-form can be any form.  Whenever any init-form is evaluated
for any parameter specifier, that form may refer to any parameter
variable to the left of the specifier in which the init-form appears,
including any supplied-p-parameter variables, and may rely on the fact
that no other parameter variable has yet been bound (including its own
parameter variable).

   A keyword-name can be any symbol, but by convention is normally a
keyword_1; all standardized functions follow that convention.

   An ordinary lambda list has five parts, any or all of which may be
empty.  For information about the treatment of argument mismatches, see
*note Error Checking in Function Calls::.

* Menu:

* Specifiers for the required parameters::
* Specifiers for optional parameters::
* A specifier for a rest parameter::
* Specifiers for keyword parameters::
* Suppressing Keyword Argument Checking::
* Examples of Suppressing Keyword Argument Checking::
* Specifiers for &aux variables::
* Examples of Ordinary Lambda Lists::


File: gcl.info,  Node: Specifiers for the required parameters,  Next: Specifiers for optional parameters,  Prev: Ordinary Lambda Lists,  Up: Ordinary Lambda Lists

3.4.1.1 Specifiers for the required parameters
..............................................

These are all the parameter specifiers up to the first lambda list
keyword; if there are no lambda list keywords, then all the specifiers
are for required parameters.  Each required parameter is specified by a
parameter variable var.  var is bound as a lexical variable unless it is
declared special.

   If there are n required parameters (n may be zero), there must be at
least n passed arguments, and the required parameters are bound to the
first n passed arguments; see *note Error Checking in Function Calls::.
The other parameters are then processed using any remaining arguments.


File: gcl.info,  Node: Specifiers for optional parameters,  Next: A specifier for a rest parameter,  Prev: Specifiers for the required parameters,  Up: Ordinary Lambda Lists

3.4.1.2 Specifiers for optional parameters
..........................................

If &optional is present, the optional parameter specifiers are those
following &optional up to the next lambda list keyword or the end of the
list.  If optional parameters are specified, then each one is processed
as follows.  If any unprocessed arguments remain, then the parameter
variable var is bound to the next remaining argument, just as for a
required parameter.  If no arguments remain, however, then init-form is
evaluated, and the parameter variable is bound to the resulting value
(or to nil if no init-form appears in the parameter specifier).  If
another variable name supplied-p-parameter appears in the specifier, it
is bound to true if an argument had been available, and to false if no
argument remained (and therefore init-form had to be evaluated).
Supplied-p-parameter is bound not to an argument but to a value
indicating whether or not an argument had been supplied for the
corresponding var.


File: gcl.info,  Node: A specifier for a rest parameter,  Next: Specifiers for keyword parameters,  Prev: Specifiers for optional parameters,  Up: Ordinary Lambda Lists

3.4.1.3 A specifier for a rest parameter
........................................

&rest, if present, must be followed by a single rest parameter
specifier, which in turn must be followed by another lambda list keyword
or the end of the lambda list.  After all optional parameter specifiers
have been processed, then there may or may not be a rest parameter.  If
there is a rest parameter, it is bound to a list of all
as-yet-unprocessed arguments.  If no unprocessed arguments remain, the
rest parameter is bound to the empty list.  If there is no rest
parameter and there are no keyword parameters, then an error should be
signaled if any unprocessed arguments remain; see *note Error Checking
in Function Calls::.  The value of a rest parameter is permitted, but
not required, to share structure with the last argument to apply.


File: gcl.info,  Node: Specifiers for keyword parameters,  Next: Suppressing Keyword Argument Checking,  Prev: A specifier for a rest parameter,  Up: Ordinary Lambda Lists

3.4.1.4 Specifiers for keyword parameters
.........................................

If &key is present, all specifiers up to the next lambda list keyword or
the end of the list are keyword parameter specifiers.  When keyword
parameters are processed, the same arguments are processed that would be
made into a list for a rest parameter.  It is permitted to specify both
&rest and &key.  In this case the remaining arguments are used for both
purposes; that is, all remaining arguments are made into a list for the
rest parameter, and are also processed for the &key parameters.

   If &key is specified, there must remain an even number of arguments;
see *note Odd Number of Keyword Arguments::.

   These arguments are considered as pairs, the first argument in each
pair being interpreted as a name and the second as the corresponding
value.  The first object of each pair must be a symbol; see *note
Invalid Keyword Arguments::.  The keyword parameter specifiers may
optionally be followed by the lambda list keyword &allow-other-keys.

   In each keyword parameter specifier must be a name var for the
parameter variable.

   If the var appears alone or in a (var init-form) combination, the
keyword name used when matching arguments to parameters is a symbol in
the KEYWORD package whose name is the same (under string=) as var's.  If
the notation ((keyword-name var) init-form) is used, then the keyword
name used to match arguments to parameters is keyword-name, which may be
a symbol in any package.  (Of course, if it is not a symbol in the
KEYWORD package, it does not necessarily self-evaluate, so care must be
taken when calling the function to make sure that normal evaluation
still yields the keyword name.)

   Thus

      (defun foo (&key radix (type 'integer)) ...)

   means exactly the same as

      (defun foo (&key ((:radix radix)) ((:type type) 'integer)) ...)

   The keyword parameter specifiers are, like all parameter specifiers,
effectively processed from left to right.  For each keyword parameter
specifier, if there is an argument pair whose name matches that
specifier's name (that is, the names are eq), then the parameter
variable for that specifier is bound to the second item (the value) of
that argument pair.  If more than one such argument pair matches, the
leftmost argument pair is used.  If no such argument pair exists, then
the init-form for that specifier is evaluated and the parameter variable
is bound to that value (or to nil if no init-form was specified).
supplied-p-parameter is treated as for &optional parameters: it is bound
to true if there was a matching argument pair, and to false otherwise.

   Unless keyword argument checking is suppressed, an argument pair must
a name matched by a parameter specifier; see *note Unrecognized Keyword
Arguments::.

   If keyword argument checking is suppressed, then it is permitted for
an argument pair to match no parameter specifier, and the argument pair
is ignored, but such an argument pair is accessible through the rest
parameter if one was supplied.  The purpose of these mechanisms is to
allow sharing of argument lists among several lambda expressions and to
allow either the caller or the called lambda expression to specify that
such sharing may be taking place.

   Note that if &key is present, a keyword argument of :allow-other-keys
is always permitted--regardless of whether the associated value is true
or false.  However, if the value is false, other non-matching keywords
are not tolerated (unless &allow-other-keys was used).

   Furthermore, if the receiving argument list specifies a regular
argument which would be flagged by :allow-other-keys, then
:allow-other-keys has both its special-cased meaning (identifying
whether additional keywords are permitted) and its normal meaning (data
flow into the function in question).


File: gcl.info,  Node: Suppressing Keyword Argument Checking,  Next: Examples of Suppressing Keyword Argument Checking,  Prev: Specifiers for keyword parameters,  Up: Ordinary Lambda Lists

3.4.1.5 Suppressing Keyword Argument Checking
.............................................

If &allow-other-keys was specified in the lambda list of a function,
keyword_2 argument checking is suppressed in calls to that function.

   If the :allow-other-keys argument is true in a call to a function,
keyword_2 argument checking is suppressed in that call.

   The :allow-other-keys argument is permissible in all situations
involving keyword_2 arguments, even when its associated value is false.


File: gcl.info,  Node: Examples of Suppressing Keyword Argument Checking,  Next: Specifiers for &aux variables,  Prev: Suppressing Keyword Argument Checking,  Up: Ordinary Lambda Lists

3.4.1.6 Examples of Suppressing Keyword Argument Checking
.........................................................

     ;;; The caller can supply :ALLOW-OTHER-KEYS T to suppress checking.
      ((lambda (&key x) x) :x 1 :y 2 :allow-other-keys t) =>  1
     ;;; The callee can use &ALLOW-OTHER-KEYS to suppress checking.
      ((lambda (&key x &allow-other-keys) x) :x 1 :y 2) =>  1
     ;;; :ALLOW-OTHER-KEYS NIL is always permitted.
      ((lambda (&key) t) :allow-other-keys nil) =>  T
     ;;; As with other keyword arguments, only the left-most pair
     ;;; named :ALLOW-OTHER-KEYS has any effect.
      ((lambda (&key x) x)
       :x 1 :y 2 :allow-other-keys t :allow-other-keys nil)
     =>  1
     ;;; Only the left-most pair named :ALLOW-OTHER-KEYS has any effect,
     ;;; so in safe code this signals a PROGRAM-ERROR (and might enter the
     ;;; debugger).  In unsafe code, the consequences are undefined.
      ((lambda (&key x) x)                   ;This call is not valid
       :x 1 :y 2 :allow-other-keys nil :allow-other-keys t)


File: gcl.info,  Node: Specifiers for &aux variables,  Next: Examples of Ordinary Lambda Lists,  Prev: Examples of Suppressing Keyword Argument Checking,  Up: Ordinary Lambda Lists

3.4.1.7 Specifiers for &aux variables
.....................................

These are not really parameters.  If the lambda list keyword &aux is
present, all specifiers after it are auxiliary variable specifiers.
After all parameter specifiers have been processed, the auxiliary
variable specifiers (those following &aux) are processed from left to
right.  For each one, init-form is evaluated and var is bound to that
value (or to nil if no init-form was specified).  &aux variable
processing is analogous to let* processing.

      (lambda (x y &aux (a (car x)) (b 2) c) (list x y a b c))
         == (lambda (x y) (let* ((a (car x)) (b 2) c) (list x y a b c)))


File: gcl.info,  Node: Examples of Ordinary Lambda Lists,  Prev: Specifiers for &aux variables,  Up: Ordinary Lambda Lists

3.4.1.8 Examples of Ordinary Lambda Lists
.........................................

Here are some examples involving optional parameters and rest
parameters:

      ((lambda (a b) (+ a (* b 3))) 4 5) =>  19
      ((lambda (a &optional (b 2)) (+ a (* b 3))) 4 5) =>  19
      ((lambda (a &optional (b 2)) (+ a (* b 3))) 4) =>  10
      ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)))
     =>  (2 NIL 3 NIL NIL)
      ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)) 6)
     =>  (6 T 3 NIL NIL)
      ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)) 6 3)
     =>  (6 T 3 T NIL)
      ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)) 6 3 8)
     =>  (6 T 3 T (8))
      ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x))
       6 3 8 9 10 11)
     =>  (6 t 3 t (8 9 10 11))

   Here are some examples involving keyword parameters:

      ((lambda (a b &key c d) (list a b c d)) 1 2) =>  (1 2 NIL NIL)
      ((lambda (a b &key c d) (list a b c d)) 1 2 :c 6) =>  (1 2 6 NIL)
      ((lambda (a b &key c d) (list a b c d)) 1 2 :d 8) =>  (1 2 NIL 8)
      ((lambda (a b &key c d) (list a b c d)) 1 2 :c 6 :d 8) =>  (1 2 6 8)
      ((lambda (a b &key c d) (list a b c d)) 1 2 :d 8 :c 6) =>  (1 2 6 8)
      ((lambda (a b &key c d) (list a b c d)) :a 1 :d 8 :c 6) =>  (:a 1 6 8)
      ((lambda (a b &key c d) (list a b c d)) :a :b :c :d) =>  (:a :b :d NIL)
      ((lambda (a b &key ((:sea c)) d) (list a b c d)) 1 2 :sea 6) =>  (1 2 6 NIL)
      ((lambda (a b &key ((c c)) d) (list a b c d)) 1 2 'c 6) =>  (1 2 6 NIL)

   Here are some examples involving optional parameters, rest
parameters, and keyword parameters together:

      ((lambda (a &optional (b 3) &rest x &key c (d a))
         (list a b c d x)) 1)
     =>  (1 3 NIL 1 ())
      ((lambda (a &optional (b 3) &rest x &key c (d a))
         (list a b c d x)) 1 2)
     =>  (1 2 NIL 1 ())
      ((lambda (a &optional (b 3) &rest x &key c (d a))
         (list a b c d x)) :c 7)
     =>  (:c 7 NIL :c ())
      ((lambda (a &optional (b 3) &rest x &key c (d a))
         (list a b c d x)) 1 6 :c 7)
     =>  (1 6 7 1 (:c 7))
      ((lambda (a &optional (b 3) &rest x &key c (d a))
         (list a b c d x)) 1 6 :d 8)
     =>  (1 6 NIL 8 (:d 8))
      ((lambda (a &optional (b 3) &rest x &key c (d a))
         (list a b c d x)) 1 6 :d 8 :c 9 :d 10)
     =>  (1 6 9 8 (:d 8 :c 9 :d 10))

   As an example of the use of &allow-other-keys and :allow-other-keys,
consider a function that takes two named arguments of its own and also
accepts additional named arguments to be passed to make-array:

      (defun array-of-strings (str dims &rest named-pairs
                               &key (start 0) end &allow-other-keys)
        (apply #'make-array dims
               :initial-element (subseq str start end)
               :allow-other-keys t
               named-pairs))

   This function takes a string and dimensioning information and returns
an array of the specified dimensions, each of whose elements is the
specified string.  However, :start and :end named arguments may be used
to specify that a substring of the given string should be used.  In
addition, the presence of &allow-other-keys in the lambda list indicates
that the caller may supply additional named arguments; the rest
parameter provides access to them.  These additional named arguments are
passed to make-array.  The function make-array normally does not allow
the named arguments :start and :end to be used, and an error should be
signaled if such named arguments are supplied to make-array.  However,
the presence in the call to make-array of the named argument
:allow-other-keys with a true value causes any extraneous named
arguments, including :start and :end, to be acceptable and ignored.


File: gcl.info,  Node: Generic Function Lambda Lists,  Next: Specialized Lambda Lists,  Prev: Ordinary Lambda Lists,  Up: Lambda Lists

3.4.2 Generic Function Lambda Lists
-----------------------------------

A generic function lambda list is used to describe the overall shape of
the argument list to be accepted by a generic function.  Individual
method signatures might contribute additional keyword parameters to the
lambda list of the effective method.

   A generic function lambda list is used by defgeneric.

   A generic function lambda list has the following syntax:

   lambda-list ::=({var}*                  [&optional {var | (var)}*]
                 [&rest var]
                 [&key {var | ({var |  					       (keyword-name var)})}* pt [&allow-other-keys]])
               

   A generic function lambda list can contain the lambda list keywords
shown in Figure 3-14.

  &allow-other-keys  &optional    
  &key               &rest        

  Figure 3-14: Lambda List Keywords used by Generic Function Lambda Lists


   A generic function lambda list differs from an ordinary lambda list
in the following ways:

Required arguments
     Zero or more required parameters must be specified.

Optional and keyword arguments
     Optional parameters and keyword parameters may not have default
     initial value forms nor use supplied-p parameters.

Use of &aux
     The use of &aux is not allowed.


File: gcl.info,  Node: Specialized Lambda Lists,  Next: Macro Lambda Lists,  Prev: Generic Function Lambda Lists,  Up: Lambda Lists

3.4.3 Specialized Lambda Lists
------------------------------

A specialized lambda list is used to specialize a method for a
particular signature and to describe how arguments matching that
signature are received by the method.  The defined names in Figure 3-15
use specialized lambda lists in some way; see the dictionary entry for
each for information about how.

  defmethod  defgeneric    

  Figure 3-15: Standardized Operators that use Specialized Lambda Lists


   A specialized lambda list can contain the lambda list keywords shown
in Figure 3-16.

  &allow-other-keys  &key       &rest  
  &aux               &optional         

  Figure 3-16: Lambda List Keywords used by Specialized Lambda Lists


   A specialized lambda list is syntactically the same as an ordinary
lambda list except that each required parameter may optionally be
associated with a class or object for which that parameter is
specialized.

   lambda-list ::=({var | (var [specializer])}*
                [&optional {var | 		       (var [init-form [supplied-p-parameter]])}*]
                [&rest var]
                [&key {var | 		          	 ({var |  					       (keyword-name var)} 				 	[init-form [supplied-p-parameter]])}* [&allow-other-keys]]
                [&aux {var | (var [init-form])}*])                


File: gcl.info,  Node: Macro Lambda Lists,  Next: Destructuring Lambda Lists,  Prev: Specialized Lambda Lists,  Up: Lambda Lists

3.4.4 Macro Lambda Lists
------------------------

A macro lambda list is used in describing macros defined by the
operators in Figure 3-17.

  define-compiler-macro  defmacro  macrolet  
  define-setf-expander                       

  Figure 3-17: Operators that use Macro Lambda Lists


   With the additional restriction that an environment parameter may
appear only once (at any of the positions indicated), a macro lambda
list has the following syntax:

   reqvars ::={var | !pattern}*

   optvars ::=[&optional {var | 		       ({var | !pattern} [init-form [supplied-p-parameter]])}*]

   restvar ::=[{&rest | &body} {var | !pattern}]

   keyvars ::=[&key {var | 		          	 ({var |  					       (keyword-name {var | !pattern})} 				 	[init-form [supplied-p-parameter]])}*
            [&allow-other-keys]]

   auxvars ::=[&aux {var | (var [init-form])}*]

   envvar ::=[&environment var]

   wholevar ::=[&whole var]

   lambda-list ::=(!wholevar !envvar !reqvars !envvar !optvars !envvar
                !restvar !envvar !keyvars !envvar !auxvars !envvar) |
                (!wholevar !envvar !reqvars !envvar !optvars !envvar . var)

   pattern ::=(!wholevar !reqvars !optvars !restvar !keyvars !auxvars) |
            (!wholevar !reqvars !optvars . var)

   A macro lambda list can contain the lambda list keywords shown in
Figure 3-18.

  &allow-other-keys  &environment  &rest   
  &aux               &key          &whole  
  &body              &optional             

  Figure 3-18: Lambda List Keywords used by Macro Lambda Lists


   Optional parameters (introduced by &optional) and keyword parameters
(introduced by &key) can be supplied in a macro lambda list, just as in
an ordinary lambda list.  Both may contain default initialization forms
and supplied-p parameters.

   &body

   is identical in function to &rest, but it can be used to inform
certain output-formatting and editing functions that the remainder of
the form is treated as a body, and should be indented accordingly.  Only
one of &body or &rest can be used at any particular level; see *note
Destructuring by Lambda Lists::.

   &body can appear at any level of a macro lambda list; for details,
see *note Destructuring by Lambda Lists::.

   &whole

   is followed by a single variable that is bound to the entire
macro-call form; this is the value that the macro function receives as
its first argument.

   If &whole and a following variable appear, they must appear first in
lambda-list,

   before any other parameter or lambda list keyword.

   &whole can appear at any level of a macro lambda list.  At inner
levels, the &whole variable is bound to the corresponding part of the
argument, as with &rest, but unlike &rest, other arguments are also
allowed.  The use of &whole does not affect the pattern of arguments
specified.

   &environment

   is followed by a single variable that is bound to an environment
representing the lexical environment in which the macro call is to be
interpreted.  This environment should be used with

   macro-function,

   get-setf-expansion,

   compiler-macro-function,

   and macroexpand (for example) in computing the expansion of the
macro, to ensure that any lexical bindings or definitions established in
the compilation environment are taken into account.

   &environment can only appear at the top level of a macro lambda list,
and can only appear once, but can appear anywhere in that list;

   the &environment parameter is bound along with &whole before any
other variables in the lambda list, regardless of where &environment
appears in the lambda list.

   The object that is bound to the environment parameter has dynamic
extent.

   Destructuring allows a macro lambda list to express the structure of
a macro call syntax.  If no lambda list keywords appear, then the macro
lambda list is a tree containing parameter names at the leaves.  The
pattern and the macro form must have compatible tree structure; that is,
their tree structure must be equivalent, or it must differ only in that
some leaves of the pattern match non-atomic objects of the macro form.

   For information about error detection in this situation, see *note
Destructuring Mismatch::.

   A destructuring lambda list (whether at top level or embedded) can be
dotted, ending in a parameter name.  This situation is treated exactly
as if the parameter name that ends the list had appeared preceded by
&rest.

   It is permissible for a macro form (or a subexpression of a macro
form) to be a dotted list only when (... &rest var) or (... . var) is
used to match it.  It is the responsibility of the macro to recognize
and deal with such situations.

   [Editorial Note by KMP: Apparently the dotted-macro-forms cleanup
doesn't allow for the macro to 'manually' notice dotted forms and fix
them as well. 	It shouldn't be required that this be done only by &REST
or a dotted pattern; it should only matter that ultimately the non-macro
result of a full-macro expansion not contain dots. 	Anyway, I plan to
address this editorially unless someone raises an objection.]

* Menu:

* Destructuring by Lambda Lists::
* Data-directed Destructuring by Lambda Lists::
* Examples of Data-directed Destructuring by Lambda Lists::
* Lambda-list-directed Destructuring by Lambda Lists::


File: gcl.info,  Node: Destructuring by Lambda Lists,  Next: Data-directed Destructuring by Lambda Lists,  Prev: Macro Lambda Lists,  Up: Macro Lambda Lists

3.4.4.1 Destructuring by Lambda Lists
.....................................

Anywhere in a macro lambda list where a parameter name can appear, and
where ordinary lambda list syntax (as described in *note Ordinary Lambda
Lists::) does not otherwise allow a list, a destructuring lambda list
can appear in place of the parameter name.  When this is done, then the
argument that would match the parameter is treated as a (possibly
dotted) list, to be used as an argument list for satisfying the
parameters in the embedded lambda list.  This is known as destructuring.

   Destructuring is the process of decomposing a compound object into
its component parts, using an abbreviated, declarative syntax, rather
than writing it out by hand using the primitive component-accessing
functions.  Each component part is bound to a variable.

   A destructuring operation requires an object to be decomposed, a
pattern that specifies what components are to be extracted, and the
names of the variables whose values are to be the components.


File: gcl.info,  Node: Data-directed Destructuring by Lambda Lists,  Next: Examples of Data-directed Destructuring by Lambda Lists,  Prev: Destructuring by Lambda Lists,  Up: Macro Lambda Lists

3.4.4.2 Data-directed Destructuring by Lambda Lists
...................................................

In data-directed destructuring, the pattern is a sample object of the
type to be decomposed.  Wherever a component is to be extracted, a
symbol appears in the pattern; this symbol is the name of the variable
whose value will be that component.


File: gcl.info,  Node: Examples of Data-directed Destructuring by Lambda Lists,  Next: Lambda-list-directed Destructuring by Lambda Lists,  Prev: Data-directed Destructuring by Lambda Lists,  Up: Macro Lambda Lists

3.4.4.3 Examples of Data-directed Destructuring by Lambda Lists
...............................................................

An example pattern is

   (a b c)

   which destructures a list of three elements.  The variable a is
assigned to the first element, b to the second, etc.  A more complex
example is

   ((first . rest) . more)

   The important features of data-directed destructuring are its
syntactic simplicity and the ability to extend it to
lambda-list-directed destructuring.


File: gcl.info,  Node: Lambda-list-directed Destructuring by Lambda Lists,  Prev: Examples of Data-directed Destructuring by Lambda Lists,  Up: Macro Lambda Lists

3.4.4.4 Lambda-list-directed Destructuring by Lambda Lists
..........................................................

An extension of data-directed destructuring of trees is
lambda-list-directed destructuring.  This derives from the analogy
between the three-element destructuring pattern

   (first second third)

   and the three-argument lambda list

   (first second third)

   Lambda-list-directed destructuring is identical to data-directed
destructuring if no lambda list keywords appear in the pattern.  Any
list in the pattern (whether a sub-list or the whole pattern itself)
that contains a lambda list keyword is interpreted specially.  Elements
of the list to the left of the first lambda list keyword are treated as
destructuring patterns, as usual, but the remaining elements of the list
are treated like a function's lambda list except that where a variable
would normally be required, an arbitrary destructuring pattern is
allowed.  Note that in case of ambiguity, lambda list syntax is
preferred over destructuring syntax.  Thus, after &optional a list of
elements is a list of a destructuring pattern and a default value form.

   The detailed behavior of each lambda list keyword in a
lambda-list-directed destructuring pattern is as follows:

&optional
     Each following element is a variable or a list of a destructuring
     pattern, a default value form, and a supplied-p variable.  The
     default value and the supplied-p variable can be omitted.  If the
     list being destructured ends early, so that it does not have an
     element to match against this destructuring (sub)-pattern, the
     default form is evaluated and destructured instead.  The supplied-p
     variable receives the value nil if the default form is used, t
     otherwise.

&rest, &body
     The next element is a destructuring pattern that matches the rest
     of the list.  &body is identical to &rest but declares that what is
     being matched is a list of forms that constitutes the body of form.
     This next element must be the last unless a lambda list keyword
     follows it.

&aux
     The remaining elements are not destructuring patterns at all, but
     are auxiliary variable bindings.

&whole
     The next element is a destructuring pattern that matches the entire
     form in a macro, or the entire subexpression at inner levels.

&key
     Each following element is one of

     
          a variable,

     or
          a list of a variable, an optional initialization form, and an
          optional supplied-p variable.

     or
          a list of a list of a keyword and a destructuring pattern, an
          optional initialization form, and an optional supplied-p
          variable.

     The rest of the list being destructured is taken to be alternating
     keywords and values and is taken apart appropriately.

&allow-other-keys
     Stands by itself.


File: gcl.info,  Node: Destructuring Lambda Lists,  Next: Boa Lambda Lists,  Prev: Macro Lambda Lists,  Up: Lambda Lists

3.4.5 Destructuring Lambda Lists
--------------------------------

A destructuring lambda list is used by destructuring-bind.

   Destructuring lambda lists are closely related to macro lambda lists;
see *note Macro Lambda Lists::.  A destructuring lambda list can contain
all of the lambda list keywords listed for macro lambda lists except for
&environment, and supports destructuring in the same way.  Inner lambda
lists nested within a macro lambda list have the syntax of destructuring
lambda lists.

   A destructuring lambda list has the following syntax:

   reqvars ::={var | !lambda-list}*

   optvars ::=[&optional {var | 		       ({var | !lambda-list} [init-form [supplied-p-parameter]])}*]

   restvar ::=[{&rest | &body} {var | !lambda-list}]

   keyvars ::=[&key {var | 		          	 ({var |  					       (keyword-name {var | !lambda-list})} 				 	[init-form [supplied-p-parameter]])}*
            [&allow-other-keys]]

   auxvars ::=[&aux {var | (var [init-form])}*]

   envvar ::=[&environment var]

   wholevar ::=[&whole var]

   lambda-list ::=(!wholevar !reqvars !optvars !restvar !keyvars !auxvars) |
                (!wholevar !reqvars !optvars . var)


File: gcl.info,  Node: Boa Lambda Lists,  Next: Defsetf Lambda Lists,  Prev: Destructuring Lambda Lists,  Up: Lambda Lists

3.4.6 Boa Lambda Lists
----------------------

A boa lambda list is a lambda list that is syntactically like an
ordinary lambda list, but that is processed in "by order of argument"
style.

   A boa lambda list is used only in a defstruct form, when explicitly
specifying the lambda list of a constructor function (sometimes called a
"boa constructor").

   The &optional, &rest, &aux,

   &key, and &allow-other-keys

   lambda list keywords are recognized in a boa lambda list.  The way
these lambda list keywords differ from their use in an ordinary lambda
list follows.

   Consider this example, which describes how destruct processes its
:constructor option.

      (:constructor create-foo
              (a &optional b (c 'sea) &rest d &aux e (f 'eff)))

   This defines create-foo to be a constructor of one or more arguments.
The first argument is used to initialize the a slot.  The second
argument is used to initialize the b slot.  If there isn't any second
argument, then the default value given in the body of the defstruct (if
given) is used instead.  The third argument is used to initialize the c
slot.  If there isn't any third argument, then the symbol sea is used
instead.  Any arguments following the third argument are collected into
a list and used to initialize the d slot.  If there are three or fewer
arguments, then nil is placed in the d slot.  The e slot is not
initialized; its initial value is implementation-defined.  Finally, the
f slot is initialized to contain the symbol eff.

   &key and &allow-other-keys arguments default in a manner similar to
that of &optional arguments: if no default is supplied in the lambda
list then the default value given in the body of the defstruct (if
given) is used instead.  For example:

      (defstruct (foo (:constructor CREATE-FOO (a &optional b (c 'sea)
                                                  &key (d 2)
                                                  &aux e (f 'eff))))
        (a 1) (b 2) (c 3) (d 4) (e 5) (f 6))

      (create-foo 10) =>  #S(FOO A 10 B 2 C SEA D 2 E implemention-dependent F EFF)
      (create-foo 10 'bee 'see :d 'dee)
     =>  #S(FOO A 10 B BEE C SEE D DEE E implemention-dependent F EFF)

   If keyword arguments of the form ((key var) [default [svar]]) are
specified, the slot name is matched with var (not key).

   The actions taken in the b and e cases were carefully chosen to allow
the user to specify all possible behaviors.  The &aux variables can be
used to completely override the default initializations given in the
body.

   If no default value is supplied for an aux variable variable, the
consequences are undefined if an attempt is later made to read the
corresponding slot's value before a value is explicitly assigned.  If
such a slot has a :type option specified, this suppressed initialization
does not imply a type mismatch situation; the declared type is only
required to apply when the slot is finally assigned.

   With this definition, the following can be written:

      (create-foo 1 2)

   instead of

      (make-foo :a 1 :b 2)

   and create-foo provides defaulting different from that of make-foo.

   Additional arguments that do not correspond to slot names but are
merely present to supply values used in subsequent initialization
computations are allowed.  For example, in the definition

      (defstruct (frob (:constructor create-frob
                       (a &key (b 3 have-b) (c-token 'c)
                               (c (list c-token (if have-b 7 2))))))
              a b c)

   the c-token argument is used merely to supply a value used in the
initialization of the c slot.  The supplied-p parameters associated with
optional parameters and keyword parameters might also be used this way.


File: gcl.info,  Node: Defsetf Lambda Lists,  Next: Deftype Lambda Lists,  Prev: Boa Lambda Lists,  Up: Lambda Lists

3.4.7 Defsetf Lambda Lists
--------------------------

A defsetf lambda list is used by defsetf.

   A defsetf lambda list has the following syntax:

   lambda-list ::=({var}*
                [&optional {var | 		       (var [init-form [supplied-p-parameter]])}*]
                [&rest var]
                [&key {var | 		          	 ({var |  					       (keyword-name var)} 				 	[init-form [supplied-p-parameter]])}* pt [&allow-other-keys]]
                [&environment var]

   A defsetf lambda list can contain the lambda list keywords shown in
Figure 3-19.

  &allow-other-keys  &key       &rest  
  &environment       &optional         

  Figure 3-19: Lambda List Keywords used by Defsetf Lambda Lists


   A defsetf lambda list differs from an ordinary lambda list only in
that it does not permit the use of &aux, and that it permits use of
&environment, which introduces an environment parameter.


File: gcl.info,  Node: Deftype Lambda Lists,  Next: Define-modify-macro Lambda Lists,  Prev: Defsetf Lambda Lists,  Up: Lambda Lists

3.4.8 Deftype Lambda Lists
--------------------------

A deftype lambda list is used by deftype.

   A deftype lambda list has the same syntax as a macro lambda list, and
can therefore contain the lambda list keywords as a macro lambda list.

   A deftype lambda list differs from a macro lambda list only in that
if no init-form is supplied for an optional parameter or keyword
parameter in the lambda-list, the default value for that parameter is
the symbol * (rather than nil).


File: gcl.info,  Node: Define-modify-macro Lambda Lists,  Next: Define-method-combination Arguments Lambda Lists,  Prev: Deftype Lambda Lists,  Up: Lambda Lists

3.4.9 Define-modify-macro Lambda Lists
--------------------------------------

A define-modify-macro lambda list is used by define-modify-macro.

   A define-modify-macro lambda list can contain the lambda list
keywords shown in Figure 3-20.

  &optional  &rest  

  Figure 3-20: Lambda List Keywords used by Define-modify-macro Lambda Lists


   Define-modify-macro lambda lists are similar to ordinary lambda
lists, but do not support keyword arguments.  define-modify-macro has no
need match keyword arguments, and a rest parameter is sufficient.  Aux
variables are also not supported, since define-modify-macro has no body
forms which could refer to such bindings.  See the macro
define-modify-macro.


File: gcl.info,  Node: Define-method-combination Arguments Lambda Lists,  Next: Syntactic Interaction of Documentation Strings and Declarations,  Prev: Define-modify-macro Lambda Lists,  Up: Lambda Lists

3.4.10 Define-method-combination Arguments Lambda Lists
-------------------------------------------------------

A define-method-combination arguments lambda list is used by the
:arguments option to define-method-combination.

   A define-method-combination arguments lambda list can contain the
lambda list keywords shown in Figure 3-21.

  &allow-other-keys  &key       &rest   
  &aux               &optional  &whole  

  Figure 3-21: Lambda List Keywords used by Define-method-combination arguments Lambda Lists


   Define-method-combination arguments lambda lists are similar to
ordinary lambda lists, but also permit the use of &whole.


File: gcl.info,  Node: Syntactic Interaction of Documentation Strings and Declarations,  Prev: Define-method-combination Arguments Lambda Lists,  Up: Lambda Lists

3.4.11 Syntactic Interaction of Documentation Strings and Declarations
----------------------------------------------------------------------

In a number of situations, a documentation string can appear amidst a
series of declare expressions prior to a series of forms.

   In that case, if a string S appears where a documentation string is
permissible and is not followed by either a declare expression or a form
then S is taken to be a form; otherwise, S is taken as a documentation
string.  The consequences are unspecified if more than one such
documentation string is present.


File: gcl.info,  Node: Error Checking in Function Calls,  Next: Traversal Rules and Side Effects,  Prev: Lambda Lists,  Up: Evaluation and Compilation

3.5 Error Checking in Function Calls
====================================

* Menu:

* Argument Mismatch Detection::


File: gcl.info,  Node: Argument Mismatch Detection,  Prev: Error Checking in Function Calls,  Up: Error Checking in Function Calls

3.5.1 Argument Mismatch Detection
---------------------------------

* Menu:

* Safe and Unsafe Calls::
* Error Detection Time in Safe Calls::
* Too Few Arguments::
* Too Many Arguments::
* Unrecognized Keyword Arguments::
* Invalid Keyword Arguments::
* Odd Number of Keyword Arguments::
* Destructuring Mismatch::
* Errors When Calling a Next Method::


File: gcl.info,  Node: Safe and Unsafe Calls,  Next: Error Detection Time in Safe Calls,  Prev: Argument Mismatch Detection,  Up: Argument Mismatch Detection

3.5.1.1 Safe and Unsafe Calls
.............................

A call is a safe call if each of the following is either safe code or
system code (other than system code that results from macro expansion of
programmer code):

*
     the call.
*
     the definition of the function being called.
*
     the point of functional evaluation

   The following special cases require some elaboration:

*
     If the function being called is a generic function, it is
     considered safe if all of the following are

     safe code or system code:

     -
          its definition (if it was defined explicitly).
     -
          the method definitions for all applicable methods.
     -
          the definition of its method combination.

*
     For the form (coerce x 'function), where x is a lambda expression,
     the value of the optimize quality safety in the global environment
     at the time the coerce is executed applies to the resulting
     function.

*
     For a call to the function ensure-generic-function, the value of
     the optimize quality safety in the environment object passed as the
     :environment argument applies to the resulting generic function.

*
     For a call to compile with a lambda expression as the argument, the
     value of the optimize quality safety in the global environment at
     the time compile is called applies to the resulting compiled
     function.

*
     For a call to compile with only one argument, if the original
     definition of the function was safe, then the resulting compiled
     function must also be safe.

*
     A call to a method by call-next-method must be considered safe if
     each of the following is

     safe code or system code:

     -
          the definition of the generic function (if it was defined
          explicitly).
     -
          the method definitions for all applicable methods.
     -
          the definition of the method combination.
     -
          the point of entry into the body of the method defining form,
          where the binding of call-next-method is established.
     -
          the point of functional evaluation of the name
          call-next-method.

   An unsafe call is a call that is not a safe call.

   The informal intent is that the programmer can rely on a call to be
safe, even when system code is involved, if all reasonable steps have
been taken to ensure that the call is safe.  For example, if a
programmer calls mapcar from safe code and supplies a function that was
compiled as safe, the implementation is required to ensure that mapcar
makes a safe call as well.


File: gcl.info,  Node: Error Detection Time in Safe Calls,  Next: Too Few Arguments,  Prev: Safe and Unsafe Calls,  Up: Argument Mismatch Detection

3.5.1.2 Error Detection Time in Safe Calls
..........................................

If an error is signaled in a safe call, the exact point of the signal is
implementation-dependent.  In particular, it might be signaled at
compile time or at run time, and if signaled at run time, it might be
prior to, during, or after executing the call.  However, it is always
prior to the execution of the body of the function being called.


File: gcl.info,  Node: Too Few Arguments,  Next: Too Many Arguments,  Prev: Error Detection Time in Safe Calls,  Up: Argument Mismatch Detection

3.5.1.3 Too Few Arguments
.........................

It is not permitted to supply too few arguments to a function.  Too few
arguments means fewer arguments than the number of required parameters
for the function.

   If this situation occurs in a safe call,

   an error of type program-error must be signaled; and in an unsafe
call the situation has undefined consequences.


File: gcl.info,  Node: Too Many Arguments,  Next: Unrecognized Keyword Arguments,  Prev: Too Few Arguments,  Up: Argument Mismatch Detection

3.5.1.4 Too Many Arguments
..........................

It is not permitted to supply too many arguments to a function.  Too
many arguments means more arguments than the number of required
parameters plus the number of optional parameters; however, if the
function uses &rest or &key, it is not possible for it to receive too
many arguments.

   If this situation occurs in a safe call,

   an error of type program-error must be signaled; and in an unsafe
call the situation has undefined consequences.


File: gcl.info,  Node: Unrecognized Keyword Arguments,  Next: Invalid Keyword Arguments,  Prev: Too Many Arguments,  Up: Argument Mismatch Detection

3.5.1.5 Unrecognized Keyword Arguments
......................................

It is not permitted to supply a keyword argument to a function using a
name that is not recognized by that function unless keyword argument
checking is suppressed as described in *note Suppressing Keyword
Argument Checking::.

   If this situation occurs in a safe call,

   an error of type program-error must be signaled; and in an unsafe
call the situation has undefined consequences.


File: gcl.info,  Node: Invalid Keyword Arguments,  Next: Odd Number of Keyword Arguments,  Prev: Unrecognized Keyword Arguments,  Up: Argument Mismatch Detection

3.5.1.6 Invalid Keyword Arguments
.................................

It is not permitted to supply a keyword argument to a function using a
name that is not a symbol.

   If this situation occurs in a safe call,

   an error of type program-error must be signaled unless keyword
argument checking is suppressed as described in *note Suppressing
Keyword Argument Checking::; and in an unsafe call the situation has
undefined consequences.


File: gcl.info,  Node: Odd Number of Keyword Arguments,  Next: Destructuring Mismatch,  Prev: Invalid Keyword Arguments,  Up: Argument Mismatch Detection

3.5.1.7 Odd Number of Keyword Arguments
.......................................

An odd number of arguments must not be supplied for the keyword
parameters.

   If this situation occurs in a safe call,

   an error of type program-error must be signaled unless keyword
argument checking is suppressed as described in *note Suppressing
Keyword Argument Checking::; and in an unsafe call the situation has
undefined consequences.


File: gcl.info,  Node: Destructuring Mismatch,  Next: Errors When Calling a Next Method,  Prev: Odd Number of Keyword Arguments,  Up: Argument Mismatch Detection

3.5.1.8 Destructuring Mismatch
..............................

When matching a destructuring lambda list against a form, the pattern
and the form must have compatible tree structure, as described in *note
Macro Lambda Lists::.

   Otherwise, in a safe call, an error of type program-error must be
signaled; and in an unsafe call the situation has undefined
consequences.


File: gcl.info,  Node: Errors When Calling a Next Method,  Prev: Destructuring Mismatch,  Up: Argument Mismatch Detection

3.5.1.9 Errors When Calling a Next Method
.........................................

If call-next-method is called with arguments, the ordered set of
applicable methods for the changed set of arguments for call-next-method
must be the same as the ordered set of applicable methods for the
original arguments to the generic function, or else an error should be
signaled.

   The comparison between the set of methods applicable to the new
arguments and the set applicable to the original arguments is
insensitive to order differences among methods with the same
specializers.

   If call-next-method is called with arguments that specify a different
ordered set of applicable methods and there is no next method available,
the test for different methods and the associated error signaling (when
present) takes precedence over calling no-next-method.


File: gcl.info,  Node: Traversal Rules and Side Effects,  Next: Destructive Operations,  Prev: Error Checking in Function Calls,  Up: Evaluation and Compilation

3.6 Traversal Rules and Side Effects
====================================

The consequences are undefined when code executed during an
object-traversing operation destructively modifies the object in a way
that might affect the ongoing traversal operation.  In particular, the
following rules apply.

List traversal
     For list traversal operations, the cdr chain of the list is not
     allowed to be destructively modified.

Array traversal
     For array traversal operations, the array is not allowed to be
     adjusted and its fill pointer, if any, is not allowed to be
     changed.

Hash-table traversal
     For hash table traversal operations, new elements may not be added
     or deleted except that the element corresponding to the current
     hash key may be changed or removed.

Package traversal
     For package traversal operations (e.g., do-symbols), new symbols
     may not be interned in or uninterned from the package being
     traversed or any package that it uses except that the current
     symbol may be uninterned from the package being traversed.


File: gcl.info,  Node: Destructive Operations,  Next: Evaluation and Compilation Dictionary,  Prev: Traversal Rules and Side Effects,  Up: Evaluation and Compilation

3.7 Destructive Operations
==========================

* Menu:

* Modification of Literal Objects::
* Transfer of Control during a Destructive Operation::


File: gcl.info,  Node: Modification of Literal Objects,  Next: Transfer of Control during a Destructive Operation,  Prev: Destructive Operations,  Up: Destructive Operations

3.7.1 Modification of Literal Objects
-------------------------------------

The consequences are undefined if literal objects are destructively
modified.  For this purpose, the following operations are considered
destructive:

random-state
     Using it as an argument to the function random.

cons
     Changing the car_1 or cdr_1 of the cons, or performing a
     destructive operation on an object which is either the car_2 or the
     cdr_2 of the cons.

array
     Storing a new value into some element of the array, or performing a
     destructive operation on an object that is already such an element.

     Changing the fill pointer, dimensions, or displacement of the array
     (regardless of whether the array is actually adjustable).

     Performing a destructive operation on another array that is
     displaced to the array or that otherwise shares its contents with
     the array.

hash-table
     Performing a destructive operation on any key.

     Storing a new value_4 for any key, or performing a destructive
     operation on any object that is such a value.

     Adding or removing entries from the hash table.

structure-object
     Storing a new value into any slot, or performing a destructive
     operation on an object that is the value of some slot.

standard-object
     Storing a new value into any slot, or performing a destructive
     operation on an object that is the value of some slot.

     Changing the class of the object (e.g., using the function
     change-class).

readtable
     Altering the readtable case.

     Altering the syntax type of any character in this readtable.

     Altering the reader macro function associated with any character in
     the readtable, or altering the reader macro functions associated
     with characters defined as dispatching macro characters in the
     readtable.

stream
     Performing I/O operations on the stream, or closing the stream.

All other standardized types
     [This category includes, for example, character, condition,
     function, method-combination, method, number, package, pathname,
     restart, and symbol.]

     There are no standardized destructive operations defined on objects
     of these types.


File: gcl.info,  Node: Transfer of Control during a Destructive Operation,  Prev: Modification of Literal Objects,  Up: Destructive Operations

3.7.2 Transfer of Control during a Destructive Operation
--------------------------------------------------------

Should a transfer of control out of a destructive operation occur (e.g.,
due to an error) the state of the object being modified is
implementation-dependent.

* Menu:

* Examples of Transfer of Control during a Destructive Operation::


File: gcl.info,  Node: Examples of Transfer of Control during a Destructive Operation,  Prev: Transfer of Control during a Destructive Operation,  Up: Transfer of Control during a Destructive Operation

3.7.2.1 Examples of Transfer of Control during a Destructive Operation
......................................................................

The following examples illustrate some of the many ways in which the
implementation-dependent nature of the modification can manifest itself.

      (let ((a (list 2 1 4 3 7 6 'five)))
        (ignore-errors (sort a #'<))
        a)
     =>  (1 2 3 4 6 7 FIVE)
     OR=> (2 1 4 3 7 6 FIVE)
     OR=> (2)

      (prog foo ((a (list 1 2 3 4 5 6 7 8 9 10)))
        (sort a #'(lambda (x y) (if (zerop (random 5)) (return-from foo a) (> x y)))))
     =>  (1 2 3 4 5 6 7 8 9 10)
     OR=> (3 4 5 6 2 7 8 9 10 1)
     OR=> (1 2 4 3)


File: gcl.info,  Node: Evaluation and Compilation Dictionary,  Prev: Destructive Operations,  Up: Evaluation and Compilation

3.8 Evaluation and Compilation Dictionary
=========================================

* Menu:

* lambda (Symbol)::
* lambda::
* compile::
* eval::
* eval-when::
* load-time-value::
* quote::
* compiler-macro-function::
* define-compiler-macro::
* defmacro::
* macro-function::
* macroexpand::
* define-symbol-macro::
* symbol-macrolet::
* *macroexpand-hook*::
* proclaim::
* declaim::
* declare::
* ignore::
* dynamic-extent::
* type::
* inline::
* ftype::
* declaration::
* optimize::
* special::
* locally::
* the::
* special-operator-p::
* constantp::


File: gcl.info,  Node: lambda (Symbol),  Next: lambda,  Prev: Evaluation and Compilation Dictionary,  Up: Evaluation and Compilation Dictionary

3.8.1 lambda [Symbol]
---------------------

Syntax::
........

'lambda' lambda-list [[{declaration}* | documentation]] {form}*

Arguments::
...........

lambda-list--an ordinary lambda list.

   declaration--a declare expression; not evaluated.

   documentation--a string; not evaluated.

   form--a form.

Description::
.............

A lambda expression is a list that can be used in place of a function
name in certain contexts to denote a function by directly describing its
behavior rather than indirectly by referring to the name of an
established function.

   Documentation is attached to the denoted function (if any is actually
created) as a documentation string.

See Also::
..........

function, *note documentation:: , *note Lambda Expressions::, *note
Lambda Forms::, *note Syntactic Interaction of Documentation Strings and
Declarations::

Notes::
.......

The lambda form

      ((lambda lambda-list . body) . arguments)

   is semantically equivalent to the function form

      (funcall #'(lambda lambda-list . body) . arguments)


File: gcl.info,  Node: lambda,  Next: compile,  Prev: lambda (Symbol),  Up: Evaluation and Compilation Dictionary

3.8.2 lambda [Macro]
--------------------

'lambda' lambda-list [[{declaration}* | documentation]] {form}* =>
function

Arguments and Values::
......................

lambda-list--an ordinary lambda list.

   declaration--a declare expression; not evaluated.

   documentation--a string; not evaluated.

   form--a form.

   function--a function.

Description::
.............

Provides a shorthand notation for a function special form involving a
lambda expression such that:

         (lambda lambda-list [[{declaration}* | documentation]] {form}*)
      == (function (lambda lambda-list [[{declaration}* | documentation]] {form}*))
      == #'(lambda lambda-list [[{declaration}* | documentation]] {form}*)

Examples::
..........

      (funcall (lambda (x) (+ x 3)) 4) =>  7

See Also::
..........

lambda (symbol)

Notes::
.......

This macro could be implemented by:

     (defmacro lambda (&whole form &rest bvl-decls-and-body)
       (declare (ignore bvl-decls-and-body))
       `#',form)


File: gcl.info,  Node: compile,  Next: eval,  Prev: lambda,  Up: Evaluation and Compilation Dictionary

3.8.3 compile [Function]
------------------------

'compile' name &optional definition => function, warnings-p, failure-p

Arguments and Values::
......................

name--a function name, or nil.

   definition--a lambda expression or a function.  The default is the
function definition of name if it names a function, or the macro
function of name if it names a macro.  The consequences are undefined if
no definition is supplied when the name is nil.

   function--the function-name,

   or a compiled function.

   warnings-p--a generalized boolean.

   failure-p--a generalized boolean.

Description::
.............

Compiles an interpreted function.

   compile produces a compiled function from definition.  If the
definition is a lambda expression, it is coerced to a function.

   If the definition is already a compiled function, compile either
produces that function itself (i.e., is an identity operation) or an
equivalent function.

   [Editorial Note by KMP: There are a number of ambiguities here that
still need resolution.]  If the name is nil, the resulting compiled
function is returned directly as the primary value.  If a non-nil name
is given, then the resulting compiled function replaces the existing
function definition of name and the name is returned as the primary
value; if name is a symbol that names a macro, its macro function is
updated and the name is returned as the primary value.

   Literal objects appearing in code processed by the compile function
are neither copied nor coalesced.  The code resulting from the execution
of compile references objects that are eql to the corresponding objects
in the source code.

   compile is permitted, but not required, to establish a handler for
conditions of type error.  For example, the handler might issue a
warning and restart compilation from some implementation-dependent point
in order to let the compilation proceed without manual intervention.

   The secondary value, warnings-p, is false if no conditions of type
error or warning were detected by the compiler, and true otherwise.

   The tertiary value, failure-p, is false if no conditions of type
error or warning (other than style-warning) were detected by the
compiler, and true otherwise.

Examples::
..........

      (defun foo () "bar") =>  FOO
      (compiled-function-p #'foo) =>  implementation-dependent
      (compile 'foo) =>  FOO
      (compiled-function-p #'foo) =>  true
      (setf (symbol-function 'foo)
            (compile nil '(lambda () "replaced"))) =>  #<Compiled-Function>
      (foo) =>  "replaced"

Affected By::
.............

*error-output*,

   *macroexpand-hook*.

   The presence of macro definitions and proclamations.

Exceptional Situations::
........................

The consequences are undefined if the lexical environment surrounding
the function to be compiled contains any bindings other than those for
macros, symbol macros, or declarations.

   For information about errors detected during the compilation process,
see *note Exceptional Situations in the Compiler::.

See Also::
..........

*note compile-file::


File: gcl.info,  Node: eval,  Next: eval-when,  Prev: compile,  Up: Evaluation and Compilation Dictionary

3.8.4 eval [Function]
---------------------

'eval' form => {result}*

Arguments and Values::
......................

form--a form.

   results--the values yielded by the evaluation of form.

Description::
.............

Evaluates form in the current dynamic environment and the null lexical
environment.

   eval is a user interface to the evaluator.

   The evaluator expands macro calls as if through the use of
macroexpand-1.

   Constants appearing in code processed by eval are not copied nor
coalesced.  The code resulting from the execution of eval references
objects that are eql to the corresponding objects in the source code.

Examples::
..........

      (setq form '(1+ a) a 999) =>  999
      (eval form) =>  1000
      (eval 'form) =>  (1+ A)
      (let ((a '(this would break if eval used local value))) (eval form))
     =>  1000

See Also::
..........

macroexpand-1, *note The Evaluation Model::

Notes::
.......

To obtain the current dynamic value of a symbol, use of symbol-value is
equivalent (and usually preferable) to use of eval.

   Note that an eval form involves two levels of evaluation for its
argument.  First, form is evaluated by the normal argument evaluation
mechanism as would occur with any call.  The object that results from
this normal argument evaluation becomes the value of the form parameter,
and is then evaluated as part of the eval form.  For example:

      (eval (list 'cdr (car '((quote (a . b)) c)))) =>  b

   The argument form (list 'cdr (car '((quote (a . b)) c))) is evaluated
in the usual way to produce the argument (cdr (quote (a . b))); eval
then evaluates its argument, (cdr (quote (a . b))), to produce b.  Since
a single evaluation already occurs for any argument form in any function
form, eval is sometimes said to perform "an extra level of evaluation."


File: gcl.info,  Node: eval-when,  Next: load-time-value,  Prev: eval,  Up: Evaluation and Compilation Dictionary

3.8.5 eval-when [Special Operator]
----------------------------------

'eval-when' ({situation}*) {form}* => {result}*

Arguments and Values::
......................

situation--One of the symbols :compile-toplevel , :load-toplevel ,
:execute , compile , load , or eval .

   The use of eval, compile, and load is deprecated.

   forms--an implicit progn.

   results--the values of the forms if they are executed, or nil if they
are not.

Description::
.............

The body of an eval-when form is processed as an implicit progn, but
only in the situations listed.

   The use of the situations :compile-toplevel (or compile) and
:load-toplevel (or load) controls whether and when evaluation occurs
when eval-when appears as a top level form in code processed by
compile-file.  See *note File Compilation::.

   The use of the situation :execute (or eval) controls whether
evaluation occurs for other eval-when forms; that is, those that are not
top level forms, or those in code processed by eval or compile.  If the
:execute situation is specified in such a form, then the body forms are
processed as an implicit progn; otherwise, the eval-when form returns
nil.

   eval-when normally appears as a top level form, but it is meaningful
for it to appear as a non-top-level form.  However, the compile-time
side effects described in *note Compilation:: only take place when
eval-when appears as a top level form.

Examples::
..........

One example of the use of eval-when is that for the compiler to be able
to read a file properly when it uses user-defined reader macros, it is
necessary to write

      (eval-when (:compile-toplevel :load-toplevel :execute)
        (set-macro-character #\$ #'(lambda (stream char)
                                     (declare (ignore char))
                                     (list 'dollar (read stream))))) =>  T

   This causes the call to set-macro-character to be executed in the
compiler's execution environment, thereby modifying its reader syntax
table.

     ;;;     The EVAL-WHEN in this case is not at toplevel, so only the :EXECUTE
     ;;;     keyword is considered. At compile time, this has no effect.
     ;;;     At load time (if the LET is at toplevel), or at execution time
     ;;;     (if the LET is embedded in some other form which does not execute
     ;;;     until later) this sets (SYMBOL-FUNCTION 'FOO1) to a function which
     ;;;     returns 1.
      (let ((x 1))
        (eval-when (:execute :load-toplevel :compile-toplevel)
          (setf (symbol-function 'foo1) #'(lambda () x))))

     ;;;     If this expression occurs at the toplevel of a file to be compiled,
     ;;;     it has BOTH a compile time AND a load-time effect of setting
     ;;;     (SYMBOL-FUNCTION 'FOO2) to a function which returns 2.
      (eval-when (:execute :load-toplevel :compile-toplevel)
        (let ((x 2))
          (eval-when (:execute :load-toplevel :compile-toplevel)
            (setf (symbol-function 'foo2) #'(lambda () x)))))

     ;;;     If this expression occurs at the toplevel of a file to be compiled,
     ;;;     it has BOTH a compile time AND a load-time effect of setting the
     ;;;     function cell of FOO3 to a function which returns 3.
      (eval-when (:execute :load-toplevel :compile-toplevel)
        (setf (symbol-function 'foo3) #'(lambda () 3)))

     ;;; #4: This always does nothing. It simply returns NIL.
      (eval-when (:compile-toplevel)
        (eval-when (:compile-toplevel)
          (print 'foo4)))

     ;;;     If this form occurs at toplevel of a file to be compiled, FOO5 is
     ;;;     printed at compile time. If this form occurs in a non-top-level
     ;;;     position, nothing is printed at compile time. Regardless of context,
     ;;;     nothing is ever printed at load time or execution time.
      (eval-when (:compile-toplevel)
        (eval-when (:execute)
          (print 'foo5)))

     ;;;     If this form occurs at toplevel of a file to be compiled, FOO6 is
     ;;;     printed at compile time.  If this form occurs in a non-top-level
     ;;;     position, nothing is printed at compile time. Regardless of context,
     ;;;     nothing is ever printed at load time or execution time.
      (eval-when (:execute :load-toplevel)
        (eval-when (:compile-toplevel)
          (print 'foo6)))

See Also::
..........

*note compile-file:: , *note Compilation::

Notes::
.......

The following effects are logical consequences of the definition of
eval-when:

*
     Execution of a single eval-when expression executes the body code
     at most once.

*
     Macros intended for use in top level forms should be written so
     that side-effects are done by the forms in the macro expansion.
     The macro-expander itself should not do the side-effects.

     For example:

     Wrong:

           (defmacro foo ()
             (really-foo)
             `(really-foo))

     Right:

           (defmacro foo ()
             `(eval-when (:compile-toplevel :execute :load-toplevel) (really-foo)))

     Adherence to this convention means that such macros behave
     intuitively when appearing as non-top-level forms.

*
     Placing a variable binding around an eval-when reliably captures
     the binding because the compile-time-too mode cannot occur (i.e.,
     introducing a variable binding means that the eval-when is not a
     top level form).  For example,

           (let ((x 3))
             (eval-when (:execute :load-toplevel :compile-toplevel) (print x)))

     prints 3 at execution (i.e., load) time, and does not print
     anything at compile time.  This is important so that expansions of
     defun and defmacro can be done in terms of eval-when and can
     correctly capture the lexical environment.

           (defun bar (x) (defun foo () (+ x 3)))

     might expand into

           (defun bar (x)
             (progn (eval-when (:compile-toplevel)
                      (compiler::notice-function-definition 'foo '(x)))
                    (eval-when (:execute :load-toplevel)
                      (setf (symbol-function 'foo) #'(lambda () (+ x 3))))))

     which would be treated by the above rules the same as

           (defun bar (x)
             (setf (symbol-function 'foo) #'(lambda () (+ x 3))))

     when the definition of bar is not a top level form.


File: gcl.info,  Node: load-time-value,  Next: quote,  Prev: eval-when,  Up: Evaluation and Compilation Dictionary

3.8.6 load-time-value [Special Operator]
----------------------------------------

'load-time-value' form &optional read-only-p => object

Arguments and Values::
......................

form--a form; evaluated as described below.

   read-only-p--a boolean; not evaluated.

   object--the primary value resulting from evaluating form.

Description::
.............

load-time-value provides a mechanism for delaying evaluation of form
until the expression is in the run-time environment; see *note
Compilation::.

   Read-only-p designates whether the result can be considered a
constant object.  If t, the result is a read-only quantity that can, if
appropriate to the implementation, be copied into read-only space and/or
coalesced with similar constant objects from other programs.  If nil
(the default), the result must be neither copied nor coalesced; it must
be considered to be potentially modifiable data.

   If a load-time-value expression is processed by compile-file, the
compiler performs its normal semantic processing (such as macro
expansion and translation into machine code) on form, but arranges for
the execution of form to occur at load time in a null lexical
environment, with the result of this evaluation then being treated as a
literal object at run time.  It is guaranteed that the evaluation of
form will take place only once when the file is loaded, but the order of
evaluation with respect to the evaluation of top level forms in the file
is implementation-dependent.

   If a load-time-value expression appears within a function compiled
with compile, the form is evaluated at compile time in a null lexical
environment.  The result of this compile-time evaluation is treated as a
literal object in the compiled code.

   If a load-time-value expression is processed by eval, form is
evaluated in a null lexical environment, and one value is returned.
Implementations that implicitly compile (or partially compile)
expressions processed by eval might evaluate form only once, at the time
this compilation is performed.

   If the same list (load-time-value form) is evaluated or compiled more
than once, it is implementation-dependent whether form is evaluated only
once or is evaluated more than once.  This can happen both when an
expression being evaluated or compiled shares substructure, and when the
same form is processed by eval or compile multiple times.  Since a
load-time-value expression can be referenced in more than one place and
can be evaluated multiple times by eval, it is implementation-dependent
whether each execution returns a fresh object or returns the same object
as some other execution.  Users must use caution when destructively
modifying the resulting object.

   If two lists (load-time-value form) that are the same under equal but
are not identical are evaluated or compiled, their values always come
from distinct evaluations of form.  Their values may not be coalesced
unless read-only-p is t.

Examples::
..........

     ;;; The function INCR1 always returns the same value, even in different images.
     ;;; The function INCR2 always returns the same value in a given image,
     ;;; but the value it returns might vary from image to image.
     (defun incr1 (x) (+ x #.(random 17)))
     (defun incr2 (x) (+ x (load-time-value (random 17))))

     ;;; The function FOO1-REF references the nth element of the first of
     ;;; the *FOO-ARRAYS* that is available at load time.  It is permissible for
     ;;; that array to be modified (e.g., by SET-FOO1-REF); FOO1-REF will see the
     ;;; updated values.
     (defvar *foo-arrays* (list (make-array 7) (make-array 8)))
     (defun foo1-ref (n) (aref (load-time-value (first *my-arrays*) nil) n))
     (defun set-foo1-ref (n val)
       (setf (aref (load-time-value (first *my-arrays*) nil) n) val))

     ;;; The function BAR1-REF references the nth element of the first of
     ;;; the *BAR-ARRAYS* that is available at load time.  The programmer has
     ;;; promised that the array will be treated as read-only, so the system
     ;;; can copy or coalesce the array.
     (defvar *bar-arrays* (list (make-array 7) (make-array 8)))
     (defun bar1-ref (n) (aref (load-time-value (first *my-arrays*) t) n))

     ;;; This use of LOAD-TIME-VALUE permits the indicated vector to be coalesced
     ;;; even though NIL was specified, because the object was already read-only
     ;;; when it was written as a literal vector rather than created by a constructor.
     ;;; User programs must treat the vector v as read-only.
     (defun baz-ref (n)
       (let ((v (load-time-value #(A B C) nil)))
         (values (svref v n) v)))

     ;;; This use of LOAD-TIME-VALUE permits the indicated vector to be coalesced
     ;;; even though NIL was specified in the outer situation because T was specified
     ;;; in the inner situation.  User programs must treat the vector v as read-only.
     (defun baz-ref (n)
       (let ((v (load-time-value (load-time-value (vector 1 2 3) t) nil)))
         (values (svref v n) v)))

See Also::
..........

*note compile-file:: , *note compile:: , *note eval:: , *note Minimal
Compilation::, *note Compilation::

Notes::
.......

load-time-value must appear outside of quoted structure in a "for
evaluation" position.  In situations which would appear to call for use
of load-time-value within a quoted structure, the backquote reader macro
is probably called for; see *note Backquote::.

   Specifying nil for read-only-p is not a way to force an object to
become modifiable if it has already been made read-only.  It is only a
way to say that, for an object that is modifiable, this operation is not
intended to make that object read-only.


File: gcl.info,  Node: quote,  Next: compiler-macro-function,  Prev: load-time-value,  Up: Evaluation and Compilation Dictionary

3.8.7 quote [Special Operator]
------------------------------

'quote' object => object

Arguments and Values::
......................

object--an object; not evaluated.

Description::
.............

The quote special operator just returns object.

   The consequences are undefined if literal objects (including quoted
objects) are destructively modified.

Examples::
..........

      (setq a 1) =>  1
      (quote (setq a 3)) =>  (SETQ A 3)
      a =>  1
      'a =>  A
      ''a =>  (QUOTE A)
      '''a =>  (QUOTE (QUOTE A))
      (setq a 43) =>  43
      (list a (cons a 3)) =>  (43 (43 . 3))
      (list (quote a) (quote (cons a 3))) =>  (A (CONS A 3))
      1 =>  1
      '1 =>  1
      "foo" =>  "foo"
      '"foo" =>  "foo"
      (car '(a b)) =>  A
      '(car '(a b)) =>  (CAR (QUOTE (A B)))
      #(car '(a b)) =>  #(CAR (QUOTE (A B)))
      '#(car '(a b)) =>  #(CAR (QUOTE (A B)))

See Also::
..........

*note Evaluation::, *note Single-Quote::,

   *note Compiler Terminology::

Notes::
.......

The textual notation 'object is equivalent to (quote object); see *note
Compiler Terminology::.

   Some objects, called self-evaluating objects, do not require
quotation by quote.  However, symbols and lists are used to represent
parts of programs, and so would not be useable as constant data in a
program without quote.  Since quote suppresses the evaluation of these
objects, they become data rather than program.


File: gcl.info,  Node: compiler-macro-function,  Next: define-compiler-macro,  Prev: quote,  Up: Evaluation and Compilation Dictionary

3.8.8 compiler-macro-function [Accessor]
----------------------------------------

'compiler-macro-function' name &optional environment => function

   (setf (' compiler-macro-function' name &optional environment)
new-function)

Arguments and Values::
......................

name--a function name.

   environment--an environment object.

   function, new-function--a compiler macro function, or nil.

Description::
.............

Accesses the compiler macro function named name, if any, in the
environment.

   A value of nil denotes the absence of a compiler macro function named
name.

Exceptional Situations::
........................

The consequences are undefined if environment is non-nil in a use of
setf of compiler-macro-function.

See Also::
..........

*note define-compiler-macro:: , *note Compiler Macros::


File: gcl.info,  Node: define-compiler-macro,  Next: defmacro,  Prev: compiler-macro-function,  Up: Evaluation and Compilation Dictionary

3.8.9 define-compiler-macro [Macro]
-----------------------------------

'define-compiler-macro' name lambda-list [[{declaration}* |
documentation]] {form}*
=> name

Arguments and Values::
......................

name--a function name.

   lambda-list--a macro lambda list.

   declaration--a declare expression; not evaluated.

   documentation--a string; not evaluated.

   form--a form.

Description::
.............

[Editorial Note by KMP: This definition probably needs to be fully
expanded to not refer through the definition of defmacro, but should
suffice for now.]

   This is the normal mechanism for defining a compiler macro function.
Its manner of definition is the same as for defmacro; the only
differences are:

*
     The name can be a function name naming any function or macro.

*
     The expander function is installed as a compiler macro function for
     the name, rather than as a macro function.

*
     The &whole argument is bound to the form argument that is passed to
     the compiler macro function.  The remaining lambda-list parameters
     are specified as if this form contained the function name in the
     car and the actual arguments in the cdr, but if the car of the
     actual form is the symbol funcall, then the destructuring of the
     arguments is actually performed using its cddr instead.

*

     Documentation is attached as a documentation string to name (as
     kind compiler-macro) and to the compiler macro function.

*
     Unlike an ordinary macro, a compiler macro can decline to provide
     an expansion merely by returning a form that is the same as the
     original (which can be obtained by using &whole).

Examples::
..........

      (defun square (x) (expt x 2)) =>  SQUARE
      (define-compiler-macro square (&whole form arg)
        (if (atom arg)
            `(expt ,arg 2)
            (case (car arg)
              (square (if (= (length arg) 2)
                          `(expt ,(nth 1 arg) 4)
                          form))
              (expt   (if (= (length arg) 3)
                          (if (numberp (nth 2 arg))
                              `(expt ,(nth 1 arg) ,(* 2 (nth 2 arg)))
                              `(expt ,(nth 1 arg) (* 2 ,(nth 2 arg))))
                          form))
              (otherwise `(expt ,arg 2))))) =>  SQUARE
      (square (square 3)) =>  81
      (macroexpand '(square x)) =>  (SQUARE X), false
      (funcall (compiler-macro-function 'square) '(square x) nil)
     =>  (EXPT X 2)
      (funcall (compiler-macro-function 'square) '(square (square x)) nil)
     =>  (EXPT X 4)
      (funcall (compiler-macro-function 'square) '(funcall #'square x) nil)
     =>  (EXPT X 2)

      (defun distance-positional (x1 y1 x2 y2)
        (sqrt (+ (expt (- x2 x1) 2) (expt (- y2 y1) 2))))
     =>  DISTANCE-POSITIONAL
      (defun distance (&key (x1 0) (y1 0) (x2 x1) (y2 y1))
        (distance-positional x1 y1 x2 y2))
     =>  DISTANCE
      (define-compiler-macro distance (&whole form
                                       &rest key-value-pairs
                                       &key (x1 0  x1-p)
                                            (y1 0  y1-p)
                                            (x2 x1 x2-p)
                                            (y2 y1 y2-p)
                                       &allow-other-keys
                                       &environment env)
        (flet ((key (n) (nth (* n 2) key-value-pairs))
               (arg (n) (nth (1+ (* n 2)) key-value-pairs))
               (simplep (x)
                 (let ((expanded-x (macroexpand x env)))
                   (or (constantp expanded-x env)
                       (symbolp expanded-x)))))
          (let ((n (/ (length key-value-pairs) 2)))
            (multiple-value-bind (x1s y1s x2s y2s others)
                (loop for (key) on key-value-pairs by #'cddr
                      count (eq key ':x1) into x1s
                      count (eq key ':y1) into y1s
                      count (eq key ':x2) into x2s
                      count (eq key ':y1) into y2s
                      count (not (member key '(:x1 :x2 :y1 :y2)))
                        into others
                      finally (return (values x1s y1s x2s y2s others)))
              (cond ((and (= n 4)
                          (eq (key 0) :x1)
                          (eq (key 1) :y1)
                          (eq (key 2) :x2)
                          (eq (key 3) :y2))
                     `(distance-positional ,x1 ,y1 ,x2 ,y2))
                    ((and (if x1-p (and (= x1s 1) (simplep x1)) t)
                          (if y1-p (and (= y1s 1) (simplep y1)) t)
                          (if x2-p (and (= x2s 1) (simplep x2)) t)
                          (if y2-p (and (= y2s 1) (simplep y2)) t)
                          (zerop others))
                     `(distance-positional ,x1 ,y1 ,x2 ,y2))
                    ((and (< x1s 2) (< y1s 2) (< x2s 2) (< y2s 2)
                          (zerop others))
                     (let ((temps (loop repeat n collect (gensym))))
                       `(let ,(loop for i below n
                                    collect (list (nth i temps) (arg i)))
                          (distance
                            ,@(loop for i below n
                                    append (list (key i) (nth i temps)))))))
                    (t form))))))
     =>  DISTANCE
      (dolist (form
                '((distance :x1 (setq x 7) :x2 (decf x) :y1 (decf x) :y2 (decf x))
                  (distance :x1 (setq x 7) :y1 (decf x) :x2 (decf x) :y2 (decf x))
                  (distance :x1 (setq x 7) :y1 (incf x))
                  (distance :x1 (setq x 7) :y1 (incf x) :x1 (incf x))
                  (distance :x1 a1 :y1 b1 :x2 a2 :y2 b2)
                  (distance :x1 a1 :x2 a2 :y1 b1 :y2 b2)
                  (distance :x1 a1 :y1 b1 :z1 c1 :x2 a2 :y2 b2 :z2 c2)))
        (print (funcall (compiler-macro-function 'distance) form nil)))
      |>  (LET ((#:G6558 (SETQ X 7))
      |>        (#:G6559 (DECF X))
      |>        (#:G6560 (DECF X))
      |>        (#:G6561 (DECF X)))
      |>    (DISTANCE :X1 #:G6558 :X2 #:G6559 :Y1 #:G6560 :Y2 #:G6561))
      |>  (DISTANCE-POSITIONAL (SETQ X 7) (DECF X) (DECF X) (DECF X))
      |>  (LET ((#:G6567 (SETQ X 7))
      |>        (#:G6568 (INCF X)))
      |>    (DISTANCE :X1 #:G6567 :Y1 #:G6568))
      |>  (DISTANCE :X1 (SETQ X 7) :Y1 (INCF X) :X1 (INCF X))
      |>  (DISTANCE-POSITIONAL A1 B1 A2 B2)
      |>  (DISTANCE-POSITIONAL A1 B1 A2 B2)
      |>  (DISTANCE :X1 A1 :Y1 B1 :Z1 C1 :X2 A2 :Y2 B2 :Z2 C2)
     =>  NIL

See Also::
..........

*note compiler-macro-function:: , *note defmacro:: , *note
documentation:: , *note Syntactic Interaction of Documentation Strings
and Declarations::

Notes::
.......

The consequences of writing a compiler macro definition for a function
in the COMMON-LISP package are undefined; it is quite possible that in
some implementations such an attempt would override an equivalent or
equally important definition.  In general, it is recommended that a
programmer only write compiler macro definitions for functions he or she
personally maintains-writing a compiler macro definition for a function
maintained elsewhere is normally considered a violation of traditional
rules of modularity and data abstraction.


File: gcl.info,  Node: defmacro,  Next: macro-function,  Prev: define-compiler-macro,  Up: Evaluation and Compilation Dictionary

3.8.10 defmacro [Macro]
-----------------------

'defmacro' name lambda-list [[{declaration}* | documentation]] {form}*
=> name

Arguments and Values::
......................

name--a symbol.

   lambda-list--a macro lambda list.

   declaration--a declare expression; not evaluated.

   documentation--a string; not evaluated.

   form--a form.

Description::
.............

Defines name as a macro by associating a macro function with that name
in the global environment.

   The macro function is defined in the same lexical environment in
which the defmacro form appears.

   The parameter variables in lambda-list are bound to destructured
portions of the macro call.

   The expansion function accepts two arguments, a form and an
environment.  The expansion function returns a form.  The body of the
expansion function is specified by forms.  Forms are executed in order.
The value of the last form executed is returned as the expansion of the
macro.

   The body forms of the expansion function (but not the lambda-list)

   are implicitly enclosed in a block whose name is name.

   The lambda-list conforms to the requirements described in *note Macro
Lambda Lists::.

   Documentation is attached as a documentation string to name (as kind
function) and to the macro function.

   defmacro can be used to redefine a macro or to replace a function
definition with a macro definition.

   Recursive expansion of the form returned must terminate, including
the expansion of other macros which are subforms of other forms
returned.

   The consequences are undefined if the result of fully macroexpanding
a form contains any circular list structure except in literal objects.

   If a defmacro form appears as a top level form, the compiler must
store the macro definition at compile time, so that occurrences of the
macro later on in the file can be expanded correctly.  Users must ensure
that the body of the macro can be evaluated at compile time if it is
referenced within the file being compiled.

Examples::
..........

      (defmacro mac1 (a b) "Mac1 multiplies and adds"
                 `(+ ,a (* ,b 3))) =>  MAC1
      (mac1 4 5) =>  19
      (documentation 'mac1 'function) =>  "Mac1 multiplies and adds"
      (defmacro mac2 (&optional (a 2 b) (c 3 d) &rest x) `'(,a ,b ,c ,d ,x)) =>  MAC2
      (mac2 6) =>  (6 T 3 NIL NIL)
      (mac2 6 3 8) =>  (6 T 3 T (8))
      (defmacro mac3 (&whole r a &optional (b 3) &rest x &key c (d a))
         `'(,r ,a ,b ,c ,d ,x)) =>  MAC3
      (mac3 1 6 :d 8 :c 9 :d 10) =>  ((MAC3 1 6 :D 8 :C 9 :D 10) 1 6 9 8 (:D 8 :C 9 :D 10))

   The stipulation that an embedded destructuring lambda list is
permitted only where ordinary lambda list syntax would permit a
parameter name but not a list is made to prevent ambiguity.  For
example, the following is not valid:

      (defmacro loser (x &optional (a b &rest c) &rest z)
        ...)

   because ordinary lambda list syntax does permit a list following
&optional; the list (a b &rest c) would be interpreted as describing an
optional parameter named a whose default value is that of the form b,
with a supplied-p parameter named &rest (not valid), and an extraneous
symbol c in the list (also not valid).  An almost correct way to express
this is

      (defmacro loser (x &optional ((a b &rest c)) &rest z)
        ...)

   The extra set of parentheses removes the ambiguity.  However, the
definition is now incorrect because a macro call such as (loser (car
pool)) would not provide any argument form for the lambda list (a b
&rest c), and so the default value against which to match the lambda
list would be nil because no explicit default value was specified.  The
consequences of this are unspecified since the empty list, nil, does not
have forms to satisfy the parameters a and b.  The fully correct
definition would be either

      (defmacro loser (x &optional ((a b &rest c) '(nil nil)) &rest z)
        ...)

   or

      (defmacro loser (x &optional ((&optional a b &rest c)) &rest z)
        ...)

   These differ slightly: the first requires that if the macro call
specifies a explicitly then it must also specify b explicitly, whereas
the second does not have this requirement.  For example,

      (loser (car pool) ((+ x 1)))

   would be a valid call for the second definition but not for the
first.

      (defmacro dm1a (&whole x) `',x)
      (macroexpand '(dm1a))  =>  (QUOTE (DM1A))
      (macroexpand '(dm1a a)) is an error.

      (defmacro dm1b (&whole x a &optional b) `'(,x ,a ,b))
      (macroexpand '(dm1b))  is an error.
      (macroexpand '(dm1b q))  =>  (QUOTE ((DM1B Q) Q NIL))
      (macroexpand '(dm1b q r)) =>  (QUOTE ((DM1B Q R) Q R))
      (macroexpand '(dm1b q r s)) is an error.

      (defmacro dm2a (&whole form a b) `'(form ,form a ,a b ,b))
      (macroexpand '(dm2a x y)) =>  (QUOTE (FORM (DM2A X Y) A X B Y))
      (dm2a x y) =>  (FORM (DM2A X Y) A X B Y)

      (defmacro dm2b (&whole form a (&whole b (c . d) &optional (e 5))
                      &body f &environment env)
        ``(,',form ,,a ,',b ,',(macroexpand c env) ,',d ,',e ,',f))
      ;Note that because backquote is involved, implementations may differ
      ;slightly in the nature (though not the functionality) of the expansion.
      (macroexpand '(dm2b x1 (((incf x2) x3 x4)) x5 x6))
      =>  (LIST* '(DM2B X1 (((INCF X2) X3 X4))
                        X5 X6)
                 X1
                 '((((INCF X2) X3 X4)) (SETQ X2 (+ X2 1)) (X3 X4) 5 (X5 X6))),
          T
      (let ((x1 5))
        (macrolet ((segundo (x) `(cadr ,x)))
          (dm2b x1 (((segundo x2) x3 x4)) x5 x6)))
      =>  ((DM2B X1 (((SEGUNDO X2) X3 X4)) X5 X6)
           5 (((SEGUNDO X2) X3 X4)) (CADR X2) (X3 X4) 5 (X5 X6))

See Also::
..........

*note define-compiler-macro:: ,

   *note destructuring-bind:: , *note documentation:: , *note
macroexpand:: , *macroexpand-hook*, macrolet, *note macro-function:: ,
*note Evaluation::, *note Compilation::, *note Syntactic Interaction of
Documentation Strings and Declarations::


File: gcl.info,  Node: macro-function,  Next: macroexpand,  Prev: defmacro,  Up: Evaluation and Compilation Dictionary

3.8.11 macro-function [Accessor]
--------------------------------

'macro-function' symbol &optional environment => function

   (setf (' macro-function' symbol &optional environment) new-function)

Arguments and Values::
......................

symbol--a symbol.

   environment--an environment object.

   function--a macro function or nil.

   new-function--a macro function.

Description::
.............

Determines whether symbol has a function definition as a macro in the
specified environment.

   If so, the macro expansion function, a function of two arguments, is
returned.  If symbol has no function definition in the lexical
environment environment, or its definition is not a macro,
macro-function returns nil.

   It is possible for both macro-function and

   special-operator-p

   to return true of symbol.  The macro definition must be available for
use by programs that understand only the standard Common Lisp special
forms.

Examples::
..........

      (defmacro macfun (x) '(macro-function 'macfun)) =>  MACFUN
      (not (macro-function 'macfun)) =>  false

      (macrolet ((foo (&environment env)
                    (if (macro-function 'bar env)
                       ''yes
                       ''no)))
         (list (foo)
               (macrolet ((bar () :beep))
                  (foo))))

     =>  (NO YES)

Affected By::
.............

(setf macro-function), defmacro, and macrolet.

Exceptional Situations::
........................

The consequences are undefined if environment is non-nil in a use of
setf of macro-function.

See Also::
..........

*note defmacro:: , *note Evaluation::

Notes::
.......

setf can be used with macro-function to install a macro as a symbol's
global function definition:

      (setf (macro-function symbol) fn)

   The value installed must be a function that accepts two arguments,
the entire macro call and an environment, and computes the expansion for
that call.  Performing this operation causes symbol to have only that
macro definition as its global function definition; any previous
definition, whether as a macro or as a function, is lost.


File: gcl.info,  Node: macroexpand,  Next: define-symbol-macro,  Prev: macro-function,  Up: Evaluation and Compilation Dictionary

3.8.12 macroexpand, macroexpand-1 [Function]
--------------------------------------------

'macroexpand' form &optional env => expansion, expanded-p

   'macroexpand-' 1 => form &optional env expansion, expanded-p

Arguments and Values::
......................

form--a form.

   env--an environment object.  The default is nil.

   expansion--a form.

   expanded-p--a generalized boolean.

Description::
.............

macroexpand and macroexpand-1 expand macros.

   If form is a macro form, then macroexpand-1 expands the macro form
call once.

   macroexpand repeatedly expands form until it is no longer a macro
form.  In effect, macroexpand calls macroexpand-1 repeatedly until the
secondary value it returns is nil.

   If form is a macro form, then the expansion is a macro expansion and
expanded-p is true.  Otherwise, the expansion is the given form and
expanded-p is false.

   Macro expansion is carried out as follows.  Once macroexpand-1 has
determined that the form is a macro form, it obtains an appropriate
expansion function for the macro or symbol macro.  The value of
*macroexpand-hook* is

   coerced to a function and

   then called as a function of three arguments: the expansion function,
the form, and the env.  The value returned from this call is taken to be
the expansion of the form.

   In addition to macro definitions in the global environment, any local
macro definitions established within env by macrolet or symbol-macrolet
are considered.  If only form is supplied as an argument, then the
environment is effectively null, and only global macro definitions as
established by defmacro are considered.  Macro definitions are shadowed
by local function definitions.

Examples::
..........

      (defmacro alpha (x y) `(beta ,x ,y)) =>  ALPHA
      (defmacro beta (x y) `(gamma ,x ,y)) =>  BETA
      (defmacro delta (x y) `(gamma ,x ,y)) =>  EPSILON
      (defmacro expand (form &environment env)
        (multiple-value-bind (expansion expanded-p)
            (macroexpand form env)
          `(values ',expansion ',expanded-p))) =>  EXPAND
      (defmacro expand-1 (form &environment env)
        (multiple-value-bind (expansion expanded-p)
            (macroexpand-1 form env)
          `(values ',expansion ',expanded-p))) =>  EXPAND-1

     ;; Simple examples involving just the global environment
      (macroexpand-1 '(alpha a b)) =>  (BETA A B), true
      (expand-1 (alpha a b)) =>  (BETA A B), true
      (macroexpand '(alpha a b)) =>  (GAMMA A B), true
      (expand (alpha a b)) =>  (GAMMA A B), true
      (macroexpand-1 'not-a-macro) =>  NOT-A-MACRO, false
      (expand-1 not-a-macro) =>  NOT-A-MACRO, false
      (macroexpand '(not-a-macro a b)) =>  (NOT-A-MACRO A B), false
      (expand (not-a-macro a b)) =>  (NOT-A-MACRO A B), false

     ;; Examples involving lexical environments
      (macrolet ((alpha (x y) `(delta ,x ,y)))
        (macroexpand-1 '(alpha a b))) =>  (BETA A B), true
      (macrolet ((alpha (x y) `(delta ,x ,y)))
        (expand-1 (alpha a b))) =>  (DELTA A B), true
      (macrolet ((alpha (x y) `(delta ,x ,y)))
        (macroexpand '(alpha a b))) =>  (GAMMA A B), true
      (macrolet ((alpha (x y) `(delta ,x ,y)))
        (expand (alpha a b))) =>  (GAMMA A B), true
      (macrolet ((beta (x y) `(epsilon ,x ,y)))
        (expand (alpha a b))) =>  (EPSILON A B), true
      (let ((x (list 1 2 3)))
        (symbol-macrolet ((a (first x)))
          (expand a))) =>  (FIRST X), true
      (let ((x (list 1 2 3)))
        (symbol-macrolet ((a (first x)))
          (macroexpand 'a))) =>  A, false
      (symbol-macrolet ((b (alpha x y)))
        (expand-1 b)) =>  (ALPHA X Y), true
      (symbol-macrolet ((b (alpha x y)))
        (expand b)) =>  (GAMMA X Y), true
      (symbol-macrolet ((b (alpha x y))
                        (a b))
        (expand-1 a)) =>  B, true
      (symbol-macrolet ((b (alpha x y))
                        (a b))
        (expand a)) =>  (GAMMA X Y), true

     ;; Examples of shadowing behavior
      (flet ((beta (x y) (+ x y)))
        (expand (alpha a b))) =>  (BETA A B), true
      (macrolet ((alpha (x y) `(delta ,x ,y)))
        (flet ((alpha (x y) (+ x y)))
          (expand (alpha a b)))) =>  (ALPHA A B), false
      (let ((x (list 1 2 3)))
        (symbol-macrolet ((a (first x)))
          (let ((a x))
            (expand a)))) =>  A, false

Affected By::
.............

defmacro, setf of macro-function, macrolet, symbol-macrolet

See Also::
..........

*macroexpand-hook*, *note defmacro:: , *note setf:: of *note
macro-function:: , macrolet, *note symbol-macrolet:: , *note
Evaluation::

Notes::
.......

Neither macroexpand nor macroexpand-1 makes any explicit attempt to
expand macro forms that are either subforms of the form or subforms of
the expansion.  Such expansion might occur implicitly, however, due to
the semantics or implementation of the macro function.


File: gcl.info,  Node: define-symbol-macro,  Next: symbol-macrolet,  Prev: macroexpand,  Up: Evaluation and Compilation Dictionary

3.8.13 define-symbol-macro [Macro]
----------------------------------

'define-symbol-macro' symbol expansion
=> symbol

Arguments and Values::
......................

symbol--a symbol.

   expansion--a form.

Description::
.............

Provides a mechanism for globally affecting the macro expansion of the
indicated symbol.

   Globally establishes an expansion function for the symbol macro named
by symbol.  The only guaranteed property of an expansion function for a
symbol macro is that when it is applied to the form and the environment
it returns the correct expansion.  (In particular, it is
implementation-dependent whether the expansion is conceptually stored in
the expansion function, the environment, or both.)

   Each global reference to symbol (i.e., not shadowed_2 by a binding
for a variable or symbol macro named by the same symbol) is expanded by
the normal macro expansion process; see *note Symbols as Forms::.  The
expansion of a symbol macro is subject to further macro expansion in the
same lexical environment as the symbol macro reference, exactly
analogous to normal macros.

   The consequences are unspecified if a special declaration is made for
symbol while in the scope of this definition (i.e., when it is not
shadowed_2 by a binding for a variable or symbol macro named by the same
symbol).

   Any use of setq to set the value of the symbol while in the scope of
this definition is treated as if it were a setf.  psetq of symbol is
treated as if it were a psetf, and multiple-value-setq is treated as if
it were a setf of values.

   A binding for a symbol macro can be shadowed_2 by let or
symbol-macrolet.

Examples::
..........

     (defvar *things* (list 'alpha 'beta 'gamma)) =>  *THINGS*

     (define-symbol-macro thing1 (first *things*)) =>  THING1
     (define-symbol-macro thing2 (second *things*)) =>  THING2
     (define-symbol-macro thing3 (third *things*)) =>  THING3

     thing1 =>  ALPHA
     (setq thing1 'ONE) =>  ONE
     *things* =>  (ONE BETA GAMMA)
     (multiple-value-setq (thing2 thing3) (values 'two 'three)) =>  TWO
     thing3 =>  THREE
     *things* =>  (ONE TWO THREE)

     (list thing2 (let ((thing2 2)) thing2)) =>  (TWO 2)

Exceptional Situations::
........................

If symbol is already defined as a global variable, an error of type
program-error is signaled.

See Also::
..........

*note symbol-macrolet:: , *note macroexpand::


File: gcl.info,  Node: symbol-macrolet,  Next: *macroexpand-hook*,  Prev: define-symbol-macro,  Up: Evaluation and Compilation Dictionary

3.8.14 symbol-macrolet [Special Operator]
-----------------------------------------

'symbol-macrolet' ({(symbol expansion )}*) {declaration}* {form}*
=> {result}*

Arguments and Values::
......................

symbol--a symbol.

   expansion--a form.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values returned by the forms.

Description::
.............

symbol-macrolet provides a mechanism for affecting the macro expansion
environment for symbols.

   symbol-macrolet lexically establishes expansion functions for each of
the symbol macros named by symbols.

   The only guaranteed property of an expansion function for a symbol
macro is that when it is applied to the form and the environment it
returns the correct expansion.  (In particular, it is
implementation-dependent whether the expansion is conceptually stored in
the expansion function, the environment, or both.)

   Each reference to symbol as a variable within the lexical scope of
symbol-macrolet is expanded by the normal macro expansion process; see
*note Symbols as Forms::.  The expansion of a symbol macro is subject to
further macro expansion in the same lexical environment as the symbol
macro invocation, exactly analogous to normal macros.

   Exactly the same declarations are allowed as for let with one
exception: symbol-macrolet signals an error if a special declaration
names one of the symbols being defined by symbol-macrolet.

   When the forms of the symbol-macrolet form are expanded, any use of
setq to set the value of one of the specified variables is treated as if
it were a setf.  psetq of a symbol defined as a symbol macro is treated
as if it were a psetf, and multiple-value-setq is treated as if it were
a setf of values.

   The use of symbol-macrolet can be shadowed by let.  In other words,
symbol-macrolet only substitutes for occurrences of symbol that would be
in the scope of a lexical binding of symbol surrounding the forms.

Examples::
..........

     ;;; The following is equivalent to
     ;;;   (list 'foo (let ((x 'bar)) x)),
     ;;; not
     ;;;   (list 'foo (let (('foo 'bar)) 'foo))
      (symbol-macrolet ((x 'foo))
        (list x (let ((x 'bar)) x)))
     =>  (foo bar)
     NOT=> (foo foo)

      (symbol-macrolet ((x '(foo x)))
        (list x))
     =>  ((FOO X))

Exceptional Situations::
........................

If an attempt is made to bind a symbol that is defined as a global
variable, an error of type program-error is signaled.

   If declaration contains a special declaration that names one of the
symbols being bound by symbol-macrolet, an error of type program-error
is signaled.

See Also::
..........

*note with-slots:: , *note macroexpand::

Notes::
.......

The special form symbol-macrolet is the basic mechanism that is used to
implement with-slots.

   If a symbol-macrolet form is a top level form, the forms are also
processed as top level forms.  See *note File Compilation::.


File: gcl.info,  Node: *macroexpand-hook*,  Next: proclaim,  Prev: symbol-macrolet,  Up: Evaluation and Compilation Dictionary

3.8.15 *macroexpand-hook* [Variable]
------------------------------------

Value Type::
............

a designator for a function of three arguments: a macro function, a
macro form, and an environment object.

Initial Value::
...............

a designator for a function that is equivalent to the function funcall,
but that might have additional implementation-dependent side-effects.

Description::
.............

Used as the expansion interface hook by macroexpand-1 to control the
macro expansion process.  When a macro form is to be expanded, this
function is called with three arguments: the macro function, the macro
form, and the environment in which the macro form is to be expanded.

   The environment object has dynamic extent; the consequences are
undefined if the environment object is referred to outside the dynamic
extent of the macro expansion function.

Examples::
..........

      (defun hook (expander form env)
         (format t "Now expanding: ~S~
         (funcall expander form env)) =>  HOOK
      (defmacro machook (x y) `(/ (+ ,x ,y) 2)) =>  MACHOOK
      (macroexpand '(machook 1 2)) =>  (/ (+ 1 2) 2), true
      (let ((*macroexpand-hook* #'hook)) (macroexpand '(machook 1 2)))
      |>  Now expanding (MACHOOK 1 2)
     =>  (/ (+ 1 2) 2), true

See Also::
..........

*note macroexpand:: , macroexpand-1, *note funcall:: , *note
Evaluation::

Notes::
.......

The net effect of the chosen initial value is to just invoke the macro
function, giving it the macro form and environment as its two arguments.

   Users or user programs can assign this variable to customize or trace
the macro expansion mechanism.  Note, however, that this variable is a
global resource, potentially shared by multiple programs; as such, if
any two programs depend for their correctness on the setting of this
variable, those programs may not be able to run in the same Lisp image.
For this reason, it is frequently best to confine its uses to debugging
situations.

   Users who put their own function into *macroexpand-hook* should
consider saving the previous value of the hook, and calling that value
from their own.


File: gcl.info,  Node: proclaim,  Next: declaim,  Prev: *macroexpand-hook*,  Up: Evaluation and Compilation Dictionary

3.8.16 proclaim [Function]
--------------------------

'proclaim' declaration-specifier => implementation-dependent

Arguments and Values::
......................

declaration-specifier--a declaration specifier.

Description::
.............

Establishes the declaration specified by declaration-specifier in the
global environment.

   Such a declaration, sometimes called a global declaration or a
proclamation, is always in force unless locally shadowed.

   Names of variables and functions within declaration-specifier refer
to dynamic variables and global function definitions, respectively.

   Figure 3-22 shows a list of declaration identifiers that can be used
with proclaim.

  declaration  inline     optimize  type  
  ftype        notinline  special         

  Figure 3-22: Global Declaration Specifiers


   An implementation is free to support other (implementation-defined)
declaration identifiers as well.

Examples::
..........

      (defun declare-variable-types-globally (type vars)
        (proclaim `(type ,type ,@vars))
        type)

      ;; Once this form is executed, the dynamic variable *TOLERANCE*
      ;; must always contain a float.
      (declare-variable-types-globally 'float '(*tolerance*))
     =>  FLOAT

See Also::
..........

*note declaim:: , declare, *note Compilation::

Notes::
.......

Although the execution of a proclaim form has effects that might affect
compilation, the compiler does not make any attempt to recognize and
specially process proclaim forms.  A proclamation such as the following,
even if a top level form, does not have any effect until it is executed:

     (proclaim '(special *x*))

   If compile time side effects are desired, eval-when may be useful.
For example:

      (eval-when (:execute :compile-toplevel :load-toplevel)
        (proclaim '(special *x*)))

   In most such cases, however, it is preferrable to use declaim for
this purpose.

   Since proclaim forms are ordinary function forms, macro forms can
expand into them.


File: gcl.info,  Node: declaim,  Next: declare,  Prev: proclaim,  Up: Evaluation and Compilation Dictionary

3.8.17 declaim [Macro]
----------------------

'declaim' {declaration-specifier}* => implementation-dependent

Arguments and Values::
......................

declaration-specifier--a declaration specifier; not evaluated.

Description::
.............

Establishes the declarations specified by the declaration-specifiers.

   If a use of this macro appears as a top level form 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 declaim persist after the file
has been compiled.

Examples::
..........

See Also::
..........

declare, *note proclaim::


File: gcl.info,  Node: declare,  Next: ignore,  Prev: declaim,  Up: Evaluation and Compilation Dictionary

3.8.18 declare [Symbol]
-----------------------

Syntax::
........

'declare' {declaration-specifier}*

Arguments::
...........

declaration-specifier--a declaration specifier; not evaluated.

Description::
.............

A declare expression, sometimes called a declaration, can occur only at
the beginning of the bodies of certain forms; that is, it may be
preceded only by other declare expressions, or by a documentation string
if the context permits.

   A declare expression can occur in a lambda expression or in any of
the forms listed in Figure 3-23.

  defgeneric                 do-external-symbols   prog                      
  define-compiler-macro      do-symbols            prog*                     
  define-method-combination  dolist                restart-case              
  define-setf-expander       dotimes               symbol-macrolet           
  defmacro                   flet                  with-accessors            
  defmethod                  handler-case          with-hash-table-iterator  
  defsetf                    labels                with-input-from-string    
  deftype                    let                   with-open-file            
  defun                      let*                  with-open-stream          
  destructuring-bind         locally               with-output-to-string     
  do                         macrolet              with-package-iterator     
  do*                        multiple-value-bind   with-slots                
  do-all-symbols             pprint-logical-block                            

       Figure 3-23: Standardized Forms In Which Declarations Can Occur      


   A declare expression can only occur where specified by the syntax of
these forms.  The consequences of attempting to evaluate a declare
expression are undefined.  In situations where such expressions can
appear, explicit checks are made for their presence and they are never
actually evaluated; it is for this reason that they are called "declare
expressions" rather than "declare forms."

   Macro forms cannot expand into declarations; declare expressions must
appear as actual subexpressions of the form to which they refer.

   Figure 3-24 shows a list of declaration identifiers that can be used
with declare.

  dynamic-extent  ignore     optimize  
  ftype           inline     special   
  ignorable       notinline  type      

  Figure 3-24: Local Declaration Specifiers


   An implementation is free to support other (implementation-defined)
declaration identifiers as well.

Examples::
..........

      (defun nonsense (k x z)
        (foo z x)                     ;First call to foo
        (let ((j (foo k x))           ;Second call to foo
              (x (* k k)))
          (declare (inline foo) (special x z))
          (foo x j z)))               ;Third call to foo

   In this example, the inline declaration applies only to the third
call to foo, but not to the first or second ones.  The special
declaration of x causes let to make a dynamic binding for x, and causes
the reference to x in the body of let to be a dynamic reference.  The
reference to x in the second call to foo is a local reference to the
second parameter of nonsense.  The reference to x in the first call to
foo is a local reference, not a special one.  The special declaration of
z causes the reference to z in the third call to foo to be a dynamic
reference; it does not refer to the parameter to nonsense named z,
because that parameter binding has not been declared to be special.
(The special declaration of z does not appear in the body of defun, but
in an inner form, and therefore does not affect the binding of the
parameter.)

Exceptional Situations::
........................

The consequences of trying to use a declare expression as a form to be
evaluated are undefined.

   [Editorial Note by KMP: Probably we need to say something here about
ill-formed declare expressions.]

See Also::
..........

*note proclaim:: , *note Type Specifiers::, declaration, dynamic-extent,
ftype, ignorable, ignore, inline, notinline, optimize, type


File: gcl.info,  Node: ignore,  Next: dynamic-extent,  Prev: declare,  Up: Evaluation and Compilation Dictionary

3.8.19 ignore, ignorable [Declaration]
--------------------------------------

Syntax::
........

(ignore {var | (function fn)}*)

   (ignorable {var | (function fn)}*)

Arguments::
...........

var--a variable name.

   fn--a function name.

Valid Context::
...............

declaration

Binding Types Affected::
........................

variable, function

Description::
.............

The ignore and ignorable declarations refer to for-value references to
variable bindings for the vars and to function bindings for the fns.

   An ignore declaration specifies that for-value references to the
indicated bindings will not occur within the scope of the declaration.
Within the scope of such a declaration, it is desirable for a compiler
to issue a warning about the presence of either a for-value reference to
any var or fn, or a special declaration for any var.

   An ignorable declaration specifies that for-value references to the
indicated bindings might or might not occur within the scope of the
declaration.  Within the scope of such a declaration, it is not
desirable for a compiler to issue a warning about the presence or
absence of either a for-value reference to any var or fn, or a special
declaration for any var.

   When not within the scope of a ignore or ignorable declaration, it is
desirable for a compiler to issue a warning about any var for which
there is neither a for-value reference nor a special declaration, or
about any fn for which there is no for-value reference.

   Any warning about a "used" or "unused" binding must be of type
style-warning, and may not affect program semantics.

   The stream variables established by with-open-file, with-open-stream,
with-input-from-string, and with-output-to-string, and all iteration
variables are, by definition, always "used".  Using (declare (ignore
v)), for such a variable v has unspecified consequences.

See Also::
..........

declare


File: gcl.info,  Node: dynamic-extent,  Next: type,  Prev: ignore,  Up: Evaluation and Compilation Dictionary

3.8.20 dynamic-extent [Declaration]
-----------------------------------

Syntax::
........

(dynamic-extent [[{var}* | (function fn)*]])

Arguments::
...........

var--a variable name.

   fn--a function name.

Valid Context::
...............

declaration

Binding Types Affected::
........................

variable, function

Description::
.............

In some containing form, F, this declaration asserts for each var_i
(which need not be bound by F), and for each value v_{ij} that var_i
takes on, and for each object x_{ijk} that is an otherwise inaccessible
part of v_{ij} at any time when v_{ij} becomes the value of var_i, that
just after the execution of F terminates, x_{ijk} is either inaccessible
(if F established a binding for var_i) or still an otherwise
inaccessible part of the current value of var_i (if F did not establish
a binding for var_i).

   The same relation holds for each fn_i, except that the bindings are
in the function namespace.

   The compiler is permitted to use this information in any way that is
appropriate to the implementation and that does not conflict with the
semantics of Common Lisp.

   dynamic-extent declarations can be free declarations or bound
declarations.

   The vars and fns named in a dynamic-extent declaration must not refer
to symbol macro or macro bindings.

Examples::
..........

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 make a dynamic-extent declaration for variables
which have no lexically apparent initial value.  For example, it is
probably useful to write:

      (defun f ()
        (let ((x (list 1 2 3)))
          (declare (dynamic-extent x))
              ...))

   This would permit those compilers that wish to do so to stack
allocate the list held by the local variable x.  It is permissible, but
in practice probably not as useful, to write:

      (defun g (x) (declare (dynamic-extent x)) ...)
      (defun f () (g (list 1 2 3)))

   Most compilers would probably not stack allocate the argument to g in
f because it would be a modularity violation for the compiler to assume
facts about g from within f.  Only an implementation that was willing to
be responsible for recompiling f if the definition of g changed
incompatibly could legitimately stack allocate the list argument to g in
f.

   Here is another example:

      (declaim (inline g))
      (defun g (x) (declare (dynamic-extent x)) ...)
      (defun f () (g (list 1 2 3)))

      (defun f ()
        (flet ((g (x) (declare (dynamic-extent x)) ...))
          (g (list 1 2 3))))


   In the previous example, some compilers might determine that
optimization was possible and others might not.

   A variant of this is the so-called "stack allocated rest list" that
can be achieved (in implementations supporting the optimization) by:

      (defun f (&rest x)
        (declare (dynamic-extent x))
        ...)

   Note that although the initial value of x is not explicit, the f
function is responsible for assembling the list x from the passed
arguments, so the f function can be optimized by the compiler to
construct a stack-allocated list instead of a heap-allocated list in
implementations that support such.

   In the following example,

      (let ((x (list 'a1 'b1 'c1))
            (y (cons 'a2 (cons 'b2 (cons 'c2 nil)))))
        (declare (dynamic-extent x y))
        ...)

   The otherwise inaccessible parts of x are three conses, and the
otherwise inaccessible parts of y are three other conses.  None of the
symbols a1, b1, c1, a2, b2, c2, or nil is an otherwise inaccessible part
of x or y because each is interned and hence accessible by the package
(or packages) in which it is interned.  However, if a freshly allocated
uninterned symbol had been used, it would have been an otherwise
inaccessible part of the list which contained it.

     ;; In this example, the implementation is permitted to stack allocate
     ;; the list that is bound to X.
      (let ((x (list 1 2 3)))
        (declare (dynamic-extent x))
        (print x)
        :done)
      |>  (1 2 3)
     =>  :DONE

     ;; In this example, the list to be bound to L can be stack-allocated.
      (defun zap (x y z)
        (do ((l (list x y z) (cdr l)))
            ((null l))
          (declare (dynamic-extent l))
          (prin1 (car l)))) =>  ZAP
      (zap 1 2 3)
      |>  123
     =>  NIL

     ;; Some implementations might open-code LIST-ALL-PACKAGES in a way
     ;; that permits using stack allocation of the list to be bound to L.
      (do ((l (list-all-packages) (cdr l)))
          ((null l))
        (declare (dynamic-extent l))
        (let ((name (package-name (car l))))
          (when (string-search "COMMON-LISP" name) (print name))))
      |>  "COMMON-LISP"
      |>  "COMMON-LISP-USER"
     =>  NIL

     ;; Some implementations might have the ability to stack allocate
     ;; rest lists.  A declaration such as the following should be a cue
     ;; to such implementations that stack-allocation of the rest list
     ;; would be desirable.
      (defun add (&rest x)
        (declare (dynamic-extent x))
        (apply #'+ x)) =>  ADD
      (add 1 2 3) =>  6

      (defun zap (n m)
        ;; Computes (RANDOM (+ M 1)) at relative speed of roughly O(N).
        ;; It may be slow, but with a good compiler at least it
        ;; doesn't waste much heap storage.  :-}
        (let ((a (make-array n)))
          (declare (dynamic-extent a))
          (dotimes (i n)
            (declare (dynamic-extent i))
            (setf (aref a i) (random (+ i 1))))
          (aref a m))) =>  ZAP
      (< (zap 5 3) 3) =>  true

   The following are in error, since the value of x is used outside of
its extent:

      (length (list (let ((x (list 1 2 3)))  ; Invalid
                     (declare (dynamic-extent x))
                     x)))

      (progn (let ((x (list 1 2 3)))  ; Invalid
               (declare (dynamic-extent x))
               x)
             nil)

See Also::
..........

declare

Notes::
.......

The most common optimization is to stack allocate the initial value of
the objects named by the vars.

   It is permissible for an implementation to simply ignore this
declaration.


File: gcl.info,  Node: type,  Next: inline,  Prev: dynamic-extent,  Up: Evaluation and Compilation Dictionary

3.8.21 type [Declaration]
-------------------------

Syntax::
........

(type typespec {var}*)

   (typespec {var}*)

Arguments::
...........

typespec--a type specifier.

   var--a variable name.

Valid Context::
...............

declaration or proclamation

Binding Types Affected::
........................

variable

Description::
.............

Affects only variable bindings and specifies that the vars take on
values only of the specified typespec.  In particular, values assigned
to the variables by setq, as well as the initial values of the vars must
be of the specified typespec.  type declarations never apply to function
bindings (see ftype).

   A type declaration of a symbol defined by symbol-macrolet is
equivalent to wrapping a the expression around the expansion of that
symbol,

   although the symbol's macro expansion is not actually affected.

   The meaning of a type declaration is equivalent to changing each
reference to a variable (var) within the scope of the declaration to
(the typespec var), changing each expression assigned to the variable
(new-value) within the scope of the declaration to (the typespec
new-value), and executing (the typespec var) at the moment the scope of
the declaration is entered.

   A type declaration is valid in all declarations.  The interpretation
of a type declaration is as follows:

1.
     During the execution of any reference to the declared variable
     within the scope of the declaration, the consequences are undefined
     if the value of the declared variable is not of the declared type.

2.
     During the execution of any setq of the declared variable within
     the scope of the declaration, the consequences are undefined if the
     newly assigned value of the declared variable is not of the
     declared type.

3.
     At the moment the scope of the declaration is entered, the
     consequences are undefined if the value of the declared variable is
     not of the declared type.

   A type declaration affects only variable references within its scope.

   If nested type declarations refer to the same variable, then the
value of the variable must be a member of the intersection of the
declared types.

   If there is a local type declaration for a dynamic variable, and
there is also a global type 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.

   type declarations can be free declarations or bound declarations.

   A symbol cannot be both the name of a type and the name of a
declaration.  Defining a symbol as the name of a class, structure,
condition, or type, when the symbol has been declared as a declaration
name, or vice versa, signals an error.

   Within the lexical scope of an array type declaration, all references
to array elements are assumed to satisfy the expressed array element
type (as opposed to the upgraded array element type).  A compiler can
treat the code within the scope of the array type declaration as if each
access of an array element were surrounded by an appropriate the form.

Examples::
..........

      (defun f (x y)
        (declare (type fixnum x y))
        (let ((z (+ x y)))
          (declare (type fixnum z))
          z)) =>  F
      (f 1 2) =>  3
      ;; The previous definition of F is equivalent to
      (defun f (x y)
        ;; This declaration is a shorthand form of the TYPE declaration
        (declare (fixnum x y))
        ;; To declare the type of a return value, it's not necessary to
        ;; create a named variable.  A THE special form can be used instead.
        (the fixnum (+ x y))) =>  F
      (f 1 2) =>  3

      (defvar *one-array* (make-array 10 :element-type '(signed-byte 5)))
      (defvar *another-array* (make-array 10 :element-type '(signed-byte 8)))

      (defun frob (an-array)
        (declare (type (array (signed-byte 5) 1) an-array))
        (setf (aref an-array 1) 31)
        (setf (aref an-array 2) 127)
        (setf (aref an-array 3) (* 2 (aref an-array 3)))
        (let ((foo 0))
          (declare (type (signed-byte 5) foo))
          (setf foo (aref an-array 0))))

      (frob *one-array*)
      (frob *another-array*)

   The above definition of frob is equivalent to:

      (defun frob (an-array)
        (setf (the (signed-byte 5) (aref an-array 1)) 31)
        (setf (the (signed-byte 5) (aref an-array 2)) 127)
        (setf (the (signed-byte 5) (aref an-array 3))
              (* 2 (the (signed-byte 5) (aref an-array 3))))
        (let ((foo 0))
          (declare (type (signed-byte 5) foo))
          (setf foo (the (signed-byte 5) (aref an-array 0)))))

   Given an implementation in which fixnums are 29 bits but fixnum
arrays are upgraded to signed 32-bit arrays, the following could be
compiled with all fixnum arithmetic:

      (defun bump-counters (counters)
        (declare (type (array fixnum *) bump-counters))
        (dotimes (i (length counters))
          (incf (aref counters i))))

See Also::
..........

declare, *note declaim:: , *note proclaim::

Notes::
.......

(typespec {var}*) is an abbreviation for (type typespec {var}*).

   A type declaration for the arguments to a function does not
necessarily imply anything about the type of the result.  The following
function is not permitted to be compiled using implementation-dependent
fixnum-only arithmetic:

      (defun f (x y) (declare (fixnum x y)) (+ x y))

   To see why, consider (f most-positive-fixnum 1).  Common Lisp defines
that F must return a bignum here, rather than signal an error or produce
a mathematically incorrect result.  If you have special knowledge such
"fixnum overflow" cases will not come up, you can declare the result
value to be in the fixnum range, enabling some compilers to use more
efficient arithmetic:

      (defun f (x y)
        (declare (fixnum x y))
        (the fixnum (+ x y)))

   Note, however, that in the three-argument case, because of the
possibility of an implicit intermediate value growing too large, the
following will not cause implementation-dependent fixnum-only arithmetic
to be used:

      (defun f (x y)
        (declare (fixnum x y z))
        (the fixnum (+ x y z)))

   To see why, consider (f most-positive-fixnum 1 -1). Although the
arguments and the result are all fixnums, an intermediate value is not a
fixnum.  If it is important that implementation-dependent fixnum-only
arithmetic be selected in implementations that provide it, consider
writing something like this instead:

      (defun f (x y)
        (declare (fixnum x y z))
        (the fixnum (+ (the fixnum (+ x y)) z)))


File: gcl.info,  Node: inline,  Next: ftype,  Prev: type,  Up: Evaluation and Compilation Dictionary

3.8.22 inline, notinline [Declaration]
--------------------------------------

Syntax::
........

(inline {function-name}*)

   (notinline {function-name}*)

Arguments::
...........

function-name--a function name.

Valid Context::
...............

declaration or proclamation

Binding Types Affected::
........................

function

Description::
.............

inline specifies that it is desirable for the compiler to produce inline
calls to the functions named by function-names; that is, the code for a
specified function-name

   should be integrated into the calling routine, appearing "in line" in
place of a procedure call.  A compiler is free to ignore this
declaration.  inline declarations never apply to variable bindings.

   If one of the functions mentioned has a lexically apparent local
definition (as made by flet or labels), then the declaration applies to
that local definition and not to the global function definition.

   While no conforming implementation is required to perform inline
expansion of user-defined functions, those implementations that do
attempt to recognize the following paradigm:

   To define a function f that is not inline by default but for which
(declare (inline f)) will make f be locally inlined, the proper
definition sequence is:

      (declaim (inline f))
      (defun f ...)
      (declaim (notinline f))

   The inline proclamation preceding the defun form ensures that the
compiler has the opportunity save the information necessary for inline
expansion, and the notinline proclamation following the defun form
prevents f from being expanded inline everywhere.

   notinline specifies that it is

   undesirable to compile the functions named by function-names in-line.
A compiler is not free to ignore this declaration; calls to the
specified functions must be implemented as out-of-line subroutine calls.

   If one of the functions mentioned has a lexically apparent local
definition (as made by flet or labels), then the declaration applies to
that local definition and not to the global function definition.

   In the presence of a compiler macro definition for function-name, a
notinline declaration prevents that

   compiler macro from being used.

   An inline declaration may be used to encourage use of compiler macro
definitions.  inline and notinline declarations otherwise have no effect
when the lexically visible definition of function-name is a macro
definition.

   inline and notinline declarations can be free declarations or bound
declarations.  inline and notinline declarations of functions that
appear before the body of a flet or labels

   form that defines that function are bound declarations.  Such
declarations in other contexts are free declarations.

Examples::
..........

      ;; The globally defined function DISPATCH should be open-coded,
      ;; if the implementation supports inlining, unless a NOTINLINE
      ;; declaration overrides this effect.
      (declaim (inline dispatch))
      (defun dispatch (x) (funcall (get (car x) 'dispatch) x))
      ;; Here is an example where inlining would be encouraged.
      (defun top-level-1 () (dispatch (read-command)))
      ;; Here is an example where inlining would be prohibited.
      (defun top-level-2 ()
        (declare (notinline dispatch))
        (dispatch (read-command)))
      ;; Here is an example where inlining would be prohibited.
      (declaim (notinline dispatch))
      (defun top-level-3 () (dispatch (read-command)))
      ;; Here is an example where inlining would be encouraged.
      (defun top-level-4 ()
        (declare (inline dispatch))
        (dispatch (read-command)))

See Also::
..........

declare, *note declaim:: , *note proclaim::


File: gcl.info,  Node: ftype,  Next: declaration,  Prev: inline,  Up: Evaluation and Compilation Dictionary

3.8.23 ftype [Declaration]
--------------------------

Syntax::
........

(ftype type {function-name}*)

Arguments::
...........

function-name--a function name.

   type--a type specifier.

Valid Context::
...............

declaration or proclamation

Binding Types Affected::
........................

function

Description::
.............

Specifies that the functions named by function-names are of the
functional type type.  For example:

      (declare (ftype (function (integer list) t) ith)
               (ftype (function (number) float) sine cosine))

   If one of the functions mentioned has a lexically apparent local
definition (as made by flet or labels), then the declaration applies to
that local definition and not to the global function definition.  ftype
declarations never apply to variable bindings (see type).

   The lexically apparent bindings of function-names must not be macro
definitions.  (This is because ftype declares the functional definition
of each function name to be of a particular subtype of function, and
macros do not denote functions.)

   ftype

   declarations can be free declarations or bound declarations.  ftype
declarations of functions that appear before the body of a flet or
labels

   form that defines that function are bound declarations.  Such
declarations in other contexts are free declarations.

See Also::
..........

declare, *note declaim:: , *note proclaim::


File: gcl.info,  Node: declaration,  Next: optimize,  Prev: ftype,  Up: Evaluation and Compilation Dictionary

3.8.24 declaration [Declaration]
--------------------------------

Syntax::
........

(declaration {name}*)

Arguments::
...........

name--a symbol.

Valid Context::
...............

proclamation only

Description::
.............

Advises the compiler that each name is a valid but potentially
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.

Examples::
..........

      (declaim (declaration author target-language target-machine))
      (declaim (target-language ada))
      (declaim (target-machine IBM-650))
      (defun strangep (x)
        (declare (author "Harry Tweeker"))
        (member x '(strange weird odd peculiar)))

See Also::
..........

*note declaim:: , *note proclaim::


File: gcl.info,  Node: optimize,  Next: special,  Prev: declaration,  Up: Evaluation and Compilation Dictionary

3.8.25 optimize [Declaration]
-----------------------------

Syntax::
........

(optimize {quality | (quality value)}*)

Arguments::
...........

quality--an optimize quality.

   value--one of the integers 0, 1, 2, or 3.

Valid Context::
...............

declaration or proclamation

Description::
.............

Advises the compiler that each quality should be given attention
according to the specified corresponding value.  Each quality must be a
symbol naming an optimize quality; the names and meanings of the
standard optimize qualities are shown in Figure 3-25.

  Name               Meaning                            
  compilation-speed  speed of the compilation process   
  debug              ease of debugging                  
  safety             run-time error checking            
  space              both code size and run-time space  
  speed              speed of the object code           

             Figure 3-25: Optimize qualities           


   There may be other, implementation-defined optimize qualities.

   A value 0 means that the corresponding quality is totally
unimportant, and 3 that the quality is extremely important; 1 and 2 are
intermediate values, with 1 the neutral value.  (quality 3) can be
abbreviated to quality.

   Note that code which has the optimization (safety 3), or just safety,
is called safe code.

   The consequences are unspecified if a quality appears more than once
with different values.

Examples::
..........

      (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))
          ;; This inner loop really needs to burn.
          (declare (optimize speed))
          (declare (fixnum i))
          ))

See Also::
..........

declare, *note declaim:: , *note proclaim:: , *note Declaration Scope::

Notes::
.......

An optimize declaration never applies to either a variable or a function
binding.  An optimize declaration can only be a free declaration.  For
more information, see *note Declaration Scope::.


File: gcl.info,  Node: special,  Next: locally,  Prev: optimize,  Up: Evaluation and Compilation Dictionary

3.8.26 special [Declaration]
----------------------------

Syntax::
........

(special {var}*)

Arguments::
...........

var--a symbol.

Valid Context::
...............

declaration or proclamation

Binding Types Affected::
........................

variable

Description::
.............

Specifies that all of the vars named are dynamic.  This specifier
affects variable bindings and affects references.  All variable bindings
affected are made to be dynamic bindings, and affected variable
references refer to the current dynamic binding.  For example:

      (defun hack (thing *mod*)    ;The binding of the parameter
        (declare (special *mod*))  ; *mod* is visible to hack1,
        (hack1 (car thing)))       ; but not that of thing.
      (defun hack1 (arg)
        (declare (special *mod*))  ;Declare references to *mod*
                                   ;within hack1 to be special.
        (if (atom arg) *mod*
            (cons (hack1 (car arg)) (hack1 (cdr arg)))))

   A special declaration does not affect inner bindings of a var; the
inner bindings implicitly shadow a special declaration and must be
explicitly re-declared to be special.  special declarations never apply
to function bindings.

   special declarations can be either bound declarations, affecting both
a binding and references, or free declarations, affecting only
references, depending on whether the declaration is attached to a
variable binding.

   When used in a proclamation, a special declaration specifier applies
to all bindings as well as to all references of the mentioned variables.
For example, after

      (declaim (special x))

   then in a function definition such as

      (defun example (x) ...)

   the parameter x is bound as a dynamic variable rather than as a
lexical variable.

Examples::
..........

     (defun declare-eg (y)                 ;this y is special
      (declare (special y))
      (let ((y t))                         ;this y is lexical
           (list y
                 (locally (declare (special y)) y)))) ;this y refers to the
                                                      ;special binding of y
     =>  DECLARE-EG
      (declare-eg nil) =>  (T NIL)

     (setf (symbol-value 'x) 6)
     (defun foo (x)                         ;a lexical binding of x
       (print x)
       (let ((x (1+ x)))                    ;a special binding of x
         (declare (special x))              ;and a lexical reference
         (bar))
       (1+ x))
     (defun bar ()
       (print (locally (declare (special x))
                x)))
     (foo 10)
      |>  10
      |>  11
     =>  11

     (setf (symbol-value 'x) 6)
     (defun bar (x y)            ;[1] 1st occurrence of x
       (let ((old-x x)           ;[2] 2nd occurrence of x -- same as 1st occurrence
             (x y))              ;[3] 3rd occurrence of x
         (declare (special x))
         (list old-x x)))
     (bar 'first 'second) =>  (FIRST SECOND)

      (defun few (x &optional (y *foo*))
        (declare (special *foo*))
        ...)

   The reference to *foo* in the first line of this example is not
special even though there is a special declaration in the second line.

      (declaim (special prosp)) =>  implementation-dependent
      (setq prosp 1 reg 1) =>  1
      (let ((prosp 2) (reg 2))         ;the binding of prosp is special
         (set 'prosp 3) (set 'reg 3)   ;due to the preceding proclamation,
         (list prosp reg))             ;whereas the variable reg is lexical
     =>  (3 2)
      (list prosp reg) =>  (1 3)

      (declaim (special x))          ;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)))) =>  EXAMPLE

   In the contorted code above, the outermost and innermost bindings of
y are dynamic, but the middle binding is lexical.  The two arguments to
+ are different, one being the value, which is 3, of the lexical
variable y, and the other being the value of the dynamic variable named
y (a binding of which happens, coincidentally, to lexically surround it
at an outer level).  All the bindings of x and references to x are
dynamic, however, because of the proclamation that x is always special.

See Also::
..........

*note defparameter:: , defvar


File: gcl.info,  Node: locally,  Next: the,  Prev: special,  Up: Evaluation and Compilation Dictionary

3.8.27 locally [Special Operator]
---------------------------------

'locally' {declaration}* {form}* => {result}*

Arguments and Values::
......................

Declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values of the forms.

Description::
.............

Sequentially evaluates a body of forms in a lexical environment where
the given declarations have effect.

Examples::
..........

      (defun sample-function (y)  ;this y is regarded as special
        (declare (special y))
        (let ((y t))              ;this y is regarded as lexical
          (list y
                (locally (declare (special y))
                  ;; this next y is regarded as special
                  y))))
     =>  SAMPLE-FUNCTION
      (sample-function nil) =>  (T NIL)
      (setq x '(1 2 3) y '(4 . 5)) =>  (4 . 5)

     ;;; The following declarations are not notably useful in specific.
     ;;; They just offer a sample of valid declaration syntax using LOCALLY.
      (locally (declare (inline floor) (notinline car cdr))
               (declare (optimize space))
         (floor (car x) (cdr y))) =>  0, 1

     ;;; This example shows a definition of a function that has a particular set
     ;;; of OPTIMIZE settings made locally to that definition.
      (locally (declare (optimize (safety 3) (space 3) (speed 0)))
        (defun frob (w x y &optional (z (foo x y)))
          (mumble x y z w)))
     =>  FROB

     ;;; This is like the previous example, except that the optimize settings
     ;;; remain in effect for subsequent definitions in the same compilation unit.
      (declaim (optimize (safety 3) (space 3) (speed 0)))
      (defun frob (w x y &optional (z (foo x y)))
        (mumble x y z w))
     =>  FROB

See Also::
..........

declare

Notes::
.......

The special declaration may be used with locally to affect references
to, rather than bindings of, variables.

   If a locally form is a top level form, the body forms are also
processed as top level forms.  See *note File Compilation::.


File: gcl.info,  Node: the,  Next: special-operator-p,  Prev: locally,  Up: Evaluation and Compilation Dictionary

3.8.28 the [Special Operator]
-----------------------------

'the' value-type form => {result}*

Arguments and Values::
......................

value-type--a type specifier; not evaluated.

   form--a form; evaluated.

   results--the values resulting from the evaluation of form.  These
values must conform to the type supplied by value-type; see below.

Description::
.............

the specifies that the values_{1a} returned by form are of the types
specified by value-type.  The consequences are undefined if any result
is not of the declared type.

   It is permissible for form to yield a different number of values than
are specified by value-type, provided that the values for which types
are declared are indeed of those types.  Missing values are treated as
nil for the purposes of checking their types.

   Regardless of number of values declared by value-type, the number of
values returned by the the special form is the same as the number of
values returned by form.

Examples::
..........

      (the symbol (car (list (gensym)))) =>  #:G9876
      (the fixnum (+ 5 7)) =>  12
      (the (values) (truncate 3.2 2)) =>  1, 1.2
      (the integer (truncate 3.2 2)) =>  1, 1.2
      (the (values integer) (truncate 3.2 2)) =>  1, 1.2
      (the (values integer float) (truncate 3.2 2))   =>  1, 1.2
      (the (values integer float symbol) (truncate 3.2 2)) =>  1, 1.2
      (the (values integer float symbol t null list)
           (truncate 3.2 2)) =>  1, 1.2
      (let ((i 100))
         (declare (fixnum i))
         (the fixnum (1+ i))) =>  101
      (let* ((x (list 'a 'b 'c))
             (y 5))
         (setf (the fixnum (car x)) y)
         x) =>  (5 B C)

Exceptional Situations::
........................

The consequences are undefined if the values yielded by the form are not
of the type specified by value-type.

See Also::
..........

values

Notes::
.......

The values type specifier can be used to indicate the types of multiple
values:

      (the (values integer integer) (floor x y))
      (the (values string t)
           (gethash the-key the-string-table))

   setf can be used with the type declarations.  In this case the
declaration is transferred to the form that specifies the new value.
The resulting setf form is then analyzed.


File: gcl.info,  Node: special-operator-p,  Next: constantp,  Prev: the,  Up: Evaluation and Compilation Dictionary

3.8.29 special-operator-p [Function]
------------------------------------

'special-operator-p' symbol => generalized-boolean

Arguments and Values::
......................

symbol--a symbol.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if symbol is a special operator; otherwise, returns false.

Examples::
..........

      (special-operator-p 'if) =>  true
      (special-operator-p 'car) =>  false
      (special-operator-p 'one) =>  false

Exceptional Situations::
........................

Should signal type-error if its argument is not a symbol.

Notes::
.......

Historically, this function was called special-form-p.  The name was
finally declared a misnomer and changed, since it returned true for
special operators, not special forms.


File: gcl.info,  Node: constantp,  Prev: special-operator-p,  Up: Evaluation and Compilation Dictionary

3.8.30 constantp [Function]
---------------------------

'constantp' form &optional environment => generalized-boolean

Arguments and Values::
......................

form--a form.

   environment--an environment object.  The default is nil.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if form can be determined by the implementation to be a
constant form in the indicated environment; otherwise, it returns false
indicating either that the form is not a constant form or that it cannot
be determined whether or not form is a constant form.

   The following kinds of forms are considered constant forms:

*
     Self-evaluating objects (such as numbers, characters, and the
     various kinds of arrays) are always considered constant forms and
     must be recognized as such by constantp.

*
     Constant variables, such as keywords, symbols defined by Common
     Lisp as constant (such as nil, t, and pi), and symbols declared as
     constant by the user in the indicated environment using defconstant
     are always considered constant forms and must be recognized as such
     by constantp.

*
     quote forms are always considered constant forms and must be
     recognized as such by constantp.

*
     An implementation is permitted, but not required, to detect
     additional constant forms.  If it does, it is also permitted, but
     not required, to make use of information in the environment.
     Examples of constant forms for which constantp might or might not
     return true are: (sqrt pi), (+ 3 2), (length '(a b c)), and (let
     ((x 7)) (zerop x)).

   If an implementation chooses to make use of the environment
information, such actions as expanding macros or performing function
inlining are permitted to be used, but not required; however, expanding
compiler macros is not permitted.

Examples::
..........

      (constantp 1) =>  true
      (constantp 'temp) =>  false
      (constantp ''temp)) =>  true
      (defconstant this-is-a-constant 'never-changing) =>  THIS-IS-A-CONSTANT
      (constantp 'this-is-a-constant) =>  true
      (constantp "temp") =>  true
      (setq a 6) =>  6
      (constantp a) =>  true
      (constantp '(sin pi)) =>  implementation-dependent
      (constantp '(car '(x))) =>  implementation-dependent
      (constantp '(eql x x)) =>  implementation-dependent
      (constantp '(typep x 'nil)) =>  implementation-dependent
      (constantp '(typep x 't)) =>  implementation-dependent
      (constantp '(values this-is-a-constant)) =>  implementation-dependent
      (constantp '(values 'x 'y)) =>  implementation-dependent
      (constantp '(let ((a '(a b c))) (+ (length a) 6))) =>  implementation-dependent

Affected By::
.............

The state of the global environment (e.g., which symbols have been
declared to be the names of constant variables).

See Also::
..........

*note defconstant::


File: gcl.info,  Node: Types and Classes,  Next: Data and Control Flow,  Prev: Evaluation and Compilation,  Up: Top

4 Types and Classes
*******************

* Menu:

* Introduction (Types and Classes)::
* Types::
* Classes::
* Types and Classes Dictionary::


File: gcl.info,  Node: Introduction (Types and Classes),  Next: Types,  Prev: Types and Classes,  Up: Types and Classes

4.1 Introduction
================

A type is a (possibly infinite) set of objects.  An object can belong to
more than one type.  Types are never explicitly represented as objects
by Common Lisp.  Instead, they are referred to indirectly by the use of
type specifiers, which are objects that denote types.

   New types can be defined using deftype, defstruct, defclass, and
define-condition.

   The function typep, a set membership test, is used to determine
whether a given object is of a given type.  The function subtypep, a
subset test, is used to determine whether a given type is a subtype of
another given type.  The function type-of returns a particular type to
which a given object belongs, even though that object must belong to one
or more other types as well.  (For example, every object is of type t,
but type-of always returns a type specifier for a type more specific
than t.)

   Objects, not variables, have types.  Normally, any variable can have
any object as its value.  It is possible to declare that a variable
takes on only values of a given type by making an explicit type
declaration.  Types are arranged in a directed acyclic graph, except for
the presence of equivalences.

   Declarations can be made about types using declare, proclaim,
declaim, or the.  For more information about declarations, see *note
Declarations::.

   Among the fundamental objects of the object system are classes.  A
class determines the structure and behavior of a set of other objects,
which are called its instances.  Every object is a direct instance of a
class.  The class of an object determines the set of operations that can
be performed on the object.  For more information, see *note Classes::.

   It is possible to write functions that have behavior specialized to
the class of the objects which are their arguments.  For more
information, see *note Generic Functions and Methods::.

   The class of the class of an object is called its metaclass .  For
more information about metaclasses, see *note Meta-Objects::.


File: gcl.info,  Node: Types,  Next: Classes,  Prev: Introduction (Types and Classes),  Up: Types and Classes

4.2 Types
=========

* Menu:

* Data Type Definition::
* Type Relationships::
* Type Specifiers::


File: gcl.info,  Node: Data Type Definition,  Next: Type Relationships,  Prev: Types,  Up: Types

4.2.1 Data Type Definition
--------------------------

Information about type usage is located in the sections specified in
Figure~4-1.  Figure~4-7 lists some classes that are particularly
relevant to the object system.  Figure~9-1 lists the defined condition
types.

  Section                                Data Type                         
  _________________________________________________________________________
  *note Classes::                        Object System types               
  *note Slots::                          Object System types               
  *note Objects::                        Object System types               
  *note Generic Functions and Methods::  Object System types               
  *note Condition System Concepts::      Condition System types            
  *note Types and Classes::              Miscellaneous types               
  *note Syntax::                         All types--read and print syntax  
  *note The Lisp Printer::               All types--print syntax           
  *note Compilation::                    All types--compilation issues     

           Figure 4-1: Cross-References to Data Type Information          



File: gcl.info,  Node: Type Relationships,  Next: Type Specifiers,  Prev: Data Type Definition,  Up: Types

4.2.2 Type Relationships
------------------------

*
     The types cons, symbol, array, number, character, hash-table,

     function,

     readtable, package, pathname, stream, random-state, condition,
     restart, and any single other type created by defstruct,

     define-condition,

     or defclass are pairwise disjoint, except for type relations
     explicitly established by specifying superclasses in defclass

     or define-condition

     or the :include option of destruct.

*
     Any two types created by defstruct are disjoint unless one is a
     supertype of the other by virtue of the defstruct :include option.

     [Editorial Note by KMP: The comments in the source say gray
     suggested some change from "common superclass" to "common subclass"
     in the following, but the result looks suspicious to me.]

*
     Any two distinct classes created by defclass or define-condition
     are disjoint unless they have a common subclass or one class is a
     subclass of the other.

*
     An implementation may be extended to add other subtype
     relationships between the specified types, as long as they do not
     violate the type relationships and disjointness requirements
     specified here.  An implementation may define additional types that
     are subtypes or supertypes of any specified types, as long as each
     additional type is a subtype of type t and a supertype of type nil
     and the disjointness requirements are not violated.

     At the discretion of the implementation, either standard-object or
     structure-object might appear in any class precedence list for a
     system class that does not already specify either standard-object
     or structure-object.  If it does, it must precede the class t and
     follow all other standardized classes.


File: gcl.info,  Node: Type Specifiers,  Prev: Type Relationships,  Up: Types

4.2.3 Type Specifiers
---------------------

Type specifiers can be symbols, classes, or lists.  Figure~4-2 lists
symbols that are standardized atomic type specifiers, and Figure~4-3
lists standardized compound type specifier names.  For syntax
information, see the dictionary entry for the corresponding type
specifier.  It is possible to define new type specifiers using defclass,
define-condition, defstruct, or deftype.

 arithmetic-error                 function           simple-condition          
 array                            generic-function   simple-error              
 atom                             hash-table         simple-string             
 base-char                        integer            simple-type-error         
 base-string                      keyword            simple-vector             
 bignum                           list               simple-warning            
 bit                              logical-pathname   single-float              
 bit-vector                       long-float         standard-char             
 broadcast-stream                 method             standard-class            
 built-in-class                   method-combination standard-generic-function 
 cell-error                       nil                standard-method           
 character                        null               standard-object           
 class                            number             storage-condition         
 compiled-function                package            stream                    
 complex                          package-error      stream-error              
 concatenated-stream              parse-error        string                    
 condition                        pathname           string-stream             
 cons                             print-not-readable structure-class           
 control-error                    program-error      structure-object          
 division-by-zero                 random-state       style-warning             
 double-float                     ratio              symbol                    
 echo-stream                      rational           synonym-stream            
 end-of-file                      reader-error       t                         
 error                            readtable          two-way-stream            
 extended-char                    real               type-error                
 file-error                       restart            unbound-slot              
 file-stream                      sequence           unbound-variable          
 fixnum                           serious-condition  undefined-function        
 float                            short-float        unsigned-byte             
 floating-point-inexact           signed-byte        vector                    
 floating-point-invalid-operation simple-array       warning                   
 floating-point-overflow          simple-base-string                           
 floating-point-underflow         simple-bit-vector                            

                 Figure 4-2: Standardized Atomic Type Specifiers               


   \indent If a type specifier is a list, the car of the list is a
symbol, and the rest of the list is subsidiary type information.  Such a
type specifier is called a compound type specifier .  Except as
explicitly stated otherwise, the subsidiary items can be unspecified.
The unspecified subsidiary items are indicated by writing *.  For
example, to completely specify a vector, the type of the elements and
the length of the vector must be present.

      (vector double-float 100)

   The following leaves the length unspecified:

      (vector double-float *)

   The following leaves the element type unspecified:

      (vector * 100)

   Suppose that two type specifiers are the same except that the first
has a * where the second has a more explicit specification.  Then the
second denotes a subtype of the type denoted by the first.

   If a list has one or more unspecified items at the end, those items
can be dropped.  If dropping all occurrences of * results in a singleton
list, then the parentheses can be dropped as well (the list can be
replaced by the symbol in its car).  For example, (vector double-float
*) can be abbreviated to (vector double-float), and (vector * *) can be
abbreviated to (vector) and then to vector.

  and           long-float    simple-base-string  
  array         member        simple-bit-vector   
  base-string   mod           simple-string       
  bit-vector    not           simple-vector       
  complex       or            single-float        
  cons          rational      string              
  double-float  real          unsigned-byte       
  eql           satisfies     values              
  float         short-float   vector              
  function      signed-byte                       
  integer       simple-array                      

  Figure 4-3: Standardized Compound Type Specifier Names


   Figure 4-4 show the defined names that can be used as compound type
specifier names but that cannot be used as atomic type specifiers.

  and     mod  satisfies  
  eql     not  values     
  member  or              

  Figure 4-4: Standardized Compound-Only Type Specifier Names


   New type specifiers can come into existence in two ways.

*
     Defining a structure by using defstruct without using the :type
     specifier or defining a class by using defclass or define-condition
     automatically causes the name of the structure or class to be a new
     type specifier symbol.
*
     deftype can be used to define derived type specifiers , which act
     as 'abbreviations' for other type specifiers.

   A class object can be used as a type specifier.  When used this way,
it denotes the set of all members of that class.

   Figure 4-5 shows some defined names relating to types and
declarations.

  coerce            defstruct  subtypep  
  declaim           deftype    the       
  declare           ftype      type      
  defclass          locally    type-of   
  define-condition  proclaim   typep     

  Figure 4-5: Defined names relating to types and declarations.


   Figure 4-6 shows all defined names that are type specifier names,
whether for atomic type specifiers or compound type specifiers; this
list is the union of the lists in Figure~4-2 and Figure~4-3.

 and                              function           simple-array              
 arithmetic-error                 generic-function   simple-base-string        
 array                            hash-table         simple-bit-vector         
 atom                             integer            simple-condition          
 base-char                        keyword            simple-error              
 base-string                      list               simple-string             
 bignum                           logical-pathname   simple-type-error         
 bit                              long-float         simple-vector             
 bit-vector                       member             simple-warning            
 broadcast-stream                 method             single-float              
 built-in-class                   method-combination standard-char             
 cell-error                       mod                standard-class            
 character                        nil                standard-generic-function 
 class                            not                standard-method           
 compiled-function                null               standard-object           
 complex                          number             storage-condition         
 concatenated-stream              or                 stream                    
 condition                        package            stream-error              
 cons                             package-error      string                    
 control-error                    parse-error        string-stream             
 division-by-zero                 pathname           structure-class           
 double-float                     print-not-readable structure-object          
 echo-stream                      program-error      style-warning             
 end-of-file                      random-state       symbol                    
 eql                              ratio              synonym-stream            
 error                            rational           t                         
 extended-char                    reader-error       two-way-stream            
 file-error                       readtable          type-error                
 file-stream                      real               unbound-slot              
 fixnum                           restart            unbound-variable          
 float                            satisfies          undefined-function        
 floating-point-inexact           sequence           unsigned-byte             
 floating-point-invalid-operation serious-condition  values                    
 floating-point-overflow          short-float        vector                    
 floating-point-underflow         signed-byte        warning                   

                  Figure 4-6: Standardized Type Specifier Names                



File: gcl.info,  Node: Classes,  Next: Types and Classes Dictionary,  Prev: Types,  Up: Types and Classes

4.3 Classes
===========

While the object system is general enough to describe all standardized
classes (including, for example, number, hash-table, and symbol), Figure
4-7 contains a list of classes that are especially relevant to
understanding the object system.

  built-in-class    method-combination         standard-object   
  class             standard-class             structure-class   
  generic-function  standard-generic-function  structure-object  
  method            standard-method                              

                Figure 4-7: Object System Classes               


* Menu:

* Introduction to Classes::
* Defining Classes::
* Creating Instances of Classes::
* Inheritance::
* Determining the Class Precedence List::
* Redefining Classes::
* Integrating Types and Classes::


File: gcl.info,  Node: Introduction to Classes,  Next: Defining Classes,  Prev: Classes,  Up: Classes

4.3.1 Introduction to Classes
-----------------------------

A class is an object that determines the structure and behavior of a set
of other objects, which are called its instances .

   A class can inherit structure and behavior from other classes.  A
class whose definition refers to other classes for the purpose of
inheriting from them is said to be a subclass of each of those classes.
The classes that are designated for purposes of inheritance are said to
be superclasses of the inheriting class.

   A class can have a name.  The function class-name takes a class
object and returns its name.  The name of an anonymous class is nil.  A
symbol can name a class.  The function find-class takes a symbol and
returns the class that the symbol names.  A class has a proper name if
the name is a symbol and if the name of the class names that class.
That is, a class~C has the proper name~S if S= (class-name C) and C=
(find-class S).  Notice that it is possible for (find-class S_1) =
(find-class S_2) and S_1!= S_2.  If C= (find-class S), we say that C is
the class named S.

   A class C_1 is a direct superclass of a class C_2 if C_2 explicitly
designates C_1 as a superclass in its definition.  In this case C_2 is a
direct subclass of C_1.  A class C_n is a superclass of a class C_1 if
there exists a series of classes C_2,...,C_{n-1} such that C_{i+1} is a
direct superclass of C_i for 1 <= i<n.  In this case, C_1 is a subclass
of C_n.  A class is considered neither a superclass nor a subclass of
itself.  That is, if C_1 is a superclass of C_2, then C_1 != C_2.  The
set of classes consisting of some given class C along with all of its
superclasses is called "C and its superclasses."

   Each class has a class precedence list , which is a total ordering on
the set of the given class and its superclasses.  The total ordering is
expressed as a list ordered from most specific to least specific.  The
class precedence list is used in several ways.  In general, more
specific classes can shadow _1 features that would otherwise be
inherited from less specific classes.  The method selection and
combination process uses the class precedence list to order methods from
most specific to least specific.

   When a class is defined, the order in which its direct superclasses
are mentioned in the defining form is important.  Each class has a local
precedence order , which is a list consisting of the class followed by
its direct superclasses in the order mentioned in the defining form.

   A class precedence list is always consistent with the local
precedence order of each class in the list.  The classes in each local
precedence order appear within the class precedence list in the same
order.  If the local precedence orders are inconsistent with each other,
no class precedence list can be constructed, and an error is signaled.
The class precedence list and its computation is discussed in *note
Determining the Class Precedence List::.

   classes are organized into a directed acyclic graph.  There are two
distinguished classes, named t and standard-object.  The class named t
has no superclasses.  It is a superclass of every class except itself.
The class named standard-object is an instance of the class
standard-class and is a superclass of every class that is an instance of
the class standard-class except itself.

   [Reviewer Note by Barmar: This or something like it needs to be said
in the introduction.]  There is a mapping from the object system class
space into the type space.  Many of the standard types specified in this
document have a corresponding class that has the same name as the type.
Some types do not have a corresponding class.  The integration of the
type and class systems is discussed in *note Integrating Types and
Classes::.

   Classes are represented by objects that are themselves instances of
classes.  The class of the class of an object is termed the metaclass of
that object.  When no misinterpretation is possible, the term metaclass
is used to refer to a class that has instances that are themselves
classes.  The metaclass determines the form of inheritance used by the
classes that are its instances and the representation of the instances
of those classes.  The object system provides a default metaclass,
standard-class, that is appropriate for most programs.

   Except where otherwise specified, all classes mentioned in this
standard are instances of the class standard-class, all generic
functions are instances of the class standard-generic-function, and all
methods are instances of the class standard-method.

* Menu:

* Standard Metaclasses::


File: gcl.info,  Node: Standard Metaclasses,  Prev: Introduction to Classes,  Up: Introduction to Classes

4.3.1.1 Standard Metaclasses
............................

The object system provides a number of predefined metaclasses.  These
include the classes standard-class, built-in-class, and structure-class:

*
     The class standard-class is the default class of classes defined by
     defclass.

*
     The class built-in-class is the class whose instances are classes
     that have special implementations with restricted capabilities.
     Any class that corresponds to a standard type might be an instance
     of built-in-class.  The predefined type specifiers that are
     required to have corresponding classes are listed in Figure~4-8.
     It is implementation-dependent whether each of these classes is
     implemented as a built-in class.

*
     All classes defined by means of defstruct are instances of the
     class structure-class.


File: gcl.info,  Node: Defining Classes,  Next: Creating Instances of Classes,  Prev: Introduction to Classes,  Up: Classes

4.3.2 Defining Classes
----------------------

The macro defclass is used to define a new named class.

   The definition of a class includes:

*
     The name of the new class.  For newly-defined classes this name is
     a proper name.

*
     The list of the direct superclasses of the new class.

*
     A set of slot specifiers .  Each slot specifier includes the name
     of the slot and zero or more slot options.  A slot option pertains
     only to a single slot.  If a class definition contains two slot
     specifiers with the same name, an error is signaled.

*
     A set of class options.  Each class option pertains to the class as
     a whole.

   The slot options and class options of the defclass form provide
mechanisms for the following:

*
     Supplying a default initial value form for a given slot.

*
     Requesting that methods for generic functions be automatically
     generated for reading or writing slots.

*
     Controlling whether a given slot is shared by all instances of the
     class or whether each instance of the class has its own slot.

*
     Supplying a set of initialization arguments and initialization
     argument defaults to be used in instance creation.

*
     Indicating that the metaclass is to be other than the default.  The
     :metaclass option is reserved for future use; an implementation can
     be extended to make use of the :metaclass option.

*
     Indicating the expected type for the value stored in the slot.

*
     Indicating the documentation string for the slot.


File: gcl.info,  Node: Creating Instances of Classes,  Next: Inheritance,  Prev: Defining Classes,  Up: Classes

4.3.3 Creating Instances of Classes
-----------------------------------

The generic function make-instance creates and returns a new instance of
a class.  The object system provides several mechanisms for specifying
how a new instance is to be initialized.  For example, it is possible to
specify the initial values for slots in newly created instances either
by giving arguments to make-instance or by providing default initial
values.  Further initialization activities can be performed by methods
written for generic functions that are part of the initialization
protocol.  The complete initialization protocol is described in *note
Object Creation and Initialization::.


File: gcl.info,  Node: Inheritance,  Next: Determining the Class Precedence List,  Prev: Creating Instances of Classes,  Up: Classes

4.3.4 Inheritance
-----------------

A class can inherit methods, slots, and some defclass options from its
superclasses.  Other sections describe the inheritance of methods, the
inheritance of slots and slot options, and the inheritance of class
options.

* Menu:

* Examples of Inheritance::
* Inheritance of Class Options::


File: gcl.info,  Node: Examples of Inheritance,  Next: Inheritance of Class Options,  Prev: Inheritance,  Up: Inheritance

4.3.4.1 Examples of Inheritance
...............................

      (defclass C1 ()
          ((S1 :initform 5.4 :type number)
           (S2 :allocation :class)))

      (defclass C2 (C1)
          ((S1 :initform 5 :type integer)
           (S2 :allocation :instance)
           (S3 :accessor C2-S3)))

   Instances of the class C1 have a local slot named S1, whose default
initial value is 5.4 and whose value should always be a number.  The
class C1 also has a shared slot named S2.

   There is a local slot named S1 in instances of C2.  The default
initial value of S1 is 5.  The value of S1 should always be of type (and
integer number).  There are also local slots named S2 and S3 in
instances of C2.  The class C2 has a method for C2-S3 for reading the
value of slot S3; there is also a method for (setf C2-S3) that writes
the value of S3.


File: gcl.info,  Node: Inheritance of Class Options,  Prev: Examples of Inheritance,  Up: Inheritance

4.3.4.2 Inheritance of Class Options
....................................

The :default-initargs class option is inherited.  The set of defaulted
initialization arguments for a class is the union of the sets of
initialization arguments supplied in the :default-initargs class options
of the class and its superclasses.  When more than one default initial
value form is supplied for a given initialization argument, the default
initial value form that is used is the one supplied by the class that is
most specific according to the class precedence list.

   If a given :default-initargs class option specifies an initialization
argument of the same name more than once, an error of type program-error
is signaled.


File: gcl.info,  Node: Determining the Class Precedence List,  Next: Redefining Classes,  Prev: Inheritance,  Up: Classes

4.3.5 Determining the Class Precedence List
-------------------------------------------

The defclass form for a class provides a total ordering on that class
and its direct superclasses.  This ordering is called the local
precedence order .  It is an ordered list of the class and its direct
superclasses.  The class precedence list for a class C is a total
ordering on C and its superclasses that is consistent with the local
precedence orders for each of C and its superclasses.

   A class precedes its direct superclasses, and a direct superclass
precedes all other direct superclasses specified to its right in the
superclasses list of the defclass form.  For every class C, define
               R_C={(C,C_1),(C_1,C_2),...,(C_{n-1},C_n)}
   where C_1,...,C_n are the direct superclasses of C in the order in
which they are mentioned in the defclass form.  These ordered pairs
generate the total ordering on the class C and its direct superclasses.

   Let S_C be the set of C and its superclasses.  Let R be

                       R=\bigcup_{c\in S_C }R_c
   .

   [Reviewer Note by Barmar: "Consistent" needs to be defined, or maybe
we should say "logically consistent"?]

   The set R might or might not generate a partial ordering, depending
on whether the R_c, c\in S_C, are consistent; it is assumed that they
are consistent and that R generates a partial ordering.  When the R_c
are not consistent, it is said that R is inconsistent.

   To compute the class precedence list for~C, topologically sort the
elements of S_C with respect to the partial ordering generated by R.
When the topological sort must select a class from a set of two or more
classes, none of which are preceded by other classes with respect to~R,
the class selected is chosen deterministically, as described below.

   If R is inconsistent, an error is signaled.

* Menu:

* Topological Sorting::
* Examples of Class Precedence List Determination::


File: gcl.info,  Node: Topological Sorting,  Next: Examples of Class Precedence List Determination,  Prev: Determining the Class Precedence List,  Up: Determining the Class Precedence List

4.3.5.1 Topological Sorting
...........................

Topological sorting proceeds by finding a class C in~S_C such that no
other class precedes that element according to the elements in~R. The
class C is placed first in the result.  Remove C from S_C, and remove
all pairs of the form (C,D), D\in S_C, from R. Repeat the process,
adding classes with no predecessors to the end of the result.  Stop when
no element can be found that has no predecessor.

   If S_C is not empty and the process has stopped, the set R is
inconsistent.  If every class in the finite set of classes is preceded
by another, then R contains a loop.  That is, there is a chain of
classes C_1,...,C_n such that C_i precedes C_{i+1}, 1<= i<n, and C_n
precedes C_1.

   Sometimes there are several classes from S_C with no predecessors.
In this case select the one that has a direct subclass rightmost in the
class precedence list computed so far.  (If there is no such candidate
class, R does not generate a partial ordering--the R_c, c\in S_C, are
inconsistent.)

   In more precise terms, let {N_1,...,N_m}, m>= 2, be the classes from
S_C with no predecessors.  Let (C_1...  C_n), n>= 1, be the class
precedence list constructed so far.  C_1 is the most specific class, and
C_n is the least specific.  Let 1<= j<= n be the largest number such
that there exists an i where 1<= i<= m and N_i is a direct superclass of
C_j; N_i is placed next.

   The effect of this rule for selecting from a set of classes with no
predecessors is that the classes in a simple superclass chain are
adjacent in the class precedence list and that classes in each
relatively separated subgraph are adjacent in the class precedence list.
For example, let T_1 and T_2 be subgraphs whose only element in common
is the class J. Suppose that no superclass of J appears in either T_1 or
T_2, and that J is in the superclass chain of every class in both T_1
and T_2.  Let C_1 be the bottom of T_1; and let C_2 be the bottom of
T_2.  Suppose C is a class whose direct superclasses are C_1 and C_2 in
that order, then the class precedence list for C starts with C and is
followed by all classes in T_1 except J. All the classes of T_2 are
next.  The class J and its superclasses appear last.


File: gcl.info,  Node: Examples of Class Precedence List Determination,  Prev: Topological Sorting,  Up: Determining the Class Precedence List

4.3.5.2 Examples of Class Precedence List Determination
.......................................................

This example determines a class precedence list for the class pie.  The
following classes are defined:

      (defclass pie (apple cinnamon) ())

      (defclass apple (fruit) ())

      (defclass cinnamon (spice) ())

      (defclass fruit (food) ())

      (defclass spice (food) ())

      (defclass food () ())

   The set S_{pie}~= {pie, apple, cinnamon, fruit, spice, food,
standard-object, t }.  The set R~= { (pie, apple), (apple, cinnamon),
(apple, fruit), (cinnamon, spice), \break (fruit, food), (spice, food),
(food, standard-object), (standard-object, t) }.

   The class pie is not preceded by anything, so it comes first; the
result so far is (pie).  Remove pie from S and pairs mentioning pie from
R to get S~= {apple, cinnamon, fruit, spice, food, standard-object, t }
and R~=~{(apple, cinnamon), (apple, fruit), (cinnamon, spice),\break
(fruit, food), (spice, food), (food, standard-object), (standard-object,
t) }.

   The class apple is not preceded by anything, so it is next; the
result is (pie apple).  Removing apple and the relevant pairs results in
S~= { cinnamon, fruit, spice, food, standard-object, t } and R~= {
(cinnamon, spice), (fruit, food), (spice, food), (food,
standard-object),\break (standard-object, t) }.

   The classes cinnamon and fruit are not preceded by anything, so the
one with a direct subclass rightmost in the class precedence list
computed so far goes next.  The class apple is a direct subclass of
fruit, and the class pie is a direct subclass of cinnamon.  Because
apple appears to the right of pie in the class precedence list, fruit
goes next, and the result so far is (pie apple fruit).  S~= { cinnamon,
spice, food, standard-object, t }; R~= {(cinnamon, spice), (spice,
food),\break (food, standard-object), (standard-object, t) }.

   The class cinnamon is next, giving the result so far as (pie apple
fruit cinnamon).  At this point S~= { spice, food, standard-object, t };
R~= { (spice, food), (food, standard-object), (standard-object, t) }.

   The classes spice, food, standard-object, and t are added in that
order, and the class precedence list is (pie apple fruit cinnamon spice
food standard-object t).

   It is possible to write a set of class definitions that cannot be
ordered.  For example:

      (defclass new-class (fruit apple) ())

      (defclass apple (fruit) ())

   The class fruit must precede apple because the local ordering of
superclasses must be preserved.  The class apple must precede fruit
because a class always precedes its own superclasses.  When this
situation occurs, an error is signaled, as happens here when the system
tries to compute the class precedence list of new-class.

   The following might appear to be a conflicting set of definitions:

      (defclass pie (apple cinnamon) ())

      (defclass pastry (cinnamon apple) ())

      (defclass apple () ())

      (defclass cinnamon () ())

   The class precedence list for pie is (pie apple cinnamon
standard-object t).

   The class precedence list for pastry is (pastry cinnamon apple
standard-object t).

   It is not a problem for apple to precede cinnamon in the ordering of
the superclasses of pie but not in the ordering for pastry.  However, it
is not possible to build a new class that has both pie and pastry as
superclasses.


File: gcl.info,  Node: Redefining Classes,  Next: Integrating Types and Classes,  Prev: Determining the Class Precedence List,  Up: Classes

4.3.6 Redefining Classes
------------------------

A class that is a direct instance of standard-class can be redefined if
the new class is also a direct instance of standard-class.  Redefining a
class modifies the existing class object to reflect the new class
definition; it does not create a new class object for the class.  Any
method object created by a :reader, :writer, or :accessor option
specified by the old defclass form is removed from the corresponding
generic function.  Methods specified by the new defclass form are added.

   When the class C is redefined, changes are propagated to its
instances and to instances of any of its subclasses.  Updating such an
instance occurs at an implementation-dependent time, but no later than
the next time a slot of that instance is read or written.  Updating an
instance does not change its identity as defined by the function eq.
The updating process may change the slots of that particular instance,
but it does not create a new instance.  Whether updating an instance
consumes storage is implementation-dependent.

   Note that redefining a class may cause slots to be added or deleted.
If a class is redefined in a way that changes the set of local slots
accessible in instances, the instances are updated.  It is
implementation-dependent whether instances are updated if a class is
redefined in a way that does not change the set of local slots
accessible in instances.

   The value of a slot that is specified as shared both in the old class
and in the new class is retained.  If such a shared slot was unbound in
the old class, it is unbound in the new class.  Slots that were local in
the old class and that are shared in the new class are initialized.
Newly added shared slots are initialized.

   Each newly added shared slot is set to the result of evaluating the
captured initialization form for the slot that was specified in the
defclass form for the new class.  If there was no initialization form,
the slot is unbound.

   If a class is redefined in such a way that the set of local slots
accessible in an instance of the class is changed, a two-step process of
updating the instances of the class takes place.  The process may be
explicitly started by invoking the generic function
make-instances-obsolete.  This two-step process can happen in other
circumstances in some implementations.  For example, in some
implementations this two-step process is triggered if the order of slots
in storage is changed.

   The first step modifies the structure of the instance by adding new
local slots and discarding local slots that are not defined in the new
version of the class.  The second step initializes the newly-added local
slots and performs any other user-defined actions.  These two steps are
further specified in the next two sections.

* Menu:

* Modifying the Structure of Instances::
* Initializing Newly Added Local Slots (Redefining Classes)::
* Customizing Class Redefinition::


File: gcl.info,  Node: Modifying the Structure of Instances,  Next: Initializing Newly Added Local Slots (Redefining Classes),  Prev: Redefining Classes,  Up: Redefining Classes

4.3.6.1 Modifying the Structure of Instances
............................................

[Reviewer Note by Barmar: What about shared slots that are deleted?]

   The first step modifies the structure of instances of the redefined
class to conform to its new class definition.  Local slots specified by
the new class definition that are not specified as either local or
shared by the old class are added, and slots not specified as either
local or shared by the new class definition that are specified as local
by the old class are discarded.  The names of these added and discarded
slots are passed as arguments to update-instance-for-redefined-class as
described in the next section.

   The values of local slots specified by both the new and old classes
are retained.  If such a local slot was unbound, it remains unbound.

   The value of a slot that is specified as shared in the old class and
as local in the new class is retained.  If such a shared slot was
unbound, the local slot is unbound.


File: gcl.info,  Node: Initializing Newly Added Local Slots (Redefining Classes),  Next: Customizing Class Redefinition,  Prev: Modifying the Structure of Instances,  Up: Redefining Classes

4.3.6.2 Initializing Newly Added Local Slots
............................................

The second step initializes the newly added local slots and performs any
other user-defined actions.  This step is implemented by the generic
function update-instance-for-redefined-class, which is called after
completion of the first step of modifying the structure of the instance.

   The generic function update-instance-for-redefined-class takes four
required arguments: the instance being updated after it has undergone
the first step, a list of the names of local slots that were added, a
list of the names of local slots that were discarded, and a property
list containing the slot names and values of slots that were discarded
and had values.  Included among the discarded slots are slots that were
local in the old class and that are shared in the new class.

   The generic function update-instance-for-redefined-class also takes
any number of initialization arguments.  When it is called by the system
to update an instance whose class has been redefined, no initialization
arguments are provided.

   There is a system-supplied primary method for
update-instance-for-redefined-class whose parameter specializer for its
instance argument is the class standard-object.  First this method
checks the validity of initialization arguments and signals an error if
an initialization argument is supplied that is not declared as valid.
(For more information, see *note Declaring the Validity of
Initialization Arguments::.)  Then it calls the generic function
shared-initialize with the following arguments: the instance, the list
of names of the newly added slots, and the initialization arguments it
received.


File: gcl.info,  Node: Customizing Class Redefinition,  Prev: Initializing Newly Added Local Slots (Redefining Classes),  Up: Redefining Classes

4.3.6.3 Customizing Class Redefinition
......................................

[Reviewer Note by Barmar: This description is hard to follow.]

   Methods for update-instance-for-redefined-class may be defined to
specify actions to be taken when an instance is updated.  If only after
methods for update-instance-for-redefined-class are defined, they will
be run after the system-supplied primary method for initialization and
therefore will not interfere with the default behavior of
update-instance-for-redefined-class.  Because no initialization
arguments are passed to update-instance-for-redefined-class when it is
called by the system, the initialization forms for slots that are filled
by before methods for update-instance-for-redefined-class will not be
evaluated by shared-initialize.

   Methods for shared-initialize may be defined to customize class
redefinition.  For more information, see *note Shared-Initialize::.


File: gcl.info,  Node: Integrating Types and Classes,  Prev: Redefining Classes,  Up: Classes

4.3.7 Integrating Types and Classes
-----------------------------------

The object system maps the space of classes into the space of types.
Every class that has a proper name has a corresponding type with the
same name.

   The proper name of every class is a valid type specifier.  In
addition, every class object is a valid type specifier.  Thus the
expression (typep object class) evaluates to true if the class of object
is class itself or a subclass of class.  The evaluation of the
expression (subtypep class1 class2) returns the values true and true if
class1 is a subclass of class2 or if they are the same class; otherwise
it returns the values false and true.  If I is an instance of some class
C named S and C is an instance of standard-class, the evaluation of the
expression (type-of I\/) returns S if S is the proper name of C;
otherwise, it returns C.

   Because the names of classes and class objects are type specifiers,
they may be used in the special form the and in type declarations.

   Many but not all of the predefined type specifiers have a
corresponding class with the same proper name as the type.  These type
specifiers are listed in Figure~4-8.  For example, the type array has a
corresponding class named array.  No type specifier that is a list, such
as (vector double-float 100), has a corresponding class.  The operator
deftype does not create any classes.

   Each class that corresponds to a predefined type specifier can be
implemented in one of three ways, at the discretion of each
implementation.  It can be a standard class, a structure class,

   or a system class.

   A built-in class is one whose generalized instances have restricted
capabilities or special representations.  Attempting to use defclass to
define subclasses of a built-in-class signals an error.  Calling
make-instance to create a generalized instance of a built-in class
signals an error.  Calling slot-value on a generalized instance of a
built-in class signals an error.  Redefining a built-in class or using
change-class to change the class of an object to or from a built-in
class signals an error.  However, built-in classes can be used as
parameter specializers in methods.

   It is possible to determine whether a class is a built-in class by
checking the metaclass.  A standard class is an instance of the class
standard-class, a built-in class is an instance of the class
built-in-class, and a structure class is an instance of the class
structure-class.

   Each structure type created by defstruct without using the :type
option has a corresponding class.  This class is a generalized instance
of the class structure-class.  The :include option of defstruct creates
a direct subclass of the class that corresponds to the included
structure type.

   It is implementation-dependent whether slots are involved in the
operation of functions defined in this specification on instances of
classes defined in this specification, except when slots are explicitly
defined by this specification.

   If in a particular implementation a class defined in this
specification has slots that are not defined by this specfication, the
names of these slots must not be external symbols of packages defined in
this specification nor otherwise accessible in the CL-USER package.

   The purpose of specifying that many of the standard type specifiers
have a corresponding class is to enable users to write methods that
discriminate on these types.  Method selection requires that a class
precedence list can be determined for each class.

   The hierarchical relationships among the type specifiers are mirrored
by relationships among the classes corresponding to those types.

   Figure~4-8 lists the set of classes that correspond to predefined
type specifiers.

 arithmetic-error                 generic-function   simple-error              
 array                            hash-table         simple-type-error         
 bit-vector                       integer            simple-warning            
 broadcast-stream                 list               standard-class            
 built-in-class                   logical-pathname   standard-generic-function 
 cell-error                       method             standard-method           
 character                        method-combination standard-object           
 class                            null               storage-condition         
 complex                          number             stream                    
 concatenated-stream              package            stream-error              
 condition                        package-error      string                    
 cons                             parse-error        string-stream             
 control-error                    pathname           structure-class           
 division-by-zero                 print-not-readable structure-object          
 echo-stream                      program-error      style-warning             
 end-of-file                      random-state       symbol                    
 error                            ratio              synonym-stream            
 file-error                       rational           t                         
 file-stream                      reader-error       two-way-stream            
 float                            readtable          type-error                
 floating-point-inexact           real               unbound-slot              
 floating-point-invalid-operation restart            unbound-variable          
 floating-point-overflow          sequence           undefined-function        
 floating-point-underflow         serious-condition  vector                    
 function                         simple-condition   warning                   

       Figure 4-8: Classes that correspond to pre-defined type specifiers      


   The class precedence list information specified in the entries for
each of these classes are those that are required by the object system.

   Individual implementations may be extended to define other type
specifiers to have a corresponding class.  Individual implementations
may be extended to add other subclass relationships and to add other
elements to the class precedence lists as long as they do not violate
the type relationships and disjointness requirements specified by this
standard.  A standard class defined with no direct superclasses is
guaranteed to be disjoint from all of the classes in the table, except
for the class named t.


File: gcl.info,  Node: Types and Classes Dictionary,  Prev: Classes,  Up: Types and Classes

4.4 Types and Classes Dictionary
================================

* Menu:

* nil (Type)::
* boolean::
* function (System Class)::
* compiled-function::
* generic-function::
* standard-generic-function::
* class::
* built-in-class::
* structure-class::
* standard-class::
* method::
* standard-method::
* structure-object::
* standard-object::
* method-combination::
* t (System Class)::
* satisfies::
* member (Type Specifier)::
* not (Type Specifier)::
* and (Type Specifier)::
* or (Type Specifier)::
* values (Type Specifier)::
* eql (Type Specifier)::
* coerce::
* deftype::
* subtypep::
* type-of::
* typep::
* type-error::
* type-error-datum::
* simple-type-error::


File: gcl.info,  Node: nil (Type),  Next: boolean,  Prev: Types and Classes Dictionary,  Up: Types and Classes Dictionary

4.4.1 nil [Type]
----------------

Supertypes::
............

all types

Description::
.............

The type nil contains no objects and so is also called the empty type.
The type nil is a subtype of every type.  No object is of type nil.

Notes::
.......

The type containing the object nil is the type null, not the type nil.


File: gcl.info,  Node: boolean,  Next: function (System Class),  Prev: nil (Type),  Up: Types and Classes Dictionary

4.4.2 boolean [Type]
--------------------

Supertypes::
............

boolean, symbol, t

Description::
.............

The type boolean contains the symbols t and nil, which represent true
and false, respectively.

See Also::
..........

t (constant variable), nil (constant variable), *note if:: , *note not::
, *note complement::

Notes::
.......

Conditional operations, such as if, permit the use of generalized
booleans, not just booleans; any non-nil value, not just t, counts as
true for a generalized boolean.  However, as a matter of convention, the
symbol t is considered the canonical value to use even for a generalized
boolean when no better choice presents itself.


File: gcl.info,  Node: function (System Class),  Next: compiled-function,  Prev: boolean,  Up: Types and Classes Dictionary

4.4.3 function [System Class]
-----------------------------

Class Precedence List::
.......................

function, t

Description::
.............

A function is an object that represents code to be executed when an
appropriate number of arguments is supplied.  A function is produced by
the function special form, the function coerce,

   or the function compile.  A function can be directly invoked by using
it as the first argument to funcall, apply, or multiple-value-call.

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('function'{[arg-typespec [value-typespec]]})

   arg-typespec ::=({typespec}* 
                  [&optional {typespec}*] 
                  [&rest typespec] 
                  [&key {(keyword typespec )}*])

Compound Type Specifier Arguments::
...................................

typespec--a type specifier.

   value-typespec--a type specifier.

Compound Type Specifier Description::
.....................................

[Editorial Note by KMP: Isn't there some context info about ftype
declarations to be merged here?]

   [Editorial Note by KMP: This could still use some cleaning up.]

   [Editorial Note by Sandra: Still need clarification about what
happens if the number of arguments doesn't match the FUNCTION type
declaration.]

   The list form of the function type-specifier can be used only for
declaration and not for discrimination.  Every element of this type is a
function that accepts arguments of the types specified by the argj-types
and returns values that are members of the types specified by
value-type.  The &optional, &rest, &key,

   and &allow-other-keys

   markers can appear in the list of argument types.

   The type specifier provided with &rest is the type of each actual
argument, not the type of the corresponding variable.

   The &key parameters should be supplied as lists of the form (keyword
type).  The keyword must be a valid keyword-name symbol as must be
supplied in the actual arguments of a call.

   This is usually a symbol in the KEYWORD package but can be any
symbol.

   When &key is given in a function type specifier lambda list, the
keyword parameters given are exhaustive unless &allow-other-keys is also
present.  &allow-other-keys is an indication that other keyword
arguments might actually be supplied and, if supplied, can be used.  For
example, the type of the function make-list could be declared as
follows:

      (function ((integer 0) &key (:initial-element t)) list)

   The value-type can be a values type specifier in order to indicate
the types of multiple values.

   Consider a declaration of the following form:

      (ftype (function (arg0-type arg1-type ...) val-type) f))

   Any form (f arg0 arg1 ...) within the scope of that declaration is
equivalent to the following:

      (the val-type (f (the arg0-type arg0) (the arg1-type arg1) ...))

   That is, the consequences are undefined if any of the arguments are
not of the specified types or the result is not of the specified type.
In particular, if any argument is not of the correct type, the result is
not guaranteed to be of the specified type.

   Thus, an ftype declaration for a function describes calls to the
function, not the actual definition of the function.

   Consider a declaration of the following form:

      (type (function (arg0-type arg1-type ...) val-type) fn-valued-variable)

   This declaration has the interpretation that, within the scope of the
declaration, the consequences are unspecified if the value of
fn-valued-variable is called with arguments not of the specified types;
the value resulting from a valid call will be of type val-type.

   As with variable type declarations, nested declarations imply
intersections of types, as follows:

*
     Consider the following two declarations of ftype:

           (ftype (function (arg0-type1 arg1-type1 ...) val-type1) f))

     and

           (ftype (function (arg0-type2 arg1-type2 ...) val-type2) f))

     If both these declarations are in effect, then within the shared
     scope of the declarations, calls to f can be treated as if f were
     declared as follows:

           (ftype (function ((and arg0-type1 arg0-type2) (and arg1-type1 arg1-type2 ...) ...)
                            (and val-type1 val-type2))
                  f))

     It is permitted to ignore one or all of the ftype declarations in
     force.

*
     If two (or more) type declarations are in effect for a variable,
     and they are both function declarations, the declarations combine
     similarly.


File: gcl.info,  Node: compiled-function,  Next: generic-function,  Prev: function (System Class),  Up: Types and Classes Dictionary

4.4.4 compiled-function [Type]
------------------------------

Supertypes::
............

compiled-function, function, t

Description::
.............

Any function may be considered by an implementation to be a a compiled
function if it contains no references to macros that must be expanded at
run time, and it contains no unresolved references to load time values.
See *note Compilation Semantics::.

   Functions whose definitions appear lexically within a file that has
been compiled with compile-file and then loaded with load are of type
compiled-function.

   Functions produced by the compile function are of type
compiled-function.

   Other functions might also be of type compiled-function.


File: gcl.info,  Node: generic-function,  Next: standard-generic-function,  Prev: compiled-function,  Up: Types and Classes Dictionary

4.4.5 generic-function [System Class]
-------------------------------------

Class Precedence List::
.......................

generic-function, function, t

Description::
.............

A generic function is a function whose behavior depends on the classes
or identities of the arguments supplied to it.  A generic function
object contains a set of methods, a lambda list, a method combination
type, and other information.  The methods define the class-specific
behavior and operations of the generic function; a method is said to
specialize a generic function.  When invoked, a generic function
executes a subset of its methods based on the classes or identities of
its arguments.

   A generic function can be used in the same ways that an ordinary
function can be used; specifically, a generic function can be used as an
argument to funcall and apply, and can be given a global or a local
name.


File: gcl.info,  Node: standard-generic-function,  Next: class,  Prev: generic-function,  Up: Types and Classes Dictionary

4.4.6 standard-generic-function [System Class]
----------------------------------------------

Class Precedence List::
.......................

standard-generic-function, generic-function, function, t

Description::
.............

The class standard-generic-function is the default class of generic
functions established by defmethod, ensure-generic-function, defgeneric,

   and defclass forms.


File: gcl.info,  Node: class,  Next: built-in-class,  Prev: standard-generic-function,  Up: Types and Classes Dictionary

4.4.7 class [System Class]
--------------------------

Class Precedence List::
.......................

class,

   standard-object,

   t

Description::
.............

The type class represents objects that determine the structure and
behavior of their instances.  Associated with an object of type class is
information describing its place in the directed acyclic graph of
classes, its slots, and its options.


File: gcl.info,  Node: built-in-class,  Next: structure-class,  Prev: class,  Up: Types and Classes Dictionary

4.4.8 built-in-class [System Class]
-----------------------------------

Class Precedence List::
.......................

built-in-class, class,

   standard-object,

   t

Description::
.............

A built-in class is a class whose instances have restricted capabilities
or special representations.  Attempting to use defclass to define
subclasses of a built-in class signals an error of type error.  Calling
make-instance to create an instance of a built-in class signals an error
of type error.  Calling slot-value on an instance of a built-in class
signals an error of type error.  Redefining a built-in class or using
change-class to change the class of an instance to or from a built-in
class signals an error of type error.  However, built-in classes can be
used as parameter specializers in methods.


File: gcl.info,  Node: structure-class,  Next: standard-class,  Prev: built-in-class,  Up: Types and Classes Dictionary

4.4.9 structure-class [System Class]
------------------------------------

Class Precedence List::
.......................

structure-class, class,

   standard-object,

   t

Description::
.............

All classes defined by means of defstruct are instances of the class
structure-class.


File: gcl.info,  Node: standard-class,  Next: method,  Prev: structure-class,  Up: Types and Classes Dictionary

4.4.10 standard-class [System Class]
------------------------------------

Class Precedence List::
.......................

standard-class, class,

   standard-object,

   t

Description::
.............

The class standard-class is the default class of classes defined by
defclass.


File: gcl.info,  Node: method,  Next: standard-method,  Prev: standard-class,  Up: Types and Classes Dictionary

4.4.11 method [System Class]
----------------------------

Class Precedence List::
.......................

method, t

Description::
.............

A method is an object that represents a modular part of the behavior of
a generic function.

   A method contains code to implement the method's behavior, a sequence
of parameter specializers that specify when the given method is
applicable, and a sequence of qualifiers that is used by the method
combination facility to distinguish among methods.  Each required
parameter of each method has an associated parameter specializer, and
the method will be invoked only on arguments that satisfy its parameter
specializers.

   The method combination facility controls the selection of methods,
the order in which they are run, and the values that are returned by the
generic function.  The object system offers a default method combination
type and provides a facility for declaring new types of method
combination.

See Also::
..........

*note Generic Functions and Methods::


File: gcl.info,  Node: standard-method,  Next: structure-object,  Prev: method,  Up: Types and Classes Dictionary

4.4.12 standard-method [System Class]
-------------------------------------

Class Precedence List::
.......................

standard-method, method,

   standard-object,

   t

Description::
.............

The class standard-method is the default class of methods defined by the
defmethod and defgeneric forms.


File: gcl.info,  Node: structure-object,  Next: standard-object,  Prev: standard-method,  Up: Types and Classes Dictionary

4.4.13 structure-object [Class]
-------------------------------

Class Precedence List::
.......................

structure-object, t

Description::
.............

The class structure-object is an instance of structure-class and is a
superclass of every class that is an instance of structure-class except
itself, and is a superclass of every class that is defined by defstruct.

See Also::
..........

*note defstruct:: , *note Sharpsign S::, *note Printing Structures::


File: gcl.info,  Node: standard-object,  Next: method-combination,  Prev: structure-object,  Up: Types and Classes Dictionary

4.4.14 standard-object [Class]
------------------------------

Class Precedence List::
.......................

standard-object, t

Description::
.............

The class standard-object is an instance of standard-class and is a
superclass of every class that is an instance of standard-class except
itself.


File: gcl.info,  Node: method-combination,  Next: t (System Class),  Prev: standard-object,  Up: Types and Classes Dictionary

4.4.15 method-combination [System Class]
----------------------------------------

Class Precedence List::
.......................

method-combination, t

Description::
.............

Every method combination object is an indirect instance of the class
method-combination.  A method combination object represents the
information about the method combination being used by a generic
function.  A method combination object contains information about both
the type of method combination and the arguments being used with that
type.


File: gcl.info,  Node: t (System Class),  Next: satisfies,  Prev: method-combination,  Up: Types and Classes Dictionary

4.4.16 t [System Class]
-----------------------

Class Precedence List::
.......................

t

Description::
.............

The set of all objects.  The type t is a supertype of every type,
including itself.  Every object is of type t.


File: gcl.info,  Node: satisfies,  Next: member (Type Specifier),  Prev: t (System Class),  Up: Types and Classes Dictionary

4.4.17 satisfies [Type Specifier]
---------------------------------

Compound Type Specifier Kind::
..............................

Predicating.

Compound Type Specifier Syntax::
................................

('satisfies'{predicate-name})

Compound Type Specifier Arguments::
...................................

predicate-name--a symbol.

Compound Type Specifier Description::
.....................................

This denotes the set of all objects that satisfy the predicate
predicate-name, which must be a symbol whose global function definition
is a one-argument predicate.  A name is required for predicate-name;
lambda expressions are not allowed.  For example, the type specifier
(and integer (satisfies evenp)) denotes the set of all even integers.
The form (typep x '(satisfies p)) is equivalent to (if (p x) t nil).

   The argument is required.  The symbol * can be the argument, but it
denotes itself (the symbol *), and does not represent an unspecified
value.

   The symbol satisfies is not valid as a type specifier.


File: gcl.info,  Node: member (Type Specifier),  Next: not (Type Specifier),  Prev: satisfies,  Up: Types and Classes Dictionary

4.4.18 member [Type Specifier]
------------------------------

Compound Type Specifier Kind::
..............................

Combining.

Compound Type Specifier Syntax::
................................

('member'{{object}*})

Compound Type Specifier Arguments::
...................................

object--an object.

Compound Type Specifier Description::
.....................................

This denotes the set containing the named objects.  An object is of this
type if and only if it is eql to one of the specified objects.

   The type specifiers (member) and nil are equivalent.  * can be among
the objects, but if so it denotes itself (the symbol *) and does not
represent an unspecified value.  The symbol member is not valid as a
type specifier; and, specifically, it is not an abbreviation for either
(member) or (member *).

See Also::
..........

the type eql


File: gcl.info,  Node: not (Type Specifier),  Next: and (Type Specifier),  Prev: member (Type Specifier),  Up: Types and Classes Dictionary

4.4.19 not [Type Specifier]
---------------------------

Compound Type Specifier Kind::
..............................

Combining.

Compound Type Specifier Syntax::
................................

('not'{typespec})

Compound Type Specifier Arguments::
...................................

typespec--a type specifier.

Compound Type Specifier Description::
.....................................

This denotes the set of all objects that are not of the type typespec.

   The argument is required, and cannot be *.

   The symbol not is not valid as a type specifier.


File: gcl.info,  Node: and (Type Specifier),  Next: or (Type Specifier),  Prev: not (Type Specifier),  Up: Types and Classes Dictionary

4.4.20 and [Type Specifier]
---------------------------

Compound Type Specifier Kind::
..............................

Combining.

Compound Type Specifier Syntax::
................................

('and'{{typespec}*})

Compound Type Specifier Arguments::
...................................

typespec--a type specifier.

Compound Type Specifier Description::
.....................................

This denotes the set of all objects of the type determined by the
intersection of the typespecs.

   * is not permitted as an argument.

   The type specifiers (and) and t are equivalent.  The symbol and is
not valid as a type specifier, and, specifically, it is not an
abbreviation for (and).


File: gcl.info,  Node: or (Type Specifier),  Next: values (Type Specifier),  Prev: and (Type Specifier),  Up: Types and Classes Dictionary

4.4.21 or [Type Specifier]
--------------------------

Compound Type Specifier Kind::
..............................

Combining.

Compound Type Specifier Syntax::
................................

('or'{{typespec}*})

Compound Type Specifier Arguments::
...................................

typespec--a type specifier.

Compound Type Specifier Description::
.....................................

This denotes the set of all objects of the type determined by the union
of the typespecs.  For example, the type list by definition is the same
as (or null cons).  Also, the value returned by position is an object of
type (or null (integer 0 *)); i.e., either nil or a non-negative
integer.

   * is not permitted as an argument.

   The type specifiers (or) and nil are equivalent.  The symbol or is
not valid as a type specifier; and, specifically, it is not an
abbreviation for (or).


File: gcl.info,  Node: values (Type Specifier),  Next: eql (Type Specifier),  Prev: or (Type Specifier),  Up: Types and Classes Dictionary

4.4.22 values [Type Specifier]
------------------------------

Compound Type Specifier Kind::
..............................

Specializing.

Compound Type Specifier Syntax::
................................

('values'{!value-typespec})

   [Reviewer Note by Barmar: Missing &key]

   value-typespec ::={typespec}* [&optional {typespec}*] [&rest typespec ] [&allow-other-keys]

Compound Type Specifier Arguments::
...................................

typespec--a type specifier.

Compound Type Specifier Description::
.....................................

This type specifier can be used only as the value-type in a function
type specifier or a the special form.  It is used to specify individual
types when multiple values are involved.  The &optional and &rest
markers can appear in the value-type list; they indicate the parameter
list of a function that, when given to multiple-value-call along with
the values, would correctly receive those values.

   The symbol * may not be among the value-types.

   The symbol values is not valid as a type specifier; and,
specifically, it is not an abbreviation for (values).


File: gcl.info,  Node: eql (Type Specifier),  Next: coerce,  Prev: values (Type Specifier),  Up: Types and Classes Dictionary

4.4.23 eql [Type Specifier]
---------------------------

Compound Type Specifier Kind::
..............................

Combining.

Compound Type Specifier Syntax::
................................

('eql'{object})

Compound Type Specifier Arguments::
...................................

object--an object.

Compound Type Specifier Description::
.....................................

Represents the type whose only element is object.

   The argument object is required.  The object can be *, but if so it
denotes itself (the symbol *) and does not represent an unspecified
value.  The symbol eql is not valid as an atomic type specifier.


File: gcl.info,  Node: coerce,  Next: deftype,  Prev: eql (Type Specifier),  Up: Types and Classes Dictionary

4.4.24 coerce [Function]
------------------------

'coerce' object result-type => result

Arguments and Values::
......................

object--an object.

   result-type--a type specifier.

   result--an object, of type result-type except in situations described
in *note Rule of Canonical Representation for Complex Rationals::.

Description::
.............

Coerces the object to type result-type.

   If object is already of type result-type, the object itself is
returned, regardless of whether it would have been possible in general
to coerce an object of some other type to result-type.

   Otherwise, the object is coerced to type result-type according to the
following rules:

sequence

     If the result-type is a recognizable subtype of list, and the
     object is a sequence, then the result is a list that has the same
     elements as object.

     If the result-type is a recognizable subtype of vector, and the
     object is a sequence, then the result is a vector that has the same
     elements as object.  If result-type is a specialized type, the
     result has an actual array element type that is the result of
     upgrading the element type part of that specialized type.  If no
     element type is specified, the element type defaults to t.  If the
     implementation cannot determine the element type, an error is
     signaled.

character
     If the result-type is character and the object is a character
     designator, the result is the character it denotes.

complex
     If the result-type is complex and the object is a number, then the
     result is obtained by constructing a complex whose real part is the
     object and whose imaginary part is the result of coercing an
     integer zero to the type of the object (using coerce).  (If the
     real part is a rational, however, then the result must be
     represented as a rational rather than a complex; see *note Rule of
     Canonical Representation for Complex Rationals::.  So, for example,
     (coerce 3 'complex) is permissible, but will return 3, which is not
     a complex.)

float
     If the result-type is any of float, short-float, single-float,
     double-float, long-float, and the object is a

     real,

     then the result is a float of type result-type which is equal in
     sign and magnitude to the object to whatever degree of
     representational precision is permitted by that float
     representation.  (If the result-type is float and object is not
     already a float, then the result is a single float.)

function
     If the result-type is function, and object is any

     function name

     that is fbound but that is globally defined neither as a macro name
     nor as a special operator, then the result is the functional value
     of object.

     If the result-type is function, and object is a lambda expression,
     then the result is a closure of object in the null lexical
     environment.

t
     Any object can be coerced to an object of type t.  In this case,
     the object is simply returned.

Examples::
..........

      (coerce '(a b c) 'vector) =>  #(A B C)
      (coerce 'a 'character) =>  #\A
      (coerce 4.56 'complex) =>  #C(4.56 0.0)
      (coerce 4.5s0 'complex) =>  #C(4.5s0 0.0s0)
      (coerce 7/2 'complex) =>  7/2
      (coerce 0 'short-float) =>  0.0s0
      (coerce 3.5L0 'float) =>  3.5L0
      (coerce 7/2 'float) =>  3.5
      (coerce (cons 1 2) t) =>  (1 . 2)

   All the following forms should signal an error:

      (coerce '(a b c) '(vector * 4))
      (coerce #(a b c) '(vector * 4))
      (coerce '(a b c) '(vector * 2))
      (coerce #(a b c) '(vector * 2))
      (coerce "foo" '(string 2))
      (coerce #(#\a #\b #\c) '(string 2))
      (coerce '(0 1) '(simple-bit-vector 3))

Exceptional Situations::
........................

If a coercion is not possible, an error of type type-error is signaled.

   (coerce x 'nil) always signals an error of type type-error.

   An error of type error is signaled if the result-type is function but
object is a symbol that is not fbound or if the symbol names a macro or
a special operator.

   An error of type type-error should be signaled if result-type
specifies the number of elements and object is of a different length.

See Also::
..........

*note rational (Function):: , *note floor:: , *note char-code:: , *note
char-int::

Notes::
.......

Coercions from floats to rationals and from ratios to integers are not
provided because of rounding problems.

      (coerce x 't) == (identity x) == x


File: gcl.info,  Node: deftype,  Next: subtypep,  Prev: coerce,  Up: Types and Classes Dictionary

4.4.25 deftype [Macro]
----------------------

'deftype' name lambda-list [[{declaration}* | documentation]] {form}* =>
name

Arguments and Values::
......................

name--a symbol.

   lambda-list--a deftype lambda list.

   declaration--a declare expression; not evaluated.

   documentation--a string; not evaluated.

   form--a form.

Description::
.............

deftype defines a derived type specifier named name.

   The meaning of the new type specifier is given in terms of a function
which expands the type specifier into another type specifier, which
itself will be expanded if it contains references to another derived
type specifier.

   The newly defined type specifier may be referenced as a list of the
form (name arg_1 arg_2 ...)\/.  The number of arguments must be
appropriate to the lambda-list.  If the new type specifier takes no
arguments, or if all of its arguments are optional, the type specifier
may be used as an atomic type specifier.

   The argument expressions to the type specifier, arg_1 ...  arg_n, are
not evaluated.  Instead, these literal objects become the objects to
which corresponding parameters become bound.

   The body of the deftype form

   (but not the lambda-list)

   is

   implicitly enclosed in a block named name,

   and is evaluated as an implicit progn, returning a new type
specifier.

   The lexical environment of the body is the one which was current at
the time the deftype form was evaluated, augmented by the variables in
the lambda-list.

   Recursive expansion of the type specifier returned as the expansion
must terminate, including the expansion of type specifiers which are
nested within the expansion.

   The consequences are undefined if the result of fully expanding a
type specifier contains any circular structure, except within the
objects referred to by member and eql type specifiers.

   Documentation is attached to name as a documentation string of kind
type.

   If a deftype form appears as a top level form, the compiler must
ensure that the name is recognized in subsequent type declarations.  The
programmer must ensure that the body of a deftype form can be evaluated
at compile time if the name is referenced in subsequent type
declarations.  If the expansion of a type specifier is not defined fully
at compile time (perhaps because it expands into an unknown type
specifier or a satisfies of a named function that isn't defined in the
compile-time environment), an implementation may ignore any references
to this type in declarations and/or signal a warning.

Examples::
..........

      (defun equidimensional (a)
        (or (< (array-rank a) 2)
            (apply #'= (array-dimensions a)))) =>  EQUIDIMENSIONAL
      (deftype square-matrix (&optional type size)
        `(and (array ,type (,size ,size))
              (satisfies equidimensional))) =>  SQUARE-MATRIX

See Also::
..........

declare, *note defmacro:: , *note documentation:: , *note Type
Specifiers::, *note Syntactic Interaction of Documentation Strings and
Declarations::


File: gcl.info,  Node: subtypep,  Next: type-of,  Prev: deftype,  Up: Types and Classes Dictionary

4.4.26 subtypep [Function]
--------------------------

'subtypep' type-1 type-2 &optional environment => subtype-p, valid-p

Arguments and Values::
......................

type-1--a type specifier.

   type-2--a type specifier.

   environment--an environment object.  The default is nil, denoting the
null lexical environment and the current global environment.

   subtype-p--a generalized boolean.

   valid-p--a generalized boolean.

Description::
.............

If type-1 is a recognizable subtype of type-2, the first value is true.
Otherwise, the first value is false, indicating that either type-1 is
not a subtype of type-2, or else type-1 is a subtype of type-2 but is
not a recognizable subtype.

   A second value is also returned indicating the 'certainty' of the
first value.  If this value is true, then the first value is an accurate
indication of the subtype relationship.  (The second value is always
true when the first value is true.)

   Figure 4-9 summarizes the possible combinations of values that might
result.

  Value 1  Value 2  Meaning                                               
  true     true     type-1 is definitely a subtype of type-2.             
  false    true     type-1 is definitely not a subtype of type-2.         
  false    false    subtypep could not determine the relationship,        
                    so type-1 might or might not be a subtype of type-2.  

               Figure 4-9: Result possibilities for subtypep             


   subtypep is permitted to return the values false and false only when
at least one argument involves one of these type specifiers: and, eql,
the list form of function, member, not, or, satisfies, or values.  (A
type specifier 'involves' such a symbol if, after being type expanded,
it contains that symbol in a position that would call for its meaning as
a type specifier to be used.)  One consequence of this is that if
neither type-1 nor type-2 involves any of these type specifiers, then
subtypep is obliged to determine the relationship accurately.  In
particular, subtypep returns the values true and true if the arguments
are equal and do not involve any of these type specifiers.

   subtypep never returns a second value of nil when both type-1 and
type-2 involve only the names in Figure~4-2, or names of types defined
by defstruct, define-condition, or defclass, or derived types that
expand into only those names.  While type specifiers listed in
Figure~4-2 and names of defclass and defstruct can in some cases be
implemented as derived types, subtypep regards them as primitive.

   The relationships between types reflected by subtypep are those
specific to the particular implementation.  For example, if an
implementation supports only a single type of floating-point numbers, in
that implementation (subtypep 'float 'long-float) returns the values
true and true (since the two types are identical).

   For all T1 and T2 other than *, (array T1) and (array T2) are two
different type specifiers that always refer to the same sets of things
if and only if they refer to arrays of exactly the same specialized
representation, i.e., if (upgraded-array-element-type 'T1) and
(upgraded-array-element-type 'T2) return two different type specifiers
that always refer to the same sets of objects.  This is another way of
saying that `(array type-specifier) and `(array
,(upgraded-array-element-type 'type-specifier)) refer to the same set of
specialized array representations.  For all T1 and T2 other than *, the
intersection of (array T1) and (array T2) is the empty set if and only
if they refer to arrays of different, distinct specialized
representations.

   Therefore,

      (subtypep '(array T1) '(array T2)) =>  true

   if and only if

      (upgraded-array-element-type 'T1)  and
      (upgraded-array-element-type 'T2)

   return two different type specifiers that always refer to the same
sets of objects.

   For all type-specifiers T1 and T2 other than *,

      (subtypep '(complex T1) '(complex T2)) =>  true, true

   if:

1.
     T1 is a subtype of T2, or
2.
     (upgraded-complex-part-type 'T1) and (upgraded-complex-part-type
     'T2) return two different type specifiers that always refer to the
     same sets of objects; in this case, (complex T1) and (complex T2)
     both refer to the same specialized representation.

   The values are false and true otherwise.

   The form

      (subtypep '(complex single-float) '(complex float))

   must return true in all implementations, but

      (subtypep '(array single-float) '(array float))

   returns true only in implementations that do not have a specialized
array representation for single floats distinct from that for other
floats.

Examples::
..........

      (subtypep 'compiled-function 'function) =>  true, true
      (subtypep 'null 'list) =>  true, true
      (subtypep 'null 'symbol) =>  true, true
      (subtypep 'integer 'string) =>  false, true
      (subtypep '(satisfies dummy) nil) =>  false, implementation-dependent
      (subtypep '(integer 1 3) '(integer 1 4)) =>  true, true
      (subtypep '(integer (0) (0)) 'nil) =>  true, true
      (subtypep 'nil '(integer (0) (0))) =>  true, true
      (subtypep '(integer (0) (0)) '(member)) =>  true, true ;or false, false
      (subtypep '(member) 'nil) =>  true, true ;or false, false
      (subtypep 'nil '(member)) =>  true, true ;or false, false

   Let <aet-x> and <aet-y> be two distinct type specifiers that do not
always refer to the same sets of objects in a given implementation, but
for which make-array, will return an object of the same array type.

   Thus, in each case,

       (subtypep (array-element-type (make-array 0 :element-type '<aet-x>))
                 (array-element-type (make-array 0 :element-type '<aet-y>)))
     =>  true, true

       (subtypep (array-element-type (make-array 0 :element-type '<aet-y>))
                 (array-element-type (make-array 0 :element-type '<aet-x>)))
     =>  true, true

   If (array <aet-x>) and (array <aet-y>) are different names for
exactly the same set of objects, these names should always refer to the
same sets of objects.  That implies that the following set of tests are
also true:

      (subtypep '(array <aet-x>) '(array <aet-y>)) =>  true, true
      (subtypep '(array <aet-y>) '(array <aet-x>)) =>  true, true

See Also::
..........

*note Types::

Notes::
.......

The small differences between the subtypep specification for the array
and complex types are necessary because there is no creation function
for complexes which allows the specification of the resultant part type
independently of the actual types of the parts.  Thus in the case of the
type complex, the actual type of the parts is referred to, although a
number can be a member of more than one type.  For example, 17 is of
type (mod 18) as well as type (mod 256) and type integer; and 2.3f5 is
of type single-float as well as type float.


File: gcl.info,  Node: type-of,  Next: typep,  Prev: subtypep,  Up: Types and Classes Dictionary

4.4.27 type-of [Function]
-------------------------

'type-of' object => typespec

Arguments and Values::
......................

object--an object.

   typespec--a type specifier.

Description::
.............

Returns a type specifier, typespec, for a type that has the object as an
element.  The typespec satisfies the following:

1.
     For any object that is an element of some built-in type:

     a.
          the type returned is a recognizable subtype of that built-in
          type.

     b.
          the type returned does not involve and, eql, member, not, or,
          satisfies, or values.

2.
     For all objects, (typep object (type-of object)) returns true.
     Implicit in this is that type specifiers which are not valid for
     use with typep, such as the list form of the function type
     specifier, are never returned by type-of.

3.
     The type returned by type-of is always a recognizable subtype of
     the class returned by class-of.  That is,

           (subtypep (type-of object) (class-of object)) =>  true, true

4.
     For objects of metaclass structure-class or standard-class,

     and for conditions,

     type-of returns the proper name of the class returned by class-of
     if it has a proper name, and otherwise returns the class itself.
     In particular, for objects created by the constructor function of a
     structure defined with defstruct without a :type option, type-of
     returns the structure name; and for objects created by
     make-condition, the typespec is the name of the condition type.

5.
     For each of the types short-float, single-float, double-float, or
     long-float of which the object is an element, the typespec is a
     recognizable subtype of that type.

Examples::
..........


      (type-of 'a) =>  SYMBOL
      (type-of '(1 . 2))
     =>  CONS
     OR=> (CONS FIXNUM FIXNUM)
      (type-of #c(0 1))
     =>  COMPLEX
     OR=> (COMPLEX INTEGER)
      (defstruct temp-struct x y z) =>  TEMP-STRUCT
      (type-of (make-temp-struct)) =>  TEMP-STRUCT
      (type-of "abc")
     =>  STRING
     OR=> (STRING 3)
      (subtypep (type-of "abc") 'string) =>  true, true
      (type-of (expt 2 40))
     =>  BIGNUM
     OR=> INTEGER
     OR=> (INTEGER 1099511627776 1099511627776)
     OR=> SYSTEM::TWO-WORD-BIGNUM
     OR=> FIXNUM
      (subtypep (type-of 112312) 'integer) =>  true, true
      (defvar *foo* (make-array 5 :element-type t)) =>  *FOO*
      (class-name (class-of *foo*)) =>  VECTOR
      (type-of *foo*)
     =>  VECTOR
     OR=> (VECTOR T 5)

See Also::
..........

*note array-element-type:: , *note class-of:: , *note defstruct:: ,
*note typecase:: , *note typep:: , *note Types::

Notes::
.......

Implementors are encouraged to arrange for type-of to return

   a portable value.


File: gcl.info,  Node: typep,  Next: type-error,  Prev: type-of,  Up: Types and Classes Dictionary

4.4.28 typep [Function]
-----------------------

'typep' object type-specifier &optional environment =>
generalized-boolean

Arguments and Values::
......................

object--an object.

   type-specifier--any type specifier except

   values, or a type specifier list whose first element is either
function or values.

   environment--an environment object.  The default is nil, denoting the
null lexical environment and the and current global environment.

   generalized-boolean--a generalized boolean.

Description::
.............

Returns true if object is of the type specified by type-specifier;
otherwise, returns false.

   A type-specifier of the form (satisfies fn) is handled by applying
the function fn to object.

   (typep object '(array type-specifier)), where type-specifier is not
*, returns true if and only if object is an array that could be the
result of supplying type-specifier as the :element-type argument to
make-array.  (array *) refers to all arrays regardless of element type,
while (array type-specifier) refers only to those arrays that can result
from giving type-specifier as the :element-type argument to make-array.
A similar interpretation applies to (simple-array type-specifier) and
(vector type-specifier).  See *note Array Upgrading::.

   (typep object '(complex type-specifier)) returns true for all complex
numbers that can result from giving numbers of type type-specifier to
the function complex, plus all other complex numbers of the same
specialized representation.  Both the real and the imaginary parts of
any such complex number must satisfy:

      (typep realpart 'type-specifier)
      (typep imagpart 'type-specifier)

   See the function upgraded-complex-part-type.

Examples::
..........

      (typep 12 'integer) =>  true
      (typep (1+ most-positive-fixnum) 'fixnum) =>  false
      (typep nil t) =>  true
      (typep nil nil) =>  false
      (typep 1 '(mod 2)) =>  true
      (typep #c(1 1) '(complex (eql 1))) =>  true
     ;; To understand this next example, you might need to refer to
     ;; *note Rule of Canonical Representation for Complex Rationals::.
      (typep #c(0 0) '(complex (eql 0))) =>  false

   Let A_x and A_y be two type specifiers that denote different types,
but for which

      (upgraded-array-element-type 'A_x)

   and

      (upgraded-array-element-type 'A_y)

   denote the same type.  Notice that

      (typep (make-array 0 :element-type 'A_x) '(array A_x)) =>  true
      (typep (make-array 0 :element-type 'A_y) '(array A_y)) =>  true
      (typep (make-array 0 :element-type 'A_x) '(array A_y)) =>  true
      (typep (make-array 0 :element-type 'A_y) '(array A_x)) =>  true

Exceptional Situations::
........................

An error of type error is signaled if type-specifier is values, or a
type specifier list whose first element is either function or values.

   The consequences are undefined if the type-specifier is not a type
specifier.

See Also::
..........

*note type-of:: , *note upgraded-array-element-type:: , *note
upgraded-complex-part-type:: , *note Type Specifiers::

Notes::
.......

Implementations are encouraged to recognize and optimize the case of
(typep x (the class y)), since it does not involve any need for
expansion of deftype information at runtime.




File: gcl.info,  Node: type-error,  Next: type-error-datum,  Prev: typep,  Up: Types and Classes Dictionary

4.4.29 type-error [Condition Type]
----------------------------------

Class Precedence List::
.......................

type-error, error, serious-condition, condition, t

Description::
.............

The type type-error represents a situation in which an object is not of
the expected type.  The "offending datum" and "expected type" are
initialized by the initialization arguments named :datum and
:expected-type to make-condition, and are accessed by the functions
type-error-datum and type-error-expected-type.

See Also::
..........

*note type-error-datum:: , type-error-expected-type


File: gcl.info,  Node: type-error-datum,  Next: simple-type-error,  Prev: type-error,  Up: Types and Classes Dictionary

4.4.30 type-error-datum, type-error-expected-type [Function]
------------------------------------------------------------

'type-error-datum' condition => datum

   'type-error-expected-type' condition => expected-type

Arguments and Values::
......................

condition--a condition of type type-error.

   datum--an object.

   expected-type--a type specifier.

Description::
.............

type-error-datum returns the offending datum in the situation
represented by the condition.

   type-error-expected-type returns the expected type of the offending
datum in the situation represented by the condition.

Examples::
..........

      (defun fix-digits (condition)
        (check-type condition type-error)
        (let* ((digits '(zero one two three four
                        five six seven eight nine))
              (val (position (type-error-datum condition) digits)))
          (if (and val (subtypep 'fixnum (type-error-expected-type condition)))
              (store-value 7))))

      (defun foo (x)
        (handler-bind ((type-error #'fix-digits))
          (check-type x number)
          (+ x 3)))

      (foo 'seven)
     =>  10

See Also::
..........

type-error, *note Conditions::


File: gcl.info,  Node: simple-type-error,  Prev: type-error-datum,  Up: Types and Classes Dictionary

4.4.31 simple-type-error [Condition Type]
-----------------------------------------

Class Precedence List::
.......................

simple-type-error, simple-condition, type-error, error,
serious-condition, condition, t

Description::
.............

Conditions of type simple-type-error are like conditions of type
type-error, except that they provide an alternate mechanism for
specifying how the condition is to be reported; see the type
simple-condition.

See Also::
..........

simple-condition,

   *note simple-condition-format-control:: ,

   simple-condition-format-arguments, *note type-error-datum:: ,
type-error-expected-type


File: gcl.info,  Node: Data and Control Flow,  Next: Iteration,  Prev: Types and Classes,  Up: Top

5 Data and Control Flow
***********************

* Menu:

* Generalized Reference::
* Transfer of Control to an Exit Point::
* Data and Control Flow Dictionary::


File: gcl.info,  Node: Generalized Reference,  Next: Transfer of Control to an Exit Point,  Prev: Data and Control Flow,  Up: Data and Control Flow

5.1 Generalized Reference
=========================

* Menu:

* Overview of Places and Generalized Reference::
* Kinds of Places::
* Treatment of Other Macros Based on SETF::


File: gcl.info,  Node: Overview of Places and Generalized Reference,  Next: Kinds of Places,  Prev: Generalized Reference,  Up: Generalized Reference

5.1.1 Overview of Places and Generalized Reference
--------------------------------------------------

A generalized reference is the use of a form, sometimes called a place ,
as if it were a variable that could be read and written.  The value of a
place is the object to which the place form evaluates.  The value of a
place can be changed by using setf.  The concept of binding a place is
not defined in Common Lisp, but an implementation is permitted to extend
the language by defining this concept.

   Figure 5-1 contains examples of the use of setf.  Note that the
values returned by evaluating the forms in column two are not
necessarily the same as those obtained by evaluating the forms in column
three.  In general, the exact macro expansion of a setf form is not
guaranteed and can even be implementation-dependent; all that is
guaranteed is that the expansion is an update form that works for that
particular implementation, that the left-to-right evaluation of subforms
is preserved, and that the ultimate result of evaluating setf is the
value or values being stored.

  Access function   Update Function   Update using setf              
  x                 (setq x datum)    (setf x datum)                 
  (car x)           (rplaca x datum)  (setf (car x) datum)           
  (symbol-value x)  (set x datum)     (setf (symbol-value x) datum)  

                     Figure 5-1: Examples of setf                   


   Figure 5-2 shows operators relating to places and generalized
reference.

  assert                defsetf             push     
  ccase                 get-setf-expansion  remf     
  ctypecase             getf                rotatef  
  decf                  incf                setf     
  define-modify-macro   pop                 shiftf   
  define-setf-expander  psetf                        

  Figure 5-2: Operators relating to places and generalized reference.


   Some of the operators above manipulate places and some manipulate
setf expanders.  A setf expansion can be derived from any place.

   New setf expanders can be defined by using defsetf and
define-setf-expander.

* Menu:

* Evaluation of Subforms to Places::
* Examples of Evaluation of Subforms to Places::
* Setf Expansions::
* Examples of Setf Expansions::


File: gcl.info,  Node: Evaluation of Subforms to Places,  Next: Examples of Evaluation of Subforms to Places,  Prev: Overview of Places and Generalized Reference,  Up: Overview of Places and Generalized Reference

5.1.1.1 Evaluation of Subforms to Places
........................................

The following rules apply to the evaluation of subforms in a place:

1.
     The evaluation ordering of subforms within a place is determined by
     the order specified by the second value returned by

     get-setf-expansion.

     For all places defined by this specification (e.g., getf, ldb,
     ...), this order of evaluation is left-to-right.

     When a place is derived from a macro expansion, this rule is
     applied after the macro is expanded to find the appropriate place.

     Places defined by using defmacro or

     define-setf-expander

     use the evaluation order defined by those definitions.  For
     example, consider the following:

           (defmacro wrong-order (x y) `(getf ,y ,x))

     This following form evaluates place2 first and then place1 because
     that is the order they are evaluated in the macro expansion:

           (push value (wrong-order place1 place2))

2.

     For the macros that manipulate places (push, pushnew, remf, incf,
     decf, shiftf, rotatef, psetf, setf, pop, and those defined by
     define-modify-macro) the subforms of the macro call are evaluated
     exactly once in left-to-right order, with the subforms of the
     places evaluated in the order specified in (1).

     push, pushnew, remf, incf, decf, shiftf, rotatef, psetf, pop
     evaluate all subforms before modifying any of the place locations.
     setf (in the case when setf has more than two arguments) performs
     its operation on each pair in sequence.  For example, in

           (setf place1 value1 place2 value2 ...)

     the subforms of place1 and value1 are evaluated, the location
     specified by place1 is modified to contain the value returned by
     value1, and then the rest of the setf form is processed in a like
     manner.

3.
     For check-type, ctypecase, and ccase, subforms of the place are
     evaluated once as in (1), but might be evaluated again if the type
     check fails in the case of check-type or none of the cases hold in
     ctypecase and ccase.

4.
     For assert, the order of evaluation of the generalized references
     is not specified.

   Rules 2, 3 and 4 cover all standardized macros that manipulate
places.


File: gcl.info,  Node: Examples of Evaluation of Subforms to Places,  Next: Setf Expansions,  Prev: Evaluation of Subforms to Places,  Up: Overview of Places and Generalized Reference

5.1.1.2 Examples of Evaluation of Subforms to Places
....................................................

      (let ((ref2 (list '())))
        (push (progn (princ "1") 'ref-1)
              (car (progn (princ "2") ref2))))
      |>  12
     =>  (REF1)

      (let (x)
         (push (setq x (list 'a))
               (car (setq x (list 'b))))
          x)
     =>  (((A) . B))

   push first evaluates (setq x (list 'a)) => (a), then evaluates (setq
x (list 'b)) => (b), then modifies the car of this latest value to be
((a) . b).


File: gcl.info,  Node: Setf Expansions,  Next: Examples of Setf Expansions,  Prev: Examples of Evaluation of Subforms to Places,  Up: Overview of Places and Generalized Reference

5.1.1.3 Setf Expansions
.......................

Sometimes it is possible to avoid evaluating subforms of a place
multiple times or in the wrong order.  A

   setf expansion

   for a given access form can be expressed as an ordered collection of
five objects:

List of temporary variables
     a list of symbols naming temporary variables to be bound
     sequentially, as if by let*, to values resulting from value forms.

List of value forms
     a list of forms (typically, subforms of the place) which when
     evaluated yield the values to which the corresponding temporary
     variables should be bound.

List of store variables
     a list of symbols naming temporary store variables which are to
     hold the new values that will be assigned to the place.

Storing form
     a form which can reference both the temporary and the store
     variables, and which changes the value of the place and guarantees
     to return as its values the values of the store variables, which
     are the correct values for setf to return.

Accessing form
     a form which can reference the temporary variables, and which
     returns the value of the place.

   The value returned by the accessing form is affected by execution of
the storing form, but either of these forms might be evaluated any
number of times.

   It is possible to do more than one setf in parallel via psetf,
shiftf, and rotatef.  Because of this, the

   setf expander

   must produce new temporary and store variable names every time.  For
examples of how to do this, see gensym.

   For each standardized accessor function F, unless it is explicitly
documented otherwise, it is implementation-dependent whether the ability
to use an F form as a setf place is implemented by a setf expander or a
setf function.  Also, it follows from this that it is
implementation-dependent whether the name (setf F) is fbound.


File: gcl.info,  Node: Examples of Setf Expansions,  Prev: Setf Expansions,  Up: Overview of Places and Generalized Reference

5.1.1.4 Examples of Setf Expansions
...................................

Examples of the contents of the constituents of setf expansions follow.

   For a variable x:

  ()              ;list of temporary variables  
  ()              ;list of value forms          
  (g0001)         ;list of store variables      
  (setq x g0001)  ;storing form                 
  x               ;accessing form               

  Figure 5-3: Sample Setf Expansion of a Variable


   For (car exp):

  (g0002)                             ;list of temporary variables  
  (exp)                               ;list of value forms          
  (g0003)                             ;list of store variables      
  (progn (rplaca g0002 g0003) g0003)  ;storing form                 
  (car g0002)                         ;accessing form               

           Figure 5-4: Sample Setf Expansion of a CAR Form         


   For (subseq seq s e):

  (g0004 g0005 g0006)         ;list of temporary variables  
  (seq s e)                   ;list of value forms          
  (g0007)                     ;list of store variables      
  (progn (replace g0004 g0007 :start1 g0005 :end1 g0006) g0007) 
                              ;storing form                 
  (subseq g0004 g0005 g0006)  ; accessing form              

     Figure 5-5: Sample Setf Expansion of a SUBSEQ Form    


   In some cases, if a subform of a place is itself a place, it is
necessary to expand the subform in order to compute some of the values
in the expansion of the outer place.  For (ldb bs (car exp)):

  (g0001 g0002)            ;list of temporary variables  
  (bs exp)                 ;list of value forms          
  (g0003)                  ;list of store variables      
  (progn (rplaca g0002 (dpb g0003 g0001 (car g0002))) g0003) 
                           ;storing form                 
  (ldb g0001 (car g0002))  ; accessing form              

     Figure 5-6: Sample Setf Expansion of a LDB Form    



File: gcl.info,  Node: Kinds of Places,  Next: Treatment of Other Macros Based on SETF,  Prev: Overview of Places and Generalized Reference,  Up: Generalized Reference

5.1.2 Kinds of Places
---------------------

Several kinds of places are defined by Common Lisp; this section
enumerates them.  This set can be extended by implementations and by
programmer code.

* Menu:

* Variable Names as Places::
* Function Call Forms as Places::
* VALUES Forms as Places::
* THE Forms as Places::
* APPLY Forms as Places::
* Setf Expansions and Places::
* Macro Forms as Places::
* Symbol Macros as Places::
* Other Compound Forms as Places::


File: gcl.info,  Node: Variable Names as Places,  Next: Function Call Forms as Places,  Prev: Kinds of Places,  Up: Kinds of Places

5.1.2.1 Variable Names as Places
................................

The name of a lexical variable or dynamic variable can be used as a
place.


File: gcl.info,  Node: Function Call Forms as Places,  Next: VALUES Forms as Places,  Prev: Variable Names as Places,  Up: Kinds of Places

5.1.2.2 Function Call Forms as Places
.....................................

A function form can be used as a place if it falls into one of the
following categories:

*
     A function call form whose first element is the name of any one of
     the functions in Figure 5-7.

     [Editorial Note by KMP: Note that what are in some places still
     called 'condition accessors' are deliberately omitted from this
     table, and are not labeled as accessors in their entries.  I have
     not yet had time to do a full search for these items and eliminate
     stray references to them as 'accessors', which they are not, but I
     will do that at some point.]

       aref    cdadr                    get                            
       bit     cdar                     gethash                        
       caaaar  cddaar                   logical-pathname-translations  
       caaadr  cddadr                   macro-function                 
       caaar   cddar                    ninth                          
       caadar  cdddar                   nth                            
       caaddr  cddddr                   readtable-case                 
       caadr   cdddr                    rest                           
       caar    cddr                     row-major-aref                 
       cadaar  cdr                      sbit                           
       cadadr  char                     schar                          
       cadar   class-name               second                         
       caddar  compiler-macro-function  seventh                        
       cadddr  documentation            sixth                          
       caddr   eighth                   slot-value                     
       cadr    elt                      subseq                         
       car     fdefinition              svref                          
       cdaaar  fifth                    symbol-function                
       cdaadr  fill-pointer             symbol-plist                   
       cdaar   find-class               symbol-value                   
       cdadar  first                    tenth                          
       cdaddr  fourth                   third                          

            Figure 5-7: Functions that setf can be used with--1      


     In the case of subseq, the replacement value must be a sequence
     whose elements might be contained by the sequence argument to
     subseq, but does not have to be a sequence of the same type as the
     sequence of which the subsequence is specified.  If the length of
     the replacement value does not equal the length of the subsequence
     to be replaced, then the shorter length determines the number of
     elements to be stored, as for replace.

*
     A function call form whose first element is the name of a selector
     function constructed by defstruct.

     The function name must refer to the global function definition,
     rather than a locally defined function.

*
     A function call form whose first element is the name of any one of
     the functions in Figure 5-8, provided that the supplied argument to
     that function is in turn a place form; in this case the new place
     has stored back into it the result of applying the supplied
     "update" function.

       Function name  Argument that is a place  Update function used      
       ldb            second                    dpb                       
       mask-field     second                    deposit-field             
       getf           first                     implementation-dependent  

              Figure 5-8: Functions that setf can be used with--2       


     During the setf expansion of these forms, it is necessary to call

     get-setf-expansion

     in order to figure out how the inner, nested generalized variable
     must be treated.

     The information from

     get-setf-expansion

     is used as follows.

     ldb
          In a form such as:

          (setf (ldb byte-spec place-form) value-form)

          the place referred to by the place-form must always be both
          read and written; note that the update is to the generalized
          variable specified by place-form, not to any object of type
          integer.

          Thus this setf should generate code to do the following:

          1.
               Evaluate byte-spec (and bind it into a temporary
               variable).
          2.
               Bind the temporary variables for place-form.
          3.
               Evaluate value-form (and bind

               its value or values into the store variable).

          4.
               Do the read from place-form.
          5.
               Do the write into place-form with the given bits of the
               integer fetched in step 4 replaced with the value from
               step 3.

          If the evaluation of value-form in step 3 alters what is found
          in place-form, such as setting different bits of integer, then
          the change of the bits denoted by byte-spec is to that altered
          integer, because step 4 is done after the value-form
          evaluation.  Nevertheless, the evaluations required for
          binding the temporary variables are done in steps 1 and 2, and
          thus the expected left-to-right evaluation order is seen.  For
          example:

                (setq integer #x69) =>  #x69
                (rotatef (ldb (byte 4 4) integer)
                         (ldb (byte 4 0) integer))
                integer =>  #x96
               ;;; This example is trying to swap two independent bit fields
               ;;; in an integer.  Note that the generalized variable of
               ;;; interest here is just the (possibly local) program variable
               ;;; integer.

     mask-field
          This case is the same as ldb in all essential aspects.

     getf
          In a form such as:

          (setf (getf place-form ind-form) value-form)

          the place referred to by place-form must always be both read
          and written; note that the update is to the generalized
          variable specified by place-form, not necessarily to the
          particular list that is the property list in question.

          Thus this setf should generate code to do the following:

          1.
               Bind the temporary variables for place-form.
          2.
               Evaluate ind-form (and bind it into a temporary
               variable).
          3.
               Evaluate value-form (and bind

               its value or values into the store variable).

          4.
               Do the read from place-form.
          5.
               Do the write into place-form with a possibly-new property
               list obtained by combining the values from steps 2, 3,
               and 4.  (Note that the phrase "possibly-new property
               list" can mean that the former property list is somehow
               destructively re-used, or it can mean partial or full
               copying of it.  Since either copying or destructive
               re-use can occur, the treatment of the resultant value
               for the possibly-new property list must proceed as if it
               were a different copy needing to be stored back into the
               generalized variable.)

          If the evaluation of value-form in step 3 alters what is found
          in place-form, such as setting a different named property in
          the list, then the change of the property denoted by ind-form
          is to that altered list, because step 4 is done after the
          value-form evaluation.  Nevertheless, the evaluations required
          for binding the temporary variables are done in steps 1 and 2,
          and thus the expected left-to-right evaluation order is seen.

          For example:

                (setq s (setq r (list (list 'a 1 'b 2 'c 3)))) =>  ((a 1 b 2 c 3))
                (setf (getf (car r) 'b)
                      (progn (setq r nil) 6)) =>  6
                r =>  NIL
                s =>  ((A 1 B 6 C 3))
               ;;; Note that the (setq r nil) does not affect the actions of
               ;;; the SETF because the value of R had already been saved in
               ;;; a temporary variable as part of the step 1. Only the CAR
               ;;; of this value will be retrieved, and subsequently modified
               ;;; after the value computation.

