Records

This section describes abstractions for creating new data types representing records—data structures with named fields. The record mechanism comes in three libraries:

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 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 constructor, a predicate, field accessors, and field mutators. The layer allows the programmer to name each of these procedures explicitly, but also provides shorthands for naming them implicitly through a set of naming conventions.

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 facility 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 6.2).

6.1  Mutability and equivalence

The fields of a record type are designated mutable or immutable. Correspondingly, a record type with no mutable field is called immutable, and all records of that type are immutable objects. All other record types are mutable, and so are their records.

Each call to a record constructor returns a new record with a fresh location (see report section on “Storage model”). Consequently, for two records obj1 and obj2, the return value of (eqv? obj1 obj2), adheres to the following criteria (see report section on “Equivalence predicates”):

6.2  Procedural layer

The procedural layer is provided by the (rnrs records procedural (6))library.

(make-record-type-descriptor name    procedure 

parent uid sealed? opaque? fields)

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. It names the record type, and 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. A record type that does not extend another record type is called a base record type.

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 #f or both true), 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. Moreover, if record-rtd (see “Inspection” below) is called an instance of the record type, an exception with condition type &assertion is raised. The record type is also opaque if an opaque parent is supplied. If opaque? is #f 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, when a program attempts to obtain a mutator for a field identified as immutable, an exception with condition type &assertion is raised. 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.

(record-type-descriptor? obj)    procedure 

Returns #t if the argument is a record-type descriptor, #f otherwise.

(make-record-constructor-descriptor rtd    procedure 

parent-constructor-descriptor protocol)

Returns a record-constructor descriptor (or constructor descriptor for short) that specifies a record constructor (or constructor for short), that can be used to construct record values of the type specified by rtd, and which can be obtained via record-constructor. A constructor descriptor can also be used to create other constructor descriptors for subtypes of its own record type. 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 should return a procedure that creates and returns an instance of the record type using p as described below. The role of p differs depending on the kind of record type represented by rtd:

If rtd is a base record type, then parent-constructor-descriptor must be #f. In this case, protocol’s argument p is a procedure that expects one argument for every field of rtd and returns a record with the fields of rtd initialized to these arguments. The procedure returned by protocol should call p once with the number of arguments it expects and return the resulting record as shown in the simple example below:

(lambda (p)
  (lambda (v1 v2 v3)
    (p v1 v2 v3)))

Here, the call to p returns a record whose fields are initialized with the values of v1, v2, and v3. The expression above is equivalent to (lambda (p) p). Note that the procedure returned by protocol is otherwise unconstrained; specifically, it can take any number of arguments.

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 parent-constructor-descriptor or protocol is #f, protocol must also be #f, and a default constructor descriptor is assumed as described below.

If parent-constructor-descriptor is a constructor descriptor and protocol is a procedure, then its argument p is a procedure that accepts the same number of arguments as the constructor of parent-constructor-descriptor and returns a procedure new that, when called, constructs the record itself. The new procedure expects one argument for every field of rtd (not including parent fields) and returns a record with the fields of rtd initialized to these arguments, and the fields of parent-rtd and its parents initialized as specified by parent-constructor-descriptor.

The procedure returned by protocol should call p once with the number of arguments it expects, call the procedure it returns once with number of arguments it expects and return the resulting record. A simple protocol in this case might be written as follows:

(lambda (p)
  (lambda (v1 v2 v3 x1 x2 x3 x4)
    (let ((new (p v1 v2 v3)))
      (new x1 x2 x3 x4))))

This passes arguments v1, v2, v3 to p for parent-constructor-descriptor and calls new with x1, ..., x4 to initialize the fields of rtd itself.

Thus, the constructor descriptors for a record type form a sequence of protocols exactly parallel to the sequence 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 value that accepts one argument for each field of rtd (not including the fields of its parent type, if any). Specifically, if rtd is a base type, the default protocol procedure behaves as if it were (lambda (p) p). If rtd is an extension of another type, then parent-constructor-descriptor must be either #f or itself specify a default constructor. In this case, the default protocol procedure behaves as if it were:

(lambda (p)
  (lambda (v1 ... vj x1 ... xk)
    (let ((new (p v1 ... vj)))
      (new x1 ... xk))))

The resulting constructor 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. (In the example, j is the complete number of fields of the parent type, and k is the number of fields of rtd itself.)

Implementation responsibilities: If protocol is a procedure, the implementation must check the restrictions on it to the extent performed by applying it as described when the constructor is called.

(record-constructor constructor-descriptor)    procedure 

Calls the protocol of constructor-descriptor (as described for make-record-constructor-descriptor) and returns the resulting constructor constructor for records of the record type associated with constructor-descriptor.

(record-predicate rtd)    procedure 

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.

(record-accessor rtd k)    procedure 

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.

(record-mutator rtd k)    procedure 

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 unspecified values.

(define :point
  (make-record-type-descriptor
    ’point #f
    #f #f #f 
    ’#((mutable x) (mutable y))))

(define :point-cd
  (make-record-constructor-descriptor :point #f #f))

(define make-point (record-constructor :point-cd))

(define point? (record-predicate :point))
(define point-x (record-accessor :point 0))
(define point-y (record-accessor :point 1))
(define point-x-set! (record-mutator :point 0))
(define point-y-set! (record-mutator :point 1))

(define p1 (make-point 1 2))
(point? p1)         ⇒ #t
(point-x p1)         ⇒ 1
(point-y p1)         ⇒ 2
(point-x-set! p1 5)         ⇒ unspecified
(point-x p1)         ⇒ 5

(define :point2
  (make-record-type-descriptor
    ’point2 :point 
    #f #f #f ’#((mutable x) (mutable y))))

(define make-point2
  (record-constructor
    (make-record-constructor-descriptor :point2
      #f #f)))
(define point2? (record-predicate :point2))
(define point2-xx (record-accessor :point2 0))
(define point2-yy (record-accessor :point2 1))

(define p2 (make-point2 1 2 3 4))
(point? p2)         ⇒ #t
(point-x p2)         ⇒ 1
(point-y p2)         ⇒ 2
(point2-xx p2)         ⇒ 3
(point2-yy p2)         ⇒ 4

(define :point-cd/abs
  (make-record-constructor-descriptor
   :point #f
   (lambda (new)
     (lambda (x y)
       (new (abs x) (abs y))))))

(define make-point/abs
  (record-constructor :point-cd/abs))

(point-x (make-point/abs -1 -2) 
                ⇒ 1
(point-y (make-point/abs -1 -2) 
                ⇒ 2

(define :cpoint
  (make-record-type-descriptor
   ’cpoint :point
   #f #f #f
   ’#((mutable rgb))))

(define make-cpoint
  (record-constructor
   (make-record-constructor-descriptor
    :cpoint :point-cd
    (lambda (p)
      (lambda (x y c)
        ((p x y) (color->rgb c)))))))

(define make-cpoint/abs
  (record-constructor
   (make-record-constructor-descriptor
    :cpoint :point-cd/abs
    (lambda (p)
      (lambda (x y c)
        ((p x y) (color->rgb c)))))))

(define cpoint-rgb
  (record-accessor :cpoint 0))

(define (color->rgb c)
  (cons ’rgb c))

(cpoint-rgb (make-cpoint -1 -3 ’red) 
                ⇒ (rgb . red)
(point-x (make-cpoint -1 -3 ’red)) 
                ⇒ -1
(point-x (make-cpoint/abs -1 -3 ’red)) 
                ⇒ 1

6.3  Syntactic layer

The syntactic layer is provided by the (rnrs records syntactic (6))library.

The record-type-defining form define-record-type is a definition and can appear anywhere any other <definition> can appear.

(define-record-type <name spec> <record clause>*)    syntax 

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, constructor, and predicate. It must take one of the following forms:

(<record name> <constructor name> <predicate name>)
<record 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.

The second form of <name spec> is an abbreviation for the first form, where the name of the constructor 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 constructor is make-frob, and the predicate name is frob?.

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.

All bindings created by define-record-type (for the record type, the constructor, the predicate, the accessors, and the mutators) must have names that are pairwise distinct.

The fields, mutable, immutable, parent, protocol, sealed, opaque, and nongenerative identifiers are all exported by the (rnrs records syntactic (6)) library with level 0. Referring to one of these identifiers out of place is a syntax violation.

Any definition that takes advantage of implicit naming for the constructor, predicate, accessor, and mutator names, can be rewritten trivially to a definition that specifies all names explicitly. For example, the implicit-naming record definition:

(define-record-type frob
  (fields (mutable widget))
  (protocol
    (lambda (c) (lambda (n) (c (make-widget n))))))

is equivalent to the following explicit-naming record definition.

(define-record-type (frob make-frob frob?)
  (fields (mutable widget
                   frob-widget frob-widget-set!))
  (protocol
    (lambda (c) (lambda (n) (c (make-widget n))))))

Also, the implicit-naming record definition:

(define-record-type point (fields x y))

is equivalent to the following explicit-naming record definition:

(define-record-type (point make-point point?)
  (fields 
    (immutable x point-x)
    (immutable y point-y)))

With implicit naming, 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
  (fields (mutable widget getwid setwid!))
  (protocol
    (lambda (c) (c (make-widget n)))))

(record-type-descriptor <record name>)    syntax 

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.

(record-constructor-descriptor <record name>)    syntax 

Evaluates to the record-constructor descriptor associated with <record name>.

(define-record-type (point make-point point?)
  (fields (immutable x point-x)
          (mutable y point-y set-point-y!))
  (nongenerative
    point-4893d957-e00b-11d9-817f-00111175eb9e))

(define-record-type (cpoint make-cpoint cpoint?)
  (parent point)
  (protocol
   (lambda (p)
     (lambda (x y c) 
       ((p x y) (color->rgb c)))))
  (fields
    (mutable rgb cpoint-rgb cpoint-rgb-set!)))

(define (color->rgb c)
  (cons ’rgb c))

(define p1 (make-point 1 2))
(define p2 (make-cpoint 3 4 ’red))

(point? p1)         ⇒ #t
(point? p2)         ⇒ #t
(point? (vector))         ⇒ #f
(point? (cons ’a ’b))         ⇒ #f
(cpoint? p1)         ⇒ #f
(cpoint? p2)         ⇒ #t
(point-x p1)         ⇒ 1
(point-y p1)         ⇒ 2
(point-x p2)         ⇒ 3
(point-y p2)         ⇒ 4
(cpoint-rgb p2)         ⇒ (rgb . red)

(set-point-y! p1 17)
(point-y p1)         ⇒ 17)

(record-rtd p1) 
                ⇒ (record-type-descriptor point)

(define-record-type (ex1 make-ex1 ex1?)
  (protocol (lambda (new) (lambda a (new a))))
  (fields (immutable f ex1-f)))

(define ex1-i1 (make-ex1 1 2 3))
(ex1-f ex1-i1)         ⇒ (1 2 3)

(define-record-type (ex2 make-ex2 ex2?)
  (protocol
    (lambda (new) (lambda (a . b) (new a b))))
  (fields (immutable a ex2-a)
          (immutable b ex2-b)))

(define ex2-i1 (make-ex2 1 2 3))
(ex2-a ex2-i1)         ⇒ 1
(ex2-b ex2-i1)         ⇒ (2 3)

(define-record-type (unit-vector
                     make-unit-vector
                     unit-vector?)
  (protocol
   (lambda (new)
     (lambda (x y z)
       (let ((length 
               (sqrt (+ (* x x) (* y y) (* z z)))))
         (new (/ x length)
              (/ y length)
              (/ z length))))))
  (fields (immutable x unit-vector-x)
          (immutable y unit-vector-y)
          (immutable z unit-vector-z)))

(define *ex3-instance* #f)

(define-record-type ex3
  (parent cpoint)
  (protocol
   (lambda (p)
     (lambda (x y t)
       (let ((r ((p x y ’red) t)))
         (set! *ex3-instance* r)
         r))))
  (fields 
   (mutable thickness))
  (sealed #t) (opaque #t))

(define ex3-i1 (make-ex3 1 2 17))
(ex3? ex3-i1)         ⇒ #t
(cpoint-rgb ex3-i1)         ⇒ (rgb . red)
(ex3-thickness ex3-i1)         ⇒ 17
(ex3-thickness-set! ex3-i1 18)
(ex3-thickness ex3-i1)         ⇒ 18
*ex3-instance*         ⇒ ex3-i1

(record? ex3-i1)         ⇒ #f

6.4  Inspection

The inspection layer is provided by the (rnrs records inspection (6))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.

On the one hand, 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 a record. 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.

(record? obj)    procedure 

Returns #t if obj is a record, and its record type is not opaque. Returns #f otherwise.

(record-rtd record)    procedure 

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.

(record-type-name rtd)    procedure 

Returns the name of the record-type descriptor rtd.

(record-type-parent rtd)    procedure 

Returns the parent of the record-type descriptor rtd, or #f if it has none.

(record-type-uid rtd)    procedure 

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.)

(record-type-generative? rtd)    procedure 

Returns #t if rtd is generative, and #f if not.

(record-type-sealed? rtd)    procedure 

Returns a boolean value indicating whether the record-type descriptor is sealed.

(record-type-opaque? rtd)    procedure 

Returns a boolean value indicating whether the record-type descriptor is opaque.

(record-type-field-names rtd)    procedure 

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.

(record-field-mutable? rtd k)    procedure 

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.