package repr

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

The type of integer used to store buffers, list or array lengths.

Int use a (compressed) variable encoding to encode integers in a binary format, while IntX always use X bytes. Overflows are not detected.

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 integers. Binary serialization uses a varying-width representation.

int32 is a representation of the 32-bit integer 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.

bytes is a representation of the bytes type.

Like string but with a given kind of size.

Like bytes but with a given kind of size.

boxed t is the same as t but with a binary representation which is always boxed (e.g. top-level values won't be unboxed). This forces Unboxed functions to be exactly the same as boxed ones.

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

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

option t is a representation of values 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.

result a b is a representation of values of type (a, b) result.

either a b is a representation of values of type (a, b) Either.t.

An uninhabited type, defined as a variant with no constructors.

empty is a representation of the empty type.

The type for representing open records of type 'a with a constructor of type 'b. 'c represents the remaining fields to be described using the (|+) operator. An open record initially satisfies 'c = 'b and can be sealed once 'c = 'a.

record n f is an incomplete representation of the record called n of type 'a with constructor f. To complete the representation, add fields with (|+) and then seal the record with sealr.

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

r |+ f is the open record r augmented with the field f.

sealr r seals the open record r. Raises. Invalid_argument if two or more fields share the same name.

The type for representing open variants of type 'a with pattern matching of type 'b. 'c represents the remaining constructors to be described using the (|~) operator. An open variant initially satisfies c' = 'b and can be sealed once 'c = 'a.

variant n p is an incomplete representation of the variant type called n of type 'a using p to deconstruct values. To complete the representation, add cases with (|~) and then seal the variant with sealv.

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

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

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

sealv v seals the open variant v. Raises. Invalid_argument if two or more cases of same arity share the same name.

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

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" (option 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))

The type for staged operations.

stage x stages x.

unstage x unstages x.

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

compare t compares values of type t.

The type for pretty-printers.

The type for parsers.

pp t is the pretty-printer for values of type t.

pp_dump t is the dump pretty-printer for values of type t.

This pretty-printer outputs an encoding which is as close as possible to native OCaml syntax, so that the result can easily be copy-pasted into an OCaml REPL to inspect the value further.

The pretty printer for generics of type t.

to_string t is Fmt.to_to_string (pp t).

of_string t parses values of type t.

Overlay on top of Jsonm to work with rewindable streams.

The type for JSON encoders.

The type for JSON decoders.

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

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:

• The unit value () is translated into the empty object {}.
• 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 options are translated differently depending on context: record fields with a value of 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.
• 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. It'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 uses an already decoded list of JSON lexemes instead of a decoder.

to_json_string is encode_json with a string encoder.

of_json_string is decode_json with a string decoder .

The type for binary encoders.

The type for binary decoders.

The type for size function related to binary encoder/decoders.

hash t x is a short hash of x of type t.

pre_hash t x is the string representation of x, of type t, which will be used to compute the digest of the value. By default it's to_bin_string t x but it can be overriden by v, like and map operators.

encode_bin t is the binary encoder for values of type t.

decode_bin t is the binary decoder for values of type t.

to_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).

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

Unboxed operations assumes that value being serialized is fully filling the underlying buffer. When that's the case, it is not necessary to prefix the value's binary representation by its size, as it is exactly the buffer's size.