package octez-proto-libs

  1. Overview
  2. Docs
package octez-proto-libs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Create encodings that produce data of a fixed length when binary encoded. See the preamble for an explanation.

val string : string_json_repr -> int -> string encoding
val bytes : string_json_repr -> int -> Bytes.t encoding
val add_padding : 'a encoding -> int -> 'a encoding

add_padding e n is a padded version of the encoding e. In Binary, there are n null bytes (\000) added after the value encoded by e. In JSON, padding is ignored.

val list : int -> 'a encoding -> 'a list encoding

list n e is an encoding for lists of exactly n elements. If a list of more or fewer elements is provided, then the encoding fails with the write_error List_invalid_length. For decoding, it can fail with read_error Not_enough_data or read_error Extra_bytes, or it may cause other failures further down the line when the AST traversal becomes out-of-sync with the underlying byte-stream traversal.

The difference of the errors being used when encoding and decoding is because when encoding we have access to the list and we can check the actual length, whereas when decoding we only see bytes, sometimes too many, sometimes not enough.

This encoding has a narrow set of possible applications because it is very restrictive. Still, it can to:

  • mirror static guarantees about the length of some lists,
  • special-case some common lengths of typical input in a union (see example below),
  • other ends.
type expr =
  | Op of string * expr list (* most commonly 1 or 2 operands *)
  | Literal of string
let expr_encoding =
  mu "expr" (fun e ->
    union [
      case ~title:"op-nonary" (Tag 0)
        string
        (function Op (op, []) -> Some op | _ -> None)
        (fun op -> Op (op, []));
      case ~title:"op-unary" (Tag 1)
        (tup2 string (Fixed.list 1 e))
        (function Op (op, ([_]) as operand) -> Some (op, operand) | _ -> None)
        (fun (op, operand) -> Op (op, operand));
      case ~title:"op-binary" (Tag 2)
        (tup2 string (Fixed.list 2 e))
        (function Op (op, ([_;_]) as operand) -> Some (op, operand) | _ -> None)
        (fun (op, operand) -> Op (op, operand));
      case ~title:"op-moreary" (Tag 3)
        (tup2 string (list e))
        (function Op (op, operand) -> Some (op, operand) | _ -> None)
        (fun (op, operand) -> Op (op, operand));
      case ~title:"literal" (Tag 4)
        string
        (function Literal l -> Some l | _ -> None)
        (fun l -> Literal l);
        ]
  )

Interestingly, the cases for known lengths can be generated programmatically.

  • raises Invalid_argument

    if the argument e is a `Variable-size encoding or a zero-byte encoding.

val array : int -> 'a encoding -> 'a array encoding

See list above.

  • raises Invalid_argument

    if the argument e is a `Variable-size encoding or a zero-byte encoding.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct