interpres/docs/CLI.md

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:

go install sourcedock.dev/petrbalvin/interpres/v2/cmd/interpres-decode@latest

Synopsis

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:

{
  "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:

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:

echo '{"title": {"type": "string", "value": "hello"}}' | ./bin/interpres-decode -encode

title = "hello"

Validate the TOML files of another repository in CI:

interpres-decode -validate config.toml deploy/example.toml

An invalid document reports the file and the library's line number:

$ interpres-decode -validate bad.toml
bad.toml: interpres: line 1: expected a value
$ echo $?
1

Run the official compliance suite against the adapter:

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.