njh/binmark-js

Markup language and tool for generating binary files

binmark.js

binmark is a markup language and JavaScript library for describing binary files, that is easier to read and write than a continuous stream of hexadecimal characters.

The following characters are supported:

Character	Description
0-9 and a-f	A byte as hexadecimal. Must be two characters long.
Whitespace	Ignored
Colon or Dash	Ignored - useful for improving readability
.nnn	A 8-bit decimal integer
""	A string of ASCII characters
#	The start of a comment - the rest of the line is ignored
\	Escape sequences (\0 \a \b \f \n \r \t \v)

Example

Given the following sample input file, which is reasonably easy read:

30             # Packet Type 3: Publish
.17            # Remaining length (17 bytes)
0004           # Topic name length
"test"         # Topic name
"hello world"  # Payload

But why?

I created binmark after my test cases, when writing test cases for my Arduino IPv6 Library, EtherSia, started resulting in long strings of hexadecimal characters in my code. I decided that these would be better in seperate external files and realised that I had the freedom to decide on the file format, to make them easier to read and write.

A long stream of hexadecimal is difficult to both read and write - particularly picking out the different fields and sections. By adding some whitespace, punctuation and comments, it is much easier.

Possible uses:

• Describing expected data for automated tests
• Creating new file formats before tools to generate them exist
• Documenting a data structure in a human readable way
• Alternative to a using a hex editor

Design Decisions

This was my thought process while designing binmark:

• Readable and concise to write for humans
• Simple for a machine to parse and convert
• Streamable - don't require input to be loaded into a buffer more parsing
• ASCII input - try and avoid potential weird character-set problems
• Not so complex that there wouldn't be other implementations in other languages

Other Languages

• C/C++: https://github.com/njh/binmark

License

binmark is licensed under the terms of the MIT license. See the file LICENSE for details.

Contact

• Author: Nicholas J Humfrey
• Twitter: @njh

binmark-js's Issues

Add support for a steaming API?

How important is this?
Is anyone really generating large binmark documents?

• https://web.dev/streams/

Add support for octal \010

Keep track of line and character position for easier debugging

Add support for returning a Uint8Array

parseUint8Array() ?

Or should it be able to return other types too?