Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 178 lines (128 sloc) 3.948 kb
d712e1a @substack modernize docs
authored
1 binary
11b5c60 @substack rebranded as binary
authored
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
07019ba @substack updated readme with new semantics
authored
7 This module is a cleaner and more complete version of
1e33146 @substack buf.js example
authored
8 [bufferlist](https://github.com/substack/node-bufferlist)'s binary module that
9 runs on pre-allocated buffers instead of a linked list.
10
cb1356b @substack using travis
authored
11 [![build status](https://secure.travis-ci.org/substack/node-binary.png)](http://travis-ci.org/substack/node-binary)
12
d712e1a @substack modernize docs
authored
13 examples
1e33146 @substack buf.js example
authored
14 ========
15
d712e1a @substack modernize docs
authored
16 stream.js
17 ---------
18
19 ``` js
20 var binary = require('binary');
21
22 var ws = binary()
23 .word32lu('x')
24 .word16bs('y')
25 .word16bu('z')
26 .tap(function (vars) {
27 console.dir(vars);
28 })
29 ;
30 process.stdin.pipe(ws);
31 process.stdin.resume();
32 ```
33
34 output:
35
36 ```
37 $ node examples/stream.js
38 abcdefgh
39 { x: 1684234849, y: 25958, z: 26472 }
40 ^D
41 ```
42
5876a65 @substack parse example
authored
43 parse.js
44 --------
503eb8b @substack readme notes about into() and a bump
authored
45
d712e1a @substack modernize docs
authored
46 ``` js
47 var buf = new Buffer([ 97, 98, 99, 100, 101, 102, 0 ]);
5876a65 @substack parse example
authored
48
d712e1a @substack modernize docs
authored
49 var binary = require('binary');
50 var vars = binary.parse(buf)
51 .word16ls('ab')
52 .word32bu('cf')
53 .word8('x')
54 .vars
55 ;
56 console.dir(vars);
57 ```
58
59 output:
d783aa4 @substack stream example
authored
60
d712e1a @substack modernize docs
authored
61 ```
62 { ab: 25185, cf: 1667523942, x: 0 }
63 ```
64
65 methods
8464aae @substack readme updates for the methods
authored
66 =======
67
d712e1a @substack modernize docs
authored
68 `var binary = require('binary')`
69
70 var b = binary()
71 ----------------
72
73 Return a new writable stream `b` that has the chainable methods documented below
74 for buffering binary input.
75
76 binary.parse(buf)
07019ba @substack updated readme with new semantics
authored
77 -----------------
8464aae @substack readme updates for the methods
authored
78
07019ba @substack updated readme with new semantics
authored
79 Parse a static buffer in one pass. Returns a chainable interface with the
80 methods below plus a `vars` field to get at the variable stash as the last item
81 in a chain.
8464aae @substack readme updates for the methods
authored
82
49590ec @substack readme note and a failing test about not enough data for parse mode
authored
83 In parse mode, methods will set their keys to `null` if the buffer isn't big
84 enough except `buffer()` and `scan()` which read up up to the end of the buffer
85 and stop.
86
d712e1a @substack modernize docs
authored
87 b.word{8,16,32,64}{l,b}{e,u,s}(key)
88 -----------------------------------
8464aae @substack readme updates for the methods
authored
89
90 Parse bytes in the buffer or stream given:
91
01c32c0 @substack silly markdown
authored
92 * number of bits
93 * endianness ( l : little, b : big ),
94 * signedness ( u and e : unsigned, s : signed )
8464aae @substack readme updates for the methods
authored
95
96 These functions won't start parsing until all previous parser functions have run
97 and the data is available.
98
9f25d14 @substack updated readme for dotted address keys, package bump
authored
99 The result of the parse goes into the variable stash at `key`.
100 If `key` has dots (`.`s), it refers to a nested address. If parent container
101 values don't exist they will be created automatically, so for instance you can
102 assign into `dst.addr` and `dst.port` and the `dst` key in the variable stash
103 will be `{ addr : x, port : y }` afterwards.
8464aae @substack readme updates for the methods
authored
104
d712e1a @substack modernize docs
authored
105 b.buffer(key, size)
106 -------------------
7735a48 @substack buffer slice in the readme and a package bump
authored
107
108 Take `size` bytes directly off the buffer stream, putting the resulting buffer
109 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
110 `vars[size]`. The key follows the same dotted address rules as the word
111 functions.
7735a48 @substack buffer slice in the readme and a package bump
authored
112
d712e1a @substack modernize docs
authored
113 b.scan(key, buffer)
114 -------------------
0dca8ef @substack spanning scan() now failing
authored
115
116 Search for `buffer` in the stream and store all the intervening data in the
117 stash at at `key`, excluding the search buffer. If `buffer` passed as a string,
118 it will be converted into a Buffer internally.
119
120 For example, to read in a line you can just do:
503eb8b @substack readme notes about into() and a bump
authored
121
d712e1a @substack modernize docs
authored
122 ``` js
123 var b = binary()
124 .scan('line', new Buffer('\r\n'))
125 .tap(function (vars) {
126 console.log(vars.line)
127 })
128 ;
129 stream.pipe(b);
130 ```
131
132 b.tap(cb)
133 ---------
8464aae @substack readme updates for the methods
authored
134
135 The callback `cb` is provided with the variable stash from all the previous
136 actions once they've all finished.
137
503eb8b @substack readme notes about into() and a bump
authored
138 You can nest additional actions onto `this` inside the callback.
139
d712e1a @substack modernize docs
authored
140 b.into(key, cb)
141 ---------------
503eb8b @substack readme notes about into() and a bump
authored
142
143 Like `.tap()`, except all nested actions will assign into a `key` in the `vars`
144 stash.
145
d712e1a @substack modernize docs
authored
146 b.loop(cb)
147 ----------
a32b25b @substack now with loops!
authored
148
149 Loop, each time calling `cb(end, vars)` for function `end` and the variable
150 stash with `this` set to a new chain for nested parsing. The loop terminates
151 once `end` is called.
152
d712e1a @substack modernize docs
authored
153 b.flush()
154 ---------
915f99e @substack readme notes, package bump for .parse()
authored
155
07019ba @substack updated readme with new semantics
authored
156 Clear the variable stash entirely.
915f99e @substack readme notes, package bump for .parse()
authored
157
d712e1a @substack modernize docs
authored
158 installation
9ebc04e @substack readme woo
authored
159 ============
160
161 To install with [npm](http://github.com/isaacs/npm):
162
d712e1a @substack modernize docs
authored
163 ```
164 npm install binary
165 ```
9ebc04e @substack readme woo
authored
166
d712e1a @substack modernize docs
authored
167 notes
1e33146 @substack buf.js example
authored
168 =====
169
170 The word64 functions will only return approximations since javascript uses ieee
171 floating point for all number types. Mind the loss of precision.
d712e1a @substack modernize docs
authored
172
173 license
174 =======
175
176 MIT
177
Something went wrong with that request. Please try again.