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 the definition of run-time representations of recursive types.
The type of integer used to store buffers, list or array lengths.
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 int : int tint is a representation of integers. Binary serialization uses a varying-width representation.
val int32 : int32 tint32 is a representation of the 32-bit integer 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 bytes : bytes tbytes is a representation of the bytes type.
array t is a representation of arrays of values of type t.
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.
val record : string -> 'b -> ('a, 'b, 'b) open_recordThe 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. Raises. Invalid_argument if n is not valid UTF-8.
The name n must not be used by any other field in the record.
For instance:
type manuscript = { title : string option }
let manuscript = field "title" (option string) (fun t -> t.title)val (|+) :
('a, 'b, 'c -> 'd) open_record ->
('a, 'c) field ->
('a, 'b, 'd) open_recordr |+ f is the open record r augmented with the field f.
val sealr : ('a, 'b, 'a) open_record -> 'a tsealr r seals the open record r. Raises. Invalid_argument if two or more fields share the same name.
Putting all together:
type menu = { restaurant : string; items : (string * int32) list }
let t =
record "t" (fun restaurant items -> { restaurant; items })
|+ field "restaurant" string (fun t -> t.restaurant)
|+ field "items" (list (pair string int32)) (fun t -> t.items)
|> sealrval variant : string -> 'b -> ('a, 'b, 'b) open_variantcase0 n v is a representation of a variant constructor v with no arguments and name n. Raises. Invalid_argument if n is not valid UTF-8.
The name n must not by used by any other case0 in the record.
For instance:
type t = Foo
let foo = case0 "Foo" Foocase1 n t c is a representation of a variant constructor c with an argument of type t and name n. Raises. Invalid_argument if n is not valid UTF-8.
The name n must not by used by any other case1 in the record.
For instance:
type t = Foo of string
let foo = case1 "Foo" string (fun s -> Foo s)val (|~) :
('a, 'b, 'c -> 'd) open_variant ->
('a, 'c) case ->
('a, 'b, 'd) open_variantv |~ c is the open variant v augmented with the case c.
val sealv : ('a, 'b, 'a -> 'a case_p) open_variant -> 'a tsealv v seals the open variant v. Raises. Invalid_argument if two or more cases of same arity share the same name.
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)
|> sealvval enum : string -> (string * 'a) list -> 'a tenum n cs is a representation of the variant type called n with singleton cases cs. e.g.
type t = Foo | Bar | Toto
let t = enum "t" [ ("Foo", Foo); ("Bar", Bar); ("Toto", Toto) ]Raises. Invalid_argument if two or more cases share the same name.
Type allows a limited description 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))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 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 short_hash : 'a t -> ?seed:int -> 'a -> inthash t x is a short hash of x of type t.
val to_string : 'a t -> 'a -> stringto_string t is Fmt.to_to_string (pp t).
module Json : sig ... endOverlay on top of Jsonm to work with rewindable streams.
type 'a decode_json = Json.decoder -> ('a, [ `Msg of string ]) Stdlib.resultThe type for JSON decoders.
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:
() is translated into the empty object {}.None are removed from the JSON object; record fields with a value of Some x are automatically unboxed into x; and outside of records, None is translated into null and Some x into {"some": x'} with x' the JSON encoding of x.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. It'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 ]) Stdlib.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 ]) Stdlib.resultdecode_json_lexemes is similar to decode_json but uses an already decoded list of JSON lexemes instead of a decoder.
val to_json_string : ?minify:bool -> 'a t -> 'a -> stringto_json_string is encode_json with a string encoder.
val of_json_string : 'a t -> string -> ('a, [ `Msg of string ]) Stdlib.resultof_json_string is decode_json with a string decoder .
type 'a encode_bin = ?headers:bool -> 'a bin_seqThe type for binary encoders. If headers is not set, do not output extra length headers for buffers.
The type for binary decoders. IF headers is not set, do not read extra length header for buffers and consider the whole buffer instead.
The type for size function related to binary encoder/decoders.
val encode_bin : 'a t -> 'a encode_binencode_bin t is the binary encoder for values of type t.
val decode_bin : 'a t -> 'a decode_bindecode_bin t is the binary decoder for values of type t.
val to_bin_string : 'a t -> 'a -> stringto_bin_string t x use encode_bin to convert x, of type t, to a string.
NOTE: When t is Type.string or Type.bytes, the original buffer x is not prefixed by its size as encode_bin would do. If t is Type.string, the result is x (without copy).
val of_bin_string : 'a t -> string -> ('a, [ `Msg of string ]) Stdlib.resultof_bin_string t s is v such that s = to_bin_string t v.
NOTE: When t is Type.string, the result is s (without copy).
size_of t x is either the size of encode_bin t x or the binary encoding of x, if the backend is not able to pre-compute serialisation lengths.
val v :
cli:('a pp * 'a of_string) ->
json:('a encode_json * 'a decode_json) ->
bin:('a encode_bin * 'a decode_bin * 'a size_of) ->
equal:('a -> 'a -> bool) ->
compare:('a -> 'a -> int) ->
short_hash:(?seed:int -> 'a -> int) ->
pre_hash:'a bin_seq ->
'a tval like :
?cli:('a pp * 'a of_string) ->
?json:('a encode_json * 'a decode_json) ->
?bin:('a encode_bin * 'a decode_bin * 'a size_of) ->
?equal:('a -> 'a -> bool) ->
?compare:('a -> 'a -> int) ->
?short_hash:('a -> int) ->
?pre_hash:'a bin_seq ->
'a t ->
'a tval map :
?cli:('a pp * 'a of_string) ->
?json:('a encode_json * 'a decode_json) ->
?bin:('a encode_bin * 'a decode_bin * 'a size_of) ->
?equal:('a -> 'a -> bool) ->
?compare:('a -> 'a -> int) ->
?short_hash:('a -> int) ->
?pre_hash:'a bin_seq ->
'b t ->
('b -> 'a) ->
('a -> 'b) ->
'a ttype 'a ty = 'a tmodule type S = sig ... end