decoders 1.0.0 · OCaml Package

Interface for decoding XML

type value

The type of XML values.

type error = value Error.t

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

val string_of_error : error -> string

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

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

type 'a decoder = (value, 'a) Decoder.t

The type of decoders.

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

To run a decoder, pass it to decode_value.

Decoding values

val data : string decoder

Decode a string.

val tag : string -> unit decoder

Assert the name of the current tag.

val any_tag : string decoder

Retrieve the name of the current tag.

val attr : string -> string decoder

attr name decodes the attribute named name.

val attr_opt : string -> string option decoder

attr_opt name decodes the attribute named name, if present.

val attrs : (string * string) list decoder

attrs decodes the attributes as an assoc list.

Children

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

children dec Decodes all the children of the current tag using dec.

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

pick_children outer_decoder Decodes the children of the current tag.

If outer_decoder fails, the child is skipped and the error is ignored.

If outer_decoder succeeds with inner_decoder, inner_decoder is used to decode the child.

For example, to decode only children like <Child>:

pick_children (tag "Child" >>= fun () -> succeed decode_child)

To decode only child elements, skipping data nodes (often useful when there are data nodes introduced by whitespace between elements in the XML):

pick_children (any_tag >>= fun tag_name -> succeed (decode_child_tag tag_name))

Inconsistent structure

val value : value decoder

Decode a literal value.

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

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.

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

Try a sequence of different decoders.

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

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.

val decode_sub : value -> 'a decoder -> 'a decoder

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

Mapping

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

Map over the result of 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 (but it's preferable to use Infix.(>>=) - see the README).

Fancy decoding

val pure : 'a -> 'a decoder

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

val succeed : 'a -> 'a decoder

Alias for pure.

val fail : string -> 'a decoder

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

val fail_with : error -> 'a decoder

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

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 : module type of Decoder.Infix

include module type of Infix

val (>>=) : 
  ('i, 'a) Decoder.t ->
  ('a -> ('i, 'b) Decoder.t) ->
  ('i, 'b) Decoder.t

val (>|=) : ('i, 'a) Decoder.t -> ('a -> 'b) -> ('i, 'b) Decoder.t

val (<*>) : 
  ('i, 'a -> 'b) Decoder.t ->
  ('i, 'a) Decoder.t ->
  ('i, 'b) Decoder.t

type ('i, 'o) t_let = ('i, 'o) Decoder.t

val let+ : ('i, 'a) t_let -> ('a -> 'b) -> ('i, 'b) t_let

val and+ : ('i, 'a) t_let -> ('i, 'b) t_let -> ('i, 'a * 'b) t_let

val let* : ('i, 'a) t_let -> ('a -> ('i, 'b) t_let) -> ('i, 'b) t_let

val and* : ('i, 'a) t_let -> ('i, 'b) t_let -> ('i, 'a * 'b) t_let

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.