Module Ezjsonm_encodingSource

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

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")] *)

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

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.

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.

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.

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.

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.

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.

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

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

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!" *)

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

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

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

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] *)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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