[Guile-commits] GNU Guile branch, stable-2.0, updated. v2.0.0-9-gd9ff850

[Neil Jerram]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=d9ff8506b32495393a77b7a2d077172d12571a34

The branch, stable-2.0 has been updated
       via  d9ff8506b32495393a77b7a2d077172d12571a34 (commit)
       via  476a51eb3893d780a1935c0754c9e7854dda8d5a (commit)
       via  a46f77f95cfcc1b4e4de94d1bc135e4d48808725 (commit)
      from  8fa6525e82a0fc6f9afabd913e0f64ba158449d8 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit d9ff8506b32495393a77b7a2d077172d12571a34
Author: Neil Jerram <address@hidden>
Date:   Fri Feb 18 19:47:05 2011 +0000

    Doc of MOP for instance and class creation
    
    * doc/ref/goops.texi (Instance Creation Protocol): Rename from
      `Customizing Instance Creation', and move before the more
      complicated class definition stuff.  Couple of very minor edits.
    
      (Class Definition Protocol): Remove ensure-metaclass-with-supers
      (too internal) and repeated material.  Move class-redefinition
      stuff to (existing) later section on that.  Merge reference-like
      material from `Customizing Class Definition' to here.

commit 476a51eb3893d780a1935c0754c9e7854dda8d5a
Author: Neil Jerram <address@hidden>
Date:   Thu Feb 17 22:09:13 2011 +0000

    Summarize class definition protocol
    
    * doc/ref/goops.texi (Class Definition Protocol): Add tree summary
      diagram.

commit a46f77f95cfcc1b4e4de94d1bc135e4d48808725
Author: Neil Jerram <address@hidden>
Date:   Thu Feb 17 21:36:10 2011 +0000

    Work on GOOPS MOP documentation
    
    * doc/ref/goops.texi (The Metaobject Protocol): Simplify intro text.
      Minor edits and simplifications throughout this section.
      (Metaobjects and the Metaobject Protocol): Insert "default".
      (Metaclasses): Renamed from `Terminology', and deleted the material
      on CPL and accessors, which just duplicated what has already been
      covered earlier in the chapter.  Remove statements that confuse
      whether "metaclass of" means "class of class of" or "class of
      (something that is itself a class)".  (I think it's actually the
      latter.)
      (Class Definition Protocol): Renamed from `Class Definition
      Internals'.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/goops.texi |  619 +++++++++++++++++++++++-----------------------------
 1 files changed, 271 insertions(+), 348 deletions(-)

diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index 3bebd8f..890081a 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -1777,23 +1777,21 @@ So let's plunge in.  GOOPS is based on a ``metaobject 
protocol'' (aka
 System), tiny-clos (a small Scheme implementation of a subset of CLOS
 functionality) and STKlos.
 
-GOOPS can be used by application authors at a basic level without any
-need to understand what the MOP is and how it works.  On the other hand,
-the MOP underlies even very simple customizations --- such as defining
-an @code{initialize} method to customize the initialization of instances
-of an application-defined class --- and an understanding of the MOP
-makes it much easier to explain such customizations in a precise way.
-And in the long run, understanding the MOP is the key both to
-understanding GOOPS at a deeper level and to taking full advantage of
-GOOPS' power, by customizing the behaviour of GOOPS itself.
+The MOP underlies many possible GOOPS customizations --- such as
+defining an @code{initialize} method to customize the initialization of
+instances of an application-defined class --- and an understanding of
+the MOP makes it much easier to explain such customizations in a precise
+way.  And at a deeper level, understanding the MOP is a key part of
+understanding GOOPS, and of taking full advantage of GOOPS' power, by
+customizing the behaviour of GOOPS itself.
 
 @menu
 * Metaobjects and the Metaobject Protocol::
-* Terminology::
+* Metaclasses::
 * MOP Specification::
-* Class Definition Internals::
+* Instance Creation Protocol::
+* Class Definition Protocol::
 * Customizing Class Definition::
-* Customizing Instance Creation::
 * Class Redefinition::
 * Method Definition::
 * Method Definition Internals::
@@ -1828,7 +1826,7 @@ as regards accessibility and protection from garbage 
collection.
 Instances are of course objects in the usual sense, and there is no
 benefit from thinking of them as metaobjects.)
 
-The ``metaobject protocol'' (aka ``MOP'') is the specification of the
+The ``metaobject protocol'' (or ``MOP'') is the specification of the
 generic functions which determine the behaviour of these metaobjects and
 the circumstances in which these generic functions are invoked.
 
@@ -1854,7 +1852,7 @@ superclasses, slot definitions and class options that 
were specified in
 the @code{define-class} form.
 
 @item
address@hidden allocates memory for the new instance, and then invokes the
address@hidden allocates memory for the new instance, and invokes the
 @code{initialize} generic function to initialize the new instance's
 slots.
 
@@ -1865,8 +1863,8 @@ performs the slot calculation.
 @end itemize
 
 In other words, rather than being hardcoded in @code{define-class}, the
-behaviour of class definition is encapsulated by generic function
-methods that are specialized for the class @code{<class>}.
+default behaviour of class definition is encapsulated by generic
+function methods that are specialized for the class @code{<class>}.
 
 It is possible to create a new class that inherits from @code{<class>},
 which is called a ``metaclass'', and to write a new @code{initialize}
@@ -1897,19 +1895,8 @@ Each following section covers a particular area of GOOPS 
functionality,
 and describes the generic functions that are relevant for customization
 of that area.
 
address@hidden Terminology
address@hidden Terminology
-
-It is assumed that the reader is already familiar with standard object
-orientation concepts such as classes, objects/instances,
-inheritance/subclassing, generic functions and methods, encapsulation
-and polymorphism.
-
-This section explains some of the less well known concepts and
-terminology that GOOPS uses, which are assumed by the following sections
-of the reference manual.
-
address@hidden Metaclass
address@hidden Metaclasses
address@hidden Metaclasses
 
 A @dfn{metaclass} is the class of an object which represents a GOOPS
 class.  Put more succinctly, a metaclass is a class's class.
@@ -1925,30 +1912,29 @@ at what happens when a new class is created using 
@code{define-class}:
 (define-class <my-class> (<object>) . slots)
 @end example
 
-GOOPS actually expands the @code{define-class} form to something like
-this
address@hidden
+Guile expands this to something like:
 
 @example
 (define <my-class> (class (<object>) . slots))
 @end example
 
-and thence to
address@hidden
+which in turn expands to:
 
 @example
 (define <my-class>
   (make <class> #:supers (list <object>) #:slots slots))
 @end example
 
-In other words, the value of @code{<my-class>} is in fact an instance of
-the class @code{<class>} with slot values specifying the superclasses
-and slot definitions for the class @code{<my-class>}.  (@code{#:supers}
-and @code{#:slots} are initialization keywords for the @code{dsupers}
-and @code{dslots} slots of the @code{<class>} class.)
+As this expansion makes clear, the resulting value of @code{<my-class>}
+is an instance of the class @code{<class>} with slot values specifying
+the superclasses and slot definitions for the class @code{<my-class>}.
+(@code{#:supers} and @code{#:slots} are initialization keywords for the
address@hidden and @code{dslots} slots of the @code{<class>} class.)
 
-In order to take advantage of the full power of the GOOPS metaobject
-protocol (@pxref{MOP Specification}), it is sometimes desirable to
-create a new class with a metaclass other than the default
address@hidden<class>}.  This is done by writing:
+Now suppose that you want to define a new class with a metaclass other
+than the default @code{<class>}.  This is done by writing:
 
 @example
 (define-class <my-class2> (<object>)
@@ -1956,7 +1942,8 @@ create a new class with a metaclass other than the default
    #:metaclass <my-metaclass>)
 @end example
 
-GOOPS expands this to something like:
address@hidden
+and Guile expands @emph{this} to something like:
 
 @example
 (define <my-class2>
@@ -1993,91 +1980,12 @@ relationships between @code{my-object}, 
@code{<my-class2>},
 The class of @code{my-object} is @code{<my-class2>}.
 
 @item
-The metaclass of @code{my-object} is @code{<my-metaclass>}.
-
address@hidden
 The class of @code{<my-class2>} is @code{<my-metaclass>}.
 
 @item
-The metaclass of @code{<my-class2>} is @code{<class>}.
-
address@hidden
 The class of @code{<my-metaclass>} is @code{<class>}.
-
address@hidden
-The metaclass of @code{<my-metaclass>} is @code{<class>}.
-
address@hidden
address@hidden<my-class2>} is not a metaclass, since it is does not inherit from
address@hidden<class>}.
-
address@hidden
address@hidden<my-metaclass>} is a metaclass, since it inherits from
address@hidden<class>}.
 @end itemize
 
address@hidden Class Precedence List
-
-The @dfn{class precedence list} of a class is the list of all direct and
-indirect superclasses of that class, including the class itself.
-
-In the absence of multiple inheritance, the class precedence list is
-ordered straightforwardly, beginning with the class itself and ending
-with @code{<top>}.
-
-For example, given this inheritance hierarchy:
-
address@hidden
-(define-class <invertebrate> (<object>) @dots{})
-(define-class <echinoderm> (<invertebrate>) @dots{})
-(define-class <starfish> (<echinoderm>) @dots{})
address@hidden example
-
-the class precedence list of <starfish> would be
-
address@hidden
-(<starfish> <echinoderm> <invertebrate> <object> <top>)
address@hidden example
-
-With multiple inheritance, the algorithm is a little more complicated.
-A full description is provided by the GOOPS Tutorial: see @ref{Class
-Precedence List}.
-
-``Class precedence list'' is often abbreviated, in documentation and
-Scheme variable names, to @dfn{cpl}.
-
address@hidden Accessor
-
-An @dfn{accessor} is a generic function with both reference and setter
-methods.
-
address@hidden
-(define-accessor perimeter)
address@hidden example
-
-Reference methods for an accessor are defined in the same way as generic
-function methods.
-
address@hidden
-(define-method (perimeter (s <square>))
-  (* 4 (side-length s)))
address@hidden example
-
-Setter methods for an accessor are defined by specifying ``(setter
-<accessor-name>)'' as the first parameter of the @code{define-method}
-call.
-
address@hidden
-(define-method ((setter perimeter) (s <square>) (n <number>))
-  (set! (side-length s) (/ n 4)))
address@hidden example
-
-Once an appropriate setter method has been defined in this way, it can
-be invoked using the generalized @code{set!} syntax, as in:
-
address@hidden
-(set! (perimeter s1) 18.3)
address@hidden example
 
 @node MOP Specification
 @subsection MOP Specification
@@ -2087,22 +1995,17 @@ customizable generic function invocations that can be 
made by the standard
 GOOPS syntax, procedures and methods, and to explain the protocol for
 customizing such invocations.
 
-A generic function invocation is customizable if the types of the arguments
-to which it is applied are not all determined by the lexical context in
-which the invocation appears.  For example,
-
address@hidden @bullet
address@hidden
-the @code{(initialize @var{instance} @var{initargs})} invocation in the
-default @code{make-instance} method is customizable, because the type of the
address@hidden@var{instance}} argument is determined by the class that was 
passed to
address@hidden
+A generic function invocation is customizable if the types of the
+arguments to which it is applied are not completely determined by the
+lexical context in which the invocation appears.  For example, the
address@hidden(initialize @var{instance} @var{initargs})} invocation in the
+default @code{make-instance} method is customizable, because the type of
+the @address@hidden argument is determined by the class that was
+passed to @code{make-instance}.
 
address@hidden
-the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
-is not customizable, because all of its arguments have lexically determined
-types.
address@hidden itemize
+(Whereas --- to give a counter-example --- the @code{(make <generic>
+#:name ',name)} invocation in @code{define-generic} is not customizable,
+because all of its arguments have lexically determined types.)
 
 When using this rule to decide whether a given generic function invocation
 is customizable, we ignore arguments that are expected to be handled in
@@ -2123,140 +2026,174 @@ effects
 what the caller expects to get as the applied method's return value.
 @end itemize
 
address@hidden Class Definition Internals
address@hidden Class Definition Internals
 
address@hidden (syntax)
address@hidden Instance Creation Protocol
address@hidden Instance Creation Protocol
+
address@hidden <class> . @var{initargs}} (method)
 
 @itemize @bullet
 @item
address@hidden (syntax)
address@hidden @var{class} @var{initargs}} (generic)
+
+The applied @code{allocate-instance} method should allocate storage for
+a new instance of class @var{class} and return the uninitialized instance.
 
address@hidden @bullet
 @item
address@hidden (procedure)
address@hidden @var{instance} @var{initargs}} (generic)
+
address@hidden is the uninitialized instance returned by
address@hidden  The applied method should initialize the new
+instance in whatever sense is appropriate for its class.  The method's
+return value is ignored.
address@hidden itemize
+
address@hidden itself is a generic function.  Hence the @code{make}
+invocation itself can be customized in the case where the new instance's
+metaclass is more specialized than the default @code{<class>}, by
+defining a @code{make} method that is specialized to that metaclass.
+
+Normally, however, the method for classes with metaclass @code{<class>}
+will be applied.  This method calls two generic functions:
 
 @itemize @bullet
 @item
address@hidden @var{metaclass} @dots{}} (generic)
+(allocate-instance @var{class} . @var{initargs})
 
address@hidden is the metaclass of the class being defined, either
-taken from the @code{#:metaclass} class option or computed by
address@hidden  The applied method must create and return the
-fully initialized class metaobject for the new class definition.
address@hidden
+(initialize @var{instance} . @var{initargs})
 @end itemize
 
address@hidden itemize
address@hidden allocates storage for and returns the new
+instance, uninitialized.  You might customize @code{allocate-instance},
+for example, if you wanted to provide a GOOPS wrapper around some other
+object programming system.
+
+To do this, you would create a specialized metaclass, which would act as
+the metaclass for all classes and instances from the other system.  Then
+define an @code{allocate-instance} method, specialized to that
+metaclass, which calls a Guile primitive C function (or FFI code), which
+in turn allocates the new instance using the interface of the other
+object system.
+
+In this case, for a complete system, you would also need to customize a
+number of other generic functions like @code{make} and
address@hidden, so that GOOPS knows how to make classes from the
+other system, access instance slots, and so on.
+
address@hidden initializes the instance that is returned by
address@hidden  The standard GOOPS methods perform
+initializations appropriate to the instance class.
 
address@hidden @bullet
 @item
address@hidden @var{old-class} @var{new-class}} (generic)
+At the least specialized level, the method for instances of type
address@hidden<object>} performs internal GOOPS instance initialization, and
+initializes the instance's slots according to the slot definitions and
+any slot initialization keywords that appear in @var{initargs}.
 
address@hidden calls @code{class-redefinition} if the variable
-specified by its first argument already held a GOOPS class definition.
address@hidden and @var{new-class} are the old and new class metaobjects.
-The applied method should perform whatever is necessary to handle the
-redefinition, and should return the class metaobject that is to be bound
-to @code{define-class}'s variable.  The default class redefinition
-protocol is described in @ref{Class Redefinition}.
address@hidden
+The method for instances of type @code{<class>} calls
address@hidden(next-method)}, then performs the class initializations described
+in @ref{Class Definition Protocol}.
+
address@hidden
+and so on for generic functions, methods, operator classes @dots{}
 @end itemize
 
-The @code{(make @var{metaclass} @dots{})} invocation above will create
-an class metaobject with metaclass @var{metaclass}.  By default, this
-metaobject will be initialized by the @code{initialize} method that is
-specialized for instances of type @code{<class>}.
+Similarly, you can customize the initialization of instances of any
+application-defined class by defining an @code{initialize} method
+specialized to that class.
+
+Imagine a class whose instances' slots need to be initialized at
+instance creation time by querying a database.  Although it might be
+possible to achieve this a combination of @code{#:init-thunk} keywords
+and closures in the slot definitions, it may be neater to write an
address@hidden method for the class that queries the database once
+and initializes all the dependent slot values according to the results.
+
+
address@hidden Class Definition Protocol
address@hidden Class Definition Protocol
 
address@hidden <class> @var{initargs}} (method)
+Here is a summary diagram of the syntax, procedures and generic
+functions that may be involved in class definition.
+
address@hidden
address@hidden (syntax)
 
 @itemize @bullet
 @item
address@hidden @var{class}} (generic)
address@hidden (syntax)
 
-The applied method should compute and return the class precedence list
-for @var{class} as a list of class metaobjects.  When @code{compute-cpl}
-is called, the following @var{class} metaobject slots have all been
-initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
address@hidden (empty), @code{direct-methods}.  The value
-returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
address@hidden @bullet
address@hidden
address@hidden (procedure)
 
address@hidden @bullet
 @item
address@hidden @var{class}} (generic)
address@hidden (procedure)
 
-The applied method should compute and return the slots (union of direct
-and inherited) for @var{class} as a list of slot definitions.  When
address@hidden is called, all the @var{class} metaobject slots
-mentioned for @code{compute-cpl} have been initialized, plus the
-following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
-The value returned by @code{compute-slots} will be stored in the
address@hidden slot.
address@hidden
address@hidden @var{metaclass} @dots{}} (generic)
 
address@hidden @bullet
 @item
address@hidden @var{class} @var{slot-def}} (generic)
address@hidden (generic)
 
address@hidden calls @code{compute-get-n-set} for each slot computed
-by @code{compute-slots}.  The applied method should compute and return a
-pair of closures that, respectively, get and set the value of the specified
-slot.  The get closure should have arity 1 and expect a single argument
-that is the instance whose slot value is to be retrieved.  The set closure
-should have arity 2 and expect two arguments, where the first argument is
-the instance whose slot value is to be set and the second argument is the
-new value for that slot.  The closures should be returned in a two element
-list: @code{(list @var{get} @var{set})}.
address@hidden
address@hidden (generic)
 
-The closures returned by @code{compute-get-n-set} are stored as part of
-the value of the @var{class} metaobject's @code{getters-n-setters} slot.
-Specifically, the value of this slot is a list with the same number of
-elements as there are slots in the class, and each element looks either like
address@hidden @bullet
address@hidden
address@hidden (generic)
 
address@hidden
address@hidden(@var{slot-name-symbol} @var{init-function} . @var{index})}
address@hidden example
address@hidden @bullet
address@hidden
address@hidden (procedure)
address@hidden itemize
 
-or like
address@hidden
address@hidden (generic)
 
address@hidden
address@hidden(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
address@hidden example
address@hidden
address@hidden (generic)
 
-Where the get and set closures are replaced by @var{index}, the slot is
-an instance slot and @var{index} is the slot's index in the underlying
-structure: GOOPS knows how to get and set the value of such slots and so
-does not need specially constructed get and set closures.  Otherwise,
address@hidden and @var{set} are the closures returned by 
@code{compute-get-n-set}.
address@hidden
address@hidden (generic)
 
-The structure of the @code{getters-n-setters} slot value is important when
-understanding the next customizable generic functions that @code{initialize}
address@hidden
address@hidden
address@hidden (generic)
address@hidden itemize
address@hidden itemize
address@hidden itemize
address@hidden itemize
 
 @item
address@hidden @var{class} @var{gns}} (generic)
address@hidden (generic)
 
address@hidden calls @code{compute-getter-method} for each of the class's
-slots (as determined by @code{compute-slots}) that includes a
address@hidden:getter} or @code{#:accessor} slot option.  @var{gns} is the
-element of the @var{class} metaobject's @code{getters-n-setters} slot that
-specifies how the slot in question is referenced and set, as described
-above under @code{compute-get-n-set}.  The applied method should create
-and return a method that is specialized for instances of type @var{class}
-and uses the get closure to retrieve the slot's value.  [ *fixme  Need
-to insert something here about checking that the value is not unbound. ]
address@hidden uses @code{add-method!} to add the returned method to
-the generic function named by the slot definition's @code{#:getter} or
address@hidden:accessor} option.
address@hidden @bullet
address@hidden
address@hidden (generic)
 
 @item
address@hidden @var{class} @var{gns}} (generic)
address@hidden (generic)
 
address@hidden is invoked with the same arguments as
address@hidden, for each of the class's slots that includes
-a @code{#:setter} or @code{#:accessor} slot option.  The applied method
-should create and return a method that is specialized for instances of
-type @var{class} and uses the set closure to set the slot's value.
address@hidden then uses @code{add-method!} to add the returned method
-to the generic function named by the slot definition's @code{#:setter}
-or @code{#:accessor} option.
address@hidden
address@hidden (generic)
address@hidden itemize
 @end itemize
 
address@hidden expands to an expression which
+Wherever a step above is marked as ``generic'', it can be customized,
+and the detail shown below it is only ``correct'' insofar as it
+describes what the default method of that generic function does.  For
+example, if you write an @code{initialize} method, for some metaclass,
+that does not call @code{next-method} and does not call
address@hidden, then @code{compute-cpl} will not be called when a
+class is defined with that metaclass. 
+
+A @code{(define-class ...)} form (@pxref{Class Definition}) expands to
+an expression which
 
 @itemize @bullet
 @item
@@ -2266,8 +2203,7 @@ checks that it is being evaluated only at top level
 defines any accessors that are implied by the @var{slot-definition}s
 
 @item
-uses @code{class} to create the new class (@pxref{Class Definition
-Internals,, class})
+uses @code{class} to create the new class
 
 @item
 checks for a previous class definition for @var{name} and, if found,
@@ -2318,8 +2254,7 @@ class precedence list
 defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
 options, if they are not specified by @var{options}, to the current
 top-level environment, the unbound value, and @code{(ensure-metaclass
address@hidden)} respectively (@pxref{Class Definition Internals,,
-ensure-metaclass})
address@hidden)} respectively
 
 @item
 checks for duplicate classes in @var{supers} and duplicate slot names in
@@ -2355,55 +2290,114 @@ has to be created once.
 The @code{env} parameter is ignored.
 @end deffn
 
address@hidden procedure ensure-metaclass-with-supers meta-supers
address@hidden is an internal procedure used by
address@hidden (@pxref{Class Definition Internals,,
-ensure-metaclass}).  It returns a metaclass that is the union by
-inheritance of the metaclasses in @var{meta-supers}.
address@hidden generic make metaclass @dots{}
address@hidden is the metaclass of the class being defined, either
+taken from the @code{#:metaclass} class option or computed by
address@hidden  The applied method must create and return the
+fully initialized class metaobject for the new class definition.
 @end deffn
 
-The internals of @code{make}, which is ultimately used to create the new
-class object, are described in @ref{Customizing Instance Creation},
-which covers the creation and initialization of instances in general.
+The @code{(make @var{metaclass} @dots{})} invocation is a particular
+case of the instance creation protocol covered in the previous section.
+It will create an class metaobject with metaclass @var{metaclass}.  By
+default, this metaobject will be initialized by the @code{initialize}
+method that is specialized for instances of type @code{<class>}.
 
address@hidden Customizing Class Definition
address@hidden Customizing Class Definition
-
-During the initialization of a new class, GOOPS calls a number of generic
-functions with the newly allocated class instance as the first
-argument.  Specifically, GOOPS calls the generic function
+The @code{initialize} method for classes (signature @code{(initialize
+<class> initargs)}) calls the following generic functions.
 
 @itemize @bullet
 @item
-(initialize @var{class} @dots{})
address@hidden itemize
address@hidden @var{class}} (generic)
 
-where @var{class} is the newly allocated class instance, and the default
address@hidden method for arguments of type @code{<class>} calls the
-generic functions
+The applied method should compute and return the class precedence list
+for @var{class} as a list of class metaobjects.  When @code{compute-cpl}
+is called, the following @var{class} metaobject slots have all been
+initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
address@hidden (empty), @code{direct-methods}.  The value
+returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
 
address@hidden @bullet
 @item
-(compute-cpl @var{class})
address@hidden @var{class}} (generic)
 
address@hidden
-(compute-slots @var{class})
+The applied method should compute and return the slots (union of direct
+and inherited) for @var{class} as a list of slot definitions.  When
address@hidden is called, all the @var{class} metaobject slots
+mentioned for @code{compute-cpl} have been initialized, plus the
+following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
+The value returned by @code{compute-slots} will be stored in the
address@hidden slot.
 
 @item
-(compute-get-n-set @var{class} @var{slot-def}), for each of the slot
-definitions returned by @code{compute-slots}
address@hidden @var{class} @var{slot-def}} (generic)
+
address@hidden calls @code{compute-get-n-set} for each slot computed
+by @code{compute-slots}.  The applied method should compute and return a
+pair of closures that, respectively, get and set the value of the specified
+slot.  The get closure should have arity 1 and expect a single argument
+that is the instance whose slot value is to be retrieved.  The set closure
+should have arity 2 and expect two arguments, where the first argument is
+the instance whose slot value is to be set and the second argument is the
+new value for that slot.  The closures should be returned in a two element
+list: @code{(list @var{get} @var{set})}.
+
+The closures returned by @code{compute-get-n-set} are stored as part of
+the value of the @var{class} metaobject's @code{getters-n-setters} slot.
+Specifically, the value of this slot is a list with the same number of
+elements as there are slots in the class, and each element looks either like
+
address@hidden
address@hidden(@var{slot-name-symbol} @var{init-function} . @var{index})}
address@hidden example
+
+or like
+
address@hidden
address@hidden(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
address@hidden example
+
+Where the get and set closures are replaced by @var{index}, the slot is
+an instance slot and @var{index} is the slot's index in the underlying
+structure: GOOPS knows how to get and set the value of such slots and so
+does not need specially constructed get and set closures.  Otherwise,
address@hidden and @var{set} are the closures returned by 
@code{compute-get-n-set}.
+
+The structure of the @code{getters-n-setters} slot value is important when
+understanding the next customizable generic functions that @code{initialize}
address@hidden
 
 @item
-(compute-getter-method @var{class} @var{slot-def}), for each of the
-slot definitions returned by @code{compute-slots} that includes a
address@hidden:getter} or @code{#:accessor} slot option
address@hidden @var{class} @var{gns}} (generic)
+
address@hidden calls @code{compute-getter-method} for each of the class's
+slots (as determined by @code{compute-slots}) that includes a
address@hidden:getter} or @code{#:accessor} slot option.  @var{gns} is the
+element of the @var{class} metaobject's @code{getters-n-setters} slot that
+specifies how the slot in question is referenced and set, as described
+above under @code{compute-get-n-set}.  The applied method should create
+and return a method that is specialized for instances of type @var{class}
+and uses the get closure to retrieve the slot's value.  [ *fixme  Need
+to insert something here about checking that the value is not unbound. ]
address@hidden uses @code{add-method!} to add the returned method to
+the generic function named by the slot definition's @code{#:getter} or
address@hidden:accessor} option.
 
 @item
-(compute-setter-method @var{class} @var{slot-def}), for each of the
-slot definitions returned by @code{compute-slots} that includes a
address@hidden:setter} or @code{#:accessor} slot option.
address@hidden @var{class} @var{gns}} (generic)
+
address@hidden is invoked with the same arguments as
address@hidden, for each of the class's slots that includes
+a @code{#:setter} or @code{#:accessor} slot option.  The applied method
+should create and return a method that is specialized for instances of
+type @var{class} and uses the set closure to set the slot's value.
address@hidden then uses @code{add-method!} to add the returned method
+to the generic function named by the slot definition's @code{#:setter}
+or @code{#:accessor} option.
 @end itemize
 
address@hidden Customizing Class Definition
address@hidden Customizing Class Definition
+
 If the metaclass of the new class is something more specialized than the
 default @code{<class>}, then the type of @var{class} in the calls above
 is more specialized than @code{<class>}, and hence it becomes possible
@@ -2421,8 +2415,7 @@ customized in order to modify the CPL ordering algorithm 
for all classes
 with a special metaclass.
 
 The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
-procedure, which is in turn called by the default @code{compute-cpl}
-method.
+procedure, which is called by the default @code{compute-cpl} method.
 
 @deffn procedure compute-std-cpl class
 Compute and return the class precedence list for @var{class} according
@@ -2491,7 +2484,7 @@ allocation to do this.
 @end example
 
 The usage of @code{compute-getter-method} and @code{compute-setter-method}
-is described in @ref{MOP Specification}.
+is described in @ref{Class Definition Protocol}.
 
 @code{compute-cpl} and @code{compute-get-n-set} are called by the
 standard @code{initialize} method for classes whose metaclass is
@@ -2502,94 +2495,24 @@ behaviour, by not calling @code{(next-method)} at all, 
but more
 typically it would perform additional class initialization steps before
 and/or after calling @code{(next-method)} for the standard behaviour.
 
address@hidden Customizing Instance Creation
address@hidden Customizing Instance Creation
-
address@hidden <class> . @var{initargs}} (method)
-
address@hidden @bullet
address@hidden
address@hidden @var{class} @var{initargs}} (generic)
-
-The applied @code{allocate-instance} method should allocate storage for
-a new instance of class @var{class} and return the uninitialized instance.
-
address@hidden
address@hidden @var{instance} @var{initargs}} (generic)
 
address@hidden is the uninitialized instance returned by
address@hidden  The applied method should initialize the new
-instance in whatever sense is appropriate for its class.  The method's
-return value is ignored.
address@hidden itemize
-
address@hidden itself is a generic function.  Hence the @code{make}
-invocation itself can be customized in the case where the new instance's
-metaclass is more specialized than the default @code{<class>}, by
-defining a @code{make} method that is specialized to that metaclass.
-
-Normally, however, the method for classes with metaclass @code{<class>}
-will be applied.  This method calls two generic functions:
-
address@hidden @bullet
address@hidden
-(allocate-instance @var{class} . @var{initargs})
-
address@hidden
-(initialize @var{instance} . @var{initargs})
address@hidden itemize
-
address@hidden allocates storage for and returns the new
-instance, uninitialized.  You might customize @code{allocate-instance},
-for example, if you wanted to provide a GOOPS wrapper around some other
-object programming system.
-
-To do this, you would create a specialized metaclass, which would act as
-the metaclass for all classes and instances from the other system.  Then
-define an @code{allocate-instance} method, specialized to that
-metaclass, which calls a Guile primitive C function, which in turn
-allocates the new instance using the interface of the other object
-system.
-
-In this case, for a complete system, you would also need to customize a
-number of other generic functions like @code{make} and
address@hidden, so that GOOPS knows how to make classes from the
-other system, access instance slots, and so on.
-
address@hidden initializes the instance that is returned by
address@hidden  The standard GOOPS methods perform
-initializations appropriate to the instance class.
address@hidden Class Redefinition
address@hidden Class Redefinition
 
 @itemize @bullet
address@hidden
-At the least specialized level, the method for instances of type
address@hidden<object>} performs internal GOOPS instance initialization, and
-initializes the instance's slots according to the slot definitions and
-any slot initialization keywords that appear in @var{initargs}.
 
 @item
-The method for instances of type @code{<class>} calls
address@hidden(next-method)}, then performs the class initializations described
-in @ref{Customizing Class Definition}.
address@hidden @var{old-class} @var{new-class}} (generic)
 
address@hidden
-and so on for generic functions, method, operator classes @dots{}
address@hidden calls @code{class-redefinition} if the variable
+specified by its first argument already held a GOOPS class definition.
address@hidden and @var{new-class} are the old and new class metaobjects.
+The applied method should perform whatever is necessary to handle the
+redefinition, and should return the class metaobject that is to be bound
+to @code{define-class}'s variable.  The default class redefinition
+protocol is described in @ref{Class Redefinition}.
 @end itemize
 
-Similarly, you can customize the initialization of instances of any
-application-defined class by defining an @code{initialize} method
-specialized to that class.
-
-Imagine a class whose instances' slots need to be initialized at
-instance creation time by querying a database.  Although it might be
-possible to achieve this a combination of @code{#:init-thunk} keywords
-and closures in the slot definitions, it is neater to write an
address@hidden method for the class that queries the database once
-and initializes all the dependent slot values according to the results.
-
address@hidden Class Redefinition
address@hidden Class Redefinition
-
 The default @code{class-redefinition} method, specialized for classes
 with the default metaclass @code{<class>}, has the following internal
 protocol.
@@ -2886,11 +2809,11 @@ accessor, passing the setter generic function as the 
value of the
 The @code{#:metaclass} class option specifies the metaclass of the class
 being defined.  @var{metaclass} must be a class that inherits from
 @code{<class>}.  For the use of metaclasses, see @ref{Metaobjects and
-the Metaobject Protocol} and @ref{Terminology}.
+the Metaobject Protocol} and @ref{Metaclasses}.
 
 If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
 metaclass for the new class by calling @code{ensure-metaclass}
-(@pxref{Class Definition Internals,, ensure-metaclass}).
+(@pxref{Class Definition Protocol,, ensure-metaclass}).
 @end deffn
 
 @deffn {class option} #:name name


hooks/post-receive
-- 
GNU Guile