HELP RECORDCLASS                               John Williams, March 1986
                                           Updated John Gibson, May 1990

      --------------------------------------------------------
      | Note: The more powerful construct -defclass- can now |
      | be used instead of -recordclass-. See REF *DEFSTRUCT |
      --------------------------------------------------------

    recordclass [identspec] <classname> <field1>
                                    <field2> <field3> ... <fieldn>;

    Define a new recordclass, providing records with n fields.

         CONTENTS - (Use <ENTER> g to access required sections)

 -- Overview
 -- Arguments that may be given to RECORDCLASS
 -- Example
 -- Recompiling a RECORDCLASS declaration
 -- See also

-- Overview -----------------------------------------------------------

RECORDCLASS is a  macro that provides convenient syntax for defining a
new record  class. E.g. a three element record might be defined thus:

    recordclass triple first second third;

This would define a record class whose data-word is "triple", along
with a number of procedures for manipulating triples, constriple,
desttriple, istriple, first, second and third. What this means is
explained more fully below.

Everything recordclass does can be done using *CONSKEY, but with less
convenience.

It  automatically   defines  constructor,  destructor,   and  recogniser
procedures for  the new class; access/update procedures for  each field;
and a variable containing its key. Examples are given below.


-- Arguments that may be given to recordclass -------------------------

The <classname> specifies the dataword of the class.

The format of each <field> is:

    <fieldname> [: <fieldspec>]

where the fieldname can be any legal Pop-11 identifier, and the optional
<fieldspec> specifies the type of object that may be stored in the given
field. More precisely it  specifies the SIZE of  the object, namely  how
many bits  it should  take, and  whether it  is a  pointer or  a  number
(integer or decimal).

The <fieldspec> if provided can be either
   -the word "full", indicating that ANY Poplog data-type may be
    stored there,
OR
   -an  integer, indicating the size of the field. In the later case
    only an integer or decimal can be stored in the field.

If no <fieldspec>  is given, the  default is "full".  See REF *KEYS  for
more details.

The <field>s may be separated by commas.

The optional <identspec> specifies the status of the identifiers created
by RECORDCLASS. One of  "constant" and "vars" may  be used, to  indicate
that the identifers should  or should not be  made constant, and one  of
"procedure" or 0 may be used, to indicate their *IDENTTYPE.

If neither "constant" nor "vars" is specified, the identifier status  is
defaulted from the variable  *POPDEFINECONSTANT; if neither  "procedure"
nor 0 is specified, the identifier  type is defaulted from the  variable
*POPDEFINEPROCEDURE.

-- Example -------------------------------------------------------------

The statement

    recordclass point colour xof:16 yof:16 ;

creates procedures

    conspoint, destpoint, ispoint, colour, xof, yof

and declares the variable

    point_key

with the new key as its value.

The COLOUR field of a point record may be any object, but the XOF and
YOF fields must be integers in the range 0 to (2 ** 16) - 1.

-- Recompiling a RECORDCLASS declaration ------------------------------

RECORDCLASS has been defined so that if you re-compile a file containing
a call of recordclass it will not construct a new key.  More precisely,
when a RECORDCLASS declaration is executed the value of the word
<name>_key is examined and if the value is a key and its specification
is the same as the specification in the declaration then a new key will
not be constructed, although the procedures associated with the key
(selectors, constructers etc.) will be reassigned to the variables that
should contain them.

This behaviour ensures that, if the declaration has not changed, then
the old constructors, selectors, etc. will continue to work on
structures already created.  If for any reason you wish the declaration
to be re-executed, then you should assign some non-key object (e.g.
undef) to the key name.  E.g. in the above example:

    undef -> point_key;

This will force the construction of a new key.  Any previously
constructed records using the old constructor will not work with the new
field selectors/updaters and will not be recognised as instances of the
new key.

-- See also ------------------------------------------------------------

    HELP *ISRECORDCLASS
    HELP *RECORDS
    HELP *VECTORCLASS
    HELP *CLASSES
    REF  *KEYS

For full details: SHOWLIB * RECORDCLASS

--- C.all/help/recordclass
--- Copyright University of Sussex 1988. All rights reserved. ----------