> For the complete documentation index, see [llms.txt](https://www.lisppad.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.lisppad.app/libraries/lispkit/lispkit-object.md). # (lispkit object) Library `(lispkit object)` implements a simple, delegation-based object system for LispKit. It provides procedural and declarative interfaces for objects and classes. The class system is optional. It mostly provides means to define and manage new object types and construct objects using object constructors. ## Introduction Similar to other Scheme and Lisp-based object systems, methods of objects are defined in terms of object/class-specific specializations of generic procedures. A generic procedure consists of methods for the various objects/classes it supports. A generic procedure performs a dynamic dispatch on the first parameter (the `self` parameter) to determine the applicable method. ### Generic procedures Generic procedures can be defined using the `define-generic` form. Here is an example which defines three generic methods, one with only a `self` parameter, and two with three parameters `self`, `x` and `y`. The last generic procedure definition includes a `default` method which is applicable to all objects for which there is no specific method. When a generic procedure without default is applied to an object that does not define its own method implementation, an error gets signaled. ```scheme (define-generic (point-coordinates self)) (define-generic (set-point-coordinates! self x y)) (define-generic (point-move! self x y) (let ((c (point-coordinate self))) (set-point-coordinate! self (+ (car c) x) (+ (cdr c) y)))) ``` ### Objects An object encapsulates a list of methods each implementing a generic procedure. These methods are regular closures which can share mutable state. Objects do not have an explicit notion of a field or slot as in other Scheme or Lisp-based object systems. Fields/slots need to be implemented via generic procedures and method implementations sharing state. Here is an example explaining this approach: ```scheme (define (make-point x y) (object () ((point-coordinates self) (cons x y)) ((set-point-coordinates! self nx ny) (set! x nx) (set! y ny)) ((object-description self) (string-append (object-description x) "/" (object-description y))))) ``` This is a function creating new point objects. The `x` and `y` parameters of the constructor function are used for representing the state of the point object. The created point objects implement three generic procedures: `point-coordinates`, `set-point-coordinates`, and `object-description`. The latter procedure is defined directly by the library and, in general, used for creating a string representation of any object. By implementing the `object-description` method, the behavior gets customized for the object. The following lines of code illustrate how point objects can be used: ```scheme (define pt (make-point 25 37)) pt ⇒ #> (object-description pt) ⇒ "25/37" (point-coordinates pt) ⇒ (25 . 37) (set-point-coordinates! pt 5 6) (object-description pt) ⇒ "5/6" (point-coordinates pt) ⇒ (5 . 6) ``` ### Inheritance The LispKit object system supports inheritance via delegation. The following code shows how colored points can be implemented by delegating all point functionality to the previous implementation and by simply adding only color-related logic. ```scheme (define-generic (point-color self) #f) (define (make-colored-point x y color) (object ((super (make-point x y))) ((point-color self) color) ((object-description self) (string-append (object-description color) ":" (invoke (super object-description) self))))) ``` The object created in function `make-colored-point` inherits all methods from object `super` which gets set to a new point object. It adds a new method to generic procedure `point-color` and redefines the `object-description` method. The redefinition is implemented in terms of the inherited `object-description` method for points. The form `invoke` can be used to refer to overridden methods in delegatee objects. Thus, `(invoke (super object-description) self)` calls the `object-description` method of the `super` object but with the identity (`self`) of the colored point. The following interaction illustrates the behavior: ```scheme (define cpt (make-colored-point 100 50 'red)) (point-color cpt) ⇒ red (point-coordinates cpt) ⇒ (100 . 50) (set-point-coordinates! cpt 101 51) (object-description cpt) ⇒ "red:101/51" ``` Objects can delegate functionality to multiple delegatees. The order in which they are listed determines the methods which are being inherited in case there are conflicts, i.e. multiple delegatees implement a method for the same generic procedure. ### Classes Classes add syntactic sugar, simplifying the creation and management of objects. They play the following role in the object-system of LispKit: 1. A class defines a constructor for objects represented by this class. 2. Each class defines an object type, which can be used to distinguish objects created by the same constructor and supporting the same methods. 3. A class can inherit functionality from several other classes, making it easy to reuse functionality. 4. Classes are first-class objects supporting a number of class-related procedures. The following code defines a `point` class with similar functionality as above: ```scheme (define-class (point x y) () (object () ((point-coordinates self) (cons x y)) ((set-point-coordinates! self nx ny) (set! x nx) (set! y ny)) ((object-description self) (string-append (object-description x) "/" (object-description y))))) ``` Instances of this class are created by using the generic procedure `make-instance` which is implemented by all class objects: ```scheme (define pt2 (make-instance point 82 10)) pt2 ⇒ #> (object-description pt2) ⇒ "82/10" ``` Each object created by a class implements a generic procedure `object-class` referring to the class of the object. Since classes are objects themselves we can obtain their name with generic procedure `class-name`: ```scheme (object-class pt2) ⇒ #> (class-name (object-class pt2)) ⇒ point (instance-of? point pt2) ⇒ #t (instance-of? point pt) ⇒ #f ``` Generic procedure `instance-of?` can be used to determine whether an object is a direct or indirect instance of a given class. The last two lines above show that `pt2` is an instance of `point`, but `pt` is not, even though it is functionally equivalent. The following definition re-implements the colored point example from above using a class: ```scheme (define-class (colored-point x y color) (point) (if (or (< x 0) (< y 0)) (error "coordinates are negative: ($0; $1)" x y)) (object ((super (make-instance point x y))) ((point-color self) color) ((object-description self) (string-append (object-description color) ":" (invoke (super object-description) self))))) ``` The following lines illustrate the behavior of `colored-point` objects vs `point` objects: ```scheme (define cpt2 (make-instance colored-point 128 256 'blue)) (point-color cpt2) ⇒ blue (point-coordinates cpt2) ⇒ (128 . 256) (set-point-coordinates! cpt2 64 32) (object-description cpt2) ⇒ "blue:64/32" (instance-of? point cpt2) ⇒ #t (instance-of? colored-point cpt2) ⇒ #t (instance-of? colored-point cpt) ⇒ #f (class-name (object-class cpt2)) ⇒ colored-point ``` ## Procedural object interface **object-type-tag** Symbol representing the `object` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all objects created via `object` or `make-object`. Every class created via `make-class` (or `define-class`) implicitly defines its own, more specific type tag for its instances, distinct from `object-type-tag` and `class-type-tag`, but not directly exposed to user code. `type-of` (see library `(lispkit type)`) returns a list of such tags for an object, ordered from most specific to least specific, e.g. `(type-of pt2) ⇒ (point object)` for an instance of a `point` class, `(type-of point) ⇒ (class object)` for the `point` class object itself, and `(type-of (make-object)) ⇒ (object)` for a plain object without a class. **(object? *****obj*****)** Returns `#t` if *obj* is an object as defined by this library. Objects are either created procedurally via `make-object` or declaratively via `object`. **(make-object)** \ **(make-object *****delegate ...*****)** Creates and returns a new object without any methods of its own. If one or more *delegate* objects are provided, the new object inherits all of their methods (see `object-methods`); if several delegates implement a method for the same generic procedure, the method of the delegate listed first takes precedence. `make-object` is the procedural counterpart of the `object` syntax, which additionally allows methods to be attached right away. **(method *****obj generic*****)** Returns the method implementing generic procedure *generic* for object *obj*, or `#f` if *obj* does not implement *generic*. The result is a plain procedure still expecting the "self" object as its first argument, e.g. `((method obj generic) obj arg ...)`. This is the procedure used internally to perform dynamic dispatch, both by generic procedures created with `make-generic-procedure` and by the `invoke` syntax. **(object-methods *****obj*****)** Returns an association list of all methods implemented by object *obj*, i.e. a list of pairs `(generic . method)`. If `add-method!` was used to add more than one method for the same generic procedure, all of them show up in the list, with the most recently added one listed first (see `add-method!`). **(add-method! *****obj generic method*****)** Adds *method* as a new implementation of generic procedure *generic* to object *obj*, mutating *obj* in place. *method* is a procedure expecting the "self" object as its first argument. If *obj* already implements *generic*, the previous method is not discarded but merely shadowed: it becomes visible again once *method* is removed via `delete-method!`. **(delete-method! *****obj generic*****)** Removes the most recently added implementation of generic procedure *generic* from object *obj*, mutating *obj* in place, and exposing a previously shadowed implementation of *generic* added earlier via `add-method!`, if there is one. If *obj* does not implement *generic*, `delete-method!` has no effect. **(make-generic-procedure)** \ **(make-generic-procedure *****default*****)** Returns a new generic procedure `(lambda (obj arg ...) ...)` implementing dynamic dispatch on its first argument *obj*: if *obj* is an object (as defined by `object?`) implementing a method for this generic procedure, that method is applied to *obj* and the remaining arguments. Otherwise, *default* is applied instead, both for objects lacking an implementation of this generic procedure and for arguments that are not objects at all. If *default* is not provided, invoking the generic procedure in such a case signals an error. `define-generic` provides a more convenient, declarative way to define generic procedures. ## Declarative object interface **(object ((*****delegatevar delegate*****) ...) ((*****generic self arg ... . rest*****) *****e1 e2 ...*****) ...)** Creates and returns a new object, combining `make-object` and `add-method!` into a single declarative expression. Each `(_delegatevar delegate_)` clause binds *delegatevar* to the value of expression *delegate* and includes it as a delegate of the new object, exactly as with `make-object`; *delegatevar* is visible in the method bodies below (and in later delegate expressions), which is how objects created with `object` implement inheritance (see the `colored-point` example in the introduction above). Each `((_generic self arg ... . rest_) _e1 e2 ..._)` clause adds a method for generic procedure *generic* to the new object, equivalent to `(add-method! obj generic (lambda (self arg ... . rest) e1 e2 ...))`. Both the delegate expressions and the method bodies may refer to variables of the surrounding lexical scope, which is how objects created with `object` encapsulate mutable state. **(define-generic (*****name self arg ... . rest*****))** \ **(define-generic (*****name self arg ... . rest*****) *****e1 e2 ...*****)** Defines *name* as a new generic procedure via `make-generic-procedure`. In the first form, *name* has no default implementation, and applying it to an object (or value) without a matching method signals an error. In the second form, `(lambda (self arg ... . rest) e1 e2 ...)` is used as the default implementation, applied whenever the first argument is not an object, or is an object without its own method for *name*. **(invoke (*****obj generic*****) *****self arg ...*****)** Invokes the method that object *obj* implements for generic procedure *generic*, passing it *self* and *arg ...* as arguments, instead of *obj* and *arg ...*. This is used to call an overridden method of a delegatee object while keeping the identity of the overriding object, as illustrated by the `colored-point` example in the introduction above: `(invoke (super object-description) self)` calls the `object-description` method implemented by the `super` delegate, but passes the colored point itself, rather than `super`, as `self`. Unlike applying *generic* directly to *obj*, `invoke` signals an error if *obj* does not implement *generic*, since it does not fall back to a default implementation. ## Procedural class interface **class-type-tag** Symbol representing the `class` type. The `type-for` procedure of library `(lispkit type)` returns this symbol for all class objects. **(class? *****obj*****)** Returns `#t` if *obj* is a class object, `#f` otherwise. **root** The root class object. All class objects have `root` as its direct or indirect superclass object. **(make-class *****name superclasses constructor*****)** Returns a new class whose name is *name*, which needs to be a symbol, or an error is signaled. *superclasses* is a list of superclass objects, each of which needs to satisfy `class?`, or an error is signaled. *constructor* is a procedure, or an error is signaled; it is called whenever an instance of this new class is being created via `make-instance`, with the arguments passed to `make-instance`, and it needs to return two values: 1. A list of *delegate* objects, one for each class listed in *superclasses*, in the same order; `make-instance` checks that the *n*-th delegate satisfies `(instance-of? (list-ref superclasses n) delegate)`, and signals an error otherwise. This is how instances of the new class inherit the methods of their superclasses (see `object` for how delegate objects contribute methods). 2. An initializer procedure `(lambda (instance) ...)`, called by `make-instance` with the newly created *instance* once its delegates have been combined and its `object-class` method has been set up (so that `object-class` and, transitively, `class-name` are already available within the initializer). The initializer is typically used to `add-method!` further methods to *instance* that are specific to the new class, rather than inherited from a delegate. The `define-class` syntax provides a more convenient, declarative way to create classes, expanding into a call to `make-class` with a suitably constructed *constructor* procedure. The following example defines a simple `counter` class directly via `make-class`, without any superclasses. Its constructor takes an initial count and returns the two required values: an empty list of delegates (since `counter` has no superclasses) and an initializer procedure that adds `counter-value` and `counter-increment!` methods to the new instance, closing over a private, mutable `count` variable: ```scheme (define-generic (counter-value self)) (define-generic (counter-increment! self)) (define counter (make-class 'counter '() (lambda (initial) (values '() (lambda (instance) (let ((count initial)) (add-method! instance counter-value (lambda (self) count)) (add-method! instance counter-increment! (lambda (self) (set! count (+ count 1)) count)))))))) ``` Since the constructor's `let` is re-evaluated for every call to `make-instance`, each instance of `counter` gets its own, independent `count`: ```scheme (define c1 (make-instance counter 10)) (define c2 (make-instance counter 100)) (counter-increment! c1) ⇒ 11 (counter-increment! c1) ⇒ 12 (counter-value c1) ⇒ 12 (counter-value c2) ⇒ 100 (class-name (object-class c1)) ⇒ counter (instance-of? counter c1) ⇒ #t ``` This is exactly the underlying mechanism that `define-class` builds on: it expands into a call to `make-class` whose constructor validates and processes *args*, evaluates the `object` expression's delegate clauses into a list of delegates, and wraps the `object` expression's method clauses into an initializer procedure, closely resembling the `counter` example above. ### Instance methods **(object-class *****obj*****)** Returns the class of object *obj*. **(object-equal? *****obj other*****)** Returns `#t` if *obj* and *other* are considered equal objects. The default implementation (used by objects and classes that do not provide their own `object-equal?` method) compares *obj* and *other* with `equal?`. Since objects internally wrap a list of methods (closures), and closures are only `equal?` to themselves, this default effectively behaves like an identity comparison for most objects: two separately constructed objects with equivalent state, but without a custom `object-equal?` method, are generally not considered equal, e.g. `(object-equal? (make-instance point 1 2) (make-instance point 1 2)) ⇒ #f`, even though both instances represent the same coordinates. Classes that need value-based equality should implement their own `object-equal?` method. **(object-description *****obj*****)** Returns a string representation of object *obj*. The default implementation (used by objects and classes that do not provide their own `object-description` method) converts *obj* to a string via `write`, e.g. `(object-description (make-object)) ⇒ "#>"`. ### Class methods **(class-name *****class*****)** Returns the class name of *class*. **(class-direct-superclasses *****class*****)** Returns a list of superclass objects of *class*. **(subclass? *****class other*****)** Returns `#t` if *class* is a subclass of class *other*, `#f` otherwise. **(make-instance *****class arg ...*****)** Creates and returns a new object of *class*. *arg ...* are the constructor arguments passed to the constructor of *class*. **(instance-of? *****class obj*****)** Returns `#t` if *obj* is an instance of *class*. ## Declarative class interface **(define-class (*****name . args*****)** \ **(*****super ...*****)**\ ***init ...***\ **(object ((*****delegatevar delegate*****) ...)**\ **((*****generic self arg ... . rest*****) *****e1 e2 ...*****) ...))**\ **(define-class (*****name . args*****)**\ ***pred?***\ **(*****super ...*****)**\ ***init ...***\ **(object ((*****delegatevar delegate*****) ...)**\ **((*****generic self arg ... . rest*****) *****e1 e2 ...*****) ...))** Defines *name* as a new class via `make-class`. The constructor of the class takes *args* and is expressed in terms of an `object` expression: each *(delegatevar delegate)* clause becomes a delegate of instances created by this class, and each *((generic self arg ... . rest) e1 e2 ...)* clause becomes a method implementation of instances of *name*, exactly as with the `object` syntax. The optional *init ...* expressions are evaluated first, in terms of *args*, before the delegates and methods are set up; they are typically used for validating constructor arguments, as illustrated by the `colored-point` example in the introduction above, which signals an error if the given coordinates are negative. The second form additionally names a type predicate *pred?* for instances of *name*, meant to be equivalent to `(lambda (obj) (instance-of? name obj))`. While the `point`/`colored-point` example in the introduction above shows single inheritance combined with method overriding via `invoke`, a class may also list several superclasses at once. In that case, the `object` expression needs to provide one delegate per superclass, listed in the same order as the superclasses; `make-instance` checks that each delegate is indeed an instance of the corresponding superclass. This is how independently defined classes can be combined via multiple inheritance, without any of the combined classes having to know about each other. The following example defines two small, independent classes, `movable` and `colored`, and then combines both into a `sprite` class that inherits all of their methods purely through delegation, without needing to override or re-implement anything itself: ```scheme (define-generic (position self)) (define-generic (move! self dx dy)) (define-generic (color self)) (define-class (movable x y) () (object () ((position self) (cons x y)) ((move! self dx dy) (set! x (+ x dx)) (set! y (+ y dy))))) (define-class (colored color-name) colored? () (object () ((color self) color-name))) ``` Class `sprite` lists both `movable` and `colored` as superclasses, and provides one delegate for each, created via `make-instance`. Since `sprite` does not need to customize any inherited behavior, its `object` expression has no method clauses of its own; all of its methods are contributed entirely by its two delegates: ```scheme (define-class (sprite x y color-name) (movable colored) (object ((pos (make-instance movable x y)) (col (make-instance colored color-name))))) ``` Instances of `sprite` behave exactly like instances of `movable` and `colored` for the generic procedures `position`, `move!`, and `color`, while `object-class` and `class-name` still correctly identify them as `sprite` objects, and each instance keeps its own, independent state: ```scheme (define s1 (make-instance sprite 0 0 'red)) (define s2 (make-instance sprite 10 10 'blue)) (color s1) ⇒ red (position s1) ⇒ (0 . 0) (move! s1 3 4) (position s1) ⇒ (3 . 4) (position s2) ⇒ (10 . 10) (instance-of? movable s1) ⇒ #t (colored? s1) ⇒ #t (class-name (object-class s1)) ⇒ sprite ```