Merge pull request keichi#68 from keichi/omit-varname

Flattened data structure for "nest" types

Author: keichi

README.md

@@ -76,7 +76,7 @@ console.log(ipHeader.parse(buf));
 Constructs a Parser object. Returned object represents a parser which parses
 nothing.
 
-### parse(buffer[, callback])
+### parse(buffer)
 Parse a `Buffer` object `buffer` with this parser and return the resulting
 object. When `parse(buffer)` is called for the first time, parser code is
 compiled on-the-fly and internally cached.
@@ -85,7 +85,7 @@ compiled on-the-fly and internally cached.
 Set the constructor function that should be called to create the object
 returned from the `parse` method.
 
-### [u]int{8, 16, 32}{le, be}(name [,options])
+### [u]int{8, 16, 32}{le, be}(name[, options])
 Parse bytes as an integer and store it in a variable named `name`. `name`
 should consist only of alphanumeric characters and start with an alphabet.
 Number of bits can be chosen from 8, 16 and 32. Byte-ordering can be either
@@ -102,12 +102,12 @@ var parser = new Parser()
   .int16be("c");
 ```
 
-### bit\[1-32\](name [,options])
+### bit\[1-32\](name[, options])
 Parse bytes as a bit field and store it in variable `name`. There are 32
 methods from `bit1` to `bit32` each corresponding to 1-bit-length to
 32-bits-length bit field.
 
-### {float, double}{le, be}(name [,options])
+### {float, double}{le, be}(name[, options])
 Parse bytes as an floating-point value and store it in a variable named
 `name`. `name` should consist only of alphanumeric characters and start with
 an alphabet.
@@ -120,10 +120,10 @@ var parser = new Parser()
   .doublele("b");
 ```
 
-### string(name [,options])
+### string(name[, options])
 Parse bytes as a string. `name` should consist only of alpha numeric
-characters and start with an alphabet. `options` is an object; following
-options are available:
+characters and start with an alphabet. `options` is an object which can have
+the following keys:
 
 - `encoding` - (Optional, defaults to `utf8`) Specify which encoding to use.
   `"utf8"`, `"ascii"`, `"hex"` and else are valid. See
@@ -139,10 +139,10 @@ options are available:
 - `stripNull` - (Optional, must be used with `length`) If true, then strip
   null characters from end of the string
 
-### buffer(name [,options])
+### buffer(name[, options])
 Parse bytes as a buffer. `name` should consist only of alpha numeric
-characters and start with an alphabet. `options` is an object; following
-options are available:
+characters and start with an alphabet. `options` is an object which can have
+the following keys:
 
 - `clone` - (Optional, defaults to `false`) By default,
   `buffer(name [,options])` returns a new buffer which references the same
@@ -156,9 +156,9 @@ options are available:
 - `readUntil` - (either `length` or `readUntil` is required) If `"eof"`, then
   this parser will read till it reaches end of the `Buffer` object.
 
-### array(name [,options])
-Parse bytes as an array. `options` is an object; following options are
-available:
+### array(name, options)
+Parse bytes as an array. `options` is an object which can have the following
+keys:
 
 - `type` - (Required) Type of the array element. Can be a string or an user
   defined Parser object. If it's a string, you have to choose from [u]int{8,
@@ -232,18 +232,18 @@ var parser = new Parser()
   });
 ```
 
-### choice(name [,options])
-Choose one parser from several choices according to a field value. Combining
-`choice` with `array` is useful for parsing a typical
-[Type-Length-Value](http://en.wikipedia.org/wiki/Type-length-value) styled
-format.
+### choice([name,] options)
+Choose one parser from multiple parsers according to a field value and store
+its parsed result to key `name`. If `name` is null or omitted, the result of
+the chosen parser is directly embedded into the current object. `options` is
+an object which can have the following keys:
 
 - `tag` - (Required) The value used to determine which parser to use from the
   `choices` Can be a string pointing to another field or a function.
 - `choices` - (Required) An object which key is an integer and value is the
   parser which is executed when `tag` equals the key value.
 - `defaultChoice` - (Optional) In case of the tag value doesn't match any of
-  `choices` use this parser.
+  `choices`, this parser is used.
 
 ```javascript
 var parser1 = ...;
@@ -260,9 +260,13 @@ var parser = new Parser().uint8("tagValue").choice("data", {
 });
 ```
 
-### nest(name [,options])
-Nest a parser in this position. Parse result of the nested parser is stored in the variable
-`name`.
+Combining `choice` with `array` is an idiom to parse
+[TLV](http://en.wikipedia.org/wiki/Type-length-value)-based formats.
+
+### nest([name,] options)
+Execute an inner parser and store its result to key `name`. If `name` is null
+or omitted, the result of the inner parser is directly embedded into the
+current object. `options` is an object which can have the following keys:
 
 - `type` - (Required) A `Parser` object.
 

example/tar.js

@@ -25,11 +25,11 @@ var tarHeader = new Parser()
   .skip(12);
 
 var tarItem = new Parser()
-  .nest("header", {
+  .nest({
     type: tarHeader
   })
   .skip(function() {
-    return Math.ceil(this.header.size / 512) * 512;
+    return Math.ceil(this.size / 512) * 512;
   });
 
 var tarArchive = new Parser().array("files", {

lib/binary_parser.js

@@ -170,12 +170,14 @@ Parser.prototype.choice = function(varName, options) {
     options = varName;
     varName = null;
   }
+
   if (!options.tag) {
     throw new Error("Tag option of array is not defined.");
   }
   if (!options.choices) {
     throw new Error("Choices option of array is not defined.");
   }
+
   Object.keys(options.choices).forEach(function(key) {
     if (isNaN(parseInt(key, 10))) {
       throw new Error("Key of choices must be a number.");
@@ -203,13 +205,22 @@ Parser.prototype.choice = function(varName, options) {
 };
 
 Parser.prototype.nest = function(varName, options) {
+  if (arguments.length == 1 && typeof varName === "object") {
+    options = varName;
+    varName = null;
+  }
+
   if (!options.type) {
     throw new Error("Type option of nest is not defined.");
   }
-
   if (!(options.type instanceof Parser) && !aliasRegistry[options.type]) {
     throw new Error("Type option of nest must be a Parser object.");
   }
+  if (!(options.type instanceof Parser) && !varName) {
+    throw new Error(
+      "options.type must be a object if variable name is omitted."
+    );
+  }
 
   return this.setNextParser("nest", varName, options);
 };
@@ -701,8 +712,11 @@ Parser.prototype.generateChoice = function(ctx) {
 
 Parser.prototype.generateNest = function(ctx) {
   var nestVar = ctx.generateVariable(this.varName);
+
   if (this.options.type instanceof Parser) {
-    ctx.pushCode("{0} = {};", nestVar);
+    if (this.varName) {
+      ctx.pushCode("{0} = {};", nestVar);
+    }
     ctx.pushPath(this.varName);
     this.options.type.generate(ctx);
     ctx.popPath(this.varName);

test/composite_parser.js

@@ -882,6 +882,28 @@ describe("Composite parser", function() {
         name: "John Doe"
       });
     });
+
+    it("should 'flatten' output when using null varName", function() {
+      var parser = new Parser()
+        .string("s1", { zeroTerminated: true })
+        .nest(null, {
+          type: new Parser().string("s2", { zeroTerminated: true })
+        });
+
+      var buf = Buffer.from("foo\0bar\0");
+
+      assert.deepEqual(parser.parse(buf), { s1: "foo", s2: "bar" });
+    });
+
+    it("should 'flatten' output when omitting varName", function() {
+      var parser = new Parser().string("s1", { zeroTerminated: true }).nest({
+        type: new Parser().string("s2", { zeroTerminated: true })
+      });
+
+      var buf = Buffer.from("foo\0bar\0");
+
+      assert.deepEqual(parser.parse(buf), { s1: "foo", s2: "bar" });
+    });
   });
 
   describe("Buffer parser", function() {