The record extension to Elk allows Scheme applications to define x "record data type" record data types (similar to, although less powerful than, Common Lisp x structures \f2structures).
A record type can be instantiated to obtain a new x record record (a member of the given record type). Each record is a collection of named x fields fields that can hold arbitrary Scheme objects. Records are first-class Scheme objects; they are members of the \f2record data type that is disjoint from all other Scheme types. Record types are first-class objects as well; each record type is a member of the \f2record-type Scheme data type.
The record extension provides facilities to define new record types, create x instances instances of existing record types, define x accessor accessor and x modifier modifier functions to read and write the fields of records of a given type, and x "type predicate" type predicates for the \f2record and \f2record-type data types.
In addition, the extension provides x macros macros that simplify the definition of x constructor constructor, accessor and modifier functions for a newly defined record type. . .Ch "Using the Record Extension" .
The record extension is loaded by evaluating .Ss (require 'record) .Se in the interactive toplevel or in a Scheme program.
This causes the files x record.scm \f2record.scm and x record.o \f2record.o to be loaded into the interpreter (\f2record.o has to be linked with the interpreter on platforms that do not support dynamic loading of object files).
Loading the record extension causes the x feature features \f2record and \f2record.o to be provided. . .Ch "Record Types" .
r make-record-type type-name fields
\f2make-record-type creates a new x "record type" record type. \f2type-name (a string or a symbol) is the name of the record type; it is used in the printed representation of the record type and of records belonging to the new type. If \f2type-name is a symbol, it is converted into a string first. x fields \f2fields is a list of symbols naming the fields of a record of the new type. An error is signaled of the list contains duplicate names.
\f2make-record-type returns the new record type (an object of the Scheme type \f2record-type).
Example: .Ss (define time-record (make-record-type 'time '(hours minutes seconds))) .Se .
r record-type? obj
This x "type predicate" type predicate returns #t if \f2obj is a \f2record-type object (i.\|e. the return value of a call to \f2make-record-type), #f otherwise. .
r record-type-name rt
This procedure returns the x "type name" type name (a string) of the record type \f2rt, i.\|e. the \f2type-name argument that was supplied to the call to \f2make-record-type that created the record type \f2rt. .
r record-type-field-names rt
\f2record-type-field-names returns the list of x "field names" field names associated with the record type \f2rt (a list of symbols), i.\|e. the \f2fields argument that was given in the call to x make-record-type \f2make-record-type that created \f2rt. . .[[
r record-constructor rt fields
r record-constructor rt .]]
\f2record-constructor returns a procedure for creating x instances instances of the record type \f2rt.
The returned procedure accepts as many arguments as there are symbols in the list \f2fields; these arguments are used as the initial values of those x fields fields in the newly created record instance. The values of any fields for which no x "initial value" initial value is specified (i.\|e. that are not present in \f2fields) are undefined. If the \f2fields argument is omitted, the field names that were given as an argument in the call to x make-record-type \f2make-record-type that created the record type \f2rt are used instead.
Example: .Ss (define make-time (record-constructor time-record)) (define noon (make-time 12 0 0)) (define make-uninitialized-time (record-constructor time-record '())) .Se .
r record-predicate rt
\f2record-predicate returns a procedure for testing membership in the record type \f2rt. The returned procedure accepts one argument and returns #t if the argument is a member of the record type \f2rt (i.\|e. if it has been created by invoking a constructor returned by calling x record constructor \f2record-constructor with \f2rt as an argument), #f otherwise. .
r record-accessor rt field
\f2record-accessor returns a procedure for reading the value of the x field field named by \f2field of a member of the record type \f2rt. The returned procedure accepts one argument, which must be a record of the record type \f2rt; it returns the current value of the specified field in that record. \f2field must be a member of the list of field names that was supplied to the call to x make-record-type \f2make-record-type that created \f2rt.
Example: .Ss (define time-hours (record-accessor time-record 'hours)) (define noon ((record-constructor time-record) 12 0 0)) (time-hours noon) \f2\(-> 12 .Se .
r record-modifier rt field
\f2record-modifier returns a procedure for writing the value of the x field field named by \f2field of a member of the record type \f2rt. The returned procedure accepts two arguments: a record of the record type \f2rt and an arbitrary object; it stores the given object into the specified field in that record and returns the previous value of the field. \f2field must be a member of the list of field names that was supplied to the call to x make-record-type \f2make-record-type that created \f2rt.
Example .Ss (define set-time-hours! (record-modifier time-record 'hours)) .Se .
r describe-record-type rt
This procedure prints the names of the x fields fields associated with the record type \f2rt; it is automatically invoked by the standard x describe \f2describe procedure of Elk if \f2describe is invoked with a record type. . .Ch "Records" .
r record? obj
This x "type predicate" type predicate returns #t if \f2obj is an object of type \f2record (i.\|e. the return value of a call to a record x constructor constructor of any record type), #f otherwise. .
r record-type-descriptor record
This procedure returns the x "record type" record type representing the type of the given record. The returned record type object is equal (in the sense of \f2eq?) to the record type argument that was passed to x record-constructor \f2record-constructor in the call that created the constructor procedure that created \f2record.
Example: evaluating the expression .Ss ((record-predicate (record-type-descriptor r)) r) .Se always yields #t for any given record \f2r. .
r record-values record
\f2record-values returns the current contents of the fields of \f2record as a x vector vector. The \f2nth element of the vector corresponds to the field with the name given as the \f2nth element of the \f2fields argument in the call to x make-record-type \f2make-record-type that created the type to which \f2record belongs.
The returned vector is not a copy of the actual fields; i.\|e. modifying the contents of the vector directly writes the corresponding fields of the record. .
r describe-record record
This procedure prints the names and current values of the x fields fields of the given record; it is automatically invoked by the standard x describe \f2describe procedure of Elk if \f2describe is invoked with a record. . .Ch "Convenience Macros"
The x macros macros described in this section are loaded by evaluating .Ss (require 'recordutil) .Se after having loaded the record extension. This causes the file x recordutil.scm \f2recordutil.scm to be loaded and defines the x feature x recordutil feature \f2recordutil. . .Sy define-record-type name fields
This macro defines a variable \f2<name>-record, invokes the procedure x make-record-type \f2make-record-type with the given \f2name and \f2fields, and assigns the result to this variable. In addition, \f2define-record-type defines a x "type predicate" type predicate for the new record type as \f2<name>-record? and a x constructor constructor function as \f2make-<name>-record. The constructor function accepts no arguments and returns an uninitialized record of the newly defined record type.
Example: .Ss (require 'record) (require 'recordutil) (define-record-type time (hours minutes seconds)) (record-type? time-record) \f2\(-> #t (define t (make-time-record)) (time-record? t) \f2\(-> #t .Se . .[[ .Sy define-record-accessors rt .Sy define-record-modifiers rt .]]
The macro \f2define-record-accessors (\f2define-record-modifiers) defines x accessor x modifier accessor (modifier) functions for the fields of the record type \f2rt. For each field named \f2field, \f2define-record-accessors (\f2define-record-modifiers) defines a function \f2<name>-<field> (\f2set-<name>-<field>!), where \f2name is the type name of the given record type. Each of the functions is the result of a call to x record-accessor x record-modifier \f2record-accessor (\f2record-modifier) as described above, with the arguments \f2rt and the name of the field.
Example: .Ss (define-record-type time (hours minutes seconds)) (define-record-modifiers time-record) (define noon (make-time-record)) (set-time-hours! noon 12) (set-time-minutes! noon 0) (set-time-seconds! noon 0) (define-record-accessors time-record) (time-hours noon) \f2\(-> 12 .Se