dpans/concept-slots.tex

% -*- Mode: TeX -*-

\beginsubSection{Introduction to Slots}
                    
An \term{object} \ofmetaclass{standard-class} has zero or more named
\term{slots}.  The \term{slots} of an \term{object} are determined 
by the \term{class} of the \term{object}.  Each \term{slot} can hold
one value.
\reviewer{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 \term{name} of a \term{slot} is a \term{symbol} that is syntactically
valid for use as a variable name.

When a \term{slot} does not have a value, the \term{slot} is said to be 
\term{unbound}.  When an unbound \term{slot} is read,
\reviewer{Barmar: from an object whose metaclass is standard-class?}
the \term{generic function} \funref{slot-unbound} is invoked. The 
system-supplied primary \term{method} 
for \funref{slot-unbound} 
%Barmar: on STANDARD-CLASS or T?
%KMP: It said T in the signature info for SLOT-UNBOUND so I copied that to here.
on \term{class} \typeref{t} signals an error.
\issue{SLOT-MISSING-VALUES:SPECIFY}
If \funref{slot-unbound} returns, its \term{primary value} 
is used that time as the \term{value} of the \term{slot}.
\endissue{SLOT-MISSING-VALUES:SPECIFY}

The default initial value form for a \term{slot} is defined by
the \kwd{initform} slot option.  When the \kwd{initform} form is used to
supply a value, it is evaluated in the lexical environment in which
the \macref{defclass} form was evaluated. The \kwd{initform} along with
the lexical environment in which the \macref{defclass} form was evaluated
is called a \term{captured initialization form}. 
For more details, \seesection\ObjectCreationAndInit.
             
A \term{local slot} is defined to be a \term{slot} that is
%Barmar says: ``Poor wording.  It's "visible" to anyone calling SLOT-VALUE.''
%    Perhaps we mean to be saying "accessible in"? -kmp 11-Oct-90
%%Ok. I'll substitute accessible. -kmp 6-Jan-91
%visible
\term{accessible}
to exactly one \term{instance}, 
namely the one in which the \term{slot} is allocated.  
A \term{shared slot} is defined to be a \term{slot} that is visible to more than one
\term{instance} of a given \term{class} and its \term{subclasses}.

A \term{class} is said to define a \term{slot} with a given \term{name} when
the \macref{defclass} form for that \term{class} contains a \term{slot specifier} with
that \term{name}.  Defining a \term{local slot} does not immediately create 
a \term{slot}; it causes a \term{slot} to be created each time 
an \term{instance} of the \term{class} is created.
Defining a \term{shared slot} immediately creates a \term{slot}.
                                                    
The \kwd{allocation} slot option to \macref{defclass} controls the kind
of \term{slot} that is defined.  If the value of the \kwd{allocation} slot
option is \kwd{instance}, a \term{local slot} is created.  If the value of
\kwd{allocation} is \kwd{class}, a \term{shared slot} is created.

A \term{slot} is said to be \term{accessible} in an \term{instance} 
of a \term{class} if
the \term{slot} is defined by the \term{class} 
of the \term{instance} or is inherited from
a \term{superclass} of that \term{class}.  
At most one \term{slot} of a given \term{name} can be
\term{accessible} in an \term{instance}.  
A \term{shared slot} defined by a \term{class} is
\term{accessible} in all \term{instances} 
of that \term{class}.  
A detailed explanation of the inheritance of \term{slots} is given in 
\secref\SlotInheritance.

\endsubSection%{Slots}
\beginsubSection{Accessing Slots}

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

\Thefunction{slot-value} can be used with any of the \term{slot}
names specified in the \macref{defclass} form to \term{access} a specific
\term{slot} \term{accessible} in an \term{instance} of the given \term{class}.

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

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

A \term{generic function} created or modified by supplying \kwd{reader},
\kwd{writer}, or \kwd{accessor} \term{slot} options can be treated exactly
as an ordinary \term{generic function}.
           
Note that \funref{slot-value} can be used to read or write the value of a
\term{slot} whether or not reader or writer \term{methods} exist for that
\term{slot}.  When \funref{slot-value} is used, no reader or writer
\term{methods} are invoked.

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

The macro \macref{with-accessors} can be used to establish a lexical
environment in which specified \term{slots} are lexically available through
their accessors as if they were variables.  The macro \macref{with-accessors}
invokes the appropriate accessors to \term{access} the specified \term{slots}. 
%Symbolics thinks this sentence is not meaningful:
%Any accessors specified by \macref{with-accessors} must
%already have been defined before they are used.

\endsubSection%{Accessing Slots}
\beginsubsection{Inheritance of Slots and Slot Options}
\DefineSection{SlotInheritance}

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

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

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

\beginlist

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

\itemitem{\bull} The allocation of a \term{slot} is controlled by the most 
specific \term{slot specifier}.  If the most specific \term{slot specifier} 
does not contain an \kwd{allocation} slot option, \kwd{instance} is used.
Less specific \term{slot specifiers} do not affect the allocation.

\itemitem{\bull} The default initial value form for a \term{slot} 
is the value of the \kwd{initform} slot option in the most specific
\term{slot specifier} that contains one.  If no \term{slot specifier}
contains an \kwd{initform} slot option, the \term{slot} 
has no default initial value form.

\itemitem{\bull} The contents of a \term{slot} will always be of type 
\f{(and $T\sub 1$ $\ldots$ $T\sub n$)} where $T\sub 1 \ldots T\sub n$ are
the values of the \kwd{type} slot options contained in all of the
\term{slot specifiers}.  If no \term{slot specifier} contains the
\kwd{type} slot option, the contents of the \term{slot} will always be 
\oftype{t}. The consequences of attempting to store in a \term{slot}
a value that does not satisfy the \term{type} of the \term{slot} are undefined.

\itemitem{\bull} The set of initialization arguments that initialize a 
given \term{slot} is the union of the initialization arguments declared in
the \kwd{initarg} slot options in all the \term{slot specifiers}.

\itemitem{\bull} The \term{documentation string} for a \term{slot} is the value of
the \kwd{documentation} slot option in the most specific \term{slot}
specifier that contains one.  If no \term{slot specifier} contains a
\kwd{documentation} slot option, the \term{slot} has no \term{documentation string}.

\endlist

A consequence of the allocation rule is that a \term{shared slot} can be
\term{shadowed}.  For example, if a class $C\sub 1$ defines 
a \term{slot} named $S$
whose value for the \kwd{allocation} slot option is \kwd{class},
that \term{slot} is \term{accessible} 
in \term{instances} of $C\sub 1$ and all of its
\term{subclasses}.  However, if $C\sub 2$ is a \term{subclass} 
of $C\sub 1$ and also
defines a \term{slot} named $S$\negthinspace, $C\sub 1$'s 
\term{slot} is not shared
by \term{instances} of $C\sub 2$ and its \term{subclasses}. When a class
$C\sub 1$ defines a \term{shared slot}, any subclass $C\sub 2$ of $C\sub
1$ will share this single \term{slot} 
unless the \macref{defclass} form for
$C\sub 2$ specifies a \term{slot} of the same 
\term{name} or there is a \term{superclass}
of $C\sub 2$ that precedes $C\sub 1$ in the \term{class precedence list} of
$C\sub 2$ that defines a \term{slot} of the same name.

A consequence of the type rule is that the value of a \term{slot}
satisfies the type constraint of each \term{slot specifier} that
contributes to that \term{slot}.  Because the result of attempting to
store in a \term{slot} a value that does not satisfy the type
constraint for the \term{slot} is undefined, the value in a \term{slot}
might fail to satisfy its type constraint.
     
The \kwd{reader}, \kwd{writer}, and \kwd{accessor} slot options
create \term{methods} rather than define the characteristics of a \term{slot}.
Reader and writer \term{methods} are inherited in the sense described in
\secref\MethodInheritance.

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

\endsubsection%{Inheritance of Slots and Slot Options}