petrbalvin/interpres
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

feat(cmd): add the encoder mode to the toml-test adapter
Test / test (push) Successful in 1m33s
Details

Browse Source 
Assisted-by: DeepSeek V4.1 Flash
This commit is contained in:
petrbalvin
2026-09-19 11:38:19 +02:00
parent 0149a5b4d1
commit bccaf087c8
10 changed files with 418 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/CLI.md
+40 -12
View File
@@ -1,8 +1,9 @@
# 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:
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
@@ -12,14 +13,20 @@ go install sourcedock.dev/petrbalvin/interpres/v2/cmd/interpres-decode@latest
```sh
interpres-decode [flags]
interpres-decode -encode
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`.
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
@@ -31,15 +38,16 @@ means stdin.
| 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; validate: every document parsed |
| `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, or a value with no tagged representation |
| `2` | a usage error, a read failure, malformed tagged JSON, or a value with no TOML representation |
## Wire format
@@ -66,6 +74,14 @@ wrapped in an object with a `type` and a `value`:
| 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:
@@ -78,8 +94,18 @@ 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:
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
@@ -101,5 +127,7 @@ 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
`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).