134 lines
4.2 KiB
Markdown
134 lines
4.2 KiB
Markdown
# Command line
|
|
|
|
The reference below is taken from the program itself. `interpres-decode` is
|
|
the toml-test harness adapter in both directions, decoding TOML into tagged
|
|
JSON and encoding tagged JSON back into TOML, and it also validates documents.
|
|
Install it with Go itself, no release assets involved:
|
|
|
|
```sh
|
|
go install sourcedock.dev/petrbalvin/interpres/v2/cmd/interpres-decode@latest
|
|
```
|
|
|
|
## Synopsis
|
|
|
|
```sh
|
|
interpres-decode [flags]
|
|
interpres-decode -encode
|
|
interpres-decode -validate [file ...]
|
|
```
|
|
|
|
Without `-validate` or `-encode` the program is the decoding half of 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 `-encode` the direction is reversed: the program reads a tagged-JSON
|
|
description from stdin and writes the TOML document it describes to stdout,
|
|
which is the shape toml-test expects of an encoder command. It takes no
|
|
arguments either, and `-validate` and `-encode` cannot be combined.
|
|
|
|
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 |
|
|
| `-encode` | read tagged JSON from stdin and write TOML instead |
|
|
| `-h` | print the usage |
|
|
|
|
## Exit codes
|
|
|
|
| Code | Meaning |
|
|
|---|---|
|
|
| `0` | adapter: the document parsed and the tagged JSON was written; encode: the TOML was written; validate: every document parsed |
|
|
| `1` | adapter: parse error; validate: at least one document is invalid |
|
|
| `2` | a usage error, a read failure, malformed tagged JSON, or a value with no TOML 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` |
|
|
|
|
The `-encode` mode reads exactly this form back. Two properties of it are
|
|
worth knowing. A float whose value has no fraction and no exponent is written
|
|
as a bare integer string, `{"type": "float", "value": "1"}`, so there the tag
|
|
decides the type and not the literal. And the form cannot tell an array of
|
|
tables from a value array of inline tables, so the adapter writes the header
|
|
form, `[[a]]`, for an array whose every element is a JSON object; a mixed
|
|
array keeps the value form.
|
|
|
|
## 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. Turn a description
|
|
back into TOML with `-encode`:
|
|
|
|
```sh
|
|
echo '{"title": {"type": "string", "value": "hello"}}' | ./bin/interpres-decode -encode
|
|
```
|
|
|
|
```toml
|
|
title = "hello"
|
|
```
|
|
|
|
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`. It runs
|
|
the suite in both directions: the decoder against the valid and invalid
|
|
corpora, and the encoder against the tagged JSON of the valid one. The full
|
|
reference for the library itself is [API.md](API.md).
|