|
| From: | Neil Jerram |
| Subject: | [Guile-commits] GNU Guile branch, master, updated. release_1-9-12-208-ga54f6dc |
| Date: | Tue, 12 Oct 2010 22:42:49 +0000 |
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=a54f6dc037db1c7c8027422173234d56300762da
The branch, master has been updated
via a54f6dc037db1c7c8027422173234d56300762da (commit)
via eed4cc7bacefa119718bc691a1af14a283341a78 (commit)
from 03604fcf509892f894ce58096bbd3458080e3a19 (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 a54f6dc037db1c7c8027422173234d56300762da
Author: Neil Jerram <address@hidden>
Date: Tue Oct 12 23:41:41 2010 +0100
Two very small edits
* doc/ref/goops.texi (User-defined classes): Remove brackets around
`formally', for better flow.
(Creating Instances): Lengthen hyphen.
commit eed4cc7bacefa119718bc691a1af14a283341a78
Author: Neil Jerram <address@hidden>
Date: Tue Oct 12 23:40:01 2010 +0100
Edit `Generic Functions and Accessors'
* doc/ref/goops.texi (Generic Function Internals): Moved to MOP section
at end of chapter.
(Basic Generic Function Creation): Flattened into parent, and text
simplified.
(Extending Primitives): Renamed from `Extending Guiles Primitives';
removed `generic-capability?', which is no longer available;
simplified a bit.
(Merging Generics): New subsection for the material about merging;
text simplified a bit.
-----------------------------------------------------------------------
Summary of changes:
doc/ref/goops.texi | 358 +++++++++++++++++++++++-----------------------------
1 files changed, 155 insertions(+), 203 deletions(-)
diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index 07a2a3f..d43af60 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -147,7 +147,7 @@ be, and how they will be initialised and accessed.
(y #:init-value 0 #:accessor y-component #:init-keyword #:y))
@end lisp
-Methods are not (formally) part of a specific class's definition,
+Methods are not formally part of a specific class's definition,
because a single method can be associated with several classes. If
you've studied object orientation in non-Lispy languages, you may
remember discussions such as whether a method to stretch a graphical
@@ -502,7 +502,7 @@ 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
appropriate instance initialization arguments as keyword and value
pairs. Note that @code{make} and @code{make-instances} are aliases for
-each other - their behaviour is identical.
+each other --- their behaviour is identical.
@deffn generic make
@deffnx method make (class <class>) . initargs
@@ -768,61 +768,67 @@ will handle a call like
by calling the most specialized method of @code{accessor} that matches
the classes of @code{args} and @code{value}.
address@hidden
-* Basic Generic Function Creation::
-* Generic Function Internals::
-* Extending Guiles Primitives::
address@hidden menu
-
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
-function may be created empty - with no methods - or it may contain
-methods that are inferred from the pre-existing value.
-
-It is not, in general, necessary to use @code{define-generic} or
address@hidden before defining methods for the generic function
-using @code{define-method}, since @code{define-method} will
-automatically interpolate a @code{define-generic} call, or upgrade an
-existing generic to an accessor, if that is implied by the
address@hidden call. Note in particular that,
-if the specified variable already has a @emph{generic function} value,
address@hidden and @code{define-accessor} will @emph{discard} it!
-Obviously it is application-dependent whether this is desirable or not.
-
-If, for example, you wanted to extend @code{+} for a class representing
-a new numerical type, you probably want to inherit any existing methods
-for @code{+} and so should not use @code{define-generic}. If, on the
-other hand, you do not want to risk inheriting methods whose behaviour
-might surprise you, you can use @code{define-generic} or
address@hidden to wipe the slate clean.
+The following forms define a variable as a generic function or accessor.
+Depending on that variable's previous value, the generic function may be
+created empty --- with no methods --- or with methods that are inferred
+from the previous value.
@deffn syntax define-generic symbol
Create a generic function with name @var{symbol} and bind it to the
-variable @var{symbol}.
-
-If the variable @var{symbol} was previously bound to a Scheme procedure
-(or procedure-with-setter), the old procedure (and setter) is
+variable @var{symbol}. If @var{symbol} was previously bound to a Scheme
+procedure (or procedure-with-setter), the old procedure (and setter) is
incorporated into the new generic function as its default procedure (and
-setter). Any other previous value that was bound to @var{symbol},
-including an existing generic function, is overwritten by the new
-generic function.
+setter). Any other previous value, including an existing generic
+function, is discarded and replaced by a new, empty generic function.
@end deffn
@deffn syntax define-accessor symbol
Create an accessor with name @var{symbol} and bind it to the variable
address@hidden
-
-If the variable @var{symbol} was previously bound to a Scheme procedure
-(or procedure-with-setter), the old procedure (and setter) is
address@hidden If @var{symbol} was previously bound to a Scheme
+procedure (or procedure-with-setter), the old procedure (and setter) is
incorporated into the new accessor as its default procedure (and
-setter). Any other previous value that was bound to @var{symbol},
-including an existing generic function or accessor, is overwritten by
-the new definition.
+setter). Any other previous value, including an existing generic
+function or accessor, is discarded and replaced by a new, empty
+accessor.
address@hidden deffn
+
address@hidden
+* Extending Primitives::
+* Merging Generics::
address@hidden menu
+
address@hidden Extending Primitives
address@hidden Extending Primitives
+
+Many of Guile's primitive procedures can be extended by giving them a
+generic function definition that operates in conjunction with their
+normal C-coded implementation. When a primitive is extended in this
+way, it behaves like a generic function with the C-coded implementation
+as its default method.
+
+This extension happens automatically if a method is defined (by a
address@hidden call) for a variable whose current value is a
+primitive. But it can also be forced by calling
address@hidden
+
address@hidden {primitive procedure} enable-primitive-generic! primitive
+Force the creation of a generic function definition for
address@hidden
address@hidden deffn
+
+Once the generic function definition for a primitive has been created,
+it can be retrieved using @code{primitive-generic-generic}.
+
address@hidden {primitive procedure} primitive-generic-generic primitive
+Return the generic function definition of @var{primitive}.
+
address@hidden raises an error if @var{primitive}
+is not a primitive with generic capability.
@end deffn
address@hidden Merging Generics
address@hidden Merging Generics
+
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
@@ -835,11 +841,13 @@ 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.
address@hidden, what does the code using those packages end up with?
-This can be resolved automagically with the duplicates handler
address@hidden which gives the module system license to merge
-all generic functions sharing a common name:
address@hidden Guile Modules,,duplicate binding handlers} explains how
+this is resolved for conflicting bindings in general. For generics,
+there is a special duplicates handler, @code{merge-generics}, which
+tells the module system to merge generic functions with the same name.
+Here is an example:
@lisp
(define-module (math 2D-vectors)
@@ -856,155 +864,30 @@ all generic functions sharing a common name:
#:duplicates merge-generics)
@end lisp
-The generic function @code{x} in @code{(my-module)} will now share
-methods with @code{x} in both imported modules.
-
-There will, in fact, now be three distinct generic functions named
address@hidden: @code{x} in @code{(2D-vectors)}, @code{x} in
address@hidden(3D-vectors)}, and @code{x} in @code{(my-module)}. The last
-function will be an @code{<extended-generic>}, extending the previous
-two functions.
-
-Let's call the imported generic functions the "ancestor functions".
-The generic function @code{x} in @code{(my-module)} is, in turn, a
-"descendant function" of the imported functions, extending its
-ancestors.
-
-For any generic function G, the applicable methods are selected from
-the union of the methods of the descendant functions, the methods of G
-itself and the methods of the ancestor functions.
-
-This, ancestor functions share methods with their descendants and vice
-versa. This implies that @code{x} in @code{(math 2D-vectors)} will
-share the methods of @code{x} in @code{(my-module)} and vice versa,
-while @code{x} in @code{(math 2D-vectors)} doesn't share the methods
-of @code{x} in @code{(math 3D-vectors)}, thus preserving modularity.
-
-Sharing is dynamic, so that adding new methods to a descendant implies
-adding it to the ancestor.
-
-If duplicates checking is desired in the above example, the following
-form of the @code{#:duplicates} option can be used instead:
-
address@hidden
- #:duplicates (merge-generics check)
address@hidden lisp
-
address@hidden Generic Function Internals
address@hidden Generic Function Internals
-
address@hidden calls @code{ensure-generic} to upgrade a
-pre-existing procedure value, or @code{make} with metaclass
address@hidden<generic>} to create a new generic function.
-
address@hidden calls @code{ensure-accessor} to upgrade a
-pre-existing procedure value, or @code{make-accessor} to create a new
-accessor.
-
address@hidden procedure ensure-generic old-definition [name]
-Return a generic function with name @var{name}, if possible by using or
-upgrading @var{old-definition}. If unspecified, @var{name} defaults to
address@hidden
-
-If @var{old-definition} is already a generic function, it is returned
-unchanged.
-
-If @var{old-definition} is a Scheme procedure or procedure-with-setter,
address@hidden returns a new generic function that uses
address@hidden for its default procedure and setter.
-
-Otherwise @code{ensure-generic} returns a new generic function with no
-defaults and no methods.
address@hidden deffn
-
address@hidden procedure make-generic [name]
-Return a new generic function with name @code{(car @var{name})}. If
-unspecified, @var{name} defaults to @code{#f}.
address@hidden deffn
-
address@hidden calls @code{make} with metaclasses
address@hidden<generic>} and @code{<generic-with-setter>}, depending on the
-previous value of the variable that it is trying to upgrade.
-
address@hidden is a simple wrapper for @code{make} with metaclass
address@hidden<generic>}.
-
address@hidden procedure ensure-accessor proc [name]
-Return an accessor with name @var{name}, if possible by using or
-upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
-
-If @var{proc} is already an accessor, it is returned unchanged.
-
-If @var{proc} is a Scheme procedure, procedure-with-setter or generic
-function, @code{ensure-accessor} returns an accessor that reuses the
-reusable elements of @var{proc}.
-
-Otherwise @code{ensure-accessor} returns a new accessor with no defaults
-and no methods.
address@hidden deffn
-
address@hidden procedure make-accessor [name]
-Return a new accessor with name @code{(car @var{name})}. If
-unspecified, @var{name} defaults to @code{#f}.
address@hidden deffn
-
address@hidden calls @code{make} with
-metaclass @code{<generic-with-setter>}, as well as calls to
address@hidden, @code{make-accessor} and (tail recursively)
address@hidden
-
address@hidden calls @code{make} twice, first
-with metaclass @code{<generic>} to create a generic function for the
-setter, then with metaclass @code{<generic-with-setter>} to create the
-accessor, passing the setter generic function as the value of the
address@hidden:setter} keyword.
-
address@hidden Extending Guiles 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
-in conjunction with their normal C-coded implementation. For
-primitives that are extended in this way, the result from the user-
-or application-level point of view is that the extended primitive
-behaves exactly like a generic function with the C-coded implementation
-as its default method.
-
-The @code{generic-capability?} predicate should be used to determine
-whether a particular primitive is extensible in this way.
-
address@hidden {primitive procedure} generic-capability? primitive
-Return @code{#t} if @var{primitive} can be extended by giving it a
-generic function definition, otherwise @code{#f}.
address@hidden deffn
-
-Even when a primitive procedure is extensible like this, its generic
-function definition is not created until it is needed by a call to
address@hidden, or until the application explicitly requests it
-by calling @code{enable-primitive-generic!}.
-
address@hidden {primitive procedure} enable-primitive-generic! primitive
-Force the creation of a generic function definition for
address@hidden
address@hidden deffn
-
-Once the generic function definition for a primitive has been created,
-it can be retrieved using @code{primitive-generic-generic}.
-
address@hidden {primitive procedure} primitive-generic-generic primitive
-Return the generic function definition of @var{primitive}.
-
address@hidden raises an error if @var{primitive}
-is not a primitive with generic capability, or if its generic capability
-has not yet been enabled, whether implicitly (by @code{define-method})
-or explicitly (by @code{enable-primitive-generic!}).
address@hidden deffn
-
-Note that the distinction between, on the one hand, primitives with
-additional generic function definitions and, on the other hand, generic
-functions with a default method, may disappear when GOOPS is fully
-integrated into the core of Guile. Consequently, the
-procedures described in this section may disappear as well.
+The generic function @code{x} in @code{(my-module)} will now incorporate
+all of the methods of @code{x} from both imported modules.
+
+To be precise, there will now be three distinct generic functions named
address@hidden: @code{x} in @code{(math 2D-vectors)}, @code{x} in @code{(math
+3D-vectors)}, and @code{x} in @code{(my-module)}; and these functions
+share their methods in an interesting and dynamic way.
+
+To explain, let's call the imported generic functions (in @code{(math
+2D-vectors)} and @code{(math 3D-vectors)}) the @dfn{ancestors}, and the
+merged generic function (in @code{(my-module)}), the @dfn{descendant}.
+The general rule is that for any generic function G, the applicable
+methods are selected from the union of the methods of G's descendant
+functions, the methods of G itself and the methods of G's ancestor
+functions.
+
+Thus ancestor functions effectively share methods with their
+descendants, and vice versa. In the example above, @code{x} in
address@hidden(math 2D-vectors)} will share the methods of @code{x} in
address@hidden(my-module)} and vice address@hidden note that @code{x} in
address@hidden(math 2D-vectors)} doesn't share methods with @code{x} in
address@hidden(math 3D-vectors)}, so modularity is still preserved.} Sharing is
+dynamic, so adding another new method to a descendant implies adding it
+to that descendant's ancestors too.
@node Adding Methods to Generic Functions
@section Adding Methods to Generic Functions
@@ -1144,9 +1027,8 @@ Add method @var{method} to the generic function
@var{generic}.
@deffn method add-method! (proc <procedure>) (method <method>)
If @var{proc} is a procedure with generic capability (@pxref{Extending
-Guiles Primitives,, generic-capability?}), upgrade it to a
-primitive generic and add @var{method} to its generic function
-definition.
+Primitives,, generic-capability?}), upgrade it to a primitive generic
+and add @var{method} to its generic function definition.
@end deffn
@deffn method add-method! (pg <primitive-generic>) (method <method>)
@@ -1807,6 +1689,7 @@ GOOPS' power, by customizing the behaviour of GOOPS
itself.
* Customizing Instance Creation::
* Class Redefinition::
* Method Definition::
+* Generic Function Internals::
* Generic Function Invocation::
@end menu
@@ -2685,13 +2568,82 @@ a generic function (the most common case)
a procedure
@item
-a primitive generic (@pxref{Extending Guiles Primitives})
+a primitive generic (@pxref{Extending Primitives})
@end itemize
By defining further methods for @code{add-method!}, you can
theoretically handle adding methods to further types of target.
@end itemize
address@hidden Generic Function Internals
address@hidden Generic Function Internals
+
address@hidden calls @code{ensure-generic} to upgrade a
+pre-existing procedure value, or @code{make} with metaclass
address@hidden<generic>} to create a new generic function.
+
address@hidden calls @code{ensure-accessor} to upgrade a
+pre-existing procedure value, or @code{make-accessor} to create a new
+accessor.
+
address@hidden procedure ensure-generic old-definition [name]
+Return a generic function with name @var{name}, if possible by using or
+upgrading @var{old-definition}. If unspecified, @var{name} defaults to
address@hidden
+
+If @var{old-definition} is already a generic function, it is returned
+unchanged.
+
+If @var{old-definition} is a Scheme procedure or procedure-with-setter,
address@hidden returns a new generic function that uses
address@hidden for its default procedure and setter.
+
+Otherwise @code{ensure-generic} returns a new generic function with no
+defaults and no methods.
address@hidden deffn
+
address@hidden procedure make-generic [name]
+Return a new generic function with name @code{(car @var{name})}. If
+unspecified, @var{name} defaults to @code{#f}.
address@hidden deffn
+
address@hidden calls @code{make} with metaclasses
address@hidden<generic>} and @code{<generic-with-setter>}, depending on the
+previous value of the variable that it is trying to upgrade.
+
address@hidden is a simple wrapper for @code{make} with metaclass
address@hidden<generic>}.
+
address@hidden procedure ensure-accessor proc [name]
+Return an accessor with name @var{name}, if possible by using or
+upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
+
+If @var{proc} is already an accessor, it is returned unchanged.
+
+If @var{proc} is a Scheme procedure, procedure-with-setter or generic
+function, @code{ensure-accessor} returns an accessor that reuses the
+reusable elements of @var{proc}.
+
+Otherwise @code{ensure-accessor} returns a new accessor with no defaults
+and no methods.
address@hidden deffn
+
address@hidden procedure make-accessor [name]
+Return a new accessor with name @code{(car @var{name})}. If
+unspecified, @var{name} defaults to @code{#f}.
address@hidden deffn
+
address@hidden calls @code{make} with
+metaclass @code{<generic-with-setter>}, as well as calls to
address@hidden, @code{make-accessor} and (tail recursively)
address@hidden
+
address@hidden calls @code{make} twice, first
+with metaclass @code{<generic>} to create a generic function for the
+setter, then with metaclass @code{<generic-with-setter>} to create the
+accessor, passing the setter generic function as the value of the
address@hidden:setter} keyword.
+
@node Generic Function Invocation
@subsection Generic Function Invocation
hooks/post-receive
--
GNU Guile
| [Prev in Thread] | Current Thread | [Next in Thread] |