From 0a3c9d52ecebe17eb06aa3c19a420694ea7c5e80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Proust?= Date: Thu, 3 May 2018 15:25:47 +0800 Subject: [PATCH] Data_encoding: deduplicate documentation --- src/lib_data_encoding/binary.mli | 31 +--- src/lib_data_encoding/bson.mli | 8 +- src/lib_data_encoding/encoding.mli | 220 +---------------------------- src/lib_data_encoding/json.mli | 48 +------ src/lib_data_encoding/size.mli | 2 + 5 files changed, 13 insertions(+), 296 deletions(-) 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