106 lines
2.9 KiB
Markdown
106 lines
2.9 KiB
Markdown
# Command line
|
|
|
|
The reference below is taken from the program itself. `interpres-decode` is
|
|
the toml-test harness adapter, and it also validates documents. Install it
|
|
with Go itself, no release assets involved:
|
|
|
|
```sh
|
|
go install sourcedock.dev/petrbalvin/interpres/cmd/interpres-decode@latest
|
|
```
|
|
|
|
## Synopsis
|
|
|
|
```sh
|
|
interpres-decode [flags]
|
|
interpres-decode -validate [file ...]
|
|
```
|
|
|
|
Without `-validate` the program is the toml-test adapter: it takes no
|
|
arguments, reads one TOML document from stdin, and writes the toml-test
|
|
tagged-JSON form to stdout. Build it locally with `just build`, which
|
|
compiles it into `bin/interpres-decode`, or run it straight from the module
|
|
directory with `just run`.
|
|
|
|
With `-validate` the program parses each named file instead, or stdin when no
|
|
file is named, and prints one line per invalid document to stderr. It is
|
|
quiet on valid documents, which is the shape a CI step wants. The `-` name
|
|
means stdin.
|
|
|
|
## Flags
|
|
|
|
| Flag | Effect |
|
|
|---|---|
|
|
| `-validate` | validate the documents instead of emitting tagged JSON |
|
|
| `-h` | print the usage |
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
|---|---|
|
|
| `0` | adapter: the document parsed and the tagged JSON was written; validate: every document parsed |
|
|
| `1` | adapter: parse error; validate: at least one document is invalid |
|
|
| `2` | a usage error, a read failure, or a value with no tagged representation |
|
|
|
|
## Wire format
|
|
|
|
Tables become JSON objects, arrays become JSON arrays, and every scalar is
|
|
wrapped in an object with a `type` and a `value`:
|
|
|
|
```json
|
|
{
|
|
"title": {"type": "string", "value": "hello"},
|
|
"port": {"type": "integer", "value": "9090"},
|
|
"enabled": {"type": "bool", "value": "true"},
|
|
"ratio": {"type": "float", "value": "3.14"}
|
|
}
|
|
```
|
|
|
|
| TOML value | Tag | Rendering |
|
|
|---|---|---|
|
|
| string | `string` | the string verbatim |
|
|
| integer | `integer` | decimal |
|
|
| float | `float` | decimal, or `inf`, `-inf`, `nan` |
|
|
| boolean | `bool` | `true` or `false` |
|
|
| offset date-time | `datetime` | RFC 3339 with nanoseconds |
|
|
| local date-time | `datetime-local` | `1979-05-27T07:32:00` |
|
|
| local date | `date-local` | `1979-05-27` |
|
|
| local time | `time-local` | `07:32:00.999999` |
|
|
|
|
## Examples
|
|
|
|
Echo a small document through the adapter:
|
|
|
|
```sh
|
|
echo 'title = "hello"
|
|
[server]
|
|
host = "127.0.0.1"
|
|
port = 9090
|
|
' | ./bin/interpres-decode
|
|
```
|
|
|
|
The output is the equivalent value tree as one JSON object. Validate the
|
|
TOML files of another repository in CI:
|
|
|
|
```sh
|
|
interpres-decode -validate config.toml deploy/example.toml
|
|
```
|
|
|
|
An invalid document reports the file and the library's line number:
|
|
|
|
```sh
|
|
$ interpres-decode -validate bad.toml
|
|
bad.toml: interpres: line 1: expected a value
|
|
$ echo $?
|
|
1
|
|
```
|
|
|
|
Run the official compliance suite against the adapter:
|
|
|
|
```sh
|
|
just toml-test
|
|
```
|
|
|
|
That recipe needs the `toml-test` binary on `PATH`, installed with
|
|
`go install github.com/toml-lang/toml-test/v2/cmd/toml-test@v2.2.0`. The full
|
|
reference for the library itself is [API.md](API.md).
|