laymanshex/README

LaymansHex
==========

LaymansHex takes a (partial) file description and allows tinkering with
the values in a binary file. It thus serves as a sort of layman's
hex editor.


File description format
-----------------------

In EBNF:
```
description =
  { comment }
  endianness
  definition
  { definition }
.

comment = '#' { LETTER | DIGIT } '\n'.

endianness = ("little endian" | "big endian") '\n'.

definition = [ IDENT ] ':' type '\n'.

type = bytefield
  | "int8"    | "int16"  | "int32"  | "int64"
  | "uint8"   | "uint16" | "uint32" | "uint64"
  | "float32" | "float64"
.

bytefield = "byte[" size "]".

size = INTEGER | ( IDENT [ "*" INTEGER ]).
```

The identifier of a definition line can be left empty to ignore that particular value.
Portions of the binary file not covered by the file description are ignored. Byte field
size can be variable - the specific value then needs to be set at program invocation (via -fvar).


Usage
-----

To get values: `laymanshex FORMATFILE BINARY`

To set values: `laymanshex -set "key1=value1,key2=value2" FORMATFILE BINARY`

To set a variable 'offset' to 113 in the file description and get values: `laymanshex -fvar="offset=113" FORMATFILE BINARY`

Examples of format descriptions can be found in the [laymanshex-files repo](/laymanshex-files/).


Advanced
--------

The variable byte field size allows to script around laymanshex and use a sliding frame
to obtain sequences. E.g. you can define a partial file format that only covers one
element of the sequence at a certain offset:

```
little endian
      : byte[offset*32]
value : int32
```

Script:

```
#/bin/bash

for i in `seq 99`; do
  laymanshex -fvar="offset=$((i*4))" FORMATFILE BINARY
done
```

If your sequence ends with a marker, add that marker to the file description and check
its value after each invocation of laymanshex.