DEFSTRUCT - "Structure" definition facility.
--------------------------------------------
Defstruct is similar to the Spice (Common) Lisp/Lisp machine/Maclisp flavor
of struct definitions, and is expected to be subsumed by the Mode package.
It is implemented in PSL as a function which builds access macros and fns
for "typed" vectors, including constructor and alterant macros, a type
predicate for the structure type, and individual selector/assignment fns
for the elements. Defstruct understands a keyword-option oriented
structure specification.
First a few miscellaneous functions on types, before we get into the depths
of defining Defstructs:
DefstructP( NAME:id ): extra-boolean expr
---- -- ------------- ----
is a predicate that returns non-NIL (the Defstruct definition) if NAME
is a structured type which has been defined using Defstruct, or NIL if
it is not.
DefstructType( S:struct ): id expr
- ------ -- ----
returns the type name field of an instance of a structured type, or
NIL if S cannot be a defstruct type.
SubTypeP( NAME1:id, NAME2:id ): boolean expr
----- -- ----- -- ------- ----
returns true if NAME1 is a structured type which has been !:Include'd in
the definition of structured type NAME2, possibly through intermediate
structure definitions. (In other words, the selectors of NAME1 can be
applied to NAME2.)
Now the function which defines the beasties, in all its gory glory:
Defstruct( name-and-options:{id,list}, [slot-descs:{id,list}] ): id fexpr
---------------- -- ---- ---------- -- ---- -- -----
Defines a record-structure data type. A general call to defstruct
looks like this: (in Rlisp syntax)
defstruct( struct-name( option-1, option-2, ... ),
slot-description-1,
slot-description-2,
...
); % (The name of the defined structure is returned.)
where slot-descriptions are:
slot-name( default-init, slot-option-1, slot-option-2, ... )
Struct-name and slot-name are id's. If there are no options following
a name in a spec, it can be a bare id with no option argument list.
The default-init form is optional and may be omitted. The default-init
form is evaluated EACH TIME a structure is to be constructed and the
value is used as the initial value of the slot. Options are either a
keyword id, or the keyword followed by its argument list. Options are
described below.
A call to a Constructor macro has the form:
MakeThing( slot-name-1( value-expr-1 ),
slot-name-2( value-expr-2 ),
... );
where the slot-name:value lists override the default-init values
which were part of the structure definition. Note that the
slot-names look like unary functions of the value, so the parens can
be left off. A call to MakeThing with no arguments of course takes
all of the default values. The order of evaluation of the
default-init forms and the list of assigned values is undefined, so
code should not depend upon the ordering.
Implementors Note: Common/LispMachine Lisps define it this
way, but Is this necessary? It wouldn't be too tough to
make the order be the same as the struct defn, or the
argument order in the constructor call. Maybe they think
such things should not be advertized and thus constrained
in the future. Or perhaps the theory is that constucts
such as this can be compiled more efficiently if the
ordering is flexible?? Also, should the overridden
default-init forms be evaluated or not? I think not.
The Alterant macro calls have a similar form:
AlterThing( thing,
slot-name-1 value-expr-1,
slot-name-2 value-expr-2,
... );
where the first argument evaluates to the struct to be altered. (The
optional parens were left off here.) This is just a
multiple-assignment form, which eventually goes through the slot
depositors. Remember that the slot-names are used, not the depositor
names. (See !:Prefix, below.) The altered structure instance
is returned as the value of an Alterant macro.
Implementators note: Common/LispMachine Lisp defines this
such that all of the slots are altered in parallel AFTER
the new value forms are evaluated, but still with the order
of evaluation of the forms undefined. This seemed to lose
more than it gained, but arguments for its worth will be
entertained.
Options:
Structure options appear as an argument list to the struct-name. Many
of the options themselves take argument lists, which are sometimes
optional. Option id's all start with a colon (!:), on the theory that
this distinguishes them from other things.
By default, the names of the constructor, alterant and predicate
macros are MakeName, AlterName and NameP, where "Name" is the
struct-name. The !:Constructor, !:Alterant, and !:Predicate options
can be used to override the default names. Their argument is the
name to use, and a name of NIL causes the respective macro not to be
defined at all.
The !:Creator option causes a different form of constructor to be
defined, in addition to the regular "Make" constructor (which can be
suppressed.) As in the !:Constructor option above, an argument
supplies the name fo the macro, but the default name in this case is
CreateName. A call to a Creator macro has the form:
CreateThing( slot-value-1, slot-value-2, ... );
where ALL of the slot-values of the structure MUST BE PRESENT, in the
order they appear in the structure definition. No checking is done,
other than assuring that the number of values is the same as the
number of slots. For obvous reasons, constructors of this form ARE
NOT RECOMMENDED for structures with many fields, or which may be
expanded or modified.
Slot selector macros may appear on either the LHS or the RHS of an
assignment. They are by default named the same as the slot-names,
but can be given a common prefix by the !:Prefix option. If
!:Prefix does not have an argument, the structure name is the
prefix. If there is an argument, it should be a string or an id
whose printname is the prefix.
The !:Include option allows building a new structure definition as an
extension of an old one. The required argument is the name of a
previously defined structure type. The access functions for the
slots of the source type will also work on instances of the new type.
This can be used to build hierarchies of types, where the source
types contain generic information in common to the more specific
subtypes which !:Include them.
The !:IncludeInit option takes an argument list of
"slot-name(default-init)" pairs, like slot-descriptors without
slot-options, and files them away to modify the default-init values for
fields inherited as part of the !:Include'd structure type.
Slot Options:
Slot-options include the !:Type option, which has an argument
declaring the type of the slot as a type id or list of permissible
type id's. This is not enforced now, but anticipates the Mode system
structures.
The !:UserGet and !:UserPut slot-options allow overriding the simple
vector reference and assignment semantics of the generated selector
macros with user-defined functions. The !:UserGet fn name is a
combination of the slot-name and a !:Prefix if applicable. The
!:UserPut fn name is the same, with "Put" prefixed. One application
of this capability is building depositors which handle the
incremental maintenance of parallel datastructures as a side effect,
such as automatically maintaining display file representations of
objects which are resident in a remote display processor in parallel
with modifications to the Lisp structures which describe the objects.
The Make and Create macros bypass the depositors, while Alter uses them.
A simple example: (Input lines have a "> " prompt at the beginning.)
> % (Do definitions twice to see what functions were defined.)
> macro procedure TWICE u; list( 'PROGN, second u, second u );
TWICE
> % A definition of Complex, structure with Real and Imaginary parts.
> % Redefine to see what functions were defined. Give 0 Init values.
> TWICE
> Defstruct( Complex( !:Creator(Complex) ), R(0), I(0) );
*** Function `MAKECOMPLEX' has been redefined
*** Function `ALTERCOMPLEX' has been redefined
*** Function `COMPLEXP' has been redefined
*** Function `COMPLEX' has been redefined
*** Function `R' has been redefined
*** Function `PUTR' has been redefined
*** Function `I' has been redefined
*** Function `PUTI' has been redefined
*** Defstruct `COMPLEX' has been redefined
COMPLEX
> C0 := MakeComplex(); % Constructor with default inits.
[COMPLEX 0 0]
> ComplexP C0; % Predicate.
T
> C1:=MakeComplex( R 1, I 2 ); % Constructor with named values.
[COMPLEX 1 2]
> R(C1); I(C1); % Named selectors.
1
2
> C2:=Complex(3,4) % Creator with positional values.
[COMPLEX 3 4]
> AlterComplex( C1, R(2), I(3) ); % Alterant with named values.
[COMPLEX 2 3]
> C1;
[COMPLEX 2 3]
> R(C1):=5; I(C1):=6; % Named depositors.
5
6
> C1;
[COMPLEX 5 6]
> % Show use of Include Option. (Again, redef to show fns defined.)
> TWICE
> Defstruct( MoreComplex( !:Include(Complex) ), Z(99) );
*** Function `MAKEMORECOMPLEX' has been redefined
*** Function `ALTERMORECOMPLEX' has been redefined
*** Function `MORECOMPLEXP' has been redefined
*** Function `Z' has been redefined
*** Function `PUTZ' has been redefined
*** Defstruct `MORECOMPLEX' has been redefined
MORECOMPLEX
> M0 := MakeMoreComplex();
[MORECOMPLEX 0 0 99]
> M1 := MakeMoreComplex( R 1, I 2, Z 3 );
[MORECOMPLEX 1 2 3]
> R C1;
5
> R M1;
1
> % A more complicated example: The structures which are used in the
> % Defstruct facility to represent defstructs. (The EX prefix has
> % been added to the names to protect the innocent...)
> TWICE % Redef to show fns generated.
> Defstruct(
> EXDefstructDescriptor( !:Prefix(EXDsDesc), !:Creator ),
> DsSize( !:Type int ), % (Upper Bound of vector.)
> Prefix( !:Type string ),
> SlotAlist( !:Type alist ), % (Cdrs are SlotDescriptors.)
> ConsName( !:Type fnId ),
> AltrName( !:Type fnId ),
> PredName( !:Type fnId ),
> CreateName( !:Type fnId ),
> Include( !:Type typeid ),
> InclInit( !:Type alist )
> );
*** Function `MAKEEXDEFSTRUCTDESCRIPTOR' has been redefined
*** Function `ALTEREXDEFSTRUCTDESCRIPTOR' has been redefined
*** Function `EXDEFSTRUCTDESCRIPTORP' has been redefined
*** Function `CREATEEXDEFSTRUCTDESCRIPTOR' has been redefined
*** Function `EXDSDESCDSSIZE' has been redefined
*** Function `PUTEXDSDESCDSSIZE' has been redefined
*** Function `EXDSDESCPREFIX' has been redefined
*** Function `PUTEXDSDESCPREFIX' has been redefined
*** Function `EXDSDESCSLOTALIST' has been redefined
*** Function `PUTEXDSDESCSLOTALIST' has been redefined
*** Function `EXDSDESCCONSNAME' has been redefined
*** Function `PUTEXDSDESCCONSNAME' has been redefined
*** Function `EXDSDESCALTRNAME' has been redefined
*** Function `PUTEXDSDESCALTRNAME' has been redefined
*** Function `EXDSDESCPREDNAME' has been redefined
*** Function `PUTEXDSDESCPREDNAME' has been redefined
*** Function `EXDSDESCCREATENAME' has been redefined
*** Function `PUTEXDSDESCCREATENAME' has been redefined
*** Function `EXDSDESCINCLUDE' has been redefined
*** Function `PUTEXDSDESCINCLUDE' has been redefined
*** Function `EXDSDESCINCLINIT' has been redefined
*** Function `PUTEXDSDESCINCLINIT' has been redefined
*** Defstruct `EXDEFSTRUCTDESCRIPTOR' has been redefined
EXDEFSTRUCTDESCRIPTOR
> TWICE % Redef to show fns generated.
> Defstruct(
> EXSlotDescriptor( !:Prefix(EXSlotDesc), !:Creator ),
> SlotNum( !:Type int ),
> InitForm( !:Type form ),
> SlotFn( !:Type fnId ), % Selector/Depositor id.
> SlotType( !:Type type ), % Hm...
> UserGet( !:Type boolean ),
> UserPut( !:Type boolean )
> );
*** Function `MAKEEXSLOTDESCRIPTOR' has been redefined
*** Function `ALTEREXSLOTDESCRIPTOR' has been redefined
*** Function `EXSLOTDESCRIPTORP' has been redefined
*** Function `CREATEEXSLOTDESCRIPTOR' has been redefined
*** Function `EXSLOTDESCSLOTNUM' has been redefined
*** Function `PUTEXSLOTDESCSLOTNUM' has been redefined
*** Function `EXSLOTDESCINITFORM' has been redefined
*** Function `PUTEXSLOTDESCINITFORM' has been redefined
*** Function `EXSLOTDESCSLOTFN' has been redefined
*** Function `PUTEXSLOTDESCSLOTFN' has been redefined
*** Function `EXSLOTDESCSLOTTYPE' has been redefined
*** Function `PUTEXSLOTDESCSLOTTYPE' has been redefined
*** Function `EXSLOTDESCUSERGET' has been redefined
*** Function `PUTEXSLOTDESCUSERGET' has been redefined
*** Function `EXSLOTDESCUSERPUT' has been redefined
*** Function `PUTEXSLOTDESCUSERPUT' has been redefined
*** Defstruct `EXSLOTDESCRIPTOR' has been redefined
EXSLOTDESCRIPTOR
> END;
NIL