Authors

Requirements

API

Basic syntax description

Patterns description

Read byte from stream and bind to varaible NAME or compare with immediate value if name not a symbol name. Supported immediate values types: integer char string

(NAME BITS)

Read n-BITS big endian unsigned integer, bind-or-compare to NAME.

(NAME BITS big)

(NAME BITS big signed)

(NAME BITS big unsigned)

(NAME BITS little)

Read n-BITS little endian unsigned integer, bind-or-compare to NAME.

(NAME BITS little signed)

(NAME BITS little unsigned)

(NAME BITS host)

Read n-BITS unsigned integer using system byte-order, bind-or-compare to NAME.

(NAME BITS host signed)

(NAME BITS host unsigned)

(NAME 16 float)

Read ieee-754 floating point half-precision, bind-or-compare to NAME.

(NAME 32 float)

Read ieee-754 floating point single precision, bind-or-compare to NAME.

(NAME float)

Read single precision floating point, bind-or-compare to NAME.

(NAME double)

Read double precision floating point, bind-or-compare to NAME.

(NAME BITS bitstring)

Read raw BITS from stream, bind-or-compare to NAME.

(NAME bitstring)

Greedy read, consume all available bits.

()

Empty bitstring

(PACKET-NAME bitpacket)

Read a packet defined by the (bitpacket PACKET-NAME ...) declaration. Bind each packet field to current lexical scope. !!! bitpacket is an experimental feature !!!

(check EXPRESSION)

user guard EXPRESSION. Matching will continue only when this evaluates to a true value.

Matching inputs against bit patterns

[syntax](bitmatch binary-data patterns-list else-guard)

Match binary-data against the patterns from patterns-list.

binary-data may be a bitstring object or a value of any of the following data types: u8vector, string or regular vector.

If nothing matches and an else-guard clause was not specified, an exception of type bitstring-match-failure is raised.

Else guard is optional.

Constructing bitstrings from input based on bit patterns

[syntax](bitconstruct pattern)

Construct bitstring based on pattern. The pattern will construct the bitstring from identifiers taken from the current lexical scope.

If nothing matches an exception of type bitstring-match-failure is raised.

Supports special pattern for concatenating bitstrings.

((EXPRESSION ...) bitstring)

EXPRESSION should evaluate to bitstring during constructing.

Defining custom bitstring forms

[syntax](bitpacket PACKET-NAME fields ...)

Define well-known set of fields. Fields syntax the same as bitmatch pattern syntax.

Dealing with bitstring objects

Bitstring objects represent strings of bits of arbitrary length. This means they can store any number of unaligned bits, rather like bitfields in C. Bitfields can also share memory with other bitfields, which means you can easily create sub-bitstrings from other bitstrings.

[procedure](bitstring=? bitstring1 bitstring2)

Compare bitstrings.

[procedure](bitstring->list bitstring [bits [byte-order]])

Convert bitstring to list of bits.

Optional group bits, default value 1, indicates how many bits each entry in the list should span. For example, to see the contents grouped by octet, use 8 here.

Optional byte-order'little - little-endian, 'big - big-endian, 'host host system byte-order, default value 'big. This has an effect only if bit is larger than 8.

[procedure](bitstring? obj)

Returns #t or #f depending on whether obj is a bitstring or another type of object.