Skip to main content

tabnas/
parser.rs

1// Copyright (c) 2013-2026 Richard Rodger, MIT License
2
3use crate::builtins::run_builtin_action_with_info;
4use crate::context::{Context, ContextSeed, InstanceInfo};
5use crate::error::TabnasError;
6use crate::lexer::{compile_number_exclude, Lexer, RelexCheckpoint};
7use crate::options::Options;
8use crate::rule::{
9    resolved_action_order, resolved_alt_action_order, ActionBinding, AltActionBinding, AltMatch,
10    AltSpec, CompareOp, Condition, Rule, RuleDone, RuleDoneAlt, RuleName, RuleSnapshot, RuleSpec,
11    RuleState, StateAction,
12};
13use crate::token::{Tin, Token, TIN_AA, TIN_BD, TIN_ZZ};
14use crate::value::Value;
15use crate::{
16    Action, AltAction, ContextAction, LexSubscriber, ParseGuard, RuleDoneSubscriber,
17    RuleSubscriber, TokenSubscriber,
18};
19use indexmap::IndexMap;
20use std::borrow::Cow;
21use std::cell::RefCell;
22use std::collections::{BTreeSet, HashMap};
23use std::panic::{catch_unwind, AssertUnwindSafe};
24use std::rc::Rc;
25use std::sync::Arc;
26
27#[derive(Debug, Clone, PartialEq, Eq)]
28pub struct Continuations {
29    pub tins: Vec<Tin>,
30    pub tokens: Vec<String>,
31}
32
33#[derive(Debug, Clone)]
34pub struct ParseRecovery {
35    pub value: Option<Value>,
36    pub errors: Vec<TabnasError>,
37    pub fatal: Option<TabnasError>,
38}
39
40#[derive(Default)]
41struct ContinuationCapture {
42    at_end: BTreeSet<Tin>,
43    have_end: bool,
44    failure: Vec<Tin>,
45}
46
47struct ParseMode<'a> {
48    continuation: Option<&'a mut ContinuationCapture>,
49    recovering: bool,
50    errors: &'a mut Vec<TabnasError>,
51    partial: Option<PartialValue>,
52    /// Recovery gave up, and the error it gave up on is already accounted
53    /// for in `errors`: recorded there, or dropped as a cascade of the
54    /// fault before it. TypeScript records an error as it is constructed
55    /// and gives up by rethrowing the last one it recorded (`RuleSpec.bad`,
56    /// ts/src/rules.ts), or the bad token it has just recorded, coalesced
57    /// or dropped (the fetch in `parse_alts`), so the error that ends the
58    /// parse is never listed a second time. Every other terminal error is
59    /// listed once, where the parse ends.
60    gave_up: bool,
61}
62
63/// A recovery result that stays borrowed from the live parse until needed.
64///
65/// Holding a cloned `Value` while its container was still being built kept a
66/// second `Arc` handle alive. Every following append then made
67/// `Arc::make_mut` copy the whole prefix. A node cell follows TypeScript's
68/// recovery path instead: keep the live node and read it once when parsing
69/// ends. `Complete` is the already-finalized value retained for a post-loop
70/// trailing-content failure.
71enum PartialValue {
72    Node(Rc<RefCell<Value>>),
73    Complete(Value),
74}
75
76impl PartialValue {
77    fn into_value(self) -> Option<Value> {
78        match self {
79            Self::Complete(value) => Some(value),
80            Self::Node(node) => {
81                let value = node.borrow().clone();
82                (!matches!(value, Value::Undefined | Value::Null)).then(|| value.unwrap_undefined())
83            }
84        }
85    }
86}
87
88struct RelexUndo {
89    position: usize,
90    token: Token,
91    checkpoint: RelexCheckpoint,
92    tokens: Vec<Token>,
93}
94
95/// Who is asking [`Parser::ensure_lookahead`] for a token, which decides
96/// what a bad token does under recovery.
97#[derive(Clone, Copy, PartialEq, Eq)]
98enum Fetch {
99    /// A rule reading its lookahead, as TypeScript's `parse_alts` does:
100    /// under recovery a bad token is recorded and skipped, and the fetch
101    /// goes on.
102    Rule,
103    /// The check for content after the parse has finished, as
104    /// TypeScript's `Parser.start` makes it: a bad token ends the parse
105    /// with its own error, recovering or not.
106    Trailing,
107}
108
109#[derive(Clone, Copy)]
110struct ParseSite<'a> {
111    source: &'a str,
112    stack: &'a [Rule],
113    alts: &'a [AltSpec],
114}
115
116pub struct Parser {
117    /// Shared with the lexer, which never writes to them. Cloning a
118    /// whole `Options` was 22% of a small parse, and it was happening
119    /// twice.
120    pub options: Arc<Options>,
121    ignore_tins: Vec<Tin>,
122    /// `options.number.exclude` compiled once, here, and shared with
123    /// the lexer of every parse instead of compiled by each of them.
124    ///
125    /// `options` is public, so this is a cache whose source has a second
126    /// writer: a caller on the low-level API may replace the whole `Arc`
127    /// between parses, and before this was cached each lexer compiled
128    /// whatever pattern was in force. `exclude_pattern` is the pattern
129    /// this regex was built from, and a parse whose options no longer
130    /// carry it compiles the one they do carry instead -- the old cost,
131    /// paid only by the callers who change the pattern under the parser.
132    exclude_regex: Option<Arc<regex::Regex>>,
133    exclude_pattern: Option<String>,
134    /// Installed rules by name.
135    ///
136    /// Private, and read through [`Parser::rules`]. Two derived tables below
137    /// are keyed by the same names and are written only by `add_rule`; while
138    /// this was public an embedder could insert or replace a rule straight
139    /// into it, leaving those tables describing the rule that used to be
140    /// there. Lookahead would then gate the custom matchers on the previous
141    /// rule's token identities, or on none at all for a name that was never
142    /// installed, and a valid document could fail to parse. Before those
143    /// identities were derived once per rule instead of once per lookahead
144    /// there was nothing to go stale, so this hazard arrived with the table.
145    rules: IndexMap<String, Arc<RuleSpec>>,
146    /// The `rule.include` and `rule.exclude` every `PreparedAlt::groups`
147    /// was worked out against, and every `expected_tins` row collated
148    /// against. Both are public and a callback may write either between
149    /// one step and the next, so the step compares these two strings
150    /// before trusting the prepared answer, and `expected_match_tins`
151    /// before trusting the row -- the same shape of guard the compiled
152    /// `number.exclude` pattern carries, and for the same reason: a cache
153    /// derived from a public mutable field is a cache with a second
154    /// writer.
155    prepared_include: String,
156    prepared_exclude: String,
157    /// The token identities each rule can accept at each lookahead slot,
158    /// worked out once per installed rule rather than once per token, and
159    /// positional in `rules` the way `names` is: a rule carries the slot
160    /// it was installed at, so reaching its row costs an index rather than
161    /// a hash of its name on every token fetch.
162    expected_tins: Vec<ExpectedTins>,
163    /// One shared copy of each installed rule's name, so pushing a rule
164    /// clones a pointer rather than reallocating the name per push.
165    ///
166    /// Parallel to `rules`, indexed by position rather than keyed by the
167    /// name again: every route already has to find the rule's spec, and
168    /// `IndexMap::get_full` hands back that rule's index with it, so the
169    /// shared name costs an array index instead of a second hash of the
170    /// same bytes. `Parser::rules` is public and hands out the map itself,
171    /// which is why the handle lives beside the map rather than in it.
172    /// `add_rule` keeps the two in step; `IndexMap` gives a replaced key
173    /// back its existing index, so a replacement overwrites in place.
174    names: Vec<RuleName>,
175    /// Per-rule state worked out once, when the grammar is installed.
176    ///
177    /// Parallel to `rules` and `names`, and written only by `add_rule`,
178    /// which rebuilds the whole table -- a route may name a rule that is
179    /// installed later, so an entry is only right once every rule is in.
180    /// The loop reaches an entry by the `slot` the rule carries and checks
181    /// it against the rule's own spec and name before trusting it, so a
182    /// callback that rewrites either just falls back to the lookup.
183    prepared: Vec<PreparedRule>,
184    pub actions: HashMap<String, Action>,
185    pub context_actions: HashMap<String, ContextAction>,
186    pub matched_actions: HashMap<String, AltAction>,
187    pub state_actions: HashMap<String, StateAction>,
188    pub token_subscribers: Vec<TokenSubscriber>,
189    pub lex_subscribers: Vec<LexSubscriber>,
190    pub rule_subscribers: Vec<RuleSubscriber>,
191    pub rule_done_subscribers: Vec<RuleDoneSubscriber>,
192    pub parse_guards: Vec<ParseGuard>,
193    pub instance: InstanceInfo,
194}
195
196/// One installed rule, with what the parse loop can work out about it
197/// before a parse starts.
198///
199/// Routing, and the order the rule's actions run in. The order is a
200/// question about the spec alone -- which of the named, callback and
201/// state lists a binding came from, and where the three interleave -- and
202/// the spec behind the `Arc` this record is checked against cannot change
203/// while a parse runs, so it is answered once here instead of rebuilt into
204/// a fresh `Vec` on every rule step. What a *named* binding resolves to is
205/// a different question: it is looked up in `Parser::actions`,
206/// `matched_actions` and `state_actions`, all of them public maps an
207/// embedder may write after `add_rule` has run, so that lookup stays where
208/// it was, on the step -- a table derived from a field with a second
209/// writer goes stale in silence, which is the hazard `rules` was made
210/// private to close.
211struct PreparedRule {
212    /// The rule's shared name handle and the spec it was installed with.
213    ///
214    /// `spec` is what the loop borrows in place of the rule's own; `name`
215    /// is only ever compared. Together they are what says the rule in hand
216    /// is still the rule this record describes.
217    name: RuleName,
218    spec: Arc<RuleSpec>,
219    open: Vec<PreparedAlt>,
220    close: Vec<PreparedAlt>,
221    /// The alternates of each state indexed by the tin they can take at
222    /// position 0, so a step tries the candidates for the first
223    /// lookahead token rather than every alternate.
224    open_first: AltIndex,
225    close_first: AltIndex,
226    /// The four lifecycle action orders, in the same order the rule runs
227    /// them. Most grammars declare none of them, and an empty list here is
228    /// what lets a step skip the whole phase rather than walk an empty
229    /// one: `bind_spec` sets a rule's `bo`/`ao`/`bc`/`ac` true
230    /// unconditionally, so those flags say the phase is *enabled*, never
231    /// that it has anything to run.
232    bo: Vec<ActionBinding>,
233    ao: Vec<ActionBinding>,
234    bc: Vec<ActionBinding>,
235    ac: Vec<ActionBinding>,
236}
237
238impl PreparedRule {
239    /// The first-token index of the open or close alternates.
240    fn first(&self, is_open: bool) -> &AltIndex {
241        if is_open {
242            &self.open_first
243        } else {
244            &self.close_first
245        }
246    }
247
248    fn alt(&self, is_open: bool, idx: usize) -> Option<&PreparedAlt> {
249        if is_open {
250            self.open.get(idx)
251        } else {
252            self.close.get(idx)
253        }
254    }
255
256    /// The before-open or before-close action order.
257    fn before(&self, is_open: bool) -> &[ActionBinding] {
258        if is_open {
259            &self.bo
260        } else {
261            &self.bc
262        }
263    }
264
265    /// The after-open or after-close action order.
266    fn after(&self, is_open: bool) -> &[ActionBinding] {
267        if is_open {
268            &self.ao
269        } else {
270            &self.ac
271        }
272    }
273}
274
275/// One alternate's two routing channels and its action order, resolved at
276/// install time.
277struct PreparedAlt {
278    p: PreparedRoute,
279    r: PreparedRoute,
280    /// The alternate's action bindings in the order they run.
281    actions: Vec<AltActionBinding>,
282    /// Whether anything a step on this alternate runs can read the
283    /// `AltMatch` record, and so see the action list the engine publishes
284    /// into `matched.actions`.
285    ///
286    /// The list is published for the callbacks that receive the record --
287    /// the `c`/`e`/`p`/`r`/`b` matched hooks, the matched modifier, and a
288    /// matched action itself. When the alternate declares none of them
289    /// nothing in the step can tell whether the field was filled, so the
290    /// step runs these bindings straight from here: no `Vec` built, no
291    /// second copy taken to iterate, no reference counts touched. When it
292    /// declares any of them the step fills the record exactly as before.
293    ///
294    /// A `Named` binding may also resolve to a matched action, and that
295    /// cannot be settled here -- `add_matched_action` may be called after
296    /// `add_rule`, and `matched_actions` is public. `named` records only
297    /// that the question arises; the step asks it of the map it is asking
298    /// anyway.
299    observed: bool,
300    named: bool,
301    /// Whether `rule.include` and `rule.exclude` leave this alternate
302    /// active, worked out when the rule was installed.
303    ///
304    /// The question is about `alt.g` against two option strings, and the
305    /// answer cannot change during a parse unless a callback rewrites the
306    /// options -- so `prepared_include`/`prepared_exclude` on the parser
307    /// record what this was computed against, and the step checks those
308    /// two strings ONCE rather than re-deriving the answer per alternate.
309    groups: bool,
310    /// `alt.g` split into the tags the step publishes into `matched.g`,
311    /// split when the rule was installed rather than per rule step.
312    ///
313    /// Unlike `groups` this is derived from the alternate alone, so no
314    /// option string can stale it; the only alternate it cannot answer for
315    /// is one a modifier rewrote, which the step detects the same way it
316    /// does for the action order.
317    group_tags: Vec<String>,
318}
319
320enum PreparedRoute {
321    /// Nothing was resolved: the alternate declares no route on this
322    /// channel, or names a rule that is not installed, or routes through a
323    /// callback. All three take the same path they took before the table --
324    /// one lookup by name, which is also what raises `unknown_rule` for a
325    /// route naming no rule.
326    ByName,
327    Static {
328        slot: usize,
329        name: RuleName,
330        spec: Arc<RuleSpec>,
331    },
332}
333
334impl PreparedRoute {
335    /// The prepared answer, if the route the parse is actually taking is
336    /// still the one that was prepared.
337    ///
338    /// The test is byte-equality of the name, unconditionally, and not a
339    /// pointer comparison of the alternate: `h` rewrites the whole
340    /// `AltSpec` per step, `p_fn`/`r_fn` and `p_match`/`r_match` produce
341    /// the name at run time, and a matched action may write `matched.p` or
342    /// `matched.r` outright -- all supported routing channels. A route that
343    /// arrives at the same name resolves to the same rule whichever of them
344    /// produced it, so the bytes are the whole question.
345    fn resolved(&self, name: &str) -> Option<(usize, RuleName, &Arc<RuleSpec>)> {
346        match self {
347            PreparedRoute::Static {
348                slot,
349                name: prepared,
350                spec,
351            } if prepared.as_str() == name => Some((*slot, prepared.clone(), spec)),
352            _ => None,
353        }
354    }
355}
356
357/// Per-slot accepted token identities for one rule, in each state.
358///
359/// This used to be derived on every lookahead: a map lookup, a `BTreeSet`
360/// built from the alternates, and a `Vec` collected out of it, once per
361/// token. None of it can change while a parse runs, so it is derived once
362/// when the rule is installed.
363/// What the names on one slot resolve to against `options` now: a slot
364/// naming a token set takes the set's current members, and a slot naming a
365/// token takes that token. `None` leaves the slot with the tins it has, and
366/// is the answer for a slot with no names (an alternate built from tins
367/// directly, or a slot set by hand before a merge carried it, whose names
368/// the merge drops), a slot whose `s` was set by hand since it was
369/// installed (it no longer equals what the names last resolved to,
370/// `s_bound`: the edit wins over the names, as it did before the names
371/// were kept), and a slot naming something the options do not know (a
372/// parser build must not mint a token).
373pub(crate) fn resolved_slot(alt: &AltSpec, slot: usize, options: &Options) -> Option<Vec<Tin>> {
374    let names = alt.s_names.get(slot)?;
375    if names.is_empty() || alt.s.get(slot) != alt.s_bound.get(slot) {
376        return None;
377    }
378    let mut tins = Vec::with_capacity(names.len());
379    for name in names {
380        if let Some(set) = options.token_set.get(name.trim_start_matches('#')) {
381            tins.extend(set.iter().copied());
382        } else {
383            tins.push(options.token(name)?);
384        }
385    }
386    Some(tins)
387}
388
389/// Resolve every slot that was declared by name against `options`
390/// (`resolved_slot`).
391fn resolve_slot_names(spec: &mut RuleSpec, options: &Options) {
392    for alt in spec.open.iter_mut().chain(spec.close.iter_mut()) {
393        for slot in 0..alt.s.len() {
394            if let Some(tins) = resolved_slot(alt, slot, options) {
395                alt.s[slot] = tins;
396            }
397        }
398    }
399}
400
401/// Alternates indexed by the tin they can take at position 0.
402///
403/// `by_tin` maps each tin some alternate names at position 0 to the
404/// ascending indices of the alternates naming it; `wild` holds the
405/// alternates that constrain nothing at position 0 (an empty sequence,
406/// an empty slot, or a slot naming `#AA`, exactly the slots
407/// `slot_matches` accepts every tin for), which are candidates for every
408/// tin. The step walks the two lists together in index order, so the
409/// candidates for a tin are the original scan with the alternates that
410/// cannot take it left out, and first-match-wins is preserved. The lists
411/// stay separate rather than being merged per tin: a rule with W
412/// wildcard alternates and T distinct first tins would otherwise cost
413/// W×T entries.
414#[derive(Debug, Default)]
415struct AltIndex {
416    by_tin: HashMap<Tin, Vec<usize>>,
417    wild: Vec<usize>,
418}
419
420const NO_ALTS: &[usize] = &[];
421
422impl AltIndex {
423    fn of(alts: &[AltSpec]) -> Self {
424        let mut by_tin: HashMap<Tin, Vec<usize>> = HashMap::new();
425        let mut wild = Vec::new();
426        for (idx, alt) in alts.iter().enumerate() {
427            match alt.s.first() {
428                Some(slot) if !slot.is_empty() && !slot.contains(&TIN_AA) => {
429                    for tin in slot {
430                        let list = by_tin.entry(*tin).or_default();
431                        // A slot naming one tin twice must not try the
432                        // alternate twice: a condition could observe it.
433                        if list.last() != Some(&idx) {
434                            list.push(idx);
435                        }
436                    }
437                }
438                _ => wild.push(idx),
439            }
440        }
441        AltIndex { by_tin, wild }
442    }
443
444    /// The ascending alternates naming `tin` at position 0; the
445    /// wildcards are `wild`, walked beside them.
446    fn named(&self, tin: Tin) -> &[usize] {
447        self.by_tin.get(&tin).map_or(NO_ALTS, Vec::as_slice)
448    }
449}
450
451#[derive(Debug, Default)]
452struct ExpectedTins {
453    open: Vec<Vec<Tin>>,
454    close: Vec<Vec<Tin>>,
455}
456
457impl ExpectedTins {
458    /// Collated over the alternates `options` enable, as TypeScript's
459    /// `tcol` is: `filterRules` has removed the others from the spec
460    /// before `norm()` collates it. An excluded alternate is never tried,
461    /// so it must not decide which matchers run in the position-expected
462    /// pass either. It did until 0.12.4, and a grammar that excludes a
463    /// group while redefining a set that group's alternates name had the
464    /// set's members expected where the grammar never takes them (toml
465    /// excludes jsonic and sets `KEY` to `#ST #ID`, and its `val` came to
466    /// expect `#ID`, whose matcher then claimed every number).
467    ///
468    /// The filters are the ones in force at install, which the parser
469    /// records as `prepared_include` and `prepared_exclude`. Both are
470    /// public options a caller may rewrite afterwards, and the step then
471    /// chooses among the alternates the live filters enable, so
472    /// `Parser::expected_match_tins` reads this table only while the live
473    /// filters are still the recorded ones, and collates from them with
474    /// `live` otherwise.
475    fn of(spec: &RuleSpec, options: &Options) -> Self {
476        Self {
477            open: Self::by_slot(&spec.open, options),
478            close: Self::by_slot(&spec.close, options),
479        }
480    }
481
482    fn by_slot(alts: &[AltSpec], options: &Options) -> Vec<Vec<Tin>> {
483        let alts: Vec<&AltSpec> = alts
484            .iter()
485            .filter(|alt| groups_enabled(alt, options))
486            .collect();
487        let slots = alts.iter().map(|alt| alt.s.len()).max().unwrap_or(0);
488        (0..slots)
489            .map(|slot| Self::collate(alts.iter().copied(), slot))
490            .collect()
491    }
492
493    /// One slot's row, collated from the alternates `options` enable now
494    /// rather than the ones they enabled at install.
495    fn live(alts: &[AltSpec], options: &Options, slot: usize) -> Vec<Tin> {
496        Self::collate(alts.iter().filter(|alt| groups_enabled(alt, options)), slot)
497    }
498
499    fn collate<'a>(alts: impl Iterator<Item = &'a AltSpec>, slot: usize) -> Vec<Tin> {
500        let mut expected = BTreeSet::new();
501        for alt in alts {
502            if let Some(tins) = alt.s.get(slot) {
503                expected.extend(tins.iter().copied());
504            }
505        }
506        expected.into_iter().collect()
507    }
508
509    fn at(&self, is_open: bool, slot: usize) -> &[Tin] {
510        let slots = if is_open { &self.open } else { &self.close };
511        slots.get(slot).map(Vec::as_slice).unwrap_or_default()
512    }
513}
514
515impl Parser {
516    pub fn new(options: Options) -> Self {
517        let mut options = options;
518        options.sort_for_lexing();
519        Self::from_shared(Arc::new(options))
520    }
521
522    /// Parse against a configuration that is already prepared and
523    /// ordered, shared with every other parse of the same grammar.
524    pub fn from_shared(options: Arc<Options>) -> Self {
525        if let Err(error) = options.validate_comment_definitions() {
526            panic!("invalid options: {error}");
527        }
528        Parser {
529            ignore_tins: options.ignore_tins(),
530            exclude_regex: compile_number_exclude(&options),
531            exclude_pattern: options.number.exclude.clone(),
532            options,
533            rules: IndexMap::new(),
534            prepared_include: String::new(),
535            prepared_exclude: String::new(),
536            expected_tins: Vec::new(),
537            names: Vec::new(),
538            prepared: Vec::new(),
539            actions: HashMap::new(),
540            context_actions: HashMap::new(),
541            matched_actions: HashMap::new(),
542            state_actions: HashMap::new(),
543            token_subscribers: Vec::new(),
544            lex_subscribers: Vec::new(),
545            rule_subscribers: Vec::new(),
546            rule_done_subscribers: Vec::new(),
547            parse_guards: Vec::new(),
548            instance: InstanceInfo::default(),
549        }
550    }
551
552    /// The installed rules, in declaration order.
553    ///
554    /// Read-only: every write goes through [`Parser::add_rule`], which is
555    /// what keeps the derived tables in step with it.
556    pub fn rules(&self) -> &IndexMap<String, Arc<RuleSpec>> {
557        &self.rules
558    }
559
560    pub fn add_rule(&mut self, spec: RuleSpec) {
561        // A slot declared by name is resolved against the options this
562        // parser is built with, so a token set overridden after the rule
563        // was installed reaches it (tabnas/parser#217). The parser is
564        // rebuilt whenever the options change, which is what makes this
565        // the late binding TypeScript's `norm()` and Go's `altS` provide.
566        let mut spec = spec;
567        resolve_slot_names(&mut spec, &self.options);
568        // `rebuild_prepared` below records the live filters as the ones
569        // every accepted-token row was collated against, so a row collated
570        // under filters rewritten since then is collated again first. Only
571        // a rewrite between two installs reaches this.
572        if self.options.rule.include != self.prepared_include
573            || self.options.rule.exclude != self.prepared_exclude
574        {
575            for (row, installed) in self.expected_tins.iter_mut().zip(self.rules.values()) {
576                *row = ExpectedTins::of(installed, &self.options);
577            }
578        }
579        let expected = ExpectedTins::of(&spec, &self.options);
580        let shared = RuleName::from(spec.name.as_str());
581        let (index, _) = self.rules.insert_full(spec.name.clone(), Arc::new(spec));
582        // A replacement keeps the key's index, so it overwrites its own
583        // name handle; a new rule is appended and takes the next slot. The
584        // accepted-token table is positional for the same reason and is
585        // written here, not in `rebuild_prepared`: it is derived from one
586        // rule's spec alone, so rebuilding it for every rule on every
587        // install would be quadratic for no gain.
588        match self.names.get_mut(index) {
589            Some(existing) => *existing = shared,
590            None => self.names.push(shared),
591        }
592        match self.expected_tins.get_mut(index) {
593            Some(existing) => *existing = expected,
594            None => self.expected_tins.push(expected),
595        }
596        self.rebuild_prepared();
597    }
598
599    /// Rebuild the prepared table for every installed rule.
600    ///
601    /// Every rule, not just the one just installed: routes point across the
602    /// grammar, so a rule installed now can be the destination an earlier
603    /// rule named and could not resolve, and a replaced rule is a new
604    /// `Arc<RuleSpec>` that every route into it has to start handing out.
605    /// That makes installing a grammar quadratic in its size, which for the
606    /// grammars this engine runs -- tens of rules, installed once -- is
607    /// nothing next to a single parse, and it is the only shape that stays
608    /// right for a `Parser` that has rules added to it after it has already
609    /// parsed something.
610    fn rebuild_prepared(&mut self) {
611        let mut prepared = Vec::with_capacity(self.rules.len());
612        for (index, spec) in self.rules.values().enumerate() {
613            prepared.push(PreparedRule {
614                name: self.names[index].clone(),
615                spec: Arc::clone(spec),
616                open: Self::prepared_alts(&spec.open, &self.rules, &self.names, &self.options),
617                close: Self::prepared_alts(&spec.close, &self.rules, &self.names, &self.options),
618                open_first: AltIndex::of(&spec.open),
619                close_first: AltIndex::of(&spec.close),
620                bo: resolved_action_order(
621                    &spec.bo,
622                    &spec.bo_fns,
623                    &spec.bo_state_fns,
624                    &spec.bo_order,
625                ),
626                ao: resolved_action_order(
627                    &spec.ao,
628                    &spec.ao_fns,
629                    &spec.ao_state_fns,
630                    &spec.ao_order,
631                ),
632                bc: resolved_action_order(
633                    &spec.bc,
634                    &spec.bc_fns,
635                    &spec.bc_state_fns,
636                    &spec.bc_order,
637                ),
638                ac: resolved_action_order(
639                    &spec.ac,
640                    &spec.ac_fns,
641                    &spec.ac_state_fns,
642                    &spec.ac_order,
643                ),
644            });
645        }
646        self.prepared = prepared;
647        self.prepared_include.clone_from(&self.options.rule.include);
648        self.prepared_exclude.clone_from(&self.options.rule.exclude);
649    }
650
651    fn prepared_alts(
652        alts: &[AltSpec],
653        rules: &IndexMap<String, Arc<RuleSpec>>,
654        names: &[RuleName],
655        options: &Options,
656    ) -> Vec<PreparedAlt> {
657        alts.iter()
658            .map(|alt| {
659                // The same normalisation the step used to run: a grammar
660                // that appended to `a` or `action_fns` after the builder
661                // last touched `action_order` gets the fallback chain built
662                // for it here instead of there.
663                let actions = resolved_alt_action_order(
664                    &alt.a,
665                    &alt.action_fns,
666                    &alt.matched_action_fns,
667                    &alt.action_order,
668                );
669                let observed = alt.c_match.is_some()
670                    || alt.c_lex_match.is_some()
671                    || alt.e_match.is_some()
672                    || alt.p_match.is_some()
673                    || alt.r_match.is_some()
674                    || alt.b_match.is_some()
675                    || alt.h_match.is_some()
676                    || actions
677                        .iter()
678                        .any(|binding| matches!(binding, AltActionBinding::Matched(_)));
679                let named = actions
680                    .iter()
681                    .any(|binding| matches!(binding, AltActionBinding::Named(_)));
682                PreparedAlt {
683                    p: Self::prepared_route(alt.p.as_deref(), rules, names),
684                    r: Self::prepared_route(alt.r.as_deref(), rules, names),
685                    actions,
686                    observed,
687                    named,
688                    groups: groups_enabled(alt, options),
689                    group_tags: listed(&alt.g).map(str::to_owned).collect(),
690                }
691            })
692            .collect()
693    }
694
695    fn prepared_route(
696        route: Option<&str>,
697        rules: &IndexMap<String, Arc<RuleSpec>>,
698        names: &[RuleName],
699    ) -> PreparedRoute {
700        // An empty route name is "no route" at the transition, so it is not
701        // one here either.
702        let Some(route) = route.filter(|route| !route.is_empty()) else {
703            return PreparedRoute::ByName;
704        };
705        match rules.get_full(route) {
706            Some((slot, _, spec)) => PreparedRoute::Static {
707                slot,
708                name: names[slot].clone(),
709                spec: Arc::clone(spec),
710            },
711            None => PreparedRoute::ByName,
712        }
713    }
714
715    /// Resolve a rule name to the shared name handle and the installed
716    /// spec in one lookup.
717    ///
718    /// Every route into a rule needs both, and used to hash the same
719    /// three-byte name three times over to get them: once to ask whether
720    /// the rule existed, once for the shared handle, once for the spec.
721    /// `get_full` answers all three at once -- absence, the index the
722    /// handle sits at, and the spec. The index is also the rule's slot in
723    /// the prepared table, which the rule carries so that the next step can
724    /// find its state without asking again.
725    fn installed(&self, name: &str) -> Option<(usize, RuleName, &Arc<RuleSpec>)> {
726        let (index, _, spec) = self.rules.get_full(name)?;
727        Some((index, self.names[index].clone(), spec))
728    }
729
730    pub fn add_action(&mut self, name: String, action: Action) {
731        self.actions.insert(name, action);
732    }
733
734    pub fn add_context_action(&mut self, name: String, action: ContextAction) {
735        self.context_actions.insert(name, action);
736    }
737
738    pub fn add_matched_action(&mut self, name: String, action: AltAction) {
739        self.matched_actions.insert(name, action);
740    }
741
742    pub fn add_state_action(&mut self, name: String, action: StateAction) {
743        self.state_actions.insert(name, action);
744    }
745
746    pub fn add_token_subscriber(&mut self, subscriber: TokenSubscriber) {
747        self.token_subscribers.push(subscriber);
748    }
749
750    pub fn add_lex_subscriber(&mut self, subscriber: LexSubscriber) {
751        self.lex_subscribers.push(subscriber);
752    }
753
754    pub fn add_rule_subscriber(&mut self, subscriber: RuleSubscriber) {
755        self.rule_subscribers.push(subscriber);
756    }
757
758    pub fn add_parse_guard(&mut self, guard: ParseGuard) {
759        self.parse_guards.push(guard);
760    }
761
762    pub fn add_rule_done_subscriber(&mut self, subscriber: RuleDoneSubscriber) {
763        self.rule_done_subscribers.push(subscriber);
764    }
765
766    pub fn set_instance_info(&mut self, instance: InstanceInfo) {
767        self.instance = instance;
768    }
769
770    fn run_action(
771        &self,
772        name: &str,
773        rule: &mut Rule,
774        context: &mut Context,
775    ) -> Result<(), TabnasError> {
776        self.run_action_with_config(name, rule, context, None)
777    }
778
779    fn run_after_actions(
780        &self,
781        spec: &RuleSpec,
782        prepared: Option<&PreparedRule>,
783        is_open: bool,
784        rule: &mut Rule,
785        context: &mut Context,
786        site: ParseSite<'_>,
787    ) -> Result<(), TabnasError> {
788        if (is_open && !rule.ao) || (!is_open && !rule.ac) {
789            return Ok(());
790        }
791        // `ao`/`ac` above are run control, not presence: a rule carries
792        // them set whether or not it declares an after action. The order
793        // itself says whether there is anything to run, and when there is
794        // not the phase costs nothing -- not the list, and not the
795        // reference count on the next rule the state callbacks would have
796        // been handed.
797        let by_spec;
798        let bindings: &[ActionBinding] = match prepared {
799            Some(prepared) => prepared.after(is_open),
800            None => {
801                let (actions, callbacks, states, order) = if is_open {
802                    (&spec.ao, &spec.ao_fns, &spec.ao_state_fns, &spec.ao_order)
803                } else {
804                    (&spec.ac, &spec.ac_fns, &spec.ac_state_fns, &spec.ac_order)
805                };
806                by_spec = resolved_action_order(actions, callbacks, states, order);
807                &by_spec
808            }
809        };
810        if bindings.is_empty() {
811            return Ok(());
812        }
813        let next = rule.next_rule.clone();
814        let mut output = None;
815        for binding in bindings {
816            output = match binding {
817                ActionBinding::Named(action) => {
818                    if let Some(callback) = self.state_actions.get(action) {
819                        self.run_state_callback(
820                            "named lifecycle after action",
821                            callback,
822                            rule,
823                            context,
824                            next.as_deref(),
825                            output,
826                        )
827                        .map_err(|error| {
828                            self.attach_action_error(
829                                error,
830                                site.source,
831                                rule,
832                                site.stack,
833                                site.alts,
834                            )
835                        })?
836                    } else {
837                        self.run_action(action, rule, context).map_err(|error| {
838                            self.attach_action_error(
839                                error,
840                                site.source,
841                                rule,
842                                site.stack,
843                                site.alts,
844                            )
845                        })?;
846                        None
847                    }
848                }
849                ActionBinding::Callback(callback) => {
850                    self.run_context_callback("lifecycle after action", callback, rule, context)
851                        .map_err(|error| {
852                            self.attach_action_error(
853                                error,
854                                site.source,
855                                rule,
856                                site.stack,
857                                site.alts,
858                            )
859                        })?;
860                    None
861                }
862                ActionBinding::State(callback) => self
863                    .run_state_callback(
864                        "lifecycle after action",
865                        callback,
866                        rule,
867                        context,
868                        next.as_deref(),
869                        output,
870                    )
871                    .map_err(|error| {
872                        self.attach_action_error(error, site.source, rule, site.stack, site.alts)
873                    })?,
874            };
875            output = self.check_lifecycle_output(output, rule, site)?;
876        }
877        Ok(())
878    }
879
880    fn run_context_callback(
881        &self,
882        label: &str,
883        callback: &ContextAction,
884        rule: &mut Rule,
885        context: &mut Context,
886    ) -> Result<(), TabnasError> {
887        context.set_rule(rule);
888        match catch_unwind(AssertUnwindSafe(|| callback(rule, context))) {
889            Ok(result) => result.map_err(|action_error| {
890                let token = match rule.state {
891                    RuleState::Open => rule.o0().or_else(|| rule.c0()),
892                    RuleState::Close => rule.c0().or_else(|| rule.o0()),
893                };
894                let mut error = TabnasError::new(
895                    action_error.code,
896                    token.map_or("", |value| value.src.as_str()),
897                    "",
898                    token.map_or(0, |value| value.site.pos),
899                    token.map_or(1, |value| value.site.ri),
900                    token.map_or(1, |value| value.site.ci),
901                );
902                error.detail = action_error.detail;
903                error
904            }),
905            Err(payload) => Err(self.action_panic(payload, label, rule)),
906        }
907    }
908
909    fn run_state_callback(
910        &self,
911        label: &str,
912        callback: &StateAction,
913        rule: &mut Rule,
914        context: &mut Context,
915        next: Option<&RuleSnapshot>,
916        out: Option<Token>,
917    ) -> Result<Option<Token>, TabnasError> {
918        context.set_rule(rule);
919        match catch_unwind(AssertUnwindSafe(|| callback(rule, context, next, out))) {
920            Ok(result) => result.map_err(|action_error| {
921                let token = match rule.state {
922                    RuleState::Open => rule.o0().or_else(|| rule.c0()),
923                    RuleState::Close => rule.c0().or_else(|| rule.o0()),
924                };
925                let mut error = TabnasError::new(
926                    action_error.code,
927                    token.map_or("", |value| value.src.as_str()),
928                    "",
929                    token.map_or(0, |value| value.site.pos),
930                    token.map_or(1, |value| value.site.ri),
931                    token.map_or(1, |value| value.site.ci),
932                );
933                error.detail = action_error.detail;
934                error
935            }),
936            Err(payload) => Err(self.action_panic(payload, label, rule)),
937        }
938    }
939
940    fn check_lifecycle_output(
941        &self,
942        output: Option<Token>,
943        rule: &Rule,
944        site: ParseSite<'_>,
945    ) -> Result<Option<Token>, TabnasError> {
946        let Some(token) = output.as_ref().filter(|token| !token.err.is_empty()) else {
947            return Ok(output);
948        };
949        Err(self.raised_token_error(token, rule, site))
950    }
951
952    fn raised_token_error(&self, token: &Token, rule: &Rule, site: ParseSite<'_>) -> TabnasError {
953        let error = TabnasError::new(
954            raised_error_code(token),
955            token.src.clone(),
956            site.source,
957            token.site.pos,
958            token.site.ri,
959            token.site.ci,
960        );
961        self.attach_error(error, rule, site.stack, site.alts, Some(token))
962    }
963
964    fn attach_action_error(
965        &self,
966        mut error: TabnasError,
967        src: &str,
968        rule: &Rule,
969        stack: &[Rule],
970        alts: &[AltSpec],
971    ) -> TabnasError {
972        error.full_source = src.into();
973        let token = match rule.state {
974            RuleState::Open => rule.o0().or_else(|| rule.c0()),
975            RuleState::Close => rule.c0().or_else(|| rule.o0()),
976        };
977        self.attach_error(error, rule, stack, alts, token)
978    }
979
980    fn run_action_with_config(
981        &self,
982        name: &str,
983        rule: &mut Rule,
984        context: &mut Context,
985        config: Option<&Value>,
986    ) -> Result<(), TabnasError> {
987        context.set_rule(rule);
988        match catch_unwind(AssertUnwindSafe(|| {
989            run_builtin_action_with_info(name, rule, context, config, &self.options.info)
990        })) {
991            Ok(true) => return Ok(()),
992            Ok(false) => {}
993            Err(payload) => return Err(self.action_panic(payload, name, rule)),
994        }
995        if let Some(action) = self.actions.get(name) {
996            return match catch_unwind(AssertUnwindSafe(|| action(rule))) {
997                Ok(()) => Ok(()),
998                Err(payload) => Err(self.action_panic(payload, name, rule)),
999            };
1000        }
1001        if let Some(action) = self.context_actions.get(name) {
1002            return self.run_context_callback(name, action, rule, context);
1003        }
1004        let token = match rule.state {
1005            RuleState::Open => rule.o0().or_else(|| rule.c0()),
1006            RuleState::Close => rule.c0().or_else(|| rule.o0()),
1007        };
1008        let mut error = TabnasError::new(
1009            "unknown",
1010            name,
1011            "",
1012            token.map_or(0, |value| value.site.pos),
1013            token.map_or(1, |value| value.site.ri),
1014            token.map_or(1, |value| value.site.ci),
1015        );
1016        error.detail = format!("unknown action: {name}");
1017        Err(error)
1018    }
1019
1020    fn action_panic(
1021        &self,
1022        payload: Box<dyn std::any::Any + Send>,
1023        name: &str,
1024        rule: &Rule,
1025    ) -> TabnasError {
1026        let token = match rule.state {
1027            RuleState::Open => rule.o0().or_else(|| rule.c0()),
1028            RuleState::Close => rule.c0().or_else(|| rule.o0()),
1029        };
1030        TabnasError::from_panic(
1031            payload,
1032            &format!("action {name}"),
1033            "",
1034            token.map_or(0, |value| value.site.pos),
1035            token.map_or(1, |value| value.site.ri),
1036            token.map_or(1, |value| value.site.ci),
1037            &self.options,
1038        )
1039    }
1040
1041    fn attach_error(
1042        &self,
1043        mut error: TabnasError,
1044        rule: &Rule,
1045        stack: &[Rule],
1046        alts: &[AltSpec],
1047        token: Option<&Token>,
1048    ) -> TabnasError {
1049        let mut rule_stack: Vec<String> = stack.iter().map(|item| item.name.to_string()).collect();
1050        rule_stack.push(rule.name.to_string());
1051        let expected = alts
1052            .iter()
1053            .filter_map(|alt| alt.s.first())
1054            .flat_map(|tins| tins.iter().copied())
1055            .map(|tin| self.options.token_name(tin))
1056            .collect();
1057        error.attach_context(
1058            &rule.name,
1059            if rule.state == RuleState::Open {
1060                "o"
1061            } else {
1062                "c"
1063            },
1064            rule_stack,
1065            token,
1066            expected,
1067        );
1068        self.decorate_error(&mut error);
1069        error
1070    }
1071
1072    fn decorate_error(&self, error: &mut TabnasError) {
1073        error.apply_options(&self.options);
1074        error.plugins = self.instance.plugins.clone();
1075    }
1076
1077    fn catch_callback<T>(
1078        &self,
1079        api: &str,
1080        src: &str,
1081        callback: impl FnOnce() -> T,
1082    ) -> Result<T, TabnasError> {
1083        catch_unwind(AssertUnwindSafe(callback))
1084            .map_err(|payload| TabnasError::from_panic(payload, api, src, 0, 1, 1, &self.options))
1085    }
1086
1087    /// The `cancel` error a budget or a guard stops the parse with, at the
1088    /// token about to be read.
1089    fn cancelled(&self, src: &str, context: &Context, rule: &Rule, stack: &[Rule]) -> TabnasError {
1090        let token = context.t.first();
1091        let pnt = token
1092            .map(|token| {
1093                (
1094                    token.src.as_str(),
1095                    token.site.pos,
1096                    token.site.ri,
1097                    token.site.ci,
1098                )
1099            })
1100            .unwrap_or(("", 0, 1, 1));
1101        let error = TabnasError::new("cancel", pnt.0, src, pnt.1, pnt.2, pnt.3);
1102        self.attach_active_error(error, rule, stack, token)
1103    }
1104
1105    fn attach_active_error(
1106        &self,
1107        mut error: TabnasError,
1108        rule: &Rule,
1109        stack: &[Rule],
1110        token: Option<&Token>,
1111    ) -> TabnasError {
1112        if let Some(spec) = self.rules.get(&*rule.name) {
1113            let alts = if rule.state == RuleState::Open {
1114                &spec.open
1115            } else {
1116                &spec.close
1117            };
1118            self.attach_error(error, rule, stack, alts, token)
1119        } else {
1120            self.decorate_error(&mut error);
1121            error
1122        }
1123    }
1124
1125    fn phase_token(rule: &Rule) -> Option<&Token> {
1126        match rule.state {
1127            RuleState::Open => rule.o0().or_else(|| rule.c0()),
1128            RuleState::Close => rule.c0().or_else(|| rule.o0()),
1129        }
1130    }
1131
1132    fn ancestors_for<'a>(rule: &Rule, stack: &'a [Rule]) -> &'a [Rule] {
1133        if stack.last().is_some_and(|ancestor| ancestor.i == rule.i) {
1134            &stack[..stack.len() - 1]
1135        } else {
1136            stack
1137        }
1138    }
1139
1140    /// A copy of the rule that just finished, when something will read it.
1141    ///
1142    /// [`Parser::notify_rule_done`] is its only reader, and that returns
1143    /// without looking when no `ruleDone` subscriber is installed. Cloning
1144    /// a `Rule` copies the value tree it has built with it, which is 3.3%
1145    /// of a 1 MB parse spent for nobody in a grammar that subscribes to
1146    /// nothing. This is the treatment `RuleDoneAlt` already gets at the
1147    /// transition arms, for the same reason.
1148    fn rule_done_copy(&self, rule: &Rule) -> Option<Rule> {
1149        (!self.rule_done_subscribers.is_empty()).then(|| rule.clone())
1150    }
1151
1152    #[allow(clippy::too_many_arguments)]
1153    fn notify_rule_done(
1154        &self,
1155        rule: &Rule,
1156        context: &Context,
1157        state: RuleState,
1158        alt: Option<RuleDoneAlt>,
1159        probe: bool,
1160        src: &str,
1161        stack: &[Rule],
1162    ) -> Result<(), TabnasError> {
1163        if self.rule_done_subscribers.is_empty() {
1164            return Ok(());
1165        }
1166        let done = RuleDone {
1167            state,
1168            alt,
1169            forced: false,
1170            probe,
1171        };
1172        let mut site_rule = rule.clone();
1173        site_rule.state = state;
1174        for subscriber in &self.rule_done_subscribers {
1175            let result = self.catch_callback("ruleDone subscriber", src, || {
1176                subscriber(rule, context, &done)
1177            });
1178            result.map_err(|error| {
1179                self.attach_active_error(
1180                    error,
1181                    &site_rule,
1182                    Self::ancestors_for(&site_rule, stack),
1183                    Self::phase_token(&site_rule),
1184                )
1185            })?;
1186        }
1187        Ok(())
1188    }
1189
1190    fn notify_forced_close(
1191        &self,
1192        rule: &Rule,
1193        context: &Context,
1194        probe: bool,
1195        src: &str,
1196        stack: &[Rule],
1197    ) -> Result<(), TabnasError> {
1198        if self.rule_done_subscribers.is_empty() {
1199            return Ok(());
1200        }
1201        let done = RuleDone {
1202            state: RuleState::Close,
1203            alt: None,
1204            forced: true,
1205            probe,
1206        };
1207        let mut site_rule = rule.clone();
1208        site_rule.state = RuleState::Close;
1209        for subscriber in &self.rule_done_subscribers {
1210            let result = self.catch_callback("ruleDone subscriber", src, || {
1211                subscriber(rule, context, &done)
1212            });
1213            result.map_err(|error| {
1214                self.attach_active_error(
1215                    error,
1216                    &site_rule,
1217                    Self::ancestors_for(&site_rule, stack),
1218                    Self::phase_token(&site_rule),
1219                )
1220            })?;
1221        }
1222        Ok(())
1223    }
1224
1225    fn attempt_recover(
1226        &self,
1227        error: TabnasError,
1228        current_rule: &mut Rule,
1229        stack: &mut Vec<Rule>,
1230        context: &mut Context,
1231        lexer: &mut Lexer,
1232        mode: &mut ParseMode<'_>,
1233    ) -> Result<bool, TabnasError> {
1234        let src = error.full_source.clone();
1235        let recover = &self.options.parse.recover;
1236
1237        // The order is TypeScript's `attemptRecover`: the error is recorded
1238        // as it is built, dropped again when it falls inside the suppress
1239        // window of the recovery before it, and only then is the cap read.
1240        // So a give-up leaves the error listed, once and without recovery
1241        // metadata, unless it was a cascade; and a cascade at the cap still
1242        // recovers, since dropping it keeps the list within the cap.
1243        let suppressed = context
1244            .recover_at
1245            .is_some_and(|at| context.v_abs.saturating_sub(at) < recover.suppress);
1246        let recorded = (!suppressed).then(|| {
1247            mode.errors.push(error.clone());
1248            context.errs.push(error.clone());
1249            mode.errors.len() - 1
1250        });
1251        if recover.max_recoveries < mode.errors.len() {
1252            return Ok(false);
1253        }
1254
1255        let no_progress = context.recover_at == Some(context.v_abs);
1256        let last_si = context.recover_si;
1257        context.recover_at = Some(context.v_abs);
1258
1259        let sync = compute_sync_tins(current_rule, stack, &self.rules, &self.options);
1260        let mut pending: std::collections::VecDeque<Token> = std::mem::take(&mut context.t).into();
1261        let mut skipped = 0usize;
1262
1263        let candidate = loop {
1264            let next = if let Some(token) = pending.pop_front() {
1265                Some(token)
1266            } else {
1267                loop {
1268                    let next_raw = self.catch_callback("lexer callback", &src, || {
1269                        lexer.next_raw_for_rule(current_rule, context)
1270                    });
1271                    let next_raw = next_raw.map_err(|error| {
1272                        self.attach_active_error(
1273                            error,
1274                            current_rule,
1275                            stack,
1276                            Self::phase_token(current_rule),
1277                        )
1278                    })?;
1279                    match next_raw {
1280                        Ok(mut token) => {
1281                            for subscriber in &self.lex_subscribers {
1282                                let result = self.catch_callback("lex subscriber", &src, || {
1283                                    subscriber(&mut token, current_rule, context)
1284                                });
1285                                result.map_err(|error| {
1286                                    self.attach_active_error(
1287                                        error,
1288                                        current_rule,
1289                                        stack,
1290                                        Some(&token),
1291                                    )
1292                                })?;
1293                            }
1294                            if self.ignore_tins.contains(&token.tin) {
1295                                continue;
1296                            }
1297                            for subscriber in &self.token_subscribers {
1298                                let result = self.catch_callback("token subscriber", &src, || {
1299                                    subscriber(&token)
1300                                });
1301                                result.map_err(|error| {
1302                                    self.attach_active_error(
1303                                        error,
1304                                        current_rule,
1305                                        stack,
1306                                        Some(&token),
1307                                    )
1308                                })?;
1309                            }
1310                            break Some(token);
1311                        }
1312                        Err(lex_error) => {
1313                            let mut token = error_token(&lex_error);
1314                            for subscriber in &self.lex_subscribers {
1315                                let result = self.catch_callback("lex subscriber", &src, || {
1316                                    subscriber(&mut token, current_rule, context)
1317                                });
1318                                result.map_err(|error| {
1319                                    self.attach_active_error(
1320                                        error,
1321                                        current_rule,
1322                                        stack,
1323                                        Some(&token),
1324                                    )
1325                                })?;
1326                            }
1327                            lexer.skip_bad(&token, mid_construct(&lex_error.code));
1328                            if skipped >= recover.max_skip {
1329                                break None;
1330                            }
1331                            skipped += 1;
1332                        }
1333                    }
1334                }
1335            };
1336            let Some(token) = next else {
1337                return Ok(false);
1338            };
1339            if token.tin == TIN_ZZ
1340                || (sync.contains(&token.tin)
1341                    && !(no_progress && last_si.is_some_and(|si| token.site.pos <= si)))
1342            {
1343                break token;
1344            }
1345            // A bad token is skipped like any other, but it did not move
1346            // the cursor when it was cut: a custom matcher's `Lexer::bad`
1347            // leaves it where it was, and so does one buffered under
1348            // relexing. Step past it, as TypeScript's `advanceLexPast` does,
1349            // or the next fetch would cut the same bad token again.
1350            if token.tin == TIN_BD {
1351                lexer.skip_bad(&token, mid_construct(&token.why));
1352            }
1353            if skipped >= recover.max_skip {
1354                return Ok(false);
1355            }
1356            skipped += 1;
1357        };
1358
1359        if candidate.tin == TIN_ZZ
1360            && no_progress
1361            && last_si.is_some_and(|si| candidate.site.pos <= si)
1362        {
1363            return Ok(false);
1364        }
1365        context.recover_si = Some(candidate.site.pos);
1366        if let Some(index) = recorded {
1367            let recovered = Some(crate::RecoveredAt {
1368                skipped,
1369                sync: Some(candidate.tin),
1370                bad: false,
1371            });
1372            if let Some(entry) = context.errs.get_mut(index) {
1373                entry.recovered.clone_from(&recovered);
1374            }
1375            if let Some(entry) = mode.errors.get_mut(index) {
1376                entry.recovered = recovered;
1377            }
1378        }
1379
1380        context.t.push(candidate.clone());
1381        context.t.extend(pending);
1382        context.bad_to = None;
1383        context.bad_error = None;
1384
1385        if !recover.pop_until_valid {
1386            // The only pop that resumes a parent WITHOUT accepting a
1387            // child node over the top of it, so the only one that would
1388            // see a parked `child_node`. `Rule::park_child_node` is
1389            // skipped for the whole parse when this option is off, so
1390            // nothing is parked to see.
1391            if let Some(parent) = stack.pop() {
1392                // The erroring rule is dropped: close the probes it opened.
1393                context.probe_abandon(current_rule);
1394                *current_rule = parent;
1395                return Ok(true);
1396            }
1397            return Ok(false);
1398        }
1399
1400        if accepts_close(current_rule, candidate.tin, &self.rules, &self.options) {
1401            if current_rule.state == RuleState::Open {
1402                current_rule.state = RuleState::Close;
1403            } else {
1404                current_rule.skip_befores = true;
1405            }
1406            return Ok(true);
1407        }
1408
1409        // Close the probes each abandoned rule opened, subscribed or not.
1410        let probe = context.probe_abandon(current_rule);
1411        self.notify_forced_close(current_rule, context, probe, &src, stack)?;
1412        while let Some(mut parent) = stack.pop() {
1413            parent.accept_child(current_rule);
1414            if accepts_close(&parent, candidate.tin, &self.rules, &self.options) {
1415                *current_rule = parent;
1416                return Ok(true);
1417            }
1418            let probe = context.probe_abandon(&parent);
1419            self.notify_forced_close(&parent, context, probe, &src, stack)?;
1420            *current_rule = parent;
1421        }
1422        Ok(false)
1423    }
1424
1425    #[allow(clippy::too_many_arguments)]
1426    fn recover_error_pass(
1427        &self,
1428        error: TabnasError,
1429        state: RuleState,
1430        mut alt: Option<RuleDoneAlt>,
1431        fallback_error_token: bool,
1432        src: &str,
1433        current_rule: &mut Rule,
1434        stack: &mut Vec<Rule>,
1435        context: &mut Context,
1436        lexer: &mut Lexer,
1437        mode: &mut ParseMode<'_>,
1438    ) -> Result<(), TabnasError> {
1439        // TypeScript's RuleSpec.bad performs recovery inside the rule pass;
1440        // the ordinary ruleDone event is dispatched only after that pass
1441        // returns. Preserve that ordering so any synthesized forced-close
1442        // events precede this final attempted-pass event.
1443        let event_rule = current_rule.clone();
1444        // The failing pass is the probe's if one is open where it failed,
1445        // even when the recovery below closes it before the pass is
1446        // reported.
1447        let probe_at_error = 0 < context.probe_depth();
1448        let recovered = mode.recovering
1449            && self.attempt_recover(error.clone(), current_rule, stack, context, lexer, mode)?;
1450        if !recovered && fallback_error_token {
1451            if let Some(alt) = alt.as_mut().filter(|alt| alt.err.is_none()) {
1452                let tin = self.options.token(&error.token.name).unwrap_or(TIN_BD);
1453                let mut token = Token::new(
1454                    error.token.name.clone(),
1455                    tin,
1456                    Value::Undefined,
1457                    error.token.src.clone(),
1458                    crate::Point {
1459                        len: error.len,
1460                        site: crate::Site {
1461                            si: error.pos,
1462                            pos: error.pos,
1463                            ri: error.row,
1464                            ci: error.col,
1465                        },
1466                    },
1467                );
1468                token.bad(&error.code);
1469                alt.err = Some(token);
1470            }
1471        }
1472        let probe = context.probe_take() || probe_at_error;
1473        self.notify_rule_done(&event_rule, context, state, alt, probe, src, stack)?;
1474        if recovered {
1475            Ok(())
1476        } else {
1477            // TypeScript's `RuleSpec.bad` gives up by rethrowing the last
1478            // error it recorded, which `attempt_recover` has just recorded
1479            // or dropped as a cascade, so the list is already complete. Only
1480            // an empty list makes it raise, and record, a fresh one.
1481            if mode.recovering && !mode.errors.is_empty() {
1482                mode.gave_up = true;
1483            }
1484            Err(error)
1485        }
1486    }
1487
1488    #[allow(clippy::too_many_arguments)]
1489    fn recover_after_actions(
1490        &self,
1491        result: Result<(), TabnasError>,
1492        state: RuleState,
1493        alt: Option<RuleDoneAlt>,
1494        src: &str,
1495        current_rule: &mut Rule,
1496        stack: &mut Vec<Rule>,
1497        context: &mut Context,
1498        lexer: &mut Lexer,
1499        mode: &mut ParseMode<'_>,
1500    ) -> Result<bool, TabnasError> {
1501        let Err(error) = result else {
1502            return Ok(false);
1503        };
1504        self.recover_error_pass(
1505            error,
1506            state,
1507            alt,
1508            true,
1509            src,
1510            current_rule,
1511            stack,
1512            context,
1513            lexer,
1514            mode,
1515        )?;
1516        Ok(true)
1517    }
1518
1519    pub fn parse(&self, src: &str) -> Result<Value, TabnasError> {
1520        self.parse_with_meta(src, Value::Undefined)
1521    }
1522
1523    pub fn parse_with_meta(&self, src: &str, meta: Value) -> Result<Value, TabnasError> {
1524        self.parse_with_owner(src, meta, None, None)
1525    }
1526
1527    pub(crate) fn parse_for(
1528        &self,
1529        owner: &crate::Tabnas,
1530        src: &str,
1531        meta: Value,
1532    ) -> Result<Value, TabnasError> {
1533        self.parse_with_owner(src, meta, Some(owner), None)
1534    }
1535
1536    pub(crate) fn parse_for_with_context(
1537        &self,
1538        owner: &crate::Tabnas,
1539        src: &str,
1540        meta: Value,
1541        parent: &ContextSeed,
1542    ) -> Result<Value, TabnasError> {
1543        self.parse_with_owner(src, meta, Some(owner), Some(parent))
1544    }
1545
1546    fn parse_with_owner(
1547        &self,
1548        src: &str,
1549        meta: Value,
1550        owner: Option<&crate::Tabnas>,
1551        parent: Option<&ContextSeed>,
1552    ) -> Result<Value, TabnasError> {
1553        match catch_unwind(AssertUnwindSafe(|| {
1554            self.parse_uncaught(src, meta, owner, parent)
1555        })) {
1556            Ok(result) => result,
1557            Err(payload) => {
1558                let mut error =
1559                    TabnasError::from_panic(payload, "Parser::parse", src, 0, 1, 1, &self.options);
1560                self.decorate_error(&mut error);
1561                Err(error)
1562            }
1563        }
1564    }
1565
1566    fn parse_uncaught(
1567        &self,
1568        src: &str,
1569        meta: Value,
1570        owner: Option<&crate::Tabnas>,
1571        parent: Option<&ContextSeed>,
1572    ) -> Result<Value, TabnasError> {
1573        if let Some(result) = self.run_parser_start(src, &meta, owner, parent) {
1574            return result.map_err(|mut error| {
1575                self.decorate_error(&mut error);
1576                error
1577            });
1578        }
1579        let mut errors = Vec::new();
1580        let recovering = self.options.parse.recover.enabled;
1581        let mut mode = ParseMode {
1582            continuation: None,
1583            recovering,
1584            errors: &mut errors,
1585            partial: None,
1586            gave_up: false,
1587        };
1588        let result = self
1589            .parse_inner(src, meta, owner, parent, &mut mode)
1590            .map_err(|mut error| {
1591                self.decorate_error(&mut error);
1592                error
1593            });
1594        match result {
1595            Err(_) if recovering => Ok(mode
1596                .partial
1597                .and_then(PartialValue::into_value)
1598                .unwrap_or(Value::Undefined)),
1599            other => other,
1600        }
1601    }
1602
1603    pub fn parse_recover(&self, src: &str) -> ParseRecovery {
1604        self.parse_recover_with_meta(src, Value::Undefined)
1605    }
1606
1607    pub fn parse_recover_with_meta(&self, src: &str, meta: Value) -> ParseRecovery {
1608        self.parse_recover_with_owner(src, meta, None, None)
1609    }
1610
1611    pub(crate) fn parse_recover_for(
1612        &self,
1613        owner: &crate::Tabnas,
1614        src: &str,
1615        meta: Value,
1616    ) -> ParseRecovery {
1617        self.parse_recover_with_owner(src, meta, Some(owner), None)
1618    }
1619
1620    pub(crate) fn parse_recover_for_with_context(
1621        &self,
1622        owner: &crate::Tabnas,
1623        src: &str,
1624        meta: Value,
1625        parent: &ContextSeed,
1626    ) -> ParseRecovery {
1627        self.parse_recover_with_owner(src, meta, Some(owner), Some(parent))
1628    }
1629
1630    fn parse_recover_with_owner(
1631        &self,
1632        src: &str,
1633        meta: Value,
1634        owner: Option<&crate::Tabnas>,
1635        parent: Option<&ContextSeed>,
1636    ) -> ParseRecovery {
1637        match catch_unwind(AssertUnwindSafe(|| {
1638            self.parse_recover_uncaught(src, meta, owner, parent)
1639        })) {
1640            Ok(result) => result,
1641            Err(payload) => {
1642                let mut error = TabnasError::from_panic(
1643                    payload,
1644                    "Parser::parse_recover",
1645                    src,
1646                    0,
1647                    1,
1648                    1,
1649                    &self.options,
1650                );
1651                self.decorate_error(&mut error);
1652                ParseRecovery {
1653                    value: None,
1654                    errors: Vec::new(),
1655                    fatal: Some(error),
1656                }
1657            }
1658        }
1659    }
1660
1661    fn parse_recover_uncaught(
1662        &self,
1663        src: &str,
1664        meta: Value,
1665        owner: Option<&crate::Tabnas>,
1666        parent: Option<&ContextSeed>,
1667    ) -> ParseRecovery {
1668        if let Some(result) = self.run_parser_start(src, &meta, owner, parent) {
1669            return match result {
1670                Ok(value) => ParseRecovery {
1671                    value: Some(value),
1672                    errors: Vec::new(),
1673                    fatal: None,
1674                },
1675                Err(mut error) => {
1676                    self.decorate_error(&mut error);
1677                    ParseRecovery {
1678                        value: None,
1679                        errors: Vec::new(),
1680                        fatal: Some(error),
1681                    }
1682                }
1683            };
1684        }
1685        let mut errors = Vec::new();
1686        let recovering = self.options.parse.recover.enabled;
1687        let (result, partial, gave_up) = {
1688            let mut mode = ParseMode {
1689                continuation: None,
1690                recovering,
1691                errors: &mut errors,
1692                partial: None,
1693                gave_up: false,
1694            };
1695            let result = self
1696                .parse_inner(src, meta, owner, parent, &mut mode)
1697                .map_err(|mut error| {
1698                    self.decorate_error(&mut error);
1699                    error
1700                });
1701            (
1702                result,
1703                mode.partial.and_then(PartialValue::into_value),
1704                mode.gave_up,
1705            )
1706        };
1707        for error in &mut errors {
1708            self.decorate_error(error);
1709        }
1710        match result {
1711            Ok(value) => ParseRecovery {
1712                value: Some(value),
1713                errors,
1714                fatal: None,
1715            },
1716            Err(error) => {
1717                // The error that ended the parse is listed once, where the
1718                // parse ended, as TypeScript's constructor lists it, unless
1719                // recovery gave up on an error it had already accounted for.
1720                if !gave_up {
1721                    errors.push(error.clone());
1722                }
1723                ParseRecovery {
1724                    value: recovering.then_some(partial).flatten(),
1725                    errors,
1726                    fatal: (!recovering).then_some(error),
1727                }
1728            }
1729        }
1730    }
1731
1732    fn run_parser_start(
1733        &self,
1734        src: &str,
1735        meta: &Value,
1736        owner: Option<&crate::Tabnas>,
1737        parent: Option<&ContextSeed>,
1738    ) -> Option<Result<Value, TabnasError>> {
1739        let result = if let Some(start) = self.options.parser.start_with_context.as_ref() {
1740            let Some(owner) = owner else {
1741                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
1742                error.detail =
1743                    "parser.start requires an owning Tabnas instance; call Tabnas::parse".into();
1744                self.decorate_error(&mut error);
1745                return Some(Err(error));
1746            };
1747            catch_unwind(AssertUnwindSafe(|| start(src, owner, meta, parent)))
1748        } else if let Some(start) = self.options.parser.start_with_instance.as_ref() {
1749            let Some(owner) = owner else {
1750                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
1751                error.detail =
1752                    "parser.start requires an owning Tabnas instance; call Tabnas::parse".into();
1753                self.decorate_error(&mut error);
1754                return Some(Err(error));
1755            };
1756            catch_unwind(AssertUnwindSafe(|| start(src, owner, meta)))
1757        } else {
1758            let start = self.options.parser.start.as_ref()?;
1759            catch_unwind(AssertUnwindSafe(|| start(src)))
1760        };
1761        Some(match result {
1762            Ok(result) => result.map_err(|error| *error),
1763            Err(payload) => Err(TabnasError::from_panic(
1764                payload,
1765                "parser.start",
1766                src,
1767                0,
1768                1,
1769                1,
1770                &self.options,
1771            )),
1772        })
1773    }
1774
1775    /// Return the token kinds that can legally follow `src` when it is
1776    /// treated as a prefix. The result is an intentional over-approximation:
1777    /// runtime conditions and counters may still reject a listed token.
1778    pub fn continuations(&self, src: &str) -> Continuations {
1779        self.continuations_with_owner(src, None)
1780    }
1781
1782    pub(crate) fn continuations_for(&self, owner: &crate::Tabnas, src: &str) -> Continuations {
1783        self.continuations_with_owner(src, Some(owner))
1784    }
1785
1786    fn continuations_with_owner(&self, src: &str, owner: Option<&crate::Tabnas>) -> Continuations {
1787        catch_unwind(AssertUnwindSafe(|| self.continuations_uncaught(src, owner)))
1788            .unwrap_or_else(|_| self.start_continuations())
1789    }
1790
1791    fn continuations_uncaught(&self, src: &str, owner: Option<&crate::Tabnas>) -> Continuations {
1792        let mut capture = ContinuationCapture::default();
1793        let mut errors = Vec::new();
1794        let result = {
1795            let mut mode = ParseMode {
1796                continuation: Some(&mut capture),
1797                recovering: false,
1798                errors: &mut errors,
1799                partial: None,
1800                gave_up: false,
1801            };
1802            self.parse_inner(src, Value::Undefined, owner, None, &mut mode)
1803        };
1804        let mut tins = if result.is_ok() {
1805            if capture.have_end {
1806                capture.at_end.insert(TIN_ZZ);
1807                capture.at_end.into_iter().collect()
1808            } else {
1809                self.start_openers()
1810            }
1811        } else if capture.failure.is_empty() {
1812            self.start_openers()
1813        } else {
1814            capture.failure
1815        };
1816        tins.sort_unstable();
1817        tins.dedup();
1818        let tokens = tins
1819            .iter()
1820            .map(|tin| self.options.token_name(*tin))
1821            .collect();
1822        Continuations { tins, tokens }
1823    }
1824
1825    fn start_continuations(&self) -> Continuations {
1826        let tins = self.start_openers();
1827        let tokens = tins
1828            .iter()
1829            .map(|tin| self.options.token_name(*tin))
1830            .collect();
1831        Continuations { tins, tokens }
1832    }
1833
1834    fn start_openers(&self) -> Vec<Tin> {
1835        let start = self.rules.get(&self.options.rule.start);
1836        let mut out = BTreeSet::new();
1837        if let Some(spec) = start {
1838            for alt in &spec.open {
1839                if groups_enabled(alt, &self.options) {
1840                    if let Some(slot) = alt.s.first() {
1841                        out.extend(completion_tins(slot));
1842                    }
1843                }
1844            }
1845        }
1846        out.into_iter().collect()
1847    }
1848
1849    /// The tins the rule can accept at `slot`, as the lexer's custom-matcher
1850    /// gate wants them, or nothing when there is no custom matcher to gate.
1851    ///
1852    /// Both consumers (the `fix_len` filter and the expected-first pass in
1853    /// `Lexer::next_raw_inner`) only read this list to decide WHICH of
1854    /// `options.match_tokens` may fire; with no match tokens the answer is
1855    /// the same for any list, and the walk over an empty table yields
1856    /// nothing either way. The empty slice is therefore exact, and it
1857    /// spares every token fetch the rule's accepted-token row entirely --
1858    /// the last work that sat on the fetch path of a grammar with no
1859    /// custom matcher at all. TS `makeMatchMatcher`
1860    /// returns null on an empty table and never asks (ts/src/lexer.ts).
1861    ///
1862    /// `options` is the one `Arc<Options>` the lexer reads too, so this
1863    /// guard consults the field its consumers consult and cannot drift
1864    /// from it.
1865    ///
1866    /// The table was collated over the alternates the group filters
1867    /// enabled at install. `rule.include` and `rule.exclude` are public and
1868    /// may have been rewritten since, and the step then chooses among the
1869    /// alternates the live filters enable (its `groups_prepared` guard),
1870    /// so the row is collated from the live filters too, rather than
1871    /// letting an alternate the step will not try decide which matcher
1872    /// runs first.
1873    fn expected_match_tins(&self, rule: &Rule, slot: usize) -> Cow<'_, [Tin]> {
1874        if self.options.match_tokens.is_empty() {
1875            return Cow::Borrowed(&[]);
1876        }
1877        // The table is the rule's, chosen by what the rule is called --
1878        // exactly as the name-keyed map this replaced chose it. The slot
1879        // is only a hint that skips the hash: `name` is public and a
1880        // callback may have written it, so the slot is trusted only while
1881        // the name installed there is still the rule's own, and anything
1882        // else falls back to the lookup by name. A slot never answers for
1883        // a name that is not at it.
1884        let index = match self.names.get(rule.slot) {
1885            Some(installed) if *installed == rule.name => rule.slot,
1886            _ => match self.rules.get_index_of(&*rule.name) {
1887                Some(index) => index,
1888                None => return Cow::Borrowed(&[]),
1889            },
1890        };
1891        let is_open = rule.state == RuleState::Open;
1892        if self.options.rule.include == self.prepared_include
1893            && self.options.rule.exclude == self.prepared_exclude
1894        {
1895            return Cow::Borrowed(self.expected_tins[index].at(is_open, slot));
1896        }
1897        let installed = &self.rules[index];
1898        let alts = if is_open {
1899            &installed.open
1900        } else {
1901            &installed.close
1902        };
1903        Cow::Owned(ExpectedTins::live(alts, &self.options, slot))
1904    }
1905
1906    /// Record, for `continuations()`, what could have followed where a
1907    /// fetch raised a bad token: the lexer's own fault, or a `#BD` token a
1908    /// custom matcher returned.
1909    ///
1910    /// TypeScript records nothing at such a fetch (`_contTins` is cleared
1911    /// when `parse_alts` begins and written only when every alternate has
1912    /// failed on a buffered token), so `Tabnas.continuations` computes the
1913    /// answer from the buffer for the rule that fetched, at position 0
1914    /// (`continuationTins(ctx, rule)`), or, when that rule is `NORULE`
1915    /// because the check for trailing content fetched, answers with the
1916    /// start rule's openers. Here a rule's fetch records the same set, and
1917    /// the trailing check records nothing, which `continuations_uncaught`
1918    /// turns into the start openers.
1919    fn capture_fetch_failure(
1920        &self,
1921        context: &Context,
1922        rule: &Rule,
1923        stack: &[Rule],
1924        mode: &mut ParseMode<'_>,
1925        fetch: Fetch,
1926    ) {
1927        if fetch != Fetch::Rule {
1928            return;
1929        }
1930        if let Some(capture) = mode.continuation.as_deref_mut() {
1931            capture.failure =
1932                continuation_tins(context, rule, stack, &self.rules, &self.options, 0, None);
1933        }
1934    }
1935
1936    #[allow(clippy::too_many_arguments)]
1937    fn ensure_lookahead(
1938        &self,
1939        lexer: &mut Lexer,
1940        context: &mut Context,
1941        rule: &mut Rule,
1942        count: usize,
1943        mode: &mut ParseMode<'_>,
1944        site: ParseSite<'_>,
1945        fetch: Fetch,
1946    ) -> Result<(), TabnasError> {
1947        while context.t.len() < count {
1948            if context.t.last().is_some_and(|token| token.tin == TIN_ZZ) {
1949                break;
1950            }
1951            let expected_match_tins = self.expected_match_tins(rule, context.t.len());
1952            let token = loop {
1953                let next = match context.next_replay() {
1954                    Some(token) => Ok(token),
1955                    None => {
1956                        let result = self.catch_callback("lexer callback", site.source, || {
1957                            lexer.next_rule_token(&expected_match_tins, rule, context)
1958                        });
1959                        result.map_err(|error| {
1960                            self.attach_active_error(
1961                                error,
1962                                rule,
1963                                site.stack,
1964                                Self::phase_token(rule),
1965                            )
1966                        })?
1967                    }
1968                };
1969                let mut token = match next {
1970                    Ok(token) => token,
1971                    // The lexer's own fault is a `#BD` token from here on,
1972                    // as it is in TypeScript, where `lex.next` builds the
1973                    // token, hands it to the lex subscribers and returns
1974                    // it, and `parse_alts` reads what came back. A
1975                    // subscriber may rewrite it, its code and position
1976                    // included, and the parse sees what it left: so the
1977                    // fault takes the path below, the one a `#BD` token a
1978                    // custom matcher returned takes, and the lexer's error
1979                    // itself goes no further than this token.
1980                    Err(error) => error_token(&error),
1981                };
1982                for subscriber in &self.lex_subscribers {
1983                    let result = self.catch_callback("lex subscriber", site.source, || {
1984                        subscriber(&mut token, rule, context)
1985                    });
1986                    result.map_err(|error| {
1987                        self.attach_active_error(error, rule, site.stack, Some(&token))
1988                    })?;
1989                }
1990                // A bad token a custom matcher returned (`Lexer::bad`,
1991                // `Lexer::bad_span`) is a lexer fault like any other, and
1992                // is handled here exactly as the lexer's own faults are
1993                // above, which is what TypeScript's fetch in `parse_alts`
1994                // does with every `#BD` token it is handed: raised at once,
1995                // with its own code at its own position, or under recovery
1996                // recorded, coalesced with the run it continues, and
1997                // stepped past. Only relexing leaves it in the lookahead,
1998                // for an alternate to re-cut. Buffered, it failed every
1999                // alternate it met, and the error named the first token of
2000                // the lookahead instead: `unexpected`, at the good token in
2001                // front of it.
2002                if token.tin == TIN_BD && !self.options.lex.relex {
2003                    let code = if token.why.is_empty() {
2004                        "unexpected"
2005                    } else {
2006                        token.why.as_str()
2007                    };
2008                    let error = TabnasError::new(
2009                        code,
2010                        token.src.clone(),
2011                        site.source,
2012                        token.site.pos,
2013                        token.site.ri,
2014                        token.site.ci,
2015                    );
2016                    let error = self.attach_error(error, rule, site.stack, site.alts, Some(&token));
2017                    if mode.recovering && fetch == Fetch::Rule {
2018                        if absorb_lex_error(&error, context, &self.options, mode.errors) {
2019                            lexer.skip_bad(&token, mid_construct(&error.code));
2020                            continue;
2021                        }
2022                        mode.gave_up = true;
2023                    }
2024                    self.capture_fetch_failure(context, rule, site.stack, mode, fetch);
2025                    return Err(error);
2026                }
2027                if token.tin == TIN_ZZ {
2028                    if let Some(capture) = mode.continuation.as_deref_mut() {
2029                        // The end is a legal continuation of a prefix that
2030                        // parses, whoever fetched it. What else is legal
2031                        // there is what the fetching rule's alternates could
2032                        // still take; the check for trailing content has no
2033                        // rule, and TypeScript's capture (the lex subscriber
2034                        // in `Tabnas.continuations`) answers it with nothing,
2035                        // since its `rule` is then `NORULE`.
2036                        capture.have_end = true;
2037                        if fetch == Fetch::Rule {
2038                            capture.at_end.extend(continuation_tins(
2039                                context,
2040                                rule,
2041                                site.stack,
2042                                &self.rules,
2043                                &self.options,
2044                                context.t.len(),
2045                                None,
2046                            ));
2047                        }
2048                    }
2049                }
2050                if !self.ignore_tins.contains(&token.tin) {
2051                    break token;
2052                }
2053            };
2054            for subscriber in &self.token_subscribers {
2055                let result =
2056                    self.catch_callback("token subscriber", site.source, || subscriber(&token));
2057                result.map_err(|error| {
2058                    self.attach_active_error(error, rule, site.stack, Some(&token))
2059                })?;
2060            }
2061            let is_end = token.tin == TIN_ZZ;
2062            context.t.push(token);
2063            if is_end {
2064                break;
2065            }
2066        }
2067        Ok(())
2068    }
2069
2070    fn parse_inner(
2071        &self,
2072        src: &str,
2073        meta: Value,
2074        owner: Option<&crate::Tabnas>,
2075        parent: Option<&ContextSeed>,
2076        mode: &mut ParseMode<'_>,
2077    ) -> Result<Value, TabnasError> {
2078        let input_meta = meta.clone();
2079        let mut context = Context::new(
2080            self.options.rewind.history,
2081            src,
2082            meta,
2083            Arc::clone(&self.options),
2084            self.instance.clone(),
2085        );
2086        if let Some(parent) = parent {
2087            context.apply_seed(parent);
2088        }
2089        for prepare in &self.options.parse.prepare {
2090            let outcome = self.catch_callback("parse.prepare", src, || {
2091                prepare.run(owner, &mut context, &input_meta)
2092            })?;
2093            if let Err(detail) = outcome {
2094                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
2095                error.detail = detail.into();
2096                return Err(error);
2097            }
2098        }
2099        for prepare in self.options.parse.named_prepare.values() {
2100            let outcome = self.catch_callback("parse.prepare", src, || {
2101                prepare.run(owner, &mut context, &input_meta)
2102            })?;
2103            if let Err(detail) = outcome {
2104                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
2105                error.detail = detail.into();
2106                return Err(error);
2107            }
2108        }
2109
2110        if src.is_empty() {
2111            return if self.options.lex.empty {
2112                Ok(self.options.lex.empty_result.clone())
2113            } else {
2114                Err(TabnasError::new("unexpected", "", src, 0, 1, 1))
2115            };
2116        }
2117
2118        // The cached regex is the one the parser was built with; use it
2119        // only while the options still carry the pattern it came from.
2120        let exclude_regex = if self.exclude_pattern == self.options.number.exclude {
2121            self.exclude_regex.clone()
2122        } else {
2123            compile_number_exclude(&self.options)
2124        };
2125        let mut lexer = Lexer::with_shared(src, Arc::clone(&self.options), exclude_regex);
2126
2127        // One lookup for the start rule: whether it exists, its shared
2128        // name handle and the spec to bind, which used to be three.
2129        let start_name = self.options.rule.start.as_str();
2130        let Some((start_slot, start_shared, start_spec)) = self.installed(start_name) else {
2131            return Ok(Value::Undefined);
2132        };
2133
2134        let mut current_rule = Rule::new(start_shared.clone(), Value::Undefined);
2135        current_rule.bind_spec(start_spec, start_shared, start_slot);
2136        current_rule.i = 0;
2137        let root_node = current_rule.node.clone();
2138        context.set_root(root_node.clone());
2139        let mut stack: Vec<Rule> = Vec::new();
2140        // Whether a pushed rule may let go of `child_node` while it is
2141        // buried. Read once: `self.options` is reached through `&self`,
2142        // so this cannot change under the parse, and the rule that parks
2143        // is the rule `attempt_recover` will resume.
2144        let park_child_nodes = self.options.parse.recover.pop_until_valid;
2145        let mut next_rule_id = 1;
2146        #[allow(unused_assignments)]
2147        let mut final_value = None;
2148
2149        let mut iterations = 0usize;
2150        let maxmul = if self.options.rule.maxmul == 0 {
2151            3
2152        } else {
2153            self.options.rule.maxmul
2154        };
2155        let max_iterations = self
2156            .rules
2157            .len()
2158            .saturating_mul(src.encode_utf16().count())
2159            .saturating_mul(4)
2160            .saturating_mul(maxmul)
2161            .max(100);
2162        let budget = &self.options.parse.budget;
2163
2164        // One match record for the whole parse, reset at the head of each
2165        // rule step. It used to be born twice per step -- a seed and a
2166        // per-alternate candidate -- and then moved twice more, at 320
2167        // bytes a move, to end up holding what one record could have held
2168        // all along. TypeScript keeps exactly one per context
2169        // (`ctx._palt`); a nested parse runs `parse_inner` again and so
2170        // gets its own, which is why this is a local and not a field.
2171        let mut matched = AltMatch::default();
2172
2173        'parse: loop {
2174            context.set_active(&current_rule, &stack);
2175            update_partial(mode, &root_node, &current_rule, &stack);
2176            iterations += 1;
2177            if iterations > max_iterations {
2178                let pnt = context
2179                    .t
2180                    .first()
2181                    .map(|t| (t.site.pos, t.site.ri, t.site.ci))
2182                    .unwrap_or((0, 1, 1));
2183                return Err(TabnasError::new("unexpected", "", src, pnt.0, pnt.1, pnt.2));
2184            }
2185            context.iteration = iterations - 1;
2186            // The guards run first, and at every step the budget can run
2187            // on: a grammar's bound holds whatever budget the caller set.
2188            if context.iteration > 0 {
2189                for guard in &self.parse_guards {
2190                    let result = self.catch_callback("parse guard", src, || guard(&context));
2191                    let keep_going = result.map_err(|error| {
2192                        self.attach_active_error(
2193                            error,
2194                            &current_rule,
2195                            &stack,
2196                            Self::phase_token(&current_rule).or_else(|| context.t.first()),
2197                        )
2198                    })?;
2199                    if !keep_going {
2200                        return Err(self.cancelled(src, &context, &current_rule, &stack));
2201                    }
2202                }
2203            }
2204            if budget.check_every_n > 0
2205                && context.iteration > 0
2206                && context.iteration % budget.check_every_n == 0
2207            {
2208                if let Some(check) = &budget.on_check {
2209                    let result =
2210                        self.catch_callback("parse.budget.onCheck", src, || check(&context));
2211                    let keep_going = result.map_err(|error| {
2212                        self.attach_active_error(
2213                            error,
2214                            &current_rule,
2215                            &stack,
2216                            Self::phase_token(&current_rule).or_else(|| context.t.first()),
2217                        )
2218                    })?;
2219                    if !keep_going {
2220                        return Err(self.cancelled(src, &context, &current_rule, &stack));
2221                    }
2222                }
2223            }
2224
2225            // The rule was bound to its prepared state when it was routed
2226            // to, and carries the slot that state sits at. Taking the spec
2227            // from there rather than from the rule costs an array index in
2228            // place of comparing the two names byte by byte, and hands out a
2229            // borrow of the parser instead of a reference count on the spec
2230            // -- the clone existed only to release the borrow on the rule
2231            // that the callbacks below need mutably, and the parser is not
2232            // mutable here at all.
2233            //
2234            // The record is a hint. `spec` and `name` are both public on a
2235            // rule and reachable from any callback, so the slot is trusted
2236            // only while the record still describes the rule in hand: same
2237            // spec by pointer, same name. Anything else falls back to the
2238            // rule's own spec, and to the lookup by name as the guard for a
2239            // rule that was never bound.
2240            let by_name;
2241            let (prepared, spec) = match self.prepared.get(current_rule.slot).filter(|prepared| {
2242                Arc::ptr_eq(&prepared.spec, &current_rule.spec)
2243                    && prepared.name == current_rule.name
2244            }) {
2245                Some(prepared) => (Some(prepared), &prepared.spec),
2246                None => {
2247                    by_name = if current_rule.spec.name == *current_rule.name {
2248                        Arc::clone(&current_rule.spec)
2249                    } else {
2250                        match self.rules.get(&*current_rule.name) {
2251                            Some(s) => s.clone(),
2252                            None => {
2253                                let pnt = context
2254                                    .t
2255                                    .first()
2256                                    .map(|t| (t.site.pos, t.site.ri, t.site.ci))
2257                                    .unwrap_or((0, 1, 1));
2258                                return Err(TabnasError::new(
2259                                    "unknown_rule",
2260                                    &*current_rule.name,
2261                                    src,
2262                                    pnt.0,
2263                                    pnt.1,
2264                                    pnt.2,
2265                                ));
2266                            }
2267                        }
2268                    };
2269                    (None, &by_name)
2270                }
2271            };
2272
2273            let is_open = current_rule.state == RuleState::Open;
2274            // A pass that begins inside a probe is the probe's, even when
2275            // error recovery closes the probe before the pass is reported.
2276            let probe_at_start = 0 < context.probe_depth();
2277            let alts = if is_open { &spec.open } else { &spec.close };
2278
2279            for subscriber in &self.rule_subscribers {
2280                let result = self.catch_callback("rule subscriber", src, || {
2281                    subscriber(&mut current_rule, &mut context)
2282                });
2283                result.map_err(|error| {
2284                    self.attach_error(
2285                        error,
2286                        &current_rule,
2287                        &stack,
2288                        alts,
2289                        Self::phase_token(&current_rule).or_else(|| context.t.first()),
2290                    )
2291                })?;
2292            }
2293            update_partial(mode, &root_node, &current_rule, &stack);
2294
2295            // 1. Run before-actions. Recovery can retry a failed close pass;
2296            // its before-close actions have already run and must not replay.
2297            let skip_befores = current_rule.skip_befores;
2298            current_rule.skip_befores = false;
2299            let before_enabled = if is_open {
2300                current_rule.bo
2301            } else {
2302                current_rule.bc
2303            };
2304            // `bo`/`bc` are run control, not presence -- see
2305            // `run_after_actions`. An empty order is the phase having
2306            // nothing to run, and skipping it here also skips the
2307            // snapshot the state callbacks would have been handed.
2308            let by_spec;
2309            let before_bindings: &[ActionBinding] = if skip_befores || !before_enabled {
2310                &[]
2311            } else {
2312                match prepared {
2313                    Some(prepared) => prepared.before(is_open),
2314                    None => {
2315                        let (actions, callbacks, states, order) = if is_open {
2316                            (&spec.bo, &spec.bo_fns, &spec.bo_state_fns, &spec.bo_order)
2317                        } else {
2318                            (&spec.bc, &spec.bc_fns, &spec.bc_state_fns, &spec.bc_order)
2319                        };
2320                        by_spec = resolved_action_order(actions, callbacks, states, order);
2321                        &by_spec
2322                    }
2323                }
2324            };
2325            if !before_bindings.is_empty() {
2326                let label = if is_open {
2327                    "before-open action"
2328                } else {
2329                    "before-close action"
2330                };
2331                let next = is_open.then(|| current_rule.snapshot());
2332                let site = ParseSite {
2333                    source: src,
2334                    stack: &stack,
2335                    alts,
2336                };
2337                let mut output = None;
2338                let mut lifecycle_error = None;
2339                for binding in before_bindings {
2340                    output = match binding {
2341                        ActionBinding::Named(action) => {
2342                            if let Some(callback) = self.state_actions.get(action) {
2343                                self.run_state_callback(
2344                                    label,
2345                                    callback,
2346                                    &mut current_rule,
2347                                    &mut context,
2348                                    next.as_deref(),
2349                                    output,
2350                                )
2351                                .map_err(|error| {
2352                                    self.attach_action_error(
2353                                        error,
2354                                        src,
2355                                        &current_rule,
2356                                        &stack,
2357                                        alts,
2358                                    )
2359                                })?
2360                            } else {
2361                                self.run_action(action, &mut current_rule, &mut context)
2362                                    .map_err(|error| {
2363                                        self.attach_action_error(
2364                                            error,
2365                                            src,
2366                                            &current_rule,
2367                                            &stack,
2368                                            alts,
2369                                        )
2370                                    })?;
2371                                None
2372                            }
2373                        }
2374                        ActionBinding::Callback(callback) => {
2375                            self.run_context_callback(
2376                                label,
2377                                callback,
2378                                &mut current_rule,
2379                                &mut context,
2380                            )
2381                            .map_err(|error| {
2382                                self.attach_action_error(error, src, &current_rule, &stack, alts)
2383                            })?;
2384                            None
2385                        }
2386                        ActionBinding::State(callback) => self
2387                            .run_state_callback(
2388                                label,
2389                                callback,
2390                                &mut current_rule,
2391                                &mut context,
2392                                next.as_deref(),
2393                                output,
2394                            )
2395                            .map_err(|error| {
2396                                self.attach_action_error(error, src, &current_rule, &stack, alts)
2397                            })?,
2398                    };
2399                    match self.check_lifecycle_output(output, &current_rule, site) {
2400                        Ok(next_output) => output = next_output,
2401                        Err(error) => {
2402                            lifecycle_error = Some(error);
2403                            break;
2404                        }
2405                    }
2406                }
2407                if let Some(error) = lifecycle_error {
2408                    update_partial(mode, &root_node, &current_rule, &stack);
2409                    self.recover_error_pass(
2410                        error,
2411                        if is_open {
2412                            RuleState::Open
2413                        } else {
2414                            RuleState::Close
2415                        },
2416                        None,
2417                        false,
2418                        src,
2419                        &mut current_rule,
2420                        &mut stack,
2421                        &mut context,
2422                        &mut lexer,
2423                        mode,
2424                    )?;
2425                    continue 'parse;
2426                }
2427            }
2428            update_partial(mode, &root_node, &current_rule, &stack);
2429
2430            // 2. Select alternates
2431            let mut matched_alt_idx: Option<usize> = None;
2432            let mut matched_count = 0;
2433            // Nothing has read the record since the last step ended, so
2434            // this is the only point it has to be clean by.
2435            matched.reset();
2436            // Set once either of the two condition callbacks that receive
2437            // the record has written into it, so a rejected alternate's
2438            // writes are wiped before the next alternate is tried. Rust
2439            // keeps the alternates isolated from each other here; only the
2440            // candidates that were actually offered a record pay for it.
2441            let mut record_written = false;
2442            // The winning alternate's matched tokens, when they are known to
2443            // still describe `context.t`. See the assignment below.
2444            let mut matched_tokens: Option<Rc<Vec<Token>>> = None;
2445
2446            // Asked once per step rather than once per alternate. When
2447            // the options still carry what the prepared answers were
2448            // worked out against, every alternate below reads a `bool`;
2449            // when a callback has rewritten either list, every alternate
2450            // falls back to deriving it, exactly as before.
2451            let groups_prepared = self.options.rule.include == self.prepared_include
2452                && self.options.rule.exclude == self.prepared_exclude;
2453
2454            // First-token index. Once the first lookahead token is in
2455            // hand, and the lexer is not renegotiating token identity
2456            // (under relex an alternate may re-cut a token it does not
2457            // name, so every alternate stays a candidate), only the
2458            // alternates that can take that token at position 0 are
2459            // tried, in their original order. Until the first fetch,
2460            // alternates are tried in order as before: the first
2461            // alternate with a sequence fetches the token.
2462            let first_index = if self.options.lex.relex {
2463                None
2464            } else {
2465                prepared.map(|prepared| prepared.first(is_open))
2466            };
2467            // The two candidate lists (alternates naming the first tin,
2468            // and the wildcards), walked together in index order once
2469            // selected, and the tin they were selected for.
2470            let mut lists: Option<(&[usize], &[usize])> = None;
2471            let mut key_tin = TIN_BD;
2472            let (mut ni, mut wi) = (0, 0);
2473            let mut next_idx = 0;
2474            loop {
2475                if lists.is_none() {
2476                    if let (Some(index), Some(t0)) = (first_index, context.t.first()) {
2477                        if t0.tin != TIN_BD {
2478                            key_tin = t0.tin;
2479                            let named = index.named(key_tin);
2480                            let wild = index.wild.as_slice();
2481                            (ni, wi) = (0, 0);
2482                            while ni < named.len() && named[ni] < next_idx {
2483                                ni += 1;
2484                            }
2485                            while wi < wild.len() && wild[wi] < next_idx {
2486                                wi += 1;
2487                            }
2488                            lists = Some((named, wild));
2489                        }
2490                    }
2491                }
2492                let idx = match lists {
2493                    Some((named, wild)) => {
2494                        let n = named.get(ni).copied().unwrap_or(alts.len());
2495                        let w = wild.get(wi).copied().unwrap_or(alts.len());
2496                        if alts.len() <= n && alts.len() <= w {
2497                            // No remaining alternate can take the first token.
2498                            break;
2499                        }
2500                        if n < w {
2501                            ni += 1;
2502                            n
2503                        } else {
2504                            wi += 1;
2505                            w
2506                        }
2507                    }
2508                    None => {
2509                        if alts.len() <= next_idx {
2510                            break;
2511                        }
2512                        next_idx += 1;
2513                        next_idx - 1
2514                    }
2515                };
2516                let alt = &alts[idx];
2517                let enabled = match prepared
2518                    .filter(|_| groups_prepared)
2519                    .and_then(|prepared| prepared.alt(is_open, idx))
2520                {
2521                    Some(prepared_alt) => prepared_alt.groups,
2522                    None => groups_enabled(alt, &self.options),
2523                };
2524                if !enabled {
2525                    continue;
2526                }
2527                let s_len = alt.s.len();
2528                let mut alt_matches = true;
2529                if record_written {
2530                    matched.reset();
2531                    record_written = false;
2532                }
2533                let mut relex_undo: Option<RelexUndo> = None;
2534                for (pos, pos_tins) in alt.s.iter().enumerate() {
2535                    if let Err(error) = self.ensure_lookahead(
2536                        &mut lexer,
2537                        &mut context,
2538                        &mut current_rule,
2539                        pos + 1,
2540                        mode,
2541                        ParseSite {
2542                            source: src,
2543                            stack: &stack,
2544                            alts,
2545                        },
2546                        Fetch::Rule,
2547                    ) {
2548                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
2549                    }
2550                    let Some(token) = context.t.get(pos).cloned() else {
2551                        alt_matches = false;
2552                        break;
2553                    };
2554                    if !slot_matches(pos_tins, token.tin) {
2555                        let recut = if self.options.lex.relex
2556                            && !token.src.is_empty()
2557                            && !pos_tins.is_empty()
2558                        {
2559                            let result = self.catch_callback("lexer relex callback", src, || {
2560                                lexer.relex(&token, pos_tins, &mut current_rule, &mut context)
2561                            });
2562                            result.map_err(|error| {
2563                                self.attach_error(error, &current_rule, &stack, alts, Some(&token))
2564                            })?
2565                        } else {
2566                            None
2567                        };
2568                        let Some((mut recut, checkpoint)) = recut else {
2569                            alt_matches = false;
2570                            break;
2571                        };
2572                        for subscriber in &self.lex_subscribers {
2573                            let result = self.catch_callback("lex subscriber", src, || {
2574                                subscriber(&mut recut, &mut current_rule, &mut context)
2575                            });
2576                            result.map_err(|error| {
2577                                self.attach_error(error, &current_rule, &stack, alts, Some(&recut))
2578                            })?;
2579                        }
2580                        if !pos_tins.contains(&recut.tin) {
2581                            lexer.unrelex(checkpoint, &mut context);
2582                            alt_matches = false;
2583                            break;
2584                        }
2585                        if relex_undo.is_none() {
2586                            relex_undo = Some(RelexUndo {
2587                                position: pos,
2588                                token,
2589                                checkpoint,
2590                                tokens: context.t.clone(),
2591                            });
2592                        }
2593                        context.t[pos] = recut;
2594                        context.t.truncate(pos + 1);
2595                    }
2596                }
2597
2598                if alt_matches {
2599                    let tokens: Rc<Vec<Token>> =
2600                        Rc::new(context.t.iter().take(s_len).cloned().collect());
2601                    // The declarative conditions are the only readers of a
2602                    // candidate rule; the callback tiers below run against
2603                    // `current_rule` itself, after its matched tokens are in
2604                    // place. Most alternates declare no declarative
2605                    // condition, and cloning a whole rule to answer a
2606                    // question nobody asks was the parse loop's largest
2607                    // single copy.
2608                    if alt.c_ref.is_some() || !alt.c.is_empty() {
2609                        let mut candidate = current_rule.clone();
2610                        if is_open {
2611                            candidate.o = Rc::clone(&tokens);
2612                        } else {
2613                            candidate.c = Rc::clone(&tokens);
2614                        }
2615                        if !builtin_condition_matches(alt.c_ref.as_deref(), &candidate)
2616                            || !conditions_match(&alt.c, &candidate, &stack)
2617                        {
2618                            alt_matches = false;
2619                        }
2620                    }
2621                    if alt_matches {
2622                        if is_open {
2623                            current_rule.o = Rc::clone(&tokens);
2624                        } else {
2625                            current_rule.c = Rc::clone(&tokens);
2626                        }
2627                        if let Some(condition) = &alt.c_fn {
2628                            context.set_rule(&current_rule);
2629                            let result = self.catch_callback("alternate condition", src, || {
2630                                condition(&mut current_rule, &mut context)
2631                            });
2632                            alt_matches = result.map_err(|error| {
2633                                self.attach_error(
2634                                    error,
2635                                    &current_rule,
2636                                    &stack,
2637                                    alts,
2638                                    Self::phase_token(&current_rule),
2639                                )
2640                            })?;
2641                        }
2642                        if alt_matches {
2643                            if let Some(condition) = &alt.c_match {
2644                                context.set_rule(&current_rule);
2645                                record_written = true;
2646                                let result =
2647                                    self.catch_callback("matched alternate condition", src, || {
2648                                        condition(&mut current_rule, &mut context, &mut matched)
2649                                    });
2650                                alt_matches = result.map_err(|error| {
2651                                    self.attach_error(
2652                                        error,
2653                                        &current_rule,
2654                                        &stack,
2655                                        alts,
2656                                        Self::phase_token(&current_rule),
2657                                    )
2658                                })?;
2659                            }
2660                        }
2661                        if alt_matches {
2662                            if let Some(condition) = &alt.c_lex_match {
2663                                context.set_rule(&current_rule);
2664                                record_written = true;
2665                                let result = self.catch_callback(
2666                                    "matched alternate lexer condition",
2667                                    src,
2668                                    || {
2669                                        condition(
2670                                            &mut current_rule,
2671                                            &mut context,
2672                                            &mut matched,
2673                                            &mut lexer,
2674                                        )
2675                                    },
2676                                );
2677                                alt_matches = result.map_err(|error| {
2678                                    self.attach_error(
2679                                        error,
2680                                        &current_rule,
2681                                        &stack,
2682                                        alts,
2683                                        Self::phase_token(&current_rule),
2684                                    )
2685                                })?;
2686                            }
2687                        }
2688                        if alt_matches {
2689                            if let Some(condition) = &alt.c_lex {
2690                                context.set_rule(&current_rule);
2691                                let result =
2692                                    self.catch_callback("alternate lexer condition", src, || {
2693                                        condition(&mut current_rule, &mut context, &mut lexer)
2694                                    });
2695                                alt_matches = result.map_err(|error| {
2696                                    self.attach_error(
2697                                        error,
2698                                        &current_rule,
2699                                        &stack,
2700                                        alts,
2701                                        Self::phase_token(&current_rule),
2702                                    )
2703                                })?;
2704                            }
2705                        }
2706                    }
2707                    if alt_matches {
2708                        matched_alt_idx = Some(idx);
2709                        matched_count = s_len;
2710                        // `tokens` is `context.t[..s_len]`, which is what the
2711                        // matched-token copy after this loop rebuilds from
2712                        // the same buffer. Between building it and here, the
2713                        // only things holding a `&mut Context` are the two
2714                        // condition callbacks, so without them the rebuild
2715                        // cannot differ and the vector below is reused
2716                        // instead of allocated and cloned a second time.
2717                        // `break` leaves the loop before the relex undo, so
2718                        // that cannot restore `context.t` underneath either.
2719                        if alt.c_fn.is_none() && alt.c_match.is_none() {
2720                            matched_tokens = Some(Rc::clone(&tokens));
2721                        }
2722                        break;
2723                    }
2724                }
2725                if let Some(undo) = relex_undo {
2726                    lexer.unrelex(undo.checkpoint, &mut context);
2727                    context.t = undo.tokens;
2728                    for subscriber in &self.lex_subscribers {
2729                        let mut restored = undo.token.clone();
2730                        let result = self.catch_callback("lex subscriber", src, || {
2731                            subscriber(&mut restored, &mut current_rule, &mut context)
2732                        });
2733                        result.map_err(|error| {
2734                            self.attach_error(error, &current_rule, &stack, alts, Some(&restored))
2735                        })?;
2736                    }
2737                    debug_assert_eq!(context.t.get(undo.position), Some(&undo.token));
2738                }
2739                // A condition can retag the first token, or replace it,
2740                // and then reject. The lists were selected for a tin the
2741                // token no longer has, and the plain scan would test every
2742                // later alternate against the token as it is now: resume
2743                // after this alternate, and select again at the top.
2744                if lists.is_some() && context.t.first().map(|t0| t0.tin) != Some(key_tin) {
2745                    lists = None;
2746                    next_idx = idx + 1;
2747                }
2748            }
2749
2750            if let Some(idx) = matched_alt_idx {
2751                // Copy matched tokens
2752                let matched_tokens = matched_tokens.unwrap_or_else(|| {
2753                    Rc::new(context.t.iter().take(matched_count).cloned().collect())
2754                });
2755                if is_open {
2756                    current_rule.o = matched_tokens;
2757                } else {
2758                    current_rule.c = matched_tokens;
2759                }
2760
2761                // Compatibility modifier for the original two-argument Rust
2762                // callback tier. It rewrites the source spec before dynamic
2763                // fields are resolved. The full `h_match` callback below runs
2764                // at the canonical point over the resolved AltMatch.
2765                //
2766                // Rewriting is the only thing here that needs an alternate of
2767                // its own; everything below reads one. A grammar that
2768                // declares no modifier — which is most of them, and both
2769                // benchmark grammars — now borrows the installed alternate
2770                // instead of copying it once per rule step.
2771                let rewritten: AltSpec;
2772                let alt: &AltSpec = if let Some(modifier) = alts[idx].h.clone() {
2773                    context.set_rule(&current_rule);
2774                    let source = alts[idx].clone();
2775                    let result = self.catch_callback("alternate modifier", src, || {
2776                        modifier(source, &mut current_rule, &mut context)
2777                    });
2778                    rewritten = result.map_err(|error| {
2779                        self.attach_error(
2780                            error,
2781                            &current_rule,
2782                            &stack,
2783                            alts,
2784                            Self::phase_token(&current_rule),
2785                        )
2786                    })?;
2787                    &rewritten
2788                } else {
2789                    &alts[idx]
2790                };
2791
2792                matched.h = alt.h_match.clone();
2793                if !alt.n.is_empty() {
2794                    matched.n = alt.n.clone();
2795                }
2796                if !alt.u.is_empty() {
2797                    matched.u = alt.u.clone();
2798                }
2799                if !alt.k.is_empty() {
2800                    matched.k = alt.k.clone();
2801                }
2802                // The alternate's group tags and action order, both worked
2803                // out when the rule was installed. A modifier rewrites the
2804                // whole `AltSpec` per step, so a rule that carries one is
2805                // resolved from what the modifier produced, not from the
2806                // record.
2807                let prepared_alt = if alts[idx].h.is_some() {
2808                    None
2809                } else {
2810                    prepared.and_then(|prepared| prepared.alt(is_open, idx))
2811                };
2812                match prepared_alt {
2813                    // `clone_from` writes into the list the last step left
2814                    // behind -- `AltMatch::reset` clears it without giving
2815                    // up its capacity -- rather than growing a fresh one.
2816                    Some(prepared_alt) => matched.g.clone_from(&prepared_alt.group_tags),
2817                    None if !alt.g.is_empty() => {
2818                        matched.g = listed(&alt.g).map(str::to_owned).collect();
2819                    }
2820                    None => {}
2821                }
2822                // Publishing the order into the record is only observable
2823                // when something this step runs receives the record. When
2824                // nothing does -- no matched condition, error, route,
2825                // backtrack, modifier or action, and no named binding that
2826                // could resolve to a matched action -- the step runs the
2827                // prepared order in place and the record keeps the empty
2828                // list it was born with. `matched_actions` is public and
2829                // may be written after `add_rule`, so whether a name can
2830                // reach it is asked here, per step, never cached.
2831                let prepared_alt = prepared_alt.filter(|prepared_alt| {
2832                    !prepared_alt.observed
2833                        && (!prepared_alt.named || self.matched_actions.is_empty())
2834                });
2835                if prepared_alt.is_none() {
2836                    let actions = resolved_alt_action_order(
2837                        &alt.a,
2838                        &alt.action_fns,
2839                        &alt.matched_action_fns,
2840                        &alt.action_order,
2841                    );
2842                    if !actions.is_empty() {
2843                        matched.actions = actions;
2844                    }
2845                }
2846                if !alt.action_configs.is_empty() {
2847                    matched.action_configs = alt.action_configs.clone();
2848                }
2849
2850                if let Some(route) = &alt.p_fn {
2851                    context.set_rule(&current_rule);
2852                    matched.p = self
2853                        .catch_callback("alternate push", src, || {
2854                            route(&mut current_rule, &mut context)
2855                        })
2856                        .map_err(|error| {
2857                            self.attach_error(
2858                                error,
2859                                &current_rule,
2860                                &stack,
2861                                alts,
2862                                Self::phase_token(&current_rule),
2863                            )
2864                        })?
2865                        .filter(|name| !name.is_empty());
2866                }
2867                if let Some(route) = &alt.p_match {
2868                    context.set_rule(&current_rule);
2869                    matched.p = self
2870                        .catch_callback("matched alternate push", src, || {
2871                            route(&mut current_rule, &mut context, &mut matched)
2872                        })
2873                        .map_err(|error| {
2874                            self.attach_error(
2875                                error,
2876                                &current_rule,
2877                                &stack,
2878                                alts,
2879                                Self::phase_token(&current_rule),
2880                            )
2881                        })?
2882                        .filter(|name| !name.is_empty());
2883                } else if alt.p_fn.is_none() {
2884                    if let Some(route) = alt.p.clone() {
2885                        matched.p = (!route.is_empty()).then_some(route);
2886                    }
2887                }
2888                if let Some(route) = &alt.r_fn {
2889                    context.set_rule(&current_rule);
2890                    matched.r = self
2891                        .catch_callback("alternate replace", src, || {
2892                            route(&mut current_rule, &mut context)
2893                        })
2894                        .map_err(|error| {
2895                            self.attach_error(
2896                                error,
2897                                &current_rule,
2898                                &stack,
2899                                alts,
2900                                Self::phase_token(&current_rule),
2901                            )
2902                        })?
2903                        .filter(|name| !name.is_empty());
2904                }
2905                if let Some(route) = &alt.r_match {
2906                    context.set_rule(&current_rule);
2907                    matched.r = self
2908                        .catch_callback("matched alternate replace", src, || {
2909                            route(&mut current_rule, &mut context, &mut matched)
2910                        })
2911                        .map_err(|error| {
2912                            self.attach_error(
2913                                error,
2914                                &current_rule,
2915                                &stack,
2916                                alts,
2917                                Self::phase_token(&current_rule),
2918                            )
2919                        })?
2920                        .filter(|name| !name.is_empty());
2921                } else if alt.r_fn.is_none() {
2922                    if let Some(route) = alt.r.clone() {
2923                        matched.r = (!route.is_empty()).then_some(route);
2924                    }
2925                }
2926                if let Some(backtrack) = &alt.b_fn {
2927                    context.set_rule(&current_rule);
2928                    matched.b = self
2929                        .catch_callback("alternate backtrack", src, || {
2930                            backtrack(&mut current_rule, &mut context)
2931                        })
2932                        .map_err(|error| {
2933                            self.attach_error(
2934                                error,
2935                                &current_rule,
2936                                &stack,
2937                                alts,
2938                                Self::phase_token(&current_rule),
2939                            )
2940                        })?;
2941                }
2942                if let Some(backtrack) = &alt.b_match {
2943                    context.set_rule(&current_rule);
2944                    matched.b = self
2945                        .catch_callback("matched alternate backtrack", src, || {
2946                            backtrack(&mut current_rule, &mut context, &mut matched)
2947                        })
2948                        .map_err(|error| {
2949                            self.attach_error(
2950                                error,
2951                                &current_rule,
2952                                &stack,
2953                                alts,
2954                                Self::phase_token(&current_rule),
2955                            )
2956                        })?;
2957                } else if alt.b_fn.is_none() && alt.b != 0 {
2958                    matched.b = alt.b;
2959                }
2960
2961                if let Some(modifier) = alt.h_match.clone() {
2962                    context.set_rule(&current_rule);
2963                    let next = is_open.then(|| current_rule.snapshot());
2964                    matched = self
2965                        .catch_callback("matched alternate modifier", src, || {
2966                            modifier(
2967                                std::mem::take(&mut matched),
2968                                &mut current_rule,
2969                                &mut context,
2970                                next.as_deref(),
2971                            )
2972                        })
2973                        .map_err(|error| {
2974                            self.attach_error(
2975                                error,
2976                                &current_rule,
2977                                &stack,
2978                                alts,
2979                                Self::phase_token(&current_rule),
2980                            )
2981                        })?;
2982                }
2983
2984                // The alternate's error hook runs AFTER the routing forms
2985                // have resolved and after both modifiers, and sees what the
2986                // modifier produced: routing, then modify, then check, in
2987                // every runtime (#154). It ran before the routing forms and
2988                // between the two modifiers here, which no grammar could
2989                // observe and no other port did.
2990                if let Some(error_hook) = alt.e.clone() {
2991                    context.set_rule(&current_rule);
2992                    let result = self.catch_callback("alternate error", src, || {
2993                        error_hook(&mut current_rule, &mut context)
2994                    });
2995                    matched.e = result
2996                        .map_err(|error| {
2997                            self.attach_error(
2998                                error,
2999                                &current_rule,
3000                                &stack,
3001                                alts,
3002                                Self::phase_token(&current_rule),
3003                            )
3004                        })?
3005                        .map(Box::new);
3006                }
3007                if let Some(error_hook) = alt.e_match.clone() {
3008                    context.set_rule(&current_rule);
3009                    let result = self.catch_callback("matched alternate error", src, || {
3010                        error_hook(&mut current_rule, &mut context, &mut matched)
3011                    });
3012                    matched.e = result
3013                        .map_err(|error| {
3014                            self.attach_error(
3015                                error,
3016                                &current_rule,
3017                                &stack,
3018                                alts,
3019                                Self::phase_token(&current_rule),
3020                            )
3021                        })?
3022                        .map(Box::new);
3023                }
3024                // Function-valued alternate errors are raised at the match
3025                // site, before counters, actions and consumption.
3026                if let Some(token) = matched.e.clone() {
3027                    let code = raised_error_code(&token);
3028                    let error = TabnasError::new(
3029                        code,
3030                        token.src.clone(),
3031                        src,
3032                        token.site.pos,
3033                        token.site.ri,
3034                        token.site.ci,
3035                    );
3036                    let done_alt = (!self.rule_done_subscribers.is_empty()).then(|| RuleDoneAlt {
3037                        b: matched.b,
3038                        g: matched.g.clone(),
3039                        p: matched.p.clone().unwrap_or_default(),
3040                        r: matched.r.clone().unwrap_or_default(),
3041                        err: Some((*token).clone()),
3042                    });
3043                    let error = self.attach_error(error, &current_rule, &stack, alts, Some(&token));
3044                    self.recover_error_pass(
3045                        error,
3046                        if is_open {
3047                            RuleState::Open
3048                        } else {
3049                            RuleState::Close
3050                        },
3051                        done_alt,
3052                        false,
3053                        src,
3054                        &mut current_rule,
3055                        &mut stack,
3056                        &mut context,
3057                        &mut lexer,
3058                        mode,
3059                    )?;
3060                    continue;
3061                }
3062
3063                // Update counters n
3064                for (k, v) in &matched.n {
3065                    if *v == 0 {
3066                        current_rule.n_mut().insert(k.clone(), 0);
3067                    } else {
3068                        *current_rule.n_mut().entry(k.clone()).or_insert(0) += *v;
3069                    }
3070                }
3071
3072                // Update user props u
3073                for (k, v) in &matched.u {
3074                    current_rule.u_mut().insert(k.clone(), v.clone());
3075                }
3076
3077                // Update keep props k
3078                for (k, v) in &matched.k {
3079                    current_rule.k_mut().insert(k.clone(), v.clone());
3080                }
3081
3082                let backtrack = matched.b;
3083                let consumed = matched_count.saturating_sub(backtrack);
3084                context.record_consumed(consumed);
3085
3086                // Run action. A bad token returned by a canonical action is
3087                // raised through the same recovery path as alt.e and
3088                // lifecycle actions; later actions must not run.
3089                let mut matched_action_error = None;
3090                let mut matched_action_token = None;
3091                // The published list has to be copied to be walked -- an
3092                // action may write the record it is being read out of, and
3093                // appending to `matched.actions` from inside this loop has
3094                // never reached it. The prepared list is not the record, so
3095                // it is walked where it lies.
3096                let published;
3097                let bindings: &[AltActionBinding] = match prepared_alt {
3098                    Some(prepared_alt) => &prepared_alt.actions,
3099                    None => {
3100                        published = matched.actions.clone();
3101                        &published
3102                    }
3103                };
3104                for binding in bindings {
3105                    let act_name = match binding {
3106                        AltActionBinding::Context(callback) => {
3107                            self.run_context_callback(
3108                                "alternate action",
3109                                callback,
3110                                &mut current_rule,
3111                                &mut context,
3112                            )
3113                            .map_err(|error| {
3114                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3115                            })?;
3116                            continue;
3117                        }
3118                        AltActionBinding::Matched(callback) => {
3119                            context.set_rule(&current_rule);
3120                            let result = self
3121                                .catch_callback("matched alternate action", src, || {
3122                                    callback(&mut current_rule, &mut context, &mut matched)
3123                                })
3124                                .map_err(|error| {
3125                                    self.attach_action_error(
3126                                        error,
3127                                        src,
3128                                        &current_rule,
3129                                        &stack,
3130                                        alts,
3131                                    )
3132                                })?;
3133                            let token = result.map_err(|action_error| {
3134                                self.attach_action_error(
3135                                    action_error.into(),
3136                                    src,
3137                                    &current_rule,
3138                                    &stack,
3139                                    alts,
3140                                )
3141                            })?;
3142                            if let Some(token) = token.filter(|token| !token.err.is_empty()) {
3143                                matched_action_error = Some(self.raised_token_error(
3144                                    &token,
3145                                    &current_rule,
3146                                    ParseSite {
3147                                        source: src,
3148                                        stack: &stack,
3149                                        alts,
3150                                    },
3151                                ));
3152                                matched_action_token = Some(token);
3153                                break;
3154                            }
3155                            continue;
3156                        }
3157                        AltActionBinding::Named(name) => name,
3158                    };
3159                    if let Some(callback) = self.matched_actions.get(act_name) {
3160                        context.set_rule(&current_rule);
3161                        let result = self
3162                            .catch_callback("named matched alternate action", src, || {
3163                                callback(&mut current_rule, &mut context, &mut matched)
3164                            })
3165                            .map_err(|error| {
3166                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3167                            })?;
3168                        let token = result.map_err(|action_error| {
3169                            self.attach_action_error(
3170                                action_error.into(),
3171                                src,
3172                                &current_rule,
3173                                &stack,
3174                                alts,
3175                            )
3176                        })?;
3177                        if let Some(token) = token.filter(|token| !token.err.is_empty()) {
3178                            matched_action_error = Some(self.raised_token_error(
3179                                &token,
3180                                &current_rule,
3181                                ParseSite {
3182                                    source: src,
3183                                    stack: &stack,
3184                                    alts,
3185                                },
3186                            ));
3187                            matched_action_token = Some(token);
3188                            break;
3189                        }
3190                        continue;
3191                    }
3192                    match act_name.as_str() {
3193                        "@probeInit$" => {
3194                            current_rule
3195                                .k_mut()
3196                                .insert("pd_phase".into(), Value::Number(0.0));
3197                            let mark = Value::Number(context.mark() as f64);
3198                            current_rule.k_mut().insert("pd_mark".into(), mark);
3199                            // The passes until the decision are the probe's.
3200                            context.probe_open(&current_rule);
3201                        }
3202                        "@probeDecide$" => {
3203                            let mark = current_rule.k.get("pd_mark").and_then(|value| {
3204                                if let Value::Number(mark) = value {
3205                                    usize::try_from(*mark as u64).ok()
3206                                } else {
3207                                    None
3208                                }
3209                            });
3210                            let Some(mark) = mark.filter(|mark| *mark <= context.v_abs) else {
3211                                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
3212                                error.detail =
3213                                    "@probeDecide$: phase-0 @probeInit$ did not record a valid mark"
3214                                        .into();
3215                                return Err(error);
3216                            };
3217                            if let Err(error) = self.ensure_lookahead(
3218                                &mut lexer,
3219                                &mut context,
3220                                &mut current_rule,
3221                                1,
3222                                mode,
3223                                ParseSite {
3224                                    source: src,
3225                                    stack: &stack,
3226                                    alts,
3227                                },
3228                                Fetch::Rule,
3229                            ) {
3230                                return Err(self.attach_error(
3231                                    error,
3232                                    &current_rule,
3233                                    &stack,
3234                                    alts,
3235                                    None,
3236                                ));
3237                            }
3238                            let disambiguator =
3239                                current_rule.k.get("pd_d").and_then(|value| match value {
3240                                    Value::String(name) => Some(name.as_str()),
3241                                    _ => None,
3242                                });
3243                            let phase = if context
3244                                .t
3245                                .first()
3246                                .is_some_and(|token| Some(token.name.as_str()) == disambiguator)
3247                            {
3248                                1.0
3249                            } else {
3250                                2.0
3251                            };
3252                            context.rewind(mark)?;
3253                            current_rule
3254                                .k_mut()
3255                                .insert("pd_phase".into(), Value::Number(phase));
3256                            context.probe_close();
3257                        }
3258                        _ => self
3259                            .run_action_with_config(
3260                                act_name,
3261                                &mut current_rule,
3262                                &mut context,
3263                                matched.action_configs.get(act_name),
3264                            )
3265                            .map_err(|error| {
3266                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3267                            })?,
3268                    }
3269                }
3270                if let Some(error) = matched_action_error {
3271                    let recovered_alt = Some(RuleDoneAlt {
3272                        b: matched.b,
3273                        g: matched.g.clone(),
3274                        p: matched.p.clone().unwrap_or_default(),
3275                        r: matched.r.clone().unwrap_or_default(),
3276                        err: None,
3277                    });
3278                    self.recover_error_pass(
3279                        error,
3280                        if is_open {
3281                            RuleState::Open
3282                        } else {
3283                            RuleState::Close
3284                        },
3285                        recovered_alt,
3286                        matched_action_token.is_some(),
3287                        src,
3288                        &mut current_rule,
3289                        &mut stack,
3290                        &mut context,
3291                        &mut lexer,
3292                        mode,
3293                    )?;
3294                    update_partial(mode, &root_node, &current_rule, &stack);
3295                    continue 'parse;
3296                }
3297                update_partial(mode, &root_node, &current_rule, &stack);
3298
3299                // The canonical action receives the live match record. Its
3300                // post-action p/r writes are a supported routing channel, so
3301                // resolve the transition only after the action sequence.
3302                // Nothing below reads `matched.p` or `matched.r` again: the
3303                // record's remaining readers take `b` and `g`. So the names
3304                // move out of it rather than being copied, which is the
3305                // second `String` each of them cost per rule step.
3306                let push_name = matched.p.take();
3307                let replace_name = matched.r.take();
3308                // Only a ruleDone subscriber ever reads this, and it is
3309                // cloned again at each of the transition arms below. A
3310                // grammar with no subscriber was building and copying it
3311                // several times per matched alternate for nobody.
3312                let done_alt = (!self.rule_done_subscribers.is_empty()).then(|| RuleDoneAlt {
3313                    b: matched.b,
3314                    g: matched.g.clone(),
3315                    p: push_name.clone().unwrap_or_default(),
3316                    r: replace_name.clone().unwrap_or_default(),
3317                    err: None,
3318                });
3319
3320                // Callback routes and action mutations cannot be validated at
3321                // grammar-install time. Reject an unknown destination at the
3322                // canonical point: after the matched action, but before any
3323                // lifecycle after-action or transition.
3324                //
3325                // Resolving it here also settles the transition below: the
3326                // arms take the shared name and the spec out of this one
3327                // lookup rather than hashing the same name twice more.
3328                // `push` wins over `replace` in the arms below, so this
3329                // resolves whichever of the two the parse will take.
3330                //
3331                // A route the grammar declared on this alternate was already
3332                // resolved when the rule was installed; all that is left of
3333                // it here is checking that the name the step is actually
3334                // routing to is still that name, which is a byte compare
3335                // against a handle rather than a hash of the same three
3336                // bytes for the tens of thousands of steps that route where
3337                // the grammar said they would.
3338                let mut route = match push_name.as_deref().or(replace_name.as_deref()) {
3339                    Some(name) => match prepared
3340                        .and_then(|prepared| prepared.alt(is_open, idx))
3341                        .map(|alt| if push_name.is_some() { &alt.p } else { &alt.r })
3342                        .and_then(|route| route.resolved(name))
3343                        .or_else(|| self.installed(name))
3344                    {
3345                        Some(resolved) => Some(resolved),
3346                        None => {
3347                            let mut token = Self::phase_token(&current_rule)
3348                                .cloned()
3349                                .or_else(|| context.t.first().cloned())
3350                                .unwrap_or_else(Token::no_token);
3351                            token.bad("unknown_rule");
3352                            token
3353                                .use_data_mut()
3354                                .insert("rulename".into(), Value::String(name.to_string()));
3355                            let error = self.raised_token_error(
3356                                &token,
3357                                &current_rule,
3358                                ParseSite {
3359                                    source: src,
3360                                    stack: &stack,
3361                                    alts,
3362                                },
3363                            );
3364                            self.recover_error_pass(
3365                                error,
3366                                if is_open {
3367                                    RuleState::Open
3368                                } else {
3369                                    RuleState::Close
3370                                },
3371                                done_alt,
3372                                false,
3373                                src,
3374                                &mut current_rule,
3375                                &mut stack,
3376                                &mut context,
3377                                &mut lexer,
3378                                mode,
3379                            )?;
3380                            update_partial(mode, &root_node, &current_rule, &stack);
3381                            continue 'parse;
3382                        }
3383                    },
3384                    None => None,
3385                };
3386
3387                // Resolve the transition before running lifecycle after-actions,
3388                // so they can inspect rule.next just like the canonical engine.
3389                // The action still belongs to the rule whose alternate matched.
3390                let completed_rule: Option<Rule>;
3391                let mut completed_value = None;
3392                if push_name.is_some() {
3393                    let (push_slot, push_shared, push_spec) =
3394                        route.take().expect("a push route was resolved above");
3395                    let mut child = Rule::bound(
3396                        push_shared.clone(),
3397                        current_rule.node.clone(),
3398                        Some(push_spec),
3399                        push_slot,
3400                    );
3401                    child.i = next_rule_id;
3402                    next_rule_id += 1;
3403                    child.d = stack.len() + 1;
3404                    child.parent_node = Some(current_rule.node.clone());
3405                    child.n = Rc::clone(&current_rule.n);
3406                    child.k = Rc::clone(&current_rule.k);
3407                    child.parent_rule = Some(bounded_history(
3408                        current_rule.snapshot(),
3409                        self.options.rule.history,
3410                        Link::PusherBefore,
3411                    ));
3412                    current_rule.next_rule_name = Some(push_shared);
3413                    current_rule.child_rule = Some(child.snapshot());
3414                    current_rule.next_rule = current_rule.child_rule.clone();
3415                    current_rule.note_child_push(&child);
3416                    // The link as this arm made it, so the relink below can
3417                    // tell whether an after action has changed it.
3418                    let linked = current_rule.child_rule.clone();
3419                    let after = self.run_after_actions(
3420                        spec,
3421                        prepared,
3422                        is_open,
3423                        &mut current_rule,
3424                        &mut context,
3425                        ParseSite {
3426                            source: src,
3427                            stack: &stack,
3428                            alts,
3429                        },
3430                    );
3431                    update_partial(mode, &root_node, &current_rule, &stack);
3432                    if self.recover_after_actions(
3433                        after,
3434                        if is_open {
3435                            RuleState::Open
3436                        } else {
3437                            RuleState::Close
3438                        },
3439                        done_alt.clone(),
3440                        src,
3441                        &mut current_rule,
3442                        &mut stack,
3443                        &mut context,
3444                        &mut lexer,
3445                        mode,
3446                    )? {
3447                        continue 'parse;
3448                    }
3449                    if is_open {
3450                        current_rule.state = RuleState::Close;
3451                    }
3452                    child.parent_rule = Some(bounded_history(
3453                        current_rule.snapshot(),
3454                        self.options.rule.history,
3455                        Link::Parent,
3456                    ));
3457                    // TypeScript and Go link the live rules, so from the
3458                    // child, `parent.child.parent.child` is the child
3459                    // itself. The snapshot linked above as `child` carries
3460                    // this rule as it stood before the push, whose `child`
3461                    // is the one pushed before (parser #259). With no
3462                    // bound, link the child again from a snapshot that
3463                    // carries this rule with the child linked, and give
3464                    // the child this rule as it then stands, so that a
3465                    // snapshot of the child reads the same chain: the
3466                    // pre-link record is two hops further down, past the
3467                    // four-hop read. The cost, measured on
3468                    // `rs/tests/rule_history_test.rs`'s flat array, is two
3469                    // more records kept per push, 8 for 6 per element.
3470                    // Under a bound the links stay as the canonical engine
3471                    // copies them, where that path reads nothing
3472                    // (`rule-history-bounded-pusher`). An after action that
3473                    // cleared or repointed `child` or `next` keeps its edit:
3474                    // the canonical engine links before the after actions
3475                    // and never overwrites them afterwards.
3476                    if crate::options::effective_rule_history(self.options.rule.history).is_none()
3477                        && current_rule.links_unchanged(&linked)
3478                    {
3479                        current_rule.relink_child(&child);
3480                        child.parent_rule = Some(current_rule.snapshot());
3481                    }
3482                    completed_rule = self.rule_done_copy(&current_rule);
3483                    // The child about to run shares this rule's node cell,
3484                    // and `child_node` may be a second handle on the very
3485                    // container it will write into. Let go of it for the
3486                    // duration -- see `Rule::park_child_node`. Taken after
3487                    // `rule_done_copy`, so a ruleDone subscriber still sees
3488                    // the rule exactly as it stood, and only when every pop
3489                    // that can resume this rule overwrites the field first
3490                    // (see `park_child_node` and `attempt_recover`).
3491                    if park_child_nodes {
3492                        current_rule.park_child_node();
3493                    }
3494                    stack.push(current_rule);
3495                    current_rule = child;
3496                } else if replace_name.is_some() {
3497                    let (replace_slot, replace_shared, replace_spec) =
3498                        route.take().expect("a replace route was resolved above");
3499                    let mut next = Rule::bound(
3500                        replace_shared.clone(),
3501                        current_rule.node.clone(),
3502                        Some(replace_spec),
3503                        replace_slot,
3504                    );
3505                    next.i = next_rule_id;
3506                    next_rule_id += 1;
3507                    next.d = current_rule.d;
3508                    next.parent_node = current_rule.parent_node.clone();
3509                    next.parent_rule = current_rule.parent_rule.clone();
3510                    next.n = Rc::clone(&current_rule.n);
3511                    next.k = Rc::clone(&current_rule.k);
3512                    current_rule.next_rule_name = Some(replace_shared);
3513                    current_rule.next_rule = Some(next.snapshot());
3514                    let after = self.run_after_actions(
3515                        spec,
3516                        prepared,
3517                        is_open,
3518                        &mut current_rule,
3519                        &mut context,
3520                        ParseSite {
3521                            source: src,
3522                            stack: &stack,
3523                            alts,
3524                        },
3525                    );
3526                    update_partial(mode, &root_node, &current_rule, &stack);
3527                    if self.recover_after_actions(
3528                        after,
3529                        if is_open {
3530                            RuleState::Open
3531                        } else {
3532                            RuleState::Close
3533                        },
3534                        done_alt.clone(),
3535                        src,
3536                        &mut current_rule,
3537                        &mut stack,
3538                        &mut context,
3539                        &mut lexer,
3540                        mode,
3541                    )? {
3542                        continue 'parse;
3543                    }
3544                    if is_open {
3545                        current_rule.state = RuleState::Close;
3546                    }
3547                    next.prev_rule = Some(bounded_history(
3548                        current_rule.snapshot(),
3549                        self.options.rule.history,
3550                        Link::Prev,
3551                    ));
3552                    // The rule being replaced stops existing here. If it is
3553                    // the one its parent PUSHED, the parent's `child` link
3554                    // stays on it -- TypeScript never relinks `rule.child`
3555                    // (rules.ts:665) and neither does Go (rule.go:1280) --
3556                    // so freeze the node cell and the record it ended on
3557                    // before it goes.
3558                    if let Some(parent) = stack.last_mut() {
3559                        parent.freeze_child(&current_rule);
3560                    }
3561                    // Moved rather than cloned: this arm hands the
3562                    // finished rule over instead of copying it, so the
3563                    // gate above has nothing to save here.
3564                    completed_rule = Some(current_rule);
3565                    current_rule = next;
3566                } else if is_open {
3567                    current_rule.next_rule_name = Some(current_rule.name.clone());
3568                    current_rule.next_rule = Some(current_rule.snapshot());
3569                    let after = self.run_after_actions(
3570                        spec,
3571                        prepared,
3572                        true,
3573                        &mut current_rule,
3574                        &mut context,
3575                        ParseSite {
3576                            source: src,
3577                            stack: &stack,
3578                            alts,
3579                        },
3580                    );
3581                    update_partial(mode, &root_node, &current_rule, &stack);
3582                    if self.recover_after_actions(
3583                        after,
3584                        RuleState::Open,
3585                        done_alt.clone(),
3586                        src,
3587                        &mut current_rule,
3588                        &mut stack,
3589                        &mut context,
3590                        &mut lexer,
3591                        mode,
3592                    )? {
3593                        continue 'parse;
3594                    }
3595                    current_rule.state = RuleState::Close;
3596                    completed_rule = self.rule_done_copy(&current_rule);
3597                } else {
3598                    // Close phase pop
3599                    current_rule.next_rule_name = stack.last().map(|rule| rule.name.clone());
3600                    current_rule.next_rule = stack.last().map(Rule::snapshot);
3601                    let after = self.run_after_actions(
3602                        spec,
3603                        prepared,
3604                        false,
3605                        &mut current_rule,
3606                        &mut context,
3607                        ParseSite {
3608                            source: src,
3609                            stack: &stack,
3610                            alts,
3611                        },
3612                    );
3613                    update_partial(mode, &root_node, &current_rule, &stack);
3614                    if self.recover_after_actions(
3615                        after,
3616                        RuleState::Close,
3617                        done_alt.clone(),
3618                        src,
3619                        &mut current_rule,
3620                        &mut stack,
3621                        &mut context,
3622                        &mut lexer,
3623                        mode,
3624                    )? {
3625                        continue 'parse;
3626                    }
3627                    let parent = stack.pop();
3628                    completed_rule = self.rule_done_copy(&current_rule);
3629                    if let Some(mut parent) = parent {
3630                        parent.accept_child(&current_rule);
3631                        current_rule = parent;
3632                    } else {
3633                        // Root rule popped! Done.
3634                        completed_value = Some(current_rule.node.borrow().clone());
3635                    }
3636                }
3637                // Read after every pass, subscribed or not, so that the
3638                // pass that opened or closed a probe is the only one its
3639                // flag covers.
3640                let probe = context.probe_take() || probe_at_start;
3641                if let Some(completed_rule) = &completed_rule {
3642                    self.notify_rule_done(
3643                        completed_rule,
3644                        &context,
3645                        if is_open {
3646                            RuleState::Open
3647                        } else {
3648                            RuleState::Close
3649                        },
3650                        done_alt,
3651                        probe,
3652                        src,
3653                        &stack,
3654                    )?;
3655                }
3656                if let Some(value) = completed_value {
3657                    final_value = Some(value);
3658                    break;
3659                }
3660                update_partial(mode, &root_node, &current_rule, &stack);
3661            } else if alts.is_empty() {
3662                // A state with no alternatives performs an implicit empty
3663                // pass. It still resolves next and runs lifecycle after-actions.
3664                let completed_rule: Option<Rule>;
3665                let mut completed_value = None;
3666                if is_open {
3667                    current_rule.next_rule_name = Some(current_rule.name.clone());
3668                    current_rule.next_rule = Some(current_rule.snapshot());
3669                    let after = self.run_after_actions(
3670                        spec,
3671                        prepared,
3672                        true,
3673                        &mut current_rule,
3674                        &mut context,
3675                        ParseSite {
3676                            source: src,
3677                            stack: &stack,
3678                            alts,
3679                        },
3680                    );
3681                    update_partial(mode, &root_node, &current_rule, &stack);
3682                    if self.recover_after_actions(
3683                        after,
3684                        RuleState::Open,
3685                        None,
3686                        src,
3687                        &mut current_rule,
3688                        &mut stack,
3689                        &mut context,
3690                        &mut lexer,
3691                        mode,
3692                    )? {
3693                        continue 'parse;
3694                    }
3695                    current_rule.state = RuleState::Close;
3696                    completed_rule = self.rule_done_copy(&current_rule);
3697                } else {
3698                    current_rule.next_rule_name = stack.last().map(|rule| rule.name.clone());
3699                    current_rule.next_rule = stack.last().map(Rule::snapshot);
3700                    let after = self.run_after_actions(
3701                        spec,
3702                        prepared,
3703                        false,
3704                        &mut current_rule,
3705                        &mut context,
3706                        ParseSite {
3707                            source: src,
3708                            stack: &stack,
3709                            alts,
3710                        },
3711                    );
3712                    update_partial(mode, &root_node, &current_rule, &stack);
3713                    if self.recover_after_actions(
3714                        after,
3715                        RuleState::Close,
3716                        None,
3717                        src,
3718                        &mut current_rule,
3719                        &mut stack,
3720                        &mut context,
3721                        &mut lexer,
3722                        mode,
3723                    )? {
3724                        continue 'parse;
3725                    }
3726                    let parent = stack.pop();
3727                    completed_rule = self.rule_done_copy(&current_rule);
3728                    if let Some(mut parent) = parent {
3729                        parent.accept_child(&current_rule);
3730                        current_rule = parent;
3731                    } else {
3732                        completed_value = Some(current_rule.node.borrow().clone());
3733                    }
3734                }
3735                let probe = context.probe_take() || probe_at_start;
3736                if let Some(completed_rule) = &completed_rule {
3737                    self.notify_rule_done(
3738                        completed_rule,
3739                        &context,
3740                        if is_open {
3741                            RuleState::Open
3742                        } else {
3743                            RuleState::Close
3744                        },
3745                        None,
3746                        probe,
3747                        src,
3748                        &stack,
3749                    )?;
3750                }
3751                if let Some(value) = completed_value {
3752                    final_value = Some(value);
3753                    break;
3754                }
3755                update_partial(mode, &root_node, &current_rule, &stack);
3756            } else {
3757                // Declared alternatives exist, but none matched.
3758                if is_open {
3759                    if let Err(error) = self.ensure_lookahead(
3760                        &mut lexer,
3761                        &mut context,
3762                        &mut current_rule,
3763                        1,
3764                        mode,
3765                        ParseSite {
3766                            source: src,
3767                            stack: &stack,
3768                            alts,
3769                        },
3770                        Fetch::Rule,
3771                    ) {
3772                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
3773                    }
3774                    if let Some(capture) = mode.continuation.as_deref_mut() {
3775                        let base = failed_alt_tins(&context, alts, &self.options);
3776                        capture.failure = continuation_tins(
3777                            &context,
3778                            &current_rule,
3779                            &stack,
3780                            &self.rules,
3781                            &self.options,
3782                            0,
3783                            Some(&base),
3784                        );
3785                    }
3786                    let t0 = context.t.first().cloned();
3787                    let (src_token, si, ri, ci) = if let Some(t) = t0.as_ref() {
3788                        (t.src.to_string(), t.site.pos, t.site.ri, t.site.ci)
3789                    } else {
3790                        (String::new(), src.len(), 1, 1)
3791                    };
3792                    let code = t0
3793                        .as_ref()
3794                        .map_or("unexpected", |t| deferred_error_code(t, mode.recovering));
3795                    let error = TabnasError::new(code, src_token, src, si, ri, ci);
3796                    let done_alt = (!alts.is_empty() && !self.rule_done_subscribers.is_empty())
3797                        .then(|| RuleDoneAlt {
3798                            b: 0,
3799                            g: Vec::new(),
3800                            p: String::new(),
3801                            r: String::new(),
3802                            err: t0.clone(),
3803                        });
3804                    let error = self.attach_error(error, &current_rule, &stack, alts, t0.as_ref());
3805                    self.recover_error_pass(
3806                        error,
3807                        RuleState::Open,
3808                        done_alt,
3809                        false,
3810                        src,
3811                        &mut current_rule,
3812                        &mut stack,
3813                        &mut context,
3814                        &mut lexer,
3815                        mode,
3816                    )?;
3817                    continue;
3818                } else {
3819                    if let Err(error) = self.ensure_lookahead(
3820                        &mut lexer,
3821                        &mut context,
3822                        &mut current_rule,
3823                        1,
3824                        mode,
3825                        ParseSite {
3826                            source: src,
3827                            stack: &stack,
3828                            alts,
3829                        },
3830                        Fetch::Rule,
3831                    ) {
3832                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
3833                    }
3834                    if let Some(capture) = mode.continuation.as_deref_mut() {
3835                        let base = failed_alt_tins(&context, alts, &self.options);
3836                        capture.failure = continuation_tins(
3837                            &context,
3838                            &current_rule,
3839                            &stack,
3840                            &self.rules,
3841                            &self.options,
3842                            0,
3843                            Some(&base),
3844                        );
3845                    }
3846                    let token = context.t.first().cloned();
3847                    let (source, pos, row, col) = token.as_ref().map_or_else(
3848                        || (String::new(), src.chars().count(), 1, 1),
3849                        |value| {
3850                            (
3851                                value.src.to_string(),
3852                                value.site.pos,
3853                                value.site.ri,
3854                                value.site.ci,
3855                            )
3856                        },
3857                    );
3858                    let code = token
3859                        .as_ref()
3860                        .map_or("unexpected", |t| deferred_error_code(t, mode.recovering));
3861                    let error = TabnasError::new(code, source, src, pos, row, col);
3862                    let done_alt = Some(RuleDoneAlt {
3863                        b: 0,
3864                        g: Vec::new(),
3865                        p: String::new(),
3866                        r: String::new(),
3867                        err: token.clone(),
3868                    });
3869                    let error =
3870                        self.attach_error(error, &current_rule, &stack, alts, token.as_ref());
3871                    self.recover_error_pass(
3872                        error,
3873                        RuleState::Close,
3874                        done_alt,
3875                        false,
3876                        src,
3877                        &mut current_rule,
3878                        &mut stack,
3879                        &mut context,
3880                        &mut lexer,
3881                        mode,
3882                    )?;
3883                    continue;
3884                }
3885            }
3886        }
3887
3888        let res = final_value.unwrap_or(Value::Null).unwrap_undefined();
3889        if mode.recovering {
3890            mode.partial = Some(PartialValue::Complete(res.clone()));
3891        }
3892
3893        // Post-loop check: ensure no unexpected trailing tokens. Recovery
3894        // keeps the completed value and reports the trailing fault. No
3895        // option turns the check off: `rule.finish` is the grammar's
3896        // end-of-source switch, kept in the options for its `@finish` to
3897        // read, not this check's (#250).
3898        if let Err(error) = self.ensure_lookahead(
3899            &mut lexer,
3900            &mut context,
3901            &mut current_rule,
3902            1,
3903            mode,
3904            ParseSite {
3905                source: src,
3906                stack: &stack,
3907                alts: &[],
3908            },
3909            Fetch::Trailing,
3910        ) {
3911            let error = self.attach_error(error, &current_rule, &stack, &[], None);
3912            if mode.recovering {
3913                mode.errors.push(error.clone());
3914                context.errs.push(error);
3915                return Ok(res);
3916            }
3917            return Err(error);
3918        }
3919        if let Some(t0) = context.t.first() {
3920            if t0.tin != TIN_ZZ {
3921                let code = if t0.tin == TIN_BD && !t0.why.is_empty() {
3922                    t0.why.as_str()
3923                } else {
3924                    "unexpected"
3925                };
3926                let error =
3927                    TabnasError::new(code, &*t0.src, src, t0.site.pos, t0.site.ri, t0.site.ci);
3928                let error = self.attach_error(
3929                    error,
3930                    &current_rule,
3931                    &stack,
3932                    &[AltSpec {
3933                        s: vec![vec![TIN_ZZ]],
3934                        ..Default::default()
3935                    }],
3936                    Some(t0),
3937                );
3938                if mode.recovering {
3939                    mode.errors.push(error.clone());
3940                    context.errs.push(error);
3941                    return Ok(res);
3942                }
3943                return Err(error);
3944            }
3945        }
3946        if self
3947            .options
3948            .result
3949            .fail
3950            .iter()
3951            .any(|failed| failed.deep_equal(&res))
3952        {
3953            let token = context.t.first();
3954            let error = token.map_or_else(
3955                || TabnasError::new("unexpected", "", src, 0, 1, 1),
3956                |token| {
3957                    TabnasError::new(
3958                        "unexpected",
3959                        &*token.src,
3960                        src,
3961                        token.site.pos,
3962                        token.site.ri,
3963                        token.site.ci,
3964                    )
3965                },
3966            );
3967            if mode.recovering {
3968                mode.errors.push(error.clone());
3969                context.errs.push(error);
3970                return Ok(res);
3971            }
3972            return Err(error);
3973        }
3974        Ok(res)
3975    }
3976}
3977
3978/// Keep a handle to the best partial node the recovery path would return.
3979///
3980/// Fifteen sites in the parse loop call this, twelve times per input
3981/// construct on the benchmark grammars, and outside recovery every one of them is a
3982/// load and a branch wrapped in a call. The guard is inline so the call
3983/// goes away. Inside recovery this deliberately clones only an `Rc` node
3984/// handle, never the `Value` being built: a `Value` snapshot keeps its
3985/// container shared and turns the next mutation into a copy of the entire
3986/// accumulated prefix.
3987///
3988/// The value read at the end is the one the last site would have taken:
3989/// the node is chosen by the same test, in the same order, and it keeps
3990/// the node even when recovery then pops the rules that held it. Only a
3991/// write to that node between the last site and the failure can tell the
3992/// two apart -- an action or callback that changes the node and then
3993/// fails, or is followed by a matched action whose error recovery gives up
3994/// on -- and the value is then the node as the failure left it, which is
3995/// what TypeScript returns: it reads the node in its `catch`
3996/// (`ts/src/parser.ts`), not before the step that failed.
3997#[inline]
3998fn update_partial(
3999    mode: &mut ParseMode<'_>,
4000    root_node: &Rc<RefCell<Value>>,
4001    current_rule: &Rule,
4002    stack: &[Rule],
4003) {
4004    if mode.recovering {
4005        mode.partial = best_partial_node(root_node, current_rule, stack).map(PartialValue::Node);
4006    }
4007}
4008
4009#[inline(never)]
4010fn best_partial_node(
4011    root_node: &Rc<RefCell<Value>>,
4012    current_rule: &Rule,
4013    stack: &[Rule],
4014) -> Option<Rc<RefCell<Value>>> {
4015    let usable = |node: &Rc<RefCell<Value>>| {
4016        (!matches!(*node.borrow(), Value::Undefined | Value::Null)).then(|| Rc::clone(node))
4017    };
4018
4019    usable(root_node)
4020        .or_else(|| stack.iter().find_map(|rule| usable(&rule.node)))
4021        .or_else(|| usable(&current_rule.node))
4022}
4023
4024fn error_token(error: &TabnasError) -> Token {
4025    let byte_position = error
4026        .full_source
4027        .char_indices()
4028        .nth(error.pos)
4029        .map_or(error.full_source.len(), |(index, _)| index);
4030    let mut token = Token::new(
4031        "#BD",
4032        TIN_BD,
4033        Value::Undefined,
4034        error.src.clone(),
4035        crate::Point {
4036            len: error.len,
4037            site: crate::Site {
4038                si: byte_position,
4039                pos: error.pos,
4040                ri: error.row,
4041                ci: error.col,
4042            },
4043        },
4044    );
4045    token.err = crate::TokenCode::from(error.code.as_str());
4046    token.why = token.err.clone();
4047    token
4048}
4049
4050/// The code an error with no matching alternative takes from the first
4051/// token of the lookahead, read as the canonical engine reads it at the
4052/// same point. Fail-fast, its deferred throw takes a bad token's why, else
4053/// `unexpected` (`bad.why || UNEXPECTED` in ts/src/rules.ts); when the
4054/// parse is recovering, `attemptRecover` takes the token's err ahead of
4055/// its why (`tkn.err || tkn.why`). This engine's own lexer faults set why
4056/// and err alike, so only a token a matcher built with err alone tells
4057/// the two apart: `unexpected` fail-fast, its err under recovery, in every
4058/// runtime (#285).
4059fn deferred_error_code(token: &Token, recovering: bool) -> &str {
4060    if token.tin != TIN_BD {
4061        "unexpected"
4062    } else if recovering && !token.err.is_empty() {
4063        &token.err
4064    } else if !token.why.is_empty() {
4065        &token.why
4066    } else {
4067        "unexpected"
4068    }
4069}
4070
4071fn raised_error_code(token: &Token) -> &str {
4072    if !token.err.is_empty() {
4073        &token.err
4074    } else if !token.why.is_empty() {
4075        &token.why
4076    } else {
4077        "unexpected"
4078    }
4079}
4080
4081fn mid_construct(code: &str) -> bool {
4082    matches!(code, "unprintable" | "invalid_unicode" | "invalid_ascii")
4083}
4084
4085/// Record a bad token met at a rule's fetch under recovery, in the order
4086/// TypeScript's `parse_alts` does it: a token inside the run the last one
4087/// began grows that run's error rather than being listed again; a new run
4088/// inside the suppress window of the recovery before it is a cascade of
4089/// that fault and is dropped; anything else is recorded. Returns whether
4090/// the fetch goes on past the token. It does not when the run outgrows
4091/// `maxSkip`, or when the list has outgrown `maxRecoveries`, a cap read
4092/// after recording, so the error that stops the parse is listed.
4093fn absorb_lex_error(
4094    error: &TabnasError,
4095    context: &mut Context,
4096    options: &Options,
4097    errors: &mut Vec<TabnasError>,
4098) -> bool {
4099    let recover = &options.parse.recover;
4100    let run = context
4101        .bad_error
4102        .filter(|index| *index < errors.len())
4103        .filter(|_| context.bad_to.is_some_and(|bad_to| error.pos <= bad_to));
4104    if let Some(index) = run {
4105        let previous = &mut errors[index];
4106        let recovered = previous.recovered.get_or_insert(crate::RecoveredAt {
4107            skipped: 0,
4108            sync: None,
4109            bad: true,
4110        });
4111        recovered.skipped = recovered.skipped.saturating_add(1);
4112        let skipped = recovered.skipped;
4113        if let Some(context_previous) = context.errs.get_mut(index) {
4114            *context_previous = previous.clone();
4115        }
4116        if recover.max_skip < skipped {
4117            return false;
4118        }
4119    } else if context
4120        .recover_at
4121        .is_some_and(|at| context.v_abs.saturating_sub(at) < recover.suppress)
4122    {
4123        context.bad_error = None;
4124    } else {
4125        let mut recorded = error.clone();
4126        recorded.recovered = Some(crate::RecoveredAt {
4127            skipped: 1,
4128            sync: None,
4129            bad: true,
4130        });
4131        errors.push(recorded.clone());
4132        context.errs.push(recorded);
4133        context.bad_error = Some(errors.len() - 1);
4134        context.recover_at = Some(context.v_abs);
4135    }
4136    context.bad_to = Some(error.pos.saturating_add(error.len.max(1)));
4137    errors.len() <= recover.max_recoveries
4138}
4139
4140fn slot_matches(slot: &[Tin], tin: Tin) -> bool {
4141    tin != TIN_BD && (slot.is_empty() || slot.contains(&tin) || slot.contains(&TIN_AA))
4142}
4143
4144fn alt_match_depth(alt: &AltSpec, context: &Context) -> usize {
4145    let mut depth = 0;
4146    while depth < alt.s.len() {
4147        let Some(token) = context.t.get(depth) else {
4148            break;
4149        };
4150        if !slot_matches(&alt.s[depth], token.tin) {
4151            break;
4152        }
4153        depth += 1;
4154    }
4155    depth
4156}
4157
4158fn completion_tins(slot: &[Tin]) -> impl Iterator<Item = Tin> + '_ {
4159    slot.iter()
4160        .copied()
4161        .chain(slot.is_empty().then_some(TIN_AA))
4162}
4163
4164fn failed_alt_tins(context: &Context, alts: &[AltSpec], options: &Options) -> Vec<Tin> {
4165    let mut out = BTreeSet::new();
4166    for alt in alts {
4167        if !groups_enabled(alt, options) {
4168            continue;
4169        }
4170        let depth = alt_match_depth(alt, context);
4171        if let Some(slot) = alt.s.get(depth) {
4172            out.extend(completion_tins(slot));
4173        }
4174    }
4175    out.into_iter().collect()
4176}
4177
4178fn lead_tins(alts: &[AltSpec], options: &Options, out: &mut BTreeSet<Tin>) {
4179    for alt in alts {
4180        if !groups_enabled(alt, options) {
4181            continue;
4182        }
4183        if let Some(slot) = alt.s.first() {
4184            out.extend(completion_tins(slot));
4185        }
4186    }
4187}
4188
4189fn has_empty_close(spec: &RuleSpec, options: &Options) -> bool {
4190    spec.close
4191        .iter()
4192        .any(|alt| groups_enabled(alt, options) && alt.s.is_empty())
4193}
4194
4195fn alt_has_sync_group(alt: &AltSpec, sync_groups: &[String]) -> bool {
4196    alt.g
4197        .split(',')
4198        .map(str::trim)
4199        .any(|tag| sync_groups.iter().any(|wanted| wanted == tag))
4200}
4201
4202fn add_close_tins(
4203    rule: &Rule,
4204    rules: &IndexMap<String, Arc<RuleSpec>>,
4205    options: &Options,
4206    tagged_only: bool,
4207    out: &mut BTreeSet<Tin>,
4208) {
4209    let Some(spec) = rules.get(&*rule.name) else {
4210        return;
4211    };
4212    for alt in &spec.close {
4213        if !groups_enabled(alt, options)
4214            || (tagged_only && !alt_has_sync_group(alt, &options.parse.recover.sync_groups))
4215        {
4216            continue;
4217        }
4218        if let Some(slot) = alt.s.first() {
4219            out.extend(completion_tins(slot));
4220        }
4221    }
4222}
4223
4224fn compute_sync_tins(
4225    rule: &Rule,
4226    stack: &[Rule],
4227    rules: &IndexMap<String, Arc<RuleSpec>>,
4228    options: &Options,
4229) -> BTreeSet<Tin> {
4230    let mut out = BTreeSet::new();
4231    add_close_tins(rule, rules, options, true, &mut out);
4232    for parent in stack.iter().rev() {
4233        add_close_tins(parent, rules, options, true, &mut out);
4234    }
4235    if out.is_empty() {
4236        add_close_tins(rule, rules, options, false, &mut out);
4237        for parent in stack.iter().rev() {
4238            add_close_tins(parent, rules, options, false, &mut out);
4239        }
4240    }
4241    for name in &options.parse.recover.sync_tokens {
4242        if let Some(tin) = options.token(name) {
4243            out.insert(tin);
4244        }
4245        if let Some(tins) = options.token_set.get(name.trim_start_matches('#')) {
4246            out.extend(tins.iter().copied());
4247        }
4248    }
4249    out
4250}
4251
4252fn accepts_close(
4253    rule: &Rule,
4254    tin: Tin,
4255    rules: &IndexMap<String, Arc<RuleSpec>>,
4256    options: &Options,
4257) -> bool {
4258    rules.get(&*rule.name).is_some_and(|spec| {
4259        spec.close.iter().any(|alt| {
4260            groups_enabled(alt, options)
4261                && (alt.s.is_empty() || alt.s.first().is_some_and(|slot| slot_matches(slot, tin)))
4262        })
4263    })
4264}
4265
4266fn add_openers(
4267    name: &str,
4268    rules: &IndexMap<String, Arc<RuleSpec>>,
4269    options: &Options,
4270    opened: &mut BTreeSet<String>,
4271    out: &mut BTreeSet<Tin>,
4272) {
4273    if name.is_empty() || !opened.insert(name.to_owned()) {
4274        return;
4275    }
4276    let Some(spec) = rules.get(name) else {
4277        return;
4278    };
4279    lead_tins(&spec.open, options, out);
4280    for alt in &spec.open {
4281        if !groups_enabled(alt, options) || !alt.s.is_empty() {
4282            continue;
4283        }
4284        if let Some(push) = alt.p.as_deref() {
4285            add_openers(push, rules, options, opened, out);
4286        }
4287        if let Some(replace) = alt.r.as_deref() {
4288            add_openers(replace, rules, options, opened, out);
4289        }
4290    }
4291}
4292
4293fn continuation_tins(
4294    context: &Context,
4295    rule: &Rule,
4296    stack: &[Rule],
4297    rules: &IndexMap<String, Arc<RuleSpec>>,
4298    options: &Options,
4299    query_pos: usize,
4300    failed: Option<&[Tin]>,
4301) -> Vec<Tin> {
4302    let Some(spec) = rules.get(&*rule.name) else {
4303        return Vec::new();
4304    };
4305    let state_alts = if rule.state == RuleState::Open {
4306        &spec.open
4307    } else {
4308        &spec.close
4309    };
4310    let mut out = BTreeSet::new();
4311
4312    if let Some(failed) = failed.filter(|tins| !tins.is_empty()) {
4313        out.extend(failed.iter().copied());
4314    } else {
4315        for alt in state_alts {
4316            if !groups_enabled(alt, options) {
4317                continue;
4318            }
4319            let depth = alt_match_depth(alt, context);
4320            if depth == query_pos {
4321                if let Some(slot) = alt.s.get(depth) {
4322                    out.extend(completion_tins(slot));
4323                }
4324            }
4325        }
4326    }
4327
4328    // If the current rule can close without consuming a token, closing
4329    // tokens accepted by each parent are legal at the same point too.
4330    let mut close_rule = rule;
4331    let mut parent_index = stack.len();
4332    while let Some(close_spec) = rules.get(&*close_rule.name) {
4333        if !has_empty_close(close_spec, options) || parent_index == 0 {
4334            break;
4335        }
4336        parent_index -= 1;
4337        let parent = &stack[parent_index];
4338        if let Some(parent_spec) = rules.get(&*parent.name) {
4339            lead_tins(&parent_spec.close, options, &mut out);
4340        }
4341        close_rule = parent;
4342    }
4343
4344    // A fully matched alternate can immediately hand control to a pushed or
4345    // replacement rule. Follow empty opening hand-offs transitively.
4346    let mut opened = BTreeSet::new();
4347    for alt in state_alts {
4348        if !groups_enabled(alt, options) || alt_match_depth(alt, context) != alt.s.len() {
4349            continue;
4350        }
4351        // A callback backtrack is only knowable while executing the match.
4352        // Do not speculate that its static default is the handover point.
4353        if alt.b_fn.is_some() {
4354            continue;
4355        }
4356        if alt.s.len().checked_sub(alt.b) != Some(query_pos) {
4357            continue;
4358        }
4359        if let Some(push) = alt.p.as_deref() {
4360            add_openers(push, rules, options, &mut opened, &mut out);
4361        }
4362        if let Some(replace) = alt.r.as_deref() {
4363            add_openers(replace, rules, options, &mut opened, &mut out);
4364        }
4365    }
4366
4367    out.into_iter().collect()
4368}
4369
4370/// The group tags a comma-separated group list declares.
4371///
4372/// One definition, because two places ask: the include/exclude filter in
4373/// `groups_enabled`, and the list the engine publishes into `matched.g`.
4374/// They have to agree on what a tag is -- trimmed, and never empty.
4375fn listed(list: &str) -> impl Iterator<Item = &str> {
4376    list.split(',')
4377        .map(str::trim)
4378        .filter(|entry| !entry.is_empty())
4379}
4380
4381pub(crate) fn groups_enabled(alt: &AltSpec, options: &Options) -> bool {
4382    // With neither an include nor an exclude list there is nothing to
4383    // test against, so every alternate is enabled whatever groups it
4384    // declares. That is the usual case, and it is asked once per
4385    // alternate per iteration.
4386    let include = options.rule.include.as_str();
4387    let exclude = options.rule.exclude.as_str();
4388    if include.is_empty() && exclude.is_empty() {
4389        return true;
4390    }
4391    // Iterators rather than three collected `Vec<&str>`. The question is
4392    // the same one and the answer is the same answer; the three heap
4393    // allocations per call were not part of either. The shipped JSON
4394    // preset sets `rule.include` to "json", so the early return above
4395    // never fires for it and every alternate of every rule step paid
4396    // them.
4397    let declares = |wanted: &str| listed(&alt.g).any(|group| group == wanted);
4398    let included = listed(include).next().is_none() || listed(include).any(&declares);
4399    included && !listed(exclude).any(&declares)
4400}
4401
4402fn builtin_condition_matches(reference: Option<&str>, rule: &Rule) -> bool {
4403    let phase = match rule.k.get("pd_phase") {
4404        Some(Value::Number(value)) => *value as i32,
4405        _ => 0,
4406    };
4407    match reference {
4408        None => true,
4409        Some("@probePhase0$") => phase == 0,
4410        Some("@probePhase1$") => phase == 1,
4411        Some("@probePhase2$") => phase == 2,
4412        Some(_) => false,
4413    }
4414}
4415
4416fn conditions_match(conditions: &[Condition], rule: &Rule, ancestors: &[Rule]) -> bool {
4417    conditions.iter().all(|condition| {
4418        let resolved = resolve_condition_path(rule, ancestors, &condition.path);
4419        if condition.op == CompareOp::Exist {
4420            let exists = condition_exists(rule, ancestors, &condition.path);
4421            let wanted = matches!(condition.value, Value::Bool(true));
4422            return exists == wanted;
4423        }
4424        let Some(actual) = resolved else {
4425            return !matches!(condition.op, CompareOp::Eq);
4426        };
4427        match condition.op {
4428            CompareOp::Eq => actual.deep_equal(&condition.value),
4429            CompareOp::Ne => !actual.deep_equal(&condition.value),
4430            CompareOp::Lt => ordered(&actual, &condition.value).is_none_or(|value| value < 0),
4431            CompareOp::Lte => ordered(&actual, &condition.value).is_none_or(|value| value <= 0),
4432            CompareOp::Gt => ordered(&actual, &condition.value).is_none_or(|value| value > 0),
4433            CompareOp::Gte => ordered(&actual, &condition.value).is_none_or(|value| value >= 0),
4434            CompareOp::Exist => unreachable!("handled above"),
4435        }
4436    })
4437}
4438
4439fn ordered(left: &Value, right: &Value) -> Option<i8> {
4440    match (left, right) {
4441        (Value::Number(left), Value::Number(right)) => Some(if left < right {
4442            -1
4443        } else if left > right {
4444            1
4445        } else {
4446            0
4447        }),
4448        (Value::String(left), Value::String(right)) => Some(match left.cmp(right) {
4449            std::cmp::Ordering::Less => -1,
4450            std::cmp::Ordering::Equal => 0,
4451            std::cmp::Ordering::Greater => 1,
4452        }),
4453        _ => None,
4454    }
4455}
4456
4457fn condition_exists(rule: &Rule, ancestors: &[Rule], path: &[String]) -> bool {
4458    if path.first().map(String::as_str) == Some("n") && path.len() == 2 {
4459        rule.n.contains_key(&path[1])
4460    } else if path.first().map(String::as_str) == Some("parent") {
4461        ancestors
4462            .split_last()
4463            .is_some_and(|(parent, parent_ancestors)| {
4464                condition_exists(parent, parent_ancestors, &path[1..])
4465            })
4466    } else if path.first().map(String::as_str) == Some("child") {
4467        rule.child_rule
4468            .as_deref()
4469            .is_some_and(|child| snapshot_condition_exists(child, &path[1..]))
4470    } else if path.first().map(String::as_str) == Some("prev") {
4471        rule.prev_rule
4472            .as_deref()
4473            .is_some_and(|prev| snapshot_condition_exists(prev, &path[1..]))
4474    } else if path.first().map(String::as_str) == Some("next") {
4475        if let Some(next) = rule.next_rule.as_deref() {
4476            snapshot_condition_exists(next, &path[1..])
4477        } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4478            condition_exists(rule, ancestors, &path[1..])
4479        } else {
4480            false
4481        }
4482    } else {
4483        resolve_condition_path(rule, ancestors, path).is_some()
4484    }
4485}
4486
4487fn resolve_condition_path(rule: &Rule, ancestors: &[Rule], path: &[String]) -> Option<Value> {
4488    let root = path.first()?.as_str();
4489    let rest = &path[1..];
4490    match root {
4491        "n" if rest.len() == 1 => Some(Value::Number(*rule.n.get(&rest[0]).unwrap_or(&0) as f64)),
4492        "u" => map_path(&rule.u, rest),
4493        "k" => map_path(&rule.k, rest),
4494        "d" if rest.is_empty() => Some(Value::Number(rule.d as f64)),
4495        "i" if rest.is_empty() => Some(Value::Number(rule.i as f64)),
4496        "name" if rest.is_empty() => Some(Value::String(rule.name.to_string())),
4497        "state" if rest.is_empty() => Some(Value::String(
4498            match rule.state {
4499                RuleState::Open => "o",
4500                RuleState::Close => "c",
4501            }
4502            .into(),
4503        )),
4504        "node" => value_path(rule.node.borrow().clone(), rest),
4505        "need" if rest.is_empty() => Some(Value::Number(rule.need as f64)),
4506        "oN" if rest.is_empty() => Some(Value::Number(rule.o.len() as f64)),
4507        "cN" if rest.is_empty() => Some(Value::Number(rule.c.len() as f64)),
4508        "o" => token_list_path(&rule.o, rest),
4509        "c" => token_list_path(&rule.c, rest),
4510        "o0" => token_path(rule.o.first(), rest),
4511        "o1" => token_path(rule.o.get(1), rest),
4512        "c0" => token_path(rule.c.first(), rest),
4513        "c1" => token_path(rule.c.get(1), rest),
4514        "parent" => {
4515            let (parent, parent_ancestors) = ancestors.split_last()?;
4516            resolve_condition_path(parent, parent_ancestors, rest)
4517        }
4518        "child" => resolve_snapshot_path(rule.child_rule.as_deref()?, rest),
4519        "prev" => resolve_snapshot_path(rule.prev_rule.as_deref()?, rest),
4520        "next" => {
4521            if let Some(next) = rule.next_rule.as_deref() {
4522                resolve_snapshot_path(next, rest)
4523            } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4524                resolve_condition_path(rule, ancestors, rest)
4525            } else {
4526                None
4527            }
4528        }
4529        "spec" if rest == ["name"] => Some(Value::String(rule.name.to_string())),
4530        _ => None,
4531    }
4532}
4533
4534/// Which link a bounded snapshot becomes (see [`bounded_history`]).
4535#[derive(Clone, Copy, PartialEq, Eq)]
4536enum Link {
4537    /// The `parent_rule` a pushed child keeps: the pusher once it has
4538    /// linked the child, made at the end of the push arm.
4539    Parent,
4540    /// The pusher before it links the child, made at the start of the
4541    /// push arm. It survives as the `parent_rule` of the child's snapshot
4542    /// taken at the push: under a bound the one the pusher links as
4543    /// `child`, and with none the one the child reads as
4544    /// `parent.child.parent.child`, since the push arm then links the
4545    /// child again once the pusher has linked it, and gives the child the
4546    /// pusher as it then stands (see [`Rule::relink_child`]). That second
4547    /// link is made after the pushing alternate's after-actions have run,
4548    /// where TypeScript and Go link the live rules before them: a state
4549    /// action on the pusher's close still reads the child pushed before,
4550    /// and six hops from the child still reach this record.
4551    PusherBefore,
4552    /// A replacement's `prev_rule`: the rule it replaces.
4553    Prev,
4554}
4555
4556/// A snapshot to link, bounded by `options.rule.history`
4557/// (`doc/rule-history-bound.md`): a copy that keeps `history - 1`
4558/// predecessors, each a copy the same way, with no `child` or `next`
4559/// links. Those links are what defeat a cut of the predecessors alone:
4560/// a rule's `child` is its finished child, whose `next` leads back to
4561/// the rule's own record, whose `prev` is a copy of its predecessor,
4562/// whose `child` does the same, a ladder through the whole sequence. So
4563/// `prev.child` and `prev.next` resolve to nothing, and so does a
4564/// predecessor's past them. A cut `next` takes its name with it: a
4565/// snapshot whose next has its own name reads itself as `next`, and a
4566/// copy that kept the name would read `prev.next` as `prev`.
4567///
4568/// The `parent` a pushed child keeps ([`Link::Parent`]) keeps the
4569/// pusher's own `child` and `next`, the child itself as it stood when
4570/// pushed, before it had a `next`: no ladder starts there, and
4571/// `parent.child` and `parent.next` read as they do unbounded. The copy
4572/// made before the pusher links the child ([`Link::PusherBefore`]) cuts
4573/// them: its `child` is the pusher's previous child, and a rule that
4574/// pushes again from its close phase would link every child it pushed,
4575/// each through the one before. So `parent.child.parent.child` and the
4576/// like, the pusher as it stood before the push, resolve to nothing
4577/// under a bound, as they do in TypeScript and Go. With no bound the
4578/// push arm links the child again (see [`Rule::relink_child`]), and
4579/// that path reads the child, as the live links of the other two
4580/// runtimes do.
4581///
4582/// What a rule reads through `prev` (counters, values, tokens, node and
4583/// name) and through `parent` (the pusher and its own parents) is kept.
4584/// A copy is a twenty-field struct with eight `Rc` clones, `history` of
4585/// them per link, and `history` is read as 1 to
4586/// [`crate::options::MAX_RULE_HISTORY`], so a link costs a constant.
4587/// `None` links the snapshot untouched.
4588fn bounded_history(
4589    snapshot: Rc<RuleSnapshot>,
4590    history: Option<usize>,
4591    link: Link,
4592) -> Rc<RuleSnapshot> {
4593    let Some(history) = crate::options::effective_rule_history(history) else {
4594        return snapshot;
4595    };
4596    // The links to copy, nearest first: the snapshot and up to
4597    // `history - 1` of its predecessors. Collected and then rebuilt from
4598    // the far end, with no recursion, so that a bound as long as the
4599    // chain costs stack nothing, as `RuleSnapshot`'s `Drop` walks the
4600    // same chain without it.
4601    let mut links: Vec<&Rc<RuleSnapshot>> = Vec::with_capacity(history);
4602    let mut current = Some(&snapshot);
4603    while let Some(snapshot) = current {
4604        if links.len() == history {
4605            break;
4606        }
4607        links.push(snapshot);
4608        current = snapshot.prev_rule.as_ref();
4609    }
4610    let mut prev: Option<Rc<RuleSnapshot>> = None;
4611    // `depth` counts back from the snapshot itself, which is 0.
4612    for (depth, original) in links.into_iter().enumerate().rev() {
4613        let mut copy = (**original).clone();
4614        if depth != 0 || link != Link::Parent {
4615            copy.child_rule = None;
4616            copy.next_rule = None;
4617            copy.next_rule_name = None;
4618        }
4619        copy.prev_rule = prev.take();
4620        prev = Some(Rc::new(copy));
4621    }
4622    prev.expect("at least the snapshot itself is copied")
4623}
4624
4625fn snapshot_condition_exists(rule: &RuleSnapshot, path: &[String]) -> bool {
4626    if path.first().map(String::as_str) == Some("n") && path.len() == 2 {
4627        rule.n.contains_key(&path[1])
4628    } else if path.first().map(String::as_str) == Some("parent") {
4629        rule.parent_rule
4630            .as_deref()
4631            .is_some_and(|parent| snapshot_condition_exists(parent, &path[1..]))
4632    } else if path.first().map(String::as_str) == Some("child") {
4633        rule.child_rule
4634            .as_deref()
4635            .is_some_and(|child| snapshot_condition_exists(child, &path[1..]))
4636    } else if path.first().map(String::as_str) == Some("prev") {
4637        rule.prev_rule
4638            .as_deref()
4639            .is_some_and(|prev| snapshot_condition_exists(prev, &path[1..]))
4640    } else if path.first().map(String::as_str) == Some("next") {
4641        if let Some(next) = rule.next_rule.as_deref() {
4642            snapshot_condition_exists(next, &path[1..])
4643        } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4644            snapshot_condition_exists(rule, &path[1..])
4645        } else {
4646            false
4647        }
4648    } else {
4649        resolve_snapshot_path(rule, path).is_some()
4650    }
4651}
4652
4653fn resolve_snapshot_path(rule: &RuleSnapshot, path: &[String]) -> Option<Value> {
4654    let root = path.first()?.as_str();
4655    let rest = &path[1..];
4656    match root {
4657        "n" if rest.len() == 1 => Some(Value::Number(*rule.n.get(&rest[0]).unwrap_or(&0) as f64)),
4658        "u" => map_path(&rule.u, rest),
4659        "k" => map_path(&rule.k, rest),
4660        "d" if rest.is_empty() => Some(Value::Number(rule.d as f64)),
4661        "i" if rest.is_empty() => Some(Value::Number(rule.i as f64)),
4662        "name" if rest.is_empty() => Some(Value::String(rule.name.to_string())),
4663        "state" if rest.is_empty() => Some(Value::String(
4664            match rule.state {
4665                RuleState::Open => "o",
4666                RuleState::Close => "c",
4667            }
4668            .into(),
4669        )),
4670        "node" => value_path(rule.node.borrow().clone(), rest),
4671        "need" if rest.is_empty() => Some(Value::Number(rule.need as f64)),
4672        "oN" if rest.is_empty() => Some(Value::Number(rule.o.len() as f64)),
4673        "cN" if rest.is_empty() => Some(Value::Number(rule.c.len() as f64)),
4674        "o" => token_list_path(&rule.o, rest),
4675        "c" => token_list_path(&rule.c, rest),
4676        "o0" => token_path(rule.o.first(), rest),
4677        "o1" => token_path(rule.o.get(1), rest),
4678        "c0" => token_path(rule.c.first(), rest),
4679        "c1" => token_path(rule.c.get(1), rest),
4680        "parent" => resolve_snapshot_path(rule.parent_rule.as_deref()?, rest),
4681        "child" => resolve_snapshot_path(rule.child_rule.as_deref()?, rest),
4682        "prev" => resolve_snapshot_path(rule.prev_rule.as_deref()?, rest),
4683        "next" => {
4684            if let Some(next) = rule.next_rule.as_deref() {
4685                resolve_snapshot_path(next, rest)
4686            } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4687                resolve_snapshot_path(rule, rest)
4688            } else {
4689                None
4690            }
4691        }
4692        "spec" if rest == ["name"] => Some(Value::String(rule.name.to_string())),
4693        _ => None,
4694    }
4695}
4696
4697fn map_path(map: &HashMap<String, Value>, path: &[String]) -> Option<Value> {
4698    let (name, rest) = path.split_first()?;
4699    value_path(map.get(name)?.clone(), rest)
4700}
4701
4702fn value_path(mut value: Value, path: &[String]) -> Option<Value> {
4703    for part in path {
4704        value = match value {
4705            Value::Object(map) => map.get(part)?.clone(),
4706            Value::Array(items) => items.get(part.parse::<usize>().ok()?)?.clone(),
4707            _ => return None,
4708        };
4709    }
4710    Some(value)
4711}
4712
4713fn token_list_path(tokens: &[Token], path: &[String]) -> Option<Value> {
4714    let (index, rest) = path.split_first()?;
4715    token_path(tokens.get(index.parse::<usize>().ok()?), rest)
4716}
4717
4718fn token_path(token: Option<&Token>, path: &[String]) -> Option<Value> {
4719    let token = token?;
4720    if path.is_empty() {
4721        let mut value = IndexMap::new();
4722        value.insert("tin".into(), Value::Number(token.tin as f64));
4723        value.insert("name".into(), Value::String(token.name.to_string()));
4724        value.insert("src".into(), Value::String(token.src.to_string()));
4725        value.insert("val".into(), token.val.clone());
4726        value.insert("why".into(), Value::String(token.why.to_string()));
4727        return Some(Value::object(value));
4728    }
4729    let (field, rest) = path.split_first()?;
4730    let value = match field.as_str() {
4731        "tin" => Value::Number(token.tin as f64),
4732        "name" => Value::String(token.name.to_string()),
4733        "src" => Value::String(token.src.to_string()),
4734        "val" => token.val.clone(),
4735        "why" => Value::String(token.why.to_string()),
4736        _ => return None,
4737    };
4738    value_path(value, rest)
4739}
4740
4741#[cfg(test)]
4742mod tests {
4743    use super::*;
4744
4745    /// `expected_tins`, `names` and `prepared` are derived from `rules` and
4746    /// positional in it, and `add_rule` is the only thing that writes any
4747    /// of the four. That is the whole reason `rules` is private: while it was
4748    /// public, an embedder inserting or replacing a rule straight into it
4749    /// left the derived tables describing the rule that used to be there,
4750    /// and lookahead went on gating the custom matchers on that rule's token
4751    /// identities. This asserts the invariant a second write path would
4752    /// break; making `add_rule` keep an existing entry instead of replacing
4753    /// it fails the second assertion.
4754    #[test]
4755    fn replacing_a_rule_replaces_the_tables_derived_from_it() {
4756        let mut parser = Parser::new(crate::Options::default());
4757
4758        let mut first = RuleSpec::new("val");
4759        first.bo.push("@enter".into());
4760        first.open.push(AltSpec {
4761            s: vec![vec![crate::TIN_NR]],
4762            a: vec!["@act".into()],
4763            ..Default::default()
4764        });
4765        parser.add_rule(first);
4766        let slot = parser
4767            .rules()
4768            .get_index_of("val")
4769            .expect("the rule was just installed");
4770        assert_eq!(parser.expected_tins[slot].at(true, 0), [crate::TIN_NR]);
4771        assert_eq!(&*parser.names[slot], "val");
4772        assert_eq!(parser.prepared[slot].before(true).len(), 1);
4773        assert_eq!(parser.prepared[slot].open[0].actions.len(), 1);
4774
4775        let mut second = RuleSpec::new("val");
4776        second.open.push(AltSpec {
4777            s: vec![vec![crate::TIN_ST]],
4778            ..Default::default()
4779        });
4780        parser.add_rule(second);
4781
4782        assert_eq!(parser.rules().len(), 1, "a replacement, not an addition");
4783        assert_eq!(
4784            parser.expected_tins[slot].at(true, 0),
4785            [crate::TIN_ST],
4786            "lookahead would still expect the replaced rule's tokens"
4787        );
4788        // The name table is positional now, so a replacement has to land on
4789        // the index the map kept for the key rather than append beside it:
4790        // an appended handle would leave `names` describing the wrong rule
4791        // at every index past this one.
4792        assert_eq!(parser.names.len(), 1, "one rule, one shared name");
4793        assert_eq!(parser.rules().get_index_of("val"), Some(slot));
4794        assert_eq!(&*parser.names[slot], "val");
4795        // The prepared table is positional for the same reason, and its
4796        // record has to describe the rule that is installed now: the parse
4797        // loop trusts a record only while its spec is the one the rule in
4798        // hand holds, so a record left pointing at the replaced spec is a
4799        // record the loop would stop using at all.
4800        assert_eq!(parser.prepared.len(), 1);
4801        assert_eq!(&*parser.prepared[slot].name, "val");
4802        assert!(Arc::ptr_eq(
4803            &parser.prepared[slot].spec,
4804            &parser.rules()["val"]
4805        ));
4806        // The action orders are derived from the same spec and go stale the
4807        // same way. The replacement declares neither the lifecycle action
4808        // nor the alternate action the first rule did, and an order left
4809        // over from that rule is one the loop would run for it.
4810        assert!(parser.prepared[slot].before(true).is_empty());
4811        assert!(parser.prepared[slot].open[0].actions.is_empty());
4812        assert!(!parser.prepared[slot].open[0].named);
4813    }
4814
4815    /// The accepted-token table is positional now, and the slot a rule
4816    /// carries is a hint rather than an authority: `name` is public and a
4817    /// callback may have written it between one token fetch and the next.
4818    /// What the rule is called is what decides which row answers, exactly
4819    /// as the name-keyed map this replaced decided it, and a name that is
4820    /// installed nowhere expects nothing rather than whatever happens to
4821    /// sit at its slot.
4822    #[test]
4823    fn expected_match_tins_follows_the_rule_name_when_the_slot_goes_stale() {
4824        fn rule_named(name: &str, tin: Tin) -> RuleSpec {
4825            let mut spec = RuleSpec::new(name);
4826            spec.open.push(AltSpec {
4827                s: vec![vec![tin]],
4828                ..Default::default()
4829            });
4830            spec
4831        }
4832
4833        let mut options = crate::Options::default();
4834        let tin = options.register_token("#QQ");
4835        options.match_tokens.insert(
4836            "#QQ".into(),
4837            crate::options::MatchToken {
4838                name: "#QQ".into(),
4839                tin,
4840                matcher: crate::options::MatchTokenMatcher::Regex(regex::Regex::new("^q").unwrap()),
4841                eager: false,
4842            },
4843        );
4844        let mut parser = Parser::new(options);
4845        parser.add_rule(rule_named("val", crate::TIN_NR));
4846        parser.add_rule(rule_named("other", crate::TIN_ST));
4847
4848        let val_slot = parser.rules().get_index_of("val").expect("installed");
4849        let other_slot = parser.rules().get_index_of("other").expect("installed");
4850        assert_ne!(val_slot, other_slot);
4851
4852        // Bound the way the parse loop binds it: slot, name and spec all
4853        // describe the same installed rule.
4854        let mut rule = Rule::new("val", Value::Undefined);
4855        rule.bind_spec(
4856            &parser.rules()["val"],
4857            parser.names[val_slot].clone(),
4858            val_slot,
4859        );
4860        assert_eq!(&*parser.expected_match_tins(&rule, 0), [crate::TIN_NR]);
4861
4862        // A callback renames the rule to another installed rule. The slot
4863        // still points at `val`, so the slot alone would answer with
4864        // `val`'s row; the name is what makes it `other`'s, which is what
4865        // the lookup by name always gave.
4866        rule.name = parser.names[other_slot].clone();
4867        assert_eq!(
4868            &*parser.expected_match_tins(&rule, 0),
4869            [crate::TIN_ST],
4870            "the rule is called `other` now, so `other`'s row answers"
4871        );
4872
4873        // A callback swaps the spec and leaves the name. Nothing about
4874        // which row answers depends on the spec, because the row is
4875        // derived from the name the rule was installed under.
4876        rule.name = parser.names[val_slot].clone();
4877        rule.spec = Arc::clone(&parser.rules()["other"]);
4878        assert_eq!(
4879            &*parser.expected_match_tins(&rule, 0),
4880            [crate::TIN_NR],
4881            "still called `val`, so still gated by `val`'s row"
4882        );
4883
4884        // A name installed nowhere expects nothing. Its slot is
4885        // `usize::MAX`, so nothing is in range to answer by accident.
4886        let ghost = Rule::new("ghost", Value::Undefined);
4887        assert_eq!(
4888            &*parser.expected_match_tins(&ghost, 0),
4889            &[] as &[Tin],
4890            "an uninstalled name has no row, not another rule's"
4891        );
4892    }
4893
4894    /// `expected_match_tins` exists to gate the custom matchers, so with no
4895    /// custom matcher registered it answers "nothing" without consulting
4896    /// the table -- the table is still built and still says what it said,
4897    /// and the moment a match token appears the same rule at the same slot
4898    /// gets the table's row again. The first assertion is what pins the
4899    /// short-circuit: were it dropped, the empty-matcher parser would
4900    /// return `[TIN_NR]` and the assertion would fail.
4901    #[test]
4902    fn expected_match_tins_is_empty_until_a_match_token_exists() {
4903        fn val_rule() -> RuleSpec {
4904            let mut spec = RuleSpec::new("val");
4905            spec.open.push(AltSpec {
4906                s: vec![vec![crate::TIN_NR]],
4907                ..Default::default()
4908            });
4909            spec
4910        }
4911        let rule = Rule::new("val", Value::Undefined);
4912
4913        let mut without = Parser::new(crate::Options::default());
4914        without.add_rule(val_rule());
4915        assert!(without.options.match_tokens.is_empty());
4916        assert_eq!(without.expected_tins[0].at(true, 0), [crate::TIN_NR]);
4917        assert_eq!(
4918            &*without.expected_match_tins(&rule, 0),
4919            &[] as &[Tin],
4920            "no custom matcher: nothing to gate, so nothing to look up"
4921        );
4922
4923        let mut options = crate::Options::default();
4924        let tin = options.register_token("#QQ");
4925        options.match_tokens.insert(
4926            "#QQ".into(),
4927            crate::options::MatchToken {
4928                name: "#QQ".into(),
4929                tin,
4930                matcher: crate::options::MatchTokenMatcher::Regex(regex::Regex::new("^q").unwrap()),
4931                eager: false,
4932            },
4933        );
4934        let mut with = Parser::new(options);
4935        with.add_rule(val_rule());
4936        assert_eq!(
4937            &*with.expected_match_tins(&rule, 0),
4938            [crate::TIN_NR],
4939            "a custom matcher is present, so the slot's tins gate it"
4940        );
4941        assert_eq!(
4942            &*with.expected_match_tins(&rule, 1),
4943            &[] as &[Tin],
4944            "a slot the rule never fills expects nothing"
4945        );
4946    }
4947}