formaty/README.md

89 lines
2.9 KiB
Markdown
Raw Normal View History

# Formaty
2022-04-09 19:53:14 +00:00
A simple configurable binary data parser. Data structures are described using TOML files.
2022-04-09 19:53:14 +00:00
## 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,
2022-05-04 02:12:54 +00:00
`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
* `Format`: Allows formats to include other formats
* `format_name`: Format definition to use
#### Example Config
[Example](./formats/example.toml)
2022-04-09 19:53:14 +00:00
## Example
```bash
2022-04-09 19:53:14 +00:00
./formaty ccsds "[0xe0, 0xa1, 0xc0, 0x00, 0x00, 0x05, 0x01, 0x02, 0x03, 0x04, 0x05]"
````
Output:
```
Version Number: 0
2022-04-09 19:53:14 +00:00
Packet Type: 1
Secondary Header Flag: 0
2022-04-09 19:53:14 +00:00
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
2022-04-09 19:53:14 +00:00
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]
2022-04-09 19:53:14 +00:00
ARGS:
<format> Format to parse data as
<data>... Raw data
```
## License
[License](./LICENSE)