formaty/README.md

# Formaty
A simple configurable binary data parser. Data structures are described using TOML files.

## Formats
All formats in [formats](./formats) are included in the `formaty` binary. See [formats.md](./formats/formats.md) for
more info.

### Configuration

#### Format
A format is a collection of fields that describe the structure of data, so it can be parsed

Members:
* `name` - name of the format, used as the argument when selecting the format to parse the data as
* `bit_flip` - should individual bytes have their bits flipped within, individual fields can override this
* `fields` - 1 or more fields to describe the structure of the data

#### Field
A field is a collection of bits that make up some sort of data. Formaty supports `Int`/`Uint` of arbitrary size, 
`Float`, `Double`, `Strings` and `Bytes`. This data does not need to be byte aligned. 

Members:
* `name` - the name of the field, used while displaying data
* `field_type` - the type of the field and associated data
* `print_type` - how to print the data, if not provided it uses the default print for a type
* `bit_flip` - overrides the global bit flip field, defaults to false if not provided

#### Field Types
* `UInt`/`Int`: standard integer types. Unsigned or signed respectively. Can be 1 or more bits. 
  * `bit_width`: number of bits composing the integer
  * `endianess`: byte ordering of the field
* `Float`/`Double`: Standard float point types of 32-bit or 64-bit width
    * `endianess`: byte ordering of the field
* `String`: Collection of bytes ended by a null character '\0'
    * `max_len`: max length of the data
    * `endianess`: byte ordering of the field
* `Bytes`: Collection of bytes with no termination
    * `max_len`: max number of bytes
    * `endianess`: byte ordering of the field

#### Example Config
[Example](./formats/example.toml)

## Example
```bash
./formaty ccsds "[0xe0, 0xa1, 0xc0, 0x00, 0x00, 0x05, 0x01, 0x02, 0x03, 0x04, 0x05]"
````

Output:
```
Version Number: 0
Packet Type: 1
Secondary Header Flag: 0
APID: 0x200
Sequence Flags: 3
Packet Sequence Count: 0
Data Length: 5
Data: [1, 2, 3, 4, 5]
```

## Help
```
Formaty 0.1.0
Arbitrary Binary Data Formatting

USAGE:
    formaty [FLAGS] [OPTIONS] <format> [data]...

FLAGS:
    -h, --help       Prints help information
    -s, --stdin      Input data from stdin
    -V, --version    Prints version information

OPTIONS:
    -b, --base <base>                      Base of the input values
    -c, --config <config>                  Path to the format config [env: FORMATY_CONFIG=]
    -g, --global_config <global-config>    Path to the global config directory [env: FORMATY_GLOBAL_CONFIG=]
    -f, --file <input-file>                Input data from file
    -i, --input_type <input-type>          Input data type [default: array]

ARGS:
    <format>     Format to parse data as
    <data>...    Raw data
```

## License
[License](./LICENSE)