docs: document set and changelog

Assisted-by: GLM 5.3 Flash
2026-08-19 18:44:00 +02:00
parent 8266dd6450
commit d12da6181d
8 changed files with 1114 additions and 0 deletions
@@ -0,0 +1,71 @@
+# Command line
+
+The reference below is taken from the program itself. `interpres-decode` is the
+toml-test harness adapter, not a general-purpose tool: it takes no flags and no
+arguments, reads one TOML document from stdin, and writes the toml-test
+tagged-JSON form to stdout.
+
+## Synopsis
+
+```sh
+interpres-decode < document.toml
+```
+
+Build it with `just build`, which compiles it into `bin/interpres-decode`, or
+run it straight from the module directory with `just run`.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | the document parsed, tagged JSON written to stdout |
+| `1` | parse error, the document is malformed; the message goes to stderr |
+| `2` | reading stdin failed, or a value has 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. Run the official
+compliance suite against the binary:
+
+```sh
+just toml-test
+```
+
+That recipe needs the `toml-test` binary on `PATH`, installed with
+`go install github.com/toml-lang/toml-test/cmd/toml-test@v1.6.0`. The full
+reference for the library itself is [API.md](API.md).