Skip to content
This repository
Browse code

updated readme with new semantics

  • Loading branch information...
commit 07019baea923ce799340611e94e028e992bf09b9 1 parent fd27d68
James Halliday authored December 13, 2010
61  README.markdown
Source Rendered
@@ -4,30 +4,13 @@ Binary
4 4
 Unpack multibyte binary values from buffers and streams.
5 5
 You can specify the endianness and signedness of the fields to be unpacked too.
6 6
 
7  
-This module is a cleaner, faster, and more complete version of
  7
+This module is a cleaner and more complete version of
8 8
 [bufferlist](https://github.com/substack/node-bufferlist)'s binary module that
9 9
 runs on pre-allocated buffers instead of a linked list.
10 10
 
11 11
 Examples
12 12
 ========
13 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  
-
31 14
 parse.js
32 15
 --------
33 16
     var buf = new Buffer([ 97, 98, 99, 100, 101, 102, 0 ]);
@@ -67,18 +50,24 @@ stream.js
67 50
 Methods
68 51
 =======
69 52
 
70  
-Binary(buf)
71  
------------
  53
+Binary.parse(buf)
  54
+-----------------
72 55
 
73  
-Start a new chain parser for a `Buffer`.
  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.
74 59
 
75  
-Binary(emitter)
76  
----------------
77  
-Binary(emitter, eventName='data')
78  
----------------------------------
  60
+Binary.stream(emitter, eventName='data')
  61
+----------------------------------------
79 62
 
80  
-Start a new chain parser for an `EventEmitter` for an event name `eventName`,
81  
-which defaults to `'data'`.
  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)`
82 71
 
83 72
 word{8,16,32,64}{l,b}{e,u,s}(key)
84 73
 ----------------------------------
@@ -119,11 +108,10 @@ Loop, each time calling `cb(end, vars)` for function `end` and the variable
119 108
 stash with `this` set to a new chain for nested parsing. The loop terminates
120 109
 once `end` is called.
121 110
 
122  
-Binary.parse(buf)
123  
------------------
  111
+flush()
  112
+-------
124 113
 
125  
-Like `Binary(buf)`, but synchronous so you can parse fields in a single pass.
126  
-Terminate a chain with `.vars` to get at the result of the parse.
  114
+Clear the variable stash entirely.
127 115
 
128 116
 Installation
129 117
 ============
@@ -136,19 +124,8 @@ To run the tests with [expresso](http://github.com/visionmedia/expresso):
136 124
 
137 125
     expresso
138 126
 
139  
-flush()
140  
--------
141  
-
142  
-Clear the variable stash entirely.
143  
-
144 127
 Notes
145 128
 =====
146 129
 
147 130
 The word64 functions will only return approximations since javascript uses ieee
148 131
 floating point for all number types. Mind the loss of precision.
149  
-
150  
-Todo
151  
-====
152  
-
153  
-* Actually verify that this approach is faster than bufferlist/binary.
154  
-* Add all the nifty nested parser functions without sacrificing performance.
9  index.js
@@ -3,6 +3,15 @@ var EventEmitter = require('events').EventEmitter;
3 3
 var Buf = require('./lib/buf.js');
4 4
 var Vars = require('./lib/vars.js');
5 5
 
  6
+exports = module.exports = function (bufOrEm, eventName) {
  7
+    if (Buffer.isBuffer(bufOrEm)) {
  8
+        return exports.parse(bufOrEm);
  9
+    }
  10
+    else {
  11
+        return exports.stream(bufOrEm, eventName);
  12
+    }
  13
+};
  14
+
6 15
 exports.stream = function (em, eventName) {
7 16
     if (eventName === undefined) eventName = 'data';
8 17
     
4  test/binary.js
@@ -6,7 +6,7 @@ exports.fromBuffer = function (assert) {
6 6
         assert.fail('never tapped');
7 7
     }, 50);
8 8
     
9  
-    Binary.parse(new Buffer([ 97, 98, 99 ]))
  9
+    Binary(new Buffer([ 97, 98, 99 ]))
10 10
         .word8('a')
11 11
         .word16be('bc')
12 12
         .tap(function (vars) {
@@ -442,7 +442,7 @@ exports.interval = function (assert) {
442 442
     }, 1);
443 443
     
444 444
     var loops = 0;
445  
-    Binary.stream(em)
  445
+    Binary(em)
446 446
         .loop(function (end) {
447 447
             this
448 448
             .word8('x')

0 notes on commit 07019ba

Please sign in to comment.
Something went wrong with that request. Please try again.