Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 139 lines (101 sloc) 3.378 kB
11b5c60 @substack rebranded as binary
authored
1 Binary
2 ======
9ebc04e @substack readme woo
authored
3
4 Unpack multibyte binary values from buffers and streams.
5 You can specify the endianness and signedness of the fields to be unpacked too.
6
1e33146 @substack buf.js example
authored
7 This module is a cleaner, faster, and more complete version of
8 [bufferlist](https://github.com/substack/node-bufferlist)'s binary module that
9 runs on pre-allocated buffers instead of a linked list.
10
11 Examples
12 ========
13
14 buf.js
15 ------
16 var buf = new Buffer([ 97, 98, 99, 100, 101, 102, 0 ]);
17
18 var Binary = require('binary');
19 Binary(buf)
20 .word16ls('ab')
21 .word32bu('cf')
22 .word8('x')
23 .tap(function (vars) {
24 console.dir(vars);
25 })
26 ;
27 -
28 $ node buf.js
29 { ab: 25185, cf: 1667523942, x: 0 }
30
d783aa4 @substack stream example
authored
31 stream.js
32 ---------
33
34 var Binary = require('binary');
35 var stdin = process.openStdin();
36
37 Binary(stdin)
38 .word32lu('x')
39 .word16bs('y')
40 .word16bu('z')
41 .tap(function (vars) {
42 console.dir(vars);
43 })
44 ;
45 -
46 $ node examples/stream.js
47 abcdefgh
48 { x: 1684234849, y: 25958, z: 26472 }
49 ^D
50
8464aae @substack readme updates for the methods
authored
51 Methods
52 =======
53
54 Binary(buf)
55 -----------
56
57 Start a new chain parser for a `Buffer`.
58
59 Binary(emitter)
60 ---------------
61 Binary(emitter, eventName='data')
62 ---------------------------------
63
64 Start a new chain parser for an `EventEmitter` for an event name `eventName`,
65 which defaults to `'data'`.
66
9f25d14 @substack updated readme for dotted address keys, package bump
authored
67 word{8,16,32,64}{l,b}{e,u,s}(key)
8464aae @substack readme updates for the methods
authored
68 ----------------------------------
69
70 Parse bytes in the buffer or stream given:
71
01c32c0 @substack silly markdown
authored
72 * number of bits
73 * endianness ( l : little, b : big ),
74 * signedness ( u and e : unsigned, s : signed )
8464aae @substack readme updates for the methods
authored
75
76 These functions won't start parsing until all previous parser functions have run
77 and the data is available.
78
9f25d14 @substack updated readme for dotted address keys, package bump
authored
79 The result of the parse goes into the variable stash at `key`.
80 If `key` has dots (`.`s), it refers to a nested address. If parent container
81 values don't exist they will be created automatically, so for instance you can
82 assign into `dst.addr` and `dst.port` and the `dst` key in the variable stash
83 will be `{ addr : x, port : y }` afterwards.
8464aae @substack readme updates for the methods
authored
84
7735a48 @substack buffer slice in the readme and a package bump
authored
85 buffer(key, size)
86 -----------------
87
88 Take `size` bytes directly off the buffer stream, putting the resulting buffer
89 slice in the variable stash at `key`. If `size` is a string, use the value at
9f25d14 @substack updated readme for dotted address keys, package bump
authored
90 `vars[size]`. The key follows the same dotted address rules as the word
91 functions.
7735a48 @substack buffer slice in the readme and a package bump
authored
92
8464aae @substack readme updates for the methods
authored
93 tap(cb)
94 -------
95
96 The callback `cb` is provided with the variable stash from all the previous
97 actions once they've all finished.
98
a32b25b @substack now with loops!
authored
99 loop(cb)
100 --------
101
102 Loop, each time calling `cb(end, vars)` for function `end` and the variable
103 stash with `this` set to a new chain for nested parsing. The loop terminates
104 once `end` is called.
105
915f99e @substack readme notes, package bump for .parse()
authored
106 Binary.parse(buf)
107 -----------------
108
109 Like `Binary(buf)`, but synchronous so you can parse fields in a single pass.
110 Terminate a chain with `.vars` to get at the result of the parse.
111
9ebc04e @substack readme woo
authored
112 Installation
113 ============
114
115 To install with [npm](http://github.com/isaacs/npm):
116
11b5c60 @substack rebranded as binary
authored
117 npm install binary
9ebc04e @substack readme woo
authored
118
119 To run the tests with [expresso](http://github.com/visionmedia/expresso):
120
121 expresso
1e33146 @substack buf.js example
authored
122
cb56bdc @substack now with flush()
authored
123 flush()
124 -------
125
126 Clear the variable stash entirely.
127
1e33146 @substack buf.js example
authored
128 Notes
129 =====
130
131 The word64 functions will only return approximations since javascript uses ieee
132 floating point for all number types. Mind the loss of precision.
133
134 Todo
135 ====
136
137 * Actually verify that this approach is faster than bufferlist/binary.
138 * Add all the nifty nested parser functions without sacrificing performance.
Something went wrong with that request. Please try again.