Dynamic types for Irmin values.
Yet-an-other type combinator library
Type provides type combinators to define runtime representation for OCaml types and generic operations to manipulate values with a runtime type representation.
The type combinators supports all the usual type primitives but also compact definitions of records and variants. It also allows to define the runtime representation of recursive types.
val unit : unit tunit is a representation of the unit type.
val bool : bool tbool is a representation of the boolean type.
val char : char tchar is a representation of the character type.
val int32 : int32 tint32 is a representation of the 32-bit integers type.
val int64 : int64 tint64 is a representation of the 64-bit integer type.
val float : float tfloat is a representation of the float type.
val string : string tstring is a representation of the string type.
val cstruct : Cstruct.t tcstruct is a representation of the Cstruct.t type.
triple x y z is a representation of values of type x * y *
z.
result a b is a representation of values of type (a, b)
result.
The type for fields holding values of type 'b and belonging to a record of type 'a.
field n t g is the representation of the field n of type t with getter g.
For instance:
type t = { foo: string option }
let foo = field "foo" (option string) (fun t -> t.x)The type for representing open records of type 'a with constructors of type 'b. 'c represents the fields missings to the record, e.g. an open record initially holds 'c = 'b and it can can be sealed when 'c = 'a.
val sealr : ('a, 'b, 'a) open_record -> 'a tsealr r seal the open record r.
val (|+) :
('a, 'b, 'c -> 'd) open_record ->
('a, 'c) field ->
('a, 'b, 'd) open_recordr |+ f adds the field f to the open record r.
val record : string -> 'b -> ('a, 'b, 'b) open_recordrecord n f fs is the representation of the record called n of type 'a using f as constructor and with the fields fs.
Putting all together:
type t = { foo: string; bar = (int * string) list; }
let t =
record "t" (fun foo -> { foo })
|+ field "foo" string (fun t -> t.foo)
|+ field "bar" (list (pair int string)) (fun t -> t.bar)
|> sealrcase0 n v is a representation of a variant case n with no argument and a singleton pattern. e.g.
type t = Foo
let foo = case0 "Foo" Foocase1 n t c is a representation of a variant case n with 1 argument of type t and a pattern c an function with one argument of type t. e.g.
type t = Foo of string
let foo = case1 "Foo" string (fun s -> Foo s)The type for representing open variants of type 'a with pattern matching of type 'b. 'c represents the missing cases for the variant, e.g. initially variant hols c' = 'b and it can be sealed when 'c = 'a.
val sealv : ('a, 'b, 'a -> 'a case_p) open_variant -> 'a tsealv v seals the open variant v.
val (|~) :
('a, 'b, 'c -> 'd) open_variant ->
('a, 'c) case ->
('a, 'b, 'd) open_variantv |~ c is the map v augmented with the case c.
val variant : string -> 'b -> ('a, 'b, 'b) open_variantvariant n c p is a representation of a variant type containing the cases c and using p to deconstruct values.
Putting all together:
type t = Foo | Bar of string
let t =
variant "t" (fun foo bar -> function
| Foo -> foo
| Bar s -> bar s)
|~ case0 "Foo" Foo
|~ case1 "Bar" string (fun x -> Bar x)
|> sealrval enum : string -> (string * 'a) list -> 'a tenum n l is a representation of the variant type which has only constant variant case. e.g.
type t = Foo | Bar | Toto
let t = enum "t" ["Foo", Foo; "Bar", Bar; "Toto", Toto]Type allows to create a limited form of recursive records and variants.
TODO: describe the limitations, e.g. only regular recursion and no use of the generics inside the mu* functions and the usual caveats with recursive values (such as infinite loops on most of the generics which don't check sharing).
mu f is the representation r such that r = mu r.
For instance:
type x = { x: x option }
let x = mu (fun x ->
record "x" (fun x -> { x })
|+ field "x" x (fun x -> x.x)
|> sealr)mu2 f is the representations r and s such that r, s = mu2 r
s.
For instance:
type r = { foo: int; bar: string list; z: z option }
and z = { x: int; r: r list }
(* Build the representation of [r] knowing [z]'s. *)
let mkr z =
record "r" (fun foo bar z -> { foo; bar; z })
|+ field "foo" int (fun t -> t.foo)
|+ field "bar" (list string) (fun t -> t.bar)
|+ field "z" (option z) (fun t -> t.z)
|> sealr
(* And the representation of [z] knowing [r]'s. *)
let mkz r =
record "z" (fun x r -> { x; r })
|+ field "x" int (fun t -> t.x)
|+ field "r" (list r) (fun t -> t.r)
|> sealr
(* Tie the loop. *)
let r, z = mu2 (fun r z -> mkr z, mkz y)Sometimes it is not always possible to describe precisely a type (or it could be too tedious) and it is easier to describe the relation with an other know type. This is what bijections are about.
like x f g is the description of a type which looks like x using the bijetion (f, g).
Given a value 'a t, it is possible to define generic operations on value of type 'a such as pretty-printing, parsing and unparsing.
val dump : 'a t -> 'a Fmt.tdump t dumps the values of type t as a parsable OCaml expression.
val equal : 'a t -> 'a -> 'a -> boolequal t is the equality function between values of type t.
val compare : 'a t -> 'a -> 'a -> intcompare t compares values of type t.
val pp_json : ?minify:bool -> 'a t -> 'a Fmt.tSimilar to dump but pretty-prints the JSON representation instead of the OCaml one. See encode_json for details about the encoding.
For instance:
type t = { foo: int option; bar: string list };;
let t =
record "r" (fun foo bar -> { foo; bar })
|+ field "foo" (option int) (fun t -> t.foo)
|+ field "bar" (list string) (fun t -> t.bar)
|> sealr
let s = Fmt.strf "%a\n" (pp t) { foo = None; bar = ["foo"] }
(* s is "{ foo = None; bar = [\"foo\"]; }" *)
let j = Fmt.strf "%a\n" (pp_json t) { foo = None; bar = ["foo"] }
(* j is "{ \"bar\":[\"foo\"] }" *)NOTE: this will automatically convert JSON fragments to valid JSON objects by adding an enclosing array if necessary.
val encode_json : 'a t -> Jsonm.encoder -> 'a -> unitencode_json t e encodes t into the jsonm encoder e. The encoding is a relatively straightforward translation of the OCaml structure into JSON. The main highlights are:
ints are translated into JSON floats.'a option are automatically unboxed in their JSON representation. If the value if None, the field is removed from the JSON object.case0 are represented as strings.case1 are represented as a record with one field; the field name is the name of the variant.NOTE: this can be used to encode JSON fragments. That's the responsibility of the caller to ensure that the encoded JSON fragment fits properly into a well-formed JSON object.
val decode_json :
'a t ->
Jsonm.decoder ->
('a, [ `Msg of string ]) Result.resultdecode_json t e decodes values of type t from the jsonm decoder e.
val decode_json_lexemes :
'a t ->
Jsonm.lexeme list ->
('a, [ `Msg of string ]) Result.resultdecode_json_lexemes is similar to decode_json but use an already decoded list of JSON lexemes instead of a decoder.
val encode_cstruct : 'a t -> 'a -> Cstruct.tencode_cstruct t e encodes t into a `Cstruct.t`. The size of the returned buffer is precomputed and the buffer is allocated at once.
NOTE: There is a special case when the parameter t is a single cstruct: the original value is returned as is, without being copied.
val decode_cstruct :
'a t ->
Cstruct.t ->
('a, [ `Msg of string ]) Result.resultdecode_cstruct t buf decodes values of type t as produced by encode_cstruct t v.
NOTE: When the parameter t is a single cstruct, the original buffer is returned as is, otherwise sub-cstruct are copied.