Skip to content

AGENTS.md

Latest commit

 

History

History
74 lines (61 loc) · 3.76 KB

AGENTS.md

File metadata and controls

74 lines (61 loc) · 3.76 KB
Raw

Copilot instructions for tomlet

Build, test, and lint commands

  • just build or gleam build compiles the package.
  • just test runs gleam test plus the upstream TOML corpus checks.
  • gleam test runs the Gleam unit tests only.
  • gleam test --target javascript runs the unit tests on the JavaScript target.
  • python3 scripts/run_corpus_tests.py valid runs only valid TOML corpus checks.
  • python3 scripts/run_corpus_tests.py invalid runs only invalid TOML corpus checks.
  • python3 scripts/run_corpus_tests.py runs all corpus checks.
  • just format runs gleam format src test.
  • just lint runs gleam format --check src test.
  • just docs runs gleam docs build.
  • just ci or just pr runs format, lint, test, build, and docs.

Gleeunit discovers every public function ending in _test under test/. It does not expose a built-in name filter. For a single Erlang-target test after test beams have been compiled, run:

erl -noshell -pa build/dev/erlang/*/ebin -eval 'case eunit:test({'"'"'tomlet@parser_test'"'"', parse_booleans_test}, [verbose]) of ok -> halt(0); error -> halt(1) end.'

Replace tomlet@parser_test and parse_booleans_test with the module and test function you want.

Architecture

Tomlet is a round-tripping TOML parser and writer for Gleam. The public API is the top-level tomlet module. Document is opaque and stores an internal tomlet/ast.Table, trailing trivia, original line-ending style, and the original source when available so unedited parsed documents can round-trip exactly.

The internal modules listed in gleam.toml are implementation details:

  • tomlet/ast defines the trivia-preserving syntax tree, including source text for values that must preserve lexical representation.
  • tomlet/parser parses normalized LF text into the internal AST, detects duplicate keys, validates TOML syntax, and reports byte offsets.
  • tomlet/path resolves key paths across root keys, standard tables, dotted keys, inline tables, nested inline tables, and arrays of tables.

The top-level tomlet module converts internal AST values into stable public mirror types before returning them, maps internal parser errors to stable public ParseError variants, and keeps edit operations checked through Result(Document, EditError).

Corpus checks are generated by scripts/run_corpus_tests.py. It clones toml-lang/toml-test into .toml-test/, writes temporary Gleam test modules for valid and invalid TOML 1.0 fixtures, runs both Erlang and JavaScript targets, and removes generated files afterward. Valid fixtures are expected to round-trip byte-for-byte unless explicitly listed in ROUNDTRIP_UNSUPPORTED.

Key conventions

  • Keep all supported user-facing API in src/tomlet.gleam; do not expose or document tomlet/ast, tomlet/parser, or tomlet/path as public API unless intentionally changing the release boundary.
  • Public variant types in tomlet.gleam are semver-stable and matchable. Adding, removing, or renaming variants is a breaking change.
  • Convert internal AST values to public tomlet.Value variants before exposing them.
  • Preserve round-trip behavior: unedited parsed documents return their original source, edits preserve nearby comments, key order, trivia, and CRLF/LF style.
  • Keep date, time, and datetime public types opaque; expose lexical forms through *_to_string helpers.
  • Inline table edits may replace existing nested values, but inserting missing nested keys inside an existing inline table returns InlineTableInsertUnsupported.
  • Parse byte input with parse_bytes when UTF-8 or BOM validation matters. Invalid byte encodings should be rejected with InvalidEncoding.
  • User-facing changes should include a Changie fragment in .changes/unreleased/ using the labels configured in .changie.yaml.