import type { Combinator } from '../types.ts' import type { HostMode } from '../cst/host-mode.ts' import type { Runnable } from '../functional/run.ts' import { any } from './first-set.ts' import { ref } from './ref.ts' import { UnresolvedReference } from '../analysis/children.ts' import { markUnusedValues } from '../compiler/value-usage.ts' import { collectAfterLink } from './link-scope.ts' import { parser as grammarParser } from './grammar.ts' import { collectGrammarReflection, NODE_TAG, NODE_TYPE, type GrammarWithReflection } from '../cst/reflection.ts' import { attachGrammarReflection } from '../cst/reflection-attach.ts' /** * Non-enumerable key on a `rules()` result holding the factory's declaration * order (the returned object's key order), which differs from the result's own * reference-creation key order. Read by `parseman/spec` for source-order output. */ export const RULE_ORDER = '__parsemanRuleOrder' function tagRule(r: Combinator, key: string): void { ;(r as unknown as { _ruleName?: string })._ruleName = key if (r._def.tag === 'node' && r._def.type === undefined) r._def.type = key } type DefinableRef = Combinator & { define(p: Combinator): void } function isDefinableRef(v: unknown): v is DefinableRef { return !!v && typeof v === 'object' && '_def' in v && (v as { _def: { tag?: string } })._def.tag === 'lazy' && typeof (v as { define?: unknown }).define === 'function' } /** The rule name a `prior.X` placeholder stands for (see `linkRules`), or `undefined`. */ export function priorNameOf(r: Combinator): string | undefined { return (r as unknown as { _priorOf?: string })._priorOf } function ruleNameOf(r: Combinator): string | undefined { return (r as unknown as { _ruleName?: string })._ruleName } function isNamedRuleRefForAnotherRule(r: Combinator, key: string): boolean { if (r._def.tag !== 'lazy') return false // A `prior.X` hole stands for an earlier piece's rule, never for this key. if (priorNameOf(r) !== undefined) return true const name = ruleNameOf(r) return name !== undefined && name !== key } /** Every rule value a finished `rules()` call holds. See `ownRule`. */ const claimedRules = new WeakSet() /** * `rules()` stamps its options (`trivia`, `scanSkip`, `hostMode`, `trackLines`) and the * rule name onto the rule object itself. So a value ANOTHER grammar already holds — one * terminal returned by two factories, or a rule of grammar A returned by grammar B — * must not be stamped in place: the second grammar would overwrite the first's options, * or inherit them wherever it omits one, and the two would parse different input than * either declared. This grammar takes its own shallow copy instead, with none of those * stamps. (A rule ref's `parse` still reads the meta it closes over — that is the other * grammar's rule carrying its own trivia, exactly as a `g.X` reference to it would.) */ function ownRule(p: Combinator, copies: Map>): Combinator { // A trivia rule is never stamped, and its identity is what ties it to `{ trivia }`. if (!claimedRules.has(p) || p._meta.isTrivia) return p let own = copies.get(p) if (own === undefined) { const { grammarTrivia: _t, grammarScanSkip: _s, grammarHostMode: _h, grammarTrackLines: _l, ...meta } = p._meta // One copy per grammar, so a value under two keys stays one object here too. copies.set(p, own = { ...p, _meta: meta }) } return own } /** * Define named grammar rules without forward declarations. * * Pass a factory that receives all rule names as references (via a Proxy) * and returns a record of combinators. rules() handles creating ref() * placeholders and wiring them up — the user never sees ref() at all. * * const { value } = rules(g => ({ * value: choice(g.object, g.array, str, num, bool, nil), * object: transform(sequence('{', sepBy(g.pair, ','), '}'), Object.fromEntries), * array: transform(sequence('[', sepBy(g.value, ','), ']'), ([, items]) => items), * pair: transform(sequence(g.key, literal(':'), g.value), ([k,, v]) => [k, v]), * })) * * Not every name in the factory must appear in the returned object — local helpers * (like `comma`, `key`) can be plain const inside the factory and composed normally. * Only names that OTHER rules reference via `g.xxx` need to be in the returned record. * * TypeScript: use an explicit type parameter for full type safety on `g`: * rules<{ value: Combinator; array: Combinator }>(g => ({ ... })) * Without it, `g.*` accesses are typed as `any` but the return is still inferred. */ /** * Grammar-level options for `rules()`. Parity with `parser({...})`, but declared * ONCE for the whole grammar instead of wrapped around a scope. `trivia` becomes * the ambient trivia for every rule (installed at the parse entry, inherited * everywhere, incremental parse included); `parser({trivia})` / `noTrivia` still * override it locally for a sub-region. */ export type RulesOptions = { /** Ambient trivia for the whole grammar. See `parser({ trivia })` for the shape * (`null` clears it — equivalent to omitting it at the grammar level). */ trivia?: Combinator | null /** * Ambient scan-skip for the whole grammar: opaque non-trivia units (strings, * balanced brackets, …) that a `scanTo`/`balanced` with no explicit `skip` * consults so a sentinel hidden inside one is never matched. Declared ONCE here * and inherited everywhere, mirroring `trivia`. `null`/absent = none. */ scanSkip?: Combinator[] | null /** * Compile-time host mode for this grammar, same meaning as `compile(g, { hostMode })` * and `compose(items, { hostMode })`: `'ast'` (default) emits each direct builder's * own result and NO positioned-CST branch; `'cst'` builds every node through the * `ctx.build` host and captures unconditionally. * * Declaring it HERE is what lets ONE grammar source serve both consumers under the * macro, which cannot take a compile option any other way: * * ```ts * const factory = (g: any) => ({ … }) * export const grammar = rules({ trivia: rw }, factory) * export const cstGrammar = rules({ trivia: rw, hostMode: 'cst' }, factory) * ``` * * Two call sites over one factory, so the macro emits two independent top-level * artifacts and each bundle tree-shakes away the one it does not import. Neither * pays the other's cost — which is the whole reason host mode is a compile-time * decision rather than a per-node runtime read. * * The INTERPRETER routes dynamically off the host and does not need this; it is * still recorded, so `run()` can refuse a mismatched host once per parse instead of * quietly producing the wrong tree shape. */ hostMode?: HostMode /** * Compile-time line tracking for this grammar. Under the macro this emits a * separate line-aware artifact from the same factory; the default artifact * remains free of line-tracking helpers and branches. */ trackLines?: boolean } // Options-first, mirroring `parser({ opts }, combinator)` — set once on the grammar // vs scope it locally, same options in the same position. The bare `rules(factory)` // form is unchanged. The impl also tolerates the legacy `rules(factory, opts)` order. type RuleNodeType = C extends { readonly [NODE_TYPE]?: infer T extends string } ? [T] extends [never] ? K : T : K type RuleNodeTag = C extends { readonly [NODE_TAG]?: infer Tag extends string } ? Tag : never type RuleMapNodeType>> = { [K in keyof T & string]: RuleNodeType }[keyof T & string] type RuleMapNodeTag>> = { [K in keyof T & string]: RuleNodeTag }[keyof T & string] type RulesResult>> = T & GrammarWithReflection, RuleMapNodeTag> /** * The second parameter of a `rules((g, prior) => …)` factory. `prior.X` is the * definition of `X` that the grammars composed BEFORE this one gave it, with a * top-level `node()` unwrapped to its body, so a composing grammar can re-reduce, * wrap or extend an inherited rule without re-spelling it: * * rules((g, prior: PriorRules) => ({ * Value: node('Value', prior.Value, reduceValue), * })) * * Naming the base grammar types `prior.X`, and a misspelled rule fails to compile. * * Its `g.X` references stay bound to the composition (open recursion). A rule's value * is `unknown` here, because unwrapping a `node()` changes it. Unnamed, the parameter * answers any string, which `noUncheckedIndexedAccess` reads as possibly undefined. * See `docs/guide/extending.md`. */ export type PriorRules>> = [KnownRuleNames] extends [never] ? { readonly [name: string]: Combinator } : { readonly [K in KnownRuleNames]: Combinator } /** The rule names a grammar's type spells out: not its index signature, if it has one. */ export type KnownRuleNames = keyof { [K in keyof Base as string extends K ? never : number extends K ? never : Base[K] extends Combinator | Runnable ? K : never]: unknown } & string const priorUnfilled = (key: string): Error => new UnresolvedReference(`compose: prior.${key} is read, but no grammar composed before it defines "${key}"`) /** The placeholder for a `prior.X` no earlier piece has defined yet. Composition * replaces it; running it, or analysing what it leads to, reports the name. */ function priorHole(key: string): Combinator { const unfilled = priorUnfilled(key) const fail = (): never => { throw unfilled } return { _tag: 'lazy', _meta: { firstSet: any(), canMatchNewline: true, isTrivia: false }, _def: { tag: 'lazy', thunk: fail }, parse: fail, _priorOf: key, } as Combinator } export function rules>, P extends object = PriorRules>(factory: (self: any, prior: P) => T): RulesResult export function rules>, P extends object = PriorRules>(options: RulesOptions, factory: (self: any, prior: P) => T): RulesResult export function rules>, P extends object = PriorRules>( a: ((self: any, prior: P) => T) | RulesOptions, b?: (self: any, prior: P) => T, ): RulesResult { // The proxy answers every name, so it satisfies whatever rules `P` names. const factory = (typeof a === 'function' ? a : b) as unknown as RulesRecipe['factory'] const options = (typeof a === 'function' ? b : a) as RulesOptions | undefined const recipe: RulesRecipe = { factory, options } const map = linkRules([recipe]) Object.defineProperty(map, RULES_RECIPE, { value: [recipe], enumerable: false }) return map as RulesResult } /** * The recipe a `rules()` result was built from — its factory and options — * non-enumerable, in piece order. Runtime `compose()` links grammars by running * these again against ONE shared namespace (`linkRules`), which is what makes a * composition the same graph as one `rules()` written over every piece. A * composed result carries the concatenated list, so it composes again. */ export const RULES_RECIPE = Symbol.for('parseman.rulesRecipe') export type RulesRecipe = { readonly factory: (self: Record>, prior: PriorRules) => Record> readonly options: RulesOptions | undefined } /** * How a composition overrides its pieces' own options: the composing grammar's * trivia governs every rule (composing-wins), and an explicit host mode wins * over each piece's. */ export type LinkOptions = { readonly trivia?: Combinator | undefined readonly hostMode?: HostMode | undefined } /** * Build ONE rule map from one or more recipes, run in order against a single * shared namespace, a later recipe's definition winning per rule name. * * `rules()` is the one-recipe case. Runtime `compose()` passes every piece's * recipe plus `link`: each `g.X` in every factory then resolves to the one * composed slot for X, so an override reroutes a base piece's own calls (open * recursion) and every choice computes its first-set dispatch against the * winners. The graph is built fresh, so no shared rule of any piece is touched; * under `link` a winner is always held in a fresh slot, so the stamps below never * land on a combinator a factory returned from module scope either. */ export function linkRules( recipes: readonly RulesRecipe[], link?: LinkOptions, ): Record> { const cache: Record> = {} // Proxy: accessing any property creates a ref() placeholder on first touch. const proxy = new Proxy(cache, { get(target, key) { if (typeof key !== 'string') return undefined const record = target as Record> if (!(key in record)) { const r = ref() // Tag the placeholder with its rule name so the linkable compiler can // emit a by-name `_r_` call for a reference to a rule defined in // ANOTHER artifact (resolved at fuse time) — see compileLinkable. tagRule(r, key) record[key] = r } return record[key] }, }) // Evaluate all rule definitions. JavaScript evaluates object-literal values // left-to-right, so any `g.ruleName` access inside triggers placeholder creation // before the rule's own parser is built — enabling forward references. A later // recipe's definition of a name WINS; the name keeps its first position. const winners = new Map; options: RulesOptions | undefined }>() const afterLink: (() => void)[] = [] // `prior.X`: the winner for X BEFORE the running recipe, read while that recipe's // factory runs (its own definitions join `winners` only after it returns). It is // the earlier definition itself, inlined into the new rule's graph, so it costs no // hop at parse time. A grammar not yet composed has no earlier piece: `prior.X` is // then a placeholder the serializer writes back as `prior.X`, and a composition // that still has no earlier X refuses it. const priorHoles = new Map>() const prior = new Proxy({}, { get(_target, key) { if (typeof key !== 'string') return undefined const earlier = winners.get(key)?.parser if (earlier !== undefined) return earlier._def.tag === 'node' ? earlier._def.parser : earlier if (link !== undefined) throw priorUnfilled(key) let hole = priorHoles.get(key) if (hole === undefined) priorHoles.set(key, hole = priorHole(key)) return hole }, }) const copies = new Map>() try { for (const recipe of recipes) { const definitions = collectAfterLink(afterLink, () => recipe.factory(proxy, prior)) for (const key of Object.keys(definitions)) { winners.set(key, { parser: definitions[key]!, options: recipe.options }) } } // Fill each ref with its actual definition, or store directly if never accessed via proxy. for (const [key, { parser: defined }] of winners) { const placeholder = cache[key] const parser = ownRule(defined, copies) if (placeholder === parser) { throw new Error(`rules(): rule "${key}" cannot be a direct alias to itself`) } if (isDefinableRef(placeholder)) { if (!isNamedRuleRefForAnotherRule(parser, key)) tagRule(parser, key) placeholder.define(parser) // Propagate actual first-set so later choices wrapping this ref get correct dispatch. placeholder._meta.firstSet = parser._meta.firstSet placeholder._meta.canMatchNewline = parser._meta.canMatchNewline } else if (isNamedRuleRefForAnotherRule(parser, key) || link !== undefined) { if (!isNamedRuleRefForAnotherRule(parser, key)) tagRule(parser, key) const alias = ref() tagRule(alias, key) alias.define(parser) alias._meta.firstSet = parser._meta.firstSet alias._meta.canMatchNewline = parser._meta.canMatchNewline cache[key] = alias } else { tagRule(parser, key) cache[key] = parser } } } finally { // A nested link's nodes wait on this list, so they settle even if this link throws. for (const settle of afterLink) settle() } const keys = [...winners.keys()] // Grammar-level stamps, per rule. Each touches only its own rule — a wrap // replaces that rule's entry, and references hold the placeholder — so one pass // is the same as a pass per stamp. Trivia rules (e.g. the grammar's `rw`, // returned so the driver can reach it as `g.rw`) take none: a trivia rule must // never carry ambient trivia, or it would recursively skip trivia within itself. for (const key of keys) { const options = winners.get(key)!.options let rule = cache[key]! if (!rule._meta.isTrivia) { const meta = rule._meta as { grammarTrivia?: Combinator grammarScanSkip?: Combinator[] grammarHostMode?: HostMode grammarTrackLines?: true } // Ambient trivia, installed at the parse entry (run()/parse() read it) and // seeded into the compiled map; `parser({trivia})` / `noTrivia` override it // locally. `!= null`: `trivia: null` clears — store nothing. Under `link` // the COMPOSING trivia governs every rule, inherited ones included. const trivia = link !== undefined ? link.trivia : options?.trivia if (trivia != null) meta.grammarTrivia = trivia // Ambient scan-skip, per piece (never composing-wins: opaque units are // dialect-specific), so any entry installs `ctx.scanSkip`. if (options?.scanSkip != null) meta.grammarScanSkip = options.scanSkip // Host mode: only `'cst'` is recorded — `'ast'` is the default everywhere. if ((link?.hostMode ?? options?.hostMode) === 'cst') meta.grammarHostMode = 'cst' if (options?.trackLines === true) { meta.grammarTrackLines = true if (rule._def.tag !== 'grammar') { rule = grammarParser({ trackLines: true }, rule) tagRule(rule, key) ;(rule._meta as { grammarTrackLines?: true }).grammarTrackLines = true cache[key] = rule } } } // Dead-value analysis: mark container aggregates that only feed a node()'s // capture so the interpreter (and, via the same flag, the compiled output) skips // building them. Each rule is its own root — refs are boundaries (see value-usage). markUnusedValues(rule) // Claimed only after the define loop, so one value under two keys of THIS grammar // stays one object. See `ownRule`. claimedRules.add(winners.get(key)!.parser).add(rule) } // Record the factory's DECLARATION order (the returned object's key order). // `cache`'s own key order is reference-creation order — a Proxy artifact — so // it can lead with an internal rule instead of the entry rule. Consumers that // want the order the author actually wrote (e.g. `parseman/spec`) read this. // Non-enumerable, so Object.keys / spread / for-in over the grammar are // unaffected and every existing consumer sees exactly the rules it did before. Object.defineProperty(cache, RULE_ORDER, { value: keys, enumerable: false, configurable: true, }) attachGrammarReflection(cache, collectGrammarReflection(keys.map(key => [key, cache[key]!]))) return cache }