Jsont.Repr
Low level representation (unstable).
This representation may change even between minor versions of the library. It can be used to devise new processors on JSON types.
Processors should be ready to catch the Jsont.Error
exception when they invoke functional members of the representation.
Processors should make sure they interpret mappings correctly. In particular:
Number
case represents the sets of JSON numbers and nulls.See the source of Json.decode'
and Json.encode'
for a simple example on how to process this representation. The paper in the Jsont source repository may also help to understand this menagerie of types.
type 'a t' := 'a t
module Type : sig ... end
Type identifiers. Can be removed once we require OCaml 5.1
type ('ret, 'f) dec_fun =
| Dec_fun : 'f -> ('ret, 'f) dec_fun
The function and its return type.
*)| Dec_app : ('ret, 'a -> 'b) dec_fun * 'a Type.Id.t -> ('ret, 'b) dec_fun
Application of an argument to a function witnessed by a type identifier. The type identifier can be used to lookup a value of the right type in an heterogenous dictionary.
*)The type for decoding functions.
type ('a, 'b) base_map = {
kind : string;
The kind of JSON value that are mapped (documentation)
*)doc : string;
A doc string for the kind of JSON value.
*)dec : Meta.t -> 'a -> 'b;
dec
decodes a base value represented by its metadata and 'a
to 'b
.
enc : 'b -> 'a;
enc
encodes a value of type 'b
to a base JSON value represented by 'a
.
enc_meta : 'b -> Meta.t;
enc_meta
recovers the base JSON value metadata from 'b
(if any).
}
The type for mapping JSON base values represented in OCaml by 'a
(these values are fixed by the cases in t
) to a value of type 'b
.
type 'a t =
| Null : (unit, 'a) base_map -> 'a t
Null maps.
*)| Bool : (bool, 'a) base_map -> 'a t
Boolean maps.
*)| Number : (float, 'a) base_map -> 'a t
Number maps.
*)| String : (string, 'a) base_map -> 'a t
String maps.
*)| Array : ('a, 'elt, 'builder) array_map -> 'a t
Array maps.
*)| Object : ('o, 'o) object_map -> 'o t
Object maps.
*)| Any : 'a any_map -> 'a t
Map for different sorts of JSON values.
*)| Map : ('b, 'a) map -> 'a t
Map from JSON type 'b
to JSON type 'a
.
| Rec : 'a t Stdlib.Lazy.t -> 'a t
Recursive definition.
*)The type for JSON types.
and ('array, 'elt, 'builder) array_map = {
kind : string;
The kind of JSON array mapped (documentation).
*)doc : string;
Documentation string for the JSON array.
*)elt : 'elt t;
The type for the array elements.
*)dec_empty : unit -> 'builder;
dec_empty ()
creates a new empty array builder.
dec_skip : int -> 'builder -> bool;
dec_skip i b
determines if the i
th index of the JSON array can be skipped.
dec_add : int -> 'elt -> 'builder -> 'builder;
dec_add
adds the i
th index value of the JSON array as decoded by elt
to the builder.
dec_finish : Meta.t -> int -> 'builder -> 'array;
dec_finish
turns the builder into an array given its metadata and length.
enc : 'acc. ('acc -> int -> 'elt -> 'acc) -> 'acc -> 'array -> 'acc;
enc
folds over the elements of the array for encoding.
enc_meta : 'array -> Meta.t;
enc_meta
recovers the metadata of an array (if any).
}
The type for mapping JSON arrays to values of type 'array
with array elements mapped to type 'elt
and using a 'builder
value to construct the array.
and ('o, 'dec) object_map = {
kind : string;
The kind of JSON object (documentation).
*)doc : string;
A doc string for the JSON member.
*)dec : ('o, 'dec) dec_fun;
The object decoding function to construct an 'o
value.
mem_decs : mem_dec String_map.t;
mem_decs
are the member decoders sorted by member name.
mem_encs : 'o mem_enc list;
mem_encs
is the list of member encoders.
enc_meta : 'o -> Meta.t;
enc_meta
recovers the metadata of an object (if any).
shape : 'o object_shape;
}
The type for mapping a JSON object to values of type 'o
using a decoding function of type 'dec
. mem_decs
and mem_encs
have the same mem_map
values they are just sorted differently for decoding and encoding purposes.
and ('o, 'a) mem_map = {
name : string;
The JSON member name.
*)doc : string;
Documentation for the JSON member.
*)type' : 'a t;
The type for the member value.
*)id : 'a Type.Id.t;
A type identifier for the member. This allows to store the decode in a Dict.t
on decode and give it in time to the object decoding function of the object map.
dec_absent : 'a option;
The value to use if absent (if any).
*)enc : 'o -> 'a;
enc
recovers the value to encode from 'o
.
enc_omit : 'a -> bool;
enc_omit
is true
if the result of enc
should not be encoded.
}
The type for mapping a JSON member to a value of type 'a
in an object represented by a value of type 'o
.
and 'o object_shape =
| Object_basic : ('o, 'mems, 'builder) unknown_mems -> 'o object_shape
A basic object, possibly indicating how to handle unknown members
*)| Object_cases : ('o, 'mems, 'builder) unknown_mems option
* ('o, 'cases, 'tag) object_cases -> 'o object_shape
An object with a case member each case further describing an object map.
*)The type for object shapes.
and ('o, 'mems, 'builder) unknown_mems =
| Unknown_skip : ('o, unit, unit) unknown_mems
Skip unknown members.
*)| Unknown_error : ('o, unit, unit) unknown_mems
Error on unknown members.
*)| Unknown_keep : ('mems, 'a, 'builder) mems_map
* ('o ->
'mems) -> ('o, 'mems, 'builder) unknown_mems
Gather unknown members in a member map.
*)The type for specifying decoding behaviour on unknown JSON object members.
and ('mems, 'a, 'builder) mems_map = {
kind : string;
The kind for unknown members (documentation).
*)doc : string;
Documentation string for the unknown members.
*)mems_type : 'a t;
The uniform type according which unknown members are typed.
*)id : 'mems Type.Id.t;
A type identifier for the unknown member map.
*)dec_empty : unit -> 'builder;
dec_empty
create a new empty member map builder.
dec_add : Meta.t -> string -> 'a -> 'builder -> 'builder;
dec_add
adds a member named n
with metadata meta
and value parsed by mems_type
to the builder.
dec_finish : Meta.t -> 'builder -> 'mems;
dec_finish
turns the builder into an unknown member map. The meta
is the meta data of the object in which they were found.
enc : 'acc. (Meta.t -> string -> 'a -> 'acc -> 'acc) -> 'mems -> 'acc -> 'acc;
enc
folds over the member map for encoding.
}
The type for gathering unknown JSON members uniformly typed according to 'a
in a map 'mems
constructed with 'builder
.
and ('o, 'cases, 'tag) object_cases = {
tag : ('tag, 'tag) mem_map;
The JSON member used to decide cases. The enc
field of this mem_map
should be the identity, this allows encoders to reuse generic encoding code for members. We don't have ('o, 'tag) mem_map
here because the tag is not stored we recover the case via enc
and enc_case
below.
tag_compare : 'tag -> 'tag -> int;
The function to compare tags.
*)tag_to_string : ('tag -> string) option;
The function to stringify tags for error reporting.
*)id : 'cases Type.Id.t;
A type identifier for the tag.
*)cases : ('cases, 'tag) case list;
The list of possible cases.
*)enc : 'o -> 'cases;
enc
is the function to recover case values from the value 'o
the object is mapped to.
enc_case : 'cases -> ('cases, 'tag) case_value;
enc_case
retrieves the concrete case from the common cases
values. You can see it as preforming a match.
}
The type for object cases mapped to a common type 'cases
stored in a vlue of type 'o
and identified by tag values of type 'tag
.
and ('cases, 'case, 'tag) case_map = {
tag : 'tag;
The tag value for the case.
*)object_map : ('case, 'case) object_map;
The object map for the case.
*)dec : 'case -> 'cases;
dec
is the function used on decoding to inject the case into the common 'cases
type.
}
The type for an object case with common type 'cases
specific type 'case
and tag type 'tag
.
and ('cases, 'tag) case_value =
| Case_value : ('cases, 'case, 'tag) case_map
* 'case -> ('cases, 'tag) case_value
The type for case values. This packs a case value and its description.
*)and 'a any_map = {
kind : string;
The kind of JSON values mapped (documentation).
*)doc : string;
Documentation string for the kind of values.
*)dec_null : 'a t option;
dec_null
, if any, is used for decoding JSON nulls.
dec_bool : 'a t option;
dec_bool
, if any, is used for decoding JSON bools.
dec_number : 'a t option;
dec_number
, if any, is used for decoding JSON numbers.
dec_string : 'a t option;
dec_string
, if any, is used for decoding JSON strings.
dec_array : 'a t option;
dec_array
, if any, is used for decoding JSON arrays.
dec_object : 'a t option;
dec_object
, if any, is used for decoding JSON objects.
enc : 'a -> 'a t;
enc
specifies the encoder to use on a given value.
}
The type for mapping JSON values with multiple sorts to a value of type 'a
. If a decoding case is None
, the decoding errors on these JSON values.
and ('a, 'b) map = {
kind : string;
The kind of JSON values mapped (documentation).
*)doc : string;
Documentation string for the kind of values.
*)dom : 'a t;
The domain of the map.
*)dec : 'a -> 'b;
dec
decodes 'a
to 'b
.
enc : 'b -> 'a;
enc
encodes 'b
to 'a
.
}
The type for mapping JSON types of type 'a
to a JSON type of type 'b
.
unsafe_to_t r
converts the representation to a type r
. It is unsafe because constructors of the Jsont
module do maintain some invariants.
val kinded_sort : 'a t -> string
kinded_sort t
is kinded sort of t
, see Jsont.kinded_sort
.
val array_map_kinded_sort : ('a, 'elt, 'builder) array_map -> string
array_map_kinded_sort map
is like kinded_sort
but acts directly on the array map
.
val object_map_kinded_sort : ('o, 'dec) object_map -> string
object_map_kind map
is like kinded_sort
but acts directly on the object map
.
val pp_kind : string fmt
pp_kind
formats kinds.
error_push_array
is like Error.push_array
but uses the given array meta
and array map to caracterize the context.
val error_push_object :
Meta.t ->
('o, 'dec) object_map ->
string node ->
Error.t ->
'a
error_push_object
is like Error.push_object
but uses the given object meta
and object map to caracterize the context.
type_error meta ~exp ~fnd
errors when kind exp
was expected but sort fnd
was found.
val missing_mems_error :
Meta.t ->
('o, 'o) object_map ->
exp:mem_dec String_map.t ->
fnd:string list ->
'a
missing_mems_error m map exp fnd
errors when exp
cannot be found, fnd
can list a few members that were found.
val unexpected_mems_error :
Meta.t ->
('o, 'o) object_map ->
fnd:(string * Meta.t) list ->
'a
unexpected_mems_error meta map ~fnd
errors when fnd
are unexpected members for object map
.
val unexpected_case_tag_error :
Meta.t ->
('o, 'o) object_map ->
('o, 'd, 'tag) object_cases ->
'tag ->
'a
unexpected_case_tag_error meta map cases tag
is when a tag
of a case member has no corresponding case.
object_meta_arg
holds the Jsont.Object.mem
to
module Dict : sig ... end
Heterogeneous dictionaries.
apply_dict dec dict
applies dict
to f
in order to get the value 'f
. Raises Invalid_argument
if dict
has not all the type identifiers that dec
needs.
type unknown_mems_option =
| Unknown_mems : ('o, 'mems, 'builder) unknown_mems option -> unknown_mems_option
val override_unknown_mems :
by:unknown_mems_option ->
unknown_mems_option ->
Dict.t ->
unknown_mems_option * Dict.t
override_unknown_mems ~by current dict
preforms the unknown member overriding logic for Jsont.Object.Case
objects. In particular if current
is a Jsont.Object.Mems.map
it adds an empty one in dict
so that the associated decoding function does not fail.
val finish_object_decode :
('o, 'o) object_map ->
Meta.t ->
('p, 'mems, 'builder) unknown_mems ->
'builder ->
mem_dec String_map.t ->
Dict.t ->
Dict.t
finish_object_decode map meta unknown_mems umap rem_mems dict
finishes an object map map
decode. It adds the umap
(if needed) to dict
, it adds meta
to dict
under object_meta_arg
and tries to find andd default values to dict
for rem_mems
(and errors if it can't).
val pp_code : string fmt
pp_code
formats strings like code (in bold).