binr

0.0.4 • Public • Published

NPM version Build Status Coverage Status Dependency Status

BINR

Reading binary files with style

Join the chat at https://gitter.im/ahom/binr

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 is aimed 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

License

MIT © Antoine Hom

Versions

Current Tags

  • Version
    Downloads (Last 7 Days)
    • Tag
  • 0.0.4
    1
    • latest

Version History

  • Version
    Downloads (Last 7 Days)
    • Published
  • 0.0.4
    1
  • 0.0.3
    0
  • 0.0.2
    0
  • 0.0.1
    0

Package Sidebar

Install

npm i binr

Weekly Downloads

1

Version

0.0.4

License

MIT

Last publish

Collaborators

  • ahom