binary
======

Unpack multibyte binary values from buffers and streams.
You can specify the endianness and signedness of the fields to be unpacked too.

This module is a cleaner and more complete version of
[bufferlist](https://github.com/substack/node-bufferlist)'s binary module that
runs on pre-allocated buffers instead of a linked list.

[![build status](https://secure.travis-ci.org/substack/node-binary.png)](http://travis-ci.org/substack/node-binary)

examples
========

stream.js
---------

``` js
var binary = require('binary');

var ws = binary()
    .word32lu('x')
    .word16bs('y')
    .word16bu('z')
    .tap(function (vars) {
        console.dir(vars);
    })
;
process.stdin.pipe(ws);
process.stdin.resume();
```

output:

```
$ node examples/stream.js
abcdefgh
{ x: 1684234849, y: 25958, z: 26472 }
^D
```

parse.js
--------

``` js
var buf = new Buffer([ 97, 98, 99, 100, 101, 102, 0 ]);

var binary = require('binary');
var vars = binary.parse(buf)
    .word16ls('ab')
    .word32bu('cf')
    .word8('x')
    .vars
;
console.dir(vars);
```

output:

```
{ ab: 25185, cf: 1667523942, x: 0 }
```

methods
=======

`var binary = require('binary')`

var b = binary()
----------------

Return a new writable stream `b` that has the chainable methods documented below
for buffering binary input.

binary.parse(buf)
-----------------

Parse a static buffer in one pass. Returns a chainable interface with the
methods below plus a `vars` field to get at the variable stash as the last item
in a chain.

In parse mode, methods will set their keys to `null` if the buffer isn't big
enough except `buffer()` and `scan()` which read up up to the end of the buffer
and stop.

b.word{8,16,32,64}{l,b}{e,u,s}(key)
-----------------------------------

Parse bytes in the buffer or stream given:

* number of bits
* endianness ( l : little, b : big ),
* signedness ( u and e : unsigned, s : signed )

These functions won't start parsing until all previous parser functions have run
and the data is available.

The result of the parse goes into the variable stash at `key`.
If `key` has dots (`.`s), it refers to a nested address. If parent container
values don't exist they will be created automatically, so for instance you can
assign into `dst.addr` and `dst.port` and the `dst` key in the variable stash
will be `{ addr : x, port : y }` afterwards.

b.buffer(key, size)
-------------------

Take `size` bytes directly off the buffer stream, putting the resulting buffer
slice in the variable stash at `key`. If `size` is a string, use the value at
`vars[size]`. The key follows the same dotted address rules as the word
functions.

b.scan(key, buffer)
-------------------

Search for `buffer` in the stream and store all the intervening data in the
stash at at `key`, excluding the search buffer. If `buffer` passed as a string,
it will be converted into a Buffer internally.

For example, to read in a line you can just do:

``` js
var b = binary()
    .scan('line', new Buffer('\r\n'))
    .tap(function (vars) {
        console.log(vars.line)
    })
;
stream.pipe(b);
```

b.tap(cb)
---------

The callback `cb` is provided with the variable stash from all the previous
actions once they've all finished.

You can nest additional actions onto `this` inside the callback.

b.into(key, cb)
---------------

Like `.tap()`, except all nested actions will assign into a `key` in the `vars`
stash.

b.loop(cb)
----------

Loop, each time calling `cb(end, vars)` for function `end` and the variable
stash with `this` set to a new chain for nested parsing. The loop terminates
once `end` is called.

b.flush()
---------

Clear the variable stash entirely.

installation
============

To install with [npm](http://github.com/isaacs/npm):

```
npm install binary
```

notes
=====

The word64 functions will only return approximations since javascript uses ieee
floating point for all number types. Mind the loss of precision.

license
=======

MIT