The type for runtime representation of values of type 'a.

unit is a representation of the unit type.

bool is a representation of the boolean type.

char is a representation of the character type.

int is a representation of the integer type.

int32 is a representation of the 32-bit integers type.

int64 is a representation of the 64-bit integer type.

float is a representation of the float type.

string is a representation of the string type.

list t is a representation of list of values of type t.

array t is a representation of array of values of type t.

option t is a representation of value of type t option.

pair x y is a representation of values of type x * y.

triple x y z is a representation of values of type x * y * z.

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.

sealr r seal the open record r.

r |+ f adds the field f to the open record r.

record 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)
    |> sealr

The type for representing variant cases of type 'a with patterns of type 'b.

The type for representing patterns for a variant of type 'a.

case0 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" Foo

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

sealv v seals the open variant v.

v |~ c is v augmented with the case c.

variant 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)
    |> sealr

enum 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]

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)

like x f g is the description of a type which looks like x using the bijetion (f, g).

dump t dumps the values of type t as a parsable OCaml expression.

equal t is the equality function between values of type t.

compare t compares values of type t.

The type for buffers.

size_of t is the size needed to serialize values of type t.

write t serializes values of type t. Use size_of to pre-determine the size of the buffer.

read t reads a serialization of a value of type t.

Similar 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.str "%a\n" (pp t) { foo = None; bar = ["foo"] }
  (* s is "{ foo = None; bar = [\"foo\"]; }" *)

  let j = Fmt.str "%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.

encode_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:

• OCaml ints are translated into JSON floats.
• OCaml strings are translated into JSON strings. You must then ensure that the OCaml strings contains only valid UTF-8 characters.
• OCaml record fields of type 'a option are automatically unboxed in their JSON representation. If the value if None, the field is removed from the JSON object.
• variant cases built using case0 are represented as strings.
• variant cases built using 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.

decode_json t e decodes values of type t from the jsonm decoder e.

decode_json_lexemes is similar to decode_json but use an already decoded list of JSON lexemes instead of a decoder.