87-002 errata

[David A. Moon <Moon@STONY-BROOK.SCRC.Symbolics.COM>]

Here is the errata sheet for the 87-002 document, revised on the
basis of all the discussion over the mail.  Dick and Linda have
graciously offered to format this and print up copies to
distribute at the X3J13 meeting.  I imagine there is still a day
or so to remove or correct anything that is not generally agreed
upon (I tried to do so already); the exact amount of time depends
on their schedule.


1-4 seventh paragraph: The distinguished class T is mentioned but its
characteristics are not described in the document, except by
implication.  Add the sentence:
  T has no superclasses and is a superclass of every class except itself.

1-5 at the end of the ``Defining Classes'' section, add "A class
definition cannot contain two slot specifiers with the same name."

1-5 first paragraph under ``Slots'': Replace the first sentence with
"An object has zero or more named slots.  An object's set of slots
is determined by the object's class.  Each slot can hold one value."

1-6 first paragraph: Change ":instance" to ":instance or :dynamic".

1-6 second and third paragraphs: Replace them with the following:
  We say that a class {\it defines\/} a slot with a given name
  when the {\bf 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
  creates a slot.
  
  We say that a slot is {\it 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 detailed explanation of the inheritance of slots is
  given in the section ``Inheritance of Slots and Slot Options.''

1-6 last paragraph: At the end of the second sentence:  change "lexically
available" to "lexically available as if they were variables".

1-7: Replace the section ``Inheritance of Slots and Slot Options'' with
the new section supplied below.

1-10: Replace the last sentence with "There is also a method
for {\bf setf} of {\tt C2-S3} that writes the value of {\tt S3}."

1-11 second paragraph: The vague word "access" is used without definition.
Add the sentence: "In this context, an instance is said to be
accessed when a generic function is called with the instance as an
argument that is used for method selection, or when {\bf slot-value}
is called with the instance as its first argument."

1-11 third paragraph: Remove the sentence "The function {\bf change-class}
is called when the number of instance variables changes or when the name of
any instance variable changes" since there is no such concept as "instance
variable" in this standard.  Replace it with the sentence:
"When a class is redefined in such a way that the set of local slots
accessible to an instance of the class is changed, or the order of slots
in storage is changed, updating an instance of the class calls the function
{\bf change-class}."

1-11 fourth paragraph: Delete the entire paragraph, it isn't true.  Replace
it with this paragraph:
  Because the class C-sub-O does not have a name, writing a method for
  class-changed that is specialized to a particular C-sub-O
  must be done through the functional interface, using add-method rather
  than using defmethod.  See the section ``Introduction to Methods.''

1-11 fifth paragraph third sentence: Change "Each slot of the new version"
to "Each local slot of the new version".  Last sentence: Delete "For
local slots," since we are only talking about local slots anyway.

1-11 last paragraph: Change "the value of that slot will be the same
in both instances" to "the value of that slot is unchanged".  Since only
one instance is involved, we can't say "both instances."

1-11 last paragraph:  Break the paragraph after the third sentence so local
slots and shared slots are discussed in separate paragraphs.  Clarify that
the paragraph discussing shared slots refers to what happens at the time
the class is redefined, and shared slots are not affected by updating an
instance nor by the values of local slots.

1-12 last paragraph: Change "Whether {\bf defclass} is allowed to change
the metaclass" to "Whether {\bf defclass} is allowed to change the
metaclass, and whether redefining a class updates existing instances,".

1-13 First paragraph: Delete the last sentence.  Add a new paragraph at
the end of the page: "Every class that has a name has a corresponding
type with the same name as the class.  In addition, every class object
is a valid type specifier.  Thus (typep <object> <class>) is true if the
class of the given <object> is <class> itself or a subclass of <class>
and (subtypep <class1> <class2>) returns t t if <class1> is a subclass of
<class2> or they are the same class, and returns nil t otherwise."

1-18 first paragraph under "Introduction to setf Generic Functions":
Change "(setf (generic-function-name arguments) new-value)"
to "(setf (symbol arguments) new-value)" because the base
function does not have to be generic, in fact it does not even have to
be defined.

1-18 last paragraph: The term "parameter specifier" is used in a way that
is inconsistent with its use by CLtL and there are a couple of typographical
problems.  Replace the entire paragraph with:
  Each method has a {\bit specialized lambda-list}, which determines
  when that method can be selected.  A specialized lambda-list is like
  an ordinary lambda-list except that a {\bit specialized parameter} may occur
  instead of the name of a parameter.  A specialized parameter is a list,
  {\tt ({\it variable-name parameter-specializer-name\/})}, where {\it
  parameter-specializer-name} is a parameter specializer name.  Every
  parameter specializer name is a Common Lisp type specifier, but the only
  Common Lisp type specifiers that are valid as parameter specializer names
  are the following:

1-19: Delete the first line "In short..." since the two bulleted items are
now introduced by the preceding paragraph.

1-19 fourth paragraph, beginning "Only required parameters can be specialized": 
The term "parameter specifier" is misused again.  Replace the paragraph with:
  Only required parameters can 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 is
  simply a variable name, its parameter specializer defaults to the class
  named {\bf t}.

1-19 fifth paragraph: Change "when the class of each required argument"
to "when each required argument".

1-19 seventh paragraph: Change to "This proposal requires that both
parameter specializers and parameter specializer names be Common Lisp
type specifiers."

1-19 tenth paragraph: Change "parameter specializers are t" to
"parameter specializers are the class named t".  Change "always part of
the generic function" to "always applicable".

1-19 last paragraph fourth sentence: Change "cons" to "list".

1-22 second paragraph: Change "the specializers must be quoted objects
(otherwise" to "the specializers must be equal (otherwise".

1-23 first line: Change "defmacro" to "defmethod".

1-25 sixth paragraph: Change "All {\bf :around} methods run before any
primary methods run." to "All {\bf :around} methods run before any
non-{\bf :around} methods run."

1-26 first paragraph: Change "Flavors" to "CommonObjects".

2-5 Values paragraph: Replace the whole sentence with
"The value is {\it generic-function}." to clarify that the value
is EQ to the argument.

2-8 Purpose paragraph:  Add the sentences "The generic function
{\bf change-class} is invoked automatically by the system after
{\bf defclass} has been used to redefine an existing class.
It can also be explicitly invoked by the user."

2-8 Values paragraph: Replace the whole sentence with
"The value is {\it instance}." to clarify that the value
is EQ to the argument.

2-11 Purpose paragraph:  Delete the sentences "The generic function
{\bf change-class} is invoked automatically by the system after
{\bf defclass} has been used to redefine an existing class.
It can also be explicitly invoked by the user."  Add the sentence
"The function {\bf class-changed} is called only by
the function {\bf change-class}."

2-11 second Arguments paragraph: Delete the second sentence.  It lost
its intended meaning as a result of previous editing.

2-11 first Remarks paragraph: Delete this.  It contradicts an
example on page 2-8 and it isn't true.

2-11 second Remarks paragraph: Some occurrences of change-class should be
class-changed and there are a couple of terminological problems ("copy",
"part").  Replace the paragraph with:
  The arguments to {\bf class-changed} are computed by {\bf change-class}.
  The first argument is an instance of the original class
  created to hold the old slot values temporarily.
  This argument has dynamic extent within {\bf class-changed},
  and therefore it is an error to reference it in any way
  once {\bf class-changed} returns.

2-15 third paragraph: Add "A class object can be used directly as a
type-specifier.  Thus (typep <object> <class>) is true if the class of the
given <object> is <class> itself or a subclass of <class>."

2-15 last line:  Delete this.  Defclass has no effect on the value cells
of symbols.

2-17 second paragraph: Delete ", from their superclasses, and so on".

2-17 :allocation bullet: Change "in the class instance" to "in each
instance".

2-18 first bullet (:type).  There is no discussion of the meaning and
enforcement of :type.  Add the following (stolen from CLtL p.310):
  This specifies that the contents of the slot will always be of the
  specified data type.  This is entirely analogous to the declaration of a
  variable or function; indeed, it effectively declares the result type of
  the reader generic function when applied to an object of this class.  An
  implementation may or may not choose to check the type of the new value
  when initializing or assigning to a slot.

2-18 :accessor-prefix, :reader-prefix bullets: Change "These ... functions
are interned" to "These ... function names are interned".

2-26 short-form-option syntax: Delete the :order clause.

2-27 fourth bullet: Delete it.

2-29 first paragraph: Replace the next to last sentence with:  "If {\bf
:description} is not specified, a default description is generated based on
the variable name and the qualifier patterns, and on whether this
method-group includes the unqualified methods."

2-33 third paragraph: Change "If no generic function is currently named by
the symbol {\it name\/}" to "If {\tt (fboundp {\it name\/})} is {\bf nil}"
to match the terminology used on page 2-21.

2-34 first paragraph: Change "primary (in this case, unqualified) methods"
to "unqualified methods".

2-34 second paragraph: Same problem with "parameter specifier" as on 1-18.
Replace the first two sentences of the paragraph with:
  The {\it specialized-lambda-list\/} argument is like an ordinary function
  lambda-list except that required parameter names can be replaced by
  specialized parameters.  A specialized parameter is a list of the form
  {\tt ({\it variable-name parameter-specializer-name\/})}.

2-35 syntax for specialized-setf-lambda-list: Change "specializer" to
"parameter-specializer-name".

2-38 fourth Arguments paragraph: Change "If the first argument is a symbol"
to "If the first argument is a symbol that names a class".

2-38 last Arguments paragraph: Change "If the first argument is a symbol"
to "If the first argument is a symbol that has a setf generic function
associated with it".

2-39 last Arguments paragraph: Change "second" to "errorp".

2-41 second Purpose paragraph: Replace it with "Whether
{\bf invalid-method-error} returns to its caller or exits
via {\bf throw} is implementation dependent."

2-46 second Purpose paragraph first sentence: It was not intended to
guarantee that the returned value is a list with certain objects in its
car and cdr.  Change "a form whose first element" to "a form whose
effect is the same as a form whose first element".

2-47 Values paragraph: same as the preceding.

2-48 second Purpose paragraph: Replace it with "Whether
{\bf method-combination-error} returns to its caller or exits
via {\bf throw} is implementation dependent."

2-53 Syntax paragraph: remove "&optional errorp".

2-53 last Arguments paragraph: Replace the entire paragraph with
"{\bf remove-method} does not signal an error if the method has
already been removed from the generic function."

2-53 Values paragraph: Replace the whole sentence with
"The value is {\it generic-function}." to clarify that the value
is EQ to the argument.

2-54: Add pages for SUBTYPEP, TYPE-OF, and TYPEP, explaining that
SUBTYPEP and TYPEP are to be extended to accept class objects as
type specifiers, and explaining that TYPE-OF never returns a
class object, with a cross-reference to CLASS-OF.  (Unresolved
issue: does TYPE-OF an instance of an anonymous class return the
class object, or does it return some symbol?)

2-55 last paragraph first sentence: Delete "or a superclass".

2-55 last paragraph fourth sentence: Change "not a subclass of the
specified class" to "not the specified class or a subclass of the
specified class".

2-55 last paragraph fifth sentence: Change "superclass of the instance" to
"superclass of the actual class of the instance" and change "different"
to "smaller".

2-56 second paragraph: Change "using the accessor function" to "calling the
accessor function", "is used to access" to "is called to access", and
"accesses the slots by using" to "accesses the slots by calling".

2-56 Values paragraph: Change "value" to "values" to clarify that the
body can return multiple values.

!
Revised ``Inheritance of Slots and Slot Options'' section:

[For readability all TEX formatting has been temporarily removed]

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.  At most one slot of a given name can be accessible in an
instance.

In the simplest case, only one class among C and its superclasses
defines a slot with a given slot name.  If the class that defines the
slot is not C, we say that the slot is inherited.  The characteristics
of the slot are determined by the slot specifier of the defining class.
If the :allocation slot option is omitted, :instance, or :dynamic, then
it specifies a local slot and each instance of C has its own slot that
stores its own value.  If the :allocation slot option is :class, then it
specifies a shared slot, the class that defined the slot stores the
value, and all instances of C access that single slot.

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
  the class precedence list of C of the classes that define them.

- 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 never affect the allocation.

- The initform of a slot is controlled by the most specific slot
  specifier that contains an :initform slot option.  If no slot specifier
  contains an :initform, the slot has no default initial value form.

- The type of a slot is (and T1 T2 T3...), where T1, T2, T3, and so on
  are the :type slot options contained in all of the slot specifiers.  If
  no slot specifier contains :type, the type is t.

The :reader and :accessor slot options were not mentioned because
they create methods, rather than defining characteristics of a slot.
Reader and accessor methods are inherited in the sense described in the
section ``Inheritance of Methods.''

A consequence of the allocation rule is that shared slots can be
shadowed.  If a class C-sub-1 defines a shared slot named S, normally
that single slot is accessible in instances of C-sub-1 and all of its
subclasses.  However, if C-sub-2 is a subclass of C-sub-1 and also
defines a slot named S, C-sub-1's slot is not shared by instances of
C-sub-2 and its subclasses.  See S2 in the section ``Examples of
Inheritance.''

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.
Note that an implementation may or may not choose to check the type of
the new value when initializing or assigning to a slot.

Methods that access slots know 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.