bindef

bindef is a DSL and command-line tool for building binary files.

It's inspired by t2b, but with a few crucial differences:

• bindef scripts run within a Ruby process, making the DSL a strict superset of Ruby
• Support for different (and multiple!) endians, string encodings, etc, is baked into the language
• Reports common mistakes loudly as warnings (or errors, if severe enough)
• Comes with a collection of user-selectable extensions for common binary formats (TLVs, control codes, etc.)

bindef's syntax is stream-oriented, with two primary expressions: commands and pragmas.

Commands cause bindef to emit data, while pragmas influence how commands act.

Here's a simple bindef script that emits a unsigned 32-bit integer twice, in different endians:

# `bindef` starts in little-endian, so this is redundant
pragma endian: :little

u32 0xFF000000

# or `pragma :endian => :big`, if you prefer
pragma endian: :big

u32 0xFF000000

The example directory has more. Read the SYNTAX file for a complete listing of commands and pragmas.

bindef is available via RubyGems:

$ gem install bindef
$ bd -h

You can also run it directly from this repository:

$ ruby -Ilib ./bin/bd -h

In general, running a bindef script is as simple as:

$ bd < path/to/input.bd > path/to/output.bin

or:

$ bd -i path/to/input.bd -o /path/to/output.bin

You can also choose to enable one or more extra command sets via the -e, --extra flag:

# extra commands for building TLVs
$ bd -e tlv < input.bd > output.bin

# extra commands for ASCII control codes and string manipulation
$ bd -e ctrl,string < input.bd > output.bin

bindef should...

• ...have no runtime dependencies other than the current stable Ruby
• ...be easy to read, even without knowledge of Ruby's syntax
• ...be easy to write, even without knowledge of Ruby's syntax
• ...be easy for other programs to emit without being (too) aware of Ruby's syntax
• ...be easy to debug, with warnings and errors for common mistakes (overflows, negative unsigned integers, etc.)