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.
29 @goops{} is the object oriented extension to @guile{}. Its
30 implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
31 version 1.3 of Gregor Kiczales @cite{Tiny-Clos}. It is very close in
32 spirit to CLOS, the Common Lisp Object System (@cite{CLtL2}) but is
33 adapted for the Scheme language. While GOOPS is not compatible with any
34 of these systems, GOOPS contains a compatibility module which allows for
35 execution of STKlos programs.
37 Briefly stated, the @goops{} extension gives the user a full object
38 oriented system with multiple inheritance and generic functions with
39 multi-method dispatch. Furthermore, the implementation relies on a true
40 meta object protocol, in the spirit of the one defined for CLOS
41 (@cite{Gregor Kiczales: A Metaobject Protocol}).
44 @section Getting Started
49 Examples of some basic GOOPS functionality.
52 * User-defined types::
53 * Asking for the type of an object::
55 See further in the GOOPS tutorial available in this distribution in
56 info (goops.info) and texinfo format.
60 @subsection Running GOOPS
70 You should now be at the Guile prompt ("guile> ").
76 (use-modules (oop goops))
79 to load GOOPS. (If your system supports dynamic loading, you
80 should be able to do this not only from `guile-oops' but from an
81 arbitrary Guile interpreter.)
84 We're now ready to try some basic GOOPS functionality.
91 (define-method (+ (x <string>) (y <string>))
95 (+ "abc" "de") --> "abcde"
99 @node User-defined types
100 @subsection User-defined types
103 (define-class <2D-vector> ()
104 (x #:init-value 0 #:accessor x-component #:init-keyword #:x)
105 (y #:init-value 0 #:accessor y-component #:init-keyword #:y))
108 (use-modules (ice-9 format))
110 (define-method (write (obj <2D-vector>) port)
111 (display (format #f "<~S, ~S>" (x-component obj) (y-component obj))
114 (define v (make <2D-vector> #:x 3 #:y 4))
120 (define-method (+ (x <2D-vector>) (y <2D-vector>))
122 #:x (+ (x-component x) (x-component y))
123 #:y (+ (y-component x) (y-component y))))
129 @node Asking for the type of an object
133 (class-of v) --> #<<class> <2D-vector> 40241ac0>
134 <2D-vector> --> #<<class> <2D-vector> 40241ac0>
135 (class-of 1) --> #<<class> <integer> 401b2a98>
136 <integer> --> #<<class> <integer> 401b2a98>
138 (is-a? v <2D-vector>) --> #t
141 @node Reference Manual
142 @section Reference Manual
144 This chapter is the GOOPS reference manual. It aims to describe all the
145 syntax, procedures, options and associated concepts that a typical
146 application author would need to understand in order to use GOOPS
147 effectively in their application. It also describes what is meant by
148 the GOOPS ``metaobject protocol'' (aka ``MOP''), and indicates how
149 authors can use the metaobject protocol to customize the behaviour of
152 For a detailed specification of the GOOPS metaobject protocol, see
153 @ref{MOP Specification}.
156 * Introductory Remarks::
157 * Defining New Classes::
158 * Creating Instances::
160 * Creating Generic Functions::
161 * Adding Methods to Generic Functions::
162 * Invoking Generic Functions::
163 * Redefining a Class::
164 * Changing the Class of an Instance::
166 * Miscellaneous Functions::
169 @node Introductory Remarks
170 @subsection Introductory Remarks
172 GOOPS is an object-oriented programming system based on a ``metaobject
173 protocol'' derived from the ones used in CLOS (the Common Lisp Object
174 System), tiny-clos (a small Scheme implementation of a subset of CLOS
175 functionality) and STKlos.
177 GOOPS can be used by application authors at a basic level without any
178 need to understand what the metaobject protocol (aka ``MOP'') is and how
179 it works. On the other hand, the MOP underlies even the customizations
180 that application authors are likely to make use of very quickly --- such
181 as defining an @code{initialize} method to customize the initialization
182 of instances of an application-defined class --- and an understanding of
183 the MOP makes it much easier to explain such customizations in a precise
184 way. And in the long run, understanding the MOP is the key both to
185 understanding GOOPS at a deeper level and to taking full advantage of
186 GOOPS' power, by customizing the behaviour of GOOPS itself.
188 Each of the following sections of the reference manual is arranged
189 such that the most basic usage is introduced first, and then subsequent
190 subsubsections discuss the related internal functions and metaobject
191 protocols, finishing with a description of how to customize that area of
194 These introductory remarks continue with a few words about metaobjects
195 and the MOP. Readers who do not want to be bothered yet with the MOP
196 and customization could safely skip this subsubsection on a first reading,
197 and should correspondingly skip subsequent subsubsections that are
198 concerned with internals and customization.
200 In general, this reference manual assumes familiarity with standard
201 object oriented concepts and terminology. However, some of the terms
202 used in GOOPS are less well known, so the Terminology subsubsection
203 provides definitions for these terms.
206 * Metaobjects and the Metaobject Protocol::
210 @node Metaobjects and the Metaobject Protocol
211 @subsubsection Metaobjects and the Metaobject Protocol
213 The conceptual building blocks of GOOPS are classes, slot definitions,
214 instances, generic functions and methods. A class is a grouping of
215 inheritance relations and slot definitions. An instance is an object
216 with slots that are allocated following the rules implied by its class's
217 superclasses and slot definitions. A generic function is a collection
218 of methods and rules for determining which of those methods to apply
219 when the generic function is invoked. A method is a procedure and a set
220 of specializers that specify the type of arguments to which the
221 procedure is applicable.
223 Of these entities, GOOPS represents classes, generic functions and
224 methods as ``metaobjects''. In other words, the values in a GOOPS
225 program that describe classes, generic functions and methods, are
226 themselves instances (or ``objects'') of special GOOPS classes that
227 encapsulate the behaviour, respectively, of classes, generic functions,
230 (The other two entities are slot definitions and instances. Slot
231 definitions are not strictly instances, but every slot definition is
232 associated with a GOOPS class that specifies the behaviour of the slot
233 as regards accessibility and protection from garbage collection.
234 Instances are of course objects in the usual sense, and there is no
235 benefit from thinking of them as metaobjects.)
237 The ``metaobject protocol'' (aka ``MOP'') is the specification of the
238 generic functions which determine the behaviour of these metaobjects and
239 the circumstances in which these generic functions are invoked.
241 For a concrete example of what this means, consider how GOOPS calculates
242 the set of slots for a class that is being defined using
243 @code{define-class}. The desired set of slots is the union of the new
244 class's direct slots and the slots of all its superclasses. But
245 @code{define-class} itself does not perform this calculation. Instead,
246 there is a method of the @code{initialize} generic function that is
247 specialized for instances of type @code{<class>}, and it is this method
248 that performs the slot calculation.
250 @code{initialize} is a generic function which GOOPS calls whenever a new
251 instance is created, immediately after allocating memory for a new
252 instance, in order to initialize the new instance's slots. The sequence
253 of steps is as follows.
257 @code{define-class} uses @code{make} to make a new instance of the
258 @code{<class>}, passing as initialization arguments the superclasses,
259 slot definitions and class options that were specified in the
260 @code{define-class} form.
263 @code{make} allocates memory for the new instance, and then invokes the
264 @code{initialize} generic function to initialize the new instance's
268 The @code{initialize} generic function applies the method that is
269 specialized for instances of type @code{<class>}, and this method
270 performs the slot calculation.
273 In other words, rather than being hardcoded in @code{define-class}, the
274 behaviour of class definition is encapsulated by generic function
275 methods that are specialized for the class @code{<class>}.
277 It is possible to create a new class that inherits from @code{<class>},
278 which is called a ``metaclass'', and to write a new @code{initialize}
279 method that is specialized for instances of the new metaclass. Then, if
280 the @code{define-class} form includes a @code{#:metaclass} class option
281 whose value is the new metaclass, the class that is defined by the
282 @code{define-class} form will be an instance of the new metaclass rather
283 than of the default @code{<class>}, and will be defined in accordance
284 with the new @code{initialize} method. Thus the default slot
285 calculation, as well as any other aspect of the new class's relationship
286 with its superclasses, can be modified or overridden.
288 In a similar way, the behaviour of generic functions can be modified or
289 overridden by creating a new class that inherits from the standard
290 generic function class @code{<generic>}, writing appropriate methods
291 that are specialized to the new class, and creating new generic
292 functions that are instances of the new class.
294 The same is true for method metaobjects. And the same basic mechanism
295 allows the application class author to write an @code{initialize} method
296 that is specialized to their application class, to initialize instances
299 Such is the power of the MOP. Note that @code{initialize} is just one
300 of a large number of generic functions that can be customized to modify
301 the behaviour of application objects and classes and of GOOPS itself.
302 Each subsequent section of the reference manual covers a particular area
303 of GOOPS functionality, and describes the generic functions that are
304 relevant for customization of that area.
306 We conclude this subsubsection by emphasizing a point that may seem
307 obvious, but contrasts with the corresponding situation in some other
308 MOP implementations, such as CLOS. The point is simply that an
309 identifier which represents a GOOPS class or generic function is a
310 variable with a first-class value, the value being an instance of class
311 @code{<class>} or @code{<generic>}. (In CLOS, on the other hand, a
312 class identifier is a symbol that indexes the corresponding class
313 metaobject in a separate namespace for classes.) This is, of course,
314 simply an extension of the tendency in Scheme to avoid the unnecessary
315 use of, on the one hand, syntactic forms that require unevaluated
316 arguments and, on the other, separate identifier namespaces (e.g. for
317 class names), but it is worth noting that GOOPS conforms fully to this
321 @subsubsection Terminology
323 It is assumed that the reader is already familiar with standard object
324 orientation concepts such as classes, objects/instances,
325 inheritance/subclassing, generic functions and methods, encapsulation
328 This section explains some of the less well known concepts and
329 terminology that GOOPS uses, which are assumed by the following sections
330 of the reference manual.
332 @subsubheading Metaclass
334 A @dfn{metaclass} is the class of an object which represents a GOOPS
335 class. Put more succinctly, a metaclass is a class's class.
337 Most GOOPS classes have the metaclass @code{<class>} and, by default,
338 any new class that is created using @code{define-class} has the
339 metaclass @code{<class>}.
341 But what does this really mean? To find out, let's look in more detail
342 at what happens when a new class is created using @code{define-class}:
345 (define-class <my-class> (<object>) . slots)
348 GOOPS actually expands the @code{define-class} form to something like
352 (define <my-class> (class (<object>) . slots))
359 (make <class> #:supers (list <object>) #:slots slots))
362 In other words, the value of @code{<my-class>} is in fact an instance of
363 the class @code{<class>} with slot values specifying the superclasses
364 and slot definitions for the class @code{<my-class>}. (@code{#:supers}
365 and @code{#:slots} are initialization keywords for the @code{dsupers}
366 and @code{dslots} slots of the @code{<class>} class.)
368 In order to take advantage of the full power of the GOOPS metaobject
369 protocol (@pxref{MOP Specification}), it is sometimes desirable to
370 create a new class with a metaclass other than the default
371 @code{<class>}. This is done by writing:
374 (define-class <my-class2> (<object>)
376 #:metaclass <my-metaclass>)
379 GOOPS expands this to something like:
383 (make <my-metaclass> #:supers (list <object>) #:slots slots))
386 In this case, the value of @code{<my-class2>} is an instance of the more
387 specialized class @code{<my-metaclass>}. Note that
388 @code{<my-metaclass>} itself must previously have been defined as a
389 subclass of @code{<class>}. For a full discussion of when and how it is
390 useful to define new metaclasses, see @ref{MOP Specification}.
392 Now let's make an instance of @code{<my-class2>}:
395 (define my-object (make <my-class2> ...))
398 All of the following statements are correct expressions of the
399 relationships between @code{my-object}, @code{<my-class2>},
400 @code{<my-metaclass>} and @code{<class>}.
404 @code{my-object} is an instance of the class @code{<my-class2>}.
407 @code{<my-class2>} is an instance of the class @code{<my-metaclass>}.
410 @code{<my-metaclass>} is an instance of the class @code{<class>}.
413 The class of @code{my-object} is @code{<my-class2>}.
416 The metaclass of @code{my-object} is @code{<my-metaclass>}.
419 The class of @code{<my-class2>} is @code{<my-metaclass>}.
422 The metaclass of @code{<my-class2>} is @code{<class>}.
425 The class of @code{<my-metaclass>} is @code{<class>}.
428 The metaclass of @code{<my-metaclass>} is @code{<class>}.
431 @code{<my-class2>} is not a metaclass, since it is does not inherit from
435 @code{<my-metaclass>} is a metaclass, since it inherits from
439 @subsubheading Class Precedence List
441 The @dfn{class precedence list} of a class is the list of all direct and
442 indirect superclasses of that class, including the class itself.
444 In the absence of multiple inheritance, the class precedence list is
445 ordered straightforwardly, beginning with the class itself and ending
448 For example, given this inheritance hierarchy:
451 (define-class <invertebrate> (<object>) @dots{})
452 (define-class <echinoderm> (<invertebrate>) @dots{})
453 (define-class <starfish> (<echinoderm>) @dots{})
456 the class precedence list of <starfish> would be
459 (<starfish> <echinoderm> <invertebrate> <object> <top>)
462 With multiple inheritance, the algorithm is a little more complicated.
463 A full description is provided by the GOOPS Tutorial: see @ref{Class
466 ``Class precedence list'' is often abbreviated, in documentation and
467 Scheme variable names, to @dfn{cpl}.
469 @subsubheading Accessor
471 An @dfn{accessor} is a generic function with both reference and setter
475 (define-accessor perimeter)
478 Reference methods for an accessor are defined in the same way as generic
482 (define-method (perimeter (s <square>))
483 (* 4 (side-length s)))
486 Setter methods for an accessor are defined by specifying ``(setter
487 <accessor-name>)'' as the first parameter of the @code{define-method}
491 (define-method ((setter perimeter) (s <square>) (n <number>))
492 (set! (side-length s) (/ n 4)))
495 Once an appropriate setter method has been defined in this way, it can
496 be invoked using the generalized @code{set!} syntax, as in:
499 (set! (perimeter s1) 18.3)
502 @node Defining New Classes
503 @subsection Defining New Classes
505 [ *fixme* Somewhere in this manual there needs to be an introductory
506 discussion about GOOPS classes, generic functions and methods, covering
510 how classes encapsulate related items of data in @dfn{slots}
513 why it is that, unlike in C++ and Java, a class does not encapsulate the
514 methods that act upon the class (at least not in the C++/Java sense)
517 how generic functions provide a more general solution that provides for
518 dispatch on all argument types, and avoids idiosyncracies like C++'s
522 how encapsulation in the sense of data- and code-hiding, or of
523 distinguishing interface from implementation, is treated in Guile as an
524 orthogonal concept to object orientation, and is the responsibility of
528 Some of this is covered in the Tutorial chapter, in @ref{Generic
529 functions and methods} - perhaps the best solution would be to expand
530 the discussion there. ]
533 * Basic Class Definition::
536 * Class Definition Internals::
537 * Customizing Class Definition::
538 * STKlos Compatibility::
541 @node Basic Class Definition
542 @subsubsection Basic Class Definition
544 New classes are defined using the @code{define-class} syntax, with
545 arguments that specify the classes that the new class should inherit
546 from, the direct slots of the new class, and any required class options.
548 @deffn syntax define-class name (super @dots{}) slot-definition @dots{} . options
549 Define a class called @var{name} that inherits from @var{super}s, with
550 direct slots defined by @var{slot-definition}s and class options
551 @var{options}. The newly created class is bound to the variable name
552 @var{name} in the current environment.
554 Each @var{slot-definition} is either a symbol that names the slot or a
558 (@var{slot-name-symbol} . @var{slot-options})
561 where @var{slot-name-symbol} is a symbol and @var{slot-options} is a
562 list with an even number of elements. The even-numbered elements of
563 @var{slot-options} (counting from zero) are slot option keywords; the
564 odd-numbered elements are the corresponding values for those keywords.
566 @var{options} is a similarly structured list containing class option
567 keywords and corresponding values.
570 The standard GOOPS class and slot options are described in the following
571 subsubsections: see @ref{Class Options} and @ref{Slot Options}.
573 Example 1. Define a class that combines two pre-existing classes by
574 inheritance but adds no new slots.
577 (define-class <combined> (<tree> <bicycle>))
580 Example 2. Define a @code{regular-polygon} class with slots for side
581 length and number of sides that have default values and can be accessed
582 via the generic functions @code{side-length} and @code{num-sides}.
585 (define-class <regular-polygon> ()
586 (sl #:init-value 1 #:accessor side-length)
587 (ns #:init-value 5 #:accessor num-sides))
590 Example 3. Define a class whose behavior (and that of its instances) is
591 customized via an application-defined metaclass.
594 (define-class <tcpip-fsm> ()
595 (s #:init-value #f #:accessor state)
597 #:metaclass <finite-state-class>)
601 @subsubsection Class Options
603 @deffn {class option} #:metaclass metaclass
604 The @code{#:metaclass} class option specifies the metaclass of the class
605 being defined. @var{metaclass} must be a class that inherits from
606 @code{<class>}. For an introduction to the use of metaclasses, see
607 @ref{Metaobjects and the Metaobject Protocol} and @ref{Terminology}.
609 If the @code{#:metaclass} option is absent, GOOPS reuses or constructs a
610 metaclass for the new class by calling @code{ensure-metaclass}
611 (@pxref{Class Definition Internals,, ensure-metaclass}).
614 @deffn {class option} #:name name
615 The @code{#:name} class option specifies the new class's name. This
616 name is used to identify the class whenever related objects - the class
617 itself, its instances and its subclasses - are printed.
619 If the @code{#:name} option is absent, GOOPS uses the first argument to
620 @code{define-class} as the class name.
623 @deffn {class option} #:environment environment
624 *fixme* Not sure about this one, but I think that the
625 @code{#:environment} option specifies the environment in which the
626 class's getters and setters are computed and evaluated.
628 If the @code{#:environment} option is not specified, the class's
629 environment defaults to the top-level environment in which the
630 @code{define-class} form appears.
634 @subsubsection Slot Options
636 @deffn {slot option} #:allocation allocation
637 The @code{#:allocation} option tells GOOPS how to allocate storage for
638 the slot. Possible values for @var{allocation} are
641 @item @code{#:instance}
643 Indicates that GOOPS should create separate storage for this slot in
644 each new instance of the containing class (and its subclasses).
648 Indicates that GOOPS should create storage for this slot that is shared
649 by all instances of the containing class (and its subclasses). In other
650 words, a slot in class @var{C} with allocation @code{#:class} is shared
651 by all @var{instance}s for which @code{(is-a? @var{instance} @var{c})}.
653 @item @code{#:each-subclass}
655 Indicates that GOOPS should create storage for this slot that is shared
656 by all @emph{direct} instances of the containing class, and that
657 whenever a subclass of the containing class is defined, GOOPS should
658 create a new storage for the slot that is shared by all @emph{direct}
659 instances of the subclass. In other words, a slot with allocation
660 @code{#:each-subclass} is shared by all instances with the same
663 @item @code{#:virtual}
665 Indicates that GOOPS should not allocate storage for this slot. The
666 slot definition must also include the @code{#:slot-ref} and
667 @code{#:slot-set!} options to specify how to reference and set the value
671 The default value is @code{#:instance}.
673 Slot allocation options are processed when defining a new class by the
674 generic function @code{compute-get-n-set}, which is specialized by the
675 class's metaclass. Hence new types of slot allocation can be
676 implemented by defining a new metaclass and a method for
677 @code{compute-get-n-set} that is specialized for the new metaclass. For
678 an example of how to do this, see @ref{Customizing Class Definition}.
681 @deffn {slot option} #:slot-ref getter
682 @deffnx {slot option} #:slot-set! setter
683 The @code{#:slot-ref} and @code{#:slot-set!} options must be specified
684 if the slot allocation is @code{#:virtual}, and are ignored otherwise.
686 @var{getter} should be a closure taking a single @var{instance} parameter
687 that returns the current slot value. @var{setter} should be a closure
688 taking two parameters - @var{instance} and @var{new-val} - that sets the
689 slot value to @var{new-val}.
692 @deffn {slot option} #:getter getter
693 @deffnx {slot option} #:setter setter
694 @deffnx {slot option} #:accessor accessor
695 These options, if present, tell GOOPS to create generic function and
696 method definitions that can be used to get and set the slot value more
697 conveniently than by using @code{slot-ref} and @code{slot-set!}.
699 @var{getter} specifies a generic function to which GOOPS will add a
700 method for getting the slot value. @var{setter} specifies a generic
701 function to which GOOPS will add a method for setting the slot value.
702 @var{accessor} specifies an accessor to which GOOPS will add methods for
703 both getting and setting the slot value.
705 So if a class includes a slot definition like this:
708 (c #:getter get-count #:setter set-count #:accessor count)
711 GOOPS defines generic function methods such that the slot value can be
712 referenced using either the getter or the accessor -
715 (let ((current-count (get-count obj))) @dots{})
716 (let ((current-count (count obj))) @dots{})
719 - and set using either the setter or the accessor -
722 (set-count obj (+ 1 current-count))
723 (set! (count obj) (+ 1 current-count))
730 with an accessor, the slot value is set using the generalized
734 in practice, it is unusual for a slot to use all three of these options:
735 read-only, write-only and read-write slots would typically use only
736 @code{#:getter}, @code{#:setter} and @code{#:accessor} options
740 If the specified names are already bound in the top-level environment to
741 values that cannot be upgraded to generic functions, those values are
742 overwritten during evaluation of the @code{define-class} that contains
743 the slot definition. For details, see @ref{Generic Function Internals,,
747 @deffn {slot option} #:init-value init-value
748 @deffnx {slot option} #:init-form init-form
749 @deffnx {slot option} #:init-thunk init-thunk
750 @deffnx {slot option} #:init-keyword init-keyword
751 These options provide various ways to specify how to initialize the
752 slot's value at instance creation time. @var{init-value} is a fixed
753 value (shared across all new instances of the class).
754 @var{init-thunk} is a procedure of no arguments that is called
755 when a new instance is created and should return the desired initial
756 slot value. @var{init-form} is an unevaluated expression that gets
757 evaluated when a new instance is created and should return the desired
758 initial slot value. @var{init-keyword} is a keyword that can be used
759 to pass an initial slot value to @code{make} when creating a new
762 Note that, since an @code{init-value} value is shared across all
763 instances of a class, you should only use it when the initial value is
764 an immutable value, like a constant. If you want to initialize a slot
765 with a fresh, independently mutable value, you should use
766 @code{init-thunk} or @code{init-form} instead. Consider the following
770 (define-class <chbouib> ()
771 (hashtab #:init-value (make-hash-table)))
775 Here only one hash table is created and all instances of
776 @code{<chbouib>} have their @code{hashtab} slot refer to it. In order
777 to have each instance of @code{<chbouib>} refer to a new hash table, you
778 should instead write:
781 (define-class <chbouib> ()
782 (hashtab #:init-thunk make-hash-table))
789 (define-class <chbouib> ()
790 (hashtab #:init-form (make-hash-table)))
793 If more than one of these options is specified for the same slot, the
794 order of precedence, highest first is
798 @code{#:init-keyword}, if @var{init-keyword} is present in the options
799 passed to @code{make}
802 @code{#:init-thunk}, @code{#:init-form} or @code{#:init-value}.
805 If the slot definition contains more than one initialization option of
806 the same precedence, the later ones are ignored. If a slot is not
807 initialized at all, its value is unbound.
809 In general, slots that are shared between more than one instance are
810 only initialized at new instance creation time if the slot value is
811 unbound at that time. However, if the new instance creation specifies
812 a valid init keyword and value for a shared slot, the slot is
813 re-initialized regardless of its previous value.
815 Note, however, that the power of GOOPS' metaobject protocol means that
816 everything written here may be customized or overridden for particular
817 classes! The slot initializations described here are performed by the least
818 specialized method of the generic function @code{initialize}, whose
822 (define-method (initialize (object <object>) initargs) ...)
825 The initialization of instances of any given class can be customized by
826 defining a @code{initialize} method that is specialized for that class,
827 and the author of the specialized method may decide to call
828 @code{next-method} - which will result in a call to the next less
829 specialized @code{initialize} method - at any point within the
830 specialized code, or maybe not at all. In general, therefore, the
831 initialization mechanisms described here may be modified or overridden by
832 more specialized code, or may not be supported at all for particular
836 @node Class Definition Internals
837 @subsubsection Class Definition Internals
839 Implementation notes: @code{define-class} expands to an expression which
843 checks that it is being evaluated only at top level
846 defines any accessors that are implied by the @var{slot-definition}s
849 uses @code{class} to create the new class (@pxref{Class Definition
853 checks for a previous class definition for @var{name} and, if found,
854 handles the redefinition by invoking @code{class-redefinition}
855 (@pxref{Redefining a Class}).
858 @deffn syntax class name (super @dots{}) slot-definition @dots{} . options
859 Return a newly created class that inherits from @var{super}s, with
860 direct slots defined by @var{slot-definition}s and class options
861 @var{options}. For the format of @var{slot-definition}s and
862 @var{options}, see @ref{Basic Class Definition,, define-class}.
865 Implementation notes: @code{class} expands to an expression which
869 processes the class and slot definition options to check that they are
870 well-formed, to convert the @code{#:init-form} option to an
871 @code{#:init-thunk} option, to supply a default environment parameter
872 (the current top-level environment) and to evaluate all the bits that
876 calls @code{make-class} to create the class with the processed and
877 evaluated parameters.
880 @deffn procedure make-class supers slots . options
881 Return a newly created class that inherits from @var{supers}, with
882 direct slots defined by @var{slots} and class options @var{options}.
883 For the format of @var{slots} and @var{options}, see @ref{Basic Class
884 Definition,, define-class}, except note that for @code{make-class},
885 @var{slots} and @var{options} are separate list parameters: @var{slots}
886 here is a list of slot definitions.
889 Implementation notes: @code{make-class}
893 adds @code{<object>} to the @var{supers} list if @var{supers} is empty
894 or if none of the classes in @var{supers} have @code{<object>} in their
895 class precedence list
898 defaults the @code{#:environment}, @code{#:name} and @code{#:metaclass}
899 options, if they are not specified by @var{options}, to the current
900 top-level environment, the unbound value, and @code{(ensure-metaclass
901 @var{supers})} respectively (@pxref{Class Definition Internals,,
905 checks for duplicate classes in @var{supers} and duplicate slot names in
906 @var{slots}, and signals an error if there are any duplicates
909 calls @code{make}, passing the metaclass as the first parameter and all
910 other parameters as option keywords with values.
913 @deffn procedure ensure-metaclass supers env
914 Return a metaclass suitable for a class that inherits from the list of
915 classes in @var{supers}. The returned metaclass is the union by
916 inheritance of the metaclasses of the classes in @var{supers}.
918 In the simplest case, where all the @var{supers} are straightforward
919 classes with metaclass @code{<class>}, the returned metaclass is just
922 For a more complex example, suppose that @var{supers} contained one
923 class with metaclass @code{<operator-class>} and one with metaclass
924 @code{<foreign-object-class>}. Then the returned metaclass would be a
925 class that inherits from both @code{<operator-class>} and
926 @code{<foreign-object-class>}.
928 If @var{supers} is the empty list, @code{ensure-metaclass} returns the
929 default GOOPS metaclass @code{<class>}.
931 GOOPS keeps a list of the metaclasses created by
932 @code{ensure-metaclass}, so that each required type of metaclass only
933 has to be created once.
935 The @code{env} parameter is ignored.
938 @deffn procedure ensure-metaclass-with-supers meta-supers
939 @code{ensure-metaclass-with-supers} is an internal procedure used by
940 @code{ensure-metaclass} (@pxref{Class Definition Internals,,
941 ensure-metaclass}). It returns a metaclass that is the union by
942 inheritance of the metaclasses in @var{meta-supers}.
945 The internals of @code{make}, which is ultimately used to create the new
946 class object, are described in @ref{Customizing Instance Creation},
947 which covers the creation and initialization of instances in general.
949 @node Customizing Class Definition
950 @subsubsection Customizing Class Definition
952 During the initialization of a new class, GOOPS calls a number of generic
953 functions with the newly allocated class instance as the first
954 argument. Specifically, GOOPS calls the generic function
958 (initialize @var{class} @dots{})
961 where @var{class} is the newly allocated class instance, and the default
962 @code{initialize} method for arguments of type @code{<class>} calls the
967 (compute-cpl @var{class})
970 (compute-slots @var{class})
973 (compute-get-n-set @var{class} @var{slot-def}), for each of the slot
974 definitions returned by @code{compute-slots}
977 (compute-getter-method @var{class} @var{slot-def}), for each of the
978 slot definitions returned by @code{compute-slots} that includes a
979 @code{#:getter} or @code{#:accessor} slot option
982 (compute-setter-method @var{class} @var{slot-def}), for each of the
983 slot definitions returned by @code{compute-slots} that includes a
984 @code{#:setter} or @code{#:accessor} slot option.
987 If the metaclass of the new class is something more specialized than the
988 default @code{<class>}, then the type of @var{class} in the calls above
989 is more specialized than @code{<class>}, and hence it becomes possible
990 to define generic function methods, specialized for the new class's
991 metaclass, that can modify or override the default behaviour of
992 @code{initialize}, @code{compute-cpl} or @code{compute-get-n-set}.
994 @code{compute-cpl} computes the class precedence list (``CPL'') for the
995 new class (@pxref{Class precedence list}), and returns it as a list of
996 class objects. The CPL is important because it defines a superclass
997 ordering that is used, when a generic function is invoked upon an
998 instance of the class, to decide which of the available generic function
999 methods is the most specific. Hence @code{compute-cpl} could be
1000 customized in order to modify the CPL ordering algorithm for all classes
1001 with a special metaclass.
1003 The default CPL algorithm is encapsulated by the @code{compute-std-cpl}
1004 procedure, which is in turn called by the default @code{compute-cpl}
1007 @deffn procedure compute-std-cpl class
1008 Compute and return the class precedence list for @var{class} according
1009 to the algorithm described in @ref{Class precedence list}.
1012 @code{compute-slots} computes and returns a list of all slot definitions
1013 for the new class. By default, this list includes the direct slot
1014 definitions from the @code{define-class} form, plus the slot definitions
1015 that are inherited from the new class's superclasses. The default
1016 @code{compute-slots} method uses the CPL computed by @code{compute-cpl}
1017 to calculate this union of slot definitions, with the rule that slots
1018 inherited from superclasses are shadowed by direct slots with the same
1019 name. One possible reason for customizing @code{compute-slots} would be
1020 to implement an alternative resolution strategy for slot name conflicts.
1022 @code{compute-get-n-set} computes the low-level closures that will be
1023 used to get and set the value of a particular slot, and returns them in
1024 a list with two elements.
1026 The closures returned depend on how storage for that slot is allocated.
1027 The standard @code{compute-get-n-set} method, specialized for classes of
1028 type @code{<class>}, handles the standard GOOPS values for the
1029 @code{#:allocation} slot option (@pxref{Slot Options,, allocation}). By
1030 defining a new @code{compute-get-n-set} method for a more specialized
1031 metaclass, it is possible to support new types of slot allocation.
1033 Suppose you wanted to create a large number of instances of some class
1034 with a slot that should be shared between some but not all instances of
1035 that class - say every 10 instances should share the same slot storage.
1036 The following example shows how to implement and use a new type of slot
1037 allocation to do this.
1040 (define-class <batched-allocation-metaclass> (<class>))
1042 (let ((batch-allocation-count 0)
1043 (batch-get-n-set #f))
1044 (define-method (compute-get-n-set (class <batched-allocation-metaclass>) s)
1045 (case (slot-definition-allocation s)
1047 ;; If we've already used the same slot storage for 10 instances,
1049 (if (= batch-allocation-count 10)
1051 (set! batch-allocation-count 0)
1052 (set! batch-get-n-set #f)))
1053 ;; If we don't have a current pair of get and set closures,
1054 ;; create one. make-closure-variable returns a pair of closures
1055 ;; around a single Scheme variable - see goops.scm for details.
1057 (set! batch-get-n-set (make-closure-variable)))
1058 ;; Increment the batch allocation count.
1059 (set! batch-allocation-count (+ batch-allocation-count 1))
1062 ;; Call next-method to handle standard allocation types.
1063 (else (next-method)))))
1065 (define-class <class-using-batched-slot> ()
1067 (c #:allocation #:batched)
1069 #:metaclass <batched-allocation-metaclass>)
1072 The usage of @code{compute-getter-method} and @code{compute-setter-method}
1073 is described in @ref{MOP Specification}.
1075 @code{compute-cpl} and @code{compute-get-n-set} are called by the
1076 standard @code{initialize} method for classes whose metaclass is
1077 @code{<class>}. But @code{initialize} itself can also be modified, by
1078 defining an @code{initialize} method specialized to the new class's
1079 metaclass. Such a method could complete override the standard
1080 behaviour, by not calling @code{(next-method)} at all, but more
1081 typically it would perform additional class initialization steps before
1082 and/or after calling @code{(next-method)} for the standard behaviour.
1084 @node STKlos Compatibility
1085 @subsubsection STKlos Compatibility
1087 If the STKlos compatibility module is loaded, @code{define-class} is
1088 overwritten by a STKlos-specific definition; the standard GOOPS
1089 definition of @code{define-class} remains available in
1090 @code{standard-define-class}.
1092 @deffn syntax standard-define-class name (super @dots{}) slot-definition @dots{} . options
1093 @code{standard-define-class} is equivalent to the standard GOOPS
1094 @code{define-class}.
1097 @node Creating Instances
1098 @subsection Creating Instances
1101 * Basic Instance Creation::
1102 * Customizing Instance Creation::
1105 @node Basic Instance Creation
1106 @subsubsection Basic Instance Creation
1108 To create a new instance of any GOOPS class, use the generic function
1109 @code{make} or @code{make-instance}, passing the required class and any
1110 appropriate instance initialization arguments as keyword and value
1111 pairs. Note that @code{make} and @code{make-instances} are aliases for
1112 each other - their behaviour is identical.
1115 @deffnx method make (class <class>) . initargs
1116 Create and return a new instance of class @var{class}, initialized using
1119 In theory, @var{initargs} can have any structure that is understood by
1120 whatever methods get applied when the @code{initialize} generic function
1121 is applied to the newly allocated instance.
1123 In practice, specialized @code{initialize} methods would normally call
1124 @code{(next-method)}, and so eventually the standard GOOPS
1125 @code{initialize} methods are applied. These methods expect
1126 @var{initargs} to be a list with an even number of elements, where
1127 even-numbered elements (counting from zero) are keywords and
1128 odd-numbered elements are the corresponding values.
1130 GOOPS processes initialization argument keywords automatically for slots
1131 whose definition includes the @code{#:init-keyword} option (@pxref{Slot
1132 Options,, init-keyword}). Other keyword value pairs can only be
1133 processed by an @code{initialize} method that is specialized for the new
1134 instance's class. Any unprocessed keyword value pairs are ignored.
1137 @deffn generic make-instance
1138 @deffnx method make-instance (class <class>) . initargs
1139 @code{make-instance} is an alias for @code{make}.
1142 @node Customizing Instance Creation
1143 @subsubsection Customizing Instance Creation
1145 @code{make} itself is a generic function. Hence the @code{make}
1146 invocation itself can be customized in the case where the new instance's
1147 metaclass is more specialized than the default @code{<class>}, by
1148 defining a @code{make} method that is specialized to that metaclass.
1150 Normally, however, the method for classes with metaclass @code{<class>}
1151 will be applied. This method calls two generic functions:
1155 (allocate-instance @var{class} . @var{initargs})
1158 (initialize @var{instance} . @var{initargs})
1161 @code{allocate-instance} allocates storage for and returns the new
1162 instance, uninitialized. You might customize @code{allocate-instance},
1163 for example, if you wanted to provide a GOOPS wrapper around some other
1164 object programming system.
1166 To do this, you would create a specialized metaclass, which would act as
1167 the metaclass for all classes and instances from the other system. Then
1168 define an @code{allocate-instance} method, specialized to that
1169 metaclass, which calls a Guile primitive C function, which in turn
1170 allocates the new instance using the interface of the other object
1173 In this case, for a complete system, you would also need to customize a
1174 number of other generic functions like @code{make} and
1175 @code{initialize}, so that GOOPS knows how to make classes from the
1176 other system, access instance slots, and so on.
1178 @code{initialize} initializes the instance that is returned by
1179 @code{allocate-instance}. The standard GOOPS methods perform
1180 initializations appropriate to the instance class.
1184 At the least specialized level, the method for instances of type
1185 @code{<object>} performs internal GOOPS instance initialization, and
1186 initializes the instance's slots according to the slot definitions and
1187 any slot initialization keywords that appear in @var{initargs}.
1190 The method for instances of type @code{<class>} calls
1191 @code{(next-method)}, then performs the class initializations described
1192 in @ref{Customizing Class Definition}.
1195 and so on for generic functions, method, operator classes @dots{}
1198 Similarly, you can customize the initialization of instances of any
1199 application-defined class by defining an @code{initialize} method
1200 specialized to that class.
1202 Imagine a class whose instances' slots need to be initialized at
1203 instance creation time by querying a database. Although it might be
1204 possible to achieve this a combination of @code{#:init-thunk} keywords
1205 and closures in the slot definitions, it is neater to write an
1206 @code{initialize} method for the class that queries the database once
1207 and initializes all the dependent slot values according to the results.
1209 @node Accessing Slots
1210 @subsection Accessing Slots
1212 The definition of a slot contains at the very least a slot name, and may
1213 also contain various slot options, including getter, setter and/or
1214 accessor functions for the slot.
1216 It is always possible to access slots by name, using the various
1217 ``slot-ref'' and ``slot-set!'' procedures described in the following
1218 subsubsections. For example,
1221 (define-class <my-class> () ;; Define a class with slots
1222 (count #:init-value 0) ;; named "count" and "cache".
1223 (cache #:init-value '())
1226 (define inst (make <my-class>)) ;; Make an instance of this class.
1228 (slot-set! inst 'count 5) ;; Set the value of the "count"
1231 (slot-set! inst 'cache ;; Modify the value of the
1232 (cons (cons "^it" "It") ;; "cache" slot.
1233 (slot-ref inst 'cache)))
1236 If a slot definition includes a getter, setter or accessor function,
1237 these can be used instead of @code{slot-ref} and @code{slot-set!} to
1241 (define-class <adv-class> () ;; Define a new class whose slots
1242 (count #:setter set-count) ;; use a getter, a setter and
1243 (cache #:accessor cache) ;; an accessor.
1244 (csize #:getter cache-size)
1247 (define inst (make <adv-class>)) ;; Make an instance of this class.
1249 (set-count inst 5) ;; Set the value of the "count"
1252 (set! (cache inst) ;; Modify the value of the
1253 (cons (cons "^it" "It") ;; "cache" slot.
1256 (let ((size (cache-size inst))) ;; Get the value of the "csize"
1260 Whichever of these methods is used to access slots, GOOPS always calls
1261 the low-level @dfn{getter} and @dfn{setter} closures for the slot to get
1262 and set its value. These closures make sure that the slot behaves
1263 according to the @code{#:allocation} type that was specified in the slot
1264 definition (@pxref{Slot Options,, allocation}). (For more about these
1265 closures, see @ref{Customizing Class Definition,, compute-get-n-set}.)
1270 * Handling Slot Access Errors::
1273 @node Instance Slots
1274 @subsubsection Instance Slots
1276 Any slot, regardless of its allocation, can be queried, referenced and
1277 set using the following four primitive procedures.
1279 @deffn {primitive procedure} slot-exists? obj slot-name
1280 Return @code{#t} if @var{obj} has a slot with name @var{slot-name},
1281 otherwise @code{#f}.
1284 @deffn {primitive procedure} slot-bound? obj slot-name
1285 Return @code{#t} if the slot named @var{slot-name} in @var{obj} has a
1286 value, otherwise @code{#f}.
1288 @code{slot-bound?} calls the generic function @code{slot-missing} if
1289 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1290 Slot Access Errors, slot-missing}).
1293 @deffn {primitive procedure} slot-ref obj slot-name
1294 Return the value of the slot named @var{slot-name} in @var{obj}.
1296 @code{slot-ref} calls the generic function @code{slot-missing} if
1297 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1298 Slot Access Errors, slot-missing}).
1300 @code{slot-ref} calls the generic function @code{slot-unbound} if the
1301 named slot in @var{obj} does not have a value (@pxref{Handling Slot
1302 Access Errors, slot-unbound}).
1305 @deffn {primitive procedure} slot-set! obj slot-name value
1306 Set the value of the slot named @var{slot-name} in @var{obj} to @var{value}.
1308 @code{slot-set!} calls the generic function @code{slot-missing} if
1309 @var{obj} does not have a slot called @var{slot-name} (@pxref{Handling
1310 Slot Access Errors, slot-missing}).
1313 GOOPS stores information about slots in class metaobjects. Internally,
1314 all of these procedures work by looking up the slot definition for the
1315 slot named @var{slot-name} in the class metaobject for @code{(class-of
1316 @var{obj})}, and then using the slot definition's ``getter'' and
1317 ``setter'' closures to get and set the slot value.
1319 The next four procedures differ from the previous ones in that they take
1320 the class metaobject as an explicit argument, rather than assuming
1321 @code{(class-of @var{obj})}. Therefore they allow you to apply the
1322 ``getter'' and ``setter'' closures of a slot definition in one class to
1323 an instance of a different class.
1325 [ *fixme* I have no idea why this is useful! Perhaps when a slot in
1326 @code{(class-of @var{obj})} shadows a slot with the same name in one of
1327 its superclasses? There should be an enlightening example here. ]
1329 @deffn {primitive procedure} slot-exists-using-class? class obj slot-name
1330 Return @code{#t} if the class metaobject @var{class} has a slot
1331 definition for a slot with name @var{slot-name}, otherwise @code{#f}.
1334 @deffn {primitive procedure} slot-bound-using-class? class obj slot-name
1335 Return @code{#t} if applying @code{slot-ref-using-class} to the same
1336 arguments would call the generic function @code{slot-unbound}, otherwise
1339 @code{slot-bound-using-class?} calls the generic function
1340 @code{slot-missing} if @var{class} does not have a slot definition for a
1341 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1345 @deffn {primitive procedure} slot-ref-using-class class obj slot-name
1346 Apply the ``getter'' closure for the slot named @var{slot-name} in
1347 @var{class} to @var{obj}, and return its result.
1349 @code{slot-ref-using-class} calls the generic function
1350 @code{slot-missing} if @var{class} does not have a slot definition for a
1351 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1354 @code{slot-ref-using-class} calls the generic function
1355 @code{slot-unbound} if the application of the ``getter'' closure to
1356 @var{obj} returns an unbound value (@pxref{Handling Slot Access Errors,
1360 @deffn {primitive procedure} slot-set-using-class! class obj slot-name value
1361 Apply the ``setter'' closure for the slot named @var{slot-name} in
1362 @var{class} to @var{obj} and @var{value}.
1364 @code{slot-set-using-class!} calls the generic function
1365 @code{slot-missing} if @var{class} does not have a slot definition for a
1366 slot called @var{slot-name} (@pxref{Handling Slot Access Errors,
1371 @subsubsection Class Slots
1373 Slots whose allocation is per-class rather than per-instance can be
1374 referenced and set without needing to specify any particular instance.
1376 @deffn procedure class-slot-ref class slot-name
1377 Return the value of the slot named @var{slot-name} in class @var{class}.
1378 The named slot must have @code{#:class} or @code{#:each-subclass}
1379 allocation (@pxref{Slot Options,, allocation}).
1381 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1382 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1383 function with arguments @var{class} and @var{slot-name}. Otherwise, if
1384 the slot value is unbound, @code{class-slot-ref} calls the
1385 @code{slot-missing} generic function, with the same arguments.
1388 @deffn procedure class-slot-set! class slot-name value
1389 Set the value of the slot named @var{slot-name} in class @var{class} to
1390 @var{value}. The named slot must have @code{#:class} or
1391 @code{#:each-subclass} allocation (@pxref{Slot Options,, allocation}).
1393 If there is no such slot with @code{#:class} or @code{#:each-subclass}
1394 allocation, @code{class-slot-ref} calls the @code{slot-missing} generic
1395 function with arguments @var{class} and @var{slot-name}.
1398 @node Handling Slot Access Errors
1399 @subsubsection Handling Slot Access Errors
1401 GOOPS calls one of the following generic functions when a ``slot-ref''
1402 or ``slot-set!'' call specifies a non-existent slot name, or tries to
1403 reference a slot whose value is unbound.
1405 @deffn generic slot-missing
1406 @deffnx method slot-missing (class <class>) slot-name
1407 @deffnx method slot-missing (class <class>) (object <object>) slot-name
1408 @deffnx method slot-missing (class <class>) (object <object>) slot-name value
1409 When an application attempts to reference or set a class or instance
1410 slot by name, and the slot name is invalid for the specified @var{class}
1411 or @var{object}, GOOPS calls the @code{slot-missing} generic function.
1413 The default methods all call @code{goops-error} with an appropriate
1417 @deffn generic slot-unbound
1418 @deffnx method slot-unbound (object <object>)
1419 @deffnx method slot-unbound (class <class>) slot-name
1420 @deffnx method slot-unbound (class <class>) (object <object>) slot-name
1421 When an application attempts to reference a class or instance slot, and
1422 the slot's value is unbound, GOOPS calls the @code{slot-unbound} generic
1425 The default methods all call @code{goops-error} with an appropriate
1429 @node Creating Generic Functions
1430 @subsection Creating Generic Functions
1432 A generic function is a collection of methods, with rules for
1433 determining which of the methods should be applied for any given
1434 invocation of the generic function.
1436 GOOPS represents generic functions as metaobjects of the class
1437 @code{<generic>} (or one of its subclasses).
1440 * Basic Generic Function Creation::
1441 * Generic Function Internals::
1442 * Extending Guiles Primitives::
1445 @node Basic Generic Function Creation
1446 @subsubsection Basic Generic Function Creation
1448 The following forms may be used to bind a variable to a generic
1449 function. Depending on that variable's pre-existing value, the generic
1450 function may be created empty - with no methods - or it may contain
1451 methods that are inferred from the pre-existing value.
1453 It is not, in general, necessary to use @code{define-generic} or
1454 @code{define-accessor} before defining methods for the generic function
1455 using @code{define-method}, since @code{define-method} will
1456 automatically interpolate a @code{define-generic} call, or upgrade an
1457 existing generic to an accessor, if that is implied by the
1458 @code{define-method} call. Note in particular that,
1459 if the specified variable already has a @emph{generic function} value,
1460 @code{define-generic} and @code{define-accessor} will @emph{discard} it!
1461 Obviously it is application-dependent whether this is desirable or not.
1463 If, for example, you wanted to extend @code{+} for a class representing
1464 a new numerical type, you probably want to inherit any existing methods
1465 for @code{+} and so should not use @code{define-generic}. If, on the
1466 other hand, you do not want to risk inheriting methods whose behaviour
1467 might surprise you, you can use @code{define-generic} or
1468 @code{define-accessor} to wipe the slate clean.
1470 @deffn syntax define-generic symbol
1471 Create a generic function with name @var{symbol} and bind it to the
1472 variable @var{symbol}.
1474 If the variable @var{symbol} was previously bound to a Scheme procedure
1475 (or procedure-with-setter), the old procedure (and setter) is
1476 incorporated into the new generic function as its default procedure (and
1477 setter). Any other previous value that was bound to @var{symbol},
1478 including an existing generic function, is overwritten by the new
1482 @deffn syntax define-accessor symbol
1483 Create an accessor with name @var{symbol} and bind it to the variable
1486 If the variable @var{symbol} was previously bound to a Scheme procedure
1487 (or procedure-with-setter), the old procedure (and setter) is
1488 incorporated into the new accessor as its default procedure (and
1489 setter). Any other previous value that was bound to @var{symbol},
1490 including an existing generic function or accessor, is overwritten by
1494 It is sometimes tempting to use GOOPS accessors with short names. For
1495 example, it is tempting to use the name @code{x} for the x-coordinate
1498 Assume that we work with a graphical package which needs to use two
1499 independent vector packages for 2D and 3D vectors respectively. If
1500 both packages export @code{x} we will encounter a name collision.
1502 This can be resolved automagically with the duplicates handler
1503 @code{merge-generics} which gives the module system license to merge
1504 all generic functions sharing a common name:
1507 (define-module (math 2D-vectors)
1508 :use-module (oop goops)
1511 (define-module (math 3D-vectors)
1512 :use-module (oop goops)
1513 :export (x y z ...))
1515 (define-module (my-module)
1516 :use-module (math 2D-vectors)
1517 :use-module (math 3D-vectors)
1518 :duplicates merge-generics)
1521 The generic function @code{x} in @code{(my-module)} will now share
1522 methods with @code{x} in both imported modules.
1524 There will, in fact, now be three distinct generic functions named
1525 @code{x}: @code{x} in @code{(2D-vectors)}, @code{x} in
1526 @code{(3D-vectors)}, and @code{x} in @code{(my-module)}. The last
1527 function will be an @code{<extended-generic>}, extending the previous
1530 Let's call the imported generic functions the "ancestor functions".
1531 The generic function @code{x} in @code{(my-module)} is, in turn, a
1532 "descendant function" of the imported functions, extending its
1535 For any generic function G, the applicable methods are selected from
1536 the union of the methods of the descendant functions, the methods of G
1537 itself and the methods of the ancestor functions.
1539 This, ancestor functions share methods with their descendants and vice
1540 versa. This implies that @code{x} in @code{(math 2D-vectors)} will
1541 share the methods of @code{x} in @code{(my-module)} and vice versa,
1542 while @code{x} in @code{(math 2D-vectors)} doesn't share the methods
1543 of @code{x} in @code{(math 3D-vectors)}, thus preserving modularity.
1545 Sharing is dynamic, so that adding new methods to a descendant implies
1546 adding it to the ancestor.
1548 If duplicates checking is desired in the above example, the following
1549 form of the @code{:duplicates} option can be used instead:
1552 :duplicates (merge-generics check)
1555 @node Generic Function Internals
1556 @subsubsection Generic Function Internals
1558 @code{define-generic} calls @code{ensure-generic} to upgrade a
1559 pre-existing procedure value, or @code{make} with metaclass
1560 @code{<generic>} to create a new generic function.
1562 @code{define-accessor} calls @code{ensure-accessor} to upgrade a
1563 pre-existing procedure value, or @code{make-accessor} to create a new
1566 @deffn procedure ensure-generic old-definition [name]
1567 Return a generic function with name @var{name}, if possible by using or
1568 upgrading @var{old-definition}. If unspecified, @var{name} defaults to
1571 If @var{old-definition} is already a generic function, it is returned
1574 If @var{old-definition} is a Scheme procedure or procedure-with-setter,
1575 @code{ensure-generic} returns a new generic function that uses
1576 @var{old-definition} for its default procedure and setter.
1578 Otherwise @code{ensure-generic} returns a new generic function with no
1579 defaults and no methods.
1582 @deffn procedure make-generic [name]
1583 Return a new generic function with name @code{(car @var{name})}. If
1584 unspecified, @var{name} defaults to @code{#f}.
1587 @code{ensure-generic} calls @code{make} with metaclasses
1588 @code{<generic>} and @code{<generic-with-setter>}, depending on the
1589 previous value of the variable that it is trying to upgrade.
1591 @code{make-generic} is a simple wrapper for @code{make} with metaclass
1594 @deffn procedure ensure-accessor proc [name]
1595 Return an accessor with name @var{name}, if possible by using or
1596 upgrading @var{proc}. If unspecified, @var{name} defaults to @code{#f}.
1598 If @var{proc} is already an accessor, it is returned unchanged.
1600 If @var{proc} is a Scheme procedure, procedure-with-setter or generic
1601 function, @code{ensure-accessor} returns an accessor that reuses the
1602 reusable elements of @var{proc}.
1604 Otherwise @code{ensure-accessor} returns a new accessor with no defaults
1608 @deffn procedure make-accessor [name]
1609 Return a new accessor with name @code{(car @var{name})}. If
1610 unspecified, @var{name} defaults to @code{#f}.
1613 @code{ensure-accessor} calls @code{make} with
1614 metaclass @code{<generic-with-setter>}, as well as calls to
1615 @code{ensure-generic}, @code{make-accessor} and (tail recursively)
1616 @code{ensure-accessor}.
1618 @code{make-accessor} calls @code{make} twice, first
1619 with metaclass @code{<generic>} to create a generic function for the
1620 setter, then with metaclass @code{<generic-with-setter>} to create the
1621 accessor, passing the setter generic function as the value of the
1622 @code{#:setter} keyword.
1624 @node Extending Guiles Primitives
1625 @subsubsection Extending Guile's Primitives
1627 When GOOPS is loaded, many of Guile's primitive procedures can be
1628 extended by giving them a generic function definition that operates
1629 in conjunction with their normal C-coded implementation. For
1630 primitives that are extended in this way, the result from the user-
1631 or application-level point of view is that the extended primitive
1632 behaves exactly like a generic function with the C-coded implementation
1633 as its default method.
1635 The @code{generic-capability?} predicate should be used to determine
1636 whether a particular primitive is extensible in this way.
1638 @deffn {primitive procedure} generic-capability? primitive
1639 Return @code{#t} if @var{primitive} can be extended by giving it a
1640 generic function definition, otherwise @code{#f}.
1643 Even when a primitive procedure is extensible like this, its generic
1644 function definition is not created until it is needed by a call to
1645 @code{define-method}, or until the application explicitly requests it
1646 by calling @code{enable-primitive-generic!}.
1648 @deffn {primitive procedure} enable-primitive-generic! primitive
1649 Force the creation of a generic function definition for
1653 Once the generic function definition for a primitive has been created,
1654 it can be retrieved using @code{primitive-generic-generic}.
1656 @deffn {primitive procedure} primitive-generic-generic primitive
1657 Return the generic function definition of @var{primitive}.
1659 @code{primitive-generic-generic} raises an error if @var{primitive}
1660 is not a primitive with generic capability, or if its generic capability
1661 has not yet been enabled, whether implicitly (by @code{define-method})
1662 or explicitly (by @code{enable-primitive-generic!}).
1665 Note that the distinction between, on the one hand, primitives with
1666 additional generic function definitions and, on the other hand, generic
1667 functions with a default method, may disappear when GOOPS is fully
1668 integrated into the core of Guile. Consequently, the
1669 procedures described in this section may disappear as well.
1671 @node Adding Methods to Generic Functions
1672 @subsection Adding Methods to Generic Functions
1675 * Basic Method Definition::
1676 * Method Definition Internals::
1679 @node Basic Method Definition
1680 @subsubsection Basic Method Definition
1682 To add a method to a generic function, use the @code{define-method} form.
1684 @deffn syntax define-method (generic parameter @dots{}) . body
1685 Define a method for the generic function or accessor @var{generic} with
1686 parameters @var{parameter}s and body @var{body}.
1688 @var{generic} is a generic function. If @var{generic} is a variable
1689 which is not yet bound to a generic function object, the expansion of
1690 @code{define-method} will include a call to @code{define-generic}. If
1691 @var{generic} is @code{(setter @var{generic-with-setter})}, where
1692 @var{generic-with-setter} is a variable which is not yet bound to a
1693 generic-with-setter object, the expansion will include a call to
1694 @code{define-accessor}.
1696 Each @var{parameter} must be either a symbol or a two-element list
1697 @code{(@var{symbol} @var{class})}. The symbols refer to variables in
1698 the @var{body} that will be bound to the parameters supplied by the
1699 caller when calling this method. The @var{class}es, if present,
1700 specify the possible combinations of parameters to which this method
1703 @var{body} is the body of the method definition.
1706 @code{define-method} expressions look a little like normal Scheme
1707 procedure definitions of the form
1710 (define (name formals @dots{}) . body)
1713 The most important difference is that each formal parameter, apart from the
1714 possible ``rest'' argument, can be qualified by a class name:
1715 @code{@var{formal}} becomes @code{(@var{formal} @var{class})}. The
1716 meaning of this qualification is that the method being defined
1717 will only be applicable in a particular generic function invocation if
1718 the corresponding argument is an instance of @code{@var{class}} (or one of
1719 its subclasses). If more than one of the formal parameters is qualified
1720 in this way, then the method will only be applicable if each of the
1721 corresponding arguments is an instance of its respective qualifying class.
1723 Note that unqualified formal parameters act as though they are qualified
1724 by the class @code{<top>}, which GOOPS uses to mean the superclass of
1725 all valid Scheme types, including both primitive types and GOOPS classes.
1727 For example, if a generic function method is defined with
1728 @var{parameter}s @code{((s1 <square>) (n <number>))}, that method is
1729 only applicable to invocations of its generic function that have two
1730 parameters where the first parameter is an instance of the
1731 @code{<square>} class and the second parameter is a number.
1733 If a generic function is invoked with a combination of parameters for which
1734 there is no applicable method, GOOPS raises an error. For more about
1735 invocation error handling, and generic function invocation in general,
1736 see @ref{Invoking Generic Functions}.
1738 @node Method Definition Internals
1739 @subsubsection Method Definition Internals
1741 @code{define-method}
1745 checks the form of the first parameter, and applies the following steps
1746 to the accessor's setter if it has the @code{(setter @dots{})} form
1749 interpolates a call to @code{define-generic} or @code{define-accessor}
1750 if a generic function is not already defined with the supplied name
1753 calls @code{method} with the @var{parameter}s and @var{body}, to make a
1757 calls @code{add-method!} to add this method to the relevant generic
1761 @deffn syntax method (parameter @dots{}) . body
1762 Make a method whose specializers are defined by the classes in
1763 @var{parameter}s and whose procedure definition is constructed from the
1764 @var{parameter} symbols and @var{body} forms.
1766 The @var{parameter} and @var{body} parameters should be as for
1767 @code{define-method} (@pxref{Basic Method Definition,, define-method}).
1774 extracts formals and specializing classes from the @var{parameter}s,
1775 defaulting the class for unspecialized parameters to @code{<top>}
1778 creates a closure using the formals and the @var{body} forms
1781 calls @code{make} with metaclass @code{<method>} and the specializers
1782 and closure using the @code{#:specializers} and @code{#:procedure}
1786 @deffn procedure make-method specializers procedure
1787 Make a method using @var{specializers} and @var{procedure}.
1789 @var{specializers} should be a list of classes that specifies the
1790 parameter combinations to which this method will be applicable.
1792 @var{procedure} should be the closure that will applied to the generic
1793 function parameters when this method is invoked.
1796 @code{make-method} is a simple wrapper around @code{make} with metaclass
1799 @deffn generic add-method! target method
1800 Generic function for adding method @var{method} to @var{target}.
1803 @deffn method add-method! (generic <generic>) (method <method>)
1804 Add method @var{method} to the generic function @var{generic}.
1807 @deffn method add-method! (proc <procedure>) (method <method>)
1808 If @var{proc} is a procedure with generic capability (@pxref{Extending
1809 Guiles Primitives,, generic-capability?}), upgrade it to a
1810 primitive generic and add @var{method} to its generic function
1814 @deffn method add-method! (pg <primitive-generic>) (method <method>)
1815 Add method @var{method} to the generic function definition of @var{pg}.
1817 Implementation: @code{(add-method! (primitive-generic-generic pg) method)}.
1820 @deffn method add-method! (whatever <top>) (method <method>)
1821 Raise an error indicating that @var{whatever} is not a valid generic
1825 @node Invoking Generic Functions
1826 @subsection Invoking Generic Functions
1828 When a variable with a generic function definition appears as the first
1829 element of a list that is being evaluated, the Guile evaluator tries
1830 to apply the generic function to the arguments obtained by evaluating
1831 the remaining elements of the list. [ *fixme* How do I put this in a
1832 more Schemely and less Lispy way? ]
1834 Usually a generic function contains several method definitions, with
1835 varying degrees of formal parameter specialization (@pxref{Basic
1836 Method Definition,, define-method}). So it is necessary to sort these
1837 methods by specificity with respect to the supplied arguments, and then
1838 apply the most specific method definition. Less specific methods
1839 may be applied subsequently if a method that is being applied calls
1843 * Determining Which Methods to Apply::
1844 * Handling Invocation Errors::
1847 @node Determining Which Methods to Apply
1848 @subsubsection Determining Which Methods to Apply
1850 [ *fixme* Sorry - this is the area of GOOPS that I understand least of
1851 all, so I'm afraid I have to pass on this section. Would some other
1852 kind person consider filling it in? ]
1854 @deffn generic apply-generic
1855 @deffnx method apply-generic (gf <generic>) args
1858 @deffn generic compute-applicable-methods
1859 @deffnx method compute-applicable-methods (gf <generic>) args
1862 @deffn generic sort-applicable-methods
1863 @deffnx method sort-applicable-methods (gf <generic>) methods args
1866 @deffn generic method-more-specific?
1867 @deffnx method method-more-specific? (m1 <method>) (m2 <method>) args
1870 @deffn generic apply-method
1871 @deffnx method apply-method (gf <generic>) methods build-next args
1874 @deffn generic apply-methods
1875 @deffnx method apply-methods (gf <generic>) (l <list>) args
1878 @node Handling Invocation Errors
1879 @subsubsection Handling Invocation Errors
1881 @deffn generic no-method
1882 @deffnx method no-method (gf <generic>) args
1883 When an application invokes a generic function, and no methods at all
1884 have been defined for that generic function, GOOPS calls the
1885 @code{no-method} generic function. The default method calls
1886 @code{goops-error} with an appropriate message.
1889 @deffn generic no-applicable-method
1890 @deffnx method no-applicable-method (gf <generic>) args
1891 When an application applies a generic function to a set of arguments,
1892 and no methods have been defined for those argument types, GOOPS calls
1893 the @code{no-applicable-method} generic function. The default method
1894 calls @code{goops-error} with an appropriate message.
1897 @deffn generic no-next-method
1898 @deffnx method no-next-method (gf <generic>) args
1899 When a generic function method calls @code{(next-method)} to invoke the
1900 next less specialized method for that generic function, and no less
1901 specialized methods have been defined for the current generic function
1902 arguments, GOOPS calls the @code{no-next-method} generic function. The
1903 default method calls @code{goops-error} with an appropriate message.
1906 @node Redefining a Class
1907 @subsection Redefining a Class
1909 Suppose that a class @code{<my-class>} is defined using @code{define-class}
1910 (@pxref{Basic Class Definition,, define-class}), with slots that have
1911 accessor functions, and that an application has created several instances
1912 of @code{<my-class>} using @code{make} (@pxref{Basic Instance Creation,,
1913 make}). What then happens if @code{<my-class>} is redefined by calling
1914 @code{define-class} again?
1917 * Default Class Redefinition Behaviour::
1918 * Customizing Class Redefinition::
1921 @node Default Class Redefinition Behaviour
1922 @subsubsection Default Class Redefinition Behaviour
1924 GOOPS' default answer to this question is as follows.
1928 All existing direct instances of @code{<my-class>} are converted to be
1929 instances of the new class. This is achieved by preserving the values
1930 of slots that exist in both the old and new definitions, and initializing the
1931 values of new slots in the usual way (@pxref{Basic Instance Creation,,
1935 All existing subclasses of @code{<my-class>} are redefined, as though
1936 the @code{define-class} expressions that defined them were re-evaluated
1937 following the redefinition of @code{<my-class>}, and the class
1938 redefinition process described here is applied recursively to the
1939 redefined subclasses.
1942 Once all of its instances and subclasses have been updated, the class
1943 metaobject previously bound to the variable @code{<my-class>} is no
1944 longer needed and so can be allowed to be garbage collected.
1947 To keep things tidy, GOOPS also needs to do a little housekeeping on
1948 methods that are associated with the redefined class.
1952 Slot accessor methods for slots in the old definition should be removed
1953 from their generic functions. They will be replaced by accessor methods
1954 for the slots of the new class definition.
1957 Any generic function method that uses the old @code{<my-class>} metaobject
1958 as one of its formal parameter specializers must be updated to refer to
1959 the new @code{<my-class>} metaobject. (Whenever a new generic function
1960 method is defined, @code{define-method} adds the method to a list stored
1961 in the class metaobject for each class used as a formal parameter
1962 specializer, so it is easy to identify all the methods that must be
1963 updated when a class is redefined.)
1966 If this class redefinition strategy strikes you as rather counter-intuitive,
1967 bear in mind that it is derived from similar behaviour in other object
1968 systems such as CLOS, and that experience in those systems has shown it to be
1969 very useful in practice.
1971 Also bear in mind that, like most of GOOPS' default behaviour, it can
1972 be customized@dots{}
1974 @node Customizing Class Redefinition
1975 @subsubsection Customizing Class Redefinition
1977 When @code{define-class} notices that a class is being redefined,
1978 it constructs the new class metaobject as usual, and then invokes the
1979 @code{class-redefinition} generic function with the old and new classes
1980 as arguments. Therefore, if the old or new classes have metaclasses
1981 other than the default @code{<class>}, class redefinition behaviour can
1982 be customized by defining a @code{class-redefinition} method that is
1983 specialized for the relevant metaclasses.
1985 @deffn generic class-redefinition
1986 Handle the class redefinition from @var{old-class} to @var{new-class},
1987 and return the new class metaobject that should be bound to the
1988 variable specified by @code{define-class}'s first argument.
1991 @deffn method class-redefinition (old-class <class>) (new-class <class>)
1992 Implements GOOPS' default class redefinition behaviour, as described in
1993 @ref{Default Class Redefinition Behaviour}. Returns the metaobject
1994 for the new class definition.
1997 An alternative class redefinition strategy could be to leave all
1998 existing instances as instances of the old class, but accepting that the
1999 old class is now ``nameless'', since its name has been taken over by the
2000 new definition. In this strategy, any existing subclasses could also
2001 be left as they are, on the understanding that they inherit from a nameless
2004 This strategy is easily implemented in GOOPS, by defining a new metaclass,
2005 that will be used as the metaclass for all classes to which the strategy
2006 should apply, and then defining a @code{class-redefinition} method that
2007 is specialized for this metaclass:
2010 (define-class <can-be-nameless> (<class>))
2012 (define-method (class-redefinition (old <can-be-nameless>) (new <class>))
2016 When customization can be as easy as this, aren't you glad that GOOPS
2017 implements the far more difficult strategy as its default!
2019 Finally, note that, if @code{class-redefinition} itself is not customized,
2020 the default @code{class-redefinition} method invokes three further
2021 generic functions that could be individually customized:
2025 (remove-class-accessors! @var{old-class})
2028 (update-direct-method! @var{method} @var{old-class} @var{new-class})
2031 (update-direct-subclass! @var{subclass} @var{old-class} @var{new-class})
2034 and the default methods for these generic functions invoke further
2035 generic functions, and so on@dots{} The detailed protocol for all of these
2036 is described in @ref{MOP Specification}.
2038 @node Changing the Class of an Instance
2039 @subsection Changing the Class of an Instance
2041 You can change the class of an existing instance by invoking the
2042 generic function @code{change-class} with two arguments: the instance
2045 @deffn generic change-class
2048 The default method for @code{change-class} decides how to implement the
2049 change of class by looking at the slot definitions for the instance's
2050 existing class and for the new class. If the new class has slots with
2051 the same name as slots in the existing class, the values for those slots
2052 are preserved. Slots that are present only in the existing class are
2053 discarded. Slots that are present only in the new class are initialized
2054 using the corresponding slot definition's init function (@pxref{Classes,,
2055 slot-init-function}).
2057 @deffn {method} change-class (obj <object>) (new <class>)
2058 Modify instance @var{obj} to make it an instance of class @var{new}.
2060 The value of each of @var{obj}'s slots is preserved only if a similarly named
2061 slot exists in @var{new}; any other slot values are discarded.
2063 The slots in @var{new} that do not correspond to any of @var{obj}'s
2064 pre-existing slots are initialized according to @var{new}'s slot definitions'
2068 Customized change of class behaviour can be implemented by defining
2069 @code{change-class} methods that are specialized either by the class
2070 of the instances to be modified or by the metaclass of the new class.
2072 When a class is redefined (@pxref{Redefining a Class}), and the default
2073 class redefinition behaviour is not overridden, GOOPS (eventually)
2074 invokes the @code{change-class} generic function for each existing
2075 instance of the redefined class.
2078 @subsection Introspection
2080 @dfn{Introspection}, also known as @dfn{reflection}, is the name given
2081 to the ability to obtain information dynamically about GOOPS metaobjects.
2082 It is perhaps best illustrated by considering an object oriented language
2083 that does not provide any introspection, namely C++.
2085 Nothing in C++ allows a running program to obtain answers to the following
2090 What are the data members of this object or class?
2093 What classes does this class inherit from?
2096 Is this method call virtual or non-virtual?
2099 If I invoke @code{Employee::adjustHoliday()}, what class contains the
2100 @code{adjustHoliday()} method that will be applied?
2103 In C++, answers to such questions can only be determined by looking at
2104 the source code, if you have access to it. GOOPS, on the other hand,
2105 includes procedures that allow answers to these questions --- or their
2106 GOOPS equivalents --- to be obtained dynamically, at run time.
2112 * Generic Functions::
2113 * Generic Function Methods::
2117 @subsubsection Classes
2119 @deffn {primitive procedure} class-name class
2120 Return the name of class @var{class}.
2121 This is the value of the @var{class} metaobject's @code{name} slot.
2124 @deffn {primitive procedure} class-direct-supers class
2125 Return a list containing the direct superclasses of @var{class}.
2126 This is the value of the @var{class} metaobject's
2127 @code{direct-supers} slot.
2130 @deffn {primitive procedure} class-direct-slots class
2131 Return a list containing the slot definitions of the direct slots of
2133 This is the value of the @var{class} metaobject's @code{direct-slots}
2137 @deffn {primitive procedure} class-direct-subclasses class
2138 Return a list containing the direct subclasses of @var{class}.
2139 This is the value of the @var{class} metaobject's
2140 @code{direct-subclasses} slot.
2143 @deffn {primitive procedure} class-direct-methods class
2144 Return a list of all the generic function methods that use @var{class}
2145 as a formal parameter specializer.
2146 This is the value of the @var{class} metaobject's @code{direct-methods}
2150 @deffn {primitive procedure} class-precedence-list class
2151 Return the class precedence list for class @var{class} (@pxref{Class
2153 This is the value of the @var{class} metaobject's @code{cpl} slot.
2156 @deffn {primitive procedure} class-slots class
2157 Return a list containing the slot definitions for all @var{class}'s slots,
2158 including any slots that are inherited from superclasses.
2159 This is the value of the @var{class} metaobject's @code{slots} slot.
2162 @deffn {primitive procedure} class-environment class
2163 Return the value of @var{class}'s @code{environment} slot.
2164 [ *fixme* I don't know what this value is used for. ]
2167 @deffn procedure class-subclasses class
2168 Return a list of all subclasses of @var{class}.
2171 @deffn procedure class-methods class
2172 Return a list of all methods that use @var{class} or a subclass of
2173 @var{class} as one of its formal parameter specializers.
2177 @subsubsection Slots
2179 @deffn procedure class-slot-definition class slot-name
2180 Return the slot definition for the slot named @var{slot-name} in class
2181 @var{class}. @var{slot-name} should be a symbol.
2184 @deffn procedure slot-definition-name slot-def
2185 Extract and return the slot name from @var{slot-def}.
2188 @deffn procedure slot-definition-options slot-def
2189 Extract and return the slot options from @var{slot-def}.
2192 @deffn procedure slot-definition-allocation slot-def
2193 Extract and return the slot allocation option from @var{slot-def}. This
2194 is the value of the @code{#:allocation} keyword (@pxref{Slot Options,,
2195 allocation}), or @code{#:instance} if the @code{#:allocation} keyword is
2199 @deffn procedure slot-definition-getter slot-def
2200 Extract and return the slot getter option from @var{slot-def}. This is
2201 the value of the @code{#:getter} keyword (@pxref{Slot Options,,
2202 getter}), or @code{#f} if the @code{#:getter} keyword is absent.
2205 @deffn procedure slot-definition-setter slot-def
2206 Extract and return the slot setter option from @var{slot-def}. This is
2207 the value of the @code{#:setter} keyword (@pxref{Slot Options,,
2208 setter}), or @code{#f} if the @code{#:setter} keyword is absent.
2211 @deffn procedure slot-definition-accessor slot-def
2212 Extract and return the slot accessor option from @var{slot-def}. This
2213 is the value of the @code{#:accessor} keyword (@pxref{Slot Options,,
2214 accessor}), or @code{#f} if the @code{#:accessor} keyword is absent.
2217 @deffn procedure slot-definition-init-value slot-def
2218 Extract and return the slot init-value option from @var{slot-def}. This
2219 is the value of the @code{#:init-value} keyword (@pxref{Slot Options,,
2220 init-value}), or the unbound value if the @code{#:init-value} keyword is
2224 @deffn procedure slot-definition-init-form slot-def
2225 Extract and return the slot init-form option from @var{slot-def}. This
2226 is the value of the @code{#:init-form} keyword (@pxref{Slot Options,,
2227 init-form}), or the unbound value if the @code{#:init-form} keyword is
2231 @deffn procedure slot-definition-init-thunk slot-def
2232 Extract and return the slot init-thunk option from @var{slot-def}. This
2233 is the value of the @code{#:init-thunk} keyword (@pxref{Slot Options,,
2234 init-thunk}), or @code{#f} if the @code{#:init-thunk} keyword is absent.
2237 @deffn procedure slot-definition-init-keyword slot-def
2238 Extract and return the slot init-keyword option from @var{slot-def}.
2239 This is the value of the @code{#:init-keyword} keyword (@pxref{Slot
2240 Options,, init-keyword}), or @code{#f} if the @code{#:init-keyword}
2244 @deffn procedure slot-init-function class slot-name
2245 Return the initialization function for the slot named @var{slot-name} in
2246 class @var{class}. @var{slot-name} should be a symbol.
2248 The returned initialization function incorporates the effects of the
2249 standard @code{#:init-thunk}, @code{#:init-form} and @code{#:init-value}
2250 slot options. These initializations can be overridden by the
2251 @code{#:init-keyword} slot option or by a specialized @code{initialize}
2252 method, so, in general, the function returned by
2253 @code{slot-init-function} may be irrelevant. For a fuller discussion,
2254 see @ref{Slot Options,, init-value}.
2258 @subsubsection Instances
2260 @deffn {primitive procedure} class-of value
2261 Return the GOOPS class of any Scheme @var{value}.
2264 @deffn {primitive procedure} instance? object
2265 Return @code{#t} if @var{object} is any GOOPS instance, otherwise
2269 @deffn procedure is-a? object class
2270 Return @code{#t} if @var{object} is an instance of @var{class} or one of
2274 Implementation notes: @code{is-a?} uses @code{class-of} and
2275 @code{class-precedence-list} to obtain the class precedence list for
2278 @node Generic Functions
2279 @subsubsection Generic Functions
2281 @deffn {primitive procedure} generic-function-name gf
2282 Return the name of generic function @var{gf}.
2285 @deffn {primitive procedure} generic-function-methods gf
2286 Return a list of the methods of generic function @var{gf}.
2287 This is the value of the @var{gf} metaobject's @code{methods} slot.
2290 @node Generic Function Methods
2291 @subsubsection Generic Function Methods
2293 @deffn {primitive procedure} method-generic-function method
2294 Return the generic function that @var{method} belongs to.
2295 This is the value of the @var{method} metaobject's
2296 @code{generic-function} slot.
2299 @deffn {primitive procedure} method-specializers method
2300 Return a list of @var{method}'s formal parameter specializers .
2301 This is the value of the @var{method} metaobject's
2302 @code{specializers} slot.
2305 @deffn {primitive procedure} method-procedure method
2306 Return the procedure that implements @var{method}.
2307 This is the value of the @var{method} metaobject's
2308 @code{procedure} slot.
2311 @deffn generic method-source
2312 @deffnx method method-source (m <method>)
2313 Return an expression that prints to show the definition of method
2317 (define-generic cube)
2319 (define-method (cube (n <number>))
2322 (map method-source (generic-function-methods cube))
2324 ((method ((n <number>)) (* n n n)))
2328 @node Miscellaneous Functions
2329 @subsection Miscellaneous Functions
2332 * Administrative Functions::
2333 * GOOPS Error Handling::
2334 * Object Comparisons::
2336 * Write and Display::
2339 @node Administrative Functions
2340 @subsubsection Administration Functions
2342 This section describes administrative, non-technical GOOPS functions.
2344 @deffn primitive goops-version
2345 Return the current GOOPS version as a string, for example ``0.2''.
2348 @node GOOPS Error Handling
2349 @subsubsection Error Handling
2351 The procedure @code{goops-error} is called to raise an appropriate error
2352 by the default methods of the following generic functions:
2356 @code{slot-missing} (@pxref{Handling Slot Access Errors,, slot-missing})
2359 @code{slot-unbound} (@pxref{Handling Slot Access Errors,, slot-unbound})
2362 @code{no-method} (@pxref{Handling Invocation Errors,, no-method})
2365 @code{no-applicable-method} (@pxref{Handling Invocation Errors,,
2366 no-applicable-method})
2369 @code{no-next-method} (@pxref{Handling Invocation Errors,,
2373 If you customize these functions for particular classes or metaclasses,
2374 you may still want to use @code{goops-error} to signal any error
2375 conditions that you detect.
2377 @deffn procedure goops-error format-string . args
2378 Raise an error with key @code{goops-error} and error message constructed
2379 from @var{format-string} and @var{args}. Error message formatting is
2380 as done by @code{scm-error}.
2383 @node Object Comparisons
2384 @subsubsection Object Comparisons
2387 @deffnx method eqv? ((x <top>) (y <top>))
2388 @deffnx generic equal?
2389 @deffnx method equal? ((x <top>) (y <top>))
2391 @deffnx method = ((x <number>) (y <number>))
2392 Generic functions and default (unspecialized) methods for comparing two
2395 The default method for @code{eqv?} returns @code{#t} for all values
2396 that are equal in the sense defined by R5RS and the Guile reference
2397 manual, otherwise @code{#f}. The default method for @code{equal?}
2398 returns @code{#t} or @code{#f} in the sense defined by R5RS and the
2399 Guile reference manual. If no such comparison is defined,
2400 @code{equal?} returns the result of a call to @code{eqv?}. The
2401 default method for = returns @code{#t} if @var{x} and @var{y} are
2402 numerically equal, otherwise @code{#f}.
2404 Application class authors may wish to define specialized methods for
2405 @code{eqv?}, @code{equal?} and @code{=} that compare instances of the
2406 same class for equality in whatever sense is useful to the
2407 application. Such methods will only be called if the arguments have
2408 the same class and the result of the comparison isn't defined by R5RS
2409 and the Guile reference manual.
2412 @node Cloning Objects
2413 @subsubsection Cloning Objects
2415 @deffn generic shallow-clone
2416 @deffnx method shallow-clone (self <object>)
2417 Return a ``shallow'' clone of @var{self}. The default method makes a
2418 shallow clone by allocating a new instance and copying slot values from
2419 self to the new instance. Each slot value is copied either as an
2420 immediate value or by reference.
2423 @deffn generic deep-clone
2424 @deffnx method deep-clone (self <object>)
2425 Return a ``deep'' clone of @var{self}. The default method makes a deep
2426 clone by allocating a new instance and copying or cloning slot values
2427 from self to the new instance. If a slot value is an instance
2428 (satisfies @code{instance?}), it is cloned by calling @code{deep-clone}
2429 on that value. Other slot values are copied either as immediate values
2433 @node Write and Display
2434 @subsubsection Write and Display
2436 @deffn {primitive generic} write object port
2437 @deffnx {primitive generic} display object port
2438 When GOOPS is loaded, @code{write} and @code{display} become generic
2439 functions with special methods for printing
2443 objects - instances of the class @code{<object>}
2446 foreign objects - instances of the class @code{<foreign-object>}
2449 classes - instances of the class @code{<class>}
2452 generic functions - instances of the class @code{<generic>}
2455 methods - instances of the class @code{<method>}.
2458 @code{write} and @code{display} print non-GOOPS values in the same way
2459 as the Guile primitive @code{write} and @code{display} functions.
2462 @node MOP Specification
2463 @section MOP Specification
2465 For an introduction to metaobjects and the metaobject protocol,
2466 see @ref{Metaobjects and the Metaobject Protocol}.
2468 The aim of the MOP specification in this chapter is to specify all the
2469 customizable generic function invocations that can be made by the standard
2470 GOOPS syntax, procedures and methods, and to explain the protocol for
2471 customizing such invocations.
2473 A generic function invocation is customizable if the types of the arguments
2474 to which it is applied are not all determined by the lexical context in
2475 which the invocation appears. For example,
2479 the @code{(initialize @var{instance} @var{initargs})} invocation in the
2480 default @code{make-instance} method is customizable, because the type of the
2481 @code{@var{instance}} argument is determined by the class that was passed to
2482 @code{make-instance}.
2485 the @code{(make <generic> #:name ',name)} invocation in @code{define-generic}
2486 is not customizable, because all of its arguments have lexically determined
2490 When using this rule to decide whether a given generic function invocation
2491 is customizable, we ignore arguments that are expected to be handled in
2492 method definitions as a single ``rest'' list argument.
2494 For each customizable generic function invocation, the @dfn{invocation
2495 protocol} is explained by specifying
2499 what, conceptually, the applied method is intended to do
2502 what assumptions, if any, the caller makes about the applied method's side
2506 what the caller expects to get as the applied method's return value.
2510 * Class Definition::
2511 * Instance Creation::
2512 * Class Redefinition::
2513 * Method Definition::
2514 * Generic Function Invocation::
2517 @node Class Definition
2518 @subsection Class Definition
2520 @code{define-class} (syntax)
2524 @code{class} (syntax)
2528 @code{make-class} (procedure)
2532 @code{make @var{metaclass} @dots{}} (generic)
2534 @var{metaclass} is the metaclass of the class being defined, either
2535 taken from the @code{#:metaclass} class option or computed by
2536 @code{ensure-metaclass}. The applied method must create and return the
2537 fully initialized class metaobject for the new class definition.
2543 @code{class-redefinition @var{old-class} @var{new-class}} (generic)
2545 @code{define-class} calls @code{class-redefinition} if the variable
2546 specified by its first argument already held a GOOPS class definition.
2547 @var{old-class} and @var{new-class} are the old and new class metaobjects.
2548 The applied method should perform whatever is necessary to handle the
2549 redefinition, and should return the class metaobject that is to be bound
2550 to @code{define-class}'s variable. The default class redefinition
2551 protocol is described in @ref{Class Redefinition}.
2554 The @code{(make @var{metaclass} @dots{})} invocation above will create
2555 an class metaobject with metaclass @var{metaclass}. By default, this
2556 metaobject will be initialized by the @code{initialize} method that is
2557 specialized for instances of type @code{<class>}.
2559 @code{initialize <class> @var{initargs}} (method)
2563 @code{compute-cpl @var{class}} (generic)
2565 The applied method should compute and return the class precedence list
2566 for @var{class} as a list of class metaobjects. When @code{compute-cpl}
2567 is called, the following @var{class} metaobject slots have all been
2568 initialized: @code{name}, @code{direct-supers}, @code{direct-slots},
2569 @code{direct-subclasses} (empty), @code{direct-methods}. The value
2570 returned by @code{compute-cpl} will be stored in the @code{cpl} slot.
2573 @code{compute-slots @var{class}} (generic)
2575 The applied method should compute and return the slots (union of direct
2576 and inherited) for @var{class} as a list of slot definitions. When
2577 @code{compute-slots} is called, all the @var{class} metaobject slots
2578 mentioned for @code{compute-cpl} have been initialized, plus the
2579 following: @code{cpl}, @code{redefined} (@code{#f}), @code{environment}.
2580 The value returned by @code{compute-slots} will be stored in the
2584 @code{compute-get-n-set @var{class} @var{slot-def}} (generic)
2586 @code{initialize} calls @code{compute-get-n-set} for each slot computed
2587 by @code{compute-slots}. The applied method should compute and return a
2588 pair of closures that, respectively, get and set the value of the specified
2589 slot. The get closure should have arity 1 and expect a single argument
2590 that is the instance whose slot value is to be retrieved. The set closure
2591 should have arity 2 and expect two arguments, where the first argument is
2592 the instance whose slot value is to be set and the second argument is the
2593 new value for that slot. The closures should be returned in a two element
2594 list: @code{(list @var{get} @var{set})}.
2596 The closures returned by @code{compute-get-n-set} are stored as part of
2597 the value of the @var{class} metaobject's @code{getters-n-setters} slot.
2598 Specifically, the value of this slot is a list with the same number of
2599 elements as there are slots in the class, and each element looks either like
2602 @code{(@var{slot-name-symbol} @var{init-function} . @var{index})}
2608 @code{(@var{slot-name-symbol} @var{init-function} @var{get} @var{set})}
2611 Where the get and set closures are replaced by @var{index}, the slot is
2612 an instance slot and @var{index} is the slot's index in the underlying
2613 structure: GOOPS knows how to get and set the value of such slots and so
2614 does not need specially constructed get and set closures. Otherwise,
2615 @var{get} and @var{set} are the closures returned by @code{compute-get-n-set}.
2617 The structure of the @code{getters-n-setters} slot value is important when
2618 understanding the next customizable generic functions that @code{initialize}
2622 @code{compute-getter-method @var{class} @var{gns}} (generic)
2624 @code{initialize} calls @code{compute-getter-method} for each of the class's
2625 slots (as determined by @code{compute-slots}) that includes a
2626 @code{#:getter} or @code{#:accessor} slot option. @var{gns} is the
2627 element of the @var{class} metaobject's @code{getters-n-setters} slot that
2628 specifies how the slot in question is referenced and set, as described
2629 above under @code{compute-get-n-set}. The applied method should create
2630 and return a method that is specialized for instances of type @var{class}
2631 and uses the get closure to retrieve the slot's value. [ *fixme Need
2632 to insert something here about checking that the value is not unbound. ]
2633 @code{initialize} uses @code{add-method!} to add the returned method to
2634 the generic function named by the slot definition's @code{#:getter} or
2635 @code{#:accessor} option.
2638 @code{compute-setter-method @var{class} @var{gns}} (generic)
2640 @code{compute-setter-method} is invoked with the same arguments as
2641 @code{compute-getter-method}, for each of the class's slots that includes
2642 a @code{#:setter} or @code{#:accessor} slot option. The applied method
2643 should create and return a method that is specialized for instances of
2644 type @var{class} and uses the set closure to set the slot's value.
2645 @code{initialize} then uses @code{add-method!} to add the returned method
2646 to the generic function named by the slot definition's @code{#:setter}
2647 or @code{#:accessor} option.
2650 @node Instance Creation
2651 @subsection Instance Creation
2653 @code{make <class> . @var{initargs}} (method)
2657 @code{allocate-instance @var{class} @var{initargs}} (generic)
2659 The applied @code{allocate-instance} method should allocate storage for
2660 a new instance of class @var{class} and return the uninitialized instance.
2663 @code{initialize @var{instance} @var{initargs}} (generic)
2665 @var{instance} is the uninitialized instance returned by
2666 @code{allocate-instance}. The applied method should initialize the new
2667 instance in whatever sense is appropriate for its class. The method's
2668 return value is ignored.
2671 @node Class Redefinition
2672 @subsection Class Redefinition
2674 The default @code{class-redefinition} method, specialized for classes
2675 with the default metaclass @code{<class>}, has the following internal
2678 @code{class-redefinition (@var{old <class>}) (@var{new <class>})}
2683 @code{remove-class-accessors! @var{old}} (generic)
2686 @code{update-direct-method! @var{method} @var{old} @var{new}} (generic)
2689 @code{update-direct-subclass! @var{subclass} @var{old} @var{new}} (generic)
2692 This protocol cleans up things that the definition of the old class
2693 once changed and modifies things to work with the new class.
2695 The default @code{remove-class-accessors!} method removes the
2696 accessor methods of the old class from all classes which they
2699 The default @code{update-direct-method!} method substitutes the new
2700 class for the old in all methods specialized to the old class.
2702 The default @code{update-direct-subclass!} method invokes
2703 @code{class-redefinition} recursively to handle the redefinition of
2706 When a class is redefined, any existing instance of the redefined class
2707 will be modified for the new class definition before the next time that
2708 any of the instance's slot is referenced or set. GOOPS modifies each
2709 instance by calling the generic function @code{change-class}.
2711 The default @code{change-class} method copies slot values from the old
2712 to the modified instance, and initializes new slots, as described in
2713 @ref{Changing the Class of an Instance}. After doing so, it makes a
2714 generic function invocation that can be used to customize the instance
2717 @code{change-class (@var{old-instance <object>}) (@var{new <class>})} (method)
2721 @code{update-instance-for-different-class @var{old-instance} @var{new-instance}} (generic)
2723 @code{change-class} invokes @code{update-instance-for-different-class}
2724 as the last thing that it does before returning. The applied method can
2725 make any further adjustments to @var{new-instance} that are required to
2726 complete or modify the change of class. The return value from the
2727 applied method is ignored.
2729 The default @code{update-instance-for-different-class} method does
2733 @node Method Definition
2734 @subsection Method Definition
2736 @code{define-method} (syntax)
2740 @code{add-method! @var{target} @var{method}} (generic)
2742 @code{define-method} invokes the @code{add-method!} generic function to
2743 handle adding the new method to a variety of possible targets. GOOPS
2744 includes methods to handle @var{target} as
2748 a generic function (the most common case)
2754 a primitive generic (@pxref{Extending Guiles Primitives})
2757 By defining further methods for @code{add-method!}, you can
2758 theoretically handle adding methods to further types of target.
2761 @node Generic Function Invocation
2762 @subsection Generic Function Invocation
2764 [ *fixme* Description required here. ]
2766 @code{apply-generic}
2773 @code{compute-applicable-methods}
2776 @code{sort-applicable-methods}
2779 @code{apply-methods}
2782 @code{no-applicable-method}
2785 @code{sort-applicable-methods}
2789 @code{method-more-specific?}
2792 @code{apply-methods}
2803 @code{no-next-method}
2808 @include goops-tutorial.texi