Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 304 lines (207 sloc) 9.181 kb
3e9f288 Converted to CoffeeScript.
Alan Gutierrez authored
1 # Node Packet
2
3 An evented binary packet and structure parser for Node.js.
4
5 ## Synopsis
6
7 Use tar as an example?
8
9 ## Installing
10
7fa167b New class based API.
Alan Gutierrez authored
11 ## Rationale
12
13 Node Packet aspires to be the go to library for converting binary data into
14 JavaScript or CoffeeScript primitives.
15
16 The following rationale is offered for the following questions that may or may
17 not be asked frequenty.
18
19 ### Why didn't you derive from EventEmitter?
20
21 EventEmitter is well suited for classes that have a set of API defined event
22 types. It does not at all suited for classes that emit of any number of event
23 types defined by the API user.
24
4fbd3ed Starting to commit to the API.
Alan Gutierrez authored
25 ## Bit Pattern Language
26
27 ### Big-Endian Byte Ordering
28
29 To define a big-endian byte ordering for a field, prefix the bit size with `b`.
30 **Mnemonic**: The letter `b` stands for big-endian.
31
32 ```javascript
33 "b16" // Big-endian 32 bit number.
34 "b8" // Endianess of a single byte is irrelevant.
35 "l16, b8" // Big-endian 16 bit integer followed by a byte.
36 ```
37
38 ### Little-Endian Byte Ordering
39
40 To define a little-endian byte ordering for a field, prefix the bit size with `l`.
41 **Mnemonic**: The letter `l` stands for little-endian.
42
43 ```javascript
44 "l32" // Little-endian 32 bit integer.
45 "l8" // Endianess of a single byte is irrelevant.
46 "l16, b8" // Little endian 16 bit integer followed by a byte.
47 ```
48
49 ### Skipping Bytes
50
51 You can skip over bytes your pattern with `x`. **Mnemonic**: The letter `x`
52 means to cross-out, which is kind of like skipping.
53
54 ```javascript
55 "b8, x16, l16" // A byte separated from a little-endian 16 bit integer by 16
56 // two bytes.
57 ```
58
59 ### Signed Versus Unsigned Integers
60
61 All numbers are assumed to be unsigned, unless prefixed by a negative symbol.
62 **Mnemonic**: The `-` symbol indicates the possiblity of negative numbers.
63
64 ```javascript
65 "-b32" // Big-endian 32 bit signed integer.
66 "-l32" // Little-endian 32 bit signed integer.
67 "b32" // Big-endian 32 bit unsigned integer.
68 ```
69
70 ### IEEE 754 Floating Point Numbers
71
72 The number type for JavaScript is the 64 bit IEEE 754 floating point. Node
73 Packet can read write 64 bit and 32 bit IEEE 754 floating point numbers.
74
75 To indicated that the type is a floating point number, use the `f` type suffix.
76 This is indicated with a `f` suffix. **Mnemonic**: The letter `f` stands for
77 *floating-point*.
78
79 ```javascript
80 "b64f" // Big-endian 64 bit IEEE 754 double floating point number.
81 "l32f" // Little-endian 32 bit IEEE 754 single floating point number.
82 ```
83
84 The floating-point numbers can be stored in little-endian or big-endian byte order.
85
86 ### Arrays of Raw Bytes
87
0a8ed04 Fixed markupo, tidy tranforms docs.
Alan Gutierrez authored
88 A value will be converted to a big-endian array of bytes if followed by an `a`
4fbd3ed Starting to commit to the API.
Alan Gutierrez authored
89 suffix. **Mnemonic**: The letter `a` stands for *array*.
90
91 ```javascript
92 "l128a" // Unsigned little-endian 128 bit integer as big-endian array
93 // of bytes.
94 ```
95
96 Note that big-endian means that the most signifcant byte is at index `0` of the
97 array.
98
99 This can be surprising if you're expecting the the significance of the bytes
100 will increase with the index of the array, but then that's what little-endian is
101 all about. (Big-endian orders like Arabic numerals, while little-endian orders
102 like offsets into memory.)
103
104 If you'd prefer a little-endian array, you can reverse the array with the `@`
105 qualifier. **Mnemonic**: The `@` character is a swirl and we want to turn our
106 array around.
107
108 ```javascript
109 "l128a@" // Unsigned little-endian 128 bit integer as little-endian
110 // array of bytes.
111 ```
112
113 ### Bytes as Hex Strings
114
115 A value will be converted to a big-endian hex string if followed by an `h`
116 suffix.
117
118 ```javascript
119 "l128h" // Unsigned little-endian 128 bit integer as a big-endian hex
120 // string.
121 ```
122
123 Like the raw byte of arrays, the hex string is in big-endian order with the most
124 significant bytes at the top. It is less likely that you'll want to reverse a
125 hex string, but if you, you can use the `@` qualifier. **Mnemonic**: The `@`
126 character is a swirl and we want to turn our string around.
127
128 ```javascript
129 "l128h@" // Unsigned little-endian 128 bit integer as a little-endian
130 // hex string.
131 ```
132
133 ### Arrays of Common Types
134
135 It is often the case that a binary format contains an array of values. The most
136 common case are arrays of bytes represnting ASCII or UTF-8 strings.
137
138 Arrays are specified with an subscript and a count. **Menmonic**: The square
139 brackets are used as array subscripts in JavaScript, and used to declare array
140 length in other C dialect languages.
141
142 ```javascript
143 "b32[4]" // An array of four big-endian 32 bit numbers.
144 "b8[16]" // An array of 16 bytes.
145 ```
146
147 The array notation produces an array of the type before the subscript.
148
149 ### Length Encoded Arrays
150
151 Length encoded arrays are specified by joining a count type and a value type
152 with a `/`. **Mnemonic**: Inspired by Perl's `pack`, this count and type
153 separator character is as good as any.
154
155 ```javascript
156 "b8/b8" // Length encoded byte array with a byte length.
157 "l16/b8" // Length encoded byte array with 16 bit little-endian length.
158 ```
159
160 ### Zero Terminated Arrays
161
162 Zero terminated series are speified with a `z` qualifier. **Mnemonic**: The
163 letter `z` stands for zero.
164
165 ```javascript
166 "l16z" // Little-endian 16 bit numbers terminated by a zero value.
167 "b8z" // Byte string terminated by zero.
168 ```
169
170 ### Transforms
171
0a8ed04 Fixed markupo, tidy tranforms docs.
Alan Gutierrez authored
172 Often there are transformations that you need to perform on an field to get
173 it to its final state. You may need to convert a byte array to string of a
174 particular character encoding, for example. This is done with a tranformation
175 functions which are specified with a transformation pipeline.
4fbd3ed Starting to commit to the API.
Alan Gutierrez authored
176
0a8ed04 Fixed markupo, tidy tranforms docs.
Alan Gutierrez authored
177 If the transformation is a fixed transformation, you can perform the
178 transformation by defining a pipeline. A pipeline defines one or more
4fbd3ed Starting to commit to the API.
Alan Gutierrez authored
179 tranformations that are invoked on the value after parsing and before
180 serialization. The transformations can accept scalar JavaScript parameters.
181
182 ```javascript
183 function str(encoding, name, field, parsing, value) {
184 if (parsing) {
185 var buffer = new Buffer(array.length)
186 for (var i = 0; i < value.length; i++) {
187 buffer[i] = value[i];
188 }
189 var length = value.length
190 if (field.terminator) {
191 length += field.terminator.length;
192 }
193 reutrn buffer.toString(encoding, 0, length);
194 } else {
195 if (field.terminator) {
196 value += field.terminator;
197 }
198 return new Buffer(value, encoding);
199 }
200 }
201 ```
202
203 Now you can use the transform in your pattern.
204
205 ```javascript
206 "n8z|str('ascii')" // An ascii string terminated by zero.
207 "n8z|str('ascii'), b16" // An ascii string terminated by zero followed by a
208 // big-endian 16 bit integer.
209 ```
210
211 The `str` transform is defined by default. The transform names are purposely
212 terse to fit with the brevity of the pattern language.
213
3e9f288 Converted to CoffeeScript.
Alan Gutierrez authored
214 ## Reference
215
216 namespace: packet
217
218 Node Packet exports the ec2 namespace, which provides the {{Structure}},
219 {{Parser}} and {{Serializer}} classes.
220
221 class: Structure
222
75319a5 Update packet.idl with Structure API.
Alan Gutierrez authored
223 parameter: pattern
224
225 The packet pattern.
226
227 A structure is an object that both reads from and writes to a buffer
228 syncrhonously. When reading, buffer must contain the entire contents of the
229 structure. When writing, the buffer must have enough space to accomdoate the
230 structure.
231
232 function: read
233
234 parameter: buffer
235
236 The byte buffer.
237
238 parameter: offset optional
239
240 The optional offset into the byte buffer. Defaults to `0`.
241
242 parameter: callback
243
244 Called with the parameters read from the byte buffer.
245
246 The read method accepts a buffer with an optional offset. The number of
247 arguments is determined by the structure packet pattern, and must match
248 the number of arguments expected by the packet pattern.
249
250 The callback will be called with the fields read from the buffer, with the
251 actual count of bytes read as the last parameter.
252
253 function: write
254
255 parameter: buffer
256
257 The byte buffer.
258
259 Write the arguments to the buffer at the optional offset. The arguments are
260 determined by the structure bit pattern. Returns the number of bytes written.
261
262 function: sizeOf
263
264 Get the size of the structure for the given variable length values. A structure
265 can have 0 or more variable length values.
266
267 The `sizeOf` method does not expect and will not correctly calculate the size of
268 the structure if fixed size value are given.
269
3e9f288 Converted to CoffeeScript.
Alan Gutierrez authored
270 class: Parser
271
7fa167b New class based API.
Alan Gutierrez authored
272 function: packet
273
274 parameter: name
275
276 The name of the packet type.
277
278 parameter: pattern
279
280 The packet pattern.
281
282 parameter: callback optional
283
284 Called when a packet of this type has been read from a buffer.
285
286 Defines a named packet type optionally assigning a default response for the
287 packet type.
288
289 function: parse
290
291 parameter: nameOrPattern
292
293 Either the name of a named packet or a one off
294
295 function: clone
296
297 Clone the packet parser to create a packet parser that shares the named packet
298 definitions but has its own parser state.
299
300 This allows a packet parser prototype to be used to efficently create initialized
301 instances.
302
3e9f288 Converted to CoffeeScript.
Alan Gutierrez authored
303 class: Serializer
Something went wrong with that request. Please try again.