Cf_data_render (p.orsetto.1.1.1.doc.orsetto.cf.Cf_data

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.

val primitive : 'v Cf_type.nym -> 'v model

Use primitive nym to compose a model that corresponds to all the values of the type associated with nym.

val cast : ('b -> 'a) -> 'a model -> 'b model

Use cast f m to compose a model that corresponds to the values produced by applying f to rendered values for the model m.

val default : 'a -> 'a model -> 'a option model

Use default v m to compose a model for rendered optional values in the model m where v is output when the rendered value is None.

val choice : ('v -> int) -> 'v model array -> 'v model

Use choice f s to compose a model that applies f to the rendered value to select the index of the model in s used to produce the output.

val vector : 'v model -> 'v array model

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:'key model -> 'key Cf_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 -> 'k index -> 'v model -> ('k * 'v) array model

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.

module Element : sig ... end

A submodule containing composers for elements indexed by position.

val record : (element, 'v) bind array -> 'v model

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.

module Field : sig ... end

A submodule containing composers for elements indexed by some totally ordered domain type.

val structure : 
  ?unsorted:unit ->
  'k index ->
  ('k index, 'v) bind array ->
  'v model

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.

val variant : 
  'k index ->
  ('v -> 'k) ->
  ('k * (element, 'v) bind) array ->
  'v model

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.

module Affix : sig ... end

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.

type control += private

| Cast : ('b -> 'a) -> ('a, 'b) control

A control value Cast f represents the operation of applying f to the rendered value to produce the value rendered by the model under control.

type control += private

| Default : 'a -> ('a, 'a option) control

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.

val control : 'a model -> ('a, 'b) control -> 'b model

Use control m c to compose a new model comprising the application of c to the model m.

type 'k pair = [

| `Table of 'k Cf_type.nym
| `Structure of 'k Cf_type.nym
| `Variant of 'k Cf_type.nym

]

Values of type 'k pair are used to describe the structure of pair elements in sequences that comprise group data models indexed by values of type 'k.

type 'k container = [

| `Vector
| `Record
| 'k pair

]

Values of type 'k container are used to describe the structure of sequences that comprise group data models.

module type Basis = sig ... end

Define a module of type Basis to create a render specialization.

module type Profile = sig ... end

The module type of render specializations.

module Create (B : Basis) : Profile with type 'v scheme := 'v B.scheme

Use Create(B) to create a render specialization from the basis B.