BINR

Reading binary files with style

Features

Define your structs as readable code
Read files as big as you want
Selectively read in a lazy manner big arrays/objects
Dig into the parsing of your structs with stack traces

This library aims at providing a simple and extensible way to read binary files while giving full informations about read operations and failures.

Roadmap

Add Int64 support
Add step by step reading
Write web hex editor focused on reverse enginnering

Contributions

You want to contribute? Perfect!

Do not hesitate to create issues/pull requests or come talk on gitter!

Install

$ npm install --save binr

Requirements

The following features from ES6 are needed in order for this library to work:

Generators
Promises

In order to use it on node.js you need to launch it with the following command:

$ node --harmony-generators

Usage

Include the library

var binr = require('binr');

Define your struct

var t = binr.types;
var struct = function* () {
  return {
    magic: yield this.read_with_args(t.bytes)(4),
    major: yield this.read(t.uint16),
    minor: yield this.read(t.uint16)
  };
};

Read it!

var data = [
  0x01, 0x02, 0x03, 0x04, // magic
  0x02, 0x00,             // major
  0x01, 0x00              // minor
];

binr.read(struct, data).then(function (result) {
  console.log('Yay! It worked!');
  console.log(result);
}).catch(function (error) {
  console.log('Oh noes! A boo-boo!');
  console.log(error);
});

> Yay! It worked!
{
  magic: { '0': 1, '1': 2, '2': 3, '3': 4 },
  major: 2,
  minor: 1
}

Fetch the stack trace!

binr.trace_read(struct, data).then(function (result) {
  console.log('Yay! It worked!');
  console.log(result);
}).catch(function (error) {
  console.log('Oh noes! A boo-boo!');
  console.log(error);
});

> Yay! It worked!
{ parent: null,
  type: { func: [Function], args: {} },
  offset: 0,
  value: { magic: { '0': 1, '1': 2, '2': 3, '3': 4 }, major: 2, minor: 1 },
  size: 8,
  children:
   [ { parent: [Circular],
       type: [Object],
       offset: 0,
       value: [Object],
       size: 4,
       children: [] },
     { parent: [Circular],
       type: [Object],
       offset: 4,
       value: 2,
       size: 2,
       children: [] },
     { parent: [Circular],
       type: [Object],
       offset: 6,
       value: 1,
       size: 2,
       children: [] } ] }

Create a js file to use in browsers!

# creates a binr.js
$ npm run browser

ahom/binrjs