Module `Bin`Source

Bin is a small library for encoding and decoding information from a buffer (like a bytes or a bigstring). Unlike a parser combinator, Bin cannot decode a stream.

Bin can be used to project values coming from a pre-allocated buffer such as a "framebuffer" (video, ethernet, etc.) or to inject values into it. Bin can be seen as a library for describing (fairly basic) "C-like" types of values that can be injected/projected into/from a particular memory area:

  #define PROPTAG_GET_COMMAND_LINE 0x00050001
  #define VALUE_LENGTH_RESPONSE (1 << 31)

  struct __attribute__((packed)) cmdline {
    uint32_t id;
    uint32_t value_len;
    uint32_t param_len;
    uint8    str[2048];
  };

  struct __attribute__((packed)) property_tag {
    uint32_t id;
    uint32_t value_len;
    uint32_t param_len;
  };

  extern char _tags;

  char *get_cmdline() {
    struct cmdline p;
    p.id = PROPTAG_GET_COMMAND_LINE;
    p.value_len = len - sizeof(struct property_tag);
    p.param_len = 2048 & ~VALUE_LENGTH_RESPONSE;
    memcpy(&_tags, &p, sizeof(struct cmdline)); // inject
    ...
  }

Bin therefore allows you to describe a representation of a serialized value in bytes and to associate with it a function that allows you to obtain an OCaml value such as a record or a variant.

  open Bin

  type cmdline = {
      id: int32
    ; value_len: int32
    ; param_len: int32
    ; cmdline: string
  }

  let cmdline =
    record (fun id value_len param_len -> { id; value_len; param_len })
    |+ field neint32 (Fun.const 0x00050001l)
    |+ field neint32 (fun t -> t.value_len)
    |+ field neint32 (fun t -> t.param_len)
    |+ field cstring (fun t -> t.cmdline)
    |> sealr

  let encode_into tags ?(off = 0) value =
    let off = ref off in
    Bin.encode_bstr cmdline value tags off (* inject *)

Of course, it's not as fast as what we can do in C, but Bin has the advantage of offering a small DSL that allows us to describe these types and go directly to OCaml values, which is generally more pleasant to manipulate with OCaml than to make C stubs.

Sourcetype 'a t

Primitives.

Sourceval char : char t

char is a representation of the character type.

Sourceval uint8 : int t

uint8 is a representation of unsigned 8-bit integers.

Sourceval int8 : int t

int8 is a representation of 8-bit integers.

Sourceval beuint16 : int t

beint16 is a representation of big-endian unsigned 16-bit integers.

Sourceval leuint16 : int t

leint16 is a representation of little-endian unsigned 16-bit integers.

Sourceval neuint16 : int t

neint16 is a representation of native-endian unsigned 16-bit integers.

Sourceval beint16 : int t

beint16 is a representation of big-endian 16-bit integers.

Sourceval leint16 : int t

leint16 is a representation of little-endian 16-bit integers.

Sourceval neint16 : int t

neint16 is a representation of native-endian 16-bit integers.

Sourceval beint32 : int32 t

beint32 is a representation of big-endian 32-bit integers.

Sourceval leint32 : int32 t

leint32 is a representation of little-endian 32-bit integers.

Sourceval neint32 : int32 t

neint32 is a representation of native-endian 32-bit integers.

Sourceval beint64 : int64 t

beint64 is a representation of big-endian 64-bit integers.

Sourceval leint64 : int64 t

leint64 is a representation of little-endian 64-bit integers.

Sourceval neint64 : int64 t

neint64 is a representation of native-endian 64-bit integers.

Sourceval varint : int t

Sourceval bytes : int -> string t

bytes n is a representation of a bytes sequence of n byte(s).

Sourceval bstr : int -> Bstr.t t

bstr n is a representation of a bigstring of n byte(s).

Sourceval cstring : string t

Sourceval until : char -> string t

Sourceval const : 'a -> 'a t

const v is v without a serialization mechanism.

Sourceval seq : len:int -> 'a t -> 'a array t

seq ~len v is a representation of fixed-length arrays of values of type v.

Sourceval map : 'b t -> ('b -> 'a) -> ('a -> 'b) -> 'a t

This combinator allows defining a representative of one type in terms of another by supplying coercions between them.

Sourcetype ('a, 'b, 'c) open_record

The type for representing open records of type 'a with a constructor of 'b. 'c represents the remaining fields to be described using the (|+) operator. An open record initially stisfies 'c = 'b and can be sealed once 'c = 'a.

Sourceval record : 'b -> ('a, 'b, 'b) open_record

record f is an incomplete representation of the record of type 'a with constructor f. To complete the representation, add fields with (|+) and then seal the record with sealr.

Sourcetype ('a, 'b) field

The type for fields holding values of type 'b and belonging to a record of type 'a.

Sourceval field : 'a t -> ('b -> 'a) -> ('b, 'a) field

field n t g is the representation of the field called n of type t with getter g. For instance:

  type t = { foo: string }

  let foo = field cstring (fun t -> t.foo)

Source

val (|+) : 
  ('a, 'b, 'c -> 'd) open_record ->
  ('a, 'c) field ->
  ('a, 'b, 'd) open_record

r |+ f is the open record r augmented with the field f.

Sourceval sealr : ('a, 'b, 'a) open_record -> 'a t

sealr r seals the open record r.

Variants.

  type t = Foo | Bar of string

  let t =
    variant (fun foo bar -> function Foo -> foo | Bar s -> bar s)
    |~ case0 Foo
    |~ case1 cstring (fun x -> Bar x)
    |> sealv

Sourcetype ('a, 'b, 'c) open_variant

The type for representing open variants of type 'a with pattern-matching of type 'b. 'c represents the remaining constructors to be described using the (|~) operator. An open variant initially satisfies 'c = 'b and can be sealed once 'c = 'a.

Sourceval variant : 'b -> ('a, 'b, 'b) open_variant

variant n p is an incomplete representation of the variant type called n of type 'a using p to deconstruct values. To complete the representation, add cases with (|~) and then seal the variant with sealv.

Sourcetype ('a, 'b) case

The type for representing variant cases of type 'a with patterns of type 'b.

Sourcetype 'a case_p

The type for representing patterns for a variant of type 'a.

Sourceval case0 : 'a -> ('a, 'a case_p) case

case0 v is a representation of a variant constructor v with no arguments. For instance:

  type t = Foo

  let foo = case0 Foo

Sourceval case1 : 'b t -> ('b -> 'a) -> ('a, 'b -> 'a case_p) case

case1 n t c is a representation of a variant constructor c with an argument of type t. For instances:

  type t = Foo of string

  let foo = case1 cstring (fun s -> Foo s)

Source

val (|~) : 
  ('a, 'b, 'c -> 'd) open_variant ->
  ('a, 'c) case ->
  ('a, 'b, 'd) open_variant

v |~ c is the open variant v augmented with the case c.

Sourceval sealv : ('a, 'b, 'a -> 'a case_p) open_variant -> 'a t

sealv v seals the open variant v.

Decoder.

Sourceval decode_bstr : 'a t -> Bstr.t -> int ref -> 'a

decode_bstr repr is the binary decoder for values of type repr.

Sourceval decode : 'a t -> string -> int ref -> 'a

Encoder.

Sourceval encode_bstr : 'a t -> 'a -> Bstr.t -> int ref -> unit

Sourceval to_string : 'a t -> 'a -> string

Sourcemodule Size : sig ... end

Sourceval size_of_value : 'a t -> 'a -> int option

size_of_value encoding value attempts to calculate the number of bytes needed to encode the given value according to the given encoding.

Sourceval size_of_bstr : ?off:int -> 'a t -> Bstr.t -> int option

size_of_encoding ?off encoding bstr attempts to calculate the number of bytes required to decode a value according to the given encoding and according to what can be decoded in the given byte sequence bstr (at the given offset off, defaults to 0).

Install

Dune Dependency

Authors

Maintainers

Sources

doc/bin/Bin/index.html

Module `Bin`Source

Primitives.

Variants.

Decoder.

Encoder.

package bin

Install

Dune Dependency

Authors

Maintainers

Sources

doc/bin/Bin/index.html

Module BinSource

Primitives.

Variants.

Decoder.

Encoder.

Module `Bin`Source