[Guile-commits] GNU Guile branch, master, updated. release_1-9-12-89-g630f46f

[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=630f46f192be9274a5ec05304ad25efd22ff9520

The branch, master has been updated
       via  630f46f192be9274a5ec05304ad25efd22ff9520 (commit)
       via  5aaf0709e635ace2f2db4048fbf8fd2756724cc3 (commit)
       via  a9bf12c2e59d73a9e7508655c28ffe37a0cc8283 (commit)
       via  c34d74fffd33ad7d09b373cba1ff00d6660c5786 (commit)
      from  23295dc35c76e0855e4ec188c0fe2ca579a0be20 (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 630f46f192be9274a5ec05304ad25efd22ff9520
Author: Neil Jerram <address@hidden>
Date:   Sat Sep 25 17:29:18 2010 +0100

    Remove unwarranted para
    
    * doc/ref/goops.texi (Metaobjects and the Metaobject Protocol): Remove
      para about GOOPS classes belonging to the usual Scheme namespace.
      Interest doesn't justify the space that it takes.

commit 5aaf0709e635ace2f2db4048fbf8fd2756724cc3
Author: Neil Jerram <address@hidden>
Date:   Sat Sep 25 17:27:14 2010 +0100

    Edit text about the MOP
    
    * doc/ref/goops.texi (The Metaobject Protocol, Metaobjects and the
      Metaobject Protocol): Minor edits.

commit a9bf12c2e59d73a9e7508655c28ffe37a0cc8283
Author: Neil Jerram <address@hidden>
Date:   Sat Sep 25 15:42:08 2010 +0100

    Start separating doc of the metaobject protocol from that of basic GOOPS 
usage
    
    * doc/ref/goops.texi (Introductory Remarks): Node deleted, with
      material moved to...
      (The Metaobject Protocol): ...here.
      (MOP Specification): Moved to become a subnode of `The Metaobject
      Protocol'.

commit c34d74fffd33ad7d09b373cba1ff00d6660c5786
Author: Neil Jerram <address@hidden>
Date:   Sat Sep 25 15:19:30 2010 +0100

    Promote subsections inside the GOOPS "Reference Manual" section
    
    * doc/ref/goops.texi (Reference Manual): Node deleted, with content
      promoted up to...
    
    * doc/ref/goops.texi (GOOPS): ...here.

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

Summary of changes:
 doc/ref/goops.texi |  774 ++++++++++++++++++++++++----------------------------
 1 files changed, 359 insertions(+), 415 deletions(-)

diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index 7b824c8..fbf4f75 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -32,8 +32,17 @@ overriding or redefining those methods.
 * Copyright Notice::
 * Quick Start::
 * Tutorial::
-* Reference Manual::
-* MOP Specification::
+* Defining New Classes::
+* Creating Instances::
+* Accessing Slots::
+* Creating Generic Functions::
+* Adding Methods to Generic Functions::
+* Invoking Generic Functions::
+* Redefining a Class::
+* Changing the Class of an Instance::
+* Introspection::
+* Miscellaneous Functions::
+* The Metaobject Protocol::
 @end menu
 
 @node Copyright Notice
@@ -182,369 +191,8 @@ objects, to add two of them together:
 @section Tutorial
 @include goops-tutorial.texi
 
address@hidden Reference Manual
address@hidden Reference Manual
-
-This chapter is the GOOPS reference manual.  It aims to describe all the
-syntax, procedures, options and associated concepts that a typical
-application author would need to understand in order to use GOOPS
-effectively in their application.  It also describes what is meant by
-the GOOPS ``metaobject protocol'' (aka ``MOP''), and indicates how
-authors can use the metaobject protocol to customize the behaviour of
-GOOPS itself.
-
-For a detailed specification of the GOOPS metaobject protocol, see
address@hidden Specification}.
-
address@hidden
-* Introductory Remarks::
-* Defining New Classes::
-* Creating Instances::
-* Accessing Slots::
-* Creating Generic Functions::
-* Adding Methods to Generic Functions::
-* Invoking Generic Functions::
-* Redefining a Class::
-* Changing the Class of an Instance::
-* Introspection::
-* Miscellaneous Functions::
address@hidden menu
-
address@hidden Introductory Remarks
address@hidden Introductory Remarks
-
-GOOPS is an object-oriented programming system based on a ``metaobject
-protocol'' derived from the ones used in CLOS (the Common Lisp Object
-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 metaobject protocol (aka ``MOP'') is and how
-it works.  On the other hand, the MOP underlies even the customizations
-that application authors are likely to make use of very quickly --- 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.
-
-Each of the following sections of the reference manual is arranged
-such that the most basic usage is introduced first, and then subsequent
-subsubsections discuss the related internal functions and metaobject
-protocols, finishing with a description of how to customize that area of
-functionality.
-
-These introductory remarks continue with a few words about metaobjects
-and the MOP.  Readers who do not want to be bothered yet with the MOP
-and customization could safely skip this subsubsection on a first reading,
-and should correspondingly skip subsequent subsubsections that are
-concerned with internals and customization.
-
-In general, this reference manual assumes familiarity with standard
-object oriented concepts and terminology.  However, some of the terms
-used in GOOPS are less well known, so the Terminology subsubsection
-provides definitions for these terms.
-
address@hidden
-* Metaobjects and the Metaobject Protocol::
-* Terminology::
address@hidden menu
-
address@hidden Metaobjects and the Metaobject Protocol
address@hidden Metaobjects and the Metaobject Protocol
-
-The conceptual building blocks of GOOPS are classes, slot definitions,
-instances, generic functions and methods.  A class is a grouping of
-inheritance relations and slot definitions.  An instance is an object
-with slots that are allocated following the rules implied by its class's
-superclasses and slot definitions.  A generic function is a collection
-of methods and rules for determining which of those methods to apply
-when the generic function is invoked.  A method is a procedure and a set
-of specializers that specify the type of arguments to which the
-procedure is applicable.
-
-Of these entities, GOOPS represents classes, generic functions and
-methods as ``metaobjects''.  In other words, the values in a GOOPS
-program that describe classes, generic functions and methods, are
-themselves instances (or ``objects'') of special GOOPS classes that
-encapsulate the behaviour, respectively, of classes, generic functions,
-and methods.
-
-(The other two entities are slot definitions and instances.  Slot
-definitions are not strictly instances, but every slot definition is
-associated with a GOOPS class that specifies the behaviour of the slot
-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
-generic functions which determine the behaviour of these metaobjects and
-the circumstances in which these generic functions are invoked.
-
-For a concrete example of what this means, consider how GOOPS calculates
-the set of slots for a class that is being defined using
address@hidden  The desired set of slots is the union of the new
-class's direct slots and the slots of all its superclasses.  But
address@hidden itself does not perform this calculation.  Instead,
-there is a method of the @code{initialize} generic function that is
-specialized for instances of type @code{<class>}, and it is this method
-that performs the slot calculation.
-
address@hidden is a generic function which GOOPS calls whenever a new
-instance is created, immediately after allocating memory for a new
-instance, in order to initialize the new instance's slots.  The sequence
-of steps is as follows.
-
address@hidden @bullet
address@hidden
address@hidden uses @code{make} to make a new instance of the
address@hidden<class>}, passing as initialization arguments the superclasses,
-slot definitions and class options that were specified in the
address@hidden form.
-
address@hidden
address@hidden allocates memory for the new instance, and then invokes the
address@hidden generic function to initialize the new instance's
-slots.
-
address@hidden
-The @code{initialize} generic function applies the method that is
-specialized for instances of type @code{<class>}, and this method
-performs the slot calculation.
address@hidden 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>}.
-
-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}
-method that is specialized for instances of the new metaclass.  Then, if
-the @code{define-class} form includes a @code{#:metaclass} class option
-whose value is the new metaclass, the class that is defined by the
address@hidden form will be an instance of the new metaclass rather
-than of the default @code{<class>}, and will be defined in accordance
-with the new @code{initialize} method.  Thus the default slot
-calculation, as well as any other aspect of the new class's relationship
-with its superclasses, can be modified or overridden.
-
-In a similar way, the behaviour of generic functions can be modified or
-overridden by creating a new class that inherits from the standard
-generic function class @code{<generic>}, writing appropriate methods
-that are specialized to the new class, and creating new generic
-functions that are instances of the new class.
-
-The same is true for method metaobjects.  And the same basic mechanism
-allows the application class author to write an @code{initialize} method
-that is specialized to their application class, to initialize instances
-of that class.
-
-Such is the power of the MOP.  Note that @code{initialize} is just one
-of a large number of generic functions that can be customized to modify
-the behaviour of application objects and classes and of GOOPS itself.
-Each subsequent section of the reference manual covers a particular area
-of GOOPS functionality, and describes the generic functions that are
-relevant for customization of that area.
-
-We conclude this subsubsection by emphasizing a point that may seem
-obvious, but contrasts with the corresponding situation in some other
-MOP implementations, such as CLOS.  The point is simply that an
-identifier which represents a GOOPS class or generic function is a
-variable with a first-class value, the value being an instance of class
address@hidden<class>} or @code{<generic>}.  (In CLOS, on the other hand, a
-class identifier is a symbol that indexes the corresponding class
-metaobject in a separate namespace for classes.)  This is, of course,
-simply an extension of the tendency in Scheme to avoid the unnecessary
-use of, on the one hand, syntactic forms that require unevaluated
-arguments and, on the other, separate identifier namespaces (e.g. for
-class names), but it is worth noting that GOOPS conforms fully to this
-Schemely principle.
-
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
-
-A @dfn{metaclass} is the class of an object which represents a GOOPS
-class.  Put more succinctly, a metaclass is a class's class.
-
-Most GOOPS classes have the metaclass @code{<class>} and, by default,
-any new class that is created using @code{define-class} has the
-metaclass @code{<class>}.
-
-But what does this really mean?  To find out, let's look in more detail
-at what happens when a new class is created using @code{define-class}:
-
address@hidden
-(define-class <my-class> (<object>) . slots)
address@hidden example
-
-GOOPS actually expands the @code{define-class} form to something like
-this
-
address@hidden
-(define <my-class> (class (<object>) . slots))
address@hidden example
-
-and thence to
-
address@hidden
-(define <my-class>
-  (make <class> #:supers (list <object>) #:slots slots))
address@hidden 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.)
-
-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:
-
address@hidden
-(define-class <my-class2> (<object>)
-   slot @dots{}
-   #:metaclass <my-metaclass>)
address@hidden example
-
-GOOPS expands this to something like:
-
address@hidden
-(define <my-class2>
-  (make <my-metaclass> #:supers (list <object>) #:slots slots))
address@hidden example
-
-In this case, the value of @code{<my-class2>} is an instance of the more
-specialized class @code{<my-metaclass>}.  Note that
address@hidden<my-metaclass>} itself must previously have been defined as a
-subclass of @code{<class>}.  For a full discussion of when and how it is
-useful to define new metaclasses, see @ref{MOP Specification}.
-
-Now let's make an instance of @code{<my-class2>}:
-
address@hidden
-(define my-object (make <my-class2> ...))
address@hidden example
-
-All of the following statements are correct expressions of the
-relationships between @code{my-object}, @code{<my-class2>},
address@hidden<my-metaclass>} and @code{<class>}.
-
address@hidden @bullet
address@hidden
address@hidden is an instance of the class @code{<my-class2>}.
-
address@hidden
address@hidden<my-class2>} is an instance of the class @code{<my-metaclass>}.
-
address@hidden
address@hidden<my-metaclass>} is an instance of the class @code{<class>}.
-
address@hidden
-The class of @code{my-object} is @code{<my-class2>}.
-
address@hidden
-The metaclass of @code{my-object} is @code{<my-metaclass>}.
-
address@hidden
-The class of @code{<my-class2>} is @code{<my-metaclass>}.
-
address@hidden
-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>}.
address@hidden 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 Defining New Classes
address@hidden Defining New Classes
address@hidden Defining New Classes
 
 [ *fixme* Somewhere in this manual there needs to be an introductory
 discussion about GOOPS classes, generic functions and methods, covering
@@ -583,7 +231,7 @@ the discussion there. ]
 @end menu
 
 @node Basic Class Definition
address@hidden Basic Class Definition
address@hidden Basic Class Definition
 
 New classes are defined using the @code{define-class} syntax, with
 arguments that specify the classes that the new class should inherit
@@ -642,7 +290,7 @@ customized via an application-defined metaclass.
 @end example
 
 @node Class Options
address@hidden Class Options
address@hidden Class Options
 
 @deffn {class option} #:metaclass metaclass
 The @code{#:metaclass} class option specifies the metaclass of the class
@@ -675,7 +323,7 @@ environment defaults to the top-level environment in which 
the
 @end deffn
 
 @node Slot Options
address@hidden Slot Options
address@hidden Slot Options
 
 @deffn {slot option} #:allocation allocation
 The @code{#:allocation} option tells GOOPS how to allocate storage for
@@ -878,7 +526,7 @@ classes.
 @end deffn
 
 @node Class Definition Internals
address@hidden Class Definition Internals
address@hidden Class Definition Internals
 
 Implementation notes: @code{define-class} expands to an expression which
 
@@ -991,7 +639,7 @@ class object, are described in @ref{Customizing Instance 
Creation},
 which covers the creation and initialization of instances in general.
 
 @node Customizing Class Definition
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
@@ -1127,7 +775,7 @@ typically it would perform additional class initialization 
steps before
 and/or after calling @code{(next-method)} for the standard behaviour.
 
 @node STKlos Compatibility
address@hidden STKlos Compatibility
address@hidden STKlos Compatibility
 
 If the STKlos compatibility module is loaded, @code{define-class} is
 overwritten by a STKlos-specific definition; the standard GOOPS
@@ -1140,7 +788,7 @@ definition of @code{define-class} remains available in
 @end deffn
 
 @node Creating Instances
address@hidden Creating Instances
address@hidden Creating Instances
 
 @menu
 * Basic Instance Creation::
@@ -1148,7 +796,7 @@ definition of @code{define-class} remains available in
 @end menu
 
 @node Basic Instance Creation
address@hidden Basic Instance Creation
address@hidden Basic Instance Creation
 
 To create a new instance of any GOOPS class, use the generic function
 @code{make} or @code{make-instance}, passing the required class and any
@@ -1185,7 +833,7 @@ instance's class.  Any unprocessed keyword value pairs are 
ignored.
 @end deffn
 
 @node Customizing Instance Creation
address@hidden Customizing Instance Creation
address@hidden Customizing Instance Creation
 
 @code{make} itself is a generic function.  Hence the @code{make}
 invocation itself can be customized in the case where the new instance's
@@ -1252,7 +900,7 @@ and closures in the slot definitions, it is neater to 
write an
 and initializes all the dependent slot values according to the results.
 
 @node Accessing Slots
address@hidden Accessing Slots
address@hidden Accessing Slots
 
 The definition of a slot contains at the very least a slot name, and may
 also contain various slot options, including getter, setter and/or
@@ -1316,7 +964,7 @@ closures, see @ref{Customizing Class Definition,, 
compute-get-n-set}.)
 @end menu
 
 @node Instance Slots
address@hidden Instance Slots
address@hidden Instance Slots
 
 Any slot, regardless of its allocation, can be queried, referenced and
 set using the following four primitive procedures.
@@ -1413,7 +1061,7 @@ slot-missing}).
 @end deffn
 
 @node Class Slots
address@hidden Class Slots
address@hidden Class Slots
 
 Slots whose allocation is per-class rather than per-instance can be
 referenced and set without needing to specify any particular instance.
@@ -1441,7 +1089,7 @@ function with arguments @var{class} and @var{slot-name}.
 @end deffn
 
 @node Handling Slot Access Errors
address@hidden Handling Slot Access Errors
address@hidden Handling Slot Access Errors
 
 GOOPS calls one of the following generic functions when a ``slot-ref''
 or ``slot-set!'' call specifies a non-existent slot name, or tries to
@@ -1472,7 +1120,7 @@ message.
 @end deffn
 
 @node Creating Generic Functions
address@hidden Creating Generic Functions
address@hidden Creating Generic Functions
 
 A generic function is a collection of methods, with rules for
 determining which of the methods should be applied for any given
@@ -1488,7 +1136,7 @@ GOOPS represents generic functions as metaobjects of the 
class
 @end menu
 
 @node Basic Generic Function Creation
address@hidden Basic Generic Function Creation
address@hidden Basic Generic Function Creation
 
 The following forms may be used to bind a variable to a generic
 function.  Depending on that variable's pre-existing value, the generic
@@ -1598,7 +1246,7 @@ form of the @code{#:duplicates} option can be used 
instead:
 @end lisp
 
 @node Generic Function Internals
address@hidden Generic Function Internals
address@hidden Generic Function Internals
 
 @code{define-generic} calls @code{ensure-generic} to upgrade a
 pre-existing procedure value, or @code{make} with metaclass
@@ -1667,7 +1315,7 @@ accessor, passing the setter generic function as the 
value of the
 @code{#:setter} keyword.
 
 @node Extending Guiles Primitives
address@hidden Extending Guile's Primitives
address@hidden Extending Guile's Primitives
 
 When GOOPS is loaded, many of Guile's primitive procedures can be
 extended by giving them a generic function definition that operates
@@ -1714,7 +1362,7 @@ integrated into the core of Guile.  Consequently, the
 procedures described in this section may disappear as well.
 
 @node Adding Methods to Generic Functions
address@hidden Adding Methods to Generic Functions
address@hidden Adding Methods to Generic Functions
 
 @menu
 * Basic Method Definition::
@@ -1722,7 +1370,7 @@ procedures described in this section may disappear as 
well.
 @end menu
 
 @node Basic Method Definition
address@hidden Basic Method Definition
address@hidden Basic Method Definition
 
 To add a method to a generic function, use the @code{define-method} form.
 
@@ -1781,7 +1429,7 @@ invocation error handling, and generic function 
invocation in general,
 see @ref{Invoking Generic Functions}.
 
 @node Method Definition Internals
address@hidden Method Definition Internals
address@hidden Method Definition Internals
 
 @code{define-method}
 
@@ -1868,7 +1516,7 @@ function.
 @end deffn
 
 @node Invoking Generic Functions
address@hidden Invoking Generic Functions
address@hidden Invoking Generic Functions
 
 When a variable with a generic function definition appears as the first
 element of a list that is being evaluated, the Guile evaluator tries
@@ -1890,7 +1538,7 @@ may be applied subsequently if a method that is being 
applied calls
 @end menu
 
 @node Determining Which Methods to Apply
address@hidden Determining Which Methods to Apply
address@hidden Determining Which Methods to Apply
 
 [ *fixme*  Sorry - this is the area of GOOPS that I understand least of
 all, so I'm afraid I have to pass on this section.  Would some other
@@ -1921,7 +1569,7 @@ kind person consider filling it in? ]
 @end deffn
 
 @node Handling Invocation Errors
address@hidden Handling Invocation Errors
address@hidden Handling Invocation Errors
 
 @deffn generic no-method
 @deffnx method no-method (gf <generic>) args
@@ -1949,7 +1597,7 @@ default method calls @code{goops-error} with an 
appropriate message.
 @end deffn
 
 @node Redefining a Class
address@hidden Redefining a Class
address@hidden Redefining a Class
 
 Suppose that a class @code{<my-class>} is defined using @code{define-class}
 (@pxref{Basic Class Definition,, define-class}), with slots that have
@@ -1964,7 +1612,7 @@ make}).  What then happens if @code{<my-class>} is 
redefined by calling
 @end menu
 
 @node Default Class Redefinition Behaviour
address@hidden Default Class Redefinition Behaviour
address@hidden Default Class Redefinition Behaviour
 
 GOOPS' default answer to this question is as follows.
 
@@ -2017,7 +1665,7 @@ Also bear in mind that, like most of GOOPS' default 
behaviour, it can
 be address@hidden
 
 @node Customizing Class Redefinition
address@hidden Customizing Class Redefinition
address@hidden Customizing Class Redefinition
 
 When @code{define-class} notices that a class is being redefined,
 it constructs the new class metaobject as usual, and then invokes the
@@ -2082,7 +1730,7 @@ generic functions, and so address@hidden  The detailed 
protocol for all of these
 is described in @ref{MOP Specification}.
 
 @node Changing the Class of an Instance
address@hidden Changing the Class of an Instance
address@hidden Changing the Class of an Instance
 
 You can change the class of an existing instance by invoking the
 generic function @code{change-class} with two arguments: the instance
@@ -2121,7 +1769,7 @@ invokes the @code{change-class} generic function for each 
existing
 instance of the redefined class.
 
 @node Introspection
address@hidden Introspection
address@hidden Introspection
 
 @dfn{Introspection}, also known as @dfn{reflection}, is the name given
 to the ability to obtain information dynamically about GOOPS metaobjects.
@@ -2160,7 +1808,7 @@ GOOPS equivalents --- to be obtained dynamically, at run 
time.
 @end menu
 
 @node Classes
address@hidden Classes
address@hidden Classes
 
 @deffn {primitive procedure} class-name class
 Return the name of class @var{class}.
@@ -2220,7 +1868,7 @@ Return a list of all methods that use @var{class} or a 
subclass of
 @end deffn
 
 @node Slots
address@hidden Slots
address@hidden Slots
 
 @deffn procedure class-slot-definition class slot-name
 Return the slot definition for the slot named @var{slot-name} in class
@@ -2301,7 +1949,7 @@ see @ref{Slot Options,, init-value}.
 @end deffn
 
 @node Instances
address@hidden Instances
address@hidden Instances
 
 @deffn {primitive procedure} class-of value
 Return the GOOPS class of any Scheme @var{value}.
@@ -2322,7 +1970,7 @@ Implementation notes: @code{is-a?} uses @code{class-of} 
and
 @var{object}.
 
 @node Generic Functions
address@hidden Generic Functions
address@hidden Generic Functions
 
 @deffn {primitive procedure} generic-function-name gf
 Return the name of generic function @var{gf}.
@@ -2334,7 +1982,7 @@ This is the value of the @var{gf} metaobject's 
@code{methods} slot.
 @end deffn
 
 @node Generic Function Methods
address@hidden Generic Function Methods
address@hidden Generic Function Methods
 
 @deffn {primitive procedure} method-generic-function method
 Return the generic function that @var{method} belongs to.
@@ -2372,7 +2020,7 @@ Return an expression that prints to show the definition 
of method
 @end deffn
 
 @node Miscellaneous Functions
address@hidden Miscellaneous Functions
address@hidden Miscellaneous Functions
 
 @menu
 * Administrative Functions::
@@ -2383,7 +2031,7 @@ Return an expression that prints to show the definition 
of method
 @end menu
 
 @node Administrative Functions
address@hidden Administration Functions
address@hidden Administration Functions
 
 This section describes administrative, non-technical GOOPS functions.
 
@@ -2392,7 +2040,7 @@ Return the current GOOPS version as a string, for example 
``0.2''.
 @end deffn
 
 @node GOOPS Error Handling
address@hidden Error Handling
address@hidden Error Handling
 
 The procedure @code{goops-error} is called to raise an appropriate error
 by the default methods of the following generic functions:
@@ -2427,7 +2075,7 @@ as done by @code{scm-error}.
 @end deffn
 
 @node Object Comparisons
address@hidden Object Comparisons
address@hidden Object Comparisons
 
 @deffn generic eqv?
 @deffnx method eqv? ((x <top>) (y <top>))
@@ -2456,7 +2104,7 @@ and the Guile reference manual.
 @end deffn
 
 @node Cloning Objects
address@hidden Cloning Objects
address@hidden Cloning Objects
 
 @deffn generic shallow-clone
 @deffnx method shallow-clone (self <object>)
@@ -2477,7 +2125,7 @@ or by reference.
 @end deffn
 
 @node Write and Display
address@hidden Write and Display
address@hidden Write and Display
 
 @deffn {primitive generic} write object port
 @deffnx {primitive generic} display object port
@@ -2505,11 +2153,315 @@ methods - instances of the class @code{<method>}.
 as the Guile primitive @code{write} and @code{display} functions.
 @end deffn
 
address@hidden MOP Specification
address@hidden MOP Specification
address@hidden The Metaobject Protocol
address@hidden The Metaobject Protocol
+
+GOOPS is based on a ``metaobject protocol'' (aka ``MOP'') derived from
+the ones used in CLOS (the Common Lisp Object 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.
+
address@hidden
+* Metaobjects and the Metaobject Protocol::
+* Terminology::
+* MOP Specification::
+* Class Definition::
+* Instance Creation::
+* Class Redefinition::
+* Method Definition::
+* Generic Function Invocation::
address@hidden menu
+
address@hidden Metaobjects and the Metaobject Protocol
address@hidden Metaobjects and the Metaobject Protocol
+
+The building blocks of GOOPS are classes, slot definitions, instances,
+generic functions and methods.  A class is a grouping of inheritance
+relations and slot definitions.  An instance is an object with slots
+that are allocated following the rules implied by its class's
+superclasses and slot definitions.  A generic function is a collection
+of methods and rules for determining which of those methods to apply
+when the generic function is invoked.  A method is a procedure and a set
+of specializers that specify the type of arguments to which the
+procedure is applicable.
+
+Of these entities, GOOPS represents classes, generic functions and
+methods as ``metaobjects''.  In other words, the values in a GOOPS
+program that describe classes, generic functions and methods, are
+themselves instances (or ``objects'') of special GOOPS classes that
+encapsulate the behaviour, respectively, of classes, generic functions,
+and methods.
+
+(The other two entities are slot definitions and instances.  Slot
+definitions are not strictly instances, but every slot definition is
+associated with a GOOPS class that specifies the behaviour of the slot
+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
+generic functions which determine the behaviour of these metaobjects and
+the circumstances in which these generic functions are invoked.
+
+For a concrete example of what this means, consider how GOOPS calculates
+the set of slots for a class that is being defined using
address@hidden  The desired set of slots is the union of the new
+class's direct slots and the slots of all its superclasses.  But
address@hidden itself does not perform this calculation.  Instead,
+there is a method of the @code{initialize} generic function that is
+specialized for instances of type @code{<class>}, and it is this method
+that performs the slot calculation.
+
address@hidden is a generic function which GOOPS calls whenever a new
+instance is created, immediately after allocating memory for a new
+instance, in order to initialize the new instance's slots.  The sequence
+of steps is as follows.
+
address@hidden @bullet
address@hidden
address@hidden uses @code{make} to make a new instance of the
address@hidden<class>} class, passing as initialization arguments the
+superclasses, slot definitions and class options that were specified in
+the @code{define-class} form.
+
address@hidden
address@hidden allocates memory for the new instance, and then invokes the
address@hidden generic function to initialize the new instance's
+slots.
+
address@hidden
+The @code{initialize} generic function applies the method that is
+specialized for instances of type @code{<class>}, and this method
+performs the slot calculation.
address@hidden 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>}.
+
+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}
+method that is specialized for instances of the new metaclass.  Then, if
+the @code{define-class} form includes a @code{#:metaclass} class option
+whose value is the new metaclass, the class that is defined by the
address@hidden form will be an instance of the new metaclass rather
+than of the default @code{<class>}, and will be defined in accordance
+with the new @code{initialize} method.  Thus the default slot
+calculation, as well as any other aspect of the new class's relationship
+with its superclasses, can be modified or overridden.
 
-For an introduction to metaobjects and the metaobject protocol,
-see @ref{Metaobjects and the Metaobject Protocol}.
+In a similar way, the behaviour of generic functions can be modified or
+overridden by creating a new class that inherits from the standard
+generic function class @code{<generic>}, writing appropriate methods
+that are specialized to the new class, and creating new generic
+functions that are instances of the new class.
+
+The same is true for method metaobjects.  And the same basic mechanism
+allows the application class author to write an @code{initialize} method
+that is specialized to their application class, to initialize instances
+of that class.
+
+Such is the power of the MOP.  Note that @code{initialize} is just one
+of a large number of generic functions that can be customized to modify
+the behaviour of application objects and classes and of GOOPS itself.
+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
+
+A @dfn{metaclass} is the class of an object which represents a GOOPS
+class.  Put more succinctly, a metaclass is a class's class.
+
+Most GOOPS classes have the metaclass @code{<class>} and, by default,
+any new class that is created using @code{define-class} has the
+metaclass @code{<class>}.
+
+But what does this really mean?  To find out, let's look in more detail
+at what happens when a new class is created using @code{define-class}:
+
address@hidden
+(define-class <my-class> (<object>) . slots)
address@hidden example
+
+GOOPS actually expands the @code{define-class} form to something like
+this
+
address@hidden
+(define <my-class> (class (<object>) . slots))
address@hidden example
+
+and thence to
+
address@hidden
+(define <my-class>
+  (make <class> #:supers (list <object>) #:slots slots))
address@hidden 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.)
+
+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:
+
address@hidden
+(define-class <my-class2> (<object>)
+   slot @dots{}
+   #:metaclass <my-metaclass>)
address@hidden example
+
+GOOPS expands this to something like:
+
address@hidden
+(define <my-class2>
+  (make <my-metaclass> #:supers (list <object>) #:slots slots))
address@hidden example
+
+In this case, the value of @code{<my-class2>} is an instance of the more
+specialized class @code{<my-metaclass>}.  Note that
address@hidden<my-metaclass>} itself must previously have been defined as a
+subclass of @code{<class>}.  For a full discussion of when and how it is
+useful to define new metaclasses, see @ref{MOP Specification}.
+
+Now let's make an instance of @code{<my-class2>}:
+
address@hidden
+(define my-object (make <my-class2> ...))
address@hidden example
+
+All of the following statements are correct expressions of the
+relationships between @code{my-object}, @code{<my-class2>},
address@hidden<my-metaclass>} and @code{<class>}.
+
address@hidden @bullet
address@hidden
address@hidden is an instance of the class @code{<my-class2>}.
+
address@hidden
address@hidden<my-class2>} is an instance of the class @code{<my-metaclass>}.
+
address@hidden
address@hidden<my-metaclass>} is an instance of the class @code{<class>}.
+
address@hidden
+The class of @code{my-object} is @code{<my-class2>}.
+
address@hidden
+The metaclass of @code{my-object} is @code{<my-metaclass>}.
+
address@hidden
+The class of @code{<my-class2>} is @code{<my-metaclass>}.
+
address@hidden
+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>}.
address@hidden 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
+
address@hidden MOP Specification
address@hidden MOP Specification
 
 The aim of the MOP specification in this chapter is to specify all the
 customizable generic function invocations that can be made by the standard
@@ -2552,14 +2504,6 @@ effects
 what the caller expects to get as the applied method's return value.
 @end itemize
 
address@hidden
-* Class Definition::
-* Instance Creation::
-* Class Redefinition::
-* Method Definition::
-* Generic Function Invocation::
address@hidden menu
-
 @node Class Definition
 @subsection Class Definition
 


hooks/post-receive
-- 
GNU Guile