Legend:
Library
Module
Module type
Parameter
Class
Class type
Rendering data according to an abstract model.
Overview
This module facilitates the rendering of data conforming to an abstract model using any interchange language provided with a basis module defining the emitter type and some basic emitters and emitter composers.
Data models are functionally composable. Optional affix convenience operators are provide an indiomatic syntax.
With a fully composed data models and the render specialization of an interchange language, you produce an emitter that produces output of well-typed values according to the corresponding model.
A data model represents either the "primitive" type of a scalar value or a "composed" type of a group of values.
A primitive model represents an OCaml value identified by a Cf_type.nym. Some nyms are conventionally accepted by every interchange language in the Orsetto distribution:
Cf_type.Unit A type with exactly one value, e.g. the JSON "null" value.
Cf_type.Bool A boolean value type.
Cf_type.Int An integer value in the range that an OCaml nt can represent.
Cf_type.Int32 An integer value in the range that an OCaml nt32 can represent.
Cf_type.Int64 An integer value in the range that an OCaml nt64 can represent.
Cf_type.Float An IEEE 754 floating point value in the range that an OCaml float can represent.
Cf_type.String An octet string, not necessarily associated with a particular encoding.
Cf_type.Opaque An opaque value conventionally representing any scalar or group value in the underlying interchange language. (Note well: opaque values may contain interchange language specific elements that cannot expressed in other interchange languages.)
A group model takes one of the following forms:
Vector A sequence of zero, one or more elements all of with the same model.
Table A sequence of zero, one or more pairs, comprising a domain model and a codomain model, where the domain model corresponds to a totally ordered type and no two pairs in the sequence share the same domain value.
Record A sequence of zero, one or more elements, each of which may have a different model indicated by its position in the sequence.
Structure A sequence of zero, one or more pairs, comprising an index model and a field model, where the index model corresponds to a totally ordered type, the field model is indicated by the value of the index, and no two pairs in the sequence share the same index value.
Variant Exactly one pair, comprising an index model and a field mode, where the field model is indicated by the value of the index.
Generalized Data Models
The types and values in this section facilitate the composition of abstract data models for use in constructing emitters with interchange languages for which a render specialization is defined.
type'v model
The type constructor 'v model represents the rendering of 'v values encoded to some interchange language.
Use defer m to compose a model by forcing m as needed. This is useful for composing recursive data models to be used in the array arguments of the choice and variant model constructors (see below).
Use vector m to compose a model that corresponds to a variable length array of values produced by the emitter for the model m.
class 'key index : ?cmp:('key->'key->
int)->?model:'keymodel->'keyCf_type.nym->object ... end
Use new index nym to create an index object for the type indicated by nym required for composing table, structure and variant group models. Use the optional ~cmp argument to specify a concrete comparator function to use instead of Stdlib.( = ). Use the optional ~model argument to specify the model explicitly, otherwise the primitive model for nym is used for the domain or index in the compoed group model.
val table : ?unsorted:unit ->'kindex->'vmodel->('k * 'v) arraymodel
Use table k v to compose a model that corresponds to a variable length array of pairs comprising a domain value of the type described by the index k and a codomain value of the type described by the model v. Use the optional ~unsorted argument to specify that the emitter does not sort the rendered array.
type element
The abstract type parameter for group elements where the position in the sequence indicates the model for the element.
type('g, 'v) bind
The type constructor ['g, 'p] bind represents the model of a specific element in a group with fields or elements of disparate type. In the case where type 'g is element, the type 'p corresponds to the type indicated by the position in the sequence. In the case where type 'g is 'k index, the type 'p corresponds to the type indicated by its index value.
Use record s to compose a model that corresponds to variable length array of elements corresponding to the projection of the rendered value with all the element binders in s in sequence.
Use structure d s to compose a model that corresponds to variable length array of pairs comprising a key of the type described by the index d and a value of a type indicated by the field in s associated with the key. Use the optional ~unsorted argument to specify that the emitter does not sort the rendered array by their keys.
Use variant d f s to compose a model that corresponds to a pair comprising a key of the type described by the index d obtained by applying f to the rendered value, and a value of a type indicated by, and a value obtained according to the field bind associated with the key.
A submodule containing affix operators the provide a convenient and idiosyncratic syntax for composing record and structure models.
Specialization
Usage of generalized data models with a specific interchange language entails composing a render specialization for it. The types and values in this section are provided for that purpose.
type(_, _) control = ..
The extensible control type. Facilitates composing data models with features extended by the render specialization for unique features of the interchange language. A value of type ('a, 'b) control represents a conversion of a model of type 'a model to a model of type 'b model as a side effect of any additional constraints applied.
A control value Default v represents the conversion of an optional rendered value into a required value by using v in the event the rendered value is None.