Skip to content

Document er-macro-transformer and channel-timeout-exception? - #40

Merged
baijum merged 1 commit into
mainfrom
docs-er-macro-and-channel-timeout
Aug 28, 2026
Merged

Document er-macro-transformer and channel-timeout-exception?#40
baijum merged 1 commit into
mainfrom
docs-er-macro-and-channel-timeout

Conversation

@baijum

@baijum baijum commented Aug 28, 2026

Copy link
Copy Markdown
Member

Two shipped-but-undocumented surfaces, one PR — both are pure prose touching no engine code, in disjoint files.

er-macro-transformer — user-facing docs (KEP-0006 step 6)

  • New page docs/guide/er-macros.md (nav: Guide → Language, right after Language Reference): the (form rename compare) convention, rename's referential transparency (fresh identifiers, definition-site resolution, same-identifier-per-invocation, datum-wide renaming), compare's binding-aware free-identifier=? semantics — "same binding or both unbound," the exact rule a syntax-rules literal matches by, refusing a shadowed use-site spelling — verified against src/expander.zig (erCompareFn) rather than the issue text, plus the pinned ER≡syntax-rules hygiene guarantee, a cond-expand feature test, and a "when to reach for it" section with an expansion-time-validation example. States plainly that this is not R7RS-large's syntax-case (KEP-0007) and does not re-litigate the sibling sub-libraries — links the dev notes instead.
  • docs/conformance.md: new row in the "Extensions beyond R7RS-small's scope" table (KEP-0006, Final, shipped v0.22.0 — verified against the tag), and the syntax-case gap row now mentions the ER surface that does exist.
  • Cross-links: docs/guide/language.md Macros section, docs/guide/index.md, docs/guide/srfi-support.md's SRFI-211 row, and the Next-link chain.

channel-timeout-exception? — document the timeout condition

  • docs/procedures/extensions.md: full reference entry ({ #channel-timeout-exception } + index metadata, so the generated procedures index picks it up) with REPL-tested guard examples for both send and receive; channel-send/channel-receive prose updated — expiry with a timeout but no timeout-val raises a distinct, testable channel-timeout condition (message "channel-send: timed out" / "channel-receive: timed out"), the direct analog of SRFI-18's join-timeout-exception?, not a generic error.
  • docs/guide/concurrency.md: new "Channel timeouts" subsection in the fibers section.

Verification

  • Every code sample executed against the v0.25.0 core binary (KAAPPI_HOME=$(mktemp -d)), including the full cumulative channel-blocks replay of extensions.md.
  • mkdocs build --strict passes (exit 0) — new page is wired into nav, all anchors resolve.
  • The new concurrency.md block shifts the sweep's hardcoded block indices in scripts/sweep/sweep_guide.py; renumbered and the block added to the checked program. Sweep sections re-run green locally: concurrency (2 passed), language, extensions.md (63 checks).

Closes kaappi/kaappi#2392
Closes kaappi/kaappi#2396

Two shipped-but-undocumented surfaces, both user-facing prose:

er-macro-transformer (KEP-0006 step 6): new guide page (Guide > Language,
after Language Reference) covering the (form rename compare) convention,
rename's referential transparency, compare's binding-aware
free-identifier=? semantics (settled by kaappi#2388), the cond-expand
feature test, and a syntax-rules-vs-ER choosing guide — stating plainly
it is not R7RS-large's syntax-case (KEP-0007). Wired into mkdocs.yml nav,
the conformance extensions table (which also now mentions the ER surface
in the syntax-case gap row), the language guide's Macros section, the
guide index, and the SRFI-211 row on the SRFI support page.

channel-timeout-exception? (KEP-0002 Phase 4): documented in the
channels section of the Concurrency guide and as a full reference entry
in procedures/extensions.md — channel-send/-receive with a timeout but
no timeout-val raise a distinct, testable channel-timeout condition (the
direct analog of SRFI-18's join-timeout-exception?), with guard examples.

The new concurrency.md code block shifts the sweep's hardcoded block
indices; renumbered and the block added to the checked program. All
samples verified against the v0.25.0 binary; mkdocs build --strict and
the guide/procs sweep sections pass.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Signed-off-by: Baiju Muthukadan <baiju.m.mail@gmail.com>
@baijum
baijum merged commit cef70a8 into main Aug 28, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant