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::
50 * Generic Functions and Accessors::
51 * Redefining a Class::
52 * Changing the Class of an Instance::
53 * GOOPS Error Handling::
54 * Object Comparisons::
57 * The Metaobject Protocol::
60 @node Copyright Notice
61 @section Copyright Notice
63 The material in this chapter is partly derived from the STk Reference
64 Manual written by Erick Gallesio, whose copyright notice is as follows.
66 Copyright © 1993-1999 Erick Gallesio - I3S-CNRS/ESSI <eg@@unice.fr>
67 Permission to use, copy, modify, distribute,and license this
68 software and its documentation for any purpose is hereby granted,
69 provided that existing copyright notices are retained in all
70 copies and that this notice is included verbatim in any
71 distributions. No written agreement, license, or royalty fee is
72 required for any of the authorized uses.
73 This software is provided ``AS IS'' without express or implied
76 The material has been adapted for use in Guile, with the author's
80 @node Class Definition
81 @section Class Definition
83 A new class is defined with the @code{define-class} syntax:
88 (define-class @var{class} (@var{superclass} @dots{})
89 @var{slot-description} @dots{}
90 @var{class-option} @dots{})
93 @var{class} is the class being defined. The list of @var{superclass}es
94 specifies which existing classes, if any, to inherit slots and
95 properties from. @dfn{Slots} hold per-instance@footnote{Usually --- but
96 see also the @code{#:allocation} slot option.} data, for instances of
97 that class --- like ``fields'' or ``member variables'' in other object
98 oriented systems. Each @var{slot-description} gives the name of a slot
99 and optionally some ``properties'' of this slot; for example its initial
100 value, the name of a function which will access its value, and so on.
101 Slot descriptions and inheritance are discussed more below. For class
102 options, see @ref{Class Options}.
105 @deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
106 Define a class called @var{name} that inherits from @var{super}s, with
107 direct slots defined by @var{slot-definition}s and class options
108 @var{options}. The newly created class is bound to the variable name
109 @var{name} in the current environment.
111 Each @var{slot-definition} is either a symbol that names the slot or a
115 (@var{slot-name-symbol} . @var{slot-options})
118 where @var{slot-name-symbol} is a symbol and @var{slot-options} is a
119 list with an even number of elements. The even-numbered elements of
120 @var{slot-options} (counting from zero) are slot option keywords; the
121 odd-numbered elements are the corresponding values for those keywords.
123 @var{options} is a similarly structured list containing class option
124 keywords and corresponding values.
127 As an example, let us define a type for representing a complex number
128 in terms of two real numbers.@footnote{Of course Guile already
129 provides complex numbers, and @code{<complex>} is in fact a predefined
130 class in GOOPS; but the definition here is still useful as an
131 example.} This can be done with the following class definition:
134 (define-class <my-complex> (<number>)
138 This binds the variable @code{<my-complex>} to a new class whose
139 instances will contain two slots. These slots are called @code{r} and
140 @code{i} and will hold the real and imaginary parts of a complex
141 number. Note that this class inherits from @code{<number>}, which is a
142 predefined class.@footnote{@code{<number>} is the direct superclass of
143 the predefined class @code{<complex>}; @code{<complex>} is the
144 superclass of @code{<real>}, and @code{<real>} is the superclass of
147 The possible slot and class options are described in the following
151 @node Instance Creation
152 @section Instance Creation and Slot Access
154 An instance (or object) of a defined class can be created with
155 @code{make}. @code{make} takes one mandatory parameter, which is the
156 class of the instance to create, and a list of optional arguments that
157 will be used to initialize the slots of the new instance. For instance
163 (define c (make <my-complex>))
167 creates a new @code{<my-complex>} object and binds it to the Scheme
171 @deffnx method make (class <class>) . initargs
172 Create and return a new instance of class @var{class}, initialized using
175 In theory, @var{initargs} can have any structure that is understood by
176 whatever methods get applied when the @code{initialize} generic function
177 is applied to the newly allocated instance.
179 In practice, specialized @code{initialize} methods would normally call
180 @code{(next-method)}, and so eventually the standard GOOPS
181 @code{initialize} methods are applied. These methods expect
182 @var{initargs} to be a list with an even number of elements, where
183 even-numbered elements (counting from zero) are keywords and
184 odd-numbered elements are the corresponding values.
186 GOOPS processes initialization argument keywords automatically for slots
187 whose definition includes the @code{#:init-keyword} option (@pxref{Slot
188 Options,, init-keyword}). Other keyword value pairs can only be
189 processed by an @code{initialize} method that is specialized for the new
190 instance's class. Any unprocessed keyword value pairs are ignored.
193 @deffn generic make-instance
194 @deffnx method make-instance (class <class>) . initargs
195 @code{make-instance} is an alias for @code{make}.
198 The slots of the new complex number can be accessed using
199 @code{slot-ref} and @code{slot-set!}. @code{slot-set!} sets the value
200 of an object slot and @code{slot-ref} retrieves it.
208 (slot-ref c 'r) @result{} 10
209 (slot-ref c 'i) @result{} 3
213 The @code{(oop goops describe)} module provides a @code{describe}
214 function that is useful for seeing all the slots of an object; it prints
215 the slots and their values to standard output.
220 #<<my-complex> 401d8638> is an instance of class <my-complex>
228 @section Slot Options
230 When specifying a slot (in a @code{(define-class @dots{})} form),
231 various options can be specified in addition to the slot's name. Each
232 option is specified by a keyword. The list of possible keywords is
235 @deffn {slot option} #:init-value init-value
236 @deffnx {slot option} #:init-form init-form
237 @deffnx {slot option} #:init-thunk init-thunk
238 @deffnx {slot option} #:init-keyword init-keyword
239 These options provide various ways to specify how to initialize the
240 slot's value at instance creation time.
241 @cindex default slot value
243 @var{init-value} specifies a fixed initial slot value (shared across all
244 new instances of the class).
246 @var{init-thunk} specifies a thunk that will provide a default value for
247 the slot. The thunk is called when a new instance is created and should
248 return the desired initial slot value.
250 @var{init-form} specifies a form that, when evaluated, will return
251 an initial value for the slot. The form is evaluated each time that
252 an instance of the class is created, in the lexical environment of the
253 containing @code{define-class} expression.
255 @var{init-keyword} specifies a keyword that can be used to pass an
256 initial slot value to @code{make} when creating a new instance.
258 Note that, since an @code{init-value} value is shared across all
259 instances of a class, you should only use it when the initial value is
260 an immutable value, like a constant. If you want to initialize a slot
261 with a fresh, independently mutable value, you should use
262 @code{init-thunk} or @code{init-form} instead. Consider the following
266 (define-class <chbouib> ()
267 (hashtab #:init-value (make-hash-table)))
271 Here only one hash table is created and all instances of
272 @code{<chbouib>} have their @code{hashtab} slot refer to it. In order
273 to have each instance of @code{<chbouib>} refer to a new hash table, you
274 should instead write:
277 (define-class <chbouib> ()
278 (hashtab #:init-thunk make-hash-table))
285 (define-class <chbouib> ()
286 (hashtab #:init-form (make-hash-table)))
289 If more than one of these options is specified for the same slot, the
290 order of precedence, highest first is
294 @code{#:init-keyword}, if @var{init-keyword} is present in the options
295 passed to @code{make}
298 @code{#:init-thunk}, @code{#:init-form} or @code{#:init-value}.
301 If the slot definition contains more than one initialization option of
302 the same precedence, the later ones are ignored. If a slot is not
303 initialized at all, its value is unbound.
305 In general, slots that are shared between more than one instance are
306 only initialized at new instance creation time if the slot value is
307 unbound at that time. However, if the new instance creation specifies
308 a valid init keyword and value for a shared slot, the slot is
309 re-initialized regardless of its previous value.
311 Note, however, that the power of GOOPS' metaobject protocol means that
312 everything written here may be customized or overridden for particular
313 classes! The slot initializations described here are performed by the least
314 specialized method of the generic function @code{initialize}, whose
318 (define-method (initialize (object <object>) initargs) ...)
321 The initialization of instances of any given class can be customized by
322 defining a @code{initialize} method that is specialized for that class,
323 and the author of the specialized method may decide to call
324 @code{next-method} - which will result in a call to the next less
325 specialized @code{initialize} method - at any point within the
326 specialized code, or maybe not at all. In general, therefore, the
327 initialization mechanisms described here may be modified or overridden by
328 more specialized code, or may not be supported at all for particular
332 @deffn {slot option} #:getter getter
333 @deffnx {slot option} #:setter setter
334 @deffnx {slot option} #:accessor accessor
335 Given an object @var{obj} with slots named @code{foo} and @code{bar}, it
336 is always possible to read and write those slots by calling
337 @code{slot-ref} and @code{slot-set!} with the relevant slot name; for
341 (slot-ref @var{obj} 'foo)
342 (slot-set! @var{obj} 'bar 25)
345 The @code{#:getter}, @code{#:setter} and @code{#:accessor} options, if
346 present, tell GOOPS to create generic function and method definitions
347 that can be used to get and set the slot value more conveniently.
348 @var{getter} specifies a generic function to which GOOPS will add a
349 method for getting the slot value. @var{setter} specifies a generic
350 function to which GOOPS will add a method for setting the slot value.
351 @var{accessor} specifies an accessor to which GOOPS will add methods for
352 both getting and setting the slot value.
354 So if a class includes a slot definition like this:
357 (c #:getter get-count #:setter set-count #:accessor count)
360 GOOPS defines generic function methods such that the slot value can be
361 referenced using either the getter or the accessor -
364 (let ((current-count (get-count obj))) @dots{})
365 (let ((current-count (count obj))) @dots{})
368 - and set using either the setter or the accessor -
371 (set-count obj (+ 1 current-count))
372 (set! (count obj) (+ 1 current-count))
379 with an accessor, the slot value is set using the generalized
383 in practice, it is unusual for a slot to use all three of these options:
384 read-only, write-only and read-write slots would typically use only
385 @code{#:getter}, @code{#:setter} and @code{#:accessor} options
389 The binding of the specified names is done in the environment of the
390 @code{define-class} expression. If the names are already bound (in that
391 environment) to values that cannot be upgraded to generic functions,
392 those values are overwritten when the @code{define-class} expression is
393 evaluated. For more detail, see @ref{Generic Function Internals,,
397 @deffn {slot option} #:allocation allocation
398 The @code{#:allocation} option tells GOOPS how to allocate storage for
399 the slot. Possible values for @var{allocation} are
402 @item @code{#:instance}
405 Indicates that GOOPS should create separate storage for this slot in
406 each new instance of the containing class (and its subclasses). This is
412 Indicates that GOOPS should create storage for this slot that is shared
413 by all instances of the containing class (and its subclasses). In other
414 words, a slot in class @var{C} with allocation @code{#:class} is shared
415 by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
416 This permits defining a kind of global variable which can be accessed
417 only by (in)direct instances of the class which defines the slot.
419 @item @code{#:each-subclass}
421 @findex #:each-subclass
422 Indicates that GOOPS should create storage for this slot that is shared
423 by all @emph{direct} instances of the containing class, and that
424 whenever a subclass of the containing class is defined, GOOPS should
425 create a new storage for the slot that is shared by all @emph{direct}
426 instances of the subclass. In other words, a slot with allocation
427 @code{#:each-subclass} is shared by all instances with the same
430 @item @code{#:virtual}
435 Indicates that GOOPS should not allocate storage for this slot. The
436 slot definition must also include the @code{#:slot-ref} and
437 @code{#:slot-set!} options to specify how to reference and set the value
438 for this slot. See the example below.
441 Slot allocation options are processed when defining a new class by the
442 generic function @code{compute-get-n-set}, which is specialized by the
443 class's metaclass. Hence new types of slot allocation can be
444 implemented by defining a new metaclass and a method for
445 @code{compute-get-n-set} that is specialized for the new metaclass. For
446 an example of how to do this, see @ref{Customizing Class Definition}.
449 @deffn {slot option} #:slot-ref getter
450 @deffnx {slot option} #:slot-set! setter
451 The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
452 if the slot allocation is @code{#:virtual}, and are ignored otherwise.
454 @var{getter} should be a closure taking a single @var{instance} parameter
455 that returns the current slot value. @var{setter} should be a closure
456 taking two parameters - @var{instance} and @var{new-val} - that sets the
457 slot value to @var{new-val}.
460 @node Slot Description Example
461 @section Illustrating Slot Description
463 To illustrate slot description, we can redefine the @code{<my-complex>}
464 class seen before. A definition could be:
467 (define-class <my-complex> (<number>)
468 (r #:init-value 0 #:getter get-r #:setter set-r! #:init-keyword #:r)
469 (i #:init-value 0 #:getter get-i #:setter set-i! #:init-keyword #:i))
473 With this definition, the @code{r} and @code{i} slots are set to 0 by
474 default, and can be initialised to other values by calling @code{make}
475 with the @code{#:r} and @code{#:i} keywords. Also the generic functions
476 @code{get-r}, @code{set-r!}, @code{get-i} and @code{set-i!} are
477 automatically defined to read and write the slots.
480 (define c1 (make <my-complex> #:r 1 #:i 2))
481 (get-r c1) @result{} 1
483 (get-r c1) @result{} 12
484 (define c2 (make <my-complex> #:r 2))
485 (get-r c2) @result{} 2
486 (get-i c2) @result{} 0
489 Accessors can both read and write a slot. So, another definition of the
490 @code{<my-complex>} class, using the @code{#:accessor} option, could be:
494 (define-class <my-complex> (<number>)
495 (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
496 (i #:init-value 0 #:accessor imag-part #:init-keyword #:i))
500 With this definition, the @code{r} slot can be read with:
507 (set! (real-part c) new-value)
510 Suppose now that we want to manipulate complex numbers with both
511 rectangular and polar coordinates. One solution could be to have a
512 definition of complex numbers which uses one particular representation
513 and some conversion functions to pass from one representation to the
514 other. A better solution is to use virtual slots, like this:
517 (define-class <my-complex> (<number>)
518 ;; True slots use rectangular coordinates
519 (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
520 (i #:init-value 0 #:accessor imag-part #:init-keyword #:i)
521 ;; Virtual slots access do the conversion
522 (m #:accessor magnitude #:init-keyword #:magn
523 #:allocation #:virtual
524 #:slot-ref (lambda (o)
525 (let ((r (slot-ref o 'r)) (i (slot-ref o 'i)))
526 (sqrt (+ (* r r) (* i i)))))
527 #:slot-set! (lambda (o m)
528 (let ((a (slot-ref o 'a)))
529 (slot-set! o 'r (* m (cos a)))
530 (slot-set! o 'i (* m (sin a))))))
531 (a #:accessor angle #:init-keyword #:angle
532 #:allocation #:virtual
533 #:slot-ref (lambda (o)
534 (atan (slot-ref o 'i) (slot-ref o 'r)))
535 #:slot-set! (lambda(o a)
536 (let ((m (slot-ref o 'm)))
537 (slot-set! o 'r (* m (cos a)))
538 (slot-set! o 'i (* m (sin a)))))))
542 In this class definition, the magniture @code{m} and angle @code{a}
543 slots are virtual, and are calculated, when referenced, from the normal
544 (i.e. @code{#:allocation #:instance}) slots @code{r} and @code{i}, by
545 calling the function defined in the relevant @code{#:slot-ref} option.
546 Correspondingly, writing @code{m} or @code{a} leads to calling the
547 function defined in the @code{#:slot-set!} option. Thus the
557 permits to set the angle of the @code{c} complex number.
560 (define c (make <my-complex> #:r 12 #:i 20))
561 (real-part c) @result{} 12
562 (angle c) @result{} 1.03037682652431
564 (set! (real-part c) 1)
567 #<<my-complex> 401e9b58> is an instance of class <my-complex>
575 Since initialization keywords have been defined for the four slots, we
576 can now define the standard Scheme primitives @code{make-rectangular}
577 and @code{make-polar}.
580 (define make-rectangular
581 (lambda (x y) (make <my-complex> #:r x #:i y)))
584 (lambda (x y) (make <my-complex> #:magn x #:angle y)))
588 @node Methods and Generic Functions
589 @section Methods and Generic Functions
591 A GOOPS method is like a Scheme procedure except that it is specialized
592 for a particular set of argument classes, and will only be used when the
593 actual arguments in a call match the classes in the method definition.
596 (define-method (+ (x <string>) (y <string>))
599 (+ "abc" "de") @result{} "abcde"
602 A method is not formally associated with any single class (as it is in
603 many other object oriented languages), because a method can be
604 specialized for a combination of several classes. If you've studied
605 object orientation in non-Lispy languages, you may remember discussions
606 such as whether a method to stretch a graphical image around a surface
607 should be a method of the image class, with a surface as a parameter, or
608 a method of the surface class, with an image as a parameter. In GOOPS
612 (define-method (stretch (im <image>) (sf <surface>))
617 and the question of which class the method is more associated with does
620 There can simultaneously be several methods with the same name but
621 different sets of specializing argument classes; for example:
624 (define-method (+ (x <string>) (y <string)) ...)
625 (define-method (+ (x <matrix>) (y <matrix>)) ...)
626 (define-method (+ (f <fish>) (b <bicyle>)) ...)
627 (define-method (+ (a <foo>) (b <bar>) (c <baz>)) ...)
631 A generic function is a container for the set of such methods that a
632 program intends to use.
634 If you look at a program's source code, and see @code{(+ x y)} somewhere
635 in it, conceptually what is happening is that the program at that point
636 calls a generic function (in this case, the generic function bound to
637 the identifier @code{+}). When that happens, Guile works out which of
638 the generic function's methods is the most appropriate for the arguments
639 that the function is being called with; then it evaluates the method's
640 code with the arguments as formal parameters. This happens every time
641 that a generic function call is evaluated --- it isn't assumed that a
642 given source code call will end up invoking the same method every time.
644 Defining an identifier as a generic function is done with the
645 @code{define-generic} macro. Definition of a new method is done with
646 the @code{define-method} macro. Note that @code{define-method}
647 automatically does a @code{define-generic} if the identifier concerned
648 is not already a generic function, so often an explicit
649 @code{define-generic} call is not needed.
650 @findex define-generic
651 @findex define-method
653 @deffn syntax define-generic symbol
654 Create a generic function with name @var{symbol} and bind it to the
655 variable @var{symbol}. If @var{symbol} was previously bound to a Scheme
656 procedure (or procedure-with-setter), the old procedure (and setter) is
657 incorporated into the new generic function as its default procedure (and
658 setter). Any other previous value, including an existing generic
659 function, is discarded and replaced by a new, empty generic function.
662 @deffn syntax define-method (generic parameter @dots{}) . body
663 Define a method for the generic function or accessor @var{generic} with
664 parameters @var{parameter}s and body @var{body}.
666 @var{generic} is a generic function. If @var{generic} is a variable
667 which is not yet bound to a generic function object, the expansion of
668 @code{define-method} will include a call to @code{define-generic}. If
669 @var{generic} is @code{(setter @var{generic-with-setter})}, where
670 @var{generic-with-setter} is a variable which is not yet bound to a
671 generic-with-setter object, the expansion will include a call to
672 @code{define-accessor}.
674 Each @var{parameter} must be either a symbol or a two-element list
675 @code{(@var{symbol} @var{class})}. The symbols refer to variables in
676 the @var{body} that will be bound to the parameters supplied by the
677 caller when calling this method. The @var{class}es, if present,
678 specify the possible combinations of parameters to which this method
681 @var{body} is the body of the method definition.
684 @code{define-method} expressions look a little like Scheme procedure
685 definitions of the form
688 (define (name formals @dots{}) . body)
691 The important difference is that each formal parameter, apart from the
692 possible ``rest'' argument, can be qualified by a class name:
693 @code{@var{formal}} becomes @code{(@var{formal} @var{class})}. The
694 meaning of this qualification is that the method being defined
695 will only be applicable in a particular generic function invocation if
696 the corresponding argument is an instance of @code{@var{class}} (or one of
697 its subclasses). If more than one of the formal parameters is qualified
698 in this way, then the method will only be applicable if each of the
699 corresponding arguments is an instance of its respective qualifying class.
701 Note that unqualified formal parameters act as though they are qualified
702 by the class @code{<top>}, which GOOPS uses to mean the superclass of
703 all valid Scheme types, including both primitive types and GOOPS classes.
705 For example, if a generic function method is defined with
706 @var{parameter}s @code{(s1 <square>)} and @code{(n <number>)}, that
707 method is only applicable to invocations of its generic function that
708 have two parameters where the first parameter is an instance of the
709 @code{<square>} class and the second parameter is a number.
713 * Extending Primitives::
716 * Generic Function and Method Examples::
717 * Handling Invocation Errors::
722 @subsection Accessors
724 An accessor is a generic function that can also be used with the
725 generalized @code{set!} syntax (@pxref{Procedures with Setters}). Guile
726 will handle a call like
729 (set! (@code{accessor} @code{args}@dots{}) @code{value})
733 by calling the most specialized method of @code{accessor} that matches
734 the classes of @code{args} and @code{value}. @code{define-accessor} is
735 used to bind an identifier to an accessor.
737 @deffn syntax define-accessor symbol
738 Create an accessor with name @var{symbol} and bind it to the variable
739 @var{symbol}. If @var{symbol} was previously bound to a Scheme
740 procedure (or procedure-with-setter), the old procedure (and setter) is
741 incorporated into the new accessor as its default procedure (and
742 setter). Any other previous value, including an existing generic
743 function or accessor, is discarded and replaced by a new, empty
748 @node Extending Primitives
749 @subsection Extending Primitives
751 Many of Guile's primitive procedures can be extended by giving them a
752 generic function definition that operates in conjunction with their
753 normal C-coded implementation. When a primitive is extended in this
754 way, it behaves like a generic function with the C-coded implementation
755 as its default method.
757 This extension happens automatically if a method is defined (by a
758 @code{define-method} call) for a variable whose current value is a
759 primitive. But it can also be forced by calling
760 @code{enable-primitive-generic!}.
762 @deffn {primitive procedure} enable-primitive-generic! primitive
763 Force the creation of a generic function definition for
767 Once the generic function definition for a primitive has been created,
768 it can be retrieved using @code{primitive-generic-generic}.
770 @deffn {primitive procedure} primitive-generic-generic primitive
771 Return the generic function definition of @var{primitive}.
773 @code{primitive-generic-generic} raises an error if @var{primitive}
774 is not a primitive with generic capability.
777 @node Merging Generics
778 @subsection Merging Generics
780 GOOPS generic functions and accessors often have short, generic names.
781 For example, if a vector package provides an accessor for the X
782 coordinate of a vector, that accessor may just be called @code{x}. It
783 doesn't need to be called, for example, @code{vector:x}, because
784 GOOPS will work out, when it sees code like @code{(x @var{obj})}, that
785 the vector-specific method of @code{x} should be called if @var{obj} is
788 That raises the question, though, of what happens when different
789 packages define a generic function with the same name. Suppose we work
790 with a graphical package which needs to use two independent vector
791 packages for 2D and 3D vectors respectively. If both packages export
792 @code{x}, what does the code using those packages end up with?
794 @ref{Creating Guile Modules,,duplicate binding handlers} explains how
795 this is resolved for conflicting bindings in general. For generics,
796 there is a special duplicates handler, @code{merge-generics}, which
797 tells the module system to merge generic functions with the same name.
801 (define-module (math 2D-vectors)
802 #:use-module (oop goops)
805 (define-module (math 3D-vectors)
806 #:use-module (oop goops)
807 #:export (x y z ...))
809 (define-module (my-module)
810 #:use-module (math 2D-vectors)
811 #:use-module (math 3D-vectors)
812 #:duplicates merge-generics)
815 The generic function @code{x} in @code{(my-module)} will now incorporate
816 all of the methods of @code{x} from both imported modules.
818 To be precise, there will now be three distinct generic functions named
819 @code{x}: @code{x} in @code{(math 2D-vectors)}, @code{x} in @code{(math
820 3D-vectors)}, and @code{x} in @code{(my-module)}; and these functions
821 share their methods in an interesting and dynamic way.
823 To explain, let's call the imported generic functions (in @code{(math
824 2D-vectors)} and @code{(math 3D-vectors)}) the @dfn{ancestors}, and the
825 merged generic function (in @code{(my-module)}), the @dfn{descendant}.
826 The general rule is that for any generic function G, the applicable
827 methods are selected from the union of the methods of G's descendant
828 functions, the methods of G itself and the methods of G's ancestor
831 Thus ancestor functions effectively share methods with their
832 descendants, and vice versa. In the example above, @code{x} in
833 @code{(math 2D-vectors)} will share the methods of @code{x} in
834 @code{(my-module)} and vice versa.@footnote{But note that @code{x} in
835 @code{(math 2D-vectors)} doesn't share methods with @code{x} in
836 @code{(math 3D-vectors)}, so modularity is still preserved.} Sharing is
837 dynamic, so adding another new method to a descendant implies adding it
838 to that descendant's ancestors too.
841 @subsection Next-method
843 When you call a generic function, with a particular set of arguments,
844 GOOPS builds a list of all the methods that are applicable to those
845 arguments and orders them by how closely the method definitions match
846 the actual argument types. It then calls the method at the top of this
847 list. If the selected method's code wants to call on to the next method
848 in this list, it can do so by using @code{next-method}.
851 (define-method (Test (a <integer>)) (cons 'integer (next-method)))
852 (define-method (Test (a <number>)) (cons 'number (next-method)))
853 (define-method (Test a) (list 'top))
856 With these definitions,
859 (Test 1) @result{} (integer number top)
860 (Test 1.0) @result{} (number top)
861 (Test #t) @result{} (top)
864 @code{next-method} is always called as just @code{(next-method)}. The
865 arguments for the next method call are always implicit, and always the
866 same as for the original method call.
868 If you want to call on to a method with the same name but with a
869 different set of arguments (as you might with overloaded methods in C++,
870 for example), you do not use @code{next-method}, but instead simply
871 write the new call as usual:
874 (define-method (Test (a <number>) min max)
875 (if (and (>= a min) (<= a max))
876 (display "Number is in range\n"))
886 (You should be careful in this case that the @code{Test} calls do not
887 lead to an infinite recursion, but this consideration is just the same
888 as in Scheme code in general.)
890 @node Generic Function and Method Examples
891 @subsection Generic Function and Method Examples
893 Consider the following definitions:
897 (define-method (G (a <integer>) b) 'integer)
898 (define-method (G (a <real>) b) 'real)
899 (define-method (G a b) 'top)
902 The @code{define-generic} call defines @var{G} as a generic function.
903 The three next lines define methods for @var{G}. Each method uses a
904 sequence of @dfn{parameter specializers} that specify when the given
905 method is applicable. A specializer permits to indicate the class a
906 parameter must belong to (directly or indirectly) to be applicable. If
907 no specializer is given, the system defaults it to @code{<top>}. Thus,
908 the first method definition is equivalent to
910 @cindex parameter specializers
912 (define-method (G (a <integer>) (b <top>)) 'integer)
915 Now, let's look at some possible calls to the generic function @var{G}:
918 (G 2 3) @result{} integer
919 (G 2 #t) @result{} integer
920 (G 1.2 'a) @result{} real
921 @c (G #3 'a) @result{} real @c was {\sharpsign}
922 (G #t #f) @result{} top
923 (G 1 2 3) @result{} error (since no method exists for 3 parameters)
926 The methods above use only one specializer per parameter list. But in
927 general, any or all of a method's parameters may be specialized.
928 Suppose we define now:
931 (define-method (G (a <integer>) (b <number>)) 'integer-number)
932 (define-method (G (a <integer>) (b <real>)) 'integer-real)
933 (define-method (G (a <integer>) (b <integer>)) 'integer-integer)
934 (define-method (G a (b <number>)) 'top-number)
937 @noindent With these definitions:
940 (G 1 2) @result{} integer-integer
941 (G 1 1.0) @result{} integer-real
942 (G 1 #t) @result{} integer
943 (G 'a 1) @result{} top-number
946 As a further example we shall continue to define operations on the
947 @code{<my-complex>} class. Suppose that we want to use it to implement
948 complex numbers completely. For instance a definition for the addition
949 of two complex numbers could be
952 (define-method (new-+ (a <my-complex>) (b <my-complex>))
953 (make-rectangular (+ (real-part a) (real-part b))
954 (+ (imag-part a) (imag-part b))))
957 To be sure that the @code{+} used in the method @code{new-+} is the
958 standard addition we can do:
961 (define-generic new-+)
964 (define-method (new-+ (a <my-complex>) (b <my-complex>))
965 (make-rectangular (+ (real-part a) (real-part b))
966 (+ (imag-part a) (imag-part b)))))
969 The @code{define-generic} ensures here that @code{new-+} will be defined
970 in the global environment. Once this is done, we can add methods to the
971 generic function @code{new-+} which make a closure on the @code{+}
972 symbol. A complete writing of the @code{new-+} methods is shown in
975 @float Figure,fig:newplus
977 (define-generic new-+)
981 (define-method (new-+ (a <real>) (b <real>)) (+ a b))
983 (define-method (new-+ (a <real>) (b <my-complex>))
984 (make-rectangular (+ a (real-part b)) (imag-part b)))
986 (define-method (new-+ (a <my-complex>) (b <real>))
987 (make-rectangular (+ (real-part a) b) (imag-part a)))
989 (define-method (new-+ (a <my-complex>) (b <my-complex>))
990 (make-rectangular (+ (real-part a) (real-part b))
991 (+ (imag-part a) (imag-part b))))
993 (define-method (new-+ (a <number>)) a)
995 (define-method (new-+) 0)
997 (define-method (new-+ . args)
999 (apply new-+ (cdr args)))))
1004 @caption{Extending @code{+} to handle complex numbers}
1007 We take advantage here of the fact that generic function are not obliged
1008 to have a fixed number of parameters. The four first methods implement
1009 dyadic addition. The fifth method says that the addition of a single
1010 element is this element itself. The sixth method says that using the
1011 addition with no parameter always return 0 (as is also true for the
1012 primitive @code{+}). The last method takes an arbitrary number of
1013 parameters@footnote{The parameter list for a @code{define-method}
1014 follows the conventions used for Scheme procedures. In particular it can
1015 use the dot notation or a symbol to denote an arbitrary number of
1016 parameters}. This method acts as a kind of @code{reduce}: it calls the
1017 dyadic addition on the @emph{car} of the list and on the result of
1018 applying it on its rest. To finish, the @code{set!} permits to redefine
1019 the @code{+} symbol to our extended addition.
1021 To conclude our implementation (integration?) of complex numbers, we
1022 could redefine standard Scheme predicates in the following manner:
1025 (define-method (complex? c <my-complex>) #t)
1026 (define-method (complex? c) #f)
1028 (define-method (number? n <number>) #t)
1029 (define-method (number? n) #f)
1033 Standard primitives in which complex numbers are involved could also be
1034 redefined in the same manner.
1037 @node Handling Invocation Errors
1038 @subsection Handling Invocation Errors
1040 If a generic function is invoked with a combination of parameters for
1041 which there is no applicable method, GOOPS raises an error.
1043 @deffn generic no-method
1044 @deffnx method no-method (gf <generic>) args
1045 When an application invokes a generic function, and no methods at all
1046 have been defined for that generic function, GOOPS calls the
1047 @code{no-method} generic function. The default method calls
1048 @code{goops-error} with an appropriate message.
1051 @deffn generic no-applicable-method
1052 @deffnx method no-applicable-method (gf <generic>) args
1053 When an application applies a generic function to a set of arguments,
1054 and no methods have been defined for those argument types, GOOPS calls
1055 the @code{no-applicable-method} generic function. The default method
1056 calls @code{goops-error} with an appropriate message.
1059 @deffn generic no-next-method
1060 @deffnx method no-next-method (gf <generic>) args
1061 When a generic function method calls @code{(next-method)} to invoke the
1062 next less specialized method for that generic function, and no less
1063 specialized methods have been defined for the current generic function
1064 arguments, GOOPS calls the @code{no-next-method} generic function. The
1065 default method calls @code{goops-error} with an appropriate message.
1070 @section Inheritance
1072 Here are some class definitions to help illustrate inheritance:
1075 (define-class A () a)
1076 (define-class B () b)
1077 (define-class C () c)
1078 (define-class D (A B) d a)
1079 (define-class E (A C) e c)
1080 (define-class F (D E) f)
1083 @code{A}, @code{B}, @code{C} have a null list of superclasses. In this
1084 case, the system will replace the null list by a list which only
1085 contains @code{<object>}, the root of all the classes defined by
1086 @code{define-class}. @code{D}, @code{E}, @code{F} use multiple
1087 inheritance: each class inherits from two previously defined classes.
1088 Those class definitions define a hierarchy which is shown in
1089 @ref{fig:hier}. In this figure, the class @code{<top>} is also shown;
1090 this class is the superclass of all Scheme objects. In particular,
1091 @code{<top>} is the superclass of all standard Scheme
1092 types.@footnote{@code{<complex>}, which is the direct subclass of
1093 @code{<number>} and the direct superclass of @code{<real>}, has been
1094 omitted in this figure.}
1096 @float Figure,fig:hier
1098 @center @image{hierarchy,5in}
1101 @verbatiminclude hierarchy.txt
1104 @caption{A class hierarchy.}
1107 When a class has superclasses, its set of slots is calculated by taking
1108 the union of its own slots and those of all its superclasses. Thus each
1109 instance of D will have three slots, @code{a}, @code{b} and
1110 @code{d}). The slots of a class can be discovered using the
1111 @code{class-slots} primitive. For instance,
1114 (class-slots A) @result{} ((a))
1115 (class-slots E) @result{} ((a) (e) (c))
1116 (class-slots F) @result{} ((e) (c) (b) (d) (a) (f))
1120 The ordering of the returned slots is not significant.
1123 * Class Precedence List::
1128 @node Class Precedence List
1129 @subsection Class Precedence List
1131 What happens when a class inherits from two or more superclasses that
1132 have a slot with the same name but incompatible definitions --- for
1133 example, different init values or slot allocations? We need a rule for
1134 deciding which slot definition the derived class ends up with, and this
1135 rule is provided by the class's @dfn{Class Precedence
1136 List}.@footnote{This section is an adaptation of material from Jeff
1137 Dalton's (J.Dalton@@ed.ac.uk) @cite{Brief introduction to CLOS}}
1139 Another problem arises when invoking a generic function, and there is
1140 more than one method that could apply to the call arguments. Here we
1141 need a way of ordering the applicable methods, so that Guile knows which
1142 method to use first, which to use next if that method calls
1143 @code{next-method}, and so on. One of the ingredients for this ordering
1144 is determining, for each given call argument, which of the specializing
1145 classes, from each applicable method's definition, is the most specific
1146 for that argument; and here again the class precedence list helps.
1148 If inheritance was restricted such that each class could only have one
1149 superclass --- which is known as @dfn{single} inheritance --- class
1150 ordering would be easy. The rule would be simply that a subclass is
1151 considered more specific than its superclass.
1153 With multiple inheritance, ordering is less obvious, and we have to
1154 impose an arbitrary rule to determine precedence. Suppose we have
1163 (define-class Z (X Y)
1168 Clearly the @code{Z} class is more specific than @code{X} or @code{Y},
1169 for instances of @code{Z}. But which is more specific out of @code{X}
1170 and @code{Y} --- and hence, for the definitions above, which
1171 @code{#:init-value} will take effect when creating an instance of
1172 @code{Z}? The rule in @goops{} is that the superclasses listed earlier
1173 are more specific than those listed later. Hence @code{X} is more
1174 specific than @code{Y}, and the @code{#:init-value} for slot @code{x} in
1175 instances of @code{Z} will be 1.
1177 Hence there is a linear ordering for a class and all its
1178 superclasses, from most specific to least specific, and this ordering is
1179 called the Class Precedence List of the class.
1181 In fact the rules above are not quite enough to always determine a
1182 unique order, but they give an idea of how things work. For example,
1183 for the @code{F} class shown in @ref{fig:hier}, the class precedence
1187 (f d e a c b <object> <top>)
1191 In cases where there is any ambiguity (like this one), it is a bad idea
1192 for programmers to rely on exactly what the order is. If the order for
1193 some superclasses is important, it can be expressed directly in the
1196 The precedence list of a class can be obtained by calling
1197 @code{class-precedence-list}. This function returns a ordered list
1198 whose first element is the most specific class. For instance:
1201 (class-precedence-list B) @result{} (#<<class> B 401b97c8>
1202 #<<class> <object> 401e4a10>
1203 #<<class> <top> 4026a9d8>)
1207 Or for a more immediately readable result:
1210 (map class-name (class-precedence-list B)) @result{} (B <object> <top>)
1214 @node Sorting Methods
1215 @subsection Sorting Methods
1217 Now, with the idea of the class precedence list, we can state precisely
1218 how the possible methods are sorted when more than one of the methods of
1219 a generic function are applicable to the call arguments.
1224 the applicable methods are sorted in order of specificity, and the most
1225 specific method is used first, then the next if that method calls
1226 @code{next-method}, and so on
1229 a method M1 is more specific than another method M2 if the first
1230 specializing class that differs, between the definitions of M1 and M2,
1231 is more specific, in M1's definition, for the corresponding actual call
1232 argument, than the specializing class in M2's definition
1235 a class C1 is more specific than another class C2, for an object of
1236 actual class C, if C1 comes before C2 in C's class precedence list.
1241 @section Introspection
1243 @dfn{Introspection}, or @dfn{reflection}, means being able to obtain
1244 information dynamically about GOOPS objects. It is perhaps best
1245 illustrated by considering an object oriented language that does not
1246 provide any introspection, namely C++.
1248 Nothing in C++ allows a running program to obtain answers to the following
1253 What are the data members of this object or class?
1256 What classes does this class inherit from?
1259 Is this method call virtual or non-virtual?
1262 If I invoke @code{Employee::adjustHoliday()}, what class contains the
1263 @code{adjustHoliday()} method that will be applied?
1266 In C++, answers to such questions can only be determined by looking at
1267 the source code, if you have access to it. GOOPS, on the other hand,
1268 includes procedures that allow answers to these questions --- or their
1269 GOOPS equivalents --- to be obtained dynamically, at run time.
1275 * Generic Functions::
1281 A GOOPS class is itself an instance of the @code{<class>} class, or of a
1282 subclass of @code{<class>}. The definition of the @code{<class>} class
1283 has slots that are used to describe the properties of a class, including
1286 @deffn {primitive procedure} class-name class
1287 Return the name of class @var{class}. This is the value of
1288 @var{class}'s @code{name} slot.
1291 @deffn {primitive procedure} class-direct-supers class
1292 Return a list containing the direct superclasses of @var{class}. This
1293 is the value of @var{class}'s @code{direct-supers} slot.
1296 @deffn {primitive procedure} class-direct-slots class
1297 Return a list containing the slot definitions of the direct slots of
1298 @var{class}. This is the value of @var{class}'s @code{direct-slots}
1302 @deffn {primitive procedure} class-direct-subclasses class
1303 Return a list containing the direct subclasses of @var{class}. This is
1304 the value of @var{class}'s @code{direct-subclasses} slot.
1307 @deffn {primitive procedure} class-direct-methods class
1308 Return a list of all the generic function methods that use @var{class}
1309 as a formal parameter specializer. This is the value of @var{class}'s
1310 @code{direct-methods} slot.
1313 @deffn {primitive procedure} class-precedence-list class
1314 Return the class precedence list for class @var{class} (@pxref{Class
1315 Precedence List}). This is the value of @var{class}'s @code{cpl} slot.
1318 @deffn {primitive procedure} class-slots class
1319 Return a list containing the slot definitions for all @var{class}'s
1320 slots, including any slots that are inherited from superclasses. This
1321 is the value of @var{class}'s @code{slots} slot.
1324 @deffn procedure class-subclasses class
1325 Return a list of all subclasses of @var{class}.
1328 @deffn procedure class-methods class
1329 Return a list of all methods that use @var{class} or a subclass of
1330 @var{class} as one of its formal parameter specializers.
1337 @deffn procedure class-slot-definition class slot-name
1338 Return the slot definition for the slot named @var{slot-name} in class
1339 @var{class}. @var{slot-name} should be a symbol.
1342 @deffn procedure slot-definition-name slot-def
1343 Extract and return the slot name from @var{slot-def}.
1346 @deffn procedure slot-definition-options slot-def
1347 Extract and return the slot options from @var{slot-def}.
1350 @deffn procedure slot-definition-allocation slot-def
1351 Extract and return the slot allocation option from @var{slot-def}. This
1352 is the value of the @code{#:allocation} keyword (@pxref{Slot Options,,
1353 allocation}), or @code{#:instance} if the @code{#:allocation} keyword is
1357 @deffn procedure slot-definition-getter slot-def
1358 Extract and return the slot getter option from @var{slot-def}. This is
1359 the value of the @code{#:getter} keyword (@pxref{Slot Options,,
1360 getter}), or @code{#f} if the @code{#:getter} keyword is absent.
1363 @deffn procedure slot-definition-setter slot-def
1364 Extract and return the slot setter option from @var{slot-def}. This is
1365 the value of the @code{#:setter} keyword (@pxref{Slot Options,,
1366 setter}), or @code{#f} if the @code{#:setter} keyword is absent.
1369 @deffn procedure slot-definition-accessor slot-def
1370 Extract and return the slot accessor option from @var{slot-def}. This
1371 is the value of the @code{#:accessor} keyword (@pxref{Slot Options,,
1372 accessor}), or @code{#f} if the @code{#:accessor} keyword is absent.
1375 @deffn procedure slot-definition-init-value slot-def
1376 Extract and return the slot init-value option from @var{slot-def}. This
1377 is the value of the @code{#:init-value} keyword (@pxref{Slot Options,,
1378 init-value}), or the unbound value if the @code{#:init-value} keyword is
1382 @deffn procedure slot-definition-init-form slot-def
1383 Extract and return the slot init-form option from @var{slot-def}. This
1384 is the value of the @code{#:init-form} keyword (@pxref{Slot Options,,
1385 init-form}), or the unbound value if the @code{#:init-form} keyword is
1389 @deffn procedure slot-definition-init-thunk slot-def
1390 Extract and return the slot init-thunk option from @var{slot-def}. This
1391 is the value of the @code{#:init-thunk} keyword (@pxref{Slot Options,,
1392 init-thunk}), or @code{#f} if the @code{#:init-thunk} keyword is absent.
1395 @deffn procedure slot-definition-init-keyword slot-def
1396 Extract and return the slot init-keyword option from @var{slot-def}.
1397 This is the value of the @code{#:init-keyword} keyword (@pxref{Slot
1398 Options,, init-keyword}), or @code{#f} if the @code{#:init-keyword}
1402 @deffn procedure slot-init-function class slot-name
1403 Return the initialization function for the slot named @var{slot-name} in
1404 class @var{class}. @var{slot-name} should be a symbol.
1406 The returned initialization function incorporates the effects of the
1407 standard @code{#:init-thunk}, @code{#:init-form} and @code{#:init-value}
1408 slot options. These initializations can be overridden by the
1409 @code{#:init-keyword} slot option or by a specialized @code{initialize}
1410 method, so, in general, the function returned by
1411 @code{slot-init-function} may be irrelevant. For a fuller discussion,
1412 see @ref{Slot Options,, init-value}.
1416 @subsection Instances
1418 @deffn {primitive procedure} class-of value
1419 Return the GOOPS class of any Scheme @var{value}.
1422 @deffn {primitive procedure} instance? object
1423 Return @code{#t} if @var{object} is any GOOPS instance, otherwise
1427 @deffn procedure is-a? object class
1428 Return @code{#t} if @var{object} is an instance of @var{class} or one of
1432 You can use the @code{is-a?} predicate to ask whether any given value
1433 belongs to a given class, or @code{class-of} to discover the class of a
1434 given value. Note that when GOOPS is loaded (by code using the
1435 @code{(oop goops)} module) built-in classes like @code{<string>},
1436 @code{<list>} and @code{<number>} are automatically set up,
1437 corresponding to all Guile Scheme types.
1440 (is-a? 2.3 <number>) @result{} #t
1441 (is-a? 2.3 <real>) @result{} #t
1442 (is-a? 2.3 <string>) @result{} #f
1443 (is-a? '("a" "b") <string>) @result{} #f
1444 (is-a? '("a" "b") <list>) @result{} #t
1445 (is-a? (car '("a" "b")) <string>) @result{} #t
1446 (is-a? <string> <class>) @result{} #t
1447 (is-a? <class> <string>) @result{} #f
1449 (class-of 2.3) @result{} #<<class> <real> 908c708>
1450 (class-of #(1 2 3)) @result{} #<<class> <vector> 908cd20>
1451 (class-of <string>) @result{} #<<class> <class> 8bd3e10>
1452 (class-of <class>) @result{} #<<class> <class> 8bd3e10>
1456 @node Generic Functions
1457 @subsection Generic Functions
1459 A generic function is an instance of the @code{<generic>} class, or of a
1460 subclass of @code{<generic>}. The definition of the @code{<generic>}
1461 class has slots that are used to describe the properties of a generic
1464 @deffn {primitive procedure} generic-function-name gf
1465 Return the name of generic function @var{gf}.
1468 @deffn {primitive procedure} generic-function-methods gf
1469 Return a list of the methods of generic function @var{gf}. This is the
1470 value of @var{gf}'s @code{methods} slot.
1473 Similarly, a method is an instance of the @code{<method>} class, or of a
1474 subclass of @code{<method>}; and the definition of the @code{<method>}
1475 class has slots that are used to describe the properties of a method.
1477 @deffn {primitive procedure} method-generic-function method
1478 Return the generic function that @var{method} belongs to. This is the
1479 value of @var{method}'s @code{generic-function} slot.
1482 @deffn {primitive procedure} method-specializers method
1483 Return a list of @var{method}'s formal parameter specializers . This is
1484 the value of @var{method}'s @code{specializers} slot.
1487 @deffn {primitive procedure} method-procedure method
1488 Return the procedure that implements @var{method}. This is the value of
1489 @var{method}'s @code{procedure} slot.
1492 @deffn generic method-source
1493 @deffnx method method-source (m <method>)
1494 Return an expression that prints to show the definition of method
1498 (define-generic cube)
1500 (define-method (cube (n <number>))
1503 (map method-source (generic-function-methods cube))
1505 ((method ((n <number>)) (* n n n)))
1511 @section Class Options
1513 @deffn {class option} #:metaclass metaclass
1514 The @code{#:metaclass} class option specifies the metaclass of the class
1515 being defined. @var{metaclass} must be a class that inherits from
1516 @code{<class>}. For the use of metaclasses, see @ref{Metaobjects and
1517 the Metaobject Protocol} and @ref{Terminology}.
1519 If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
1520 metaclass for the new class by calling @code{ensure-metaclass}
1521 (@pxref{Class Definition Internals,, ensure-metaclass}).
1524 @deffn {class option} #:name name
1525 The @code{#:name} class option specifies the new class's name. This
1526 name is used to identify the class whenever related objects - the class
1527 itself, its instances and its subclasses - are printed.
1529 If the @code{#:name} option is absent, GOOPS uses the first argument to
1530 @code{define-class} as the class name.
1533 @node Accessing Slots
1534 @section Accessing Slots
1539 * Handling Slot Access Errors::
1542 @node Instance Slots
1543 @subsection Instance Slots
1545 Any slot, regardless of its allocation, can be queried, referenced and
1546 set using the following four primitive procedures.
1548 @deffn {primitive procedure} slot-exists? obj slot-name
1549 Return @code{#t} if @var{obj} has a slot with name @var{slot-name},
1550 otherwise @code{#f}.
1553 @deffn {primitive procedure} slot-bound? obj slot-name
1554 Return @code{#t} if the slot named @var{slot-name} in @var{obj} has a
1555 value, otherwise @code{#f}.
1557 @code{slot-bound?} calls the generic function @code{slot-missing} if
1558 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1559 Slot Access Errors, slot-missing}).
1562 @deffn {primitive procedure} slot-ref obj slot-name
1563 Return the value of the slot named @var{slot-name} in @var{obj}.
1565 @code{slot-ref} calls the generic function @code{slot-missing} if
1566 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1567 Slot Access Errors, slot-missing}).
1569 @code{slot-ref} calls the generic function @code{slot-unbound} if the
1570 named slot in @var{obj} does not have a value (@pxref{Handling Slot
1571 Access Errors, slot-unbound}).
1574 @deffn {primitive procedure} slot-set! obj slot-name value
1575 Set the value of the slot named @var{slot-name} in @var{obj} to @var{value}.
1577 @code{slot-set!} calls the generic function @code{slot-missing} if
1578 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1579 Slot Access Errors, slot-missing}).
1582 GOOPS stores information about slots in classes. Internally,
1583 all of these procedures work by looking up the slot definition for the
1584 slot named @var{slot-name} in the class @code{(class-of
1585 @var{obj})}, and then using the slot definition's ``getter'' and
1586 ``setter'' closures to get and set the slot value.
1588 The next four procedures differ from the previous ones in that they take
1589 the class as an explicit argument, rather than assuming
1590 @code{(class-of @var{obj})}. Therefore they allow you to apply the
1591 ``getter'' and ``setter'' closures of a slot definition in one class to
1592 an instance of a different class.
1594 @deffn {primitive procedure} slot-exists-using-class? class obj slot-name
1595 Return @code{#t} if @var{class} has a slot definition for a slot with
1596 name @var{slot-name}, otherwise @code{#f}.
1599 @deffn {primitive procedure} slot-bound-using-class? class obj slot-name
1600 Return @code{#t} if applying @code{slot-ref-using-class} to the same
1601 arguments would call the generic function @code{slot-unbound}, otherwise
1604 @code{slot-bound-using-class?} calls the generic function
1605 @code{slot-missing} if @var{class} does not have a slot definition for a
1606 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1610 @deffn {primitive procedure} slot-ref-using-class class obj slot-name
1611 Apply the ``getter'' closure for the slot named @var{slot-name} in
1612 @var{class} to @var{obj}, and return its result.
1614 @code{slot-ref-using-class} calls the generic function
1615 @code{slot-missing} if @var{class} does not have a slot definition for a
1616 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1619 @code{slot-ref-using-class} calls the generic function
1620 @code{slot-unbound} if the application of the ``getter'' closure to
1621 @var{obj} returns an unbound value (@pxref{Handling Slot Access Errors,
1625 @deffn {primitive procedure} slot-set-using-class! class obj slot-name value
1626 Apply the ``setter'' closure for the slot named @var{slot-name} in
1627 @var{class} to @var{obj} and @var{value}.
1629 @code{slot-set-using-class!} calls the generic function
1630 @code{slot-missing} if @var{class} does not have a slot definition for a
1631 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1636 @subsection Class Slots
1638 Slots whose allocation is per-class rather than per-instance can be
1639 referenced and set without needing to specify any particular instance.
1641 @deffn procedure class-slot-ref class slot-name
1642 Return the value of the slot named @var{slot-name} in class @var{class}.
1643 The named slot must have @code{#:class} or @code{#:each-subclass}
1644 allocation (@pxref{Slot Options,, allocation}).
1646 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1647 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1648 function with arguments @var{class} and @var{slot-name}. Otherwise, if
1649 the slot value is unbound, @code{class-slot-ref} calls the
1650 @code{slot-unbound} generic function, with the same arguments.
1653 @deffn procedure class-slot-set! class slot-name value
1654 Set the value of the slot named @var{slot-name} in class @var{class} to
1655 @var{value}. The named slot must have @code{#:class} or
1656 @code{#:each-subclass} allocation (@pxref{Slot Options,, allocation}).
1658 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1659 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1660 function with arguments @var{class} and @var{slot-name}.
1663 @node Handling Slot Access Errors
1664 @subsection Handling Slot Access Errors
1666 GOOPS calls one of the following generic functions when a ``slot-ref''
1667 or ``slot-set!'' call specifies a non-existent slot name, or tries to
1668 reference a slot whose value is unbound.
1670 @deffn generic slot-missing
1671 @deffnx method slot-missing (class <class>) slot-name
1672 @deffnx method slot-missing (class <class>) (object <object>) slot-name
1673 @deffnx method slot-missing (class <class>) (object <object>) slot-name value
1674 When an application attempts to reference or set a class or instance
1675 slot by name, and the slot name is invalid for the specified @var{class}
1676 or @var{object}, GOOPS calls the @code{slot-missing} generic function.
1678 The default methods all call @code{goops-error} with an appropriate
1682 @deffn generic slot-unbound
1683 @deffnx method slot-unbound (object <object>)
1684 @deffnx method slot-unbound (class <class>) slot-name
1685 @deffnx method slot-unbound (class <class>) (object <object>) slot-name
1686 When an application attempts to reference a class or instance slot, and
1687 the slot's value is unbound, GOOPS calls the @code{slot-unbound} generic
1690 The default methods all call @code{goops-error} with an appropriate
1694 @node Generic Functions and Accessors
1695 @section Generic Functions and Accessors
1697 A generic function is a collection of methods, with rules for
1698 determining which of the methods should be applied for any given
1699 invocation of the generic function. GOOPS represents generic functions
1700 as metaobjects of the class @code{<generic>} (or one of its subclasses).
1703 * Determining Which Methods to Apply::
1706 @node Determining Which Methods to Apply
1707 @subsection Determining Which Methods to Apply
1709 [ *fixme* Sorry - this is the area of GOOPS that I understand least of
1710 all, so I'm afraid I have to pass on this section. Would some other
1711 kind person consider filling it in? ]
1713 @deffn generic apply-generic
1714 @deffnx method apply-generic (gf <generic>) args
1717 @deffn generic compute-applicable-methods
1718 @deffnx method compute-applicable-methods (gf <generic>) args
1721 @deffn generic sort-applicable-methods
1722 @deffnx method sort-applicable-methods (gf <generic>) methods args
1725 @deffn generic method-more-specific?
1726 @deffnx method method-more-specific? (m1 <method>) (m2 <method>) args
1729 @deffn generic apply-method
1730 @deffnx method apply-method (gf <generic>) methods build-next args
1733 @deffn generic apply-methods
1734 @deffnx method apply-methods (gf <generic>) (l <list>) args
1737 @node Redefining a Class
1738 @section Redefining a Class
1740 Suppose that a class @code{<my-class>} is defined using @code{define-class}
1741 (@pxref{Class Definition,, define-class}), with slots that have
1742 accessor functions, and that an application has created several instances
1743 of @code{<my-class>} using @code{make} (@pxref{Instance Creation,,
1744 make}). What then happens if @code{<my-class>} is redefined by calling
1745 @code{define-class} again?
1748 * Default Class Redefinition Behaviour::
1749 * Customizing Class Redefinition::
1752 @node Default Class Redefinition Behaviour
1753 @subsection Default Class Redefinition Behaviour
1755 GOOPS' default answer to this question is as follows.
1759 All existing direct instances of @code{<my-class>} are converted to be
1760 instances of the new class. This is achieved by preserving the values
1761 of slots that exist in both the old and new definitions, and
1762 initializing the values of new slots in the usual way (@pxref{Instance
1766 All existing subclasses of @code{<my-class>} are redefined, as though
1767 the @code{define-class} expressions that defined them were re-evaluated
1768 following the redefinition of @code{<my-class>}, and the class
1769 redefinition process described here is applied recursively to the
1770 redefined subclasses.
1773 Once all of its instances and subclasses have been updated, the class
1774 metaobject previously bound to the variable @code{<my-class>} is no
1775 longer needed and so can be allowed to be garbage collected.
1778 To keep things tidy, GOOPS also needs to do a little housekeeping on
1779 methods that are associated with the redefined class.
1783 Slot accessor methods for slots in the old definition should be removed
1784 from their generic functions. They will be replaced by accessor methods
1785 for the slots of the new class definition.
1788 Any generic function method that uses the old @code{<my-class>} metaobject
1789 as one of its formal parameter specializers must be updated to refer to
1790 the new @code{<my-class>} metaobject. (Whenever a new generic function
1791 method is defined, @code{define-method} adds the method to a list stored
1792 in the class metaobject for each class used as a formal parameter
1793 specializer, so it is easy to identify all the methods that must be
1794 updated when a class is redefined.)
1797 If this class redefinition strategy strikes you as rather counter-intuitive,
1798 bear in mind that it is derived from similar behaviour in other object
1799 systems such as CLOS, and that experience in those systems has shown it to be
1800 very useful in practice.
1802 Also bear in mind that, like most of GOOPS' default behaviour, it can
1803 be customized@dots{}
1805 @node Customizing Class Redefinition
1806 @subsection Customizing Class Redefinition
1808 When @code{define-class} notices that a class is being redefined,
1809 it constructs the new class metaobject as usual, and then invokes the
1810 @code{class-redefinition} generic function with the old and new classes
1811 as arguments. Therefore, if the old or new classes have metaclasses
1812 other than the default @code{<class>}, class redefinition behaviour can
1813 be customized by defining a @code{class-redefinition} method that is
1814 specialized for the relevant metaclasses.
1816 @deffn generic class-redefinition
1817 Handle the class redefinition from @var{old-class} to @var{new-class},
1818 and return the new class metaobject that should be bound to the
1819 variable specified by @code{define-class}'s first argument.
1822 @deffn method class-redefinition (old-class <class>) (new-class <class>)
1823 Implements GOOPS' default class redefinition behaviour, as described in
1824 @ref{Default Class Redefinition Behaviour}. Returns the metaobject
1825 for the new class definition.
1828 An alternative class redefinition strategy could be to leave all
1829 existing instances as instances of the old class, but accepting that the
1830 old class is now ``nameless'', since its name has been taken over by the
1831 new definition. In this strategy, any existing subclasses could also
1832 be left as they are, on the understanding that they inherit from a nameless
1835 This strategy is easily implemented in GOOPS, by defining a new metaclass,
1836 that will be used as the metaclass for all classes to which the strategy
1837 should apply, and then defining a @code{class-redefinition} method that
1838 is specialized for this metaclass:
1841 (define-class <can-be-nameless> (<class>))
1843 (define-method (class-redefinition (old <can-be-nameless>)
1848 When customization can be as easy as this, aren't you glad that GOOPS
1849 implements the far more difficult strategy as its default!
1851 Finally, note that, if @code{class-redefinition} itself is not customized,
1852 the default @code{class-redefinition} method invokes three further
1853 generic functions that could be individually customized:
1857 (remove-class-accessors! @var{old-class})
1860 (update-direct-method! @var{method} @var{old-class} @var{new-class})
1863 (update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
1866 and the default methods for these generic functions invoke further
1867 generic functions, and so on@dots{} The detailed protocol for all of these
1868 is described in @ref{MOP Specification}.
1870 @node Changing the Class of an Instance
1871 @section Changing the Class of an Instance
1873 You can change the class of an existing instance by invoking the
1874 generic function @code{change-class} with two arguments: the instance
1877 @deffn generic change-class
1880 The default method for @code{change-class} decides how to implement the
1881 change of class by looking at the slot definitions for the instance's
1882 existing class and for the new class. If the new class has slots with
1883 the same name as slots in the existing class, the values for those slots
1884 are preserved. Slots that are present only in the existing class are
1885 discarded. Slots that are present only in the new class are initialized
1886 using the corresponding slot definition's init function (@pxref{Classes,,
1887 slot-init-function}).
1889 @deffn {method} change-class (obj <object>) (new <class>)
1890 Modify instance @var{obj} to make it an instance of class @var{new}.
1892 The value of each of @var{obj}'s slots is preserved only if a similarly named
1893 slot exists in @var{new}; any other slot values are discarded.
1895 The slots in @var{new} that do not correspond to any of @var{obj}'s
1896 pre-existing slots are initialized according to @var{new}'s slot definitions'
1900 Customized change of class behaviour can be implemented by defining
1901 @code{change-class} methods that are specialized either by the class
1902 of the instances to be modified or by the metaclass of the new class.
1904 When a class is redefined (@pxref{Redefining a Class}), and the default
1905 class redefinition behaviour is not overridden, GOOPS (eventually)
1906 invokes the @code{change-class} generic function for each existing
1907 instance of the redefined class.
1909 @node GOOPS Error Handling
1910 @section Error Handling
1912 The procedure @code{goops-error} is called to raise an appropriate error
1913 by the default methods of the following generic functions:
1917 @code{slot-missing} (@pxref{Handling Slot Access Errors,, slot-missing})
1920 @code{slot-unbound} (@pxref{Handling Slot Access Errors,, slot-unbound})
1923 @code{no-method} (@pxref{Handling Invocation Errors,, no-method})
1926 @code{no-applicable-method} (@pxref{Handling Invocation Errors,,
1927 no-applicable-method})
1930 @code{no-next-method} (@pxref{Handling Invocation Errors,,
1934 If you customize these functions for particular classes or metaclasses,
1935 you may still want to use @code{goops-error} to signal any error
1936 conditions that you detect.
1938 @deffn procedure goops-error format-string . args
1939 Raise an error with key @code{goops-error} and error message constructed
1940 from @var{format-string} and @var{args}. Error message formatting is
1941 as done by @code{scm-error}.
1944 @node Object Comparisons
1945 @section Object Comparisons
1948 @deffnx method eqv? ((x <top>) (y <top>))
1949 @deffnx generic equal?
1950 @deffnx method equal? ((x <top>) (y <top>))
1952 @deffnx method = ((x <number>) (y <number>))
1953 Generic functions and default (unspecialized) methods for comparing two
1956 The default method for @code{eqv?} returns @code{#t} for all values
1957 that are equal in the sense defined by R5RS and the Guile reference
1958 manual, otherwise @code{#f}. The default method for @code{equal?}
1959 returns @code{#t} or @code{#f} in the sense defined by R5RS and the
1960 Guile reference manual. If no such comparison is defined,
1961 @code{equal?} returns the result of a call to @code{eqv?}. The
1962 default method for = returns @code{#t} if @var{x} and @var{y} are
1963 numerically equal, otherwise @code{#f}.
1965 Application class authors may wish to define specialized methods for
1966 @code{eqv?}, @code{equal?} and @code{=} that compare instances of the
1967 same class for equality in whatever sense is useful to the
1968 application. Such methods will only be called if the arguments have
1969 the same class and the result of the comparison isn't defined by R5RS
1970 and the Guile reference manual.
1973 @node Cloning Objects
1974 @section Cloning Objects
1976 @deffn generic shallow-clone
1977 @deffnx method shallow-clone (self <object>)
1978 Return a ``shallow'' clone of @var{self}. The default method makes a
1979 shallow clone by allocating a new instance and copying slot values from
1980 self to the new instance. Each slot value is copied either as an
1981 immediate value or by reference.
1984 @deffn generic deep-clone
1985 @deffnx method deep-clone (self <object>)
1986 Return a ``deep'' clone of @var{self}. The default method makes a deep
1987 clone by allocating a new instance and copying or cloning slot values
1988 from self to the new instance. If a slot value is an instance
1989 (satisfies @code{instance?}), it is cloned by calling @code{deep-clone}
1990 on that value. Other slot values are copied either as immediate values
1994 @node Write and Display
1995 @section Write and Display
1997 @deffn {primitive generic} write object port
1998 @deffnx {primitive generic} display object port
1999 When GOOPS is loaded, @code{write} and @code{display} become generic
2000 functions with special methods for printing
2004 objects - instances of the class @code{<object>}
2007 foreign objects - instances of the class @code{<foreign-object>}
2010 classes - instances of the class @code{<class>}
2013 generic functions - instances of the class @code{<generic>}
2016 methods - instances of the class @code{<method>}.
2019 @code{write} and @code{display} print non-GOOPS values in the same way
2020 as the Guile primitive @code{write} and @code{display} functions.
2023 @node The Metaobject Protocol
2024 @section The Metaobject Protocol
2026 GOOPS is based on a ``metaobject protocol'' (aka ``MOP'') derived from
2027 the ones used in CLOS (the Common Lisp Object System), tiny-clos (a
2028 small Scheme implementation of a subset of CLOS functionality) and
2031 GOOPS can be used by application authors at a basic level without any
2032 need to understand what the MOP is and how it works. On the other hand,
2033 the MOP underlies even very simple customizations --- such as defining
2034 an @code{initialize} method to customize the initialization of instances
2035 of an application-defined class --- and an understanding of the MOP
2036 makes it much easier to explain such customizations in a precise way.
2037 And in the long run, understanding the MOP is the key both to
2038 understanding GOOPS at a deeper level and to taking full advantage of
2039 GOOPS' power, by customizing the behaviour of GOOPS itself.
2042 * Metaobjects and the Metaobject Protocol::
2044 * MOP Specification::
2045 * Class Definition Internals::
2046 * Customizing Class Definition::
2047 * Customizing Instance Creation::
2048 * Class Redefinition::
2049 * Method Definition::
2050 * Method Definition Internals::
2051 * Generic Function Internals::
2052 * Generic Function Invocation::
2055 @node Metaobjects and the Metaobject Protocol
2056 @subsection Metaobjects and the Metaobject Protocol
2058 The building blocks of GOOPS are classes, slot definitions, instances,
2059 generic functions and methods. A class is a grouping of inheritance
2060 relations and slot definitions. An instance is an object with slots
2061 that are allocated following the rules implied by its class's
2062 superclasses and slot definitions. A generic function is a collection
2063 of methods and rules for determining which of those methods to apply
2064 when the generic function is invoked. A method is a procedure and a set
2065 of specializers that specify the type of arguments to which the
2066 procedure is applicable.
2068 Of these entities, GOOPS represents classes, generic functions and
2069 methods as ``metaobjects''. In other words, the values in a GOOPS
2070 program that describe classes, generic functions and methods, are
2071 themselves instances (or ``objects'') of special GOOPS classes that
2072 encapsulate the behaviour, respectively, of classes, generic functions,
2075 (The other two entities are slot definitions and instances. Slot
2076 definitions are not strictly instances, but every slot definition is
2077 associated with a GOOPS class that specifies the behaviour of the slot
2078 as regards accessibility and protection from garbage collection.
2079 Instances are of course objects in the usual sense, and there is no
2080 benefit from thinking of them as metaobjects.)
2082 The ``metaobject protocol'' (aka ``MOP'') is the specification of the
2083 generic functions which determine the behaviour of these metaobjects and
2084 the circumstances in which these generic functions are invoked.
2086 For a concrete example of what this means, consider how GOOPS calculates
2087 the set of slots for a class that is being defined using
2088 @code{define-class}. The desired set of slots is the union of the new
2089 class's direct slots and the slots of all its superclasses. But
2090 @code{define-class} itself does not perform this calculation. Instead,
2091 there is a method of the @code{initialize} generic function that is
2092 specialized for instances of type @code{<class>}, and it is this method
2093 that performs the slot calculation.
2095 @code{initialize} is a generic function which GOOPS calls whenever a new
2096 instance is created, immediately after allocating memory for a new
2097 instance, in order to initialize the new instance's slots. The sequence
2098 of steps is as follows.
2102 @code{define-class} uses @code{make} to make a new instance of the
2103 @code{<class>} class, passing as initialization arguments the
2104 superclasses, slot definitions and class options that were specified in
2105 the @code{define-class} form.
2108 @code{make} allocates memory for the new instance, and then invokes the
2109 @code{initialize} generic function to initialize the new instance's
2113 The @code{initialize} generic function applies the method that is
2114 specialized for instances of type @code{<class>}, and this method
2115 performs the slot calculation.
2118 In other words, rather than being hardcoded in @code{define-class}, the
2119 behaviour of class definition is encapsulated by generic function
2120 methods that are specialized for the class @code{<class>}.
2122 It is possible to create a new class that inherits from @code{<class>},
2123 which is called a ``metaclass'', and to write a new @code{initialize}
2124 method that is specialized for instances of the new metaclass. Then, if
2125 the @code{define-class} form includes a @code{#:metaclass} class option
2126 whose value is the new metaclass, the class that is defined by the
2127 @code{define-class} form will be an instance of the new metaclass rather
2128 than of the default @code{<class>}, and will be defined in accordance
2129 with the new @code{initialize} method. Thus the default slot
2130 calculation, as well as any other aspect of the new class's relationship
2131 with its superclasses, can be modified or overridden.
2133 In a similar way, the behaviour of generic functions can be modified or
2134 overridden by creating a new class that inherits from the standard
2135 generic function class @code{<generic>}, writing appropriate methods
2136 that are specialized to the new class, and creating new generic
2137 functions that are instances of the new class.
2139 The same is true for method metaobjects. And the same basic mechanism
2140 allows the application class author to write an @code{initialize} method
2141 that is specialized to their application class, to initialize instances
2144 Such is the power of the MOP. Note that @code{initialize} is just one
2145 of a large number of generic functions that can be customized to modify
2146 the behaviour of application objects and classes and of GOOPS itself.
2147 Each following section covers a particular area of GOOPS functionality,
2148 and describes the generic functions that are relevant for customization
2152 @subsection Terminology
2154 It is assumed that the reader is already familiar with standard object
2155 orientation concepts such as classes, objects/instances,
2156 inheritance/subclassing, generic functions and methods, encapsulation
2159 This section explains some of the less well known concepts and
2160 terminology that GOOPS uses, which are assumed by the following sections
2161 of the reference manual.
2163 @subsubheading Metaclass
2165 A @dfn{metaclass} is the class of an object which represents a GOOPS
2166 class. Put more succinctly, a metaclass is a class's class.
2168 Most GOOPS classes have the metaclass @code{<class>} and, by default,
2169 any new class that is created using @code{define-class} has the
2170 metaclass @code{<class>}.
2172 But what does this really mean? To find out, let's look in more detail
2173 at what happens when a new class is created using @code{define-class}:
2176 (define-class <my-class> (<object>) . slots)
2179 GOOPS actually expands the @code{define-class} form to something like
2183 (define <my-class> (class (<object>) . slots))
2190 (make <class> #:supers (list <object>) #:slots slots))
2193 In other words, the value of @code{<my-class>} is in fact an instance of
2194 the class @code{<class>} with slot values specifying the superclasses
2195 and slot definitions for the class @code{<my-class>}. (@code{#:supers}
2196 and @code{#:slots} are initialization keywords for the @code{dsupers}
2197 and @code{dslots} slots of the @code{<class>} class.)
2199 In order to take advantage of the full power of the GOOPS metaobject
2200 protocol (@pxref{MOP Specification}), it is sometimes desirable to
2201 create a new class with a metaclass other than the default
2202 @code{<class>}. This is done by writing:
2205 (define-class <my-class2> (<object>)
2207 #:metaclass <my-metaclass>)
2210 GOOPS expands this to something like:
2214 (make <my-metaclass> #:supers (list <object>) #:slots slots))
2217 In this case, the value of @code{<my-class2>} is an instance of the more
2218 specialized class @code{<my-metaclass>}. Note that
2219 @code{<my-metaclass>} itself must previously have been defined as a
2220 subclass of @code{<class>}. For a full discussion of when and how it is
2221 useful to define new metaclasses, see @ref{MOP Specification}.
2223 Now let's make an instance of @code{<my-class2>}:
2226 (define my-object (make <my-class2> ...))
2229 All of the following statements are correct expressions of the
2230 relationships between @code{my-object}, @code{<my-class2>},
2231 @code{<my-metaclass>} and @code{<class>}.
2235 @code{my-object} is an instance of the class @code{<my-class2>}.
2238 @code{<my-class2>} is an instance of the class @code{<my-metaclass>}.
2241 @code{<my-metaclass>} is an instance of the class @code{<class>}.
2244 The class of @code{my-object} is @code{<my-class2>}.
2247 The metaclass of @code{my-object} is @code{<my-metaclass>}.
2250 The class of @code{<my-class2>} is @code{<my-metaclass>}.
2253 The metaclass of @code{<my-class2>} is @code{<class>}.
2256 The class of @code{<my-metaclass>} is @code{<class>}.
2259 The metaclass of @code{<my-metaclass>} is @code{<class>}.
2262 @code{<my-class2>} is not a metaclass, since it is does not inherit from
2266 @code{<my-metaclass>} is a metaclass, since it inherits from
2270 @subsubheading Class Precedence List
2272 The @dfn{class precedence list} of a class is the list of all direct and
2273 indirect superclasses of that class, including the class itself.
2275 In the absence of multiple inheritance, the class precedence list is
2276 ordered straightforwardly, beginning with the class itself and ending
2279 For example, given this inheritance hierarchy:
2282 (define-class <invertebrate> (<object>) @dots{})
2283 (define-class <echinoderm> (<invertebrate>) @dots{})
2284 (define-class <starfish> (<echinoderm>) @dots{})
2287 the class precedence list of <starfish> would be
2290 (<starfish> <echinoderm> <invertebrate> <object> <top>)
2293 With multiple inheritance, the algorithm is a little more complicated.
2294 A full description is provided by the GOOPS Tutorial: see @ref{Class
2297 ``Class precedence list'' is often abbreviated, in documentation and
2298 Scheme variable names, to @dfn{cpl}.
2300 @subsubheading Accessor
2302 An @dfn{accessor} is a generic function with both reference and setter
2306 (define-accessor perimeter)
2309 Reference methods for an accessor are defined in the same way as generic
2313 (define-method (perimeter (s <square>))
2314 (* 4 (side-length s)))
2317 Setter methods for an accessor are defined by specifying ``(setter
2318 <accessor-name>)'' as the first parameter of the @code{define-method}
2322 (define-method ((setter perimeter) (s <square>) (n <number>))
2323 (set! (side-length s) (/ n 4)))
2326 Once an appropriate setter method has been defined in this way, it can
2327 be invoked using the generalized @code{set!} syntax, as in:
2330 (set! (perimeter s1) 18.3)
2333 @node MOP Specification
2334 @subsection MOP Specification
2336 The aim of the MOP specification in this chapter is to specify all the
2337 customizable generic function invocations that can be made by the standard
2338 GOOPS syntax, procedures and methods, and to explain the protocol for
2339 customizing such invocations.
2341 A generic function invocation is customizable if the types of the arguments
2342 to which it is applied are not all determined by the lexical context in
2343 which the invocation appears. For example,
2347 the @code{(initialize @var{instance} @var{initargs})} invocation in the
2348 default @code{make-instance} method is customizable, because the type of the
2349 @code{@var{instance}} argument is determined by the class that was passed to
2350 @code{make-instance}.
2353 the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
2354 is not customizable, because all of its arguments have lexically determined
2358 When using this rule to decide whether a given generic function invocation
2359 is customizable, we ignore arguments that are expected to be handled in
2360 method definitions as a single ``rest'' list argument.
2362 For each customizable generic function invocation, the @dfn{invocation
2363 protocol} is explained by specifying
2367 what, conceptually, the applied method is intended to do
2370 what assumptions, if any, the caller makes about the applied method's side
2374 what the caller expects to get as the applied method's return value.
2377 @node Class Definition Internals
2378 @subsection Class Definition Internals
2380 @code{define-class} (syntax)
2384 @code{class} (syntax)
2388 @code{make-class} (procedure)
2392 @code{make @var{metaclass} @dots{}} (generic)
2394 @var{metaclass} is the metaclass of the class being defined, either
2395 taken from the @code{#:metaclass} class option or computed by
2396 @code{ensure-metaclass}. The applied method must create and return the
2397 fully initialized class metaobject for the new class definition.
2403 @code{class-redefinition @var{old-class} @var{new-class}} (generic)
2405 @code{define-class} calls @code{class-redefinition} if the variable
2406 specified by its first argument already held a GOOPS class definition.
2407 @var{old-class} and @var{new-class} are the old and new class metaobjects.
2408 The applied method should perform whatever is necessary to handle the
2409 redefinition, and should return the class metaobject that is to be bound
2410 to @code{define-class}'s variable. The default class redefinition
2411 protocol is described in @ref{Class Redefinition}.
2414 The @code{(make @var{metaclass} @dots{})} invocation above will create
2415 an class metaobject with metaclass @var{metaclass}. By default, this
2416 metaobject will be initialized by the @code{initialize} method that is
2417 specialized for instances of type @code{<class>}.
2419 @code{initialize <class> @var{initargs}} (method)
2423 @code{compute-cpl @var{class}} (generic)
2425 The applied method should compute and return the class precedence list
2426 for @var{class} as a list of class metaobjects. When @code{compute-cpl}
2427 is called, the following @var{class} metaobject slots have all been
2428 initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
2429 @code{direct-subclasses} (empty), @code{direct-methods}. The value
2430 returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
2433 @code{compute-slots @var{class}} (generic)
2435 The applied method should compute and return the slots (union of direct
2436 and inherited) for @var{class} as a list of slot definitions. When
2437 @code{compute-slots} is called, all the @var{class} metaobject slots
2438 mentioned for @code{compute-cpl} have been initialized, plus the
2439 following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
2440 The value returned by @code{compute-slots} will be stored in the
2444 @code{compute-get-n-set @var{class} @var{slot-def}} (generic)
2446 @code{initialize} calls @code{compute-get-n-set} for each slot computed
2447 by @code{compute-slots}. The applied method should compute and return a
2448 pair of closures that, respectively, get and set the value of the specified
2449 slot. The get closure should have arity 1 and expect a single argument
2450 that is the instance whose slot value is to be retrieved. The set closure
2451 should have arity 2 and expect two arguments, where the first argument is
2452 the instance whose slot value is to be set and the second argument is the
2453 new value for that slot. The closures should be returned in a two element
2454 list: @code{(list @var{get} @var{set})}.
2456 The closures returned by @code{compute-get-n-set} are stored as part of
2457 the value of the @var{class} metaobject's @code{getters-n-setters} slot.
2458 Specifically, the value of this slot is a list with the same number of
2459 elements as there are slots in the class, and each element looks either like
2462 @code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
2468 @code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
2471 Where the get and set closures are replaced by @var{index}, the slot is
2472 an instance slot and @var{index} is the slot's index in the underlying
2473 structure: GOOPS knows how to get and set the value of such slots and so
2474 does not need specially constructed get and set closures. Otherwise,
2475 @var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
2477 The structure of the @code{getters-n-setters} slot value is important when
2478 understanding the next customizable generic functions that @code{initialize}
2482 @code{compute-getter-method @var{class} @var{gns}} (generic)
2484 @code{initialize} calls @code{compute-getter-method} for each of the class's
2485 slots (as determined by @code{compute-slots}) that includes a
2486 @code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
2487 element of the @var{class} metaobject's @code{getters-n-setters} slot that
2488 specifies how the slot in question is referenced and set, as described
2489 above under @code{compute-get-n-set}. The applied method should create
2490 and return a method that is specialized for instances of type @var{class}
2491 and uses the get closure to retrieve the slot's value. [ *fixme Need
2492 to insert something here about checking that the value is not unbound. ]
2493 @code{initialize} uses @code{add-method!} to add the returned method to
2494 the generic function named by the slot definition's @code{#:getter} or
2495 @code{#:accessor} option.
2498 @code{compute-setter-method @var{class} @var{gns}} (generic)
2500 @code{compute-setter-method} is invoked with the same arguments as
2501 @code{compute-getter-method}, for each of the class's slots that includes
2502 a @code{#:setter} or @code{#:accessor} slot option. The applied method
2503 should create and return a method that is specialized for instances of
2504 type @var{class} and uses the set closure to set the slot's value.
2505 @code{initialize} then uses @code{add-method!} to add the returned method
2506 to the generic function named by the slot definition's @code{#:setter}
2507 or @code{#:accessor} option.
2510 @code{define-class} expands to an expression which
2514 checks that it is being evaluated only at top level
2517 defines any accessors that are implied by the @var{slot-definition}s
2520 uses @code{class} to create the new class (@pxref{Class Definition
2524 checks for a previous class definition for @var{name} and, if found,
2525 handles the redefinition by invoking @code{class-redefinition}
2526 (@pxref{Redefining a Class}).
2529 @deffn syntax class name (super @dots{}) slot-definition @dots{} . options
2530 Return a newly created class that inherits from @var{super}s, with
2531 direct slots defined by @var{slot-definition}s and class options
2532 @var{options}. For the format of @var{slot-definition}s and
2533 @var{options}, see @ref{Class Definition,, define-class}.
2536 @noindent @code{class} expands to an expression which
2540 processes the class and slot definition options to check that they are
2541 well-formed, to convert the @code{#:init-form} option to an
2542 @code{#:init-thunk} option, to supply a default environment parameter
2543 (the current top-level environment) and to evaluate all the bits that
2544 need to be evaluated
2547 calls @code{make-class} to create the class with the processed and
2548 evaluated parameters.
2551 @deffn procedure make-class supers slots . options
2552 Return a newly created class that inherits from @var{supers}, with
2553 direct slots defined by @var{slots} and class options @var{options}.
2554 For the format of @var{slots} and @var{options}, see @ref{Class
2555 Definition,, define-class}, except note that for @code{make-class},
2556 @var{slots} and @var{options} are separate list parameters: @var{slots}
2557 here is a list of slot definitions.
2560 @noindent @code{make-class}
2564 adds @code{<object>} to the @var{supers} list if @var{supers} is empty
2565 or if none of the classes in @var{supers} have @code{<object>} in their
2566 class precedence list
2569 defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
2570 options, if they are not specified by @var{options}, to the current
2571 top-level environment, the unbound value, and @code{(ensure-metaclass
2572 @var{supers})} respectively (@pxref{Class Definition Internals,,
2576 checks for duplicate classes in @var{supers} and duplicate slot names in
2577 @var{slots}, and signals an error if there are any duplicates
2580 calls @code{make}, passing the metaclass as the first parameter and all
2581 other parameters as option keywords with values.
2584 @deffn procedure ensure-metaclass supers env
2585 Return a metaclass suitable for a class that inherits from the list of
2586 classes in @var{supers}. The returned metaclass is the union by
2587 inheritance of the metaclasses of the classes in @var{supers}.
2589 In the simplest case, where all the @var{supers} are straightforward
2590 classes with metaclass @code{<class>}, the returned metaclass is just
2593 For a more complex example, suppose that @var{supers} contained one
2594 class with metaclass @code{<operator-class>} and one with metaclass
2595 @code{<foreign-object-class>}. Then the returned metaclass would be a
2596 class that inherits from both @code{<operator-class>} and
2597 @code{<foreign-object-class>}.
2599 If @var{supers} is the empty list, @code{ensure-metaclass} returns the
2600 default GOOPS metaclass @code{<class>}.
2602 GOOPS keeps a list of the metaclasses created by
2603 @code{ensure-metaclass}, so that each required type of metaclass only
2604 has to be created once.
2606 The @code{env} parameter is ignored.
2609 @deffn procedure ensure-metaclass-with-supers meta-supers
2610 @code{ensure-metaclass-with-supers} is an internal procedure used by
2611 @code{ensure-metaclass} (@pxref{Class Definition Internals,,
2612 ensure-metaclass}). It returns a metaclass that is the union by
2613 inheritance of the metaclasses in @var{meta-supers}.
2616 The internals of @code{make}, which is ultimately used to create the new
2617 class object, are described in @ref{Customizing Instance Creation},
2618 which covers the creation and initialization of instances in general.
2620 @node Customizing Class Definition
2621 @subsection Customizing Class Definition
2623 During the initialization of a new class, GOOPS calls a number of generic
2624 functions with the newly allocated class instance as the first
2625 argument. Specifically, GOOPS calls the generic function
2629 (initialize @var{class} @dots{})
2632 where @var{class} is the newly allocated class instance, and the default
2633 @code{initialize} method for arguments of type @code{<class>} calls the
2638 (compute-cpl @var{class})
2641 (compute-slots @var{class})
2644 (compute-get-n-set @var{class} @var{slot-def}), for each of the slot
2645 definitions returned by @code{compute-slots}
2648 (compute-getter-method @var{class} @var{slot-def}), for each of the
2649 slot definitions returned by @code{compute-slots} that includes a
2650 @code{#:getter} or @code{#:accessor} slot option
2653 (compute-setter-method @var{class} @var{slot-def}), for each of the
2654 slot definitions returned by @code{compute-slots} that includes a
2655 @code{#:setter} or @code{#:accessor} slot option.
2658 If the metaclass of the new class is something more specialized than the
2659 default @code{<class>}, then the type of @var{class} in the calls above
2660 is more specialized than @code{<class>}, and hence it becomes possible
2661 to define generic function methods, specialized for the new class's
2662 metaclass, that can modify or override the default behaviour of
2663 @code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
2665 @code{compute-cpl} computes the class precedence list (``CPL'') for the
2666 new class (@pxref{Class Precedence List}), and returns it as a list of
2667 class objects. The CPL is important because it defines a superclass
2668 ordering that is used, when a generic function is invoked upon an
2669 instance of the class, to decide which of the available generic function
2670 methods is the most specific. Hence @code{compute-cpl} could be
2671 customized in order to modify the CPL ordering algorithm for all classes
2672 with a special metaclass.
2674 The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
2675 procedure, which is in turn called by the default @code{compute-cpl}
2678 @deffn procedure compute-std-cpl class
2679 Compute and return the class precedence list for @var{class} according
2680 to the algorithm described in @ref{Class Precedence List}.
2683 @code{compute-slots} computes and returns a list of all slot definitions
2684 for the new class. By default, this list includes the direct slot
2685 definitions from the @code{define-class} form, plus the slot definitions
2686 that are inherited from the new class's superclasses. The default
2687 @code{compute-slots} method uses the CPL computed by @code{compute-cpl}
2688 to calculate this union of slot definitions, with the rule that slots
2689 inherited from superclasses are shadowed by direct slots with the same
2690 name. One possible reason for customizing @code{compute-slots} would be
2691 to implement an alternative resolution strategy for slot name conflicts.
2693 @code{compute-get-n-set} computes the low-level closures that will be
2694 used to get and set the value of a particular slot, and returns them in
2695 a list with two elements.
2697 The closures returned depend on how storage for that slot is allocated.
2698 The standard @code{compute-get-n-set} method, specialized for classes of
2699 type @code{<class>}, handles the standard GOOPS values for the
2700 @code{#:allocation} slot option (@pxref{Slot Options,, allocation}). By
2701 defining a new @code{compute-get-n-set} method for a more specialized
2702 metaclass, it is possible to support new types of slot allocation.
2704 Suppose you wanted to create a large number of instances of some class
2705 with a slot that should be shared between some but not all instances of
2706 that class - say every 10 instances should share the same slot storage.
2707 The following example shows how to implement and use a new type of slot
2708 allocation to do this.
2711 (define-class <batched-allocation-metaclass> (<class>))
2713 (let ((batch-allocation-count 0)
2714 (batch-get-n-set #f))
2715 (define-method (compute-get-n-set
2716 (class <batched-allocation-metaclass>) s)
2717 (case (slot-definition-allocation s)
2719 ;; If we've already used the same slot storage for 10 instances,
2721 (if (= batch-allocation-count 10)
2723 (set! batch-allocation-count 0)
2724 (set! batch-get-n-set #f)))
2725 ;; If we don't have a current pair of get and set closures,
2726 ;; create one. make-closure-variable returns a pair of closures
2727 ;; around a single Scheme variable - see goops.scm for details.
2729 (set! batch-get-n-set (make-closure-variable)))
2730 ;; Increment the batch allocation count.
2731 (set! batch-allocation-count (+ batch-allocation-count 1))
2734 ;; Call next-method to handle standard allocation types.
2735 (else (next-method)))))
2737 (define-class <class-using-batched-slot> ()
2739 (c #:allocation #:batched)
2741 #:metaclass <batched-allocation-metaclass>)
2744 The usage of @code{compute-getter-method} and @code{compute-setter-method}
2745 is described in @ref{MOP Specification}.
2747 @code{compute-cpl} and @code{compute-get-n-set} are called by the
2748 standard @code{initialize} method for classes whose metaclass is
2749 @code{<class>}. But @code{initialize} itself can also be modified, by
2750 defining an @code{initialize} method specialized to the new class's
2751 metaclass. Such a method could complete override the standard
2752 behaviour, by not calling @code{(next-method)} at all, but more
2753 typically it would perform additional class initialization steps before
2754 and/or after calling @code{(next-method)} for the standard behaviour.
2756 @node Customizing Instance Creation
2757 @subsection Customizing Instance Creation
2759 @code{make <class> . @var{initargs}} (method)
2763 @code{allocate-instance @var{class} @var{initargs}} (generic)
2765 The applied @code{allocate-instance} method should allocate storage for
2766 a new instance of class @var{class} and return the uninitialized instance.
2769 @code{initialize @var{instance} @var{initargs}} (generic)
2771 @var{instance} is the uninitialized instance returned by
2772 @code{allocate-instance}. The applied method should initialize the new
2773 instance in whatever sense is appropriate for its class. The method's
2774 return value is ignored.
2777 @code{make} itself is a generic function. Hence the @code{make}
2778 invocation itself can be customized in the case where the new instance's
2779 metaclass is more specialized than the default @code{<class>}, by
2780 defining a @code{make} method that is specialized to that metaclass.
2782 Normally, however, the method for classes with metaclass @code{<class>}
2783 will be applied. This method calls two generic functions:
2787 (allocate-instance @var{class} . @var{initargs})
2790 (initialize @var{instance} . @var{initargs})
2793 @code{allocate-instance} allocates storage for and returns the new
2794 instance, uninitialized. You might customize @code{allocate-instance},
2795 for example, if you wanted to provide a GOOPS wrapper around some other
2796 object programming system.
2798 To do this, you would create a specialized metaclass, which would act as
2799 the metaclass for all classes and instances from the other system. Then
2800 define an @code{allocate-instance} method, specialized to that
2801 metaclass, which calls a Guile primitive C function, which in turn
2802 allocates the new instance using the interface of the other object
2805 In this case, for a complete system, you would also need to customize a
2806 number of other generic functions like @code{make} and
2807 @code{initialize}, so that GOOPS knows how to make classes from the
2808 other system, access instance slots, and so on.
2810 @code{initialize} initializes the instance that is returned by
2811 @code{allocate-instance}. The standard GOOPS methods perform
2812 initializations appropriate to the instance class.
2816 At the least specialized level, the method for instances of type
2817 @code{<object>} performs internal GOOPS instance initialization, and
2818 initializes the instance's slots according to the slot definitions and
2819 any slot initialization keywords that appear in @var{initargs}.
2822 The method for instances of type @code{<class>} calls
2823 @code{(next-method)}, then performs the class initializations described
2824 in @ref{Customizing Class Definition}.
2827 and so on for generic functions, method, operator classes @dots{}
2830 Similarly, you can customize the initialization of instances of any
2831 application-defined class by defining an @code{initialize} method
2832 specialized to that class.
2834 Imagine a class whose instances' slots need to be initialized at
2835 instance creation time by querying a database. Although it might be
2836 possible to achieve this a combination of @code{#:init-thunk} keywords
2837 and closures in the slot definitions, it is neater to write an
2838 @code{initialize} method for the class that queries the database once
2839 and initializes all the dependent slot values according to the results.
2841 @node Class Redefinition
2842 @subsection Class Redefinition
2844 The default @code{class-redefinition} method, specialized for classes
2845 with the default metaclass @code{<class>}, has the following internal
2848 @code{class-redefinition (@var{old <class>}) (@var{new <class>})}
2853 @code{remove-class-accessors! @var{old}} (generic)
2856 @code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
2859 @code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
2862 This protocol cleans up things that the definition of the old class
2863 once changed and modifies things to work with the new class.
2865 The default @code{remove-class-accessors!} method removes the
2866 accessor methods of the old class from all classes which they
2869 The default @code{update-direct-method!} method substitutes the new
2870 class for the old in all methods specialized to the old class.
2872 The default @code{update-direct-subclass!} method invokes
2873 @code{class-redefinition} recursively to handle the redefinition of
2876 When a class is redefined, any existing instance of the redefined class
2877 will be modified for the new class definition before the next time that
2878 any of the instance's slot is referenced or set. GOOPS modifies each
2879 instance by calling the generic function @code{change-class}.
2881 The default @code{change-class} method copies slot values from the old
2882 to the modified instance, and initializes new slots, as described in
2883 @ref{Changing the Class of an Instance}. After doing so, it makes a
2884 generic function invocation that can be used to customize the instance
2887 @code{change-class (@var{old-instance <object>}) (@var{new <class>})} (method)
2891 @code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
2893 @code{change-class} invokes @code{update-instance-for-different-class}
2894 as the last thing that it does before returning. The applied method can
2895 make any further adjustments to @var{new-instance} that are required to
2896 complete or modify the change of class. The return value from the
2897 applied method is ignored.
2899 The default @code{update-instance-for-different-class} method does
2903 @node Method Definition
2904 @subsection Method Definition
2906 @code{define-method} (syntax)
2910 @code{add-method! @var{target} @var{method}} (generic)
2912 @code{define-method} invokes the @code{add-method!} generic function to
2913 handle adding the new method to a variety of possible targets. GOOPS
2914 includes methods to handle @var{target} as
2918 a generic function (the most common case)
2924 a primitive generic (@pxref{Extending Primitives})
2927 By defining further methods for @code{add-method!}, you can
2928 theoretically handle adding methods to further types of target.
2931 @node Method Definition Internals
2932 @subsection Method Definition Internals
2934 @code{define-method}
2938 checks the form of the first parameter, and applies the following steps
2939 to the accessor's setter if it has the @code{(setter @dots{})} form
2942 interpolates a call to @code{define-generic} or @code{define-accessor}
2943 if a generic function is not already defined with the supplied name
2946 calls @code{method} with the @var{parameter}s and @var{body}, to make a
2950 calls @code{add-method!} to add this method to the relevant generic
2954 @deffn syntax method (parameter @dots{}) . body
2955 Make a method whose specializers are defined by the classes in
2956 @var{parameter}s and whose procedure definition is constructed from the
2957 @var{parameter} symbols and @var{body} forms.
2959 The @var{parameter} and @var{body} parameters should be as for
2960 @code{define-method} (@pxref{Methods and Generic Functions,,
2968 extracts formals and specializing classes from the @var{parameter}s,
2969 defaulting the class for unspecialized parameters to @code{<top>}
2972 creates a closure using the formals and the @var{body} forms
2975 calls @code{make} with metaclass @code{<method>} and the specializers
2976 and closure using the @code{#:specializers} and @code{#:procedure}
2980 @deffn procedure make-method specializers procedure
2981 Make a method using @var{specializers} and @var{procedure}.
2983 @var{specializers} should be a list of classes that specifies the
2984 parameter combinations to which this method will be applicable.
2986 @var{procedure} should be the closure that will applied to the generic
2987 function parameters when this method is invoked.
2990 @code{make-method} is a simple wrapper around @code{make} with metaclass
2993 @deffn generic add-method! target method
2994 Generic function for adding method @var{method} to @var{target}.
2997 @deffn method add-method! (generic <generic>) (method <method>)
2998 Add method @var{method} to the generic function @var{generic}.
3001 @deffn method add-method! (proc <procedure>) (method <method>)
3002 If @var{proc} is a procedure with generic capability (@pxref{Extending
3003 Primitives,, generic-capability?}), upgrade it to a primitive generic
3004 and add @var{method} to its generic function definition.
3007 @deffn method add-method! (pg <primitive-generic>) (method <method>)
3008 Add method @var{method} to the generic function definition of @var{pg}.
3010 Implementation: @code{(add-method! (primitive-generic-generic pg) method)}.
3013 @deffn method add-method! (whatever <top>) (method <method>)
3014 Raise an error indicating that @var{whatever} is not a valid generic
3018 @node Generic Function Internals
3019 @subsection Generic Function Internals
3021 @code{define-generic} calls @code{ensure-generic} to upgrade a
3022 pre-existing procedure value, or @code{make} with metaclass
3023 @code{<generic>} to create a new generic function.
3025 @code{define-accessor} calls @code{ensure-accessor} to upgrade a
3026 pre-existing procedure value, or @code{make-accessor} to create a new
3029 @deffn procedure ensure-generic old-definition [name]
3030 Return a generic function with name @var{name}, if possible by using or
3031 upgrading @var{old-definition}. If unspecified, @var{name} defaults to
3034 If @var{old-definition} is already a generic function, it is returned
3037 If @var{old-definition} is a Scheme procedure or procedure-with-setter,
3038 @code{ensure-generic} returns a new generic function that uses
3039 @var{old-definition} for its default procedure and setter.
3041 Otherwise @code{ensure-generic} returns a new generic function with no
3042 defaults and no methods.
3045 @deffn procedure make-generic [name]
3046 Return a new generic function with name @code{(car @var{name})}. If
3047 unspecified, @var{name} defaults to @code{#f}.
3050 @code{ensure-generic} calls @code{make} with metaclasses
3051 @code{<generic>} and @code{<generic-with-setter>}, depending on the
3052 previous value of the variable that it is trying to upgrade.
3054 @code{make-generic} is a simple wrapper for @code{make} with metaclass
3057 @deffn procedure ensure-accessor proc [name]
3058 Return an accessor with name @var{name}, if possible by using or
3059 upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
3061 If @var{proc} is already an accessor, it is returned unchanged.
3063 If @var{proc} is a Scheme procedure, procedure-with-setter or generic
3064 function, @code{ensure-accessor} returns an accessor that reuses the
3065 reusable elements of @var{proc}.
3067 Otherwise @code{ensure-accessor} returns a new accessor with no defaults
3071 @deffn procedure make-accessor [name]
3072 Return a new accessor with name @code{(car @var{name})}. If
3073 unspecified, @var{name} defaults to @code{#f}.
3076 @code{ensure-accessor} calls @code{make} with
3077 metaclass @code{<generic-with-setter>}, as well as calls to
3078 @code{ensure-generic}, @code{make-accessor} and (tail recursively)
3079 @code{ensure-accessor}.
3081 @code{make-accessor} calls @code{make} twice, first
3082 with metaclass @code{<generic>} to create a generic function for the
3083 setter, then with metaclass @code{<generic-with-setter>} to create the
3084 accessor, passing the setter generic function as the value of the
3085 @code{#:setter} keyword.
3087 @node Generic Function Invocation
3088 @subsection Generic Function Invocation
3090 [ *fixme* Description required here. ]
3092 @code{apply-generic}
3099 @code{compute-applicable-methods}
3102 @code{sort-applicable-methods}
3105 @code{apply-methods}
3108 @code{no-applicable-method}
3111 @code{sort-applicable-methods}
3115 @code{method-more-specific?}
3118 @code{apply-methods}
3129 @code{no-next-method}