Module B0_std.Conv

Value converters.

FIXME. Likely get rid of this. See Benc. We also have better sexps in B0_sexp. Configuration likely wants something simpler.

A value converter describes how to encode and decode OCaml values to a binary presentation and a textual, human specifiable, s-expression based, representation.

Notation. Given a value v and a converter c we write [v]c the textual encoding of v according to c.

Low-level encoders and decoders

exception Error of int * int * string

The exception for conversion errors. This exception is raised both by encoders and decoders with raise_notrace. The integers indicates a byte index range in the input on decoding errors, it is meaningless on encoding ones.

Note. This exception is used for defining converters. High-level converting functions do not raise but use result values to report errors.

module Bin : sig ... end

Binary codecs.

module Txt : sig ... end

Textual codecs

Converters

type 'a t

The type for converters.

val v : kind:string -> docvar:string -> 'a Bin.enc -> 'a Bin.dec -> 'a Txt.enc -> 'a Txt.dec -> 'a t

v ~kind ~docvar bin_enc bin_dec txt_enc txt_dec is a value converter using bin_enc, bin_dec, txt_enc, txt_dec for binary and textual conversions. kind documents the kind of converted value and docvar a meta-variable used in documentation to stand for these values (use uppercase e.g. INT for integers).

val kind : 'a t -> string

kind c is the documented kind of value converted by c.

val docvar : 'a t -> string

docvar c is the documentation meta-variable for values converted by c.

val bin_enc : 'a t -> 'a Bin.enc

bin_enc c is the binary encoder of c.

val bin_dec : 'a t -> 'a Bin.dec

bin_dec c is the binary decoder of c.

val txt_enc : 'a t -> 'a Txt.enc

txt_enc c is the textual encoder of c.

val txt_dec : 'a t -> 'a Txt.dec

txt_dec c is the textual decoder of c.

val with_kind : ?⁠docvar:string -> string -> 'a t -> 'a t

with_kind ~docvar k c is c with kind k and documentation meta-variable docvar (defaults to docvar c).

val with_docvar : string -> 'a t -> 'a t

with_docvar docvar c is c with documentation meta-variable docvar.

val with_conv : kind:string -> docvar:string -> ('b -> 'a) -> ('a -> 'b) -> 'a t -> 'b t

with_conv ~kind ~docvar to_t of_t t_conv is a converter for type 'b given a converter t_conv for type 'a and conversion functions from and to type 'b. The conversion functions should raise Error if they are not total.

Converting

val to_bin : ?⁠buf:Stdlib.Buffer.t -> 'a t -> 'a -> (string, string) Stdlib.result

to_bin c v binary encodes v using c. buf is used as the internal buffer if specified (it is Buffer.cleared before usage).

val of_bin : 'a t -> string -> ('a, string) Stdlib.result

of_bin c s binary decodes a value from s using c.

val to_txt : ?⁠buf:Stdlib.Buffer.t -> 'a t -> 'a -> (string, string) Stdlib.result

to_txt c v textually encodes v using c. buf is used as the internal buffer if specified (it is Buffer.cleared before usage).

val of_txt : 'a t -> string -> ('a, string) Stdlib.result

of_txt c s textually decodes a value from s using c.

val to_pp : 'a t -> 'a Fmt.t

to_pp c is a formatter using to_txt to format values. Any error that might occur is printed in the output using the s-expression (conv-error [c]kind [e]) with [c]kind the atom for the value kind c and [e] the atom for the error message.

Predefined converters

Base types

val unit : unit t

unit unit converts unit. Textual conversion represent unit with "unit".

val bool : bool t

bool converts booleans. Textual conversions represent booleans with the atoms true and false.

val byte : int t

byte converts a byte. Textual decoding parses an atom according to the syntax of int_of_string. Conversions fail if the integer is not in the range [0;255].

val int : int t

int converts signed OCaml integers. Textual decoding parses an atom according to the syntax of int_of_string. Conversions fail if the integer is not in the range [-2Sys.int_size-1;2Sys.int_size-1-1].

Warning. A large integer encoded on a 64-bit platform may fail to decode on a 32-bit platform, use int31 or int64 if this is a problem.

val int31 : int t

int31 converts signed 31-bit integers. Textual decoding parses an atom according to the syntax of int_of_string. Conversions fail if the integer is not in the range [-230;230-1].

val int32 : int32 t

int32 converts signed 32-bit integers. Textual decoding parses an atom according to the syntax of Int32.of_string. Conversions fail if the integer is not in the range [-231;231-1].

val int64 : int64 t

int64 converts signed 64-bit integers. Textual decoding parses an atom according to the syntax of Int64.of_string. Conversions fail if the integer is not in the range [-263;263-1].

val float : float t

float converts floating point numbers. Textual decoding parses an atom using float_of_string.

val string_bytes : string t

string_bytes converts OCaml strings as byte sequences. Textual conversion represents the bytes of s with the s-expression (hex [s]hex) with [s]hex the atom resulting from String.Ascii.to_hex s. See also atom and only_string.

Warning. A large string encoded on a 64-bit platform may fail to decode on a 32-bit platform.

val atom : string t

atom converts strings assumed to represent UTF-8 encoded Unicode text; but the encoding is not checked. Textual conversions represent strings as atoms. See also string_bytes and only_string.

Warning. A large atom encoded on a 64-bit platform may fail to decode on a 32-bit platform.

val atom_non_empty : string t

atom_non_empty is like atom but ensures the atom is not empty.

val fpath : Fpath.t t

fpath converts file paths. The textual representation uses non-empty atoms. See also fpath_only.

val hash : Hash.t t

hash converts using string_bytes.

val time_span : Time.span t

time_span is a converter for time spans. Texual conversion parses an atom using Int64.of_string.

val time_cpu_span : Time.cpu_span t

time_cpu_span is a converter for CPU spans.

val cmd : Cmd.t t

cmd converts command lines.

val os_cmd_status : Os.Cmd.status t

os_cmd_status converts tool spawn statuses.

Higher-order converters

val option : ?⁠kind:string -> ?⁠docvar:string -> 'a t -> 'a option t

option c converts optional values converted with c. Textual conversions represent None with the atom none and Some v with the s-expression (some [v]c).

val some : 'a t -> 'a option t

some c wraps decodes of c with Option.some. Warning. None can't be converted in either direction, use option for this.

val result : ?⁠kind:string -> ?⁠docvar:string -> 'a t -> 'b t -> ('a'b) Stdlib.result t

result ok error converts result values with ok and error. Textual conversions represent Ok v with the s-expression (ok [v]ok) and Error e with (error [e]error).

val list : ?⁠kind:string -> ?⁠docvar:string -> 'a t -> 'a list t

array c converts a list of values converted with c. Textual conversions represent a list [v0; ... vn] by the s-expression ([v0]c ... [vn]c).

Warning. A large list encoded on a 64-bit platform may fail to decode on a 32-bit platform.

val array : ?⁠kind:string -> ?⁠docvar:string -> 'a t -> 'a array t

array c is like list but converts arrays.

Warning. A large array encoded on a 64-bit platform may fail to decode on a 32-bit platform.

val pair : ?⁠kind:string -> ?⁠docvar:string -> 'a t -> 'b t -> ('a * 'b) t

pair c0 c1 converts pairs of values converted with c0 and c1. Textual conversion represent a pair (v0, v1) by the s-expression ([v0]c0 [v1]c1).

val enum : kind:string -> docvar:string -> ?⁠eq:('a -> 'a -> bool) -> (string * 'a) list -> 'a t

enum ~kind ~docvar ~eq vs converts values present in vs. eq is used to test equality among values (defaults to ( = )). The list length should not exceed 256. Textual conversions use the strings of the pairs in vs as atoms to encode the corresponding value.

Non-composable predefined converters

Textual conversions performed by the following converters cannot be composed; they do not respect the syntax of s-expression atoms. They can be used for direct conversions when one does not want to be subject to the syntactic constraints of s-expressions. For example when parsing command line interface arguments or environment variables.

val string_only : string t

string_only converts OCaml strings. Textual conversion is not composable, use string_bytes or atom instead. Textual encoding passes the string as is and decoding ignores the initial starting point and returns the whole input string.

Warning. A large string encoded on a 64-bit platform may fail to decode on a 32-bit platform.

val fpath_only : Fpath.t t

fpath_only converts file paths. Textual conversion is not composable, use path instead. Textual encoding pass the string as is and decoding ignores the initial starting point and parses the whole input string into a file path.