Jsont
Types for JSON values.
This module provides a type for describing subsets of JSON values as bidirectional maps with arbitrary OCaml values. We call these values JSON types.
In these maps the decoding direction maps from JSON values to OCaml values and the encoding direction maps from OCaml values to JSON values. Depending on your needs, one direction or the other can be left unspecified. Some of the decoding maps may be lossy or creative which leads to JSON queries and transforms.
Read the quick start and the cookbook.
module Textloc : sig ... end
Text locations.
module Meta : sig ... end
Abstract syntax tree node metadata.
type 'a node = 'a * Meta.t
The type for abstract syntax tree nodes. The node data of type 'a
and its metadata.
module Path : sig ... end
JSON paths.
module Sort : sig ... end
Sorts of JSON values.
module Error : sig ... end
Encoding, decoding and query errors.
exception Error of Error.t
The exception raised on map errors. In general codec and query functions turn that for you into a result
value.
The type for JSON types.
A value of this type represents a subset of JSON values mapped to a subset of values of type 'a
and vice versa.
val kinded_sort : 'a t -> string
kinded_sort t
is a human readable string describing the JSON values typed by t
. This combines the kind of the map with the sort(s) of JSON value mapped by t
. For example if t
is an object map and the kind specified for the map is "T"
then this is "T object"
, if the kind is empty this is simply "object"
. See also Sort.kinded
.
val kind : 'a t -> string
kind t
is the kind
of the underlying map. If the kind is an empty string this falls back to mention the sort. For example if t
is an object map and the kind specified for the map is "T"
then this is "T"
, if the kind is empty then this is "object"
. See also Sort.or_kind
.
val doc : 'a t -> string
doc t
is a documentation string for the JSON values typed by t
.
Read the cookbook on base types.
module Base : sig ... end
Mapping JSON base types.
Read the cookbook on null
s.
val null : ?kind:string -> ?doc:string -> 'a -> 'a t
val none : 'a option t
none
maps JSON nulls to None
.
some t
maps JSON like t
does but wraps results in Some
. Encoding fails if the value is None
.
option t
maps JSON nulls to None
and other values by t
. doc
and kind
are given to the underlying any
map.
Read the cookbook on JSON numbers and their many pitfalls.
val number : float t
number
maps JSON nulls or numbers to float
values. On decodes JSON null is mapped to Float.nan
. On encodes any non-finite float is lossily mapped to JSON null (explanation). See also Base.number
, any_float
and the integer combinators below.
val any_float : float t
any_float
is a lossless representation for IEEE 754 doubles. It maps non-finite floats by the JSON strings defined by Float.to_string
. This contrasts with number
which maps them to JSON null values (explanation). Note that on decodes this still maps JSON nulls to Float.nan
and any successful string decode of Float.of_string_opt
(so numbers can also be written as strings). See also number
.
Warning. any_float
should only be used between parties that have agreed on such an encoding. To maximize interoperability you should use the lossy number
map.
val float_as_hex_string : float t
float_as_hex_string
maps JSON strings made of IEEE 754 doubles in hex notation to float values. On encodes strings this uses the "%h"
format string. On decodes it accepts anything sucessfully decoded by Float.of_string_opt
.
val uint8 : int t
uint8
maps JSON numbers to unsigned 8-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [0;255] range. Encoding errors if the integer is out of range.
val uint16 : int t
uint16
maps JSON numbers to unsigned 16-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [0;65535] range. Encoding errors if the integer is out of range.
val int8 : int t
int8
maps JSON numbers to 8-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [-128;127] range. Encoding errors if the integer is out of range.
val int16 : int t
int16
maps JSON numbers to 16-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the [-32768;32767] range. Encoding errors if the integer is out of range.
val int32 : int32 t
int32
maps JSON numbers to 32-bit integers. JSON numbers are sucessfully decoded if after truncation they can be represented on the int32
range, otherwise the decoder errors.
val int64 : int64 t
int
maps truncated JSON numbers or JSON strings to 64-bit integers.
int64
range, otherwise the decoder errors. int64
values are encoded as JSON numbers if the integer is in the [-253;253] range.int_of_string_opt
, this allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. int
values are encoded as JSON strings with Int.to_string
when the integer is outside the [-253;253] rangeval int64_as_string : int64 t
int64_as_string
maps JSON strings to 64-bit integers. On decodes this uses Int64.of_string_opt
which allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. On encodes uses Int64.to_string
.
val int : int t
int
maps truncated JSON numbers or JSON strings to int
values.
int
range, otherwise the decoder errors. int
values are encoded as JSON numbers if the integer is in the [-253;253] range.int_of_string_opt
, this allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. int
values are encoded as JSON strings with Int.to_string
when the integer is outside the [-253;253] rangeWarning. The behaviour of this function is platform dependent, it depends on the value of Sys.int_size
.
val int_as_string : int t
int_as_string
maps JSON strings to int
values. On decodes this uses int_of_string_opt
which allows binary, octal, decimal and hex syntaxes and errors on overflow and syntax errors. On encodes uses Int.to_string
.
Warning. The behaviour of this function is platform dependent, it depends on the value of Sys.int_size
.
Read the cookbook on transforming strings.
val string : string t
string
maps unescaped JSON strings to UTF-8 encoded string
values. See also Base.string
.
Warning. Encoders assume OCaml string
s have been checked for UTF-8 validity.
val of_of_string :
?kind:string ->
?doc:string ->
?enc:('a -> string) ->
(string -> ('a, string) Stdlib.result) ->
'a t
val enum :
?cmp:('a -> 'a -> int) ->
?kind:string ->
?doc:string ->
(string * 'a) list ->
'a t
enum assoc
maps JSON strings member of the assoc
list to the corresponding OCaml value and vice versa in log(n). cmp
is used to compare the OCaml values, it defaults to Stdlib.compare
. Decoding and encoding errors on strings or values not part of assoc
val binary_string : string t
binary_string
maps JSON strings made of an even number of hexdecimal US-ASCII upper or lower case digits to the corresponding byte sequence. On encoding uses only lower case hexadecimal digits to encode the byte sequence.
Read the cookbok on arrays and see also array queries and updates.
module Array : sig ... end
Mapping JSON arrays.
list t
maps JSON arrays of type t
to list
values. See also Array.list_map
.
array t
maps JSON arrays of type t
to array
values. See also Array.array_map
.
val array_as_string_map :
?kind:string ->
?doc:string ->
key:('a -> string) ->
'a t ->
'a Stdlib.Map.Make(Stdlib.String).t t
array_as_string_map ~key t
maps JSON array elements of type t
to string maps by indexing them with key
. If two elements have the same key
the element with the greatest index takes over. Elements of the map are encoded to a JSON array in (binary) key order.
val bigarray :
?kind:string ->
?doc:string ->
('a, 'b) Stdlib.Bigarray.kind ->
'a t ->
('a, 'b, Stdlib.Bigarray.c_layout) Stdlib.Bigarray.Array1.t t
bigarray k t
maps JSON arrays of type t
to Bigarray.Array1.t
values. See also Array.bigarray_map
.
val t2 :
?kind:string ->
?doc:string ->
?dec:('a -> 'a -> 't2) ->
?enc:('t2 -> int -> 'a) ->
'a t ->
't2 t
t2 ?dec ?enc t
maps JSON arrays with exactly 2 elements of type t
to value of type 't2
. Decodes error if there are more elements. enc v i
must return the zero-based i
th element.
val t3 :
?kind:string ->
?doc:string ->
?dec:('a -> 'a -> 'a -> 't3) ->
?enc:('t3 -> int -> 'a) ->
'a t ->
't3 t
t3
is like t2
but for 3 elements.
val t4 :
?kind:string ->
?doc:string ->
?dec:('a -> 'a -> 'a -> 'a -> 't4) ->
?enc:('t4 -> int -> 'a) ->
'a t ->
't4 t
t4
is like t2
but for 4 elements.
tn ~n t
maps JSON arrays of exactly n
elements of type t
to array
values. This is array
limited by n
.
Read the cookbook on objects. See a simple example. See also object queries and updates.
module Object : sig ... end
Mapping JSON objects.
val any :
?kind:string ->
?doc:string ->
?dec_null:'a t ->
?dec_bool:'a t ->
?dec_number:'a t ->
?dec_string:'a t ->
?dec_array:'a t ->
?dec_object:'a t ->
?enc:('a -> 'a t) ->
unit ->
'a t
any ()
maps subsets of JSON value of different sorts to values of type 'a
. The unspecified cases are not part of the subset and error on decoding. enc
selects the type to use on encoding and errors if omitted. kind
names the entities represented by the type and doc
documents them, both defaults to ""
.
map t
changes the type of t
from 'a
to 'b
.
kind
names the entities represented by the type and doc
documents them, both default to ""
.dec
decodes values of type 'a
to values of type 'b
. Can be omitted if the result is only used for encoding. The default errors.enc
encodes values of type 'b
to values of type 'a
. Can be omitted if the result is only used for decoding. The default errors.iter ?enc dec t
applies dec
on decoding and enc
on encoding but otherwise behaves like t
does. Typically dec
can be used to further assert the shape of the decoded value and Error.msgf
if it hasn't the right shape. iter
can also be used as a tracing facility for debugging.
val ignore : unit t
ignore
lossily maps all JSON values to ()
on decoding and errors on encoding. See also const
.
val zero : unit t
zero
lossily maps all JSON values to ()
on decoding and encodes JSON nulls.
val todo : ?kind:string -> ?doc:string -> ?dec_stub:'a -> unit -> 'a t
todo ?dec_stub ()
maps all JSON values to dec_stub
if specified (errors otherwise) and errors on encoding.
type name = string node
The type for JSON member names.
and object' = mem list
The type for generic JSON objects.
module Json : sig ... end
Generic JSON values.
json_number
maps JSON nulls or numbers (explanation) to their generic representation.
val json_mems : (json, json, mem list) Object.Mems.map
json_mems
is a members map collecting unknown members into a generic JSON object. See this example.
Queries are lossy or aggregating decodes. Updates decode to json
values but transform the data along the way. They allow to process JSON data without having to fully model it (see the update example in the quick start).
const t v
maps any JSON value to v
on decodes and unconditionally encodes v
with t
.
recode ~dec f ~enc
maps on decodes like dec
does followed by f
and on encodes uses enc
. This can be used to change the JSON sort of value. For example:
recode ~dec:int (fun _ i -> string_of_int s) ~enc:string
decodes an integer but encodes the integer as a string.
update t
decodes any JSON with t
and directly encodes it back with t
to yield the decode result. Encodes any JSON like json
does.
nth n t
decodes the n
th index of a JSON array with t
. Other indices are skipped. The decode errors if there is no such index unless absent
is specified in which case this value is returned. Encodes a singleton array.
set_nth t n v
on decodes sets the n
th value of a JSON array to v
encoded by t
. Other indices are left untouched. Errors if there is no such index unless ~allow_absent:true
is specified in which case the index is created preceeded by as many stub
indices as needed. stub
defaults to Json.zero
applied to the value v
encoded by t
(i.e. the "natural zero" of v
's encoding sort). Encodes like json_array
does.
update_nth n t
on decode recodes the n
th value of a JSON array with t
. Errors if there is no such index unless absent
is specified in which case the index is created with absent
, encoded with t
and preceeded by as many stub
values as needed. stub
defaults to Json.zero
applied to the recode. Encodes like json_array
does.
delete_nth n
drops the n
th index of a JSON array on both decode and encodes. Other indices are left untouched. Errors if there is no such index unless ~allow_absent:true
is specified in which case the data is left untouched.
filter_map_array a b f
maps the a
elements of a JSON array with f
to b
elements or deletes them on None
. Encodes generic JSON arrays like json_array
does.
fold_array t f acc
fold f
over the t
elements of a JSON array starting with acc
. Encodes an empty JSON array.
mem name t
decodes the member named name
of a JSON object with t
. Other members are skipped. The decode errors if there is no such member unless absent
is specified in which case this value is returned. Encodes an object with a single name
member.
set_mem t name v
sets the member value of name
of a JSON
object to an encoding of v
with t
. This happens both on decodes and encodes. Errors if there is no such member unless allow_absent:true
is specified in which case a member is added to the object.
update_mem name t
recodes the member value of name
of a JSON object with t
. This happens both on decodes and encodes. Errors if there is no such member unless absent
is specified in which case a member with this value encoded with t
is added to the object.
delete_mem name
deletes the member named name
of a JSON object on decode. Other members are left untouched. The decode errors if there is no such member unless ~allow_absent:true
is specified in which case the data is left untouched. Encodes generic JSON objects like json_object
does.
filter_map_object a b f
maps the a
members of a JSON object with f
to (n, b)
members or deletes them on None
. The meta given to f
is the meta of the member name. Encodes generic JSON arrays like json_object
does.
fold_object t f acc
folds f
over the t
members of a JSON object starting with acc
. Encodes an empty JSON object.
val index : ?absent:'a -> Path.index -> 'a t -> 'a t
val set_index : ?allow_absent:bool -> 'a t -> Path.index -> 'a -> json t
val update_index : ?stub:json -> ?absent:'a -> Path.index -> 'a t -> json t
update_index
uses update_nth
or update_mem
on the given index.
val delete_index : ?allow_absent:bool -> Path.index -> json t
delete_index
uses delete_nth
or delete_mem
on the given index.
update_path p t
updates the last index of p
with t
. On the root path this is t
.
The type for specifying JSON encoding formatting. See for example Jsont_bytesrw.encode
.
The type for JSON number formatters.
val default_number_format : number_format
default_number_format
is "%.17g"
. This number formats ensures that finite floating point values can be interchanged without loss of precision.
val pp_null : unit fmt
pp_null
formats a JSON null.
val pp_bool : bool fmt
pp_bool
formats a JSON bool.
val pp_number : float fmt
pp_number
formats a JSON number of a JSON null if the float is not finite. Uses the default_number_format
.
val pp_number' : number_format -> float fmt
pp_number fmt
is like pp_number
but uses fmt
to format the number.
val pp_string : string fmt
pp_string
formats a JSON string (quoted and escaped). Assumes the string is valid UTF-8.
val pp_json' : ?number_format:number_format -> unit -> json fmt
pp' ~format ~number_format () ppf j
formats j
on ppf
. The output is indented but may be more compact than an Indent
JSON encoder may do. For example arrays may be output on one line if they fit etc.
number_format
is used to format JSON numbers. Defaults to default_number_format
val pp_value : ?number_format:number_format -> 'a t -> unit -> 'a fmt
pp_value t ()
formats the JSON representation of values as described by t
by encoding it with Json.encode
and formatting it with pp_json'
. If the encoding of the value errors a JSON string with the error message is formatted. This means that pp_value
should always format valid JSON text.
module Repr : sig ... end
Low level representation (unstable).