Module: bre

Like C struct, bre allows accessing binary data as a structure fastly.

The following steps are the basic usage of bre:

  1. Defines structures (calls it records).
  2. Creates mapping between the structure and a binary data.
  3. Reads/Writes the binary data as the structure.

1. Defines structures (calls it records).

const bre = require("bre")
const ExampleRecord = bre.defineObjectRecord("ExampleRecord", [
    {type: "uint8", name: "a"},
    {type: "uint8", name: "b"},
])

At first, it defines classes of structures by bre.defineObjectRecord or bre.defineArrayRecord.

The code above defines a class ExampleRecord which has 2 properties (a and b).

2. Creates mapping between the structure and a binary data.

ExampleRecord can be instantiated with an ArrayBuffer object or a view of an ArrayBuffer object. E.g., Node.js Buffer objects are the view of ArrayBuffer objects.

const buffer = Buffer.from([0x01, 0x02, 0x03])
const record1 = ExampleRecord.view(buffer, 0)
const record2 = ExampleRecord.view(buffer, 1)  // offset 1

ExampleRecord.view factory method creates an instance of ExampleRecord.

  • The 1st argument is the buffer to access.
  • The 2nd argument is the offset in bytes to access.

3. Reads/Writes the binary data as the structure.

console.log(record1.a, record1.b)  // => 1 2
console.log(record2.a, record2.b)  // => 2 3

record1.b = 10

console.log(record1.b)  // => 10
console.log(record2.a)  // => 10
console.log(buffer[1])  // => 10

Those record instances are just wrappers. The record1.a getter will read the 1st byte of buffer directly. The record2.a getter will read the 2nd byte of buffer directly.

Also, The record1.a setter will write the 1st byte of buffer directly. This means that record2.a which is sharing the buffer will be changed.

This would be useful to read and write binary data.

The size of records.

Record classes have 2 properties to get the record size. Those are static getter properties (since records are fixed size).

const bytes = ExampleRecord.byteLength
const bits = ExampleRecord.bitLength

Also, BinaryRecord class provides 2 methods to get the record size of a record instance.

const bytes = bre.BinaryRecord.byteLength(record1)
const bits = bre.BinaryRecord.bitLength(record1)
Source:

Classes

BinaryRecord

Methods

(static) defineArrayRecord(type, length) → {class}

Defines an array record.

The class this method defined is array-like. It has the ability to access by indexes and iterators.

const ListRecord = bre.defineArrayRecord("uint8", 3)

const buffer = Buffer.from([0x01, 0x02, 0x03])
const record = ListRecord.view(buffer)

console.log(record.length)  // => 3
console.log(record[0])      // => 1
console.log(record[1])      // => 2
console.log(record[2])      // => 3

for (const value of record) {
    console.log(value)      // => 1 2 3
}

And it has several methods of Array.prototype:

  • concat
  • entries
  • every
  • filter
  • find
  • findIndex
  • forEach
  • includes
  • indexOf
  • join
  • keys
  • lastIndexOf
  • map
  • reduce
  • reduceRight
  • slice
  • some
  • values
Parameters:
Name Type Description
type string | class | Array

The type of the elements. See module:bre.FieldDefinition's type property for details.

length number

The count of elements.

Source:
Returns:

The defined record class.

Type
class

(static) defineObjectRecord(className, fields) → {class}

Defines an object record.

Object records are similar to C struct. It has several properties and it can map to binary blocks.

const ExampleRecord = bre.defineObjectRecord("ExampleRecord", [
    {type: "uint8", name: "a"},
    {type: "uint8", name: "b"},
])

const buffer = Buffer.from([0x01, 0x02])
const record = ExampleRecord.view(buffer)

console.log("a =", record.a)           // => "a = 1"
console.log("buffer[0] =", buffer[0])  // => "buffer[0] = 1"
record.a = 7
console.log("a =", record.a)           // => "a = 7"
console.log("buffer[0] =", buffer[0])  // => "buffer[0] = 7"
Parameters:
Name Type Description
className string

The class name of new record.

fields Array.<(module:bre.FieldDefinition|module:bre.SkipDefinition)>

The list of field definition.

Source:
Returns:

The defined record class.

Type
class

(static) getTextEncoder() → {module:bre/lib/text-encoders.TextEncoder|null}

Gets the current text encoder.

Default is null.

const encoder = bre.getTextEncoder()
console.log(encoder)
Source:
Returns:

The current text encoder.

Type
module:bre/lib/text-encoders.TextEncoder | null

(static) setTextEncoder(value) → {void}

Sets the current text encoder.

If you want to use string fields in records, you needs to set a text encoder.

const encoder = require("bre/lib/text-encoders/buffer")
bre.setTextEncoder(encoder)

bre provides 2 implementations of TextEncoder.

Parameters:
Name Type Description
value module:bre/lib/text-encoders.TextEncoder | null

The text encoder to set.

Source:
Returns:
Type
void