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: Introduction to Slots,  Next: Accessing Slots,  Prev: Slots,  Up: Slots

7.5.1 Introduction to Slots
---------------------------

An object of metaclass standard-class has zero or more named slots.  The
slots of an object are determined by the class of the object.  Each slot
can hold one value.

   [Reviewer Note by Barmar: All symbols are valid variable names.
Perhaps this means to preclude the use of named constants?  We have a
terminology problem to solve.]  The name of a slot is a symbol that is
syntactically valid for use as a variable name.

   When a slot does not have a value, the slot is said to be unbound.
When an unbound slot is read,

   [Reviewer Note by Barmar: from an object whose metaclass is
standard-class?]  the generic function slot-unbound is invoked.  The
system-supplied primary method for slot-unbound on class t signals an
error.

   If slot-unbound returns, its primary value is used that time as the
value of the slot.

   The default initial value form for a slot is defined by the :initform
slot option.  When the :initform form is used to supply a value, it is
evaluated in the lexical environment in which the defclass form was
evaluated.  The :initform along with the lexical environment in which
the defclass form was evaluated is called a captured initialization
form.  For more details, see *note Object Creation and Initialization::.

   A local slot is defined to be a slot that is accessible to exactly
one instance, namely the one in which the slot is allocated.  A shared
slot is defined to be a slot that is visible to more than one instance
of a given class and its subclasses.

   A class is said to define a slot with a given name when the defclass
form for that class contains a slot specifier with that name.  Defining
a local slot does not immediately create a slot; it causes a slot to be
created each time an instance of the class is created.  Defining a
shared slot immediately creates a slot.

   The :allocation slot option to defclass controls the kind of slot
that is defined.  If the value of the :allocation slot option is
:instance, a local slot is created.  If the value of :allocation is
:class, a shared slot is created.

   A slot is said to be accessible in an instance of a class if the slot
is defined by the class of the instance or is inherited from a
superclass of that class.  At most one slot of a given name can be
accessible in an instance.  A shared slot defined by a class is
accessible in all instances of that class.  A detailed explanation of
the inheritance of slots is given in *note Inheritance of Slots and Slot
Options::.


File: gcl.info,  Node: Accessing Slots,  Next: Inheritance of Slots and Slot Options,  Prev: Introduction to Slots,  Up: Slots

7.5.2 Accessing Slots
---------------------

Slots can be accessed in two ways: by use of the primitive function
slot-value and by use of generic functions generated by the defclass
form.

   The function slot-value can be used with any of the slot names
specified in the defclass form to access a specific slot accessible in
an instance of the given class.

   The macro defclass provides syntax for generating methods to read and
write slots.  If a reader method is requested, a method is automatically
generated for reading the value of the slot, but no method for storing a
value into it is generated.  If a writer method is requested, a method
is automatically generated for storing a value into the slot, but no
method for reading its value is generated.  If an accessor method is
requested, a method for reading the value of the slot and a method for
storing a value into the slot are automatically generated.  Reader and
writer methods are implemented using slot-value.

   When a reader or writer method is specified for a slot, the name of
the generic function to which the generated method belongs is directly
specified.  If the name specified for the writer method is the symbol
name, the name of the generic function for writing the slot is the
symbol name, and the generic function takes two arguments: the new value
and the instance, in that order.  If the name specified for the accessor
method is the symbol name, the name of the generic function for reading
the slot is the symbol name, and the name of the generic function for
writing the slot is the list (setf name).

   A generic function created or modified by supplying :reader, :writer,
or :accessor slot options can be treated exactly as an ordinary generic
function.

   Note that slot-value can be used to read or write the value of a slot
whether or not reader or writer methods exist for that slot.  When
slot-value is used, no reader or writer methods are invoked.

   The macro with-slots can be used to establish a lexical environment
in which specified slots are lexically available as if they were
variables.  The macro with-slots invokes the function slot-value to
access the specified slots.

   The macro with-accessors can be used to establish a lexical
environment in which specified slots are lexically available through
their accessors as if they were variables.  The macro with-accessors
invokes the appropriate accessors to access the specified slots.


File: gcl.info,  Node: Inheritance of Slots and Slot Options,  Prev: Accessing Slots,  Up: Slots

7.5.3 Inheritance of Slots and Slot Options
-------------------------------------------

The set of the names of all slots accessible in an instance of a class C
is the union of the sets of names of slots defined by C and its
superclasses.  The structure of an instance is the set of names of local
slots in that instance.

   In the simplest case, only one class among C and its superclasses
defines a slot with a given slot name.  If a slot is defined by a
superclass of C, the slot is said to be inherited.  The characteristics
of the slot are determined by the slot specifier of the defining class.
Consider the defining class for a slot S. If the value of the
:allocation slot option is :instance, then S is a local slot and each
instance of C has its own slot named S that stores its own value.  If
the value of the :allocation slot option is :class, then S is a shared
slot, the class that defined S stores the value, and all instances of C
can access that single slot.  If the :allocation slot option is omitted,
:instance is used.

   In general, more than one class among C and its superclasses can
define a slot with a given name.  In such cases, only one slot with the
given name is accessible in an instance of C, and the characteristics of
that slot are a combination of the several slot specifiers, computed as
follows:

*
     All the slot specifiers for a given slot name are ordered from most
     specific to least specific, according to the order in C's class
     precedence list of the classes that define them.  All references to
     the specificity of slot specifiers immediately below refers to this
     ordering.

*
     The allocation of a slot is controlled by the most specific slot
     specifier.  If the most specific slot specifier does not contain an
     :allocation slot option, :instance is used.  Less specific slot
     specifiers do not affect the allocation.

*
     The default initial value form for a slot is the value of the
     :initform slot option in the most specific slot specifier that
     contains one.  If no slot specifier contains an :initform slot
     option, the slot has no default initial value form.

*
     The contents of a slot will always be of type (and T_1 ... T_n)
     where T_1 ...  T_n are the values of the :type slot options
     contained in all of the slot specifiers.  If no slot specifier
     contains the :type slot option, the contents of the slot will
     always be of type t.  The consequences of attempting to store in a
     slot a value that does not satisfy the type of the slot are
     undefined.

*
     The set of initialization arguments that initialize a given slot is
     the union of the initialization arguments declared in the :initarg
     slot options in all the slot specifiers.

*
     The documentation string for a slot is the value of the
     :documentation slot option in the most specific slot specifier that
     contains one.  If no slot specifier contains a :documentation slot
     option, the slot has no documentation string.

   A consequence of the allocation rule is that a shared slot can be
shadowed.  For example, if a class C_1 defines a slot named S whose
value for the :allocation slot option is :class, that slot is accessible
in instances of C_1 and all of its subclasses.  However, if C_2 is a
subclass of C_1 and also defines a slot named S, C_1's slot is not
shared by instances of C_2 and its subclasses.  When a class C_1 defines
a shared slot, any subclass C_2 of C_1 will share this single slot
unless the defclass form for C_2 specifies a slot of the same name or
there is a superclass of C_2 that precedes C_1 in the class precedence
list of C_2 that defines a slot of the same name.

   A consequence of the type rule is that the value of a slot satisfies
the type constraint of each slot specifier that contributes to that
slot.  Because the result of attempting to store in a slot a value that
does not satisfy the type constraint for the slot is undefined, the
value in a slot might fail to satisfy its type constraint.

   The :reader, :writer, and :accessor slot options create methods
rather than define the characteristics of a slot.  Reader and writer
methods are inherited in the sense described in *note Inheritance of
Methods::.

   Methods that access slots use only the name of the slot and the type
of the slot's value.  Suppose a superclass provides a method that
expects to access a shared slot of a given name, and a subclass defines
a local slot with the same name.  If the method provided by the
superclass is used on an instance of the subclass, the method accesses
the local slot.


File: gcl.info,  Node: Generic Functions and Methods,  Next: Objects Dictionary,  Prev: Slots,  Up: Objects

7.6 Generic Functions and Methods
=================================

* Menu:

* Introduction to Generic Functions::
* Introduction to Methods::
* Agreement on Parameter Specializers and Qualifiers::
* Congruent Lambda-lists for all Methods of a Generic Function::
* Keyword Arguments in Generic Functions and Methods::
* Method Selection and Combination::
* Inheritance of Methods::


File: gcl.info,  Node: Introduction to Generic Functions,  Next: Introduction to Methods,  Prev: Generic Functions and Methods,  Up: Generic Functions and Methods

7.6.1 Introduction to Generic Functions
---------------------------------------

A generic function is a function whose behavior depends on the classes
or identities of the arguments supplied to it.  A generic function
object is associated with a set of methods, a lambda list, a method
combination_2, and other information.

   Like an ordinary function, a generic function takes arguments,
performs a series of operations, and perhaps returns useful values.  An
ordinary function has a single body of code that is always executed when
the function is called.  A generic function has a set of bodies of code
of which a subset is selected for execution.  The selected bodies of
code and the manner of their combination are determined by the classes
or identities of one or more of the arguments to the generic function
and by its method combination.

   Ordinary functions and generic functions are called with identical
syntax.

   Generic functions are true functions that can be passed as arguments
and used as the first argument to funcall and apply.

   A binding of a function name to a generic function can be established
in one of several ways.  It can be established in the global environment
by ensure-generic-function, defmethod (implicitly, due to
ensure-generic-function) or defgeneric (also implicitly, due to
ensure-generic-function).

   No standardized mechanism is provided for establishing a binding of a
function name to a generic function in the lexical environment.

   When a defgeneric form is evaluated, one of three actions is taken
(due to ensure-generic-function):

*
     If a generic function of the given name already exists, the
     existing generic function object is modified.  Methods specified by
     the current defgeneric form are added, and any methods in the
     existing generic function that were defined by a previous
     defgeneric form are removed.  Methods added by the current
     defgeneric form might replace methods defined by defmethod,
     defclass, define-condition, or defstruct.  No other methods in the
     generic function are affected or replaced.

*
     If the given name names an ordinary function, a macro, or a special
     operator, an error is signaled.

*
     Otherwise a generic function is created with the methods specified
     by the method definitions in the defgeneric form.

   Some operators permit specification of the options of a generic
function, such as the type of method combination it uses or its argument
precedence order.  These operators will be referred to as "operators
that specify generic function options."

   The only standardized operator in this category is defgeneric.

   Some operators define methods for a generic function.  These
operators will be referred to as method-defining operators ; their
associated forms are called method-defining forms.  The standardized
method-defining operators are listed in Figure 7-2.

  defgeneric        defmethod  defclass  
  define-condition  defstruct            

  Figure 7-2: Standardized Method-Defining Operators


   Note that of the standardized method-defining operators only
defgeneric can specify generic function options.  defgeneric and any
implementation-defined operators that can specify generic function
options are also referred to as "operators that specify generic function
options."


File: gcl.info,  Node: Introduction to Methods,  Next: Agreement on Parameter Specializers and Qualifiers,  Prev: Introduction to Generic Functions,  Up: Generic Functions and Methods

7.6.2 Introduction to Methods
-----------------------------

Methods define the class-specific or identity-specific behavior and
operations of a generic function.

   A method object is associated with code that implements the method's
behavior, a sequence of parameter specializers that specify when the
given method is applicable, a lambda list, and a sequence of qualifiers
that are used by the method combination facility to distinguish among
methods.

   A method object is not a function and cannot be invoked as a
function.  Various mechanisms in the object system take a method object
and invoke its method function, as is the case when a generic function
is invoked.  When this occurs it is said that the method is invoked or
called.

   A method-defining form contains the code that is to be run when the
arguments to the generic function cause the method that it defines to be
invoked.  When a method-defining form is evaluated, a method object is
created and one of four actions is taken:

*
     If a generic function of the given name already exists and if a
     method object already exists that agrees with the new one on
     parameter specializers and qualifiers, the new method object
     replaces the old one.  For a definition of one method agreeing with
     another on parameter specializers and qualifiers, see *note
     Agreement on Parameter Specializers and Qualifiers::.

*
     If a generic function of the given name already exists and if there
     is no method object that agrees with the new one on parameter
     specializers and qualifiers, the existing generic function object
     is modified to contain the new method object.

*
     If the given name names an ordinary function, a macro, or a special
     operator, an error is signaled.

*
     Otherwise a generic function is created with the method specified
     by the method-defining form.

   If the lambda list of a new method is not congruent with the lambda
list of the generic function, an error is signaled.  If a
method-defining operator that cannot specify generic function options
creates a new generic function, a lambda list for that generic function
is derived from the lambda list of the method in the method-defining
form in such a way as to be congruent with it.  For a discussion of
congruence , see *note Congruent Lambda-lists for all Methods of a
Generic Function::.

   Each method has a specialized lambda list, which determines when that
method can be applied.  A specialized lambda list is like an ordinary
lambda list except that a specialized parameter may occur instead of the
name of a required parameter.  A specialized parameter is a list
(variable-name parameter-specializer-name), where
parameter-specializer-name is one of the following:

a symbol
     denotes a parameter specializer which is the class named by that
     symbol.

a class
     denotes a parameter specializer which is the class itself.

(eql form)
     denotes a parameter specializer which satisfies the type specifier
     (eql object), where object is the result of evaluating form.  The
     form form is evaluated in the lexical environment in which the
     method-defining form is evaluated.  Note that form is evaluated
     only once, at the time the method is defined, not each time the
     generic function is called.

   Parameter specializer names are used in macros intended as the
user-level interface (defmethod), while parameter specializers are used
in the functional interface.

   Only required parameters may be specialized, and there must be a
parameter specializer for each required parameter.  For notational
simplicity, if some required parameter in a specialized lambda list in a
method-defining form is simply a variable name, its parameter
specializer defaults to the class t.

   Given a generic function and a set of arguments, an applicable method
is a method for that generic function whose parameter specializers are
satisfied by their corresponding arguments.  The following definition
specifies what it means for a method to be applicable and for an
argument to satisfy a parameter specializer.

   Let < A_1, ..., A_n> be the required arguments to a generic function
in order.  Let < P_1, ..., P_n> be the parameter specializers
corresponding to the required parameters of the method M in order.  The
method M is applicable when each A_i is of the type specified by the
type specifier P_i.  Because every valid parameter specializer is also a
valid type specifier, the function typep can be used during method
selection to determine whether an argument satisfies a parameter
specializer.

   A method all of whose parameter specializers are the class t is
called a default method ; it is always applicable but may be shadowed by
a more specific method.

   Methods can have qualifiers, which give the method combination
procedure a way to distinguish among methods.  A method that has one or
more qualifiers is called a qualified method.  A method with no
qualifiers is called an unqualified method.  A qualifier is any
non-list.  The qualifiers defined by the standardized method combination
types are symbols.

   In this specification, the terms "primary method" and "auxiliary
method" are used to partition methods within a method combination type
according to their intended use.  In standard method combination,
primary methods are unqualified methods and auxiliary methods are
methods with a single qualifier that is one of :around, :before, or
:after.  Methods with these qualifiers are called around methods, before
methods, and after methods, respectively.  When a method combination
type is defined using the short form of define-method-combination,
primary methods are methods qualified with the name of the type of
method combination, and auxiliary methods have the qualifier :around.
Thus the terms "primary method" and "auxiliary method" have only a
relative definition within a given method combination type.


File: gcl.info,  Node: Agreement on Parameter Specializers and Qualifiers,  Next: Congruent Lambda-lists for all Methods of a Generic Function,  Prev: Introduction to Methods,  Up: Generic Functions and Methods

7.6.3 Agreement on Parameter Specializers and Qualifiers
--------------------------------------------------------

Two methods are said to agree with each other on parameter specializers
and qualifiers if the following conditions hold:

1.
     Both methods have the same number of required parameters.  Suppose
     the parameter specializers of the two methods are P_{1,1}...
     P_{1,n} and P_{2,1}...  P_{2,n}.

2.
     For each 1<= i<= n, P_{1,i} agrees with P_{2,i}.  The parameter
     specializer P_{1,i} agrees with P_{2,i} if P_{1,i} and P_{2,i} are
     the same class or if P_{1,i}=(eql object_1), P_{2,i}=(eql
     object_2), and (eql object_1 object_2).  Otherwise P_{1,i} and
     P_{2,i} do not agree.

3.
     The two lists of qualifiers are the same under equal.


File: gcl.info,  Node: Congruent Lambda-lists for all Methods of a Generic Function,  Next: Keyword Arguments in Generic Functions and Methods,  Prev: Agreement on Parameter Specializers and Qualifiers,  Up: Generic Functions and Methods

7.6.4 Congruent Lambda-lists for all Methods of a Generic Function
------------------------------------------------------------------

These rules define the congruence of a set of lambda lists, including
the lambda list of each method for a given generic function and the
lambda list specified for the generic function itself, if given.

1.
     Each lambda list must have the same number of required parameters.

2.
     Each lambda list must have the same number of optional parameters.
     Each method can supply its own default for an optional parameter.

3.
     If any lambda list mentions &rest or &key, each lambda list must
     mention one or both of them.

4.
     If the generic function lambda list mentions &key, each method must
     accept all of the keyword names mentioned after &key, either by
     accepting them explicitly, by specifying &allow-other-keys, or by
     specifying &rest but not &key.  Each method can accept additional
     keyword arguments of its own.  The checking of the validity of
     keyword names is done in the generic function, not in each method.
     A method is invoked as if the keyword argument pair whose name is
     :allow-other-keys and whose value is true were supplied, though no
     such argument pair will be passed.

5.
     The use of &allow-other-keys need not be consistent across lambda
     lists.  If &allow-other-keys is mentioned in the lambda list of any
     applicable method or of the generic function, any keyword arguments
     may be mentioned in the call to the generic function.

6.
     The use of &aux need not be consistent across methods.

     If a method-defining operator that cannot specify generic function
     options creates a generic function, and if the lambda list for the
     method mentions keyword arguments, the lambda list of the generic
     function will mention &key (but no keyword arguments).


File: gcl.info,  Node: Keyword Arguments in Generic Functions and Methods,  Next: Method Selection and Combination,  Prev: Congruent Lambda-lists for all Methods of a Generic Function,  Up: Generic Functions and Methods

7.6.5 Keyword Arguments in Generic Functions and Methods
--------------------------------------------------------

When a generic function or any of its methods mentions &key in a lambda
list, the specific set of keyword arguments accepted by the generic
function varies according to the applicable methods.  The set of keyword
arguments accepted by the generic function for a particular call is the
union of the keyword arguments accepted by all applicable methods and
the keyword arguments mentioned after &key in the generic function
definition, if any.  A method that has &rest but not &key does not
affect the set of acceptable keyword arguments.  If the lambda list of
any applicable method or of the generic function definition contains
&allow-other-keys, all keyword arguments are accepted by the generic
function.

   The lambda list congruence rules require that each method accept all
of the keyword arguments mentioned after &key in the generic function
definition, by accepting them explicitly, by specifying
&allow-other-keys, or by specifying &rest but not &key.  Each method can
accept additional keyword arguments of its own, in addition to the
keyword arguments mentioned in the generic function definition.

   If a generic function is passed a keyword argument that no applicable
method accepts, an error should be signaled; see *note Error Checking in
Function Calls::.

* Menu:

* Examples of Keyword Arguments in Generic Functions and Methods::


File: gcl.info,  Node: Examples of Keyword Arguments in Generic Functions and Methods,  Prev: Keyword Arguments in Generic Functions and Methods,  Up: Keyword Arguments in Generic Functions and Methods

7.6.5.1 Examples of Keyword Arguments in Generic Functions and Methods
......................................................................

For example, suppose there are two methods defined for width as follows:

      (defmethod width ((c character-class) &key font) ...)

      (defmethod width ((p picture-class) &key pixel-size) ...)

Assume that there are no other methods and no generic function
definition for width.  The evaluation of the following form should
signal an error because the keyword argument :pixel-size is not accepted
by the applicable method.

      (width (make-instance `character-class :char #\Q)
             :font 'baskerville :pixel-size 10)

   The evaluation of the following form should signal an error.

      (width (make-instance `picture-class :glyph (glyph #\Q))
             :font 'baskerville :pixel-size 10)

   The evaluation of the following form will not signal an error if the
class named character-picture-class is a subclass of both picture-class
and character-class.

      (width (make-instance `character-picture-class :char #\Q)
             :font 'baskerville :pixel-size 10)


File: gcl.info,  Node: Method Selection and Combination,  Next: Inheritance of Methods,  Prev: Keyword Arguments in Generic Functions and Methods,  Up: Generic Functions and Methods

7.6.6 Method Selection and Combination
--------------------------------------

When a generic function is called with particular arguments, it must
determine the code to execute.  This code is called the effective method
for those arguments.  The effective method is a combination of the
applicable methods in the generic function that calls some or all of the
methods.

   If a generic function is called and no methods are applicable, the
generic function no-applicable-method is invoked, with the results from
that call being used as the results of the call to the original generic
function.  Calling no-applicable-method takes precedence over checking
for acceptable keyword arguments; see *note Keyword Arguments in Generic
Functions and Methods::.

   When the effective method has been determined, it is invoked with the
same arguments as were passed to the generic function.  Whatever values
it returns are returned as the values of the generic function.

* Menu:

* Determining the Effective Method::
* Selecting the Applicable Methods::
* Sorting the Applicable Methods by Precedence Order::
* Applying method combination to the sorted list of applicable methods::
* Standard Method Combination::
* Declarative Method Combination::
* Built-in Method Combination Types::


File: gcl.info,  Node: Determining the Effective Method,  Next: Selecting the Applicable Methods,  Prev: Method Selection and Combination,  Up: Method Selection and Combination

7.6.6.1 Determining the Effective Method
........................................

The effective method is determined by the following three-step
procedure:

1.
     Select the applicable methods.

2.
     Sort the applicable methods by precedence order, putting the most
     specific method first.

3.
     Apply method combination to the sorted list of applicable methods,
     producing the effective method.


File: gcl.info,  Node: Selecting the Applicable Methods,  Next: Sorting the Applicable Methods by Precedence Order,  Prev: Determining the Effective Method,  Up: Method Selection and Combination

7.6.6.2 Selecting the Applicable Methods
........................................

This step is described in *note Introduction to Methods::.


File: gcl.info,  Node: Sorting the Applicable Methods by Precedence Order,  Next: Applying method combination to the sorted list of applicable methods,  Prev: Selecting the Applicable Methods,  Up: Method Selection and Combination

7.6.6.3 Sorting the Applicable Methods by Precedence Order
..........................................................

To compare the precedence of two methods, their parameter specializers
are examined in order.  The default examination order is from left to
right, but an alternative order may be specified by the
:argument-precedence-order option to defgeneric or to any of the other
operators that specify generic function options.

   The corresponding parameter specializers from each method are
compared.  When a pair of parameter specializers agree, the next pair
are compared for agreement.  If all corresponding parameter specializers
agree, the two methods must have different qualifiers; in this case,
either method can be selected to precede the other.  For information
about agreement, see *note Agreement on Parameter Specializers and
Qualifiers::.

   If some corresponding parameter specializers do not agree, the first
pair of parameter specializers that do not agree determines the
precedence.  If both parameter specializers are classes, the more
specific of the two methods is the method whose parameter specializer
appears earlier in the class precedence list of the corresponding
argument.  Because of the way in which the set of applicable methods is
chosen, the parameter specializers are guaranteed to be present in the
class precedence list of the class of the argument.

   If just one of a pair of corresponding parameter specializers is (eql
object), the method with that parameter specializer precedes the other
method.  If both parameter specializers are eql expressions, the
specializers must agree (otherwise the two methods would not both have
been applicable to this argument).

   The resulting list of applicable methods has the most specific method
first and the least specific method last.


File: gcl.info,  Node: Applying method combination to the sorted list of applicable methods,  Next: Standard Method Combination,  Prev: Sorting the Applicable Methods by Precedence Order,  Up: Method Selection and Combination

7.6.6.4 Applying method combination to the sorted list of applicable methods
............................................................................

In the simple case--if standard method combination is used and all
applicable methods are primary methods--the effective method is the most
specific method.  That method can call the next most specific method by
using the function call-next-method.  The method that call-next-method
will call is referred to as the next method .  The predicate
next-method-p tests whether a next method exists.  If call-next-method
is called and there is no next most specific method, the generic
function no-next-method is invoked.

   In general, the effective method is some combination of the
applicable methods.  It is described by a form that contains calls to
some or all of the applicable methods, returns the value or values that
will be returned as the value or values of the generic function, and
optionally makes some of the methods accessible by means of
call-next-method.

   The role of each method in the effective method is determined by its
qualifiers and the specificity of the method.  A qualifier serves to
mark a method, and the meaning of a qualifier is determined by the way
that these marks are used by this step of the procedure.  If an
applicable method has an unrecognized qualifier, this step signals an
error and does not include that method in the effective method.

   When standard method combination is used together with qualified
methods, the effective method is produced as described in *note Standard
Method Combination::.

   Another type of method combination can be specified by using the
:method-combination option of defgeneric or of any of the other
operators that specify generic function options.  In this way this step
of the procedure can be customized.

   New types of method combination can be defined by using the
define-method-combination macro.


File: gcl.info,  Node: Standard Method Combination,  Next: Declarative Method Combination,  Prev: Applying method combination to the sorted list of applicable methods,  Up: Method Selection and Combination

7.6.6.5 Standard Method Combination
...................................

Standard method combination is supported by the class
standard-generic-function.  It is used if no other type of method
combination is specified or if the built-in method combination type
standard is specified.

   Primary methods define the main action of the effective method, while
auxiliary methods modify that action in one of three ways.  A primary
method has no method qualifiers.

   An auxiliary method is a method whose qualifier is :before, :after,
or :around.  Standard method combination allows no more than one
qualifier per method; if a method definition specifies more than one
qualifier per method, an error is signaled.

*
     A before method has the keyword :before as its only qualifier.  A
     before method specifies code that is to be run before any primary
     methods.

*
     An after method has the keyword :after as its only qualifier.  An
     after method specifies code that is to be run after primary
     methods.

*
     An around method has the keyword :around as its only qualifier.  An
     around method specifies code that is to be run instead of other
     applicable methods, but which might contain explicit code which
     calls some of those shadowed methods (via call-next-method).

   The semantics of standard method combination is as follows:

*
     If there are any around methods, the most specific around method is
     called.  It supplies the value or values of the generic function.

*
     Inside the body of an around method, call-next-method can be used
     to call the next method.  When the next method returns, the around
     method can execute more code, perhaps based on the returned value
     or values.  The generic function no-next-method is invoked if
     call-next-method is used and there is no applicable method to call.
     The function next-method-p may be used to determine whether a next
     method exists.

*
     If an around method invokes call-next-method, the next most
     specific around method is called, if one is applicable.  If there
     are no around methods or if call-next-method is called by the least
     specific around method, the other methods are called as follows:

     -
          All the before methods are called, in most-specific-first
          order.  Their values are ignored.  An error is signaled if
          call-next-method is used in a before method.

     -
          The most specific primary method is called.  Inside the body
          of a primary method, call-next-method may be used to call the
          next most specific primary method.  When that method returns,
          the previous primary method can execute more code, perhaps
          based on the returned value or values.  The generic function
          no-next-method is invoked if call-next-method is used and
          there are no more applicable primary methods.  The function
          next-method-p may be used to determine whether a next method
          exists.  If call-next-method is not used, only the most
          specific primary method is called.

     -
          All the after methods are called in most-specific-last order.
          Their values are ignored.  An error is signaled if
          call-next-method is used in an after method.

*
     If no around methods were invoked, the most specific primary method
     supplies the value or values returned by the generic function.  The
     value or values returned by the invocation of call-next-method in
     the least specific around method are those returned by the most
     specific primary method.

   In standard method combination, if there is an applicable method but
no applicable primary method, an error is signaled.

   The before methods are run in most-specific-first order while the
after methods are run in least-specific-first order.  The design
rationale for this difference can be illustrated with an example.
Suppose class C_1 modifies the behavior of its superclass, C_2, by
adding before methods and after methods.  Whether the behavior of the
class C_2 is defined directly by methods on C_2 or is inherited from its
superclasses does not affect the relative order of invocation of methods
on instances of the class C_1.  Class C_1's before method runs before
all of class C_2's methods.  Class C_1's after method runs after all of
class C_2's methods.

   By contrast, all around methods run before any other methods run.
Thus a less specific around method runs before a more specific primary
method.

   If only primary methods are used and if call-next-method is not used,
only the most specific method is invoked; that is, more specific methods
shadow more general ones.


File: gcl.info,  Node: Declarative Method Combination,  Next: Built-in Method Combination Types,  Prev: Standard Method Combination,  Up: Method Selection and Combination

7.6.6.6 Declarative Method Combination
......................................

The macro define-method-combination defines new forms of method
combination.  It provides a mechanism for customizing the production of
the effective method.  The default procedure for producing an effective
method is described in *note Determining the Effective Method::.  There
are two forms of define-method-combination.  The short form is a simple
facility while the long form is more powerful and more verbose.  The
long form resembles defmacro in that the body is an expression that
computes a Lisp form; it provides mechanisms for implementing arbitrary
control structures within method combination and for arbitrary
processing of method qualifiers.


File: gcl.info,  Node: Built-in Method Combination Types,  Prev: Declarative Method Combination,  Up: Method Selection and Combination

7.6.6.7 Built-in Method Combination Types
.........................................

The object system provides a set of built-in method combination types.
To specify that a generic function is to use one of these method
combination types, the name of the method combination type is given as
the argument to the :method-combination option to defgeneric or to the
:method-combination option to any of the other operators that specify
generic function options.

   The names of the built-in method combination types are listed in
Figure 7-3.

  +    append  max  nconc  progn     
  and  list    min  or     standard  

  Figure 7-3: Built-in Method Combination Types


   The semantics of the standard built-in method combination type is
described in *note Standard Method Combination::.  The other built-in
method combination types are called simple built-in method combination
types.

   The simple built-in method combination types act as though they were
defined by the short form of define-method-combination.  They recognize
two roles for methods:

*
     An around method has the keyword symbol :around as its sole
     qualifier.  The meaning of :around methods is the same as in
     standard method combination.  Use of the functions call-next-method
     and next-method-p is supported in around methods.

*
     A primary method has the name of the method combination type as its
     sole qualifier.  For example, the built-in method combination type
     and recognizes methods whose sole qualifier is and; these are
     primary methods.  Use of the functions call-next-method and
     next-method-p is not supported in primary methods.

   The semantics of the simple built-in method combination types is as
follows:

*
     If there are any around methods, the most specific around method is
     called.  It supplies the value or values of the generic function.

*
     Inside the body of an around method, the function call-next-method
     can be used to call the next method.  The generic function
     no-next-method is invoked if call-next-method is used and there is
     no applicable method to call.  The function next-method-p may be
     used to determine whether a next method exists.  When the next
     method returns, the around method can execute more code, perhaps
     based on the returned value or values.

*
     If an around method invokes call-next-method, the next most
     specific around method is called, if one is applicable.  If there
     are no around methods or if call-next-method is called by the least
     specific around method, a Lisp form derived from the name of the
     built-in method combination type and from the list of applicable
     primary methods is evaluated to produce the value of the generic
     function.  Suppose the name of the method combination type is
     operator and the call to the generic function is of the form

                     (generic-function a_1... a_n)

     Let M_1,...,M_k be the applicable primary methods in order; then
     the derived Lisp form is

                            (operator < M_1
     a_1...  a_n>...< M_k a_1...  a_n>)

     If the expression < M_i a_1...  a_n> is evaluated, the method M_i
     will be applied to the arguments a_1...  a_n.  For example, if
     operator is or, the expression < M_i a_1...  a_n> is evaluated only
     if < M_j a_1...  a_n>, 1<= j<i, returned nil.

     The default order for the primary methods is :most-specific-first.
     However, the order can be reversed by supplying :most-specific-last
     as the second argument to the :method-combination option.

   The simple built-in method combination types require exactly one
qualifier per method.  An error is signaled if there are applicable
methods with no qualifiers or with qualifiers that are not supported by
the method combination type.  An error is signaled if there are
applicable around methods and no applicable primary methods.


File: gcl.info,  Node: Inheritance of Methods,  Prev: Method Selection and Combination,  Up: Generic Functions and Methods

7.6.7 Inheritance of Methods
----------------------------

A subclass inherits methods in the sense that any method applicable to
all instances of a class is also applicable to all instances of any
subclass of that class.

   The inheritance of methods acts the same way regardless of which of
the method-defining operators created the methods.

   The inheritance of methods is described in detail in *note Method
Selection and Combination::.


File: gcl.info,  Node: Objects Dictionary,  Prev: Generic Functions and Methods,  Up: Objects

7.7 Objects Dictionary
======================

* Menu:

* function-keywords::
* ensure-generic-function::
* allocate-instance::
* reinitialize-instance::
* shared-initialize::
* update-instance-for-different-class::
* update-instance-for-redefined-class::
* change-class::
* slot-boundp::
* slot-exists-p::
* slot-makunbound::
* slot-missing::
* slot-unbound::
* slot-value::
* method-qualifiers::
* no-applicable-method::
* no-next-method::
* remove-method::
* make-instance::
* make-instances-obsolete::
* make-load-form::
* make-load-form-saving-slots::
* with-accessors::
* with-slots::
* defclass::
* defgeneric::
* defmethod::
* find-class::
* next-method-p::
* call-method::
* call-next-method::
* compute-applicable-methods::
* define-method-combination::
* find-method::
* add-method::
* initialize-instance::
* class-name::
* setf class-name::
* class-of::
* unbound-slot::
* unbound-slot-instance::


File: gcl.info,  Node: function-keywords,  Next: ensure-generic-function,  Prev: Objects Dictionary,  Up: Objects Dictionary

7.7.1 function-keywords [Standard Generic Function]
---------------------------------------------------

Syntax::
........

'function-keywords' method => keys, allow-other-keys-p

Method Signatures::
...................

'function-keywords' (method standard-method)

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

method--a method.

   keys--a list.

   allow-other-keys-p--a generalized boolean.

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

Returns the keyword parameter specifiers for a method.

   Two values are returned: a list of the explicitly named keywords and
a generalized boolean that states whether &allow-other-keys had been
specified in the method definition.

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

      (defmethod gf1 ((a integer) &optional (b 2)
                      &key (c 3) ((:dee d) 4) e ((eff f)))
        (list a b c d e f))
     =>  #<STANDARD-METHOD GF1 (INTEGER) 36324653>
      (find-method #'gf1 '() (list (find-class 'integer)))
     =>  #<STANDARD-METHOD GF1 (INTEGER) 36324653>
      (function-keywords *)
     =>  (:C :DEE :E EFF), false
      (defmethod gf2 ((a integer))
        (list a b c d e f))
     =>  #<STANDARD-METHOD GF2 (INTEGER) 42701775>
      (function-keywords (find-method #'gf1 '() (list (find-class 'integer))))
     =>  (), false
      (defmethod gf3 ((a integer) &key b c d &allow-other-keys)
        (list a b c d e f))
      (function-keywords *)
     =>  (:B :C :D), true

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

defmethod

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

*note defmethod::


File: gcl.info,  Node: ensure-generic-function,  Next: allocate-instance,  Prev: function-keywords,  Up: Objects Dictionary

7.7.2 ensure-generic-function [Function]
----------------------------------------

'ensure-generic-function' function-name &key argument-precedence-order
declare documentation environment generic-function-class lambda-list
method-class method-combination
=> generic-function

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

function-name--a function name.

   The keyword arguments correspond to the option arguments of
defgeneric, except that the :method-class and :generic-function-class
arguments can be class objects as well as names.

   Method-combination - method combination object.

   Environment - the same as the &environment argument to macro
expansion functions and is used to distinguish between compile-time and
run-time environments.

   [Editorial Note by KMP: What about documentation.  Missing from this
arguments enumeration, and confusing in description below.]

   generic-function--a generic function object.

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

The function ensure-generic-function is used to define a globally named
generic function with no methods or to specify or modify options and
declarations that pertain to a globally named generic function as a
whole.

   If function-name is not fbound in the global environment, a new
generic function is created.  If

   (fdefinition function-name)

   is an ordinary function, a macro, or a special operator, an error is
signaled.

   If function-name is a list, it must be of the form (setf symbol).  If
function-name specifies a generic function that has a different value
for any of the following arguments, the generic function is modified to
have the new value: :argument-precedence-order, :declare,
:documentation, :method-combination.

   If function-name specifies a generic function that has a different
value for the :lambda-list argument, and the new value is congruent with
the lambda lists of all existing methods or there are no methods, the
value is changed; otherwise an error is signaled.

   If function-name specifies a generic function that has a different
value for the :generic-function-class argument and if the new generic
function class is compatible with the old, change-class is called to
change the class of the generic function; otherwise an error is
signaled.

   If function-name specifies a generic function that has a different
value for the :method-class argument, the value is changed, but any
existing methods are not changed.

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

Existing function binding of function-name.

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

If

   (fdefinition function-name)

   is an ordinary function, a macro, or a special operator, an error of
type error is signaled.

   If function-name specifies a generic function that has a different
value for the :lambda-list argument, and the new value is not congruent
with the lambda list of any existing method, an error of type error is
signaled.

   If function-name specifies a generic function that has a different
value for the :generic-function-class argument and if the new generic
function class not is compatible with the old, an error of type error is
signaled.

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

*note defgeneric::


File: gcl.info,  Node: allocate-instance,  Next: reinitialize-instance,  Prev: ensure-generic-function,  Up: Objects Dictionary

7.7.3 allocate-instance [Standard Generic Function]
---------------------------------------------------

Syntax::
........

'allocate-instance' class &rest initargs &key &allow-other-keys =>
new-instance

Method Signatures::
...................

'allocate-instance' (class standard-class) &rest initargs

   'allocate-instance' (class structure-class) &rest initargs

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

class--a class.

   initargs--a list of keyword/value pairs (initialization argument
names and values).

   new-instance--an object whose class is class.

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

The generic function allocate-instance creates and returns a new
instance of the class, without initializing it.  When the class is a
standard class, this means that the slots are unbound; when the class is
a structure class, this means the slots' values are unspecified.

   The caller of allocate-instance is expected to have already checked
the initialization arguments.

   The generic function allocate-instance is called by make-instance, as
described in *note Object Creation and Initialization::.

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

*note defclass:: , *note make-instance:: , *note class-of:: , *note
Object Creation and Initialization::

Notes::
.......

The consequences of adding methods to allocate-instance is unspecified.
This capability might be added by the Metaobject Protocol.


File: gcl.info,  Node: reinitialize-instance,  Next: shared-initialize,  Prev: allocate-instance,  Up: Objects Dictionary

7.7.4 reinitialize-instance [Standard Generic Function]
-------------------------------------------------------

Syntax::
........

'reinitialize-instance' instance &rest initargs &key &allow-other-keys
=> instance

Method Signatures::
...................

'reinitialize-instance' (instance standard-object) &rest initargs

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

instance--an object.

   initargs--an initialization argument list.

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

The generic function reinitialize-instance can be used to change the
values of local slots of an instance according to initargs.  This
generic function can be called by users.

   The system-supplied primary method for reinitialize-instance checks
the validity of initargs and signals an error if an initarg is supplied
that is not declared as valid.  The method then calls the generic
function shared-initialize with the following arguments: the instance,
nil (which means no slots should be initialized according to their
initforms), and the initargs it received.

Side Effects::
..............

The generic function reinitialize-instance changes the values of local
slots.

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

The system-supplied primary method for reinitialize-instance signals an
error if an initarg is supplied that is not declared as valid.

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

*note Initialize-Instance:: , *note Shared-Initialize:: , *note
update-instance-for-redefined-class:: , *note
update-instance-for-different-class:: , *note slot-boundp:: , *note
slot-makunbound:: , *note Reinitializing an Instance::, *note Rules for
Initialization Arguments::, *note Declaring the Validity of
Initialization Arguments::

Notes::
.......

Initargs are declared as valid by using the :initarg option to defclass,
or by defining methods for reinitialize-instance or shared-initialize.
The keyword name of each keyword parameter specifier in the lambda list
of any method defined on reinitialize-instance or shared-initialize is
declared as a valid initialization argument name for all classes for
which that method is applicable.


File: gcl.info,  Node: shared-initialize,  Next: update-instance-for-different-class,  Prev: reinitialize-instance,  Up: Objects Dictionary

7.7.5 shared-initialize [Standard Generic Function]
---------------------------------------------------

Syntax::
........

'shared-initialize' instance slot-names &rest initargs &key
&allow-other-keys => instance

Method Signatures::
...................

'shared-initialize' (instance standard-object) slot-names &rest initargs

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

instance--an object.

   slot-names--a list or t.

   initargs--a list of keyword/value pairs (of initialization argument
names and values).

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

The generic function shared-initialize is used to fill the slots of an
instance using initargs and :initform forms.  It is called when an
instance is created, when an instance is re-initialized, when an
instance is updated to conform to a redefined class, and when an
instance is updated to conform to a different class.  The generic
function shared-initialize is called by the system-supplied primary
method for initialize-instance, reinitialize-instance,
update-instance-for-redefined-class, and
update-instance-for-different-class.

   The generic function shared-initialize takes the following arguments:
the instance to be initialized, a specification of a set of slot-names
accessible in that instance, and any number of initargs.  The arguments
after the first two must form an initialization argument list.  The
system-supplied primary method on shared-initialize initializes the
slots with values according to the initargs and supplied :initform
forms.  Slot-names indicates which slots should be initialized according
to their :initform forms if no initargs are provided for those slots.

   The system-supplied primary method behaves as follows, regardless of
whether the slots are local or shared:

*
     If an initarg in the initialization argument list specifies a value
     for that slot, that value is stored into the slot, even if a value
     has already been stored in the slot before the method is run.

*
     Any slots indicated by slot-names that are still unbound at this
     point are initialized according to their :initform forms.  For any
     such slot that has an :initform form, that form is evaluated in the
     lexical environment of its defining defclass form and the result is
     stored into the slot.  For example, if a before method stores a
     value in the slot, the :initform form will not be used to supply a
     value for the slot.

*
     The rules mentioned in *note Rules for Initialization Arguments::
     are obeyed.

   The slots-names argument specifies the slots that are to be
initialized according to their :initform forms if no initialization
arguments apply.  It can be a list of slot names, which specifies the
set of those slot names; or it can be the symbol t, which specifies the
set of all of the slots.

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

*note Initialize-Instance:: , *note reinitialize-instance:: , *note
update-instance-for-redefined-class:: , *note
update-instance-for-different-class:: , *note slot-boundp:: , *note
slot-makunbound:: , *note Object Creation and Initialization::, *note
Rules for Initialization Arguments::, *note Declaring the Validity of
Initialization Arguments::

Notes::
.......

Initargs are declared as valid by using the :initarg option to defclass,
or by defining methods for shared-initialize.  The keyword name of each
keyword parameter specifier in the lambda list of any method defined on
shared-initialize is declared as a valid initarg name for all classes
for which that method is applicable.

   Implementations are permitted to optimize :initform forms that
neither produce nor depend on side effects, by evaluating these forms
and storing them into slots before running any initialize-instance
methods, rather than by handling them in the primary initialize-instance
method.  (This optimization might be implemented by having the
allocate-instance method copy a prototype instance.)

   Implementations are permitted to optimize default initial value forms
for initargs associated with slots by not actually creating the complete
initialization argument list when the only method that would receive the
complete list is the method on standard-object.  In this case default
initial value forms can be treated like :initform forms.  This
optimization has no visible effects other than a performance
improvement.


File: gcl.info,  Node: update-instance-for-different-class,  Next: update-instance-for-redefined-class,  Prev: shared-initialize,  Up: Objects Dictionary

7.7.6 update-instance-for-different-class [Standard Generic Function]
---------------------------------------------------------------------

Syntax::
........

'update-instance-for-different-class' previous current &rest initargs
&key &allow-other-keys => implementation-dependent

Method Signatures::
...................

'update-instance-for-different-class' (previous standard-object)
(current standard-object) &rest initargs

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

previous--a copy of the original instance.

   current--the original instance (altered).

   initargs--an initialization argument list.

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

The generic function update-instance-for-different-class is not intended
to be called by programmers.  Programmers may write methods for it.  The
function update-instance-for-different-class is called only by the
function change-class.

   The system-supplied primary method on
update-instance-for-different-class checks the validity of initargs and
signals an error if an initarg is supplied that is not declared as
valid.  This method then initializes slots with values according to the
initargs, and initializes the newly added slots with values according to
their :initform forms.  It does this by calling the generic function
shared-initialize with the following arguments: the instance (current),
a list of names of the newly added slots, and the initargs it received.
Newly added slots are those local slots for which no slot of the same
name exists in the previous class.

   Methods for update-instance-for-different-class can be defined to
specify actions to be taken when an instance is updated.  If only after
methods for update-instance-for-different-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-different-class.

   Methods on update-instance-for-different-class can be defined to
initialize slots differently from change-class.  The default behavior of
change-class is described in *note Changing the Class of an Instance::.

   The arguments to update-instance-for-different-class are computed by
change-class.  When change-class is invoked on an instance, a copy of
that instance is made; change-class then destructively alters the
original instance.  The first argument to
update-instance-for-different-class, previous, is that copy; it holds
the old slot values temporarily.  This argument has dynamic extent
within change-class; if it is referenced in any way once
update-instance-for-different-class returns, the results are undefined.
The second argument to update-instance-for-different-class, current, is
the altered original instance.  The intended use of previous is to
extract old slot values by using slot-value or with-slots or by invoking
a reader generic function, or to run other methods that were applicable
to instances of the original class.

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

See the example for the function change-class.

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

The system-supplied primary method on
update-instance-for-different-class signals an error if an
initialization argument is supplied that is not declared as valid.

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

*note change-class:: , *note Shared-Initialize:: , *note Changing the
Class of an Instance::, *note Rules for Initialization Arguments::,
*note Declaring the Validity of Initialization Arguments::

Notes::
.......

Initargs are declared as valid by using the :initarg option to defclass,
or by defining methods for update-instance-for-different-class or
shared-initialize.  The keyword name of each keyword parameter specifier
in the lambda list of any method defined on
update-instance-for-different-class or shared-initialize is declared as
a valid initarg name for all classes for which that method is
applicable.

   The value returned by update-instance-for-different-class is ignored
by change-class.


File: gcl.info,  Node: update-instance-for-redefined-class,  Next: change-class,  Prev: update-instance-for-different-class,  Up: Objects Dictionary

7.7.7 update-instance-for-redefined-class [Standard Generic Function]
---------------------------------------------------------------------

Syntax::
........

'update-instance-for-redefined-class' instance added-slots
discarded-slots property-list &rest initargs &key &allow-other-keys
=> {result}*

Method Signatures::
...................

'update-instance-for-redefined-class' (instance standard-object)
added-slots discarded-slots property-list &rest initargs

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

instance--an object.

   added-slots--a list.

   discarded-slots--a list.

   property-list--a list.

   initargs--an initialization argument list.

   result--an object.

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

The generic function update-instance-for-redefined-class is not intended
to be called by programmers.  Programmers may write methods for it.  The
generic function update-instance-for-redefined-class is called by the
mechanism activated by make-instances-obsolete.

   The system-supplied primary method on
update-instance-for-redefined-class checks the validity of initargs and
signals an error if an initarg is supplied that is not declared as
valid.  This method then initializes slots with values according to the
initargs, and initializes the newly added-slots with values according to
their :initform forms.  It does this by calling the generic function
shared-initialize with the following arguments: the instance, a list of
names of the newly added-slots to instance, and the initargs it
received.  Newly added-slots are those local slots for which no slot of
the same name exists in the old version of the class.

   When make-instances-obsolete is invoked or when a class has been
redefined and an instance is being updated, a property-list is created
that captures the slot names and values of all the discarded-slots with
values in the original instance.  The structure of the instance is
transformed so that it conforms to the current class definition.  The
arguments to update-instance-for-redefined-class are this transformed
instance, a list of added-slots to the instance, a list discarded-slots
from the instance, and the property-list containing the slot names and
values for slots that were discarded and had values.  Included in this
list of discarded slots are slots that were local in the old class and
are shared in the new class.

   The value returned by update-instance-for-redefined-class is ignored.

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


      (defclass position () ())

      (defclass x-y-position (position)
          ((x :initform 0 :accessor position-x)
           (y :initform 0 :accessor position-y)))

     ;;; It turns out polar coordinates are used more than Cartesian
     ;;; coordinates, so the representation is altered and some new
     ;;; accessor methods are added.

      (defmethod update-instance-for-redefined-class :before
         ((pos x-y-position) added deleted plist &key)
        ;; Transform the x-y coordinates to polar coordinates
        ;; and store into the new slots.
        (let ((x (getf plist 'x))
              (y (getf plist 'y)))
          (setf (position-rho pos) (sqrt (+ (* x x) (* y y)))
                (position-theta pos) (atan y x))))

      (defclass x-y-position (position)
          ((rho :initform 0 :accessor position-rho)
           (theta :initform 0 :accessor position-theta)))

     ;;; All instances of the old x-y-position class will be updated
     ;;; automatically.

     ;;; The new representation is given the look and feel of the old one.

      (defmethod position-x ((pos x-y-position))
         (with-slots (rho theta) pos (* rho (cos theta))))

      (defmethod (setf position-x) (new-x (pos x-y-position))
         (with-slots (rho theta) pos
           (let ((y (position-y pos)))
             (setq rho (sqrt (+ (* new-x new-x) (* y y)))
                   theta (atan y new-x))
             new-x)))

      (defmethod position-y ((pos x-y-position))
         (with-slots (rho theta) pos (* rho (sin theta))))

      (defmethod (setf position-y) (new-y (pos x-y-position))
         (with-slots (rho theta) pos
           (let ((x (position-x pos)))
             (setq rho (sqrt (+ (* x x) (* new-y new-y)))
                   theta (atan new-y x))
             new-y)))


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

The system-supplied primary method on
update-instance-for-redefined-class signals an error if an initarg is
supplied that is not declared as valid.

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

*note make-instances-obsolete:: , *note Shared-Initialize:: , *note
Redefining Classes::, *note Rules for Initialization Arguments::, *note
Declaring the Validity of Initialization Arguments::

Notes::
.......

Initargs are declared as valid by using the :initarg option to defclass,
or by defining methods for update-instance-for-redefined-class or
shared-initialize.  The keyword name of each keyword parameter specifier
in the lambda list of any method defined on
update-instance-for-redefined-class or shared-initialize is declared as
a valid initarg name for all classes for which that method is
applicable.


File: gcl.info,  Node: change-class,  Next: slot-boundp,  Prev: update-instance-for-redefined-class,  Up: Objects Dictionary

7.7.8 change-class [Standard Generic Function]
----------------------------------------------

Syntax::
........

'change-class' instance new-class &key &allow-other-keys => instance

Method Signatures::
...................

'change-class' (instance standard-object) (new-class standard-class)
&rest initargs

   'change-class' (instance t) (new-class symbol) &rest initargs

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

instance--an object.

   new-class--a class designator.

   initargs--an initialization argument list.

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

The generic function change-class changes the class of an instance to
new-class.  It destructively modifies and returns the instance.

   If in the old class there is any slot of the same name as a local
slot in the new-class, the value of that slot is retained.  This means
that if the slot has a value, the value returned by slot-value after
change-class is invoked is eql to the value returned by slot-value
before change-class is invoked.  Similarly, if the slot was unbound, it
remains unbound.  The other slots are initialized as described in *note
Changing the Class of an Instance::.

   After completing all other actions, change-class invokes
update-instance-for-different-class.  The generic function
update-instance-for-different-class can be used to assign values to
slots in the transformed instance.

   See *note Initializing Newly Added Local Slots (Changing the Class of
an Instance)::.

   If the second of the above methods is selected, that method invokes
change-class on instance, (find-class new-class), and the initargs.

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


      (defclass position () ())

      (defclass x-y-position (position)
          ((x :initform 0 :initarg :x)
           (y :initform 0 :initarg :y)))

      (defclass rho-theta-position (position)
          ((rho :initform 0)
           (theta :initform 0)))

      (defmethod update-instance-for-different-class :before ((old x-y-position)
                                                              (new rho-theta-position)
                                                              &key)
        ;; Copy the position information from old to new to make new
        ;; be a rho-theta-position at the same position as old.
        (let ((x (slot-value old 'x))
              (y (slot-value old 'y)))
          (setf (slot-value new 'rho) (sqrt (+ (* x x) (* y y)))
                (slot-value new 'theta) (atan y x))))

     ;;; At this point an instance of the class x-y-position can be
     ;;; changed to be an instance of the class rho-theta-position using
     ;;; change-class:

      (setq p1 (make-instance 'x-y-position :x 2 :y 0))

      (change-class p1 'rho-theta-position)

     ;;; The result is that the instance bound to p1 is now an instance of
     ;;; the class rho-theta-position.   The update-instance-for-different-class
     ;;; method performed the initialization of the rho and theta slots based
     ;;; on the value of the x and y slots, which were maintained by
     ;;; the old instance.


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

*note update-instance-for-different-class:: , *note Changing the Class
of an Instance::

Notes::
.......

The generic function change-class has several semantic difficulties.
First, it performs a destructive operation that can be invoked within a
method on an instance that was used to select that method.  When
multiple methods are involved because methods are being combined, the
methods currently executing or about to be executed may no longer be
applicable.  Second, some implementations might use compiler
optimizations of slot access, and when the class of an instance is
changed the assumptions the compiler made might be violated.  This
implies that a programmer must not use change-class inside a method if
any methods for that generic function access any slots, or the results
are undefined.


File: gcl.info,  Node: slot-boundp,  Next: slot-exists-p,  Prev: change-class,  Up: Objects Dictionary

7.7.9 slot-boundp [Function]
----------------------------

'slot-boundp' instance slot-name => generalized-boolean

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

instance--an object.

   slot-name--a symbol naming a slot of instance.

   generalized-boolean--a generalized boolean.

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

Returns true if the slot named slot-name in instance is bound;
otherwise, returns false.

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

If no slot of the name slot-name exists in the instance, slot-missing is
called as follows:

      (slot-missing (class-of instance)
                    instance
                    slot-name
                    'slot-boundp)

   (If slot-missing is invoked and returns a value, a boolean equivalent
to its primary value is returned by slot-boundp.)

   The specific behavior depends on instance's metaclass.  An error is
never signaled if instance has metaclass standard-class.  An error is
always signaled if instance has metaclass built-in-class.  The
consequences are undefined if instance has any other metaclass-an error
might or might not be signaled in this situation.  Note in particular
that the behavior for conditions and structures is not specified.

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

*note slot-makunbound:: , *note slot-missing::

Notes::
.......

The function slot-boundp allows for writing after methods on
initialize-instance in order to initialize only those slots that have
not already been bound.

   Although no implementation is required to do so, implementors are
strongly encouraged to implement the function slot-boundp using the
function slot-boundp-using-class described in the Metaobject Protocol.


File: gcl.info,  Node: slot-exists-p,  Next: slot-makunbound,  Prev: slot-boundp,  Up: Objects Dictionary

7.7.10 slot-exists-p [Function]
-------------------------------

'slot-exists-p' object slot-name => generalized-boolean

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

object--an object.

   slot-name--a symbol.

   generalized-boolean--a generalized boolean.

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

Returns true if the object has a slot named slot-name.

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

defclass, defstruct

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

*note defclass:: , *note slot-missing::

Notes::
.......

Although no implementation is required to do so, implementors are
strongly encouraged to implement the function slot-exists-p using the
function slot-exists-p-using-class described in the Metaobject Protocol.


File: gcl.info,  Node: slot-makunbound,  Next: slot-missing,  Prev: slot-exists-p,  Up: Objects Dictionary

7.7.11 slot-makunbound [Function]
---------------------------------

'slot-makunbound' instance slot-name => instance

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

instance - instance.

   Slot-name--a symbol.

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

The function slot-makunbound restores a slot of the name slot-name in an
instance to the unbound state.

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

If no slot of the name slot-name exists in the instance, slot-missing is
called as follows:

     (slot-missing (class-of instance)
                   instance
                   slot-name
                   'slot-makunbound)

   (Any values returned by slot-missing in this case are ignored by
slot-makunbound.)

   The specific behavior depends on instance's metaclass.  An error is
never signaled if instance has metaclass standard-class.  An error is
always signaled if instance has metaclass built-in-class.  The
consequences are undefined if instance has any other metaclass-an error
might or might not be signaled in this situation.  Note in particular
that the behavior for conditions and structures is not specified.

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

*note slot-boundp:: , *note slot-missing::

Notes::
.......

Although no implementation is required to do so, implementors are
strongly encouraged to implement the function slot-makunbound using the
function slot-makunbound-using-class described in the Metaobject
Protocol.


File: gcl.info,  Node: slot-missing,  Next: slot-unbound,  Prev: slot-makunbound,  Up: Objects Dictionary

7.7.12 slot-missing [Standard Generic Function]
-----------------------------------------------

Syntax::
........

'slot-missing' class object slot-name operation &optional new-value =>
{result}*

Method Signatures::
...................

'slot-missing' (class t) object slot-name operation &optional new-value

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

class--the class of object.

   object--an object.

   slot-name--a symbol (the name of a would-be slot).

   operation--one of the symbols setf, slot-boundp, slot-makunbound, or
slot-value.

   new-value--an object.

   result--an object.

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

The generic function slot-missing is invoked when an attempt is made to
access a slot in an object whose metaclass is standard-class and the
slot of the name slot-name is not a name of a slot in that class.  The
default method signals an error.

   The generic function slot-missing is not intended to be called by
programmers.  Programmers may write methods for it.

   The generic function slot-missing may be called during evaluation of
slot-value, (setf slot-value), slot-boundp, and slot-makunbound.  For
each of these operations the corresponding symbol for the operation
argument is slot-value, setf, slot-boundp, and slot-makunbound
respectively.

   The optional new-value argument to slot-missing is used when the
operation is attempting to set the value of the slot.

   If slot-missing returns, its values will be treated as follows:

*
     If the operation is setf or slot-makunbound, any values will be
     ignored by the caller.

*
     If the operation is slot-value, only the primary value will be used
     by the caller, and all other values will be ignored.

*
     If the operation is slot-boundp, any boolean equivalent of the
     primary value of the method might be is used, and all other values
     will be ignored.

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

The default method on slot-missing signals an error of type error.

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

*note defclass:: , *note slot-exists-p:: , *note slot-value::

Notes::
.......

The set of arguments (including the class of the instance) facilitates
defining methods on the metaclass for slot-missing.


File: gcl.info,  Node: slot-unbound,  Next: slot-value,  Prev: slot-missing,  Up: Objects Dictionary

7.7.13 slot-unbound [Standard Generic Function]
-----------------------------------------------

Syntax::
........

'slot-unbound' class instance slot-name => {result}*

Method Signatures::
...................

'slot-unbound' (class t) instance slot-name

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

class--the class of the instance.

   instance--the instance in which an attempt was made to read the
unbound slot.

   slot-name--the name of the unbound slot.

   result--an object.

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

The generic function slot-unbound is called when an unbound slot is read
in an instance whose metaclass is standard-class.  The default method
signals an error

   of type unbound-slot.  The name slot of the unbound-slot condition is
initialized to the name of the offending variable, and the instance slot
of the unbound-slot condition is initialized to the offending instance.

   The generic function slot-unbound is not intended to be called by
programmers.  Programmers may write methods for it.  The function
slot-unbound is called only indirectly by slot-value.

   If slot-unbound returns, only the primary value will be used by the
caller, and all other values will be ignored.

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

The default method on slot-unbound signals an error of type
unbound-slot.

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

*note slot-makunbound::

Notes::
.......

An unbound slot may occur if no :initform form was specified for the
slot and the slot value has not been set, or if slot-makunbound has been
called on the slot.


File: gcl.info,  Node: slot-value,  Next: method-qualifiers,  Prev: slot-unbound,  Up: Objects Dictionary

7.7.14 slot-value [Function]
----------------------------

'slot-value' object slot-name => value

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

object--an object.

   name--a symbol.

   value--an object.

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

The function slot-value returns the value of the slot named slot-name in
the object.  If there is no slot named slot-name, slot-missing is
called.  If the slot is unbound, slot-unbound is called.

   The macro setf can be used with slot-value to change the value of a
slot.

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

      (defclass foo ()
        ((a :accessor foo-a :initarg :a :initform 1)
         (b :accessor foo-b :initarg :b)
         (c :accessor foo-c :initform 3)))
     =>  #<STANDARD-CLASS FOO 244020371>
      (setq foo1 (make-instance 'foo :a 'one :b 'two))
     =>  #<FOO 36325624>
      (slot-value foo1 'a) =>  ONE
      (slot-value foo1 'b) =>  TWO
      (slot-value foo1 'c) =>  3
      (setf (slot-value foo1 'a) 'uno) =>  UNO
      (slot-value foo1 'a) =>  UNO
      (defmethod foo-method ((x foo))
        (slot-value x 'a))
     =>  #<STANDARD-METHOD FOO-METHOD (FOO) 42720573>
      (foo-method foo1) =>  UNO

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

If an attempt is made to read a slot and no slot of the name slot-name
exists in the object, slot-missing is called as follows:

      (slot-missing (class-of instance)
                    instance
                    slot-name
                    'slot-value)

   (If slot-missing is invoked, its primary value is returned by
slot-value.)

   If an attempt is made to write a slot and no slot of the name
slot-name exists in the object, slot-missing is called as follows:

      (slot-missing (class-of instance)
                    instance
                    slot-name
                    'setf
                    new-value)

   (If slot-missing returns in this case, any values are ignored.)

   The specific behavior depends on object's metaclass.  An error is
never signaled if object has metaclass standard-class.  An error is
always signaled if object has metaclass built-in-class.  The
consequences are unspecified if object has any other metaclass-an error
might or might not be signaled in this situation.  Note in particular
that the behavior for conditions and structures is not specified.

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

*note slot-missing:: , *note slot-unbound:: , *note with-slots::

Notes::
.......

Although no implementation is required to do so, implementors are
strongly encouraged to implement the function slot-value using the
function slot-value-using-class described in the Metaobject Protocol.

   Implementations may optimize slot-value by compiling it inline.


File: gcl.info,  Node: method-qualifiers,  Next: no-applicable-method,  Prev: slot-value,  Up: Objects Dictionary

7.7.15 method-qualifiers [Standard Generic Function]
----------------------------------------------------

Syntax::
........

'method-qualifiers' method => qualifiers

Method Signatures::
...................

'method-qualifiers' (method standard-method)

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

method--a method.

   qualifiers--a proper list.

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

Returns a list of the qualifiers of the method.

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

      (defmethod some-gf :before ((a integer)) a)
     =>  #<STANDARD-METHOD SOME-GF (:BEFORE) (INTEGER) 42736540>
      (method-qualifiers *) =>  (:BEFORE)

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

*note define-method-combination::


File: gcl.info,  Node: no-applicable-method,  Next: no-next-method,  Prev: method-qualifiers,  Up: Objects Dictionary

7.7.16 no-applicable-method [Standard Generic Function]
-------------------------------------------------------

Syntax::
........

'no-applicable-method' generic-function &rest function-arguments =>
{result}*

Method Signatures::
...................

'no-applicable-method' (generic-function t) &rest function-arguments

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

generic-function--a generic function on which no applicable method was
found.

   function-arguments--arguments to the generic-function.

   result--an object.

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

The generic function no-applicable-method is called when a generic
function is invoked and no method on that generic function is
applicable.  The default method signals an error.

   The generic function no-applicable-method is not intended to be
called by programmers.  Programmers may write methods for it.

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

The default method signals an error of type error.

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


File: gcl.info,  Node: no-next-method,  Next: remove-method,  Prev: no-applicable-method,  Up: Objects Dictionary

7.7.17 no-next-method [Standard Generic Function]
-------------------------------------------------

Syntax::
........

'no-next-method' generic-function method &rest args => {result}*

Method Signatures::
...................

'no-next-method' (generic-function standard-generic-function) (method
standard-method) &rest args

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

generic-function - generic function to which method belongs.

   method - method that contained the call to call-next-method for which
there is no next method.

   args - arguments to call-next-method.

   result--an object.

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

The generic function no-next-method is called by call-next-method when
there is no next method.

   The generic function no-next-method is not intended to be called by
programmers.  Programmers may write methods for it.

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

The system-supplied method on no-next-method signals an error of type
error.  [Editorial Note by KMP: perhaps control-error??]

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

*note call-next-method::


File: gcl.info,  Node: remove-method,  Next: make-instance,  Prev: no-next-method,  Up: Objects Dictionary

7.7.18 remove-method [Standard Generic Function]
------------------------------------------------

Syntax::
........

'remove-method' generic-function method => generic-function

Method Signatures::
...................

'remove-method' (generic-function standard-generic-function) method

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

generic-function--a generic function.

   method--a method.

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

The generic function remove-method removes a method from
generic-function by modifying the generic-function (if necessary).

   remove-method must not signal an error if the method is not one of
the methods on the generic-function.

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

*note find-method::


File: gcl.info,  Node: make-instance,  Next: make-instances-obsolete,  Prev: remove-method,  Up: Objects Dictionary

7.7.19 make-instance [Standard Generic Function]
------------------------------------------------

Syntax::
........

'make-instance' class &rest initargs &key &allow-other-keys => instance

Method Signatures::
...................

'make-instance' (class standard-class) &rest initargs

   'make-instance' (class symbol) &rest initargs

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

class--a class, or a symbol that names a class.

   initargs--an initialization argument list.

   instance--a fresh instance of class class.

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

The generic function make-instance creates and returns a new instance of
the given class.

   If the second of the above methods is selected, that method invokes
make-instance on the arguments (find-class class) and initargs.

   The initialization arguments are checked within make-instance.

   The generic function make-instance may be used as described in *note
Object Creation and Initialization::.

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

If any of the initialization arguments has not been declared as valid,
an error of type error is signaled.

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

*note defclass:: , *note class-of:: , *note allocate-instance:: , *note
Initialize-Instance:: , *note Object Creation and Initialization::


File: gcl.info,  Node: make-instances-obsolete,  Next: make-load-form,  Prev: make-instance,  Up: Objects Dictionary

7.7.20 make-instances-obsolete [Standard Generic Function]
----------------------------------------------------------

Syntax::
........

'make-instances-obsolete' class => class

Method Signatures::
...................

'make-instances-obsolete' (class standard-class)

   'make-instances-obsolete' (class symbol)

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

class--a class designator.

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

The function make-instances-obsolete has the effect of initiating the
process of updating the instances of the class.  During updating, the
generic function update-instance-for-redefined-class will be invoked.

   The generic function make-instances-obsolete is invoked automatically
by the system when defclass has been used to redefine an existing
standard class and the set of local slots accessible in an instance is
changed or the order of slots in storage is changed.  It can also be
explicitly invoked by the user.

   If the second of the above methods is selected, that method invokes
make-instances-obsolete on (find-class class).

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

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

*note update-instance-for-redefined-class:: , *note Redefining Classes::


File: gcl.info,  Node: make-load-form,  Next: make-load-form-saving-slots,  Prev: make-instances-obsolete,  Up: Objects Dictionary

7.7.21 make-load-form [Standard Generic Function]
-------------------------------------------------

Syntax::
........

'make-load-form' object &optional environment => creation-form [,
initialization-form ]

Method Signatures::
...................

'make-load-form' (object standard-object) &optional environment

   'make-load-form' (object structure-object) &optional environment

   'make-load-form' (object condition) &optional environment

   'make-load-form' (object class) &optional environment

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

object--an object.

   environment--an environment object.

   creation-form--a form.

   initialization-form--a form.

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

The generic function make-load-form creates and returns one or two
forms, a creation-form and an initialization-form, that enable load to
construct an object equivalent to object.  Environment is an environment
object corresponding to the lexical environment in which the forms will
be processed.

   The file compiler calls make-load-form to process certain classes of
literal objects; see *note Additional Constraints on Externalizable
Objects::.

   Conforming programs may call make-load-form directly, providing
object is a generalized instance of standard-object, structure-object,
or condition.

   The creation form is a form that, when evaluated at load time, should
return an object that is equivalent to object.  The exact meaning of
equivalent depends on the type of object and is up to the programmer who
defines a method for make-load-form; see *note Literal Objects in
Compiled Files::.

   The initialization form is a form that, when evaluated at load time,
should perform further initialization of the object.  The value returned
by the initialization form is ignored.  If make-load-form returns only
one value, the initialization form is nil, which has no effect.  If
object appears as a constant in the initialization form, at load time it
will be replaced by the equivalent object constructed by the creation
form; this is how the further initialization gains access to the object.

   Both the creation-form and the initialization-form may contain
references to any externalizable object.  However, there must not be any
circular dependencies in creation forms.  An example of a circular
dependency is when the creation form for the object X contains a
reference to the object Y, and the creation form for the object Y
contains a reference to the object X.  Initialization forms are not
subject to any restriction against circular dependencies, which is the
reason that initialization forms exist; see the example of circular data
structures below.

   The creation form for an object is always evaluated before the
initialization form for that object.  When either the creation form or
the initialization form references other objects that have not been
referenced earlier in the file being compiled, the compiler ensures that
all of the referenced objects have been created before evaluating the
referencing form.  When the referenced object is of a type which the
file compiler processes using make-load-form, this involves evaluating
the creation form returned for it.  (This is the reason for the
prohibition against circular references among creation forms).

   Each initialization form is evaluated as soon as possible after its
associated creation form, as determined by data flow.  If the
initialization form for an object does not reference any other objects
not referenced earlier in the file and processed by the file compiler
using make-load-form, the initialization form is evaluated immediately
after the creation form.  If a creation or initialization form F does
contain references to such objects, the creation forms for those other
objects are evaluated before F, and the initialization forms for those
other objects are also evaluated before F whenever they do not depend on
the object created or initialized by F. Where these rules do not
uniquely determine an order of evaluation between two
creation/initialization forms, the order of evaluation is unspecified.

   While these creation and initialization forms are being evaluated,
the objects are possibly in an uninitialized state, analogous to the
state of an object between the time it has been created by
allocate-instance and it has been processed fully by
initialize-instance.  Programmers writing methods for make-load-form
must take care in manipulating objects not to depend on slots that have
not yet been initialized.

   It is implementation-dependent whether load calls eval on the forms
or does some other operation that has an equivalent effect.  For
example, the forms might be translated into different but equivalent
forms and then evaluated, they might be compiled and the resulting
functions called by load, or they might be interpreted by a
special-purpose function different from eval.  All that is required is
that the effect be equivalent to evaluating the forms.

   The method specialized on class returns a creation form using the
name of the class if the class has a proper name in environment,
signaling an error of type error if it does not have a proper name.
Evaluation of the creation form uses the name to find the class with
that name, as if by calling find-class.  If a class with that name has
not been defined, then a class may be computed in an
implementation-defined manner.  If a class cannot be returned as the
result of evaluating the creation form, then an error of type error is
signaled.

   Both conforming implementations and conforming programs may further
specialize make-load-form.

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

      (defclass obj ()
         ((x :initarg :x :reader obj-x)
          (y :initarg :y :reader obj-y)
          (dist :accessor obj-dist)))
     =>  #<STANDARD-CLASS OBJ 250020030>
      (defmethod shared-initialize :after ((self obj) slot-names &rest keys)
        (declare (ignore slot-names keys))
        (unless (slot-boundp self 'dist)
          (setf (obj-dist self)
                (sqrt (+ (expt (obj-x self) 2) (expt (obj-y self) 2))))))
     =>  #<STANDARD-METHOD SHARED-INITIALIZE (:AFTER) (OBJ T) 26266714>
      (defmethod make-load-form ((self obj) &optional environment)
        (declare (ignore environment))
        ;; Note that this definition only works because X and Y do not
        ;; contain information which refers back to the object itself.
        ;; For a more general solution to this problem, see revised example below.
        `(make-instance ',(class-of self)
                        :x ',(obj-x self) :y ',(obj-y self)))
     =>  #<STANDARD-METHOD MAKE-LOAD-FORM (OBJ) 26267532>
      (setq obj1 (make-instance 'obj :x 3.0 :y 4.0)) =>  #<OBJ 26274136>
      (obj-dist obj1) =>  5.0
      (make-load-form obj1) =>  (MAKE-INSTANCE 'OBJ :X '3.0 :Y '4.0)

   In the above example, an equivalent instance of obj is reconstructed
by using the values of two of its slots.  The value of the third slot is
derived from those two values.

   Another way to write the make-load-form method in that example is to
use make-load-form-saving-slots.  The code it generates might yield a
slightly different result from the make-load-form method shown above,
but the operational effect will be the same.  For example:

      ;; Redefine method defined above.
      (defmethod make-load-form ((self obj) &optional environment)
         (make-load-form-saving-slots self
                                      :slot-names '(x y)
                                      :environment environment))
     =>  #<STANDARD-METHOD MAKE-LOAD-FORM (OBJ) 42755655>
      ;; Try MAKE-LOAD-FORM on object created above.
      (make-load-form obj1)
     =>  (ALLOCATE-INSTANCE '#<STANDARD-CLASS OBJ 250020030>),
         (PROGN
           (SETF (SLOT-VALUE '#<OBJ 26274136> 'X) '3.0)
           (SETF (SLOT-VALUE '#<OBJ 26274136> 'Y) '4.0)
           (INITIALIZE-INSTANCE '#<OBJ 26274136>))

   In the following example, instances of my-frob are "interned" in some
way.  An equivalent instance is reconstructed by using the value of the
name slot as a key for searching existing objects.  In this case the
programmer has chosen to create a new object if no existing object is
found; alternatively an error could have been signaled in that case.

      (defclass my-frob ()
         ((name :initarg :name :reader my-name)))
      (defmethod make-load-form ((self my-frob) &optional environment)
        (declare (ignore environment))
        `(find-my-frob ',(my-name self) :if-does-not-exist :create))

   In the following example, the data structure to be dumped is
circular, because each parent has a list of its children and each child
has a reference back to its parent.  If make-load-form is called on one
object in such a structure, the creation form creates an equivalent
object and fills in the children slot, which forces creation of
equivalent objects for all of its children, grandchildren, etc.  At this
point none of the parent slots have been filled in.  The initialization
form fills in the parent slot, which forces creation of an equivalent
object for the parent if it was not already created.  Thus the entire
tree is recreated at load time.  At compile time, make-load-form is
called once for each object in the tree.  All of the creation forms are
evaluated, in implementation-dependent order, and then all of the
initialization forms are evaluated, also in implementation-dependent
order.

      (defclass tree-with-parent () ((parent :accessor tree-parent)
                                     (children :initarg :children)))
      (defmethod make-load-form ((x tree-with-parent) &optional environment)
        (declare (ignore environment))
        (values
          ;; creation form
          `(make-instance ',(class-of x) :children ',(slot-value x 'children))
          ;; initialization form
          `(setf (tree-parent ',x) ',(slot-value x 'parent))))

   In the following example, the data structure to be dumped has no
special properties and an equivalent structure can be reconstructed
simply by reconstructing the slots' contents.

      (defstruct my-struct a b c)
      (defmethod make-load-form ((s my-struct) &optional environment)
         (make-load-form-saving-slots s :environment environment))

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

The methods specialized on standard-object, structure-object, and
condition all signal an error of type error.

   It is implementation-dependent whether calling make-load-form on a
generalized instance of a system class signals an error or returns
creation and initialization forms.

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

*note compile-file:: , *note make-load-form-saving-slots:: , *note
Additional Constraints on Externalizable Objects:: *note Evaluation::,
*note Compilation::

Notes::
.......

The file compiler calls make-load-form in specific circumstances
detailed in *note Additional Constraints on Externalizable Objects::.

   Some implementations may provide facilities for defining new
subclasses of classes which are specified as system classes.  (Some
likely candidates include generic-function, method, and stream).  Such
implementations should document how the file compiler processes
instances of such classes when encountered as literal objects, and
should document any relevant methods for make-load-form.


File: gcl.info,  Node: make-load-form-saving-slots,  Next: with-accessors,  Prev: make-load-form,  Up: Objects Dictionary

7.7.22 make-load-form-saving-slots [Function]
---------------------------------------------

'make-load-form-saving-slots' object &key slot-names environment
=> creation-form, initialization-form

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

object--an object.

   slot-names--a list.

   environment--an environment object.

   creation-form--a form.

   initialization-form--a form.

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

Returns forms that, when evaluated, will construct an object equivalent
to object, without executing initialization forms.  The slots in the new
object that correspond to initialized slots in object are initialized
using the values from object.  Uninitialized slots in object are not
initialized in the new object.  make-load-form-saving-slots works for
any instance of standard-object or structure-object.

   Slot-names is a list of the names of the slots to preserve.  If
slot-names is not supplied, its value is all of the local slots.

   make-load-form-saving-slots returns two values, thus it can deal with
circular structures.  Whether the result is useful in an application
depends on whether the object's type and slot contents fully capture the
application's idea of the object's state.

   Environment is the environment in which the forms will be processed.

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

*note make-load-form:: , *note make-instance:: , *note setf:: , *note
slot-value:: , *note slot-makunbound::

Notes::
.......

make-load-form-saving-slots can be useful in user-written make-load-form
methods.

   When the object is an instance of standard-object,
make-load-form-saving-slots could return a creation form that calls
allocate-instance and an initialization form that contains calls to setf
of slot-value and slot-makunbound, though other functions of similar
effect might actually be used.


File: gcl.info,  Node: with-accessors,  Next: with-slots,  Prev: make-load-form-saving-slots,  Up: Objects Dictionary

7.7.23 with-accessors [Macro]
-----------------------------

'with-accessors' ({slot-entry}*) instance-form {declaration}* {form}*
=> {result}*

   slot-entry ::=(variable-name accessor-name )

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

variable-name--a variable name; not evaluated.

   accessor-name--a function name; not evaluated.

   instance-form--a form; evaluated.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values returned by the forms.

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

Creates a lexical environment in which the slots specified by slot-entry
are lexically available through their accessors as if they were
variables.  The macro with-accessors invokes the appropriate accessors
to access the slots specified by slot-entry.  Both setf and setq can be
used to set the value of the slot.

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

      (defclass thing ()
                ((x :initarg :x :accessor thing-x)
                 (y :initarg :y :accessor thing-y)))
     =>  #<STANDARD-CLASS THING 250020173>
      (defmethod (setf thing-x) :before (new-x (thing thing))
        (format t "~&Changing X from ~D to ~D in ~S.~
                (thing-x thing) new-x thing))
      (setq thing1 (make-instance 'thing :x 1 :y 2)) =>  #<THING 43135676>
      (setq thing2 (make-instance 'thing :x 7 :y 8)) =>  #<THING 43147374>
      (with-accessors ((x1 thing-x) (y1 thing-y))
                      thing1
        (with-accessors ((x2 thing-x) (y2 thing-y))
                        thing2
          (list (list x1 (thing-x thing1) y1 (thing-y thing1)
                      x2 (thing-x thing2) y2 (thing-y thing2))
                (setq x1 (+ y1 x2))
                (list x1 (thing-x thing1) y1 (thing-y thing1)
                      x2 (thing-x thing2) y2 (thing-y thing2))
                (setf (thing-x thing2) (list x1))
                (list x1 (thing-x thing1) y1 (thing-y thing1)
                      x2 (thing-x thing2) y2 (thing-y thing2)))))
      |>  Changing X from 1 to 9 in #<THING 43135676>.
      |>  Changing X from 7 to (9) in #<THING 43147374>.
     =>  ((1 1 2 2 7 7 8 8)
          9
          (9 9 2 2 7 7 8 8)
          (9)
          (9 9 2 2 (9) (9) 8 8))

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

defclass

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

The consequences are undefined if any accessor-name is not the name of
an accessor for the instance.

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

*note with-slots:: , *note symbol-macrolet::

Notes::
.......

A with-accessors expression of the form:


     (with-accessors (slot-entry_1 ...slot-entry_n) instance-form form_1 ...form_k)


expands into the equivalent of


     (let ((in instance-form))

      (symbol-macrolet (Q_1... Q_n) form_1 ...form_k))


where Q_i is

     (variable-name_i ()
     (accessor-name_i in))


File: gcl.info,  Node: with-slots,  Next: defclass,  Prev: with-accessors,  Up: Objects Dictionary

7.7.24 with-slots [Macro]
-------------------------

'with-slots' ({slot-entry}*) instance-form {declaration}* {form}*
=> {result}*

   slot-entry ::=slot-name | (variable-name slot-name)

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

slot-name--a slot name; not evaluated.

   variable-name--a variable name; not evaluated.

   instance-form--a form; evaluted to produce instance.

   instance--an object.

   declaration--a declare expression; not evaluated.

   forms--an implicit progn.

   results--the values returned by the forms.

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

The macro with-slots establishes a lexical environment for referring to
the slots in the instance named by the given slot-names as though they
were variables.  Within such a context the value of the slot can be
specified by using its slot name, as if it were a lexically bound
variable.  Both setf and setq can be used to set the value of the slot.

   The macro with-slots translates an appearance of the slot name as a
variable into a call to slot-value.

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

      (defclass thing ()
                ((x :initarg :x :accessor thing-x)
                 (y :initarg :y :accessor thing-y)))
     =>  #<STANDARD-CLASS THING 250020173>
      (defmethod (setf thing-x) :before (new-x (thing thing))
        (format t "~&Changing X from ~D to ~D in ~S.~
                (thing-x thing) new-x thing))
      (setq thing (make-instance 'thing :x 0 :y 1)) =>  #<THING 62310540>
      (with-slots (x y) thing (incf x) (incf y)) =>  2
      (values (thing-x thing) (thing-y thing)) =>  1, 2
      (setq thing1 (make-instance 'thing :x 1 :y 2)) =>  #<THING 43135676>
      (setq thing2 (make-instance 'thing :x 7 :y 8)) =>  #<THING 43147374>
      (with-slots ((x1 x) (y1 y))
                  thing1
        (with-slots ((x2 x) (y2 y))
                    thing2
          (list (list x1 (thing-x thing1) y1 (thing-y thing1)
                      x2 (thing-x thing2) y2 (thing-y thing2))
                (setq x1 (+ y1 x2))
                (list x1 (thing-x thing1) y1 (thing-y thing1)
                      x2 (thing-x thing2) y2 (thing-y thing2))
                (setf (thing-x thing2) (list x1))
                (list x1 (thing-x thing1) y1 (thing-y thing1)
                      x2 (thing-x thing2) y2 (thing-y thing2)))))
      |>  Changing X from 7 to (9) in #<THING 43147374>.
     =>  ((1 1 2 2 7 7 8 8)
          9
          (9 9 2 2 7 7 8 8)
          (9)
          (9 9 2 2 (9) (9) 8 8))

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

defclass

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

The consequences are undefined if any slot-name is not the name of a
slot in the instance.

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

*note with-accessors:: , *note slot-value:: , *note symbol-macrolet::

Notes::
.......

A with-slots expression of the form:


     (with-slots (slot-entry_1 ...slot-entry_n) instance-form form_1 ...form_k)


expands into the equivalent of


     (let ((in instance-form))

      (symbol-macrolet (Q_1... Q_n) form_1 ...form_k))


where Q_i is

     (slot-entry_i ()
     (slot-value in 'slot-entry_i))

if slot-entry_i is a symbol and is

     (variable-name_i ()
     (slot-value in 'slot-name_i))

if slot-entry_i is of the form

     (variable-name_i
     slot-name_i)


File: gcl.info,  Node: defclass,  Next: defgeneric,  Prev: with-slots,  Up: Objects Dictionary

7.7.25 defclass [Macro]
-----------------------

'defclass' class-name ({superclass-name}*) ({slot-specifier}*)
[[!class-option]]
=> new-class

    slot-specifier::=slot-name | (slot-name [[!slot-option]])

    slot-name::= symbol

    slot-option::={:reader reader-function-name}* |
                         {:writer writer-function-name}* |
                         {:accessor reader-function-name}* |
                         {:allocation allocation-type} |
                         {:initarg initarg-name}* |
                         {:initform form} |
                         {:type type-specifier} |
                         {:documentation string}

    function-name::= {symbol | (setf symbol)}

    class-option::=(:default-initargs . initarg-list) |
                          (:documentation string) |
                          (:metaclass class-name)

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

Class-name--a non-nil symbol.

   Superclass-name-a non-nil symbol.

   Slot-name-a symbol.  The slot-name argument is a symbol that is
syntactically valid for use as a variable name.

   Reader-function-name--a non-nil symbol.  :reader can be supplied more
than once for a given slot.

   Writer-function-name--a generic function name.  :writer can be
supplied more than once for a given slot.

   Reader-function-name--a non-nil symbol.  :accessor can be supplied
more than once for a given slot.

   Allocation-type--(member :instance :class).  :allocation can be
supplied once at most for a given slot.

   Initarg-name--a symbol.  :initarg can be supplied more than once for
a given slot.

   Form--a form.  :init-form can be supplied once at most for a given
slot.

   Type-specifier--a type specifier.  :type can be supplied once at most
for a given slot.

   Class-option-- refers to the class as a whole or to all class slots.

   Initarg-list--a list of alternating initialization argument names and
default initial value forms.  :default-initargs can be supplied at most
once.

   Class-name--a non-nil symbol.  :metaclass can be supplied once at
most.

   new-class--the new class object.

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

The macro defclass defines a new named class.  It returns the new class
object as its result.

   The syntax of defclass provides options for specifying initialization
arguments for slots, for specifying default initialization values for
slots, and for requesting that methods on specified generic functions be
automatically generated for reading and writing the values of slots.  No
reader or writer functions are defined by default; their generation must
be explicitly requested.  However, slots can always be accessed using
slot-value.

   Defining a new class also causes a type of the same name to be
defined.  The predicate (typep object class-name) returns true if the
class of the given object is the class named by class-name itself or a
subclass of the class class-name.  A class object can be used as a type
specifier.  Thus (typep object class) returns true if the class of the
object is class itself or a subclass of class.

   The class-name argument specifies the proper name of the new class.
If a class with the same proper name already exists and that class is an
instance of standard-class, and if the defclass form for the definition
of the new class specifies a class of class standard-class, the existing
class is redefined, and instances of it (and its subclasses) are updated
to the new definition at the time that they are next accessed.  For
details, see *note Redefining Classes::.

   Each superclass-name argument specifies a direct superclass of the
new class.  If the superclass list is empty, then the superclass
defaults depending on the metaclass, with standard-object being the
default for standard-class.

   The new class will inherit slots and methods from each of its direct
superclasses, from their direct superclasses, and so on.  For a
discussion of how slots and methods are inherited, see *note
Inheritance::.

   The following slot options are available:

*
     The :reader slot option specifies that an unqualified method is to
     be defined on the generic function named reader-function-name to
     read the value of the given slot.

*
     The :writer slot option specifies that an unqualified method is to
     be defined on the generic function named writer-function-name to
     write the value of the slot.

*
     The :accessor slot option specifies that an unqualified method is
     to be defined on the generic function named reader-function-name to
     read the value of the given slot and that an unqualified method is
     to be defined on the generic function named (setf
     reader-function-name) to be used with setf to modify the value of
     the slot.

*
     The :allocation slot option is used to specify where storage is to
     be allocated for the given slot.  Storage for a slot can be located
     in each instance or in the class object itself.  The value of the
     allocation-type argument can be either the keyword :instance or the
     keyword :class.  If the :allocation slot option is not specified,
     the effect is the same as specifying :allocation :instance.

     -
          If allocation-type is :instance, a local slot of the name
          slot-name is allocated in each instance of the class.

     -
          If allocation-type is :class, a shared slot of the given name
          is allocated in the class object created by this defclass
          form.  The value of the slot is shared by all instances of the
          class.  If a class C_1 defines such a shared slot, any
          subclass C_2 of C_1 will share this single slot unless the
          defclass form for C_2 specifies a slot of the same name or
          there is a superclass of C_2 that precedes C_1 in the class
          precedence list of C_2 and that defines a slot of the same
          name.

*
     The :initform slot option is used to provide a default initial
     value form to be used in the initialization of the slot.  This form
     is evaluated every time it is used to initialize the slot.  The
     lexical environment in which this form is evaluated is the lexical
     environment in which the defclass form was evaluated.  Note that
     the lexical environment refers both to variables and to functions.
     For local slots, the dynamic environment is the dynamic environment
     in which make-instance is called; for shared slots, the dynamic
     environment is the dynamic environment in which the defclass form
     was evaluated.  See *note Object Creation and Initialization::.

     No implementation is permitted to extend the syntax of defclass to
     allow (slot-name form) as an abbreviation for (slot-name :initform
     form).

     [Reviewer Note by Barmar: Can you extend this to mean something
     else?]

*
     The :initarg slot option declares an initialization argument named
     initarg-name and specifies that this initialization argument
     initializes the given slot.  If the initialization argument has a
     value in the call to initialize-instance, the value will be stored
     into the given slot, and the slot's :initform slot option, if any,
     is not evaluated.  If none of the initialization arguments
     specified for a given slot has a value, the slot is initialized
     according to the :initform slot option, if specified.

*
     The :type slot option specifies that the contents of the slot will
     always be of the specified data type.  It effectively declares the
     result type of the reader generic function when applied to an
     object of this class.  The consequences of attempting to store in a
     slot a value that does not satisfy the type of the slot are
     undefined.  The :type slot option is further discussed in *note
     Inheritance of Slots and Slot Options::.

*
     The :documentation slot option provides a documentation string for
     the slot.  :documentation can be supplied once at most for a given
     slot.  [Reviewer Note by Barmar: How is this retrieved?]

   Each class option is an option that refers to the class as a whole.
The following class options are available:

*
     The :default-initargs class option is followed by a list of
     alternating initialization argument names and default initial value
     forms.  If any of these initialization arguments does not appear in
     the initialization argument list supplied to make-instance, the
     corresponding default initial value form is evaluated, and the
     initialization argument name and the form's value are added to the
     end of the initialization argument list before the instance is
     created; see *note Object Creation and Initialization::.  The
     default initial value form is evaluated each time it is used.  The
     lexical environment in which this form is evaluated is the lexical
     environment in which the defclass form was evaluated.  The dynamic
     environment is the dynamic environment in which make-instance was
     called.  If an initialization argument name appears more than once
     in a :default-initargs class option, an error is signaled.

*

     The :documentation class option causes a documentation string to be
     attached with the class object, and attached with kind type to the
     class-name.  :documentation can be supplied once at most.

*
     The :metaclass class option is used to specify that instances of
     the class being defined are to have a different metaclass than the
     default provided by the system (the class standard-class).

   Note the following rules of defclass for standard classes:

*
     It is not required that the superclasses of a class be defined
     before the defclass form for that class is evaluated.

*
     All the superclasses of a class must be defined before an instance
     of the class can be made.

*
     A class must be defined before it can be used as a parameter
     specializer in a defmethod form.

   The object system can be extended to cover situations where these
rules are not obeyed.

   Some slot options are inherited by a class from its superclasses, and
some can be shadowed or altered by providing a local slot description.
No class options except :default-initargs are inherited.  For a detailed
description of how slots and slot options are inherited, see *note
Inheritance of Slots and Slot Options::.

   The options to defclass can be extended.  It is required that all
implementations signal an error if they observe a class option or a slot
option that is not implemented locally.

   It is valid to specify more than one reader, writer, accessor, or
initialization argument for a slot.  No other slot option can appear
more than once in a single slot description, or an error is signaled.

   If no reader, writer, or accessor is specified for a slot, the slot
can only be accessed by the function slot-value.

   If a defclass form appears as a top level form, the compiler must
make the class name be recognized as a valid type name in subsequent
declarations (as for deftype) and be recognized as a valid class name
for defmethod parameter specializers and for use as the :metaclass
option of a subsequent defclass.  The compiler must make the class
definition available to be returned by find-class when its environment
argument is a value received as the environment parameter of a macro.

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

If there are any duplicate slot names, an error of type program-error is
signaled.

   If an initialization argument name appears more than once in
:default-initargs class option, an error of type program-error is
signaled.

   If any of the following slot options appears more than once in a
single slot description, an error of type program-error is signaled:
:allocation, :initform, :type, :documentation.

   It is required that all implementations signal an error of type
program-error if they observe a class option or a slot option that is
not implemented locally.

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

*note documentation:: , *note Initialize-Instance:: , *note
make-instance:: , *note slot-value:: , *note Classes::, *note
Inheritance::, *note Redefining Classes::, *note Determining the Class
Precedence List::, *note Object Creation and Initialization::


File: gcl.info,  Node: defgeneric,  Next: defmethod,  Prev: defclass,  Up: Objects Dictionary

7.7.26 defgeneric [Macro]
-------------------------

'defgeneric' function-name gf-lambda-list [[!option |
{!method-description}*]]
=> new-generic

   option ::=(:argument-precedence-order {parameter-name}^+) |
           (declare {gf-declaration}^+) |
           (:documentation gf-documentation) |
           (:method-combination method-combination {method-combination-argument}*) |
           (:generic-function-class generic-function-class) |
           (:method-class method-class)

   method-description ::=(:method {method-qualifier}* specialized-lambda-list [[{declaration}* | documentation]] {form}*)

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

function-name--a function name.

   generic-function-class--a non-nil symbol naming a class.

   gf-declaration--an optimize declaration specifier; other declaration
specifiers are not permitted.

   gf-documentation--a string; not evaluated.

   gf-lambda-list--a generic function lambda list.

   method-class--a non-nil symbol naming a class.

   method-combination-argument--an object.

   method-combination-name--a symbol naming a method combination type.

   method-qualifiers, specialized-lambda-list, declarations,
documentation, forms--as per defmethod.

   new-generic--the generic function object.

   parameter-name--a symbol that names a required parameter in the
lambda-list.  (If the :argument-precedence-order option is specified,
each required parameter in the lambda-list must be used exactly once as
a parameter-name.)

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

The macro defgeneric is used to define a generic function or to specify
options and declarations that pertain to a generic function as a whole.

   If function-name is a list it must be of the form (setf symbol).  If
(fboundp function-name) is false, a new generic function is created.

   If (fdefinition function-name) is a generic function, that

   generic function is modified.  If function-name names an ordinary
function, a macro, or a special operator, an error is signaled.

   The effect of the defgeneric macro is as if the following three steps
were performed: first, methods defined by previous defgeneric forms are
removed;

   [Reviewer Note by Barmar: Shouldn't this (second) be first?]  second,
ensure-generic-function is called; and finally, methods specified by the
current defgeneric form are added to the generic function.

   Each method-description defines a method on the generic function.
The lambda list of each method must be congruent with the lambda list
specified by the gf-lambda-list option.  If no method descriptions are
specified and a generic function of the same name does not already
exist, a generic function with no methods is created.

   The gf-lambda-list argument of defgeneric specifies the shape of
lambda lists for the methods on this generic function.  All methods on
the resulting generic function must have lambda lists that are congruent
with this shape.  If a defgeneric form is evaluated and some methods for
that generic function have lambda lists that are not congruent with that
given in the defgeneric form, an error is signaled.  For further details
on method congruence, see *note Congruent Lambda-lists for all Methods
of a Generic Function::.

   The generic function passes to the method all the argument values
passed to it, and only those; default values are not supported.  Note
that optional and keyword arguments in method definitions, however, can
have default initial value forms and can use supplied-p parameters.

   The following options are provided.

   Except as otherwise noted,

   a given option may occur only once.

*
     The :argument-precedence-order option is used to specify the order
     in which the required arguments in a call to the generic function
     are tested for specificity when selecting a particular method.
     Each required argument, as specified in the gf-lambda-list
     argument, must be included exactly once as a parameter-name so that
     the full and unambiguous precedence order is supplied.  If this
     condition is not met, an error is signaled.

     [Reviewer Note by Barmar: What is the default order?]

*
     The declare option is used to specify declarations that pertain to
     the generic function.

     An optimize declaration specifier is allowed.  It specifies whether
     method selection should be optimized for speed or space, but it has
     no effect on methods.  To control how a method is optimized, an
     optimize declaration must be placed directly in the defmethod form
     or method description.  The optimization qualities speed and space
     are the only qualities this standard requires, but an
     implementation can extend the object system to recognize other
     qualities.  A simple implementation that has only one method
     selection technique and ignores optimize declaration specifiers is
     valid.

     The special, ftype, function, inline, notinline, and declaration
     declarations are not permitted.  Individual implementations can
     extend the declare option to support additional declarations.

     [Editorial Note by KMP: Does "additional" mean including special,
     ftype, etc.?  Or only other things that are not mentioned here?]
     If an implementation notices a declaration specifier that it does
     not support and that has not been proclaimed as a non-standard
     declaration identifier name in a declaration proclamation, it
     should issue a warning.  [Editorial Note by KMP: The wording of
     this previous sentence, particularly the word "and" suggests to me
     that you can 'proclaim declaration' of an unsupported declaration
     (e.g., ftype) in order to suppress the warning.  That seems wrong.
     Perhaps it instead means to say "does not support or is both
     undefined and not proclaimed declaration."]

     The declare option may be specified more than once.  The effect is
     the same as if the lists of declaration specifiers had been
     appended together into a single list and specified as a single
     declare option.

*
     The :documentation argument is a documentation string to be
     attached to the generic function object, and to be attached with
     kind function to the function-name.

*
     The :generic-function-class option may be used to specify that the
     generic function is to have a different class than the default
     provided by the system (the class standard-generic-function).  The
     class-name argument is the name of a class that can be the class of
     a generic function.  If function-name specifies an existing generic
     function that has a different value for the :generic-function-class
     argument and the new generic function class is compatible with the
     old, change-class is called to change the class of the generic
     function; otherwise an error is signaled.

*
     The :method-class option is used to specify that all methods on
     this generic function are to have a different class from the
     default provided by the system (the class standard-method).  The
     class-name argument is the name of a class that is capable of being
     the class of a method.

     [Reviewer Note by Barmar: Is change-class called on existing
     methods?]

*
     The :method-combination option is followed by a symbol that names a
     type of method combination.  The arguments (if any) that follow
     that symbol depend on the type of method combination.  Note that
     the standard method combination type does not support any
     arguments.  However, all types of method combination defined by the
     short form of define-method-combination accept an optional argument
     named order, defaulting to :most-specific-first, where a value of
     :most-specific-last reverses the order of the primary methods
     without affecting the order of the auxiliary methods.

   The method-description arguments define methods that will be
associated with the generic function.  The method-qualifier and
specialized-lambda-list arguments in a method description are the same
as for defmethod.

   The form arguments specify the method body.  The body of the method
is enclosed in an implicit block.  If function-name is a symbol, this
block bears the same name as the generic function.  If function-name is
a list of the form (setf symbol), the name of the block is symbol.

   Implementations can extend defgeneric to include other options.  It
is required that an implementation signal an error if it observes an
option that is not implemented locally.

   defgeneric is not required to perform any compile-time side effects.
In particular, the methods are not installed for invocation during
compilation.  An implementation may choose to store information about
the generic function for the purposes of compile-time error-checking
(such as checking the number of arguments on calls, or noting that a
definition for the function name has been seen).

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

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

If function-name names an ordinary function, a macro, or a special
operator, an error of type program-error is signaled.

   Each required argument, as specified in the gf-lambda-list argument,
must be included exactly once as a parameter-name, or an error of type
program-error is signaled.

   The lambda list of each method specified by a method-description must
be congruent with the lambda list specified by the gf-lambda-list
option, or an error of type error is signaled.

   If a defgeneric form is evaluated and some methods for that generic
function have lambda lists that are not congruent with that given in the
defgeneric form, an error of type error is signaled.

   A given option may occur only once, or an error of type program-error
is signaled.

   [Reviewer Note by Barmar: This says that an error is signaled if you
specify the same generic function class as it already has!]  If
function-name specifies an existing generic function that has a
different value for the :generic-function-class argument and the new
generic function class is compatible with the old, change-class is
called to change the class of the generic function; otherwise an error
of type error is signaled.

   Implementations can extend defgeneric to include other options.  It
is required that an implementation signal an error of type program-error
if it observes an option that is not implemented locally.

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

*note defmethod:: , *note documentation:: , *note
ensure-generic-function:: ,

   generic-function,

   *note Congruent Lambda-lists for all Methods of a Generic Function::


File: gcl.info,  Node: defmethod,  Next: find-class,  Prev: defgeneric,  Up: Objects Dictionary

7.7.27 defmethod [Macro]
------------------------

'defmethod' function-name {method-qualifier}* specialized-lambda-list
[[{declaration}* | documentation]] {form}*
=> new-method

   function-name::= {symbol | (setf symbol)}

   method-qualifier::= non-list

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

    parameter-specializer-name::= symbol | (eql eql-specializer-form)

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

declaration--a declare expression; not evaluated.

   documentation--a string; not evaluated.

   var--a variable name.

   eql-specializer-form--a form.

   Form--a form.

   Initform--a form.

   Supplied-p-parameter--variable name.

   new-method--the new method object.

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

The macro defmethod defines a method on a generic function.

   If (fboundp function-name) is nil, a generic function is created with
default values for the argument precedence order (each argument is more
specific than the arguments to its right in the argument list), for the
generic function class (the class standard-generic-function), for the
method class (the class standard-method), and for the method combination
type (the standard method combination type).  The lambda list of the
generic function is congruent with the lambda list of the method being
defined; if the defmethod form mentions keyword arguments, the lambda
list of the generic function will mention &key (but no keyword
arguments).  If function-name names an ordinary function, a macro, or a
special operator, an error is signaled.

   If a generic function is currently named by function-name, the lambda
list of the method must be congruent with the lambda list of the generic
function.  If this condition does not hold, an error is signaled.  For a
definition of congruence in this context, see *note Congruent
Lambda-lists for all Methods of a Generic Function::.

   Each method-qualifier argument is an object that is used by method
combination to identify the given method.  The method combination type
might further restrict what a method qualifier can be.  The standard
method combination type allows for unqualified methods and methods whose
sole qualifier is one of the keywords :before, :after, or :around.

   The specialized-lambda-list argument is like an ordinary lambda list
except that the names of required parameters can be replaced by
specialized parameters.  A specialized parameter is a list of the form
(var parameter-specializer-name).  Only required parameters can be
specialized.  If parameter-specializer-name is a symbol it names a
class; if it is a list, it is of the form (eql eql-specializer-form).
The parameter specializer name (eql eql-specializer-form) indicates that
the corresponding argument must be eql to the object that is the value
of eql-specializer-form for the method to be applicable.  The
eql-specializer-form is evaluated at the time that the expansion of the
defmethod macro is evaluated.  If no parameter specializer name is
specified for a given required parameter, the parameter specializer
defaults to the class t.  For further discussion, see *note Introduction
to Methods::.

   The form arguments specify the method body.  The body of the method
is enclosed in an implicit block.  If function-name is a symbol, this
block bears the same name as the generic function.  If function-name is
a list of the form (setf symbol), the name of the block is symbol.

   The class of the method object that is created is that given by the
method class option of the generic function on which the method is
defined.

   If the generic function already has a method that agrees with the
method being defined on parameter specializers and qualifiers, defmethod
replaces the existing method with the one now being defined.  For a
definition of agreement in this context.  see *note Agreement on
Parameter Specializers and Qualifiers::.

   The parameter specializers are derived from the parameter specializer
names as described in *note Introduction to Methods::.

   The expansion of the defmethod macro "refers to" each specialized
parameter (see the description of ignore within the description of
declare).  This includes parameters that have an explicit parameter
specializer name of t.  This means that a compiler warning does not
occur if the body of the method does not refer to a specialized
parameter, while a warning might occur if the body of the method does
not refer to an unspecialized parameter.  For this reason, a parameter
that specializes on t is not quite synonymous with an unspecialized
parameter in this context.

   Declarations at the head of the method body that apply to the
method's lambda variables are treated as bound declarations whose scope
is the same as the corresponding bindings.

   Declarations at the head of the method body that apply to the
functional bindings of call-next-method or next-method-p apply to
references to those functions within the method body forms.  Any outer
bindings of the function names call-next-method and next-method-p, and
declarations associated with such bindings are shadowed_2 within the
method body forms.

   The scope of free declarations at the head of the method body is the
entire method body, which includes any implicit local function
definitions but excludes initialization forms for the lambda variables.

   defmethod is not required to perform any compile-time side effects.
In particular, the methods are not installed for invocation during
compilation.  An implementation may choose to store information about
the generic function for the purposes of compile-time error-checking
(such as checking the number of arguments on calls, or noting that a
definition for the function name has been seen).

   Documentation is attached as a documentation string to the method
object.

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

The definition of the referenced generic function.

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

If function-name names an ordinary function, a macro, or a special
operator, an error of type error is signaled.

   If a generic function is currently named by function-name, the lambda
list of the method must be congruent with the lambda list of the generic
function, or an error of type error is signaled.

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

*note defgeneric:: , *note documentation:: , *note Introduction to
Methods::, *note Congruent Lambda-lists for all Methods of a Generic
Function::, *note Agreement on Parameter Specializers and Qualifiers::,
*note Syntactic Interaction of Documentation Strings and Declarations::


File: gcl.info,  Node: find-class,  Next: next-method-p,  Prev: defmethod,  Up: Objects Dictionary

7.7.28 find-class [Accessor]
----------------------------

'find-class' symbol &optional errorp environment => class

   (setf (' find-class' symbol &optional errorp environment) new-class)

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

symbol--a symbol.

   errorp--a generalized boolean.  The default is true.

   environment - same as the &environment argument to macro expansion
functions and is used to distinguish between compile-time and run-time
environments.

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

   class--a class object, or nil.

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

Returns the class object named by the symbol in the environment.  If
there is no such class, nil is returned if errorp is false; otherwise,
if errorp is true, an error is signaled.

   The class associated with a particular symbol can be changed by using
setf with find-class;

   or, if the new class given to setf is nil, the class association is
removed (but the class object itself is not affected).

   The results are undefined if the user attempts to change

   or remove

   the class associated with a symbol that is defined as a type
specifier in this standard.  See *note Integrating Types and Classes::.

   When using setf of find-class, any errorp argument is evaluated for
effect, but any values it returns are ignored; the errorp parameter is
permitted primarily so that the environment parameter can be used.

   The environment might be used to distinguish between a compile-time
and a run-time environment.

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

If there is no such class and errorp is true, find-class signals an
error of type error.

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

*note defmacro:: , *note Integrating Types and Classes::


File: gcl.info,  Node: next-method-p,  Next: call-method,  Prev: find-class,  Up: Objects Dictionary

7.7.29 next-method-p [Local Function]
-------------------------------------

Syntax::
........

'next-method-p' <no arguments> => generalized-boolean

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

generalized-boolean--a generalized boolean.

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

The locally defined function next-method-p can be used

   within the body forms (but not the lambda list)

   defined by a method-defining form to determine whether a next method
exists.

   The function next-method-p has lexical scope and indefinite extent.

   Whether or not next-method-p is fbound in the global environment is
implementation-dependent; however, the restrictions on redefinition and
shadowing of next-method-p are the same as for symbols in the
COMMON-LISP package which are fbound in the global environment.  The
consequences of attempting to use next-method-p outside of a
method-defining form are undefined.

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

*note call-next-method:: , *note defmethod:: , *note call-method::


File: gcl.info,  Node: call-method,  Next: call-next-method,  Prev: next-method-p,  Up: Objects Dictionary

7.7.30 call-method, make-method [Local Macro]
---------------------------------------------

Syntax::
........

'call-method' method &optional next-method-list => {result}*

   'make-method' form => method-object

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

method--a method object, or a list (see below); not evaluated.

   method-object--a method object.

   next-method-list--a list of method objects; not evaluated.

   results--the values returned by the method invocation.

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

The macro call-method is used in method combination.  It hides the
implementation-dependent details of how methods are called.  The macro
call-method has lexical scope and can only be used within an effective
method form.

   [Editorial Note by KMP: This next paragraph still needs some work.]

   Whether or not call-method is fbound in the global environment is
implementation-dependent; however, the restrictions on redefinition and
shadowing of call-method are the same as for symbols in the COMMON-LISP
package which are fbound in the global environment.  The consequences of
attempting to use call-method outside of an effective method form are
undefined.

   The macro call-method invokes the specified method, supplying it with
arguments and with definitions for call-next-method and for
next-method-p.  If the invocation of call-method is lexically inside of
a make-method, the arguments are those that were supplied to that
method.  Otherwise the arguments are those that were supplied to the
generic function.  The definitions of call-next-method and next-method-p
rely on the specified next-method-list.

   If method is a list, the first element of the list must be the symbol
make-method and the second element must be a form.  Such a list
specifies a method object whose method function has a body that is the
given form.

   Next-method-list can contain method objects or lists, the first
element of which must be the symbol make-method and the second element
of which must be a form.

   Those are the only two places where make-method can be used.  The
form used with make-method is evaluated in the null lexical environment
augmented with a local macro definition for call-method and with
bindings named by symbols not accessible from the COMMON-LISP-USER
package.

   The call-next-method function available to method will call the first
method in next-method-list.  The call-next-method function available in
that method, in turn, will call the second method in next-method-list,
and so on, until the list of next methods is exhausted.

   If next-method-list is not supplied, the call-next-method function
available to method signals an error of type control-error and the
next-method-p function available to method returns nil.

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

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

*note call-next-method:: , *note define-method-combination:: , *note
next-method-p::


File: gcl.info,  Node: call-next-method,  Next: compute-applicable-methods,  Prev: call-method,  Up: Objects Dictionary

7.7.31 call-next-method [Local Function]
----------------------------------------

Syntax::
........

'call-next-method' &rest args => {result}*

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

arg--an object.

   results--the values returned by the method it calls.

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

The function call-next-method can be used

   within the body forms (but not the lambda list)

   of a method defined by a method-defining form to call the next
method.

   If there is no next method, the generic function no-next-method is
called.

   The type of method combination used determines which methods can
invoke call-next-method.  The standard method combination type allows
call-next-method to be used within primary methods and around methods.
For generic functions using a type of method combination defined by the
short form of define-method-combination, call-next-method can be used in
around methods only.

   When call-next-method is called with no arguments, it passes the
current method's original arguments to the next method.  Neither
argument defaulting, nor using setq, nor rebinding variables with the
same names as parameters of the method affects the values
call-next-method passes to the method it calls.

   When call-next-method is called with arguments, the next method is
called with those arguments.

   If call-next-method is called with arguments but omits optional
arguments, the next method called defaults those arguments.

   The function call-next-method returns any values that are returned by
the next method.

   The function call-next-method has lexical scope and indefinite extent
and can only be used within the body of a method defined by a
method-defining form.

   Whether or not call-next-method is fbound in the global environment
is implementation-dependent; however, the restrictions on redefinition
and shadowing of call-next-method are the same as for symbols in the
COMMON-LISP package which are fbound in the global environment.  The
consequences of attempting to use call-next-method outside of a
method-defining form are undefined.

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

defmethod, call-method, define-method-combination.

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

When providing arguments to call-next-method, the following rule must be
satisfied or an error of type error should be signaled: the ordered set
of applicable methods for a 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.
Optimizations of the error checking are possible, but they must not
change the semantics of call-next-method.

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

*note define-method-combination:: , *note defmethod:: , *note
next-method-p:: , *note no-next-method:: , *note call-method:: , *note
Method Selection and Combination::, *note Standard Method Combination::,
*note Built-in Method Combination Types::


File: gcl.info,  Node: compute-applicable-methods,  Next: define-method-combination,  Prev: call-next-method,  Up: Objects Dictionary

7.7.32 compute-applicable-methods [Standard Generic Function]
-------------------------------------------------------------

Syntax::
........

'compute-applicable-methods' generic-function function-arguments =>
methods

Method Signatures::
...................

'compute-applicable-methods' (generic-function
standard-generic-function)

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

generic-function--a generic function.

   function-arguments--a list of arguments for the generic-function.

   methods--a list of method objects.

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

Given a generic-function and a set of function-arguments, the function
compute-applicable-methods returns the set of methods that are
applicable for those arguments sorted according to precedence order.
See *note Method Selection and Combination::.

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

defmethod

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

*note Method Selection and Combination::


File: gcl.info,  Node: define-method-combination,  Next: find-method,  Prev: compute-applicable-methods,  Up: Objects Dictionary

7.7.33 define-method-combination [Macro]
----------------------------------------

'define-method-combination' name [[!short-form-option]]
=> name

   'define-method-combination' name lambda-list
({method-group-specifier}*) [(:arguments .  args-lambda-list)]
[(:generic-function generic-function-symbol)] [[{declaration}* |
documentation]] {form}*
=> name

   short-form-option ::=:documentation documentation | 
                      :identity-with-one-argument identity-with-one-argument |
                      :operator operator

   method-group-specifier ::=(name {{qualifier-pattern}^+ | predicate} [[!long-form-option]])

   long-form-option ::=:description description |
                     :order order |
                     :required required-p

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

args-lambda-list-- a define-method-combination arguments lambda list.

   declaration--a declare expression; not evaluated.

   description--a format control.

   documentation--a string; not evaluated.

   forms--an implicit progn that must compute and return the form that
specifies how the methods are combined, that is, the effective method.

   generic-function-symbol--a symbol.

   identity-with-one-argument--a generalized boolean.

   lambda-list--ordinary lambda list.

   name--a symbol.  Non-keyword, non-nil symbols are usually used.

   operator--an operator.  Name and operator are often the same symbol.
This is the default, but it is not required.

   order--:most-specific-first or :most-specific-last; evaluated.

   predicate--a symbol that names a function of one argument that
returns a generalized boolean.

   qualifier-pattern--a list, or the symbol *.

   required-p--a generalized boolean.

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

The macro define-method-combination is used to define new types of
method combination.

   There are two forms of define-method-combination.  The short form is
a simple facility for the cases that are expected to be most commonly
needed.  The long form is more powerful but more verbose.  It resembles
defmacro in that the body is an expression, usually using backquote,
that computes a form.  Thus arbitrary control structures can be
implemented.  The long form also allows arbitrary processing of method
qualifiers.

Short Form
     The short form syntax of define-method-combination is recognized
     when the second subform is a non-nil symbol or is not present.
     When the short form is used, name is defined as a type of method
     combination that produces a Lisp form (operator method-call
     method-call ...).  The operator is a symbol that can be the name of
     a function, macro, or special operator.  The operator can be
     supplied by a keyword option; it defaults to name.

     Keyword options for the short form are the following:

     *
          The :documentation option is used to document the
          method-combination type; see description of long form below.

     *
          The :identity-with-one-argument option enables an optimization
          when its value is true (the default is false).  If there is
          exactly one applicable method and it is a primary method, that
          method serves as the effective method and operator is not
          called.  This optimization avoids the need to create a new
          effective method and avoids the overhead of a function call.
          This option is designed to be used with operators such as
          progn, and, +, and max.

     *
          The :operator option specifies the name of the operator.  The
          operator argument is a symbol that can be the name of a
          function, macro, or special form.

     These types of method combination require exactly one qualifier per
     method.  An error is signaled if there are applicable methods with
     no qualifiers or with qualifiers that are not supported by the
     method combination type.

     A method combination procedure defined in this way recognizes two
     roles for methods.  A method whose one qualifier is the symbol
     naming this type of method combination is defined to be a primary
     method.  At least one primary method must be applicable or an error
     is signaled.  A method with :around as its one qualifier is an
     auxiliary method that behaves the same as an around method in
     standard method combination.  The function call-next-method can
     only be used in around methods; it cannot be used in primary
     methods defined by the short form of the define-method-combination
     macro.

     A method combination procedure defined in this way accepts an
     optional argument named order, which defaults to
     :most-specific-first.  A value of :most-specific-last reverses the
     order of the primary methods without affecting the order of the
     auxiliary methods.

     The short form automatically includes error checking and support
     for around methods.

     For a discussion of built-in method combination types, see *note
     Built-in Method Combination Types::.

Long Form
     The long form syntax of define-method-combination is recognized
     when the second subform is a list.

     The lambda-list receives any arguments provided after the name of
     the method combination type in the :method-combination option to
     defgeneric.

     A list of method group specifiers follows.  Each specifier selects
     a subset of the applicable methods to play a particular role,
     either by matching their qualifiers against some patterns or by
     testing their qualifiers with a predicate.  These method group
     specifiers define all method qualifiers that can be used with this
     type of method combination.

     The car of each method-group-specifier is a symbol which names a
     variable.  During the execution of the forms in the body of
     define-method-combination, this variable is bound to a list of the
     methods in the method group.  The methods in this list occur in the
     order specified by the :order option.

     If qualifier-pattern is a symbol it must be *.  A method matches a
     qualifier-pattern if the method's list of qualifiers is equal to
     the qualifier-pattern (except that the symbol * in a
     qualifier-pattern matches anything).  Thus a qualifier-pattern can
     be one of the following: the empty list, which matches unqualified
     methods; the symbol *, which matches all methods; a true list,
     which matches methods with the same number of qualifiers as the
     length of the list when each qualifier matches the corresponding
     list element; or a dotted list that ends in the symbol * (the *
     matches any number of additional qualifiers).

     Each applicable method is tested against the qualifier-patterns and
     predicates in left-to-right order.  As soon as a qualifier-pattern
     matches or a predicate returns true, the method becomes a member of
     the corresponding method group and no further tests are made.  Thus
     if a method could be a member of more than one method group, it
     joins only the first such group.  If a method group has more than
     one qualifier-pattern, a method need only satisfy one of the
     qualifier-patterns to be a member of the group.

     The name of a predicate function can appear instead of
     qualifier-patterns in a method group specifier.  The predicate is
     called for each method that has not been assigned to an earlier
     method group; it is called with one argument, the method's
     qualifier list.  The predicate should return true if the method is
     to be a member of the method group.  A predicate can be
     distinguished from a qualifier-pattern because it is a symbol other
     than nil or *.

     If there is an applicable method that does not fall into any method
     group, the function invalid-method-error is called.

     Method group specifiers can have keyword options following the
     qualifier patterns or predicate.  Keyword options can be
     distinguished from additional qualifier patterns because they are
     neither lists nor the symbol *.  The keyword options are as
     follows:

     *
          The :description option is used to provide a description of
          the role of methods in the method group.  Programming
          environment tools use (apply #'format stream format-control
          (method-qualifiers method)) to print this description, which
          is expected to be concise.  This keyword option allows the
          description of a method qualifier to be defined in the same
          module that defines the meaning of the method qualifier.  In
          most cases, format-control will not contain any format
          directives, but they are available for generality.  If
          :description is not supplied, a default description is
          generated based on the variable name and the qualifier
          patterns and on whether this method group includes the
          unqualified methods.

     *
          The :order option specifies the order of methods.  The order
          argument is a form that evaluates to :most-specific-first or
          :most-specific-last.  If it evaluates to any other value, an
          error is signaled.  If :order is not supplied, it defaults to
          :most-specific-first.

     *
          The :required option specifies whether at least one method in
          this method group is required.  If its value is true and the
          method group is empty (that is, no applicable methods match
          the qualifier patterns or satisfy the predicate), an error is
          signaled.  If :required is not supplied, it defaults to nil.

     The use of method group specifiers provides a convenient syntax to
     select methods, to divide them among the possible roles, and to
     perform the necessary error checking.  It is possible to perform
     further filtering of methods in the body forms by using normal
     list-processing operations and the functions method-qualifiers and
     invalid-method-error.  It is permissible to use setq on the
     variables named in the method group specifiers and to bind
     additional variables.  It is also possible to bypass the method
     group specifier mechanism and do everything in the body forms.
     This is accomplished by writing a single method group with * as its
     only qualifier-pattern; the variable is then bound to a list of all
     of the applicable methods, in most-specific-first order.

     The body forms compute and return the form that specifies how the
     methods are combined, that is, the effective method.  The effective
     method is evaluated in the null lexical environment augmented with
     a local macro definition for call-method and with bindings named by
     symbols not accessible from the COMMON-LISP-USER package.  Given a
     method object in one of the lists produced by the method group
     specifiers and a list of next methods, call-method will invoke the
     method such that call-next-method has available the next methods.

     When an effective method has no effect other than to call a single
     method, some implementations employ an optimization that uses the
     single method directly as the effective method, thus avoiding the
     need to create a new effective method.  This optimization is active
     when the effective method form consists entirely of an invocation
     of the call-method macro whose first subform is a method object and
     whose second subform is nil or unsupplied.  Each
     define-method-combination body is responsible for stripping off
     redundant invocations of progn, and, multiple-value-prog1, and the
     like, if this optimization is desired.

     The list (:arguments . lambda-list) can appear before any
     declarations or documentation string.  This form is useful when the
     method combination type performs some specific behavior as part of
     the combined method and that behavior needs access to the arguments
     to the generic function.  Each parameter variable defined by
     lambda-list is bound to a form that can be inserted into the
     effective method.  When this form is evaluated during execution of
     the effective method, its value is the corresponding argument to
     the generic function; the consequences of using such a form as the
     place in a setf form are undefined.

     Argument correspondence is computed by dividing the :arguments
     lambda-list and the generic function lambda-list into three
     sections: the required parameters, the optional parameters, and the
     keyword and rest parameters.  The arguments supplied to the generic
     function for a particular call are also divided into three
     sections; the required arguments section contains as many arguments
     as the generic function has required parameters, the optional
     arguments section contains as many arguments as the generic
     function has optional parameters, and the keyword/rest arguments
     section contains the remaining arguments.  Each parameter in the
     required and optional sections of the :arguments lambda-list
     accesses the argument at the same position in the corresponding
     section of the arguments.  If the section of the :arguments
     lambda-list is shorter, extra arguments are ignored.  If the
     section of the :arguments lambda-list is longer, excess required
     parameters are bound to forms that evaluate to nil and excess
     optional parameters are bound to their initforms.  The keyword
     parameters and rest parameters in the :arguments lambda-list access
     the keyword/rest section of the arguments.  If the :arguments
     lambda-list contains &key, it behaves as if it also contained
     &allow-other-keys.

     In addition, &whole var can be placed first in the :arguments
     lambda-list.  It causes var to be bound to a form that evaluates to
     a list of all of the arguments supplied to the generic function.
     This is different from &rest because it accesses all of the
     arguments, not just the keyword/rest arguments.

     Erroneous conditions detected by the body should be reported with
     method-combination-error or invalid-method-error; these functions
     add any necessary contextual information to the error message and
     will signal the appropriate error.

     The body forms are evaluated inside of the bindings created by the
     lambda list and method group specifiers.

     [Reviewer Note by Barmar: Are they inside or outside the :ARGUMENTS
     bindings?]  Declarations at the head of the body are positioned
     directly inside of bindings created by the lambda list and outside
     of the bindings of the method group variables.  Thus method group
     variables cannot be declared in this way.  locally may be used
     around the body, however.

     Within the body forms, generic-function-symbol is bound to the
     generic function object.

     Documentation is attached as a documentation string to name (as
     kind method-combination) and to the method combination object.

     Note that two methods with identical specializers, but with
     different qualifiers, are not ordered by the algorithm described in
     Step 2 of the method selection and combination process described in
     *note Method Selection and Combination::.  Normally the two methods
     play different roles in the effective method because they have
     different qualifiers, and no matter how they are ordered in the
     result of Step 2, the effective method is the same.  If the two
     methods play the same role and their order matters,

     [Reviewer Note by Barmar: How does the system know when the order
     matters?]  an error is signaled.  This happens as part of the
     qualifier pattern matching in define-method-combination.

   If a define-method-combination form appears as a top level form, the
compiler must make the method combination name be recognized as a valid
method combination name in subsequent defgeneric forms.  However, the
method combination is executed no earlier than when the
define-method-combination form is executed, and possibly as late as the
time that generic functions that use the method combination are
executed.

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

Most examples of the long form of define-method-combination also
illustrate the use of the related functions that are provided as part of
the declarative method combination facility.

     ;;; Examples of the short form of define-method-combination

      (define-method-combination and :identity-with-one-argument t)

      (defmethod func and ((x class1) y) ...)

     ;;; The equivalent of this example in the long form is:

      (define-method-combination and
              (&optional (order :most-specific-first))
              ((around (:around))
               (primary (and) :order order :required t))
        (let ((form (if (rest primary)
                        `(and ,@(mapcar #'(lambda (method)
                                            `(call-method ,method))
                                        primary))
                        `(call-method ,(first primary)))))
          (if around
              `(call-method ,(first around)
                            (,@(rest around)
                             (make-method ,form)))
              form)))

     ;;; Examples of the long form of define-method-combination

     ;The default method-combination technique
      (define-method-combination standard ()
              ((around (:around))
               (before (:before))
               (primary () :required t)
               (after (:after)))
        (flet ((call-methods (methods)
                 (mapcar #'(lambda (method)
                             `(call-method ,method))
                         methods)))
          (let ((form (if (or before after (rest primary))
                          `(multiple-value-prog1
                             (progn ,@(call-methods before)
                                    (call-method ,(first primary)
                                                 ,(rest primary)))
                             ,@(call-methods (reverse after)))
                          `(call-method ,(first primary)))))
            (if around
                `(call-method ,(first around)
                              (,@(rest around)
                               (make-method ,form)))
                form))))

     ;A simple way to try several methods until one returns non-nil
      (define-method-combination or ()
              ((methods (or)))
        `(or ,@(mapcar #'(lambda (method)
                           `(call-method ,method))
                       methods)))

     ;A more complete version of the preceding
      (define-method-combination or
              (&optional (order ':most-specific-first))
              ((around (:around))
               (primary (or)))
        ;; Process the order argument
        (case order
          (:most-specific-first)
          (:most-specific-last (setq primary (reverse primary)))
          (otherwise (method-combination-error "~S is an invalid order.~@
          :most-specific-first and :most-specific-last are the possible values."
                                               order)))
        ;; Must have a primary method
        (unless primary
          (method-combination-error "A primary method is required."))
        ;; Construct the form that calls the primary methods
        (let ((form (if (rest primary)
                        `(or ,@(mapcar #'(lambda (method)
                                           `(call-method ,method))
                                       primary))
                        `(call-method ,(first primary)))))
          ;; Wrap the around methods around that form
          (if around
              `(call-method ,(first around)
                            (,@(rest around)
                             (make-method ,form)))
              form)))

     ;The same thing, using the :order and :required keyword options
      (define-method-combination or
              (&optional (order ':most-specific-first))
              ((around (:around))
               (primary (or) :order order :required t))
        (let ((form (if (rest primary)
                        `(or ,@(mapcar #'(lambda (method)
                                           `(call-method ,method))
                                       primary))
                        `(call-method ,(first primary)))))
          (if around
              `(call-method ,(first around)
                            (,@(rest around)
                             (make-method ,form)))
              form)))

     ;This short-form call is behaviorally identical to the preceding
      (define-method-combination or :identity-with-one-argument t)

     ;Order methods by positive integer qualifiers
     ;:around methods are disallowed to keep the example small
      (define-method-combination example-method-combination ()
              ((methods positive-integer-qualifier-p))
        `(progn ,@(mapcar #'(lambda (method)
                              `(call-method ,method))
                          (stable-sort methods #'<
                            :key #'(lambda (method)
                                     (first (method-qualifiers method)))))))

      (defun positive-integer-qualifier-p (method-qualifiers)
        (and (= (length method-qualifiers) 1)
             (typep (first method-qualifiers) '(integer 0 *))))

     ;;; Example of the use of :arguments
      (define-method-combination progn-with-lock ()
              ((methods ()))
        (:arguments object)
        `(unwind-protect
             (progn (lock (object-lock ,object))
                    ,@(mapcar #'(lambda (method)
                                  `(call-method ,method))
                              methods))
           (unlock (object-lock ,object))))


Side Effects::
..............

The compiler is not required to perform any compile-time side-effects.

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

Method combination types defined with the short form require exactly one
qualifier per method.  An error of type error is signaled if there are
applicable methods with no qualifiers or with qualifiers that are not
supported by the method combination type.  At least one primary method
must be applicable or an error of type error is signaled.

   If an applicable method does not fall into any method group, the
system signals an error of type error indicating that the method is
invalid for the kind of method combination in use.

   If the value of the :required option is true and the method group is
empty (that is, no applicable methods match the qualifier patterns or
satisfy the predicate), an error of type error is signaled.

   If the :order option evaluates to a value other than
:most-specific-first or :most-specific-last, an error of type error is
signaled.

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

*note call-method:: , *note call-next-method:: , *note documentation:: ,
*note method-qualifiers:: , *note method-combination-error:: , *note
invalid-method-error:: , *note defgeneric:: , *note Method Selection and
Combination::, *note Built-in Method Combination Types::, *note
Syntactic Interaction of Documentation Strings and Declarations::

Notes::
.......

The :method-combination option of defgeneric is used to specify that a
generic function should use a particular method combination type.  The
first argument to the :method-combination option is the name of a method
combination type and the remaining arguments are options for that type.


File: gcl.info,  Node: find-method,  Next: add-method,  Prev: define-method-combination,  Up: Objects Dictionary

7.7.34 find-method [Standard Generic Function]
----------------------------------------------

Syntax::
........

'find-method' generic-function method-qualifiers specializers &optional
errorp
=> method

Method Signatures::
...................

'find-method' (generic-function standard-generic-function)
method-qualifiers specializers &optional errorp

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

generic-function--a generic function.

   method-qualifiers--a list.

   specializers--a list.

   errorp--a generalized boolean.  The default is true.

   method--a method object, or nil.

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

The generic function find-method takes a generic function and returns
the method object that agrees on qualifiers and parameter specializers
with the method-qualifiers and specializers arguments of find-method.
Method-qualifiers contains the method qualifiers for the method.  The
order of the method qualifiers is significant.  For a definition of
agreement in this context, see *note Agreement on Parameter Specializers
and Qualifiers::.

   The specializers argument contains the parameter specializers for the
method.  It must correspond in length to the number of required
arguments of the generic function, or an error is signaled.  This means
that to obtain the default method on a given generic-function, a list
whose elements are the class t must be given.

   If there is no such method and errorp is true, find-method signals an
error.  If there is no such method and errorp is false, find-method
returns nil.

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

      (defmethod some-operation ((a integer) (b float)) (list a b))
     =>  #<STANDARD-METHOD SOME-OPERATION (INTEGER FLOAT) 26723357>
      (find-method #'some-operation '() (mapcar #'find-class '(integer float)))
     =>  #<STANDARD-METHOD SOME-OPERATION (INTEGER FLOAT) 26723357>
      (find-method #'some-operation '() (mapcar #'find-class '(integer integer)))
      |>  Error: No matching method
      (find-method #'some-operation '() (mapcar #'find-class '(integer integer)) nil)
     =>  NIL

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

add-method, defclass, defgeneric, defmethod

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

If the specializers argument does not correspond in length to the number
of required arguments of the generic-function, an an error of type error
is signaled.

   If there is no such method and errorp is true, find-method signals an
error of type error.

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

*note Agreement on Parameter Specializers and Qualifiers::


File: gcl.info,  Node: add-method,  Next: initialize-instance,  Prev: find-method,  Up: Objects Dictionary

7.7.35 add-method [Standard Generic Function]
---------------------------------------------

Syntax::
........

'add-method' generic-function method => generic-function

Method Signatures::
...................

'add-method' (generic-function standard-generic-function) (method
method)

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

generic-function--a generic function object.

   method--a method object.

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

The generic function add-method adds a method to a generic function.

   If method agrees with an existing method of generic-function on
parameter specializers and qualifiers, the existing method is replaced.

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

The lambda list of the method function of method must be congruent with
the lambda list of generic-function, or an error of type error is
signaled.

   If method is a method object of another generic function, an error of
type error is signaled.

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

*note defmethod:: , *note defgeneric:: , *note find-method:: , *note
remove-method:: , *note Agreement on Parameter Specializers and
Qualifiers::


File: gcl.info,  Node: initialize-instance,  Next: class-name,  Prev: add-method,  Up: Objects Dictionary

7.7.36 initialize-instance [Standard Generic Function]
------------------------------------------------------

Syntax::
........

'initialize-instance' instance &rest initargs &key &allow-other-keys =>
instance

Method Signatures::
...................

'initialize-instance' (instance standard-object) &rest initargs

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

instance--an object.

   initargs--a defaulted initialization argument list.

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

Called by make-instance to initialize a newly created instance.  The
generic function is called with the new instance and the defaulted
initialization argument list.

   The system-supplied primary method on initialize-instance initializes
the slots of the instance with values according to the initargs and the
:initform forms of the slots.  It does this by calling the generic
function shared-initialize with the following arguments: the instance, t
(this indicates that all slots for which no initialization arguments are
provided should be initialized according to their :initform forms), and
the initargs.

   Programmers can define methods for initialize-instance to specify
actions to be taken when an instance is initialized.  If only after
methods are defined, they will be run after the system-supplied primary
method for initialization and therefore will not interfere with the
default behavior of initialize-instance.

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

*note Shared-Initialize:: , *note make-instance:: , *note slot-boundp::
, *note slot-makunbound:: , *note Object Creation and Initialization::,
*note Rules for Initialization Arguments::, *note Declaring the Validity
of Initialization Arguments::


File: gcl.info,  Node: class-name,  Next: setf class-name,  Prev: initialize-instance,  Up: Objects Dictionary

7.7.37 class-name [Standard Generic Function]
---------------------------------------------

Syntax::
........

'class-name' class => name

Method Signatures::
...................

'class-name' (class class)

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

class--a class object.

   name--a symbol.

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

Returns the name of the given class.

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

*note find-class:: , *note Classes::

Notes::
.......

If S is a symbol such that S =(class-name C) and C =(find-class S), then
S is the proper name of C. For further discussion, see *note Classes::.

   The name of an anonymous class is nil.


File: gcl.info,  Node: setf class-name,  Next: class-of,  Prev: class-name,  Up: Objects Dictionary

7.7.38 setf class-name [Standard Generic Function]
--------------------------------------------------

Syntax::
........

'setf class-name' new-value class => new-value

Method Signatures::
...................

'setf class-name' new-value (class class)

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

new-value--a symbol.

   class--a class.

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

The generic function setf class-name sets the name of a class object.

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

*note find-class:: , proper name, *note Classes::


File: gcl.info,  Node: class-of,  Next: unbound-slot,  Prev: setf class-name,  Up: Objects Dictionary

7.7.39 class-of [Function]
--------------------------

'class-of' object => class

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

object--an object.

   class--a class object.

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

Returns the class of which the object is a direct instance.

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

      (class-of 'fred) =>  #<BUILT-IN-CLASS SYMBOL 610327300>
      (class-of 2/3) =>  #<BUILT-IN-CLASS RATIO 610326642>

      (defclass book () ()) =>  #<STANDARD-CLASS BOOK 33424745>
      (class-of (make-instance 'book)) =>  #<STANDARD-CLASS BOOK 33424745>

      (defclass novel (book) ()) =>  #<STANDARD-CLASS NOVEL 33424764>
      (class-of (make-instance 'novel)) =>  #<STANDARD-CLASS NOVEL 33424764>

      (defstruct kons kar kdr) =>  KONS
      (class-of (make-kons :kar 3 :kdr 4)) =>  #<STRUCTURE-CLASS KONS 250020317>

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

*note make-instance:: , *note type-of::


File: gcl.info,  Node: unbound-slot,  Next: unbound-slot-instance,  Prev: class-of,  Up: Objects Dictionary

7.7.40 unbound-slot [Condition Type]
------------------------------------

Class Precedence List::
.......................

unbound-slot, cell-error, error, serious-condition, condition, t

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

The object having the unbound slot is initialized by the :instance
initialization argument to make-condition, and is accessed by the
function unbound-slot-instance.

   The name of the cell (see cell-error) is the name of the slot.

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

*note cell-error-name:: , unbound-slot-object, *note Condition System
Concepts::


File: gcl.info,  Node: unbound-slot-instance,  Prev: unbound-slot,  Up: Objects Dictionary

7.7.41 unbound-slot-instance [Function]
---------------------------------------

'unbound-slot-instance' condition => instance

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

condition--a condition of type unbound-slot.

   instance--an object.

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

Returns the instance which had the unbound slot in the situation
represented by the condition.

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

*note cell-error-name:: , unbound-slot, *note Condition System
Concepts::


File: gcl.info,  Node: Structures,  Next: Conditions,  Prev: Objects,  Up: Top

8 Structures
************

* Menu:

* Structures Dictionary::


File: gcl.info,  Node: Structures Dictionary,  Prev: Structures,  Up: Structures

8.1 Structures Dictionary
=========================

* Menu:

* defstruct::
* copy-structure::


File: gcl.info,  Node: defstruct,  Next: copy-structure,  Prev: Structures Dictionary,  Up: Structures Dictionary

8.1.1 defstruct [Macro]
-----------------------

'defstruct' name-and-options [documentation] {!slot-description}*
=> structure-name

   name-and-options ::=structure-name | (structure-name [[!options]])

   options ::=!conc-name-option |             {!constructor-option}* |
            !copier-option |             !include-option |
            !initial-offset-option |             !named-option |
            !predicate-option |             !printer-option |
            !type-option

   conc-name-option ::=:conc-name | (:conc-name) | (:conc-name conc-name)

   constructor-option ::=:constructor |
                       (:constructor) |
                       (:constructor constructor-name) |
                       (:constructor constructor-name constructor-arglist)

   copier-option ::=:copier | (:copier) | (:copier copier-name)

   predicate-option ::=:predicate | (:predicate) | (:predicate predicate-name)

   include-option ::=(:include included-structure-name {!slot-description}*)

   printer-option ::=!print-object-option | !print-function-option

   print-object-option ::=(:print-object printer-name) | (:print-object)

   print-function-option ::=(:print-function printer-name) | (:print-function)

   type-option ::=(:type type)

   named-option ::=:named

   initial-offset-option ::=(:initial-offset initial-offset)

   slot-description ::=slot-name | 
                     (slot-name [slot-initform [[!slot-option]]])

   slot-option ::=:type slot-type | 
                :read-only slot-read-only-p

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

conc-name--a string designator.

   constructor-arglist--a boa lambda list.

   constructor-name--a symbol.

   copier-name--a symbol.

   included-structure-name--an already-defined structure name.

   Note that a derived type is not permissible, even if it would expand
into a structure name.

   initial-offset--a non-negative integer.

   predicate-name--a symbol.

   printer-name--a function name or a lambda expression.

   slot-name--a symbol.

   slot-initform--a form.

   slot-read-only-p--a generalized boolean.

   structure-name--a symbol.

   type--one of the type specifiers list, vector, or (vector size), or
some other type specifier defined by the implementation to be
appropriate.

   documentation--a string; not evaluated.

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

defstruct defines a structured type, named structure-type, with named
slots as specified by the slot-options.

   defstruct defines readers for the slots and arranges for setf to work
properly on such reader functions.  Also, unless overridden, it defines
a predicate named name-p, defines a constructor function named
make-constructor-name, and defines a copier function named
copy-constructor-name.  All names of automatically created functions
might automatically be declared inline (at the discretion of the
implementation).

   If documentation is supplied, it is attached to structure-name as a
documentation string of kind structure,

   and unless :type is used, the documentation is also attached to
structure-name as a documentation string of kind type and as a
documentation string to the class object for the class named
structure-name.

   defstruct defines a constructor function that is used to create
instances of the structure created by defstruct.  The default name is
make-structure-name.  A different name can be supplied by giving the
name as the argument to the constructor option.  nil indicates that no
constructor function will be created.

   After a new structure type has been defined, instances of that type
normally can be created by using the constructor function for the type.
A call to a constructor function is of the following form:

    (constructor-function-name
  slot-keyword-1 form-1
  slot-keyword-2 form-2
  ...)

   The arguments to the constructor function are all keyword arguments.
Each slot keyword argument must be a keyword whose name corresponds to
the name of a structure slot.  All the keywords and forms are evaluated.
If a slot is not initialized in this way, it is initialized by
evaluating slot-initform in the slot description

   at the time the constructor function is called.

   If no slot-initform is supplied, the consequences are undefined if an
attempt is later made to read the slot's value before a value is
explicitly assigned.

   Each slot-initform supplied for a defstruct component, when used by
the constructor function for an otherwise unsupplied component, is
re-evaluated on every call to the constructor function.

   The slot-initform is not evaluated unless it is needed in the
creation of a particular structure instance.  If it is never needed,
there can be no type-mismatch error, even if the type of the slot is
specified; no warning should be issued in this case.

   For example, in the following sequence, only the last call is an
error.

      (defstruct person (name 007 :type string))
      (make-person :name "James")
      (make-person)

   It is as if the slot-initforms were used as initialization forms for
the keyword parameters of the constructor function.

   The symbols which name the slots must not be used by the
implementation as the names for the lambda variables in the constructor
function, since one or more of those symbols might have been proclaimed
special or might be defined as the name of a constant variable.  The
slot default init forms are evaluated in the lexical environment in
which the defstruct form itself appears and in the dynamic environment
in which the call to the constructor function appears.

   For example, if the form (gensym) were used as an initialization
form, either in the constructor-function call or as the default
initialization form in defstruct, then every call to the constructor
function would call gensym once to generate a new symbol.

   Each slot-description in defstruct can specify zero or more
slot-options.

   A slot-option consists of a pair of a keyword and a value (which is
not a form to be evaluated, but the value itself).  For example:

      (defstruct ship
        (x-position 0.0 :type short-float)
        (y-position 0.0 :type short-float)
        (x-velocity 0.0 :type short-float)
        (y-velocity 0.0 :type short-float)
        (mass *default-ship-mass* :type short-float :read-only t))

   This specifies that each slot always contains a short float, and that
the last slot cannot be altered once a ship is constructed.

   The available slot-options are:

:type type
     This specifies that the contents of the slot is always of type
     type.  This is entirely analogous to the declaration of a variable
     or function; it effectively declares the result type of the reader
     function.  It is implementation-dependent whether the type is
     checked when initializing a slot or when assigning to it.  Type is
     not evaluated; it must be a valid type specifier.

:read-only x
     When x is true, this specifies that this slot cannot be altered; it
     will always contain the value supplied at construction time.  setf
     will not accept the reader function for this slot.  If x is false,
     this slot-option has no effect.  X is not evaluated.

     When this option is false or unsupplied, it is
     implementation-dependent whether the ability to write the slot is
     implemented by a setf function or a setf expander.

   The following keyword options are available for use with defstruct.
A defstruct option can be either a keyword or a list of a keyword and
arguments for that keyword; specifying the keyword by itself is
equivalent to specifying a list consisting of the keyword and no
arguments.  The syntax for defstruct options differs from the pair
syntax used for slot-options.  No part of any of these options is
evaluated.

:conc-name
     This provides for automatic prefixing of names of reader (or
     access) functions.  The default behavior is to begin the names of
     all the reader functions of a structure with the name of the
     structure followed by a hyphen.

     :conc-name supplies an alternate prefix to be used.  If a hyphen is
     to be used as a separator, it must be supplied as part of the
     prefix.  If :conc-name is nil or no argument is supplied, then no
     prefix is used; then the names of the reader functions are the same
     as the slot names.  If a non-nil prefix is given, the name of the
     reader function for each slot is constructed by concatenating that
     prefix and the name of the slot, and interning the resulting symbol
     in the package that is current at the time the defstruct form is
     expanded.

     Note that no matter what is supplied for :conc-name, slot keywords
     that match the slot names with no prefix attached are used with a
     constructor function.  The reader function name is used in
     conjunction with setf.  Here is an example:

           (defstruct (door (:conc-name dr-)) knob-color width material) =>  DOOR
           (setq my-door (make-door :knob-color 'red :width 5.0))
          =>  #S(DOOR :KNOB-COLOR RED :WIDTH 5.0 :MATERIAL NIL)
           (dr-width my-door) =>  5.0
           (setf (dr-width my-door) 43.7) =>  43.7
           (dr-width my-door) =>  43.7

     Whether or not the :conc-name option is explicitly supplied, the
     following rule governs name conflicts of generated reader (or
     accessor) names: For any structure type S_1 having a reader
     function named R for a slot named X_1 that is inherited by another
     structure type S_2 that would have a reader function with the same
     name R for a slot named X_2, no definition for R is generated by
     the definition of S_2; instead, the definition of R is inherited
     from the definition of S_1.  (In such a case, if X_1 and X_2 are
     different slots, the implementation might signal a style warning.)

:constructor
     This option takes zero, one, or two arguments.  If at least one
     argument is supplied and the first argument is not nil, then that
     argument is a symbol which specifies the name of the constructor
     function.  If the argument is not supplied (or if the option itself
     is not supplied), the name of the constructor is produced by
     concatenating the string "MAKE-" and the name of the structure,
     interning the name in whatever package is current at the time
     defstruct is expanded.  If the argument is provided and is nil, no
     constructor function is defined.

     If :constructor is given as (:constructor name arglist), then
     instead of making a keyword driven constructor function, defstruct
     defines a "positional" constructor function, taking arguments whose
     meaning is determined by the argument's position and possibly by
     keywords.  Arglist is used to describe what the arguments to the
     constructor will be.  In the simplest case something like
     (:constructor make-foo (a b c)) defines make-foo to be a
     three-argument constructor function whose arguments are used to
     initialize the slots named a, b, and c.

     Because a constructor of this type operates "By Order of
     Arguments," it is sometimes known as a "boa constructor."

     For information on how the arglist for a "boa constructor" is
     processed, see *note Boa Lambda Lists::.

     It is permissible to use the :constructor option more than once, so
     that you can define several different constructor functions, each
     taking different parameters.

     [Reviewer Note by Barmar: What about (:constructor) and
     (:constructor nil). 	Should we worry about it?]

     defstruct creates the default-named keyword constructor function
     only if no explicit :constructor options are specified, or if the
     :constructor option is specified without a name argument.

     (:constructor nil) is meaningful only when there are no other
     :constructor options specified.  It prevents defstruct from
     generating any constructors at all.

     Otherwise, defstruct creates a constructor function corresponding
     to each supplied :constructor option.  It is permissible to specify
     multiple keyword constructor functions as well as multiple "boa
     constructors".

:copier
     This option takes one argument, a symbol, which specifies the name
     of the copier function.  If the argument is not provided or if the
     option itself is not provided, the name of the copier is produced
     by concatenating the string "COPY-" and the name of the structure,
     interning the name in whatever package is current at the time
     defstruct is expanded.  If the argument is provided and is nil, no
     copier function is defined.

     The automatically defined copier function is a function of one
     argument,

     which must be of the structure type being defined.

     The copier function creates a fresh structure that has the same
     type as its argument, and that has the same component values as the
     original structure; that is, the component values are not copied
     recursively.

     If the defstruct :type option was not used, the following
     equivalence applies:

           (copier-name x) = (copy-structure (the structure-name x))

:include
     This option is used for building a new structure definition as an
     extension of another structure definition.  For example:

           (defstruct person name age sex)

     To make a new structure to represent an astronaut that has the
     attributes of name, age, and sex, and functions that operate on
     person structures, astronaut is defined with :include as follows:

           (defstruct (astronaut (:include person)
                                 (:conc-name astro-))
              helmet-size
              (favorite-beverage 'tang))

     :include causes the structure being defined to have the same slots
     as the included structure.  This is done in such a way that the
     reader functions for the included structure also work on the
     structure being defined.  In this example, an astronaut therefore
     has five slots: the three defined in person and the two defined in
     astronaut itself.  The reader functions defined by the person
     structure can be applied to instances of the astronaut structure,
     and they work correctly.  Moreover, astronaut has its own reader
     functions for components defined by the person structure.  The
     following examples illustrate the use of astronaut structures:

           (setq x (make-astronaut :name 'buzz
                                   :age 45.
                                   :sex t
                                   :helmet-size 17.5))
           (person-name x) =>  BUZZ
           (astro-name x) =>  BUZZ
           (astro-favorite-beverage x) =>  TANG

           (reduce #'+ astros :key #'person-age) ; obtains the total of the ages
                                                 ; of the possibly empty
                                                 ; sequence of astros

     The difference between the reader functions person-name and
     astro-name is that person-name can be correctly applied to any
     person, including an astronaut, while astro-name can be correctly
     applied only to an astronaut.  An implementation might check for
     incorrect use of reader functions.

     At most one :include can be supplied in a single defstruct.  The
     argument to :include is required and must be the name of some
     previously defined structure.  If the structure being defined has
     no :type option, then the included structure must also have had no
     :type option supplied for it.  If the structure being defined has a
     :type option, then the included structure must have been declared
     with a :type option specifying the same representation type.

     If no :type option is involved, then the structure name of the
     including structure definition becomes the name of a data type, and
     therefore a valid type specifier recognizable by typep; it becomes
     a subtype of the included structure.  In the above example,
     astronaut is a subtype of person; hence

           (typep (make-astronaut) 'person) =>  true

     indicating that all operations on persons also work on astronauts.

     The structure using :include can specify default values or
     slot-options for the included slots different from those the
     included structure specifies, by giving the :include option as:

           (:include included-structure-name {slot-description}*)

     Each slot-description must have a slot-name that is the same as
     that of some slot in the included structure.  If a slot-description
     has no slot-initform, then in the new structure the slot has no
     initial value.  Otherwise its initial value form is replaced by the
     slot-initform in the slot-description.  A normally writable slot
     can be made read-only.  If a slot is read-only in the included
     structure, then it must also be so in the including structure.  If
     a type is supplied for a slot, it must be a subtype of the type
     specified in the included structure.

     For example, if the default age for an astronaut is 45, then

           (defstruct (astronaut (:include person (age 45)))
              helmet-size
              (favorite-beverage 'tang))

     If :include is used with the :type option, then the effect is first
     to skip over as many representation elements as needed to represent
     the included structure, then to skip over any additional elements
     supplied by the :initial-offset option, and then to begin
     allocation of elements from that point.  For example:

           (defstruct (binop (:type list) :named (:initial-offset 2))
             (operator '? :type symbol)
             operand-1
             operand-2) =>  BINOP
           (defstruct (annotated-binop (:type list)
                                       (:initial-offset 3)
                                       (:include binop))
            commutative associative identity) =>  ANNOTATED-BINOP
           (make-annotated-binop :operator '*
                                 :operand-1 'x
                                 :operand-2 5
                                 :commutative t
                                 :associative t
                                 :identity 1)
             =>  (NIL NIL BINOP * X 5 NIL NIL NIL T T 1)

     The first two nil elements stem from the :initial-offset of 2 in
     the definition of binop.  The next four elements contain the
     structure name and three slots for binop.  The next three nil
     elements stem from the :initial-offset of 3 in the definition of
     annotated-binop.  The last three list elements contain the
     additional slots for an annotated-binop.

:initial-offset
     :initial-offset instructs defstruct to skip over a certain number
     of slots before it starts allocating the slots described in the
     body.  This option's argument is the number of slots defstruct
     should skip.  :initial-offset can be used only if :type is also
     supplied.

     [Reviewer Note by Barmar: What are initial values of the skipped
     slots?]

     :initial-offset allows slots to be allocated beginning at a
     representational element other than the first.  For example, the
     form

           (defstruct (binop (:type list) (:initial-offset 2))
             (operator '? :type symbol)
             operand-1
             operand-2) =>  BINOP

     would result in the following behavior for make-binop:

           (make-binop :operator '+ :operand-1 'x :operand-2 5)
          =>  (NIL NIL + X 5)
           (make-binop :operand-2 4 :operator '*)
          =>  (NIL NIL * NIL 4)

     The selector functions binop-operator, binop-operand-1, and
     binop-operand-2 would be essentially equivalent to third, fourth,
     and fifth, respectively.  Similarly, the form

           (defstruct (binop (:type list) :named (:initial-offset 2))
             (operator '? :type symbol)
             operand-1
             operand-2) =>  BINOP

     would result in the following behavior for make-binop:

           (make-binop :operator '+ :operand-1 'x :operand-2 5) =>  (NIL NIL BINOP + X 5)
           (make-binop :operand-2 4 :operator '*) =>  (NIL NIL BINOP * NIL 4)

     The first two nil elements stem from the :initial-offset of 2 in
     the definition of binop.  The next four elements contain the
     structure name and three slots for binop.

:named
     :named specifies that the structure is named.  If no :type is
     supplied, then the structure is always named.

     For example:

           (defstruct (binop (:type list))
             (operator '? :type symbol)
             operand-1
             operand-2) =>  BINOP

     This defines a constructor function make-binop and three selector
     functions, namely binop-operator, binop-operand-1, and
     binop-operand-2.  (It does not, however, define a predicate
     binop-p, for reasons explained below.)

     The effect of make-binop is simply to construct a list of length
     three:

           (make-binop :operator '+ :operand-1 'x :operand-2 5) =>  (+ X 5)
           (make-binop :operand-2 4 :operator '*) =>  (* NIL 4)

     It is just like the function list except that it takes keyword
     arguments and performs slot defaulting appropriate to the binop
     conceptual data type.  Similarly, the selector functions
     binop-operator, binop-operand-1, and binop-operand-2 are
     essentially equivalent to car, cadr, and caddr, respectively.  They
     might not be completely equivalent because, for example, an
     implementation would be justified in adding error-checking code to
     ensure that the argument to each selector function is a length-3
     list.

     binop is a conceptual data type in that it is not made a part of
     the Common Lisp type system.  typep does not recognize binop as a
     type specifier, and type-of returns list when given a binop
     structure.  There is no way to distinguish a data structure
     constructed by make-binop from any other list that happens to have
     the correct structure.

     There is not any way to recover the structure name binop from a
     structure created by make-binop.  This can only be done if the
     structure is named.  A named structure has the property that, given
     an instance of the structure, the structure name (that names the
     type) can be reliably recovered.  For structures defined with no
     :type option, the structure name actually becomes part of the
     Common Lisp data-type system.  type-of, when applied to such a
     structure, returns the structure name as the type of the object;
     typep recognizes the structure name as a valid type specifier.

     For structures defined with a :type option, type-of returns a type
     specifier such as list or (vector t), depending on the type
     supplied to the :type option.  The structure name does not become a
     valid type specifier.  However, if the :named option is also
     supplied, then the first component of the structure (as created by
     a defstruct constructor function) always contains the structure
     name.  This allows the structure name to be recovered from an
     instance of the structure and allows a reasonable predicate for the
     conceptual type to be defined: the automatically defined name-p
     predicate for the structure operates by first checking that its
     argument is of the proper type (list, (vector t), or whatever) and
     then checking whether the first component contains the appropriate
     type name.

     Consider the binop example shown above, modified only to include
     the :named option:

           (defstruct (binop (:type list) :named)
             (operator '? :type symbol)
             operand-1
             operand-2) =>  BINOP

     As before, this defines a constructor function make-binop and three
     selector functions binop-operator, binop-operand-1, and
     binop-operand-2.  It also defines a predicate binop-p.  The effect
     of make-binop is now to construct a list of length four:

           (make-binop :operator '+ :operand-1 'x :operand-2 5) =>  (BINOP + X 5)
           (make-binop :operand-2 4 :operator '*) =>  (BINOP * NIL 4)

     The structure has the same layout as before except that the
     structure name binop is included as the first list element.  The
     selector functions binop-operator, binop-operand-1, and
     binop-operand-2 are essentially equivalent to cadr, caddr, and
     cadddr, respectively.  The predicate binop-p is more or less
     equivalent to this definition:

           (defun binop-p (x)
             (and (consp x) (eq (car x) 'binop))) =>  BINOP-P

     The name binop is still not a valid type specifier recognizable to
     typep, but at least there is a way of distinguishing binop
     structures from other similarly defined structures.

:predicate
     This option takes one argument, which specifies the name of the
     type predicate.  If the argument is not supplied or if the option
     itself is not supplied, the name of the predicate is made by
     concatenating the name of the structure to the string "-P",
     interning the name in whatever package is current at the time
     defstruct is expanded.  If the argument is provided and is nil, no
     predicate is defined.  A predicate can be defined only if the
     structure is named; if :type is supplied and :named is not
     supplied, then :predicate must either be unsupplied or have the
     value nil.

:print-function, :print-object
     The :print-function and :print-object options specify that a
     print-object method for structures of type structure-name should be
     generated.  These options are not synonyms, but do perform a
     similar service; the choice of which option (:print-function or
     :print-object) is used affects how the function named printer-name
     is called.  Only one of these options may be used, and these
     options may be used only if :type is not supplied.

     If the :print-function option is used, then when a structure of
     type structure-name is to be printed, the designated printer
     function is called on three arguments:

     -
          the structure to be printed (a generalized instance of
          structure-name).

     -
          a stream to print to.

     -
          an integer indicating the current depth. 	The magnitude of
          this integer may vary between implementations; however, it can
          reliably be compared against *print-level* to determine
          whether depth abbreviation is appropriate.

     Specifying (:print-function printer-name) is approximately
     equivalent to specifying:

           (defmethod print-object ((object structure-name) stream)
             (funcall (function printer-name) object stream <<current-print-depth>>))

     where the <<current-print-depth>> represents the printer's belief
     of how deep it is currently printing.  It is
     implementation-dependent whether <<current-print-depth>> is always
     0 and *print-level*, if non-nil, is re-bound to successively
     smaller values as printing descends recursively, or whether
     current-print-depth varies in value as printing descends
     recursively and *print-level* remains constant during the same
     traversal.

     If the :print-object option is used, then when a structure of type
     structure-name is to be printed, the designated printer function is
     called on two arguments:

     -
          the structure to be printed.

     -
          the stream to print to.

     Specifying (:print-object printer-name) is equivalent to
     specifying:

           (defmethod print-object ((object structure-name) stream)
             (funcall (function printer-name) object stream))

     If no :type option is supplied, and if either a :print-function or
     a :print-object option is supplied, and if no printer-name is
     supplied, then a print-object method specialized for structure-name
     is generated that calls a function that implements the default
     printing behavior for structures using #S notation; see *note
     Printing Structures::.

     If neither a :print-function nor a :print-object option is
     supplied, then defstruct does not generate a print-object method
     specialized for structure-name and some default behavior is
     inherited either from a structure named in an :include option or
     from the default behavior for printing structures; see the function
     print-object and *note Printing Structures::.

     When *print-circle* is true, a user-defined print function can
     print objects to the supplied stream using write, prin1, princ, or
     format and expect circularities to be detected and printed using
     the #n# syntax.  This applies to methods on print-object in
     addition to :print-function options.  If a user-defined print
     function prints to a stream other than the one that was supplied,
     then circularity detection starts over for that stream.  See the
     variable *print-circle*.

:type
     :type explicitly specifies the representation to be used for the
     structure.  Its argument must be one of these types:

     vector
          This produces the same result as specifying (vector t).  The
          structure is represented as a general vector, storing
          components as vector elements.  The first component is vector
          element 1 if the structure is :named, and element 0 otherwise.

          [Reviewer Note by Barmar: Do any implementations create
          non-simple vectors?]

     (vector element-type)
          The structure is represented as a (possibly specialized)
          vector, storing components as vector elements.  Every
          component must be of a type that can be stored in a vector of
          the type specified.  The first component is vector element 1
          if the structure is :named, and element 0 otherwise.  The
          structure can be :named only if the type symbol is a subtype
          of the supplied element-type.

     list
          The structure is represented as a list.  The first component
          is the cadr if the structure is :named, and the car if it is
          not :named.

     Specifying this option has the effect of forcing a specific
     representation and of forcing the components to be stored in the
     order specified in defstruct in corresponding successive elements
     of the specified representation.  It also prevents the structure
     name from becoming a valid type specifier recognizable by typep.

     For example:

           (defstruct (quux (:type list) :named) x y)

     should make a constructor that builds a list exactly like the one
     that list produces, with quux as its car.

     If this type is defined:

           (deftype quux () '(satisfies quux-p))

     then this form

           (typep (make-quux) 'quux)

     should return precisely what this one does

           (typep (list 'quux nil nil) 'quux)

     If :type is not supplied, the structure is represented as an object
     of type structure-object.

     defstruct without a :type option defines a class with the structure
     name as its name.  The metaclass of structure instances is
     structure-class.

   The consequences of redefining a defstruct structure are undefined.

   In the case where no defstruct options have been supplied, the
following functions are automatically defined to operate on instances of
the new structure:

Predicate
     A predicate with the name structure-name-p is defined to test
     membership in the structure type.  The predicate (structure-name-p
     object) is true if an object is of this type; otherwise it is
     false.  typep can also be used with the name of the new type to
     test whether an object belongs to the type.  Such a function call
     has the form (typep object 'structure-name).

Component reader functions
     Reader functions are defined to read the components of the
     structure.  For each slot name, there is a corresponding reader
     function with the name structure-name-slot-name.  This function
     reads the contents of that slot.  Each reader function takes one
     argument, which is an instance of the structure type.  setf can be
     used with any of these reader functions to alter the slot contents.

Constructor function
     A constructor function with the name make-structure-name is
     defined.  This function creates and returns new instances of the
     structure type.

Copier function
     A copier function with the name copy-structure-name is defined.
     The copier function takes an object of the structure type and
     creates a new object of the same type that is a copy of the first.
     The copier function creates a new structure with the same component
     entries as the original.  Corresponding components of the two
     structure instances are eql.

   If a defstruct form appears as a top level form, the compiler must
make the structure type name recognized as a valid type name in
subsequent declarations (as for deftype) and make the structure slot
readers known to setf.  In addition, the compiler must save enough
information about the structure type so that further defstruct
definitions can use :include in a subsequent deftype in the same file to
refer to the structure type name.  The functions which defstruct
generates are not defined in the compile time environment, although the
compiler may save enough information about the functions to code
subsequent calls inline.  The #S reader macro might or might not
recognize the newly defined structure type name at compile time.

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

An example of a structure definition follows:

      (defstruct ship
        x-position
        y-position
        x-velocity
        y-velocity
        mass)

   This declares that every ship is an object with five named
components.  The evaluation of this form does the following:

1.
     It defines ship-x-position to be a function of one argument, a
     ship, that returns the x-position of the ship; ship-y-position and
     the other components are given similar function definitions.  These
     functions are called the access functions, as they are used to
     access elements of the structure.

2.
     ship becomes the name of a type of which instances of ships are
     elements.  ship becomes acceptable to typep, for example; (typep x
     'ship) is true if x is a ship and false if x is any object other
     than a ship.

3.
     A function named ship-p of one argument is defined; it is a
     predicate that is true if its argument is a ship and is false
     otherwise.

4.
     A function called make-ship is defined that, when invoked, creates
     a data structure with five components, suitable for use with the
     access functions.  Thus executing

           (setq ship2 (make-ship))

     sets ship2 to a newly created ship object.  One can supply the
     initial values of any desired component in the call to make-ship by
     using keyword arguments in this way:

           (setq ship2 (make-ship :mass *default-ship-mass*
                                  :x-position 0
                                  :y-position 0))

     This constructs a new ship and initializes three of its components.
     This function is called the "constructor function" because it
     constructs a new structure.

5.
     A function called copy-ship of one argument is defined that, when
     given a ship object, creates a new ship object that is a copy of
     the given one.  This function is called the "copier function."

   setf can be used to alter the components of a ship:

      (setf (ship-x-position ship2) 100)

   This alters the x-position of ship2 to be 100.  This works because
defstruct behaves as if it generates an appropriate defsetf for each
access function.

     ;;;
     ;;; Example 1
     ;;; define town structure type
     ;;; area, watertowers, firetrucks, population, elevation are its components
     ;;;
      (defstruct town
                  area
                  watertowers
                  (firetrucks 1 :type fixnum)    ;an initialized slot
                  population
                  (elevation 5128 :read-only t)) ;a slot that can't be changed
     =>  TOWN
     ;create a town instance
      (setq town1 (make-town :area 0 :watertowers 0)) =>  #S(TOWN...)
     ;town's predicate recognizes the new instance
      (town-p town1) =>  true
     ;new town's area is as specified by make-town
      (town-area town1) =>  0
     ;new town's elevation has initial value
      (town-elevation town1) =>  5128
     ;setf recognizes reader function
      (setf (town-population town1) 99) =>  99
      (town-population town1) =>  99
     ;copier function makes a copy of town1
      (setq town2 (copy-town town1)) =>  #S(TOWN...)
      (= (town-population town1) (town-population town2))  =>  true
     ;since elevation is a read-only slot, its value can be set only
     ;when the structure is created
      (setq town3 (make-town :area 0 :watertowers 3 :elevation 1200))
     =>  #S(TOWN...)
     ;;;
     ;;; Example 2
     ;;; define clown structure type
     ;;; this structure uses a nonstandard prefix
     ;;;
      (defstruct (clown (:conc-name bozo-))
                  (nose-color 'red)
                  frizzy-hair-p polkadots) =>  CLOWN
      (setq funny-clown (make-clown)) =>  #S(CLOWN)
     ;use non-default reader name
      (bozo-nose-color funny-clown) =>  RED
      (defstruct (klown (:constructor make-up-klown) ;similar def using other
                  (:copier clone-klown)              ;customizing keywords
                  (:predicate is-a-bozo-p))
                  nose-color frizzy-hair-p polkadots) =>  klown
     ;custom constructor now exists
      (fboundp 'make-up-klown) =>  true
     ;;;
     ;;; Example 3
     ;;; define a vehicle structure type
     ;;; then define a truck structure type that includes
     ;;; the vehicle structure
     ;;;
      (defstruct vehicle name year (diesel t :read-only t)) =>  VEHICLE
      (defstruct (truck (:include vehicle (year 79)))
                  load-limit
                  (axles 6)) =>  TRUCK
      (setq x (make-truck :name 'mac :diesel t :load-limit 17))
     =>  #S(TRUCK...)
     ;vehicle readers work on trucks
      (vehicle-name x)
     =>  MAC
     ;default taken from :include clause
      (vehicle-year x)
     =>  79
      (defstruct (pickup (:include truck))     ;pickup type includes truck
                  camper long-bed four-wheel-drive) =>  PICKUP
      (setq x (make-pickup :name 'king :long-bed t)) =>  #S(PICKUP...)
     ;:include default inherited
      (pickup-year x) =>  79
     ;;;
     ;;; Example 4
     ;;; use of BOA constructors
     ;;;
      (defstruct (dfs-boa                      ;BOA constructors
                    (:constructor make-dfs-boa (a b c))
                    (:constructor create-dfs-boa
                      (a &optional b (c 'cc) &rest d &aux e (f 'ff))))
                  a b c d e f) =>  DFS-BOA
     ;a, b, and c set by position, and the rest are uninitialized
      (setq x (make-dfs-boa 1 2 3)) =>  #(DFS-BOA...)
      (dfs-boa-a x) =>  1
     ;a and b set, c and f defaulted
      (setq x (create-dfs-boa 1 2)) =>  #(DFS-BOA...)
      (dfs-boa-b x) =>  2
      (eq (dfs-boa-c x) 'cc) =>  true
     ;a, b, and c set, and the rest are collected into d
      (setq x (create-dfs-boa 1 2 3 4 5 6)) =>  #(DFS-BOA...)
      (dfs-boa-d x) =>  (4 5 6)

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

If any two slot names (whether present directly or inherited by the
:include option) are the same under string=, defstruct should signal an
error of type program-error.

   The consequences are undefined if the included-structure-name does
not name a structure type.

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

*note documentation:: , *note print-object:: , *note setf:: , *note
subtypep:: , *note type-of:: , *note typep:: , *note Compilation::

Notes::
.......

The printer-name should observe the values of such printer-control
variables as *print-escape*.

   The restriction against issuing a warning for type mismatches between
a slot-initform and the corresponding slot's :type option is necessary
because a slot-initform must be specified in order to specify slot
options; in some cases, no suitable default may exist.

   The mechanism by which defstruct arranges for slot accessors to be
usable with setf is implementation-dependent; for example, it may use
setf functions, setf expanders, or some other implementation-dependent
mechanism known to that implementation's code for setf.


File: gcl.info,  Node: copy-structure,  Prev: defstruct,  Up: Structures Dictionary

8.1.2 copy-structure [Function]
-------------------------------

'copy-structure' structure => copy

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

structure--a structure.

   copy--a copy of the structure.

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

Returns a copy_6 of the structure.

   Only the structure itself is copied; not the values of the slots.

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

the :copier option to *note defstruct::

Notes::
.......

The copy is the same as the given structure under equalp, but not under
equal.


File: gcl.info,  Node: Conditions,  Next: Symbols,  Prev: Structures,  Up: Top

9 Conditions
************

* Menu:

* Condition System Concepts::
* Conditions Dictionary::


File: gcl.info,  Node: Condition System Concepts,  Next: Conditions Dictionary,  Prev: Conditions,  Up: Conditions

9.1 Condition System Concepts
=============================

Common Lisp constructs are described not only in terms of their behavior
in situations during which they are intended to be used (see the
"Description" part of each operator specification), but in all other
situations (see the "Exceptional Situations" part of each operator
specification).

   A situation is the evaluation of an expression in a specific context.
A condition is an object that represents a specific situation that has
been detected.  Conditions are generalized instances of the class
condition.  A hierarchy of condition classes is defined in Common Lisp.
A condition has slots that contain data relevant to the situation that
the condition represents.

   An error is a situation in which normal program execution cannot
continue correctly without some form of intervention (either
interactively by the user or under program control).  Not all errors are
detected.  When an error goes undetected, the effects can be
implementation-dependent, implementation-defined, unspecified, or
undefined.  See *note Definitions::.  All detected errors can be
represented by conditions, but not all conditions represent errors.

   Signaling is the process by which a condition can alter the flow of
control in a program by raising the condition which can then be handled.
The functions error, cerror, signal, and warn are used to signal
conditions.

   The process of signaling involves the selection and invocation of a
handler from a set of active handlers.  A handler is a function of one
argument (the condition) that is invoked to handle a condition.  Each
handler is associated with a condition type, and a handler will be
invoked only on a condition of the handler's associated type.

   Active handlers are established dynamically (see handler-bind or
handler-case).  Handlers are invoked in a dynamic environment equivalent
to that of the signaler, except that the set of active handlers is bound
in such a way as to include only those that were active at the time the
handler being invoked was established.  Signaling a condition has no
side-effect on the condition, and there is no dynamic state contained in
a condition.

   If a handler is invoked, it can address the situation in one of three
ways:

Decline
     It can decline to handle the condition.  It does this by simply
     returning rather than transferring control.  When this happens, any
     values returned by the handler are ignored and the next most
     recently established handler is invoked.  If there is no such
     handler and the signaling function is error or cerror, the debugger
     is entered in the dynamic environment of the signaler.  If there is
     no such handler and the signaling function is either signal or
     warn, the signaling function simply returns~nil.

Handle
     It can handle the condition by performing a non-local transfer of
     control.  This can be done either primitively by using go, return,
     throw or more abstractly by using a function such as abort or
     invoke-restart.

Defer
     It can put off a decision about whether to handle or decline, by
     any of a number of actions, but most commonly by signaling another
     condition, resignaling the same condition, or forcing entry into
     the debugger.

* Menu:

* Condition Types::
* Creating Conditions::
* Printing Conditions::
* Signaling and Handling Conditions::
* Assertions::
* Notes about the Condition System`s Background::


File: gcl.info,  Node: Condition Types,  Next: Creating Conditions,  Prev: Condition System Concepts,  Up: Condition System Concepts

9.1.1 Condition Types
---------------------

Figure 9-1 lists the standardized condition types.  Additional condition
types can be defined by using define-condition.

 arithmetic-error                 floating-point-overflow  simple-type-error  
 cell-error                       floating-point-underflow simple-warning     
 condition                        package-error            storage-condition  
 control-error                    parse-error              stream-error       
 division-by-zero                 print-not-readable       style-warning      
 end-of-file                      program-error            type-error         
 error                            reader-error             unbound-slot       
 file-error                       serious-condition        unbound-variable   
 floating-point-inexact           simple-condition         undefined-function 
 floating-point-invalid-operation simple-error             warning            

                    Figure 9-1: Standardized Condition Types                  


   All condition types are subtypes of type condition.  That is,

      (typep c 'condition) =>  true

   if and only if c is a condition.

   Implementations must define all specified subtype relationships.
Except where noted, all subtype relationships indicated in this document
are not mutually exclusive.  A condition inherits the structure of its
supertypes.

   The metaclass of the class condition is not specified.  Names of
condition types may be used to specify supertype relationships in
define-condition, but the consequences are not specified if an attempt
is made to use a condition type as a superclass in a defclass form.

   Figure 9-2 shows operators that define condition types and creating
conditions.

  define-condition  make-condition    

  Figure 9-2: Operators that define and create conditions.


   Figure 9-3 shows operators that read the value of condition slots.

  arithmetic-error-operands   simple-condition-format-arguments  
  arithmetic-error-operation  simple-condition-format-control    
  cell-error-name             stream-error-stream                
  file-error-pathname         type-error-datum                   
  package-error-package       type-error-expected-type           
  print-not-readable-object   unbound-slot-instance              

         Figure 9-3: Operators that read condition slots.       


* Menu:

* Serious Conditions::


File: gcl.info,  Node: Serious Conditions,  Prev: Condition Types,  Up: Condition Types

9.1.1.1 Serious Conditions
..........................

A serious condition is a condition serious enough to require interactive
intervention if not handled.  Serious conditions are typically signaled
with error or cerror; non-serious conditions are typically signaled with
signal or warn.


File: gcl.info,  Node: Creating Conditions,  Next: Printing Conditions,  Prev: Condition Types,  Up: Condition System Concepts

9.1.2 Creating Conditions
-------------------------

The function make-condition can be used to construct a condition object
explicitly.  Functions such as error, cerror, signal, and warn operate
on conditions and might create condition objects implicitly.  Macros
such as ccase, ctypecase, ecase, etypecase, check-type, and assert might
also implicitly create (and signal) conditions.

* Menu:

* Condition Designators::


File: gcl.info,  Node: Condition Designators,  Prev: Creating Conditions,  Up: Creating Conditions

9.1.2.1 Condition Designators
.............................

A number of the functions in the condition system take arguments which
are identified as condition designators .  By convention, those
arguments are notated as

   datum &rest arguments

   Taken together, the datum and the arguments are "designators for a
condition of default type default-type."  How the denoted condition is
computed depends on the type of the datum:

* If the datum is a symbol
     naming a condition type ...  The denoted condition is the result of

           (apply #'make-condition datum arguments)

* If the datum is a format control ...

     The denoted condition is the result of

           (make-condition defaulted-type
                           :format-control datum
                           :format-arguments arguments)

     where the defaulted-type is a subtype of default-type.

* If the datum is a condition ...
     The denoted condition is the datum itself.  In this case, unless
     otherwise specified by the description of the operator in question,
     the arguments must be null; that is, the consequences are undefined
     if any arguments were supplied.

   Note that the default-type gets used only in the case where the datum
string is supplied.  In the other situations, the resulting condition is
not necessarily of type default-type.

   Here are some illustrations of how different condition designators
can denote equivalent condition objects:

     (let ((c (make-condition 'arithmetic-error :operator '/ :operands '(7 0))))
       (error c))
     == (error 'arithmetic-error :operator '/ :operands '(7 0))

     (error "Bad luck.")
     == (error 'simple-error :format-control "Bad luck." :format-arguments '())


File: gcl.info,  Node: Printing Conditions,  Next: Signaling and Handling Conditions,  Prev: Creating Conditions,  Up: Condition System Concepts

9.1.3 Printing Conditions
-------------------------

If the :report argument to define-condition is used, a print function is
defined that is called whenever the defined condition is printed while
the value of *print-escape* is false.  This function is called the
condition reporter ; the text which it outputs is called a report
message .

   When a condition is printed and *print-escape* is false, the
condition reporter for the condition is invoked.  Conditions are printed
automatically by functions such as invoke-debugger, break, and warn.

   When *print-escape* is true, the object should print in an
abbreviated fashion according to the style of the implementation (e.g.,
by print-unreadable-object).  It is not required that a condition can be
recreated by reading its printed representation.

   No function is provided for directly accessing or invoking condition
reporters.

* Menu:

* Recommended Style in Condition Reporting::
* Capitalization and Punctuation in Condition Reports::
* Leading and Trailing Newlines in Condition Reports::
* Embedded Newlines in Condition Reports::
* Note about Tabs in Condition Reports::
* Mentioning Containing Function in Condition Reports::


File: gcl.info,  Node: Recommended Style in Condition Reporting,  Next: Capitalization and Punctuation in Condition Reports,  Prev: Printing Conditions,  Up: Printing Conditions

9.1.3.1 Recommended Style in Condition Reporting
................................................

In order to ensure a properly aesthetic result when presenting report
messages to the user, certain stylistic conventions are recommended.

   There are stylistic recommendations for the content of the messages
output by condition reporters, but there are no formal requirements on
those programs.  If a program violates the recommendations for some
message, the display of that message might be less aesthetic than if the
guideline had been observed, but the program is still considered a
conforming program.

   The requirements on a program or implementation which invokes a
condition reporter are somewhat stronger.  A conforming program must be
permitted to assume that if these style guidelines are followed, proper
aesthetics will be maintained.  Where appropriate, any specific
requirements on such routines are explicitly mentioned below.


File: gcl.info,  Node: Capitalization and Punctuation in Condition Reports,  Next: Leading and Trailing Newlines in Condition Reports,  Prev: Recommended Style in Condition Reporting,  Up: Printing Conditions

9.1.3.2 Capitalization and Punctuation in Condition Reports
...........................................................

It is recommended that a report message be a complete sentences, in the
proper case and correctly punctuated.  In English, for example, this
means the first letter should be uppercase, and there should be a
trailing period.

      (error "This is a message")  ; Not recommended
      (error "this is a message.") ; Not recommended

      (error "This is a message.") ; Recommended instead


File: gcl.info,  Node: Leading and Trailing Newlines in Condition Reports,  Next: Embedded Newlines in Condition Reports,  Prev: Capitalization and Punctuation in Condition Reports,  Up: Printing Conditions

9.1.3.3 Leading and Trailing Newlines in Condition Reports
..........................................................

It is recommended that a report message not begin with any introductory
text, such as "Error: " or "Warning: " or even just freshline or
newline.  Such text is added, if appropriate to the context, by the
routine invoking the condition reporter.

   It is recommended that a report message not be followed by a trailing
freshline or newline.  Such text is added, if appropriate to the
context, by the routine invoking the condition reporter.

      (error "This is a message.~
      (error "~&This is a message.")   ; Not recommended
      (error "~&This is a message.~

      (error "This is a message.")     ; Recommended instead


File: gcl.info,  Node: Embedded Newlines in Condition Reports,  Next: Note about Tabs in Condition Reports,  Prev: Leading and Trailing Newlines in Condition Reports,  Up: Printing Conditions

9.1.3.4 Embedded Newlines in Condition Reports
..............................................

Especially if it is long, it is permissible and appropriate for a report
message to contain one or more embedded newlines.

   If the calling routine conventionally inserts some additional prefix
(such as "Error: " or ";; Error: ") on the first line of the message, it
must also assure that an appropriate prefix will be added to each
subsequent line of the output, so that the left edge of the message
output by the condition reporter will still be properly aligned.

      (defun test ()
        (error "This is an error message.~%It has two lines."))

      ;; Implementation A
      (test)
      This is an error message.
      It has two lines.

      ;; Implementation B
      (test)
      ;; Error: This is an error message.
      ;;        It has two lines.

      ;; Implementation C
      (test)
      >> Error: This is an error message.
                It has two lines.


File: gcl.info,  Node: Note about Tabs in Condition Reports,  Next: Mentioning Containing Function in Condition Reports,  Prev: Embedded Newlines in Condition Reports,  Up: Printing Conditions

9.1.3.5 Note about Tabs in Condition Reports
............................................

Because the indentation of a report message might be shifted to the
right or left by an arbitrary amount, special care should be taken with
the semi-standard character <Tab> (in those implementations that support
such a character).  Unless the implementation specifically defines its
behavior in this context, its use should be avoided.


File: gcl.info,  Node: Mentioning Containing Function in Condition Reports,  Prev: Note about Tabs in Condition Reports,  Up: Printing Conditions

9.1.3.6 Mentioning Containing Function in Condition Reports
...........................................................

The name of the containing function should generally not be mentioned in
report messages.  It is assumed that the debugger will make this
information accessible in situations where it is necessary and
appropriate.


File: gcl.info,  Node: Signaling and Handling Conditions,  Next: Assertions,  Prev: Printing Conditions,  Up: Condition System Concepts

9.1.4 Signaling and Handling Conditions
---------------------------------------

The operation of the condition system depends on the ordering of active
applicable handlers from most recent to least recent.

   Each handler is associated with a type specifier that must designate
a subtype of type condition.  A handler is said to be applicable to a
condition if that condition is of the type designated by the associated
type specifier.

   Active handlers are established by using handler-bind (or an
abstraction based on handler-bind, such as handler-case or
ignore-errors).

   Active handlers can be established within the dynamic scope of other
active handlers.  At any point during program execution, there is a set
of active handlers.  When a condition is signaled, the most recent
active applicable handler for that condition is selected from this set.
Given a condition, the order of recentness of active applicable handlers
is defined by the following two rules:

1.
     Each handler in a set of active handlers H_1 is more recent than
     every handler in a set H_2 if the handlers in H_2 were active when
     the handlers in H_1 were established.

2.
     Let h_1 and h_2 be two applicable active handlers established by
     the same form.  Then h_1 is more recent than h_2 if h_1 was defined
     to the left of h_2 in the form that established them.

   Once a handler in a handler binding form (such as handler-bind or
handler-case) has been selected, all handlers in that form become
inactive for the remainder of the signaling process.  While the selected
handler runs, no other handler established by that form is active.  That
is, if the handler declines, no other handler established by that form
will be considered for possible invocation.

   Figure 9-4 shows operators relating to the handling of conditions.

  handler-bind  handler-case  ignore-errors  

  Figure 9-4: Operators relating to handling conditions.


* Menu:

* Signaling::
* Resignaling a Condition::
* Restarts::
* Interactive Use of Restarts::
* Interfaces to Restarts::
* Restart Tests::
* Associating a Restart with a Condition::


File: gcl.info,  Node: Signaling,  Next: Resignaling a Condition,  Prev: Signaling and Handling Conditions,  Up: Signaling and Handling Conditions

9.1.4.1 Signaling
.................

When a condition is signaled, the most recent applicable active handler
is invoked.  Sometimes a handler will decline by simply returning
without a transfer of control.  In such cases, the next most recent
applicable active handler is invoked.

   If there are no applicable handlers for a condition that has been
signaled, or if all applicable handlers decline, the condition is
unhandled.

   The functions cerror and error invoke the interactive condition
handler (the debugger) rather than return if the condition being
signaled, regardless of its type, is unhandled.  In contrast, signal
returns nil if the condition being signaled, regardless of its type, is
unhandled.

   The variable *break-on-signals* can be used to cause the debugger to
be entered before the signaling process begins.

   Figure 9-5 shows defined names relating to the signaling of
conditions.

  *break-on-signals*  error   warn  
  cerror              signal        

  Figure 9-5: Defined names relating to signaling conditions.



File: gcl.info,  Node: Resignaling a Condition,  Next: Restarts,  Prev: Signaling,  Up: Signaling and Handling Conditions

9.1.4.2 Resignaling a Condition
...............................

During the dynamic extent of the signaling process for a particular
condition object, signaling the same condition object again is permitted
if and only if the situation represented in both cases are the same.

   For example, a handler might legitimately signal the condition object
that is its argument in order to allow outer handlers first opportunity
to handle the condition.  (Such a handlers is sometimes called a
"default handler.")  This action is permitted because the situation
which the second signaling process is addressing is really the same
situation.

   On the other hand, in an implementation that implemented asynchronous
keyboard events by interrupting the user process with a call to signal,
it would not be permissible for two distinct asynchronous keyboard
events to signal identical condition objects at the same time for
different situations.


File: gcl.info,  Node: Restarts,  Next: Interactive Use of Restarts,  Prev: Resignaling a Condition,  Up: Signaling and Handling Conditions

9.1.4.3 Restarts
................

The interactive condition handler returns only through non-local
transfer of control to specially defined restarts that can be set up
either by the system or by user code.  Transferring control to a restart
is called "invoking" the restart.  Like handlers, active restarts are
established dynamically, and only active restarts can be invoked.  An
active restart can be invoked by the user from the debugger or by a
program by using invoke-restart.

   A restart contains a function to be called when the restart is
invoked, an optional name that can be used to find or invoke the
restart, and an optional set of interaction information for the debugger
to use to enable the user to manually invoke a restart.

   The name of a restart is used by invoke-restart.  Restarts that can
be invoked only within the debugger do not need names.

   Restarts can be established by using restart-bind, restart-case, and
with-simple-restart.  A restart function can itself invoke any other
restart that was active at the time of establishment of the restart of
which the function is part.

   The restarts established by a restart-bind form, a restart-case form,
or a with-simple-restart form have dynamic extent which extends for the
duration of that form's execution.

   Restarts of the same name can be ordered from least recent to most
recent according to the following two rules:

1.
     Each restart in a set of active restarts R_1 is more recent than
     every restart in a set R_2 if the restarts in R_2 were active when
     the restarts in R_1 were established.

2.
     Let r_1 and r_2 be two active restarts with the same name
     established by the same form.  Then r_1 is more recent than r_2 if
     r_1 was defined to the left of r_2 in the form that established
     them.

   If a restart is invoked but does not transfer control, the values
resulting from the restart function are returned by the function that
invoked the restart, either invoke-restart or
invoke-restart-interactively.


File: gcl.info,  Node: Interactive Use of Restarts,  Next: Interfaces to Restarts,  Prev: Restarts,  Up: Signaling and Handling Conditions

9.1.4.4 Interactive Use of Restarts
...................................

For interactive handling, two pieces of information are needed from a
restart: a report function and an interactive function.

   The report function is used by a program such as the debugger to
present a description of the action the restart will take.  The report
function is specified and established by the :report-function keyword to
restart-bind or the :report keyword to restart-case.

   The interactive function, which can be specified using the
:interactive-function keyword to restart-bind or :interactive keyword to
restart-case, is used when the restart is invoked interactively, such as
from the debugger, to produce a suitable list of arguments.

   invoke-restart invokes the most recently established restart whose
name is the same as the first argument to invoke-restart.  If a restart
is invoked interactively by the debugger and does not transfer control
but rather returns values, the precise action of the debugger on those
values is implementation-defined.


File: gcl.info,  Node: Interfaces to Restarts,  Next: Restart Tests,  Prev: Interactive Use of Restarts,  Up: Signaling and Handling Conditions

9.1.4.5 Interfaces to Restarts
..............................

Some restarts have functional interfaces, such as abort, continue,
muffle-warning, store-value, and use-value.  They are ordinary functions
that use find-restart and invoke-restart internally, that have the same
name as the restarts they manipulate, and that are provided simply for
notational convenience.

   Figure 9-6 shows defined names relating to restarts.

  abort             invoke-restart-interactively  store-value          
  compute-restarts  muffle-warning                use-value            
  continue          restart-bind                  with-simple-restart  
  find-restart      restart-case                                       
  invoke-restart    restart-name                                       

            Figure 9-6: Defined names relating to restarts.           



File: gcl.info,  Node: Restart Tests,  Next: Associating a Restart with a Condition,  Prev: Interfaces to Restarts,  Up: Signaling and Handling Conditions

9.1.4.6 Restart Tests
.....................

Each restart has an associated test, which is a function of one argument
(a condition or nil) which returns true if the restart should be visible
in the current situation.  This test is created by the :test-function
option to restart-bind or the :test option to restart-case.


File: gcl.info,  Node: Associating a Restart with a Condition,  Prev: Restart Tests,  Up: Signaling and Handling Conditions

9.1.4.7 Associating a Restart with a Condition
..............................................

A restart can be "associated with" a condition explicitly by
with-condition-restarts, or implicitly by restart-case.  Such an
assocation has dynamic extent.

   A single restart may be associated with several conditions at the
same time.  A single condition may have several associated restarts at
the same time.

   Active restarts associated with a particular condition can be
detected by calling a function such as find-restart, supplying that
condition as the condition argument.  Active restarts can also be
detected without regard to any associated condition by calling such a
function without a condition argument, or by supplying a value of nil
for such an argument.


File: gcl.info,  Node: Assertions,  Next: Notes about the Condition System`s Background,  Prev: Signaling and Handling Conditions,  Up: Condition System Concepts

9.1.5 Assertions
----------------

Conditional signaling of conditions based on such things as key match,
form evaluation, and type are handled by assertion operators.  Figure
9-7 shows operators relating to assertions.

  assert  check-type  ecase      
  ccase   ctypecase   etypecase  

  Figure 9-7: Operators relating to assertions.



File: gcl.info,  Node: Notes about the Condition System`s Background,  Prev: Assertions,  Up: Condition System Concepts

9.1.6 Notes about the Condition System's Background
---------------------------------------------------

For a background reference to the abstract concepts detailed in this
section, see Exceptional Situations in Lisp.  The details of that paper
are not binding on this document, but may be helpful in establishing a
conceptual basis for understanding this material.


File: gcl.info,  Node: Conditions Dictionary,  Prev: Condition System Concepts,  Up: Conditions

9.2 Conditions Dictionary
=========================

* Menu:

* condition::
* warning::
* style-warning::
* serious-condition::
* error (Condition Type)::
* cell-error::
* cell-error-name::
* parse-error::
* storage-condition::
* assert::
* error::
* cerror::
* check-type::
* simple-error::
* invalid-method-error::
* method-combination-error::
* signal::
* simple-condition::
* simple-condition-format-control::
* warn::
* simple-warning::
* invoke-debugger::
* break::
* *debugger-hook*::
* *break-on-signals*::
* handler-bind::
* handler-case::
* ignore-errors::
* define-condition::
* make-condition::
* restart::
* compute-restarts::
* find-restart::
* invoke-restart::
* invoke-restart-interactively::
* restart-bind::
* restart-case::
* restart-name::
* with-condition-restarts::
* with-simple-restart::
* abort (Restart)::
* continue::
* muffle-warning::
* store-value::
* use-value::
* abort (Function)::


File: gcl.info,  Node: condition,  Next: warning,  Prev: Conditions Dictionary,  Up: Conditions Dictionary

9.2.1 condition [Condition Type]
--------------------------------

[Reviewer Note by Barrett: I think CONDITION-RESTARTS is not fully
integrated.]

Class Precedence List::
.......................

condition, t

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

All types of conditions, whether error or non-error, must inherit from
this type.

   No additional subtype relationships among the specified subtypes of
type condition are allowed, except when explicitly mentioned in the
text; however implementations are permitted to introduce additional
types and one of these types can be a subtype of any number of the
subtypes of type condition.

   Whether a user-defined condition type has slots that are accessible
by with-slots is implementation-dependent.  Furthermore, even in an
implementation in which user-defined condition types would have slots,
it is implementation-dependent whether any condition types defined in
this document have such slots or, if they do, what their names might be;
only the reader functions documented by this specification may be relied
upon by portable code.

   Conforming code must observe the following restrictions related to
conditions:

*
     define-condition, not defclass, must be used to define new
     condition types.

*
     make-condition, not make-instance, must be used to create condition
     objects explicitly.

*
     The :report option of define-condition, not defmethod for
     print-object, must be used to define a condition reporter.

*
     slot-value, slot-boundp, slot-makunbound, and with-slots must not
     be used on condition objects.  Instead, the appropriate accessor
     functions (defined by define-condition) should be used.


File: gcl.info,  Node: warning,  Next: style-warning,  Prev: condition,  Up: Conditions Dictionary

9.2.2 warning [Condition Type]
------------------------------

Class Precedence List::
.......................

warning, condition, t

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

The type warning consists of all types of warnings.

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

style-warning


File: gcl.info,  Node: style-warning,  Next: serious-condition,  Prev: warning,  Up: Conditions Dictionary

9.2.3 style-warning [Condition Type]
------------------------------------

Class Precedence List::
.......................

style-warning, warning, condition, t

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

The type style-warning includes those conditions that represent
situations involving code that is conforming code but that is
nevertheless considered to be faulty or substandard.

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

*note muffle-warning::

Notes::
.......

An implementation might signal such a condition if it encounters code
that uses deprecated features or that appears unaesthetic or
inefficient.

   An 'unused variable' warning must be of type style-warning.

   In general, the question of whether code is faulty or substandard is
a subjective decision to be made by the facility processing that code.
The intent is that whenever such a facility wishes to complain about
code on such subjective grounds, it should use this condition type so
that any clients who wish to redirect or muffle superfluous warnings can
do so without risking that they will be redirecting or muffling other,
more serious warnings.


File: gcl.info,  Node: serious-condition,  Next: error (Condition Type),  Prev: style-warning,  Up: Conditions Dictionary

9.2.4 serious-condition [Condition Type]
----------------------------------------

Class Precedence List::
.......................

serious-condition, condition, t

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

All conditions serious enough to require interactive intervention if not
handled should inherit from the type serious-condition.  This condition
type is provided primarily so that it may be included as a superclass of
other condition types; it is not intended to be signaled directly.

Notes::
.......

Signaling a serious condition does not itself force entry into the
debugger.  However, except in the unusual situation where the programmer
can assure that no harm will come from failing to handle a serious
condition, such a condition is usually signaled with error rather than
signal in order to assure that the program does not continue without
handling the condition.  (And conversely, it is conventional to use
signal rather than error to signal conditions which are not serious
conditions, since normally the failure to handle a non-serious condition
is not reason enough for the debugger to be entered.)


File: gcl.info,  Node: error (Condition Type),  Next: cell-error,  Prev: serious-condition,  Up: Conditions Dictionary

9.2.5 error [Condition Type]
----------------------------

Class Precedence List::
.......................

error, serious-condition, condition, t

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

The type error consists of all conditions that represent errors.


File: gcl.info,  Node: cell-error,  Next: cell-error-name,  Prev: error (Condition Type),  Up: Conditions Dictionary

9.2.6 cell-error [Condition Type]
---------------------------------

Class Precedence List::
.......................

cell-error, error, serious-condition, condition, t

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

The type cell-error consists of error conditions that occur during a
location access.  The name of the offending cell is initialized by the
:name initialization argument to make-condition, and is accessed by the
function cell-error-name.

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

*note cell-error-name::


File: gcl.info,  Node: cell-error-name,  Next: parse-error,  Prev: cell-error,  Up: Conditions Dictionary

9.2.7 cell-error-name [Function]
--------------------------------

'cell-error-name' condition => name

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

condition--a condition of type cell-error.

   name--an object.

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

Returns the name of the offending cell involved in the situation
represented by condition.

   The nature of the result depends on the specific type of condition.
For example, if the condition is of type unbound-variable, the result is
the name of the unbound variable which was being accessed, if the
condition is of type undefined-function, this is the name of the
undefined function which was being accessed, and if the condition is of
type unbound-slot, this is the name of the slot which was being
accessed.

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

cell-error, unbound-slot, unbound-variable, undefined-function, *note
Condition System Concepts::


File: gcl.info,  Node: parse-error,  Next: storage-condition,  Prev: cell-error-name,  Up: Conditions Dictionary

9.2.8 parse-error [Condition Type]
----------------------------------

Class Precedence List::
.......................

parse-error, error, serious-condition, condition, t

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

The type parse-error consists of error conditions that are related to
parsing.

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

*note parse-namestring:: , *note reader-error::


File: gcl.info,  Node: storage-condition,  Next: assert,  Prev: parse-error,  Up: Conditions Dictionary

9.2.9 storage-condition [Condition Type]
----------------------------------------

Class Precedence List::
.......................

storage-condition, serious-condition, condition, t

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

The type storage-condition consists of serious conditions that relate to
problems with memory management that are potentially due to
implementation-dependent limits rather than semantic errors in
conforming programs, and that typically warrant entry to the debugger if
not handled.  Depending on the details of the implementation, these
might include such problems as stack overflow, memory region overflow,
and storage exhausted.

Notes::
.......

While some Common Lisp operations might signal storage-condition because
they are defined to create objects, it is unspecified whether operations
that are not defined to create objects create them anyway and so might
also signal storage-condition.  Likewise, the evaluator itself might
create objects and so might signal storage-condition.  (The natural
assumption might be that such object creation is naturally inefficient,
but even that is implementation-dependent.)  In general, the entire
question of how storage allocation is done is implementation-dependent,
and so any operation might signal storage-condition at any time.
Because such a condition is indicative of a limitation of the
implementation or of the image rather than an error in a program,
objects of type storage-condition are not of type error.


File: gcl.info,  Node: assert,  Next: error,  Prev: storage-condition,  Up: Conditions Dictionary

9.2.10 assert [Macro]
---------------------

'assert' test-form [({place}*) [datum-form {argument-form}*]]
=> nil

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

test-form--a form; always evaluated.

   place--a place; evaluated if an error is signaled.

   datum-form--a form that evaluates to a datum.  Evaluated each time an
error is to be signaled, or not at all if no error is to be signaled.

   argument-form--a form that evaluates to an argument.  Evaluated each
time an error is to be signaled, or not at all if no error is to be
signaled.

   datum, arguments--designators for a condition of default type error.
(These designators are the result of evaluating datum-form and each of
the argument-forms.)

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

assert assures that test-form evaluates to true.  If test-form evaluates
to false, assert signals a correctable error (denoted by datum and
arguments).  Continuing from this error using the continue restart makes
it possible for the user to alter the values of the places before assert
evaluates test-form again.  If the value of test-form is non-nil, assert
returns nil.

   The places are generalized references to data upon which test-form
depends, whose values can be changed by the user in attempting to
correct the error.  Subforms of each place are only evaluated if an
error is signaled, and might be re-evaluated if the error is re-signaled
(after continuing without actually fixing the problem).

   The order of evaluation of the places is not specified; see *note
Evaluation of Subforms to Places::.

   If a place form is supplied that produces more values than there are
store variables, the extra values are ignored.  If the supplied form
produces fewer values than there are store variables, the missing values
are set to nil.

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

      (setq x (make-array '(3 5) :initial-element 3))
     =>  #2A((3 3 3 3 3) (3 3 3 3 3) (3 3 3 3 3))
      (setq y (make-array '(3 5) :initial-element 7))
     =>  #2A((7 7 7 7 7) (7 7 7 7 7) (7 7 7 7 7))
      (defun matrix-multiply (a b)
        (let ((*print-array* nil))
          (assert (and (= (array-rank a) (array-rank b) 2)
                       (= (array-dimension a 1) (array-dimension b 0)))
                  (a b)
                  "Cannot multiply ~S by ~S." a b)
                 (really-matrix-multiply a b))) =>  MATRIX-MULTIPLY
      (matrix-multiply x y)
      |>  Correctable error in MATRIX-MULTIPLY:
      |>  Cannot multiply #<ARRAY ...> by #<ARRAY ...>.
      |>  Restart options:
      |>   1: You will be prompted for one or more new values.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
      |>  Value for A: |>>x<<|
      |>  Value for B: |>>(make-array '(5 3) :initial-element 6)<<|
     =>  #2A((54 54 54 54 54)
            (54 54 54 54 54)
            (54 54 54 54 54)
            (54 54 54 54 54)
            (54 54 54 54 54))

      (defun double-safely (x) (assert (numberp x) (x)) (+ x x))
      (double-safely 4)
     =>  8

      (double-safely t)
      |>  Correctable error in DOUBLE-SAFELY: The value of (NUMBERP X) must be non-NIL.
      |>  Restart options:
      |>   1: You will be prompted for one or more new values.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
      |>  Value for X: |>>7<<|
     =>  14

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

*break-on-signals*

   The set of active condition handlers.

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

*note check-type:: , *note error:: , *note Generalized Reference::

Notes::
.......

The debugger need not include the test-form in the error message, and
the places should not be included in the message, but they should be
made available for the user's perusal.  If the user gives the "continue"
command, the values of any of the references can be altered.  The
details of this depend on the implementation's style of user interface.


File: gcl.info,  Node: error,  Next: cerror,  Prev: assert,  Up: Conditions Dictionary

9.2.11 error [Function]
-----------------------

'error' datum &rest arguments => #<NoValue>

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

datum, arguments--designators for a condition of default type
simple-error.

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

error effectively invokes signal on the denoted condition.

   If the condition is not handled, (invoke-debugger condition) is done.
As a consequence of calling invoke-debugger, error cannot directly
return; the only exit from error can come by non-local transfer of
control in a handler or by use of an interactive debugging command.

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

      (defun factorial (x)
        (cond ((or (not (typep x 'integer)) (minusp x))
               (error "~S is not a valid argument to FACTORIAL." x))
              ((zerop x) 1)
              (t (* x (factorial (- x 1))))))
     =>  FACTORIAL
     (factorial 20)
     =>  2432902008176640000
     (factorial -1)
      |>  Error: -1 is not a valid argument to FACTORIAL.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Return to Lisp Toplevel.
      |>  Debug>

      (setq a 'fred)
     =>  FRED
      (if (numberp a) (1+ a) (error "~S is not a number." A))
      |>  Error: FRED is not a number.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Return to Lisp Toplevel.
      |>  Debug> |>>:Continue 1<<|
      |>  Return to Lisp Toplevel.

      (define-condition not-a-number (error)
                        ((argument :reader not-a-number-argument :initarg :argument))
        (:report (lambda (condition stream)
                   (format stream "~S is not a number."
                           (not-a-number-argument condition)))))
     =>  NOT-A-NUMBER

      (if (numberp a) (1+ a) (error 'not-a-number :argument a))
      |>  Error: FRED is not a number.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Return to Lisp Toplevel.
      |>  Debug> |>>:Continue 1<<|
      |>  Return to Lisp Toplevel.

Side Effects::
..............

Handlers for the specified condition, if any, are invoked and might have
side effects.  Program execution might stop, and the debugger might be
entered.

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

Existing handler bindings.

   *break-on-signals*

   Signals an error of type type-error if datum and arguments are not
designators for a condition.

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

*note cerror:: , *note signal:: , *note format:: , *note ignore-errors::
, *break-on-signals*, *note handler-bind:: , *note Condition System
Concepts::

Notes::
.......

Some implementations may provide debugger commands for interactively
returning from individual stack frames.  However, it should be possible
for the programmer to feel confident about writing code like:

      (defun wargames:no-win-scenario ()
        (if (error "pushing the button would be stupid."))
        (push-the-button))

   In this scenario, there should be no chance that error will return
and the button will get pushed.

   While the meaning of this program is clear and it might be proven
'safe' by a formal theorem prover, such a proof is no guarantee that the
program is safe to execute.  Compilers have been known to have bugs,
computers to have signal glitches, and human beings to manually
intervene in ways that are not always possible to predict.  Those kinds
of errors, while beyond the scope of the condition system to formally
model, are not beyond the scope of things that should seriously be
considered when writing code that could have the kinds of sweeping
effects hinted at by this example.


File: gcl.info,  Node: cerror,  Next: check-type,  Prev: error,  Up: Conditions Dictionary

9.2.12 cerror [Function]
------------------------

'cerror' continue-format-control datum &rest arguments => nil

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

Continue-format-control--a format control.

   [Reviewer Note by Barmar: What is continue-format-control used for??]

   datum, arguments--designators for a condition of default type
simple-error.

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

cerror effectively invokes error on the condition named by datum.  As
with any function that implicitly calls error, if the condition is not
handled, (invoke-debugger condition) is executed.  While signaling is
going on, and while in the debugger if it is reached, it is possible to
continue code execution (i.e., to return from cerror) using the continue
restart.

   If datum is a condition, arguments can be supplied, but are used only
in conjunction with the continue-format-control.

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

      (defun real-sqrt (n)
        (when (minusp n)
          (setq n (- n))
          (cerror "Return sqrt(~D) instead." "Tried to take sqrt(-~D)." n))
        (sqrt n))

      (real-sqrt 4)
     =>  2.0

      (real-sqrt -9)
      |>  Correctable error in REAL-SQRT: Tried to take sqrt(-9).
      |>  Restart options:
      |>   1: Return sqrt(9) instead.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
     =>  3.0

      (define-condition not-a-number (error)
        ((argument :reader not-a-number-argument :initarg :argument))
        (:report (lambda (condition stream)
                   (format stream "~S is not a number."
                           (not-a-number-argument condition)))))

      (defun assure-number (n)
        (loop (when (numberp n) (return n))
              (cerror "Enter a number."
                      'not-a-number :argument n)
              (format t "~&Type a number: ")
              (setq n (read))
              (fresh-line)))

      (assure-number 'a)
      |>  Correctable error in ASSURE-NUMBER: A is not a number.
      |>  Restart options:
      |>   1: Enter a number.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
      |>  Type a number: |>>1/2<<|
     =>  1/2

      (defun assure-large-number (n)
        (loop (when (and (numberp n) (> n 73)) (return n))
              (cerror "Enter a number~:[~; a bit larger than ~D~]."
                      "~*~A is not a large number."
                      (numberp n) n)
              (format t "~&Type a large number: ")
              (setq n (read))
              (fresh-line)))

      (assure-large-number 10000)
     =>  10000

      (assure-large-number 'a)
      |>  Correctable error in ASSURE-LARGE-NUMBER: A is not a large number.
      |>  Restart options:
      |>   1: Enter a number.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
      |>  Type a large number: |>>88<<|
     =>  88

      (assure-large-number 37)
      |>  Correctable error in ASSURE-LARGE-NUMBER: 37 is not a large number.
      |>  Restart options:
      |>   1: Enter a number a bit larger than 37.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
      |>  Type a large number: |>>259<<|
     =>  259

      (define-condition not-a-large-number (error)
        ((argument :reader not-a-large-number-argument :initarg :argument))
        (:report (lambda (condition stream)
                   (format stream "~S is not a large number."
                           (not-a-large-number-argument condition)))))

      (defun assure-large-number (n)
        (loop (when (and (numberp n) (> n 73)) (return n))
              (cerror "Enter a number~3*~:[~; a bit larger than ~*~D~]."
                      'not-a-large-number
                      :argument n
                      :ignore (numberp n)
                      :ignore n
                      :allow-other-keys t)
              (format t "~&Type a large number: ")
              (setq n (read))
              (fresh-line)))

      (assure-large-number 'a)
      |>  Correctable error in ASSURE-LARGE-NUMBER: A is not a large number.
      |>  Restart options:
      |>   1: Enter a number.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
      |>  Type a large number: |>>88<<|
     =>  88

      (assure-large-number 37)
      |>  Correctable error in ASSURE-LARGE-NUMBER: A is not a large number.
      |>  Restart options:
      |>   1: Enter a number a bit larger than 37.
      |>   2: Top level.
      |>  Debug> |>>:continue 1<<|
      |>  Type a large number: |>>259<<|
     =>  259

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

*break-on-signals*.

   Existing handler bindings.

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

*note error:: , *note format:: , *note handler-bind:: ,
*break-on-signals*, simple-type-error

Notes::
.......

If datum is a condition type rather than a string, the format directive
~* may be especially useful in the continue-format-control in order to
ignore the keywords in the initialization argument list.  For example:

     (cerror "enter a new value to replace ~*~s"
             'not-a-number
             :argument a)


File: gcl.info,  Node: check-type,  Next: simple-error,  Prev: cerror,  Up: Conditions Dictionary

9.2.13 check-type [Macro]
-------------------------

'check-type' place typespec [string] => nil

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

place--a place.

   typespec--a type specifier.

   string--a string; evaluated.

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

check-type signals a correctable error of type type-error if the
contents of place are not of the type typespec.

   check-type can return only if the store-value restart is invoked,
either explicitly from a handler or implicitly as one of the options
offered by the debugger.  If the store-value restart is invoked,
check-type stores the new value that is the argument to the restart
invocation (or that is prompted for interactively by the debugger) in
place and starts over, checking the type of the new value and signaling
another error if it is still not of the desired type.

   The first time place is evaluated, it is evaluated by normal
evaluation rules.  It is later evaluated as a place if the type check
fails and the store-value restart is used; see *note Evaluation of
Subforms to Places::.

   string should be an English description of the type, starting with an
indefinite article ("a" or "an").  If string is not supplied, it is
computed automatically from typespec.  The automatically generated
message mentions place, its contents, and the desired type.  An
implementation may choose to generate a somewhat differently worded
error message if it recognizes that place is of a particular form, such
as one of the arguments to the function that called check-type.  string
is allowed because some applications of check-type may require a more
specific description of what is wanted than can be generated
automatically from typespec.

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

      (setq aardvarks '(sam harry fred))
     =>  (SAM HARRY FRED)
      (check-type aardvarks (array * (3)))
      |>  Error: The value of AARDVARKS, (SAM HARRY FRED),
      |>         is not a 3-long array.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Specify a value to use instead.
      |>   2: Return to Lisp Toplevel.
      |>  Debug> |>>:CONTINUE 1<<|
      |>  Use Value: |>>#(SAM FRED HARRY)<<|
     =>  NIL
      aardvarks
     =>  #<ARRAY-T-3 13571>
      (map 'list #'identity aardvarks)
     =>  (SAM FRED HARRY)
      (setq aardvark-count 'foo)
     =>  FOO
      (check-type aardvark-count (integer 0 *) "A positive integer")
      |>  Error: The value of AARDVARK-COUNT, FOO, is not a positive integer.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Specify a value to use instead.
      |>   2: Top level.
      |>  Debug> |>>:CONTINUE 2<<|

      (defmacro define-adder (name amount)
        (check-type name (and symbol (not null)) "a name for an adder function")
        (check-type amount integer)
        `(defun ,name (x) (+ x ,amount)))

      (macroexpand '(define-adder add3 3))
     =>  (defun add3 (x) (+ x 3))

      (macroexpand '(define-adder 7 7))
      |>  Error: The value of NAME, 7, is not a name for an adder function.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Specify a value to use instead.
      |>   2: Top level.
      |>  Debug> |>>:Continue 1<<|
      |>  Specify a value to use instead.
      |>  Type a form to be evaluated and used instead: |>>'ADD7<<|
     =>  (defun add7 (x) (+ x 7))

      (macroexpand '(define-adder add5 something))
      |>  Error: The value of AMOUNT, SOMETHING, is not an integer.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Specify a value to use instead.
      |>   2: Top level.
      |>  Debug> |>>:Continue 1<<|
      |>  Type a form to be evaluated and used instead: |>>5<<|
     =>  (defun add5 (x) (+ x 5))


   Control is transferred to a handler.

Side Effects::
..............

The debugger might be entered.

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

*break-on-signals*

   The implementation.

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

*note Condition System Concepts::

Notes::
.......

      (check-type place typespec)
      == (assert (typep place 'typespec) (place)
                 'type-error :datum place :expected-type 'typespec)


File: gcl.info,  Node: simple-error,  Next: invalid-method-error,  Prev: check-type,  Up: Conditions Dictionary

9.2.14 simple-error [Condition Type]
------------------------------------

Class Precedence List::
.......................

simple-error, simple-condition, error, serious-condition, condition, t

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

The type simple-error consists of conditions that are signaled by error
or cerror when a

   format control

   is supplied as the function's first argument.


File: gcl.info,  Node: invalid-method-error,  Next: method-combination-error,  Prev: simple-error,  Up: Conditions Dictionary

9.2.15 invalid-method-error [Function]
--------------------------------------

'invalid-method-error' method format-control &rest args =>
implementation-dependent

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

method--a method.

   format-control--a format control.

   args--format arguments for the format-control.

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

The function invalid-method-error is used to signal an error of type
error when there is an applicable method whose qualifiers are not valid
for the method combination type.  The error message is constructed by
using the format-control suitable for format and any args to it.
Because an implementation may need to add additional contextual
information to the error message, invalid-method-error should be called
only within the dynamic extent of a method combination function.

   The function invalid-method-error is called automatically when a
method fails to satisfy every qualifier pattern and predicate in a
define-method-combination form.  A method combination function that
imposes additional restrictions should call invalid-method-error
explicitly if it encounters a method it cannot accept.

   Whether invalid-method-error returns to its caller or exits via throw
is implementation-dependent.

Side Effects::
..............

The debugger might be entered.

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

*break-on-signals*

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

*note define-method-combination::


File: gcl.info,  Node: method-combination-error,  Next: signal,  Prev: invalid-method-error,  Up: Conditions Dictionary

9.2.16 method-combination-error [Function]
------------------------------------------

'method-combination-error' format-control &rest args =>
implementation-dependent

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

format-control--a format control.

   args--format arguments for format-control.

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

The function method-combination-error is used to signal an error in
method combination.

   The error message is constructed by using a format-control suitable
for format and any args to it.  Because an implementation may need to
add additional contextual information to the error message,
method-combination-error should be called only within the dynamic extent
of a method combination function.

   Whether method-combination-error returns to its caller or exits via
throw is implementation-dependent.

Side Effects::
..............

The debugger might be entered.

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

*break-on-signals*

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

*note define-method-combination::


File: gcl.info,  Node: signal,  Next: simple-condition,  Prev: method-combination-error,  Up: Conditions Dictionary

9.2.17 signal [Function]
------------------------

'signal' datum &rest arguments => nil

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

datum, arguments--designators for a condition of default type
simple-condition.

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

Signals the condition denoted by the given datum and arguments.  If the
condition is not handled, signal returns nil.

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

      (defun handle-division-conditions (condition)
        (format t "Considering condition for division condition handling~
        (when (and (typep condition 'arithmetic-error)
                   (eq '/ (arithmetic-error-operation condition)))
          (invoke-debugger condition)))
     HANDLE-DIVISION-CONDITIONS
      (defun handle-other-arithmetic-errors (condition)
        (format t "Considering condition for arithmetic condition handling~
        (when (typep condition 'arithmetic-error)
          (abort)))
     HANDLE-OTHER-ARITHMETIC-ERRORS
      (define-condition a-condition-with-no-handler (condition) ())
     A-CONDITION-WITH-NO-HANDLER
      (signal 'a-condition-with-no-handler)
     NIL
      (handler-bind ((condition #'handle-division-conditions)
                       (condition #'handle-other-arithmetic-errors))
        (signal 'a-condition-with-no-handler))
     Considering condition for division condition handling
     Considering condition for arithmetic condition handling
     NIL
      (handler-bind ((arithmetic-error #'handle-division-conditions)
                       (arithmetic-error #'handle-other-arithmetic-errors))
        (signal 'arithmetic-error :operation '* :operands '(1.2 b)))
     Considering condition for division condition handling
     Considering condition for arithmetic condition handling
     Back to Lisp Toplevel

Side Effects::
..............

The debugger might be entered due to *break-on-signals*.

   Handlers for the condition being signaled might transfer control.

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

Existing handler bindings.

   *break-on-signals*

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

*break-on-signals*, *note error:: , simple-condition, *note Signaling
and Handling Conditions::

Notes::
.......

If (typep datum *break-on-signals*) yields true, the debugger is entered
prior to beginning the signaling process.  The continue restart can be
used to continue with the signaling process.  This is also true for all
other functions and macros that should, might, or must signal
conditions.


File: gcl.info,  Node: simple-condition,  Next: simple-condition-format-control,  Prev: signal,  Up: Conditions Dictionary

9.2.18 simple-condition [Condition Type]
----------------------------------------

Class Precedence List::
.......................

simple-condition, condition, t

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

The type simple-condition represents conditions that are signaled by
signal whenever a format-control is supplied as the function's first
argument.

   The format control and format arguments are initialized with the
initialization arguments named :format-control

   and :format-arguments to make-condition, and are accessed by the
functions

   simple-condition-format-control

   and simple-condition-format-arguments.  If format arguments are not
supplied to make-condition, nil is used as a default.

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

*note simple-condition-format-control:: ,

   simple-condition-format-arguments


File: gcl.info,  Node: simple-condition-format-control,  Next: warn,  Prev: simple-condition,  Up: Conditions Dictionary

9.2.19 simple-condition-format-control, simple-condition-format-arguments
-------------------------------------------------------------------------

                                                             [Function]

   'simple-condition-format-control' condition => format-control

   'simple-condition-format-arguments' condition => format-arguments

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

condition--a condition of type simple-condition.

   format-control--a format control.

   format-arguments--a list.

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

simple-condition-format-control returns the format control needed to
process the condition's format arguments.

   simple-condition-format-arguments returns a list of format arguments
needed to process the condition's format control.

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

      (setq foo (make-condition 'simple-condition
                               :format-control "Hi ~S"
                               :format-arguments '(ho)))
     =>  #<SIMPLE-CONDITION 26223553>
      (apply #'format nil (simple-condition-format-control foo)
                          (simple-condition-format-arguments foo))
     =>  "Hi HO"

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

*note simple-condition:: , *note Condition System Concepts::


File: gcl.info,  Node: warn,  Next: simple-warning,  Prev: simple-condition-format-control,  Up: Conditions Dictionary

9.2.20 warn [Function]
----------------------

'warn' datum &rest arguments => nil

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

datum, arguments--designators for a condition of default type
simple-warning.

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

Signals a condition of type warning.  If the condition is not handled,
reports the condition to error output.

   The precise mechanism for warning is as follows:

The warning condition is signaled
     While the warning condition is being signaled, the muffle-warning
     restart is established for use by a handler.  If invoked, this
     restart bypasses further action by warn, which in turn causes warn
     to immediately return nil.

If no handler for the warning condition is found
     If no handlers for the warning condition are found, or if all such
     handlers decline, then the condition is reported to error output by
     warn in an implementation-dependent format.

nil is returned
     The value returned by warn if it returns is nil.

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

       (defun foo (x)
         (let ((result (* x 2)))
           (if (not (typep result 'fixnum))
               (warn "You're using very big numbers."))
           result))
     =>  FOO

       (foo 3)
     =>  6

       (foo most-positive-fixnum)
      |>  Warning: You're using very big numbers.
     =>  4294967294

       (setq *break-on-signals* t)
     =>  T

       (foo most-positive-fixnum)
      |>  Break: Caveat emptor.
      |>  To continue, type :CONTINUE followed by an option number.
      |>   1: Return from Break.
      |>   2: Abort to Lisp Toplevel.
      |>  Debug> :continue 1
      |>  Warning: You're using very big numbers.
     =>  4294967294

Side Effects::
..............

A warning is issued.  The debugger might be entered.

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

Existing handler bindings.

   *break-on-signals*, *error-output*.

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

If datum is a condition and if the condition is not of type warning, or
arguments is non-nil, an error of type type-error is signaled.

   If datum is a condition type, the result of (apply #'make-condition
datum arguments) must be of type warning or an error of type type-error
is signaled.

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

*break-on-signals*, *note muffle-warning:: , *note signal::


File: gcl.info,  Node: simple-warning,  Next: invoke-debugger,  Prev: warn,  Up: Conditions Dictionary

9.2.21 simple-warning [Condition Type]
--------------------------------------

Class Precedence List::
.......................

simple-warning, simple-condition, warning, condition, t

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

The type simple-warning represents conditions that are signaled by warn
whenever a

   format control

   is supplied as the function's first argument.


File: gcl.info,  Node: invoke-debugger,  Next: break,  Prev: simple-warning,  Up: Conditions Dictionary

9.2.22 invoke-debugger [Function]
---------------------------------

'invoke-debugger' condition => #<NoValue>

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

condition--a condition object.

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

invoke-debugger attempts to enter the debugger with condition.

   If *debugger-hook* is not nil, it should be a function (or the name
of a function) to be called prior to entry to the standard debugger.
The function is called with *debugger-hook* bound to nil, and the
function must accept two arguments: the condition and the value of
*debugger-hook* prior to binding it to nil.  If the function returns
normally, the standard debugger is entered.

   The standard debugger never directly returns.  Return can occur only
by a non-local transfer of control, such as the use of a restart
function.

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

      (ignore-errors ;Normally, this would suppress debugger entry
        (handler-bind ((error #'invoke-debugger)) ;But this forces debugger entry
          (error "Foo.")))
     Debug: Foo.
     To continue, type :CONTINUE followed by an option number:
      1: Return to Lisp Toplevel.
     Debug>

Side Effects::
..............

*debugger-hook* is bound to nil, program execution is discontinued, and
the debugger is entered.

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

*debug-io* and *debugger-hook*.

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

*note error:: , *note break::


File: gcl.info,  Node: break,  Next: *debugger-hook*,  Prev: invoke-debugger,  Up: Conditions Dictionary

9.2.23 break [Function]
-----------------------

'break' &optional format-control &rest format-arguments => nil

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

format-control--a format control.

   The default is implementation-dependent.

   format-arguments--format arguments for the format-control.

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

break formats format-control and format-arguments and then goes directly
into the debugger without allowing any possibility of interception by
programmed error-handling facilities.

   If the continue restart is used while in the debugger, break
immediately returns nil without taking any unusual recovery action.

   break binds *debugger-hook* to nil before attempting to enter the
debugger.

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

      (break "You got here with arguments: ~:S." '(FOO 37 A))
      |>  BREAK: You got here with these arguments: FOO, 37, A.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Return from BREAK.
      |>   2: Top level.
      |>  Debug> :CONTINUE 1
      |>  Return from BREAK.
     =>  NIL


Side Effects::
..............

The debugger is entered.

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

*debug-io*.

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

*note error:: , *note invoke-debugger:: .

Notes::
.......

break is used as a way of inserting temporary debugging "breakpoints" in
a program, not as a way of signaling errors.  For this reason, break
does not take the continue-format-control argument that cerror takes.
This and the lack of any possibility of interception by condition
handling are the only program-visible differences between break and
cerror.

   The user interface aspects of break and cerror are permitted to vary
more widely, in order to accomodate the interface needs of the
implementation.  For example, it is permissible for a Lisp
read-eval-print loop to be entered by break rather than the conventional
debugger.

   break could be defined by:

      (defun break (&optional (format-control "Break") &rest format-arguments)
        (with-simple-restart (continue "Return from BREAK.")
          (let ((*debugger-hook* nil))
            (invoke-debugger
                (make-condition 'simple-condition
                                :format-control format-control
                                :format-arguments format-arguments))))
        nil)


File: gcl.info,  Node: *debugger-hook*,  Next: *break-on-signals*,  Prev: break,  Up: Conditions Dictionary

9.2.24 *debugger-hook* [Variable]
---------------------------------

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

a designator for a function of two arguments (a condition and the value
of *debugger-hook* at the time the debugger was entered), or nil.

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

nil.

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

When the value of *debugger-hook* is non-nil, it is called prior to
normal entry into the debugger, either due to a call to invoke-debugger
or due to automatic entry into the debugger from a call to error or
cerror with a condition that is not handled.  The function may either
handle the condition (transfer control) or return normally (allowing the
standard debugger to run).  To minimize recursive errors while
debugging, *debugger-hook* is bound to nil by invoke-debugger prior to
calling the function.

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

      (defun one-of (choices &optional (prompt "Choice"))
        (let ((n (length choices)) (i))
          (do ((c choices (cdr c)) (i 1 (+ i 1)))
              ((null c))
            (format t "~&[~D] ~A~
          (do () ((typep i `(integer 1 ,n)))
            (format t "~&~A: " prompt)
            (setq i (read))
            (fresh-line))
          (nth (- i 1) choices)))

      (defun my-debugger (condition me-or-my-encapsulation)
        (format t "~&Fooey: ~A" condition)
        (let ((restart (one-of (compute-restarts))))
          (if (not restart) (error "My debugger got an error."))
          (let ((*debugger-hook* me-or-my-encapsulation))
            (invoke-restart-interactively restart))))

      (let ((*debugger-hook* #'my-debugger))
        (+ 3 'a))
      |>  Fooey: The argument to +, A, is not a number.
      |>   [1] Supply a replacement for A.
      |>   [2] Return to Cloe Toplevel.
      |>  Choice: 1
      |>   Form to evaluate and use: (+ 5 'b)
      |>   Fooey: The argument to +, B, is not a number.
      |>   [1] Supply a replacement for B.
      |>   [2] Supply a replacement for A.
      |>   [3] Return to Cloe Toplevel.
      |>  Choice: 1
      |>   Form to evaluate and use: 1
     =>  9

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

invoke-debugger

Notes::
.......

When evaluating code typed in by the user interactively, it is sometimes
useful to have the hook function bind *debugger-hook* to the function
that was its second argument so that recursive errors can be handled
using the same interactive facility.


File: gcl.info,  Node: *break-on-signals*,  Next: handler-bind,  Prev: *debugger-hook*,  Up: Conditions Dictionary

9.2.25 *break-on-signals* [Variable]
------------------------------------

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

a type specifier.

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

nil.

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

When (typep condition *break-on-signals*) returns true, calls to signal,
and to other operators such as error that implicitly call signal, enter
the debugger prior to signaling the condition.

   The continue restart can be used to continue with the normal
signaling process when a break occurs process due to *break-on-signals*.

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

      *break-on-signals* =>  NIL
      (ignore-errors (error 'simple-error :format-control "Fooey!"))
     =>  NIL, #<SIMPLE-ERROR 32207172>

      (let ((*break-on-signals* 'error))
        (ignore-errors (error 'simple-error :format-control "Fooey!")))
      |>  Break: Fooey!
      |>  BREAK entered because of *BREAK-ON-SIGNALS*.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Continue to signal.
      |>   2: Top level.
      |>  Debug> |>>:CONTINUE 1<<|
      |>  Continue to signal.
     =>  NIL, #<SIMPLE-ERROR 32212257>

      (let ((*break-on-signals* 'error))
        (error 'simple-error :format-control "Fooey!"))
      |>  Break: Fooey!
      |>  BREAK entered because of *BREAK-ON-SIGNALS*.
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Continue to signal.
      |>   2: Top level.
      |>  Debug> |>>:CONTINUE 1<<|
      |>  Continue to signal.
      |>  Error: Fooey!
      |>  To continue, type :CONTINUE followed by an option number:
      |>   1: Top level.
      |>  Debug> |>>:CONTINUE 1<<|
      |>  Top level.

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

*note break:: , *note signal:: , *note warn:: , *note error:: , *note
typep:: , *note Condition System Concepts::

Notes::
.......

*break-on-signals* is intended primarily for use in debugging code that
does signaling.  When setting *break-on-signals*, the user is encouraged
to choose the most restrictive specification that suffices.  Setting
*break-on-signals* effectively violates the modular handling of
condition signaling.  In practice, the complete effect of setting
*break-on-signals* might be unpredictable in some cases since the user
might not be aware of the variety or number of calls to signal that are
used in code called only incidentally.

   *break-on-signals* enables an early entry to the debugger but such an
entry does not preclude an additional entry to the debugger in the case
of operations such as error and cerror.


File: gcl.info,  Node: handler-bind,  Next: handler-case,  Prev: *break-on-signals*,  Up: Conditions Dictionary

9.2.26 handler-bind [Macro]
---------------------------

'handler-bind' ({!binding}*) {form}* => {result}*

   binding ::=(type handler)

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

type--a type specifier.

   handler--a form; evaluated to produce a handler-function.

   handler-function--a designator for a function of one argument.

   forms--an implicit progn.

   results--the values returned by the forms.

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

Executes forms in a dynamic environment where the indicated handler
bindings are in effect.

   Each handler should evaluate to a handler-function, which is used to
handle conditions of the given type during execution of the forms.  This
function should take a single argument, the condition being signaled.

   If more than one handler binding is supplied, the handler bindings
are searched sequentially from top to bottom in search of a match (by
visual analogy with typecase).  If an appropriate type is found, the
associated handler is run in a dynamic environment where none of these
handler bindings are visible (to avoid recursive errors).  If the
handler declines, the search continues for another handler.

   If no appropriate handler is found, other handlers are sought from
dynamically enclosing contours.  If no handler is found outside, then
signal returns or error enters the debugger.

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

In the following code, if an unbound variable error is signaled in the
body (and not handled by an intervening handler), the first function is
called.

      (handler-bind ((unbound-variable #'(lambda ...))
                     (error #'(lambda ...)))
        ...)

   If any other kind of error is signaled, the second function is
called.  In either case, neither handler is active while executing the
code in the associated function.

      (defun trap-error-handler (condition)
        (format *error-output* "~&~A~&" condition)
        (throw 'trap-errors nil))

      (defmacro trap-errors (&rest forms)
        `(catch 'trap-errors
           (handler-bind ((error #'trap-error-handler))
             ,@forms)))

      (list (trap-errors (signal "Foo.") 1)
            (trap-errors (error  "Bar.") 2)
            (+ 1 2))
      |>  Bar.
     =>  (1 NIL 3)

   Note that "Foo."  is not printed because the condition made by signal
is a simple condition, which is not of type error, so it doesn't trigger
the handler for error set up by trap-errors.

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

*note handler-case::


File: gcl.info,  Node: handler-case,  Next: ignore-errors,  Prev: handler-bind,  Up: Conditions Dictionary

9.2.27 handler-case [Macro]
---------------------------

'handler-case' expression [[{!error-clause}* | !no-error-clause]] =>
{result}*

   clause ::=!error-clause | !no-error-clause

   error-clause ::=(typespec ([var]) {declaration}* {form}*)

   no-error-clause ::=(:no-error lambda-list {declaration}* {form}*)

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

expression--a form.

   typespec--a type specifier.

   var--a variable name.

   lambda-list--an ordinary lambda list.

   declaration--a declare expression; not evaluated.

   form--a form.

   results--In the normal situation, the values returned are those that
result from the evaluation of expression; in the exceptional situation
when control is transferred to a clause, the value of the last form in
that clause is returned.

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

handler-case executes expression in a dynamic environment where various
handlers are active.  Each error-clause specifies how to handle a
condition matching the indicated typespec.  A no-error-clause allows the
specification of a particular action if control returns normally.

   If a condition is signaled for which there is an appropriate
error-clause during the execution of expression (i.e., one for which
(typep condition 'typespec) returns true) and if there is no intervening
handler for a condition of that type, then control is transferred to the
body of the relevant error-clause.  In this case, the dynamic state is
unwound appropriately (so that the handlers established around the
expression are no longer active), and var is bound to the condition that
had been signaled.  If more than one case is provided, those cases are
made accessible in parallel.  That is, in

       (handler-case form
         (typespec1 (var1) form1)
         (typespec2 (var2) form2))

   if the first clause (containing form1) has been selected, the handler
for the second is no longer visible (or vice versa).

   The clauses are searched sequentially from top to bottom.  If there
is type overlap between typespecs, the earlier of the clauses is
selected.

   If var is not needed, it can be omitted.  That is, a clause such as:

       (typespec (var) (declare (ignore var)) form)

   can be written (typespec () form).

   If there are no forms in a selected clause, the case, and therefore
handler-case, returns nil.  If execution of expression returns normally
and no no-error-clause exists, the values returned by expression are
returned by handler-case.  If execution of expression returns normally
and a no-error-clause does exist, the values returned are used as
arguments to the function described by constructing (lambda lambda-list
{form}*) from the no-error-clause, and the values of that function call
are returned by handler-case.  The handlers which were established
around the expression are no longer active at the time of this call.

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

      (defun assess-condition (condition)
        (handler-case (signal condition)
          (warning () "Lots of smoke, but no fire.")
          ((or arithmetic-error control-error cell-error stream-error)
             (condition)
            (format nil "~S looks especially bad." condition))
          (serious-condition (condition)
            (format nil "~S looks serious." condition))
          (condition () "Hardly worth mentioning.")))
     =>  ASSESS-CONDITION
      (assess-condition (make-condition 'stream-error :stream *terminal-io*))
     =>  "#<STREAM-ERROR 12352256> looks especially bad."
      (define-condition random-condition (condition) ()
        (:report (lambda (condition stream)
                   (declare (ignore condition))
                   (princ "Yow" stream))))
     =>  RANDOM-CONDITION
      (assess-condition (make-condition 'random-condition))
     =>  "Hardly worth mentioning."

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

*note handler-bind:: , *note ignore-errors:: , *note Condition System
Concepts::

Notes::
.......

      (handler-case form
        (type1 (var1) . body1)
        (type2 (var2) . body2) ...)

   is approximately equivalent to:

      (block #1=#:g0001
        (let ((#2=#:g0002 nil))
          (tagbody
            (handler-bind ((type1 #'(lambda (temp)
                                            (setq #1# temp)
                                            (go #3=#:g0003)))
                           (type2 #'(lambda (temp)
                                            (setq #2# temp)
                                            (go #4=#:g0004))) ...)
            (return-from #1# form))
              #3# (return-from #1# (let ((var1 #2#)) . body1))
              #4# (return-from #1# (let ((var2 #2#)) . body2)) ...)))

      (handler-case form
        (type1 (var1) . body1)
        ...
        (:no-error (varN-1 varN-2 ...) . bodyN))

   is approximately equivalent to:


      (block #1=#:error-return
       (multiple-value-call #'(lambda (varN-1 varN-2 ...) . bodyN)
          (block #2=#:normal-return
            (return-from #1#
              (handler-case (return-from #2# form)
                (type1 (var1) . body1) ...)))))

