Document er-macro-transformer and channel-timeout-exception? - #40
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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)
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 againstsrc/expander.zig(erCompareFn) rather than the issue text, plus the pinned ER≡syntax-rules hygiene guarantee, acond-expandfeature test, and a "when to reach for it" section with an expansion-time-validation example. States plainly that this is not R7RS-large'ssyntax-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 thesyntax-casegap row now mentions the ER surface that does exist.docs/guide/language.mdMacros 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-testedguardexamples for both send and receive;channel-send/channel-receiveprose updated — expiry with a timeout but notimeout-valraises a distinct, testable channel-timeout condition (message"channel-send: timed out"/"channel-receive: timed out"), the direct analog of SRFI-18'sjoin-timeout-exception?, not a generic error.docs/guide/concurrency.md: new "Channel timeouts" subsection in the fibers section.Verification
KAAPPI_HOME=$(mktemp -d)), including the full cumulative channel-blocks replay of extensions.md.mkdocs build --strictpasses (exit 0) — new page is wired into nav, all anchors resolve.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