Skip to content

Latest commit

 

History

History
118 lines (86 loc) · 4.72 KB

README.md

File metadata and controls

118 lines (86 loc) · 4.72 KB
Raw

∆ corrode

MIT license NPM version dependencies coverage build status docs

Corrode is a batteries-included library for reading binary data. It helps you converting that blob-mess into useable data.

Use it to parse that one obscure binary-file with the help of JavaScript.

Install

$ npm install --save corrode

Tests

$ npm test

Offline Docs

$ npm run docs
$ open doc/index.html

What's this?

corrode provides standard read-actions like uint8-uint64 for big & little endian, strings, buffers and control-structures like loops, skipping, etc. for your buffers and files. Additionally you can use assertions to always be sure, the data you parse corresponds to a specified format. The parsing is done not by a configuration-object, but by imperative code, allowing for far greater flexibility.

corrode is an abstraction on top of TransformStream and as such is pipeable to but also provides functions for more simple usage.

This library is not only heavily inspired by dissolve, it in fact can be seen as a total rewrite with even more features. The code is written in ES7, fully documented and tested.

Quick examples

const Corrode = require('corrode');
const parser = new Corrode();

parser
    .uint8('val_1')
    .uint32('val_2')
    .int16be('val_3')
    .tap(function(){
        console.log(this.vars.val_1 * this.vars.val_3);
    })
    .repeat('array', 5, function(){
        this
            .uint32('array_val_1')
            .string('array_val_4', 5);
    });

Parsing a buffer

parser.fromBuffer(buffer, () => console.log(parser.vars));

Parsing a filestream

var stream = fs.createReadStream(file);
stream.pipe(parser);
parser.on('finish', () => console.log(parser.vars));

These are just some of the very basic operations supported by Corrode.

Examples

All examples can be found in the examples/-folder. Included:

  • ID3v2.3-Parser - strict, unforgiving parser for a subset of the standard used to store meta-data in mp3-files. It needs npm i image-to-ascii temp and can be run with node examples/id3 test.mp3.

If you'd like to include your own examples, just open a PR. I'm more than happy to not have to think about existing complex structured binary data to parse myself.

Documentation & API Reference

Why use corrode over dissolve

It solves most of the major shortcomings dissolve has:

  • EOF terminates corrode. If not explicitly asked not to do so it will give you all variables, without you having to fiddle with its intestines.
  • Loops get unwinded correctly.
  • Thoroughly tested.
  • As a js-library from 2016 it has all the swag you need.

When not to use corrode

  • Your data is too complex - If you need to apply black magic on your data, to retrieve meaningful values, corrode currently may not support your use-case.
  • Your data is really simple - If you don't need to read structured data, but instead just numbers or strings you should simply use the built-in read-functions provided by Buffer.

Not yet included are additions like bignum-support for int64 and additional non-node-standard-encodings.

corrode also works in browsers. You will need a setImmediate() polyfill, but you're able to parse ArrayBuffers as usual.

Used dependencies (3)

The following dependencies are installed when installing corrode:

  • bl - used for buffering data, in case a job gets greedy or you don't want to auto-flush
  • readable-streams - ensures consistent and stable behaviour of the underlying Transform-Stream
  • lodash - several utility functions

License

This library is issued under the MIT license.

The Logo is from The Noun Project, created by Michael Senkow and licensed under the CC-BY-3.0.