2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2008, 2009
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
18 @goops{} is the object oriented extension to @guile{}. Its
19 implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
20 version 1.3 of Gregor Kiczales' @cite{Tiny-Clos}. It is very close in
21 spirit to CLOS, the Common Lisp Object System, but is adapted for the
24 @goops{} is a full object oriented system, with classes, objects,
25 multiple inheritance, and generic functions with multi-method
26 dispatch. Furthermore its implementation relies on a meta object
27 protocol --- which means that @goops{}'s core operations are themselves
28 defined as methods on relevant classes, and can be customised by
29 overriding or redefining those methods.
31 To start using @goops{} you first need to import the @code{(oop goops)}
32 module. You can do this at the Guile REPL by evaluating:
35 (use-modules (oop goops))
44 * Slot Description Example::
45 * Methods and Generic Functions::
48 * GOOPS Object Miscellany::
50 * Redefining a Class::
51 * Changing the Class of an Instance::
52 * GOOPS Error Handling::
53 * The Metaobject Protocol::
56 @node Copyright Notice
57 @section Copyright Notice
59 The material in this chapter is partly derived from the STk Reference
60 Manual written by Erick Gallesio, whose copyright notice is as follows.
62 Copyright © 1993-1999 Erick Gallesio - I3S-CNRS/ESSI <eg@@unice.fr>
63 Permission to use, copy, modify, distribute,and license this
64 software and its documentation for any purpose is hereby granted,
65 provided that existing copyright notices are retained in all
66 copies and that this notice is included verbatim in any
67 distributions. No written agreement, license, or royalty fee is
68 required for any of the authorized uses.
69 This software is provided ``AS IS'' without express or implied
72 The material has been adapted for use in Guile, with the author's
76 @node Class Definition
77 @section Class Definition
79 A new class is defined with the @code{define-class} syntax:
84 (define-class @var{class} (@var{superclass} @dots{})
85 @var{slot-description} @dots{}
86 @var{class-option} @dots{})
89 @var{class} is the class being defined. The list of @var{superclass}es
90 specifies which existing classes, if any, to inherit slots and
91 properties from. @dfn{Slots} hold per-instance@footnote{Usually --- but
92 see also the @code{#:allocation} slot option.} data, for instances of
93 that class --- like ``fields'' or ``member variables'' in other object
94 oriented systems. Each @var{slot-description} gives the name of a slot
95 and optionally some ``properties'' of this slot; for example its initial
96 value, the name of a function which will access its value, and so on.
97 Slot descriptions and inheritance are discussed more below. For class
98 options, see @ref{Class Options}.
101 @deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
102 Define a class called @var{name} that inherits from @var{super}s, with
103 direct slots defined by @var{slot-definition}s and class options
104 @var{options}. The newly created class is bound to the variable name
105 @var{name} in the current environment.
107 Each @var{slot-definition} is either a symbol that names the slot or a
111 (@var{slot-name-symbol} . @var{slot-options})
114 where @var{slot-name-symbol} is a symbol and @var{slot-options} is a
115 list with an even number of elements. The even-numbered elements of
116 @var{slot-options} (counting from zero) are slot option keywords; the
117 odd-numbered elements are the corresponding values for those keywords.
119 @var{options} is a similarly structured list containing class option
120 keywords and corresponding values.
123 As an example, let us define a type for representing a complex number
124 in terms of two real numbers.@footnote{Of course Guile already
125 provides complex numbers, and @code{<complex>} is in fact a predefined
126 class in GOOPS; but the definition here is still useful as an
127 example.} This can be done with the following class definition:
130 (define-class <my-complex> (<number>)
134 This binds the variable @code{<my-complex>} to a new class whose
135 instances will contain two slots. These slots are called @code{r} and
136 @code{i} and will hold the real and imaginary parts of a complex
137 number. Note that this class inherits from @code{<number>}, which is a
138 predefined class.@footnote{@code{<number>} is the direct superclass of
139 the predefined class @code{<complex>}; @code{<complex>} is the
140 superclass of @code{<real>}, and @code{<real>} is the superclass of
143 The possible slot and class options are described in the following
147 @node Instance Creation
148 @section Instance Creation and Slot Access
150 An instance (or object) of a defined class can be created with
151 @code{make}. @code{make} takes one mandatory parameter, which is the
152 class of the instance to create, and a list of optional arguments that
153 will be used to initialize the slots of the new instance. For instance
159 (define c (make <my-complex>))
163 creates a new @code{<my-complex>} object and binds it to the Scheme
167 @deffnx method make (class <class>) . initargs
168 Create and return a new instance of class @var{class}, initialized using
171 In theory, @var{initargs} can have any structure that is understood by
172 whatever methods get applied when the @code{initialize} generic function
173 is applied to the newly allocated instance.
175 In practice, specialized @code{initialize} methods would normally call
176 @code{(next-method)}, and so eventually the standard GOOPS
177 @code{initialize} methods are applied. These methods expect
178 @var{initargs} to be a list with an even number of elements, where
179 even-numbered elements (counting from zero) are keywords and
180 odd-numbered elements are the corresponding values.
182 GOOPS processes initialization argument keywords automatically for slots
183 whose definition includes the @code{#:init-keyword} option (@pxref{Slot
184 Options,, init-keyword}). Other keyword value pairs can only be
185 processed by an @code{initialize} method that is specialized for the new
186 instance's class. Any unprocessed keyword value pairs are ignored.
189 @deffn generic make-instance
190 @deffnx method make-instance (class <class>) . initargs
191 @code{make-instance} is an alias for @code{make}.
194 The slots of the new complex number can be accessed using
195 @code{slot-ref} and @code{slot-set!}. @code{slot-set!} sets the value
196 of an object slot and @code{slot-ref} retrieves it.
204 (slot-ref c 'r) @result{} 10
205 (slot-ref c 'i) @result{} 3
209 The @code{(oop goops describe)} module provides a @code{describe}
210 function that is useful for seeing all the slots of an object; it prints
211 the slots and their values to standard output.
216 #<<my-complex> 401d8638> is an instance of class <my-complex>
224 @section Slot Options
226 When specifying a slot (in a @code{(define-class @dots{})} form),
227 various options can be specified in addition to the slot's name. Each
228 option is specified by a keyword. The list of possible keywords is
231 @deffn {slot option} #:init-value init-value
232 @deffnx {slot option} #:init-form init-form
233 @deffnx {slot option} #:init-thunk init-thunk
234 @deffnx {slot option} #:init-keyword init-keyword
235 These options provide various ways to specify how to initialize the
236 slot's value at instance creation time.
237 @cindex default slot value
239 @var{init-value} specifies a fixed initial slot value (shared across all
240 new instances of the class).
242 @var{init-thunk} specifies a thunk that will provide a default value for
243 the slot. The thunk is called when a new instance is created and should
244 return the desired initial slot value.
246 @var{init-form} specifies a form that, when evaluated, will return
247 an initial value for the slot. The form is evaluated each time that
248 an instance of the class is created, in the lexical environment of the
249 containing @code{define-class} expression.
251 @var{init-keyword} specifies a keyword that can be used to pass an
252 initial slot value to @code{make} when creating a new instance.
254 Note that, since an @code{init-value} value is shared across all
255 instances of a class, you should only use it when the initial value is
256 an immutable value, like a constant. If you want to initialize a slot
257 with a fresh, independently mutable value, you should use
258 @code{init-thunk} or @code{init-form} instead. Consider the following
262 (define-class <chbouib> ()
263 (hashtab #:init-value (make-hash-table)))
267 Here only one hash table is created and all instances of
268 @code{<chbouib>} have their @code{hashtab} slot refer to it. In order
269 to have each instance of @code{<chbouib>} refer to a new hash table, you
270 should instead write:
273 (define-class <chbouib> ()
274 (hashtab #:init-thunk make-hash-table))
281 (define-class <chbouib> ()
282 (hashtab #:init-form (make-hash-table)))
285 If more than one of these options is specified for the same slot, the
286 order of precedence, highest first is
290 @code{#:init-keyword}, if @var{init-keyword} is present in the options
291 passed to @code{make}
294 @code{#:init-thunk}, @code{#:init-form} or @code{#:init-value}.
297 If the slot definition contains more than one initialization option of
298 the same precedence, the later ones are ignored. If a slot is not
299 initialized at all, its value is unbound.
301 In general, slots that are shared between more than one instance are
302 only initialized at new instance creation time if the slot value is
303 unbound at that time. However, if the new instance creation specifies
304 a valid init keyword and value for a shared slot, the slot is
305 re-initialized regardless of its previous value.
307 Note, however, that the power of GOOPS' metaobject protocol means that
308 everything written here may be customized or overridden for particular
309 classes! The slot initializations described here are performed by the least
310 specialized method of the generic function @code{initialize}, whose
314 (define-method (initialize (object <object>) initargs) ...)
317 The initialization of instances of any given class can be customized by
318 defining a @code{initialize} method that is specialized for that class,
319 and the author of the specialized method may decide to call
320 @code{next-method} - which will result in a call to the next less
321 specialized @code{initialize} method - at any point within the
322 specialized code, or maybe not at all. In general, therefore, the
323 initialization mechanisms described here may be modified or overridden by
324 more specialized code, or may not be supported at all for particular
328 @deffn {slot option} #:getter getter
329 @deffnx {slot option} #:setter setter
330 @deffnx {slot option} #:accessor accessor
331 Given an object @var{obj} with slots named @code{foo} and @code{bar}, it
332 is always possible to read and write those slots by calling
333 @code{slot-ref} and @code{slot-set!} with the relevant slot name; for
337 (slot-ref @var{obj} 'foo)
338 (slot-set! @var{obj} 'bar 25)
341 The @code{#:getter}, @code{#:setter} and @code{#:accessor} options, if
342 present, tell GOOPS to create generic function and method definitions
343 that can be used to get and set the slot value more conveniently.
344 @var{getter} specifies a generic function to which GOOPS will add a
345 method for getting the slot value. @var{setter} specifies a generic
346 function to which GOOPS will add a method for setting the slot value.
347 @var{accessor} specifies an accessor to which GOOPS will add methods for
348 both getting and setting the slot value.
350 So if a class includes a slot definition like this:
353 (c #:getter get-count #:setter set-count #:accessor count)
356 GOOPS defines generic function methods such that the slot value can be
357 referenced using either the getter or the accessor -
360 (let ((current-count (get-count obj))) @dots{})
361 (let ((current-count (count obj))) @dots{})
364 - and set using either the setter or the accessor -
367 (set-count obj (+ 1 current-count))
368 (set! (count obj) (+ 1 current-count))
375 with an accessor, the slot value is set using the generalized
379 in practice, it is unusual for a slot to use all three of these options:
380 read-only, write-only and read-write slots would typically use only
381 @code{#:getter}, @code{#:setter} and @code{#:accessor} options
385 The binding of the specified names is done in the environment of the
386 @code{define-class} expression. If the names are already bound (in that
387 environment) to values that cannot be upgraded to generic functions,
388 those values are overwritten when the @code{define-class} expression is
389 evaluated. For more detail, see @ref{Generic Function Internals,,
393 @deffn {slot option} #:allocation allocation
394 The @code{#:allocation} option tells GOOPS how to allocate storage for
395 the slot. Possible values for @var{allocation} are
398 @item @code{#:instance}
401 Indicates that GOOPS should create separate storage for this slot in
402 each new instance of the containing class (and its subclasses). This is
408 Indicates that GOOPS should create storage for this slot that is shared
409 by all instances of the containing class (and its subclasses). In other
410 words, a slot in class @var{C} with allocation @code{#:class} is shared
411 by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
412 This permits defining a kind of global variable which can be accessed
413 only by (in)direct instances of the class which defines the slot.
415 @item @code{#:each-subclass}
417 @findex #:each-subclass
418 Indicates that GOOPS should create storage for this slot that is shared
419 by all @emph{direct} instances of the containing class, and that
420 whenever a subclass of the containing class is defined, GOOPS should
421 create a new storage for the slot that is shared by all @emph{direct}
422 instances of the subclass. In other words, a slot with allocation
423 @code{#:each-subclass} is shared by all instances with the same
426 @item @code{#:virtual}
431 Indicates that GOOPS should not allocate storage for this slot. The
432 slot definition must also include the @code{#:slot-ref} and
433 @code{#:slot-set!} options to specify how to reference and set the value
434 for this slot. See the example below.
437 Slot allocation options are processed when defining a new class by the
438 generic function @code{compute-get-n-set}, which is specialized by the
439 class's metaclass. Hence new types of slot allocation can be
440 implemented by defining a new metaclass and a method for
441 @code{compute-get-n-set} that is specialized for the new metaclass. For
442 an example of how to do this, see @ref{Customizing Class Definition}.
445 @deffn {slot option} #:slot-ref getter
446 @deffnx {slot option} #:slot-set! setter
447 The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
448 if the slot allocation is @code{#:virtual}, and are ignored otherwise.
450 @var{getter} should be a closure taking a single @var{instance} parameter
451 that returns the current slot value. @var{setter} should be a closure
452 taking two parameters - @var{instance} and @var{new-val} - that sets the
453 slot value to @var{new-val}.
456 @node Slot Description Example
457 @section Illustrating Slot Description
459 To illustrate slot description, we can redefine the @code{<my-complex>}
460 class seen before. A definition could be:
463 (define-class <my-complex> (<number>)
464 (r #:init-value 0 #:getter get-r #:setter set-r! #:init-keyword #:r)
465 (i #:init-value 0 #:getter get-i #:setter set-i! #:init-keyword #:i))
469 With this definition, the @code{r} and @code{i} slots are set to 0 by
470 default, and can be initialised to other values by calling @code{make}
471 with the @code{#:r} and @code{#:i} keywords. Also the generic functions
472 @code{get-r}, @code{set-r!}, @code{get-i} and @code{set-i!} are
473 automatically defined to read and write the slots.
476 (define c1 (make <my-complex> #:r 1 #:i 2))
477 (get-r c1) @result{} 1
479 (get-r c1) @result{} 12
480 (define c2 (make <my-complex> #:r 2))
481 (get-r c2) @result{} 2
482 (get-i c2) @result{} 0
485 Accessors can both read and write a slot. So, another definition of the
486 @code{<my-complex>} class, using the @code{#:accessor} option, could be:
490 (define-class <my-complex> (<number>)
491 (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
492 (i #:init-value 0 #:accessor imag-part #:init-keyword #:i))
496 With this definition, the @code{r} slot can be read with:
503 (set! (real-part c) new-value)
506 Suppose now that we want to manipulate complex numbers with both
507 rectangular and polar coordinates. One solution could be to have a
508 definition of complex numbers which uses one particular representation
509 and some conversion functions to pass from one representation to the
510 other. A better solution is to use virtual slots, like this:
513 (define-class <my-complex> (<number>)
514 ;; True slots use rectangular coordinates
515 (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
516 (i #:init-value 0 #:accessor imag-part #:init-keyword #:i)
517 ;; Virtual slots access do the conversion
518 (m #:accessor magnitude #:init-keyword #:magn
519 #:allocation #:virtual
520 #:slot-ref (lambda (o)
521 (let ((r (slot-ref o 'r)) (i (slot-ref o 'i)))
522 (sqrt (+ (* r r) (* i i)))))
523 #:slot-set! (lambda (o m)
524 (let ((a (slot-ref o 'a)))
525 (slot-set! o 'r (* m (cos a)))
526 (slot-set! o 'i (* m (sin a))))))
527 (a #:accessor angle #:init-keyword #:angle
528 #:allocation #:virtual
529 #:slot-ref (lambda (o)
530 (atan (slot-ref o 'i) (slot-ref o 'r)))
531 #:slot-set! (lambda(o a)
532 (let ((m (slot-ref o 'm)))
533 (slot-set! o 'r (* m (cos a)))
534 (slot-set! o 'i (* m (sin a)))))))
538 In this class definition, the magniture @code{m} and angle @code{a}
539 slots are virtual, and are calculated, when referenced, from the normal
540 (i.e. @code{#:allocation #:instance}) slots @code{r} and @code{i}, by
541 calling the function defined in the relevant @code{#:slot-ref} option.
542 Correspondingly, writing @code{m} or @code{a} leads to calling the
543 function defined in the @code{#:slot-set!} option. Thus the
553 permits to set the angle of the @code{c} complex number.
556 (define c (make <my-complex> #:r 12 #:i 20))
557 (real-part c) @result{} 12
558 (angle c) @result{} 1.03037682652431
560 (set! (real-part c) 1)
563 #<<my-complex> 401e9b58> is an instance of class <my-complex>
571 Since initialization keywords have been defined for the four slots, we
572 can now define the standard Scheme primitives @code{make-rectangular}
573 and @code{make-polar}.
576 (define make-rectangular
577 (lambda (x y) (make <my-complex> #:r x #:i y)))
580 (lambda (x y) (make <my-complex> #:magn x #:angle y)))
584 @node Methods and Generic Functions
585 @section Methods and Generic Functions
587 A GOOPS method is like a Scheme procedure except that it is specialized
588 for a particular set of argument classes, and will only be used when the
589 actual arguments in a call match the classes in the method definition.
592 (define-method (+ (x <string>) (y <string>))
595 (+ "abc" "de") @result{} "abcde"
598 A method is not formally associated with any single class (as it is in
599 many other object oriented languages), because a method can be
600 specialized for a combination of several classes. If you've studied
601 object orientation in non-Lispy languages, you may remember discussions
602 such as whether a method to stretch a graphical image around a surface
603 should be a method of the image class, with a surface as a parameter, or
604 a method of the surface class, with an image as a parameter. In GOOPS
608 (define-method (stretch (im <image>) (sf <surface>))
613 and the question of which class the method is more associated with does
616 There can simultaneously be several methods with the same name but
617 different sets of specializing argument classes; for example:
620 (define-method (+ (x <string>) (y <string)) ...)
621 (define-method (+ (x <matrix>) (y <matrix>)) ...)
622 (define-method (+ (f <fish>) (b <bicyle>)) ...)
623 (define-method (+ (a <foo>) (b <bar>) (c <baz>)) ...)
627 A generic function is a container for the set of such methods that a
628 program intends to use.
630 If you look at a program's source code, and see @code{(+ x y)} somewhere
631 in it, conceptually what is happening is that the program at that point
632 calls a generic function (in this case, the generic function bound to
633 the identifier @code{+}). When that happens, Guile works out which of
634 the generic function's methods is the most appropriate for the arguments
635 that the function is being called with; then it evaluates the method's
636 code with the arguments as formal parameters. This happens every time
637 that a generic function call is evaluated --- it isn't assumed that a
638 given source code call will end up invoking the same method every time.
640 Defining an identifier as a generic function is done with the
641 @code{define-generic} macro. Definition of a new method is done with
642 the @code{define-method} macro. Note that @code{define-method}
643 automatically does a @code{define-generic} if the identifier concerned
644 is not already a generic function, so often an explicit
645 @code{define-generic} call is not needed.
646 @findex define-generic
647 @findex define-method
649 @deffn syntax define-generic symbol
650 Create a generic function with name @var{symbol} and bind it to the
651 variable @var{symbol}. If @var{symbol} was previously bound to a Scheme
652 procedure (or procedure-with-setter), the old procedure (and setter) is
653 incorporated into the new generic function as its default procedure (and
654 setter). Any other previous value, including an existing generic
655 function, is discarded and replaced by a new, empty generic function.
658 @deffn syntax define-method (generic parameter @dots{}) . body
659 Define a method for the generic function or accessor @var{generic} with
660 parameters @var{parameter}s and body @var{body}.
662 @var{generic} is a generic function. If @var{generic} is a variable
663 which is not yet bound to a generic function object, the expansion of
664 @code{define-method} will include a call to @code{define-generic}. If
665 @var{generic} is @code{(setter @var{generic-with-setter})}, where
666 @var{generic-with-setter} is a variable which is not yet bound to a
667 generic-with-setter object, the expansion will include a call to
668 @code{define-accessor}.
670 Each @var{parameter} must be either a symbol or a two-element list
671 @code{(@var{symbol} @var{class})}. The symbols refer to variables in
672 the @var{body} that will be bound to the parameters supplied by the
673 caller when calling this method. The @var{class}es, if present,
674 specify the possible combinations of parameters to which this method
677 @var{body} is the body of the method definition.
680 @code{define-method} expressions look a little like Scheme procedure
681 definitions of the form
684 (define (name formals @dots{}) . body)
687 The important difference is that each formal parameter, apart from the
688 possible ``rest'' argument, can be qualified by a class name:
689 @code{@var{formal}} becomes @code{(@var{formal} @var{class})}. The
690 meaning of this qualification is that the method being defined
691 will only be applicable in a particular generic function invocation if
692 the corresponding argument is an instance of @code{@var{class}} (or one of
693 its subclasses). If more than one of the formal parameters is qualified
694 in this way, then the method will only be applicable if each of the
695 corresponding arguments is an instance of its respective qualifying class.
697 Note that unqualified formal parameters act as though they are qualified
698 by the class @code{<top>}, which GOOPS uses to mean the superclass of
699 all valid Scheme types, including both primitive types and GOOPS classes.
701 For example, if a generic function method is defined with
702 @var{parameter}s @code{(s1 <square>)} and @code{(n <number>)}, that
703 method is only applicable to invocations of its generic function that
704 have two parameters where the first parameter is an instance of the
705 @code{<square>} class and the second parameter is a number.
709 * Extending Primitives::
712 * Generic Function and Method Examples::
713 * Handling Invocation Errors::
718 @subsection Accessors
720 An accessor is a generic function that can also be used with the
721 generalized @code{set!} syntax (@pxref{Procedures with Setters}). Guile
722 will handle a call like
725 (set! (@code{accessor} @code{args}@dots{}) @code{value})
729 by calling the most specialized method of @code{accessor} that matches
730 the classes of @code{args} and @code{value}. @code{define-accessor} is
731 used to bind an identifier to an accessor.
733 @deffn syntax define-accessor symbol
734 Create an accessor with name @var{symbol} and bind it to the variable
735 @var{symbol}. If @var{symbol} was previously bound to a Scheme
736 procedure (or procedure-with-setter), the old procedure (and setter) is
737 incorporated into the new accessor as its default procedure (and
738 setter). Any other previous value, including an existing generic
739 function or accessor, is discarded and replaced by a new, empty
744 @node Extending Primitives
745 @subsection Extending Primitives
747 Many of Guile's primitive procedures can be extended by giving them a
748 generic function definition that operates in conjunction with their
749 normal C-coded implementation. When a primitive is extended in this
750 way, it behaves like a generic function with the C-coded implementation
751 as its default method.
753 This extension happens automatically if a method is defined (by a
754 @code{define-method} call) for a variable whose current value is a
755 primitive. But it can also be forced by calling
756 @code{enable-primitive-generic!}.
758 @deffn {primitive procedure} enable-primitive-generic! primitive
759 Force the creation of a generic function definition for
763 Once the generic function definition for a primitive has been created,
764 it can be retrieved using @code{primitive-generic-generic}.
766 @deffn {primitive procedure} primitive-generic-generic primitive
767 Return the generic function definition of @var{primitive}.
769 @code{primitive-generic-generic} raises an error if @var{primitive}
770 is not a primitive with generic capability.
773 @node Merging Generics
774 @subsection Merging Generics
776 GOOPS generic functions and accessors often have short, generic names.
777 For example, if a vector package provides an accessor for the X
778 coordinate of a vector, that accessor may just be called @code{x}. It
779 doesn't need to be called, for example, @code{vector:x}, because
780 GOOPS will work out, when it sees code like @code{(x @var{obj})}, that
781 the vector-specific method of @code{x} should be called if @var{obj} is
784 That raises the question, though, of what happens when different
785 packages define a generic function with the same name. Suppose we work
786 with a graphical package which needs to use two independent vector
787 packages for 2D and 3D vectors respectively. If both packages export
788 @code{x}, what does the code using those packages end up with?
790 @ref{Creating Guile Modules,,duplicate binding handlers} explains how
791 this is resolved for conflicting bindings in general. For generics,
792 there is a special duplicates handler, @code{merge-generics}, which
793 tells the module system to merge generic functions with the same name.
797 (define-module (math 2D-vectors)
798 #:use-module (oop goops)
801 (define-module (math 3D-vectors)
802 #:use-module (oop goops)
803 #:export (x y z ...))
805 (define-module (my-module)
806 #:use-module (math 2D-vectors)
807 #:use-module (math 3D-vectors)
808 #:duplicates merge-generics)
811 The generic function @code{x} in @code{(my-module)} will now incorporate
812 all of the methods of @code{x} from both imported modules.
814 To be precise, there will now be three distinct generic functions named
815 @code{x}: @code{x} in @code{(math 2D-vectors)}, @code{x} in @code{(math
816 3D-vectors)}, and @code{x} in @code{(my-module)}; and these functions
817 share their methods in an interesting and dynamic way.
819 To explain, let's call the imported generic functions (in @code{(math
820 2D-vectors)} and @code{(math 3D-vectors)}) the @dfn{ancestors}, and the
821 merged generic function (in @code{(my-module)}), the @dfn{descendant}.
822 The general rule is that for any generic function G, the applicable
823 methods are selected from the union of the methods of G's descendant
824 functions, the methods of G itself and the methods of G's ancestor
827 Thus ancestor functions effectively share methods with their
828 descendants, and vice versa. In the example above, @code{x} in
829 @code{(math 2D-vectors)} will share the methods of @code{x} in
830 @code{(my-module)} and vice versa.@footnote{But note that @code{x} in
831 @code{(math 2D-vectors)} doesn't share methods with @code{x} in
832 @code{(math 3D-vectors)}, so modularity is still preserved.} Sharing is
833 dynamic, so adding another new method to a descendant implies adding it
834 to that descendant's ancestors too.
837 @subsection Next-method
839 When you call a generic function, with a particular set of arguments,
840 GOOPS builds a list of all the methods that are applicable to those
841 arguments and orders them by how closely the method definitions match
842 the actual argument types. It then calls the method at the top of this
843 list. If the selected method's code wants to call on to the next method
844 in this list, it can do so by using @code{next-method}.
847 (define-method (Test (a <integer>)) (cons 'integer (next-method)))
848 (define-method (Test (a <number>)) (cons 'number (next-method)))
849 (define-method (Test a) (list 'top))
852 With these definitions,
855 (Test 1) @result{} (integer number top)
856 (Test 1.0) @result{} (number top)
857 (Test #t) @result{} (top)
860 @code{next-method} is always called as just @code{(next-method)}. The
861 arguments for the next method call are always implicit, and always the
862 same as for the original method call.
864 If you want to call on to a method with the same name but with a
865 different set of arguments (as you might with overloaded methods in C++,
866 for example), you do not use @code{next-method}, but instead simply
867 write the new call as usual:
870 (define-method (Test (a <number>) min max)
871 (if (and (>= a min) (<= a max))
872 (display "Number is in range\n"))
882 (You should be careful in this case that the @code{Test} calls do not
883 lead to an infinite recursion, but this consideration is just the same
884 as in Scheme code in general.)
886 @node Generic Function and Method Examples
887 @subsection Generic Function and Method Examples
889 Consider the following definitions:
893 (define-method (G (a <integer>) b) 'integer)
894 (define-method (G (a <real>) b) 'real)
895 (define-method (G a b) 'top)
898 The @code{define-generic} call defines @var{G} as a generic function.
899 The three next lines define methods for @var{G}. Each method uses a
900 sequence of @dfn{parameter specializers} that specify when the given
901 method is applicable. A specializer permits to indicate the class a
902 parameter must belong to (directly or indirectly) to be applicable. If
903 no specializer is given, the system defaults it to @code{<top>}. Thus,
904 the first method definition is equivalent to
906 @cindex parameter specializers
908 (define-method (G (a <integer>) (b <top>)) 'integer)
911 Now, let's look at some possible calls to the generic function @var{G}:
914 (G 2 3) @result{} integer
915 (G 2 #t) @result{} integer
916 (G 1.2 'a) @result{} real
917 @c (G #3 'a) @result{} real @c was {\sharpsign}
918 (G #t #f) @result{} top
919 (G 1 2 3) @result{} error (since no method exists for 3 parameters)
922 The methods above use only one specializer per parameter list. But in
923 general, any or all of a method's parameters may be specialized.
924 Suppose we define now:
927 (define-method (G (a <integer>) (b <number>)) 'integer-number)
928 (define-method (G (a <integer>) (b <real>)) 'integer-real)
929 (define-method (G (a <integer>) (b <integer>)) 'integer-integer)
930 (define-method (G a (b <number>)) 'top-number)
933 @noindent With these definitions:
936 (G 1 2) @result{} integer-integer
937 (G 1 1.0) @result{} integer-real
938 (G 1 #t) @result{} integer
939 (G 'a 1) @result{} top-number
942 As a further example we shall continue to define operations on the
943 @code{<my-complex>} class. Suppose that we want to use it to implement
944 complex numbers completely. For instance a definition for the addition
945 of two complex numbers could be
948 (define-method (new-+ (a <my-complex>) (b <my-complex>))
949 (make-rectangular (+ (real-part a) (real-part b))
950 (+ (imag-part a) (imag-part b))))
953 To be sure that the @code{+} used in the method @code{new-+} is the
954 standard addition we can do:
957 (define-generic new-+)
960 (define-method (new-+ (a <my-complex>) (b <my-complex>))
961 (make-rectangular (+ (real-part a) (real-part b))
962 (+ (imag-part a) (imag-part b)))))
965 The @code{define-generic} ensures here that @code{new-+} will be defined
966 in the global environment. Once this is done, we can add methods to the
967 generic function @code{new-+} which make a closure on the @code{+}
968 symbol. A complete writing of the @code{new-+} methods is shown in
971 @float Figure,fig:newplus
973 (define-generic new-+)
977 (define-method (new-+ (a <real>) (b <real>)) (+ a b))
979 (define-method (new-+ (a <real>) (b <my-complex>))
980 (make-rectangular (+ a (real-part b)) (imag-part b)))
982 (define-method (new-+ (a <my-complex>) (b <real>))
983 (make-rectangular (+ (real-part a) b) (imag-part a)))
985 (define-method (new-+ (a <my-complex>) (b <my-complex>))
986 (make-rectangular (+ (real-part a) (real-part b))
987 (+ (imag-part a) (imag-part b))))
989 (define-method (new-+ (a <number>)) a)
991 (define-method (new-+) 0)
993 (define-method (new-+ . args)
995 (apply new-+ (cdr args)))))
1000 @caption{Extending @code{+} to handle complex numbers}
1003 We take advantage here of the fact that generic function are not obliged
1004 to have a fixed number of parameters. The four first methods implement
1005 dyadic addition. The fifth method says that the addition of a single
1006 element is this element itself. The sixth method says that using the
1007 addition with no parameter always return 0 (as is also true for the
1008 primitive @code{+}). The last method takes an arbitrary number of
1009 parameters@footnote{The parameter list for a @code{define-method}
1010 follows the conventions used for Scheme procedures. In particular it can
1011 use the dot notation or a symbol to denote an arbitrary number of
1012 parameters}. This method acts as a kind of @code{reduce}: it calls the
1013 dyadic addition on the @emph{car} of the list and on the result of
1014 applying it on its rest. To finish, the @code{set!} permits to redefine
1015 the @code{+} symbol to our extended addition.
1017 To conclude our implementation (integration?) of complex numbers, we
1018 could redefine standard Scheme predicates in the following manner:
1021 (define-method (complex? c <my-complex>) #t)
1022 (define-method (complex? c) #f)
1024 (define-method (number? n <number>) #t)
1025 (define-method (number? n) #f)
1029 Standard primitives in which complex numbers are involved could also be
1030 redefined in the same manner.
1033 @node Handling Invocation Errors
1034 @subsection Handling Invocation Errors
1036 If a generic function is invoked with a combination of parameters for
1037 which there is no applicable method, GOOPS raises an error.
1039 @deffn generic no-method
1040 @deffnx method no-method (gf <generic>) args
1041 When an application invokes a generic function, and no methods at all
1042 have been defined for that generic function, GOOPS calls the
1043 @code{no-method} generic function. The default method calls
1044 @code{goops-error} with an appropriate message.
1047 @deffn generic no-applicable-method
1048 @deffnx method no-applicable-method (gf <generic>) args
1049 When an application applies a generic function to a set of arguments,
1050 and no methods have been defined for those argument types, GOOPS calls
1051 the @code{no-applicable-method} generic function. The default method
1052 calls @code{goops-error} with an appropriate message.
1055 @deffn generic no-next-method
1056 @deffnx method no-next-method (gf <generic>) args
1057 When a generic function method calls @code{(next-method)} to invoke the
1058 next less specialized method for that generic function, and no less
1059 specialized methods have been defined for the current generic function
1060 arguments, GOOPS calls the @code{no-next-method} generic function. The
1061 default method calls @code{goops-error} with an appropriate message.
1066 @section Inheritance
1068 Here are some class definitions to help illustrate inheritance:
1071 (define-class A () a)
1072 (define-class B () b)
1073 (define-class C () c)
1074 (define-class D (A B) d a)
1075 (define-class E (A C) e c)
1076 (define-class F (D E) f)
1079 @code{A}, @code{B}, @code{C} have a null list of superclasses. In this
1080 case, the system will replace the null list by a list which only
1081 contains @code{<object>}, the root of all the classes defined by
1082 @code{define-class}. @code{D}, @code{E}, @code{F} use multiple
1083 inheritance: each class inherits from two previously defined classes.
1084 Those class definitions define a hierarchy which is shown in
1085 @ref{fig:hier}. In this figure, the class @code{<top>} is also shown;
1086 this class is the superclass of all Scheme objects. In particular,
1087 @code{<top>} is the superclass of all standard Scheme
1088 types.@footnote{@code{<complex>}, which is the direct subclass of
1089 @code{<number>} and the direct superclass of @code{<real>}, has been
1090 omitted in this figure.}
1092 @float Figure,fig:hier
1094 @center @image{hierarchy,5in}
1097 @verbatiminclude hierarchy.txt
1100 @caption{A class hierarchy.}
1103 When a class has superclasses, its set of slots is calculated by taking
1104 the union of its own slots and those of all its superclasses. Thus each
1105 instance of D will have three slots, @code{a}, @code{b} and
1106 @code{d}). The slots of a class can be discovered using the
1107 @code{class-slots} primitive. For instance,
1110 (class-slots A) @result{} ((a))
1111 (class-slots E) @result{} ((a) (e) (c))
1112 (class-slots F) @result{} ((e) (c) (b) (d) (a) (f))
1116 The ordering of the returned slots is not significant.
1119 * Class Precedence List::
1124 @node Class Precedence List
1125 @subsection Class Precedence List
1127 What happens when a class inherits from two or more superclasses that
1128 have a slot with the same name but incompatible definitions --- for
1129 example, different init values or slot allocations? We need a rule for
1130 deciding which slot definition the derived class ends up with, and this
1131 rule is provided by the class's @dfn{Class Precedence
1132 List}.@footnote{This section is an adaptation of material from Jeff
1133 Dalton's (J.Dalton@@ed.ac.uk) @cite{Brief introduction to CLOS}}
1135 Another problem arises when invoking a generic function, and there is
1136 more than one method that could apply to the call arguments. Here we
1137 need a way of ordering the applicable methods, so that Guile knows which
1138 method to use first, which to use next if that method calls
1139 @code{next-method}, and so on. One of the ingredients for this ordering
1140 is determining, for each given call argument, which of the specializing
1141 classes, from each applicable method's definition, is the most specific
1142 for that argument; and here again the class precedence list helps.
1144 If inheritance was restricted such that each class could only have one
1145 superclass --- which is known as @dfn{single} inheritance --- class
1146 ordering would be easy. The rule would be simply that a subclass is
1147 considered more specific than its superclass.
1149 With multiple inheritance, ordering is less obvious, and we have to
1150 impose an arbitrary rule to determine precedence. Suppose we have
1159 (define-class Z (X Y)
1164 Clearly the @code{Z} class is more specific than @code{X} or @code{Y},
1165 for instances of @code{Z}. But which is more specific out of @code{X}
1166 and @code{Y} --- and hence, for the definitions above, which
1167 @code{#:init-value} will take effect when creating an instance of
1168 @code{Z}? The rule in @goops{} is that the superclasses listed earlier
1169 are more specific than those listed later. Hence @code{X} is more
1170 specific than @code{Y}, and the @code{#:init-value} for slot @code{x} in
1171 instances of @code{Z} will be 1.
1173 Hence there is a linear ordering for a class and all its
1174 superclasses, from most specific to least specific, and this ordering is
1175 called the Class Precedence List of the class.
1177 In fact the rules above are not quite enough to always determine a
1178 unique order, but they give an idea of how things work. For example,
1179 for the @code{F} class shown in @ref{fig:hier}, the class precedence
1183 (f d e a c b <object> <top>)
1187 In cases where there is any ambiguity (like this one), it is a bad idea
1188 for programmers to rely on exactly what the order is. If the order for
1189 some superclasses is important, it can be expressed directly in the
1192 The precedence list of a class can be obtained by calling
1193 @code{class-precedence-list}. This function returns a ordered list
1194 whose first element is the most specific class. For instance:
1197 (class-precedence-list B) @result{} (#<<class> B 401b97c8>
1198 #<<class> <object> 401e4a10>
1199 #<<class> <top> 4026a9d8>)
1203 Or for a more immediately readable result:
1206 (map class-name (class-precedence-list B)) @result{} (B <object> <top>)
1210 @node Sorting Methods
1211 @subsection Sorting Methods
1213 Now, with the idea of the class precedence list, we can state precisely
1214 how the possible methods are sorted when more than one of the methods of
1215 a generic function are applicable to the call arguments.
1220 the applicable methods are sorted in order of specificity, and the most
1221 specific method is used first, then the next if that method calls
1222 @code{next-method}, and so on
1225 a method M1 is more specific than another method M2 if the first
1226 specializing class that differs, between the definitions of M1 and M2,
1227 is more specific, in M1's definition, for the corresponding actual call
1228 argument, than the specializing class in M2's definition
1231 a class C1 is more specific than another class C2, for an object of
1232 actual class C, if C1 comes before C2 in C's class precedence list.
1237 @section Introspection
1239 @dfn{Introspection}, or @dfn{reflection}, means being able to obtain
1240 information dynamically about GOOPS objects. It is perhaps best
1241 illustrated by considering an object oriented language that does not
1242 provide any introspection, namely C++.
1244 Nothing in C++ allows a running program to obtain answers to the following
1249 What are the data members of this object or class?
1252 What classes does this class inherit from?
1255 Is this method call virtual or non-virtual?
1258 If I invoke @code{Employee::adjustHoliday()}, what class contains the
1259 @code{adjustHoliday()} method that will be applied?
1262 In C++, answers to such questions can only be determined by looking at
1263 the source code, if you have access to it. GOOPS, on the other hand,
1264 includes procedures that allow answers to these questions --- or their
1265 GOOPS equivalents --- to be obtained dynamically, at run time.
1271 * Generic Functions::
1278 A GOOPS class is itself an instance of the @code{<class>} class, or of a
1279 subclass of @code{<class>}. The definition of the @code{<class>} class
1280 has slots that are used to describe the properties of a class, including
1283 @deffn {primitive procedure} class-name class
1284 Return the name of class @var{class}. This is the value of
1285 @var{class}'s @code{name} slot.
1288 @deffn {primitive procedure} class-direct-supers class
1289 Return a list containing the direct superclasses of @var{class}. This
1290 is the value of @var{class}'s @code{direct-supers} slot.
1293 @deffn {primitive procedure} class-direct-slots class
1294 Return a list containing the slot definitions of the direct slots of
1295 @var{class}. This is the value of @var{class}'s @code{direct-slots}
1299 @deffn {primitive procedure} class-direct-subclasses class
1300 Return a list containing the direct subclasses of @var{class}. This is
1301 the value of @var{class}'s @code{direct-subclasses} slot.
1304 @deffn {primitive procedure} class-direct-methods class
1305 Return a list of all the generic function methods that use @var{class}
1306 as a formal parameter specializer. This is the value of @var{class}'s
1307 @code{direct-methods} slot.
1310 @deffn {primitive procedure} class-precedence-list class
1311 Return the class precedence list for class @var{class} (@pxref{Class
1312 Precedence List}). This is the value of @var{class}'s @code{cpl} slot.
1315 @deffn {primitive procedure} class-slots class
1316 Return a list containing the slot definitions for all @var{class}'s
1317 slots, including any slots that are inherited from superclasses. This
1318 is the value of @var{class}'s @code{slots} slot.
1321 @deffn procedure class-subclasses class
1322 Return a list of all subclasses of @var{class}.
1325 @deffn procedure class-methods class
1326 Return a list of all methods that use @var{class} or a subclass of
1327 @var{class} as one of its formal parameter specializers.
1332 @subsection Instances
1334 @deffn {primitive procedure} class-of value
1335 Return the GOOPS class of any Scheme @var{value}.
1338 @deffn {primitive procedure} instance? object
1339 Return @code{#t} if @var{object} is any GOOPS instance, otherwise
1343 @deffn procedure is-a? object class
1344 Return @code{#t} if @var{object} is an instance of @var{class} or one of
1348 You can use the @code{is-a?} predicate to ask whether any given value
1349 belongs to a given class, or @code{class-of} to discover the class of a
1350 given value. Note that when GOOPS is loaded (by code using the
1351 @code{(oop goops)} module) built-in classes like @code{<string>},
1352 @code{<list>} and @code{<number>} are automatically set up,
1353 corresponding to all Guile Scheme types.
1356 (is-a? 2.3 <number>) @result{} #t
1357 (is-a? 2.3 <real>) @result{} #t
1358 (is-a? 2.3 <string>) @result{} #f
1359 (is-a? '("a" "b") <string>) @result{} #f
1360 (is-a? '("a" "b") <list>) @result{} #t
1361 (is-a? (car '("a" "b")) <string>) @result{} #t
1362 (is-a? <string> <class>) @result{} #t
1363 (is-a? <class> <string>) @result{} #f
1365 (class-of 2.3) @result{} #<<class> <real> 908c708>
1366 (class-of #(1 2 3)) @result{} #<<class> <vector> 908cd20>
1367 (class-of <string>) @result{} #<<class> <class> 8bd3e10>
1368 (class-of <class>) @result{} #<<class> <class> 8bd3e10>
1375 @deffn procedure class-slot-definition class slot-name
1376 Return the slot definition for the slot named @var{slot-name} in class
1377 @var{class}. @var{slot-name} should be a symbol.
1380 @deffn procedure slot-definition-name slot-def
1381 Extract and return the slot name from @var{slot-def}.
1384 @deffn procedure slot-definition-options slot-def
1385 Extract and return the slot options from @var{slot-def}.
1388 @deffn procedure slot-definition-allocation slot-def
1389 Extract and return the slot allocation option from @var{slot-def}. This
1390 is the value of the @code{#:allocation} keyword (@pxref{Slot Options,,
1391 allocation}), or @code{#:instance} if the @code{#:allocation} keyword is
1395 @deffn procedure slot-definition-getter slot-def
1396 Extract and return the slot getter option from @var{slot-def}. This is
1397 the value of the @code{#:getter} keyword (@pxref{Slot Options,,
1398 getter}), or @code{#f} if the @code{#:getter} keyword is absent.
1401 @deffn procedure slot-definition-setter slot-def
1402 Extract and return the slot setter option from @var{slot-def}. This is
1403 the value of the @code{#:setter} keyword (@pxref{Slot Options,,
1404 setter}), or @code{#f} if the @code{#:setter} keyword is absent.
1407 @deffn procedure slot-definition-accessor slot-def
1408 Extract and return the slot accessor option from @var{slot-def}. This
1409 is the value of the @code{#:accessor} keyword (@pxref{Slot Options,,
1410 accessor}), or @code{#f} if the @code{#:accessor} keyword is absent.
1413 @deffn procedure slot-definition-init-value slot-def
1414 Extract and return the slot init-value option from @var{slot-def}. This
1415 is the value of the @code{#:init-value} keyword (@pxref{Slot Options,,
1416 init-value}), or the unbound value if the @code{#:init-value} keyword is
1420 @deffn procedure slot-definition-init-form slot-def
1421 Extract and return the slot init-form option from @var{slot-def}. This
1422 is the value of the @code{#:init-form} keyword (@pxref{Slot Options,,
1423 init-form}), or the unbound value if the @code{#:init-form} keyword is
1427 @deffn procedure slot-definition-init-thunk slot-def
1428 Extract and return the slot init-thunk option from @var{slot-def}. This
1429 is the value of the @code{#:init-thunk} keyword (@pxref{Slot Options,,
1430 init-thunk}), or @code{#f} if the @code{#:init-thunk} keyword is absent.
1433 @deffn procedure slot-definition-init-keyword slot-def
1434 Extract and return the slot init-keyword option from @var{slot-def}.
1435 This is the value of the @code{#:init-keyword} keyword (@pxref{Slot
1436 Options,, init-keyword}), or @code{#f} if the @code{#:init-keyword}
1440 @deffn procedure slot-init-function class slot-name
1441 Return the initialization function for the slot named @var{slot-name} in
1442 class @var{class}. @var{slot-name} should be a symbol.
1444 The returned initialization function incorporates the effects of the
1445 standard @code{#:init-thunk}, @code{#:init-form} and @code{#:init-value}
1446 slot options. These initializations can be overridden by the
1447 @code{#:init-keyword} slot option or by a specialized @code{initialize}
1448 method, so, in general, the function returned by
1449 @code{slot-init-function} may be irrelevant. For a fuller discussion,
1450 see @ref{Slot Options,, init-value}.
1454 @node Generic Functions
1455 @subsection Generic Functions
1457 A generic function is an instance of the @code{<generic>} class, or of a
1458 subclass of @code{<generic>}. The definition of the @code{<generic>}
1459 class has slots that are used to describe the properties of a generic
1462 @deffn {primitive procedure} generic-function-name gf
1463 Return the name of generic function @var{gf}.
1466 @deffn {primitive procedure} generic-function-methods gf
1467 Return a list of the methods of generic function @var{gf}. This is the
1468 value of @var{gf}'s @code{methods} slot.
1471 Similarly, a method is an instance of the @code{<method>} class, or of a
1472 subclass of @code{<method>}; and the definition of the @code{<method>}
1473 class has slots that are used to describe the properties of a method.
1475 @deffn {primitive procedure} method-generic-function method
1476 Return the generic function that @var{method} belongs to. This is the
1477 value of @var{method}'s @code{generic-function} slot.
1480 @deffn {primitive procedure} method-specializers method
1481 Return a list of @var{method}'s formal parameter specializers . This is
1482 the value of @var{method}'s @code{specializers} slot.
1485 @deffn {primitive procedure} method-procedure method
1486 Return the procedure that implements @var{method}. This is the value of
1487 @var{method}'s @code{procedure} slot.
1490 @deffn generic method-source
1491 @deffnx method method-source (m <method>)
1492 Return an expression that prints to show the definition of method
1496 (define-generic cube)
1498 (define-method (cube (n <number>))
1501 (map method-source (generic-function-methods cube))
1503 ((method ((n <number>)) (* n n n)))
1508 @node Accessing Slots
1509 @subsection Accessing Slots
1511 Any slot, regardless of its allocation, can be queried, referenced and
1512 set using the following four primitive procedures.
1514 @deffn {primitive procedure} slot-exists? obj slot-name
1515 Return @code{#t} if @var{obj} has a slot with name @var{slot-name},
1516 otherwise @code{#f}.
1519 @deffn {primitive procedure} slot-bound? obj slot-name
1520 Return @code{#t} if the slot named @var{slot-name} in @var{obj} has a
1521 value, otherwise @code{#f}.
1523 @code{slot-bound?} calls the generic function @code{slot-missing} if
1524 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1525 Slot Access Errors, slot-missing}).
1528 @deffn {primitive procedure} slot-ref obj slot-name
1529 Return the value of the slot named @var{slot-name} in @var{obj}.
1531 @code{slot-ref} calls the generic function @code{slot-missing} if
1532 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1533 Slot Access Errors, slot-missing}).
1535 @code{slot-ref} calls the generic function @code{slot-unbound} if the
1536 named slot in @var{obj} does not have a value (@pxref{Handling Slot
1537 Access Errors, slot-unbound}).
1540 @deffn {primitive procedure} slot-set! obj slot-name value
1541 Set the value of the slot named @var{slot-name} in @var{obj} to @var{value}.
1543 @code{slot-set!} calls the generic function @code{slot-missing} if
1544 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1545 Slot Access Errors, slot-missing}).
1548 GOOPS stores information about slots in classes. Internally,
1549 all of these procedures work by looking up the slot definition for the
1550 slot named @var{slot-name} in the class @code{(class-of
1551 @var{obj})}, and then using the slot definition's ``getter'' and
1552 ``setter'' closures to get and set the slot value.
1554 The next four procedures differ from the previous ones in that they take
1555 the class as an explicit argument, rather than assuming
1556 @code{(class-of @var{obj})}. Therefore they allow you to apply the
1557 ``getter'' and ``setter'' closures of a slot definition in one class to
1558 an instance of a different class.
1560 @deffn {primitive procedure} slot-exists-using-class? class obj slot-name
1561 Return @code{#t} if @var{class} has a slot definition for a slot with
1562 name @var{slot-name}, otherwise @code{#f}.
1565 @deffn {primitive procedure} slot-bound-using-class? class obj slot-name
1566 Return @code{#t} if applying @code{slot-ref-using-class} to the same
1567 arguments would call the generic function @code{slot-unbound}, otherwise
1570 @code{slot-bound-using-class?} calls the generic function
1571 @code{slot-missing} if @var{class} does not have a slot definition for a
1572 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1576 @deffn {primitive procedure} slot-ref-using-class class obj slot-name
1577 Apply the ``getter'' closure for the slot named @var{slot-name} in
1578 @var{class} to @var{obj}, and return its result.
1580 @code{slot-ref-using-class} calls the generic function
1581 @code{slot-missing} if @var{class} does not have a slot definition for a
1582 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1585 @code{slot-ref-using-class} calls the generic function
1586 @code{slot-unbound} if the application of the ``getter'' closure to
1587 @var{obj} returns an unbound value (@pxref{Handling Slot Access Errors,
1591 @deffn {primitive procedure} slot-set-using-class! class obj slot-name value
1592 Apply the ``setter'' closure for the slot named @var{slot-name} in
1593 @var{class} to @var{obj} and @var{value}.
1595 @code{slot-set-using-class!} calls the generic function
1596 @code{slot-missing} if @var{class} does not have a slot definition for a
1597 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1601 Slots whose allocation is per-class rather than per-instance can be
1602 referenced and set without needing to specify any particular instance.
1604 @deffn procedure class-slot-ref class slot-name
1605 Return the value of the slot named @var{slot-name} in class @var{class}.
1606 The named slot must have @code{#:class} or @code{#:each-subclass}
1607 allocation (@pxref{Slot Options,, allocation}).
1609 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1610 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1611 function with arguments @var{class} and @var{slot-name}. Otherwise, if
1612 the slot value is unbound, @code{class-slot-ref} calls the
1613 @code{slot-unbound} generic function, with the same arguments.
1616 @deffn procedure class-slot-set! class slot-name value
1617 Set the value of the slot named @var{slot-name} in class @var{class} to
1618 @var{value}. The named slot must have @code{#:class} or
1619 @code{#:each-subclass} allocation (@pxref{Slot Options,, allocation}).
1621 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1622 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1623 function with arguments @var{class} and @var{slot-name}.
1627 @node GOOPS Object Miscellany
1628 @section GOOPS Object Miscellany
1630 Here we cover some points about GOOPS objects that aren't substantial
1631 enough to merit sections on their own.
1633 @subheading Object Equality
1635 When GOOPS is loaded, @code{eqv?}, @code{equal?} and @code{=} become
1636 generic functions, and you can define methods for them, specialized for
1637 your own classes, so as to control what the various kinds of equality
1638 mean for your classes.
1640 For example, the @code{assoc} procedure, for looking up an entry in an
1641 alist, is specified as using @code{equal?} to determine when the car of
1642 an entry in the alist is the same as the key parameter that @code{assoc}
1643 is called with. Hence, if you had defined a new class, and wanted to
1644 use instances of that class as the keys in an alist, you could define a
1645 method for @code{equal?}, for your class, to control @code{assoc}'s
1648 @subheading Cloning Objects
1650 @deffn generic shallow-clone
1651 @deffnx method shallow-clone (self <object>)
1652 Return a ``shallow'' clone of @var{self}. The default method makes a
1653 shallow clone by allocating a new instance and copying slot values from
1654 self to the new instance. Each slot value is copied either as an
1655 immediate value or by reference.
1658 @deffn generic deep-clone
1659 @deffnx method deep-clone (self <object>)
1660 Return a ``deep'' clone of @var{self}. The default method makes a deep
1661 clone by allocating a new instance and copying or cloning slot values
1662 from self to the new instance. If a slot value is an instance
1663 (satisfies @code{instance?}), it is cloned by calling @code{deep-clone}
1664 on that value. Other slot values are copied either as immediate values
1668 @subheading Write and Display
1670 @deffn {primitive generic} write object port
1671 @deffnx {primitive generic} display object port
1672 When GOOPS is loaded, @code{write} and @code{display} become generic
1673 functions with special methods for printing
1677 objects - instances of the class @code{<object>}
1680 foreign objects - instances of the class @code{<foreign-object>}
1683 classes - instances of the class @code{<class>}
1686 generic functions - instances of the class @code{<generic>}
1689 methods - instances of the class @code{<method>}.
1692 @code{write} and @code{display} print non-GOOPS values in the same way
1693 as the Guile primitive @code{write} and @code{display} functions.
1696 In addition to the cases mentioned, you can of course define
1697 @code{write} and @code{display} methods for your own classes, to
1698 customize how they are printed.
1702 @section Class Options
1704 @deffn {class option} #:metaclass metaclass
1705 The @code{#:metaclass} class option specifies the metaclass of the class
1706 being defined. @var{metaclass} must be a class that inherits from
1707 @code{<class>}. For the use of metaclasses, see @ref{Metaobjects and
1708 the Metaobject Protocol} and @ref{Terminology}.
1710 If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
1711 metaclass for the new class by calling @code{ensure-metaclass}
1712 (@pxref{Class Definition Internals,, ensure-metaclass}).
1715 @deffn {class option} #:name name
1716 The @code{#:name} class option specifies the new class's name. This
1717 name is used to identify the class whenever related objects - the class
1718 itself, its instances and its subclasses - are printed.
1720 If the @code{#:name} option is absent, GOOPS uses the first argument to
1721 @code{define-class} as the class name.
1725 @node Redefining a Class
1726 @section Redefining a Class
1728 Suppose that a class @code{<my-class>} is defined using @code{define-class}
1729 (@pxref{Class Definition,, define-class}), with slots that have
1730 accessor functions, and that an application has created several instances
1731 of @code{<my-class>} using @code{make} (@pxref{Instance Creation,,
1732 make}). What then happens if @code{<my-class>} is redefined by calling
1733 @code{define-class} again?
1736 * Default Class Redefinition Behaviour::
1737 * Customizing Class Redefinition::
1740 @node Default Class Redefinition Behaviour
1741 @subsection Default Class Redefinition Behaviour
1743 GOOPS' default answer to this question is as follows.
1747 All existing direct instances of @code{<my-class>} are converted to be
1748 instances of the new class. This is achieved by preserving the values
1749 of slots that exist in both the old and new definitions, and
1750 initializing the values of new slots in the usual way (@pxref{Instance
1754 All existing subclasses of @code{<my-class>} are redefined, as though
1755 the @code{define-class} expressions that defined them were re-evaluated
1756 following the redefinition of @code{<my-class>}, and the class
1757 redefinition process described here is applied recursively to the
1758 redefined subclasses.
1761 Once all of its instances and subclasses have been updated, the class
1762 metaobject previously bound to the variable @code{<my-class>} is no
1763 longer needed and so can be allowed to be garbage collected.
1766 To keep things tidy, GOOPS also needs to do a little housekeeping on
1767 methods that are associated with the redefined class.
1771 Slot accessor methods for slots in the old definition should be removed
1772 from their generic functions. They will be replaced by accessor methods
1773 for the slots of the new class definition.
1776 Any generic function method that uses the old @code{<my-class>} metaobject
1777 as one of its formal parameter specializers must be updated to refer to
1778 the new @code{<my-class>} metaobject. (Whenever a new generic function
1779 method is defined, @code{define-method} adds the method to a list stored
1780 in the class metaobject for each class used as a formal parameter
1781 specializer, so it is easy to identify all the methods that must be
1782 updated when a class is redefined.)
1785 If this class redefinition strategy strikes you as rather counter-intuitive,
1786 bear in mind that it is derived from similar behaviour in other object
1787 systems such as CLOS, and that experience in those systems has shown it to be
1788 very useful in practice.
1790 Also bear in mind that, like most of GOOPS' default behaviour, it can
1791 be customized@dots{}
1793 @node Customizing Class Redefinition
1794 @subsection Customizing Class Redefinition
1796 When @code{define-class} notices that a class is being redefined,
1797 it constructs the new class metaobject as usual, and then invokes the
1798 @code{class-redefinition} generic function with the old and new classes
1799 as arguments. Therefore, if the old or new classes have metaclasses
1800 other than the default @code{<class>}, class redefinition behaviour can
1801 be customized by defining a @code{class-redefinition} method that is
1802 specialized for the relevant metaclasses.
1804 @deffn generic class-redefinition
1805 Handle the class redefinition from @var{old-class} to @var{new-class},
1806 and return the new class metaobject that should be bound to the
1807 variable specified by @code{define-class}'s first argument.
1810 @deffn method class-redefinition (old-class <class>) (new-class <class>)
1811 Implements GOOPS' default class redefinition behaviour, as described in
1812 @ref{Default Class Redefinition Behaviour}. Returns the metaobject
1813 for the new class definition.
1816 An alternative class redefinition strategy could be to leave all
1817 existing instances as instances of the old class, but accepting that the
1818 old class is now ``nameless'', since its name has been taken over by the
1819 new definition. In this strategy, any existing subclasses could also
1820 be left as they are, on the understanding that they inherit from a nameless
1823 This strategy is easily implemented in GOOPS, by defining a new metaclass,
1824 that will be used as the metaclass for all classes to which the strategy
1825 should apply, and then defining a @code{class-redefinition} method that
1826 is specialized for this metaclass:
1829 (define-class <can-be-nameless> (<class>))
1831 (define-method (class-redefinition (old <can-be-nameless>)
1836 When customization can be as easy as this, aren't you glad that GOOPS
1837 implements the far more difficult strategy as its default!
1839 Finally, note that, if @code{class-redefinition} itself is not customized,
1840 the default @code{class-redefinition} method invokes three further
1841 generic functions that could be individually customized:
1845 (remove-class-accessors! @var{old-class})
1848 (update-direct-method! @var{method} @var{old-class} @var{new-class})
1851 (update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
1854 and the default methods for these generic functions invoke further
1855 generic functions, and so on@dots{} The detailed protocol for all of these
1856 is described in @ref{MOP Specification}.
1858 @node Changing the Class of an Instance
1859 @section Changing the Class of an Instance
1861 You can change the class of an existing instance by invoking the
1862 generic function @code{change-class} with two arguments: the instance
1865 @deffn generic change-class
1868 The default method for @code{change-class} decides how to implement the
1869 change of class by looking at the slot definitions for the instance's
1870 existing class and for the new class. If the new class has slots with
1871 the same name as slots in the existing class, the values for those slots
1872 are preserved. Slots that are present only in the existing class are
1873 discarded. Slots that are present only in the new class are initialized
1874 using the corresponding slot definition's init function (@pxref{Classes,,
1875 slot-init-function}).
1877 @deffn {method} change-class (obj <object>) (new <class>)
1878 Modify instance @var{obj} to make it an instance of class @var{new}.
1880 The value of each of @var{obj}'s slots is preserved only if a similarly named
1881 slot exists in @var{new}; any other slot values are discarded.
1883 The slots in @var{new} that do not correspond to any of @var{obj}'s
1884 pre-existing slots are initialized according to @var{new}'s slot definitions'
1888 Customized change of class behaviour can be implemented by defining
1889 @code{change-class} methods that are specialized either by the class
1890 of the instances to be modified or by the metaclass of the new class.
1892 When a class is redefined (@pxref{Redefining a Class}), and the default
1893 class redefinition behaviour is not overridden, GOOPS (eventually)
1894 invokes the @code{change-class} generic function for each existing
1895 instance of the redefined class.
1897 @node GOOPS Error Handling
1898 @section Error Handling
1900 The procedure @code{goops-error} is called to raise an appropriate error
1901 by the default methods of the following generic functions:
1905 @code{slot-missing} (@pxref{Handling Slot Access Errors,, slot-missing})
1908 @code{slot-unbound} (@pxref{Handling Slot Access Errors,, slot-unbound})
1911 @code{no-method} (@pxref{Handling Invocation Errors,, no-method})
1914 @code{no-applicable-method} (@pxref{Handling Invocation Errors,,
1915 no-applicable-method})
1918 @code{no-next-method} (@pxref{Handling Invocation Errors,,
1922 If you customize these functions for particular classes or metaclasses,
1923 you may still want to use @code{goops-error} to signal any error
1924 conditions that you detect.
1926 @deffn procedure goops-error format-string . args
1927 Raise an error with key @code{goops-error} and error message constructed
1928 from @var{format-string} and @var{args}. Error message formatting is
1929 as done by @code{scm-error}.
1933 * Handling Slot Access Errors::
1937 @node Handling Slot Access Errors
1938 @subsection Handling Slot Access Errors
1940 GOOPS calls one of the following generic functions when a ``slot-ref''
1941 or ``slot-set!'' call specifies a non-existent slot name, or tries to
1942 reference a slot whose value is unbound.
1944 @deffn generic slot-missing
1945 @deffnx method slot-missing (class <class>) slot-name
1946 @deffnx method slot-missing (class <class>) (object <object>) slot-name
1947 @deffnx method slot-missing (class <class>) (object <object>) slot-name value
1948 When an application attempts to reference or set a class or instance
1949 slot by name, and the slot name is invalid for the specified @var{class}
1950 or @var{object}, GOOPS calls the @code{slot-missing} generic function.
1952 The default methods all call @code{goops-error} with an appropriate
1956 @deffn generic slot-unbound
1957 @deffnx method slot-unbound (object <object>)
1958 @deffnx method slot-unbound (class <class>) slot-name
1959 @deffnx method slot-unbound (class <class>) (object <object>) slot-name
1960 When an application attempts to reference a class or instance slot, and
1961 the slot's value is unbound, GOOPS calls the @code{slot-unbound} generic
1964 The default methods all call @code{goops-error} with an appropriate
1969 @node The Metaobject Protocol
1970 @section The Metaobject Protocol
1972 GOOPS is based on a ``metaobject protocol'' (aka ``MOP'') derived from
1973 the ones used in CLOS (the Common Lisp Object System), tiny-clos (a
1974 small Scheme implementation of a subset of CLOS functionality) and
1977 GOOPS can be used by application authors at a basic level without any
1978 need to understand what the MOP is and how it works. On the other hand,
1979 the MOP underlies even very simple customizations --- such as defining
1980 an @code{initialize} method to customize the initialization of instances
1981 of an application-defined class --- and an understanding of the MOP
1982 makes it much easier to explain such customizations in a precise way.
1983 And in the long run, understanding the MOP is the key both to
1984 understanding GOOPS at a deeper level and to taking full advantage of
1985 GOOPS' power, by customizing the behaviour of GOOPS itself.
1988 * Metaobjects and the Metaobject Protocol::
1990 * MOP Specification::
1991 * Class Definition Internals::
1992 * Customizing Class Definition::
1993 * Customizing Instance Creation::
1994 * Class Redefinition::
1995 * Method Definition::
1996 * Method Definition Internals::
1997 * Generic Function Internals::
1998 * Generic Function Invocation::
2001 @node Metaobjects and the Metaobject Protocol
2002 @subsection Metaobjects and the Metaobject Protocol
2004 The building blocks of GOOPS are classes, slot definitions, instances,
2005 generic functions and methods. A class is a grouping of inheritance
2006 relations and slot definitions. An instance is an object with slots
2007 that are allocated following the rules implied by its class's
2008 superclasses and slot definitions. A generic function is a collection
2009 of methods and rules for determining which of those methods to apply
2010 when the generic function is invoked. A method is a procedure and a set
2011 of specializers that specify the type of arguments to which the
2012 procedure is applicable.
2014 Of these entities, GOOPS represents classes, generic functions and
2015 methods as ``metaobjects''. In other words, the values in a GOOPS
2016 program that describe classes, generic functions and methods, are
2017 themselves instances (or ``objects'') of special GOOPS classes that
2018 encapsulate the behaviour, respectively, of classes, generic functions,
2021 (The other two entities are slot definitions and instances. Slot
2022 definitions are not strictly instances, but every slot definition is
2023 associated with a GOOPS class that specifies the behaviour of the slot
2024 as regards accessibility and protection from garbage collection.
2025 Instances are of course objects in the usual sense, and there is no
2026 benefit from thinking of them as metaobjects.)
2028 The ``metaobject protocol'' (aka ``MOP'') is the specification of the
2029 generic functions which determine the behaviour of these metaobjects and
2030 the circumstances in which these generic functions are invoked.
2032 For a concrete example of what this means, consider how GOOPS calculates
2033 the set of slots for a class that is being defined using
2034 @code{define-class}. The desired set of slots is the union of the new
2035 class's direct slots and the slots of all its superclasses. But
2036 @code{define-class} itself does not perform this calculation. Instead,
2037 there is a method of the @code{initialize} generic function that is
2038 specialized for instances of type @code{<class>}, and it is this method
2039 that performs the slot calculation.
2041 @code{initialize} is a generic function which GOOPS calls whenever a new
2042 instance is created, immediately after allocating memory for a new
2043 instance, in order to initialize the new instance's slots. The sequence
2044 of steps is as follows.
2048 @code{define-class} uses @code{make} to make a new instance of the
2049 @code{<class>} class, passing as initialization arguments the
2050 superclasses, slot definitions and class options that were specified in
2051 the @code{define-class} form.
2054 @code{make} allocates memory for the new instance, and then invokes the
2055 @code{initialize} generic function to initialize the new instance's
2059 The @code{initialize} generic function applies the method that is
2060 specialized for instances of type @code{<class>}, and this method
2061 performs the slot calculation.
2064 In other words, rather than being hardcoded in @code{define-class}, the
2065 behaviour of class definition is encapsulated by generic function
2066 methods that are specialized for the class @code{<class>}.
2068 It is possible to create a new class that inherits from @code{<class>},
2069 which is called a ``metaclass'', and to write a new @code{initialize}
2070 method that is specialized for instances of the new metaclass. Then, if
2071 the @code{define-class} form includes a @code{#:metaclass} class option
2072 whose value is the new metaclass, the class that is defined by the
2073 @code{define-class} form will be an instance of the new metaclass rather
2074 than of the default @code{<class>}, and will be defined in accordance
2075 with the new @code{initialize} method. Thus the default slot
2076 calculation, as well as any other aspect of the new class's relationship
2077 with its superclasses, can be modified or overridden.
2079 In a similar way, the behaviour of generic functions can be modified or
2080 overridden by creating a new class that inherits from the standard
2081 generic function class @code{<generic>}, writing appropriate methods
2082 that are specialized to the new class, and creating new generic
2083 functions that are instances of the new class.
2085 The same is true for method metaobjects. And the same basic mechanism
2086 allows the application class author to write an @code{initialize} method
2087 that is specialized to their application class, to initialize instances
2090 Such is the power of the MOP. Note that @code{initialize} is just one
2091 of a large number of generic functions that can be customized to modify
2092 the behaviour of application objects and classes and of GOOPS itself.
2093 Each following section covers a particular area of GOOPS functionality,
2094 and describes the generic functions that are relevant for customization
2098 @subsection Terminology
2100 It is assumed that the reader is already familiar with standard object
2101 orientation concepts such as classes, objects/instances,
2102 inheritance/subclassing, generic functions and methods, encapsulation
2105 This section explains some of the less well known concepts and
2106 terminology that GOOPS uses, which are assumed by the following sections
2107 of the reference manual.
2109 @subsubheading Metaclass
2111 A @dfn{metaclass} is the class of an object which represents a GOOPS
2112 class. Put more succinctly, a metaclass is a class's class.
2114 Most GOOPS classes have the metaclass @code{<class>} and, by default,
2115 any new class that is created using @code{define-class} has the
2116 metaclass @code{<class>}.
2118 But what does this really mean? To find out, let's look in more detail
2119 at what happens when a new class is created using @code{define-class}:
2122 (define-class <my-class> (<object>) . slots)
2125 GOOPS actually expands the @code{define-class} form to something like
2129 (define <my-class> (class (<object>) . slots))
2136 (make <class> #:supers (list <object>) #:slots slots))
2139 In other words, the value of @code{<my-class>} is in fact an instance of
2140 the class @code{<class>} with slot values specifying the superclasses
2141 and slot definitions for the class @code{<my-class>}. (@code{#:supers}
2142 and @code{#:slots} are initialization keywords for the @code{dsupers}
2143 and @code{dslots} slots of the @code{<class>} class.)
2145 In order to take advantage of the full power of the GOOPS metaobject
2146 protocol (@pxref{MOP Specification}), it is sometimes desirable to
2147 create a new class with a metaclass other than the default
2148 @code{<class>}. This is done by writing:
2151 (define-class <my-class2> (<object>)
2153 #:metaclass <my-metaclass>)
2156 GOOPS expands this to something like:
2160 (make <my-metaclass> #:supers (list <object>) #:slots slots))
2163 In this case, the value of @code{<my-class2>} is an instance of the more
2164 specialized class @code{<my-metaclass>}. Note that
2165 @code{<my-metaclass>} itself must previously have been defined as a
2166 subclass of @code{<class>}. For a full discussion of when and how it is
2167 useful to define new metaclasses, see @ref{MOP Specification}.
2169 Now let's make an instance of @code{<my-class2>}:
2172 (define my-object (make <my-class2> ...))
2175 All of the following statements are correct expressions of the
2176 relationships between @code{my-object}, @code{<my-class2>},
2177 @code{<my-metaclass>} and @code{<class>}.
2181 @code{my-object} is an instance of the class @code{<my-class2>}.
2184 @code{<my-class2>} is an instance of the class @code{<my-metaclass>}.
2187 @code{<my-metaclass>} is an instance of the class @code{<class>}.
2190 The class of @code{my-object} is @code{<my-class2>}.
2193 The metaclass of @code{my-object} is @code{<my-metaclass>}.
2196 The class of @code{<my-class2>} is @code{<my-metaclass>}.
2199 The metaclass of @code{<my-class2>} is @code{<class>}.
2202 The class of @code{<my-metaclass>} is @code{<class>}.
2205 The metaclass of @code{<my-metaclass>} is @code{<class>}.
2208 @code{<my-class2>} is not a metaclass, since it is does not inherit from
2212 @code{<my-metaclass>} is a metaclass, since it inherits from
2216 @subsubheading Class Precedence List
2218 The @dfn{class precedence list} of a class is the list of all direct and
2219 indirect superclasses of that class, including the class itself.
2221 In the absence of multiple inheritance, the class precedence list is
2222 ordered straightforwardly, beginning with the class itself and ending
2225 For example, given this inheritance hierarchy:
2228 (define-class <invertebrate> (<object>) @dots{})
2229 (define-class <echinoderm> (<invertebrate>) @dots{})
2230 (define-class <starfish> (<echinoderm>) @dots{})
2233 the class precedence list of <starfish> would be
2236 (<starfish> <echinoderm> <invertebrate> <object> <top>)
2239 With multiple inheritance, the algorithm is a little more complicated.
2240 A full description is provided by the GOOPS Tutorial: see @ref{Class
2243 ``Class precedence list'' is often abbreviated, in documentation and
2244 Scheme variable names, to @dfn{cpl}.
2246 @subsubheading Accessor
2248 An @dfn{accessor} is a generic function with both reference and setter
2252 (define-accessor perimeter)
2255 Reference methods for an accessor are defined in the same way as generic
2259 (define-method (perimeter (s <square>))
2260 (* 4 (side-length s)))
2263 Setter methods for an accessor are defined by specifying ``(setter
2264 <accessor-name>)'' as the first parameter of the @code{define-method}
2268 (define-method ((setter perimeter) (s <square>) (n <number>))
2269 (set! (side-length s) (/ n 4)))
2272 Once an appropriate setter method has been defined in this way, it can
2273 be invoked using the generalized @code{set!} syntax, as in:
2276 (set! (perimeter s1) 18.3)
2279 @node MOP Specification
2280 @subsection MOP Specification
2282 The aim of the MOP specification in this chapter is to specify all the
2283 customizable generic function invocations that can be made by the standard
2284 GOOPS syntax, procedures and methods, and to explain the protocol for
2285 customizing such invocations.
2287 A generic function invocation is customizable if the types of the arguments
2288 to which it is applied are not all determined by the lexical context in
2289 which the invocation appears. For example,
2293 the @code{(initialize @var{instance} @var{initargs})} invocation in the
2294 default @code{make-instance} method is customizable, because the type of the
2295 @code{@var{instance}} argument is determined by the class that was passed to
2296 @code{make-instance}.
2299 the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
2300 is not customizable, because all of its arguments have lexically determined
2304 When using this rule to decide whether a given generic function invocation
2305 is customizable, we ignore arguments that are expected to be handled in
2306 method definitions as a single ``rest'' list argument.
2308 For each customizable generic function invocation, the @dfn{invocation
2309 protocol} is explained by specifying
2313 what, conceptually, the applied method is intended to do
2316 what assumptions, if any, the caller makes about the applied method's side
2320 what the caller expects to get as the applied method's return value.
2323 @node Class Definition Internals
2324 @subsection Class Definition Internals
2326 @code{define-class} (syntax)
2330 @code{class} (syntax)
2334 @code{make-class} (procedure)
2338 @code{make @var{metaclass} @dots{}} (generic)
2340 @var{metaclass} is the metaclass of the class being defined, either
2341 taken from the @code{#:metaclass} class option or computed by
2342 @code{ensure-metaclass}. The applied method must create and return the
2343 fully initialized class metaobject for the new class definition.
2349 @code{class-redefinition @var{old-class} @var{new-class}} (generic)
2351 @code{define-class} calls @code{class-redefinition} if the variable
2352 specified by its first argument already held a GOOPS class definition.
2353 @var{old-class} and @var{new-class} are the old and new class metaobjects.
2354 The applied method should perform whatever is necessary to handle the
2355 redefinition, and should return the class metaobject that is to be bound
2356 to @code{define-class}'s variable. The default class redefinition
2357 protocol is described in @ref{Class Redefinition}.
2360 The @code{(make @var{metaclass} @dots{})} invocation above will create
2361 an class metaobject with metaclass @var{metaclass}. By default, this
2362 metaobject will be initialized by the @code{initialize} method that is
2363 specialized for instances of type @code{<class>}.
2365 @code{initialize <class> @var{initargs}} (method)
2369 @code{compute-cpl @var{class}} (generic)
2371 The applied method should compute and return the class precedence list
2372 for @var{class} as a list of class metaobjects. When @code{compute-cpl}
2373 is called, the following @var{class} metaobject slots have all been
2374 initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
2375 @code{direct-subclasses} (empty), @code{direct-methods}. The value
2376 returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
2379 @code{compute-slots @var{class}} (generic)
2381 The applied method should compute and return the slots (union of direct
2382 and inherited) for @var{class} as a list of slot definitions. When
2383 @code{compute-slots} is called, all the @var{class} metaobject slots
2384 mentioned for @code{compute-cpl} have been initialized, plus the
2385 following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
2386 The value returned by @code{compute-slots} will be stored in the
2390 @code{compute-get-n-set @var{class} @var{slot-def}} (generic)
2392 @code{initialize} calls @code{compute-get-n-set} for each slot computed
2393 by @code{compute-slots}. The applied method should compute and return a
2394 pair of closures that, respectively, get and set the value of the specified
2395 slot. The get closure should have arity 1 and expect a single argument
2396 that is the instance whose slot value is to be retrieved. The set closure
2397 should have arity 2 and expect two arguments, where the first argument is
2398 the instance whose slot value is to be set and the second argument is the
2399 new value for that slot. The closures should be returned in a two element
2400 list: @code{(list @var{get} @var{set})}.
2402 The closures returned by @code{compute-get-n-set} are stored as part of
2403 the value of the @var{class} metaobject's @code{getters-n-setters} slot.
2404 Specifically, the value of this slot is a list with the same number of
2405 elements as there are slots in the class, and each element looks either like
2408 @code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
2414 @code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
2417 Where the get and set closures are replaced by @var{index}, the slot is
2418 an instance slot and @var{index} is the slot's index in the underlying
2419 structure: GOOPS knows how to get and set the value of such slots and so
2420 does not need specially constructed get and set closures. Otherwise,
2421 @var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
2423 The structure of the @code{getters-n-setters} slot value is important when
2424 understanding the next customizable generic functions that @code{initialize}
2428 @code{compute-getter-method @var{class} @var{gns}} (generic)
2430 @code{initialize} calls @code{compute-getter-method} for each of the class's
2431 slots (as determined by @code{compute-slots}) that includes a
2432 @code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
2433 element of the @var{class} metaobject's @code{getters-n-setters} slot that
2434 specifies how the slot in question is referenced and set, as described
2435 above under @code{compute-get-n-set}. The applied method should create
2436 and return a method that is specialized for instances of type @var{class}
2437 and uses the get closure to retrieve the slot's value. [ *fixme Need
2438 to insert something here about checking that the value is not unbound. ]
2439 @code{initialize} uses @code{add-method!} to add the returned method to
2440 the generic function named by the slot definition's @code{#:getter} or
2441 @code{#:accessor} option.
2444 @code{compute-setter-method @var{class} @var{gns}} (generic)
2446 @code{compute-setter-method} is invoked with the same arguments as
2447 @code{compute-getter-method}, for each of the class's slots that includes
2448 a @code{#:setter} or @code{#:accessor} slot option. The applied method
2449 should create and return a method that is specialized for instances of
2450 type @var{class} and uses the set closure to set the slot's value.
2451 @code{initialize} then uses @code{add-method!} to add the returned method
2452 to the generic function named by the slot definition's @code{#:setter}
2453 or @code{#:accessor} option.
2456 @code{define-class} expands to an expression which
2460 checks that it is being evaluated only at top level
2463 defines any accessors that are implied by the @var{slot-definition}s
2466 uses @code{class} to create the new class (@pxref{Class Definition
2470 checks for a previous class definition for @var{name} and, if found,
2471 handles the redefinition by invoking @code{class-redefinition}
2472 (@pxref{Redefining a Class}).
2475 @deffn syntax class name (super @dots{}) slot-definition @dots{} . options
2476 Return a newly created class that inherits from @var{super}s, with
2477 direct slots defined by @var{slot-definition}s and class options
2478 @var{options}. For the format of @var{slot-definition}s and
2479 @var{options}, see @ref{Class Definition,, define-class}.
2482 @noindent @code{class} expands to an expression which
2486 processes the class and slot definition options to check that they are
2487 well-formed, to convert the @code{#:init-form} option to an
2488 @code{#:init-thunk} option, to supply a default environment parameter
2489 (the current top-level environment) and to evaluate all the bits that
2490 need to be evaluated
2493 calls @code{make-class} to create the class with the processed and
2494 evaluated parameters.
2497 @deffn procedure make-class supers slots . options
2498 Return a newly created class that inherits from @var{supers}, with
2499 direct slots defined by @var{slots} and class options @var{options}.
2500 For the format of @var{slots} and @var{options}, see @ref{Class
2501 Definition,, define-class}, except note that for @code{make-class},
2502 @var{slots} and @var{options} are separate list parameters: @var{slots}
2503 here is a list of slot definitions.
2506 @noindent @code{make-class}
2510 adds @code{<object>} to the @var{supers} list if @var{supers} is empty
2511 or if none of the classes in @var{supers} have @code{<object>} in their
2512 class precedence list
2515 defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
2516 options, if they are not specified by @var{options}, to the current
2517 top-level environment, the unbound value, and @code{(ensure-metaclass
2518 @var{supers})} respectively (@pxref{Class Definition Internals,,
2522 checks for duplicate classes in @var{supers} and duplicate slot names in
2523 @var{slots}, and signals an error if there are any duplicates
2526 calls @code{make}, passing the metaclass as the first parameter and all
2527 other parameters as option keywords with values.
2530 @deffn procedure ensure-metaclass supers env
2531 Return a metaclass suitable for a class that inherits from the list of
2532 classes in @var{supers}. The returned metaclass is the union by
2533 inheritance of the metaclasses of the classes in @var{supers}.
2535 In the simplest case, where all the @var{supers} are straightforward
2536 classes with metaclass @code{<class>}, the returned metaclass is just
2539 For a more complex example, suppose that @var{supers} contained one
2540 class with metaclass @code{<operator-class>} and one with metaclass
2541 @code{<foreign-object-class>}. Then the returned metaclass would be a
2542 class that inherits from both @code{<operator-class>} and
2543 @code{<foreign-object-class>}.
2545 If @var{supers} is the empty list, @code{ensure-metaclass} returns the
2546 default GOOPS metaclass @code{<class>}.
2548 GOOPS keeps a list of the metaclasses created by
2549 @code{ensure-metaclass}, so that each required type of metaclass only
2550 has to be created once.
2552 The @code{env} parameter is ignored.
2555 @deffn procedure ensure-metaclass-with-supers meta-supers
2556 @code{ensure-metaclass-with-supers} is an internal procedure used by
2557 @code{ensure-metaclass} (@pxref{Class Definition Internals,,
2558 ensure-metaclass}). It returns a metaclass that is the union by
2559 inheritance of the metaclasses in @var{meta-supers}.
2562 The internals of @code{make}, which is ultimately used to create the new
2563 class object, are described in @ref{Customizing Instance Creation},
2564 which covers the creation and initialization of instances in general.
2566 @node Customizing Class Definition
2567 @subsection Customizing Class Definition
2569 During the initialization of a new class, GOOPS calls a number of generic
2570 functions with the newly allocated class instance as the first
2571 argument. Specifically, GOOPS calls the generic function
2575 (initialize @var{class} @dots{})
2578 where @var{class} is the newly allocated class instance, and the default
2579 @code{initialize} method for arguments of type @code{<class>} calls the
2584 (compute-cpl @var{class})
2587 (compute-slots @var{class})
2590 (compute-get-n-set @var{class} @var{slot-def}), for each of the slot
2591 definitions returned by @code{compute-slots}
2594 (compute-getter-method @var{class} @var{slot-def}), for each of the
2595 slot definitions returned by @code{compute-slots} that includes a
2596 @code{#:getter} or @code{#:accessor} slot option
2599 (compute-setter-method @var{class} @var{slot-def}), for each of the
2600 slot definitions returned by @code{compute-slots} that includes a
2601 @code{#:setter} or @code{#:accessor} slot option.
2604 If the metaclass of the new class is something more specialized than the
2605 default @code{<class>}, then the type of @var{class} in the calls above
2606 is more specialized than @code{<class>}, and hence it becomes possible
2607 to define generic function methods, specialized for the new class's
2608 metaclass, that can modify or override the default behaviour of
2609 @code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
2611 @code{compute-cpl} computes the class precedence list (``CPL'') for the
2612 new class (@pxref{Class Precedence List}), and returns it as a list of
2613 class objects. The CPL is important because it defines a superclass
2614 ordering that is used, when a generic function is invoked upon an
2615 instance of the class, to decide which of the available generic function
2616 methods is the most specific. Hence @code{compute-cpl} could be
2617 customized in order to modify the CPL ordering algorithm for all classes
2618 with a special metaclass.
2620 The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
2621 procedure, which is in turn called by the default @code{compute-cpl}
2624 @deffn procedure compute-std-cpl class
2625 Compute and return the class precedence list for @var{class} according
2626 to the algorithm described in @ref{Class Precedence List}.
2629 @code{compute-slots} computes and returns a list of all slot definitions
2630 for the new class. By default, this list includes the direct slot
2631 definitions from the @code{define-class} form, plus the slot definitions
2632 that are inherited from the new class's superclasses. The default
2633 @code{compute-slots} method uses the CPL computed by @code{compute-cpl}
2634 to calculate this union of slot definitions, with the rule that slots
2635 inherited from superclasses are shadowed by direct slots with the same
2636 name. One possible reason for customizing @code{compute-slots} would be
2637 to implement an alternative resolution strategy for slot name conflicts.
2639 @code{compute-get-n-set} computes the low-level closures that will be
2640 used to get and set the value of a particular slot, and returns them in
2641 a list with two elements.
2643 The closures returned depend on how storage for that slot is allocated.
2644 The standard @code{compute-get-n-set} method, specialized for classes of
2645 type @code{<class>}, handles the standard GOOPS values for the
2646 @code{#:allocation} slot option (@pxref{Slot Options,, allocation}). By
2647 defining a new @code{compute-get-n-set} method for a more specialized
2648 metaclass, it is possible to support new types of slot allocation.
2650 Suppose you wanted to create a large number of instances of some class
2651 with a slot that should be shared between some but not all instances of
2652 that class - say every 10 instances should share the same slot storage.
2653 The following example shows how to implement and use a new type of slot
2654 allocation to do this.
2657 (define-class <batched-allocation-metaclass> (<class>))
2659 (let ((batch-allocation-count 0)
2660 (batch-get-n-set #f))
2661 (define-method (compute-get-n-set
2662 (class <batched-allocation-metaclass>) s)
2663 (case (slot-definition-allocation s)
2665 ;; If we've already used the same slot storage for 10 instances,
2667 (if (= batch-allocation-count 10)
2669 (set! batch-allocation-count 0)
2670 (set! batch-get-n-set #f)))
2671 ;; If we don't have a current pair of get and set closures,
2672 ;; create one. make-closure-variable returns a pair of closures
2673 ;; around a single Scheme variable - see goops.scm for details.
2675 (set! batch-get-n-set (make-closure-variable)))
2676 ;; Increment the batch allocation count.
2677 (set! batch-allocation-count (+ batch-allocation-count 1))
2680 ;; Call next-method to handle standard allocation types.
2681 (else (next-method)))))
2683 (define-class <class-using-batched-slot> ()
2685 (c #:allocation #:batched)
2687 #:metaclass <batched-allocation-metaclass>)
2690 The usage of @code{compute-getter-method} and @code{compute-setter-method}
2691 is described in @ref{MOP Specification}.
2693 @code{compute-cpl} and @code{compute-get-n-set} are called by the
2694 standard @code{initialize} method for classes whose metaclass is
2695 @code{<class>}. But @code{initialize} itself can also be modified, by
2696 defining an @code{initialize} method specialized to the new class's
2697 metaclass. Such a method could complete override the standard
2698 behaviour, by not calling @code{(next-method)} at all, but more
2699 typically it would perform additional class initialization steps before
2700 and/or after calling @code{(next-method)} for the standard behaviour.
2702 @node Customizing Instance Creation
2703 @subsection Customizing Instance Creation
2705 @code{make <class> . @var{initargs}} (method)
2709 @code{allocate-instance @var{class} @var{initargs}} (generic)
2711 The applied @code{allocate-instance} method should allocate storage for
2712 a new instance of class @var{class} and return the uninitialized instance.
2715 @code{initialize @var{instance} @var{initargs}} (generic)
2717 @var{instance} is the uninitialized instance returned by
2718 @code{allocate-instance}. The applied method should initialize the new
2719 instance in whatever sense is appropriate for its class. The method's
2720 return value is ignored.
2723 @code{make} itself is a generic function. Hence the @code{make}
2724 invocation itself can be customized in the case where the new instance's
2725 metaclass is more specialized than the default @code{<class>}, by
2726 defining a @code{make} method that is specialized to that metaclass.
2728 Normally, however, the method for classes with metaclass @code{<class>}
2729 will be applied. This method calls two generic functions:
2733 (allocate-instance @var{class} . @var{initargs})
2736 (initialize @var{instance} . @var{initargs})
2739 @code{allocate-instance} allocates storage for and returns the new
2740 instance, uninitialized. You might customize @code{allocate-instance},
2741 for example, if you wanted to provide a GOOPS wrapper around some other
2742 object programming system.
2744 To do this, you would create a specialized metaclass, which would act as
2745 the metaclass for all classes and instances from the other system. Then
2746 define an @code{allocate-instance} method, specialized to that
2747 metaclass, which calls a Guile primitive C function, which in turn
2748 allocates the new instance using the interface of the other object
2751 In this case, for a complete system, you would also need to customize a
2752 number of other generic functions like @code{make} and
2753 @code{initialize}, so that GOOPS knows how to make classes from the
2754 other system, access instance slots, and so on.
2756 @code{initialize} initializes the instance that is returned by
2757 @code{allocate-instance}. The standard GOOPS methods perform
2758 initializations appropriate to the instance class.
2762 At the least specialized level, the method for instances of type
2763 @code{<object>} performs internal GOOPS instance initialization, and
2764 initializes the instance's slots according to the slot definitions and
2765 any slot initialization keywords that appear in @var{initargs}.
2768 The method for instances of type @code{<class>} calls
2769 @code{(next-method)}, then performs the class initializations described
2770 in @ref{Customizing Class Definition}.
2773 and so on for generic functions, method, operator classes @dots{}
2776 Similarly, you can customize the initialization of instances of any
2777 application-defined class by defining an @code{initialize} method
2778 specialized to that class.
2780 Imagine a class whose instances' slots need to be initialized at
2781 instance creation time by querying a database. Although it might be
2782 possible to achieve this a combination of @code{#:init-thunk} keywords
2783 and closures in the slot definitions, it is neater to write an
2784 @code{initialize} method for the class that queries the database once
2785 and initializes all the dependent slot values according to the results.
2787 @node Class Redefinition
2788 @subsection Class Redefinition
2790 The default @code{class-redefinition} method, specialized for classes
2791 with the default metaclass @code{<class>}, has the following internal
2794 @code{class-redefinition (@var{old <class>}) (@var{new <class>})}
2799 @code{remove-class-accessors! @var{old}} (generic)
2802 @code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
2805 @code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
2808 This protocol cleans up things that the definition of the old class
2809 once changed and modifies things to work with the new class.
2811 The default @code{remove-class-accessors!} method removes the
2812 accessor methods of the old class from all classes which they
2815 The default @code{update-direct-method!} method substitutes the new
2816 class for the old in all methods specialized to the old class.
2818 The default @code{update-direct-subclass!} method invokes
2819 @code{class-redefinition} recursively to handle the redefinition of
2822 When a class is redefined, any existing instance of the redefined class
2823 will be modified for the new class definition before the next time that
2824 any of the instance's slot is referenced or set. GOOPS modifies each
2825 instance by calling the generic function @code{change-class}.
2827 The default @code{change-class} method copies slot values from the old
2828 to the modified instance, and initializes new slots, as described in
2829 @ref{Changing the Class of an Instance}. After doing so, it makes a
2830 generic function invocation that can be used to customize the instance
2833 @code{change-class (@var{old-instance <object>}) (@var{new <class>})} (method)
2837 @code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
2839 @code{change-class} invokes @code{update-instance-for-different-class}
2840 as the last thing that it does before returning. The applied method can
2841 make any further adjustments to @var{new-instance} that are required to
2842 complete or modify the change of class. The return value from the
2843 applied method is ignored.
2845 The default @code{update-instance-for-different-class} method does
2849 @node Method Definition
2850 @subsection Method Definition
2852 @code{define-method} (syntax)
2856 @code{add-method! @var{target} @var{method}} (generic)
2858 @code{define-method} invokes the @code{add-method!} generic function to
2859 handle adding the new method to a variety of possible targets. GOOPS
2860 includes methods to handle @var{target} as
2864 a generic function (the most common case)
2870 a primitive generic (@pxref{Extending Primitives})
2873 By defining further methods for @code{add-method!}, you can
2874 theoretically handle adding methods to further types of target.
2877 @node Method Definition Internals
2878 @subsection Method Definition Internals
2880 @code{define-method}
2884 checks the form of the first parameter, and applies the following steps
2885 to the accessor's setter if it has the @code{(setter @dots{})} form
2888 interpolates a call to @code{define-generic} or @code{define-accessor}
2889 if a generic function is not already defined with the supplied name
2892 calls @code{method} with the @var{parameter}s and @var{body}, to make a
2896 calls @code{add-method!} to add this method to the relevant generic
2900 @deffn syntax method (parameter @dots{}) . body
2901 Make a method whose specializers are defined by the classes in
2902 @var{parameter}s and whose procedure definition is constructed from the
2903 @var{parameter} symbols and @var{body} forms.
2905 The @var{parameter} and @var{body} parameters should be as for
2906 @code{define-method} (@pxref{Methods and Generic Functions,,
2914 extracts formals and specializing classes from the @var{parameter}s,
2915 defaulting the class for unspecialized parameters to @code{<top>}
2918 creates a closure using the formals and the @var{body} forms
2921 calls @code{make} with metaclass @code{<method>} and the specializers
2922 and closure using the @code{#:specializers} and @code{#:procedure}
2926 @deffn procedure make-method specializers procedure
2927 Make a method using @var{specializers} and @var{procedure}.
2929 @var{specializers} should be a list of classes that specifies the
2930 parameter combinations to which this method will be applicable.
2932 @var{procedure} should be the closure that will applied to the generic
2933 function parameters when this method is invoked.
2936 @code{make-method} is a simple wrapper around @code{make} with metaclass
2939 @deffn generic add-method! target method
2940 Generic function for adding method @var{method} to @var{target}.
2943 @deffn method add-method! (generic <generic>) (method <method>)
2944 Add method @var{method} to the generic function @var{generic}.
2947 @deffn method add-method! (proc <procedure>) (method <method>)
2948 If @var{proc} is a procedure with generic capability (@pxref{Extending
2949 Primitives,, generic-capability?}), upgrade it to a primitive generic
2950 and add @var{method} to its generic function definition.
2953 @deffn method add-method! (pg <primitive-generic>) (method <method>)
2954 Add method @var{method} to the generic function definition of @var{pg}.
2956 Implementation: @code{(add-method! (primitive-generic-generic pg) method)}.
2959 @deffn method add-method! (whatever <top>) (method <method>)
2960 Raise an error indicating that @var{whatever} is not a valid generic
2964 @node Generic Function Internals
2965 @subsection Generic Function Internals
2967 @code{define-generic} calls @code{ensure-generic} to upgrade a
2968 pre-existing procedure value, or @code{make} with metaclass
2969 @code{<generic>} to create a new generic function.
2971 @code{define-accessor} calls @code{ensure-accessor} to upgrade a
2972 pre-existing procedure value, or @code{make-accessor} to create a new
2975 @deffn procedure ensure-generic old-definition [name]
2976 Return a generic function with name @var{name}, if possible by using or
2977 upgrading @var{old-definition}. If unspecified, @var{name} defaults to
2980 If @var{old-definition} is already a generic function, it is returned
2983 If @var{old-definition} is a Scheme procedure or procedure-with-setter,
2984 @code{ensure-generic} returns a new generic function that uses
2985 @var{old-definition} for its default procedure and setter.
2987 Otherwise @code{ensure-generic} returns a new generic function with no
2988 defaults and no methods.
2991 @deffn procedure make-generic [name]
2992 Return a new generic function with name @code{(car @var{name})}. If
2993 unspecified, @var{name} defaults to @code{#f}.
2996 @code{ensure-generic} calls @code{make} with metaclasses
2997 @code{<generic>} and @code{<generic-with-setter>}, depending on the
2998 previous value of the variable that it is trying to upgrade.
3000 @code{make-generic} is a simple wrapper for @code{make} with metaclass
3003 @deffn procedure ensure-accessor proc [name]
3004 Return an accessor with name @var{name}, if possible by using or
3005 upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
3007 If @var{proc} is already an accessor, it is returned unchanged.
3009 If @var{proc} is a Scheme procedure, procedure-with-setter or generic
3010 function, @code{ensure-accessor} returns an accessor that reuses the
3011 reusable elements of @var{proc}.
3013 Otherwise @code{ensure-accessor} returns a new accessor with no defaults
3017 @deffn procedure make-accessor [name]
3018 Return a new accessor with name @code{(car @var{name})}. If
3019 unspecified, @var{name} defaults to @code{#f}.
3022 @code{ensure-accessor} calls @code{make} with
3023 metaclass @code{<generic-with-setter>}, as well as calls to
3024 @code{ensure-generic}, @code{make-accessor} and (tail recursively)
3025 @code{ensure-accessor}.
3027 @code{make-accessor} calls @code{make} twice, first
3028 with metaclass @code{<generic>} to create a generic function for the
3029 setter, then with metaclass @code{<generic-with-setter>} to create the
3030 accessor, passing the setter generic function as the value of the
3031 @code{#:setter} keyword.
3033 @node Generic Function Invocation
3034 @subsection Generic Function Invocation
3036 [ *fixme* Description required here. ]
3038 @code{apply-generic}
3045 @code{compute-applicable-methods}
3048 @code{sort-applicable-methods}
3051 @code{apply-methods}
3054 @code{no-applicable-method}
3057 @code{sort-applicable-methods}
3061 @code{method-more-specific?}
3064 @code{apply-methods}
3075 @code{no-next-method}