Beagle SCM

BEE-075: snippet variables wear a $ — $1 one token, $a zero or more, $A one or more

Ruled 2026-09-18 (gritzko): a spot snippet's variables are $-prefixed and a bare letter is always a literal. BEE-074 ported be's matcher with bare-letter variables, where a one-letter name (i, union U) could never be matched as itself and a block could not be empty, so every callable needed two def rules. Patch bee's matcher and def table; libdog changes only where needed. Main-tree work permitted, no commits.

Input

Context

• index/match.js: isPlaceholder takes any single letter; lowercase binds one token, uppercase a balanced block of one or more.
• index/match.js:241:vT a block refuses to start on a closing bracket, so f(A) never matches f().
• index/defs.js carries rule pairs (s(A){B} and s(){B}) and an allow-list entry for an empty { } body.
• Lexers disagree on $: .c, .js, .sh keep $1 whole, .go, .py, .rs, .rl cut it (12 vs 15 tokens for one needle).
• tok/LINK.rl takes a snippet body as opaque bytes, so the link grammar and tok.link need no change (DOG-050).

Goals

• $1..$9 bind exactly ONE token; $a..$z a balanced block of ZERO or more; $A..$Z a block of ONE or more.
• $0 is a def template's name slot, swapped for the symbol before lexing; a user needle may not hold it. $$ is a literal $.
• The needle's $x become opaque identifiers BEFORE lexing, in every language alike; a $x inside a string token stays text.
• $a tries empty first, then shortest-first; an empty bound block recurs as empty.
• A block with no literal after it runs to the end of its bracket level or to ;; two adjacent blocks are a malformed needle.
• Two spaces stay a gap. A replace template is substituted by a function, never handed to String.replace.
• index/defs.js in the new notation ($0($a){$b}, typedef $A $0;): rule pairs collapse, the allow-list goes if it can.
• Repro first (work 3): f($a) takes f(), f($A) does not, a bare i is literal, one needle works in .c, .js, .go.

Constraints

• Existing suites green, no edits to tests older than BEE-074; comment budgets per comment; README and INDEXES follow.
• libdog: nothing but the stale x/X comment at tok/LINK.h:20:Ha (fixed); a lexer change there needs its own DOG ticket.
• Out of scope: beagle's spot/SPOT.c and be's views/spot/match.js keep the old notation; bee and links are the work here.

WIP

Design decisions

• Arity is the author's choice, not inferred from the next literal: = $a - 1 may bind empty because the author wrote $a.
• One opaque-identifier path for all languages over per-lexer $ fusing: no dependence on what a tokenizer does with $.
• On a command line a needle goes in single quotes: "f($1)" is f() to sh, fish and PowerShell alike (BEE-073).

TODOs

• red tests for the new notation and arities
• index/match.js: the sentinel swap, $a empty-first, the trailing block, adjacent-block rejection
• index/defs.js rewritten, the corpus cross-check green
• README.mkd, INDEXES.mkd, the anchor and scope suites in the new notation

Blockers and bummers

• The sentinel is Zq<nn>qZ: one identifier token in c, h, cpp, js, jsx, ts, tsx, go, py, rs, rl, mkd, md, txt, sh, java.
• A sentinel butting onto an identifier byte would fuse with it, so one space is inserted there; $a$b then reads as two.
• Ruled nowhere, decided here: a $ no variable follows ($(, $ ) is a LITERAL $; only $0 in a needle is refused.
• The old anchor-guided lookahead went with the bare letters: a block now enumerates its extents shortest-first instead.
• That is simpler and takes the ruling verbatim, but it is no longer a line-for-line twin of spot/SPOT.c, which is untouched.
• Both of BEE-074's template bummers died here: the span-carries-the-name guard and the empty-body allow-list are gone.
• Every callable rule pair collapsed to one, and .go/.rs lost their two-space gaps to a $b before the body brace.
• tok/LINK.h:20:Ha was NOT touched: dog/ is read-only here, so the stale x/X comment is reported, not fixed.

Outcome

Working tree only, nothing committed. index/match.js swaps every $x for an opaque identifier before lexing, tells variables apart by sentinel after it, and binds a block by enumerating its extents shortest-first — empty first for $a, maximal for a block no literal follows; a needle with adjacent blocks or a block beside a gap is refused in words at make. index/defs.js carries the templates in the new notation, $0 swapped by hand for the symbol. test/anchor is 14 shell + 50 JS checks (21 of them new), test/scope 7 + 14; all 79 suites green.