Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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