Home

Awesome

If you are interest in jParser then look at jBinary. This is a better version that supports both reads and write, extensions, templates ... yet preserves the declarative API of jParser.

<a href="http://blog.vjeux.com/2011/javascript/binaryparser-unleash-javascript-power.html">jParser</a> - Parsing binary files made easy.

jParser makes it easy to parse binary files in Javascript.

API

Primitive Structures:

jParser Methods:

jParser Constructor:

Examples

Basic C Structure You have the ability to define C-like structures. It's a Javascript object where keys are labels and values are types.

var parser = new jParser(file, {
  header: {
    fileId: 'int32',
    recordIndex: 'int32',
    hash: ['array', 'uint32', 4],
    fileName: ['string', 256],
    version: 2,
    flags: {
      precisionFlag: 1,
      marker: {
       part1: 2,
       part2: 2
      }
    },
    _reserved: 1 // padding to 8*N bits
  }
});
parser.parse('header');
// {
//   fileId: 42,
//   recordIndex: 6002,
//   hash: [4237894687, 3491173757, 3626834111, 2631772842],
//   fileName: ".\\Resources\\Excel\\Items_Weapons.xls",
//   version: 3,
//   flags: {
//     precisionFlag: 1,
//     marker: {
//       part1: 2,
//       part2: 0
//     }
//   },
//   _reserved: 0
// }

References Structures can reference other structures. Use structure name within a string in order to reference it. The following is an example from World of Warcraft model files.

nofs: {
  count: 'uint32',
  offset: 'uint32'
},
 
animationBlock: {
  interpolationType: 'uint16',
  globalSequenceID: 'int16',
  timestamps: 'nofs',
  keyFrame: 'nofs'
},
 
uvAnimation: {
  translation: 'animationBlock',
  rotation: 'animationBlock',
  scaling: 'animationBlock'
}

Helpers It is really easy to make new primitive types. You can either use existing constructions such as objects (float3) or arrays (float4). In case you want to do something more complicated, you always have the option to define a new function and use this.parse to keep parsing (hex32, string0).

float3: {
  x: 'float32',
  y: 'float32',
  z: 'float32'
},
float4: ['array', 'float32', 4],
hex32: function () {
  return '0x' + this.parse('uint32').toString(16);
},
string0: function (length) {
  return this.parse(['string', length]).replace(/\0+$/g, '');
}

Back Reference Instead of using an integer for the array size, you can put a function that will return an integer. In this function, you can use this.current to reference the englobing object being parsed.

image: {
  width: 'uint8',
  height: 'uint8',
  pixels: [
    'array',
    ['array', 'rgba', function () { return this.current.width; }],
    function () { return this.current.height; }
  ]
}

Advanced Parsing The best part of jParser is that complicated parsing logic can be expressed within the structure. It allows to parse complex files without having to split structure from parsing code.

entryHeader: {
  start: 'int32',
  count: 'int32'
},

entry: function (type) {
  var that = this;
  var header = this.parse('entryHeader');

  var res = [];
  this.seek(header.start, function () {
    for (var i = 0; i < header.count; ++i) {
      res.push(that.parse(type));
    }
  });
  return res;
},

name: {
 language: 'int32',
 text: ['string', 256]
},

file: {
  names: ['entry', 'name']
}

Get Started

NodeJS: Just use npm to install jParser and you are set :)

npm install jParser

var fs = require('fs');
var jParser = require('jParser');

fs.readFile('file.bin', function (err, data) {
  var parser = new jParser(data, {
    magic: ['array', 'uint8', 4]
  });
  console.log(parser.parse('magic'));
});

Browser: I've patched jQuery to allow to download binary files using the best binary format. You include this patched jQuery, jDataView and jParser and you are set :)

<script src="https://raw.github.com/vjeux/jDataView/master/jquery/jquery-1.7.1-binary-ajax.js"></script>
<script src="https://raw.github.com/vjeux/jDataView/master/src/jdataview.js"></script>
<script src="https://raw.github.com/vjeux/jParser/master/src/jparser.js"></script>

<script>
$.get('file.bin', function (data) {
  var parser = new jParser(data, {
    magic: ['array', 'uint8', 4]
  });
  console.log(parser.parse('magic'));
}, 'dataview');
</script>

Caveats

This tool works thanks to a feature that is not in the Javascript specification: When you iterate over an object keys, the keys will be listed in their order of insertion. Note that Chrome and Opera do not respect this implicit rule for keys that are numbers.

If you follow those two rules, the library will work in all the current Javascript implementations.

Demos

ICO Parser. This is a basic example to parse a binary file in NodeJS. It shows how to solve many common issues with binary file parsing.

Tar Extractor. This is a basic example to parse a binary file in the browser.

<a href="http://fooo.fr/~vjeux/github/jsWoWModelViewer/modelviewer.html">World of Warcraft Model Viewer</a>. It uses jParser to read the binary model and then WebGL to display it.

<a href="http://fooo.fr/~vjeux/github/jsWoWModelViewer/modelviewer.html"><img src="http://fooo.fr/~vjeux/github/jsWoWModelViewer/images/modelviewer.png"></a>

Diablo 3 Internal Files.