Module type Decode.S

The type of values to be decoded (e.g. JSON or Yaml).

The type of decoders.

Use the functions below to construct decoders for your data types.

To run a decoder, pass it to decode_value.

Decode a string.

Decode an int.

Decode a float.

Decode a bool.

Decode a null.

Decode a literal value.

Decode a collection into an OCaml list.

Decode a collection into an OCaml list, skipping elements for which the decoder returns None.

Decode a collection with an accumulator.

If we consider that an 'a decoder is basically a type alias for json -> ('a, error) result, the signature of this function is comparable to that of List.fold_left:

val List.fold_left : ('a ->   'b ->                 'a) -> 'a -> 'b list ->                 'a
val list_fold_left : ('a -> json -> ('a, error) result) -> 'a ->    json -> ('a, error) result
val list_fold_left : ('a ->                 'a decoder) -> 'a ->                    'a decoder

Decode a collection into an OCaml array.

Decode a collection, requiring a particular index.

fst |> uncons rest decodes the first element of a list using fst, then decodes the remainder of the list using rest.

For example, to decode this s-expression:

(library
  (name decoders))

we can use this decoder:

string |> uncons (function
  | "library" -> field "name" string
  | _ -> fail "Expected a library stanza")

As another example, say you have a JSON array that starts with a string, then a bool, then a list of integers:

["hello", true, 1, 2, 3, 4]

We could decode it like this:

let (>>=::) fst rest = uncons rest fst

let decoder : (string * bool * int list) decoder =
  string >>=:: fun the_string ->
  bool >>=:: fun the_bool ->
  list int >>= fun the_ints ->
  succeed (the_string, the_bool, the_ints)

(If you squint, the uncons operator >>=:: kind of looks like the cons operator ::.)

Decode an object, requiring a particular field.

Decode an object, where a particular field may or may not be present.

For example, (field_opt "hello" int):

• when run on {"hello": 123}, will succeed with Some 123
• when run on {"hello": null}, will fail
• when run on {"world": 123}, will succeed with None
• when run on ["a", "list", "of", "strings"], will fail

Similar to field_opt but with a default value.

• since 0.7

Decode an object, requiring exactly one field.

Decode a nested object, requiring certain fields.

maybe d is a decoder that always succeeds. If d succeeds with x, then maybe d succeeds with Some x, otherwise if d fails, then maybe d succeeds with None.

For example, maybe (field "hello" int):

• when run on {"hello": 123}, will succeed with Some 123
• when run on {"hello": null}, will succeed with None
• when run on {"world": 123}, will succeed with None
• when run on ["a", "list", "of", "strings"], will succeed with None

nullable d will succeed with None if the JSON value is null. If the JSON value is non-null, it wraps the result of running x in a Some.

For example, field "hello" (nullable int):

• when run on {"hello": 123}, will succeed with Some 123
• when run on {"hello": null}, will succeed with None
• when run on {"world": 123}, will fail
• when run on ["a", "list", "of", "strings"], will fail

Try a sequence of different decoders.

pick choices picks a single choice, like one_of. However, each element of choices can look at the value, decide if it applies (e.g. based on the value of a single field, like a "kind" or "type" field), and if it does, returns a decoder for the rest of the value.

If a choice is made, even if the returned sub-decoder fails, the error message will totally ignore the rest of the choices and only be about the choice that was initially made.

• since 0.7

decode_sub value sub_dec uses sub_dec to decode value. This is useful when one has a value on hand.

• since 0.7

Map over the result of a decoder.

Try two decoders and then combine the result. We can use this to decode objects with many fields (but it's preferable to use Infix.(>>=) - see the README).

Decode all of the keys of an object to a list of strings.

Decode an object into a list of key-value pairs.

Decode an object into a list of values, where the value decoder depends on the key.

keys' is for when your keys might not be strings - probably only likely for Yaml.

A decoder that always succeeds with the argument, ignoring the input.

A decoder that always fails with the given message, ignoring the input.

Create decoders that depend on previous results.

Recursive decoders.

let my_decoder = fix (fun my_decoder -> ...) allows you to define my_decoder in terms of itself.

Create a decoder from a function of_string : string -> 'a option

Run a decoder on some input.

Run a decoder on a string.

Run a decoder on a file.