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 (@cite{CLtL2}) but is
22 adapted for the Scheme language. While GOOPS is not compatible with any
23 of these systems, GOOPS contains a compatibility module which allows for
24 execution of STKlos programs.
26 Briefly stated, the @goops{} extension gives the user a full object
27 oriented system with multiple inheritance and generic functions with
28 multi-method dispatch. Furthermore, the implementation relies on a true
29 meta object protocol, in the spirit of the one defined for CLOS
30 (@cite{Gregor Kiczales: A Metaobject Protocol}).
42 To give an immediate flavour of what GOOPS can do, here is a very
43 quick introduction to its main operations.
45 To start using GOOPS, load the @code{(oop goops)} module:
48 (use-modules (oop goops))
51 We're now ready to try some basic GOOPS functionality.
55 * User-defined types::
56 * Asking for the type of an object::
62 A GOOPS method is like a Scheme procedure except that it is
63 specialized for a particular set of argument types.
66 (define-method (+ (x <string>) (y <string>))
69 (+ "abc" "de") @result{} "abcde"
72 If @code{+} is used with arguments that do not match the method's
73 types, Guile falls back to using the normal Scheme @code{+} procedure.
80 @node User-defined types
81 @subsection User-defined types
84 (define-class <2D-vector> ()
85 (x #:init-value 0 #:accessor x-component #:init-keyword #:x)
86 (y #:init-value 0 #:accessor y-component #:init-keyword #:y))
89 (use-modules (ice-9 format))
91 (define-method (write (obj <2D-vector>) port)
92 (display (format #f "<~S, ~S>" (x-component obj) (y-component obj))
95 (define v (make <2D-vector> #:x 3 #:y 4))
101 (define-method (+ (x <2D-vector>) (y <2D-vector>))
103 #:x (+ (x-component x) (x-component y))
104 #:y (+ (y-component x) (y-component y))))
106 (+ v v) @result{} <6, 8>
110 @node Asking for the type of an object
114 (class-of v) @result{} #<<class> <2D-vector> 40241ac0>
115 <2D-vector> @result{} #<<class> <2D-vector> 40241ac0>
116 (class-of 1) @result{} #<<class> <integer> 401b2a98>
117 <integer> @result{} #<<class> <integer> 401b2a98>
119 (is-a? v <2D-vector>) @result{} #t
124 @include goops-tutorial.texi
126 @node Reference Manual
127 @section Reference Manual
129 This chapter is the GOOPS reference manual. It aims to describe all the
130 syntax, procedures, options and associated concepts that a typical
131 application author would need to understand in order to use GOOPS
132 effectively in their application. It also describes what is meant by
133 the GOOPS ``metaobject protocol'' (aka ``MOP''), and indicates how
134 authors can use the metaobject protocol to customize the behaviour of
137 For a detailed specification of the GOOPS metaobject protocol, see
138 @ref{MOP Specification}.
141 * Introductory Remarks::
142 * Defining New Classes::
143 * Creating Instances::
145 * Creating Generic Functions::
146 * Adding Methods to Generic Functions::
147 * Invoking Generic Functions::
148 * Redefining a Class::
149 * Changing the Class of an Instance::
151 * Miscellaneous Functions::
154 @node Introductory Remarks
155 @subsection Introductory Remarks
157 GOOPS is an object-oriented programming system based on a ``metaobject
158 protocol'' derived from the ones used in CLOS (the Common Lisp Object
159 System), tiny-clos (a small Scheme implementation of a subset of CLOS
160 functionality) and STKlos.
162 GOOPS can be used by application authors at a basic level without any
163 need to understand what the metaobject protocol (aka ``MOP'') is and how
164 it works. On the other hand, the MOP underlies even the customizations
165 that application authors are likely to make use of very quickly --- such
166 as defining an @code{initialize} method to customize the initialization
167 of instances of an application-defined class --- and an understanding of
168 the MOP makes it much easier to explain such customizations in a precise
169 way. And in the long run, understanding the MOP is the key both to
170 understanding GOOPS at a deeper level and to taking full advantage of
171 GOOPS' power, by customizing the behaviour of GOOPS itself.
173 Each of the following sections of the reference manual is arranged
174 such that the most basic usage is introduced first, and then subsequent
175 subsubsections discuss the related internal functions and metaobject
176 protocols, finishing with a description of how to customize that area of
179 These introductory remarks continue with a few words about metaobjects
180 and the MOP. Readers who do not want to be bothered yet with the MOP
181 and customization could safely skip this subsubsection on a first reading,
182 and should correspondingly skip subsequent subsubsections that are
183 concerned with internals and customization.
185 In general, this reference manual assumes familiarity with standard
186 object oriented concepts and terminology. However, some of the terms
187 used in GOOPS are less well known, so the Terminology subsubsection
188 provides definitions for these terms.
191 * Metaobjects and the Metaobject Protocol::
195 @node Metaobjects and the Metaobject Protocol
196 @subsubsection Metaobjects and the Metaobject Protocol
198 The conceptual building blocks of GOOPS are classes, slot definitions,
199 instances, generic functions and methods. A class is a grouping of
200 inheritance relations and slot definitions. An instance is an object
201 with slots that are allocated following the rules implied by its class's
202 superclasses and slot definitions. A generic function is a collection
203 of methods and rules for determining which of those methods to apply
204 when the generic function is invoked. A method is a procedure and a set
205 of specializers that specify the type of arguments to which the
206 procedure is applicable.
208 Of these entities, GOOPS represents classes, generic functions and
209 methods as ``metaobjects''. In other words, the values in a GOOPS
210 program that describe classes, generic functions and methods, are
211 themselves instances (or ``objects'') of special GOOPS classes that
212 encapsulate the behaviour, respectively, of classes, generic functions,
215 (The other two entities are slot definitions and instances. Slot
216 definitions are not strictly instances, but every slot definition is
217 associated with a GOOPS class that specifies the behaviour of the slot
218 as regards accessibility and protection from garbage collection.
219 Instances are of course objects in the usual sense, and there is no
220 benefit from thinking of them as metaobjects.)
222 The ``metaobject protocol'' (aka ``MOP'') is the specification of the
223 generic functions which determine the behaviour of these metaobjects and
224 the circumstances in which these generic functions are invoked.
226 For a concrete example of what this means, consider how GOOPS calculates
227 the set of slots for a class that is being defined using
228 @code{define-class}. The desired set of slots is the union of the new
229 class's direct slots and the slots of all its superclasses. But
230 @code{define-class} itself does not perform this calculation. Instead,
231 there is a method of the @code{initialize} generic function that is
232 specialized for instances of type @code{<class>}, and it is this method
233 that performs the slot calculation.
235 @code{initialize} is a generic function which GOOPS calls whenever a new
236 instance is created, immediately after allocating memory for a new
237 instance, in order to initialize the new instance's slots. The sequence
238 of steps is as follows.
242 @code{define-class} uses @code{make} to make a new instance of the
243 @code{<class>}, passing as initialization arguments the superclasses,
244 slot definitions and class options that were specified in the
245 @code{define-class} form.
248 @code{make} allocates memory for the new instance, and then invokes the
249 @code{initialize} generic function to initialize the new instance's
253 The @code{initialize} generic function applies the method that is
254 specialized for instances of type @code{<class>}, and this method
255 performs the slot calculation.
258 In other words, rather than being hardcoded in @code{define-class}, the
259 behaviour of class definition is encapsulated by generic function
260 methods that are specialized for the class @code{<class>}.
262 It is possible to create a new class that inherits from @code{<class>},
263 which is called a ``metaclass'', and to write a new @code{initialize}
264 method that is specialized for instances of the new metaclass. Then, if
265 the @code{define-class} form includes a @code{#:metaclass} class option
266 whose value is the new metaclass, the class that is defined by the
267 @code{define-class} form will be an instance of the new metaclass rather
268 than of the default @code{<class>}, and will be defined in accordance
269 with the new @code{initialize} method. Thus the default slot
270 calculation, as well as any other aspect of the new class's relationship
271 with its superclasses, can be modified or overridden.
273 In a similar way, the behaviour of generic functions can be modified or
274 overridden by creating a new class that inherits from the standard
275 generic function class @code{<generic>}, writing appropriate methods
276 that are specialized to the new class, and creating new generic
277 functions that are instances of the new class.
279 The same is true for method metaobjects. And the same basic mechanism
280 allows the application class author to write an @code{initialize} method
281 that is specialized to their application class, to initialize instances
284 Such is the power of the MOP. Note that @code{initialize} is just one
285 of a large number of generic functions that can be customized to modify
286 the behaviour of application objects and classes and of GOOPS itself.
287 Each subsequent section of the reference manual covers a particular area
288 of GOOPS functionality, and describes the generic functions that are
289 relevant for customization of that area.
291 We conclude this subsubsection by emphasizing a point that may seem
292 obvious, but contrasts with the corresponding situation in some other
293 MOP implementations, such as CLOS. The point is simply that an
294 identifier which represents a GOOPS class or generic function is a
295 variable with a first-class value, the value being an instance of class
296 @code{<class>} or @code{<generic>}. (In CLOS, on the other hand, a
297 class identifier is a symbol that indexes the corresponding class
298 metaobject in a separate namespace for classes.) This is, of course,
299 simply an extension of the tendency in Scheme to avoid the unnecessary
300 use of, on the one hand, syntactic forms that require unevaluated
301 arguments and, on the other, separate identifier namespaces (e.g. for
302 class names), but it is worth noting that GOOPS conforms fully to this
306 @subsubsection Terminology
308 It is assumed that the reader is already familiar with standard object
309 orientation concepts such as classes, objects/instances,
310 inheritance/subclassing, generic functions and methods, encapsulation
313 This section explains some of the less well known concepts and
314 terminology that GOOPS uses, which are assumed by the following sections
315 of the reference manual.
317 @subsubheading Metaclass
319 A @dfn{metaclass} is the class of an object which represents a GOOPS
320 class. Put more succinctly, a metaclass is a class's class.
322 Most GOOPS classes have the metaclass @code{<class>} and, by default,
323 any new class that is created using @code{define-class} has the
324 metaclass @code{<class>}.
326 But what does this really mean? To find out, let's look in more detail
327 at what happens when a new class is created using @code{define-class}:
330 (define-class <my-class> (<object>) . slots)
333 GOOPS actually expands the @code{define-class} form to something like
337 (define <my-class> (class (<object>) . slots))
344 (make <class> #:supers (list <object>) #:slots slots))
347 In other words, the value of @code{<my-class>} is in fact an instance of
348 the class @code{<class>} with slot values specifying the superclasses
349 and slot definitions for the class @code{<my-class>}. (@code{#:supers}
350 and @code{#:slots} are initialization keywords for the @code{dsupers}
351 and @code{dslots} slots of the @code{<class>} class.)
353 In order to take advantage of the full power of the GOOPS metaobject
354 protocol (@pxref{MOP Specification}), it is sometimes desirable to
355 create a new class with a metaclass other than the default
356 @code{<class>}. This is done by writing:
359 (define-class <my-class2> (<object>)
361 #:metaclass <my-metaclass>)
364 GOOPS expands this to something like:
368 (make <my-metaclass> #:supers (list <object>) #:slots slots))
371 In this case, the value of @code{<my-class2>} is an instance of the more
372 specialized class @code{<my-metaclass>}. Note that
373 @code{<my-metaclass>} itself must previously have been defined as a
374 subclass of @code{<class>}. For a full discussion of when and how it is
375 useful to define new metaclasses, see @ref{MOP Specification}.
377 Now let's make an instance of @code{<my-class2>}:
380 (define my-object (make <my-class2> ...))
383 All of the following statements are correct expressions of the
384 relationships between @code{my-object}, @code{<my-class2>},
385 @code{<my-metaclass>} and @code{<class>}.
389 @code{my-object} is an instance of the class @code{<my-class2>}.
392 @code{<my-class2>} is an instance of the class @code{<my-metaclass>}.
395 @code{<my-metaclass>} is an instance of the class @code{<class>}.
398 The class of @code{my-object} is @code{<my-class2>}.
401 The metaclass of @code{my-object} is @code{<my-metaclass>}.
404 The class of @code{<my-class2>} is @code{<my-metaclass>}.
407 The metaclass of @code{<my-class2>} is @code{<class>}.
410 The class of @code{<my-metaclass>} is @code{<class>}.
413 The metaclass of @code{<my-metaclass>} is @code{<class>}.
416 @code{<my-class2>} is not a metaclass, since it is does not inherit from
420 @code{<my-metaclass>} is a metaclass, since it inherits from
424 @subsubheading Class Precedence List
426 The @dfn{class precedence list} of a class is the list of all direct and
427 indirect superclasses of that class, including the class itself.
429 In the absence of multiple inheritance, the class precedence list is
430 ordered straightforwardly, beginning with the class itself and ending
433 For example, given this inheritance hierarchy:
436 (define-class <invertebrate> (<object>) @dots{})
437 (define-class <echinoderm> (<invertebrate>) @dots{})
438 (define-class <starfish> (<echinoderm>) @dots{})
441 the class precedence list of <starfish> would be
444 (<starfish> <echinoderm> <invertebrate> <object> <top>)
447 With multiple inheritance, the algorithm is a little more complicated.
448 A full description is provided by the GOOPS Tutorial: see @ref{Class
451 ``Class precedence list'' is often abbreviated, in documentation and
452 Scheme variable names, to @dfn{cpl}.
454 @subsubheading Accessor
456 An @dfn{accessor} is a generic function with both reference and setter
460 (define-accessor perimeter)
463 Reference methods for an accessor are defined in the same way as generic
467 (define-method (perimeter (s <square>))
468 (* 4 (side-length s)))
471 Setter methods for an accessor are defined by specifying ``(setter
472 <accessor-name>)'' as the first parameter of the @code{define-method}
476 (define-method ((setter perimeter) (s <square>) (n <number>))
477 (set! (side-length s) (/ n 4)))
480 Once an appropriate setter method has been defined in this way, it can
481 be invoked using the generalized @code{set!} syntax, as in:
484 (set! (perimeter s1) 18.3)
487 @node Defining New Classes
488 @subsection Defining New Classes
490 [ *fixme* Somewhere in this manual there needs to be an introductory
491 discussion about GOOPS classes, generic functions and methods, covering
495 how classes encapsulate related items of data in @dfn{slots}
498 why it is that, unlike in C++ and Java, a class does not encapsulate the
499 methods that act upon the class (at least not in the C++/Java sense)
502 how generic functions provide a more general solution that provides for
503 dispatch on all argument types, and avoids idiosyncracies like C++'s
507 how encapsulation in the sense of data- and code-hiding, or of
508 distinguishing interface from implementation, is treated in Guile as an
509 orthogonal concept to object orientation, and is the responsibility of
513 Some of this is covered in the Tutorial chapter, in @ref{Generic
514 functions and methods} - perhaps the best solution would be to expand
515 the discussion there. ]
518 * Basic Class Definition::
521 * Class Definition Internals::
522 * Customizing Class Definition::
523 * STKlos Compatibility::
526 @node Basic Class Definition
527 @subsubsection Basic Class Definition
529 New classes are defined using the @code{define-class} syntax, with
530 arguments that specify the classes that the new class should inherit
531 from, the direct slots of the new class, and any required class options.
533 @deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
534 Define a class called @var{name} that inherits from @var{super}s, with
535 direct slots defined by @var{slot-definition}s and class options
536 @var{options}. The newly created class is bound to the variable name
537 @var{name} in the current environment.
539 Each @var{slot-definition} is either a symbol that names the slot or a
543 (@var{slot-name-symbol} . @var{slot-options})
546 where @var{slot-name-symbol} is a symbol and @var{slot-options} is a
547 list with an even number of elements. The even-numbered elements of
548 @var{slot-options} (counting from zero) are slot option keywords; the
549 odd-numbered elements are the corresponding values for those keywords.
551 @var{options} is a similarly structured list containing class option
552 keywords and corresponding values.
555 The standard GOOPS class and slot options are described in the following
556 subsubsections: see @ref{Class Options} and @ref{Slot Options}.
558 Example 1. Define a class that combines two pre-existing classes by
559 inheritance but adds no new slots.
562 (define-class <combined> (<tree> <bicycle>))
565 Example 2. Define a @code{regular-polygon} class with slots for side
566 length and number of sides that have default values and can be accessed
567 via the generic functions @code{side-length} and @code{num-sides}.
570 (define-class <regular-polygon> ()
571 (sl #:init-value 1 #:accessor side-length)
572 (ns #:init-value 5 #:accessor num-sides))
575 Example 3. Define a class whose behavior (and that of its instances) is
576 customized via an application-defined metaclass.
579 (define-class <tcpip-fsm> ()
580 (s #:init-value #f #:accessor state)
582 #:metaclass <finite-state-class>)
586 @subsubsection Class Options
588 @deffn {class option} #:metaclass metaclass
589 The @code{#:metaclass} class option specifies the metaclass of the class
590 being defined. @var{metaclass} must be a class that inherits from
591 @code{<class>}. For an introduction to the use of metaclasses, see
592 @ref{Metaobjects and the Metaobject Protocol} and @ref{Terminology}.
594 If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
595 metaclass for the new class by calling @code{ensure-metaclass}
596 (@pxref{Class Definition Internals,, ensure-metaclass}).
599 @deffn {class option} #:name name
600 The @code{#:name} class option specifies the new class's name. This
601 name is used to identify the class whenever related objects - the class
602 itself, its instances and its subclasses - are printed.
604 If the @code{#:name} option is absent, GOOPS uses the first argument to
605 @code{define-class} as the class name.
608 @deffn {class option} #:environment environment
609 *fixme* Not sure about this one, but I think that the
610 @code{#:environment} option specifies the environment in which the
611 class's getters and setters are computed and evaluated.
613 If the @code{#:environment} option is not specified, the class's
614 environment defaults to the top-level environment in which the
615 @code{define-class} form appears.
619 @subsubsection Slot Options
621 @deffn {slot option} #:allocation allocation
622 The @code{#:allocation} option tells GOOPS how to allocate storage for
623 the slot. Possible values for @var{allocation} are
626 @item @code{#:instance}
628 Indicates that GOOPS should create separate storage for this slot in
629 each new instance of the containing class (and its subclasses).
633 Indicates that GOOPS should create storage for this slot that is shared
634 by all instances of the containing class (and its subclasses). In other
635 words, a slot in class @var{C} with allocation @code{#:class} is shared
636 by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
638 @item @code{#:each-subclass}
640 Indicates that GOOPS should create storage for this slot that is shared
641 by all @emph{direct} instances of the containing class, and that
642 whenever a subclass of the containing class is defined, GOOPS should
643 create a new storage for the slot that is shared by all @emph{direct}
644 instances of the subclass. In other words, a slot with allocation
645 @code{#:each-subclass} is shared by all instances with the same
648 @item @code{#:virtual}
650 Indicates that GOOPS should not allocate storage for this slot. The
651 slot definition must also include the @code{#:slot-ref} and
652 @code{#:slot-set!} options to specify how to reference and set the value
656 The default value is @code{#:instance}.
658 Slot allocation options are processed when defining a new class by the
659 generic function @code{compute-get-n-set}, which is specialized by the
660 class's metaclass. Hence new types of slot allocation can be
661 implemented by defining a new metaclass and a method for
662 @code{compute-get-n-set} that is specialized for the new metaclass. For
663 an example of how to do this, see @ref{Customizing Class Definition}.
666 @deffn {slot option} #:slot-ref getter
667 @deffnx {slot option} #:slot-set! setter
668 The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
669 if the slot allocation is @code{#:virtual}, and are ignored otherwise.
671 @var{getter} should be a closure taking a single @var{instance} parameter
672 that returns the current slot value. @var{setter} should be a closure
673 taking two parameters - @var{instance} and @var{new-val} - that sets the
674 slot value to @var{new-val}.
677 @deffn {slot option} #:getter getter
678 @deffnx {slot option} #:setter setter
679 @deffnx {slot option} #:accessor accessor
680 These options, if present, tell GOOPS to create generic function and
681 method definitions that can be used to get and set the slot value more
682 conveniently than by using @code{slot-ref} and @code{slot-set!}.
684 @var{getter} specifies a generic function to which GOOPS will add a
685 method for getting the slot value. @var{setter} specifies a generic
686 function to which GOOPS will add a method for setting the slot value.
687 @var{accessor} specifies an accessor to which GOOPS will add methods for
688 both getting and setting the slot value.
690 So if a class includes a slot definition like this:
693 (c #:getter get-count #:setter set-count #:accessor count)
696 GOOPS defines generic function methods such that the slot value can be
697 referenced using either the getter or the accessor -
700 (let ((current-count (get-count obj))) @dots{})
701 (let ((current-count (count obj))) @dots{})
704 - and set using either the setter or the accessor -
707 (set-count obj (+ 1 current-count))
708 (set! (count obj) (+ 1 current-count))
715 with an accessor, the slot value is set using the generalized
719 in practice, it is unusual for a slot to use all three of these options:
720 read-only, write-only and read-write slots would typically use only
721 @code{#:getter}, @code{#:setter} and @code{#:accessor} options
725 If the specified names are already bound in the top-level environment to
726 values that cannot be upgraded to generic functions, those values are
727 overwritten during evaluation of the @code{define-class} that contains
728 the slot definition. For details, see @ref{Generic Function Internals,,
732 @deffn {slot option} #:init-value init-value
733 @deffnx {slot option} #:init-form init-form
734 @deffnx {slot option} #:init-thunk init-thunk
735 @deffnx {slot option} #:init-keyword init-keyword
736 These options provide various ways to specify how to initialize the
737 slot's value at instance creation time. @var{init-value} is a fixed
738 value (shared across all new instances of the class).
739 @var{init-thunk} is a procedure of no arguments that is called
740 when a new instance is created and should return the desired initial
741 slot value. @var{init-form} is an unevaluated expression that gets
742 evaluated when a new instance is created and should return the desired
743 initial slot value. @var{init-keyword} is a keyword that can be used
744 to pass an initial slot value to @code{make} when creating a new
747 Note that, since an @code{init-value} value is shared across all
748 instances of a class, you should only use it when the initial value is
749 an immutable value, like a constant. If you want to initialize a slot
750 with a fresh, independently mutable value, you should use
751 @code{init-thunk} or @code{init-form} instead. Consider the following
755 (define-class <chbouib> ()
756 (hashtab #:init-value (make-hash-table)))
760 Here only one hash table is created and all instances of
761 @code{<chbouib>} have their @code{hashtab} slot refer to it. In order
762 to have each instance of @code{<chbouib>} refer to a new hash table, you
763 should instead write:
766 (define-class <chbouib> ()
767 (hashtab #:init-thunk make-hash-table))
774 (define-class <chbouib> ()
775 (hashtab #:init-form (make-hash-table)))
778 If more than one of these options is specified for the same slot, the
779 order of precedence, highest first is
783 @code{#:init-keyword}, if @var{init-keyword} is present in the options
784 passed to @code{make}
787 @code{#:init-thunk}, @code{#:init-form} or @code{#:init-value}.
790 If the slot definition contains more than one initialization option of
791 the same precedence, the later ones are ignored. If a slot is not
792 initialized at all, its value is unbound.
794 In general, slots that are shared between more than one instance are
795 only initialized at new instance creation time if the slot value is
796 unbound at that time. However, if the new instance creation specifies
797 a valid init keyword and value for a shared slot, the slot is
798 re-initialized regardless of its previous value.
800 Note, however, that the power of GOOPS' metaobject protocol means that
801 everything written here may be customized or overridden for particular
802 classes! The slot initializations described here are performed by the least
803 specialized method of the generic function @code{initialize}, whose
807 (define-method (initialize (object <object>) initargs) ...)
810 The initialization of instances of any given class can be customized by
811 defining a @code{initialize} method that is specialized for that class,
812 and the author of the specialized method may decide to call
813 @code{next-method} - which will result in a call to the next less
814 specialized @code{initialize} method - at any point within the
815 specialized code, or maybe not at all. In general, therefore, the
816 initialization mechanisms described here may be modified or overridden by
817 more specialized code, or may not be supported at all for particular
821 @node Class Definition Internals
822 @subsubsection Class Definition Internals
824 Implementation notes: @code{define-class} expands to an expression which
828 checks that it is being evaluated only at top level
831 defines any accessors that are implied by the @var{slot-definition}s
834 uses @code{class} to create the new class (@pxref{Class Definition
838 checks for a previous class definition for @var{name} and, if found,
839 handles the redefinition by invoking @code{class-redefinition}
840 (@pxref{Redefining a Class}).
843 @deffn syntax class name (super @dots{}) slot-definition @dots{} . options
844 Return a newly created class that inherits from @var{super}s, with
845 direct slots defined by @var{slot-definition}s and class options
846 @var{options}. For the format of @var{slot-definition}s and
847 @var{options}, see @ref{Basic Class Definition,, define-class}.
850 Implementation notes: @code{class} expands to an expression which
854 processes the class and slot definition options to check that they are
855 well-formed, to convert the @code{#:init-form} option to an
856 @code{#:init-thunk} option, to supply a default environment parameter
857 (the current top-level environment) and to evaluate all the bits that
861 calls @code{make-class} to create the class with the processed and
862 evaluated parameters.
865 @deffn procedure make-class supers slots . options
866 Return a newly created class that inherits from @var{supers}, with
867 direct slots defined by @var{slots} and class options @var{options}.
868 For the format of @var{slots} and @var{options}, see @ref{Basic Class
869 Definition,, define-class}, except note that for @code{make-class},
870 @var{slots} and @var{options} are separate list parameters: @var{slots}
871 here is a list of slot definitions.
874 Implementation notes: @code{make-class}
878 adds @code{<object>} to the @var{supers} list if @var{supers} is empty
879 or if none of the classes in @var{supers} have @code{<object>} in their
880 class precedence list
883 defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
884 options, if they are not specified by @var{options}, to the current
885 top-level environment, the unbound value, and @code{(ensure-metaclass
886 @var{supers})} respectively (@pxref{Class Definition Internals,,
890 checks for duplicate classes in @var{supers} and duplicate slot names in
891 @var{slots}, and signals an error if there are any duplicates
894 calls @code{make}, passing the metaclass as the first parameter and all
895 other parameters as option keywords with values.
898 @deffn procedure ensure-metaclass supers env
899 Return a metaclass suitable for a class that inherits from the list of
900 classes in @var{supers}. The returned metaclass is the union by
901 inheritance of the metaclasses of the classes in @var{supers}.
903 In the simplest case, where all the @var{supers} are straightforward
904 classes with metaclass @code{<class>}, the returned metaclass is just
907 For a more complex example, suppose that @var{supers} contained one
908 class with metaclass @code{<operator-class>} and one with metaclass
909 @code{<foreign-object-class>}. Then the returned metaclass would be a
910 class that inherits from both @code{<operator-class>} and
911 @code{<foreign-object-class>}.
913 If @var{supers} is the empty list, @code{ensure-metaclass} returns the
914 default GOOPS metaclass @code{<class>}.
916 GOOPS keeps a list of the metaclasses created by
917 @code{ensure-metaclass}, so that each required type of metaclass only
918 has to be created once.
920 The @code{env} parameter is ignored.
923 @deffn procedure ensure-metaclass-with-supers meta-supers
924 @code{ensure-metaclass-with-supers} is an internal procedure used by
925 @code{ensure-metaclass} (@pxref{Class Definition Internals,,
926 ensure-metaclass}). It returns a metaclass that is the union by
927 inheritance of the metaclasses in @var{meta-supers}.
930 The internals of @code{make}, which is ultimately used to create the new
931 class object, are described in @ref{Customizing Instance Creation},
932 which covers the creation and initialization of instances in general.
934 @node Customizing Class Definition
935 @subsubsection Customizing Class Definition
937 During the initialization of a new class, GOOPS calls a number of generic
938 functions with the newly allocated class instance as the first
939 argument. Specifically, GOOPS calls the generic function
943 (initialize @var{class} @dots{})
946 where @var{class} is the newly allocated class instance, and the default
947 @code{initialize} method for arguments of type @code{<class>} calls the
952 (compute-cpl @var{class})
955 (compute-slots @var{class})
958 (compute-get-n-set @var{class} @var{slot-def}), for each of the slot
959 definitions returned by @code{compute-slots}
962 (compute-getter-method @var{class} @var{slot-def}), for each of the
963 slot definitions returned by @code{compute-slots} that includes a
964 @code{#:getter} or @code{#:accessor} slot option
967 (compute-setter-method @var{class} @var{slot-def}), for each of the
968 slot definitions returned by @code{compute-slots} that includes a
969 @code{#:setter} or @code{#:accessor} slot option.
972 If the metaclass of the new class is something more specialized than the
973 default @code{<class>}, then the type of @var{class} in the calls above
974 is more specialized than @code{<class>}, and hence it becomes possible
975 to define generic function methods, specialized for the new class's
976 metaclass, that can modify or override the default behaviour of
977 @code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
979 @code{compute-cpl} computes the class precedence list (``CPL'') for the
980 new class (@pxref{Class precedence list}), and returns it as a list of
981 class objects. The CPL is important because it defines a superclass
982 ordering that is used, when a generic function is invoked upon an
983 instance of the class, to decide which of the available generic function
984 methods is the most specific. Hence @code{compute-cpl} could be
985 customized in order to modify the CPL ordering algorithm for all classes
986 with a special metaclass.
988 The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
989 procedure, which is in turn called by the default @code{compute-cpl}
992 @deffn procedure compute-std-cpl class
993 Compute and return the class precedence list for @var{class} according
994 to the algorithm described in @ref{Class precedence list}.
997 @code{compute-slots} computes and returns a list of all slot definitions
998 for the new class. By default, this list includes the direct slot
999 definitions from the @code{define-class} form, plus the slot definitions
1000 that are inherited from the new class's superclasses. The default
1001 @code{compute-slots} method uses the CPL computed by @code{compute-cpl}
1002 to calculate this union of slot definitions, with the rule that slots
1003 inherited from superclasses are shadowed by direct slots with the same
1004 name. One possible reason for customizing @code{compute-slots} would be
1005 to implement an alternative resolution strategy for slot name conflicts.
1007 @code{compute-get-n-set} computes the low-level closures that will be
1008 used to get and set the value of a particular slot, and returns them in
1009 a list with two elements.
1011 The closures returned depend on how storage for that slot is allocated.
1012 The standard @code{compute-get-n-set} method, specialized for classes of
1013 type @code{<class>}, handles the standard GOOPS values for the
1014 @code{#:allocation} slot option (@pxref{Slot Options,, allocation}). By
1015 defining a new @code{compute-get-n-set} method for a more specialized
1016 metaclass, it is possible to support new types of slot allocation.
1018 Suppose you wanted to create a large number of instances of some class
1019 with a slot that should be shared between some but not all instances of
1020 that class - say every 10 instances should share the same slot storage.
1021 The following example shows how to implement and use a new type of slot
1022 allocation to do this.
1025 (define-class <batched-allocation-metaclass> (<class>))
1027 (let ((batch-allocation-count 0)
1028 (batch-get-n-set #f))
1029 (define-method (compute-get-n-set
1030 (class <batched-allocation-metaclass>) s)
1031 (case (slot-definition-allocation s)
1033 ;; If we've already used the same slot storage for 10 instances,
1035 (if (= batch-allocation-count 10)
1037 (set! batch-allocation-count 0)
1038 (set! batch-get-n-set #f)))
1039 ;; If we don't have a current pair of get and set closures,
1040 ;; create one. make-closure-variable returns a pair of closures
1041 ;; around a single Scheme variable - see goops.scm for details.
1043 (set! batch-get-n-set (make-closure-variable)))
1044 ;; Increment the batch allocation count.
1045 (set! batch-allocation-count (+ batch-allocation-count 1))
1048 ;; Call next-method to handle standard allocation types.
1049 (else (next-method)))))
1051 (define-class <class-using-batched-slot> ()
1053 (c #:allocation #:batched)
1055 #:metaclass <batched-allocation-metaclass>)
1058 The usage of @code{compute-getter-method} and @code{compute-setter-method}
1059 is described in @ref{MOP Specification}.
1061 @code{compute-cpl} and @code{compute-get-n-set} are called by the
1062 standard @code{initialize} method for classes whose metaclass is
1063 @code{<class>}. But @code{initialize} itself can also be modified, by
1064 defining an @code{initialize} method specialized to the new class's
1065 metaclass. Such a method could complete override the standard
1066 behaviour, by not calling @code{(next-method)} at all, but more
1067 typically it would perform additional class initialization steps before
1068 and/or after calling @code{(next-method)} for the standard behaviour.
1070 @node STKlos Compatibility
1071 @subsubsection STKlos Compatibility
1073 If the STKlos compatibility module is loaded, @code{define-class} is
1074 overwritten by a STKlos-specific definition; the standard GOOPS
1075 definition of @code{define-class} remains available in
1076 @code{standard-define-class}.
1078 @deffn syntax standard-define-class name (super @dots{}) slot-definition @dots{} . options
1079 @code{standard-define-class} is equivalent to the standard GOOPS
1080 @code{define-class}.
1083 @node Creating Instances
1084 @subsection Creating Instances
1087 * Basic Instance Creation::
1088 * Customizing Instance Creation::
1091 @node Basic Instance Creation
1092 @subsubsection Basic Instance Creation
1094 To create a new instance of any GOOPS class, use the generic function
1095 @code{make} or @code{make-instance}, passing the required class and any
1096 appropriate instance initialization arguments as keyword and value
1097 pairs. Note that @code{make} and @code{make-instances} are aliases for
1098 each other - their behaviour is identical.
1101 @deffnx method make (class <class>) . initargs
1102 Create and return a new instance of class @var{class}, initialized using
1105 In theory, @var{initargs} can have any structure that is understood by
1106 whatever methods get applied when the @code{initialize} generic function
1107 is applied to the newly allocated instance.
1109 In practice, specialized @code{initialize} methods would normally call
1110 @code{(next-method)}, and so eventually the standard GOOPS
1111 @code{initialize} methods are applied. These methods expect
1112 @var{initargs} to be a list with an even number of elements, where
1113 even-numbered elements (counting from zero) are keywords and
1114 odd-numbered elements are the corresponding values.
1116 GOOPS processes initialization argument keywords automatically for slots
1117 whose definition includes the @code{#:init-keyword} option (@pxref{Slot
1118 Options,, init-keyword}). Other keyword value pairs can only be
1119 processed by an @code{initialize} method that is specialized for the new
1120 instance's class. Any unprocessed keyword value pairs are ignored.
1123 @deffn generic make-instance
1124 @deffnx method make-instance (class <class>) . initargs
1125 @code{make-instance} is an alias for @code{make}.
1128 @node Customizing Instance Creation
1129 @subsubsection Customizing Instance Creation
1131 @code{make} itself is a generic function. Hence the @code{make}
1132 invocation itself can be customized in the case where the new instance's
1133 metaclass is more specialized than the default @code{<class>}, by
1134 defining a @code{make} method that is specialized to that metaclass.
1136 Normally, however, the method for classes with metaclass @code{<class>}
1137 will be applied. This method calls two generic functions:
1141 (allocate-instance @var{class} . @var{initargs})
1144 (initialize @var{instance} . @var{initargs})
1147 @code{allocate-instance} allocates storage for and returns the new
1148 instance, uninitialized. You might customize @code{allocate-instance},
1149 for example, if you wanted to provide a GOOPS wrapper around some other
1150 object programming system.
1152 To do this, you would create a specialized metaclass, which would act as
1153 the metaclass for all classes and instances from the other system. Then
1154 define an @code{allocate-instance} method, specialized to that
1155 metaclass, which calls a Guile primitive C function, which in turn
1156 allocates the new instance using the interface of the other object
1159 In this case, for a complete system, you would also need to customize a
1160 number of other generic functions like @code{make} and
1161 @code{initialize}, so that GOOPS knows how to make classes from the
1162 other system, access instance slots, and so on.
1164 @code{initialize} initializes the instance that is returned by
1165 @code{allocate-instance}. The standard GOOPS methods perform
1166 initializations appropriate to the instance class.
1170 At the least specialized level, the method for instances of type
1171 @code{<object>} performs internal GOOPS instance initialization, and
1172 initializes the instance's slots according to the slot definitions and
1173 any slot initialization keywords that appear in @var{initargs}.
1176 The method for instances of type @code{<class>} calls
1177 @code{(next-method)}, then performs the class initializations described
1178 in @ref{Customizing Class Definition}.
1181 and so on for generic functions, method, operator classes @dots{}
1184 Similarly, you can customize the initialization of instances of any
1185 application-defined class by defining an @code{initialize} method
1186 specialized to that class.
1188 Imagine a class whose instances' slots need to be initialized at
1189 instance creation time by querying a database. Although it might be
1190 possible to achieve this a combination of @code{#:init-thunk} keywords
1191 and closures in the slot definitions, it is neater to write an
1192 @code{initialize} method for the class that queries the database once
1193 and initializes all the dependent slot values according to the results.
1195 @node Accessing Slots
1196 @subsection Accessing Slots
1198 The definition of a slot contains at the very least a slot name, and may
1199 also contain various slot options, including getter, setter and/or
1200 accessor functions for the slot.
1202 It is always possible to access slots by name, using the various
1203 ``slot-ref'' and ``slot-set!'' procedures described in the following
1204 subsubsections. For example,
1207 (define-class <my-class> () ;; Define a class with slots
1208 (count #:init-value 0) ;; named "count" and "cache".
1209 (cache #:init-value '())
1212 (define inst (make <my-class>)) ;; Make an instance of this class.
1214 (slot-set! inst 'count 5) ;; Set the value of the "count"
1217 (slot-set! inst 'cache ;; Modify the value of the
1218 (cons (cons "^it" "It") ;; "cache" slot.
1219 (slot-ref inst 'cache)))
1222 If a slot definition includes a getter, setter or accessor function,
1223 these can be used instead of @code{slot-ref} and @code{slot-set!} to
1227 (define-class <adv-class> () ;; Define a new class whose slots
1228 (count #:setter set-count) ;; use a getter, a setter and
1229 (cache #:accessor cache) ;; an accessor.
1230 (csize #:getter cache-size)
1233 (define inst (make <adv-class>)) ;; Make an instance of this class.
1235 (set-count inst 5) ;; Set the value of the "count"
1238 (set! (cache inst) ;; Modify the value of the
1239 (cons (cons "^it" "It") ;; "cache" slot.
1242 (let ((size (cache-size inst))) ;; Get the value of the "csize"
1246 Whichever of these methods is used to access slots, GOOPS always calls
1247 the low-level @dfn{getter} and @dfn{setter} closures for the slot to get
1248 and set its value. These closures make sure that the slot behaves
1249 according to the @code{#:allocation} type that was specified in the slot
1250 definition (@pxref{Slot Options,, allocation}). (For more about these
1251 closures, see @ref{Customizing Class Definition,, compute-get-n-set}.)
1256 * Handling Slot Access Errors::
1259 @node Instance Slots
1260 @subsubsection Instance Slots
1262 Any slot, regardless of its allocation, can be queried, referenced and
1263 set using the following four primitive procedures.
1265 @deffn {primitive procedure} slot-exists? obj slot-name
1266 Return @code{#t} if @var{obj} has a slot with name @var{slot-name},
1267 otherwise @code{#f}.
1270 @deffn {primitive procedure} slot-bound? obj slot-name
1271 Return @code{#t} if the slot named @var{slot-name} in @var{obj} has a
1272 value, otherwise @code{#f}.
1274 @code{slot-bound?} calls the generic function @code{slot-missing} if
1275 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1276 Slot Access Errors, slot-missing}).
1279 @deffn {primitive procedure} slot-ref obj slot-name
1280 Return the value of the slot named @var{slot-name} in @var{obj}.
1282 @code{slot-ref} calls the generic function @code{slot-missing} if
1283 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1284 Slot Access Errors, slot-missing}).
1286 @code{slot-ref} calls the generic function @code{slot-unbound} if the
1287 named slot in @var{obj} does not have a value (@pxref{Handling Slot
1288 Access Errors, slot-unbound}).
1291 @deffn {primitive procedure} slot-set! obj slot-name value
1292 Set the value of the slot named @var{slot-name} in @var{obj} to @var{value}.
1294 @code{slot-set!} calls the generic function @code{slot-missing} if
1295 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1296 Slot Access Errors, slot-missing}).
1299 GOOPS stores information about slots in class metaobjects. Internally,
1300 all of these procedures work by looking up the slot definition for the
1301 slot named @var{slot-name} in the class metaobject for @code{(class-of
1302 @var{obj})}, and then using the slot definition's ``getter'' and
1303 ``setter'' closures to get and set the slot value.
1305 The next four procedures differ from the previous ones in that they take
1306 the class metaobject as an explicit argument, rather than assuming
1307 @code{(class-of @var{obj})}. Therefore they allow you to apply the
1308 ``getter'' and ``setter'' closures of a slot definition in one class to
1309 an instance of a different class.
1311 [ *fixme* I have no idea why this is useful! Perhaps when a slot in
1312 @code{(class-of @var{obj})} shadows a slot with the same name in one of
1313 its superclasses? There should be an enlightening example here. ]
1315 @deffn {primitive procedure} slot-exists-using-class? class obj slot-name
1316 Return @code{#t} if the class metaobject @var{class} has a slot
1317 definition for a slot with name @var{slot-name}, otherwise @code{#f}.
1320 @deffn {primitive procedure} slot-bound-using-class? class obj slot-name
1321 Return @code{#t} if applying @code{slot-ref-using-class} to the same
1322 arguments would call the generic function @code{slot-unbound}, otherwise
1325 @code{slot-bound-using-class?} calls the generic function
1326 @code{slot-missing} if @var{class} does not have a slot definition for a
1327 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1331 @deffn {primitive procedure} slot-ref-using-class class obj slot-name
1332 Apply the ``getter'' closure for the slot named @var{slot-name} in
1333 @var{class} to @var{obj}, and return its result.
1335 @code{slot-ref-using-class} calls the generic function
1336 @code{slot-missing} if @var{class} does not have a slot definition for a
1337 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1340 @code{slot-ref-using-class} calls the generic function
1341 @code{slot-unbound} if the application of the ``getter'' closure to
1342 @var{obj} returns an unbound value (@pxref{Handling Slot Access Errors,
1346 @deffn {primitive procedure} slot-set-using-class! class obj slot-name value
1347 Apply the ``setter'' closure for the slot named @var{slot-name} in
1348 @var{class} to @var{obj} and @var{value}.
1350 @code{slot-set-using-class!} calls the generic function
1351 @code{slot-missing} if @var{class} does not have a slot definition for a
1352 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1357 @subsubsection Class Slots
1359 Slots whose allocation is per-class rather than per-instance can be
1360 referenced and set without needing to specify any particular instance.
1362 @deffn procedure class-slot-ref class slot-name
1363 Return the value of the slot named @var{slot-name} in class @var{class}.
1364 The named slot must have @code{#:class} or @code{#:each-subclass}
1365 allocation (@pxref{Slot Options,, allocation}).
1367 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1368 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1369 function with arguments @var{class} and @var{slot-name}. Otherwise, if
1370 the slot value is unbound, @code{class-slot-ref} calls the
1371 @code{slot-missing} generic function, with the same arguments.
1374 @deffn procedure class-slot-set! class slot-name value
1375 Set the value of the slot named @var{slot-name} in class @var{class} to
1376 @var{value}. The named slot must have @code{#:class} or
1377 @code{#:each-subclass} allocation (@pxref{Slot Options,, allocation}).
1379 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1380 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1381 function with arguments @var{class} and @var{slot-name}.
1384 @node Handling Slot Access Errors
1385 @subsubsection Handling Slot Access Errors
1387 GOOPS calls one of the following generic functions when a ``slot-ref''
1388 or ``slot-set!'' call specifies a non-existent slot name, or tries to
1389 reference a slot whose value is unbound.
1391 @deffn generic slot-missing
1392 @deffnx method slot-missing (class <class>) slot-name
1393 @deffnx method slot-missing (class <class>) (object <object>) slot-name
1394 @deffnx method slot-missing (class <class>) (object <object>) slot-name value
1395 When an application attempts to reference or set a class or instance
1396 slot by name, and the slot name is invalid for the specified @var{class}
1397 or @var{object}, GOOPS calls the @code{slot-missing} generic function.
1399 The default methods all call @code{goops-error} with an appropriate
1403 @deffn generic slot-unbound
1404 @deffnx method slot-unbound (object <object>)
1405 @deffnx method slot-unbound (class <class>) slot-name
1406 @deffnx method slot-unbound (class <class>) (object <object>) slot-name
1407 When an application attempts to reference a class or instance slot, and
1408 the slot's value is unbound, GOOPS calls the @code{slot-unbound} generic
1411 The default methods all call @code{goops-error} with an appropriate
1415 @node Creating Generic Functions
1416 @subsection Creating Generic Functions
1418 A generic function is a collection of methods, with rules for
1419 determining which of the methods should be applied for any given
1420 invocation of the generic function.
1422 GOOPS represents generic functions as metaobjects of the class
1423 @code{<generic>} (or one of its subclasses).
1426 * Basic Generic Function Creation::
1427 * Generic Function Internals::
1428 * Extending Guiles Primitives::
1431 @node Basic Generic Function Creation
1432 @subsubsection Basic Generic Function Creation
1434 The following forms may be used to bind a variable to a generic
1435 function. Depending on that variable's pre-existing value, the generic
1436 function may be created empty - with no methods - or it may contain
1437 methods that are inferred from the pre-existing value.
1439 It is not, in general, necessary to use @code{define-generic} or
1440 @code{define-accessor} before defining methods for the generic function
1441 using @code{define-method}, since @code{define-method} will
1442 automatically interpolate a @code{define-generic} call, or upgrade an
1443 existing generic to an accessor, if that is implied by the
1444 @code{define-method} call. Note in particular that,
1445 if the specified variable already has a @emph{generic function} value,
1446 @code{define-generic} and @code{define-accessor} will @emph{discard} it!
1447 Obviously it is application-dependent whether this is desirable or not.
1449 If, for example, you wanted to extend @code{+} for a class representing
1450 a new numerical type, you probably want to inherit any existing methods
1451 for @code{+} and so should not use @code{define-generic}. If, on the
1452 other hand, you do not want to risk inheriting methods whose behaviour
1453 might surprise you, you can use @code{define-generic} or
1454 @code{define-accessor} to wipe the slate clean.
1456 @deffn syntax define-generic symbol
1457 Create a generic function with name @var{symbol} and bind it to the
1458 variable @var{symbol}.
1460 If the variable @var{symbol} was previously bound to a Scheme procedure
1461 (or procedure-with-setter), the old procedure (and setter) is
1462 incorporated into the new generic function as its default procedure (and
1463 setter). Any other previous value that was bound to @var{symbol},
1464 including an existing generic function, is overwritten by the new
1468 @deffn syntax define-accessor symbol
1469 Create an accessor with name @var{symbol} and bind it to the variable
1472 If the variable @var{symbol} was previously bound to a Scheme procedure
1473 (or procedure-with-setter), the old procedure (and setter) is
1474 incorporated into the new accessor as its default procedure (and
1475 setter). Any other previous value that was bound to @var{symbol},
1476 including an existing generic function or accessor, is overwritten by
1480 It is sometimes tempting to use GOOPS accessors with short names. For
1481 example, it is tempting to use the name @code{x} for the x-coordinate
1484 Assume that we work with a graphical package which needs to use two
1485 independent vector packages for 2D and 3D vectors respectively. If
1486 both packages export @code{x} we will encounter a name collision.
1488 This can be resolved automagically with the duplicates handler
1489 @code{merge-generics} which gives the module system license to merge
1490 all generic functions sharing a common name:
1493 (define-module (math 2D-vectors)
1494 :use-module (oop goops)
1497 (define-module (math 3D-vectors)
1498 :use-module (oop goops)
1499 :export (x y z ...))
1501 (define-module (my-module)
1502 :use-module (math 2D-vectors)
1503 :use-module (math 3D-vectors)
1504 :duplicates merge-generics)
1507 The generic function @code{x} in @code{(my-module)} will now share
1508 methods with @code{x} in both imported modules.
1510 There will, in fact, now be three distinct generic functions named
1511 @code{x}: @code{x} in @code{(2D-vectors)}, @code{x} in
1512 @code{(3D-vectors)}, and @code{x} in @code{(my-module)}. The last
1513 function will be an @code{<extended-generic>}, extending the previous
1516 Let's call the imported generic functions the "ancestor functions".
1517 The generic function @code{x} in @code{(my-module)} is, in turn, a
1518 "descendant function" of the imported functions, extending its
1521 For any generic function G, the applicable methods are selected from
1522 the union of the methods of the descendant functions, the methods of G
1523 itself and the methods of the ancestor functions.
1525 This, ancestor functions share methods with their descendants and vice
1526 versa. This implies that @code{x} in @code{(math 2D-vectors)} will
1527 share the methods of @code{x} in @code{(my-module)} and vice versa,
1528 while @code{x} in @code{(math 2D-vectors)} doesn't share the methods
1529 of @code{x} in @code{(math 3D-vectors)}, thus preserving modularity.
1531 Sharing is dynamic, so that adding new methods to a descendant implies
1532 adding it to the ancestor.
1534 If duplicates checking is desired in the above example, the following
1535 form of the @code{:duplicates} option can be used instead:
1538 :duplicates (merge-generics check)
1541 @node Generic Function Internals
1542 @subsubsection Generic Function Internals
1544 @code{define-generic} calls @code{ensure-generic} to upgrade a
1545 pre-existing procedure value, or @code{make} with metaclass
1546 @code{<generic>} to create a new generic function.
1548 @code{define-accessor} calls @code{ensure-accessor} to upgrade a
1549 pre-existing procedure value, or @code{make-accessor} to create a new
1552 @deffn procedure ensure-generic old-definition [name]
1553 Return a generic function with name @var{name}, if possible by using or
1554 upgrading @var{old-definition}. If unspecified, @var{name} defaults to
1557 If @var{old-definition} is already a generic function, it is returned
1560 If @var{old-definition} is a Scheme procedure or procedure-with-setter,
1561 @code{ensure-generic} returns a new generic function that uses
1562 @var{old-definition} for its default procedure and setter.
1564 Otherwise @code{ensure-generic} returns a new generic function with no
1565 defaults and no methods.
1568 @deffn procedure make-generic [name]
1569 Return a new generic function with name @code{(car @var{name})}. If
1570 unspecified, @var{name} defaults to @code{#f}.
1573 @code{ensure-generic} calls @code{make} with metaclasses
1574 @code{<generic>} and @code{<generic-with-setter>}, depending on the
1575 previous value of the variable that it is trying to upgrade.
1577 @code{make-generic} is a simple wrapper for @code{make} with metaclass
1580 @deffn procedure ensure-accessor proc [name]
1581 Return an accessor with name @var{name}, if possible by using or
1582 upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
1584 If @var{proc} is already an accessor, it is returned unchanged.
1586 If @var{proc} is a Scheme procedure, procedure-with-setter or generic
1587 function, @code{ensure-accessor} returns an accessor that reuses the
1588 reusable elements of @var{proc}.
1590 Otherwise @code{ensure-accessor} returns a new accessor with no defaults
1594 @deffn procedure make-accessor [name]
1595 Return a new accessor with name @code{(car @var{name})}. If
1596 unspecified, @var{name} defaults to @code{#f}.
1599 @code{ensure-accessor} calls @code{make} with
1600 metaclass @code{<generic-with-setter>}, as well as calls to
1601 @code{ensure-generic}, @code{make-accessor} and (tail recursively)
1602 @code{ensure-accessor}.
1604 @code{make-accessor} calls @code{make} twice, first
1605 with metaclass @code{<generic>} to create a generic function for the
1606 setter, then with metaclass @code{<generic-with-setter>} to create the
1607 accessor, passing the setter generic function as the value of the
1608 @code{#:setter} keyword.
1610 @node Extending Guiles Primitives
1611 @subsubsection Extending Guile's Primitives
1613 When GOOPS is loaded, many of Guile's primitive procedures can be
1614 extended by giving them a generic function definition that operates
1615 in conjunction with their normal C-coded implementation. For
1616 primitives that are extended in this way, the result from the user-
1617 or application-level point of view is that the extended primitive
1618 behaves exactly like a generic function with the C-coded implementation
1619 as its default method.
1621 The @code{generic-capability?} predicate should be used to determine
1622 whether a particular primitive is extensible in this way.
1624 @deffn {primitive procedure} generic-capability? primitive
1625 Return @code{#t} if @var{primitive} can be extended by giving it a
1626 generic function definition, otherwise @code{#f}.
1629 Even when a primitive procedure is extensible like this, its generic
1630 function definition is not created until it is needed by a call to
1631 @code{define-method}, or until the application explicitly requests it
1632 by calling @code{enable-primitive-generic!}.
1634 @deffn {primitive procedure} enable-primitive-generic! primitive
1635 Force the creation of a generic function definition for
1639 Once the generic function definition for a primitive has been created,
1640 it can be retrieved using @code{primitive-generic-generic}.
1642 @deffn {primitive procedure} primitive-generic-generic primitive
1643 Return the generic function definition of @var{primitive}.
1645 @code{primitive-generic-generic} raises an error if @var{primitive}
1646 is not a primitive with generic capability, or if its generic capability
1647 has not yet been enabled, whether implicitly (by @code{define-method})
1648 or explicitly (by @code{enable-primitive-generic!}).
1651 Note that the distinction between, on the one hand, primitives with
1652 additional generic function definitions and, on the other hand, generic
1653 functions with a default method, may disappear when GOOPS is fully
1654 integrated into the core of Guile. Consequently, the
1655 procedures described in this section may disappear as well.
1657 @node Adding Methods to Generic Functions
1658 @subsection Adding Methods to Generic Functions
1661 * Basic Method Definition::
1662 * Method Definition Internals::
1665 @node Basic Method Definition
1666 @subsubsection Basic Method Definition
1668 To add a method to a generic function, use the @code{define-method} form.
1670 @deffn syntax define-method (generic parameter @dots{}) . body
1671 Define a method for the generic function or accessor @var{generic} with
1672 parameters @var{parameter}s and body @var{body}.
1674 @var{generic} is a generic function. If @var{generic} is a variable
1675 which is not yet bound to a generic function object, the expansion of
1676 @code{define-method} will include a call to @code{define-generic}. If
1677 @var{generic} is @code{(setter @var{generic-with-setter})}, where
1678 @var{generic-with-setter} is a variable which is not yet bound to a
1679 generic-with-setter object, the expansion will include a call to
1680 @code{define-accessor}.
1682 Each @var{parameter} must be either a symbol or a two-element list
1683 @code{(@var{symbol} @var{class})}. The symbols refer to variables in
1684 the @var{body} that will be bound to the parameters supplied by the
1685 caller when calling this method. The @var{class}es, if present,
1686 specify the possible combinations of parameters to which this method
1689 @var{body} is the body of the method definition.
1692 @code{define-method} expressions look a little like normal Scheme
1693 procedure definitions of the form
1696 (define (name formals @dots{}) . body)
1699 The most important difference is that each formal parameter, apart from the
1700 possible ``rest'' argument, can be qualified by a class name:
1701 @code{@var{formal}} becomes @code{(@var{formal} @var{class})}. The
1702 meaning of this qualification is that the method being defined
1703 will only be applicable in a particular generic function invocation if
1704 the corresponding argument is an instance of @code{@var{class}} (or one of
1705 its subclasses). If more than one of the formal parameters is qualified
1706 in this way, then the method will only be applicable if each of the
1707 corresponding arguments is an instance of its respective qualifying class.
1709 Note that unqualified formal parameters act as though they are qualified
1710 by the class @code{<top>}, which GOOPS uses to mean the superclass of
1711 all valid Scheme types, including both primitive types and GOOPS classes.
1713 For example, if a generic function method is defined with
1714 @var{parameter}s @code{((s1 <square>) (n <number>))}, that method is
1715 only applicable to invocations of its generic function that have two
1716 parameters where the first parameter is an instance of the
1717 @code{<square>} class and the second parameter is a number.
1719 If a generic function is invoked with a combination of parameters for which
1720 there is no applicable method, GOOPS raises an error. For more about
1721 invocation error handling, and generic function invocation in general,
1722 see @ref{Invoking Generic Functions}.
1724 @node Method Definition Internals
1725 @subsubsection Method Definition Internals
1727 @code{define-method}
1731 checks the form of the first parameter, and applies the following steps
1732 to the accessor's setter if it has the @code{(setter @dots{})} form
1735 interpolates a call to @code{define-generic} or @code{define-accessor}
1736 if a generic function is not already defined with the supplied name
1739 calls @code{method} with the @var{parameter}s and @var{body}, to make a
1743 calls @code{add-method!} to add this method to the relevant generic
1747 @deffn syntax method (parameter @dots{}) . body
1748 Make a method whose specializers are defined by the classes in
1749 @var{parameter}s and whose procedure definition is constructed from the
1750 @var{parameter} symbols and @var{body} forms.
1752 The @var{parameter} and @var{body} parameters should be as for
1753 @code{define-method} (@pxref{Basic Method Definition,, define-method}).
1760 extracts formals and specializing classes from the @var{parameter}s,
1761 defaulting the class for unspecialized parameters to @code{<top>}
1764 creates a closure using the formals and the @var{body} forms
1767 calls @code{make} with metaclass @code{<method>} and the specializers
1768 and closure using the @code{#:specializers} and @code{#:procedure}
1772 @deffn procedure make-method specializers procedure
1773 Make a method using @var{specializers} and @var{procedure}.
1775 @var{specializers} should be a list of classes that specifies the
1776 parameter combinations to which this method will be applicable.
1778 @var{procedure} should be the closure that will applied to the generic
1779 function parameters when this method is invoked.
1782 @code{make-method} is a simple wrapper around @code{make} with metaclass
1785 @deffn generic add-method! target method
1786 Generic function for adding method @var{method} to @var{target}.
1789 @deffn method add-method! (generic <generic>) (method <method>)
1790 Add method @var{method} to the generic function @var{generic}.
1793 @deffn method add-method! (proc <procedure>) (method <method>)
1794 If @var{proc} is a procedure with generic capability (@pxref{Extending
1795 Guiles Primitives,, generic-capability?}), upgrade it to a
1796 primitive generic and add @var{method} to its generic function
1800 @deffn method add-method! (pg <primitive-generic>) (method <method>)
1801 Add method @var{method} to the generic function definition of @var{pg}.
1803 Implementation: @code{(add-method! (primitive-generic-generic pg) method)}.
1806 @deffn method add-method! (whatever <top>) (method <method>)
1807 Raise an error indicating that @var{whatever} is not a valid generic
1811 @node Invoking Generic Functions
1812 @subsection Invoking Generic Functions
1814 When a variable with a generic function definition appears as the first
1815 element of a list that is being evaluated, the Guile evaluator tries
1816 to apply the generic function to the arguments obtained by evaluating
1817 the remaining elements of the list. [ *fixme* How do I put this in a
1818 more Schemely and less Lispy way? ]
1820 Usually a generic function contains several method definitions, with
1821 varying degrees of formal parameter specialization (@pxref{Basic
1822 Method Definition,, define-method}). So it is necessary to sort these
1823 methods by specificity with respect to the supplied arguments, and then
1824 apply the most specific method definition. Less specific methods
1825 may be applied subsequently if a method that is being applied calls
1829 * Determining Which Methods to Apply::
1830 * Handling Invocation Errors::
1833 @node Determining Which Methods to Apply
1834 @subsubsection Determining Which Methods to Apply
1836 [ *fixme* Sorry - this is the area of GOOPS that I understand least of
1837 all, so I'm afraid I have to pass on this section. Would some other
1838 kind person consider filling it in? ]
1840 @deffn generic apply-generic
1841 @deffnx method apply-generic (gf <generic>) args
1844 @deffn generic compute-applicable-methods
1845 @deffnx method compute-applicable-methods (gf <generic>) args
1848 @deffn generic sort-applicable-methods
1849 @deffnx method sort-applicable-methods (gf <generic>) methods args
1852 @deffn generic method-more-specific?
1853 @deffnx method method-more-specific? (m1 <method>) (m2 <method>) args
1856 @deffn generic apply-method
1857 @deffnx method apply-method (gf <generic>) methods build-next args
1860 @deffn generic apply-methods
1861 @deffnx method apply-methods (gf <generic>) (l <list>) args
1864 @node Handling Invocation Errors
1865 @subsubsection Handling Invocation Errors
1867 @deffn generic no-method
1868 @deffnx method no-method (gf <generic>) args
1869 When an application invokes a generic function, and no methods at all
1870 have been defined for that generic function, GOOPS calls the
1871 @code{no-method} generic function. The default method calls
1872 @code{goops-error} with an appropriate message.
1875 @deffn generic no-applicable-method
1876 @deffnx method no-applicable-method (gf <generic>) args
1877 When an application applies a generic function to a set of arguments,
1878 and no methods have been defined for those argument types, GOOPS calls
1879 the @code{no-applicable-method} generic function. The default method
1880 calls @code{goops-error} with an appropriate message.
1883 @deffn generic no-next-method
1884 @deffnx method no-next-method (gf <generic>) args
1885 When a generic function method calls @code{(next-method)} to invoke the
1886 next less specialized method for that generic function, and no less
1887 specialized methods have been defined for the current generic function
1888 arguments, GOOPS calls the @code{no-next-method} generic function. The
1889 default method calls @code{goops-error} with an appropriate message.
1892 @node Redefining a Class
1893 @subsection Redefining a Class
1895 Suppose that a class @code{<my-class>} is defined using @code{define-class}
1896 (@pxref{Basic Class Definition,, define-class}), with slots that have
1897 accessor functions, and that an application has created several instances
1898 of @code{<my-class>} using @code{make} (@pxref{Basic Instance Creation,,
1899 make}). What then happens if @code{<my-class>} is redefined by calling
1900 @code{define-class} again?
1903 * Default Class Redefinition Behaviour::
1904 * Customizing Class Redefinition::
1907 @node Default Class Redefinition Behaviour
1908 @subsubsection Default Class Redefinition Behaviour
1910 GOOPS' default answer to this question is as follows.
1914 All existing direct instances of @code{<my-class>} are converted to be
1915 instances of the new class. This is achieved by preserving the values
1916 of slots that exist in both the old and new definitions, and initializing the
1917 values of new slots in the usual way (@pxref{Basic Instance Creation,,
1921 All existing subclasses of @code{<my-class>} are redefined, as though
1922 the @code{define-class} expressions that defined them were re-evaluated
1923 following the redefinition of @code{<my-class>}, and the class
1924 redefinition process described here is applied recursively to the
1925 redefined subclasses.
1928 Once all of its instances and subclasses have been updated, the class
1929 metaobject previously bound to the variable @code{<my-class>} is no
1930 longer needed and so can be allowed to be garbage collected.
1933 To keep things tidy, GOOPS also needs to do a little housekeeping on
1934 methods that are associated with the redefined class.
1938 Slot accessor methods for slots in the old definition should be removed
1939 from their generic functions. They will be replaced by accessor methods
1940 for the slots of the new class definition.
1943 Any generic function method that uses the old @code{<my-class>} metaobject
1944 as one of its formal parameter specializers must be updated to refer to
1945 the new @code{<my-class>} metaobject. (Whenever a new generic function
1946 method is defined, @code{define-method} adds the method to a list stored
1947 in the class metaobject for each class used as a formal parameter
1948 specializer, so it is easy to identify all the methods that must be
1949 updated when a class is redefined.)
1952 If this class redefinition strategy strikes you as rather counter-intuitive,
1953 bear in mind that it is derived from similar behaviour in other object
1954 systems such as CLOS, and that experience in those systems has shown it to be
1955 very useful in practice.
1957 Also bear in mind that, like most of GOOPS' default behaviour, it can
1958 be customized@dots{}
1960 @node Customizing Class Redefinition
1961 @subsubsection Customizing Class Redefinition
1963 When @code{define-class} notices that a class is being redefined,
1964 it constructs the new class metaobject as usual, and then invokes the
1965 @code{class-redefinition} generic function with the old and new classes
1966 as arguments. Therefore, if the old or new classes have metaclasses
1967 other than the default @code{<class>}, class redefinition behaviour can
1968 be customized by defining a @code{class-redefinition} method that is
1969 specialized for the relevant metaclasses.
1971 @deffn generic class-redefinition
1972 Handle the class redefinition from @var{old-class} to @var{new-class},
1973 and return the new class metaobject that should be bound to the
1974 variable specified by @code{define-class}'s first argument.
1977 @deffn method class-redefinition (old-class <class>) (new-class <class>)
1978 Implements GOOPS' default class redefinition behaviour, as described in
1979 @ref{Default Class Redefinition Behaviour}. Returns the metaobject
1980 for the new class definition.
1983 An alternative class redefinition strategy could be to leave all
1984 existing instances as instances of the old class, but accepting that the
1985 old class is now ``nameless'', since its name has been taken over by the
1986 new definition. In this strategy, any existing subclasses could also
1987 be left as they are, on the understanding that they inherit from a nameless
1990 This strategy is easily implemented in GOOPS, by defining a new metaclass,
1991 that will be used as the metaclass for all classes to which the strategy
1992 should apply, and then defining a @code{class-redefinition} method that
1993 is specialized for this metaclass:
1996 (define-class <can-be-nameless> (<class>))
1998 (define-method (class-redefinition (old <can-be-nameless>)
2003 When customization can be as easy as this, aren't you glad that GOOPS
2004 implements the far more difficult strategy as its default!
2006 Finally, note that, if @code{class-redefinition} itself is not customized,
2007 the default @code{class-redefinition} method invokes three further
2008 generic functions that could be individually customized:
2012 (remove-class-accessors! @var{old-class})
2015 (update-direct-method! @var{method} @var{old-class} @var{new-class})
2018 (update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
2021 and the default methods for these generic functions invoke further
2022 generic functions, and so on@dots{} The detailed protocol for all of these
2023 is described in @ref{MOP Specification}.
2025 @node Changing the Class of an Instance
2026 @subsection Changing the Class of an Instance
2028 You can change the class of an existing instance by invoking the
2029 generic function @code{change-class} with two arguments: the instance
2032 @deffn generic change-class
2035 The default method for @code{change-class} decides how to implement the
2036 change of class by looking at the slot definitions for the instance's
2037 existing class and for the new class. If the new class has slots with
2038 the same name as slots in the existing class, the values for those slots
2039 are preserved. Slots that are present only in the existing class are
2040 discarded. Slots that are present only in the new class are initialized
2041 using the corresponding slot definition's init function (@pxref{Classes,,
2042 slot-init-function}).
2044 @deffn {method} change-class (obj <object>) (new <class>)
2045 Modify instance @var{obj} to make it an instance of class @var{new}.
2047 The value of each of @var{obj}'s slots is preserved only if a similarly named
2048 slot exists in @var{new}; any other slot values are discarded.
2050 The slots in @var{new} that do not correspond to any of @var{obj}'s
2051 pre-existing slots are initialized according to @var{new}'s slot definitions'
2055 Customized change of class behaviour can be implemented by defining
2056 @code{change-class} methods that are specialized either by the class
2057 of the instances to be modified or by the metaclass of the new class.
2059 When a class is redefined (@pxref{Redefining a Class}), and the default
2060 class redefinition behaviour is not overridden, GOOPS (eventually)
2061 invokes the @code{change-class} generic function for each existing
2062 instance of the redefined class.
2065 @subsection Introspection
2067 @dfn{Introspection}, also known as @dfn{reflection}, is the name given
2068 to the ability to obtain information dynamically about GOOPS metaobjects.
2069 It is perhaps best illustrated by considering an object oriented language
2070 that does not provide any introspection, namely C++.
2072 Nothing in C++ allows a running program to obtain answers to the following
2077 What are the data members of this object or class?
2080 What classes does this class inherit from?
2083 Is this method call virtual or non-virtual?
2086 If I invoke @code{Employee::adjustHoliday()}, what class contains the
2087 @code{adjustHoliday()} method that will be applied?
2090 In C++, answers to such questions can only be determined by looking at
2091 the source code, if you have access to it. GOOPS, on the other hand,
2092 includes procedures that allow answers to these questions --- or their
2093 GOOPS equivalents --- to be obtained dynamically, at run time.
2099 * Generic Functions::
2100 * Generic Function Methods::
2104 @subsubsection Classes
2106 @deffn {primitive procedure} class-name class
2107 Return the name of class @var{class}.
2108 This is the value of the @var{class} metaobject's @code{name} slot.
2111 @deffn {primitive procedure} class-direct-supers class
2112 Return a list containing the direct superclasses of @var{class}.
2113 This is the value of the @var{class} metaobject's
2114 @code{direct-supers} slot.
2117 @deffn {primitive procedure} class-direct-slots class
2118 Return a list containing the slot definitions of the direct slots of
2120 This is the value of the @var{class} metaobject's @code{direct-slots}
2124 @deffn {primitive procedure} class-direct-subclasses class
2125 Return a list containing the direct subclasses of @var{class}.
2126 This is the value of the @var{class} metaobject's
2127 @code{direct-subclasses} slot.
2130 @deffn {primitive procedure} class-direct-methods class
2131 Return a list of all the generic function methods that use @var{class}
2132 as a formal parameter specializer.
2133 This is the value of the @var{class} metaobject's @code{direct-methods}
2137 @deffn {primitive procedure} class-precedence-list class
2138 Return the class precedence list for class @var{class} (@pxref{Class
2140 This is the value of the @var{class} metaobject's @code{cpl} slot.
2143 @deffn {primitive procedure} class-slots class
2144 Return a list containing the slot definitions for all @var{class}'s slots,
2145 including any slots that are inherited from superclasses.
2146 This is the value of the @var{class} metaobject's @code{slots} slot.
2149 @deffn {primitive procedure} class-environment class
2150 Return the value of @var{class}'s @code{environment} slot.
2151 [ *fixme* I don't know what this value is used for. ]
2154 @deffn procedure class-subclasses class
2155 Return a list of all subclasses of @var{class}.
2158 @deffn procedure class-methods class
2159 Return a list of all methods that use @var{class} or a subclass of
2160 @var{class} as one of its formal parameter specializers.
2164 @subsubsection Slots
2166 @deffn procedure class-slot-definition class slot-name
2167 Return the slot definition for the slot named @var{slot-name} in class
2168 @var{class}. @var{slot-name} should be a symbol.
2171 @deffn procedure slot-definition-name slot-def
2172 Extract and return the slot name from @var{slot-def}.
2175 @deffn procedure slot-definition-options slot-def
2176 Extract and return the slot options from @var{slot-def}.
2179 @deffn procedure slot-definition-allocation slot-def
2180 Extract and return the slot allocation option from @var{slot-def}. This
2181 is the value of the @code{#:allocation} keyword (@pxref{Slot Options,,
2182 allocation}), or @code{#:instance} if the @code{#:allocation} keyword is
2186 @deffn procedure slot-definition-getter slot-def
2187 Extract and return the slot getter option from @var{slot-def}. This is
2188 the value of the @code{#:getter} keyword (@pxref{Slot Options,,
2189 getter}), or @code{#f} if the @code{#:getter} keyword is absent.
2192 @deffn procedure slot-definition-setter slot-def
2193 Extract and return the slot setter option from @var{slot-def}. This is
2194 the value of the @code{#:setter} keyword (@pxref{Slot Options,,
2195 setter}), or @code{#f} if the @code{#:setter} keyword is absent.
2198 @deffn procedure slot-definition-accessor slot-def
2199 Extract and return the slot accessor option from @var{slot-def}. This
2200 is the value of the @code{#:accessor} keyword (@pxref{Slot Options,,
2201 accessor}), or @code{#f} if the @code{#:accessor} keyword is absent.
2204 @deffn procedure slot-definition-init-value slot-def
2205 Extract and return the slot init-value option from @var{slot-def}. This
2206 is the value of the @code{#:init-value} keyword (@pxref{Slot Options,,
2207 init-value}), or the unbound value if the @code{#:init-value} keyword is
2211 @deffn procedure slot-definition-init-form slot-def
2212 Extract and return the slot init-form option from @var{slot-def}. This
2213 is the value of the @code{#:init-form} keyword (@pxref{Slot Options,,
2214 init-form}), or the unbound value if the @code{#:init-form} keyword is
2218 @deffn procedure slot-definition-init-thunk slot-def
2219 Extract and return the slot init-thunk option from @var{slot-def}. This
2220 is the value of the @code{#:init-thunk} keyword (@pxref{Slot Options,,
2221 init-thunk}), or @code{#f} if the @code{#:init-thunk} keyword is absent.
2224 @deffn procedure slot-definition-init-keyword slot-def
2225 Extract and return the slot init-keyword option from @var{slot-def}.
2226 This is the value of the @code{#:init-keyword} keyword (@pxref{Slot
2227 Options,, init-keyword}), or @code{#f} if the @code{#:init-keyword}
2231 @deffn procedure slot-init-function class slot-name
2232 Return the initialization function for the slot named @var{slot-name} in
2233 class @var{class}. @var{slot-name} should be a symbol.
2235 The returned initialization function incorporates the effects of the
2236 standard @code{#:init-thunk}, @code{#:init-form} and @code{#:init-value}
2237 slot options. These initializations can be overridden by the
2238 @code{#:init-keyword} slot option or by a specialized @code{initialize}
2239 method, so, in general, the function returned by
2240 @code{slot-init-function} may be irrelevant. For a fuller discussion,
2241 see @ref{Slot Options,, init-value}.
2245 @subsubsection Instances
2247 @deffn {primitive procedure} class-of value
2248 Return the GOOPS class of any Scheme @var{value}.
2251 @deffn {primitive procedure} instance? object
2252 Return @code{#t} if @var{object} is any GOOPS instance, otherwise
2256 @deffn procedure is-a? object class
2257 Return @code{#t} if @var{object} is an instance of @var{class} or one of
2261 Implementation notes: @code{is-a?} uses @code{class-of} and
2262 @code{class-precedence-list} to obtain the class precedence list for
2265 @node Generic Functions
2266 @subsubsection Generic Functions
2268 @deffn {primitive procedure} generic-function-name gf
2269 Return the name of generic function @var{gf}.
2272 @deffn {primitive procedure} generic-function-methods gf
2273 Return a list of the methods of generic function @var{gf}.
2274 This is the value of the @var{gf} metaobject's @code{methods} slot.
2277 @node Generic Function Methods
2278 @subsubsection Generic Function Methods
2280 @deffn {primitive procedure} method-generic-function method
2281 Return the generic function that @var{method} belongs to.
2282 This is the value of the @var{method} metaobject's
2283 @code{generic-function} slot.
2286 @deffn {primitive procedure} method-specializers method
2287 Return a list of @var{method}'s formal parameter specializers .
2288 This is the value of the @var{method} metaobject's
2289 @code{specializers} slot.
2292 @deffn {primitive procedure} method-procedure method
2293 Return the procedure that implements @var{method}.
2294 This is the value of the @var{method} metaobject's
2295 @code{procedure} slot.
2298 @deffn generic method-source
2299 @deffnx method method-source (m <method>)
2300 Return an expression that prints to show the definition of method
2304 (define-generic cube)
2306 (define-method (cube (n <number>))
2309 (map method-source (generic-function-methods cube))
2311 ((method ((n <number>)) (* n n n)))
2315 @node Miscellaneous Functions
2316 @subsection Miscellaneous Functions
2319 * Administrative Functions::
2320 * GOOPS Error Handling::
2321 * Object Comparisons::
2323 * Write and Display::
2326 @node Administrative Functions
2327 @subsubsection Administration Functions
2329 This section describes administrative, non-technical GOOPS functions.
2331 @deffn primitive goops-version
2332 Return the current GOOPS version as a string, for example ``0.2''.
2335 @node GOOPS Error Handling
2336 @subsubsection Error Handling
2338 The procedure @code{goops-error} is called to raise an appropriate error
2339 by the default methods of the following generic functions:
2343 @code{slot-missing} (@pxref{Handling Slot Access Errors,, slot-missing})
2346 @code{slot-unbound} (@pxref{Handling Slot Access Errors,, slot-unbound})
2349 @code{no-method} (@pxref{Handling Invocation Errors,, no-method})
2352 @code{no-applicable-method} (@pxref{Handling Invocation Errors,,
2353 no-applicable-method})
2356 @code{no-next-method} (@pxref{Handling Invocation Errors,,
2360 If you customize these functions for particular classes or metaclasses,
2361 you may still want to use @code{goops-error} to signal any error
2362 conditions that you detect.
2364 @deffn procedure goops-error format-string . args
2365 Raise an error with key @code{goops-error} and error message constructed
2366 from @var{format-string} and @var{args}. Error message formatting is
2367 as done by @code{scm-error}.
2370 @node Object Comparisons
2371 @subsubsection Object Comparisons
2374 @deffnx method eqv? ((x <top>) (y <top>))
2375 @deffnx generic equal?
2376 @deffnx method equal? ((x <top>) (y <top>))
2378 @deffnx method = ((x <number>) (y <number>))
2379 Generic functions and default (unspecialized) methods for comparing two
2382 The default method for @code{eqv?} returns @code{#t} for all values
2383 that are equal in the sense defined by R5RS and the Guile reference
2384 manual, otherwise @code{#f}. The default method for @code{equal?}
2385 returns @code{#t} or @code{#f} in the sense defined by R5RS and the
2386 Guile reference manual. If no such comparison is defined,
2387 @code{equal?} returns the result of a call to @code{eqv?}. The
2388 default method for = returns @code{#t} if @var{x} and @var{y} are
2389 numerically equal, otherwise @code{#f}.
2391 Application class authors may wish to define specialized methods for
2392 @code{eqv?}, @code{equal?} and @code{=} that compare instances of the
2393 same class for equality in whatever sense is useful to the
2394 application. Such methods will only be called if the arguments have
2395 the same class and the result of the comparison isn't defined by R5RS
2396 and the Guile reference manual.
2399 @node Cloning Objects
2400 @subsubsection Cloning Objects
2402 @deffn generic shallow-clone
2403 @deffnx method shallow-clone (self <object>)
2404 Return a ``shallow'' clone of @var{self}. The default method makes a
2405 shallow clone by allocating a new instance and copying slot values from
2406 self to the new instance. Each slot value is copied either as an
2407 immediate value or by reference.
2410 @deffn generic deep-clone
2411 @deffnx method deep-clone (self <object>)
2412 Return a ``deep'' clone of @var{self}. The default method makes a deep
2413 clone by allocating a new instance and copying or cloning slot values
2414 from self to the new instance. If a slot value is an instance
2415 (satisfies @code{instance?}), it is cloned by calling @code{deep-clone}
2416 on that value. Other slot values are copied either as immediate values
2420 @node Write and Display
2421 @subsubsection Write and Display
2423 @deffn {primitive generic} write object port
2424 @deffnx {primitive generic} display object port
2425 When GOOPS is loaded, @code{write} and @code{display} become generic
2426 functions with special methods for printing
2430 objects - instances of the class @code{<object>}
2433 foreign objects - instances of the class @code{<foreign-object>}
2436 classes - instances of the class @code{<class>}
2439 generic functions - instances of the class @code{<generic>}
2442 methods - instances of the class @code{<method>}.
2445 @code{write} and @code{display} print non-GOOPS values in the same way
2446 as the Guile primitive @code{write} and @code{display} functions.
2449 @node MOP Specification
2450 @section MOP Specification
2452 For an introduction to metaobjects and the metaobject protocol,
2453 see @ref{Metaobjects and the Metaobject Protocol}.
2455 The aim of the MOP specification in this chapter is to specify all the
2456 customizable generic function invocations that can be made by the standard
2457 GOOPS syntax, procedures and methods, and to explain the protocol for
2458 customizing such invocations.
2460 A generic function invocation is customizable if the types of the arguments
2461 to which it is applied are not all determined by the lexical context in
2462 which the invocation appears. For example,
2466 the @code{(initialize @var{instance} @var{initargs})} invocation in the
2467 default @code{make-instance} method is customizable, because the type of the
2468 @code{@var{instance}} argument is determined by the class that was passed to
2469 @code{make-instance}.
2472 the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
2473 is not customizable, because all of its arguments have lexically determined
2477 When using this rule to decide whether a given generic function invocation
2478 is customizable, we ignore arguments that are expected to be handled in
2479 method definitions as a single ``rest'' list argument.
2481 For each customizable generic function invocation, the @dfn{invocation
2482 protocol} is explained by specifying
2486 what, conceptually, the applied method is intended to do
2489 what assumptions, if any, the caller makes about the applied method's side
2493 what the caller expects to get as the applied method's return value.
2497 * Class Definition::
2498 * Instance Creation::
2499 * Class Redefinition::
2500 * Method Definition::
2501 * Generic Function Invocation::
2504 @node Class Definition
2505 @subsection Class Definition
2507 @code{define-class} (syntax)
2511 @code{class} (syntax)
2515 @code{make-class} (procedure)
2519 @code{make @var{metaclass} @dots{}} (generic)
2521 @var{metaclass} is the metaclass of the class being defined, either
2522 taken from the @code{#:metaclass} class option or computed by
2523 @code{ensure-metaclass}. The applied method must create and return the
2524 fully initialized class metaobject for the new class definition.
2530 @code{class-redefinition @var{old-class} @var{new-class}} (generic)
2532 @code{define-class} calls @code{class-redefinition} if the variable
2533 specified by its first argument already held a GOOPS class definition.
2534 @var{old-class} and @var{new-class} are the old and new class metaobjects.
2535 The applied method should perform whatever is necessary to handle the
2536 redefinition, and should return the class metaobject that is to be bound
2537 to @code{define-class}'s variable. The default class redefinition
2538 protocol is described in @ref{Class Redefinition}.
2541 The @code{(make @var{metaclass} @dots{})} invocation above will create
2542 an class metaobject with metaclass @var{metaclass}. By default, this
2543 metaobject will be initialized by the @code{initialize} method that is
2544 specialized for instances of type @code{<class>}.
2546 @code{initialize <class> @var{initargs}} (method)
2550 @code{compute-cpl @var{class}} (generic)
2552 The applied method should compute and return the class precedence list
2553 for @var{class} as a list of class metaobjects. When @code{compute-cpl}
2554 is called, the following @var{class} metaobject slots have all been
2555 initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
2556 @code{direct-subclasses} (empty), @code{direct-methods}. The value
2557 returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
2560 @code{compute-slots @var{class}} (generic)
2562 The applied method should compute and return the slots (union of direct
2563 and inherited) for @var{class} as a list of slot definitions. When
2564 @code{compute-slots} is called, all the @var{class} metaobject slots
2565 mentioned for @code{compute-cpl} have been initialized, plus the
2566 following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
2567 The value returned by @code{compute-slots} will be stored in the
2571 @code{compute-get-n-set @var{class} @var{slot-def}} (generic)
2573 @code{initialize} calls @code{compute-get-n-set} for each slot computed
2574 by @code{compute-slots}. The applied method should compute and return a
2575 pair of closures that, respectively, get and set the value of the specified
2576 slot. The get closure should have arity 1 and expect a single argument
2577 that is the instance whose slot value is to be retrieved. The set closure
2578 should have arity 2 and expect two arguments, where the first argument is
2579 the instance whose slot value is to be set and the second argument is the
2580 new value for that slot. The closures should be returned in a two element
2581 list: @code{(list @var{get} @var{set})}.
2583 The closures returned by @code{compute-get-n-set} are stored as part of
2584 the value of the @var{class} metaobject's @code{getters-n-setters} slot.
2585 Specifically, the value of this slot is a list with the same number of
2586 elements as there are slots in the class, and each element looks either like
2589 @code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
2595 @code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
2598 Where the get and set closures are replaced by @var{index}, the slot is
2599 an instance slot and @var{index} is the slot's index in the underlying
2600 structure: GOOPS knows how to get and set the value of such slots and so
2601 does not need specially constructed get and set closures. Otherwise,
2602 @var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
2604 The structure of the @code{getters-n-setters} slot value is important when
2605 understanding the next customizable generic functions that @code{initialize}
2609 @code{compute-getter-method @var{class} @var{gns}} (generic)
2611 @code{initialize} calls @code{compute-getter-method} for each of the class's
2612 slots (as determined by @code{compute-slots}) that includes a
2613 @code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
2614 element of the @var{class} metaobject's @code{getters-n-setters} slot that
2615 specifies how the slot in question is referenced and set, as described
2616 above under @code{compute-get-n-set}. The applied method should create
2617 and return a method that is specialized for instances of type @var{class}
2618 and uses the get closure to retrieve the slot's value. [ *fixme Need
2619 to insert something here about checking that the value is not unbound. ]
2620 @code{initialize} uses @code{add-method!} to add the returned method to
2621 the generic function named by the slot definition's @code{#:getter} or
2622 @code{#:accessor} option.
2625 @code{compute-setter-method @var{class} @var{gns}} (generic)
2627 @code{compute-setter-method} is invoked with the same arguments as
2628 @code{compute-getter-method}, for each of the class's slots that includes
2629 a @code{#:setter} or @code{#:accessor} slot option. The applied method
2630 should create and return a method that is specialized for instances of
2631 type @var{class} and uses the set closure to set the slot's value.
2632 @code{initialize} then uses @code{add-method!} to add the returned method
2633 to the generic function named by the slot definition's @code{#:setter}
2634 or @code{#:accessor} option.
2637 @node Instance Creation
2638 @subsection Instance Creation
2640 @code{make <class> . @var{initargs}} (method)
2644 @code{allocate-instance @var{class} @var{initargs}} (generic)
2646 The applied @code{allocate-instance} method should allocate storage for
2647 a new instance of class @var{class} and return the uninitialized instance.
2650 @code{initialize @var{instance} @var{initargs}} (generic)
2652 @var{instance} is the uninitialized instance returned by
2653 @code{allocate-instance}. The applied method should initialize the new
2654 instance in whatever sense is appropriate for its class. The method's
2655 return value is ignored.
2658 @node Class Redefinition
2659 @subsection Class Redefinition
2661 The default @code{class-redefinition} method, specialized for classes
2662 with the default metaclass @code{<class>}, has the following internal
2665 @code{class-redefinition (@var{old <class>}) (@var{new <class>})}
2670 @code{remove-class-accessors! @var{old}} (generic)
2673 @code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
2676 @code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
2679 This protocol cleans up things that the definition of the old class
2680 once changed and modifies things to work with the new class.
2682 The default @code{remove-class-accessors!} method removes the
2683 accessor methods of the old class from all classes which they
2686 The default @code{update-direct-method!} method substitutes the new
2687 class for the old in all methods specialized to the old class.
2689 The default @code{update-direct-subclass!} method invokes
2690 @code{class-redefinition} recursively to handle the redefinition of
2693 When a class is redefined, any existing instance of the redefined class
2694 will be modified for the new class definition before the next time that
2695 any of the instance's slot is referenced or set. GOOPS modifies each
2696 instance by calling the generic function @code{change-class}.
2698 The default @code{change-class} method copies slot values from the old
2699 to the modified instance, and initializes new slots, as described in
2700 @ref{Changing the Class of an Instance}. After doing so, it makes a
2701 generic function invocation that can be used to customize the instance
2704 @code{change-class (@var{old-instance <object>}) (@var{new <class>})} (method)
2708 @code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
2710 @code{change-class} invokes @code{update-instance-for-different-class}
2711 as the last thing that it does before returning. The applied method can
2712 make any further adjustments to @var{new-instance} that are required to
2713 complete or modify the change of class. The return value from the
2714 applied method is ignored.
2716 The default @code{update-instance-for-different-class} method does
2720 @node Method Definition
2721 @subsection Method Definition
2723 @code{define-method} (syntax)
2727 @code{add-method! @var{target} @var{method}} (generic)
2729 @code{define-method} invokes the @code{add-method!} generic function to
2730 handle adding the new method to a variety of possible targets. GOOPS
2731 includes methods to handle @var{target} as
2735 a generic function (the most common case)
2741 a primitive generic (@pxref{Extending Guiles Primitives})
2744 By defining further methods for @code{add-method!}, you can
2745 theoretically handle adding methods to further types of target.
2748 @node Generic Function Invocation
2749 @subsection Generic Function Invocation
2751 [ *fixme* Description required here. ]
2753 @code{apply-generic}
2760 @code{compute-applicable-methods}
2763 @code{sort-applicable-methods}
2766 @code{apply-methods}
2769 @code{no-applicable-method}
2772 @code{sort-applicable-methods}
2776 @code{method-more-specific?}
2779 @code{apply-methods}
2790 @code{no-next-method}