Linear 0.4.0

Linear

Linear file structure ingest library

This library uses structure specification files to read structured data from files. It is built for .NET Standard 2.1.

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

Usage: lyn <structureFile> <inputFile> <outputDir>

Builds (requires .NET 7 runtime) are generated by this workflow.

For structure file examples, see the sample folder. Also check the 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)