HexSpec

A spec for verifying byte buffers

Example

; Simple Open Framing Header
sofh:
.length:        0000003F          ; SOFH message length
.sig:           EB50              ; SOFH Encoding SBE little endian

; Simple Binary Encoding Header
sbe:
.length:        3700              ; SBE Block Length
.template:      6300              ; SBE Template ID
.schema:        5B00              ; SBE Schema ID
.version:       0000              ; SBE Schema Version

; Single Order
single_order:
.cl_ord_id:     @"ORD00006"
.account:       @"ACCT96\0\0"
.symbol:        @"GEM1" 0000
.side:          32                ; encoded for Sell
.transact:      0000000000000000  ; 1970-1-1T00:00:00.000Z Too lazy to put value here
.order_qty:     05000000          ; 5
.ord_type:      31                ; Market
.price:         @ql(100500)       ; 100.500 (fixed point 3 digits)
.stop_px:       0000000000000000  ; Null
.exec_inst:     04                ; Not Held

comments start with a ; and last to the end of a line

labels may begin a line and are postfixed with : and describe

relative labels start with a . and are associated with a non relative label (absolute labels)

._: and _: unset relative labels and absolute labels respectively

sequences that start with @ are known as interprets and may come in many forms.

All other tokens are hex bytes. Stray nibbles (a single hex code/half a byte) maybe not be left on a line.

Usage

Rust Api

#[test]
fn some_spec() {
  let spec = HexSpec::load(&PathBuf::from("some_spec.hexspec")).unwrap();
  let some_buffer = todo!();

  spec.validate(&some_buffer);
}

Cli support

Byte generator

Hexspec can be used to describe a byte buffer in a human readable way.

hexspec bytes -f sample.hexspec -o sample.bin

will generate the bytes described by sample.hexspec and put them into sample.bin

Verfy

Hexspec was made to verify byte buffers and you can do that on the command line.

hexspec verify -f sample.hexspec -i sample.bin

Fmt

hexspec has a default format

# format a hexspec stream
cat sample.hexspec | hexspec fmt

# format a hexspec file
hexspec fmt -w sample.hexspec

Editor Support

There is a vim plugin for syntax support in /editors/vim

lib.rs:

A library/language for testing hex based byte buffers