Linear 0.5.0

Linear

Linear file structure ingest library

This library uses structure specification files to read structured data from files.

The command-line program lyn provides a simple means for using a structure file to lay out an input file and dump its outputs.

Installation: dotnet tool install -g lyn

Usage: lyn export <structureFile> <inputFile> <outputDir> LinearParser.g4 For structure file examples, see the sample folder. Also check the parser grammar file which has comments for significant elements.

ANTLR4 generates the structure file parser.

Writing structure files

Example

// Structure files follow a simple format.
// For lyn command-line programs, a 'main' struct is needed.
main {
    // '`' means deserialize. Type is taken from type marker intb.
    intb numEntries `0x4;

    // Plain array of 'file' objects starting at 0x10, numEntries elements.
    file[numEntries] entries 0x10;
}

// Structure named 'file' with raw size 0x8 (used in plain arrays)
file 0x8 {
    // Can use explicit deserializer name to get
    // data with 'intb' deserializer at offset 0.
    var offsetChunk intb`0;

    intb length `0x4;

    // Variable depending on offsetChunk.
    int offset (offsetChunk * 0x800);

    // Call registered function 'log' with another call to 'format' (uses string.Format).
    // $i is a replacement for the array index.
    $call log(format("Entry {0} offset {1} length {2}", $i, offset, length));

    // Export content using the 'data' (direct) exporter.
    // Format name (again using string.Format).
    // $a is a replacement for the absolute position of the structure in the stream.
    $output data [offset - $a, length] format("{0:D6}.dat", $i);
}

Ranges

Some deserializers like string and string16 need a range instead of an offset.

These ranges are expressed as [<sourceOffset>..<endOffsetExclusive>] and [<sourceOffset>, <length>]

Standard deserializers

Standard methods

(1) Available replacements: $$i index, $$v value

Standard replacements

• $length
  • Length of array element (only available in plain arrays or extended pointer arrays)
• $a
  • Absolute offset of structure in stream
• $i
  • Index of array element (only available in array context)
• $p / $parent
  • Parent structure (for referencing parent members with '.')
• $u / $unique
  • Unique integer (sequential, for generating output IDs)