Merge pull request #64 from keichi/pointer

Add pointer parser

Author: keichi

README.md

@@ -10,20 +10,24 @@ data. Binary-parser dynamically generates and compiles the parser code
 on-the-fly, which runs as fast as a hand-written parser (which takes much more
 time and effort to write). Supported data types are:
 
-- Integers (supports 8, 16, 32 bit signed- and unsigned integers)
-- Floating point numbers (supports 32 and 64 bit floating point values)
-- Bit fields (supports bit fields with length from 1 to 32 bits)
-- Strings (supports various encodings, fixed-length and variable-length, zero
-  terminated string)
-- Arrays (supports user-defined element type, fixed-length and variable-length)
-- Choices
+- [Integers](#uint8-16-32-64le-bename-options) (supports 8, 16, 32 and 64bit
+  signed and unsigned integers)
+- [Floating point numbers](#float-doublele-bename-options) (supports 32 and 64
+  bit floating point values)
+- [Bit fields](#bit1-32name-options) (supports bit fields with length from 1
+  to 32 bits)
+- [Strings](#stringname-options) (supports various encodings, fixed-length and
+  variable-length, zero terminated string)
+- [Arrays](#arrayname-options) (supports user-defined element type,
+  fixed-length and variable-length)
+- [Choices](#choicename-options)
+- [Pointers](#pointername-options)
 - User defined types
 
-This library's features are inspired by [BinData](https://github.com/dmendel/bindata)
-, its syntax by [binary](https://github.com/substack/node-binary).
+Binary-parser is inspired by [BinData](https://github.com/dmendel/bindata)
+and [binary](https://github.com/substack/node-binary).
 
 ## Installation
-Binary-parser can be installed with [npm](https://npmjs.org/):
 
 ```shell
 $ npm install binary-parser
@@ -78,8 +82,8 @@ nothing.
 
 ### 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.
+object. When `parse(buffer)` is called for the first time, the associated
+parser code is compiled on-the-fly and internally cached.
 
 ### create(constructorFunction)
 Set the constructor function that should be called to create the object
@@ -90,11 +94,11 @@ 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, 32 and 64. Byte-ordering can be either
 `l` for little endian or `b` for big endian. With no prefix, it parses as a
-signed number, with `u` prefixed as an unsigned number. The runtime type 
-returned by the 8, 16, 32 bit methods is `number` while the type 
-returned by the 64 bit is `bigint`.  
-  
-**NOTE:** [u]int64{be,le} methods only work if your runtime is Nodejs v12.0.0 or 
+signed number, with `u` prefixed as an unsigned number. The runtime type
+returned by the 8, 16, 32 bit methods is `number` while the type
+returned by the 64 bit is `bigint`.
+
+**NOTE:** [u]int64{be,le} methods only work if your runtime is node v12.0.0 or
 greater. Lower version will throw a runtime error.
 
 ```javascript
@@ -277,6 +281,14 @@ current object. `options` is an object which can have the following keys:
 
 - `type` - (Required) A `Parser` object.
 
+### pointer(name [,options])
+Jump to `offset`, execute parser for `type` and rewind to previous offset.
+
+- `type` - (Required) A `Parser` object.
+- `offset` - (Required) Note that this indicates absolute offset from the
+    start of the input buffer. Can be a string `[u]int{8, 16, 32, 64}{le, be}`
+    or an user defined Parser object.
+
 ### skip(length)
 Skip parsing for `length` bytes.
 
@@ -398,7 +410,7 @@ Dynamically generates the code for this parser and returns it as a string.
 Usually used for debugging.
 
 ### Common options
-These are common options that can be specified in all parsers.
+These options can be used in all parsers.
 
 - `formatter` - Function that transforms the parsed value into a more desired
   form.
@@ -437,11 +449,10 @@ These are common options that can be specified in all parsers.
     ```
 
 ## Examples
-See `example` for more complex examples.
+See `example/` for real-world examples.
 
 ## Support
 Please report issues to the
-[issue tracker](https://github.com/Keichi/binary-parser/issues) if you have
+[issue tracker](https://github.com/keichi/binary-parser/issues) if you have
 any difficulties using this module, found a bug, or request a new feature.
-
-Pull requests with fixes and improvements are welcomed!
+Pull requests are welcomed.

example/elf32.js

@@ -0,0 +1,84 @@
+var Parser = require('../dist/binary_parser').Parser;
+
+var ELF32ProgramHeader = new Parser()
+  .endianess('little')
+  .uint32('type')
+  .uint32('offset')
+  .uint32('vaddr')
+  .uint32('paddr')
+  .uint32('filesz')
+  .uint32('memsz')
+  .uint32('flags')
+  .uint32('align');
+
+var ELF32ProgramHeaderTable = new Parser().array('items', {
+  type: ELF32ProgramHeader,
+  length: function(vars) {
+    return vars.phnum;
+  },
+});
+
+var ELF32SectionHeader = new Parser()
+  .endianess('little')
+  .uint32('name')
+  .uint32('type')
+  .uint32('flags')
+  .uint32('address')
+  .uint32('offset')
+  .uint32('size')
+  .uint32('link')
+  .uint32('info')
+  .uint32('addralign')
+  .uint32('entsize');
+
+var ELF32SectionHeaderTable = new Parser().array('items', {
+  type: ELF32SectionHeader,
+  length: function(vars) {
+    return vars.shnum;
+  },
+});
+
+var ELF32SectionHeaderStringTable = new Parser().skip(1).array('items', {
+  type: new Parser().string('name', { zeroTerminated: true }),
+  lengthInBytes: function(vars) {
+    var shstr = vars.section_headers.items[vars.shstrndx];
+    return shstr.size - 1;
+  },
+});
+
+var ELF32Header = new Parser()
+  .endianess('little')
+  .buffer('ident', { length: 16 })
+  .uint16('type')
+  .uint16('machine')
+  .uint32('version')
+  .uint32('entry')
+  .uint32('phoff')
+  .uint32('shoff')
+  .uint32('flags')
+  .uint16('ehsize')
+  .uint16('phentsize')
+  .uint16('phnum')
+  .uint16('shentsize')
+  .uint16('shnum')
+  .uint16('shstrndx')
+  .pointer('program_headers', {
+    type: ELF32ProgramHeaderTable,
+    offset: 'phoff',
+  })
+  .pointer('section_headers', {
+    type: ELF32SectionHeaderTable,
+    offset: 'shoff',
+  })
+  .pointer('strings', {
+    type: ELF32SectionHeaderStringTable,
+    offset: function() {
+      var shstr = vars.section_headers.items[vars.shstrndx];
+      return shstr.offset;
+    },
+  });
+
+require('fs').readFile('hello', function(err, data) {
+  var result = ELF32Header.parse(data);
+  console.log(require('util').inspect(result, { depth: null }));
+});

example/hello

@@ -21,6 +21,7 @@ interface ParserOptions {
   stripNull?: null;
   key?: null;
   tag?: null;
+  offset?: null;
 }
 
 type Types = PrimitiveTypes | ComplexTypes;
@@ -33,6 +34,7 @@ type ComplexTypes =
   | 'choice'
   | 'nest'
   | 'skip'
+  | 'pointer'
   | '';
 
 type Endianess = 'be' | 'le';
@@ -148,6 +150,7 @@ const CAPITILIZED_TYPE_NAMES: { [key in Types]: string } = {
   choice: 'Choice',
   nest: 'Nest',
   skip: 'Skip',
+  pointer: 'Pointer',
   '': '',
 };
 
@@ -510,6 +513,32 @@ export class Parser {
     return this.setNextParser('nest', varName as string, options);
   }
 
+  pointer(varName: string, options?: ParserOptions) {
+    if (!options.offset) {
+      throw new Error('Offset option of pointer is not defined.');
+    }
+
+    if (!options.type) {
+      throw new Error('Type option of pointer is not defined.');
+    } else if (typeof options.type === 'string') {
+      if (
+        Object.keys(PRIMITIVE_SIZES).indexOf(options.type) < 0 &&
+        !aliasRegistry[options.type]
+      ) {
+        throw new Error(
+          'Specified type "' + options.type + '" is not supported.'
+        );
+      }
+    } else if (options.type instanceof Parser) {
+    } else {
+      throw new Error(
+        'Type option of pointer must be a string or a Parser object.'
+      );
+    }
+
+    return this.setNextParser('pointer', varName, options);
+  }
+
   endianess(endianess: 'little' | 'big') {
     switch (endianess.toLowerCase()) {
       case 'little':
@@ -730,6 +759,9 @@ export class Parser {
         case 'choice':
           this.generateChoice(ctx);
           break;
+        case 'pointer':
+          this.generatePointer(ctx);
+          break;
       }
       this.generateAssert(ctx);
     }
@@ -1040,4 +1072,40 @@ export class Parser {
       ctx.pushCode(`${varName} = (${formatter}).call(this, ${varName});`);
     }
   }
+
+  private generatePointer(ctx: Context) {
+    const type = this.options.type;
+    const offset = ctx.generateOption(this.options.offset);
+    const tempVar = ctx.generateTmpVariable();
+    const nestVar = ctx.generateVariable(this.varName);
+
+    // Save current offset
+    ctx.pushCode(`var ${tempVar} = offset;`);
+
+    // Move offset
+    ctx.pushCode(`offset = ${offset};`);
+
+    if (this.options.type instanceof Parser) {
+      ctx.pushCode(`${nestVar} = {};`);
+      ctx.pushPath(this.varName);
+      this.options.type.generate(ctx);
+      ctx.popPath(this.varName);
+    } else if (aliasRegistry[this.options.type]) {
+      const tempVar = ctx.generateTmpVariable();
+      ctx.pushCode(
+        `var ${tempVar} = ${FUNCTION_PREFIX + this.options.type}(offset);`
+      );
+      ctx.pushCode(
+        `${nestVar} = ${tempVar}.result; offset = ${tempVar}.offset;`
+      );
+      if (this.options.type !== this.alias) ctx.addReference(this.options.type);
+    } else if (Object.keys(PRIMITIVE_SIZES).indexOf(this.options.type) >= 0) {
+      const typeName = CAPITILIZED_TYPE_NAMES[type as Types];
+      ctx.pushCode(`${nestVar} = buffer.read${typeName}(offset);`);
+      ctx.pushCode(`offset += ${PRIMITIVE_SIZES[type as PrimitiveTypes]};`);
+    }
+
+    // Restore offset
+    ctx.pushCode(`offset = ${tempVar};`);
+  }
 }

lib/binary_parser.ts

@@ -943,6 +943,58 @@ describe('Composite parser', function() {
     });
   });
 
+  describe('Pointer parser', function() {
+    it('should move pointer to specified offset', function() {
+      var parser = Parser.start().pointer('x', { type: 'uint8', offset: 2 });
+      var buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
+
+      assert.deepEqual(parser.parse(buf), { x: 3 });
+    });
+
+    it('should restore pointer to original position', function() {
+      var parser = Parser.start()
+        .pointer('x', { type: 'uint8', offset: 2 })
+        .uint16be('y');
+      var buf = Buffer.from([0x1, 0x2, 0x3, 0x4, 0x5]);
+
+      assert.deepEqual(parser.parse(buf), { x: 0x3, y: 0x0102 });
+    });
+
+    it('should work with child parser', function() {
+      var parser = Parser.start()
+        .uint32le('x')
+        .pointer('y', {
+          type: Parser.start().string('s', { zeroTerminated: true }),
+          offset: 4,
+        });
+      var buf = Buffer.from('\1\2\3\4hello\0\6', 'ascii');
+
+      assert.deepEqual(parser.parse(buf), {
+        x: 0x04030201,
+        y: { s: 'hello' },
+      });
+    });
+
+    it('should pass variable context to child parser', function() {});
+    var parser = Parser.start()
+      .uint16be('len')
+      .pointer('child', {
+        offset: 4,
+        type: Parser.start().array('a', {
+          type: 'uint8',
+          length: function(vars) {
+            return vars.len;
+          },
+        }),
+      });
+    var buf = Buffer.from('\0\6\0\0\1\2\3\4\5\6');
+
+    assert.deepEqual(parser.parse(buf), {
+      len: 6,
+      child: { a: [1, 2, 3, 4, 5, 6] },
+    });
+  });
+
   describe('Utilities', function() {
     it('should count size for fixed size structs', function() {
       var parser = Parser.start()