This section introduces the goops package in more detail.  It was originally written by Erick Gallesio as an appendix for the STk reference manual, and subsequently adapted to goops.

The procedures and syntax described in this tutorial are provided by Guile modules that may need to be imported before being available. The main goops module is imported by evaluating:

     (use-modules (oop goops))

Copyright
---------

Original attribution:

STk Reference manual (Appendix: An Introduction to STklos)

Copyright © 1993-1999 Erick Gallesio - I3S-CNRS/ESSI <eg@unice.fr> Permission to use, copy, modify, distribute,and license this software and its documentation for any purpose is hereby granted, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions.  No written agreement, license, or royalty fee is required for any of the authorized uses. This software is provided ``AS IS'' without express or implied warranty.

Adapted for use in Guile with the author's permission

Class definition
----------------

A new class is defined with the define-class macro. The syntax of define-class is close to CLOS defclass:

     (define-class CLASS (SUPERCLASS ...)
        SLOT-DESCRIPTION ...
        CLASS-OPTION ...)

CLASS is the class being defined.  The list of SUPERCLASSes specifies which existing classes, if any, to inherit slots and properties from.  Each SLOT-DESCRIPTION gives the name of a slot and optionally some ``properties'' of this slot; for example its initial value, the name of a function which will access its value, and so on.  Slot descriptions and inheritance are discussed more below.  For class options, see Class Options.

As an example, let us define a type for representing a complex number in terms of two real numbers. (Of course Guile already provides complex numbers, and <complex> is in fact a predefined class in GOOPS; but the definition here is still useful as an example.)  This can be done with the following class definition:

     (define-class <my-complex> (<number>)
        r i)

This binds the variable <my-complex> to a new class whose instances will contain two slots.  These slots are called r and i and will hold the real and imaginary parts of a complex number. Note that this class inherits from <number>, which is a predefined class. (<number> is the direct superclass of the predefined class <complex>; <complex> is the superclass of <real>, and <real> is the superclass of <integer>.)

Instance creation and slot access
---------------------------------

Creation of an instance of a previously defined class can be done with the make procedure. This procedure takes one mandatory parameter which is the class of the instance which must be created and a list of optional arguments. Optional arguments are generally used to initialize some slots of the newly created instance. For instance, the following form

     (define c (make <my-complex>))

will create a new <my-complex> object and will bind it to the c Scheme variable.

Accessing the slots of the new complex number can be done with the slot-ref and the slot-set!  primitives. slot-set! sets the value of an object slot and slot-ref retrieves it.

     (slot-set! c 'r 10)
     (slot-set! c 'i 3)
     (slot-ref c 'r) => 10
     (slot-ref c 'i) => 3

Using the describe function is a simple way to see all the slots of an object at one time: this function prints all the slots of an object on the standard output.

First load the module (oop goops describe):

     (use-modules (oop goops describe))

Then the expression

     (describe c)

will print the following information on the standard output:

     #<<my-complex> 401d8638> is an instance of class <my-complex>
     Slots are:
          r = 10
          i = 3

Slot description
----------------

When specifying a slot (in a (define-class ...) form), various options can be specified in addition to the slot's name.  Each option is specified by a keyword.  The list of authorized keywords is given below:

  * #:init-value permits to supply a constant default value for the slot.  The value is obtained by evaluating the form given after the #:init-value at class definition time.

  * #:init-form specifies a form that, when evaluated, will return an initial value for the slot.  The form is evaluated each time that an instance of the class is created, in the lexical environment of the containing define-class expression.

  * #:init-thunk permits to supply a thunk that will provide a default value for the slot.  The value is obtained by invoking the thunk at instance creation time.

  * #:init-keyword permits to specify a keyword for initializing the slot.  The init-keyword may be provided during instance creation (i.e. in the make optional parameter list).  Specifying such a keyword during instance initialization will supersede the default slot initialization possibly given with #:init-form.

  * #:getter permits to supply the name for the slot getter. The name binding is done in the environment of the define-class macro.

  * #:setter permits to supply the name for the slot setter. The name binding is done in the environment of the define-class macro.

  * #:accessor permits to supply the name for the slot accessor. The name binding is done in the global environment. An accessor permits to get and set the value of a slot. Setting the value of a slot is done with the extended version of set!.

  * #:allocation permits to specify how storage for the slot is allocated. Three kinds of allocation are provided. They are described below:

       - #:instance indicates that each instance gets its own storage for the slot. This is the default.

       - #:class indicates that there is one storage location used by all the direct and indirect instances of the class. This permits to define a kind of global variable which can be accessed only by (in)direct instances of the class which defines this slot.

       - #:each-subclass indicates that there is one storage location used by all the direct instances of the class. In other words, if two classes are not siblings in the class hierarchy, they will not see the same value.

       - #:virtual indicates that no storage will be allocated for this slot.  It is up to the user to define a getter and a setter function for this slot. Those functions must be defined with the #:slot-ref and #:slot-set! options. See the example below.

To illustrate slot description, we shall redefine the <my-complex> class seen before. A definition could be:

     (define-class <my-complex> (<number>)
        (r #:init-value 0 #:getter get-r #:setter set-r! #:init-keyword #:r)
        (i #:init-value 0 #:getter get-i #:setter set-i! #:init-keyword #:i))

With this definition, the r and i slot are set to 0 by default.  Value of a slot can also be specified by calling make with the #:r and #:i keywords. Furthermore, the generic functions get-r and set-r! (resp. get-i and set-i!) are automatically defined by the system to read and write the r (resp. i) slot.

     (define c1 (make <my-complex> #:r 1 #:i 2))
     (get-r c1) => 1
     (set-r! c1 12)
     (get-r c1) => 12
     (define c2 (make <my-complex> #:r 2))
     (get-r c2) => 2
     (get-i c2) => 0

Accessors provide an uniform access for reading and writing an object slot.  Writing a slot is done with an extended form of set! which is close to the Common Lisp setf macro. So, another definition of the previous <my-complex> class, using the #:accessor option, could be:

     (define-class <my-complex> (<number>)
        (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
        (i #:init-value 0 #:accessor imag-part #:init-keyword #:i))

Using this class definition, reading the real part of the c complex can be done with:

     (real-part c)

and setting it to the value contained in the new-value variable can be done using the extended form of set!.

     (set! (real-part c) new-value)

Suppose now that we have to manipulate complex numbers with rectangular coordinates as well as with polar coordinates. One solution could be to have a definition of complex numbers which uses one particular representation and some conversion functions to pass from one representation to the other.  A better solution uses virtual slots. A complete definition of the <my-complex> class using virtual slots is given in Figure 2.

          (define-class <my-complex> (<number>)
             ;; True slots use rectangular coordinates
             (r #:init-value 0 #:accessor real-part #:init-keyword #:r)
             (i #:init-value 0 #:accessor imag-part #:init-keyword #:i)
             ;; Virtual slots access do the conversion
             (m #:accessor magnitude #:init-keyword #:magn
                #:allocation #:virtual
                #:slot-ref (lambda (o)
                            (let ((r (slot-ref o 'r)) (i (slot-ref o 'i)))
                              (sqrt (+ (* r r) (* i i)))))
                #:slot-set! (lambda (o m)
                              (let ((a (slot-ref o 'a)))
                                (slot-set! o 'r (* m (cos a)))
                                (slot-set! o 'i (* m (sin a))))))
             (a #:accessor angle #:init-keyword #:angle
                #:allocation #:virtual
                #:slot-ref (lambda (o)
                            (atan (slot-ref o 'i) (slot-ref o 'r)))
                #:slot-set! (lambda(o a)
                             (let ((m (slot-ref o 'm)))
                                (slot-set! o 'r (* m (cos a)))
                                (slot-set! o 'i (* m (sin a)))))))

     Fig 2: A <my-complex> number class definition using virtual slots

This class definition implements two real slots (r and i). Values of the m and a virtual slots are calculated from real slot values. Reading a virtual slot leads to the application of the function defined in the #:slot-ref option. Writing such a slot leads to the application of the function defined in the #:slot-set! option.  For instance, the following expression

     (slot-set! c 'a 3)

permits to set the angle of the c complex number. This expression conducts, in fact, to the evaluation of the following expression

     ((lambda o m)
         (let ((m (slot-ref o 'm)))
            (slot-set! o 'r (* m (cos a)))
            (slot-set! o 'i (* m (sin a))))
       c 3)

A more complete example is given below:

          (define c (make <my-complex> #:r 12 #:i 20))
          (real-part c) => 12
          (angle c) => 1.03037682652431
          (slot-set! c 'i 10)
          (set! (real-part c) 1)
          (describe c)
          -|
          #<<my-complex> 401e9b58> is an instance of class <my-complex>
          Slots are:
               r = 1
               i = 10
               m = 10.0498756211209
               a = 1.47112767430373

Since initialization keywords have been defined for the four slots, we can now define the make-rectangular and make-polar standard Scheme primitives.

     (define make-rectangular
        (lambda (x y) (make <my-complex> #:r x #:i y)))

     (define make-polar
        (lambda (x y) (make <my-complex> #:magn x #:angle y)))

Inheritance
-----------

Class hierarchy and inheritance of slots
........................................

Inheritance is specified upon class definition. As said in the introduction, goops supports multiple inheritance.  Here are some class definitions:

     (define-class A () a)
     (define-class B () b)
     (define-class C () c)
     (define-class D (A B) d a)
     (define-class E (A C) e c)
     (define-class F (D E) f)

A, B, C have a null list of super classes. In this case, the system will replace it by the list which only contains <object>, the root of all the classes defined by define-class. D, E, F use multiple inheritance: each class inherits from two previously defined classes. Those class definitions define a hierarchy which is shown in Figure 1. In this figure, the class <top> is also shown; this class is the super class of all Scheme objects. In particular, <top> is the super class of all standard Scheme types.

          [file hierarchy.txt not included]

     Fig 1: A class hierarchy
     (<complex> which is the direct subclass of <number>
     and the direct superclass of <real> has been omitted in this
     figure.)

The set of slots of a given class is calculated by taking the union of the slots of all its super class. For instance, each instance of the class D, defined before will have three slots (a, b and d). The slots of a class can be obtained by the class-slots primitive.  For instance,

     (class-slots A) => ((a))
     (class-slots E) => ((a) (e) (c))
     (class-slots F) => ((e) (c) (b) (d) (a) (f))

Note:  The order of slots is not significant.

Class precedence list
.....................

A class may have more than one superclass.   (This section is an adaptation of Jeff Dalton's (J.Dalton@ed.ac.uk) Brief introduction to CLOS) With single inheritance (one superclass), it is easy to order the super classes from most to least specific. This is the rule:

     Rule 1: Each class is more specific than its superclasses. was \bf

With multiple inheritance, ordering is harder. Suppose we have

     (define-class X ()
        (x #:init-value 1))

     (define-class Y ()
        (x #:init-value 2))

     (define-class Z (X Y)
        (...))

In this case, the Z class is more specific than the X or Y class for instances of Z. However, the #:init-value specified in X and Y leads to a problem: which one overrides the other?  The rule in goops, as in CLOS, is that the superclasses listed earlier are more specific than those listed later. So:

     Rule 2: For a given class, superclasses listed earlier are more
             specific than those listed later.

These rules are used to compute a linear order for a class and all its superclasses, from most specific to least specific.  This order is called the ``class precedence list'' of the class. Given these two rules, we can claim that the initial form for the x slot of previous example is 1 since the class X is placed before Y in class precedence list of Z.

These two rules are not always enough to determine a unique order, however, but they give an idea of how things work.  Taking the F class shown in Figure 1, the class precedence list is

     (f d e a c b <object> <top>)

However, it is usually considered a bad idea for programmers to rely on exactly what the order is.  If the order for some superclasses is important, it can be expressed directly in the class definition.

The precedence list of a class can be obtained by the function class-precedence-list. This function returns a ordered list whose first element is the most specific class. For instance,

     (class-precedence-list B) => (#<<class> B 401b97c8>
                                          #<<class> <object> 401e4a10>
                                          #<<class> <top> 4026a9d8>)

However, this result is not too much readable; using the function class-name yields a clearer result:

     (map class-name (class-precedence-list B)) => (B <object> <top>)

Generic functions
-----------------

Generic functions and methods
.............................

Neither goops nor CLOS use the message mechanism for methods as most Object Oriented language do. Instead, they use the notion of generic functions.  A generic function can be seen as a methods ``tanker''. When the evaluator requested the application of a generic function, all the methods of this generic function will be grabbed and the most specific among them will be applied. We say that a method M is more specific than a method M' if the class of its parameters are more specific than the M' ones.  To be more precise, when a generic function must be ``called'' the system will:

 1. search among all the generic function those which are applicable

 2. sort the list of applicable methods in the ``most specific'' order

 3. call the most specific method of this list (i.e. the first method of the sorted methods list).

The definition of a generic function is done with the define-generic macro. Definition of a new method is done with the define-method macro.  Note that define-method automatically defines the generic function if it has not been defined before. Consequently, most of the time, the define-generic needs not be used. Consider the following definitions:

     (define-generic G)
     (define-method  (G (a <integer>) b) 'integer)
     (define-method  (G (a <real>) b) 'real)
     (define-method  (G a b) 'top)

The define-generic call defines G as a generic function. Note that the signature of the generic function is not given upon definition, contrarily to CLOS. This will permit methods with different signatures for a given generic function, as we shall see later. The three next lines define methods for the G generic function. Each method uses a sequence of parameter specializers that specify when the given method is applicable. A specializer permits to indicate the class a parameter must belong to (directly or indirectly) to be applicable. If no specializer is given, the system defaults it to <top>. Thus, the first method definition is equivalent to

     (define-method (G (a <integer>) (b <top>)) 'integer)

Now, let us look at some possible calls to generic function G:

     (G 2 3)    => integer
     (G 2 #t)   => integer
     (G 1.2 'a) => real
     (G #t #f)  => top
     (G 1 2 3)  => error (since no method exists for 3 parameters)

The preceding methods use only one specializer per parameter list. Of course, each parameter can use a specializer. In this case, the parameter list is scanned from left to right to determine the applicability of a method. Suppose we declare now

     (define-method (G (a <integer>) (b <number>))  'integer-number)
     (define-method (G (a <integer>) (b <real>))    'integer-real)
     (define-method (G (a <integer>) (b <integer>)) 'integer-integer)
     (define-method (G a (b <number>))              'top-number)

In this case,

     (G 1 2)   => integer-integer
     (G 1 1.0) => integer-real
     (G 1 #t)  => integer
     (G 'a 1)  => top-number

Next-method
...........

When you call a generic function, with a particular set of arguments, GOOPS builds a list of all the methods that are applicable to those arguments and orders them by how closely the method definitions match the actual argument types.  It then calls the method at the top of this list.  If the selected method's code wants to call on to the next method in this list, it can do so by using next-method.

     (define-method (Test (a <integer>)) (cons 'integer (next-method)))
     (define-method (Test (a <number>))  (cons 'number  (next-method)))
     (define-method (Test a)             (list 'top))

With these definitions,

     (Test 1)   => (integer number top)
     (Test 1.0) => (number top)
     (Test #t)  => (top)

next-method is always called as just (next-method).  The arguments for the next method call are always implicit, and always the same as for the original method call.

If you want to call on to a method with the same name but with a different set of arguments (as you might with overloaded methods in C++, for example), you do not use next-method, but instead simply write the new call as usual:

     (define-method (Test (a <number>) min max)
       (if (and (>= a min) (<= a max))
           (display "Number is in range\n"))
       (Test a))

     (Test 2 1 10)
     -|
     Number is in range
     =>
     (integer number top)

(You should be careful in this case that the Test calls do not lead to an infinite recursion, but this consideration is just the same as in Scheme code in general.)

Example
.......

In this section we shall continue to define operations on the <my-complex> class defined in Figure 2. Suppose that we want to use it to implement complex numbers completely. For instance a definition for the addition of two complexes could be

     (define-method (new-+ (a <my-complex>) (b <my-complex>))
       (make-rectangular (+ (real-part a) (real-part b))
                         (+ (imag-part a) (imag-part b))))

To be sure that the + used in the method new-+ is the standard addition we can do:

     (define-generic new-+)

     (let ((+ +))
       (define-method (new-+ (a <my-complex>) (b <my-complex>))
         (make-rectangular (+ (real-part a) (real-part b))
                           (+ (imag-part a) (imag-part b)))))

The define-generic ensures here that new-+ will be defined in the global environment. Once this is done, we can add methods to the generic function new-+ which make a closure on the + symbol.  A complete writing of the new-+ methods is shown in Figure 3.

          (define-generic new-+)

          (let ((+ +))

            (define-method (new-+ (a <real>) (b <real>)) (+ a b))

            (define-method (new-+ (a <real>) (b <my-complex>))
              (make-rectangular (+ a (real-part b)) (imag-part b)))

            (define-method (new-+ (a <my-complex>) (b <real>))
              (make-rectangular (+ (real-part a) b) (imag-part a)))

            (define-method (new-+ (a <my-complex>) (b <my-complex>))
              (make-rectangular (+ (real-part a) (real-part b))
                                (+ (imag-part a) (imag-part b))))

            (define-method (new-+ (a <number>))  a)

            (define-method (new-+) 0)

            (define-method (new-+ . args)
              (new-+ (car args)
                (apply new-+ (cdr args)))))

          (set! + new-+)

     Fig 3: Extending + for dealing with complex numbers

We use here the fact that generic function are not obliged to have the same number of parameters, contrarily to CLOS.  The four first methods implement the dyadic addition. The fifth method says that the addition of a single element is this element itself. The sixth method says that using the addition with no parameter always return 0. The last method takes an arbitrary number of parameters (The parameter list for a define-method follows the conventions used for Scheme procedures. In particular it can use the dot notation or a symbol to denote an arbitrary number of parameters).  This method acts as a kind of reduce: it calls the dyadic addition on the car of the list and on the result of applying it on its rest.  To finish, the set! permits to redefine the + symbol to our extended addition.

To terminate our implementation (integration?) of  complex numbers, we can redefine standard Scheme predicates in the following manner:

     (define-method (complex? c <my-complex>) #t)
     (define-method (complex? c)           #f)

     (define-method (number? n <number>) #t)
     (define-method (number? n)          #f)
     ...
     ...

Standard primitives in which complex numbers are involved could also be redefined in the same manner.