2 @c This is part of the GNU Guile Reference Manual.
3 @c Copyright (C) 2008, 2009
4 @c Free Software Foundation, Inc.
5 @c See the file guile.texi for copying conditions.
18 @goops{} is the object oriented extension to @guile{}. Its
19 implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
20 version 1.3 of Gregor Kiczales @cite{Tiny-Clos}. It is very close in
21 spirit to CLOS, the Common Lisp Object System (@cite{CLtL2}) but is
22 adapted for the Scheme language. While GOOPS is not compatible with any
23 of these systems, GOOPS contains a compatibility module which allows for
24 execution of STKlos programs.
26 Briefly stated, the @goops{} extension gives the user a full object
27 oriented system with multiple inheritance and generic functions with
28 multi-method dispatch. Furthermore, the implementation relies on a true
29 meta object protocol, in the spirit of the one defined for CLOS
30 (@cite{Gregor Kiczales: A Metaobject Protocol}).
40 @section Getting Started
45 Examples of some basic GOOPS functionality.
48 * User-defined types::
49 * Asking for the type of an object::
51 See further in the GOOPS tutorial available in this distribution in
52 info (goops.info) and texinfo format.
56 @subsection Running GOOPS
66 You should now be at the Guile prompt ("guile> ").
72 (use-modules (oop goops))
75 to load GOOPS. (If your system supports dynamic loading, you
76 should be able to do this not only from `guile-oops' but from an
77 arbitrary Guile interpreter.)
80 We're now ready to try some basic GOOPS functionality.
87 (define-method (+ (x <string>) (y <string>))
91 (+ "abc" "de") --> "abcde"
95 @node User-defined types
96 @subsection User-defined types
99 (define-class <2D-vector> ()
100 (x #:init-value 0 #:accessor x-component #:init-keyword #:x)
101 (y #:init-value 0 #:accessor y-component #:init-keyword #:y))
104 (use-modules (ice-9 format))
106 (define-method (write (obj <2D-vector>) port)
107 (display (format #f "<~S, ~S>" (x-component obj) (y-component obj))
110 (define v (make <2D-vector> #:x 3 #:y 4))
116 (define-method (+ (x <2D-vector>) (y <2D-vector>))
118 #:x (+ (x-component x) (x-component y))
119 #:y (+ (y-component x) (y-component y))))
125 @node Asking for the type of an object
129 (class-of v) --> #<<class> <2D-vector> 40241ac0>
130 <2D-vector> --> #<<class> <2D-vector> 40241ac0>
131 (class-of 1) --> #<<class> <integer> 401b2a98>
132 <integer> --> #<<class> <integer> 401b2a98>
134 (is-a? v <2D-vector>) --> #t
137 @node Reference Manual
138 @section Reference Manual
140 This chapter is the GOOPS reference manual. It aims to describe all the
141 syntax, procedures, options and associated concepts that a typical
142 application author would need to understand in order to use GOOPS
143 effectively in their application. It also describes what is meant by
144 the GOOPS ``metaobject protocol'' (aka ``MOP''), and indicates how
145 authors can use the metaobject protocol to customize the behaviour of
148 For a detailed specification of the GOOPS metaobject protocol, see
149 @ref{MOP Specification}.
152 * Introductory Remarks::
153 * Defining New Classes::
154 * Creating Instances::
156 * Creating Generic Functions::
157 * Adding Methods to Generic Functions::
158 * Invoking Generic Functions::
159 * Redefining a Class::
160 * Changing the Class of an Instance::
162 * Miscellaneous Functions::
165 @node Introductory Remarks
166 @subsection Introductory Remarks
168 GOOPS is an object-oriented programming system based on a ``metaobject
169 protocol'' derived from the ones used in CLOS (the Common Lisp Object
170 System), tiny-clos (a small Scheme implementation of a subset of CLOS
171 functionality) and STKlos.
173 GOOPS can be used by application authors at a basic level without any
174 need to understand what the metaobject protocol (aka ``MOP'') is and how
175 it works. On the other hand, the MOP underlies even the customizations
176 that application authors are likely to make use of very quickly --- such
177 as defining an @code{initialize} method to customize the initialization
178 of instances of an application-defined class --- and an understanding of
179 the MOP makes it much easier to explain such customizations in a precise
180 way. And in the long run, understanding the MOP is the key both to
181 understanding GOOPS at a deeper level and to taking full advantage of
182 GOOPS' power, by customizing the behaviour of GOOPS itself.
184 Each of the following sections of the reference manual is arranged
185 such that the most basic usage is introduced first, and then subsequent
186 subsubsections discuss the related internal functions and metaobject
187 protocols, finishing with a description of how to customize that area of
190 These introductory remarks continue with a few words about metaobjects
191 and the MOP. Readers who do not want to be bothered yet with the MOP
192 and customization could safely skip this subsubsection on a first reading,
193 and should correspondingly skip subsequent subsubsections that are
194 concerned with internals and customization.
196 In general, this reference manual assumes familiarity with standard
197 object oriented concepts and terminology. However, some of the terms
198 used in GOOPS are less well known, so the Terminology subsubsection
199 provides definitions for these terms.
202 * Metaobjects and the Metaobject Protocol::
206 @node Metaobjects and the Metaobject Protocol
207 @subsubsection Metaobjects and the Metaobject Protocol
209 The conceptual building blocks of GOOPS are classes, slot definitions,
210 instances, generic functions and methods. A class is a grouping of
211 inheritance relations and slot definitions. An instance is an object
212 with slots that are allocated following the rules implied by its class's
213 superclasses and slot definitions. A generic function is a collection
214 of methods and rules for determining which of those methods to apply
215 when the generic function is invoked. A method is a procedure and a set
216 of specializers that specify the type of arguments to which the
217 procedure is applicable.
219 Of these entities, GOOPS represents classes, generic functions and
220 methods as ``metaobjects''. In other words, the values in a GOOPS
221 program that describe classes, generic functions and methods, are
222 themselves instances (or ``objects'') of special GOOPS classes that
223 encapsulate the behaviour, respectively, of classes, generic functions,
226 (The other two entities are slot definitions and instances. Slot
227 definitions are not strictly instances, but every slot definition is
228 associated with a GOOPS class that specifies the behaviour of the slot
229 as regards accessibility and protection from garbage collection.
230 Instances are of course objects in the usual sense, and there is no
231 benefit from thinking of them as metaobjects.)
233 The ``metaobject protocol'' (aka ``MOP'') is the specification of the
234 generic functions which determine the behaviour of these metaobjects and
235 the circumstances in which these generic functions are invoked.
237 For a concrete example of what this means, consider how GOOPS calculates
238 the set of slots for a class that is being defined using
239 @code{define-class}. The desired set of slots is the union of the new
240 class's direct slots and the slots of all its superclasses. But
241 @code{define-class} itself does not perform this calculation. Instead,
242 there is a method of the @code{initialize} generic function that is
243 specialized for instances of type @code{<class>}, and it is this method
244 that performs the slot calculation.
246 @code{initialize} is a generic function which GOOPS calls whenever a new
247 instance is created, immediately after allocating memory for a new
248 instance, in order to initialize the new instance's slots. The sequence
249 of steps is as follows.
253 @code{define-class} uses @code{make} to make a new instance of the
254 @code{<class>}, passing as initialization arguments the superclasses,
255 slot definitions and class options that were specified in the
256 @code{define-class} form.
259 @code{make} allocates memory for the new instance, and then invokes the
260 @code{initialize} generic function to initialize the new instance's
264 The @code{initialize} generic function applies the method that is
265 specialized for instances of type @code{<class>}, and this method
266 performs the slot calculation.
269 In other words, rather than being hardcoded in @code{define-class}, the
270 behaviour of class definition is encapsulated by generic function
271 methods that are specialized for the class @code{<class>}.
273 It is possible to create a new class that inherits from @code{<class>},
274 which is called a ``metaclass'', and to write a new @code{initialize}
275 method that is specialized for instances of the new metaclass. Then, if
276 the @code{define-class} form includes a @code{#:metaclass} class option
277 whose value is the new metaclass, the class that is defined by the
278 @code{define-class} form will be an instance of the new metaclass rather
279 than of the default @code{<class>}, and will be defined in accordance
280 with the new @code{initialize} method. Thus the default slot
281 calculation, as well as any other aspect of the new class's relationship
282 with its superclasses, can be modified or overridden.
284 In a similar way, the behaviour of generic functions can be modified or
285 overridden by creating a new class that inherits from the standard
286 generic function class @code{<generic>}, writing appropriate methods
287 that are specialized to the new class, and creating new generic
288 functions that are instances of the new class.
290 The same is true for method metaobjects. And the same basic mechanism
291 allows the application class author to write an @code{initialize} method
292 that is specialized to their application class, to initialize instances
295 Such is the power of the MOP. Note that @code{initialize} is just one
296 of a large number of generic functions that can be customized to modify
297 the behaviour of application objects and classes and of GOOPS itself.
298 Each subsequent section of the reference manual covers a particular area
299 of GOOPS functionality, and describes the generic functions that are
300 relevant for customization of that area.
302 We conclude this subsubsection by emphasizing a point that may seem
303 obvious, but contrasts with the corresponding situation in some other
304 MOP implementations, such as CLOS. The point is simply that an
305 identifier which represents a GOOPS class or generic function is a
306 variable with a first-class value, the value being an instance of class
307 @code{<class>} or @code{<generic>}. (In CLOS, on the other hand, a
308 class identifier is a symbol that indexes the corresponding class
309 metaobject in a separate namespace for classes.) This is, of course,
310 simply an extension of the tendency in Scheme to avoid the unnecessary
311 use of, on the one hand, syntactic forms that require unevaluated
312 arguments and, on the other, separate identifier namespaces (e.g. for
313 class names), but it is worth noting that GOOPS conforms fully to this
317 @subsubsection Terminology
319 It is assumed that the reader is already familiar with standard object
320 orientation concepts such as classes, objects/instances,
321 inheritance/subclassing, generic functions and methods, encapsulation
324 This section explains some of the less well known concepts and
325 terminology that GOOPS uses, which are assumed by the following sections
326 of the reference manual.
328 @subsubheading Metaclass
330 A @dfn{metaclass} is the class of an object which represents a GOOPS
331 class. Put more succinctly, a metaclass is a class's class.
333 Most GOOPS classes have the metaclass @code{<class>} and, by default,
334 any new class that is created using @code{define-class} has the
335 metaclass @code{<class>}.
337 But what does this really mean? To find out, let's look in more detail
338 at what happens when a new class is created using @code{define-class}:
341 (define-class <my-class> (<object>) . slots)
344 GOOPS actually expands the @code{define-class} form to something like
348 (define <my-class> (class (<object>) . slots))
355 (make <class> #:supers (list <object>) #:slots slots))
358 In other words, the value of @code{<my-class>} is in fact an instance of
359 the class @code{<class>} with slot values specifying the superclasses
360 and slot definitions for the class @code{<my-class>}. (@code{#:supers}
361 and @code{#:slots} are initialization keywords for the @code{dsupers}
362 and @code{dslots} slots of the @code{<class>} class.)
364 In order to take advantage of the full power of the GOOPS metaobject
365 protocol (@pxref{MOP Specification}), it is sometimes desirable to
366 create a new class with a metaclass other than the default
367 @code{<class>}. This is done by writing:
370 (define-class <my-class2> (<object>)
372 #:metaclass <my-metaclass>)
375 GOOPS expands this to something like:
379 (make <my-metaclass> #:supers (list <object>) #:slots slots))
382 In this case, the value of @code{<my-class2>} is an instance of the more
383 specialized class @code{<my-metaclass>}. Note that
384 @code{<my-metaclass>} itself must previously have been defined as a
385 subclass of @code{<class>}. For a full discussion of when and how it is
386 useful to define new metaclasses, see @ref{MOP Specification}.
388 Now let's make an instance of @code{<my-class2>}:
391 (define my-object (make <my-class2> ...))
394 All of the following statements are correct expressions of the
395 relationships between @code{my-object}, @code{<my-class2>},
396 @code{<my-metaclass>} and @code{<class>}.
400 @code{my-object} is an instance of the class @code{<my-class2>}.
403 @code{<my-class2>} is an instance of the class @code{<my-metaclass>}.
406 @code{<my-metaclass>} is an instance of the class @code{<class>}.
409 The class of @code{my-object} is @code{<my-class2>}.
412 The metaclass of @code{my-object} is @code{<my-metaclass>}.
415 The class of @code{<my-class2>} is @code{<my-metaclass>}.
418 The metaclass of @code{<my-class2>} is @code{<class>}.
421 The class of @code{<my-metaclass>} is @code{<class>}.
424 The metaclass of @code{<my-metaclass>} is @code{<class>}.
427 @code{<my-class2>} is not a metaclass, since it is does not inherit from
431 @code{<my-metaclass>} is a metaclass, since it inherits from
435 @subsubheading Class Precedence List
437 The @dfn{class precedence list} of a class is the list of all direct and
438 indirect superclasses of that class, including the class itself.
440 In the absence of multiple inheritance, the class precedence list is
441 ordered straightforwardly, beginning with the class itself and ending
444 For example, given this inheritance hierarchy:
447 (define-class <invertebrate> (<object>) @dots{})
448 (define-class <echinoderm> (<invertebrate>) @dots{})
449 (define-class <starfish> (<echinoderm>) @dots{})
452 the class precedence list of <starfish> would be
455 (<starfish> <echinoderm> <invertebrate> <object> <top>)
458 With multiple inheritance, the algorithm is a little more complicated.
459 A full description is provided by the GOOPS Tutorial: see @ref{Class
462 ``Class precedence list'' is often abbreviated, in documentation and
463 Scheme variable names, to @dfn{cpl}.
465 @subsubheading Accessor
467 An @dfn{accessor} is a generic function with both reference and setter
471 (define-accessor perimeter)
474 Reference methods for an accessor are defined in the same way as generic
478 (define-method (perimeter (s <square>))
479 (* 4 (side-length s)))
482 Setter methods for an accessor are defined by specifying ``(setter
483 <accessor-name>)'' as the first parameter of the @code{define-method}
487 (define-method ((setter perimeter) (s <square>) (n <number>))
488 (set! (side-length s) (/ n 4)))
491 Once an appropriate setter method has been defined in this way, it can
492 be invoked using the generalized @code{set!} syntax, as in:
495 (set! (perimeter s1) 18.3)
498 @node Defining New Classes
499 @subsection Defining New Classes
501 [ *fixme* Somewhere in this manual there needs to be an introductory
502 discussion about GOOPS classes, generic functions and methods, covering
506 how classes encapsulate related items of data in @dfn{slots}
509 why it is that, unlike in C++ and Java, a class does not encapsulate the
510 methods that act upon the class (at least not in the C++/Java sense)
513 how generic functions provide a more general solution that provides for
514 dispatch on all argument types, and avoids idiosyncracies like C++'s
518 how encapsulation in the sense of data- and code-hiding, or of
519 distinguishing interface from implementation, is treated in Guile as an
520 orthogonal concept to object orientation, and is the responsibility of
524 Some of this is covered in the Tutorial chapter, in @ref{Generic
525 functions and methods} - perhaps the best solution would be to expand
526 the discussion there. ]
529 * Basic Class Definition::
532 * Class Definition Internals::
533 * Customizing Class Definition::
534 * STKlos Compatibility::
537 @node Basic Class Definition
538 @subsubsection Basic Class Definition
540 New classes are defined using the @code{define-class} syntax, with
541 arguments that specify the classes that the new class should inherit
542 from, the direct slots of the new class, and any required class options.
544 @deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
545 Define a class called @var{name} that inherits from @var{super}s, with
546 direct slots defined by @var{slot-definition}s and class options
547 @var{options}. The newly created class is bound to the variable name
548 @var{name} in the current environment.
550 Each @var{slot-definition} is either a symbol that names the slot or a
554 (@var{slot-name-symbol} . @var{slot-options})
557 where @var{slot-name-symbol} is a symbol and @var{slot-options} is a
558 list with an even number of elements. The even-numbered elements of
559 @var{slot-options} (counting from zero) are slot option keywords; the
560 odd-numbered elements are the corresponding values for those keywords.
562 @var{options} is a similarly structured list containing class option
563 keywords and corresponding values.
566 The standard GOOPS class and slot options are described in the following
567 subsubsections: see @ref{Class Options} and @ref{Slot Options}.
569 Example 1. Define a class that combines two pre-existing classes by
570 inheritance but adds no new slots.
573 (define-class <combined> (<tree> <bicycle>))
576 Example 2. Define a @code{regular-polygon} class with slots for side
577 length and number of sides that have default values and can be accessed
578 via the generic functions @code{side-length} and @code{num-sides}.
581 (define-class <regular-polygon> ()
582 (sl #:init-value 1 #:accessor side-length)
583 (ns #:init-value 5 #:accessor num-sides))
586 Example 3. Define a class whose behavior (and that of its instances) is
587 customized via an application-defined metaclass.
590 (define-class <tcpip-fsm> ()
591 (s #:init-value #f #:accessor state)
593 #:metaclass <finite-state-class>)
597 @subsubsection Class Options
599 @deffn {class option} #:metaclass metaclass
600 The @code{#:metaclass} class option specifies the metaclass of the class
601 being defined. @var{metaclass} must be a class that inherits from
602 @code{<class>}. For an introduction to the use of metaclasses, see
603 @ref{Metaobjects and the Metaobject Protocol} and @ref{Terminology}.
605 If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
606 metaclass for the new class by calling @code{ensure-metaclass}
607 (@pxref{Class Definition Internals,, ensure-metaclass}).
610 @deffn {class option} #:name name
611 The @code{#:name} class option specifies the new class's name. This
612 name is used to identify the class whenever related objects - the class
613 itself, its instances and its subclasses - are printed.
615 If the @code{#:name} option is absent, GOOPS uses the first argument to
616 @code{define-class} as the class name.
619 @deffn {class option} #:environment environment
620 *fixme* Not sure about this one, but I think that the
621 @code{#:environment} option specifies the environment in which the
622 class's getters and setters are computed and evaluated.
624 If the @code{#:environment} option is not specified, the class's
625 environment defaults to the top-level environment in which the
626 @code{define-class} form appears.
630 @subsubsection Slot Options
632 @deffn {slot option} #:allocation allocation
633 The @code{#:allocation} option tells GOOPS how to allocate storage for
634 the slot. Possible values for @var{allocation} are
637 @item @code{#:instance}
639 Indicates that GOOPS should create separate storage for this slot in
640 each new instance of the containing class (and its subclasses).
644 Indicates that GOOPS should create storage for this slot that is shared
645 by all instances of the containing class (and its subclasses). In other
646 words, a slot in class @var{C} with allocation @code{#:class} is shared
647 by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
649 @item @code{#:each-subclass}
651 Indicates that GOOPS should create storage for this slot that is shared
652 by all @emph{direct} instances of the containing class, and that
653 whenever a subclass of the containing class is defined, GOOPS should
654 create a new storage for the slot that is shared by all @emph{direct}
655 instances of the subclass. In other words, a slot with allocation
656 @code{#:each-subclass} is shared by all instances with the same
659 @item @code{#:virtual}
661 Indicates that GOOPS should not allocate storage for this slot. The
662 slot definition must also include the @code{#:slot-ref} and
663 @code{#:slot-set!} options to specify how to reference and set the value
667 The default value is @code{#:instance}.
669 Slot allocation options are processed when defining a new class by the
670 generic function @code{compute-get-n-set}, which is specialized by the
671 class's metaclass. Hence new types of slot allocation can be
672 implemented by defining a new metaclass and a method for
673 @code{compute-get-n-set} that is specialized for the new metaclass. For
674 an example of how to do this, see @ref{Customizing Class Definition}.
677 @deffn {slot option} #:slot-ref getter
678 @deffnx {slot option} #:slot-set! setter
679 The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
680 if the slot allocation is @code{#:virtual}, and are ignored otherwise.
682 @var{getter} should be a closure taking a single @var{instance} parameter
683 that returns the current slot value. @var{setter} should be a closure
684 taking two parameters - @var{instance} and @var{new-val} - that sets the
685 slot value to @var{new-val}.
688 @deffn {slot option} #:getter getter
689 @deffnx {slot option} #:setter setter
690 @deffnx {slot option} #:accessor accessor
691 These options, if present, tell GOOPS to create generic function and
692 method definitions that can be used to get and set the slot value more
693 conveniently than by using @code{slot-ref} and @code{slot-set!}.
695 @var{getter} specifies a generic function to which GOOPS will add a
696 method for getting the slot value. @var{setter} specifies a generic
697 function to which GOOPS will add a method for setting the slot value.
698 @var{accessor} specifies an accessor to which GOOPS will add methods for
699 both getting and setting the slot value.
701 So if a class includes a slot definition like this:
704 (c #:getter get-count #:setter set-count #:accessor count)
707 GOOPS defines generic function methods such that the slot value can be
708 referenced using either the getter or the accessor -
711 (let ((current-count (get-count obj))) @dots{})
712 (let ((current-count (count obj))) @dots{})
715 - and set using either the setter or the accessor -
718 (set-count obj (+ 1 current-count))
719 (set! (count obj) (+ 1 current-count))
726 with an accessor, the slot value is set using the generalized
730 in practice, it is unusual for a slot to use all three of these options:
731 read-only, write-only and read-write slots would typically use only
732 @code{#:getter}, @code{#:setter} and @code{#:accessor} options
736 If the specified names are already bound in the top-level environment to
737 values that cannot be upgraded to generic functions, those values are
738 overwritten during evaluation of the @code{define-class} that contains
739 the slot definition. For details, see @ref{Generic Function Internals,,
743 @deffn {slot option} #:init-value init-value
744 @deffnx {slot option} #:init-form init-form
745 @deffnx {slot option} #:init-thunk init-thunk
746 @deffnx {slot option} #:init-keyword init-keyword
747 These options provide various ways to specify how to initialize the
748 slot's value at instance creation time. @var{init-value} is a fixed
749 value (shared across all new instances of the class).
750 @var{init-thunk} is a procedure of no arguments that is called
751 when a new instance is created and should return the desired initial
752 slot value. @var{init-form} is an unevaluated expression that gets
753 evaluated when a new instance is created and should return the desired
754 initial slot value. @var{init-keyword} is a keyword that can be used
755 to pass an initial slot value to @code{make} when creating a new
758 Note that, since an @code{init-value} value is shared across all
759 instances of a class, you should only use it when the initial value is
760 an immutable value, like a constant. If you want to initialize a slot
761 with a fresh, independently mutable value, you should use
762 @code{init-thunk} or @code{init-form} instead. Consider the following
766 (define-class <chbouib> ()
767 (hashtab #:init-value (make-hash-table)))
771 Here only one hash table is created and all instances of
772 @code{<chbouib>} have their @code{hashtab} slot refer to it. In order
773 to have each instance of @code{<chbouib>} refer to a new hash table, you
774 should instead write:
777 (define-class <chbouib> ()
778 (hashtab #:init-thunk make-hash-table))
785 (define-class <chbouib> ()
786 (hashtab #:init-form (make-hash-table)))
789 If more than one of these options is specified for the same slot, the
790 order of precedence, highest first is
794 @code{#:init-keyword}, if @var{init-keyword} is present in the options
795 passed to @code{make}
798 @code{#:init-thunk}, @code{#:init-form} or @code{#:init-value}.
801 If the slot definition contains more than one initialization option of
802 the same precedence, the later ones are ignored. If a slot is not
803 initialized at all, its value is unbound.
805 In general, slots that are shared between more than one instance are
806 only initialized at new instance creation time if the slot value is
807 unbound at that time. However, if the new instance creation specifies
808 a valid init keyword and value for a shared slot, the slot is
809 re-initialized regardless of its previous value.
811 Note, however, that the power of GOOPS' metaobject protocol means that
812 everything written here may be customized or overridden for particular
813 classes! The slot initializations described here are performed by the least
814 specialized method of the generic function @code{initialize}, whose
818 (define-method (initialize (object <object>) initargs) ...)
821 The initialization of instances of any given class can be customized by
822 defining a @code{initialize} method that is specialized for that class,
823 and the author of the specialized method may decide to call
824 @code{next-method} - which will result in a call to the next less
825 specialized @code{initialize} method - at any point within the
826 specialized code, or maybe not at all. In general, therefore, the
827 initialization mechanisms described here may be modified or overridden by
828 more specialized code, or may not be supported at all for particular
832 @node Class Definition Internals
833 @subsubsection Class Definition Internals
835 Implementation notes: @code{define-class} expands to an expression which
839 checks that it is being evaluated only at top level
842 defines any accessors that are implied by the @var{slot-definition}s
845 uses @code{class} to create the new class (@pxref{Class Definition
849 checks for a previous class definition for @var{name} and, if found,
850 handles the redefinition by invoking @code{class-redefinition}
851 (@pxref{Redefining a Class}).
854 @deffn syntax class name (super @dots{}) slot-definition @dots{} . options
855 Return a newly created class that inherits from @var{super}s, with
856 direct slots defined by @var{slot-definition}s and class options
857 @var{options}. For the format of @var{slot-definition}s and
858 @var{options}, see @ref{Basic Class Definition,, define-class}.
861 Implementation notes: @code{class} expands to an expression which
865 processes the class and slot definition options to check that they are
866 well-formed, to convert the @code{#:init-form} option to an
867 @code{#:init-thunk} option, to supply a default environment parameter
868 (the current top-level environment) and to evaluate all the bits that
872 calls @code{make-class} to create the class with the processed and
873 evaluated parameters.
876 @deffn procedure make-class supers slots . options
877 Return a newly created class that inherits from @var{supers}, with
878 direct slots defined by @var{slots} and class options @var{options}.
879 For the format of @var{slots} and @var{options}, see @ref{Basic Class
880 Definition,, define-class}, except note that for @code{make-class},
881 @var{slots} and @var{options} are separate list parameters: @var{slots}
882 here is a list of slot definitions.
885 Implementation notes: @code{make-class}
889 adds @code{<object>} to the @var{supers} list if @var{supers} is empty
890 or if none of the classes in @var{supers} have @code{<object>} in their
891 class precedence list
894 defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
895 options, if they are not specified by @var{options}, to the current
896 top-level environment, the unbound value, and @code{(ensure-metaclass
897 @var{supers})} respectively (@pxref{Class Definition Internals,,
901 checks for duplicate classes in @var{supers} and duplicate slot names in
902 @var{slots}, and signals an error if there are any duplicates
905 calls @code{make}, passing the metaclass as the first parameter and all
906 other parameters as option keywords with values.
909 @deffn procedure ensure-metaclass supers env
910 Return a metaclass suitable for a class that inherits from the list of
911 classes in @var{supers}. The returned metaclass is the union by
912 inheritance of the metaclasses of the classes in @var{supers}.
914 In the simplest case, where all the @var{supers} are straightforward
915 classes with metaclass @code{<class>}, the returned metaclass is just
918 For a more complex example, suppose that @var{supers} contained one
919 class with metaclass @code{<operator-class>} and one with metaclass
920 @code{<foreign-object-class>}. Then the returned metaclass would be a
921 class that inherits from both @code{<operator-class>} and
922 @code{<foreign-object-class>}.
924 If @var{supers} is the empty list, @code{ensure-metaclass} returns the
925 default GOOPS metaclass @code{<class>}.
927 GOOPS keeps a list of the metaclasses created by
928 @code{ensure-metaclass}, so that each required type of metaclass only
929 has to be created once.
931 The @code{env} parameter is ignored.
934 @deffn procedure ensure-metaclass-with-supers meta-supers
935 @code{ensure-metaclass-with-supers} is an internal procedure used by
936 @code{ensure-metaclass} (@pxref{Class Definition Internals,,
937 ensure-metaclass}). It returns a metaclass that is the union by
938 inheritance of the metaclasses in @var{meta-supers}.
941 The internals of @code{make}, which is ultimately used to create the new
942 class object, are described in @ref{Customizing Instance Creation},
943 which covers the creation and initialization of instances in general.
945 @node Customizing Class Definition
946 @subsubsection Customizing Class Definition
948 During the initialization of a new class, GOOPS calls a number of generic
949 functions with the newly allocated class instance as the first
950 argument. Specifically, GOOPS calls the generic function
954 (initialize @var{class} @dots{})
957 where @var{class} is the newly allocated class instance, and the default
958 @code{initialize} method for arguments of type @code{<class>} calls the
963 (compute-cpl @var{class})
966 (compute-slots @var{class})
969 (compute-get-n-set @var{class} @var{slot-def}), for each of the slot
970 definitions returned by @code{compute-slots}
973 (compute-getter-method @var{class} @var{slot-def}), for each of the
974 slot definitions returned by @code{compute-slots} that includes a
975 @code{#:getter} or @code{#:accessor} slot option
978 (compute-setter-method @var{class} @var{slot-def}), for each of the
979 slot definitions returned by @code{compute-slots} that includes a
980 @code{#:setter} or @code{#:accessor} slot option.
983 If the metaclass of the new class is something more specialized than the
984 default @code{<class>}, then the type of @var{class} in the calls above
985 is more specialized than @code{<class>}, and hence it becomes possible
986 to define generic function methods, specialized for the new class's
987 metaclass, that can modify or override the default behaviour of
988 @code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
990 @code{compute-cpl} computes the class precedence list (``CPL'') for the
991 new class (@pxref{Class precedence list}), and returns it as a list of
992 class objects. The CPL is important because it defines a superclass
993 ordering that is used, when a generic function is invoked upon an
994 instance of the class, to decide which of the available generic function
995 methods is the most specific. Hence @code{compute-cpl} could be
996 customized in order to modify the CPL ordering algorithm for all classes
997 with a special metaclass.
999 The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
1000 procedure, which is in turn called by the default @code{compute-cpl}
1003 @deffn procedure compute-std-cpl class
1004 Compute and return the class precedence list for @var{class} according
1005 to the algorithm described in @ref{Class precedence list}.
1008 @code{compute-slots} computes and returns a list of all slot definitions
1009 for the new class. By default, this list includes the direct slot
1010 definitions from the @code{define-class} form, plus the slot definitions
1011 that are inherited from the new class's superclasses. The default
1012 @code{compute-slots} method uses the CPL computed by @code{compute-cpl}
1013 to calculate this union of slot definitions, with the rule that slots
1014 inherited from superclasses are shadowed by direct slots with the same
1015 name. One possible reason for customizing @code{compute-slots} would be
1016 to implement an alternative resolution strategy for slot name conflicts.
1018 @code{compute-get-n-set} computes the low-level closures that will be
1019 used to get and set the value of a particular slot, and returns them in
1020 a list with two elements.
1022 The closures returned depend on how storage for that slot is allocated.
1023 The standard @code{compute-get-n-set} method, specialized for classes of
1024 type @code{<class>}, handles the standard GOOPS values for the
1025 @code{#:allocation} slot option (@pxref{Slot Options,, allocation}). By
1026 defining a new @code{compute-get-n-set} method for a more specialized
1027 metaclass, it is possible to support new types of slot allocation.
1029 Suppose you wanted to create a large number of instances of some class
1030 with a slot that should be shared between some but not all instances of
1031 that class - say every 10 instances should share the same slot storage.
1032 The following example shows how to implement and use a new type of slot
1033 allocation to do this.
1036 (define-class <batched-allocation-metaclass> (<class>))
1038 (let ((batch-allocation-count 0)
1039 (batch-get-n-set #f))
1040 (define-method (compute-get-n-set
1041 (class <batched-allocation-metaclass>) s)
1042 (case (slot-definition-allocation s)
1044 ;; If we've already used the same slot storage for 10 instances,
1046 (if (= batch-allocation-count 10)
1048 (set! batch-allocation-count 0)
1049 (set! batch-get-n-set #f)))
1050 ;; If we don't have a current pair of get and set closures,
1051 ;; create one. make-closure-variable returns a pair of closures
1052 ;; around a single Scheme variable - see goops.scm for details.
1054 (set! batch-get-n-set (make-closure-variable)))
1055 ;; Increment the batch allocation count.
1056 (set! batch-allocation-count (+ batch-allocation-count 1))
1059 ;; Call next-method to handle standard allocation types.
1060 (else (next-method)))))
1062 (define-class <class-using-batched-slot> ()
1064 (c #:allocation #:batched)
1066 #:metaclass <batched-allocation-metaclass>)
1069 The usage of @code{compute-getter-method} and @code{compute-setter-method}
1070 is described in @ref{MOP Specification}.
1072 @code{compute-cpl} and @code{compute-get-n-set} are called by the
1073 standard @code{initialize} method for classes whose metaclass is
1074 @code{<class>}. But @code{initialize} itself can also be modified, by
1075 defining an @code{initialize} method specialized to the new class's
1076 metaclass. Such a method could complete override the standard
1077 behaviour, by not calling @code{(next-method)} at all, but more
1078 typically it would perform additional class initialization steps before
1079 and/or after calling @code{(next-method)} for the standard behaviour.
1081 @node STKlos Compatibility
1082 @subsubsection STKlos Compatibility
1084 If the STKlos compatibility module is loaded, @code{define-class} is
1085 overwritten by a STKlos-specific definition; the standard GOOPS
1086 definition of @code{define-class} remains available in
1087 @code{standard-define-class}.
1089 @deffn syntax standard-define-class name (super @dots{}) slot-definition @dots{} . options
1090 @code{standard-define-class} is equivalent to the standard GOOPS
1091 @code{define-class}.
1094 @node Creating Instances
1095 @subsection Creating Instances
1098 * Basic Instance Creation::
1099 * Customizing Instance Creation::
1102 @node Basic Instance Creation
1103 @subsubsection Basic Instance Creation
1105 To create a new instance of any GOOPS class, use the generic function
1106 @code{make} or @code{make-instance}, passing the required class and any
1107 appropriate instance initialization arguments as keyword and value
1108 pairs. Note that @code{make} and @code{make-instances} are aliases for
1109 each other - their behaviour is identical.
1112 @deffnx method make (class <class>) . initargs
1113 Create and return a new instance of class @var{class}, initialized using
1116 In theory, @var{initargs} can have any structure that is understood by
1117 whatever methods get applied when the @code{initialize} generic function
1118 is applied to the newly allocated instance.
1120 In practice, specialized @code{initialize} methods would normally call
1121 @code{(next-method)}, and so eventually the standard GOOPS
1122 @code{initialize} methods are applied. These methods expect
1123 @var{initargs} to be a list with an even number of elements, where
1124 even-numbered elements (counting from zero) are keywords and
1125 odd-numbered elements are the corresponding values.
1127 GOOPS processes initialization argument keywords automatically for slots
1128 whose definition includes the @code{#:init-keyword} option (@pxref{Slot
1129 Options,, init-keyword}). Other keyword value pairs can only be
1130 processed by an @code{initialize} method that is specialized for the new
1131 instance's class. Any unprocessed keyword value pairs are ignored.
1134 @deffn generic make-instance
1135 @deffnx method make-instance (class <class>) . initargs
1136 @code{make-instance} is an alias for @code{make}.
1139 @node Customizing Instance Creation
1140 @subsubsection Customizing Instance Creation
1142 @code{make} itself is a generic function. Hence the @code{make}
1143 invocation itself can be customized in the case where the new instance's
1144 metaclass is more specialized than the default @code{<class>}, by
1145 defining a @code{make} method that is specialized to that metaclass.
1147 Normally, however, the method for classes with metaclass @code{<class>}
1148 will be applied. This method calls two generic functions:
1152 (allocate-instance @var{class} . @var{initargs})
1155 (initialize @var{instance} . @var{initargs})
1158 @code{allocate-instance} allocates storage for and returns the new
1159 instance, uninitialized. You might customize @code{allocate-instance},
1160 for example, if you wanted to provide a GOOPS wrapper around some other
1161 object programming system.
1163 To do this, you would create a specialized metaclass, which would act as
1164 the metaclass for all classes and instances from the other system. Then
1165 define an @code{allocate-instance} method, specialized to that
1166 metaclass, which calls a Guile primitive C function, which in turn
1167 allocates the new instance using the interface of the other object
1170 In this case, for a complete system, you would also need to customize a
1171 number of other generic functions like @code{make} and
1172 @code{initialize}, so that GOOPS knows how to make classes from the
1173 other system, access instance slots, and so on.
1175 @code{initialize} initializes the instance that is returned by
1176 @code{allocate-instance}. The standard GOOPS methods perform
1177 initializations appropriate to the instance class.
1181 At the least specialized level, the method for instances of type
1182 @code{<object>} performs internal GOOPS instance initialization, and
1183 initializes the instance's slots according to the slot definitions and
1184 any slot initialization keywords that appear in @var{initargs}.
1187 The method for instances of type @code{<class>} calls
1188 @code{(next-method)}, then performs the class initializations described
1189 in @ref{Customizing Class Definition}.
1192 and so on for generic functions, method, operator classes @dots{}
1195 Similarly, you can customize the initialization of instances of any
1196 application-defined class by defining an @code{initialize} method
1197 specialized to that class.
1199 Imagine a class whose instances' slots need to be initialized at
1200 instance creation time by querying a database. Although it might be
1201 possible to achieve this a combination of @code{#:init-thunk} keywords
1202 and closures in the slot definitions, it is neater to write an
1203 @code{initialize} method for the class that queries the database once
1204 and initializes all the dependent slot values according to the results.
1206 @node Accessing Slots
1207 @subsection Accessing Slots
1209 The definition of a slot contains at the very least a slot name, and may
1210 also contain various slot options, including getter, setter and/or
1211 accessor functions for the slot.
1213 It is always possible to access slots by name, using the various
1214 ``slot-ref'' and ``slot-set!'' procedures described in the following
1215 subsubsections. For example,
1218 (define-class <my-class> () ;; Define a class with slots
1219 (count #:init-value 0) ;; named "count" and "cache".
1220 (cache #:init-value '())
1223 (define inst (make <my-class>)) ;; Make an instance of this class.
1225 (slot-set! inst 'count 5) ;; Set the value of the "count"
1228 (slot-set! inst 'cache ;; Modify the value of the
1229 (cons (cons "^it" "It") ;; "cache" slot.
1230 (slot-ref inst 'cache)))
1233 If a slot definition includes a getter, setter or accessor function,
1234 these can be used instead of @code{slot-ref} and @code{slot-set!} to
1238 (define-class <adv-class> () ;; Define a new class whose slots
1239 (count #:setter set-count) ;; use a getter, a setter and
1240 (cache #:accessor cache) ;; an accessor.
1241 (csize #:getter cache-size)
1244 (define inst (make <adv-class>)) ;; Make an instance of this class.
1246 (set-count inst 5) ;; Set the value of the "count"
1249 (set! (cache inst) ;; Modify the value of the
1250 (cons (cons "^it" "It") ;; "cache" slot.
1253 (let ((size (cache-size inst))) ;; Get the value of the "csize"
1257 Whichever of these methods is used to access slots, GOOPS always calls
1258 the low-level @dfn{getter} and @dfn{setter} closures for the slot to get
1259 and set its value. These closures make sure that the slot behaves
1260 according to the @code{#:allocation} type that was specified in the slot
1261 definition (@pxref{Slot Options,, allocation}). (For more about these
1262 closures, see @ref{Customizing Class Definition,, compute-get-n-set}.)
1267 * Handling Slot Access Errors::
1270 @node Instance Slots
1271 @subsubsection Instance Slots
1273 Any slot, regardless of its allocation, can be queried, referenced and
1274 set using the following four primitive procedures.
1276 @deffn {primitive procedure} slot-exists? obj slot-name
1277 Return @code{#t} if @var{obj} has a slot with name @var{slot-name},
1278 otherwise @code{#f}.
1281 @deffn {primitive procedure} slot-bound? obj slot-name
1282 Return @code{#t} if the slot named @var{slot-name} in @var{obj} has a
1283 value, otherwise @code{#f}.
1285 @code{slot-bound?} calls the generic function @code{slot-missing} if
1286 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1287 Slot Access Errors, slot-missing}).
1290 @deffn {primitive procedure} slot-ref obj slot-name
1291 Return the value of the slot named @var{slot-name} in @var{obj}.
1293 @code{slot-ref} calls the generic function @code{slot-missing} if
1294 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1295 Slot Access Errors, slot-missing}).
1297 @code{slot-ref} calls the generic function @code{slot-unbound} if the
1298 named slot in @var{obj} does not have a value (@pxref{Handling Slot
1299 Access Errors, slot-unbound}).
1302 @deffn {primitive procedure} slot-set! obj slot-name value
1303 Set the value of the slot named @var{slot-name} in @var{obj} to @var{value}.
1305 @code{slot-set!} calls the generic function @code{slot-missing} if
1306 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1307 Slot Access Errors, slot-missing}).
1310 GOOPS stores information about slots in class metaobjects. Internally,
1311 all of these procedures work by looking up the slot definition for the
1312 slot named @var{slot-name} in the class metaobject for @code{(class-of
1313 @var{obj})}, and then using the slot definition's ``getter'' and
1314 ``setter'' closures to get and set the slot value.
1316 The next four procedures differ from the previous ones in that they take
1317 the class metaobject as an explicit argument, rather than assuming
1318 @code{(class-of @var{obj})}. Therefore they allow you to apply the
1319 ``getter'' and ``setter'' closures of a slot definition in one class to
1320 an instance of a different class.
1322 [ *fixme* I have no idea why this is useful! Perhaps when a slot in
1323 @code{(class-of @var{obj})} shadows a slot with the same name in one of
1324 its superclasses? There should be an enlightening example here. ]
1326 @deffn {primitive procedure} slot-exists-using-class? class obj slot-name
1327 Return @code{#t} if the class metaobject @var{class} has a slot
1328 definition for a slot with name @var{slot-name}, otherwise @code{#f}.
1331 @deffn {primitive procedure} slot-bound-using-class? class obj slot-name
1332 Return @code{#t} if applying @code{slot-ref-using-class} to the same
1333 arguments would call the generic function @code{slot-unbound}, otherwise
1336 @code{slot-bound-using-class?} calls the generic function
1337 @code{slot-missing} if @var{class} does not have a slot definition for a
1338 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1342 @deffn {primitive procedure} slot-ref-using-class class obj slot-name
1343 Apply the ``getter'' closure for the slot named @var{slot-name} in
1344 @var{class} to @var{obj}, and return its result.
1346 @code{slot-ref-using-class} calls the generic function
1347 @code{slot-missing} if @var{class} does not have a slot definition for a
1348 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1351 @code{slot-ref-using-class} calls the generic function
1352 @code{slot-unbound} if the application of the ``getter'' closure to
1353 @var{obj} returns an unbound value (@pxref{Handling Slot Access Errors,
1357 @deffn {primitive procedure} slot-set-using-class! class obj slot-name value
1358 Apply the ``setter'' closure for the slot named @var{slot-name} in
1359 @var{class} to @var{obj} and @var{value}.
1361 @code{slot-set-using-class!} calls the generic function
1362 @code{slot-missing} if @var{class} does not have a slot definition for a
1363 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1368 @subsubsection Class Slots
1370 Slots whose allocation is per-class rather than per-instance can be
1371 referenced and set without needing to specify any particular instance.
1373 @deffn procedure class-slot-ref class slot-name
1374 Return the value of the slot named @var{slot-name} in class @var{class}.
1375 The named slot must have @code{#:class} or @code{#:each-subclass}
1376 allocation (@pxref{Slot Options,, allocation}).
1378 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1379 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1380 function with arguments @var{class} and @var{slot-name}. Otherwise, if
1381 the slot value is unbound, @code{class-slot-ref} calls the
1382 @code{slot-missing} generic function, with the same arguments.
1385 @deffn procedure class-slot-set! class slot-name value
1386 Set the value of the slot named @var{slot-name} in class @var{class} to
1387 @var{value}. The named slot must have @code{#:class} or
1388 @code{#:each-subclass} allocation (@pxref{Slot Options,, allocation}).
1390 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1391 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1392 function with arguments @var{class} and @var{slot-name}.
1395 @node Handling Slot Access Errors
1396 @subsubsection Handling Slot Access Errors
1398 GOOPS calls one of the following generic functions when a ``slot-ref''
1399 or ``slot-set!'' call specifies a non-existent slot name, or tries to
1400 reference a slot whose value is unbound.
1402 @deffn generic slot-missing
1403 @deffnx method slot-missing (class <class>) slot-name
1404 @deffnx method slot-missing (class <class>) (object <object>) slot-name
1405 @deffnx method slot-missing (class <class>) (object <object>) slot-name value
1406 When an application attempts to reference or set a class or instance
1407 slot by name, and the slot name is invalid for the specified @var{class}
1408 or @var{object}, GOOPS calls the @code{slot-missing} generic function.
1410 The default methods all call @code{goops-error} with an appropriate
1414 @deffn generic slot-unbound
1415 @deffnx method slot-unbound (object <object>)
1416 @deffnx method slot-unbound (class <class>) slot-name
1417 @deffnx method slot-unbound (class <class>) (object <object>) slot-name
1418 When an application attempts to reference a class or instance slot, and
1419 the slot's value is unbound, GOOPS calls the @code{slot-unbound} generic
1422 The default methods all call @code{goops-error} with an appropriate
1426 @node Creating Generic Functions
1427 @subsection Creating Generic Functions
1429 A generic function is a collection of methods, with rules for
1430 determining which of the methods should be applied for any given
1431 invocation of the generic function.
1433 GOOPS represents generic functions as metaobjects of the class
1434 @code{<generic>} (or one of its subclasses).
1437 * Basic Generic Function Creation::
1438 * Generic Function Internals::
1439 * Extending Guiles Primitives::
1442 @node Basic Generic Function Creation
1443 @subsubsection Basic Generic Function Creation
1445 The following forms may be used to bind a variable to a generic
1446 function. Depending on that variable's pre-existing value, the generic
1447 function may be created empty - with no methods - or it may contain
1448 methods that are inferred from the pre-existing value.
1450 It is not, in general, necessary to use @code{define-generic} or
1451 @code{define-accessor} before defining methods for the generic function
1452 using @code{define-method}, since @code{define-method} will
1453 automatically interpolate a @code{define-generic} call, or upgrade an
1454 existing generic to an accessor, if that is implied by the
1455 @code{define-method} call. Note in particular that,
1456 if the specified variable already has a @emph{generic function} value,
1457 @code{define-generic} and @code{define-accessor} will @emph{discard} it!
1458 Obviously it is application-dependent whether this is desirable or not.
1460 If, for example, you wanted to extend @code{+} for a class representing
1461 a new numerical type, you probably want to inherit any existing methods
1462 for @code{+} and so should not use @code{define-generic}. If, on the
1463 other hand, you do not want to risk inheriting methods whose behaviour
1464 might surprise you, you can use @code{define-generic} or
1465 @code{define-accessor} to wipe the slate clean.
1467 @deffn syntax define-generic symbol
1468 Create a generic function with name @var{symbol} and bind it to the
1469 variable @var{symbol}.
1471 If the variable @var{symbol} was previously bound to a Scheme procedure
1472 (or procedure-with-setter), the old procedure (and setter) is
1473 incorporated into the new generic function as its default procedure (and
1474 setter). Any other previous value that was bound to @var{symbol},
1475 including an existing generic function, is overwritten by the new
1479 @deffn syntax define-accessor symbol
1480 Create an accessor with name @var{symbol} and bind it to the variable
1483 If the variable @var{symbol} was previously bound to a Scheme procedure
1484 (or procedure-with-setter), the old procedure (and setter) is
1485 incorporated into the new accessor as its default procedure (and
1486 setter). Any other previous value that was bound to @var{symbol},
1487 including an existing generic function or accessor, is overwritten by
1491 It is sometimes tempting to use GOOPS accessors with short names. For
1492 example, it is tempting to use the name @code{x} for the x-coordinate
1495 Assume that we work with a graphical package which needs to use two
1496 independent vector packages for 2D and 3D vectors respectively. If
1497 both packages export @code{x} we will encounter a name collision.
1499 This can be resolved automagically with the duplicates handler
1500 @code{merge-generics} which gives the module system license to merge
1501 all generic functions sharing a common name:
1504 (define-module (math 2D-vectors)
1505 :use-module (oop goops)
1508 (define-module (math 3D-vectors)
1509 :use-module (oop goops)
1510 :export (x y z ...))
1512 (define-module (my-module)
1513 :use-module (math 2D-vectors)
1514 :use-module (math 3D-vectors)
1515 :duplicates merge-generics)
1518 The generic function @code{x} in @code{(my-module)} will now share
1519 methods with @code{x} in both imported modules.
1521 There will, in fact, now be three distinct generic functions named
1522 @code{x}: @code{x} in @code{(2D-vectors)}, @code{x} in
1523 @code{(3D-vectors)}, and @code{x} in @code{(my-module)}. The last
1524 function will be an @code{<extended-generic>}, extending the previous
1527 Let's call the imported generic functions the "ancestor functions".
1528 The generic function @code{x} in @code{(my-module)} is, in turn, a
1529 "descendant function" of the imported functions, extending its
1532 For any generic function G, the applicable methods are selected from
1533 the union of the methods of the descendant functions, the methods of G
1534 itself and the methods of the ancestor functions.
1536 This, ancestor functions share methods with their descendants and vice
1537 versa. This implies that @code{x} in @code{(math 2D-vectors)} will
1538 share the methods of @code{x} in @code{(my-module)} and vice versa,
1539 while @code{x} in @code{(math 2D-vectors)} doesn't share the methods
1540 of @code{x} in @code{(math 3D-vectors)}, thus preserving modularity.
1542 Sharing is dynamic, so that adding new methods to a descendant implies
1543 adding it to the ancestor.
1545 If duplicates checking is desired in the above example, the following
1546 form of the @code{:duplicates} option can be used instead:
1549 :duplicates (merge-generics check)
1552 @node Generic Function Internals
1553 @subsubsection Generic Function Internals
1555 @code{define-generic} calls @code{ensure-generic} to upgrade a
1556 pre-existing procedure value, or @code{make} with metaclass
1557 @code{<generic>} to create a new generic function.
1559 @code{define-accessor} calls @code{ensure-accessor} to upgrade a
1560 pre-existing procedure value, or @code{make-accessor} to create a new
1563 @deffn procedure ensure-generic old-definition [name]
1564 Return a generic function with name @var{name}, if possible by using or
1565 upgrading @var{old-definition}. If unspecified, @var{name} defaults to
1568 If @var{old-definition} is already a generic function, it is returned
1571 If @var{old-definition} is a Scheme procedure or procedure-with-setter,
1572 @code{ensure-generic} returns a new generic function that uses
1573 @var{old-definition} for its default procedure and setter.
1575 Otherwise @code{ensure-generic} returns a new generic function with no
1576 defaults and no methods.
1579 @deffn procedure make-generic [name]
1580 Return a new generic function with name @code{(car @var{name})}. If
1581 unspecified, @var{name} defaults to @code{#f}.
1584 @code{ensure-generic} calls @code{make} with metaclasses
1585 @code{<generic>} and @code{<generic-with-setter>}, depending on the
1586 previous value of the variable that it is trying to upgrade.
1588 @code{make-generic} is a simple wrapper for @code{make} with metaclass
1591 @deffn procedure ensure-accessor proc [name]
1592 Return an accessor with name @var{name}, if possible by using or
1593 upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
1595 If @var{proc} is already an accessor, it is returned unchanged.
1597 If @var{proc} is a Scheme procedure, procedure-with-setter or generic
1598 function, @code{ensure-accessor} returns an accessor that reuses the
1599 reusable elements of @var{proc}.
1601 Otherwise @code{ensure-accessor} returns a new accessor with no defaults
1605 @deffn procedure make-accessor [name]
1606 Return a new accessor with name @code{(car @var{name})}. If
1607 unspecified, @var{name} defaults to @code{#f}.
1610 @code{ensure-accessor} calls @code{make} with
1611 metaclass @code{<generic-with-setter>}, as well as calls to
1612 @code{ensure-generic}, @code{make-accessor} and (tail recursively)
1613 @code{ensure-accessor}.
1615 @code{make-accessor} calls @code{make} twice, first
1616 with metaclass @code{<generic>} to create a generic function for the
1617 setter, then with metaclass @code{<generic-with-setter>} to create the
1618 accessor, passing the setter generic function as the value of the
1619 @code{#:setter} keyword.
1621 @node Extending Guiles Primitives
1622 @subsubsection Extending Guile's Primitives
1624 When GOOPS is loaded, many of Guile's primitive procedures can be
1625 extended by giving them a generic function definition that operates
1626 in conjunction with their normal C-coded implementation. For
1627 primitives that are extended in this way, the result from the user-
1628 or application-level point of view is that the extended primitive
1629 behaves exactly like a generic function with the C-coded implementation
1630 as its default method.
1632 The @code{generic-capability?} predicate should be used to determine
1633 whether a particular primitive is extensible in this way.
1635 @deffn {primitive procedure} generic-capability? primitive
1636 Return @code{#t} if @var{primitive} can be extended by giving it a
1637 generic function definition, otherwise @code{#f}.
1640 Even when a primitive procedure is extensible like this, its generic
1641 function definition is not created until it is needed by a call to
1642 @code{define-method}, or until the application explicitly requests it
1643 by calling @code{enable-primitive-generic!}.
1645 @deffn {primitive procedure} enable-primitive-generic! primitive
1646 Force the creation of a generic function definition for
1650 Once the generic function definition for a primitive has been created,
1651 it can be retrieved using @code{primitive-generic-generic}.
1653 @deffn {primitive procedure} primitive-generic-generic primitive
1654 Return the generic function definition of @var{primitive}.
1656 @code{primitive-generic-generic} raises an error if @var{primitive}
1657 is not a primitive with generic capability, or if its generic capability
1658 has not yet been enabled, whether implicitly (by @code{define-method})
1659 or explicitly (by @code{enable-primitive-generic!}).
1662 Note that the distinction between, on the one hand, primitives with
1663 additional generic function definitions and, on the other hand, generic
1664 functions with a default method, may disappear when GOOPS is fully
1665 integrated into the core of Guile. Consequently, the
1666 procedures described in this section may disappear as well.
1668 @node Adding Methods to Generic Functions
1669 @subsection Adding Methods to Generic Functions
1672 * Basic Method Definition::
1673 * Method Definition Internals::
1676 @node Basic Method Definition
1677 @subsubsection Basic Method Definition
1679 To add a method to a generic function, use the @code{define-method} form.
1681 @deffn syntax define-method (generic parameter @dots{}) . body
1682 Define a method for the generic function or accessor @var{generic} with
1683 parameters @var{parameter}s and body @var{body}.
1685 @var{generic} is a generic function. If @var{generic} is a variable
1686 which is not yet bound to a generic function object, the expansion of
1687 @code{define-method} will include a call to @code{define-generic}. If
1688 @var{generic} is @code{(setter @var{generic-with-setter})}, where
1689 @var{generic-with-setter} is a variable which is not yet bound to a
1690 generic-with-setter object, the expansion will include a call to
1691 @code{define-accessor}.
1693 Each @var{parameter} must be either a symbol or a two-element list
1694 @code{(@var{symbol} @var{class})}. The symbols refer to variables in
1695 the @var{body} that will be bound to the parameters supplied by the
1696 caller when calling this method. The @var{class}es, if present,
1697 specify the possible combinations of parameters to which this method
1700 @var{body} is the body of the method definition.
1703 @code{define-method} expressions look a little like normal Scheme
1704 procedure definitions of the form
1707 (define (name formals @dots{}) . body)
1710 The most important difference is that each formal parameter, apart from the
1711 possible ``rest'' argument, can be qualified by a class name:
1712 @code{@var{formal}} becomes @code{(@var{formal} @var{class})}. The
1713 meaning of this qualification is that the method being defined
1714 will only be applicable in a particular generic function invocation if
1715 the corresponding argument is an instance of @code{@var{class}} (or one of
1716 its subclasses). If more than one of the formal parameters is qualified
1717 in this way, then the method will only be applicable if each of the
1718 corresponding arguments is an instance of its respective qualifying class.
1720 Note that unqualified formal parameters act as though they are qualified
1721 by the class @code{<top>}, which GOOPS uses to mean the superclass of
1722 all valid Scheme types, including both primitive types and GOOPS classes.
1724 For example, if a generic function method is defined with
1725 @var{parameter}s @code{((s1 <square>) (n <number>))}, that method is
1726 only applicable to invocations of its generic function that have two
1727 parameters where the first parameter is an instance of the
1728 @code{<square>} class and the second parameter is a number.
1730 If a generic function is invoked with a combination of parameters for which
1731 there is no applicable method, GOOPS raises an error. For more about
1732 invocation error handling, and generic function invocation in general,
1733 see @ref{Invoking Generic Functions}.
1735 @node Method Definition Internals
1736 @subsubsection Method Definition Internals
1738 @code{define-method}
1742 checks the form of the first parameter, and applies the following steps
1743 to the accessor's setter if it has the @code{(setter @dots{})} form
1746 interpolates a call to @code{define-generic} or @code{define-accessor}
1747 if a generic function is not already defined with the supplied name
1750 calls @code{method} with the @var{parameter}s and @var{body}, to make a
1754 calls @code{add-method!} to add this method to the relevant generic
1758 @deffn syntax method (parameter @dots{}) . body
1759 Make a method whose specializers are defined by the classes in
1760 @var{parameter}s and whose procedure definition is constructed from the
1761 @var{parameter} symbols and @var{body} forms.
1763 The @var{parameter} and @var{body} parameters should be as for
1764 @code{define-method} (@pxref{Basic Method Definition,, define-method}).
1771 extracts formals and specializing classes from the @var{parameter}s,
1772 defaulting the class for unspecialized parameters to @code{<top>}
1775 creates a closure using the formals and the @var{body} forms
1778 calls @code{make} with metaclass @code{<method>} and the specializers
1779 and closure using the @code{#:specializers} and @code{#:procedure}
1783 @deffn procedure make-method specializers procedure
1784 Make a method using @var{specializers} and @var{procedure}.
1786 @var{specializers} should be a list of classes that specifies the
1787 parameter combinations to which this method will be applicable.
1789 @var{procedure} should be the closure that will applied to the generic
1790 function parameters when this method is invoked.
1793 @code{make-method} is a simple wrapper around @code{make} with metaclass
1796 @deffn generic add-method! target method
1797 Generic function for adding method @var{method} to @var{target}.
1800 @deffn method add-method! (generic <generic>) (method <method>)
1801 Add method @var{method} to the generic function @var{generic}.
1804 @deffn method add-method! (proc <procedure>) (method <method>)
1805 If @var{proc} is a procedure with generic capability (@pxref{Extending
1806 Guiles Primitives,, generic-capability?}), upgrade it to a
1807 primitive generic and add @var{method} to its generic function
1811 @deffn method add-method! (pg <primitive-generic>) (method <method>)
1812 Add method @var{method} to the generic function definition of @var{pg}.
1814 Implementation: @code{(add-method! (primitive-generic-generic pg) method)}.
1817 @deffn method add-method! (whatever <top>) (method <method>)
1818 Raise an error indicating that @var{whatever} is not a valid generic
1822 @node Invoking Generic Functions
1823 @subsection Invoking Generic Functions
1825 When a variable with a generic function definition appears as the first
1826 element of a list that is being evaluated, the Guile evaluator tries
1827 to apply the generic function to the arguments obtained by evaluating
1828 the remaining elements of the list. [ *fixme* How do I put this in a
1829 more Schemely and less Lispy way? ]
1831 Usually a generic function contains several method definitions, with
1832 varying degrees of formal parameter specialization (@pxref{Basic
1833 Method Definition,, define-method}). So it is necessary to sort these
1834 methods by specificity with respect to the supplied arguments, and then
1835 apply the most specific method definition. Less specific methods
1836 may be applied subsequently if a method that is being applied calls
1840 * Determining Which Methods to Apply::
1841 * Handling Invocation Errors::
1844 @node Determining Which Methods to Apply
1845 @subsubsection Determining Which Methods to Apply
1847 [ *fixme* Sorry - this is the area of GOOPS that I understand least of
1848 all, so I'm afraid I have to pass on this section. Would some other
1849 kind person consider filling it in? ]
1851 @deffn generic apply-generic
1852 @deffnx method apply-generic (gf <generic>) args
1855 @deffn generic compute-applicable-methods
1856 @deffnx method compute-applicable-methods (gf <generic>) args
1859 @deffn generic sort-applicable-methods
1860 @deffnx method sort-applicable-methods (gf <generic>) methods args
1863 @deffn generic method-more-specific?
1864 @deffnx method method-more-specific? (m1 <method>) (m2 <method>) args
1867 @deffn generic apply-method
1868 @deffnx method apply-method (gf <generic>) methods build-next args
1871 @deffn generic apply-methods
1872 @deffnx method apply-methods (gf <generic>) (l <list>) args
1875 @node Handling Invocation Errors
1876 @subsubsection Handling Invocation Errors
1878 @deffn generic no-method
1879 @deffnx method no-method (gf <generic>) args
1880 When an application invokes a generic function, and no methods at all
1881 have been defined for that generic function, GOOPS calls the
1882 @code{no-method} generic function. The default method calls
1883 @code{goops-error} with an appropriate message.
1886 @deffn generic no-applicable-method
1887 @deffnx method no-applicable-method (gf <generic>) args
1888 When an application applies a generic function to a set of arguments,
1889 and no methods have been defined for those argument types, GOOPS calls
1890 the @code{no-applicable-method} generic function. The default method
1891 calls @code{goops-error} with an appropriate message.
1894 @deffn generic no-next-method
1895 @deffnx method no-next-method (gf <generic>) args
1896 When a generic function method calls @code{(next-method)} to invoke the
1897 next less specialized method for that generic function, and no less
1898 specialized methods have been defined for the current generic function
1899 arguments, GOOPS calls the @code{no-next-method} generic function. The
1900 default method calls @code{goops-error} with an appropriate message.
1903 @node Redefining a Class
1904 @subsection Redefining a Class
1906 Suppose that a class @code{<my-class>} is defined using @code{define-class}
1907 (@pxref{Basic Class Definition,, define-class}), with slots that have
1908 accessor functions, and that an application has created several instances
1909 of @code{<my-class>} using @code{make} (@pxref{Basic Instance Creation,,
1910 make}). What then happens if @code{<my-class>} is redefined by calling
1911 @code{define-class} again?
1914 * Default Class Redefinition Behaviour::
1915 * Customizing Class Redefinition::
1918 @node Default Class Redefinition Behaviour
1919 @subsubsection Default Class Redefinition Behaviour
1921 GOOPS' default answer to this question is as follows.
1925 All existing direct instances of @code{<my-class>} are converted to be
1926 instances of the new class. This is achieved by preserving the values
1927 of slots that exist in both the old and new definitions, and initializing the
1928 values of new slots in the usual way (@pxref{Basic Instance Creation,,
1932 All existing subclasses of @code{<my-class>} are redefined, as though
1933 the @code{define-class} expressions that defined them were re-evaluated
1934 following the redefinition of @code{<my-class>}, and the class
1935 redefinition process described here is applied recursively to the
1936 redefined subclasses.
1939 Once all of its instances and subclasses have been updated, the class
1940 metaobject previously bound to the variable @code{<my-class>} is no
1941 longer needed and so can be allowed to be garbage collected.
1944 To keep things tidy, GOOPS also needs to do a little housekeeping on
1945 methods that are associated with the redefined class.
1949 Slot accessor methods for slots in the old definition should be removed
1950 from their generic functions. They will be replaced by accessor methods
1951 for the slots of the new class definition.
1954 Any generic function method that uses the old @code{<my-class>} metaobject
1955 as one of its formal parameter specializers must be updated to refer to
1956 the new @code{<my-class>} metaobject. (Whenever a new generic function
1957 method is defined, @code{define-method} adds the method to a list stored
1958 in the class metaobject for each class used as a formal parameter
1959 specializer, so it is easy to identify all the methods that must be
1960 updated when a class is redefined.)
1963 If this class redefinition strategy strikes you as rather counter-intuitive,
1964 bear in mind that it is derived from similar behaviour in other object
1965 systems such as CLOS, and that experience in those systems has shown it to be
1966 very useful in practice.
1968 Also bear in mind that, like most of GOOPS' default behaviour, it can
1969 be customized@dots{}
1971 @node Customizing Class Redefinition
1972 @subsubsection Customizing Class Redefinition
1974 When @code{define-class} notices that a class is being redefined,
1975 it constructs the new class metaobject as usual, and then invokes the
1976 @code{class-redefinition} generic function with the old and new classes
1977 as arguments. Therefore, if the old or new classes have metaclasses
1978 other than the default @code{<class>}, class redefinition behaviour can
1979 be customized by defining a @code{class-redefinition} method that is
1980 specialized for the relevant metaclasses.
1982 @deffn generic class-redefinition
1983 Handle the class redefinition from @var{old-class} to @var{new-class},
1984 and return the new class metaobject that should be bound to the
1985 variable specified by @code{define-class}'s first argument.
1988 @deffn method class-redefinition (old-class <class>) (new-class <class>)
1989 Implements GOOPS' default class redefinition behaviour, as described in
1990 @ref{Default Class Redefinition Behaviour}. Returns the metaobject
1991 for the new class definition.
1994 An alternative class redefinition strategy could be to leave all
1995 existing instances as instances of the old class, but accepting that the
1996 old class is now ``nameless'', since its name has been taken over by the
1997 new definition. In this strategy, any existing subclasses could also
1998 be left as they are, on the understanding that they inherit from a nameless
2001 This strategy is easily implemented in GOOPS, by defining a new metaclass,
2002 that will be used as the metaclass for all classes to which the strategy
2003 should apply, and then defining a @code{class-redefinition} method that
2004 is specialized for this metaclass:
2007 (define-class <can-be-nameless> (<class>))
2009 (define-method (class-redefinition (old <can-be-nameless>)
2014 When customization can be as easy as this, aren't you glad that GOOPS
2015 implements the far more difficult strategy as its default!
2017 Finally, note that, if @code{class-redefinition} itself is not customized,
2018 the default @code{class-redefinition} method invokes three further
2019 generic functions that could be individually customized:
2023 (remove-class-accessors! @var{old-class})
2026 (update-direct-method! @var{method} @var{old-class} @var{new-class})
2029 (update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
2032 and the default methods for these generic functions invoke further
2033 generic functions, and so on@dots{} The detailed protocol for all of these
2034 is described in @ref{MOP Specification}.
2036 @node Changing the Class of an Instance
2037 @subsection Changing the Class of an Instance
2039 You can change the class of an existing instance by invoking the
2040 generic function @code{change-class} with two arguments: the instance
2043 @deffn generic change-class
2046 The default method for @code{change-class} decides how to implement the
2047 change of class by looking at the slot definitions for the instance's
2048 existing class and for the new class. If the new class has slots with
2049 the same name as slots in the existing class, the values for those slots
2050 are preserved. Slots that are present only in the existing class are
2051 discarded. Slots that are present only in the new class are initialized
2052 using the corresponding slot definition's init function (@pxref{Classes,,
2053 slot-init-function}).
2055 @deffn {method} change-class (obj <object>) (new <class>)
2056 Modify instance @var{obj} to make it an instance of class @var{new}.
2058 The value of each of @var{obj}'s slots is preserved only if a similarly named
2059 slot exists in @var{new}; any other slot values are discarded.
2061 The slots in @var{new} that do not correspond to any of @var{obj}'s
2062 pre-existing slots are initialized according to @var{new}'s slot definitions'
2066 Customized change of class behaviour can be implemented by defining
2067 @code{change-class} methods that are specialized either by the class
2068 of the instances to be modified or by the metaclass of the new class.
2070 When a class is redefined (@pxref{Redefining a Class}), and the default
2071 class redefinition behaviour is not overridden, GOOPS (eventually)
2072 invokes the @code{change-class} generic function for each existing
2073 instance of the redefined class.
2076 @subsection Introspection
2078 @dfn{Introspection}, also known as @dfn{reflection}, is the name given
2079 to the ability to obtain information dynamically about GOOPS metaobjects.
2080 It is perhaps best illustrated by considering an object oriented language
2081 that does not provide any introspection, namely C++.
2083 Nothing in C++ allows a running program to obtain answers to the following
2088 What are the data members of this object or class?
2091 What classes does this class inherit from?
2094 Is this method call virtual or non-virtual?
2097 If I invoke @code{Employee::adjustHoliday()}, what class contains the
2098 @code{adjustHoliday()} method that will be applied?
2101 In C++, answers to such questions can only be determined by looking at
2102 the source code, if you have access to it. GOOPS, on the other hand,
2103 includes procedures that allow answers to these questions --- or their
2104 GOOPS equivalents --- to be obtained dynamically, at run time.
2110 * Generic Functions::
2111 * Generic Function Methods::
2115 @subsubsection Classes
2117 @deffn {primitive procedure} class-name class
2118 Return the name of class @var{class}.
2119 This is the value of the @var{class} metaobject's @code{name} slot.
2122 @deffn {primitive procedure} class-direct-supers class
2123 Return a list containing the direct superclasses of @var{class}.
2124 This is the value of the @var{class} metaobject's
2125 @code{direct-supers} slot.
2128 @deffn {primitive procedure} class-direct-slots class
2129 Return a list containing the slot definitions of the direct slots of
2131 This is the value of the @var{class} metaobject's @code{direct-slots}
2135 @deffn {primitive procedure} class-direct-subclasses class
2136 Return a list containing the direct subclasses of @var{class}.
2137 This is the value of the @var{class} metaobject's
2138 @code{direct-subclasses} slot.
2141 @deffn {primitive procedure} class-direct-methods class
2142 Return a list of all the generic function methods that use @var{class}
2143 as a formal parameter specializer.
2144 This is the value of the @var{class} metaobject's @code{direct-methods}
2148 @deffn {primitive procedure} class-precedence-list class
2149 Return the class precedence list for class @var{class} (@pxref{Class
2151 This is the value of the @var{class} metaobject's @code{cpl} slot.
2154 @deffn {primitive procedure} class-slots class
2155 Return a list containing the slot definitions for all @var{class}'s slots,
2156 including any slots that are inherited from superclasses.
2157 This is the value of the @var{class} metaobject's @code{slots} slot.
2160 @deffn {primitive procedure} class-environment class
2161 Return the value of @var{class}'s @code{environment} slot.
2162 [ *fixme* I don't know what this value is used for. ]
2165 @deffn procedure class-subclasses class
2166 Return a list of all subclasses of @var{class}.
2169 @deffn procedure class-methods class
2170 Return a list of all methods that use @var{class} or a subclass of
2171 @var{class} as one of its formal parameter specializers.
2175 @subsubsection Slots
2177 @deffn procedure class-slot-definition class slot-name
2178 Return the slot definition for the slot named @var{slot-name} in class
2179 @var{class}. @var{slot-name} should be a symbol.
2182 @deffn procedure slot-definition-name slot-def
2183 Extract and return the slot name from @var{slot-def}.
2186 @deffn procedure slot-definition-options slot-def
2187 Extract and return the slot options from @var{slot-def}.
2190 @deffn procedure slot-definition-allocation slot-def
2191 Extract and return the slot allocation option from @var{slot-def}. This
2192 is the value of the @code{#:allocation} keyword (@pxref{Slot Options,,
2193 allocation}), or @code{#:instance} if the @code{#:allocation} keyword is
2197 @deffn procedure slot-definition-getter slot-def
2198 Extract and return the slot getter option from @var{slot-def}. This is
2199 the value of the @code{#:getter} keyword (@pxref{Slot Options,,
2200 getter}), or @code{#f} if the @code{#:getter} keyword is absent.
2203 @deffn procedure slot-definition-setter slot-def
2204 Extract and return the slot setter option from @var{slot-def}. This is
2205 the value of the @code{#:setter} keyword (@pxref{Slot Options,,
2206 setter}), or @code{#f} if the @code{#:setter} keyword is absent.
2209 @deffn procedure slot-definition-accessor slot-def
2210 Extract and return the slot accessor option from @var{slot-def}. This
2211 is the value of the @code{#:accessor} keyword (@pxref{Slot Options,,
2212 accessor}), or @code{#f} if the @code{#:accessor} keyword is absent.
2215 @deffn procedure slot-definition-init-value slot-def
2216 Extract and return the slot init-value option from @var{slot-def}. This
2217 is the value of the @code{#:init-value} keyword (@pxref{Slot Options,,
2218 init-value}), or the unbound value if the @code{#:init-value} keyword is
2222 @deffn procedure slot-definition-init-form slot-def
2223 Extract and return the slot init-form option from @var{slot-def}. This
2224 is the value of the @code{#:init-form} keyword (@pxref{Slot Options,,
2225 init-form}), or the unbound value if the @code{#:init-form} keyword is
2229 @deffn procedure slot-definition-init-thunk slot-def
2230 Extract and return the slot init-thunk option from @var{slot-def}. This
2231 is the value of the @code{#:init-thunk} keyword (@pxref{Slot Options,,
2232 init-thunk}), or @code{#f} if the @code{#:init-thunk} keyword is absent.
2235 @deffn procedure slot-definition-init-keyword slot-def
2236 Extract and return the slot init-keyword option from @var{slot-def}.
2237 This is the value of the @code{#:init-keyword} keyword (@pxref{Slot
2238 Options,, init-keyword}), or @code{#f} if the @code{#:init-keyword}
2242 @deffn procedure slot-init-function class slot-name
2243 Return the initialization function for the slot named @var{slot-name} in
2244 class @var{class}. @var{slot-name} should be a symbol.
2246 The returned initialization function incorporates the effects of the
2247 standard @code{#:init-thunk}, @code{#:init-form} and @code{#:init-value}
2248 slot options. These initializations can be overridden by the
2249 @code{#:init-keyword} slot option or by a specialized @code{initialize}
2250 method, so, in general, the function returned by
2251 @code{slot-init-function} may be irrelevant. For a fuller discussion,
2252 see @ref{Slot Options,, init-value}.
2256 @subsubsection Instances
2258 @deffn {primitive procedure} class-of value
2259 Return the GOOPS class of any Scheme @var{value}.
2262 @deffn {primitive procedure} instance? object
2263 Return @code{#t} if @var{object} is any GOOPS instance, otherwise
2267 @deffn procedure is-a? object class
2268 Return @code{#t} if @var{object} is an instance of @var{class} or one of
2272 Implementation notes: @code{is-a?} uses @code{class-of} and
2273 @code{class-precedence-list} to obtain the class precedence list for
2276 @node Generic Functions
2277 @subsubsection Generic Functions
2279 @deffn {primitive procedure} generic-function-name gf
2280 Return the name of generic function @var{gf}.
2283 @deffn {primitive procedure} generic-function-methods gf
2284 Return a list of the methods of generic function @var{gf}.
2285 This is the value of the @var{gf} metaobject's @code{methods} slot.
2288 @node Generic Function Methods
2289 @subsubsection Generic Function Methods
2291 @deffn {primitive procedure} method-generic-function method
2292 Return the generic function that @var{method} belongs to.
2293 This is the value of the @var{method} metaobject's
2294 @code{generic-function} slot.
2297 @deffn {primitive procedure} method-specializers method
2298 Return a list of @var{method}'s formal parameter specializers .
2299 This is the value of the @var{method} metaobject's
2300 @code{specializers} slot.
2303 @deffn {primitive procedure} method-procedure method
2304 Return the procedure that implements @var{method}.
2305 This is the value of the @var{method} metaobject's
2306 @code{procedure} slot.
2309 @deffn generic method-source
2310 @deffnx method method-source (m <method>)
2311 Return an expression that prints to show the definition of method
2315 (define-generic cube)
2317 (define-method (cube (n <number>))
2320 (map method-source (generic-function-methods cube))
2322 ((method ((n <number>)) (* n n n)))
2326 @node Miscellaneous Functions
2327 @subsection Miscellaneous Functions
2330 * Administrative Functions::
2331 * GOOPS Error Handling::
2332 * Object Comparisons::
2334 * Write and Display::
2337 @node Administrative Functions
2338 @subsubsection Administration Functions
2340 This section describes administrative, non-technical GOOPS functions.
2342 @deffn primitive goops-version
2343 Return the current GOOPS version as a string, for example ``0.2''.
2346 @node GOOPS Error Handling
2347 @subsubsection Error Handling
2349 The procedure @code{goops-error} is called to raise an appropriate error
2350 by the default methods of the following generic functions:
2354 @code{slot-missing} (@pxref{Handling Slot Access Errors,, slot-missing})
2357 @code{slot-unbound} (@pxref{Handling Slot Access Errors,, slot-unbound})
2360 @code{no-method} (@pxref{Handling Invocation Errors,, no-method})
2363 @code{no-applicable-method} (@pxref{Handling Invocation Errors,,
2364 no-applicable-method})
2367 @code{no-next-method} (@pxref{Handling Invocation Errors,,
2371 If you customize these functions for particular classes or metaclasses,
2372 you may still want to use @code{goops-error} to signal any error
2373 conditions that you detect.
2375 @deffn procedure goops-error format-string . args
2376 Raise an error with key @code{goops-error} and error message constructed
2377 from @var{format-string} and @var{args}. Error message formatting is
2378 as done by @code{scm-error}.
2381 @node Object Comparisons
2382 @subsubsection Object Comparisons
2385 @deffnx method eqv? ((x <top>) (y <top>))
2386 @deffnx generic equal?
2387 @deffnx method equal? ((x <top>) (y <top>))
2389 @deffnx method = ((x <number>) (y <number>))
2390 Generic functions and default (unspecialized) methods for comparing two
2393 The default method for @code{eqv?} returns @code{#t} for all values
2394 that are equal in the sense defined by R5RS and the Guile reference
2395 manual, otherwise @code{#f}. The default method for @code{equal?}
2396 returns @code{#t} or @code{#f} in the sense defined by R5RS and the
2397 Guile reference manual. If no such comparison is defined,
2398 @code{equal?} returns the result of a call to @code{eqv?}. The
2399 default method for = returns @code{#t} if @var{x} and @var{y} are
2400 numerically equal, otherwise @code{#f}.
2402 Application class authors may wish to define specialized methods for
2403 @code{eqv?}, @code{equal?} and @code{=} that compare instances of the
2404 same class for equality in whatever sense is useful to the
2405 application. Such methods will only be called if the arguments have
2406 the same class and the result of the comparison isn't defined by R5RS
2407 and the Guile reference manual.
2410 @node Cloning Objects
2411 @subsubsection Cloning Objects
2413 @deffn generic shallow-clone
2414 @deffnx method shallow-clone (self <object>)
2415 Return a ``shallow'' clone of @var{self}. The default method makes a
2416 shallow clone by allocating a new instance and copying slot values from
2417 self to the new instance. Each slot value is copied either as an
2418 immediate value or by reference.
2421 @deffn generic deep-clone
2422 @deffnx method deep-clone (self <object>)
2423 Return a ``deep'' clone of @var{self}. The default method makes a deep
2424 clone by allocating a new instance and copying or cloning slot values
2425 from self to the new instance. If a slot value is an instance
2426 (satisfies @code{instance?}), it is cloned by calling @code{deep-clone}
2427 on that value. Other slot values are copied either as immediate values
2431 @node Write and Display
2432 @subsubsection Write and Display
2434 @deffn {primitive generic} write object port
2435 @deffnx {primitive generic} display object port
2436 When GOOPS is loaded, @code{write} and @code{display} become generic
2437 functions with special methods for printing
2441 objects - instances of the class @code{<object>}
2444 foreign objects - instances of the class @code{<foreign-object>}
2447 classes - instances of the class @code{<class>}
2450 generic functions - instances of the class @code{<generic>}
2453 methods - instances of the class @code{<method>}.
2456 @code{write} and @code{display} print non-GOOPS values in the same way
2457 as the Guile primitive @code{write} and @code{display} functions.
2460 @node MOP Specification
2461 @section MOP Specification
2463 For an introduction to metaobjects and the metaobject protocol,
2464 see @ref{Metaobjects and the Metaobject Protocol}.
2466 The aim of the MOP specification in this chapter is to specify all the
2467 customizable generic function invocations that can be made by the standard
2468 GOOPS syntax, procedures and methods, and to explain the protocol for
2469 customizing such invocations.
2471 A generic function invocation is customizable if the types of the arguments
2472 to which it is applied are not all determined by the lexical context in
2473 which the invocation appears. For example,
2477 the @code{(initialize @var{instance} @var{initargs})} invocation in the
2478 default @code{make-instance} method is customizable, because the type of the
2479 @code{@var{instance}} argument is determined by the class that was passed to
2480 @code{make-instance}.
2483 the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
2484 is not customizable, because all of its arguments have lexically determined
2488 When using this rule to decide whether a given generic function invocation
2489 is customizable, we ignore arguments that are expected to be handled in
2490 method definitions as a single ``rest'' list argument.
2492 For each customizable generic function invocation, the @dfn{invocation
2493 protocol} is explained by specifying
2497 what, conceptually, the applied method is intended to do
2500 what assumptions, if any, the caller makes about the applied method's side
2504 what the caller expects to get as the applied method's return value.
2508 * Class Definition::
2509 * Instance Creation::
2510 * Class Redefinition::
2511 * Method Definition::
2512 * Generic Function Invocation::
2515 @node Class Definition
2516 @subsection Class Definition
2518 @code{define-class} (syntax)
2522 @code{class} (syntax)
2526 @code{make-class} (procedure)
2530 @code{make @var{metaclass} @dots{}} (generic)
2532 @var{metaclass} is the metaclass of the class being defined, either
2533 taken from the @code{#:metaclass} class option or computed by
2534 @code{ensure-metaclass}. The applied method must create and return the
2535 fully initialized class metaobject for the new class definition.
2541 @code{class-redefinition @var{old-class} @var{new-class}} (generic)
2543 @code{define-class} calls @code{class-redefinition} if the variable
2544 specified by its first argument already held a GOOPS class definition.
2545 @var{old-class} and @var{new-class} are the old and new class metaobjects.
2546 The applied method should perform whatever is necessary to handle the
2547 redefinition, and should return the class metaobject that is to be bound
2548 to @code{define-class}'s variable. The default class redefinition
2549 protocol is described in @ref{Class Redefinition}.
2552 The @code{(make @var{metaclass} @dots{})} invocation above will create
2553 an class metaobject with metaclass @var{metaclass}. By default, this
2554 metaobject will be initialized by the @code{initialize} method that is
2555 specialized for instances of type @code{<class>}.
2557 @code{initialize <class> @var{initargs}} (method)
2561 @code{compute-cpl @var{class}} (generic)
2563 The applied method should compute and return the class precedence list
2564 for @var{class} as a list of class metaobjects. When @code{compute-cpl}
2565 is called, the following @var{class} metaobject slots have all been
2566 initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
2567 @code{direct-subclasses} (empty), @code{direct-methods}. The value
2568 returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
2571 @code{compute-slots @var{class}} (generic)
2573 The applied method should compute and return the slots (union of direct
2574 and inherited) for @var{class} as a list of slot definitions. When
2575 @code{compute-slots} is called, all the @var{class} metaobject slots
2576 mentioned for @code{compute-cpl} have been initialized, plus the
2577 following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
2578 The value returned by @code{compute-slots} will be stored in the
2582 @code{compute-get-n-set @var{class} @var{slot-def}} (generic)
2584 @code{initialize} calls @code{compute-get-n-set} for each slot computed
2585 by @code{compute-slots}. The applied method should compute and return a
2586 pair of closures that, respectively, get and set the value of the specified
2587 slot. The get closure should have arity 1 and expect a single argument
2588 that is the instance whose slot value is to be retrieved. The set closure
2589 should have arity 2 and expect two arguments, where the first argument is
2590 the instance whose slot value is to be set and the second argument is the
2591 new value for that slot. The closures should be returned in a two element
2592 list: @code{(list @var{get} @var{set})}.
2594 The closures returned by @code{compute-get-n-set} are stored as part of
2595 the value of the @var{class} metaobject's @code{getters-n-setters} slot.
2596 Specifically, the value of this slot is a list with the same number of
2597 elements as there are slots in the class, and each element looks either like
2600 @code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
2606 @code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
2609 Where the get and set closures are replaced by @var{index}, the slot is
2610 an instance slot and @var{index} is the slot's index in the underlying
2611 structure: GOOPS knows how to get and set the value of such slots and so
2612 does not need specially constructed get and set closures. Otherwise,
2613 @var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
2615 The structure of the @code{getters-n-setters} slot value is important when
2616 understanding the next customizable generic functions that @code{initialize}
2620 @code{compute-getter-method @var{class} @var{gns}} (generic)
2622 @code{initialize} calls @code{compute-getter-method} for each of the class's
2623 slots (as determined by @code{compute-slots}) that includes a
2624 @code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
2625 element of the @var{class} metaobject's @code{getters-n-setters} slot that
2626 specifies how the slot in question is referenced and set, as described
2627 above under @code{compute-get-n-set}. The applied method should create
2628 and return a method that is specialized for instances of type @var{class}
2629 and uses the get closure to retrieve the slot's value. [ *fixme Need
2630 to insert something here about checking that the value is not unbound. ]
2631 @code{initialize} uses @code{add-method!} to add the returned method to
2632 the generic function named by the slot definition's @code{#:getter} or
2633 @code{#:accessor} option.
2636 @code{compute-setter-method @var{class} @var{gns}} (generic)
2638 @code{compute-setter-method} is invoked with the same arguments as
2639 @code{compute-getter-method}, for each of the class's slots that includes
2640 a @code{#:setter} or @code{#:accessor} slot option. The applied method
2641 should create and return a method that is specialized for instances of
2642 type @var{class} and uses the set closure to set the slot's value.
2643 @code{initialize} then uses @code{add-method!} to add the returned method
2644 to the generic function named by the slot definition's @code{#:setter}
2645 or @code{#:accessor} option.
2648 @node Instance Creation
2649 @subsection Instance Creation
2651 @code{make <class> . @var{initargs}} (method)
2655 @code{allocate-instance @var{class} @var{initargs}} (generic)
2657 The applied @code{allocate-instance} method should allocate storage for
2658 a new instance of class @var{class} and return the uninitialized instance.
2661 @code{initialize @var{instance} @var{initargs}} (generic)
2663 @var{instance} is the uninitialized instance returned by
2664 @code{allocate-instance}. The applied method should initialize the new
2665 instance in whatever sense is appropriate for its class. The method's
2666 return value is ignored.
2669 @node Class Redefinition
2670 @subsection Class Redefinition
2672 The default @code{class-redefinition} method, specialized for classes
2673 with the default metaclass @code{<class>}, has the following internal
2676 @code{class-redefinition (@var{old <class>}) (@var{new <class>})}
2681 @code{remove-class-accessors! @var{old}} (generic)
2684 @code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
2687 @code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
2690 This protocol cleans up things that the definition of the old class
2691 once changed and modifies things to work with the new class.
2693 The default @code{remove-class-accessors!} method removes the
2694 accessor methods of the old class from all classes which they
2697 The default @code{update-direct-method!} method substitutes the new
2698 class for the old in all methods specialized to the old class.
2700 The default @code{update-direct-subclass!} method invokes
2701 @code{class-redefinition} recursively to handle the redefinition of
2704 When a class is redefined, any existing instance of the redefined class
2705 will be modified for the new class definition before the next time that
2706 any of the instance's slot is referenced or set. GOOPS modifies each
2707 instance by calling the generic function @code{change-class}.
2709 The default @code{change-class} method copies slot values from the old
2710 to the modified instance, and initializes new slots, as described in
2711 @ref{Changing the Class of an Instance}. After doing so, it makes a
2712 generic function invocation that can be used to customize the instance
2715 @code{change-class (@var{old-instance <object>}) (@var{new <class>})} (method)
2719 @code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
2721 @code{change-class} invokes @code{update-instance-for-different-class}
2722 as the last thing that it does before returning. The applied method can
2723 make any further adjustments to @var{new-instance} that are required to
2724 complete or modify the change of class. The return value from the
2725 applied method is ignored.
2727 The default @code{update-instance-for-different-class} method does
2731 @node Method Definition
2732 @subsection Method Definition
2734 @code{define-method} (syntax)
2738 @code{add-method! @var{target} @var{method}} (generic)
2740 @code{define-method} invokes the @code{add-method!} generic function to
2741 handle adding the new method to a variety of possible targets. GOOPS
2742 includes methods to handle @var{target} as
2746 a generic function (the most common case)
2752 a primitive generic (@pxref{Extending Guiles Primitives})
2755 By defining further methods for @code{add-method!}, you can
2756 theoretically handle adding methods to further types of target.
2759 @node Generic Function Invocation
2760 @subsection Generic Function Invocation
2762 [ *fixme* Description required here. ]
2764 @code{apply-generic}
2771 @code{compute-applicable-methods}
2774 @code{sort-applicable-methods}
2777 @code{apply-methods}
2780 @code{no-applicable-method}
2783 @code{sort-applicable-methods}
2787 @code{method-more-specific?}
2790 @code{apply-methods}
2801 @code{no-next-method}
2806 @include goops-tutorial.texi