Node:Object Properties, Next:, Previous:Equality, Up:Utility Functions

24.2 Object Properties

It's often useful to associate a piece of additional information with a Scheme object even though that object does not have a dedicated slot available in which the additional information could be stored. Object properties allow you to do just that.

An object property is most commonly used to associate one kind of additional information with each instance of a class of similar Scheme objects. For example, all procedures have a `name' property, which stores the name of the variable in which the procedure was stored by a define expression, or #f if the procedure wasn't created by that kind of expression.

Guile's representation of an object property is a procedure-with-setter (see Procedures with Setters) that can be used with the generalized form of set! (REFFIXME) to set and retrieve that property for any Scheme object. So, setting a property looks like this:

(set! (my-property obj1) value-for-obj1)
(set! (my-property obj2) value-for-obj2)

And retrieving values of the same property looks like this:

(my-property obj1)

(my-property obj2)

To create an object property in the first place, use the make-object-property procedure:

(define my-property (make-object-property))

make-object-property Scheme Procedure
Create and return an object property. An object property is a procedure-with-setter that can be called in two ways. (set! (property obj) val) sets obj's property to val. (property obj) returns the current setting of obj's property.

A single object property created by make-object-property can associate distinct property values with all Scheme values that are distinguishable by eq? (including, for example, integers).

Internally, object properties are implemented using a weak key hash table. This means that, as long as a Scheme value with property values is protected from garbage collection, its property values are also protected. When the Scheme value is collected, its entry in the property table is removed and so the (ex-) property values are no longer protected by the table.