4 @setfilename goops.info
13 @dircategory The Algorithmic Language Scheme
15 * GOOPS: (goops). The GOOPS reference manual.
27 This file documents GOOPS, an object oriented extension for Guile.
29 Copyright (C) 1999, 2000, 2001, 2003, 2006 Free Software Foundation
31 Permission is granted to make and distribute verbatim copies of
32 this manual provided the copyright notice and this permission notice
33 are preserved on all copies.
37 @c This title page illustrates only one of the
38 @c two methods of forming a title page.
42 @subtitle For use with GOOPS @value{VERSION}
46 @c The GOOPS tutorial was written by Christian Lynbech and Mikael
47 @c Djurfeldt, who also wrote GOOPS itself. The GOOPS reference manual
48 @c and MOP documentation were written by Neil Jerram and reviewed by
51 @author Christian Lynbech
52 @author @email{chl@@tbit.dk}
54 @author Mikael Djurfeldt
55 @author @email{djurfeldt@@nada.kth.se}
58 @author @email{neil@@ossau.uklinux.net}
60 @c The following two commands
61 @c start the copyright page.
63 @vskip 0pt plus 1filll
64 Copyright @copyright{} 1999, 2006 Free Software Foundation
66 Permission is granted to make and distribute verbatim copies of
67 this manual provided the copyright notice and this permission notice
68 are preserved on all copies.
72 @node Top, Introduction, (dir), (dir)
83 * Function and Variable Index::
87 @chapter Preliminaries
90 @node Introduction, Getting Started, Top, Top
98 @goops{} is the object oriented extension to @guile{}. Its
99 implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
100 version 1.3 of Gregor Kiczales @cite{Tiny-Clos}. It is very close in
101 spirit to CLOS, the Common Lisp Object System (@cite{CLtL2}) but is
102 adapted for the Scheme language. While GOOPS is not compatible with any
103 of these systems, GOOPS contains a compatibility module which allows for
104 execution of STKlos programs.
106 Briefly stated, the @goops{} extension gives the user a full object
107 oriented system with multiple inheritance and generic functions with
108 multi-method dispatch. Furthermore, the implementation relies on a true
109 meta object protocol, in the spirit of the one defined for CLOS
110 (@cite{Gregor Kiczales: A Metaobject Protocol}).
112 @node Getting Started, Reference Manual, Introduction, Top
114 @section Getting Started
117 @chapter Getting Started
123 Examples of some basic GOOPS functionality.
126 * User-defined types::
127 * Asking for the type of an object::
129 See further in the GOOPS tutorial available in this distribution in
130 info (goops.info) and texinfo format.
133 @node Running GOOPS, Methods, Getting Started, Getting Started
134 @subsection Running GOOPS
144 You should now be at the Guile prompt ("guile> ").
150 (use-modules (oop goops))
153 to load GOOPS. (If your system supports dynamic loading, you
154 should be able to do this not only from `guile-oops' but from an
155 arbitrary Guile interpreter.)
158 We're now ready to try some basic GOOPS functionality.
160 @node Methods, User-defined types, Running GOOPS, Getting Started
165 (define-method (+ (x <string>) (y <string>))
169 (+ "abc" "de") --> "abcde"
173 @node User-defined types, Asking for the type of an object, Methods, Getting Started
174 @subsection User-defined types
177 (define-class <2D-vector> ()
178 (x #:init-value 0 #:accessor x-component #:init-keyword #:x)
179 (y #:init-value 0 #:accessor y-component #:init-keyword #:y))
182 (use-modules (ice-9 format))
184 (define-method (write (obj <2D-vector>) port)
185 (display (format #f "<~S, ~S>" (x-component obj) (y-component obj))
188 (define v (make <2D-vector> #:x 3 #:y 4))
194 (define-method (+ (x <2D-vector>) (y <2D-vector>))
196 #:x (+ (x-component x) (x-component y))
197 #:y (+ (y-component x) (y-component y))))
203 @node Asking for the type of an object, , User-defined types, Getting Started
207 (class-of v) --> #<<class> <2D-vector> 40241ac0>
208 <2D-vector> --> #<<class> <2D-vector> 40241ac0>
209 (class-of 1) --> #<<class> <integer> 401b2a98>
210 <integer> --> #<<class> <integer> 401b2a98>
212 (is-a? v <2D-vector>) --> #t
215 @node Reference Manual, MOP Specification, Getting Started, Top
216 @chapter Reference Manual
218 This chapter is the GOOPS reference manual. It aims to describe all the
219 syntax, procedures, options and associated concepts that a typical
220 application author would need to understand in order to use GOOPS
221 effectively in their application. It also describes what is meant by
222 the GOOPS ``metaobject protocol'' (aka ``MOP''), and indicates how
223 authors can use the metaobject protocol to customize the behaviour of
226 For a detailed specification of the GOOPS metaobject protocol, see
227 @ref{MOP Specification}.
230 * Introductory Remarks::
231 * Defining New Classes::
232 * Creating Instances::
234 * Creating Generic Functions::
235 * Adding Methods to Generic Functions::
236 * Invoking Generic Functions::
237 * Redefining a Class::
238 * Changing the Class of an Instance::
240 * Miscellaneous Functions::
243 @node Introductory Remarks
244 @section Introductory Remarks
246 GOOPS is an object-oriented programming system based on a ``metaobject
247 protocol'' derived from the ones used in CLOS (the Common Lisp Object
248 System), tiny-clos (a small Scheme implementation of a subset of CLOS
249 functionality) and STKlos.
251 GOOPS can be used by application authors at a basic level without any
252 need to understand what the metaobject protocol (aka ``MOP'') is and how
253 it works. On the other hand, the MOP underlies even the customizations
254 that application authors are likely to make use of very quickly --- such
255 as defining an @code{initialize} method to customize the initialization
256 of instances of an application-defined class --- and an understanding of
257 the MOP makes it much easier to explain such customizations in a precise
258 way. And in the long run, understanding the MOP is the key both to
259 understanding GOOPS at a deeper level and to taking full advantage of
260 GOOPS' power, by customizing the behaviour of GOOPS itself.
262 Each of the following sections of the reference manual is arranged
263 such that the most basic usage is introduced first, and then subsequent
264 subsections discuss the related internal functions and metaobject
265 protocols, finishing with a description of how to customize that area of
268 These introductory remarks continue with a few words about metaobjects
269 and the MOP. Readers who do not want to be bothered yet with the MOP
270 and customization could safely skip this subsection on a first reading,
271 and should correspondingly skip subsequent subsections that are
272 concerned with internals and customization.
274 In general, this reference manual assumes familiarity with standard
275 object oriented concepts and terminology. However, some of the terms
276 used in GOOPS are less well known, so the Terminology subsection
277 provides definitions for these terms.
280 * Metaobjects and the Metaobject Protocol::
284 @node Metaobjects and the Metaobject Protocol
285 @subsection Metaobjects and the Metaobject Protocol
287 The conceptual building blocks of GOOPS are classes, slot definitions,
288 instances, generic functions and methods. A class is a grouping of
289 inheritance relations and slot definitions. An instance is an object
290 with slots that are allocated following the rules implied by its class's
291 superclasses and slot definitions. A generic function is a collection
292 of methods and rules for determining which of those methods to apply
293 when the generic function is invoked. A method is a procedure and a set
294 of specializers that specify the type of arguments to which the
295 procedure is applicable.
297 Of these entities, GOOPS represents classes, generic functions and
298 methods as ``metaobjects''. In other words, the values in a GOOPS
299 program that describe classes, generic functions and methods, are
300 themselves instances (or ``objects'') of special GOOPS classes that
301 encapsulate the behaviour, respectively, of classes, generic functions,
304 (The other two entities are slot definitions and instances. Slot
305 definitions are not strictly instances, but every slot definition is
306 associated with a GOOPS class that specifies the behaviour of the slot
307 as regards accessibility and protection from garbage collection.
308 Instances are of course objects in the usual sense, and there is no
309 benefit from thinking of them as metaobjects.)
311 The ``metaobject protocol'' (aka ``MOP'') is the specification of the
312 generic functions which determine the behaviour of these metaobjects and
313 the circumstances in which these generic functions are invoked.
315 For a concrete example of what this means, consider how GOOPS calculates
316 the set of slots for a class that is being defined using
317 @code{define-class}. The desired set of slots is the union of the new
318 class's direct slots and the slots of all its superclasses. But
319 @code{define-class} itself does not perform this calculation. Instead,
320 there is a method of the @code{initialize} generic function that is
321 specialized for instances of type @code{<class>}, and it is this method
322 that performs the slot calculation.
324 @code{initialize} is a generic function which GOOPS calls whenever a new
325 instance is created, immediately after allocating memory for a new
326 instance, in order to initialize the new instance's slots. The sequence
327 of steps is as follows.
331 @code{define-class} uses @code{make} to make a new instance of the
332 @code{<class>}, passing as initialization arguments the superclasses,
333 slot definitions and class options that were specified in the
334 @code{define-class} form.
337 @code{make} allocates memory for the new instance, and then invokes the
338 @code{initialize} generic function to initialize the new instance's
342 The @code{initialize} generic function applies the method that is
343 specialized for instances of type @code{<class>}, and this method
344 performs the slot calculation.
347 In other words, rather than being hardcoded in @code{define-class}, the
348 behaviour of class definition is encapsulated by generic function
349 methods that are specialized for the class @code{<class>}.
351 It is possible to create a new class that inherits from @code{<class>},
352 which is called a ``metaclass'', and to write a new @code{initialize}
353 method that is specialized for instances of the new metaclass. Then, if
354 the @code{define-class} form includes a @code{#:metaclass} class option
355 whose value is the new metaclass, the class that is defined by the
356 @code{define-class} form will be an instance of the new metaclass rather
357 than of the default @code{<class>}, and will be defined in accordance
358 with the new @code{initialize} method. Thus the default slot
359 calculation, as well as any other aspect of the new class's relationship
360 with its superclasses, can be modified or overridden.
362 In a similar way, the behaviour of generic functions can be modified or
363 overridden by creating a new class that inherits from the standard
364 generic function class @code{<generic>}, writing appropriate methods
365 that are specialized to the new class, and creating new generic
366 functions that are instances of the new class.
368 The same is true for method metaobjects. And the same basic mechanism
369 allows the application class author to write an @code{initialize} method
370 that is specialized to their application class, to initialize instances
373 Such is the power of the MOP. Note that @code{initialize} is just one
374 of a large number of generic functions that can be customized to modify
375 the behaviour of application objects and classes and of GOOPS itself.
376 Each subsequent section of the reference manual covers a particular area
377 of GOOPS functionality, and describes the generic functions that are
378 relevant for customization of that area.
380 We conclude this subsection by emphasizing a point that may seem
381 obvious, but contrasts with the corresponding situation in some other
382 MOP implementations, such as CLOS. The point is simply that an
383 identifier which represents a GOOPS class or generic function is a
384 variable with a first-class value, the value being an instance of class
385 @code{<class>} or @code{<generic>}. (In CLOS, on the other hand, a
386 class identifier is a symbol that indexes the corresponding class
387 metaobject in a separate namespace for classes.) This is, of course,
388 simply an extension of the tendency in Scheme to avoid the unnecessary
389 use of, on the one hand, syntactic forms that require unevaluated
390 arguments and, on the other, separate identifier namespaces (e.g. for
391 class names), but it is worth noting that GOOPS conforms fully to this
395 @subsection Terminology
397 It is assumed that the reader is already familiar with standard object
398 orientation concepts such as classes, objects/instances,
399 inheritance/subclassing, generic functions and methods, encapsulation
402 This section explains some of the less well known concepts and
403 terminology that GOOPS uses, which are assumed by the following sections
404 of the reference manual.
408 * Class Precedence List::
413 @subsubsection Metaclass
415 A @dfn{metaclass} is the class of an object which represents a GOOPS
416 class. Put more succinctly, a metaclass is a class's class.
418 Most GOOPS classes have the metaclass @code{<class>} and, by default,
419 any new class that is created using @code{define-class} has the
420 metaclass @code{<class>}.
422 But what does this really mean? To find out, let's look in more detail
423 at what happens when a new class is created using @code{define-class}:
426 (define-class <my-class> (<object>) . slots)
429 GOOPS actually expands the @code{define-class} form to something like
433 (define <my-class> (class (<object>) . slots))
440 (make <class> #:supers (list <object>) #:slots slots))
443 In other words, the value of @code{<my-class>} is in fact an instance of
444 the class @code{<class>} with slot values specifying the superclasses
445 and slot definitions for the class @code{<my-class>}. (@code{#:supers}
446 and @code{#:slots} are initialization keywords for the @code{dsupers}
447 and @code{dslots} slots of the @code{<class>} class.)
449 In order to take advantage of the full power of the GOOPS metaobject
450 protocol (@pxref{MOP Specification}), it is sometimes desirable to
451 create a new class with a metaclass other than the default
452 @code{<class>}. This is done by writing:
455 (define-class <my-class2> (<object>)
457 #:metaclass <my-metaclass>)
460 GOOPS expands this to something like:
464 (make <my-metaclass> #:supers (list <object>) #:slots slots))
467 In this case, the value of @code{<my-class2>} is an instance of the more
468 specialized class @code{<my-metaclass>}. Note that
469 @code{<my-metaclass>} itself must previously have been defined as a
470 subclass of @code{<class>}. For a full discussion of when and how it is
471 useful to define new metaclasses, see @ref{MOP Specification}.
473 Now let's make an instance of @code{<my-class2>}:
476 (define my-object (make <my-class2> ...))
479 All of the following statements are correct expressions of the
480 relationships between @code{my-object}, @code{<my-class2>},
481 @code{<my-metaclass>} and @code{<class>}.
485 @code{my-object} is an instance of the class @code{<my-class2>}.
488 @code{<my-class2>} is an instance of the class @code{<my-metaclass>}.
491 @code{<my-metaclass>} is an instance of the class @code{<class>}.
494 The class of @code{my-object} is @code{<my-class2>}.
497 The metaclass of @code{my-object} is @code{<my-metaclass>}.
500 The class of @code{<my-class2>} is @code{<my-metaclass>}.
503 The metaclass of @code{<my-class2>} is @code{<class>}.
506 The class of @code{<my-metaclass>} is @code{<class>}.
509 The metaclass of @code{<my-metaclass>} is @code{<class>}.
512 @code{<my-class2>} is not a metaclass, since it is does not inherit from
516 @code{<my-metaclass>} is a metaclass, since it inherits from
520 @node Class Precedence List
521 @subsubsection Class Precedence List
523 The @dfn{class precedence list} of a class is the list of all direct and
524 indirect superclasses of that class, including the class itself.
526 In the absence of multiple inheritance, the class precedence list is
527 ordered straightforwardly, beginning with the class itself and ending
530 For example, given this inheritance hierarchy:
533 (define-class <invertebrate> (<object>) @dots{})
534 (define-class <echinoderm> (<invertebrate>) @dots{})
535 (define-class <starfish> (<echinoderm>) @dots{})
538 the class precedence list of <starfish> would be
541 (<starfish> <echinoderm> <invertebrate> <object> <top>)
544 With multiple inheritance, the algorithm is a little more complicated.
545 A full description is provided by the GOOPS Tutorial: see @ref{Class
548 ``Class precedence list'' is often abbreviated, in documentation and
549 Scheme variable names, to @dfn{cpl}.
552 @subsubsection Accessor
554 An @dfn{accessor} is a generic function with both reference and setter
558 (define-accessor perimeter)
561 Reference methods for an accessor are defined in the same way as generic
565 (define-method (perimeter (s <square>))
566 (* 4 (side-length s)))
569 Setter methods for an accessor are defined by specifying ``(setter
570 <accessor-name>)'' as the first parameter of the @code{define-method}
574 (define-method ((setter perimeter) (s <square>) (n <number>))
575 (set! (side-length s) (/ n 4)))
578 Once an appropriate setter method has been defined in this way, it can
579 be invoked using the generalized @code{set!} syntax, as in:
582 (set! (perimeter s1) 18.3)
585 @node Defining New Classes
586 @section Defining New Classes
588 [ *fixme* Somewhere in this manual there needs to be an introductory
589 discussion about GOOPS classes, generic functions and methods, covering
593 how classes encapsulate related items of data in @dfn{slots}
596 why it is that, unlike in C++ and Java, a class does not encapsulate the
597 methods that act upon the class (at least not in the C++/Java sense)
600 how generic functions provide a more general solution that provides for
601 dispatch on all argument types, and avoids idiosyncracies like C++'s
605 how encapsulation in the sense of data- and code-hiding, or of
606 distinguishing interface from implementation, is treated in Guile as an
607 orthogonal concept to object orientation, and is the responsibility of
611 Some of this is covered in the Tutorial chapter, in @ref{Generic
612 functions and methods} - perhaps the best solution would be to expand
613 the discussion there. ]
616 * Basic Class Definition::
619 * Class Definition Internals::
620 * Customizing Class Definition::
621 * STKlos Compatibility::
624 @node Basic Class Definition
625 @subsection Basic Class Definition
627 New classes are defined using the @code{define-class} syntax, with
628 arguments that specify the classes that the new class should inherit
629 from, the direct slots of the new class, and any required class options.
631 @deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
632 Define a class called @var{name} that inherits from @var{super}s, with
633 direct slots defined by @var{slot-definition}s and class options
634 @var{options}. The newly created class is bound to the variable name
635 @var{name} in the current environment.
637 Each @var{slot-definition} is either a symbol that names the slot or a
641 (@var{slot-name-symbol} . @var{slot-options})
644 where @var{slot-name-symbol} is a symbol and @var{slot-options} is a
645 list with an even number of elements. The even-numbered elements of
646 @var{slot-options} (counting from zero) are slot option keywords; the
647 odd-numbered elements are the corresponding values for those keywords.
649 @var{options} is a similarly structured list containing class option
650 keywords and corresponding values.
653 The standard GOOPS class and slot options are described in the following
654 subsections: see @ref{Class Options} and @ref{Slot Options}.
656 Example 1. Define a class that combines two pre-existing classes by
657 inheritance but adds no new slots.
660 (define-class <combined> (<tree> <bicycle>))
663 Example 2. Define a @code{regular-polygon} class with slots for side
664 length and number of sides that have default values and can be accessed
665 via the generic functions @code{side-length} and @code{num-sides}.
668 (define-class <regular-polygon> ()
669 (sl #:init-value 1 #:accessor side-length)
670 (ns #:init-value 5 #:accessor num-sides))
673 Example 3. Define a class whose behavior (and that of its instances) is
674 customized via an application-defined metaclass.
677 (define-class <tcpip-fsm> ()
678 (s #:init-value #f #:accessor state)
680 #:metaclass <finite-state-class>)
684 @subsection Class Options
686 @deffn {class option} #:metaclass metaclass
687 The @code{#:metaclass} class option specifies the metaclass of the class
688 being defined. @var{metaclass} must be a class that inherits from
689 @code{<class>}. For an introduction to the use of metaclasses, see
690 @ref{Metaobjects and the Metaobject Protocol} and @ref{Metaclass}.
692 If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
693 metaclass for the new class by calling @code{ensure-metaclass}
694 (@pxref{Class Definition Internals,, ensure-metaclass}).
697 @deffn {class option} #:name name
698 The @code{#:name} class option specifies the new class's name. This
699 name is used to identify the class whenever related objects - the class
700 itself, its instances and its subclasses - are printed.
702 If the @code{#:name} option is absent, GOOPS uses the first argument to
703 @code{define-class} as the class name.
706 @deffn {class option} #:environment environment
707 *fixme* Not sure about this one, but I think that the
708 @code{#:environment} option specifies the environment in which the
709 class's getters and setters are computed and evaluated.
711 If the @code{#:environment} option is not specified, the class's
712 environment defaults to the top-level environment in which the
713 @code{define-class} form appears.
717 @subsection Slot Options
719 @deffn {slot option} #:allocation allocation
720 The @code{#:allocation} option tells GOOPS how to allocate storage for
721 the slot. Possible values for @var{allocation} are
724 @item @code{#:instance}
726 Indicates that GOOPS should create separate storage for this slot in
727 each new instance of the containing class (and its subclasses).
731 Indicates that GOOPS should create storage for this slot that is shared
732 by all instances of the containing class (and its subclasses). In other
733 words, a slot in class @var{C} with allocation @code{#:class} is shared
734 by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
736 @item @code{#:each-subclass}
738 Indicates that GOOPS should create storage for this slot that is shared
739 by all @emph{direct} instances of the containing class, and that
740 whenever a subclass of the containing class is defined, GOOPS should
741 create a new storage for the slot that is shared by all @emph{direct}
742 instances of the subclass. In other words, a slot with allocation
743 @code{#:each-subclass} is shared by all instances with the same
746 @item @code{#:virtual}
748 Indicates that GOOPS should not allocate storage for this slot. The
749 slot definition must also include the @code{#:slot-ref} and
750 @code{#:slot-set!} options to specify how to reference and set the value
754 The default value is @code{#:instance}.
756 Slot allocation options are processed when defining a new class by the
757 generic function @code{compute-get-n-set}, which is specialized by the
758 class's metaclass. Hence new types of slot allocation can be
759 implemented by defining a new metaclass and a method for
760 @code{compute-get-n-set} that is specialized for the new metaclass. For
761 an example of how to do this, see @ref{Customizing Class Definition}.
764 @deffn {slot option} #:slot-ref getter
765 @deffnx {slot option} #:slot-set! setter
766 The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
767 if the slot allocation is @code{#:virtual}, and are ignored otherwise.
769 @var{getter} should be a closure taking a single @var{instance} parameter
770 that returns the current slot value. @var{setter} should be a closure
771 taking two parameters - @var{instance} and @var{new-val} - that sets the
772 slot value to @var{new-val}.
775 @deffn {slot option} #:getter getter
776 @deffnx {slot option} #:setter setter
777 @deffnx {slot option} #:accessor accessor
778 These options, if present, tell GOOPS to create generic function and
779 method definitions that can be used to get and set the slot value more
780 conveniently than by using @code{slot-ref} and @code{slot-set!}.
782 @var{getter} specifies a generic function to which GOOPS will add a
783 method for getting the slot value. @var{setter} specifies a generic
784 function to which GOOPS will add a method for setting the slot value.
785 @var{accessor} specifies an accessor to which GOOPS will add methods for
786 both getting and setting the slot value.
788 So if a class includes a slot definition like this:
791 (c #:getter get-count #:setter set-count #:accessor count)
794 GOOPS defines generic function methods such that the slot value can be
795 referenced using either the getter or the accessor -
798 (let ((current-count (get-count obj))) @dots{})
799 (let ((current-count (count obj))) @dots{})
802 - and set using either the setter or the accessor -
805 (set-count obj (+ 1 current-count))
806 (set! (count obj) (+ 1 current-count))
813 with an accessor, the slot value is set using the generalized
817 in practice, it is unusual for a slot to use all three of these options:
818 read-only, write-only and read-write slots would typically use only
819 @code{#:getter}, @code{#:setter} and @code{#:accessor} options
823 If the specified names are already bound in the top-level environment to
824 values that cannot be upgraded to generic functions, those values are
825 overwritten during evaluation of the @code{define-class} that contains
826 the slot definition. For details, see @ref{Generic Function Internals,,
830 @deffn {slot option} #:init-value init-value
831 @deffnx {slot option} #:init-form init-form
832 @deffnx {slot option} #:init-thunk init-thunk
833 @deffnx {slot option} #:init-keyword init-keyword
834 These options provide various ways to specify how to initialize the
835 slot's value at instance creation time. @var{init-value} is a fixed
836 value (shared across all new instances of the class).
837 @var{init-thunk} is a procedure of no arguments that is called
838 when a new instance is created and should return the desired initial
839 slot value. @var{init-form} is an unevaluated expression that gets
840 evaluated when a new instance is created and should return the desired
841 initial slot value. @var{init-keyword} is a keyword that can be used
842 to pass an initial slot value to @code{make} when creating a new
845 Note that, since an @code{init-value} value is shared across all
846 instances of a class, you should only use it when the initial value is
847 an immutable value, like a constant. If you want to initialize a slot
848 with a fresh, independently mutable value, you should use
849 @code{init-thunk} or @code{init-form} instead. Consider the following
853 (define-class <chbouib> ()
854 (hashtab #:init-value (make-hash-table)))
858 Here only one hash table is created and all instances of
859 @code{<chbouib>} have their @code{hashtab} slot refer to it. In order
860 to have each instance of @code{<chbouib>} refer to a new hash table, you
861 should instead write:
864 (define-class <chbouib> ()
865 (hashtab #:init-thunk make-hash-table))
872 (define-class <chbouib> ()
873 (hashtab #:init-form (make-hash-table)))
876 If more than one of these options is specified for the same slot, the
877 order of precedence, highest first is
881 @code{#:init-keyword}, if @var{init-keyword} is present in the options
882 passed to @code{make}
885 @code{#:init-thunk}, @code{#:init-form} or @code{#:init-value}.
888 If the slot definition contains more than one initialization option of
889 the same precedence, the later ones are ignored. If a slot is not
890 initialized at all, its value is unbound.
892 In general, slots that are shared between more than one instance are
893 only initialized at new instance creation time if the slot value is
894 unbound at that time. However, if the new instance creation specifies
895 a valid init keyword and value for a shared slot, the slot is
896 re-initialized regardless of its previous value.
898 Note, however, that the power of GOOPS' metaobject protocol means that
899 everything written here may be customized or overridden for particular
900 classes! The slot initializations described here are performed by the least
901 specialized method of the generic function @code{initialize}, whose
905 (define-method (initialize (object <object>) initargs) ...)
908 The initialization of instances of any given class can be customized by
909 defining a @code{initialize} method that is specialized for that class,
910 and the author of the specialized method may decide to call
911 @code{next-method} - which will result in a call to the next less
912 specialized @code{initialize} method - at any point within the
913 specialized code, or maybe not at all. In general, therefore, the
914 initialization mechanisms described here may be modified or overridden by
915 more specialized code, or may not be supported at all for particular
919 @node Class Definition Internals
920 @subsection Class Definition Internals
922 Implementation notes: @code{define-class} expands to an expression which
926 checks that it is being evaluated only at top level
929 defines any accessors that are implied by the @var{slot-definition}s
932 uses @code{class} to create the new class (@pxref{Class Definition
936 checks for a previous class definition for @var{name} and, if found,
937 handles the redefinition by invoking @code{class-redefinition}
938 (@pxref{Redefining a Class}).
941 @deffn syntax class name (super @dots{}) slot-definition @dots{} . options
942 Return a newly created class that inherits from @var{super}s, with
943 direct slots defined by @var{slot-definition}s and class options
944 @var{options}. For the format of @var{slot-definition}s and
945 @var{options}, see @ref{Basic Class Definition,, define-class}.
948 Implementation notes: @code{class} expands to an expression which
952 processes the class and slot definition options to check that they are
953 well-formed, to convert the @code{#:init-form} option to an
954 @code{#:init-thunk} option, to supply a default environment parameter
955 (the current top-level environment) and to evaluate all the bits that
959 calls @code{make-class} to create the class with the processed and
960 evaluated parameters.
963 @deffn procedure make-class supers slots . options
964 Return a newly created class that inherits from @var{supers}, with
965 direct slots defined by @var{slots} and class options @var{options}.
966 For the format of @var{slots} and @var{options}, see @ref{Basic Class
967 Definition,, define-class}, except note that for @code{make-class},
968 @var{slots} and @var{options} are separate list parameters: @var{slots}
969 here is a list of slot definitions.
972 Implementation notes: @code{make-class}
976 adds @code{<object>} to the @var{supers} list if @var{supers} is empty
977 or if none of the classes in @var{supers} have @code{<object>} in their
978 class precedence list
981 defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
982 options, if they are not specified by @var{options}, to the current
983 top-level environment, the unbound value, and @code{(ensure-metaclass
984 @var{supers})} respectively (@pxref{Class Definition Internals,,
988 checks for duplicate classes in @var{supers} and duplicate slot names in
989 @var{slots}, and signals an error if there are any duplicates
992 calls @code{make}, passing the metaclass as the first parameter and all
993 other parameters as option keywords with values.
996 @deffn procedure ensure-metaclass supers env
997 Return a metaclass suitable for a class that inherits from the list of
998 classes in @var{supers}. The returned metaclass is the union by
999 inheritance of the metaclasses of the classes in @var{supers}.
1001 In the simplest case, where all the @var{supers} are straightforward
1002 classes with metaclass @code{<class>}, the returned metaclass is just
1005 For a more complex example, suppose that @var{supers} contained one
1006 class with metaclass @code{<operator-class>} and one with metaclass
1007 @code{<foreign-object-class>}. Then the returned metaclass would be a
1008 class that inherits from both @code{<operator-class>} and
1009 @code{<foreign-object-class>}.
1011 If @var{supers} is the empty list, @code{ensure-metaclass} returns the
1012 default GOOPS metaclass @code{<class>}.
1014 GOOPS keeps a list of the metaclasses created by
1015 @code{ensure-metaclass}, so that each required type of metaclass only
1016 has to be created once.
1018 The @code{env} parameter is ignored.
1021 @deffn procedure ensure-metaclass-with-supers meta-supers
1022 @code{ensure-metaclass-with-supers} is an internal procedure used by
1023 @code{ensure-metaclass} (@pxref{Class Definition Internals,,
1024 ensure-metaclass}). It returns a metaclass that is the union by
1025 inheritance of the metaclasses in @var{meta-supers}.
1028 The internals of @code{make}, which is ultimately used to create the new
1029 class object, are described in @ref{Customizing Instance Creation},
1030 which covers the creation and initialization of instances in general.
1032 @node Customizing Class Definition
1033 @subsection Customizing Class Definition
1035 During the initialization of a new class, GOOPS calls a number of generic
1036 functions with the newly allocated class instance as the first
1037 argument. Specifically, GOOPS calls the generic function
1041 (initialize @var{class} @dots{})
1044 where @var{class} is the newly allocated class instance, and the default
1045 @code{initialize} method for arguments of type @code{<class>} calls the
1050 (compute-cpl @var{class})
1053 (compute-slots @var{class})
1056 (compute-get-n-set @var{class} @var{slot-def}), for each of the slot
1057 definitions returned by @code{compute-slots}
1060 (compute-getter-method @var{class} @var{slot-def}), for each of the
1061 slot definitions returned by @code{compute-slots} that includes a
1062 @code{#:getter} or @code{#:accessor} slot option
1065 (compute-setter-method @var{class} @var{slot-def}), for each of the
1066 slot definitions returned by @code{compute-slots} that includes a
1067 @code{#:setter} or @code{#:accessor} slot option.
1070 If the metaclass of the new class is something more specialized than the
1071 default @code{<class>}, then the type of @var{class} in the calls above
1072 is more specialized than @code{<class>}, and hence it becomes possible
1073 to define generic function methods, specialized for the new class's
1074 metaclass, that can modify or override the default behaviour of
1075 @code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
1077 @code{compute-cpl} computes the class precedence list (``CPL'') for the
1078 new class (@pxref{Class precedence list}), and returns it as a list of
1079 class objects. The CPL is important because it defines a superclass
1080 ordering that is used, when a generic function is invoked upon an
1081 instance of the class, to decide which of the available generic function
1082 methods is the most specific. Hence @code{compute-cpl} could be
1083 customized in order to modify the CPL ordering algorithm for all classes
1084 with a special metaclass.
1086 The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
1087 procedure, which is in turn called by the default @code{compute-cpl}
1090 @deffn procedure compute-std-cpl class
1091 Compute and return the class precedence list for @var{class} according
1092 to the algorithm described in @ref{Class precedence list}.
1095 @code{compute-slots} computes and returns a list of all slot definitions
1096 for the new class. By default, this list includes the direct slot
1097 definitions from the @code{define-class} form, plus the slot definitions
1098 that are inherited from the new class's superclasses. The default
1099 @code{compute-slots} method uses the CPL computed by @code{compute-cpl}
1100 to calculate this union of slot definitions, with the rule that slots
1101 inherited from superclasses are shadowed by direct slots with the same
1102 name. One possible reason for customizing @code{compute-slots} would be
1103 to implement an alternative resolution strategy for slot name conflicts.
1105 @code{compute-get-n-set} computes the low-level closures that will be
1106 used to get and set the value of a particular slot, and returns them in
1107 a list with two elements.
1109 The closures returned depend on how storage for that slot is allocated.
1110 The standard @code{compute-get-n-set} method, specialized for classes of
1111 type @code{<class>}, handles the standard GOOPS values for the
1112 @code{#:allocation} slot option (@pxref{Slot Options,, allocation}). By
1113 defining a new @code{compute-get-n-set} method for a more specialized
1114 metaclass, it is possible to support new types of slot allocation.
1116 Suppose you wanted to create a large number of instances of some class
1117 with a slot that should be shared between some but not all instances of
1118 that class - say every 10 instances should share the same slot storage.
1119 The following example shows how to implement and use a new type of slot
1120 allocation to do this.
1123 (define-class <batched-allocation-metaclass> (<class>))
1125 (let ((batch-allocation-count 0)
1126 (batch-get-n-set #f))
1127 (define-method (compute-get-n-set (class <batched-allocation-metaclass>) s)
1128 (case (slot-definition-allocation s)
1130 ;; If we've already used the same slot storage for 10 instances,
1132 (if (= batch-allocation-count 10)
1134 (set! batch-allocation-count 0)
1135 (set! batch-get-n-set #f)))
1136 ;; If we don't have a current pair of get and set closures,
1137 ;; create one. make-closure-variable returns a pair of closures
1138 ;; around a single Scheme variable - see goops.scm for details.
1140 (set! batch-get-n-set (make-closure-variable)))
1141 ;; Increment the batch allocation count.
1142 (set! batch-allocation-count (+ batch-allocation-count 1))
1145 ;; Call next-method to handle standard allocation types.
1146 (else (next-method)))))
1148 (define-class <class-using-batched-slot> ()
1150 (c #:allocation #:batched)
1152 #:metaclass <batched-allocation-metaclass>)
1155 The usage of @code{compute-getter-method} and @code{compute-setter-method}
1156 is described in @ref{MOP Specification}.
1158 @code{compute-cpl} and @code{compute-get-n-set} are called by the
1159 standard @code{initialize} method for classes whose metaclass is
1160 @code{<class>}. But @code{initialize} itself can also be modified, by
1161 defining an @code{initialize} method specialized to the new class's
1162 metaclass. Such a method could complete override the standard
1163 behaviour, by not calling @code{(next-method)} at all, but more
1164 typically it would perform additional class initialization steps before
1165 and/or after calling @code{(next-method)} for the standard behaviour.
1167 @node STKlos Compatibility
1168 @subsection STKlos Compatibility
1170 If the STKlos compatibility module is loaded, @code{define-class} is
1171 overwritten by a STKlos-specific definition; the standard GOOPS
1172 definition of @code{define-class} remains available in
1173 @code{standard-define-class}.
1175 @deffn syntax standard-define-class name (super @dots{}) slot-definition @dots{} . options
1176 @code{standard-define-class} is equivalent to the standard GOOPS
1177 @code{define-class}.
1180 @node Creating Instances
1181 @section Creating Instances
1184 * Basic Instance Creation::
1185 * Customizing Instance Creation::
1188 @node Basic Instance Creation
1189 @subsection Basic Instance Creation
1191 To create a new instance of any GOOPS class, use the generic function
1192 @code{make} or @code{make-instance}, passing the required class and any
1193 appropriate instance initialization arguments as keyword and value
1194 pairs. Note that @code{make} and @code{make-instances} are aliases for
1195 each other - their behaviour is identical.
1198 @deffnx method make (class <class>) . initargs
1199 Create and return a new instance of class @var{class}, initialized using
1202 In theory, @var{initargs} can have any structure that is understood by
1203 whatever methods get applied when the @code{initialize} generic function
1204 is applied to the newly allocated instance.
1206 In practice, specialized @code{initialize} methods would normally call
1207 @code{(next-method)}, and so eventually the standard GOOPS
1208 @code{initialize} methods are applied. These methods expect
1209 @var{initargs} to be a list with an even number of elements, where
1210 even-numbered elements (counting from zero) are keywords and
1211 odd-numbered elements are the corresponding values.
1213 GOOPS processes initialization argument keywords automatically for slots
1214 whose definition includes the @code{#:init-keyword} option (@pxref{Slot
1215 Options,, init-keyword}). Other keyword value pairs can only be
1216 processed by an @code{initialize} method that is specialized for the new
1217 instance's class. Any unprocessed keyword value pairs are ignored.
1220 @deffn generic make-instance
1221 @deffnx method make-instance (class <class>) . initargs
1222 @code{make-instance} is an alias for @code{make}.
1225 @node Customizing Instance Creation
1226 @subsection Customizing Instance Creation
1228 @code{make} itself is a generic function. Hence the @code{make}
1229 invocation itself can be customized in the case where the new instance's
1230 metaclass is more specialized than the default @code{<class>}, by
1231 defining a @code{make} method that is specialized to that metaclass.
1233 Normally, however, the method for classes with metaclass @code{<class>}
1234 will be applied. This method calls two generic functions:
1238 (allocate-instance @var{class} . @var{initargs})
1241 (initialize @var{instance} . @var{initargs})
1244 @code{allocate-instance} allocates storage for and returns the new
1245 instance, uninitialized. You might customize @code{allocate-instance},
1246 for example, if you wanted to provide a GOOPS wrapper around some other
1247 object programming system.
1249 To do this, you would create a specialized metaclass, which would act as
1250 the metaclass for all classes and instances from the other system. Then
1251 define an @code{allocate-instance} method, specialized to that
1252 metaclass, which calls a Guile primitive C function, which in turn
1253 allocates the new instance using the interface of the other object
1256 In this case, for a complete system, you would also need to customize a
1257 number of other generic functions like @code{make} and
1258 @code{initialize}, so that GOOPS knows how to make classes from the
1259 other system, access instance slots, and so on.
1261 @code{initialize} initializes the instance that is returned by
1262 @code{allocate-instance}. The standard GOOPS methods perform
1263 initializations appropriate to the instance class.
1267 At the least specialized level, the method for instances of type
1268 @code{<object>} performs internal GOOPS instance initialization, and
1269 initializes the instance's slots according to the slot definitions and
1270 any slot initialization keywords that appear in @var{initargs}.
1273 The method for instances of type @code{<class>} calls
1274 @code{(next-method)}, then performs the class initializations described
1275 in @ref{Customizing Class Definition}.
1278 and so on for generic functions, method, operator classes @dots{}
1281 Similarly, you can customize the initialization of instances of any
1282 application-defined class by defining an @code{initialize} method
1283 specialized to that class.
1285 Imagine a class whose instances' slots need to be initialized at
1286 instance creation time by querying a database. Although it might be
1287 possible to achieve this a combination of @code{#:init-thunk} keywords
1288 and closures in the slot definitions, it is neater to write an
1289 @code{initialize} method for the class that queries the database once
1290 and initializes all the dependent slot values according to the results.
1292 @node Accessing Slots
1293 @section Accessing Slots
1295 The definition of a slot contains at the very least a slot name, and may
1296 also contain various slot options, including getter, setter and/or
1297 accessor functions for the slot.
1299 It is always possible to access slots by name, using the various
1300 ``slot-ref'' and ``slot-set!'' procedures described in the following
1301 subsections. For example,
1304 (define-class <my-class> () ;; Define a class with slots
1305 (count #:init-value 0) ;; named "count" and "cache".
1306 (cache #:init-value '())
1309 (define inst (make <my-class>)) ;; Make an instance of this class.
1311 (slot-set! inst 'count 5) ;; Set the value of the "count"
1314 (slot-set! inst 'cache ;; Modify the value of the
1315 (cons (cons "^it" "It") ;; "cache" slot.
1316 (slot-ref inst 'cache)))
1319 If a slot definition includes a getter, setter or accessor function,
1320 these can be used instead of @code{slot-ref} and @code{slot-set!} to
1324 (define-class <adv-class> () ;; Define a new class whose slots
1325 (count #:setter set-count) ;; use a getter, a setter and
1326 (cache #:accessor cache) ;; an accessor.
1327 (csize #:getter cache-size)
1330 (define inst (make <adv-class>)) ;; Make an instance of this class.
1332 (set-count inst 5) ;; Set the value of the "count"
1335 (set! (cache inst) ;; Modify the value of the
1336 (cons (cons "^it" "It") ;; "cache" slot.
1339 (let ((size (cache-size inst))) ;; Get the value of the "csize"
1343 Whichever of these methods is used to access slots, GOOPS always calls
1344 the low-level @dfn{getter} and @dfn{setter} closures for the slot to get
1345 and set its value. These closures make sure that the slot behaves
1346 according to the @code{#:allocation} type that was specified in the slot
1347 definition (@pxref{Slot Options,, allocation}). (For more about these
1348 closures, see @ref{Customizing Class Definition,, compute-get-n-set}.)
1353 * Handling Slot Access Errors::
1356 @node Instance Slots
1357 @subsection Instance Slots
1359 Any slot, regardless of its allocation, can be queried, referenced and
1360 set using the following four primitive procedures.
1362 @deffn {primitive procedure} slot-exists? obj slot-name
1363 Return @code{#t} if @var{obj} has a slot with name @var{slot-name},
1364 otherwise @code{#f}.
1367 @deffn {primitive procedure} slot-bound? obj slot-name
1368 Return @code{#t} if the slot named @var{slot-name} in @var{obj} has a
1369 value, otherwise @code{#f}.
1371 @code{slot-bound?} calls the generic function @code{slot-missing} if
1372 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1373 Slot Access Errors, slot-missing}).
1376 @deffn {primitive procedure} slot-ref obj slot-name
1377 Return the value of the slot named @var{slot-name} in @var{obj}.
1379 @code{slot-ref} calls the generic function @code{slot-missing} if
1380 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1381 Slot Access Errors, slot-missing}).
1383 @code{slot-ref} calls the generic function @code{slot-unbound} if the
1384 named slot in @var{obj} does not have a value (@pxref{Handling Slot
1385 Access Errors, slot-unbound}).
1388 @deffn {primitive procedure} slot-set! obj slot-name value
1389 Set the value of the slot named @var{slot-name} in @var{obj} to @var{value}.
1391 @code{slot-set!} calls the generic function @code{slot-missing} if
1392 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1393 Slot Access Errors, slot-missing}).
1396 GOOPS stores information about slots in class metaobjects. Internally,
1397 all of these procedures work by looking up the slot definition for the
1398 slot named @var{slot-name} in the class metaobject for @code{(class-of
1399 @var{obj})}, and then using the slot definition's ``getter'' and
1400 ``setter'' closures to get and set the slot value.
1402 The next four procedures differ from the previous ones in that they take
1403 the class metaobject as an explicit argument, rather than assuming
1404 @code{(class-of @var{obj})}. Therefore they allow you to apply the
1405 ``getter'' and ``setter'' closures of a slot definition in one class to
1406 an instance of a different class.
1408 [ *fixme* I have no idea why this is useful! Perhaps when a slot in
1409 @code{(class-of @var{obj})} shadows a slot with the same name in one of
1410 its superclasses? There should be an enlightening example here. ]
1412 @deffn {primitive procedure} slot-exists-using-class? class obj slot-name
1413 Return @code{#t} if the class metaobject @var{class} has a slot
1414 definition for a slot with name @var{slot-name}, otherwise @code{#f}.
1417 @deffn {primitive procedure} slot-bound-using-class? class obj slot-name
1418 Return @code{#t} if applying @code{slot-ref-using-class} to the same
1419 arguments would call the generic function @code{slot-unbound}, otherwise
1422 @code{slot-bound-using-class?} calls the generic function
1423 @code{slot-missing} if @var{class} does not have a slot definition for a
1424 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1428 @deffn {primitive procedure} slot-ref-using-class class obj slot-name
1429 Apply the ``getter'' closure for the slot named @var{slot-name} in
1430 @var{class} to @var{obj}, and return its result.
1432 @code{slot-ref-using-class} calls the generic function
1433 @code{slot-missing} if @var{class} does not have a slot definition for a
1434 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1437 @code{slot-ref-using-class} calls the generic function
1438 @code{slot-unbound} if the application of the ``getter'' closure to
1439 @var{obj} returns an unbound value (@pxref{Handling Slot Access Errors,
1443 @deffn {primitive procedure} slot-set-using-class! class obj slot-name value
1444 Apply the ``setter'' closure for the slot named @var{slot-name} in
1445 @var{class} to @var{obj} and @var{value}.
1447 @code{slot-set-using-class!} calls the generic function
1448 @code{slot-missing} if @var{class} does not have a slot definition for a
1449 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1454 @subsection Class Slots
1456 Slots whose allocation is per-class rather than per-instance can be
1457 referenced and set without needing to specify any particular instance.
1459 @deffn procedure class-slot-ref class slot-name
1460 Return the value of the slot named @var{slot-name} in class @var{class}.
1461 The named slot must have @code{#:class} or @code{#:each-subclass}
1462 allocation (@pxref{Slot Options,, allocation}).
1464 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1465 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1466 function with arguments @var{class} and @var{slot-name}. Otherwise, if
1467 the slot value is unbound, @code{class-slot-ref} calls the
1468 @code{slot-missing} generic function, with the same arguments.
1471 @deffn procedure class-slot-set! class slot-name value
1472 Set the value of the slot named @var{slot-name} in class @var{class} to
1473 @var{value}. The named slot must have @code{#:class} or
1474 @code{#:each-subclass} allocation (@pxref{Slot Options,, allocation}).
1476 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1477 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1478 function with arguments @var{class} and @var{slot-name}.
1481 @node Handling Slot Access Errors
1482 @subsection Handling Slot Access Errors
1484 GOOPS calls one of the following generic functions when a ``slot-ref''
1485 or ``slot-set!'' call specifies a non-existent slot name, or tries to
1486 reference a slot whose value is unbound.
1488 @deffn generic slot-missing
1489 @deffnx method slot-missing (class <class>) slot-name
1490 @deffnx method slot-missing (class <class>) (object <object>) slot-name
1491 @deffnx method slot-missing (class <class>) (object <object>) slot-name value
1492 When an application attempts to reference or set a class or instance
1493 slot by name, and the slot name is invalid for the specified @var{class}
1494 or @var{object}, GOOPS calls the @code{slot-missing} generic function.
1496 The default methods all call @code{goops-error} with an appropriate
1500 @deffn generic slot-unbound
1501 @deffnx method slot-unbound (object <object>)
1502 @deffnx method slot-unbound (class <class>) slot-name
1503 @deffnx method slot-unbound (class <class>) (object <object>) slot-name
1504 When an application attempts to reference a class or instance slot, and
1505 the slot's value is unbound, GOOPS calls the @code{slot-unbound} generic
1508 The default methods all call @code{goops-error} with an appropriate
1512 @node Creating Generic Functions
1513 @section Creating Generic Functions
1515 A generic function is a collection of methods, with rules for
1516 determining which of the methods should be applied for any given
1517 invocation of the generic function.
1519 GOOPS represents generic functions as metaobjects of the class
1520 @code{<generic>} (or one of its subclasses).
1523 * Basic Generic Function Creation::
1524 * Generic Function Internals::
1525 * Extending Guiles Primitives::
1528 @node Basic Generic Function Creation
1529 @subsection Basic Generic Function Creation
1531 The following forms may be used to bind a variable to a generic
1532 function. Depending on that variable's pre-existing value, the generic
1533 function may be created empty - with no methods - or it may contain
1534 methods that are inferred from the pre-existing value.
1536 It is not, in general, necessary to use @code{define-generic} or
1537 @code{define-accessor} before defining methods for the generic function
1538 using @code{define-method}, since @code{define-method} will
1539 automatically interpolate a @code{define-generic} call, or upgrade an
1540 existing generic to an accessor, if that is implied by the
1541 @code{define-method} call. Note in particular that,
1542 if the specified variable already has a @emph{generic function} value,
1543 @code{define-generic} and @code{define-accessor} will @emph{discard} it!
1544 Obviously it is application-dependent whether this is desirable or not.
1546 If, for example, you wanted to extend @code{+} for a class representing
1547 a new numerical type, you probably want to inherit any existing methods
1548 for @code{+} and so should not use @code{define-generic}. If, on the
1549 other hand, you do not want to risk inheriting methods whose behaviour
1550 might surprise you, you can use @code{define-generic} or
1551 @code{define-accessor} to wipe the slate clean.
1553 @deffn syntax define-generic symbol
1554 Create a generic function with name @var{symbol} and bind it to the
1555 variable @var{symbol}.
1557 If the variable @var{symbol} was previously bound to a Scheme procedure
1558 (or procedure-with-setter), the old procedure (and setter) is
1559 incorporated into the new generic function as its default procedure (and
1560 setter). Any other previous value that was bound to @var{symbol},
1561 including an existing generic function, is overwritten by the new
1565 @deffn syntax define-accessor symbol
1566 Create an accessor with name @var{symbol} and bind it to the variable
1569 If the variable @var{symbol} was previously bound to a Scheme procedure
1570 (or procedure-with-setter), the old procedure (and setter) is
1571 incorporated into the new accessor as its default procedure (and
1572 setter). Any other previous value that was bound to @var{symbol},
1573 including an existing generic function or accessor, is overwritten by
1577 It is sometimes tempting to use GOOPS accessors with short names. For
1578 example, it is tempting to use the name @code{x} for the x-coordinate
1581 Assume that we work with a graphical package which needs to use two
1582 independent vector packages for 2D and 3D vectors respectively. If
1583 both packages export @code{x} we will encounter a name collision.
1585 This can be resolved automagically with the duplicates handler
1586 @code{merge-generics} which gives the module system license to merge
1587 all generic functions sharing a common name:
1590 (define-module (math 2D-vectors)
1591 :use-module (oop goops)
1594 (define-module (math 3D-vectors)
1595 :use-module (oop goops)
1596 :export (x y z ...))
1598 (define-module (my-module)
1599 :use-module (math 2D-vectors)
1600 :use-module (math 3D-vectors)
1601 :duplicates merge-generics)
1604 The generic function @code{x} in @code{(my-module)} will now share
1605 methods with @code{x} in both imported modules.
1607 There will, in fact, now be three distinct generic functions named
1608 @code{x}: @code{x} in @code{(2D-vectors)}, @code{x} in
1609 @code{(3D-vectors)}, and @code{x} in @code{(my-module)}. The last
1610 function will be an @code{<extended-generic>}, extending the previous
1613 Let's call the imported generic functions the "ancestor functions".
1614 The generic function @code{x} in @code{(my-module)} is, in turn, a
1615 "descendant function" of the imported functions, extending its
1618 For any generic function G, the applicable methods are selected from
1619 the union of the methods of the descendant functions, the methods of G
1620 itself and the methods of the ancestor functions.
1622 This, ancestor functions share methods with their descendants and vice
1623 versa. This implies that @code{x} in @code{(math 2D-vectors)} will
1624 share the methods of @code{x} in @code{(my-module)} and vice versa,
1625 while @code{x} in @code{(math 2D-vectors)} doesn't share the methods
1626 of @code{x} in @code{(math 3D-vectors)}, thus preserving modularity.
1628 Sharing is dynamic, so that adding new methods to a descendant implies
1629 adding it to the ancestor.
1631 If duplicates checking is desired in the above example, the following
1632 form of the @code{:duplicates} option can be used instead:
1635 :duplicates (merge-generics check)
1638 @node Generic Function Internals
1639 @subsection Generic Function Internals
1641 @code{define-generic} calls @code{ensure-generic} to upgrade a
1642 pre-existing procedure value, or @code{make} with metaclass
1643 @code{<generic>} to create a new generic function.
1645 @code{define-accessor} calls @code{ensure-accessor} to upgrade a
1646 pre-existing procedure value, or @code{make-accessor} to create a new
1649 @deffn procedure ensure-generic old-definition [name]
1650 Return a generic function with name @var{name}, if possible by using or
1651 upgrading @var{old-definition}. If unspecified, @var{name} defaults to
1654 If @var{old-definition} is already a generic function, it is returned
1657 If @var{old-definition} is a Scheme procedure or procedure-with-setter,
1658 @code{ensure-generic} returns a new generic function that uses
1659 @var{old-definition} for its default procedure and setter.
1661 Otherwise @code{ensure-generic} returns a new generic function with no
1662 defaults and no methods.
1665 @deffn procedure make-generic [name]
1666 Return a new generic function with name @code{(car @var{name})}. If
1667 unspecified, @var{name} defaults to @code{#f}.
1670 @code{ensure-generic} calls @code{make} with metaclasses
1671 @code{<generic>} and @code{<generic-with-setter>}, depending on the
1672 previous value of the variable that it is trying to upgrade.
1674 @code{make-generic} is a simple wrapper for @code{make} with metaclass
1677 @deffn procedure ensure-accessor proc [name]
1678 Return an accessor with name @var{name}, if possible by using or
1679 upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
1681 If @var{proc} is already an accessor, it is returned unchanged.
1683 If @var{proc} is a Scheme procedure, procedure-with-setter or generic
1684 function, @code{ensure-accessor} returns an accessor that reuses the
1685 reusable elements of @var{proc}.
1687 Otherwise @code{ensure-accessor} returns a new accessor with no defaults
1691 @deffn procedure make-accessor [name]
1692 Return a new accessor with name @code{(car @var{name})}. If
1693 unspecified, @var{name} defaults to @code{#f}.
1696 @code{ensure-accessor} calls @code{make} with
1697 metaclass @code{<generic-with-setter>}, as well as calls to
1698 @code{ensure-generic}, @code{make-accessor} and (tail recursively)
1699 @code{ensure-accessor}.
1701 @code{make-accessor} calls @code{make} twice, first
1702 with metaclass @code{<generic>} to create a generic function for the
1703 setter, then with metaclass @code{<generic-with-setter>} to create the
1704 accessor, passing the setter generic function as the value of the
1705 @code{#:setter} keyword.
1707 @node Extending Guiles Primitives
1708 @subsection Extending Guile's Primitives
1710 When GOOPS is loaded, many of Guile's primitive procedures can be
1711 extended by giving them a generic function definition that operates
1712 in conjunction with their normal C-coded implementation. For
1713 primitives that are extended in this way, the result from the user-
1714 or application-level point of view is that the extended primitive
1715 behaves exactly like a generic function with the C-coded implementation
1716 as its default method.
1718 The @code{generic-capability?} predicate should be used to determine
1719 whether a particular primitive is extensible in this way.
1721 @deffn {primitive procedure} generic-capability? primitive
1722 Return @code{#t} if @var{primitive} can be extended by giving it a
1723 generic function definition, otherwise @code{#f}.
1726 Even when a primitive procedure is extensible like this, its generic
1727 function definition is not created until it is needed by a call to
1728 @code{define-method}, or until the application explicitly requests it
1729 by calling @code{enable-primitive-generic!}.
1731 @deffn {primitive procedure} enable-primitive-generic! primitive
1732 Force the creation of a generic function definition for
1736 Once the generic function definition for a primitive has been created,
1737 it can be retrieved using @code{primitive-generic-generic}.
1739 @deffn {primitive procedure} primitive-generic-generic primitive
1740 Return the generic function definition of @var{primitive}.
1742 @code{primitive-generic-generic} raises an error if @var{primitive}
1743 is not a primitive with generic capability, or if its generic capability
1744 has not yet been enabled, whether implicitly (by @code{define-method})
1745 or explicitly (by @code{enable-primitive-generic!}).
1748 Note that the distinction between, on the one hand, primitives with
1749 additional generic function definitions and, on the other hand, generic
1750 functions with a default method, may disappear when GOOPS is fully
1751 integrated into the core of Guile. Consequently, the
1752 procedures described in this section may disappear as well.
1754 @node Adding Methods to Generic Functions
1755 @section Adding Methods to Generic Functions
1758 * Basic Method Definition::
1759 * Method Definition Internals::
1762 @node Basic Method Definition
1763 @subsection Basic Method Definition
1765 To add a method to a generic function, use the @code{define-method} form.
1767 @deffn syntax define-method (generic parameter @dots{}) . body
1768 Define a method for the generic function or accessor @var{generic} with
1769 parameters @var{parameter}s and body @var{body}.
1771 @var{generic} is a generic function. If @var{generic} is a variable
1772 which is not yet bound to a generic function object, the expansion of
1773 @code{define-method} will include a call to @code{define-generic}. If
1774 @var{generic} is @code{(setter @var{generic-with-setter})}, where
1775 @var{generic-with-setter} is a variable which is not yet bound to a
1776 generic-with-setter object, the expansion will include a call to
1777 @code{define-accessor}.
1779 Each @var{parameter} must be either a symbol or a two-element list
1780 @code{(@var{symbol} @var{class})}. The symbols refer to variables in
1781 the @var{body} that will be bound to the parameters supplied by the
1782 caller when calling this method. The @var{class}es, if present,
1783 specify the possible combinations of parameters to which this method
1786 @var{body} is the body of the method definition.
1789 @code{define-method} expressions look a little like normal Scheme
1790 procedure definitions of the form
1793 (define (name formals @dots{}) . body)
1796 The most important difference is that each formal parameter, apart from the
1797 possible ``rest'' argument, can be qualified by a class name:
1798 @code{@var{formal}} becomes @code{(@var{formal} @var{class})}. The
1799 meaning of this qualification is that the method being defined
1800 will only be applicable in a particular generic function invocation if
1801 the corresponding argument is an instance of @code{@var{class}} (or one of
1802 its subclasses). If more than one of the formal parameters is qualified
1803 in this way, then the method will only be applicable if each of the
1804 corresponding arguments is an instance of its respective qualifying class.
1806 Note that unqualified formal parameters act as though they are qualified
1807 by the class @code{<top>}, which GOOPS uses to mean the superclass of
1808 all valid Scheme types, including both primitive types and GOOPS classes.
1810 For example, if a generic function method is defined with
1811 @var{parameter}s @code{((s1 <square>) (n <number>))}, that method is
1812 only applicable to invocations of its generic function that have two
1813 parameters where the first parameter is an instance of the
1814 @code{<square>} class and the second parameter is a number.
1816 If a generic function is invoked with a combination of parameters for which
1817 there is no applicable method, GOOPS raises an error. For more about
1818 invocation error handling, and generic function invocation in general,
1819 see @ref{Invoking Generic Functions}.
1821 @node Method Definition Internals
1822 @subsection Method Definition Internals
1824 @code{define-method}
1828 checks the form of the first parameter, and applies the following steps
1829 to the accessor's setter if it has the @code{(setter @dots{})} form
1832 interpolates a call to @code{define-generic} or @code{define-accessor}
1833 if a generic function is not already defined with the supplied name
1836 calls @code{method} with the @var{parameter}s and @var{body}, to make a
1840 calls @code{add-method!} to add this method to the relevant generic
1844 @deffn syntax method (parameter @dots{}) . body
1845 Make a method whose specializers are defined by the classes in
1846 @var{parameter}s and whose procedure definition is constructed from the
1847 @var{parameter} symbols and @var{body} forms.
1849 The @var{parameter} and @var{body} parameters should be as for
1850 @code{define-method} (@pxref{Basic Method Definition,, define-method}).
1857 extracts formals and specializing classes from the @var{parameter}s,
1858 defaulting the class for unspecialized parameters to @code{<top>}
1861 creates a closure using the formals and the @var{body} forms
1864 calls @code{make} with metaclass @code{<method>} and the specializers
1865 and closure using the @code{#:specializers} and @code{#:procedure}
1869 @deffn procedure make-method specializers procedure
1870 Make a method using @var{specializers} and @var{procedure}.
1872 @var{specializers} should be a list of classes that specifies the
1873 parameter combinations to which this method will be applicable.
1875 @var{procedure} should be the closure that will applied to the generic
1876 function parameters when this method is invoked.
1879 @code{make-method} is a simple wrapper around @code{make} with metaclass
1882 @deffn generic add-method! target method
1883 Generic function for adding method @var{method} to @var{target}.
1886 @deffn method add-method! (generic <generic>) (method <method>)
1887 Add method @var{method} to the generic function @var{generic}.
1890 @deffn method add-method! (proc <procedure>) (method <method>)
1891 If @var{proc} is a procedure with generic capability (@pxref{Extending
1892 Guiles Primitives,, generic-capability?}), upgrade it to a
1893 primitive generic and add @var{method} to its generic function
1897 @deffn method add-method! (pg <primitive-generic>) (method <method>)
1898 Add method @var{method} to the generic function definition of @var{pg}.
1900 Implementation: @code{(add-method! (primitive-generic-generic pg) method)}.
1903 @deffn method add-method! (whatever <top>) (method <method>)
1904 Raise an error indicating that @var{whatever} is not a valid generic
1908 @node Invoking Generic Functions
1909 @section Invoking Generic Functions
1911 When a variable with a generic function definition appears as the first
1912 element of a list that is being evaluated, the Guile evaluator tries
1913 to apply the generic function to the arguments obtained by evaluating
1914 the remaining elements of the list. [ *fixme* How do I put this in a
1915 more Schemely and less Lispy way? ]
1917 Usually a generic function contains several method definitions, with
1918 varying degrees of formal parameter specialization (@pxref{Basic
1919 Method Definition,, define-method}). So it is necessary to sort these
1920 methods by specificity with respect to the supplied arguments, and then
1921 apply the most specific method definition. Less specific methods
1922 may be applied subsequently if a method that is being applied calls
1926 * Determining Which Methods to Apply::
1927 * Handling Invocation Errors::
1930 @node Determining Which Methods to Apply
1931 @subsection Determining Which Methods to Apply
1933 [ *fixme* Sorry - this is the area of GOOPS that I understand least of
1934 all, so I'm afraid I have to pass on this section. Would some other
1935 kind person consider filling it in? ]
1937 @deffn generic apply-generic
1938 @deffnx method apply-generic (gf <generic>) args
1941 @deffn generic compute-applicable-methods
1942 @deffnx method compute-applicable-methods (gf <generic>) args
1945 @deffn generic sort-applicable-methods
1946 @deffnx method sort-applicable-methods (gf <generic>) methods args
1949 @deffn generic method-more-specific?
1950 @deffnx method method-more-specific? (m1 <method>) (m2 <method>) args
1953 @deffn generic apply-method
1954 @deffnx method apply-method (gf <generic>) methods build-next args
1957 @deffn generic apply-methods
1958 @deffnx method apply-methods (gf <generic>) (l <list>) args
1961 @node Handling Invocation Errors
1962 @subsection Handling Invocation Errors
1964 @deffn generic no-method
1965 @deffnx method no-method (gf <generic>) args
1966 When an application invokes a generic function, and no methods at all
1967 have been defined for that generic function, GOOPS calls the
1968 @code{no-method} generic function. The default method calls
1969 @code{goops-error} with an appropriate message.
1972 @deffn generic no-applicable-method
1973 @deffnx method no-applicable-method (gf <generic>) args
1974 When an application applies a generic function to a set of arguments,
1975 and no methods have been defined for those argument types, GOOPS calls
1976 the @code{no-applicable-method} generic function. The default method
1977 calls @code{goops-error} with an appropriate message.
1980 @deffn generic no-next-method
1981 @deffnx method no-next-method (gf <generic>) args
1982 When a generic function method calls @code{(next-method)} to invoke the
1983 next less specialized method for that generic function, and no less
1984 specialized methods have been defined for the current generic function
1985 arguments, GOOPS calls the @code{no-next-method} generic function. The
1986 default method calls @code{goops-error} with an appropriate message.
1989 @node Redefining a Class
1990 @section Redefining a Class
1992 Suppose that a class @code{<my-class>} is defined using @code{define-class}
1993 (@pxref{Basic Class Definition,, define-class}), with slots that have
1994 accessor functions, and that an application has created several instances
1995 of @code{<my-class>} using @code{make} (@pxref{Basic Instance Creation,,
1996 make}). What then happens if @code{<my-class>} is redefined by calling
1997 @code{define-class} again?
2000 * Default Class Redefinition Behaviour::
2001 * Customizing Class Redefinition::
2004 @node Default Class Redefinition Behaviour
2005 @subsection Default Class Redefinition Behaviour
2007 GOOPS' default answer to this question is as follows.
2011 All existing direct instances of @code{<my-class>} are converted to be
2012 instances of the new class. This is achieved by preserving the values
2013 of slots that exist in both the old and new definitions, and initializing the
2014 values of new slots in the usual way (@pxref{Basic Instance Creation,,
2018 All existing subclasses of @code{<my-class>} are redefined, as though
2019 the @code{define-class} expressions that defined them were re-evaluated
2020 following the redefinition of @code{<my-class>}, and the class
2021 redefinition process described here is applied recursively to the
2022 redefined subclasses.
2025 Once all of its instances and subclasses have been updated, the class
2026 metaobject previously bound to the variable @code{<my-class>} is no
2027 longer needed and so can be allowed to be garbage collected.
2030 To keep things tidy, GOOPS also needs to do a little housekeeping on
2031 methods that are associated with the redefined class.
2035 Slot accessor methods for slots in the old definition should be removed
2036 from their generic functions. They will be replaced by accessor methods
2037 for the slots of the new class definition.
2040 Any generic function method that uses the old @code{<my-class>} metaobject
2041 as one of its formal parameter specializers must be updated to refer to
2042 the new @code{<my-class>} metaobject. (Whenever a new generic function
2043 method is defined, @code{define-method} adds the method to a list stored
2044 in the class metaobject for each class used as a formal parameter
2045 specializer, so it is easy to identify all the methods that must be
2046 updated when a class is redefined.)
2049 If this class redefinition strategy strikes you as rather counter-intuitive,
2050 bear in mind that it is derived from similar behaviour in other object
2051 systems such as CLOS, and that experience in those systems has shown it to be
2052 very useful in practice.
2054 Also bear in mind that, like most of GOOPS' default behaviour, it can
2055 be customized@dots{}
2057 @node Customizing Class Redefinition
2058 @subsection Customizing Class Redefinition
2060 When @code{define-class} notices that a class is being redefined,
2061 it constructs the new class metaobject as usual, and then invokes the
2062 @code{class-redefinition} generic function with the old and new classes
2063 as arguments. Therefore, if the old or new classes have metaclasses
2064 other than the default @code{<class>}, class redefinition behaviour can
2065 be customized by defining a @code{class-redefinition} method that is
2066 specialized for the relevant metaclasses.
2068 @deffn generic class-redefinition
2069 Handle the class redefinition from @var{old-class} to @var{new-class},
2070 and return the new class metaobject that should be bound to the
2071 variable specified by @code{define-class}'s first argument.
2074 @deffn method class-redefinition (old-class <class>) (new-class <class>)
2075 Implements GOOPS' default class redefinition behaviour, as described in
2076 @ref{Default Class Redefinition Behaviour}. Returns the metaobject
2077 for the new class definition.
2080 An alternative class redefinition strategy could be to leave all
2081 existing instances as instances of the old class, but accepting that the
2082 old class is now ``nameless'', since its name has been taken over by the
2083 new definition. In this strategy, any existing subclasses could also
2084 be left as they are, on the understanding that they inherit from a nameless
2087 This strategy is easily implemented in GOOPS, by defining a new metaclass,
2088 that will be used as the metaclass for all classes to which the strategy
2089 should apply, and then defining a @code{class-redefinition} method that
2090 is specialized for this metaclass:
2093 (define-class <can-be-nameless> (<class>))
2095 (define-method (class-redefinition (old <can-be-nameless>) (new <class>))
2099 When customization can be as easy as this, aren't you glad that GOOPS
2100 implements the far more difficult strategy as its default!
2102 Finally, note that, if @code{class-redefinition} itself is not customized,
2103 the default @code{class-redefinition} method invokes three further
2104 generic functions that could be individually customized:
2108 (remove-class-accessors! @var{old-class})
2111 (update-direct-method! @var{method} @var{old-class} @var{new-class})
2114 (update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
2117 and the default methods for these generic functions invoke further
2118 generic functions, and so on@dots{} The detailed protocol for all of these
2119 is described in @ref{MOP Specification}.
2121 @node Changing the Class of an Instance
2122 @section Changing the Class of an Instance
2124 You can change the class of an existing instance by invoking the
2125 generic function @code{change-class} with two arguments: the instance
2128 @deffn generic change-class
2131 The default method for @code{change-class} decides how to implement the
2132 change of class by looking at the slot definitions for the instance's
2133 existing class and for the new class. If the new class has slots with
2134 the same name as slots in the existing class, the values for those slots
2135 are preserved. Slots that are present only in the existing class are
2136 discarded. Slots that are present only in the new class are initialized
2137 using the corresponding slot definition's init function (@pxref{Classes,,
2138 slot-init-function}).
2140 @deffn {method} change-class (obj <object>) (new <class>)
2141 Modify instance @var{obj} to make it an instance of class @var{new}.
2143 The value of each of @var{obj}'s slots is preserved only if a similarly named
2144 slot exists in @var{new}; any other slot values are discarded.
2146 The slots in @var{new} that do not correspond to any of @var{obj}'s
2147 pre-existing slots are initialized according to @var{new}'s slot definitions'
2151 Customized change of class behaviour can be implemented by defining
2152 @code{change-class} methods that are specialized either by the class
2153 of the instances to be modified or by the metaclass of the new class.
2155 When a class is redefined (@pxref{Redefining a Class}), and the default
2156 class redefinition behaviour is not overridden, GOOPS (eventually)
2157 invokes the @code{change-class} generic function for each existing
2158 instance of the redefined class.
2161 @section Introspection
2163 @dfn{Introspection}, also known as @dfn{reflection}, is the name given
2164 to the ability to obtain information dynamically about GOOPS metaobjects.
2165 It is perhaps best illustrated by considering an object oriented language
2166 that does not provide any introspection, namely C++.
2168 Nothing in C++ allows a running program to obtain answers to the following
2173 What are the data members of this object or class?
2176 What classes does this class inherit from?
2179 Is this method call virtual or non-virtual?
2182 If I invoke @code{Employee::adjustHoliday()}, what class contains the
2183 @code{adjustHoliday()} method that will be applied?
2186 In C++, answers to such questions can only be determined by looking at
2187 the source code, if you have access to it. GOOPS, on the other hand,
2188 includes procedures that allow answers to these questions --- or their
2189 GOOPS equivalents --- to be obtained dynamically, at run time.
2195 * Generic Functions::
2196 * Generic Function Methods::
2202 @deffn {primitive procedure} class-name class
2203 Return the name of class @var{class}.
2204 This is the value of the @var{class} metaobject's @code{name} slot.
2207 @deffn {primitive procedure} class-direct-supers class
2208 Return a list containing the direct superclasses of @var{class}.
2209 This is the value of the @var{class} metaobject's
2210 @code{direct-supers} slot.
2213 @deffn {primitive procedure} class-direct-slots class
2214 Return a list containing the slot definitions of the direct slots of
2216 This is the value of the @var{class} metaobject's @code{direct-slots}
2220 @deffn {primitive procedure} class-direct-subclasses class
2221 Return a list containing the direct subclasses of @var{class}.
2222 This is the value of the @var{class} metaobject's
2223 @code{direct-subclasses} slot.
2226 @deffn {primitive procedure} class-direct-methods class
2227 Return a list of all the generic function methods that use @var{class}
2228 as a formal parameter specializer.
2229 This is the value of the @var{class} metaobject's @code{direct-methods}
2233 @deffn {primitive procedure} class-precedence-list class
2234 Return the class precedence list for class @var{class} (@pxref{Class
2236 This is the value of the @var{class} metaobject's @code{cpl} slot.
2239 @deffn {primitive procedure} class-slots class
2240 Return a list containing the slot definitions for all @var{class}'s slots,
2241 including any slots that are inherited from superclasses.
2242 This is the value of the @var{class} metaobject's @code{slots} slot.
2245 @deffn {primitive procedure} class-environment class
2246 Return the value of @var{class}'s @code{environment} slot.
2247 [ *fixme* I don't know what this value is used for. ]
2250 @deffn procedure class-subclasses class
2251 Return a list of all subclasses of @var{class}.
2254 @deffn procedure class-methods class
2255 Return a list of all methods that use @var{class} or a subclass of
2256 @var{class} as one of its formal parameter specializers.
2262 @deffn procedure class-slot-definition class slot-name
2263 Return the slot definition for the slot named @var{slot-name} in class
2264 @var{class}. @var{slot-name} should be a symbol.
2267 @deffn procedure slot-definition-name slot-def
2268 Extract and return the slot name from @var{slot-def}.
2271 @deffn procedure slot-definition-options slot-def
2272 Extract and return the slot options from @var{slot-def}.
2275 @deffn procedure slot-definition-allocation slot-def
2276 Extract and return the slot allocation option from @var{slot-def}. This
2277 is the value of the @code{#:allocation} keyword (@pxref{Slot Options,,
2278 allocation}), or @code{#:instance} if the @code{#:allocation} keyword is
2282 @deffn procedure slot-definition-getter slot-def
2283 Extract and return the slot getter option from @var{slot-def}. This is
2284 the value of the @code{#:getter} keyword (@pxref{Slot Options,,
2285 getter}), or @code{#f} if the @code{#:getter} keyword is absent.
2288 @deffn procedure slot-definition-setter slot-def
2289 Extract and return the slot setter option from @var{slot-def}. This is
2290 the value of the @code{#:setter} keyword (@pxref{Slot Options,,
2291 setter}), or @code{#f} if the @code{#:setter} keyword is absent.
2294 @deffn procedure slot-definition-accessor slot-def
2295 Extract and return the slot accessor option from @var{slot-def}. This
2296 is the value of the @code{#:accessor} keyword (@pxref{Slot Options,,
2297 accessor}), or @code{#f} if the @code{#:accessor} keyword is absent.
2300 @deffn procedure slot-definition-init-value slot-def
2301 Extract and return the slot init-value option from @var{slot-def}. This
2302 is the value of the @code{#:init-value} keyword (@pxref{Slot Options,,
2303 init-value}), or the unbound value if the @code{#:init-value} keyword is
2307 @deffn procedure slot-definition-init-form slot-def
2308 Extract and return the slot init-form option from @var{slot-def}. This
2309 is the value of the @code{#:init-form} keyword (@pxref{Slot Options,,
2310 init-form}), or the unbound value if the @code{#:init-form} keyword is
2314 @deffn procedure slot-definition-init-thunk slot-def
2315 Extract and return the slot init-thunk option from @var{slot-def}. This
2316 is the value of the @code{#:init-thunk} keyword (@pxref{Slot Options,,
2317 init-thunk}), or @code{#f} if the @code{#:init-thunk} keyword is absent.
2320 @deffn procedure slot-definition-init-keyword slot-def
2321 Extract and return the slot init-keyword option from @var{slot-def}.
2322 This is the value of the @code{#:init-keyword} keyword (@pxref{Slot
2323 Options,, init-keyword}), or @code{#f} if the @code{#:init-keyword}
2327 @deffn procedure slot-init-function class slot-name
2328 Return the initialization function for the slot named @var{slot-name} in
2329 class @var{class}. @var{slot-name} should be a symbol.
2331 The returned initialization function incorporates the effects of the
2332 standard @code{#:init-thunk}, @code{#:init-form} and @code{#:init-value}
2333 slot options. These initializations can be overridden by the
2334 @code{#:init-keyword} slot option or by a specialized @code{initialize}
2335 method, so, in general, the function returned by
2336 @code{slot-init-function} may be irrelevant. For a fuller discussion,
2337 see @ref{Slot Options,, init-value}.
2341 @subsection Instances
2343 @deffn {primitive procedure} class-of value
2344 Return the GOOPS class of any Scheme @var{value}.
2347 @deffn {primitive procedure} instance? object
2348 Return @code{#t} if @var{object} is any GOOPS instance, otherwise
2352 @deffn procedure is-a? object class
2353 Return @code{#t} if @var{object} is an instance of @var{class} or one of
2357 Implementation notes: @code{is-a?} uses @code{class-of} and
2358 @code{class-precedence-list} to obtain the class precedence list for
2361 @node Generic Functions
2362 @subsection Generic Functions
2364 @deffn {primitive procedure} generic-function-name gf
2365 Return the name of generic function @var{gf}.
2368 @deffn {primitive procedure} generic-function-methods gf
2369 Return a list of the methods of generic function @var{gf}.
2370 This is the value of the @var{gf} metaobject's @code{methods} slot.
2373 @node Generic Function Methods
2374 @subsection Generic Function Methods
2376 @deffn {primitive procedure} method-generic-function method
2377 Return the generic function that @var{method} belongs to.
2378 This is the value of the @var{method} metaobject's
2379 @code{generic-function} slot.
2382 @deffn {primitive procedure} method-specializers method
2383 Return a list of @var{method}'s formal parameter specializers .
2384 This is the value of the @var{method} metaobject's
2385 @code{specializers} slot.
2388 @deffn {primitive procedure} method-procedure method
2389 Return the procedure that implements @var{method}.
2390 This is the value of the @var{method} metaobject's
2391 @code{procedure} slot.
2394 @deffn generic method-source
2395 @deffnx method method-source (m <method>)
2396 Return an expression that prints to show the definition of method
2400 (define-generic cube)
2402 (define-method (cube (n <number>))
2405 (map method-source (generic-function-methods cube))
2407 ((method ((n <number>)) (* n n n)))
2411 @node Miscellaneous Functions
2412 @section Miscellaneous Functions
2415 * Administrative Functions::
2417 * Object Comparisons::
2419 * Write and Display::
2422 @node Administrative Functions
2423 @subsection Administration Functions
2425 This section describes administrative, non-technical GOOPS functions.
2427 @deffn primitive goops-version
2428 Return the current GOOPS version as a string, for example ``0.2''.
2431 @node Error Handling
2432 @subsection Error Handling
2434 The procedure @code{goops-error} is called to raise an appropriate error
2435 by the default methods of the following generic functions:
2439 @code{slot-missing} (@pxref{Handling Slot Access Errors,, slot-missing})
2442 @code{slot-unbound} (@pxref{Handling Slot Access Errors,, slot-unbound})
2445 @code{no-method} (@pxref{Handling Invocation Errors,, no-method})
2448 @code{no-applicable-method} (@pxref{Handling Invocation Errors,,
2449 no-applicable-method})
2452 @code{no-next-method} (@pxref{Handling Invocation Errors,,
2456 If you customize these functions for particular classes or metaclasses,
2457 you may still want to use @code{goops-error} to signal any error
2458 conditions that you detect.
2460 @deffn procedure goops-error format-string . args
2461 Raise an error with key @code{goops-error} and error message constructed
2462 from @var{format-string} and @var{args}. Error message formatting is
2463 as done by @code{scm-error}.
2466 @node Object Comparisons
2467 @subsection Object Comparisons
2470 @deffnx method eqv? ((x <top>) (y <top>))
2471 @deffnx generic equal?
2472 @deffnx method equal? ((x <top>) (y <top>))
2474 @deffnx method = ((x <number>) (y <number>))
2475 Generic functions and default (unspecialized) methods for comparing two
2478 The default method for @code{eqv?} returns @code{#t} for all values
2479 that are equal in the sense defined by R5RS and the Guile reference
2480 manual, otherwise @code{#f}. The default method for @code{equal?}
2481 returns @code{#t} or @code{#f} in the sense defined by R5RS and the
2482 Guile reference manual. If no such comparison is defined,
2483 @code{equal?} returns the result of a call to @code{eqv?}. The
2484 default method for = returns @code{#t} if @var{x} and @var{y} are
2485 numerically equal, otherwise @code{#f}.
2487 Application class authors may wish to define specialized methods for
2488 @code{eqv?}, @code{equal?} and @code{=} that compare instances of the
2489 same class for equality in whatever sense is useful to the
2490 application. Such methods will only be called if the arguments have
2491 the same class and the result of the comparison isn't defined by R5RS
2492 and the Guile reference manual.
2495 @node Cloning Objects
2496 @subsection Cloning Objects
2498 @deffn generic shallow-clone
2499 @deffnx method shallow-clone (self <object>)
2500 Return a ``shallow'' clone of @var{self}. The default method makes a
2501 shallow clone by allocating a new instance and copying slot values from
2502 self to the new instance. Each slot value is copied either as an
2503 immediate value or by reference.
2506 @deffn generic deep-clone
2507 @deffnx method deep-clone (self <object>)
2508 Return a ``deep'' clone of @var{self}. The default method makes a deep
2509 clone by allocating a new instance and copying or cloning slot values
2510 from self to the new instance. If a slot value is an instance
2511 (satisfies @code{instance?}), it is cloned by calling @code{deep-clone}
2512 on that value. Other slot values are copied either as immediate values
2516 @node Write and Display
2517 @subsection Write and Display
2519 @deffn {primitive generic} write object port
2520 @deffnx {primitive generic} display object port
2521 When GOOPS is loaded, @code{write} and @code{display} become generic
2522 functions with special methods for printing
2526 objects - instances of the class @code{<object>}
2529 foreign objects - instances of the class @code{<foreign-object>}
2532 classes - instances of the class @code{<class>}
2535 generic functions - instances of the class @code{<generic>}
2538 methods - instances of the class @code{<method>}.
2541 @code{write} and @code{display} print non-GOOPS values in the same way
2542 as the Guile primitive @code{write} and @code{display} functions.
2545 @node MOP Specification, Tutorial, Reference Manual, Top
2546 @chapter MOP Specification
2548 For an introduction to metaobjects and the metaobject protocol,
2549 see @ref{Metaobjects and the Metaobject Protocol}.
2551 The aim of the MOP specification in this chapter is to specify all the
2552 customizable generic function invocations that can be made by the standard
2553 GOOPS syntax, procedures and methods, and to explain the protocol for
2554 customizing such invocations.
2556 A generic function invocation is customizable if the types of the arguments
2557 to which it is applied are not all determined by the lexical context in
2558 which the invocation appears. For example,
2562 the @code{(initialize @var{instance} @var{initargs})} invocation in the
2563 default @code{make-instance} method is customizable, because the type of the
2564 @code{@var{instance}} argument is determined by the class that was passed to
2565 @code{make-instance}.
2568 the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
2569 is not customizable, because all of its arguments have lexically determined
2573 When using this rule to decide whether a given generic function invocation
2574 is customizable, we ignore arguments that are expected to be handled in
2575 method definitions as a single ``rest'' list argument.
2577 For each customizable generic function invocation, the @dfn{invocation
2578 protocol} is explained by specifying
2582 what, conceptually, the applied method is intended to do
2585 what assumptions, if any, the caller makes about the applied method's side
2589 what the caller expects to get as the applied method's return value.
2593 * Class Definition::
2594 * Instance Creation::
2595 * Class Redefinition::
2596 * Method Definition::
2597 * Generic Function Invocation::
2600 @node Class Definition
2601 @section Class Definition
2603 @code{define-class} (syntax)
2607 @code{class} (syntax)
2611 @code{make-class} (procedure)
2615 @code{make @var{metaclass} @dots{}} (generic)
2617 @var{metaclass} is the metaclass of the class being defined, either
2618 taken from the @code{#:metaclass} class option or computed by
2619 @code{ensure-metaclass}. The applied method must create and return the
2620 fully initialized class metaobject for the new class definition.
2626 @code{class-redefinition @var{old-class} @var{new-class}} (generic)
2628 @code{define-class} calls @code{class-redefinition} if the variable
2629 specified by its first argument already held a GOOPS class definition.
2630 @var{old-class} and @var{new-class} are the old and new class metaobjects.
2631 The applied method should perform whatever is necessary to handle the
2632 redefinition, and should return the class metaobject that is to be bound
2633 to @code{define-class}'s variable. The default class redefinition
2634 protocol is described in @ref{Class Redefinition}.
2637 The @code{(make @var{metaclass} @dots{})} invocation above will create
2638 an class metaobject with metaclass @var{metaclass}. By default, this
2639 metaobject will be initialized by the @code{initialize} method that is
2640 specialized for instances of type @code{<class>}.
2642 @code{initialize <class> @var{initargs}} (method)
2646 @code{compute-cpl @var{class}} (generic)
2648 The applied method should compute and return the class precedence list
2649 for @var{class} as a list of class metaobjects. When @code{compute-cpl}
2650 is called, the following @var{class} metaobject slots have all been
2651 initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
2652 @code{direct-subclasses} (empty), @code{direct-methods}. The value
2653 returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
2656 @code{compute-slots @var{class}} (generic)
2658 The applied method should compute and return the slots (union of direct
2659 and inherited) for @var{class} as a list of slot definitions. When
2660 @code{compute-slots} is called, all the @var{class} metaobject slots
2661 mentioned for @code{compute-cpl} have been initialized, plus the
2662 following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
2663 The value returned by @code{compute-slots} will be stored in the
2667 @code{compute-get-n-set @var{class} @var{slot-def}} (generic)
2669 @code{initialize} calls @code{compute-get-n-set} for each slot computed
2670 by @code{compute-slots}. The applied method should compute and return a
2671 pair of closures that, respectively, get and set the value of the specified
2672 slot. The get closure should have arity 1 and expect a single argument
2673 that is the instance whose slot value is to be retrieved. The set closure
2674 should have arity 2 and expect two arguments, where the first argument is
2675 the instance whose slot value is to be set and the second argument is the
2676 new value for that slot. The closures should be returned in a two element
2677 list: @code{(list @var{get} @var{set})}.
2679 The closures returned by @code{compute-get-n-set} are stored as part of
2680 the value of the @var{class} metaobject's @code{getters-n-setters} slot.
2681 Specifically, the value of this slot is a list with the same number of
2682 elements as there are slots in the class, and each element looks either like
2685 @code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
2691 @code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
2694 Where the get and set closures are replaced by @var{index}, the slot is
2695 an instance slot and @var{index} is the slot's index in the underlying
2696 structure: GOOPS knows how to get and set the value of such slots and so
2697 does not need specially constructed get and set closures. Otherwise,
2698 @var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
2700 The structure of the @code{getters-n-setters} slot value is important when
2701 understanding the next customizable generic functions that @code{initialize}
2705 @code{compute-getter-method @var{class} @var{gns}} (generic)
2707 @code{initialize} calls @code{compute-getter-method} for each of the class's
2708 slots (as determined by @code{compute-slots}) that includes a
2709 @code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
2710 element of the @var{class} metaobject's @code{getters-n-setters} slot that
2711 specifies how the slot in question is referenced and set, as described
2712 above under @code{compute-get-n-set}. The applied method should create
2713 and return a method that is specialized for instances of type @var{class}
2714 and uses the get closure to retrieve the slot's value. [ *fixme Need
2715 to insert something here about checking that the value is not unbound. ]
2716 @code{initialize} uses @code{add-method!} to add the returned method to
2717 the generic function named by the slot definition's @code{#:getter} or
2718 @code{#:accessor} option.
2721 @code{compute-setter-method @var{class} @var{gns}} (generic)
2723 @code{compute-setter-method} is invoked with the same arguments as
2724 @code{compute-getter-method}, for each of the class's slots that includes
2725 a @code{#:setter} or @code{#:accessor} slot option. The applied method
2726 should create and return a method that is specialized for instances of
2727 type @var{class} and uses the set closure to set the slot's value.
2728 @code{initialize} then uses @code{add-method!} to add the returned method
2729 to the generic function named by the slot definition's @code{#:setter}
2730 or @code{#:accessor} option.
2733 @node Instance Creation
2734 @section Instance Creation
2736 @code{make <class> . @var{initargs}} (method)
2740 @code{allocate-instance @var{class} @var{initargs}} (generic)
2742 The applied @code{allocate-instance} method should allocate storage for
2743 a new instance of class @var{class} and return the uninitialized instance.
2746 @code{initialize @var{instance} @var{initargs}} (generic)
2748 @var{instance} is the uninitialized instance returned by
2749 @code{allocate-instance}. The applied method should initialize the new
2750 instance in whatever sense is appropriate for its class. The method's
2751 return value is ignored.
2754 @node Class Redefinition
2755 @section Class Redefinition
2757 The default @code{class-redefinition} method, specialized for classes
2758 with the default metaclass @code{<class>}, has the following internal
2761 @code{class-redefinition @var{(old <class>)} @var{(new <class>)}}
2766 @code{remove-class-accessors! @var{old}} (generic)
2769 @code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
2772 @code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
2775 This protocol cleans up things that the definition of the old class
2776 once changed and modifies things to work with the new class.
2778 The default @code{remove-class-accessors!} method removes the
2779 accessor methods of the old class from all classes which they
2782 The default @code{update-direct-method!} method substitutes the new
2783 class for the old in all methods specialized to the old class.
2785 The default @code{update-direct-subclass!} method invokes
2786 @code{class-redefinition} recursively to handle the redefinition of
2789 When a class is redefined, any existing instance of the redefined class
2790 will be modified for the new class definition before the next time that
2791 any of the instance's slot is referenced or set. GOOPS modifies each
2792 instance by calling the generic function @code{change-class}.
2794 The default @code{change-class} method copies slot values from the old
2795 to the modified instance, and initializes new slots, as described in
2796 @ref{Changing the Class of an Instance}. After doing so, it makes a
2797 generic function invocation that can be used to customize the instance
2800 @code{change-class @var{(old-instance <object>)} @var{(new <class>)}} (method)
2804 @code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
2806 @code{change-class} invokes @code{update-instance-for-different-class}
2807 as the last thing that it does before returning. The applied method can
2808 make any further adjustments to @var{new-instance} that are required to
2809 complete or modify the change of class. The return value from the
2810 applied method is ignored.
2812 The default @code{update-instance-for-different-class} method does
2816 @node Method Definition
2817 @section Method Definition
2819 @code{define-method} (syntax)
2823 @code{add-method! @var{target} @var{method}} (generic)
2825 @code{define-method} invokes the @code{add-method!} generic function to
2826 handle adding the new method to a variety of possible targets. GOOPS
2827 includes methods to handle @var{target} as
2831 a generic function (the most common case)
2837 a primitive generic (@pxref{Extending Guiles Primitives})
2840 By defining further methods for @code{add-method!}, you can
2841 theoretically handle adding methods to further types of target.
2844 @node Generic Function Invocation
2845 @section Generic Function Invocation
2847 [ *fixme* Description required here. ]
2849 @code{apply-generic}
2856 @code{compute-applicable-methods}
2859 @code{sort-applicable-methods}
2862 @code{apply-methods}
2865 @code{no-applicable-method}
2868 @code{sort-applicable-methods}
2872 @code{method-more-specific?}
2875 @code{apply-methods}
2886 @code{no-next-method}
2889 @node Tutorial, Concept Index, MOP Specification, Top
2891 @include goops-tutorial.texi
2893 @node Concept Index, Function and Variable Index, Tutorial, Top
2894 @unnumberedsec Concept Index
2898 @node Function and Variable Index, , Concept Index, Top
2899 @unnumberedsec Function and Variable Index