package ezjsonm-encoding

  1. Overview
  2. Docs

Module Ezjsonm_encodingSource

An encoding combinators library for Ezjsonm whose API, heavily inspired by data-encoding.

The two main differences between ezjsonm-encoding and the JSON support of data-encoding are:

  • objN combinators accept JSON objects with _more_ fields than the one explicitely specified in the encoding.
  • ezjsonm-encoding does not have a dependency to Zarith (which depends on GMP). As a consequence, `ezjsonm-encoding` does not provide support for big numbers out of the box.

The examples of this documentation can be copy/pasted to an OCaml REPL.

Sourcetype 'a t

A JSON encoding combinator for a value of type 'a.

Sourceval to_value_exn : 'a t -> 'a -> Ezjsonm.value

to_value_exn encoding value encodes value in JSON using encoding. Will raise an exception in case encoding cannot serialize value.

  open Ezjsonm_encoding

  let encoding = obj1 (req "hello" string)

  let json = to_value_exn encoding "world"
    (* `O [("hello", `String "world")] *)
Sourceval to_value : 'a t -> 'a -> Ezjsonm.value option

to_value_exn encoding value encodes value in JSON using encoding. Will return None in case encoding cannot serialize value.

Sourceval to_string_exn : minify:bool -> 'a t -> 'a -> string

to_string_exn ~minify encoding value encodes value using encoding into a JSON value serialized in a string. Will raise an exception in case encoding cannot serialize value.

Sourceval to_string : minify:bool -> 'a t -> 'a -> string option

to_string ~minify encoding value encodes value using encoding into a JSON value serialized in a string. Will return None in case encoding cannot serialize value.

Sourceval from_string_exn : 'a t -> string -> 'a

from_string_exn encoding str decodes a JSON value from str, then uses encoding to construct an OCaml value. Will raise an exception if str is not a valid JSON value, or if encoding cannot construct an OCaml value from str.

Sourceval from_string : 'a t -> string -> 'a option

from_string encoding str decodes a JSON value from str, then uses encoding to construct an OCaml value. Will return None if str is not a valid JSON value, or if encoding cannot construct an OCaml value from str.

Sourceval from_value_exn : 'a t -> Ezjsonm.value -> 'a

from_value_exn encoding value uses encoding to construct an OCaml value from value. Will raise an exception if encoding cannot construct an OCaml value from value.

Sourceval from_value : 'a t -> Ezjsonm.value -> 'a option

from_string encoding str decodes a JSON value from str, then uses encoding to construct an OCaml value. Will return None if str is not a valid JSON value, or if encoding cannot construct an OCaml value from str.

The identity encoding.

Sourceval conv : ('a -> 'b) -> ('b -> 'a) -> 'b t -> 'a t

conv f g encoding crafts a new encoding from encoding. This is typically used to creates a JSON encoder/decoder for OCaml records by projecting them to tuples, and using objN combinators.

  open Ezjsonm_encoding

  type t = { f1 : int; f2 : bool }

  let encoding =
    conv
      (fun { f1; f2 } -> (f1, f2))
      (fun (f1, f2) -> { f1; f2 })
      (obj2 (req "f1" int) (req "f2" bool))

  let json = to_value_exn encoding { f1 = 0; f2 = true }
    (* `O [("f2", `Bool true); ("f1", `Float 0.)] *)
Sourceval string_enum : (string * 'a) list -> 'a t

string_enum maps JSON strings to fixed OCaml values.

  open Ezjsonm_encoding

  type toggle = On | Off

  let toggle_encoding = string_enum [ "on", On; "off", Off ]

  let json = to_value_exn toggle_encoding On
    (* `String "on" *)

  let toggle = from_string_exn toggle_encoding {|"on"|}
    (* On *)
Sourceval enum : 'b t -> ('b * 'a) list -> 'a t

enum is a more generic version of string_enum, taking an encoder to deal with the supported constant values.

  open Ezjsonm_encoding

  type toggle = On | Off

  let toggle_encoding = enum int [ 1, On; 2, Off ]

  let json = to_value_exn toggle_encoding On
    (* `Float 1. *)

  let toggle = from_string_exn toggle_encoding {|1|}
    (* On *)
Sourceval constant : string -> unit t

constant name maps the JSON string name to (). A typical use case for constant is to tag objects.

  open Ezjsonm_encoding

  let encoding =
    conv
      (fun str -> ((), str))
      (fun ((), str) -> str)
      (obj2
        (req "purpose" (constant "name"))
        (req "value" string))

  let json = to_value_exn encoding "Thomas"
    (* `O [("value", `String "Thomas"); ("purpose", `String "name")] *)

  let value = from_string_exn encoding {|{"purpose": "name", "value": "Thomas"}|}
    (* "Thomas" *)
Sourceval string : string t

The encoding which maps JSON strings and OCaml strings.

  open Ezjsonm_encoding

  let json = to_value_exn string "hello, world!"
    (* `String "hello, world!" *)

  let str = from_string_exn string {|"hello, world!"|}
    (* "hello, world!" *)
Sourceval int64 : int64 t

The encoding which maps JSON ints and OCaml int64. As a reminder, Ezjsonm uses floats internally to encode integers.

  open Ezjsonm_encoding

  let json = to_value_exn int64 1L
    (* `Float 1. *)

  let str = from_string_exn int64 "1"
    (* 1L *)
Sourceval int : int t

The encoding which maps JSON ints and OCaml ints. As a reminder, Ezjsonm uses floats internally to encode integers.

  open Ezjsonm_encoding

  let json = to_value_exn int 1
    (* `Float 1. *)

  let str = from_string_exn int "1"
    (* 1 *)
Sourceval null : unit t

The encoding which maps JSON null and OCaml unit.

  open Ezjsonm_encoding

  let json = to_value_exn null ()
    (* `Null *)

  let str = from_string_exn null "null"
    (* 1 *)
Sourceval bool : bool t

The encoding which maps JSON booleans and OCaml booleans.

  open Ezjsonm_encoding

  let json = to_value_exn bool false
    (* `Bool false *)

  let str = from_string_exn bool "false"
    (* false *)
Sourceval list : 'a t -> 'a list t

list encoding creates a encoding for a list of values based on the encoding of said values.

  open Ezjsonm_encoding

  let json = to_value_exn (list bool) [true; true; false]
    (* `A [`Bool true; `Bool true; `Bool false] *)

  let str = from_string_exn (list int) "[1, 2, 3]"
    (* [1; 2; 3] *)
Sourceval empty : unit t

empty maps the empty object to the OCaml unit value. Contrary to obj0, it is strict. That is, objects with fields will be rejected by this encoding.

  open Ezjsonm_encoding

  let json = to_value_exn empty ()
    (* `O [] *)

  let str = from_string_exn empty "{}"
    (* () *)
Sourceval tup1 : 'a t -> 'a t

tup1 f represents an array characterized by the positional (mandatory) element f.

  open Ezjsonm_encoding

  let json = to_value_exn (tup1 int) 1
  (* `A [`Float 1.] *)
Sourceval tup2 : 'a t -> 'b t -> ('a * 'b) t

tup2 f1 f2 represents an array characterized by two positional (mandatory) elements f1 and f2.

  open Ezjsonm_encoding

  let json = to_value_exn (tup2 int string) (1, "hello")
  (* `A [`Float 1.; `String "hello"] *)
Sourceval tup3 : 'a t -> 'b t -> 'c t -> ('a * 'b * 'c) t

Same as tup2 but with three positional elements.

Sourceval tup4 : 'a t -> 'b t -> 'c t -> 'd t -> ('a * 'b * 'c * 'd) t

Same as tup2 but with four positional elements.

Sourceval tup5 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> ('a * 'b * 'c * 'd * 'e) t

Same as tup2 but with five positional elements.

Sourceval tup6 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> ('a * 'b * 'c * 'd * 'e * 'f) t

Same as tup2 but with six positional elements.

Sourceval tup7 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> 'i t -> ('a * 'b * 'c * 'd * 'e * 'f * 'i) t

Same as tup2 but with seven positional elements.

Sourceval tup8 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> 'i t -> 'j t -> ('a * 'b * 'c * 'd * 'e * 'f * 'i * 'j) t

Same as tup2 but with eight positional elements.

Sourceval tup9 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> 'i t -> 'j t -> 'k t -> ('a * 'b * 'c * 'd * 'e * 'f * 'i * 'j * 'k) t

Same as tup2 but with nine positional elements.

Sourceval tup10 : 'a t -> 'b t -> 'c t -> 'd t -> 'e t -> 'f t -> 'i t -> 'j t -> 'k t -> 'l t -> ('a * 'b * 'c * 'd * 'e * 'f * 'i * 'j * 'k * 'l) t

Same as tup2 but with 10 positional elements.

Sourcetype 'a field

The description of one field of a JSON object. See req, opt and dft to construct field values, and obj1 to obj10 and merge_objs to construct encoding for objects.

Sourceval req : string -> 'a t -> 'a field

req field_name encoding represents a required field. That is, the decoding will fail if provided an object lacking this field (and raises an exepction with from_string_exn and from_string_exn).

  open Ezjsonm_encoding

  let json = to_value_exn (obj1 (req "hello" string)) "world!"
    (* `O [("hello", `String "world!")] *)

  let str = from_string_exn (obj1 (req "hello" string)) {|{ "hello": "world!"}|}
    (* "world!" *)

  let str = from_string (obj1 (req "hello" string)) {|{ "bye": "world!"}|}
    (* None *)
Sourceval opt : string -> 'a t -> 'a option field

opt field_name encoding represents an optional field (i.e., wrapped in an option).

If the field is present but cannot be decoded by encoding, then None is returned. This may change in a future version of this library.

  open Ezjsonm_encoding

  let json = to_value_exn (obj1 (opt "hello" string)) (Some "world!")
    (* `O [("hello", `String "world!")] *)

  let json' = to_value_exn (obj1 (opt "hello" string)) None
    (* `O [] *)

  let str = from_string_exn (obj1 (opt "hello" string)) {|{ "hello": "world!"}|}
    (* Some "world!" *)

  let str = from_string (obj1 (opt "hello" string)) {|{ "bye": "world!"}|}
    (* Some None *)
Sourceval dft : ?equal:('a -> 'a -> bool) -> string -> 'a t -> 'a -> 'a field

dft field_name encoding default represents an optional field that defaults to default in OCaml if missing. The field is omitted when encoding if the value is equal (according to equal, defaulting to (=)) the default value.

If the field is present but cannot be decoded by encoding, then default is returned. This may change in a future version of this library.

  open Ezjsonm_encoding

  let encoding = obj1 (dft "hello" string "world!")

  let json1 = to_value_exn encoding "friend!"
  (* `O [("hello", `String "friend!")] *)

  let json2 = to_value_exn encoding "world!"
  (* `O [] *)

  let str = from_string_exn encoding {|{ "hello": "Kat!"}|}
  (* "Kat!" *)
Sourceval obj0 : unit t

obj0 represents the empty object. Since ezjsonm-encoding default behavior is to ignore unspecified fields, obj0 matches any objects. Use empty if you want to reject non-empty objects.

Sourceval obj1 : 'a field -> 'a t

obj1 f represents an object characterized by at least the field f. This field can be optional or required depending on how it has been defined (see req and opt).

Sourceval obj2 : 'a field -> 'b field -> ('a * 'b) t

obj2 f1 f2 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj3 : 'a field -> 'b field -> 'c field -> ('a * 'b * 'c) t

obj3 f1 f2 f3 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj4 : 'a field -> 'b field -> 'c field -> 'd field -> ('a * 'b * 'c * 'd) t

obj4 f1 f2 f3 f4 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj5 : 'a field -> 'b field -> 'c field -> 'd field -> 'e field -> ('a * 'b * 'c * 'd * 'e) t

obj5 f1 f2 f3 f4 f5 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj6 : 'a field -> 'b field -> 'c field -> 'd field -> 'e field -> 'f field -> ('a * 'b * 'c * 'd * 'e * 'f) t

obj6 f1 f2 f3 f4 f5 f6 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj7 : 'a field -> 'b field -> 'c field -> 'd field -> 'e field -> 'f field -> 'g field -> ('a * 'b * 'c * 'd * 'e * 'f * 'g) t

obj7 f1 f2 f3 f4 f5 f6 f7 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj8 : 'a field -> 'b field -> 'c field -> 'd field -> 'e field -> 'f field -> 'g field -> 'h field -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h) t

obj8 f1 f2 f3 f4 f5 f6 f7 f8 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj9 : 'a field -> 'b field -> 'c field -> 'd field -> 'e field -> 'f field -> 'g field -> 'h field -> 'i field -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i) t

obj9 f1 f2 f3 f4 f5 f6 f7 f8 f9 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval obj10 : 'a field -> 'b field -> 'c field -> 'd field -> 'e field -> 'f field -> 'g field -> 'h field -> 'i field -> 'j field -> ('a * 'b * 'c * 'd * 'e * 'f * 'g * 'h * 'i * 'j) t

obj10 f1 f2 f3 f4 f5 f6 f7 f8 f9 f10 represents an object characterized by at least the fields passed as arguments. They can be optional or required depending on how they have been defined (see req and opt).

Sourceval merge_objs : 'a t -> 'b t -> ('a * 'b) t

merg_objs obj1 obj2 represents an object characterized by at least the fields of obj1 and obj2. This is useful when an object expects at least more than 10 fields. Note that it is expected that obj1 and obj2 do not have conflict wrt. field names. This is not checked by ezjsonm-encoding, and is considered an undefined behavior (which may change in a future version of the library).

  open Ezjsonm_encoding

  let json =
    to_value_exn
      (merge_objs
         (obj2 (req "foo" string) (req "bar" bool))
         (obj1 (opt "foobar" int)))
      (("hello", true), Some 1)
    (* `O [("bar", `Bool true); ("foo", `String "hello"); ("foobar", `Float 1.)] *)
Sourceval case : ('a -> 'b option) -> ('b -> 'a) -> 'b t -> 'a t

case proj inj enc is a partial encoding that can be used to encode and decode a subset of the values of the type domain. It is typically used with union.

Sourceval union : 'a t list -> 'a t

union cases is the union of several partial encoding. It can be used to decode and encode algebraic data type. Cases are tried in order, i.e., the first encoding which works is selected.

union is compatible with merge_objs if every encoding in cases matches objects.

  open Ezjsonm_encoding

  type id = Number of int | String of string | Null

  let id_encoding =
    union
      [
        case (function Number i -> Some i | _ -> None) (fun i -> Number i) int;
        case
          (function String s -> Some s | _ -> None)
          (fun s -> String s)
          string;
        case (function Null -> Some () | _ -> None) (fun () -> Null) null;
      ]

  let json = to_value_exn id_encoding (Number 1)
  (* `String "on" *)

  let id = from_string_exn id_encoding {|1|}
  (* Number 1 *)

  let json = to_value_exn id_encoding Null
  (* `Null *)

  let id = from_string_exn id_encoding {|null|}
  (* Null *)
Sourceval satisfies : ('a -> bool) -> 'a t -> 'a t

satisfies cond enc restricts the domain of enc to values satisfying cond.

  open Ezjsonm_encoding

  let ranged_int = satisfies (fun i -> 2 < i && i <= 5) int

  let json1 = to_value ranged_int 1
  (* None *)

  let json2 = to_value ranged_int 3
  (* Some (`Float 3) *)
Sourcemodule Decoding : sig ... end
OCaml

Innovation. Community. Security.