[Guile-commits] GNU Guile branch, master, updated. release_1-9-12-90-g8445eb1

[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=8445eb1db513bc68b26f0363da7ea419d7994f06

The branch, master has been updated
       via  8445eb1db513bc68b26f0363da7ea419d7994f06 (commit)
      from  630f46f192be9274a5ec05304ad25efd22ff9520 (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 8445eb1db513bc68b26f0363da7ea419d7994f06
Author: Neil Jerram <address@hidden>
Date:   Sun Sep 26 19:42:01 2010 +0100

    Edit define-class doc
    
    * doc/ref/goops.texi (Defining New Classes): Remove "fixme" text
      (saying we should have something that we in fact already have).  A
      few minor edits throughout.
    
      (Basic Class Definition): Move content up into `Defining New
      Classes'.
    
      (Class Options): Move after `Slot Options' (because slot options are
      more important).  Remove doc of the #:environment option, since I
      believe it's now fictitious.
    
      (Slot Options): Reorder the options so that the most commonly used
      ones come first.

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

Summary of changes:
 doc/ref/goops.texi |  352 ++++++++++++++++++++++++----------------------------
 1 files changed, 161 insertions(+), 191 deletions(-)

diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index fbf4f75..9a7e774 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -191,51 +191,13 @@ objects, to add two of them together:
 @section Tutorial
 @include goops-tutorial.texi
 
+
 @node Defining New Classes
 @section Defining New Classes
 
-[ *fixme* Somewhere in this manual there needs to be an introductory
-discussion about GOOPS classes, generic functions and methods, covering
-
address@hidden @bullet
address@hidden
-how classes encapsulate related items of data in @dfn{slots}
-
address@hidden
-why it is that, unlike in C++ and Java, a class does not encapsulate the
-methods that act upon the class (at least not in the C++/Java sense)
-
address@hidden
-how generic functions provide a more general solution that provides for
-dispatch on all argument types, and avoids idiosyncracies like C++'s
-friend classes
-
address@hidden
-how encapsulation in the sense of data- and code-hiding, or of
-distinguishing interface from implementation, is treated in Guile as an
-orthogonal concept to object orientation, and is the responsibility of
-the module system.
address@hidden itemize
-
-Some of this is covered in the Tutorial chapter, in @ref{Generic
-functions and methods} - perhaps the best solution would be to expand
-the discussion there. ]
-
address@hidden
-* Basic Class Definition::
-* Class Options::
-* Slot Options::
-* Class Definition Internals::
-* Customizing Class Definition::
-* STKlos Compatibility::
address@hidden menu
-
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
-from, the direct slots of the new class, and any required class options.
+from, the direct slots of the new class, and any class options.
 
 @deffn syntax define-class name (super @dots{}) slot-definition @dots{} . 
options
 Define a class called @var{name} that inherits from @var{super}s, with
@@ -259,9 +221,6 @@ odd-numbered elements are the corresponding values for 
those keywords.
 keywords and corresponding values.
 @end deffn
 
-The standard GOOPS class and slot options are described in the following
-subsubsections: see @ref{Class Options} and @ref{Slot Options}.
-
 Example 1.  Define a class that combines two pre-existing classes by
 inheritance but adds no new slots.
 
@@ -270,8 +229,9 @@ inheritance but adds no new slots.
 @end example
 
 Example 2.  Define a @code{regular-polygon} class with slots for side
-length and number of sides that have default values and can be accessed
-via the generic functions @code{side-length} and @code{num-sides}.
+length and number of sides.  The slots have default values and can be
+accessed via the generic functions @code{side-length} and
address@hidden
 
 @example
 (define-class <regular-polygon> ()
@@ -289,153 +249,20 @@ customized via an application-defined metaclass.
   #:metaclass <finite-state-class>)
 @end example
 
address@hidden Class Options
address@hidden Class Options
-
address@hidden {class option} #:metaclass metaclass
-The @code{#:metaclass} class option specifies the metaclass of the class
-being defined.  @var{metaclass} must be a class that inherits from
address@hidden<class>}.  For an introduction to the use of metaclasses, see
address@hidden and the Metaobject Protocol} and @ref{Terminology}.
-
-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}).
address@hidden deffn
+The possible slot and class options are described in the following
+subsections.
 
address@hidden {class option} #:name name
-The @code{#:name} class option specifies the new class's name.  This
-name is used to identify the class whenever related objects - the class
-itself, its instances and its subclasses - are printed.
-
-If the @code{#:name} option is absent, GOOPS uses the first argument to
address@hidden as the class name.
address@hidden deffn
-
address@hidden {class option} #:environment environment
-*fixme* Not sure about this one, but I think that the
address@hidden:environment} option specifies the environment in which the
-class's getters and setters are computed and evaluated.
-
-If the @code{#:environment} option is not specified, the class's
-environment defaults to the top-level environment in which the
address@hidden form appears.
address@hidden deffn
address@hidden
+* Slot Options::
+* Class Options::
+* Class Definition Internals::
+* Customizing Class Definition::
+* STKlos Compatibility::
address@hidden menu
 
 @node Slot Options
 @subsection Slot Options
 
address@hidden {slot option} #:allocation allocation
-The @code{#:allocation} option tells GOOPS how to allocate storage for
-the slot.  Possible values for @var{allocation} are
-
address@hidden @bullet
address@hidden @code{#:instance}
-
-Indicates that GOOPS should create separate storage for this slot in
-each new instance of the containing class (and its subclasses).
-
address@hidden @code{#:class}
-
-Indicates that GOOPS should create storage for this slot that is shared
-by all instances of the containing class (and its subclasses).  In other
-words, a slot in class @var{C} with allocation @code{#:class} is shared
-by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
-
address@hidden @code{#:each-subclass}
-
-Indicates that GOOPS should create storage for this slot that is shared
-by all @emph{direct} instances of the containing class, and that
-whenever a subclass of the containing class is defined, GOOPS should
-create a new storage for the slot that is shared by all @emph{direct}
-instances of the subclass.  In other words, a slot with allocation
address@hidden:each-subclass} is shared by all instances with the same
address@hidden
-
address@hidden @code{#:virtual}
-
-Indicates that GOOPS should not allocate storage for this slot.  The
-slot definition must also include the @code{#:slot-ref} and
address@hidden:slot-set!} options to specify how to reference and set the value
-for this slot.
address@hidden itemize
-
-The default value is @code{#:instance}.
-
-Slot allocation options are processed when defining a new class by the
-generic function @code{compute-get-n-set}, which is specialized by the
-class's metaclass.  Hence new types of slot allocation can be
-implemented by defining a new metaclass and a method for
address@hidden that is specialized for the new metaclass.  For
-an example of how to do this, see @ref{Customizing Class Definition}.
address@hidden deffn
-
address@hidden {slot option} #:slot-ref getter
address@hidden {slot option} #:slot-set! setter
-The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
-if the slot allocation is @code{#:virtual}, and are ignored otherwise.
-
address@hidden should be a closure taking a single @var{instance} parameter
-that returns the current slot value.  @var{setter} should be a closure
-taking two parameters - @var{instance} and @var{new-val} - that sets the
-slot value to @var{new-val}.
address@hidden deffn
-
address@hidden {slot option} #:getter getter
address@hidden {slot option} #:setter setter
address@hidden {slot option} #:accessor accessor
-These options, if present, tell GOOPS to create generic function and
-method definitions that can be used to get and set the slot value more
-conveniently than by using @code{slot-ref} and @code{slot-set!}.
-
address@hidden specifies a generic function to which GOOPS will add a
-method for getting the slot value.  @var{setter} specifies a generic
-function to which GOOPS will add a method for setting the slot value.
address@hidden specifies an accessor to which GOOPS will add methods for
-both getting and setting the slot value.
-
-So if a class includes a slot definition like this:
-
address@hidden
-(c #:getter get-count #:setter set-count #:accessor count)
address@hidden example
-
-GOOPS defines generic function methods such that the slot value can be
-referenced using either the getter or the accessor -
-
address@hidden
-(let ((current-count (get-count obj))) @dots{})
-(let ((current-count (count obj))) @dots{})
address@hidden example
-
-- and set using either the setter or the accessor -
-
address@hidden
-(set-count obj (+ 1 current-count))
-(set! (count obj) (+ 1 current-count))
address@hidden example
-
-Note that
-
address@hidden @bullet
address@hidden
-with an accessor, the slot value is set using the generalized
address@hidden syntax
-
address@hidden
-in practice, it is unusual for a slot to use all three of these options:
-read-only, write-only and read-write slots would typically use only
address@hidden:getter}, @code{#:setter} and @code{#:accessor} options
-respectively.
address@hidden itemize
-
-If the specified names are already bound in the top-level environment to
-values that cannot be upgraded to generic functions, those values are
-overwritten during evaluation of the @code{define-class} that contains
-the slot definition.  For details, see @ref{Generic Function Internals,,
-ensure-generic}.
address@hidden deffn
-
 @deffn {slot option} #:init-value init-value
 @deffnx {slot option} #:init-form init-form
 @deffnx {slot option} #:init-thunk init-thunk
@@ -525,6 +352,149 @@ more specialized code, or may not be supported at all for 
particular
 classes.
 @end deffn
 
address@hidden {slot option} #:getter getter
address@hidden {slot option} #:setter setter
address@hidden {slot option} #:accessor accessor
+Given an object @var{obj} with slots named @code{foo} and @code{bar}, it
+is always possible to read and write those slots by calling
address@hidden and @code{slot-set!} with the relevant slot name; for
+example:
+
address@hidden
+(slot-ref @var{obj} 'foo)
+(slot-set! @var{obj} 'bar 25)
address@hidden example
+
+The @code{#:getter}, @code{#:setter} and @code{#:accessor} options, if
+present, tell GOOPS to create generic function and method definitions
+that can be used to get and set the slot value more conveniently.
address@hidden specifies a generic function to which GOOPS will add a
+method for getting the slot value.  @var{setter} specifies a generic
+function to which GOOPS will add a method for setting the slot value.
address@hidden specifies an accessor to which GOOPS will add methods for
+both getting and setting the slot value.
+
+So if a class includes a slot definition like this:
+
address@hidden
+(c #:getter get-count #:setter set-count #:accessor count)
address@hidden example
+
+GOOPS defines generic function methods such that the slot value can be
+referenced using either the getter or the accessor -
+
address@hidden
+(let ((current-count (get-count obj))) @dots{})
+(let ((current-count (count obj))) @dots{})
address@hidden example
+
+- and set using either the setter or the accessor -
+
address@hidden
+(set-count obj (+ 1 current-count))
+(set! (count obj) (+ 1 current-count))
address@hidden example
+
+Note that
+
address@hidden @bullet
address@hidden
+with an accessor, the slot value is set using the generalized
address@hidden syntax
+
address@hidden
+in practice, it is unusual for a slot to use all three of these options:
+read-only, write-only and read-write slots would typically use only
address@hidden:getter}, @code{#:setter} and @code{#:accessor} options
+respectively.
address@hidden itemize
+
+If the specified names are already bound in the top-level environment to
+values that cannot be upgraded to generic functions, those values are
+overwritten during evaluation of the @code{define-class} that contains
+the slot definition.  For details, see @ref{Generic Function Internals,,
+ensure-generic}.
address@hidden deffn
+
address@hidden {slot option} #:allocation allocation
+The @code{#:allocation} option tells GOOPS how to allocate storage for
+the slot.  Possible values for @var{allocation} are
+
address@hidden @bullet
address@hidden @code{#:instance}
+
+Indicates that GOOPS should create separate storage for this slot in
+each new instance of the containing class (and its subclasses).
+
address@hidden @code{#:class}
+
+Indicates that GOOPS should create storage for this slot that is shared
+by all instances of the containing class (and its subclasses).  In other
+words, a slot in class @var{C} with allocation @code{#:class} is shared
+by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
+
address@hidden @code{#:each-subclass}
+
+Indicates that GOOPS should create storage for this slot that is shared
+by all @emph{direct} instances of the containing class, and that
+whenever a subclass of the containing class is defined, GOOPS should
+create a new storage for the slot that is shared by all @emph{direct}
+instances of the subclass.  In other words, a slot with allocation
address@hidden:each-subclass} is shared by all instances with the same
address@hidden
+
address@hidden @code{#:virtual}
+
+Indicates that GOOPS should not allocate storage for this slot.  The
+slot definition must also include the @code{#:slot-ref} and
address@hidden:slot-set!} options to specify how to reference and set the value
+for this slot.
address@hidden itemize
+
+The default value is @code{#:instance}.
+
+Slot allocation options are processed when defining a new class by the
+generic function @code{compute-get-n-set}, which is specialized by the
+class's metaclass.  Hence new types of slot allocation can be
+implemented by defining a new metaclass and a method for
address@hidden that is specialized for the new metaclass.  For
+an example of how to do this, see @ref{Customizing Class Definition}.
address@hidden deffn
+
address@hidden {slot option} #:slot-ref getter
address@hidden {slot option} #:slot-set! setter
+The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
+if the slot allocation is @code{#:virtual}, and are ignored otherwise.
+
address@hidden should be a closure taking a single @var{instance} parameter
+that returns the current slot value.  @var{setter} should be a closure
+taking two parameters - @var{instance} and @var{new-val} - that sets the
+slot value to @var{new-val}.
address@hidden deffn
+
address@hidden Class Options
address@hidden Class Options
+
address@hidden {class option} #:metaclass metaclass
+The @code{#:metaclass} class option specifies the metaclass of the class
+being defined.  @var{metaclass} must be a class that inherits from
address@hidden<class>}.  For the use of metaclasses, see @ref{Metaobjects and
+the Metaobject Protocol} and @ref{Terminology}.
+
+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}).
address@hidden deffn
+
address@hidden {class option} #:name name
+The @code{#:name} class option specifies the new class's name.  This
+name is used to identify the class whenever related objects - the class
+itself, its instances and its subclasses - are printed.
+
+If the @code{#:name} option is absent, GOOPS uses the first argument to
address@hidden as the class name.
address@hidden deffn
+
 @node Class Definition Internals
 @subsection Class Definition Internals
 
@@ -551,7 +521,7 @@ handles the redefinition by invoking 
@code{class-redefinition}
 Return a newly created class that inherits from @var{super}s, with
 direct slots defined by @var{slot-definition}s and class options
 @var{options}.  For the format of @var{slot-definition}s and
address@hidden, see @ref{Basic Class Definition,, define-class}.
address@hidden, see @ref{Defining New Classes,, define-class}.
 @end deffn
 
 Implementation notes: @code{class} expands to an expression which
@@ -572,8 +542,8 @@ evaluated parameters.
 @deffn procedure make-class supers slots . options
 Return a newly created class that inherits from @var{supers}, with
 direct slots defined by @var{slots} and class options @var{options}.
-For the format of @var{slots} and @var{options}, see @ref{Basic Class
-Definition,, define-class}, except note that for @code{make-class},
+For the format of @var{slots} and @var{options}, see @ref{Defining New
+Classes,, define-class}, except note that for @code{make-class},
 @var{slots} and @var{options} are separate list parameters: @var{slots}
 here is a list of slot definitions.
 @end deffn
@@ -1600,7 +1570,7 @@ default method calls @code{goops-error} with an 
appropriate message.
 @section 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
+(@pxref{Defining New Classes,, define-class}), with slots that have
 accessor functions, and that an application has created several instances
 of @code{<my-class>} using @code{make} (@pxref{Basic Instance Creation,,
 make}).  What then happens if @code{<my-class>} is redefined by calling


hooks/post-receive
-- 
GNU Guile