package orsetto

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

Concise Binary Object Representation (CBOR) event decoder and parsers.

Overview

This module provides a

f_decode

scheme for CBOR events, and a system of

f_scan

parsers for scanning CBOR encoded octet streams.

Events

The CBOR event decoder scheme. This scheme can decode most valid CBOR encodings.

Note well: scanning events with this scheme raises Cf_decode.Invalid when it encounters a definite length array or map with more elements than an OCaml array type can comprise, and when it encounters a definite length octet sequence or Unicode text with more octets than an OCaml string type can comprise. All other valid CBOR encodings are recognized.

The annotation system.

Include the scanner profile. Errors from the symbol decoder are translated to raise Bad_syntax.

include Cf_scan.Profile with type symbol := Cbor_event.t and type position := Cf_decode.position and type 'a form := 'a Annot.form
type +'r t

The monad type.

include Cf_monad.Unary.Profile with type +'r t := 'r t

Module inclusions from Cf_monad_core and Cf_seqmonad.

include Cf_monad.Core.Unary.Profile with type 'r t := 'r t
val return : 'r -> 'r t

Use return a to apply the binding to a.

val bind : 'a t -> ('a -> 'b t) -> 'b t

Use bind m f to bind f to the value returned by m.

val map : 'a t -> f:('a -> 'b) -> 'b t

Use map m ~f to return the result of applying f to the value returned by m.

val product : 'a t -> 'b t -> ('a * 'b) t

Use product a b to return the monoidal product of a and b.

val disregard : 'r t -> unit t

Use disregard m to ignore the value returned by m and apply the unit value to the bound function.

module Infix : sig ... end

Deprecated module alias.

include Cf_seqmonad.Functor.Unary with type 'r t := 'r t
val collect : 'r t Seq.t -> (int * 'r list) t

Use collect s to bind in sequence every monad value in the finite sequence s and collect all the returned values. Returns (n, s) where n is the number of values collected and s is the list of values in reverse order, i.e. from last collected to first collected. Never returns and exhausts all memory if s never terminates.

val serial : unit t Seq.t -> unit t

Use serial s to bind in sequence every monad value in the sequence s.

val nil : 'r t

A scanner that never produces any value.

val fin : bool t

A scanner that returns true at the end of the input sequence, otherwise returns false.

Backtracking
type mark

The abstract type representing a resumption point in the input.

val cur : mark t

A scanner that produces a mark captured at the current position.

val mov : mark -> unit t

Use mov mark to resume scanning at the captured mark.

val pos : mark -> unit Annot.form

Use pos mark to make a unit value attributed with the position of captured mark. If the mark was captured at the end of the stream, then the result is an implicit form.

Terminal Scanner

The universal symbol scanner. Recognizes any symbol in the input stream and produces its form. Does not produce anything at the end of input.

The literal symbol scanner. Use one symbol to make a scanner that recognizes symbol in the input stream and produces its form.

val sat : (Cbor_event.t -> bool) -> Cbor_event.t Annot.form t

The symbol satisfier scanner. Use sat f to make a scanner that recognizes any symbol for which applying f returns true and produces its form.

val ign : (Cbor_event.t -> bool) -> unit Annot.form t

The ignore scanner. Use ign f to make a scanner that scans the input while applying f to each symbol returns true, then produces a unit form that annotates the span of ignored symbols. Produces an implicit unit form if the end of input has already been reached.

val tok : (Cbor_event.t -> 'r option) -> 'r Annot.form t

The symbolic token scanner. Use tok f to make a scanner that recognizes any symbol for which applying f returns Some v, then produces the form of v.

Scanner Composers

The opaque value form scanner composer. Use ntyp n p to make a scanner that encloses the value contained in the form produced by p in an opaque value with the runtime type indicated by n and returns its form in the same position.

val dflt : 'r -> 'r Annot.form t -> 'r Annot.form t

The default value scanner. Use dflt v p to produce the output of p or the default value v with implicit annotation if p does not produce output.

val opt : 'r t -> 'r option t

The optional scanner composer. Use opt p to make a scanner that produces either Some v if p produces v otherwise None.

val vis : ?a:int -> ?b:int -> ('r -> 'r t) -> 'r -> 'r t

The visitor scanner composer. Use vis ?a ?b f v to compose a scanner that recognizes a sequence of elements in the input stream by applying a visitor function f at each element to obtain its scanner. The first element is visited with the initializer v, and each following element is visited with the value returned by the preceding scanner.

If ~a is used, then it specifies the minimum number of elements to visit. If ~b is used then it specifies the maximum number of elements to visit. Composition raises Invalid_argument if a < 0 or b < a.

val seq : ?a:int -> ?b:int -> 'r t -> 'r list t

The homogenous list scanner composer. Use seq ?a ?b p to create a new scanner that uses p to recognize and produce, in order, each element in a sequence of elements in the input stream.

If ~a is used, then it specifies the minimum number of elements that must be recognized and produced in the output. If ~b is used then it specifies the maximum number of elements to recognize. Composition raises Invalid_argument if a < 0 or b < a.

val alt : 'r t list -> 'r t

The bounded multiple choice scanner. Use alt ps to create a scanner that produces the output from the first scanner ps that produces. If no scanner in ps produces output, then the resulting scanner does not produce.

val altz : 'r t Seq.t -> 'r t

The unbounded multiple choice scanner. Use alt ps to create a scanner that produces the output from the first scanner ps that produces. If no scanner in ps produces output, then the resulting scanner does not produce.

Error Parsers
type exn +=
  1. | Bad_syntax of string Annot.form

A distinguished syntax failure exception.

val fail : string -> 'r t

Use fail msg to raise Bad_syntax with msg optionally annotated with the current position.

val or_fail : string -> 'r t -> 'r t

Use or_fail msg p to make a scanner that raises Bad_syntax with msg if p does not recognize its input. It may be convenient to call this function with a pipeline operator, i.e. p |> or_fail "reasons".

val err : ?x:exn -> unit -> 'r t

Use err ~x () to make a scanner that raises x. If ?x is not provided, then it raises Not_found.

val errf : ?xf:(mark -> 'x) -> unit -> 'r t

Use errf ~xf () to make a scanner that captures a mark and applies it to xf to raise an exception. If ?xf is not provided, then raises Not_found.

val req : ?x:exn -> 'r t -> 'r t

Use req ~x p to make a scanner that either produces the output of p or raises x. If p does not produce and ?x is not provided, then it raises Not_found.

val reqf : ?xf:(mark -> 'x) -> 'r t -> 'r t

Use reqf ~xf p to make a scanner that either produces the output of p or captures a mark at the current input and applies it to xf to raise an exception. If ?xf is not provided, then raises Not_found.

val cast : ('a -> 'b) -> 'a Annot.form t -> 'b Annot.form t

The conversion scanner. Use cast f p to create a scanner produces the result of applying f to the value recognized by p. If f raises Not_found then the resulting scanner does not produce. If f raises Failure s then it will be caught and Bad_syntax will be raised with the corresponding message decorated with the position.

val ck : 'r t -> ('r, exn) result t

The error check scanner. Use ck p to create a new scanner that either produces either Ok v if p produces v or Error x if scanning the input with p raises the exception x.

val sync : 'r t -> 'r option t

The error recovery scanner. Use sync p to scan the input with p until it produces or reaches the end of input. Produces Some v if p ever produces v, otherwise produces None if the end of input is reached without p producing a value.

Elaboration
val lift : ?start:Cf_decode.position -> 'r t -> Cbor_event.t Seq.t -> 'r Seq.t

Use lift p s to map s into a persistent sequence of the values produced by p. If ~start is provided, then it specifies the starting position of the first symbol in s.

val of_seq : ?start:Cf_decode.position -> 'r t -> Cbor_event.t Seq.t -> 'r

Use of_seq p s to parse s with p and return the result. Raises Not_found if p does not recognize the entire sequence of s. If ~start is provided, then it specifies the starting position of the first symbol in s.

module Affix : sig ... end

Combinator operators

Parsers
val of_slice : 'a t -> string Cf_slice.t -> 'a

Use of_slice p s to parse the octets in s with p.

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

Use of_string p s to parse the octets in s with p.

Scalar Values
val null : unit Annot.form t

A parser that recognizes the CBOR null value.

val break : unit Annot.form t

A parser that recognizes the CBOR break value, signifying the end of an indefinite length sequence.

val boolean : bool Annot.form t

A parser that recognizes the CBOR true and false values.

val integer : int Annot.form t

A parser that recognizes a positive or negative CBOR integer value, provided that it can be represented by an OCaml integer.

val int32 : (Cbor_event.sign * int32) Annot.form t

A parser that recognizes a positive or negative CBOR integer value, provided that it can be represented by an OCaml int32 value. The returned 32 octets are to be regarded unsigned. The arithmetic sign of the encoded integer is returned separately.

val int64 : (Cbor_event.sign * int64) Annot.form t

A parser that recognizes any positive or negative CBOR integer value. The returned 64 octets are to be regarded unsigned. The arithmetic sign of the encoded integer is returned separately.

val float : float Annot.form t

A parser that recognizes a CBOR floating point number value.

val octets : ?a:int -> ?b:int -> unit -> string Annot.form t

A parser that recognizes a CBOR octets value. Indefinite length and definite length octet sequences are recognized equivalently.

If ~a is used, then it specifies the minimum number of octets in the recognized value. If ~b is used, then it specifies the maximum number of octets in the recognized value. The default value of ~a is zero and the default value of ~b is Sys.max_string_length. Raises Invalid_argument if a < 0, b < a or b > Sys.max_string_length.

If the encoded value has indefinite length, then CBOR events are only consumed from the input stream while the total number of octets does not exceeed b.

val text : ?nf:(module Ucs_normal.Profile) -> ?a:int -> ?b:int -> unit -> Ucs_text.t Annot.form t

A parser that recognizes a CBOR text value. Indefinite length and definite length texts are recognized equivalently.

If ~nf is used, then the decoded text is normalized accordingly.

If ~a is used, then it specifies the minimum number of UTF-8 encoded octets in the encoded text. If ~b is used, then it specifies the maximum number of UTF-8 encoded octets in the encoded text. The default value of ~a is zero and the default value of ~b is Sys.max_string_length. Raises Invalid_argument if a < 0, b < a or b > Sys.max_string_length. If ~nf is used with either ~a or ~b, then it's possible that normalization may produce a decoded text with fewer than a UTF-8 encoded octets, or more than b UTF-8 encoded octets. Raises Failure if the normalized result requires more than Sys.max_string_length UTF-8 encoded octets.

If the encoded value has indefinite length, then CBOR events are only consumed from the input stream while the total number of octets does not exceeed b.

Aggregate Values
val tag : int64 Annot.form t

A parser that recognizes a CBOR tag number.

val start : [< `Octets | `Text | `Array | `Map ] -> unit Annot.form t

Use start s to make a parser that recognizes the start of an indefinite length sequence of the form s. What follows in a valid CBOR event stream depends on the form accordingly:

  • `Octets: a sequence of definite length octet values.
  • `Text: a sequence of definite length text values.
  • `Array: a sequence of CBOR values, each of arbitrary form.
  • `Map: a sequence of CBOR key-value pairs, where keys and values are both of arbitrary form.

All indefinite length sequences in a valid CBOR event stream are terminated by a break value.

val group : ?a:int -> ?b:int -> [< `Array | `Map ] -> 'a t -> 'a Annot.form t

Use group ?a ?b g p to make a parser that recognizes a group comprising, according to g, either a CBOR array or a CBOR map with content recognized by p.

If the encoded group is definite length, then the input stream provided to p is limited to the events comprising the content, and no result from p is recognized unless it consumes all its input. If the encoded content is indefinite length, then the result is only recognized if a break event follows the content.

If ~a is used, then it specifies the minimum number of elements in the group. In the case of a map, each group element is a key-value pair. If ~b is used, then it specifies the maximum number of elements in the group. The default value of ~a is zero and the default value of ~b is Sys.max_array_length.

Composing raises Invalid_argument if a < 0, b < a or b > Sys.max_array_length. If the encoded value has indefinite length, then the input stream provided to p is limited to the events comprising the first b array elements (or map key-value pairs) in the group.

Parsing raises Bad_syntax if a break event appears in the content of a definite length array or map, or after a key in map content, or if an indefinite length group is not terminated by a break event.

Opaque Types
module Opaque : sig ... end

A submodule containing logic for parsing CBOR messages to values of type Cf_type.opaque according to optional mode selectors.

Abstract Data Ingestion
module Ingest : sig ... end

The data ingestor module specialized for CBOR encoded octet streams.

(4 Obsolescent

}

The following interfaces are obsolescent with attributes noting their preferable alternatives. They may be removed in a future revision.

An opaque value decode created by Opaque.value with default mode.

  • deprecated Use Opaque.value instead!
module Record_obsolescent : sig ... end

This module provides an adaptation of the

module Record = Record_obsolescent
module Int_map : Record_obsolescent.Profile with type index := int

A record module with integer indexes.

module String_map : Record_obsolescent.Profile with type index := string

A record module with text indexes.