217 lines
10 KiB
HTML
217 lines
10 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
|
|
<!Converted with LaTeX2HTML 0.6.5 (Tue Nov 15 1994) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
|
|
<HEAD>
|
|
<TITLE>19.2. How to Use Defstruct</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<meta name="description" value=" How to Use Defstruct">
|
|
<meta name="keywords" value="clm">
|
|
<meta name="resource-type" value="document">
|
|
<meta name="distribution" value="global">
|
|
<P>
|
|
<b>Common Lisp the Language, 2nd Edition</b>
|
|
<BR> <HR><A NAME=tex2html3654 HREF="node171.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html3652 HREF="node168.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html3646 HREF="node169.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html3656 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html3657 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
|
<B> Next:</B> <A NAME=tex2html3655 HREF="node171.html"> Using the Automatically </A>
|
|
<B>Up:</B> <A NAME=tex2html3653 HREF="node168.html"> Structures</A>
|
|
<B> Previous:</B> <A NAME=tex2html3647 HREF="node169.html"> Introduction to Structures</A>
|
|
<HR> <P>
|
|
<H1><A NAME=SECTION002320000000000000000>19.2. How to Use Defstruct</A></H1>
|
|
<P>
|
|
All structures are defined through the <tt>defstruct</tt> construct.
|
|
A call to <tt>defstruct</tt> defines a new data type whose instances
|
|
have named slots.
|
|
<P>
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
|
<BR><b>[Macro]</b><BR>
|
|
<pre>
|
|
defstruct <i>name-and-options</i> [<i>doc-string</i>] {<i>slot-description</i>}+
|
|
</pre>
|
|
<P>X3J13 voted in June 1988
|
|
(DEFSTRUCT-SLOTS-CONSTRAINTS-NUMBER) <A NAME=18488> </A>
|
|
to allow a <tt>defstruct</tt> definition
|
|
to have no <i>slot-description</i> at all; in other words, the
|
|
occurrence of <i>slot-description</i> in the preceding
|
|
header line would be replaced by <i>slot-description</i>.
|
|
<P>
|
|
Such structure definitions are particularly useful if the
|
|
<tt>:include</tt> 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 <tt>:print-function</tt> options).
|
|
<P>
|
|
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.
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
|
<P>
|
|
This defines a record-structure data type.
|
|
A general call to <tt>defstruct</tt> looks like the following example.
|
|
<pre>
|
|
(defstruct (<i>name</i> <i>option-1</i> <i>option-2</i> ... <i>option-m</i>)
|
|
<i>doc-string</i>
|
|
<i>slot-description-1</i>
|
|
<i>slot-description-2</i>
|
|
...
|
|
<i>slot-description-n</i>)
|
|
</pre><P>
|
|
The <i>name</i> must be a symbol; it becomes the name of a new data type
|
|
consisting of all instances of the structure.
|
|
The function <tt>typep</tt> will accept and use this name
|
|
as appropriate. The <i>name</i> is returned as the value of the <i>defstruct</i>
|
|
form.
|
|
<P>
|
|
Usually no options are needed at all.
|
|
If no options are specified, then one may write simply <i>name</i> instead
|
|
of <tt>(<i>name</i>)</tt> after the word <tt>defstruct</tt>. The syntax of options
|
|
and the options provided are discussed in section <A HREF="node173.html#DEFSTRUCTOPTIONS">19.5</A>.
|
|
<P>
|
|
If the optional documentation string <i>doc-string</i> is present,
|
|
then it is attached to the <i>name</i>
|
|
as a documentation string of type <tt>structure</tt>; see <tt>documentation</tt>.
|
|
<P>
|
|
Each <i>slot-description-j</i> is of the form
|
|
<P><CODE>
|
|
(<i>slot-name</i> <i>default-init</i>
|
|
<i>slot-option-name-1</i> <i>slot-option-value-1</i>
|
|
<i>slot-option-name-2</i> <i>slot-option-value-2</i>
|
|
...
|
|
<i>slot-option-name-kj</i> <i>slot-option-value-kj</i>)
|
|
<P>
|
|
</CODE><P>
|
|
Each <i>slot-name</i> must be a symbol; an access function is defined
|
|
for each slot. If no options and no <i>default-init</i> are specified,
|
|
then one may write simply <i>slot-name</i> instead of <tt>(<i>slot-name</i>)</tt>
|
|
as the slot description.
|
|
<P>
|
|
<img align=bottom alt="old_change_begin" src="gif/old_change_begin.gif"><br>
|
|
The <i>default-init</i> is a form that is
|
|
evaluated <i>each time</i> a structure is to be constructed; the value
|
|
is used as the initial value of the slot.
|
|
<br><img align=bottom alt="old_change_end" src="gif/old_change_end.gif">
|
|
<P>
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
|
X3J13 voted in October 1988 (DEFSTRUCT-DEFAULT-VALUE-EVALUATION) <A NAME=18541> </A>
|
|
to clarify that a <i>default-init</i> form is evaluated only if the corresponding
|
|
argument is not supplied to the constructor function. The preceding
|
|
sentence should therefore read as follows:
|
|
<P>
|
|
The <i>default-init</i> is a form that is
|
|
evaluated <i>each time</i> its value
|
|
is to be used as the initial value of the slot.
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
|
<P>
|
|
If no <i>default-init</i>
|
|
is specified, then the initial contents of the slot are undefined
|
|
and implementation-dependent. The available slot-options are
|
|
described in section <A HREF="node172.html#DefstructSlotOptions">19.4</A>.
|
|
<P>
|
|
<hr>
|
|
<b>Compatibility note:</b> Slot-options are not currently provided
|
|
in Lisp Machine Lisp, but this is an upward-compatible extension.
|
|
<hr>
|
|
<P>
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
|
X3J13 voted in January 1989
|
|
(DEFSTRUCT-SLOTS-CONSTRAINTS-NAME) <A NAME=18551> </A>
|
|
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 <tt>string=</tt> would be true.
|
|
Under this interpretation
|
|
<P><CODE>
|
|
(defstruct lotsa-slots slot slot)
|
|
<P>
|
|
</CODE><P>
|
|
obviously is incorrect
|
|
but the following one is also in error, even assuming that the symbols
|
|
<tt>coin:slot</tt> and <tt>blot:slot</tt> really are distinct (non-<tt>eql</tt>) symbols:
|
|
<P><CODE>
|
|
(defstruct no-dice coin:slot blot:slot)
|
|
<P>
|
|
</CODE><P>
|
|
To illustrate another case, the first <tt>defstruct</tt> form below is
|
|
correct, but the second one is in error.
|
|
<P><CODE>
|
|
(defstruct one-slot slot)
|
|
(defstruct (two-slots (:include one-slot)) slot)
|
|
<P>
|
|
</CODE><P>
|
|
<P>
|
|
<hr>
|
|
<b>Rationale:</b> Print names are the criterion for slot-names being the same, rather
|
|
than the symbols themselves, because <tt>defstruct</tt> constructs names
|
|
of accessor functions from the print names and interns the resulting
|
|
new names in the current package.
|
|
<hr>
|
|
<P>
|
|
X3J13 recommended that expanding
|
|
a <tt>defstruct</tt> form violating this
|
|
restriction should signal an error and noted, with an eye to the Common Lisp
|
|
Object System
|
|
(CLOS) <A NAME=18567> </A> , that the restriction applies only to the operation of the
|
|
<tt>defstruct</tt> macro as such and not to the <tt>structure-class</tt> or
|
|
structures defined with <tt>defclass</tt>.
|
|
<P>
|
|
X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL) <A NAME=18573> </A>
|
|
to clarify that, while defining forms normally appear at top level,
|
|
it is meaningful to place them in non-top-level contexts;
|
|
<tt>defstruct</tt> must treat slot <i>default-init</i> 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.
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
|
<P>
|
|
<tt>defstruct</tt> not only defines an access function for each slot, but also
|
|
arranges for <tt>setf</tt> to work properly on such access functions,
|
|
defines a predicate named <tt><i>name</i>-p</tt>,
|
|
defines a constructor function named <tt>make-<i>name</i></tt>,
|
|
and defines a copier function named <tt>copy-<i>name</i></tt>.
|
|
All names of automatically created functions are interned
|
|
in whatever package is current at the time the <tt>defstruct</tt>
|
|
form is processed (see <tt>*package*</tt>).
|
|
Also, all such functions may be declared <tt>inline</tt>
|
|
at the discretion of the implementation to improve efficiency;
|
|
if you do not want some function declared <tt>inline</tt>,
|
|
follow the <tt>defstruct</tt> form with a <tt>notinline</tt> declaration
|
|
to override any automatic <tt>inline</tt> declaration.
|
|
<P>
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
|
X3J13 voted in January 1989 (DEFSTRUCT-REDEFINITION) <A NAME=18591> </A>
|
|
to specify that the results of redefining a <tt>defstruct</tt> structure
|
|
(that is, evaluating more than one <tt>defstruct</tt> structure
|
|
for the same name) are undefined.
|
|
<P>
|
|
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 <tt>inline</tt> and compiled
|
|
into code that remains accessible after the new definition has been
|
|
evaluated; such code may be incompatible with the new instances.
|
|
<P>
|
|
In practice this restriction affects the development
|
|
and debugging process rather than production runs of fully developed code.
|
|
The <tt>defstruct</tt> feature is intended to provide
|
|
``the most efficient'' structure class.
|
|
CLOS classes defined by <tt>defclass</tt>
|
|
allow much more flexible structures to be defined and redefined.
|
|
<P>
|
|
Programming environments are allowed and encouraged to permit <tt>defstruct</tt>
|
|
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.
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
|
<P>
|
|
<BR> <HR><A NAME=tex2html3654 HREF="node171.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html3652 HREF="node168.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html3646 HREF="node169.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html3656 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html3657 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
|
<B> Next:</B> <A NAME=tex2html3655 HREF="node171.html"> Using the Automatically </A>
|
|
<B>Up:</B> <A NAME=tex2html3653 HREF="node168.html"> Structures</A>
|
|
<B> Previous:</B> <A NAME=tex2html3647 HREF="node169.html"> Introduction to Structures</A>
|
|
<HR> <P>
|
|
<HR>
|
|
<P><ADDRESS>
|
|
AI.Repository@cs.cmu.edu
|
|
</ADDRESS>
|
|
</BODY>
|