ezjsonm-encoding 2.0.0 · OCaml Package

type 'a encoding = 'a t

type 'a t

A JSON decoder. Compared to an encoding, this type provides the mu combinator, and a monadic DSL to write decoder. See the Syntax module.

val from_encoding : 'a encoding -> 'a t

from_encoding specializes an Ezjsonmer encoding to be a decoder.

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

from_string enc input interprets input as a serialized Json value, then uses enc to decode it into an OCaml value, if possible. It returns None in case of error.

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

Same as from_string, but raises exceptions in case of error.

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

from_value enc value uses enc to decode value into an OCaml value, if possible. It returns None in case of error.

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

Same as from_value, but raises exceptions in case of error.

module Syntax : sig ... end

This modules provides a monadic interface to compose existing decoders together.

val field : string -> 'a t -> 'a t

field name dec decodes the input Json as an object which contains at least one property whose name is name, and whose value can be decoded with dec. The resulting OCaml value is returned as-is.

field is typically used to read from several property of an object, which can later be composed together.

let tup2 dl dr =
  let open Ezjsonm_encoding.Decoding in
  let open Syntax in
  let+ x = field "0" dl
  and+ y = field "1" dr in
  (x, y)

The decoding will fail in the input Json value does not have a property name.

val field_opt : string -> 'a t -> 'a option t

Same as field, but the the decoding will not fail if the input Json value does not have the expected property. In that case, None is returned.

val list : 'a t -> 'a list t

list enc decodes the input Json value as a list of values which can be decoded using enc.

val string : string t

string decodes the input Json value as a string.

val int64 : int64 t

int64 decodes the input Json value as an 64-byte integer.

val bool : bool t

bool decodes the input Json value as a boolean.

val float : float t

float decodes the input Json value as a float.

val string_enum : (string * 'a) list -> 'a t

string_enum l decodes the input Json value as a string, then compare said string with the values contained in the associated list l, to return the OCaml value associated to that string.

val mu : ('a t -> 'a t) -> 'a t

mu is a combinator that lets you write a recursive decoder, without having to write a recursive function. For instance, if mu can be used to manipulate tree-like structures.

open Ezjsonm_encoding.Decoding

type tree = { value : int64; children : tree list }

let decoder =
  let open Syntax in
  mu (fun tree_decoder ->
      let+ value = field "value" int64
      and+ children = field "children" @@ list tree_decoder in
      { value; children })

let leaf = of_string_exn decoder {|{ "value": 3 , "children" : [] }|}
  (* { value = 3L; children = [] } *)

let tree = of_string_exn decoder {|{ "value": 3 , "children" : [ { "value": 5, "children": [] } ] }|}
  (* { value = 3L; children = [{ value = 5L; children = [] }] } *)

package ezjsonm-encoding