Typesets

Typesets normally contain dictionary of typeName => type pairs, but they may also contain special config values that set some global options or modes for entire typeset.

As for now, such options are:

• jBinary.littleEndian - sets endianness for this format.
• jBinary.mimeType - sets mime-type which should be used for saving data from this typeset (i.e., when calling toURI without argument).

The Repo

jBinary provides special Repo for popular file formats and corresponding demos.

Using standard typesets is easy - just make require-like call to jBinary.Repo async loader method.

You can call it with one typeset name:

jBinary.Repo('bmp', function (BMP) {
  var binary = new jBinary(data, BMP);
});

Or with list of names:

jBinary.Repo(['tar', 'gzip'], function (TAR, GZIP) {
  // your code goes here ;)
});

All the typesets that are already loaded, are stored inside jBinary.Repo itself with upper-case names of typesets used as keys (like jBinary.Repo.BMP).

If you know some popular format structure and can write own typeset, you're welcome to contribute!

Typeset associations

Inside the Repo, there is also associations.js file which provides associations between typesets and corresponding file name extensions & mime types.

jBinary uses those associations for loading data from external sources when typeset is not specified explicitly.

If you want your typeset to be associated with special file extensions or some mime-types, simply add entry into descriptors object in this file like:

var descriptors = {
  // ...
  tar: {
    extensions: ['tar'],
    mimeTypes: ['application/tar', 'application/x-tar', 'applicaton/x-gtar', 'multipart/x-tar']
  }
};

Loading/saving data

In most cases you don't have binary data hard-coded in your JavaScript (why do you need any operation on it otherwise, eh?).

So you need to get this data from some external source and show result when you are done.

And jBinary provides handy methods for that:

• jBinary.loadData(source, callback) (static method):

  Loads data from given source and returns it in Node.js-like callback(error, data).

  Source can be one of (if supported on current engine):

  • Blob / File instance (HTML5 File API).
  • HTTP(S) URL (should be on the same host or allowed by CORS if called from browser).
  • Data-URI (simple or base64-encoded).
  • Node.js local file path.
  • Node.js Readable stream.

• jBinary.load(source, [typeSet,] callback) (static method):

Loads data from given source using jBinary.loadData, detects typeset using Repo associations if it's not specified explicitly, creates jBinary instance on this data and typeset and returns it in callback(error, binary).

If Repo is not used, jBinary.load would accept only explicit typeset objects (no loading by name nor file format auto-detection).

• toURI(mimeType = 'application/octet-stream')

Returns URI suitable for usage in DOM elements (uses Blob URIs where supported, data-URIs in other cases, so may be problematic when creating from big data in old browsers).

Example:

jBinary.load('sample.tar', function (error, binary) {
  if (error) {
    return console.log(error);
  }

  // here TAR format is auto-detected and used by `binary`
  var tar = binary.read('File');

  // ... more code ...
});

Internal jBinary Methods (useful for custom types)

• getType(type): Returns constructed jBinary.Type instance from given descriptor.
• createProperty(type): Constructs property from given type linked to current binary.
• getContext(filter): Get object context specified by filter. Possible filter types:
  • not set - current context will be returned.
  • number - filter will be used as relative depth (0 is current context, 1 for parent and so on).
  • string - will look for closest context that contains property name equal to filter.
  • function - will be used as boolean function (true to stop) while bubbling up through contexts.
• inContext(newContext, callback): Executes function inside given context.