Module Jsonc

module Jsonc: sig .. end

JSON data structure codecs.

Jsont describes JSON data structures with codec combinators. The resulting typed descriptions enable JSON backend codecs to encode and decode these structures from/to OCaml values.

Consult the basics and limitations.

Release v0.0.0-18-gc65e084 — %%MAINTAINER%%

Value codecs

Value codec allow to refine JSON value codecs to more appopriate OCaml types and hook into Jsont's error reporting mecanism. This allows, for example, to parse a JSON string value into an URI, a JSON object into a record, etc.

type ('a, 'b) value_decoder = 'a -> [ `Error of string | `Ok of 'b ]

The type for value decoders.

type ('b, 'a) value_encoder = 'b -> 'a

The type for value encoders.

type ('a, 'b) value_codec = ('a, 'b) value_decoder * ('b, 'a) value_encoder

The type for value codecs.

Value location

type loc = (int * int) * (int * int)

The type for value location ranges. A pair of line and column numbers repsectively one and zero based.

type 'a def = loc * 'a

The type for values tagged with a location.

val invalid_loc : loc

invalid_loc is an invalid location.

val is_invalid_loc : loc -> bool

is_invalid_loc l is true iff l is Jsonc.invalid_loc.

val invalid_def : 'a -> 'a def

invalid_def v is (invalid_loc, v)

val undef : 'a def -> 'a

undef v is snd v.

JSON values

type nat_string = Jsonc_codec.nat_string

The type for native strings.

val nat_string_of_string : string -> nat_string

nat_string_of_string s is a native string from the OCaml string s.

val nat_string_to_string : nat_string -> string

nat_string_to_string s is an OCaml string from the native string s.

type soup = Jsonc_codec.soup

The type for arbitrary undescribed JSON values.

type obj

The type for JSON object values. Values of this type represent a concrete JSON object that conforms to a particular object codec. See the functions in JSON object value for using values of this type.

JSON base value codecs

type 'a codec

The type for JSON value codecs. A value of this type describes a JSON value structure and knows how to codec it to an OCaml value of type 'a.

All value codecs have a Jsonc.default value of type 'a. This value is used either as a placeholder in case of error during robust parsing or as a default value during object creation.

val default : 'a codec -> 'a

default c is c's default value.

val with_default : 'a -> 'a codec -> 'a codec

with_default v c is c with default value v.

val null : [ `Null ] codec

null is the JSON null value. `Null is its default value.

val bool : bool codec

bool is a JSON boolean. false is its default value.

val float : float codec

float is a JSON number. 0. is its default value.

val int : int codec

int is a JSON number as an integer. 0 is its default value. Any existing fractional part is truncated, see also Jsonc.int_strict.

val int_strict : int codec

int_strict is like Jsonc.int but errors on a JSON number with a fractional part.

val string : string codec

string is a JSON string. "" is its default value.

val nat_string : nat_string codec

nat_string is like Jsonc.string but the OCaml representation is a backend native string value. The empty native string is its default value.

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

nullable c is either the JSON value c or JSON null. Some (default d) is its default value.

val view : ?default:'b -> ('a, 'b) value_codec -> 'a codec -> 'b codec

view view c is the JSON value c whose OCaml representation is transformed by value codec view.
Raises Invalid_argument if default is absent and c's default value cannot be parsed by view.

val enum : ?default:'a -> (string * 'a) list -> 'a codec

enum default enums maps finite sets of JSON strings to values of type 'a. default defaults to the first element of the list.

Warning. The type 'a must be comparable with Pervasives.compare
Raises Invalid_argument if enums is empty.

val type_match : default:'a ->
       ([ `Array | `Bool | `Float | `Null | `Object | `String ] ->
        [ `Error of string | `Ok of 'a codec ]) ->
       ('a -> 'a codec) -> 'a codec

type_match default dec enc is a JSON value codec by:

On decoding: dec typ where typ is determined according to the type found in the data. If `Error is returned on a given data type the error will be returned by the decoder. If `Ok d is, d is used to decode the value. You must make sure that d does actually describe the given datatype (i.e. it would be wrong to return Jsonc.int on `Bool).
On encoding: enc v where v is the member value.

default is its default value.

val soup : soup codec

soup is any JSON value. JSON's null is its default value.

type json = [ `A of json list
       | `Bool of bool
       | `Float of float
       | `Null
       | `O of (nat_string * json) list
       | `String of nat_string ]

The type generic JSON text representations.

val json : json codec

json is any JSON value using a generic JSON text representation. `Null it its default value.

val some : 'a codec -> 'a option codec

some c is the JSON value c but wrapped by Some. Its default value is None.

Warning. None cannot be encoded with this combinator, it will raise Invalid_argument, use Jsonc.nullable for encoding an option. The result of some c is to be given to Jsonc.mem with ~opt:`Yes_rem.

JSON array codecs

val array : 'a codec -> 'a list codec

array elt is a JSON array whose elements are JSON values elt. [] is its default value.

val array_array : 'a codec -> 'a array codec

array_array is like Jsonc.array but the OCaml representation is an array. [||] is its default value.

JSON object codec

type objc

The type for JSON object codecs.

type 'a mem

The type for the JSON object member codecs. The type 'a is the OCaml value used to represent the member JSON value. A value of this type always tied to a particular object codec.

type 'a anon

The type for anonymous JSON object member codecs. The type 'a is the OCaml value used to represent all the unknown member JSON values of an object. A value of this type always tied to a particular object codec.

val objc : ?kind:string -> unit -> objc

objc kind () is a new object codec. kind can be used to give a name the to kind of object described (for error messages).

val mem : ?eq:('a -> 'a -> bool) ->
       ?opt:[ `No | `Yes | `Yes_rem ] ->
       objc -> string -> 'a codec -> 'a mem

mem opt o name c declares in o an object member named name with JSON value c. If opt is

`No (default), it is a decoding error if the member is missing from the object.
`Yes, the member can be absent on decoding in which case it will take c's default value.
`Yes_rem, the member can be absent on decoding in which case it will take c's default value. If on encoding the member value is equal to c's default value as determined by eq (defaults to =), the member will not be encoded in the output.

Raises Invalid_argument if name is already described in o or if o was already sealed.

val mem_opt : objc -> string -> 'a codec -> 'a option mem

mem_opt o name c is mem o name ~opt:`Yes_rem (some c). In other words: if the member is absent on decoding the member value with None; if the member value is None on encoding, the member is not encoded.

val mem_match : ?eq:('b -> 'b -> bool) ->
       ?opt:[ `No | `Yes | `Yes_rem ] ->
       objc ->
       'a mem -> string -> ('a -> 'b codec) -> 'b mem

mem_match opt o m name select is like Jsonc.mem, except its value at encoding and decoding time is determined by select v where v is the value of the member m in the JSON object. Its default is the default of the codec resulting from applying m's default to select.

val anon : ?default:(string * 'a) list -> objc -> 'a codec -> 'a anon

anon o c declares that all unknown object members of o have a JSON value c.
Raises Invalid_argument if o already has an anonymous member description or if o was already sealed.

val obj : ?seal:bool -> objc -> obj codec

obj seal o is a codec for a JSON object described by o. The default value is an object o's members defaults.

If seal is true (default), o is sealed and the resulting codec can be used to codec data; it is no longer possible to modify it using Jsonc.anon or Jsonc.mem.

If seal is false, o is not sealed. The resulting codec can be used with the combinators in the definition of other codecs and it's still possible to modify o. However Invalid_argument is raised if the codec is used to codec data or if it's default value accessed with Jsonc.default (either directly or indirectly through the default value of a codec that depends on it). It will be usable once o has been seal by calling obj again on o with seal:true (the resulting codec can be ignored).

JSON object value

Warning. All the functions below when used on a JSON object value that is not derived from the object codec used to access them raise Invalid_argument. An object is derived from an object codec either if it was created with the codec or if it was decoded using that codec.

type memv

The type for a member and its value.

val memv : 'a mem -> 'a -> memv

memv m v is member m with value v.

val anonv : 'a anon -> string -> 'a -> memv

anonv a name v is an a anonymous member named name with value v.

val new_obj : obj codec -> memv list -> obj

new_obj c memvs is a new object described by c with members memvs. Unspecified members default to the defaults of c.

val get : 'a mem -> obj -> 'a

get m o is o's m member value.

val set : 'a mem -> obj -> 'a -> obj

set m o v is o except o's m member value is v.

val anon_names : 'a anon -> obj -> string list

anon_names a o is o's list of anonymous member names.

val find_anon : 'a anon -> string -> obj -> 'a option

find_anon a name o is o's name anonymous member value. None is returned if name is not an anonymous member of o.

val get_anon : 'a anon -> string -> obj -> 'a

get_anon is like Jsonc.find_anon but
Raises Invalid_argument if the name is absent.

val add_anon : 'a anon -> string -> obj -> 'a -> obj

add_anon a name o v is o except its name anonymous member is v.

val rem_anon : 'a anon -> string -> obj -> obj

rem_anon a name o is o except its name anonymous member is deleted.

Accessing position information

val get_def : 'a mem -> obj -> 'a def

get_def is like Jsonc.get but with location information.

val find_anon_def : 'a anon -> string -> obj -> 'a def option

find_anon_def is like Jsonc.find_anon but with location information.

val get_anon_def : 'a anon -> string -> obj -> 'a def

get_anon_def is like Jsonc.get_anon but with location information.

JSON decode

type error = [ `Json_decoder of Jsonc_codec.error
       | `Member of string * string * [ `Dup | `Miss | `Unknown ]
       | `Type of string * string
       | `Value_decoder of string ]

The type for decode errors.

val error_to_string : error -> string

error_to_string e is e as an unspecified string.

type 'a decoder

The type for decoders. The type 'a is the resulting OCaml type decoded.

val decoder : ?loc:bool ->
       ?dups:[ `Error | `Skip ] ->
       ?unknown:[ `Error | `Skip ] ->
       Jsonc_codec.decoder -> 'a codec -> 'a decoder

decoder unsafe loc mem_dups d v is a decoder for a value described v using the backend decoder d. The following optional may not be available in all backends:

loc if true will attach location information to the decoded values (default to false).
dups indicate the behaviour in case of duplicate object member in the data (defaults to `Skip).
unknown indicate the behaviour in case of unknown object member in the data (defaults to `Skip).

val decode : 'a decoder ->
       [ `Await | `Error of error def | `Ok of 'a def ]

decode d is:

`Await if d's backend decoder is non-blocking and needs a refill.
`Error e if an error occured. If the client is interested in a best-effort decoding it can still continue to decode.
`Ok v when the end of input was reached and the value is decoded. In case of error this value may be partially defined by codec default values.

Note. Repeated invocation always eventually return `Ok even in case of errors. In the worst case the returned value with be the decoder's default value.

val decoder_decoder : 'a decoder -> Jsonc_codec.decoder

decoder_decoder d is d's backend decoder.

JSON encode

type encoder

The type for encoders.

val encoder : Jsonc_codec.encoder -> 'a codec -> 'a -> encoder

encoder e c v is an encoder that encodes v as described by c using the native encoder e.

val encode : encoder -> [ `Ok | `Partial ]

encode e encodes the value in e returns

`Partial if e's native encoder is non-blocking an needs more output storage.
`Ok when the encoder finished to encode the value.

Note. You should always call the function until `Ok is returned.

val encoder_encoder : encoder -> Jsonc_codec.encoder

encoder_encoder e is e's backend encoder.

Basics

Tips

To keep the undescribed members of an object without bothering – e.g. if you are decoding an object to change a field and recode it back. Use Jsonc.anon with Jsonc.soup
For handling unreasonable object schemes with conditional and optional members get all members as optional and sort out the logic through a Jsonc.codec.