gcl.info-22

This is Info file gcl.info, produced by Makeinfo-1.55 from the input file
gcl.texi.

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

Copyright 1994 William F. Schelter


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

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

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; psetf:: ,
*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

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

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

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; (setf 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

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; (setf documentation):: , *Note
ensure-generic-function:: ,

generic-function,

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