This section describes abstractions for creating new data types representing records—data structures with named fields. The record mechanism comes in four libraries:
the (r6rs records procedural) library, a procedural layer for creating and manipulating record types and record instances,
the (r6rs records explicit) library, an explicit-naming syntactic layer for defining record types and explicitly named bindings for various procedures to manipulate the record type,
the (r6rs records implicit) library, an implicit-naming syntactic layer that extends the explicit-naming syntactic layer, allowing the names of the defined procedures to be determined implicitly from the names of the record type and fields, and
the (r6rs records inspection) library, a set of inspection procedures.
The procedural layer allows programs to construct new record types and the associated procedures for creating and manipulating records dynamically. It is particularly useful for writing interpreters that construct host-compatible record types. It may also serve as a target for expansion of the syntactic layers.
The explicit-naming syntactic layer provides a basic syntactic interface whereby a single record definition serves as a shorthand for the definition of several record creation and manipulation routines: a construction procedure, a predicate, field accessors, and field mutators. As the name suggests, the explicit-naming syntactic layer requires the programmer to name each of these procedures explicitly.
The implicit-naming syntactic layer extends the explicit-naming syntactic layer by allowing the names for the construction procedure, predicate, accessors, and mutators to be determined automatically from the name of the record and names of the fields. This establishes a standard naming convention and allows record-type definitions to be more succinct, with the downside that the procedure definitions cannot easily be located via a simple search for the procedure name. The programmer may override some or all of the default names by specifying them explicitly, as in the explicit-naming syntactic layer.
The two syntactic layers are designed to be fully compatible; the implicit-naming layer is simply a conservative extension of the explicit-naming layer. The design makes both explicit-naming and implicit-naming definitions natural while allowing a seamless transition between explicit and implicit naming.
Each of these layers permits record types to be extended via single inheritance, allowing record types to model hierarchies that occur in applications like algebraic data types as well as single-inheritance class systems.
Each of the layers also supports generative and nongenerative record types.
The inspection procedures allow programs to obtain from a record instance a descriptor for the type and from there obtain access to the fields of the record instance. This allows the creation of portable printers and inspectors. A program may prevent access to a record’s type and thereby protect the information stored in the record from the inspection mechanism by declaring the type opaque. Thus, opacity as presented here can be used to enforce abstraction barriers.
This section uses the rtd and constructor-descriptor parameter names for arguments that must be record-type descriptors and constructor descriptors, respectively (see section 5.1).
The procedural layer is provided by the (r6rs records procedural)library.
Returns a record-type descriptor, or rtd, representing a record type distinct from all built-in types and other record types.
The name argument must be a symbol naming the record type; it is intended purely for informational purposes and may be used for printing by the underlying Scheme system.
The parent argument must be either #f or an rtd. If it is an rtd, the returned record type, t, extends the record type p represented by parent. Each record of type t is also a record of type p, and all operations applicable to a record of type p are also applicable to a record of type t, except for inspection operations if t is opaque but p is not. An exception with condition type &assertion is raised if parent is sealed (see below).
The extension relationship is transitive in the sense that a type extends its parent’s parent, if any, and so on.
The uid argument must be either #f or a symbol. If uid is a symbol, the record-creation operation is nongenerative i.e., a new record type is created only if no previous call to make-record-type-descriptor was made with the uid. If uid is #f, the record-creation operation is generative, i.e., a new record type is created even if a previous call to make-record-type-descriptor was made with the same arguments.
If make-record-type-descriptor is called twice with the same uid symbol, the parent arguments in the two calls must be eqv?, the fields arguments equal?, the sealed? arguments boolean-equivalent (both false or both non-false), and the opaque? arguments boolean-equivalent. If these conditions are not met, an exception with condition type &assertion is raised when the second call occurs. If they are met, the second call returns, without creating a new record type, the same record-type descriptor (in the sense of eqv?) as the first call.
Note: Users are encouraged to use symbol names constructed using the UUID namespace (for example, using the record-type name as a prefix) for the uid argument.
The sealed? flag must be a boolean. If true, the returned record type is sealed, i.e., it cannot be extended.
The opaque? flag must be a boolean. If true, the record type is opaque. If passed an instance of the record type, record? returns #f and record-rtd (see “Inspection” below) raises an exception with condition type &assertion. The record type is also opaque if an opaque parent is supplied. If opaque? is false and an opaque parent is not supplied, the record is not opaque.
The fields argument must be a vector of field specifiers. Each field specifier must be a list of the form (mutable name) or a list of the form (immutable name). Each name must be a symbol and names the corresponding field of the record type; the names need not be distinct. A field identified as mutable may be modified, whereas an attempt to obtain a mutator for a field identified as immutable raises an exception with condition type &assertion. Where field order is relevant, e.g., for record construction and field access, the fields are considered to be ordered as specified, although no particular order is required for the actual representation of a record instance.
The specified fields are added to the parent fields, if any, to determine the complete set of fields of the returned record type. If fields is modified after make-record-type has been called, the effect on the returned rtd is unspecified.
A record type is considered immutable if all fields in its complete set of fields is immutable, and is mutable otherwise.
A generative record-type descriptor created by a call to make-record-type-descriptor is not eqv? to any record-type descriptor (generative or nongenerative) created by another call to make-record-type-descriptor. A generative record-type descriptor is eqv? only to itself, i.e., (eqv?
rtd1
rtd2) iff (eq?
rtd1
rtd2). Also, two nongenerative record-type descriptors are eqv? iff they were created by calls to make-record-type-descriptor with the same uid arguments.
Rationale: The record and field names passed to make-record-type-descriptor and appearing in the explicit-naming syntactic layer are for informational purposes only, e.g., for printers and debuggers. In particular, the accessor and mutator creation routines do not use names, but rather field indices, to identify fields.Thus, field names are not required to be distinct in the procedural or implicit-naming syntactic layers. This relieves macros and other code generators from the need to generate distinct names.
The record and field names are used in the implicit-naming syntactic layer for the generation of accessor and mutator names, and duplicate field names may lead to accessor and mutator naming conflicts.
Rationale: Sealing a record type can help to enforce abstraction barriers by preventing extensions that may expose implementation details of the parent type. Type extensions also make monomorphic code polymorphic and difficult to change the parent class at a later time, and also prevent effective predictions of types by a compiler or human reader.
Rationale: Multiple inheritance was considered but omitted from the records facility, as it raises a number of semantic issues such as sharing among common parent types.
Returns #t if the argument is a record-type descriptor, #f otherwise.
Returns a record-constructor descriptor (or constructor descriptor for short) that can be used to create record constructors (via record-constructor; see below) or other constructor descriptors. Rtd must be a record-type descriptor. Protocolmust be a procedure or #f. If it is #f, a default protocol procedure is supplied. If protocol is a procedure, it is called by record-constructor with a single argument p and must return a procedure that creates and returns an instance of the record type using p as described below.
If rtd is not an extension of another record type, then parent-constructor-descriptor must be #f. In this case, protocol’s argument p is a procedure new that expects one parameter for every field of rtd and returns a record instance with the fields of rtd initialized to its arguments. The procedure returned by protocol may take any number of arguments but must call new with the number of arguments it expects and return the resulting record instance, as shown in the simple example below.
(lambda (new)
Here, the call to new returns a record whose fields are simply initialized with the arguments v1 .... The expression above is equivalent to (lambda (new) new).
If rtd is an extension of another record type parent-rtd, parent-constructor-descriptor must be a constructor descriptor of parent-rtd or #f. If it is #f, a default constructor descriptor is assumed, whose constructor accepts as many values as there are fields and initializes the fields to the arguments. In the extension case, p is a procedure that accepts the same number of arguments as the constructor of parent-constructor-descriptor and returns a procedure new, which, as above, expects one parameter for every field of rtd (not including parent fields) and returns a record instance with the fields of rtd initialized to its arguments and the fields of parent-rtd and its parents initialized by the constructor of parent-constructor-descriptor. A simple protocol in this case might be written as follows.
(lambda (p)
This passes some number of arguments x1 ... to p for the constructor of parent-constructor-descriptor and calls new with v1 ... to initialize the child fields.
The constructor descriptors for a record type form a chain of protocols exactly parallel to the chain of record-type parents. Each constructor descriptor in the chain determines the field values for the associated record type. Child record constructors need not know the number or contents of parent fields, only the number of arguments required by the parent constructor.
protocol may be #f, specifying a default, only if rtd is not an extension of another record type, or, if it is, if the parent constructor-descriptor encapsulates a default protocol. In the first case, the default protocol procedure is equivalent to the following:
(lambda (p)
or, simply, (lambda (p) p).
In the second case, the default protocol procedure returns a constructor that accepts one argument for each of the record type’s complete set of fields (including those of the parent record type, the parent’s parent record type, etc.) and returns a record with the fields initialized to those arguments, with the field values for the parent coming before those of the extension in the argument list.
Even if rtd extends another record type, parent-constructor-descriptor may also be #f, in which case a constructor with default protocol is supplied.
Rationale: The constructor-descriptor mechanism is an infrastructure for creating specialized constructors, rather than just creating default constructors that accept the initial values of all the fields as arguments. This infrastructure achieves full generality while leaving each level of an inheritance hierarchy in control over its own fields and allowing child record definitions to be abstracted away from the actual number and contents of parent fields.The design allows the initial values of the fields to be specially computed or to default to constant values. It also allows for operations to be performed on or with the resulting record, such as the registration of a record for finalization. Moreover, the constructor-descriptor mechanism allows the creation of such initializers in a modular manner, separating the initialization concerns of the parent types from those of the extensions.
The mechanism described here achieves complete generality without cluttering the syntactic layer, sacrificing a bit of notational convenience in special cases.
Calls the protocol of constructor-descriptor (as described for make-record-constructor-descriptor) and returns the resulting construction procedure constructor for instances of the record type associated with constructor-descriptor.
Two values created by constructor are equal according to equal? iff they are eqv?, provided their record type is not used to implement any of the types explicitly mentioned in the definition of equal?.
For any constructor returned by record-constructor, the following holds:
(let ((r (constructor v ...)))
For mutable records, but not necessarily for immutable ones, the following hold. (A record of a mutable record type is mutable; a record of an immutable record type is immutable.)
(let ((r (constructor v ...)))
Returns a procedure that, given an object obj, returns a boolean that is #t iff obj is a record of the type represented by rtd.
K must be a valid field index of rtd. The record-accessor procedure returns a one-argument procedure that, given a record of the type represented by rtd, returns the value of the selected field of that record.
The field selected is the one corresponding the kth element (0-based) of the fields argument to the invocation of make-record-type-descriptor that created rtd. Note that k cannot be used to specify a field of any type rtd extends.
If the accessor procedure is given something other than a record of the type represented by rtd, an exception with condition type &assertion is raised. Records of the type represented by rtd include records of extensions of the type represented by rtd.
K must be a valid field index of rtd. The record-mutator procedure returns a two-argument procedure that, given a record r of the type represented by rtd and an object obj, stores obj within the field of r specified by k. The k argument is as in record-accessor. If k specifies an immutable field, an exception with condition type &assertion is raised. The mutator returns the unspecified value.
(define :point
The explicit-naming syntactic layer is provided by the (r6rs records explicit)library.
The record-type-defining form define-record-type is a definition and can appear anywhere any other <definition> can appear.
A define-record-type form defines a record type along with associated constructor descriptor and constructor, predicate, field accessors, and field mutators. The define-record-type form expands into a set of definitions in the environment where define-record-type appears; hence, it is possible to refer to the bindings (except for that of the record type itself) recursively.
The <name spec> specifies the names of the record type, construction procedure, and predicate. It must take the following form.
(<record name> <constructor name> <predicate name>)
<Record name>, <constructor name>, and <predicate name> must all be identifiers.
<Record name>, taken as a symbol, becomes the name of the record type. Additionally, it is bound by this definition to an expand-time or run-time description of the record type for use as parent name in syntactic record-type definitions that extend this definition. It may also be used as a handle to gain access to the underlying record-type descriptor and constructor descriptor (see record-type-descriptor and record-constructor-descriptor below).
<Constructor name> is defined by this definition to be a constructor for the defined record type, with a protocol specified by the protocol clause, or, in its absence, using a default protocol. For details, see the description of the protocol clause below.
<Predicate name> is defined by this definition to a predicate for the defined record type.
Each <record clause> must take one of the following forms; it is a syntax violation if multiple <record clause>s of the same kind appear in a define-record-type form.
(fields <field-spec>*)
where each <field-spec> has one of the following forms
(immutable <field name> <accessor name>)
<Field name>, <accessor name>, and <mutator name> must all be identifiers. The first form declares an immutable field called <field name>, with the corresponding accessor named <accessor name>. The second form declares a mutable field called <field name>, with the corresponding accessor named <accessor name>, and with the corresponding mutator named <mutator name>.
The <field name>s become, as symbols, the names of the fields of the record type being created, in the same order. They are not used in any other way.
(parent <parent name>)
This specifies that the record type is to have parent type <parent name>, where <parent name> is the <record name> of a record type previously defined using define-record-type. The absence of a parent clause implies a record type with no parent type.
(protocol <expression>)
<Expression> is evaluated in the same environment as the define-record-type form, and must evaluate to a protocol appropriate for the record type being defined (see the description of make-record-constructor-descriptor). The protocol is used to create a record-constructor descriptor where, if the record type being defined has a parent, the parent-type constructor descriptor is the one associated with the parent type specified in the parent clause.
If no protocol clause is specified, a constructor descriptor is still created using a default protocol. The rules for this are the same as for make-record-constructor-descriptor: the clause can be absent only if the record type defined has no parent type, or if the parent definition does not specify a protocol.
(sealed #t)
(sealed #f)
If this option is specified with operand #t, the defined record type is sealed. Otherwise, the defined record type is not sealed.
(opaque #t)
(opaque #f)
If this option is specified with operand #t, or if an opaque parent record type is specified, the defined record type is opaque. Otherwise, the defined record type is not opaque.
(nongenerative <uid>)
(nongenerative)
This specifies that the record type is nongenerative with uid <uid>, which must be an <identifier>. If <uid> is absent, a unique uid is generated at macro-expansion time. If two record-type definitions specify the same uid, then the implied arguments to make-record-type-descriptor must be equivalent as described under make-record-type-descriptor. If this condition is not met, it is either considered a syntax violation or an exception with condition type &assertion is raised. If the condition is met, a single record type is generated for both definitions.
In the absence of a nongenerative clause, a new record type is generated every time a define-record-type form is evaluated:
(let ((f (lambda (x)
All bindings created by define-record-type (for the record type, the construction procedure, the predicate, the accessors, and the mutators) must have names that are pairwise distinct.
Evaluates to the record-type descriptor associated with the type specified by <record-name>.
Note that record-type-descriptor works on both opaque and non-opaque record types.
Evaluates to the record-constructor descriptor associated with <record name>.
Explicit-naming syntactic-layer examples:
(define-record-type (point3 make-point3 point3?)
The implicit-naming syntactic layer is provided by the (r6rs records implicit)library.
The define-record-type form of the implicit-naming syntactic layer is a conservative extension of the define-record-type form of the explicit-naming layer: a define-record-type form that conforms to the syntax of the explicit-naming layer also conforms to the syntax of the implicit-naming layer, and any definition in the implicit-naming layer can be understood by its translation into the explicit-naming layer.
This means that a record type defined by the define-record-type form of either layer can be used by the other.
The implicit-naming syntactic layer extends the explicit-naming layer in two ways. First, <name-spec> may be a single identifier representing just the record name. In this case, the name of the construction procedure is generated by prefixing the record name with make-, and the predicate name is generated by adding a question mark (?) to the end of the record name. For example, if the record name is frob, the name of the construction procedure is make-frob, and the predicate name is frob?.
Second, the syntax of <field-spec> is extended to allow the accessor and mutator names to be omitted. That is, <field-spec> can take one of the following forms as well as the forms described in the preceding section.
(immutable <field name>)
If <field-spec> takes one of these forms, the accessor name is generated by appending the record name and field name with a hyphen separator, and the mutator name (for a mutable field) is generated by adding a -set! suffix to the accessor name. For example, if the record name is frob and the field name is widget, the accessor name is frob-widget and the mutator name is frob-widget-set!.
Third, the syntax of <field-spec> is also extended to consist of just the field name. The corresponding field is assumed to be immutable.
Any definition that takes advantage of implicit naming can be rewritten trivially to a definition that conforms to the syntax of the explicit-naming layer merely by specifying the names explicitly. For example, the implicit-naming layer record definition:
(define-record-type frob
is equivalent to the following explicit-naming layer record definition.
(define-record-type (frob make-frob frob?)
Also, the implicit-naming layer record definition:
(define-record-type point (fields x y))
is equivalent to the following explicit-naming layer record definition:
(define-record-type (point make-point point?)
With the implicit-naming layer, one can choose to specify just some of the names explicitly; for example, the following overrides the choice of accessor and mutator names for the widget field.
(define-record-type frob
(define *ex3-instance* #f)
This is the same as record-type-descriptor from the (r6rs records explicit) library.
This is the same as record-constructor-descriptor from the (r6rs records explicit) library.
The implicit-naming syntactic layer is provided by the (r6rs records inspection)library.
A set of procedures are provided for inspecting records and their record-type descriptors. These procedures are designed to allow the writing of portable printers and inspectors.
Note that record? and record-rtd treat records of opaque record types as if they were not records. On the other hand, the inspection procedures that operate on record-type descriptors themselves are not affected by opacity. In other words, opacity controls whether a program can obtain an rtd from an instance. If the program has access to the original rtd via make-record-type-descriptor or record-type-descriptor, it can still make use of the inspection procedures.
Any of the standard types mentioned in this report may or may not be implemented as an opaque record type. Consequently, record?, when applied to an object of one of these types, may return #t. In this case, inspection is possible for these objects.
Returns #t if obj is a record, and its record type is not opaque. Returns #f otherwise.
Returns the rtd representing the type of record if the type is not opaque. The rtd of the most precise type is returned; that is, the type t such that record is of type t but not of any type that extends t. If the type is opaque, an exception is raised with condition type &assertion.
Returns the name of the record-type descriptor rtd.
Returns the parent of the record-type descriptor rtd, or #f if it has none.
Returns the uid of the record-type descriptor rtd, or #f if it has none. (An implementation may assign a generated uid to a record type even if the type is generative, so the return of a uid does not necessarily imply that the type is nongenerative.)
Returns #t if rtd is generative, and #f if not.
Returns a boolean value indicating whether the record-type descriptor is sealed.
Returns a boolean value indicating whether the record-type descriptor is opaque.
Returns a vector of symbols naming the fields of the type represented by rtd (not including the fields of parent types) where the fields are ordered as described under make-record-type-descriptor. The returned vector may be immutable. If the returned vector is modified, the effect on rtd is unspecified.
Returns a boolean value indicating whether the field specified by k of the type represented by rtd is mutable, where k is as in record-accessor.