This module implements a macro to create binary parsers. The parsers generated reads from a Stream and returns a tuple with each named field. The general format the macro takes is:
[type]<size>: <name>[options]
Where optional fields are in [] brackets and required fields are in <> brackets. Each field has separate meanings, as described in the table below:
| Name | Description |
| type | This is the type of value found in this field, if no type is
specified then it will be parsed as an integer. Supported types
are u to get unsigned integers, f for floating point,
s for strings, and * for custom parser. |
| size | The size, in bits, of the field to read. For uint and int values from 1 to 64 inclusive are supported. For floats only 32 and 64 are supported. Strings use this field to specify the amount of characters to read into the string. If they don't specify a size they will be read to the first NULL byte (this only applies to strings). When the custom parser type is specified the size field is used to name the custom parser procedure. |
| name | The name of the value, this will be used as the name in the
resulting tuple. If the value doesn't need to be stored one can
use _ as the name and it will not get a field in the result. |
| options | These will change the regular behaviour of reading into a field. Since they are so different in what they do they are described below instead of in this table. |
Many binary formats include special "magic" sequences to identify the file
or regions within it. The option = <value> can be used to check if a
field has a certain value. If the value doesn't match a MagicError is
raised. Value must match the value of the field it checks. When the field is
a string type the exact length of the magic string is read, to include a
terminating NULL byte use \0 in the string literal.
To read more fields of a certain kind into a sequence you can use the option
[[count]] (that is square brackets with an optional count inside). If no
count is specified and the brackets left empty it must be the last field or
the next field needs to be a magic number and will be used to terminate the
sequence. If it is the last field it will read until the end of the stream.
As count you can use the name of any previous field, literals, previously
defined variables, or a combination. Note that all sequences are assumed to
terminate on a byte border, even if given a statically evaluatable size.
Another thing commonly found in binary formats are repeating blocks or
formats within the format. These can be read by using a custom parser.
Custom parsers technically supports any procedure that takes a Stream as the
first argument, however care must be taken to leave the Stream in the correct
position. You can also define the inner format with a parser from this module
and then pass that parser to the outer parser. This means that you can easily
nest parsers. If you need values from the outer parser you can add parameters
to the inner parser by giving it colon expressions before the body (e.g the
call createParser(list, size: uint16) would create a parser
proc (stream: Stream, size: uint16): <return type>). To call a parser
use the * type as described above and give it the name of the parser and
any optional arguments. The stream object will get added automatically as the
first parameter.
When creating a parser you get a tuple with two members, get and put
which is stored by a let as the identifier given when calling createParser.
These are both procedures, the first only takes a stream (and any optional
arguments as described above) and returns a tuple containing all the fields.
The second takes a stream and a tuple containing all the fields, this is the
same tuple returned by the get procedure and writes the format to the
stream.
Example:
In lieu of proper examples the binaryparse.nim file contains a when
isMainModule() block showcasing how it can be used. The table below
describes that block in a bit more detail:
| Format | Description |
u8: _ = 128 |
Reads an unsigned 8-bit integer and checks if it equals 128 without storing the value as a field in returned tuple |
u16: size |
Reads an unsigned 16-bit integer and names it
size in the returned tuple |
4: data[size*2] |
Reads a sequence of 4-bit integers into a data
field in the returned tuple. Size is the value read
above, and denotes the count of integers to read. |
s: str[] |
Reads null terminated strings into a str field in
the returned tuple. Since it's given empty brackets
the next field needs to be a magic field and the
sequence will be read until the magic is found. |
s: _ = "9xC\0" |
Reads a non-null terminated string and checks if it equals the magic sequence. |
*list(size): inner |
Uses a pre-defined procedure list which is called
with the current Stream and the size read
earlier. Stores the return value in a field inner
in the returned tuple. |
u8: _ = 67 |
Reads an unsigned 8-bit integer and checks if it equals 67 without storing the value. |
This file is automatically generated from the documentation found in
binaryparse.nim. Use nim doc2 binaryparse.nim to get the full documentation.