hedit/format~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 73

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, coloropt) → {Format}
format.js, line 104

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

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

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

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

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 165

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 237

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();

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

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();

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

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 189

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