ARCHITECTURE: TOML 1.0.0 Parser
| Field | Value |
|---|---|
| Version | 20260814 V1 |
| Description | Defines the standard-library Go architecture for the TOML parser and decoder command. |
| Depends On | — |
| Provides | parser module boundary, decoder command boundary, tagged JSON contract |
| Consumes | — |
Intent
The application is a deterministic command-line filter that reads TOML 1.0.0 from standard input and emits tagged JSON on standard output. Invalid TOML produces a diagnostic on standard error and a non-zero exit status.
Module Boundaries
| Module | Responsibility |
|---|---|
cmd/toml-decoder | Reads stdin, invokes the parser, encodes successful results, and maps failures to process behavior. |
internal/toml | Parses TOML 1.0.0, validates lexical and structural rules, and exposes the internal value model. |
| JSON encoder | Converts internal values to the required tagged JSON representation. |
The parser separates lexical scanning, structural parsing, semantic validation, value representation, and JSON encoding responsibilities. The internal value model uses explicit value kinds and preserves integer lexemes losslessly.
Technology Stack
| Technology | Use |
|---|---|
| Go | Parser, command, tests, and standard-library integration. |
| Shell | Supplied conformance harness entry points. |
The Go module declares no external dependencies. Runtime behavior uses only the Go standard library.
Process Contract
The decoder accepts no arguments or configuration. It reads the complete TOML document from stdin. Valid input produces one JSON document on stdout and exit status 0. Invalid input produces no successful JSON result, writes diagnostics to stderr, and exits non-zero. The command has no filesystem or network side effects.
Tagged JSON Contract
Tables are JSON objects and arrays are JSON arrays. Each scalar TOML value is represented as an object with type and value fields. The value field is always a JSON string. Supported scalar types are string, integer, float, bool, datetime, datetime-local, date-local, and time-local.
Guardrails
- The implementation uses Go with no
go.moddependencies. - The parser does not import a third-party TOML parser.
- The parser preserves signed 64-bit integer values without floating-point conversion.
- The decoder remains an argument-free stdin/stdout filter.
- Supplied scoring scripts remain unchanged.
Programmatic Acceptance
=== AC architecture-module ===
Intent: The completed build contains the declared Go module and command boundary. from pathlib import Path
module = Path("go.mod") command = Path("cmd/toml-decoder") parser = Path("internal/toml") assert module.is_file() assert command.is_dir() assert parser.is_dir() === END AC architecture-module ===
=== AC architecture-dependencies ===
Intent: The Go module has no third-party dependency declarations. from pathlib import Path
module_text = Path("go.mod").read_text(encoding="utf-8") assert "require " not in module_text assert "github.com/BurntSushi/toml" not in module_text assert "github.com/pelletier/go-toml" not in module_text === END AC architecture-dependencies ===
=== AC architecture-command-build ===
Intent: The declared decoder command builds successfully. import subprocess
result = subprocess.run( ["go", "build", "./cmd/toml-decoder"], capture_output=True, text=True, ) print(result.stdout) print(result.stderr) assert result.returncode == 0 === END AC architecture-command-build ===
User Acceptance
- None.
Guardrails
- None.