Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 132 lines (96 sloc) 3.328 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
36 Binary(stdin)
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
07019ba @substack updated readme with new semantics
authored
60 Binary.stream(emitter, eventName='data')
61 ----------------------------------------
8464aae @substack readme updates for the methods
authored
62
07019ba @substack updated readme with new semantics
authored
63 Parse a stream of buffer events from `eventName`. Each action will only execute
64 once enough data has arrived from the event emitter.
65
66 Binary(bufOrEm, eventName)
67 --------------------------
68
69 If `bufOrEm` is a Buffer, returns `Binary.parse(bufOrEm)`, else returns
70 `Binary.stream(bufOrEm, eventName)`
8464aae @substack readme updates for the methods
authored
71
9f25d14 @substack updated readme for dotted address keys, package bump
authored
72 word{8,16,32,64}{l,b}{e,u,s}(key)
8464aae @substack readme updates for the methods
authored
73 ----------------------------------
74
75 Parse bytes in the buffer or stream given:
76
01c32c0 @substack silly markdown
authored
77 * number of bits
78 * endianness ( l : little, b : big ),
79 * signedness ( u and e : unsigned, s : signed )
8464aae @substack readme updates for the methods
authored
80
81 These functions won't start parsing until all previous parser functions have run
82 and the data is available.
83
9f25d14 @substack updated readme for dotted address keys, package bump
authored
84 The result of the parse goes into the variable stash at `key`.
85 If `key` has dots (`.`s), it refers to a nested address. If parent container
86 values don't exist they will be created automatically, so for instance you can
87 assign into `dst.addr` and `dst.port` and the `dst` key in the variable stash
88 will be `{ addr : x, port : y }` afterwards.
8464aae @substack readme updates for the methods
authored
89
7735a48 @substack buffer slice in the readme and a package bump
authored
90 buffer(key, size)
91 -----------------
92
93 Take `size` bytes directly off the buffer stream, putting the resulting buffer
94 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
95 `vars[size]`. The key follows the same dotted address rules as the word
96 functions.
7735a48 @substack buffer slice in the readme and a package bump
authored
97
8464aae @substack readme updates for the methods
authored
98 tap(cb)
99 -------
100
101 The callback `cb` is provided with the variable stash from all the previous
102 actions once they've all finished.
103
a32b25b @substack now with loops!
authored
104 loop(cb)
105 --------
106
107 Loop, each time calling `cb(end, vars)` for function `end` and the variable
108 stash with `this` set to a new chain for nested parsing. The loop terminates
109 once `end` is called.
110
07019ba @substack updated readme with new semantics
authored
111 flush()
112 -------
915f99e @substack readme notes, package bump for .parse()
authored
113
07019ba @substack updated readme with new semantics
authored
114 Clear the variable stash entirely.
915f99e @substack readme notes, package bump for .parse()
authored
115
9ebc04e @substack readme woo
authored
116 Installation
117 ============
118
119 To install with [npm](http://github.com/isaacs/npm):
120
11b5c60 @substack rebranded as binary
authored
121 npm install binary
9ebc04e @substack readme woo
authored
122
123 To run the tests with [expresso](http://github.com/visionmedia/expresso):
124
125 expresso
1e33146 @substack buf.js example
authored
126
127 Notes
128 =====
129
130 The word64 functions will only return approximations since javascript uses ieee
131 floating point for all number types. Mind the loss of precision.
Something went wrong with that request. Please try again.