Skip to content

Scopes what parse and compile refuse in the README - #163

Merged
johnnyt merged 1 commit into
mainfrom
pts-d3ft-readme-parse-compile-sentences
Oct 1, 2026
Merged

johnnyt merged 1 commit into
mainfrom
pts-d3ft-readme-parse-compile-sentences

Conversation

@johnnyt

@johnnyt johnnyt commented Oct 1, 2026

Copy link
Copy Markdown
Member

Bead: pts-d3ft

What changes

README only (an also-gated path, so the full gate ran).

  • The decompile example's comment said parse refuses exactly what compile refuses. It now says parse refuses every source whose scan or grammar fails, with the refusal compile answers for that source, and that the converse does not hold: compile runs an emitter parse does not, and the emitter refuses a numeric literal the value domain cannot hold and a source its walk counts past the depth limit where the grammar's count stops short. A new executed check in the same block shows a library hold rule with an oversized literal parsing and being refused by compile with number_out_of_range.
  • The Ast paragraph scopes the round-trip promise: for a source compile accepts, decompile(parse(source).ast) keeps answering what the reference answers for that source.
  • The paragraph opening "Compiling an expression from its source text is compile" no longer says the statement grammar arrives in a later release. It names compileProgram and its two located siblings beside compile and its two, and says execute and executeValue run a source string as a statement program while evaluate compiles an expression, as src/index.ts and src/compile.ts do on main.
  • The "The entry points" bullet for the main entry point is rewrapped to the wrap width of its neighbours.

Provenance

  • The entry-points bullet also gains the statement program in its list (the compilation of a statement program's source text, and the run of a list), so the bullet describes the entry point as it is; beyond the rewrap the bead's note asked for.
  • A second overlong line, in the paragraph after the decompile example, is rewrapped (whitespace only).

Checks

  • Full gate (mise exec -- pnpm run gate) green on the committed tree; the README examples run under test/readme.test.ts.
  • Two sabotage checks on the new example, each restored byte-equal: expecting a different reason for the compile refusal, and making the parsed source ungrammatical; each turned test/readme.test.ts red on the example's own thrown check.
  • No changelog fragment: documentation only, per changelog.d/README.md.

Review

Own in-turn review round (gate tier): every new sentence was checked against src/index.ts (parse's doc comment, which names the two emitter-only refusals) and src/compile.ts on main, and the oversized-literal behaviour was run before it was written down.

The README's decompile example said parse refuses exactly what compile
refuses. It now says parse refuses every source whose scan or grammar
fails, and shows compile refusing a numeric literal parse accepts,
since the emitter refuses on its own account. The Ast paragraph scopes
the round-trip promise to sources compile accepts.

The paragraph that said the statement grammar arrives in a later
release now names compileProgram, its two located siblings, and the
program run that execute and executeValue perform on a source string.
Two overlong lines are rewrapped.
@johnnyt
johnnyt merged commit fe15d4b into main Oct 1, 2026
1 check passed
@johnnyt
johnnyt deleted the pts-d3ft-readme-parse-compile-sentences branch October 1, 2026 14:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant