Module Jsont

module Jsont: 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 0.0.0-16-gb3662d5 — Daniel Bünzli <daniel.buenzl>

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 Jsont.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 = Jsont_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 = Jsont_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 Jsont.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 Jsont.int_strict.
val int_strict : int codec
int_strict is like 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 Jsont.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
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: 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 Jsont.nullable for encoding an option. The result of some c is to be given to Jsont.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 Jsont.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
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 Jsont.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 Jsont.anon or Jsont.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 Jsont.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 Jsont.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 Jsont.get but with location information.
val find_anon_def : 'a anon -> string -> obj -> 'a def option
find_anon_def is like Jsont.find_anon but with location information.
val get_anon_def : 'a anon -> string -> obj -> 'a def
get_anon_def is like Jsont.get_anon but with location information.

JSON decode

type error = [ `Json_decoder of Jsont_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 ] ->
Jsont_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:
val decode : 'a decoder ->
[ `Await | `Error of error def | `Ok of 'a def ]
decode d is:

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 -> Jsont_codec.decoder
decoder_decoder d is d's backend decoder.

JSON encode

type encoder 
The type for encoders.
val encoder : Jsont_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

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

val encoder_encoder : encoder -> Jsont_codec.encoder
encoder_encoder e is e's backend encoder.





Modeling JSON data