Package Exports

arcsecond-binary

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (arcsecond-binary) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Arcsecond Binary

Binary parsers for arcsecond v2!

Before opening an issue, check to see if your question has been answered in the FAQ!

1. Parser Input
2. API
Click to view API table of contents

Parser Input

The input for an arcsecond-binary parser is a DataView. A DataView can be created from an ArrayBuffer, which is the underlying representation of essentially every TypedArray or Node Buffer.

If you have an ArrayBuffer

new DataView(anArrayBuffer);

If you have a Node Buffer

Although the underlying representation of a node Buffer is an ArrayBuffer, when accessing the the ArrayBuffer through the .buffer property, the data may not be as expected. If the buffer size is smaller than node's default pool size, then the ArrayBuffer will be created with the pool size, and the actual data will be somewhere inside the ArrayBuffer, with seemingly random data surrounding it. To avoid these issues, it's best to first cast a node Buffer to a Uint8Array, will will ensure that the ArrayBuffer properly correlates to the expected data.

const asUint8Array = new Uint8Array(nodeBuffer);
new DataView(asUint8Array.buffer);

If you have a TypedArray (Uint16Array, Int32Array, Float32Array, etc)

new DataView(typedArray.buffer);

API

Click here for the main arcsecond API docs. Many of the parser combinators (for example many, sepBy, anythingExcept, endOfInput etc) will work with the binary parsers, but any that specifically assume that the input is a string will not (for example string, letters, regex etc).

u8

u8 :: Parser String Number DataView

u8 consumes exactly one byte, and returns a match that interprets the result as an unsigned integer in the range [0, 255].

Example

const input = new Uint8Array([0x48, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

u8.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 72,
//      index: 1,
//      data: null
//    }

s8

s8 :: Parser String Number DataView

s8 consumes exactly one byte, and returns a match that interprets the result as a signed integer in the range [-128, 127].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

s8.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: -106,
//      index: 1,
//      data: null
//    }

u16LE

u16LE :: Parser String Number DataView

u16LE consumes exactly two bytes, read in little endian order, and returns a match that interprets the result as an unsigned integer in the range [0, 65535].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

u16LE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 17814,
//      index: 2,
//      data: null
//    }

u16BE

u16BE :: Parser String Number DataView

u16BE consumes exactly two bytes, read in big endian order, and returns a match that interprets the result as an unsigned integer in the range [0, 65535].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

u16BE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 38469,
//      index: 2,
//      data: null
//    }

s16LE

s16LE :: Parser String Number DataView

s16LE consumes exactly two bytes, read in little endian order, and returns a match that interprets the result as a signed integer in the range [-32768, 32767].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

s16LE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 17814,
//      index: 2,
//      data: null
//    }

s16BE

s16BE :: Parser String Number DataView

s16BE consumes exactly two bytes, read in big endian order, and returns a match that interprets the result as a signed integer in the range [-32768, 32767].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

s16BE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: -27067,
//      index: 2,
//      data: null
//    }

u32LE

u32LE :: Parser String Number DataView

u32LE consumes exactly four bytes, read in little endian order, and returns a match that interprets the result as an unsigned integer in the range [0, 4294967295].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

u32LE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 1280066966,
//      index: 4,
//      data: null
//    }

u32BE

u32BE :: Parser String Number DataView

u32BE consumes exactly four bytes, read in big endian order, and returns a match that interprets the result as an unsigned integer in the range [0, 4294967295].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

u32BE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 2521123916,
//      index: 4,
//      data: null
//    }

s32LE

s32LE :: Parser String Number DataView

s32LE consumes exactly four bytes, read in little endian order, and returns a match that interprets the result as a signed integer in the range [-2147483648, 2147483647].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

s32LE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 1280066966,
//      index: 4,
//      data: null
//    }

s32BE

s32BE :: Parser String Number DataView

s32BE consumes exactly four bytes, read in big endian order, and returns a match that interprets the result as a signed integer in the range [-2147483648, 2147483647].

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

s32BE.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: -1773843380,
//      index: 4,
//      data: null
//    }

exactU8

exactU8 :: UnsignedByte -> Parser String Number DataView

exactU8 takes an unsigned byte b, and consumes exactly one byte, matching a value equal to b, when interpreted as an unsigned integer.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactU8(0x96).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 150,
//      index: 1,
//      data: null
//    }

exactS8

exactS8 :: SignedByte -> Parser String Number DataView

exactS8 takes a signed byte b, and consumes exactly one byte, matching a value equal to b, when interpreted as a signed integer.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactS8(-106).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: -106,
//      index: 1,
//      data: null
//    }

exactU16LE

exactU16LE :: UnsignedU16 -> Parser String Number DataView

exactU16LE takes an unsigned 16-bit number b, and consumes exactly two bytes, matching a value equal to b, when interpreted as an unsigned integer in little endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactU16LE(0x4596).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 17814,
//      index: 1,
//      data: null
//    }

exactU16BE

exactU16BE :: UnsignedU16 -> Parser String Number DataView

exactU16BE takes an unsigned 16-bit number b, and consumes exactly two bytes, matching a value equal to b, when interpreted as an unsigned integer in big endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactU16BE(0x9645).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 38469,
//      index: 1,
//      data: null
//    }

exactS16LE

exactS16LE :: SignedU16 -> Parser String Number DataView

exactS16LE takes an signed 16-bit number b, and consumes exactly two bytes, matching a value equal to b, when interpreted as a signed integer in little endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactS16LE(17814).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 17814,
//      index: 1,
//      data: null
//    }

exactS16BE

exactS16BE :: SignedU16 -> Parser String Number DataView

exactS16BE takes an signed 16-bit number b, and consumes exactly two bytes, matching a value equal to b, when interpreted as a signed integer in big endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactS16BE(-27067).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: -27067,
//      index: 1,
//      data: null
//    }

exactU32LE

exactU32LE :: UnsignedU32 -> Parser String Number DataView

exactU32LE takes an unsigned 32-bit number b, and consumes exactly four bytes, matching a value equal to b, when interpreted as an unsigned integer in little endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactU32LE(0x4c4c4596).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 1280066966,
//      index: 1,
//      data: null
//    }

exactU32BE

exactU32BE :: UnsignedU32 -> Parser String Number DataView

exactU32BE takes an unsigned 32-bit number b, and consumes exactly four bytes, matching a value equal to b, when interpreted as an unsigned integer in big endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactU32BE(0x96454c4c).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 2521123916,
//      index: 1,
//      data: null
//    }

exactS32LE

exactS32LE :: SignedU32 -> Parser String Number DataView

exactS32LE takes an signed 32-bit number b, and consumes exactly four bytes, matching a value equal to b, when interpreted as a signed integer in little endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactS32LE(1280066966).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 1280066966,
//      index: 1,
//      data: null
//    }

exactS32BE

exactS32BE :: SignedU32 -> Parser String Number DataView

exactS32BE takes an signed 32-bit number b, and consumes exactly four bytes, matching a value equal to b, when interpreted as a signed integer in big endian order.

Example

const input = new Uint8Array([0x96, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

exactS32BE(-1773843380).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: -1773843380,
//      index: 1,
//      data: null
//    }

rawString

rawString :: String -> Parser String String DataView

rawString takes a string s, and consumes exactly as many bytes as s is long, matching a value equal to s, when interpreted as a string data.

Example

const input = new Uint8Array([0x48, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

rawString('HELLO').run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 'HELLO',
//      index: 1,
//      data: null
//    }

nullTerminatedString

nullTerminatedString :: Parser String String DataView

nullTerminatedString consumes as much input as possible until it matches a null byte (0x00), matching a string made from the bytes interpreted as string data.

Example

const input = new Uint8Array([0x48, 0x45, 0x4c, 0x4c, 0x4f, 0x2e, 0x2e, 0x2e, 0x00]);
const dataViewOfInput = new DataView(input);

nullTerminatedString.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 'HELLO...',
//      index: 1,
//      data: null
//    }

endOfInput

endOfInput :: Parser String null DataView

endOfInput succeeds when there is no more input to consume, and fails when there is. The value it returns is always null.

Example

const input = new Uint8Array([0x48, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

const parser = A.sequenceOf([
  rawString('HELLO'),
  endOfInput
]);

parser.run(dataViewOfInput);
// -> {
//      isError: false,
//      result: ['HELLO', null],
//      index: 1,
//      data: null
//    }

anythingExcept

anythingExcept :: Parser e a DataView -> Parser String Number DataView

anythingExcept takes a exception parser and returns a new parser which matches exactly one byte, if it is not matched by the exception parser.

Example

const input = new Uint8Array([0x48, 0x45, 0x4c, 0x4c, 0x4f]);
const dataViewOfInput = new DataView(input);

anythingExcept(exactU8(0x01)).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: 72,
//      index: 1,
//      data: null
//    }

everythingUntil

everythingUntil :: Parser e a DataView -> Parser String [Number] DataView

everythingUntil takes a termination parser and returns a new parser which matches unsigned bytes up until a value is matched by the termination parser. When a value is matched by the termination parser, it is not "consumed".

Example

const input = new Uint8Array([0x48, 0x45, 0x4c, 0x4c, 0x4f, 0xc0, 0xde]);
const dataViewOfInput = new DataView(input);

everythingUntil(exactU16BE(0xc0de)).run(dataViewOfInput);
// -> {
//      isError: false,
//      result: [72, 69, 76, 76, 79],
//      index: 1,
//      data: null
//    }