|
| 1 | +# js Binary Schema Parser |
| 2 | + |
| 3 | +Parse binary files in client javascript using clean schema objects. |
| 4 | + |
| 5 | +We needed this when building the **[Ruffle][1]** hybrid app, so that we could effectively parse GIF files for manipulation. While this readme describes how to parse binary files in general, our *[GIF Parser][2]* library exhibits a full use of this project (including a *[demo][2]*), which might be further help to anyone looking. |
| 6 | + |
| 7 | +As we knew our compatibility requirements in advance, this parser expects the input file to be converted to a `Uint8Array` array. |
| 8 | + |
| 9 | +### How to Use |
| 10 | + |
| 11 | +*Installation:* |
| 12 | + |
| 13 | + bower install --save js-binary-schema-parser |
| 14 | + |
| 15 | +*Include in your app:* |
| 16 | + |
| 17 | + <script src="/bower_components/js-binary-schema-parser/dist/js-binary-schema-parser.min.js"></script> |
| 18 | + |
| 19 | +*Create a schema and parse a file:* |
| 20 | + |
| 21 | + // optional included basic parsers |
| 22 | + var Parsers = BSP.Parsers; |
| 23 | + |
| 24 | + var schema = [ |
| 25 | + // part definitions... |
| 26 | + ]; |
| 27 | + |
| 28 | + // get the input file data |
| 29 | + var data = new Uint8Array(fileArrayBuffer); |
| 30 | + // create a parser object |
| 31 | + var file = new BSP.DataParser(data); |
| 32 | + // parse the file using your schema |
| 33 | + var parsedObject = file.parse(schema); |
| 34 | + |
| 35 | +### Schemas |
| 36 | + |
| 37 | +Schemas are an array of *parts*, which are objects containing particular keys and values defining how the next bytes in the file should be parsed. *Parts* can also contain other parts internally, and include syntax for loops, and bit parsing. You can also include your own custom functions for parsing, providing direct access to the data stream. Below is a list of all the available keys a part object can use, along with some examples: |
| 38 | + |
| 39 | +*Keys:* |
| 40 | + |
| 41 | +**label** - The name of the part used in the output object (required) |
| 42 | + |
| 43 | +**requires** - A function that is provided the stream, and the output object, which can be used to determine whether or not this part should be parsed. - `function(stream, obj){}` |
| 44 | + |
| 45 | +*Parser type keys (only one can be used per part):* |
| 46 | + |
| 47 | +**parser** - A function used to extract the next valid content from the data stream. This library contains a Parsers object which houses the most commonly required parsers. They are: |
| 48 | + |
| 49 | +- `readByte()` - Returns the next byte off the data stream |
| 50 | +- `readBytes(n)` - Returns the *n* next bytes off the data stream |
| 51 | +- `readString(length)` - Returns a string representation of the next *length* bytes off the data stream |
| 52 | +- `readUnsigned(endian)` - Returns an unsigned int using the provided *endian*. |
| 53 | +- `readrray(size, totalFunc)` - Returns an array of byte sets (sub-arrays) of size *size*. The *totalFunc* is used to determine the number of items in the set, and is provided the stream, and the output object. - `function(stream, obj){}` |
| 54 | + |
| 55 | +The parser can also be a custom function that is provided the stream with which you can manipulate however you please. |
| 56 | + |
| 57 | +**bits** - This is used when you want to parse the next byte as individual bits. It is defined as an object that contains keys that outline the label, index, and bitlength of each item within the byte. For example, `firstThreeBits: { index: 0, length: 3 }`. |
| 58 | + |
| 59 | +**parts** - An array defining sub-parts that are parsed recursively. For example, a part could contain five sub parts, that each read off a mixture of unsigned ints and bytes. |
| 60 | + |
| 61 | +**loop** - Loop is used to parse a part multiple times. It is a function that returns `true` or `false` after each parse iteration, indicating whether or not the loop should continue. - `function(stream){}` |
| 62 | + |
| 63 | +### Example |
| 64 | + |
| 65 | +You can see a full example [here][2] of parsing GIF files completely, but here is just the header. |
| 66 | + |
| 67 | + var gifSchema = [ |
| 68 | + { |
| 69 | + label: 'header', // gif header |
| 70 | + parts: [ |
| 71 | + { label: 'signature', parser: Parsers.readString(3) }, |
| 72 | + { label: 'version', parser: Parsers.readString(3) } |
| 73 | + ] |
| 74 | + },{ |
| 75 | + label: 'lsd', // local screen descriptor |
| 76 | + parts: [ |
| 77 | + { label: 'width', parser: Parsers.readUnsigned(true) }, |
| 78 | + { label: 'height', parser: Parsers.readUnsigned(true) }, |
| 79 | + { label: 'gct', bits: { |
| 80 | + exists: { index: 0 }, |
| 81 | + resolution: { index: 1, length: 3 }, |
| 82 | + sort: { index: 4 }, |
| 83 | + size: { index: 5, length: 3 } |
| 84 | + }}, |
| 85 | + { label: 'backgroundColorIndex', parser: Parsers.readByte() }, |
| 86 | + { label: 'pixelAspectRatio', parser: Parsers.readByte() } |
| 87 | + ] |
| 88 | + } |
| 89 | + ]; |
| 90 | + |
| 91 | + |
| 92 | +### Why this parser? |
| 93 | + |
| 94 | +There are other good parsers around, like [jBinary][4], but we weren't a fan of relying on object key ordering, and defining parser types as strings. This parser does only cater to browsers that are able to utilise the `Uint8Array` data type, so if you need something more compatible, these other parsers might better fit your requirements. |
| 95 | + |
| 96 | +### Demo |
| 97 | + |
| 98 | +You can see a full demo **[here][2]** which uses this lib to parse GIF files for manipulation. |
| 99 | + |
| 100 | +### Who are we? |
| 101 | + |
| 102 | +[Unassigned][3] |
| 103 | + |
| 104 | +[1]: http://ruffle.us |
| 105 | +[2]: https://github.com/matt-way/gifuct-js |
| 106 | +[3]: http://unassigned.co |
| 107 | +[4]: https://github.com/jDataView/jBinary |
0 commit comments