Common Lisp the Language, 2nd Edition

19.2. How to Use Defstruct

All structures are defined through the defstruct construct. A call to defstruct defines a new data type whose instances have named slots.

[Macro]

defstruct name-and-options [doc-string] {slot-description}+

X3J13 voted in June 1988 (DEFSTRUCT-SLOTS-CONSTRAINTS-NUMBER)   to allow a defstruct definition to have no slot-description at all; in other words, the occurrence of slot-description in the preceding header line would be replaced by slot-description.

Such structure definitions are particularly useful if the :include option is used, perhaps with other options; for example, one can have two structures that are exactly alike except that they print differently (having different :print-function options).

Implementors are encouraged to permit this simple extension as soon as convenient. Users, however, may wish to maximize portability of their code by avoiding the use of this extension unless and until it is adopted as part of the ANSI standard.

This defines a record-structure data type. A general call to defstruct looks like the following example.

(defstruct (name option-1 option-2 ... option-m) 
           doc-string 
           slot-description-1 
           slot-description-2 
           ... 
           slot-description-n) 

The name must be a symbol; it becomes the name of a new data type consisting of all instances of the structure. The function typep will accept and use this name as appropriate. The name is returned as the value of the defstruct form.

Usually no options are needed at all. If no options are specified, then one may write simply name instead of (name) after the word defstruct. The syntax of options and the options provided are discussed in section 19.5.

If the optional documentation string doc-string is present, then it is attached to the name as a documentation string of type structure; see documentation.

Each slot-description-j is of the form

(slot-name default-init slot-option-name-1 slot-option-value-1 slot-option-name-2 slot-option-value-2 ... slot-option-name-kj slot-option-value-kj)

Each slot-name must be a symbol; an access function is defined for each slot. If no options and no default-init are specified, then one may write simply slot-name instead of (slot-name) as the slot description.

The default-init is a form that is evaluated each time a structure is to be constructed; the value is used as the initial value of the slot.

X3J13 voted in October 1988 (DEFSTRUCT-DEFAULT-VALUE-EVALUATION)   to clarify that a default-init form is evaluated only if the corresponding argument is not supplied to the constructor function. The preceding sentence should therefore read as follows:

The default-init is a form that is evaluated each time its value is to be used as the initial value of the slot.

If no default-init is specified, then the initial contents of the slot are undefined and implementation-dependent. The available slot-options are described in section 19.4.

X3J13 voted in January 1989 (DEFSTRUCT-SLOTS-CONSTRAINTS-NAME)   to specify that it is an error for two slots to have the same name; more precisely, no two slots may have names for whose print names string= would be true. Under this interpretation

(defstruct lotsa-slots slot slot)

obviously is incorrect but the following one is also in error, even assuming that the symbols coin:slot and blot:slot really are distinct (non-eql) symbols:

(defstruct no-dice coin:slot blot:slot)

To illustrate another case, the first defstruct form below is correct, but the second one is in error.

(defstruct one-slot slot) (defstruct (two-slots (:include one-slot)) slot)

X3J13 recommended that expanding a defstruct form violating this restriction should signal an error and noted, with an eye to the Common Lisp Object System (CLOS)   , that the restriction applies only to the operation of the defstruct macro as such and not to the structure-class or structures defined with defclass.

X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL)   to clarify that, while defining forms normally appear at top level, it is meaningful to place them in non-top-level contexts; defstruct must treat slot default-init forms and any initialization forms within the specification of a by-position constructor function as occurring within the enclosing lexical environment, not within the global environment.

defstruct not only defines an access function for each slot, but also arranges for setf to work properly on such access functions, defines a predicate named name-p, defines a constructor function named make-name, and defines a copier function named copy-name. All names of automatically created functions are interned in whatever package is current at the time the defstruct form is processed (see *package*). Also, all such functions may be declared inline at the discretion of the implementation to improve efficiency; if you do not want some function declared inline, follow the defstruct form with a notinline declaration to override any automatic inline declaration.

X3J13 voted in January 1989 (DEFSTRUCT-REDEFINITION)   to specify that the results of redefining a defstruct structure (that is, evaluating more than one defstruct structure for the same name) are undefined.

The problem is that if instances have been created under the old definition and then remain accessible after the new definition has been evaluated, the accessors and other functions for the new definition may be incompatible with the old instances. Conversely, functions associated with the old definition may have been declared inline and compiled into code that remains accessible after the new definition has been evaluated; such code may be incompatible with the new instances.

In practice this restriction affects the development and debugging process rather than production runs of fully developed code. The defstruct feature is intended to provide ``the most efficient'' structure class. CLOS classes defined by defclass allow much more flexible structures to be defined and redefined.

Programming environments are allowed and encouraged to permit defstruct redefinition, perhaps with warning messages about possible interactions with other parts of the programming environment or memory state. It is beyond the scope of the Common Lisp language standard to define those interactions except to note that they are not portable.