diff --git a/src/lib_data_encoding/binary.mli b/src/lib_data_encoding/binary.mli
index e9c64b9f6..57088771e 100644
--- a/src/lib_data_encoding/binary.mli
+++ b/src/lib_data_encoding/binary.mli
@@ -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 read : 'a Encoding.t -> MBytes.t -> int -> int -> (int * 'a) option
val write : 'a Encoding.t -> 'a -> MBytes.t -> int -> int option
val to_bytes : 'a Encoding.t -> 'a -> MBytes.t
val of_bytes : 'a Encoding.t -> MBytes.t -> 'a option
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
-
-(** 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 =
| Success of { res : 'a ; res_len : int ; remaining : MBytes.t list }
| Await of (MBytes.t -> 'a status)
| 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
-
-(** 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 fixed_length : 'a Encoding.t -> int option
val fixed_length_exn : 'a Encoding.t -> int
diff --git a/src/lib_data_encoding/bson.mli b/src/lib_data_encoding/bson.mli
index 0a670dec4..8e4d7fc2f 100644
--- a/src/lib_data_encoding/bson.mli
+++ b/src/lib_data_encoding/bson.mli
@@ -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 t = bson
-
-(** Construct a BSON object from an encoding. *)
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
diff --git a/src/lib_data_encoding/encoding.mli b/src/lib_data_encoding/encoding.mli
index 1923dc570..12f1a233c 100644
--- a/src/lib_data_encoding/encoding.mli
+++ b/src/lib_data_encoding/encoding.mli
@@ -7,63 +7,16 @@
(* *)
(**************************************************************************)
-(** Type-safe serialization and deserialization of data structures. *)
-
-(** {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 *)
+(** This is for use *within* the data encoding library only. Instead, you should
+ use the corresponding module intended for use: {Data_encoding.Encoding}. *)
module Kind: sig
-
type t = [ `Fixed of int | `Dynamic | `Variable ]
-
type length = [ `Fixed of int | `Variable ]
-
type enum = [ `Dynamic | `Variable ]
-
val combine: string -> t -> t -> t
-
val merge : t -> t -> t
-
val merge_list: Size.tag_size -> t list -> t
-
end
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
-(** Special value [null] in JSON, nothing in binary. *)
val null : unit encoding
-
-(** Empty object (not included in binary, encoded as empty object in JSON). *)
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
-
-(** Constant string (data is not included in the binary data). *)
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
-
-(** Unsigned 8 bit integer
- (data is encoded as a byte in binary and an integer in JSON). *)
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
-
-(** Unsigned 16 bit integer
- (data is encoded as a short in binary and an integer in JSON). *)
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
-
-(** Signed 32 bit integer
- (data is encoded as a 32-bit int in binary and an integer in JSON). *)
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
-
-(** 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
-
-(** Float with bounds in a given range. Both bounds are inclusive *)
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
-
-(** 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
-
-(** Encoding of arbitrary bytes
- (encoded via hex in JSON and directly as a sequence byte in binary). *)
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
-
-(** 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
-
-(** 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
-
-(** Encode enumeration via association list
- (represented as a string in JSON and binary). *)
val string_enum : (string * 'a) list -> 'a encoding
-
-
-(** Is the given encoding serialized as a JSON object? *)
val is_obj : 'a encoding -> bool
-
-(** Does the given encoding encode a tuple? *)
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
-
- (** Encode a fixed length string *)
val string : int -> string encoding
-
- (** Encode a fixed length byte sequence *)
val bytes : int -> MBytes.t encoding
end
-
-(** Create encodings that produce data of a variable length when binary encoded.
- See the preamble for an explanation. *)
module Variable : sig
- (** Encode a string *)
val string : string encoding
-
- (** Encode a byte sequence *)
val bytes : MBytes.t encoding
-
- (** Array encoding combinator *)
val array : 'a encoding -> 'a array encoding
-
- (** List encoding combinator *)
val list : 'a encoding -> 'a list encoding
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
-
-(** 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
-
-(** Required field. *)
val req :
?title:string -> ?description:string ->
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 :
?title:string -> ?description:string ->
string -> 't encoding -> 't option field
-
-(** Optional field of variable length.
- Only one can be present in a given object. *)
val varopt :
?title:string -> ?description:string ->
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 :
?title:string -> ?description:string ->
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 :
'f1 field -> 'f1 encoding
val obj2 :
@@ -339,12 +178,6 @@ val obj10 :
'f6 field -> 'f7 field -> 'f8 field -> 'f9 field -> 'f10 field ->
('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 :
'f1 encoding ->
'f1 encoding
@@ -384,77 +217,28 @@ val tup10 :
'f9 encoding -> '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
-
-(** 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
-
-(** Array combinator. *)
val array : 'a encoding -> 'a array encoding
-
-(** List combinator. *)
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 :
?name:string ->
case_tag ->
'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 :
?tag_size:[ `Uint8 | `Uint16 ] -> 't case list -> 't encoding
-(** Add documentation to an encoding. *)
val describe :
?title:string -> ?description:string ->
't encoding ->'t encoding
-
-(** Give a name to an 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 :
('a -> 'b) -> ('b -> 'a) ->
?schema:Json_schema.schema ->
'b encoding -> 'a encoding
-
-(** Combinator for recursive encodings. *)
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 ]
-
-(** Define different encodings for JSON and binary serialization. *)
val raw_splitted : json:'a Json_encoding.encoding -> binary:'a encoding -> 'a encoding
-
diff --git a/src/lib_data_encoding/json.mli b/src/lib_data_encoding/json.mli
index 75811afe6..b6382b4f0 100644
--- a/src/lib_data_encoding/json.mli
+++ b/src/lib_data_encoding/json.mli
@@ -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 =
[ `O of (string * json) list
| `Bool of bool
@@ -18,79 +18,37 @@ type json =
| `Null
| `String of string ]
type t = json
-
type schema = Json_schema.schema
-
-(** Create a {!Json_encoding.encoding} from an {encoding}. *)
val convert : 'a Encoding.t -> 'a Json_encoding.encoding
-
-(** Generate a schema from an {!encoding}. *)
val schema : 'a Encoding.t -> schema
-
val encoding: json Encoding.t
val schema_encoding: schema Encoding.t
-
-
-(** Construct a JSON object from an encoding. *)
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
-(** JSON Error. *)
-
type path = path_item list
-
-(** A set of accessors that point to a location in a JSON object. *)
and path_item =
[ `Field of string
- (** A field in an object. *)
| `Index of int
- (** An index in an array. *)
| `Star
- (** Any / every field or index. *)
| `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)
-
-(** Unexpected kind of data encountered (w/ the expectation). *)
exception Unexpected of string * string
-
-(** Some {!union} couldn't be destructed, w/ the reasons for each {!case}. *)
exception No_case_matched of exn list
-
-(** Array of unexpected size encountered (w/ the expectation). *)
exception Bad_array_size of int * int
-
-(** Missing field in an object. *)
exception Missing_field of string
-
-(** Supernumerary field in an object. *)
exception Unexpected_field of string
val print_error :
?print_unknown: (Format.formatter -> exn -> unit) ->
Format.formatter -> exn -> unit
-(** Helpers for writing encoders. *)
val cannot_destruct : ('a, Format.formatter, unit, 'b) format4 -> 'a
val wrap_error : ('a -> 'b) -> 'a -> 'b
-(** Read a JSON document from a string. *)
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
-
-(** 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 pp : Format.formatter -> json -> unit
diff --git a/src/lib_data_encoding/size.mli b/src/lib_data_encoding/size.mli
index 65ab9f625..9807d2a8d 100644
--- a/src/lib_data_encoding/size.mli
+++ b/src/lib_data_encoding/size.mli
@@ -7,6 +7,8 @@
(* *)
(**************************************************************************)
+(** This is for use *within* the data encoding library only. *)
+
val bool: int
val int8: int
val uint8: int