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.
[](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