Data_encoding: deduplicate documentation
This commit is contained in:
parent
194d3f9120
commit
0a3c9d52ec
@ -7,46 +7,21 @@
|
|||||||
(* *)
|
(* *)
|
||||||
(**************************************************************************)
|
(**************************************************************************)
|
||||||
|
|
||||||
|
(** This is for use *within* the data encoding library only. Instead, you should
|
||||||
|
use the corresponding module intended for use: {Data_encoding.Binary}. *)
|
||||||
|
|
||||||
val length : 'a Encoding.t -> 'a -> int
|
val length : 'a Encoding.t -> 'a -> int
|
||||||
val read : 'a Encoding.t -> MBytes.t -> int -> int -> (int * 'a) option
|
val read : 'a Encoding.t -> MBytes.t -> int -> int -> (int * 'a) option
|
||||||
val write : 'a Encoding.t -> 'a -> MBytes.t -> int -> int option
|
val write : 'a Encoding.t -> 'a -> MBytes.t -> int -> int option
|
||||||
val to_bytes : 'a Encoding.t -> 'a -> MBytes.t
|
val to_bytes : 'a Encoding.t -> 'a -> MBytes.t
|
||||||
val of_bytes : 'a Encoding.t -> MBytes.t -> 'a option
|
val of_bytes : 'a Encoding.t -> MBytes.t -> 'a option
|
||||||
val of_bytes_exn : 'a Encoding.t -> MBytes.t -> 'a
|
val of_bytes_exn : 'a Encoding.t -> MBytes.t -> 'a
|
||||||
|
|
||||||
(** [to_bytes_list ?copy_blocks blocks_size encod data] encode the
|
|
||||||
given data as a list of successive blocks of length
|
|
||||||
'blocks_size' at most.
|
|
||||||
|
|
||||||
NB. If 'copy_blocks' is false (default), the blocks of the list
|
|
||||||
can be garbage-collected only when all the blocks are
|
|
||||||
unreachable (because of the 'optimized' implementation of
|
|
||||||
MBytes.sub used internally *)
|
|
||||||
val to_bytes_list : ?copy_blocks:bool -> int -> 'a Encoding.t -> 'a -> MBytes.t list
|
val to_bytes_list : ?copy_blocks:bool -> int -> 'a Encoding.t -> 'a -> MBytes.t list
|
||||||
|
|
||||||
(** This type is used when decoding binary data incrementally.
|
|
||||||
- In case of 'Success', the decoded data, the size of used data
|
|
||||||
to decode the result, and the remaining data are returned
|
|
||||||
- In case of error, 'Error' is returned
|
|
||||||
- 'Await' status embeds a function that waits for additional data
|
|
||||||
to continue decoding, when given data are not sufficient *)
|
|
||||||
type 'a status =
|
type 'a status =
|
||||||
| Success of { res : 'a ; res_len : int ; remaining : MBytes.t list }
|
| Success of { res : 'a ; res_len : int ; remaining : MBytes.t list }
|
||||||
| Await of (MBytes.t -> 'a status)
|
| Await of (MBytes.t -> 'a status)
|
||||||
| Error
|
| Error
|
||||||
|
|
||||||
(** This function allows to decode (or to initialize decoding) a
|
|
||||||
stream of 'MByte.t'. The given data encoding should have a
|
|
||||||
'Fixed' or a 'Dynamic' size, otherwise an exception
|
|
||||||
'Invalid_argument "streaming data with variable size"' is
|
|
||||||
raised *)
|
|
||||||
val read_stream_of_bytes : ?init:MBytes.t list -> 'a Encoding.t -> 'a status
|
val read_stream_of_bytes : ?init:MBytes.t list -> 'a Encoding.t -> 'a status
|
||||||
|
|
||||||
(** Like read_stream_of_bytes, but only checks that the stream can
|
|
||||||
be read. Note that this is an approximation because failures
|
|
||||||
that may come from conversion functions present in encodings are
|
|
||||||
not checked *)
|
|
||||||
val check_stream_of_bytes : ?init:MBytes.t list -> 'a Encoding.t -> unit status
|
val check_stream_of_bytes : ?init:MBytes.t list -> 'a Encoding.t -> unit status
|
||||||
|
|
||||||
val fixed_length : 'a Encoding.t -> int option
|
val fixed_length : 'a Encoding.t -> int option
|
||||||
val fixed_length_exn : 'a Encoding.t -> int
|
val fixed_length_exn : 'a Encoding.t -> int
|
||||||
|
@ -7,12 +7,10 @@
|
|||||||
(* *)
|
(* *)
|
||||||
(**************************************************************************)
|
(**************************************************************************)
|
||||||
|
|
||||||
|
(** This is for use *within* the data encoding library only. Instead, you should
|
||||||
|
use the corresponding module intended for use: {Data_encoding.Bson}. *)
|
||||||
|
|
||||||
type bson = Json_repr_bson.bson
|
type bson = Json_repr_bson.bson
|
||||||
type t = bson
|
type t = bson
|
||||||
|
|
||||||
(** Construct a BSON object from an encoding. *)
|
|
||||||
val construct : 't Encoding.t -> 't -> bson
|
val construct : 't Encoding.t -> 't -> bson
|
||||||
|
|
||||||
(** Destruct a BSON object into a value.
|
|
||||||
Fail with an exception if the JSON object and encoding do not match.. *)
|
|
||||||
val destruct : 't Encoding.t -> bson -> 't
|
val destruct : 't Encoding.t -> bson -> 't
|
||||||
|
@ -7,63 +7,16 @@
|
|||||||
(* *)
|
(* *)
|
||||||
(**************************************************************************)
|
(**************************************************************************)
|
||||||
|
|
||||||
(** Type-safe serialization and deserialization of data structures. *)
|
(** This is for use *within* the data encoding library only. Instead, you should
|
||||||
|
use the corresponding module intended for use: {Data_encoding.Encoding}. *)
|
||||||
(** {1 Data Encoding} *)
|
|
||||||
|
|
||||||
(** This module provides type-safe serialization and deserialization of
|
|
||||||
data structures. Backends are provided to both binary and JSON.
|
|
||||||
|
|
||||||
This works by writing type descriptors by hand, using the provided
|
|
||||||
combinators. These combinators can fine-tune the binary
|
|
||||||
representation to be compact and efficient, but also provide
|
|
||||||
proper field names and meta information, so the API of Tezos can
|
|
||||||
be automatically introspected and documented.
|
|
||||||
|
|
||||||
Here is an example encoding for type [(int * string)].
|
|
||||||
|
|
||||||
[let enc = obj2 (req "code" uint16) (req "message" string)]
|
|
||||||
|
|
||||||
In JSON, this encoding maps values of type [int * string] to JSON
|
|
||||||
objects with a field [code] whose value is a number and a field
|
|
||||||
[message] whose value is a string.
|
|
||||||
|
|
||||||
In binary, this encoding maps to two raw bytes for the [int]
|
|
||||||
followed by the size of the string in bytes, and finally the raw
|
|
||||||
contents of the string. This binary format is mostly tagless,
|
|
||||||
meaning that serialized data cannot be interpreted without the
|
|
||||||
encoding that was used for serialization.
|
|
||||||
|
|
||||||
Regarding binary serialization, encodings are classified as either:
|
|
||||||
- fixed size (booleans, integers, numbers)
|
|
||||||
data is always the same size for that type ;
|
|
||||||
- dynamically sized (arbitrary strings and bytes)
|
|
||||||
data is of unknown size and requires an explicit length field ;
|
|
||||||
- variable size (special case of strings, bytes, and arrays)
|
|
||||||
data makes up the remainder of an object of known size,
|
|
||||||
thus its size is given by the context, and does not
|
|
||||||
have to be serialized.
|
|
||||||
|
|
||||||
JSON operations are delegated to [ocplib-json-typed]. *)
|
|
||||||
|
|
||||||
(* TODO: reorder all the functions so it makes sense (ground, combinator,
|
|
||||||
* predicates, etc.) *)
|
|
||||||
(* TODO: move the doc into the packing module *)
|
|
||||||
|
|
||||||
module Kind: sig
|
module Kind: sig
|
||||||
|
|
||||||
type t = [ `Fixed of int | `Dynamic | `Variable ]
|
type t = [ `Fixed of int | `Dynamic | `Variable ]
|
||||||
|
|
||||||
type length = [ `Fixed of int | `Variable ]
|
type length = [ `Fixed of int | `Variable ]
|
||||||
|
|
||||||
type enum = [ `Dynamic | `Variable ]
|
type enum = [ `Dynamic | `Variable ]
|
||||||
|
|
||||||
val combine: string -> t -> t -> t
|
val combine: string -> t -> t -> t
|
||||||
|
|
||||||
val merge : t -> t -> t
|
val merge : t -> t -> t
|
||||||
|
|
||||||
val merge_list: Size.tag_size -> t list -> t
|
val merge_list: Size.tag_size -> t list -> t
|
||||||
|
|
||||||
end
|
end
|
||||||
|
|
||||||
type case_tag = Tag of int | Json_only
|
type case_tag = Tag of int | Json_only
|
||||||
@ -145,167 +98,53 @@ exception Int_out_of_range of int * int * int
|
|||||||
exception Invalid_size of int
|
exception Invalid_size of int
|
||||||
|
|
||||||
|
|
||||||
(** Special value [null] in JSON, nothing in binary. *)
|
|
||||||
val null : unit encoding
|
val null : unit encoding
|
||||||
|
|
||||||
(** Empty object (not included in binary, encoded as empty object in JSON). *)
|
|
||||||
val empty : unit encoding
|
val empty : unit encoding
|
||||||
|
|
||||||
(** Unit value, ommitted in binary.
|
|
||||||
Serialized as an empty object in JSON, accepts any object when deserializing. *)
|
|
||||||
val unit : unit encoding
|
val unit : unit encoding
|
||||||
|
|
||||||
(** Constant string (data is not included in the binary data). *)
|
|
||||||
val constant : string -> unit encoding
|
val constant : string -> unit encoding
|
||||||
|
|
||||||
(** Signed 8 bit integer
|
|
||||||
(data is encoded as a byte in binary and an integer in JSON). *)
|
|
||||||
val int8 : int encoding
|
val int8 : int encoding
|
||||||
|
|
||||||
(** Unsigned 8 bit integer
|
|
||||||
(data is encoded as a byte in binary and an integer in JSON). *)
|
|
||||||
val uint8 : int encoding
|
val uint8 : int encoding
|
||||||
|
|
||||||
(** Signed 16 bit integer
|
|
||||||
(data is encoded as a short in binary and an integer in JSON). *)
|
|
||||||
val int16 : int encoding
|
val int16 : int encoding
|
||||||
|
|
||||||
(** Unsigned 16 bit integer
|
|
||||||
(data is encoded as a short in binary and an integer in JSON). *)
|
|
||||||
val uint16 : int encoding
|
val uint16 : int encoding
|
||||||
|
|
||||||
(** Signed 31 bit integer, which corresponds to type int on 32-bit OCaml systems
|
|
||||||
(data is encoded as a 32 bit int in binary and an integer in JSON). *)
|
|
||||||
val int31 : int encoding
|
val int31 : int encoding
|
||||||
|
|
||||||
(** Signed 32 bit integer
|
|
||||||
(data is encoded as a 32-bit int in binary and an integer in JSON). *)
|
|
||||||
val int32 : int32 encoding
|
val int32 : int32 encoding
|
||||||
|
|
||||||
(** Signed 64 bit integer
|
|
||||||
(data is encodedas a 64-bit int in binary and a decimal string in JSON). *)
|
|
||||||
val int64 : int64 encoding
|
val int64 : int64 encoding
|
||||||
|
|
||||||
(** Integer with bounds in a given range. Both bounds are inclusive.
|
|
||||||
|
|
||||||
Raises [Invalid_argument] if the bounds are beyond the interval
|
|
||||||
[-2^30; 2^30-1]. These bounds are chosen to be compatible with all versions
|
|
||||||
of OCaml.
|
|
||||||
*)
|
|
||||||
val ranged_int : int -> int -> int encoding
|
val ranged_int : int -> int -> int encoding
|
||||||
|
|
||||||
(** Float with bounds in a given range. Both bounds are inclusive *)
|
|
||||||
val ranged_float : float -> float -> float encoding
|
val ranged_float : float -> float -> float encoding
|
||||||
|
|
||||||
(** Encoding of a boolean
|
|
||||||
(data is encoded as a byte in binary and a boolean in JSON). *)
|
|
||||||
val bool : bool encoding
|
val bool : bool encoding
|
||||||
|
|
||||||
(** Encoding of a string
|
|
||||||
- default variable in width
|
|
||||||
- encoded as a byte sequence in binary
|
|
||||||
- encoded as a string in JSON. *)
|
|
||||||
val string : string encoding
|
val string : string encoding
|
||||||
|
|
||||||
(** Encoding of arbitrary bytes
|
|
||||||
(encoded via hex in JSON and directly as a sequence byte in binary). *)
|
|
||||||
val bytes : MBytes.t encoding
|
val bytes : MBytes.t encoding
|
||||||
|
|
||||||
(** Encoding of floating point number
|
|
||||||
(encoded as a floating point number in JSON and a double in binary). *)
|
|
||||||
val float : float encoding
|
val float : float encoding
|
||||||
|
|
||||||
(** Combinator to make an optional value
|
|
||||||
(represented as a 1-byte tag followed by the data (or nothing) in binary
|
|
||||||
and either the raw value or an empty object in JSON). *)
|
|
||||||
val option : 'a encoding -> 'a option encoding
|
val option : 'a encoding -> 'a option encoding
|
||||||
|
|
||||||
(** Combinator to make a {!result} value
|
|
||||||
(represented as a 1-byte tag followed by the data of either type in binary,
|
|
||||||
and either unwrapped value in JSON (the caller must ensure that both
|
|
||||||
encodings do not collide)). *)
|
|
||||||
val result : 'a encoding -> 'b encoding -> ('a, 'b) result encoding
|
val result : 'a encoding -> 'b encoding -> ('a, 'b) result encoding
|
||||||
|
|
||||||
(** Encode enumeration via association list
|
|
||||||
(represented as a string in JSON and binary). *)
|
|
||||||
val string_enum : (string * 'a) list -> 'a encoding
|
val string_enum : (string * 'a) list -> 'a encoding
|
||||||
|
|
||||||
|
|
||||||
(** Is the given encoding serialized as a JSON object? *)
|
|
||||||
val is_obj : 'a encoding -> bool
|
val is_obj : 'a encoding -> bool
|
||||||
|
|
||||||
(** Does the given encoding encode a tuple? *)
|
|
||||||
val is_tup : 'a encoding -> bool
|
val is_tup : 'a encoding -> bool
|
||||||
|
|
||||||
(** Create encodings that produce data of a fixed length when binary encoded.
|
|
||||||
See the preamble for an explanation. *)
|
|
||||||
module Fixed : sig
|
module Fixed : sig
|
||||||
|
|
||||||
(** Encode a fixed length string *)
|
|
||||||
val string : int -> string encoding
|
val string : int -> string encoding
|
||||||
|
|
||||||
(** Encode a fixed length byte sequence *)
|
|
||||||
val bytes : int -> MBytes.t encoding
|
val bytes : int -> MBytes.t encoding
|
||||||
end
|
end
|
||||||
|
|
||||||
(** Create encodings that produce data of a variable length when binary encoded.
|
|
||||||
See the preamble for an explanation. *)
|
|
||||||
module Variable : sig
|
module Variable : sig
|
||||||
(** Encode a string *)
|
|
||||||
val string : string encoding
|
val string : string encoding
|
||||||
|
|
||||||
(** Encode a byte sequence *)
|
|
||||||
val bytes : MBytes.t encoding
|
val bytes : MBytes.t encoding
|
||||||
|
|
||||||
(** Array encoding combinator *)
|
|
||||||
val array : 'a encoding -> 'a array encoding
|
val array : 'a encoding -> 'a array encoding
|
||||||
|
|
||||||
(** List encoding combinator *)
|
|
||||||
val list : 'a encoding -> 'a list encoding
|
val list : 'a encoding -> 'a list encoding
|
||||||
end
|
end
|
||||||
|
|
||||||
(** Mark an encoding as being of dynamic size.
|
|
||||||
Forces the size to be stored alongside content when needed.
|
|
||||||
Usually used to fix errors from combining two encodings. *)
|
|
||||||
val dynamic_size : 'a encoding -> 'a encoding
|
val dynamic_size : 'a encoding -> 'a encoding
|
||||||
|
|
||||||
(** Recompute the encoding definition each time it is used.
|
|
||||||
Useful for dynamically updating the encoding of values of an extensible
|
|
||||||
type via a global reference (e.g. exceptions). *)
|
|
||||||
val delayed : (unit -> 'a encoding) -> 'a encoding
|
val delayed : (unit -> 'a encoding) -> 'a encoding
|
||||||
|
|
||||||
(** Required field. *)
|
|
||||||
val req :
|
val req :
|
||||||
?title:string -> ?description:string ->
|
?title:string -> ?description:string ->
|
||||||
string -> 't encoding -> 't field
|
string -> 't encoding -> 't field
|
||||||
|
|
||||||
(** Optional field. Omitted entirely in JSON encoding if None.
|
|
||||||
Omitted in binary if the only optional field in a [`Variable]
|
|
||||||
encoding, otherwise a 1-byte prefix (`0` or `1`) tells if the
|
|
||||||
field is present or not. *)
|
|
||||||
val opt :
|
val opt :
|
||||||
?title:string -> ?description:string ->
|
?title:string -> ?description:string ->
|
||||||
string -> 't encoding -> 't option field
|
string -> 't encoding -> 't option field
|
||||||
|
|
||||||
(** Optional field of variable length.
|
|
||||||
Only one can be present in a given object. *)
|
|
||||||
val varopt :
|
val varopt :
|
||||||
?title:string -> ?description:string ->
|
?title:string -> ?description:string ->
|
||||||
string -> 't encoding -> 't option field
|
string -> 't encoding -> 't option field
|
||||||
|
|
||||||
(** Required field with a default value.
|
|
||||||
If the default value is passed, the field is omitted in JSON.
|
|
||||||
The value is always serialized in binary. *)
|
|
||||||
val dft :
|
val dft :
|
||||||
?title:string -> ?description:string ->
|
?title:string -> ?description:string ->
|
||||||
string -> 't encoding -> 't -> 't field
|
string -> 't encoding -> 't -> 't field
|
||||||
|
|
||||||
(** {2 Constructors for objects with N fields} *)
|
|
||||||
|
|
||||||
(** These are serialized to binary by converting each internal object to binary
|
|
||||||
and placing them in the order of the original object.
|
|
||||||
These are serialized to JSON as a JSON object with the field names. *)
|
|
||||||
|
|
||||||
val obj1 :
|
val obj1 :
|
||||||
'f1 field -> 'f1 encoding
|
'f1 field -> 'f1 encoding
|
||||||
val obj2 :
|
val obj2 :
|
||||||
@ -339,12 +178,6 @@ val obj10 :
|
|||||||
'f6 field -> 'f7 field -> 'f8 field -> 'f9 field -> 'f10 field ->
|
'f6 field -> 'f7 field -> 'f8 field -> 'f9 field -> 'f10 field ->
|
||||||
('f1 * 'f2 * 'f3 * 'f4 * 'f5 * 'f6 * 'f7 * 'f8 * 'f9 * 'f10) encoding
|
('f1 * 'f2 * 'f3 * 'f4 * 'f5 * 'f6 * 'f7 * 'f8 * 'f9 * 'f10) encoding
|
||||||
|
|
||||||
(** {2 Constructors for tuples with N fields} *)
|
|
||||||
|
|
||||||
(** These are serialized to binary by converting each internal object to binary
|
|
||||||
and placing them in the order of the original object.
|
|
||||||
These are serialized to JSON as JSON arrays/lists. *)
|
|
||||||
|
|
||||||
val tup1 :
|
val tup1 :
|
||||||
'f1 encoding ->
|
'f1 encoding ->
|
||||||
'f1 encoding
|
'f1 encoding
|
||||||
@ -384,77 +217,28 @@ val tup10 :
|
|||||||
'f9 encoding -> 'f10 encoding ->
|
'f9 encoding -> 'f10 encoding ->
|
||||||
('f1 * 'f2 * 'f3 * 'f4 * 'f5 * 'f6 * 'f7 * 'f8 * 'f9 * 'f10) encoding
|
('f1 * 'f2 * 'f3 * 'f4 * 'f5 * 'f6 * 'f7 * 'f8 * 'f9 * 'f10) encoding
|
||||||
|
|
||||||
(** {2 Combinators} *)
|
|
||||||
|
|
||||||
(** Create a larger object from the encodings of two smaller ones.
|
|
||||||
@raise invalid_arg if both arguments are not objects. *)
|
|
||||||
val merge_objs : 'o1 encoding -> 'o2 encoding -> ('o1 * 'o2) encoding
|
val merge_objs : 'o1 encoding -> 'o2 encoding -> ('o1 * 'o2) encoding
|
||||||
|
|
||||||
(** Create a large tuple encoding from two smaller ones.
|
|
||||||
@raise invalid_arg if both values are not tuples. *)
|
|
||||||
val merge_tups : 'a1 encoding -> 'a2 encoding -> ('a1 * 'a2) encoding
|
val merge_tups : 'a1 encoding -> 'a2 encoding -> ('a1 * 'a2) encoding
|
||||||
|
|
||||||
(** Array combinator. *)
|
|
||||||
val array : 'a encoding -> 'a array encoding
|
val array : 'a encoding -> 'a array encoding
|
||||||
|
|
||||||
(** List combinator. *)
|
|
||||||
val list : 'a encoding -> 'a list encoding
|
val list : 'a encoding -> 'a list encoding
|
||||||
|
|
||||||
(** Encodes a variant constructor. Takes the encoding for the specific
|
|
||||||
parameters, a recognizer function that will extract the parameters
|
|
||||||
in case the expected case of the variant is being serialized, and
|
|
||||||
a constructor function for deserialization.
|
|
||||||
|
|
||||||
The tag must be less than the tag size of the union in which you use the case.
|
|
||||||
An optional tag gives a name to a case and should be used to maintain
|
|
||||||
compatibility.
|
|
||||||
|
|
||||||
An optional name for the case can be provided,
|
|
||||||
which is used in the binary documentation. *)
|
|
||||||
val case :
|
val case :
|
||||||
?name:string ->
|
?name:string ->
|
||||||
case_tag ->
|
case_tag ->
|
||||||
'a encoding -> ('t -> 'a option) -> ('a -> 't) -> 't case
|
'a encoding -> ('t -> 'a option) -> ('a -> 't) -> 't case
|
||||||
|
|
||||||
(** Create a single encoding from a series of cases.
|
|
||||||
|
|
||||||
In JSON, all cases are tried one after the other. The caller must
|
|
||||||
check for collisions.
|
|
||||||
|
|
||||||
In binary, a prefix tag is added to discriminate quickly between
|
|
||||||
cases. The default is `Uint8 and you must use a `Uint16 if you are
|
|
||||||
going to have more than 256 cases.
|
|
||||||
|
|
||||||
This function will raise an exception if it is given the empty list
|
|
||||||
or if there are more cases than can fit in the tag size. *)
|
|
||||||
val union :
|
val union :
|
||||||
?tag_size:[ `Uint8 | `Uint16 ] -> 't case list -> 't encoding
|
?tag_size:[ `Uint8 | `Uint16 ] -> 't case list -> 't encoding
|
||||||
|
|
||||||
(** Add documentation to an encoding. *)
|
|
||||||
val describe :
|
val describe :
|
||||||
?title:string -> ?description:string ->
|
?title:string -> ?description:string ->
|
||||||
't encoding ->'t encoding
|
't encoding ->'t encoding
|
||||||
|
|
||||||
(** Give a name to an encoding. *)
|
|
||||||
val def : string -> 'a encoding -> 'a encoding
|
val def : string -> 'a encoding -> 'a encoding
|
||||||
|
|
||||||
(** Provide a transformer from one encoding to a different one.
|
|
||||||
|
|
||||||
Used to simplify nested encodings or to change the generic tuples
|
|
||||||
built by {obj1}, {tup1} and the like into proper records.
|
|
||||||
|
|
||||||
A schema may optionally be provided as documentation of the new encoding. *)
|
|
||||||
val conv :
|
val conv :
|
||||||
('a -> 'b) -> ('b -> 'a) ->
|
('a -> 'b) -> ('b -> 'a) ->
|
||||||
?schema:Json_schema.schema ->
|
?schema:Json_schema.schema ->
|
||||||
'b encoding -> 'a encoding
|
'b encoding -> 'a encoding
|
||||||
|
|
||||||
(** Combinator for recursive encodings. *)
|
|
||||||
val mu : string -> ('a encoding -> 'a encoding) -> 'a encoding
|
val mu : string -> ('a encoding -> 'a encoding) -> 'a encoding
|
||||||
|
|
||||||
(** Classify an encoding wrt. its binary serialization as explained in the preamble. *)
|
|
||||||
val classify : 'a encoding -> [ `Fixed of int | `Dynamic | `Variable ]
|
val classify : 'a encoding -> [ `Fixed of int | `Dynamic | `Variable ]
|
||||||
|
|
||||||
(** Define different encodings for JSON and binary serialization. *)
|
|
||||||
val raw_splitted : json:'a Json_encoding.encoding -> binary:'a encoding -> 'a encoding
|
val raw_splitted : json:'a Json_encoding.encoding -> binary:'a encoding -> 'a encoding
|
||||||
|
|
||||||
|
@ -7,9 +7,9 @@
|
|||||||
(* *)
|
(* *)
|
||||||
(**************************************************************************)
|
(**************************************************************************)
|
||||||
|
|
||||||
(** Type-safe serialization and deserialization of data structures. *)
|
(** This is for use *within* the data encoding library only. Instead, you should
|
||||||
|
use the corresponding module intended for use: {Data_encoding.Json}. *)
|
||||||
|
|
||||||
(** In memory JSON data, compatible with [Ezjsonm]. *)
|
|
||||||
type json =
|
type json =
|
||||||
[ `O of (string * json) list
|
[ `O of (string * json) list
|
||||||
| `Bool of bool
|
| `Bool of bool
|
||||||
@ -18,79 +18,37 @@ type json =
|
|||||||
| `Null
|
| `Null
|
||||||
| `String of string ]
|
| `String of string ]
|
||||||
type t = json
|
type t = json
|
||||||
|
|
||||||
type schema = Json_schema.schema
|
type schema = Json_schema.schema
|
||||||
|
|
||||||
|
|
||||||
(** Create a {!Json_encoding.encoding} from an {encoding}. *)
|
|
||||||
val convert : 'a Encoding.t -> 'a Json_encoding.encoding
|
val convert : 'a Encoding.t -> 'a Json_encoding.encoding
|
||||||
|
|
||||||
(** Generate a schema from an {!encoding}. *)
|
|
||||||
val schema : 'a Encoding.t -> schema
|
val schema : 'a Encoding.t -> schema
|
||||||
|
|
||||||
val encoding: json Encoding.t
|
val encoding: json Encoding.t
|
||||||
val schema_encoding: schema Encoding.t
|
val schema_encoding: schema Encoding.t
|
||||||
|
|
||||||
|
|
||||||
(** Construct a JSON object from an encoding. *)
|
|
||||||
val construct : 't Encoding.t -> 't -> json
|
val construct : 't Encoding.t -> 't -> json
|
||||||
|
|
||||||
(** Destruct a JSON object into a value.
|
|
||||||
Fail with an exception if the JSON object and encoding do not match.. *)
|
|
||||||
val destruct : 't Encoding.t -> json -> 't
|
val destruct : 't Encoding.t -> json -> 't
|
||||||
|
|
||||||
(** JSON Error. *)
|
|
||||||
|
|
||||||
type path = path_item list
|
type path = path_item list
|
||||||
|
|
||||||
(** A set of accessors that point to a location in a JSON object. *)
|
|
||||||
and path_item =
|
and path_item =
|
||||||
[ `Field of string
|
[ `Field of string
|
||||||
(** A field in an object. *)
|
|
||||||
| `Index of int
|
| `Index of int
|
||||||
(** An index in an array. *)
|
|
||||||
| `Star
|
| `Star
|
||||||
(** Any / every field or index. *)
|
|
||||||
| `Next
|
| `Next
|
||||||
(** The next element after an array. *) ]
|
]
|
||||||
|
|
||||||
(** Exception raised by destructors, with the location in the original
|
|
||||||
JSON structure and the specific error. *)
|
|
||||||
exception Cannot_destruct of (path * exn)
|
exception Cannot_destruct of (path * exn)
|
||||||
|
|
||||||
(** Unexpected kind of data encountered (w/ the expectation). *)
|
|
||||||
exception Unexpected of string * string
|
exception Unexpected of string * string
|
||||||
|
|
||||||
(** Some {!union} couldn't be destructed, w/ the reasons for each {!case}. *)
|
|
||||||
exception No_case_matched of exn list
|
exception No_case_matched of exn list
|
||||||
|
|
||||||
(** Array of unexpected size encountered (w/ the expectation). *)
|
|
||||||
exception Bad_array_size of int * int
|
exception Bad_array_size of int * int
|
||||||
|
|
||||||
(** Missing field in an object. *)
|
|
||||||
exception Missing_field of string
|
exception Missing_field of string
|
||||||
|
|
||||||
(** Supernumerary field in an object. *)
|
|
||||||
exception Unexpected_field of string
|
exception Unexpected_field of string
|
||||||
|
|
||||||
val print_error :
|
val print_error :
|
||||||
?print_unknown: (Format.formatter -> exn -> unit) ->
|
?print_unknown: (Format.formatter -> exn -> unit) ->
|
||||||
Format.formatter -> exn -> unit
|
Format.formatter -> exn -> unit
|
||||||
|
|
||||||
(** Helpers for writing encoders. *)
|
|
||||||
val cannot_destruct : ('a, Format.formatter, unit, 'b) format4 -> 'a
|
val cannot_destruct : ('a, Format.formatter, unit, 'b) format4 -> 'a
|
||||||
val wrap_error : ('a -> 'b) -> 'a -> 'b
|
val wrap_error : ('a -> 'b) -> 'a -> 'b
|
||||||
|
|
||||||
(** Read a JSON document from a string. *)
|
|
||||||
val from_string : string -> (json, string) result
|
val from_string : string -> (json, string) result
|
||||||
|
|
||||||
(** Read a stream of JSON documents from a stream of strings.
|
|
||||||
A single JSON document may be represented in multiple consecutive
|
|
||||||
strings. But only the first document of a string is considered. *)
|
|
||||||
val from_stream : string Lwt_stream.t -> (json, string) result Lwt_stream.t
|
val from_stream : string Lwt_stream.t -> (json, string) result Lwt_stream.t
|
||||||
|
|
||||||
(** Write a JSON document to a string. This goes via an intermediate
|
|
||||||
buffer and so may be slow on large documents. *)
|
|
||||||
val to_string : ?minify:bool -> json -> string
|
val to_string : ?minify:bool -> json -> string
|
||||||
|
|
||||||
val pp : Format.formatter -> json -> unit
|
val pp : Format.formatter -> json -> unit
|
||||||
|
@ -7,6 +7,8 @@
|
|||||||
(* *)
|
(* *)
|
||||||
(**************************************************************************)
|
(**************************************************************************)
|
||||||
|
|
||||||
|
(** This is for use *within* the data encoding library only. *)
|
||||||
|
|
||||||
val bool: int
|
val bool: int
|
||||||
val int8: int
|
val int8: int
|
||||||
val uint8: int
|
val uint8: int
|
||||||
|
Loading…
Reference in New Issue
Block a user