decoders 0.1.0 · OCaml Package

User-facing Decoder interface.

type value

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

type error = value exposed_error

val pp_error : Format.formatter -> error -> unit

val of_string : string -> (value, error) result

val of_file : string -> (value, error) result

type 'a decoder

The type of decoders.

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

To run a decoder, pass it to decode_value.

Primitives

val string : string decoder

Decode a string.

val int : int decoder

Decode an int.

val float : float decoder

Decode a float.

val bool : bool decoder

Decode a bool.

val value : value decoder

Decode a literal value.

Data structures

val list : 'a decoder -> 'a list decoder

Decode a collection into an OCaml list.

val list_filter : 'a option decoder -> 'a list decoder

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

Object primitives

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

Decode an object, requiring a particular field.

val single_field : (string -> 'a decoder) -> 'a decoder

Decode an object, requiring exactly one field.

val index : int -> 'a decoder -> 'a decoder

Decode an array, requiring a particular index.

val at : string list -> 'a decoder -> 'a decoder

Decode a nested object, requiring certain fields.

Inconsistent structure

val maybe : 'a decoder -> 'a option decoder

Helpful for dealing with optional fields.

val nullable : 'a decoder -> 'a option decoder

val one_of : (string * 'a decoder) list -> 'a decoder

Try a sequence of different decoders.

Mapping

Map functions are useful for decoding complex objects.

For example, given an object with structure

{
  "name": "Joe"
      "age": 42
}

we want to decode it to our OCaml type

type person =
  { name : string
  ; age : int
  }

We define a helper function to construct values of this type:

let as_person name age =
  { name = name
  ; age = age
  }

The decoder looks like this:

let person_decoder : person decoder =
  map2 as_person
    (field "name" string)
    (field "age" int)

val map : ('a -> 'b) -> 'a decoder -> 'b decoder

Transform a decoder.

val apply : ('a -> 'b) decoder -> 'a decoder -> 'b decoder

Try two decoders and then combine the result. We can use this to decode objects with many fields.

Working with object keys

val keys : string list decoder

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

val key_value_pairs : 'v decoder -> (string * 'v) list decoder

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

val key_value_pairs_seq : (string -> 'v decoder) -> 'v list decoder

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

val keys' : 'k decoder -> 'k list decoder

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

val key_value_pairs' : 'k decoder -> 'v decoder -> ('k * 'v) list decoder

val key_value_pairs_seq' : 'k decoder -> ('k -> 'v decoder) -> 'v list decoder

Decode an object into a String.Map.t.

Fancy decoding

val succeed : 'a -> 'a decoder

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

val fail : string -> 'a decoder

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

val fail_with : error -> 'a decoder

val from_result : ('a, error) result -> 'a decoder

val and_then : ('a -> 'b decoder) -> 'a decoder -> 'b decoder

Create decoders that depend on previous results.

val fix : ('a decoder -> 'a decoder) -> 'a decoder

Recursive decoders.

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

module Infix : sig ... end

include module type of Infix

val (>|=) : 'a decoder -> ('a -> 'b) -> 'b decoder

val (>>=) : 'a decoder -> ('a -> 'b decoder) -> 'b decoder

val (<*>) : ('a -> 'b) decoder -> 'a decoder -> 'b decoder

Running decoders

val decode_value : 'a decoder -> value -> ('a, error) result

Run a decoder on some input.

val decode_string : 'a decoder -> string -> ('a, error) result

Run a decoder on a string.

val decode_file : 'a decoder -> string -> ('a, error) result

Run a decoder on a file.

module Pipeline : sig ... end

package decoders