Inlay

This program provides a very simple translation from binary data to csv, and csv to binary data. It is intended for working with simple, fixed size binary formats, and especially for initial testing and development while there may not be tools specific to the format.

Usage

inlay 0.3.2
nsmryan <nsmryan@gmail.com>
A command line tool for quickly reading and writing simple binary formats

USAGE:
    inlay.exe <SUBCOMMAND>

FLAGS:
    -h, --help       Prints help information
    -V, --version    Prints version information

SUBCOMMANDS:
    decode    CLI tool for encoding and decoding simple binary data structures
    encode    CLI tool for encoding and decoding simple binary data structures
    help      Prints this message or the help of the given subcommand(s)
    summary   CLI tool for encoding and decoding simple binary data structures

Decoding

USAGE:
    inlay.exe decode [FLAGS] [OPTIONS] <template_file> [in_file_globs]...

FLAGS:
    -h, --help       Prints help information
    -r, --rows       Decode row based file
    -V, --version    Prints version information

OPTIONS:
    -l, --log-level <log_level>     [default: error]
    -o, --output <out_file>         [default: ]

ARGS:
    <template_file>
    <in_file_globs>...

Encoding

USAGE:
    inlay.exe encode [FLAGS] [OPTIONS] <template_file> [in_file_globs]...

FLAGS:
    -h, --help       Prints help information
    -r, --rows       Encode row based file
    -V, --version    Prints version information

OPTIONS:
    -l, --log-level <log_level>     [default: error]
    -o, --output <out_file>         [default: ]

ARGS:
    <template_file>
    <in_file_globs>...

Summary

USAGE:
    inlay.exe summary <template_file>

Installation

The 'inlay' tool can be installed with cargo using the command:

cargo install inlay

There are also releases available.

Template Files

The 'inlay' program makes use a template files, which are just csv files with a name and type for fields. These files are intended to be simple to write or generate, containing a simple format specifier described below, and a name to refer to the field.

These files can also contain a 'value' column, and can be encoded into binary without a separate file of values.

An example template file for a CCSDS Primary Header would look like:

type,description
uint11_be:16, apid
uint1_be:16, secHeaderFlag
uint1_be:16, type
uint3_be:16, version
uint14_be:16, seqCount
uint2_be:16, seqFlag
uint16_be, packetLen

Types

The types are given by the following regex: (uint8|uint16|uint32|uint64|int8|int16|int32|int64|float|double)_(be|le)

Any field can be big endian or little endian, allowing mixed endianness within a file.

For example, an unsigned, big endian with a width of 16 bits would be 'uint16_be'.

Note that bit fields are given with an integer width after a colon (unlike in C/C++), so a 3 bit integer within a 16 bit bitfield would be 'uint3_be:16'.

CSV -> Binary

When building a binary file, the data to encode can be provided as either a 'row-based' or 'column-based' csv file.

Row Based

A row based csv file in the following format must be provided:

type,description,value
uint8\_be,field1,1
uint16\_be,field2,141
uint32\_be,field3,1245

The header must have fields typ, description, and value, in that order.

Column Based

A column based csv file provides a header with fields for each field of the binary structure, and must have a template file:

type,description,value
uint8\_be,field1,1
uint16\_be,field2,141
uint32\_be,field3,1245

Note that if a 'value' column is present it is ignored. This template file is used to match field names to the field in the data file, and gives the types to use when encoding its data.

Binary -> CSV

When translating binary to CSV, a file of the following format must be provided: type,description uint64_be,a 64 bit field uint8_be,an 8 bit field

This file must have a header "type,description" and any number of entries with a type as defined above. The description is optional and will be copied into the output csv file.

The output csv file is in exactly the same format as the input csv file when encoding from CSV -> Binary. This means that a binary structure can be decoded, modified and written back. To assist with this use case, if the "template" file given during decoding has a "values" column it will be ignored. This allows a csv file from decoding to be used as the template when decoding other instances of a binary structure.

Variations in Use

There are several ways to run the 'inlay' tool. The main way is to either encode or decode a series of records, such as decoding a binary file containing one or more record, or encoding a csv file containing a record of data for each line.

Encode

Encode a single file into a binary file, row format:

• inlay encode template.csv
• inlay encode template.csv -o data.bin

Encode a column csv file into a binary file:

• inlay encode template.csv data.csv
• inlay encode template.csv data.csv -o data.bin

Encode multiple input files into their own binary files:

• inlay encode template.csv data.csv
• inlay encode template.csv data.csv data2.csv data3.csv

Encode multiple input files into a single binary file:

• inlay encode template.csv data.csv
• inlay encode template.csv data.csv data2.csv data3.csv -o data.bin

Decode

Decode a single binary file, row format:

• inlay decode template.csv data.bin -r

Decode a single binary file, col format:

• inlay decode template.csv data.bin

Decode multiple binary files, row format:

• inlay decode template.csv data.bin data2.bin data3.bin -r

Decode multiple binary files, col format:

• inlay decode template.csv data.bin data2.bin data3.bin -r

Decode multiple binary files into a single file, row format:

• inlay decode template.csv data.bin data2.bin data3.bin -r -o output.csv

Decode multiple binary files into a single file, col format:

• inlay decode template.csv data.bin data2.bin data3.bin -o output.csv

Summary

Summarize your binary format:

• inlay summary template.csv

This provides a printout of the binary structure, providing byte and bit sizes as well as byte and bit offsets from the start of the structure.

License

Inlay is licensed under either MIT or APACHE2, whichever you prefer.