data-encoding 0.7 · OCaml Package

type id = string

type t

A encoding that has been registered. It can be retrieved using either list or find.

Note registration/retrieval erases the type information that is built by the combinator. In other words, t is a non-parametric type. As a result, you cannot recover an OCaml value of the type of the registered encoding. You can only perform operations where the type doesn't escape — e.g., converting between binary and json.

val binary_schema : t -> Binary_schema.t

Descriptions and schemas of registered encodings.

val json_schema : t -> Json.schema

val description : t -> string option

val json_pretty_printer : t -> Stdlib.Format.formatter -> Json.t -> unit

Printers for the encodings.

val binary_pretty_printer : 
  t ->
  Stdlib.Format.formatter ->
  Stdlib.Bytes.t ->
  unit

val register : 
  ?pp:(Stdlib.Format.formatter -> 'a -> unit) ->
  'a Encoding.t ->
  unit

register (def id encoding) registers the encoding with the id. It can later be found using find and providing the matching id. It will also appear in the results of list.

raises [Invalid_argument]
if encoding is not of one of the following form:
- def id _ (see Encoding.def)
- splitted ~binary:(def id _) (see Encoding.splitted)
- dynamic_size (def id _) (see Encoding.dynamic_size)
- check_size _ (def id _) (see Encoding.check_size)

val slice : 
  t ->
  string ->
  (Binary.Slicer.slice list, Binary.read_error) Stdlib.result

slice r b attempts to slice a binary representation b of some data assuming it is correctly described by the registered encoding r. If r does not correctly describe b, then it returns None.

See Binary.Slicer.slice_string for details about slicing.

val slice_all : string -> (string * Binary.Slicer.slice list) list

slice_all b attempts to slice a binary representation b of some data for all of the registered encodings. It returns a list of the slicing for each of the registered encodings that correctly describe b.

See Binary.Slicer.slice_string for details about slicing.

val find : id -> t option

find id is Some r if register (def id e) has been called, in which case r matches e. Otherwise, it is None.

val list : unit -> (id * t) list

list () is a list of pairs (id, r) where r is a registered encoding for the id.

val bytes_of_json : t -> Json.t -> Stdlib.Bytes.t option

Conversion functions from JSON to bytes.

val json_of_bytes : t -> Stdlib.Bytes.t -> Json.t option

Conversion functions from bytes to JSON.

Introspection API

The introspection functions below expose some internal representations of the registered encodings. These functions are not for the casual user and are subject to changes from one version of the library to another.

type introspectable =

| Any : _ Encoding.t -> introspectable

A transparent, raw form of a registered encoding, allowing far greater introspection than a t value. It can be retrieved using find_introspectable or operated upon using iter.

Note that retrieval and iteration over introspectable preserve, but do not present, the type information of the original combinator. In other words, introspectable is a non-parametric abstraction over arbitrarily-typed Encoding.t. This means that, while it cannot be used in any way that would allow the underlying type parameter to escape, it can be operated upon (e.g. using iter) using functions with locally abstract types (fun (type a) -> ...) or explicit polymorphism.

The inclusion of this type is intended almost exclusively for use in specialized external tools rather than by casual users. As this type and its related functions permit introspection into a registered encoding that is otherwise opaque-by-design, it should only be relied upon as a last resort when no other options are available.

val find_introspectable : id -> introspectable option

find_introspectable id is Some e' if register (def id e) has been called, in which case e' should be Any e. Otherwise, it is None.

As with the introspectable type itself, casual users are discouraged from calling this function; it is designed only for external tools to process raw encodings that cannot be brought into scope except through querying the Registration module.

val iter : id:string -> (introspectable -> unit) -> unit

iter ~id f is equivalent to calling Option.iter f (find_introspectable id). It may be called wherever the result of find_introspectable id would otherwise be used only once, as an argument to a function call, and discarded subsequently.

package data-encoding

Introspection API