[Guile-commits] GNU Guile branch, master, updated. release_1-9-12-138-g17285a7

[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=17285a7c491a5d23c6d44c519dbf5b93e3dbb916

The branch, master has been updated
       via  17285a7c491a5d23c6d44c519dbf5b93e3dbb916 (commit)
       via  647db87dbc623e07bb12270b1a8f377d8bfe061b (commit)
       via  1e32c6cd6ec505a3dcee947c6b441a8a0f64d607 (commit)
      from  6e197f3d1af34cffef0b285f655b84d2d63bbdeb (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 17285a7c491a5d23c6d44c519dbf5b93e3dbb916
Author: Neil Jerram <address@hidden>
Date:   Sun Oct 3 23:22:03 2010 +0100

    Edit section on generic functions
    
    * doc/ref/goops.texi (Generic Functions and Accessors): Renamed from
      `Creating Generic Functions'.  Explain what an accessor is.
      (Basic Generic Function Creation): Clarify the point of the text
      about generics having short names.

commit 647db87dbc623e07bb12270b1a8f377d8bfe061b
Author: Neil Jerram <address@hidden>
Date:   Sun Oct 3 23:20:17 2010 +0100

    Edit section on slot access
    
    * doc/ref/goops.texi (Instance Slots): Remove a little verbosity.
      (Class Slots): Correct one `slot-missing' to `slot-unbound'.

commit 1e32c6cd6ec505a3dcee947c6b441a8a0f64d607
Author: Neil Jerram <address@hidden>
Date:   Sun Oct 3 23:17:54 2010 +0100

    Typeset Ludo's name correctly
    
    * doc/ref/history.texi (A Scheme of Many Maintainers): Add
      TeX-specific version of `Courtès'.

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

Summary of changes:
 doc/ref/goops.texi   |   58 ++++++++++++++++++++++++++++++-------------------
 doc/ref/history.texi |   18 +++++++++++++--
 2 files changed, 50 insertions(+), 26 deletions(-)

diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index e0a0088..07a2a3f 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -35,7 +35,7 @@ overriding or redefining those methods.
 * Defining New Classes::
 * Creating Instances::
 * Accessing Slots::
-* Creating Generic Functions::
+* Generic Functions and Accessors::
 * Adding Methods to Generic Functions::
 * Invoking Generic Functions::
 * Redefining a Class::
@@ -636,25 +636,21 @@ Set the value of the slot named @var{slot-name} in 
@var{obj} to @var{value}.
 Slot Access Errors, slot-missing}).
 @end deffn
 
-GOOPS stores information about slots in class metaobjects.  Internally,
+GOOPS stores information about slots in classes.  Internally,
 all of these procedures work by looking up the slot definition for the
-slot named @var{slot-name} in the class metaobject for @code{(class-of
+slot named @var{slot-name} in the class @code{(class-of
 @var{obj})}, and then using the slot definition's ``getter'' and
 ``setter'' closures to get and set the slot value.
 
 The next four procedures differ from the previous ones in that they take
-the class metaobject as an explicit argument, rather than assuming
+the class as an explicit argument, rather than assuming
 @code{(class-of @var{obj})}.  Therefore they allow you to apply the
 ``getter'' and ``setter'' closures of a slot definition in one class to
 an instance of a different class.
 
-[ *fixme* I have no idea why this is useful!  Perhaps when a slot in
address@hidden(class-of @var{obj})} shadows a slot with the same name in one of
-its superclasses?  There should be an enlightening example here. ]
-
 @deffn {primitive procedure} slot-exists-using-class? class obj slot-name
-Return @code{#t} if the class metaobject @var{class} has a slot
-definition for a slot with name @var{slot-name}, otherwise @code{#f}.
+Return @code{#t} if @var{class} has a slot definition for a slot with
+name @var{slot-name}, otherwise @code{#f}.
 @end deffn
 
 @deffn {primitive procedure} slot-bound-using-class? class obj slot-name
@@ -708,7 +704,7 @@ If there is no such slot with @code{#:class} or 
@code{#:each-subclass}
 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
 function with arguments @var{class} and @var{slot-name}.  Otherwise, if
 the slot value is unbound, @code{class-slot-ref} calls the
address@hidden generic function, with the same arguments.
address@hidden generic function, with the same arguments.
 @end deffn
 
 @deffn procedure class-slot-set! class slot-name value
@@ -752,15 +748,25 @@ The default methods all call @code{goops-error} with an 
appropriate
 message.
 @end deffn
 
address@hidden Creating Generic Functions
address@hidden Creating Generic Functions
address@hidden Generic Functions and Accessors
address@hidden Generic Functions and Accessors
 
 A generic function is a collection of methods, with rules for
 determining which of the methods should be applied for any given
-invocation of the generic function.
+invocation of the generic function.  GOOPS represents generic functions
+as metaobjects of the class @code{<generic>} (or one of its subclasses).
+
+An accessor is a generic function that can also be used with the
+generalized @code{set!} syntax (@pxref{Procedures with Setters}).  Guile
+will handle a call like
+
address@hidden
+(set! (@code{accessor} @address@hidden) @code{value})
address@hidden example
 
-GOOPS represents generic functions as metaobjects of the class
address@hidden<generic>} (or one of its subclasses).
address@hidden
+by calling the most specialized method of @code{accessor} that matches
+the classes of @code{args} and @code{value}.
 
 @menu
 * Basic Generic Function Creation::
@@ -817,13 +823,19 @@ including an existing generic function or accessor, is 
overwritten by
 the new definition.
 @end deffn
 
-It is sometimes tempting to use GOOPS accessors with short names.  For
-example, it is tempting to use the name @code{x} for the x-coordinate
-in vector packages.
+GOOPS generic functions and accessors often have short, generic names.
+For example, if a vector package provides an accessor for the X
+coordinate of a vector, that accessor may just be called @code{x}.  It
+doesn't need to be called, for example, @code{vector:x}, because
+GOOPS will work out, when it sees code like @code{(x @var{obj})}, that
+the vector-specific method of @code{x} should be called if @var{obj} is
+a vector.
 
-Assume that we work with a graphical package which needs to use two
-independent vector packages for 2D and 3D vectors respectively.  If
-both packages export @code{x} we will encounter a name collision.
+That raises the question, however, of what happens when different
+packages define a generic function with the same name.  Suppose we
+work with a graphical package which needs to use two independent vector
+packages for 2D and 3D vectors respectively.  If both packages export
address@hidden we will encounter a name collision.
 
 This can be resolved automagically with the duplicates handler
 @code{merge-generics} which gives the module system license to merge
diff --git a/doc/ref/history.texi b/doc/ref/history.texi
index f1109b2..112696c 100644
--- a/doc/ref/history.texi
+++ b/doc/ref/history.texi
@@ -133,9 +133,21 @@ years until the end of 1999, when he too moved on to other 
projects.
 Since then, Guile has had a group maintainership. The first group was
 Maciej Stachowiak, Mikael Djurfeldt, and Marius Vollmer, with Vollmer
 staying on the longest. By late 2007, Vollmer had mostly moved on to
-other things, so Neil Jerram and Ludovic Courtès stepped up to take on
-the primary maintenance responsibility. Jerram and Courtès were joined
-by Andy Wingo in late 2009.
+other things, so Neil Jerram and Ludovic
address@hidden
address@hidden
address@hidden iftex
address@hidden
+Courtès
address@hidden ifnottex
+stepped up to take on the primary maintenance responsibility. Jerram and
address@hidden
address@hidden
address@hidden iftex
address@hidden
+Courtès
address@hidden ifnottex
+were joined by Andy Wingo in late 2009.
 
 Of course, a large part of the actual work on Guile has come from
 other contributors too numerous to mention, but without whom the world


hooks/post-receive
-- 
GNU Guile