Permalink
Browse files

modernize docs

  • Loading branch information...
1 parent c88a447 commit d712e1a67f30c3f6416290bff8e6ab78b939c152 @substack committed May 11, 2012
Showing with 94 additions and 85 deletions.
  1. +91 −81 README.markdown
  2. +3 −4 package.json
View
@@ -1,4 +1,4 @@
-Binary
+binary
======
Unpack multibyte binary values from buffers and streams.
@@ -10,50 +10,70 @@ runs on pre-allocated buffers instead of a linked list.
[![build status](https://secure.travis-ci.org/substack/node-binary.png)](http://travis-ci.org/substack/node-binary)
-Examples
+examples
========
+stream.js
+---------
+
+``` js
+var binary = require('binary');
+
+var ws = binary()
+ .word32lu('x')
+ .word16bs('y')
+ .word16bu('z')
+ .tap(function (vars) {
+ console.dir(vars);
+ })
+;
+process.stdin.pipe(ws);
+process.stdin.resume();
+```
+
+output:
+
+```
+$ node examples/stream.js
+abcdefgh
+{ x: 1684234849, y: 25958, z: 26472 }
+^D
+```
+
parse.js
--------
- var buf = new Buffer([ 97, 98, 99, 100, 101, 102, 0 ]);
-
- var Binary = require('binary');
- var vars = Binary.parse(buf)
- .word16ls('ab')
- .word32bu('cf')
- .word8('x')
- .vars
- ;
- console.dir(vars);
--
- $ node parse.js
- { ab: 25185, cf: 1667523942, x: 0 }
+``` js
+var buf = new Buffer([ 97, 98, 99, 100, 101, 102, 0 ]);
-stream.js
----------
+var binary = require('binary');
+var vars = binary.parse(buf)
+ .word16ls('ab')
+ .word32bu('cf')
+ .word8('x')
+ .vars
+;
+console.dir(vars);
+```
+
+output:
- var Binary = require('binary');
- var stdin = process.openStdin();
-
- Binary.stream(stdin)
- .word32lu('x')
- .word16bs('y')
- .word16bu('z')
- .tap(function (vars) {
- console.dir(vars);
- })
- ;
--
- $ node examples/stream.js
- abcdefgh
- { x: 1684234849, y: 25958, z: 26472 }
- ^D
-
-Methods
+```
+{ ab: 25185, cf: 1667523942, x: 0 }
+```
+
+methods
=======
-Binary.parse(buf)
+`var binary = require('binary')`
+
+var b = binary()
+----------------
+
+Return a new writable stream `b` that has the chainable methods documented below
+for buffering binary input.
+
+binary.parse(buf)
-----------------
Parse a static buffer in one pass. Returns a chainable interface with the
@@ -64,25 +84,8 @@ In parse mode, methods will set their keys to `null` if the buffer isn't big
enough except `buffer()` and `scan()` which read up up to the end of the buffer
and stop.
-Binary.stream(emitter, eventName='data')
-----------------------------------------
-
-Parse a stream of buffer events from `eventName`. Each action will only execute
-once enough data has arrived from the event emitter.
-
-Binary(bufOrEm, eventName)
---------------------------
-
-If `bufOrEm` is a Buffer, returns `Binary.parse(bufOrEm)`, else returns
-`Binary.stream(bufOrEm, eventName)`
-
-Binary.put()
-------------
-
-Returns a new [put object](http://github.com/substack/node-put).
-
-word{8,16,32,64}{l,b}{e,u,s}(key)
-----------------------------------
+b.word{8,16,32,64}{l,b}{e,u,s}(key)
+-----------------------------------
Parse bytes in the buffer or stream given:
@@ -99,69 +102,76 @@ values don't exist they will be created automatically, so for instance you can
assign into `dst.addr` and `dst.port` and the `dst` key in the variable stash
will be `{ addr : x, port : y }` afterwards.
-buffer(key, size)
------------------
+b.buffer(key, size)
+-------------------
Take `size` bytes directly off the buffer stream, putting the resulting buffer
slice in the variable stash at `key`. If `size` is a string, use the value at
`vars[size]`. The key follows the same dotted address rules as the word
functions.
-scan(key, buffer)
------------------
+b.scan(key, buffer)
+-------------------
Search for `buffer` in the stream and store all the intervening data in the
stash at at `key`, excluding the search buffer. If `buffer` passed as a string,
it will be converted into a Buffer internally.
For example, to read in a line you can just do:
- Binary(em)
- .scan('line', new Buffer('\r\n'))
- .tap(function (vars) {
- console.log(vars.line)
- })
- ;
-
-tap(cb)
--------
+``` js
+var b = binary()
+ .scan('line', new Buffer('\r\n'))
+ .tap(function (vars) {
+ console.log(vars.line)
+ })
+;
+stream.pipe(b);
+```
+
+b.tap(cb)
+---------
The callback `cb` is provided with the variable stash from all the previous
actions once they've all finished.
You can nest additional actions onto `this` inside the callback.
-into(key, cb)
--------------
+b.into(key, cb)
+---------------
Like `.tap()`, except all nested actions will assign into a `key` in the `vars`
stash.
-loop(cb)
---------
+b.loop(cb)
+----------
Loop, each time calling `cb(end, vars)` for function `end` and the variable
stash with `this` set to a new chain for nested parsing. The loop terminates
once `end` is called.
-flush()
--------
+b.flush()
+---------
Clear the variable stash entirely.
-Installation
+installation
============
To install with [npm](http://github.com/isaacs/npm):
-
- npm install binary
-To run the tests with [expresso](http://github.com/visionmedia/expresso):
+```
+npm install binary
+```
- expresso
-
-Notes
+notes
=====
The word64 functions will only return approximations since javascript uses ieee
floating point for all number types. Mind the loss of precision.
+
+license
+=======
+
+MIT
+
View
@@ -21,9 +21,8 @@
"url" : "http://substack.net"
},
"dependencies" : {
- "chainsaw" : "0.1.x",
- "put" : ">=0.0.5 <0.1",
- "buffers" : "0.1.x"
+ "chainsaw" : "~0.1.0",
+ "buffers" : "~0.1.1"
},
"devDependencies" : {
"seq" : "~0.2.5",
@@ -32,7 +31,7 @@
"scripts" : {
"test" : "tap test/*.js"
},
- "license" : "MIT/X11",
+ "license" : "MIT",
"engine" : {
"node" : ">=0.4.0"
}

0 comments on commit d712e1a

Please sign in to comment.