package orsetto

Private representation of the size requirement of a decoded value.

Private representation of the stream position of a decoded value.

Scanning raises Incomplete (s, n) when a finite octet stream terminates and at least n more octets are required in the working slice s before a value can be decoded.

Scanning raises Invalid (p, s) to indicate the stream position p of the first octet encountered where decoding is not valid, with a diagnostic message s to describe the validation error.

Private representation of an analysis result, comprising a non-negative count of the encoded octets and the structural analysis value.

Use analyze have need x to make a structural analysis result, where have is the size of the current slice of working octets, need is the total number of octets from the analyzed structure of octets in the working slice that decode to the next value, and x is the structural analysis of the octets, which is provided to the rd function in the scheme.

Using analyze have need, i.e. without applying x, raises Incomplete if need > have, otherwise it returns with a unary constructor for the structural analysis.

Raises Invalid_argument if either have or need is negative. A scanner raises Failure if an analysis result indicates that need is less than the minimum required octets for the decoding scheme.

Use invalid p m in a decoding scheme function with the position p in the octet vector where the first invalid octet is located, and a diagnostic message m, to signal a validation error in decoding by raising an internal exception caught by the scanner class (see below).

Use advance i pos in check functions to advance pos by i positions. Raises Invalid_argument if i < 0.

The type of a decoding scheme for values of the associated type.

Use scheme sz ck rd to make a decoding scheme for values that require sz or more octets to encode, are validated by applying ck s p n for the n octets in s starting at p to produce an analysis x, then by applying rd s x for decoding the octets in s according to x as the scanned value.

Raises Invalid_argument if sz < 0.

The nil scheme. Scans no octets.

The position scheme. Scans no octets, produces the current position.

The any octet scheme. Scans exactly one octet.

Use sat f to make a decoding scheme that scans exactly one octet and produces it if it satisfies the predicate f, otherwise raises Invalid.

Use lit s to make a decoding scheme that scans a sequence of octets required to be equal to s.

Use opaque n to make a decoding scheme that scans n octets to produce a string value comprising those octets.

Raises Invalid_argument if n < 0.

Use fixed_width sz rd to make a decoding scheme for values that can be decoded from some sequences of exactly sz octets by applying rd to the working slice vector and its start index. The rd function may use invalid pos s where no valid decoding of the sequence exists.

Use valid_fixed_width sz rd to make a decoding scheme for values that always can be decoded from any sequence of exactly sz octets by applying rd to the working slice vector and its start index. Compare with fixed_width which provides an index of type position suitable for use with the invalid function.

Use ign s to make a decoding scheme that scans a value according to s and ignores the octets comprising it.

Use opt s to make a decoding scheme for optional values, i.e. if octets scanned are valid for s, then decodes Some v according to s, else if the octets are not valid, then decodes None.

Use pair a b to make a decoding scheme for pairs of values, which decodes its first value according to a and its second according to b.

Use triple a b c to make a decoding scheme for triples of values, which decodes its first value according to a, its second according to b, and its third value according to c.

Use vec n s to make a decoding scheme for fixed-length vectors of n values, with each element decoded according to s.

Raises Invalid_argument if n < 0.

Use seq s to make a deconding scheme for variable-length sequences of values decoded according to s. Use ~a to specify a minimum number of elements to decode. Use ~b to specify a maximum number of elements to decode. Stops decoding if encounters an invalid element according to s. Raises Invalid_argument if a is less than zero or b is less than a.

Use map f s to make a decoding scheme that applies f to each value decoded according to s to map the value into its corresponding type. The function f may call invalid if the map is not injective.

Use ntyp n s to create decoding scheme that encloses the value decoded by s in an untyped value with the type indicated by n. It is a convenient and efficient shortcut for map (fun _ -> Cf_type.witness n) s.

Use this monad to compose decoding schemes where intermediate values scanned earlier in the octet stream are used to select decoding schemes for the values scanned later in the stream.

Use of_string octets scheme to decode the octets octets according to the scheme scheme, to return either Some v, if s comprises the complete encoding of v, or otherwise returns None.

Use of_slice octets scheme to decode the octets octets according to the scheme scheme, to return either Some v, if s comprises the complete encoding of v, or otherwise returns None.

The class of imperative octet stream scanners. Use new scanner () to make a basic scanner object that can progressively decode values from a working slice of octets. Use inherit scanner () to derive a subclass that implements more refined behavior by overriding private methods to manipulate the working slice and the cursor position. Use the ~start parameter to initialize the starting position counter to a number other than zero. (See documentation below for the various private members.)

Use string_scanner ?start s to make a scanner that decodes values progressively from the string s and raises Incomplete when the remaining octets in the string are insufficient to decode a value. Use the ~start parameter to initialize the starting position to a number other than zero.

Use slice_scanner ?start sl to make a scanner that decodes values progressively from the string slice sl and raises Incomplete when the remaining octets in the slice are insufficient to decode a value. Use the ~start parameter to initialize the starting position to a number other than zero.

Use chars_scanner ?limit s to make a scanner that decodes values progressively from the character sequence s. Use ~limit to make the scan method raise Failure if the size requirement for a scanned value is larger than limit. Raises Incomplete when the end of the sequence is reached and the remaining octets are insufficient to decode a value. Use the ~start parameter to initialize the starting position to a number other than zero.

Use channel_scanner ?limit c to make a scanner that decodes values progressively from the input channel c. Use ~limit to make the scan method raise Failure if the size requirement for a scanned value is larger than limit. Raises Incomplete when the end of the file is reached and the remaining octets are insufficient to decode a value. Use the ~start parameter to initialize the starting position to a number other than zero.

Use scanner_to_vals sxr s to make a contextually limited volatile sequence enclosing sxr, which produces each progressive application of sxr#scan s. The sequence terminates when the scan method raises Incomplete with an empty working slice.

Use string_to_vals ?start sch str to make a concurrently persistent sequence of values decoded progressively from str according to sch. Consuming raises Invalid or Incomplete as necessary. The sequence terminates if no values can be decoded according to sch with an empty slice and the end of str is reached. If ~start is provided then it specifies the starting position of the first octet in str. Otherwise, the starting position is zero.

Use slice_to_vals ?start sch sl to make a concurrently persistent sequence of values decoded progressively from sl according to sch. Consuming raises Invalid or Incomplete as necessary. The sequence terminates if no values can be decoded according to sch with an empty slice and the end of sl is reached. If ~start is provided then it specifies the starting position of the first octet in sl. Otherwise, the starting position is zero

Use chars_to_vals ?start ?limit sch seq as an abbreviation for scanner_to_vals sch (chars_scanner ?start ?limit seq).