Format()

A Format represents the binary structure of a file.

A format is logically divided in spans, each of which holds some information like an user friendly name and its length. The name is displayed in the statusbar at the bottom of the screen to help the user navigate the file.

Some file formats have spans that depend on the actual value of some bytes before them (think of a Pascal-style string), so it is needed to establish some kind of dependency on those bytes. To accomplish this, you can assign a variable name to a span and read its value later when needed. See below for an example of the Pascal string format.

The Format class exposes a fluent API to build formats in a single expression, and can be combined to create complex trees out of simple smaller formats. When you nest formats (using array(), or child(), as well as when using group()), you can always specify a name: this name will be prepended to the name of the inner spans, resulting in names with the following structure:

'Group 1 > Group 2 > A byte'

You can access this class importing hedit/format:

import Format from 'hedit/format';

new Format()
format.js, line 68

See:

  • For a list of the builtin formats, check the source.

Examples
// This is a format describing a sequence of two integers of diffent lengths
const exampleFormat =
    new Format()
        .uint16('A 16 bit integer', 'orange')
        .uint32('A longer 32 bit integer', 'blue');
// This is a format for a Pascal-like string, i.e. a string with its length prefixed.
const pascalString =
    new Format()
        .uint8('String length', 'orange', 'len')
        .array('String contents', 'len', 'blue');
        // The line above is a shortcut for:
        // .array('String contents', vars => vars.len, 'blue');

Methods

array(namenullable, length, child) → {Format}
format.js, line 99

Repeates a child format a fixed number of times.

Parameters:
Name Type Attributes Description
name string <nullable>

Name of this segment.
length integer | function | string

How many times to repeat the child format. If it is an integer, it represents a fixed number of repetitions. If it is a function, it is called with a dictionary of all the available variables and is expected to return an integer. If it is a string, it is treated as a shortcut for vars => vars[length].
child Format

Child format to repeat.
Returns:
Format

array(namenullable, length, coloropt) → {Format}
format.js, line 99

Adds a span of raw bytes to the format.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of this segment.
length integer | function | string

How many times to repeat the child format. If it is an integer, it represents a fixed number of repetitions. If it is a function, it is called with a dictionary of all the available variables and is expected to return an integer. If it is a string, it is treated as a shortcut for vars => vars[length].
color string <optional>
 white

Color of the span.
Returns:
Format

child(name, c) → {Format}
format.js, line 160

Adds a child format to this format. This is equivalent to array(name, 1, c).

Parameters:
Name Type Description
name string

Name of this span.
c Format

Child format to insert.
Returns:
Format

child(c) → {Format}
format.js, line 160

Adds a child format to this format. This is equivalent to array(null, 1, c).

Parameters:
Name Type Description
c Format

Child format to insert.
Returns:
Format

endgroup() → {Format}
format.js, line 232

Ends a group started with group(). There must be a matching call to group().

Returns:
Format
Example
// This generates the following two spans with the following names:
// Group > A byte
// Group > Another byte
new Format()
    .group('Group')
        .uint8('A byte')
        .uint8('Another byte')
    .endgroup();

float32(namenullable, coloropt, idopt) → {Format}
format.js, line 517

Adds a span of 4 bytes to the current format. The difference between the little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

float32be(namenullable, coloropt, idopt) → {Format}
format.js, line 543

Adds a span of 4 bytes to the current format. The difference between the little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

float32le(namenullable, coloropt, idopt) → {Format}
format.js, line 530

Adds a span of 4 bytes to the current format. The difference between the little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

float64(namenullable, coloropt, idopt) → {Format}
format.js, line 558

Adds a span of 8 bytes to the current format. The difference between the little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

float64be(namenullable, coloropt, idopt) → {Format}
format.js, line 584

Adds a span of 8 bytes to the current format. The difference between the little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

float64le(namenullable, coloropt, idopt) → {Format}
format.js, line 571

Adds a span of 8 bytes to the current format. The difference between the little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

group(name) → {Format}
format.js, line 209

Groups multiple spans under a single name. There must be a matching call to endgroup().

Parameters:
Name Type Description
name string

Group name.
Returns:
Format
Example
// This generates the following two spans with the following names:
// Group > A byte
// Group > Another byte
new Format()
    .group('Group')
        .uint8('A byte')
        .uint8('Another byte')
    .endgroup();

int8(namenullable, coloropt, idopt) → {Format}
format.js, line 327

Adds a span of 1 byte to the current format. The difference between the signed and unsigned versions matters only if reading the actual value of the byte.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

int16(namenullable, coloropt, idopt) → {Format}
format.js, line 355

Adds a span of 2 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

int16be(namenullable, coloropt, idopt) → {Format}
format.js, line 381

Adds a span of 2 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

int16le(namenullable, coloropt, idopt) → {Format}
format.js, line 368

Adds a span of 2 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

int32(namenullable, coloropt, idopt) → {Format}
format.js, line 436

Adds a span of 4 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

int32be(namenullable, coloropt, idopt) → {Format}
format.js, line 462

Adds a span of 4 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

int32le(namenullable, coloropt, idopt) → {Format}
format.js, line 449

Adds a span of 4 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

sequence(name, c) → {Format}
format.js, line 184

Adds an infinite sequence of the given child format to this format. This is equivalent to array(name, Infinity, c).

Parameters:
Name Type Description
name string

Name of this span.
c Format

Child format to repeat indefinitely.
Returns:
Format

sequence(c) → {Format}
format.js, line 184

Adds an infinite sequence of the given child format to this format. This is equivalent to array(null, Infinity, c).

Parameters:
Name Type Description
c Format

Child format to repeat indefinitely.
Returns:
Format

uint8(namenullable, coloropt, idopt) → {Format}
format.js, line 341

Adds a span of 1 byte to the current format. The difference between the signed and unsigned versions matters only if reading the actual value of the byte.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

uint16(namenullable, coloropt, idopt) → {Format}
format.js, line 394

Adds a span of 2 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

uint16be(namenullable, coloropt, idopt) → {Format}
format.js, line 420

Adds a span of 2 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

uint16le(namenullable, coloropt, idopt) → {Format}
format.js, line 407

Adds a span of 2 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

uint32(namenullable, coloropt, idopt) → {Format}
format.js, line 475

Adds a span of 4 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

uint32be(namenullable, coloropt, idopt) → {Format}
format.js, line 501

Adds a span of 4 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format

uint32le(namenullable, coloropt, idopt) → {Format}
format.js, line 488

Adds a span of 4 bytes to the current format. The difference between the signed, unsigned, little and big endian versions matters only if reading the actual value of the byte. If no endianess is specified, the default is big endian.

Parameters:
Name Type Attributes Default Description
name string <nullable>

Name of the span.
color string <optional>
 white

Color of the span.
id string <optional>

Name of the variable in which to store the actual value of this byte.
Returns:
Format