binary-parser

Binary-parser

Binary-parser is a parser builder library for node, which enables you to write efficient binary parsers in a simple & declarative way. It supports all common data types required to parse a structured binary data, such as integers, bit fields, floating point numbers, strings, arrays (both fixed length and variable length), etc. Binary-parser dynamically generates and compiles the parser code on-the-fly.

This library's features are inspired by BinData , its syntax by binary.

Installation

In your project's directory, execute:

$ npm install binary-parser

Quick Start

First create an empty Parser object with new Parser(), then chain methods to build the desired parser. Calling Parser.parse with an Buffer object returns the result object.

var Parser = require('binary-parser').Parser;

var keyValue = new Parser()
    .int32le('key')
    .int16le('length')
    .string('message', {length: 'length'});

var parser = new Parser()
    .uint16le('count')
    .array('kvs', {
        type: keyValueParser,
        length: 'count'
    })

parser.parse(buffer);
    

API

new Parser()

Constructs a Parser object. Returned object represents a parser which parses nothing.

parse(buffer[, callback])

Parse a Buffer object buffer with this parser and return the resulting object. When parse(buffer) is called for the first time, parser code is compiled on-the-fly and internally cached.

If parser's async option is true, then a callback function has to be passed as an argument. This callback should take two arguements like other node.js callbacks: function(err, result).

[u]int{8, 16, 32}{le, be}(name [,options])

Parse bytes as an integer and store it in a variable named name. name should consist only of alphanumeric characters and start with an alphabet. Number of bits can be chosen from 8, 16 and 32. Byte-ordering can be either l for litte endian or b for big endian. With no prefix, it parses as a signed number, with u prefixed as an unsigned number.

var parser = new Parser()
	// Signed 32-bit integer (little endian)
    .int32le('a')
    // Unsigned 8-bit integer (little/big endian)
    .uint8('b')
    // Signed 16-bit integer (big endian)
    .int16be('c')

bit[1-32](name [,options])

Parse bytes as a bit field and store it in variable name. There are 32 methods from bit1 to bit32 each corresponding to 1-bit-length to 32-bits-length bit field.

{float, double}{le, be}(name [,options])

Parse bytes as an floating-point value and store it in a variable named name. name should consist only of alphanumeric characters and start with an alphabet.

string(name [,options])

Parse bytes as a string. name should consist only of alpha numeric characters and start with an alphabet. options is an object; following options are available:

• encoding - (Optional, defaults to utf8) Specify which encoding to use. 'utf8', 'ascii', 'hex' and else are valid. See Buffer.toString for more info.
• length - (Required) Length of the string. Can be a number, string or a function. Use number for statically sized arrays, string to reference another variable and function to do some calculation.
• zeroTerminated - (Optional, defaults to false) If true, then this parser reads until it reaches zero.

buffer(name [,options])

Parse bytes as a string. name should consist only of alpha numeric characters and start with an alphabet. options is an object; following options are available:

• clone - (Optional, defaults to false) By default, buffer(name [,options]) returns a new buffer which references the same memory as the parser input, but offset and cropped by a certain range. If this option is true, input buffer will be cloned and a new buffer referncing another memory is returned.
• length - (either length or readUntil is required) Length of the buffer. Can be a number, string or a function. Use number for statically sized buffers, string to reference another variable and function to do some calculation.
• readUntil - (either length or readUntil is required) If 'eof', then this parser will read till it reaches end of the Buffer object.

array(name [,options])

Parse bytes as an array. options is an object; following options are available:

• type - (Required) Type of the array element. Can be a string or an user defined Parser object. If it's a string, you have to choose from [u]int{8, 16, 32}{le, be}.
• length - (either length or readUntil is required) Length of the array. Can be a number, string or a function. Use number for statically sized arrays.
• readUntil - (either length or readUntil is required) If 'eof', then this parser will read till it reaches end of the Buffer object.

var parser = new Parser()
	// Statically sized array
	.array('data', {
		type: 'int32',
		length: 8
	})
	
	// Dynamically sized array (reference another variable)
	.uint8('dataLength')
	.array('data2', {
		type: 'int32',
		length: 'dataLength'
	})
	
	// Dynamically sized array (with some calculation)
	.array('data3', {
		type: 'int32',
		length: function() { return this.dataLength - 1; } // other fields are available through this
	});
	
	// Use user defined parser object
	.array('data4', {
		type: userDefinedParser,
		length: 'dataLength'
	})

choice(name [,options])

Choose one parser from several choices according to a field value. Combining choice with array is useful for parsing a typical Type-Length-Value styled format.

• tag - (Required) The value used to determine which parser to use from the choices Can be a string pointing to another field or a function.
• choices - (Required) An object which key is an integer and value is the parser which is executed when tag equals the key value.
• defaultChoice - (Optional) In case of the tag value doesn't match any of choices use this parser.

var parser1 = ...;
var parser2 = ...;
var parser3 = ...;

var parser = new Parser()
	.uint8('tagValue')
	.choice('data', {
		tag: 'tagValue',
		choices: [
			1: parser1, // When tagValue == 1, execute parser1
			4: parser2, // When tagValue == 4, execute parser2
			5: parser3  // When tagValue == 5, execute parser3
		]
	});

nest(name [,options])

Nest a parser in this position. Parse result of the nested parser is stored in the variable name.

• type - (Required) A Parser object.

skip(length)

Skip parsing for length bytes.

endianess(endianess)

Define what endianess to use in this parser. endianess can be either 'little' or 'big'. After this method is called, you can omit endianess postfix from primitive parsers.

var parser = new Parser()
	// usually you have to specify endianess explicitly
	.uint16be('a')
	.endianess('big')
	// you can omit le/be after endianess is called
	.uint16('b')
	.int32('c')

compile()

Compile this parser on-the-fly and chache its result. Usually, there is no need to call this method directly, since it's called when parse(buffer) is executed for the first time.

getCode()

Dynamically generates the code for this parser and returns it as a string. Usually used for debugging.

Common options

These are common options that can be specified in all parsers.

• assert - A predicate function. You can do assertions during the parsing (useful for checking magic numbers and so on). This assertion function should take one argument, which is the parsed result, and return true if assertion successes or false when assertion fails. An exception is thrown during the parsing when assertion fails.

  var ClassFile =
  	Parser.start()
      .endianess('big')
      .uint32('magic', {assert: function(x) {return x === 0xcafebabe; }})
  

• async - If true, then this parser will be executed asynchronously. You also have to pass a callback function to Parser.parse(buffer, callback).

Examples

See example for more complex examples.

Support

Please report issues to the issue tracker if you have any difficulties using this module, found a bug, or request a new feature.

Pull requests with fixes and improvements are welcomed!

License

The MIT License (MIT)

Copyright (c) 2013 Keichi Takahashi [e-mail]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.