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            bound_child_link(&mut parent, self.options.rule.history);
1415            if accepts_close(&parent, candidate.tin, &self.rules, &self.options) {
1416                *current_rule = parent;
1417                return Ok(true);
1418            }
1419            let probe = context.probe_abandon(&parent);
1420            self.notify_forced_close(&parent, context, probe, &src, stack)?;
1421            *current_rule = parent;
1422        }
1423        Ok(false)
1424    }
1425
1426    #[allow(clippy::too_many_arguments)]
1427    fn recover_error_pass(
1428        &self,
1429        error: TabnasError,
1430        state: RuleState,
1431        mut alt: Option<RuleDoneAlt>,
1432        fallback_error_token: bool,
1433        src: &str,
1434        current_rule: &mut Rule,
1435        stack: &mut Vec<Rule>,
1436        context: &mut Context,
1437        lexer: &mut Lexer,
1438        mode: &mut ParseMode<'_>,
1439    ) -> Result<(), TabnasError> {
1440        // TypeScript's RuleSpec.bad performs recovery inside the rule pass;
1441        // the ordinary ruleDone event is dispatched only after that pass
1442        // returns. Preserve that ordering so any synthesized forced-close
1443        // events precede this final attempted-pass event.
1444        let event_rule = current_rule.clone();
1445        // The failing pass is the probe's if one is open where it failed,
1446        // even when the recovery below closes it before the pass is
1447        // reported.
1448        let probe_at_error = 0 < context.probe_depth();
1449        let recovered = mode.recovering
1450            && self.attempt_recover(error.clone(), current_rule, stack, context, lexer, mode)?;
1451        if !recovered && fallback_error_token {
1452            if let Some(alt) = alt.as_mut().filter(|alt| alt.err.is_none()) {
1453                let tin = self.options.token(&error.token.name).unwrap_or(TIN_BD);
1454                let mut token = Token::new(
1455                    error.token.name.clone(),
1456                    tin,
1457                    Value::Undefined,
1458                    error.token.src.clone(),
1459                    crate::Point {
1460                        len: error.len,
1461                        site: crate::Site {
1462                            si: error.pos,
1463                            pos: error.pos,
1464                            ri: error.row,
1465                            ci: error.col,
1466                        },
1467                    },
1468                );
1469                token.bad(&error.code);
1470                alt.err = Some(token);
1471            }
1472        }
1473        let probe = context.probe_take() || probe_at_error;
1474        self.notify_rule_done(&event_rule, context, state, alt, probe, src, stack)?;
1475        if recovered {
1476            Ok(())
1477        } else {
1478            // TypeScript's `RuleSpec.bad` gives up by rethrowing the last
1479            // error it recorded, which `attempt_recover` has just recorded
1480            // or dropped as a cascade, so the list is already complete. Only
1481            // an empty list makes it raise, and record, a fresh one.
1482            if mode.recovering && !mode.errors.is_empty() {
1483                mode.gave_up = true;
1484            }
1485            Err(error)
1486        }
1487    }
1488
1489    #[allow(clippy::too_many_arguments)]
1490    fn recover_after_actions(
1491        &self,
1492        result: Result<(), TabnasError>,
1493        state: RuleState,
1494        alt: Option<RuleDoneAlt>,
1495        src: &str,
1496        current_rule: &mut Rule,
1497        stack: &mut Vec<Rule>,
1498        context: &mut Context,
1499        lexer: &mut Lexer,
1500        mode: &mut ParseMode<'_>,
1501    ) -> Result<bool, TabnasError> {
1502        let Err(error) = result else {
1503            return Ok(false);
1504        };
1505        self.recover_error_pass(
1506            error,
1507            state,
1508            alt,
1509            true,
1510            src,
1511            current_rule,
1512            stack,
1513            context,
1514            lexer,
1515            mode,
1516        )?;
1517        Ok(true)
1518    }
1519
1520    pub fn parse(&self, src: &str) -> Result<Value, TabnasError> {
1521        self.parse_with_meta(src, Value::Undefined)
1522    }
1523
1524    pub fn parse_with_meta(&self, src: &str, meta: Value) -> Result<Value, TabnasError> {
1525        self.parse_with_owner(src, meta, None, None)
1526    }
1527
1528    pub(crate) fn parse_for(
1529        &self,
1530        owner: &crate::Tabnas,
1531        src: &str,
1532        meta: Value,
1533    ) -> Result<Value, TabnasError> {
1534        self.parse_with_owner(src, meta, Some(owner), None)
1535    }
1536
1537    pub(crate) fn parse_for_with_context(
1538        &self,
1539        owner: &crate::Tabnas,
1540        src: &str,
1541        meta: Value,
1542        parent: &ContextSeed,
1543    ) -> Result<Value, TabnasError> {
1544        self.parse_with_owner(src, meta, Some(owner), Some(parent))
1545    }
1546
1547    fn parse_with_owner(
1548        &self,
1549        src: &str,
1550        meta: Value,
1551        owner: Option<&crate::Tabnas>,
1552        parent: Option<&ContextSeed>,
1553    ) -> Result<Value, TabnasError> {
1554        match catch_unwind(AssertUnwindSafe(|| {
1555            self.parse_uncaught(src, meta, owner, parent)
1556        })) {
1557            Ok(result) => result,
1558            Err(payload) => {
1559                let mut error =
1560                    TabnasError::from_panic(payload, "Parser::parse", src, 0, 1, 1, &self.options);
1561                self.decorate_error(&mut error);
1562                Err(error)
1563            }
1564        }
1565    }
1566
1567    fn parse_uncaught(
1568        &self,
1569        src: &str,
1570        meta: Value,
1571        owner: Option<&crate::Tabnas>,
1572        parent: Option<&ContextSeed>,
1573    ) -> Result<Value, TabnasError> {
1574        if let Some(result) = self.run_parser_start(src, &meta, owner, parent) {
1575            return result.map_err(|mut error| {
1576                self.decorate_error(&mut error);
1577                error
1578            });
1579        }
1580        let mut errors = Vec::new();
1581        let recovering = self.options.parse.recover.enabled;
1582        let mut mode = ParseMode {
1583            continuation: None,
1584            recovering,
1585            errors: &mut errors,
1586            partial: None,
1587            gave_up: false,
1588        };
1589        let result = self
1590            .parse_inner(src, meta, owner, parent, &mut mode)
1591            .map_err(|mut error| {
1592                self.decorate_error(&mut error);
1593                error
1594            });
1595        match result {
1596            Err(_) if recovering => Ok(mode
1597                .partial
1598                .and_then(PartialValue::into_value)
1599                .unwrap_or(Value::Undefined)),
1600            other => other,
1601        }
1602    }
1603
1604    pub fn parse_recover(&self, src: &str) -> ParseRecovery {
1605        self.parse_recover_with_meta(src, Value::Undefined)
1606    }
1607
1608    pub fn parse_recover_with_meta(&self, src: &str, meta: Value) -> ParseRecovery {
1609        self.parse_recover_with_owner(src, meta, None, None)
1610    }
1611
1612    pub(crate) fn parse_recover_for(
1613        &self,
1614        owner: &crate::Tabnas,
1615        src: &str,
1616        meta: Value,
1617    ) -> ParseRecovery {
1618        self.parse_recover_with_owner(src, meta, Some(owner), None)
1619    }
1620
1621    pub(crate) fn parse_recover_for_with_context(
1622        &self,
1623        owner: &crate::Tabnas,
1624        src: &str,
1625        meta: Value,
1626        parent: &ContextSeed,
1627    ) -> ParseRecovery {
1628        self.parse_recover_with_owner(src, meta, Some(owner), Some(parent))
1629    }
1630
1631    fn parse_recover_with_owner(
1632        &self,
1633        src: &str,
1634        meta: Value,
1635        owner: Option<&crate::Tabnas>,
1636        parent: Option<&ContextSeed>,
1637    ) -> ParseRecovery {
1638        match catch_unwind(AssertUnwindSafe(|| {
1639            self.parse_recover_uncaught(src, meta, owner, parent)
1640        })) {
1641            Ok(result) => result,
1642            Err(payload) => {
1643                let mut error = TabnasError::from_panic(
1644                    payload,
1645                    "Parser::parse_recover",
1646                    src,
1647                    0,
1648                    1,
1649                    1,
1650                    &self.options,
1651                );
1652                self.decorate_error(&mut error);
1653                ParseRecovery {
1654                    value: None,
1655                    errors: Vec::new(),
1656                    fatal: Some(error),
1657                }
1658            }
1659        }
1660    }
1661
1662    fn parse_recover_uncaught(
1663        &self,
1664        src: &str,
1665        meta: Value,
1666        owner: Option<&crate::Tabnas>,
1667        parent: Option<&ContextSeed>,
1668    ) -> ParseRecovery {
1669        if let Some(result) = self.run_parser_start(src, &meta, owner, parent) {
1670            return match result {
1671                Ok(value) => ParseRecovery {
1672                    value: Some(value),
1673                    errors: Vec::new(),
1674                    fatal: None,
1675                },
1676                Err(mut error) => {
1677                    self.decorate_error(&mut error);
1678                    ParseRecovery {
1679                        value: None,
1680                        errors: Vec::new(),
1681                        fatal: Some(error),
1682                    }
1683                }
1684            };
1685        }
1686        let mut errors = Vec::new();
1687        let recovering = self.options.parse.recover.enabled;
1688        let (result, partial, gave_up) = {
1689            let mut mode = ParseMode {
1690                continuation: None,
1691                recovering,
1692                errors: &mut errors,
1693                partial: None,
1694                gave_up: false,
1695            };
1696            let result = self
1697                .parse_inner(src, meta, owner, parent, &mut mode)
1698                .map_err(|mut error| {
1699                    self.decorate_error(&mut error);
1700                    error
1701                });
1702            (
1703                result,
1704                mode.partial.and_then(PartialValue::into_value),
1705                mode.gave_up,
1706            )
1707        };
1708        for error in &mut errors {
1709            self.decorate_error(error);
1710        }
1711        match result {
1712            Ok(value) => ParseRecovery {
1713                value: Some(value),
1714                errors,
1715                fatal: None,
1716            },
1717            Err(error) => {
1718                // The error that ended the parse is listed once, where the
1719                // parse ended, as TypeScript's constructor lists it, unless
1720                // recovery gave up on an error it had already accounted for.
1721                if !gave_up {
1722                    errors.push(error.clone());
1723                }
1724                ParseRecovery {
1725                    value: recovering.then_some(partial).flatten(),
1726                    errors,
1727                    fatal: (!recovering).then_some(error),
1728                }
1729            }
1730        }
1731    }
1732
1733    fn run_parser_start(
1734        &self,
1735        src: &str,
1736        meta: &Value,
1737        owner: Option<&crate::Tabnas>,
1738        parent: Option<&ContextSeed>,
1739    ) -> Option<Result<Value, TabnasError>> {
1740        let result = if let Some(start) = self.options.parser.start_with_context.as_ref() {
1741            let Some(owner) = owner else {
1742                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
1743                error.detail =
1744                    "parser.start requires an owning Tabnas instance; call Tabnas::parse".into();
1745                self.decorate_error(&mut error);
1746                return Some(Err(error));
1747            };
1748            catch_unwind(AssertUnwindSafe(|| start(src, owner, meta, parent)))
1749        } else if let Some(start) = self.options.parser.start_with_instance.as_ref() {
1750            let Some(owner) = owner else {
1751                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
1752                error.detail =
1753                    "parser.start requires an owning Tabnas instance; call Tabnas::parse".into();
1754                self.decorate_error(&mut error);
1755                return Some(Err(error));
1756            };
1757            catch_unwind(AssertUnwindSafe(|| start(src, owner, meta)))
1758        } else {
1759            let start = self.options.parser.start.as_ref()?;
1760            catch_unwind(AssertUnwindSafe(|| start(src)))
1761        };
1762        Some(match result {
1763            Ok(result) => result.map_err(|error| *error),
1764            Err(payload) => Err(TabnasError::from_panic(
1765                payload,
1766                "parser.start",
1767                src,
1768                0,
1769                1,
1770                1,
1771                &self.options,
1772            )),
1773        })
1774    }
1775
1776    /// Return the token kinds that can legally follow `src` when it is
1777    /// treated as a prefix. The result is an intentional over-approximation:
1778    /// runtime conditions and counters may still reject a listed token.
1779    pub fn continuations(&self, src: &str) -> Continuations {
1780        self.continuations_with_owner(src, None)
1781    }
1782
1783    pub(crate) fn continuations_for(&self, owner: &crate::Tabnas, src: &str) -> Continuations {
1784        self.continuations_with_owner(src, Some(owner))
1785    }
1786
1787    fn continuations_with_owner(&self, src: &str, owner: Option<&crate::Tabnas>) -> Continuations {
1788        catch_unwind(AssertUnwindSafe(|| self.continuations_uncaught(src, owner)))
1789            .unwrap_or_else(|_| self.start_continuations())
1790    }
1791
1792    fn continuations_uncaught(&self, src: &str, owner: Option<&crate::Tabnas>) -> Continuations {
1793        let mut capture = ContinuationCapture::default();
1794        let mut errors = Vec::new();
1795        let result = {
1796            let mut mode = ParseMode {
1797                continuation: Some(&mut capture),
1798                recovering: false,
1799                errors: &mut errors,
1800                partial: None,
1801                gave_up: false,
1802            };
1803            self.parse_inner(src, Value::Undefined, owner, None, &mut mode)
1804        };
1805        let mut tins = if result.is_ok() {
1806            if capture.have_end {
1807                capture.at_end.insert(TIN_ZZ);
1808                capture.at_end.into_iter().collect()
1809            } else {
1810                self.start_openers()
1811            }
1812        } else if capture.failure.is_empty() {
1813            self.start_openers()
1814        } else {
1815            capture.failure
1816        };
1817        tins.sort_unstable();
1818        tins.dedup();
1819        let tokens = tins
1820            .iter()
1821            .map(|tin| self.options.token_name(*tin))
1822            .collect();
1823        Continuations { tins, tokens }
1824    }
1825
1826    fn start_continuations(&self) -> Continuations {
1827        let tins = self.start_openers();
1828        let tokens = tins
1829            .iter()
1830            .map(|tin| self.options.token_name(*tin))
1831            .collect();
1832        Continuations { tins, tokens }
1833    }
1834
1835    fn start_openers(&self) -> Vec<Tin> {
1836        let start = self.rules.get(&self.options.rule.start);
1837        let mut out = BTreeSet::new();
1838        if let Some(spec) = start {
1839            for alt in &spec.open {
1840                if groups_enabled(alt, &self.options) {
1841                    if let Some(slot) = alt.s.first() {
1842                        out.extend(completion_tins(slot));
1843                    }
1844                }
1845            }
1846        }
1847        out.into_iter().collect()
1848    }
1849
1850    /// The tins the rule can accept at `slot`, as the lexer's custom-matcher
1851    /// gate wants them, or nothing when there is no custom matcher to gate.
1852    ///
1853    /// Both consumers (the `fix_len` filter and the expected-first pass in
1854    /// `Lexer::next_raw_inner`) only read this list to decide WHICH of
1855    /// `options.match_tokens` may fire; with no match tokens the answer is
1856    /// the same for any list, and the walk over an empty table yields
1857    /// nothing either way. The empty slice is therefore exact, and it
1858    /// spares every token fetch the rule's accepted-token row entirely --
1859    /// the last work that sat on the fetch path of a grammar with no
1860    /// custom matcher at all. TS `makeMatchMatcher`
1861    /// returns null on an empty table and never asks (ts/src/lexer.ts).
1862    ///
1863    /// `options` is the one `Arc<Options>` the lexer reads too, so this
1864    /// guard consults the field its consumers consult and cannot drift
1865    /// from it.
1866    ///
1867    /// The table was collated over the alternates the group filters
1868    /// enabled at install. `rule.include` and `rule.exclude` are public and
1869    /// may have been rewritten since, and the step then chooses among the
1870    /// alternates the live filters enable (its `groups_prepared` guard),
1871    /// so the row is collated from the live filters too, rather than
1872    /// letting an alternate the step will not try decide which matcher
1873    /// runs first.
1874    fn expected_match_tins(&self, rule: &Rule, slot: usize) -> Cow<'_, [Tin]> {
1875        if self.options.match_tokens.is_empty() {
1876            return Cow::Borrowed(&[]);
1877        }
1878        // The table is the rule's, chosen by what the rule is called --
1879        // exactly as the name-keyed map this replaced chose it. The slot
1880        // is only a hint that skips the hash: `name` is public and a
1881        // callback may have written it, so the slot is trusted only while
1882        // the name installed there is still the rule's own, and anything
1883        // else falls back to the lookup by name. A slot never answers for
1884        // a name that is not at it.
1885        let index = match self.names.get(rule.slot) {
1886            Some(installed) if *installed == rule.name => rule.slot,
1887            _ => match self.rules.get_index_of(&*rule.name) {
1888                Some(index) => index,
1889                None => return Cow::Borrowed(&[]),
1890            },
1891        };
1892        let is_open = rule.state == RuleState::Open;
1893        if self.options.rule.include == self.prepared_include
1894            && self.options.rule.exclude == self.prepared_exclude
1895        {
1896            return Cow::Borrowed(self.expected_tins[index].at(is_open, slot));
1897        }
1898        let installed = &self.rules[index];
1899        let alts = if is_open {
1900            &installed.open
1901        } else {
1902            &installed.close
1903        };
1904        Cow::Owned(ExpectedTins::live(alts, &self.options, slot))
1905    }
1906
1907    /// Record, for `continuations()`, what could have followed where a
1908    /// fetch raised a bad token: the lexer's own fault, or a `#BD` token a
1909    /// custom matcher returned.
1910    ///
1911    /// TypeScript records nothing at such a fetch (`_contTins` is cleared
1912    /// when `parse_alts` begins and written only when every alternate has
1913    /// failed on a buffered token), so `Tabnas.continuations` computes the
1914    /// answer from the buffer for the rule that fetched, at position 0
1915    /// (`continuationTins(ctx, rule)`), or, when that rule is `NORULE`
1916    /// because the check for trailing content fetched, answers with the
1917    /// start rule's openers. Here a rule's fetch records the same set, and
1918    /// the trailing check records nothing, which `continuations_uncaught`
1919    /// turns into the start openers.
1920    fn capture_fetch_failure(
1921        &self,
1922        context: &Context,
1923        rule: &Rule,
1924        stack: &[Rule],
1925        mode: &mut ParseMode<'_>,
1926        fetch: Fetch,
1927    ) {
1928        if fetch != Fetch::Rule {
1929            return;
1930        }
1931        if let Some(capture) = mode.continuation.as_deref_mut() {
1932            capture.failure =
1933                continuation_tins(context, rule, stack, &self.rules, &self.options, 0, None);
1934        }
1935    }
1936
1937    #[allow(clippy::too_many_arguments)]
1938    fn ensure_lookahead(
1939        &self,
1940        lexer: &mut Lexer,
1941        context: &mut Context,
1942        rule: &mut Rule,
1943        count: usize,
1944        mode: &mut ParseMode<'_>,
1945        site: ParseSite<'_>,
1946        fetch: Fetch,
1947    ) -> Result<(), TabnasError> {
1948        while context.t.len() < count {
1949            if context.t.last().is_some_and(|token| token.tin == TIN_ZZ) {
1950                break;
1951            }
1952            let expected_match_tins = self.expected_match_tins(rule, context.t.len());
1953            let token = loop {
1954                let next = match context.next_replay() {
1955                    Some(token) => Ok(token),
1956                    None => {
1957                        let result = self.catch_callback("lexer callback", site.source, || {
1958                            lexer.next_rule_token(&expected_match_tins, rule, context)
1959                        });
1960                        result.map_err(|error| {
1961                            self.attach_active_error(
1962                                error,
1963                                rule,
1964                                site.stack,
1965                                Self::phase_token(rule),
1966                            )
1967                        })?
1968                    }
1969                };
1970                let mut token = match next {
1971                    Ok(token) => token,
1972                    // The lexer's own fault is a `#BD` token from here on,
1973                    // as it is in TypeScript, where `lex.next` builds the
1974                    // token, hands it to the lex subscribers and returns
1975                    // it, and `parse_alts` reads what came back. A
1976                    // subscriber may rewrite it, its code and position
1977                    // included, and the parse sees what it left: so the
1978                    // fault takes the path below, the one a `#BD` token a
1979                    // custom matcher returned takes, and the lexer's error
1980                    // itself goes no further than this token.
1981                    Err(error) => error_token(&error),
1982                };
1983                for subscriber in &self.lex_subscribers {
1984                    let result = self.catch_callback("lex subscriber", site.source, || {
1985                        subscriber(&mut token, rule, context)
1986                    });
1987                    result.map_err(|error| {
1988                        self.attach_active_error(error, rule, site.stack, Some(&token))
1989                    })?;
1990                }
1991                // A bad token a custom matcher returned (`Lexer::bad`,
1992                // `Lexer::bad_span`) is a lexer fault like any other, and
1993                // is handled here exactly as the lexer's own faults are
1994                // above, which is what TypeScript's fetch in `parse_alts`
1995                // does with every `#BD` token it is handed: raised at once,
1996                // with its own code at its own position, or under recovery
1997                // recorded, coalesced with the run it continues, and
1998                // stepped past. Only relexing leaves it in the lookahead,
1999                // for an alternate to re-cut. Buffered, it failed every
2000                // alternate it met, and the error named the first token of
2001                // the lookahead instead: `unexpected`, at the good token in
2002                // front of it.
2003                if token.tin == TIN_BD && !self.options.lex.relex {
2004                    let code = if token.why.is_empty() {
2005                        "unexpected"
2006                    } else {
2007                        token.why.as_str()
2008                    };
2009                    let error = TabnasError::new(
2010                        code,
2011                        token.src.clone(),
2012                        site.source,
2013                        token.site.pos,
2014                        token.site.ri,
2015                        token.site.ci,
2016                    );
2017                    let error = self.attach_error(error, rule, site.stack, site.alts, Some(&token));
2018                    if mode.recovering && fetch == Fetch::Rule {
2019                        if absorb_lex_error(&error, context, &self.options, mode.errors) {
2020                            lexer.skip_bad(&token, mid_construct(&error.code));
2021                            continue;
2022                        }
2023                        mode.gave_up = true;
2024                    }
2025                    self.capture_fetch_failure(context, rule, site.stack, mode, fetch);
2026                    return Err(error);
2027                }
2028                if token.tin == TIN_ZZ {
2029                    if let Some(capture) = mode.continuation.as_deref_mut() {
2030                        // The end is a legal continuation of a prefix that
2031                        // parses, whoever fetched it. What else is legal
2032                        // there is what the fetching rule's alternates could
2033                        // still take; the check for trailing content has no
2034                        // rule, and TypeScript's capture (the lex subscriber
2035                        // in `Tabnas.continuations`) answers it with nothing,
2036                        // since its `rule` is then `NORULE`.
2037                        capture.have_end = true;
2038                        if fetch == Fetch::Rule {
2039                            capture.at_end.extend(continuation_tins(
2040                                context,
2041                                rule,
2042                                site.stack,
2043                                &self.rules,
2044                                &self.options,
2045                                context.t.len(),
2046                                None,
2047                            ));
2048                        }
2049                    }
2050                }
2051                if !self.ignore_tins.contains(&token.tin) {
2052                    break token;
2053                }
2054            };
2055            for subscriber in &self.token_subscribers {
2056                let result =
2057                    self.catch_callback("token subscriber", site.source, || subscriber(&token));
2058                result.map_err(|error| {
2059                    self.attach_active_error(error, rule, site.stack, Some(&token))
2060                })?;
2061            }
2062            let is_end = token.tin == TIN_ZZ;
2063            context.t.push(token);
2064            if is_end {
2065                break;
2066            }
2067        }
2068        Ok(())
2069    }
2070
2071    fn parse_inner(
2072        &self,
2073        src: &str,
2074        meta: Value,
2075        owner: Option<&crate::Tabnas>,
2076        parent: Option<&ContextSeed>,
2077        mode: &mut ParseMode<'_>,
2078    ) -> Result<Value, TabnasError> {
2079        let input_meta = meta.clone();
2080        let mut context = Context::new(
2081            self.options.rewind.history,
2082            src,
2083            meta,
2084            Arc::clone(&self.options),
2085            self.instance.clone(),
2086        );
2087        if let Some(parent) = parent {
2088            context.apply_seed(parent);
2089        }
2090        for prepare in &self.options.parse.prepare {
2091            let outcome = self.catch_callback("parse.prepare", src, || {
2092                prepare.run(owner, &mut context, &input_meta)
2093            })?;
2094            if let Err(detail) = outcome {
2095                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
2096                error.detail = detail.into();
2097                return Err(error);
2098            }
2099        }
2100        for prepare in self.options.parse.named_prepare.values() {
2101            let outcome = self.catch_callback("parse.prepare", src, || {
2102                prepare.run(owner, &mut context, &input_meta)
2103            })?;
2104            if let Err(detail) = outcome {
2105                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
2106                error.detail = detail.into();
2107                return Err(error);
2108            }
2109        }
2110
2111        if src.is_empty() {
2112            return if self.options.lex.empty {
2113                Ok(self.options.lex.empty_result.clone())
2114            } else {
2115                Err(TabnasError::new("unexpected", "", src, 0, 1, 1))
2116            };
2117        }
2118
2119        // The cached regex is the one the parser was built with; use it
2120        // only while the options still carry the pattern it came from.
2121        let exclude_regex = if self.exclude_pattern == self.options.number.exclude {
2122            self.exclude_regex.clone()
2123        } else {
2124            compile_number_exclude(&self.options)
2125        };
2126        let mut lexer = Lexer::with_shared(src, Arc::clone(&self.options), exclude_regex);
2127
2128        // One lookup for the start rule: whether it exists, its shared
2129        // name handle and the spec to bind, which used to be three.
2130        let start_name = self.options.rule.start.as_str();
2131        let Some((start_slot, start_shared, start_spec)) = self.installed(start_name) else {
2132            return Ok(Value::Undefined);
2133        };
2134
2135        let mut current_rule = Rule::new(start_shared.clone(), Value::Undefined);
2136        current_rule.bind_spec(start_spec, start_shared, start_slot);
2137        // Instance 1, as in TypeScript, whose NORULE sentinel is made by
2138        // `makeRule` and takes 0; this engine's is made outside the count.
2139        current_rule.i = 1;
2140        let root_node = current_rule.node.clone();
2141        context.set_root(root_node.clone());
2142        let mut stack: Vec<Rule> = Vec::new();
2143        // Whether a pushed rule may let go of `child_node` while it is
2144        // buried. Read once: `self.options` is reached through `&self`,
2145        // so this cannot change under the parse, and the rule that parks
2146        // is the rule `attempt_recover` will resume.
2147        let park_child_nodes = self.options.parse.recover.pop_until_valid;
2148        let mut next_rule_id = 2;
2149        #[allow(unused_assignments)]
2150        let mut final_value = None;
2151
2152        let mut iterations = 0usize;
2153        let maxmul = if self.options.rule.maxmul == 0 {
2154            3
2155        } else {
2156            self.options.rule.maxmul
2157        };
2158        let max_iterations = self
2159            .rules
2160            .len()
2161            .saturating_mul(src.encode_utf16().count())
2162            .saturating_mul(4)
2163            .saturating_mul(maxmul)
2164            .max(100);
2165        let budget = &self.options.parse.budget;
2166
2167        // One match record for the whole parse, reset at the head of each
2168        // rule step. It used to be born twice per step -- a seed and a
2169        // per-alternate candidate -- and then moved twice more, at 320
2170        // bytes a move, to end up holding what one record could have held
2171        // all along. TypeScript keeps exactly one per context
2172        // (`ctx._palt`); a nested parse runs `parse_inner` again and so
2173        // gets its own, which is why this is a local and not a field.
2174        let mut matched = AltMatch::default();
2175
2176        'parse: loop {
2177            context.set_active(&current_rule, &stack);
2178            update_partial(mode, &root_node, &current_rule, &stack);
2179            iterations += 1;
2180            if iterations > max_iterations {
2181                let pnt = context
2182                    .t
2183                    .first()
2184                    .map(|t| (t.site.pos, t.site.ri, t.site.ci))
2185                    .unwrap_or((0, 1, 1));
2186                return Err(TabnasError::new("unexpected", "", src, pnt.0, pnt.1, pnt.2));
2187            }
2188            context.iteration = iterations - 1;
2189            // The guards run first, and at every step the budget can run
2190            // on: a grammar's bound holds whatever budget the caller set.
2191            if context.iteration > 0 {
2192                for guard in &self.parse_guards {
2193                    let result = self.catch_callback("parse guard", src, || guard(&context));
2194                    let keep_going = result.map_err(|error| {
2195                        self.attach_active_error(
2196                            error,
2197                            &current_rule,
2198                            &stack,
2199                            Self::phase_token(&current_rule).or_else(|| context.t.first()),
2200                        )
2201                    })?;
2202                    if !keep_going {
2203                        return Err(self.cancelled(src, &context, &current_rule, &stack));
2204                    }
2205                }
2206            }
2207            if budget.check_every_n > 0
2208                && context.iteration > 0
2209                && context.iteration % budget.check_every_n == 0
2210            {
2211                if let Some(check) = &budget.on_check {
2212                    let result =
2213                        self.catch_callback("parse.budget.onCheck", src, || check(&context));
2214                    let keep_going = result.map_err(|error| {
2215                        self.attach_active_error(
2216                            error,
2217                            &current_rule,
2218                            &stack,
2219                            Self::phase_token(&current_rule).or_else(|| context.t.first()),
2220                        )
2221                    })?;
2222                    if !keep_going {
2223                        return Err(self.cancelled(src, &context, &current_rule, &stack));
2224                    }
2225                }
2226            }
2227
2228            // The rule was bound to its prepared state when it was routed
2229            // to, and carries the slot that state sits at. Taking the spec
2230            // from there rather than from the rule costs an array index in
2231            // place of comparing the two names byte by byte, and hands out a
2232            // borrow of the parser instead of a reference count on the spec
2233            // -- the clone existed only to release the borrow on the rule
2234            // that the callbacks below need mutably, and the parser is not
2235            // mutable here at all.
2236            //
2237            // The record is a hint. `spec` and `name` are both public on a
2238            // rule and reachable from any callback, so the slot is trusted
2239            // only while the record still describes the rule in hand: same
2240            // spec by pointer, same name. Anything else falls back to the
2241            // rule's own spec, and to the lookup by name as the guard for a
2242            // rule that was never bound.
2243            let by_name;
2244            let (prepared, spec) = match self.prepared.get(current_rule.slot).filter(|prepared| {
2245                Arc::ptr_eq(&prepared.spec, &current_rule.spec)
2246                    && prepared.name == current_rule.name
2247            }) {
2248                Some(prepared) => (Some(prepared), &prepared.spec),
2249                None => {
2250                    by_name = if current_rule.spec.name == *current_rule.name {
2251                        Arc::clone(&current_rule.spec)
2252                    } else {
2253                        match self.rules.get(&*current_rule.name) {
2254                            Some(s) => s.clone(),
2255                            None => {
2256                                let pnt = context
2257                                    .t
2258                                    .first()
2259                                    .map(|t| (t.site.pos, t.site.ri, t.site.ci))
2260                                    .unwrap_or((0, 1, 1));
2261                                return Err(TabnasError::new(
2262                                    "unknown_rule",
2263                                    &*current_rule.name,
2264                                    src,
2265                                    pnt.0,
2266                                    pnt.1,
2267                                    pnt.2,
2268                                ));
2269                            }
2270                        }
2271                    };
2272                    (None, &by_name)
2273                }
2274            };
2275
2276            let is_open = current_rule.state == RuleState::Open;
2277            // A pass that begins inside a probe is the probe's, even when
2278            // error recovery closes the probe before the pass is reported.
2279            let probe_at_start = 0 < context.probe_depth();
2280            let alts = if is_open { &spec.open } else { &spec.close };
2281
2282            for subscriber in &self.rule_subscribers {
2283                let result = self.catch_callback("rule subscriber", src, || {
2284                    subscriber(&mut current_rule, &mut context)
2285                });
2286                result.map_err(|error| {
2287                    self.attach_error(
2288                        error,
2289                        &current_rule,
2290                        &stack,
2291                        alts,
2292                        Self::phase_token(&current_rule).or_else(|| context.t.first()),
2293                    )
2294                })?;
2295            }
2296            update_partial(mode, &root_node, &current_rule, &stack);
2297
2298            // 1. Run before-actions. Recovery can retry a failed close pass;
2299            // its before-close actions have already run and must not replay.
2300            let skip_befores = current_rule.skip_befores;
2301            current_rule.skip_befores = false;
2302            let before_enabled = if is_open {
2303                current_rule.bo
2304            } else {
2305                current_rule.bc
2306            };
2307            // `bo`/`bc` are run control, not presence -- see
2308            // `run_after_actions`. An empty order is the phase having
2309            // nothing to run, and skipping it here also skips the
2310            // snapshot the state callbacks would have been handed.
2311            let by_spec;
2312            let before_bindings: &[ActionBinding] = if skip_befores || !before_enabled {
2313                &[]
2314            } else {
2315                match prepared {
2316                    Some(prepared) => prepared.before(is_open),
2317                    None => {
2318                        let (actions, callbacks, states, order) = if is_open {
2319                            (&spec.bo, &spec.bo_fns, &spec.bo_state_fns, &spec.bo_order)
2320                        } else {
2321                            (&spec.bc, &spec.bc_fns, &spec.bc_state_fns, &spec.bc_order)
2322                        };
2323                        by_spec = resolved_action_order(actions, callbacks, states, order);
2324                        &by_spec
2325                    }
2326                }
2327            };
2328            if !before_bindings.is_empty() {
2329                let label = if is_open {
2330                    "before-open action"
2331                } else {
2332                    "before-close action"
2333                };
2334                let next = is_open.then(|| current_rule.snapshot());
2335                let site = ParseSite {
2336                    source: src,
2337                    stack: &stack,
2338                    alts,
2339                };
2340                let mut output = None;
2341                let mut lifecycle_error = None;
2342                for binding in before_bindings {
2343                    output = match binding {
2344                        ActionBinding::Named(action) => {
2345                            if let Some(callback) = self.state_actions.get(action) {
2346                                self.run_state_callback(
2347                                    label,
2348                                    callback,
2349                                    &mut current_rule,
2350                                    &mut context,
2351                                    next.as_deref(),
2352                                    output,
2353                                )
2354                                .map_err(|error| {
2355                                    self.attach_action_error(
2356                                        error,
2357                                        src,
2358                                        &current_rule,
2359                                        &stack,
2360                                        alts,
2361                                    )
2362                                })?
2363                            } else {
2364                                self.run_action(action, &mut current_rule, &mut context)
2365                                    .map_err(|error| {
2366                                        self.attach_action_error(
2367                                            error,
2368                                            src,
2369                                            &current_rule,
2370                                            &stack,
2371                                            alts,
2372                                        )
2373                                    })?;
2374                                None
2375                            }
2376                        }
2377                        ActionBinding::Callback(callback) => {
2378                            self.run_context_callback(
2379                                label,
2380                                callback,
2381                                &mut current_rule,
2382                                &mut context,
2383                            )
2384                            .map_err(|error| {
2385                                self.attach_action_error(error, src, &current_rule, &stack, alts)
2386                            })?;
2387                            None
2388                        }
2389                        ActionBinding::State(callback) => self
2390                            .run_state_callback(
2391                                label,
2392                                callback,
2393                                &mut current_rule,
2394                                &mut context,
2395                                next.as_deref(),
2396                                output,
2397                            )
2398                            .map_err(|error| {
2399                                self.attach_action_error(error, src, &current_rule, &stack, alts)
2400                            })?,
2401                    };
2402                    match self.check_lifecycle_output(output, &current_rule, site) {
2403                        Ok(next_output) => output = next_output,
2404                        Err(error) => {
2405                            lifecycle_error = Some(error);
2406                            break;
2407                        }
2408                    }
2409                }
2410                if let Some(error) = lifecycle_error {
2411                    update_partial(mode, &root_node, &current_rule, &stack);
2412                    self.recover_error_pass(
2413                        error,
2414                        if is_open {
2415                            RuleState::Open
2416                        } else {
2417                            RuleState::Close
2418                        },
2419                        None,
2420                        false,
2421                        src,
2422                        &mut current_rule,
2423                        &mut stack,
2424                        &mut context,
2425                        &mut lexer,
2426                        mode,
2427                    )?;
2428                    continue 'parse;
2429                }
2430            }
2431            update_partial(mode, &root_node, &current_rule, &stack);
2432
2433            // 2. Select alternates
2434            let mut matched_alt_idx: Option<usize> = None;
2435            let mut matched_count = 0;
2436            // Nothing has read the record since the last step ended, so
2437            // this is the only point it has to be clean by.
2438            matched.reset();
2439            // Set once either of the two condition callbacks that receive
2440            // the record has written into it, so a rejected alternate's
2441            // writes are wiped before the next alternate is tried. Rust
2442            // keeps the alternates isolated from each other here; only the
2443            // candidates that were actually offered a record pay for it.
2444            let mut record_written = false;
2445            // The winning alternate's matched tokens, when they are known to
2446            // still describe `context.t`. See the assignment below.
2447            let mut matched_tokens: Option<Rc<Vec<Token>>> = None;
2448
2449            // Asked once per step rather than once per alternate. When
2450            // the options still carry what the prepared answers were
2451            // worked out against, every alternate below reads a `bool`;
2452            // when a callback has rewritten either list, every alternate
2453            // falls back to deriving it, exactly as before.
2454            let groups_prepared = self.options.rule.include == self.prepared_include
2455                && self.options.rule.exclude == self.prepared_exclude;
2456
2457            // First-token index. Once the first lookahead token is in
2458            // hand, and the lexer is not renegotiating token identity
2459            // (under relex an alternate may re-cut a token it does not
2460            // name, so every alternate stays a candidate), only the
2461            // alternates that can take that token at position 0 are
2462            // tried, in their original order. Until the first fetch,
2463            // alternates are tried in order as before: the first
2464            // alternate with a sequence fetches the token.
2465            let first_index = if self.options.lex.relex {
2466                None
2467            } else {
2468                prepared.map(|prepared| prepared.first(is_open))
2469            };
2470            // The two candidate lists (alternates naming the first tin,
2471            // and the wildcards), walked together in index order once
2472            // selected, and the tin they were selected for.
2473            let mut lists: Option<(&[usize], &[usize])> = None;
2474            let mut key_tin = TIN_BD;
2475            let (mut ni, mut wi) = (0, 0);
2476            let mut next_idx = 0;
2477            loop {
2478                if lists.is_none() {
2479                    if let (Some(index), Some(t0)) = (first_index, context.t.first()) {
2480                        if t0.tin != TIN_BD {
2481                            key_tin = t0.tin;
2482                            let named = index.named(key_tin);
2483                            let wild = index.wild.as_slice();
2484                            (ni, wi) = (0, 0);
2485                            while ni < named.len() && named[ni] < next_idx {
2486                                ni += 1;
2487                            }
2488                            while wi < wild.len() && wild[wi] < next_idx {
2489                                wi += 1;
2490                            }
2491                            lists = Some((named, wild));
2492                        }
2493                    }
2494                }
2495                let idx = match lists {
2496                    Some((named, wild)) => {
2497                        let n = named.get(ni).copied().unwrap_or(alts.len());
2498                        let w = wild.get(wi).copied().unwrap_or(alts.len());
2499                        if alts.len() <= n && alts.len() <= w {
2500                            // No remaining alternate can take the first token.
2501                            break;
2502                        }
2503                        if n < w {
2504                            ni += 1;
2505                            n
2506                        } else {
2507                            wi += 1;
2508                            w
2509                        }
2510                    }
2511                    None => {
2512                        if alts.len() <= next_idx {
2513                            break;
2514                        }
2515                        next_idx += 1;
2516                        next_idx - 1
2517                    }
2518                };
2519                let alt = &alts[idx];
2520                let enabled = match prepared
2521                    .filter(|_| groups_prepared)
2522                    .and_then(|prepared| prepared.alt(is_open, idx))
2523                {
2524                    Some(prepared_alt) => prepared_alt.groups,
2525                    None => groups_enabled(alt, &self.options),
2526                };
2527                if !enabled {
2528                    continue;
2529                }
2530                let s_len = alt.s.len();
2531                let mut alt_matches = true;
2532                if record_written {
2533                    matched.reset();
2534                    record_written = false;
2535                }
2536                let mut relex_undo: Option<RelexUndo> = None;
2537                for (pos, pos_tins) in alt.s.iter().enumerate() {
2538                    if let Err(error) = self.ensure_lookahead(
2539                        &mut lexer,
2540                        &mut context,
2541                        &mut current_rule,
2542                        pos + 1,
2543                        mode,
2544                        ParseSite {
2545                            source: src,
2546                            stack: &stack,
2547                            alts,
2548                        },
2549                        Fetch::Rule,
2550                    ) {
2551                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
2552                    }
2553                    let Some(token) = context.t.get(pos).cloned() else {
2554                        alt_matches = false;
2555                        break;
2556                    };
2557                    if !slot_matches(pos_tins, token.tin) {
2558                        let recut = if self.options.lex.relex
2559                            && !token.src.is_empty()
2560                            && !pos_tins.is_empty()
2561                        {
2562                            let result = self.catch_callback("lexer relex callback", src, || {
2563                                lexer.relex(&token, pos_tins, &mut current_rule, &mut context)
2564                            });
2565                            result.map_err(|error| {
2566                                self.attach_error(error, &current_rule, &stack, alts, Some(&token))
2567                            })?
2568                        } else {
2569                            None
2570                        };
2571                        let Some((mut recut, checkpoint)) = recut else {
2572                            alt_matches = false;
2573                            break;
2574                        };
2575                        for subscriber in &self.lex_subscribers {
2576                            let result = self.catch_callback("lex subscriber", src, || {
2577                                subscriber(&mut recut, &mut current_rule, &mut context)
2578                            });
2579                            result.map_err(|error| {
2580                                self.attach_error(error, &current_rule, &stack, alts, Some(&recut))
2581                            })?;
2582                        }
2583                        if !pos_tins.contains(&recut.tin) {
2584                            lexer.unrelex(checkpoint, &mut context);
2585                            alt_matches = false;
2586                            break;
2587                        }
2588                        if relex_undo.is_none() {
2589                            relex_undo = Some(RelexUndo {
2590                                position: pos,
2591                                token,
2592                                checkpoint,
2593                                tokens: context.t.clone(),
2594                            });
2595                        }
2596                        context.t[pos] = recut;
2597                        context.t.truncate(pos + 1);
2598                    }
2599                }
2600
2601                if alt_matches {
2602                    let tokens: Rc<Vec<Token>> =
2603                        Rc::new(context.t.iter().take(s_len).cloned().collect());
2604                    // The declarative conditions are the only readers of a
2605                    // candidate rule; the callback tiers below run against
2606                    // `current_rule` itself, after its matched tokens are in
2607                    // place. Most alternates declare no declarative
2608                    // condition, and cloning a whole rule to answer a
2609                    // question nobody asks was the parse loop's largest
2610                    // single copy.
2611                    if alt.c_ref.is_some() || !alt.c.is_empty() {
2612                        let mut candidate = current_rule.clone();
2613                        if is_open {
2614                            candidate.o = Rc::clone(&tokens);
2615                        } else {
2616                            candidate.c = Rc::clone(&tokens);
2617                        }
2618                        if !builtin_condition_matches(alt.c_ref.as_deref(), &candidate)
2619                            || !conditions_match(&alt.c, &candidate, &stack)
2620                        {
2621                            alt_matches = false;
2622                        }
2623                    }
2624                    if alt_matches {
2625                        if is_open {
2626                            current_rule.o = Rc::clone(&tokens);
2627                        } else {
2628                            current_rule.c = Rc::clone(&tokens);
2629                        }
2630                        if let Some(condition) = &alt.c_fn {
2631                            context.set_rule(&current_rule);
2632                            let result = self.catch_callback("alternate condition", src, || {
2633                                condition(&mut current_rule, &mut context)
2634                            });
2635                            alt_matches = result.map_err(|error| {
2636                                self.attach_error(
2637                                    error,
2638                                    &current_rule,
2639                                    &stack,
2640                                    alts,
2641                                    Self::phase_token(&current_rule),
2642                                )
2643                            })?;
2644                        }
2645                        if alt_matches {
2646                            if let Some(condition) = &alt.c_match {
2647                                context.set_rule(&current_rule);
2648                                record_written = true;
2649                                let result =
2650                                    self.catch_callback("matched alternate condition", src, || {
2651                                        condition(&mut current_rule, &mut context, &mut matched)
2652                                    });
2653                                alt_matches = result.map_err(|error| {
2654                                    self.attach_error(
2655                                        error,
2656                                        &current_rule,
2657                                        &stack,
2658                                        alts,
2659                                        Self::phase_token(&current_rule),
2660                                    )
2661                                })?;
2662                            }
2663                        }
2664                        if alt_matches {
2665                            if let Some(condition) = &alt.c_lex_match {
2666                                context.set_rule(&current_rule);
2667                                record_written = true;
2668                                let result = self.catch_callback(
2669                                    "matched alternate lexer condition",
2670                                    src,
2671                                    || {
2672                                        condition(
2673                                            &mut current_rule,
2674                                            &mut context,
2675                                            &mut matched,
2676                                            &mut lexer,
2677                                        )
2678                                    },
2679                                );
2680                                alt_matches = result.map_err(|error| {
2681                                    self.attach_error(
2682                                        error,
2683                                        &current_rule,
2684                                        &stack,
2685                                        alts,
2686                                        Self::phase_token(&current_rule),
2687                                    )
2688                                })?;
2689                            }
2690                        }
2691                        if alt_matches {
2692                            if let Some(condition) = &alt.c_lex {
2693                                context.set_rule(&current_rule);
2694                                let result =
2695                                    self.catch_callback("alternate lexer condition", src, || {
2696                                        condition(&mut current_rule, &mut context, &mut lexer)
2697                                    });
2698                                alt_matches = result.map_err(|error| {
2699                                    self.attach_error(
2700                                        error,
2701                                        &current_rule,
2702                                        &stack,
2703                                        alts,
2704                                        Self::phase_token(&current_rule),
2705                                    )
2706                                })?;
2707                            }
2708                        }
2709                    }
2710                    if alt_matches {
2711                        matched_alt_idx = Some(idx);
2712                        matched_count = s_len;
2713                        // `tokens` is `context.t[..s_len]`, which is what the
2714                        // matched-token copy after this loop rebuilds from
2715                        // the same buffer. Between building it and here, the
2716                        // only things holding a `&mut Context` are the two
2717                        // condition callbacks, so without them the rebuild
2718                        // cannot differ and the vector below is reused
2719                        // instead of allocated and cloned a second time.
2720                        // `break` leaves the loop before the relex undo, so
2721                        // that cannot restore `context.t` underneath either.
2722                        if alt.c_fn.is_none() && alt.c_match.is_none() {
2723                            matched_tokens = Some(Rc::clone(&tokens));
2724                        }
2725                        break;
2726                    }
2727                }
2728                if let Some(undo) = relex_undo {
2729                    lexer.unrelex(undo.checkpoint, &mut context);
2730                    context.t = undo.tokens;
2731                    for subscriber in &self.lex_subscribers {
2732                        let mut restored = undo.token.clone();
2733                        let result = self.catch_callback("lex subscriber", src, || {
2734                            subscriber(&mut restored, &mut current_rule, &mut context)
2735                        });
2736                        result.map_err(|error| {
2737                            self.attach_error(error, &current_rule, &stack, alts, Some(&restored))
2738                        })?;
2739                    }
2740                    debug_assert_eq!(context.t.get(undo.position), Some(&undo.token));
2741                }
2742                // A condition can retag the first token, or replace it,
2743                // and then reject. The lists were selected for a tin the
2744                // token no longer has, and the plain scan would test every
2745                // later alternate against the token as it is now: resume
2746                // after this alternate, and select again at the top.
2747                if lists.is_some() && context.t.first().map(|t0| t0.tin) != Some(key_tin) {
2748                    lists = None;
2749                    next_idx = idx + 1;
2750                }
2751            }
2752
2753            if let Some(idx) = matched_alt_idx {
2754                // Copy matched tokens
2755                let matched_tokens = matched_tokens.unwrap_or_else(|| {
2756                    Rc::new(context.t.iter().take(matched_count).cloned().collect())
2757                });
2758                if is_open {
2759                    current_rule.o = matched_tokens;
2760                } else {
2761                    current_rule.c = matched_tokens;
2762                }
2763
2764                // Compatibility modifier for the original two-argument Rust
2765                // callback tier. It rewrites the source spec before dynamic
2766                // fields are resolved. The full `h_match` callback below runs
2767                // at the canonical point over the resolved AltMatch.
2768                //
2769                // Rewriting is the only thing here that needs an alternate of
2770                // its own; everything below reads one. A grammar that
2771                // declares no modifier — which is most of them, and both
2772                // benchmark grammars — now borrows the installed alternate
2773                // instead of copying it once per rule step.
2774                let rewritten: AltSpec;
2775                let alt: &AltSpec = if let Some(modifier) = alts[idx].h.clone() {
2776                    context.set_rule(&current_rule);
2777                    let source = alts[idx].clone();
2778                    let result = self.catch_callback("alternate modifier", src, || {
2779                        modifier(source, &mut current_rule, &mut context)
2780                    });
2781                    rewritten = result.map_err(|error| {
2782                        self.attach_error(
2783                            error,
2784                            &current_rule,
2785                            &stack,
2786                            alts,
2787                            Self::phase_token(&current_rule),
2788                        )
2789                    })?;
2790                    &rewritten
2791                } else {
2792                    &alts[idx]
2793                };
2794
2795                matched.h = alt.h_match.clone();
2796                if !alt.n.is_empty() {
2797                    matched.n = alt.n.clone();
2798                }
2799                if !alt.u.is_empty() {
2800                    matched.u = alt.u.clone();
2801                }
2802                if !alt.k.is_empty() {
2803                    matched.k = alt.k.clone();
2804                }
2805                // The alternate's group tags and action order, both worked
2806                // out when the rule was installed. A modifier rewrites the
2807                // whole `AltSpec` per step, so a rule that carries one is
2808                // resolved from what the modifier produced, not from the
2809                // record.
2810                let prepared_alt = if alts[idx].h.is_some() {
2811                    None
2812                } else {
2813                    prepared.and_then(|prepared| prepared.alt(is_open, idx))
2814                };
2815                match prepared_alt {
2816                    // `clone_from` writes into the list the last step left
2817                    // behind -- `AltMatch::reset` clears it without giving
2818                    // up its capacity -- rather than growing a fresh one.
2819                    Some(prepared_alt) => matched.g.clone_from(&prepared_alt.group_tags),
2820                    None if !alt.g.is_empty() => {
2821                        matched.g = listed(&alt.g).map(str::to_owned).collect();
2822                    }
2823                    None => {}
2824                }
2825                // Publishing the order into the record is only observable
2826                // when something this step runs receives the record. When
2827                // nothing does -- no matched condition, error, route,
2828                // backtrack, modifier or action, and no named binding that
2829                // could resolve to a matched action -- the step runs the
2830                // prepared order in place and the record keeps the empty
2831                // list it was born with. `matched_actions` is public and
2832                // may be written after `add_rule`, so whether a name can
2833                // reach it is asked here, per step, never cached.
2834                let prepared_alt = prepared_alt.filter(|prepared_alt| {
2835                    !prepared_alt.observed
2836                        && (!prepared_alt.named || self.matched_actions.is_empty())
2837                });
2838                if prepared_alt.is_none() {
2839                    let actions = resolved_alt_action_order(
2840                        &alt.a,
2841                        &alt.action_fns,
2842                        &alt.matched_action_fns,
2843                        &alt.action_order,
2844                    );
2845                    if !actions.is_empty() {
2846                        matched.actions = actions;
2847                    }
2848                }
2849                if !alt.action_configs.is_empty() {
2850                    matched.action_configs = alt.action_configs.clone();
2851                }
2852
2853                if let Some(route) = &alt.p_fn {
2854                    context.set_rule(&current_rule);
2855                    matched.p = self
2856                        .catch_callback("alternate push", src, || {
2857                            route(&mut current_rule, &mut context)
2858                        })
2859                        .map_err(|error| {
2860                            self.attach_error(
2861                                error,
2862                                &current_rule,
2863                                &stack,
2864                                alts,
2865                                Self::phase_token(&current_rule),
2866                            )
2867                        })?
2868                        .filter(|name| !name.is_empty());
2869                }
2870                if let Some(route) = &alt.p_match {
2871                    context.set_rule(&current_rule);
2872                    matched.p = self
2873                        .catch_callback("matched alternate push", src, || {
2874                            route(&mut current_rule, &mut context, &mut matched)
2875                        })
2876                        .map_err(|error| {
2877                            self.attach_error(
2878                                error,
2879                                &current_rule,
2880                                &stack,
2881                                alts,
2882                                Self::phase_token(&current_rule),
2883                            )
2884                        })?
2885                        .filter(|name| !name.is_empty());
2886                } else if alt.p_fn.is_none() {
2887                    if let Some(route) = alt.p.clone() {
2888                        matched.p = (!route.is_empty()).then_some(route);
2889                    }
2890                }
2891                if let Some(route) = &alt.r_fn {
2892                    context.set_rule(&current_rule);
2893                    matched.r = self
2894                        .catch_callback("alternate replace", src, || {
2895                            route(&mut current_rule, &mut context)
2896                        })
2897                        .map_err(|error| {
2898                            self.attach_error(
2899                                error,
2900                                &current_rule,
2901                                &stack,
2902                                alts,
2903                                Self::phase_token(&current_rule),
2904                            )
2905                        })?
2906                        .filter(|name| !name.is_empty());
2907                }
2908                if let Some(route) = &alt.r_match {
2909                    context.set_rule(&current_rule);
2910                    matched.r = self
2911                        .catch_callback("matched alternate replace", src, || {
2912                            route(&mut current_rule, &mut context, &mut matched)
2913                        })
2914                        .map_err(|error| {
2915                            self.attach_error(
2916                                error,
2917                                &current_rule,
2918                                &stack,
2919                                alts,
2920                                Self::phase_token(&current_rule),
2921                            )
2922                        })?
2923                        .filter(|name| !name.is_empty());
2924                } else if alt.r_fn.is_none() {
2925                    if let Some(route) = alt.r.clone() {
2926                        matched.r = (!route.is_empty()).then_some(route);
2927                    }
2928                }
2929                if let Some(backtrack) = &alt.b_fn {
2930                    context.set_rule(&current_rule);
2931                    matched.b = self
2932                        .catch_callback("alternate backtrack", src, || {
2933                            backtrack(&mut current_rule, &mut context)
2934                        })
2935                        .map_err(|error| {
2936                            self.attach_error(
2937                                error,
2938                                &current_rule,
2939                                &stack,
2940                                alts,
2941                                Self::phase_token(&current_rule),
2942                            )
2943                        })?;
2944                }
2945                if let Some(backtrack) = &alt.b_match {
2946                    context.set_rule(&current_rule);
2947                    matched.b = self
2948                        .catch_callback("matched alternate backtrack", src, || {
2949                            backtrack(&mut current_rule, &mut context, &mut matched)
2950                        })
2951                        .map_err(|error| {
2952                            self.attach_error(
2953                                error,
2954                                &current_rule,
2955                                &stack,
2956                                alts,
2957                                Self::phase_token(&current_rule),
2958                            )
2959                        })?;
2960                } else if alt.b_fn.is_none() && alt.b != 0 {
2961                    matched.b = alt.b;
2962                }
2963
2964                if let Some(modifier) = alt.h_match.clone() {
2965                    context.set_rule(&current_rule);
2966                    let next = is_open.then(|| current_rule.snapshot());
2967                    matched = self
2968                        .catch_callback("matched alternate modifier", src, || {
2969                            modifier(
2970                                std::mem::take(&mut matched),
2971                                &mut current_rule,
2972                                &mut context,
2973                                next.as_deref(),
2974                            )
2975                        })
2976                        .map_err(|error| {
2977                            self.attach_error(
2978                                error,
2979                                &current_rule,
2980                                &stack,
2981                                alts,
2982                                Self::phase_token(&current_rule),
2983                            )
2984                        })?;
2985                }
2986
2987                // The alternate's error hook runs AFTER the routing forms
2988                // have resolved and after both modifiers, and sees what the
2989                // modifier produced: routing, then modify, then check, in
2990                // every runtime (#154). It ran before the routing forms and
2991                // between the two modifiers here, which no grammar could
2992                // observe and no other port did.
2993                if let Some(error_hook) = alt.e.clone() {
2994                    context.set_rule(&current_rule);
2995                    let result = self.catch_callback("alternate error", src, || {
2996                        error_hook(&mut current_rule, &mut context)
2997                    });
2998                    matched.e = result
2999                        .map_err(|error| {
3000                            self.attach_error(
3001                                error,
3002                                &current_rule,
3003                                &stack,
3004                                alts,
3005                                Self::phase_token(&current_rule),
3006                            )
3007                        })?
3008                        .map(Box::new);
3009                }
3010                if let Some(error_hook) = alt.e_match.clone() {
3011                    context.set_rule(&current_rule);
3012                    let result = self.catch_callback("matched alternate error", src, || {
3013                        error_hook(&mut current_rule, &mut context, &mut matched)
3014                    });
3015                    matched.e = result
3016                        .map_err(|error| {
3017                            self.attach_error(
3018                                error,
3019                                &current_rule,
3020                                &stack,
3021                                alts,
3022                                Self::phase_token(&current_rule),
3023                            )
3024                        })?
3025                        .map(Box::new);
3026                }
3027                // Function-valued alternate errors are raised at the match
3028                // site, before counters, actions and consumption.
3029                if let Some(token) = matched.e.clone() {
3030                    let code = raised_error_code(&token);
3031                    let error = TabnasError::new(
3032                        code,
3033                        token.src.clone(),
3034                        src,
3035                        token.site.pos,
3036                        token.site.ri,
3037                        token.site.ci,
3038                    );
3039                    let done_alt = (!self.rule_done_subscribers.is_empty()).then(|| RuleDoneAlt {
3040                        b: matched.b,
3041                        g: matched.g.clone(),
3042                        p: matched.p.clone().unwrap_or_default(),
3043                        r: matched.r.clone().unwrap_or_default(),
3044                        err: Some((*token).clone()),
3045                    });
3046                    let error = self.attach_error(error, &current_rule, &stack, alts, Some(&token));
3047                    self.recover_error_pass(
3048                        error,
3049                        if is_open {
3050                            RuleState::Open
3051                        } else {
3052                            RuleState::Close
3053                        },
3054                        done_alt,
3055                        false,
3056                        src,
3057                        &mut current_rule,
3058                        &mut stack,
3059                        &mut context,
3060                        &mut lexer,
3061                        mode,
3062                    )?;
3063                    continue;
3064                }
3065
3066                // Update counters n
3067                for (k, v) in &matched.n {
3068                    if *v == 0 {
3069                        current_rule.n_mut().insert(k.clone(), 0);
3070                    } else {
3071                        *current_rule.n_mut().entry(k.clone()).or_insert(0) += *v;
3072                    }
3073                }
3074
3075                // Update user props u
3076                for (k, v) in &matched.u {
3077                    current_rule.u_mut().insert(k.clone(), v.clone());
3078                }
3079
3080                // Update keep props k
3081                for (k, v) in &matched.k {
3082                    current_rule.k_mut().insert(k.clone(), v.clone());
3083                }
3084
3085                let backtrack = matched.b;
3086                let consumed = matched_count.saturating_sub(backtrack);
3087                context.record_consumed(consumed);
3088
3089                // Run action. A bad token returned by a canonical action is
3090                // raised through the same recovery path as alt.e and
3091                // lifecycle actions; later actions must not run.
3092                let mut matched_action_error = None;
3093                let mut matched_action_token = None;
3094                // The published list has to be copied to be walked -- an
3095                // action may write the record it is being read out of, and
3096                // appending to `matched.actions` from inside this loop has
3097                // never reached it. The prepared list is not the record, so
3098                // it is walked where it lies.
3099                let published;
3100                let bindings: &[AltActionBinding] = match prepared_alt {
3101                    Some(prepared_alt) => &prepared_alt.actions,
3102                    None => {
3103                        published = matched.actions.clone();
3104                        &published
3105                    }
3106                };
3107                for binding in bindings {
3108                    let act_name = match binding {
3109                        AltActionBinding::Context(callback) => {
3110                            self.run_context_callback(
3111                                "alternate action",
3112                                callback,
3113                                &mut current_rule,
3114                                &mut context,
3115                            )
3116                            .map_err(|error| {
3117                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3118                            })?;
3119                            continue;
3120                        }
3121                        AltActionBinding::Matched(callback) => {
3122                            context.set_rule(&current_rule);
3123                            let result = self
3124                                .catch_callback("matched alternate action", src, || {
3125                                    callback(&mut current_rule, &mut context, &mut matched)
3126                                })
3127                                .map_err(|error| {
3128                                    self.attach_action_error(
3129                                        error,
3130                                        src,
3131                                        &current_rule,
3132                                        &stack,
3133                                        alts,
3134                                    )
3135                                })?;
3136                            let token = result.map_err(|action_error| {
3137                                self.attach_action_error(
3138                                    action_error.into(),
3139                                    src,
3140                                    &current_rule,
3141                                    &stack,
3142                                    alts,
3143                                )
3144                            })?;
3145                            if let Some(token) = token.filter(|token| !token.err.is_empty()) {
3146                                matched_action_error = Some(self.raised_token_error(
3147                                    &token,
3148                                    &current_rule,
3149                                    ParseSite {
3150                                        source: src,
3151                                        stack: &stack,
3152                                        alts,
3153                                    },
3154                                ));
3155                                matched_action_token = Some(token);
3156                                break;
3157                            }
3158                            continue;
3159                        }
3160                        AltActionBinding::Named(name) => name,
3161                    };
3162                    if let Some(callback) = self.matched_actions.get(act_name) {
3163                        context.set_rule(&current_rule);
3164                        let result = self
3165                            .catch_callback("named matched alternate action", src, || {
3166                                callback(&mut current_rule, &mut context, &mut matched)
3167                            })
3168                            .map_err(|error| {
3169                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3170                            })?;
3171                        let token = result.map_err(|action_error| {
3172                            self.attach_action_error(
3173                                action_error.into(),
3174                                src,
3175                                &current_rule,
3176                                &stack,
3177                                alts,
3178                            )
3179                        })?;
3180                        if let Some(token) = token.filter(|token| !token.err.is_empty()) {
3181                            matched_action_error = Some(self.raised_token_error(
3182                                &token,
3183                                &current_rule,
3184                                ParseSite {
3185                                    source: src,
3186                                    stack: &stack,
3187                                    alts,
3188                                },
3189                            ));
3190                            matched_action_token = Some(token);
3191                            break;
3192                        }
3193                        continue;
3194                    }
3195                    match act_name.as_str() {
3196                        "@probeInit$" => {
3197                            current_rule
3198                                .k_mut()
3199                                .insert("pd_phase".into(), Value::Number(0.0));
3200                            let mark = Value::Number(context.mark() as f64);
3201                            current_rule.k_mut().insert("pd_mark".into(), mark);
3202                            // The passes until the decision are the probe's.
3203                            context.probe_open(&current_rule);
3204                        }
3205                        "@probeDecide$" => {
3206                            let mark = current_rule.k.get("pd_mark").and_then(|value| {
3207                                if let Value::Number(mark) = value {
3208                                    usize::try_from(*mark as u64).ok()
3209                                } else {
3210                                    None
3211                                }
3212                            });
3213                            let Some(mark) = mark.filter(|mark| *mark <= context.v_abs) else {
3214                                let mut error = TabnasError::new("internal", "", src, 0, 1, 1);
3215                                error.detail =
3216                                    "@probeDecide$: phase-0 @probeInit$ did not record a valid mark"
3217                                        .into();
3218                                return Err(error);
3219                            };
3220                            if let Err(error) = self.ensure_lookahead(
3221                                &mut lexer,
3222                                &mut context,
3223                                &mut current_rule,
3224                                1,
3225                                mode,
3226                                ParseSite {
3227                                    source: src,
3228                                    stack: &stack,
3229                                    alts,
3230                                },
3231                                Fetch::Rule,
3232                            ) {
3233                                return Err(self.attach_error(
3234                                    error,
3235                                    &current_rule,
3236                                    &stack,
3237                                    alts,
3238                                    None,
3239                                ));
3240                            }
3241                            let disambiguator =
3242                                current_rule.k.get("pd_d").and_then(|value| match value {
3243                                    Value::String(name) => Some(name.as_str()),
3244                                    _ => None,
3245                                });
3246                            let phase = if context
3247                                .t
3248                                .first()
3249                                .is_some_and(|token| Some(token.name.as_str()) == disambiguator)
3250                            {
3251                                1.0
3252                            } else {
3253                                2.0
3254                            };
3255                            context.rewind(mark)?;
3256                            current_rule
3257                                .k_mut()
3258                                .insert("pd_phase".into(), Value::Number(phase));
3259                            context.probe_close();
3260                        }
3261                        _ => self
3262                            .run_action_with_config(
3263                                act_name,
3264                                &mut current_rule,
3265                                &mut context,
3266                                matched.action_configs.get(act_name),
3267                            )
3268                            .map_err(|error| {
3269                                self.attach_action_error(error, src, &current_rule, &stack, alts)
3270                            })?,
3271                    }
3272                }
3273                if let Some(error) = matched_action_error {
3274                    let recovered_alt = Some(RuleDoneAlt {
3275                        b: matched.b,
3276                        g: matched.g.clone(),
3277                        p: matched.p.clone().unwrap_or_default(),
3278                        r: matched.r.clone().unwrap_or_default(),
3279                        err: None,
3280                    });
3281                    self.recover_error_pass(
3282                        error,
3283                        if is_open {
3284                            RuleState::Open
3285                        } else {
3286                            RuleState::Close
3287                        },
3288                        recovered_alt,
3289                        matched_action_token.is_some(),
3290                        src,
3291                        &mut current_rule,
3292                        &mut stack,
3293                        &mut context,
3294                        &mut lexer,
3295                        mode,
3296                    )?;
3297                    update_partial(mode, &root_node, &current_rule, &stack);
3298                    continue 'parse;
3299                }
3300                update_partial(mode, &root_node, &current_rule, &stack);
3301
3302                // The canonical action receives the live match record. Its
3303                // post-action p/r writes are a supported routing channel, so
3304                // resolve the transition only after the action sequence.
3305                // Nothing below reads `matched.p` or `matched.r` again: the
3306                // record's remaining readers take `b` and `g`. So the names
3307                // move out of it rather than being copied, which is the
3308                // second `String` each of them cost per rule step.
3309                let push_name = matched.p.take();
3310                let replace_name = matched.r.take();
3311                // Only a ruleDone subscriber ever reads this, and it is
3312                // cloned again at each of the transition arms below. A
3313                // grammar with no subscriber was building and copying it
3314                // several times per matched alternate for nobody.
3315                let done_alt = (!self.rule_done_subscribers.is_empty()).then(|| RuleDoneAlt {
3316                    b: matched.b,
3317                    g: matched.g.clone(),
3318                    p: push_name.clone().unwrap_or_default(),
3319                    r: replace_name.clone().unwrap_or_default(),
3320                    err: None,
3321                });
3322
3323                // Callback routes and action mutations cannot be validated at
3324                // grammar-install time. Reject an unknown destination at the
3325                // canonical point: after the matched action, but before any
3326                // lifecycle after-action or transition.
3327                //
3328                // Resolving it here also settles the transition below: the
3329                // arms take the shared name and the spec out of this one
3330                // lookup rather than hashing the same name twice more.
3331                // `push` wins over `replace` in the arms below, so this
3332                // resolves whichever of the two the parse will take.
3333                //
3334                // A route the grammar declared on this alternate was already
3335                // resolved when the rule was installed; all that is left of
3336                // it here is checking that the name the step is actually
3337                // routing to is still that name, which is a byte compare
3338                // against a handle rather than a hash of the same three
3339                // bytes for the tens of thousands of steps that route where
3340                // the grammar said they would.
3341                let mut route = match push_name.as_deref().or(replace_name.as_deref()) {
3342                    Some(name) => match prepared
3343                        .and_then(|prepared| prepared.alt(is_open, idx))
3344                        .map(|alt| if push_name.is_some() { &alt.p } else { &alt.r })
3345                        .and_then(|route| route.resolved(name))
3346                        .or_else(|| self.installed(name))
3347                    {
3348                        Some(resolved) => Some(resolved),
3349                        None => {
3350                            let mut token = Self::phase_token(&current_rule)
3351                                .cloned()
3352                                .or_else(|| context.t.first().cloned())
3353                                .unwrap_or_else(Token::no_token);
3354                            token.bad("unknown_rule");
3355                            token
3356                                .use_data_mut()
3357                                .insert("rulename".into(), Value::String(name.to_string()));
3358                            let error = self.raised_token_error(
3359                                &token,
3360                                &current_rule,
3361                                ParseSite {
3362                                    source: src,
3363                                    stack: &stack,
3364                                    alts,
3365                                },
3366                            );
3367                            self.recover_error_pass(
3368                                error,
3369                                if is_open {
3370                                    RuleState::Open
3371                                } else {
3372                                    RuleState::Close
3373                                },
3374                                done_alt,
3375                                false,
3376                                src,
3377                                &mut current_rule,
3378                                &mut stack,
3379                                &mut context,
3380                                &mut lexer,
3381                                mode,
3382                            )?;
3383                            update_partial(mode, &root_node, &current_rule, &stack);
3384                            continue 'parse;
3385                        }
3386                    },
3387                    None => None,
3388                };
3389
3390                // Resolve the transition before running lifecycle after-actions,
3391                // so they can inspect rule.next just like the canonical engine.
3392                // The action still belongs to the rule whose alternate matched.
3393                let completed_rule: Option<Rule>;
3394                let mut completed_value = None;
3395                if push_name.is_some() {
3396                    let (push_slot, push_shared, push_spec) =
3397                        route.take().expect("a push route was resolved above");
3398                    let mut child = Rule::bound(
3399                        push_shared.clone(),
3400                        current_rule.node.clone(),
3401                        Some(push_spec),
3402                        push_slot,
3403                    );
3404                    child.i = next_rule_id;
3405                    next_rule_id += 1;
3406                    child.d = stack.len() + 1;
3407                    child.parent_node = Some(current_rule.node.clone());
3408                    child.n = Rc::clone(&current_rule.n);
3409                    child.k = Rc::clone(&current_rule.k);
3410                    child.parent_rule = Some(bounded_history(
3411                        current_rule.snapshot(),
3412                        self.options.rule.history,
3413                        Link::PusherBefore,
3414                    ));
3415                    current_rule.next_rule_name = Some(push_shared);
3416                    current_rule.child_rule = Some(child.snapshot());
3417                    current_rule.next_rule = current_rule.child_rule.clone();
3418                    current_rule.note_child_push(&child);
3419                    // The link as this arm made it, so the relink below can
3420                    // tell whether an after action has changed it.
3421                    let linked = current_rule.child_rule.clone();
3422                    let after = self.run_after_actions(
3423                        spec,
3424                        prepared,
3425                        is_open,
3426                        &mut current_rule,
3427                        &mut context,
3428                        ParseSite {
3429                            source: src,
3430                            stack: &stack,
3431                            alts,
3432                        },
3433                    );
3434                    update_partial(mode, &root_node, &current_rule, &stack);
3435                    if self.recover_after_actions(
3436                        after,
3437                        if is_open {
3438                            RuleState::Open
3439                        } else {
3440                            RuleState::Close
3441                        },
3442                        done_alt.clone(),
3443                        src,
3444                        &mut current_rule,
3445                        &mut stack,
3446                        &mut context,
3447                        &mut lexer,
3448                        mode,
3449                    )? {
3450                        continue 'parse;
3451                    }
3452                    if is_open {
3453                        current_rule.state = RuleState::Close;
3454                    }
3455                    child.parent_rule = Some(bounded_history(
3456                        current_rule.snapshot(),
3457                        self.options.rule.history,
3458                        Link::Parent,
3459                    ));
3460                    // TypeScript and Go link the live rules, so from the
3461                    // child, `parent.child.parent.child` is the child
3462                    // itself. The snapshot linked above as `child` carries
3463                    // this rule as it stood before the push, whose `child`
3464                    // is the one pushed before (parser #259). With no
3465                    // bound, link the child again from a snapshot that
3466                    // carries this rule with the child linked, and give
3467                    // the child this rule as it then stands, so that a
3468                    // snapshot of the child reads the same chain: the
3469                    // pre-link record is two hops further down, past the
3470                    // four-hop read. The cost, measured on
3471                    // `rs/tests/rule_history_test.rs`'s flat array, is two
3472                    // more records kept per push, 8 for 6 per element.
3473                    // Under a bound the links stay as the canonical engine
3474                    // copies them, where that path reads nothing
3475                    // (`rule-history-bounded-pusher`). An after action that
3476                    // cleared or repointed `child` or `next` keeps its edit:
3477                    // the canonical engine links before the after actions
3478                    // and never overwrites them afterwards.
3479                    if crate::options::effective_rule_history(self.options.rule.history).is_none()
3480                        && current_rule.links_unchanged(&linked)
3481                    {
3482                        current_rule.relink_child(&child);
3483                        child.parent_rule = Some(current_rule.snapshot());
3484                    }
3485                    completed_rule = self.rule_done_copy(&current_rule);
3486                    // The child about to run shares this rule's node cell,
3487                    // and `child_node` may be a second handle on the very
3488                    // container it will write into. Let go of it for the
3489                    // duration -- see `Rule::park_child_node`. Taken after
3490                    // `rule_done_copy`, so a ruleDone subscriber still sees
3491                    // the rule exactly as it stood, and only when every pop
3492                    // that can resume this rule overwrites the field first
3493                    // (see `park_child_node` and `attempt_recover`).
3494                    if park_child_nodes {
3495                        current_rule.park_child_node();
3496                    }
3497                    stack.push(current_rule);
3498                    current_rule = child;
3499                } else if replace_name.is_some() {
3500                    let (replace_slot, replace_shared, replace_spec) =
3501                        route.take().expect("a replace route was resolved above");
3502                    let mut next = Rule::bound(
3503                        replace_shared.clone(),
3504                        current_rule.node.clone(),
3505                        Some(replace_spec),
3506                        replace_slot,
3507                    );
3508                    next.i = next_rule_id;
3509                    next_rule_id += 1;
3510                    next.d = current_rule.d;
3511                    next.parent_node = current_rule.parent_node.clone();
3512                    next.parent_rule = current_rule.parent_rule.clone();
3513                    next.n = Rc::clone(&current_rule.n);
3514                    next.k = Rc::clone(&current_rule.k);
3515                    current_rule.next_rule_name = Some(replace_shared);
3516                    current_rule.next_rule = Some(next.snapshot());
3517                    let after = self.run_after_actions(
3518                        spec,
3519                        prepared,
3520                        is_open,
3521                        &mut current_rule,
3522                        &mut context,
3523                        ParseSite {
3524                            source: src,
3525                            stack: &stack,
3526                            alts,
3527                        },
3528                    );
3529                    update_partial(mode, &root_node, &current_rule, &stack);
3530                    if self.recover_after_actions(
3531                        after,
3532                        if is_open {
3533                            RuleState::Open
3534                        } else {
3535                            RuleState::Close
3536                        },
3537                        done_alt.clone(),
3538                        src,
3539                        &mut current_rule,
3540                        &mut stack,
3541                        &mut context,
3542                        &mut lexer,
3543                        mode,
3544                    )? {
3545                        continue 'parse;
3546                    }
3547                    if is_open {
3548                        current_rule.state = RuleState::Close;
3549                    }
3550                    next.prev_rule = Some(bounded_history(
3551                        current_rule.snapshot(),
3552                        self.options.rule.history,
3553                        Link::Prev,
3554                    ));
3555                    // The rule being replaced stops existing here. If it is
3556                    // the one its parent PUSHED, the parent's `child` link
3557                    // stays on it -- TypeScript never relinks `rule.child`
3558                    // (rules.ts:665) and neither does Go (rule.go:1280) --
3559                    // so freeze the node cell and the record it ended on
3560                    // before it goes.
3561                    if let Some(parent) = stack.last_mut() {
3562                        parent.freeze_child(&current_rule);
3563                    }
3564                    // Moved rather than cloned: this arm hands the
3565                    // finished rule over instead of copying it, so the
3566                    // gate above has nothing to save here.
3567                    completed_rule = Some(current_rule);
3568                    current_rule = next;
3569                } else if is_open {
3570                    current_rule.next_rule_name = Some(current_rule.name.clone());
3571                    current_rule.next_rule = Some(current_rule.snapshot());
3572                    let after = self.run_after_actions(
3573                        spec,
3574                        prepared,
3575                        true,
3576                        &mut current_rule,
3577                        &mut context,
3578                        ParseSite {
3579                            source: src,
3580                            stack: &stack,
3581                            alts,
3582                        },
3583                    );
3584                    update_partial(mode, &root_node, &current_rule, &stack);
3585                    if self.recover_after_actions(
3586                        after,
3587                        RuleState::Open,
3588                        done_alt.clone(),
3589                        src,
3590                        &mut current_rule,
3591                        &mut stack,
3592                        &mut context,
3593                        &mut lexer,
3594                        mode,
3595                    )? {
3596                        continue 'parse;
3597                    }
3598                    current_rule.state = RuleState::Close;
3599                    completed_rule = self.rule_done_copy(&current_rule);
3600                } else {
3601                    // Close phase pop
3602                    current_rule.next_rule_name = stack.last().map(|rule| rule.name.clone());
3603                    current_rule.next_rule = stack.last().map(Rule::snapshot);
3604                    let after = self.run_after_actions(
3605                        spec,
3606                        prepared,
3607                        false,
3608                        &mut current_rule,
3609                        &mut context,
3610                        ParseSite {
3611                            source: src,
3612                            stack: &stack,
3613                            alts,
3614                        },
3615                    );
3616                    update_partial(mode, &root_node, &current_rule, &stack);
3617                    if self.recover_after_actions(
3618                        after,
3619                        RuleState::Close,
3620                        done_alt.clone(),
3621                        src,
3622                        &mut current_rule,
3623                        &mut stack,
3624                        &mut context,
3625                        &mut lexer,
3626                        mode,
3627                    )? {
3628                        continue 'parse;
3629                    }
3630                    let parent = stack.pop();
3631                    completed_rule = self.rule_done_copy(&current_rule);
3632                    if let Some(mut parent) = parent {
3633                        parent.accept_child(&current_rule);
3634                        bound_child_link(&mut parent, self.options.rule.history);
3635                        current_rule = parent;
3636                    } else {
3637                        // Root rule popped! Done.
3638                        completed_value = Some(current_rule.node.borrow().clone());
3639                    }
3640                }
3641                // Read after every pass, subscribed or not, so that the
3642                // pass that opened or closed a probe is the only one its
3643                // flag covers.
3644                let probe = context.probe_take() || probe_at_start;
3645                if let Some(completed_rule) = &completed_rule {
3646                    self.notify_rule_done(
3647                        completed_rule,
3648                        &context,
3649                        if is_open {
3650                            RuleState::Open
3651                        } else {
3652                            RuleState::Close
3653                        },
3654                        done_alt,
3655                        probe,
3656                        src,
3657                        &stack,
3658                    )?;
3659                }
3660                if let Some(value) = completed_value {
3661                    final_value = Some(value);
3662                    break;
3663                }
3664                update_partial(mode, &root_node, &current_rule, &stack);
3665            } else if alts.is_empty() {
3666                // A state with no alternatives performs an implicit empty
3667                // pass. It still resolves next and runs lifecycle after-actions.
3668                let completed_rule: Option<Rule>;
3669                let mut completed_value = None;
3670                if is_open {
3671                    current_rule.next_rule_name = Some(current_rule.name.clone());
3672                    current_rule.next_rule = Some(current_rule.snapshot());
3673                    let after = self.run_after_actions(
3674                        spec,
3675                        prepared,
3676                        true,
3677                        &mut current_rule,
3678                        &mut context,
3679                        ParseSite {
3680                            source: src,
3681                            stack: &stack,
3682                            alts,
3683                        },
3684                    );
3685                    update_partial(mode, &root_node, &current_rule, &stack);
3686                    if self.recover_after_actions(
3687                        after,
3688                        RuleState::Open,
3689                        None,
3690                        src,
3691                        &mut current_rule,
3692                        &mut stack,
3693                        &mut context,
3694                        &mut lexer,
3695                        mode,
3696                    )? {
3697                        continue 'parse;
3698                    }
3699                    current_rule.state = RuleState::Close;
3700                    completed_rule = self.rule_done_copy(&current_rule);
3701                } else {
3702                    current_rule.next_rule_name = stack.last().map(|rule| rule.name.clone());
3703                    current_rule.next_rule = stack.last().map(Rule::snapshot);
3704                    let after = self.run_after_actions(
3705                        spec,
3706                        prepared,
3707                        false,
3708                        &mut current_rule,
3709                        &mut context,
3710                        ParseSite {
3711                            source: src,
3712                            stack: &stack,
3713                            alts,
3714                        },
3715                    );
3716                    update_partial(mode, &root_node, &current_rule, &stack);
3717                    if self.recover_after_actions(
3718                        after,
3719                        RuleState::Close,
3720                        None,
3721                        src,
3722                        &mut current_rule,
3723                        &mut stack,
3724                        &mut context,
3725                        &mut lexer,
3726                        mode,
3727                    )? {
3728                        continue 'parse;
3729                    }
3730                    let parent = stack.pop();
3731                    completed_rule = self.rule_done_copy(&current_rule);
3732                    if let Some(mut parent) = parent {
3733                        parent.accept_child(&current_rule);
3734                        bound_child_link(&mut parent, self.options.rule.history);
3735                        current_rule = parent;
3736                    } else {
3737                        completed_value = Some(current_rule.node.borrow().clone());
3738                    }
3739                }
3740                let probe = context.probe_take() || probe_at_start;
3741                if let Some(completed_rule) = &completed_rule {
3742                    self.notify_rule_done(
3743                        completed_rule,
3744                        &context,
3745                        if is_open {
3746                            RuleState::Open
3747                        } else {
3748                            RuleState::Close
3749                        },
3750                        None,
3751                        probe,
3752                        src,
3753                        &stack,
3754                    )?;
3755                }
3756                if let Some(value) = completed_value {
3757                    final_value = Some(value);
3758                    break;
3759                }
3760                update_partial(mode, &root_node, &current_rule, &stack);
3761            } else {
3762                // Declared alternatives exist, but none matched.
3763                if is_open {
3764                    if let Err(error) = self.ensure_lookahead(
3765                        &mut lexer,
3766                        &mut context,
3767                        &mut current_rule,
3768                        1,
3769                        mode,
3770                        ParseSite {
3771                            source: src,
3772                            stack: &stack,
3773                            alts,
3774                        },
3775                        Fetch::Rule,
3776                    ) {
3777                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
3778                    }
3779                    if let Some(capture) = mode.continuation.as_deref_mut() {
3780                        let base = failed_alt_tins(&context, alts, &self.options);
3781                        capture.failure = continuation_tins(
3782                            &context,
3783                            &current_rule,
3784                            &stack,
3785                            &self.rules,
3786                            &self.options,
3787                            0,
3788                            Some(&base),
3789                        );
3790                    }
3791                    let t0 = context.t.first().cloned();
3792                    let (src_token, si, ri, ci) = if let Some(t) = t0.as_ref() {
3793                        (t.src.to_string(), t.site.pos, t.site.ri, t.site.ci)
3794                    } else {
3795                        (String::new(), src.len(), 1, 1)
3796                    };
3797                    let code = t0
3798                        .as_ref()
3799                        .map_or("unexpected", |t| deferred_error_code(t, mode.recovering));
3800                    let error = TabnasError::new(code, src_token, src, si, ri, ci);
3801                    let done_alt = (!alts.is_empty() && !self.rule_done_subscribers.is_empty())
3802                        .then(|| RuleDoneAlt {
3803                            b: 0,
3804                            g: Vec::new(),
3805                            p: String::new(),
3806                            r: String::new(),
3807                            err: t0.clone(),
3808                        });
3809                    let error = self.attach_error(error, &current_rule, &stack, alts, t0.as_ref());
3810                    self.recover_error_pass(
3811                        error,
3812                        RuleState::Open,
3813                        done_alt,
3814                        false,
3815                        src,
3816                        &mut current_rule,
3817                        &mut stack,
3818                        &mut context,
3819                        &mut lexer,
3820                        mode,
3821                    )?;
3822                    continue;
3823                } else {
3824                    if let Err(error) = self.ensure_lookahead(
3825                        &mut lexer,
3826                        &mut context,
3827                        &mut current_rule,
3828                        1,
3829                        mode,
3830                        ParseSite {
3831                            source: src,
3832                            stack: &stack,
3833                            alts,
3834                        },
3835                        Fetch::Rule,
3836                    ) {
3837                        return Err(self.attach_error(error, &current_rule, &stack, alts, None));
3838                    }
3839                    if let Some(capture) = mode.continuation.as_deref_mut() {
3840                        let base = failed_alt_tins(&context, alts, &self.options);
3841                        capture.failure = continuation_tins(
3842                            &context,
3843                            &current_rule,
3844                            &stack,
3845                            &self.rules,
3846                            &self.options,
3847                            0,
3848                            Some(&base),
3849                        );
3850                    }
3851                    let token = context.t.first().cloned();
3852                    let (source, pos, row, col) = token.as_ref().map_or_else(
3853                        || (String::new(), src.chars().count(), 1, 1),
3854                        |value| {
3855                            (
3856                                value.src.to_string(),
3857                                value.site.pos,
3858                                value.site.ri,
3859                                value.site.ci,
3860                            )
3861                        },
3862                    );
3863                    let code = token
3864                        .as_ref()
3865                        .map_or("unexpected", |t| deferred_error_code(t, mode.recovering));
3866                    let error = TabnasError::new(code, source, src, pos, row, col);
3867                    let done_alt = Some(RuleDoneAlt {
3868                        b: 0,
3869                        g: Vec::new(),
3870                        p: String::new(),
3871                        r: String::new(),
3872                        err: token.clone(),
3873                    });
3874                    let error =
3875                        self.attach_error(error, &current_rule, &stack, alts, token.as_ref());
3876                    self.recover_error_pass(
3877                        error,
3878                        RuleState::Close,
3879                        done_alt,
3880                        false,
3881                        src,
3882                        &mut current_rule,
3883                        &mut stack,
3884                        &mut context,
3885                        &mut lexer,
3886                        mode,
3887                    )?;
3888                    continue;
3889                }
3890            }
3891        }
3892
3893        let res = final_value.unwrap_or(Value::Null).unwrap_undefined();
3894        if mode.recovering {
3895            mode.partial = Some(PartialValue::Complete(res.clone()));
3896        }
3897
3898        // Post-loop check: ensure no unexpected trailing tokens. Recovery
3899        // keeps the completed value and reports the trailing fault. No
3900        // option turns the check off: `rule.finish` is the grammar's
3901        // end-of-source switch, kept in the options for its `@finish` to
3902        // read, not this check's (#250).
3903        if let Err(error) = self.ensure_lookahead(
3904            &mut lexer,
3905            &mut context,
3906            &mut current_rule,
3907            1,
3908            mode,
3909            ParseSite {
3910                source: src,
3911                stack: &stack,
3912                alts: &[],
3913            },
3914            Fetch::Trailing,
3915        ) {
3916            let error = self.attach_error(error, &current_rule, &stack, &[], None);
3917            if mode.recovering {
3918                mode.errors.push(error.clone());
3919                context.errs.push(error);
3920                return Ok(res);
3921            }
3922            return Err(error);
3923        }
3924        if let Some(t0) = context.t.first() {
3925            if t0.tin != TIN_ZZ {
3926                let code = if t0.tin == TIN_BD && !t0.why.is_empty() {
3927                    t0.why.as_str()
3928                } else {
3929                    "unexpected"
3930                };
3931                let error =
3932                    TabnasError::new(code, &*t0.src, src, t0.site.pos, t0.site.ri, t0.site.ci);
3933                let error = self.attach_error(
3934                    error,
3935                    &current_rule,
3936                    &stack,
3937                    &[AltSpec {
3938                        s: vec![vec![TIN_ZZ]],
3939                        ..Default::default()
3940                    }],
3941                    Some(t0),
3942                );
3943                if mode.recovering {
3944                    mode.errors.push(error.clone());
3945                    context.errs.push(error);
3946                    return Ok(res);
3947                }
3948                return Err(error);
3949            }
3950        }
3951        if self
3952            .options
3953            .result
3954            .fail
3955            .iter()
3956            .any(|failed| failed.deep_equal(&res))
3957        {
3958            let token = context.t.first();
3959            let error = token.map_or_else(
3960                || TabnasError::new("unexpected", "", src, 0, 1, 1),
3961                |token| {
3962                    TabnasError::new(
3963                        "unexpected",
3964                        &*token.src,
3965                        src,
3966                        token.site.pos,
3967                        token.site.ri,
3968                        token.site.ci,
3969                    )
3970                },
3971            );
3972            if mode.recovering {
3973                mode.errors.push(error.clone());
3974                context.errs.push(error);
3975                return Ok(res);
3976            }
3977            return Err(error);
3978        }
3979        Ok(res)
3980    }
3981}
3982
3983/// Keep a handle to the best partial node the recovery path would return.
3984///
3985/// Fifteen sites in the parse loop call this, twelve times per input
3986/// construct on the benchmark grammars, and outside recovery every one of them is a
3987/// load and a branch wrapped in a call. The guard is inline so the call
3988/// goes away. Inside recovery this deliberately clones only an `Rc` node
3989/// handle, never the `Value` being built: a `Value` snapshot keeps its
3990/// container shared and turns the next mutation into a copy of the entire
3991/// accumulated prefix.
3992///
3993/// The value read at the end is the one the last site would have taken:
3994/// the node is chosen by the same test, in the same order, and it keeps
3995/// the node even when recovery then pops the rules that held it. Only a
3996/// write to that node between the last site and the failure can tell the
3997/// two apart -- an action or callback that changes the node and then
3998/// fails, or is followed by a matched action whose error recovery gives up
3999/// on -- and the value is then the node as the failure left it, which is
4000/// what TypeScript returns: it reads the node in its `catch`
4001/// (`ts/src/parser.ts`), not before the step that failed.
4002#[inline]
4003fn update_partial(
4004    mode: &mut ParseMode<'_>,
4005    root_node: &Rc<RefCell<Value>>,
4006    current_rule: &Rule,
4007    stack: &[Rule],
4008) {
4009    if mode.recovering {
4010        mode.partial = best_partial_node(root_node, current_rule, stack).map(PartialValue::Node);
4011    }
4012}
4013
4014#[inline(never)]
4015fn best_partial_node(
4016    root_node: &Rc<RefCell<Value>>,
4017    current_rule: &Rule,
4018    stack: &[Rule],
4019) -> Option<Rc<RefCell<Value>>> {
4020    let usable = |node: &Rc<RefCell<Value>>| {
4021        (!matches!(*node.borrow(), Value::Undefined | Value::Null)).then(|| Rc::clone(node))
4022    };
4023
4024    usable(root_node)
4025        .or_else(|| stack.iter().find_map(|rule| usable(&rule.node)))
4026        .or_else(|| usable(&current_rule.node))
4027}
4028
4029fn error_token(error: &TabnasError) -> Token {
4030    let byte_position = error
4031        .full_source
4032        .char_indices()
4033        .nth(error.pos)
4034        .map_or(error.full_source.len(), |(index, _)| index);
4035    let mut token = Token::new(
4036        "#BD",
4037        TIN_BD,
4038        Value::Undefined,
4039        error.src.clone(),
4040        crate::Point {
4041            len: error.len,
4042            site: crate::Site {
4043                si: byte_position,
4044                pos: error.pos,
4045                ri: error.row,
4046                ci: error.col,
4047            },
4048        },
4049    );
4050    token.err = crate::TokenCode::from(error.code.as_str());
4051    token.why = token.err.clone();
4052    token
4053}
4054
4055/// The code an error with no matching alternative takes from the first
4056/// token of the lookahead, read as the canonical engine reads it at the
4057/// same point. Fail-fast, its deferred throw takes a bad token's why, else
4058/// `unexpected` (`bad.why || UNEXPECTED` in ts/src/rules.ts); when the
4059/// parse is recovering, `attemptRecover` takes the token's err ahead of
4060/// its why (`tkn.err || tkn.why`). This engine's own lexer faults set why
4061/// and err alike, so only a token a matcher built with err alone tells
4062/// the two apart: `unexpected` fail-fast, its err under recovery, in every
4063/// runtime (#285).
4064fn deferred_error_code(token: &Token, recovering: bool) -> &str {
4065    if token.tin != TIN_BD {
4066        "unexpected"
4067    } else if recovering && !token.err.is_empty() {
4068        &token.err
4069    } else if !token.why.is_empty() {
4070        &token.why
4071    } else {
4072        "unexpected"
4073    }
4074}
4075
4076fn raised_error_code(token: &Token) -> &str {
4077    if !token.err.is_empty() {
4078        &token.err
4079    } else if !token.why.is_empty() {
4080        &token.why
4081    } else {
4082        "unexpected"
4083    }
4084}
4085
4086fn mid_construct(code: &str) -> bool {
4087    matches!(code, "unprintable" | "invalid_unicode" | "invalid_ascii")
4088}
4089
4090/// Record a bad token met at a rule's fetch under recovery, in the order
4091/// TypeScript's `parse_alts` does it: a token inside the run the last one
4092/// began grows that run's error rather than being listed again; a new run
4093/// inside the suppress window of the recovery before it is a cascade of
4094/// that fault and is dropped; anything else is recorded. Returns whether
4095/// the fetch goes on past the token. It does not when the run outgrows
4096/// `maxSkip`, or when the list has outgrown `maxRecoveries`, a cap read
4097/// after recording, so the error that stops the parse is listed.
4098fn absorb_lex_error(
4099    error: &TabnasError,
4100    context: &mut Context,
4101    options: &Options,
4102    errors: &mut Vec<TabnasError>,
4103) -> bool {
4104    let recover = &options.parse.recover;
4105    let run = context
4106        .bad_error
4107        .filter(|index| *index < errors.len())
4108        .filter(|_| context.bad_to.is_some_and(|bad_to| error.pos <= bad_to));
4109    if let Some(index) = run {
4110        let previous = &mut errors[index];
4111        let recovered = previous.recovered.get_or_insert(crate::RecoveredAt {
4112            skipped: 0,
4113            sync: None,
4114            bad: true,
4115        });
4116        recovered.skipped = recovered.skipped.saturating_add(1);
4117        let skipped = recovered.skipped;
4118        if let Some(context_previous) = context.errs.get_mut(index) {
4119            *context_previous = previous.clone();
4120        }
4121        if recover.max_skip < skipped {
4122            return false;
4123        }
4124    } else if context
4125        .recover_at
4126        .is_some_and(|at| context.v_abs.saturating_sub(at) < recover.suppress)
4127    {
4128        context.bad_error = None;
4129    } else {
4130        let mut recorded = error.clone();
4131        recorded.recovered = Some(crate::RecoveredAt {
4132            skipped: 1,
4133            sync: None,
4134            bad: true,
4135        });
4136        errors.push(recorded.clone());
4137        context.errs.push(recorded);
4138        context.bad_error = Some(errors.len() - 1);
4139        context.recover_at = Some(context.v_abs);
4140    }
4141    context.bad_to = Some(error.pos.saturating_add(error.len.max(1)));
4142    errors.len() <= recover.max_recoveries
4143}
4144
4145fn slot_matches(slot: &[Tin], tin: Tin) -> bool {
4146    tin != TIN_BD && (slot.is_empty() || slot.contains(&tin) || slot.contains(&TIN_AA))
4147}
4148
4149fn alt_match_depth(alt: &AltSpec, context: &Context) -> usize {
4150    let mut depth = 0;
4151    while depth < alt.s.len() {
4152        let Some(token) = context.t.get(depth) else {
4153            break;
4154        };
4155        if !slot_matches(&alt.s[depth], token.tin) {
4156            break;
4157        }
4158        depth += 1;
4159    }
4160    depth
4161}
4162
4163fn completion_tins(slot: &[Tin]) -> impl Iterator<Item = Tin> + '_ {
4164    slot.iter()
4165        .copied()
4166        .chain(slot.is_empty().then_some(TIN_AA))
4167}
4168
4169fn failed_alt_tins(context: &Context, alts: &[AltSpec], options: &Options) -> Vec<Tin> {
4170    let mut out = BTreeSet::new();
4171    for alt in alts {
4172        if !groups_enabled(alt, options) {
4173            continue;
4174        }
4175        let depth = alt_match_depth(alt, context);
4176        if let Some(slot) = alt.s.get(depth) {
4177            out.extend(completion_tins(slot));
4178        }
4179    }
4180    out.into_iter().collect()
4181}
4182
4183fn lead_tins(alts: &[AltSpec], options: &Options, out: &mut BTreeSet<Tin>) {
4184    for alt in alts {
4185        if !groups_enabled(alt, options) {
4186            continue;
4187        }
4188        if let Some(slot) = alt.s.first() {
4189            out.extend(completion_tins(slot));
4190        }
4191    }
4192}
4193
4194fn has_empty_close(spec: &RuleSpec, options: &Options) -> bool {
4195    spec.close
4196        .iter()
4197        .any(|alt| groups_enabled(alt, options) && alt.s.is_empty())
4198}
4199
4200fn alt_has_sync_group(alt: &AltSpec, sync_groups: &[String]) -> bool {
4201    alt.g
4202        .split(',')
4203        .map(str::trim)
4204        .any(|tag| sync_groups.iter().any(|wanted| wanted == tag))
4205}
4206
4207fn add_close_tins(
4208    rule: &Rule,
4209    rules: &IndexMap<String, Arc<RuleSpec>>,
4210    options: &Options,
4211    tagged_only: bool,
4212    out: &mut BTreeSet<Tin>,
4213) {
4214    let Some(spec) = rules.get(&*rule.name) else {
4215        return;
4216    };
4217    for alt in &spec.close {
4218        if !groups_enabled(alt, options)
4219            || (tagged_only && !alt_has_sync_group(alt, &options.parse.recover.sync_groups))
4220        {
4221            continue;
4222        }
4223        if let Some(slot) = alt.s.first() {
4224            out.extend(completion_tins(slot));
4225        }
4226    }
4227}
4228
4229fn compute_sync_tins(
4230    rule: &Rule,
4231    stack: &[Rule],
4232    rules: &IndexMap<String, Arc<RuleSpec>>,
4233    options: &Options,
4234) -> BTreeSet<Tin> {
4235    let mut out = BTreeSet::new();
4236    add_close_tins(rule, rules, options, true, &mut out);
4237    for parent in stack.iter().rev() {
4238        add_close_tins(parent, rules, options, true, &mut out);
4239    }
4240    if out.is_empty() {
4241        add_close_tins(rule, rules, options, false, &mut out);
4242        for parent in stack.iter().rev() {
4243            add_close_tins(parent, rules, options, false, &mut out);
4244        }
4245    }
4246    for name in &options.parse.recover.sync_tokens {
4247        if let Some(tin) = options.token(name) {
4248            out.insert(tin);
4249        }
4250        if let Some(tins) = options.token_set.get(name.trim_start_matches('#')) {
4251            out.extend(tins.iter().copied());
4252        }
4253    }
4254    out
4255}
4256
4257fn accepts_close(
4258    rule: &Rule,
4259    tin: Tin,
4260    rules: &IndexMap<String, Arc<RuleSpec>>,
4261    options: &Options,
4262) -> bool {
4263    rules.get(&*rule.name).is_some_and(|spec| {
4264        spec.close.iter().any(|alt| {
4265            groups_enabled(alt, options)
4266                && (alt.s.is_empty() || alt.s.first().is_some_and(|slot| slot_matches(slot, tin)))
4267        })
4268    })
4269}
4270
4271fn add_openers(
4272    name: &str,
4273    rules: &IndexMap<String, Arc<RuleSpec>>,
4274    options: &Options,
4275    opened: &mut BTreeSet<String>,
4276    out: &mut BTreeSet<Tin>,
4277) {
4278    if name.is_empty() || !opened.insert(name.to_owned()) {
4279        return;
4280    }
4281    let Some(spec) = rules.get(name) else {
4282        return;
4283    };
4284    lead_tins(&spec.open, options, out);
4285    for alt in &spec.open {
4286        if !groups_enabled(alt, options) || !alt.s.is_empty() {
4287            continue;
4288        }
4289        if let Some(push) = alt.p.as_deref() {
4290            add_openers(push, rules, options, opened, out);
4291        }
4292        if let Some(replace) = alt.r.as_deref() {
4293            add_openers(replace, rules, options, opened, out);
4294        }
4295    }
4296}
4297
4298fn continuation_tins(
4299    context: &Context,
4300    rule: &Rule,
4301    stack: &[Rule],
4302    rules: &IndexMap<String, Arc<RuleSpec>>,
4303    options: &Options,
4304    query_pos: usize,
4305    failed: Option<&[Tin]>,
4306) -> Vec<Tin> {
4307    let Some(spec) = rules.get(&*rule.name) else {
4308        return Vec::new();
4309    };
4310    let state_alts = if rule.state == RuleState::Open {
4311        &spec.open
4312    } else {
4313        &spec.close
4314    };
4315    let mut out = BTreeSet::new();
4316
4317    if let Some(failed) = failed.filter(|tins| !tins.is_empty()) {
4318        out.extend(failed.iter().copied());
4319    } else {
4320        for alt in state_alts {
4321            if !groups_enabled(alt, options) {
4322                continue;
4323            }
4324            let depth = alt_match_depth(alt, context);
4325            if depth == query_pos {
4326                if let Some(slot) = alt.s.get(depth) {
4327                    out.extend(completion_tins(slot));
4328                }
4329            }
4330        }
4331    }
4332
4333    // If the current rule can close without consuming a token, closing
4334    // tokens accepted by each parent are legal at the same point too.
4335    let mut close_rule = rule;
4336    let mut parent_index = stack.len();
4337    while let Some(close_spec) = rules.get(&*close_rule.name) {
4338        if !has_empty_close(close_spec, options) || parent_index == 0 {
4339            break;
4340        }
4341        parent_index -= 1;
4342        let parent = &stack[parent_index];
4343        if let Some(parent_spec) = rules.get(&*parent.name) {
4344            lead_tins(&parent_spec.close, options, &mut out);
4345        }
4346        close_rule = parent;
4347    }
4348
4349    // A fully matched alternate can immediately hand control to a pushed or
4350    // replacement rule. Follow empty opening hand-offs transitively.
4351    let mut opened = BTreeSet::new();
4352    for alt in state_alts {
4353        if !groups_enabled(alt, options) || alt_match_depth(alt, context) != alt.s.len() {
4354            continue;
4355        }
4356        // A callback backtrack is only knowable while executing the match.
4357        // Do not speculate that its static default is the handover point.
4358        if alt.b_fn.is_some() {
4359            continue;
4360        }
4361        if alt.s.len().checked_sub(alt.b) != Some(query_pos) {
4362            continue;
4363        }
4364        if let Some(push) = alt.p.as_deref() {
4365            add_openers(push, rules, options, &mut opened, &mut out);
4366        }
4367        if let Some(replace) = alt.r.as_deref() {
4368            add_openers(replace, rules, options, &mut opened, &mut out);
4369        }
4370    }
4371
4372    out.into_iter().collect()
4373}
4374
4375/// The group tags a comma-separated group list declares.
4376///
4377/// One definition, because two places ask: the include/exclude filter in
4378/// `groups_enabled`, and the list the engine publishes into `matched.g`.
4379/// They have to agree on what a tag is -- trimmed, and never empty.
4380fn listed(list: &str) -> impl Iterator<Item = &str> {
4381    list.split(',')
4382        .map(str::trim)
4383        .filter(|entry| !entry.is_empty())
4384}
4385
4386pub(crate) fn groups_enabled(alt: &AltSpec, options: &Options) -> bool {
4387    // With neither an include nor an exclude list there is nothing to
4388    // test against, so every alternate is enabled whatever groups it
4389    // declares. That is the usual case, and it is asked once per
4390    // alternate per iteration.
4391    let include = options.rule.include.as_str();
4392    let exclude = options.rule.exclude.as_str();
4393    if include.is_empty() && exclude.is_empty() {
4394        return true;
4395    }
4396    // Iterators rather than three collected `Vec<&str>`. The question is
4397    // the same one and the answer is the same answer; the three heap
4398    // allocations per call were not part of either. The shipped JSON
4399    // preset sets `rule.include` to "json", so the early return above
4400    // never fires for it and every alternate of every rule step paid
4401    // them.
4402    let declares = |wanted: &str| listed(&alt.g).any(|group| group == wanted);
4403    let included = listed(include).next().is_none() || listed(include).any(&declares);
4404    included && !listed(exclude).any(&declares)
4405}
4406
4407fn builtin_condition_matches(reference: Option<&str>, rule: &Rule) -> bool {
4408    let phase = match rule.k.get("pd_phase") {
4409        Some(Value::Number(value)) => *value as i32,
4410        _ => 0,
4411    };
4412    match reference {
4413        None => true,
4414        Some("@probePhase0$") => phase == 0,
4415        Some("@probePhase1$") => phase == 1,
4416        Some("@probePhase2$") => phase == 2,
4417        Some(_) => false,
4418    }
4419}
4420
4421fn conditions_match(conditions: &[Condition], rule: &Rule, ancestors: &[Rule]) -> bool {
4422    conditions.iter().all(|condition| {
4423        let resolved = resolve_condition_path(rule, ancestors, &condition.path);
4424        if condition.op == CompareOp::Exist {
4425            let exists = condition_exists(rule, ancestors, &condition.path);
4426            let wanted = matches!(condition.value, Value::Bool(true));
4427            return exists == wanted;
4428        }
4429        let Some(actual) = resolved else {
4430            return !matches!(condition.op, CompareOp::Eq);
4431        };
4432        match condition.op {
4433            CompareOp::Eq => actual.deep_equal(&condition.value),
4434            CompareOp::Ne => !actual.deep_equal(&condition.value),
4435            CompareOp::Lt => ordered(&actual, &condition.value).is_none_or(|value| value < 0),
4436            CompareOp::Lte => ordered(&actual, &condition.value).is_none_or(|value| value <= 0),
4437            CompareOp::Gt => ordered(&actual, &condition.value).is_none_or(|value| value > 0),
4438            CompareOp::Gte => ordered(&actual, &condition.value).is_none_or(|value| value >= 0),
4439            CompareOp::Exist => unreachable!("handled above"),
4440        }
4441    })
4442}
4443
4444fn ordered(left: &Value, right: &Value) -> Option<i8> {
4445    match (left, right) {
4446        (Value::Number(left), Value::Number(right)) => Some(if left < right {
4447            -1
4448        } else if left > right {
4449            1
4450        } else {
4451            0
4452        }),
4453        (Value::String(left), Value::String(right)) => Some(match left.cmp(right) {
4454            std::cmp::Ordering::Less => -1,
4455            std::cmp::Ordering::Equal => 0,
4456            std::cmp::Ordering::Greater => 1,
4457        }),
4458        _ => None,
4459    }
4460}
4461
4462fn condition_exists(rule: &Rule, ancestors: &[Rule], path: &[String]) -> bool {
4463    if path.first().map(String::as_str) == Some("n") && path.len() == 2 {
4464        rule.n.contains_key(&path[1])
4465    } else if path.first().map(String::as_str) == Some("parent") {
4466        ancestors
4467            .split_last()
4468            .is_some_and(|(parent, parent_ancestors)| {
4469                condition_exists(parent, parent_ancestors, &path[1..])
4470            })
4471    } else if path.first().map(String::as_str) == Some("child") {
4472        rule.child_rule
4473            .as_deref()
4474            .is_some_and(|child| snapshot_condition_exists(child, &path[1..]))
4475    } else if path.first().map(String::as_str) == Some("prev") {
4476        rule.prev_rule
4477            .as_deref()
4478            .is_some_and(|prev| snapshot_condition_exists(prev, &path[1..]))
4479    } else if path.first().map(String::as_str) == Some("next") {
4480        if let Some(next) = rule.next_rule.as_deref() {
4481            snapshot_condition_exists(next, &path[1..])
4482        } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4483            condition_exists(rule, ancestors, &path[1..])
4484        } else {
4485            false
4486        }
4487    } else {
4488        resolve_condition_path(rule, ancestors, path).is_some()
4489    }
4490}
4491
4492fn resolve_condition_path(rule: &Rule, ancestors: &[Rule], path: &[String]) -> Option<Value> {
4493    let root = path.first()?.as_str();
4494    let rest = &path[1..];
4495    match root {
4496        "n" if rest.len() == 1 => Some(Value::Number(*rule.n.get(&rest[0]).unwrap_or(&0) as f64)),
4497        "u" => map_path(&rule.u, rest),
4498        "k" => map_path(&rule.k, rest),
4499        "d" if rest.is_empty() => Some(Value::Number(rule.d as f64)),
4500        "i" if rest.is_empty() => Some(Value::Number(rule.i as f64)),
4501        "name" if rest.is_empty() => Some(Value::String(rule.name.to_string())),
4502        "state" if rest.is_empty() => Some(Value::String(
4503            match rule.state {
4504                RuleState::Open => "o",
4505                RuleState::Close => "c",
4506            }
4507            .into(),
4508        )),
4509        "node" => value_path(rule.node.borrow().clone(), rest),
4510        "need" if rest.is_empty() => Some(Value::Number(rule.need as f64)),
4511        "oN" if rest.is_empty() => Some(Value::Number(rule.o.len() as f64)),
4512        "cN" if rest.is_empty() => Some(Value::Number(rule.c.len() as f64)),
4513        "o" => token_list_path(&rule.o, rest),
4514        "c" => token_list_path(&rule.c, rest),
4515        "o0" => token_path(rule.o.first(), rest),
4516        "o1" => token_path(rule.o.get(1), rest),
4517        "c0" => token_path(rule.c.first(), rest),
4518        "c1" => token_path(rule.c.get(1), rest),
4519        "parent" => {
4520            let (parent, parent_ancestors) = ancestors.split_last()?;
4521            resolve_condition_path(parent, parent_ancestors, rest)
4522        }
4523        "child" => resolve_snapshot_path(rule.child_rule.as_deref()?, rest),
4524        "prev" => resolve_snapshot_path(rule.prev_rule.as_deref()?, rest),
4525        "next" => {
4526            if let Some(next) = rule.next_rule.as_deref() {
4527                resolve_snapshot_path(next, rest)
4528            } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4529                resolve_condition_path(rule, ancestors, rest)
4530            } else {
4531                None
4532            }
4533        }
4534        "spec" if rest == ["name"] => Some(Value::String(rule.name.to_string())),
4535        _ => None,
4536    }
4537}
4538
4539/// Which link a bounded snapshot becomes (see [`bounded_history`]).
4540#[derive(Clone, Copy, PartialEq, Eq)]
4541enum Link {
4542    /// The `parent_rule` a pushed child keeps: the pusher once it has
4543    /// linked the child, made at the end of the push arm.
4544    Parent,
4545    /// The pusher before it links the child, made at the start of the
4546    /// push arm. It survives as the `parent_rule` of the child's snapshot
4547    /// taken at the push: under a bound the one the pusher links as
4548    /// `child`, and with none the one the child reads as
4549    /// `parent.child.parent.child`, since the push arm then links the
4550    /// child again once the pusher has linked it, and gives the child the
4551    /// pusher as it then stands (see [`Rule::relink_child`]). That second
4552    /// link is made after the pushing alternate's after-actions have run,
4553    /// where TypeScript and Go link the live rules before them: a state
4554    /// action on the pusher's close still reads the child pushed before,
4555    /// and six hops from the child still reach this record.
4556    PusherBefore,
4557    /// A replacement's `prev_rule`: the rule it replaces.
4558    Prev,
4559}
4560
4561/// A snapshot to link, bounded by `options.rule.history`
4562/// (`doc/rule-history-bound.md`): a copy that keeps `history - 1`
4563/// predecessors, each a copy the same way, with no `child` or `next`
4564/// links. Those links are what defeat a cut of the predecessors alone:
4565/// a rule's `child` is its finished child, whose `next` leads back to
4566/// the rule's own record, whose `prev` is a copy of its predecessor,
4567/// whose `child` does the same, a ladder through the whole sequence. So
4568/// `prev.child` and `prev.next` resolve to nothing, and so does a
4569/// predecessor's past them. A cut `next` takes its name with it: a
4570/// snapshot whose next has its own name reads itself as `next`, and a
4571/// copy that kept the name would read `prev.next` as `prev`.
4572///
4573/// The `parent` a pushed child keeps ([`Link::Parent`]) keeps the
4574/// pusher's own `child` and `next`, the child itself as it stood when
4575/// pushed, before it had a `next`: no ladder starts there, and
4576/// `parent.child` and `parent.next` read as they do unbounded. The copy
4577/// made before the pusher links the child ([`Link::PusherBefore`]) cuts
4578/// them: its `child` is the pusher's previous child, and a rule that
4579/// pushes again from its close phase would link every child it pushed,
4580/// each through the one before. So `parent.child.parent.child` and the
4581/// like, the pusher as it stood before the push, resolve to nothing
4582/// under a bound, as they do in TypeScript and Go. With no bound the
4583/// push arm links the child again (see [`Rule::relink_child`]), and
4584/// that path reads the child, as the live links of the other two
4585/// runtimes do.
4586///
4587/// What a rule reads through `prev` (counters, values, tokens, node and
4588/// name) and through `parent` (the pusher and its own parents) is kept.
4589/// A copy is a twenty-field struct with eight `Rc` clones, `history` of
4590/// them per link, and `history` is read as 1 to
4591/// [`crate::options::MAX_RULE_HISTORY`], so a link costs a constant.
4592/// `None` links the snapshot untouched.
4593fn bounded_history(
4594    snapshot: Rc<RuleSnapshot>,
4595    history: Option<usize>,
4596    link: Link,
4597) -> Rc<RuleSnapshot> {
4598    let Some(history) = crate::options::effective_rule_history(history) else {
4599        return snapshot;
4600    };
4601    // The links to copy, nearest first: the snapshot and up to
4602    // `history - 1` of its predecessors. Collected and then rebuilt from
4603    // the far end, with no recursion, so that a bound as long as the
4604    // chain costs stack nothing, as `RuleSnapshot`'s `Drop` walks the
4605    // same chain without it.
4606    let mut links: Vec<&Rc<RuleSnapshot>> = Vec::with_capacity(history);
4607    let mut current = Some(&snapshot);
4608    while let Some(snapshot) = current {
4609        if links.len() == history {
4610            break;
4611        }
4612        links.push(snapshot);
4613        current = snapshot.prev_rule.as_ref();
4614    }
4615    let mut prev: Option<Rc<RuleSnapshot>> = None;
4616    // `depth` counts back from the snapshot itself, which is 0.
4617    for (depth, original) in links.into_iter().enumerate().rev() {
4618        let mut copy = (**original).clone();
4619        if depth != 0 || link != Link::Parent {
4620            copy.child_rule = None;
4621            copy.next_rule = None;
4622            copy.next_rule_name = None;
4623        }
4624        copy.prev_rule = prev.take();
4625        prev = Some(Rc::new(copy));
4626    }
4627    prev.expect("at least the snapshot itself is copied")
4628}
4629
4630/// Under a bound, a pusher links the child it pushed, once that child has
4631/// finished, as a bounded copy ([`Link::Prev`]): the child as it ended,
4632/// with no `child` or `next`, as TypeScript's `freezeHistoryChild`
4633/// publishes it. So `child.child`, `child.next` and `next.next` read
4634/// nothing from the pusher under a bound, as in TypeScript and Go
4635/// (`rule-history-bounded-links`), and the finished child keeps nothing
4636/// past itself alive. With no bound the link is the child's record.
4637fn bound_child_link(rule: &mut Rule, history: Option<usize>) {
4638    if crate::options::effective_rule_history(history).is_none() {
4639        return;
4640    }
4641    if let Some(record) = rule.child_rule.take() {
4642        let bounded = bounded_history(record, history, Link::Prev);
4643        rule.next_rule = Some(Rc::clone(&bounded));
4644        rule.child_rule = Some(bounded);
4645    }
4646}
4647
4648fn snapshot_condition_exists(rule: &RuleSnapshot, path: &[String]) -> bool {
4649    if path.first().map(String::as_str) == Some("n") && path.len() == 2 {
4650        rule.n.contains_key(&path[1])
4651    } else if path.first().map(String::as_str) == Some("parent") {
4652        rule.parent_rule
4653            .as_deref()
4654            .is_some_and(|parent| snapshot_condition_exists(parent, &path[1..]))
4655    } else if path.first().map(String::as_str) == Some("child") {
4656        rule.child_rule
4657            .as_deref()
4658            .is_some_and(|child| snapshot_condition_exists(child, &path[1..]))
4659    } else if path.first().map(String::as_str) == Some("prev") {
4660        rule.prev_rule
4661            .as_deref()
4662            .is_some_and(|prev| snapshot_condition_exists(prev, &path[1..]))
4663    } else if path.first().map(String::as_str) == Some("next") {
4664        if let Some(next) = rule.next_rule.as_deref() {
4665            snapshot_condition_exists(next, &path[1..])
4666        } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4667            snapshot_condition_exists(rule, &path[1..])
4668        } else {
4669            false
4670        }
4671    } else {
4672        resolve_snapshot_path(rule, path).is_some()
4673    }
4674}
4675
4676fn resolve_snapshot_path(rule: &RuleSnapshot, path: &[String]) -> Option<Value> {
4677    let root = path.first()?.as_str();
4678    let rest = &path[1..];
4679    match root {
4680        "n" if rest.len() == 1 => Some(Value::Number(*rule.n.get(&rest[0]).unwrap_or(&0) as f64)),
4681        "u" => map_path(&rule.u, rest),
4682        "k" => map_path(&rule.k, rest),
4683        "d" if rest.is_empty() => Some(Value::Number(rule.d as f64)),
4684        "i" if rest.is_empty() => Some(Value::Number(rule.i as f64)),
4685        "name" if rest.is_empty() => Some(Value::String(rule.name.to_string())),
4686        "state" if rest.is_empty() => Some(Value::String(
4687            match rule.state {
4688                RuleState::Open => "o",
4689                RuleState::Close => "c",
4690            }
4691            .into(),
4692        )),
4693        "node" => value_path(rule.node.borrow().clone(), rest),
4694        "need" if rest.is_empty() => Some(Value::Number(rule.need as f64)),
4695        "oN" if rest.is_empty() => Some(Value::Number(rule.o.len() as f64)),
4696        "cN" if rest.is_empty() => Some(Value::Number(rule.c.len() as f64)),
4697        "o" => token_list_path(&rule.o, rest),
4698        "c" => token_list_path(&rule.c, rest),
4699        "o0" => token_path(rule.o.first(), rest),
4700        "o1" => token_path(rule.o.get(1), rest),
4701        "c0" => token_path(rule.c.first(), rest),
4702        "c1" => token_path(rule.c.get(1), rest),
4703        "parent" => resolve_snapshot_path(rule.parent_rule.as_deref()?, rest),
4704        "child" => resolve_snapshot_path(rule.child_rule.as_deref()?, rest),
4705        "prev" => resolve_snapshot_path(rule.prev_rule.as_deref()?, rest),
4706        "next" => {
4707            if let Some(next) = rule.next_rule.as_deref() {
4708                resolve_snapshot_path(next, rest)
4709            } else if rule.next_rule_name.as_deref() == Some(&*rule.name) {
4710                resolve_snapshot_path(rule, rest)
4711            } else {
4712                None
4713            }
4714        }
4715        "spec" if rest == ["name"] => Some(Value::String(rule.name.to_string())),
4716        _ => None,
4717    }
4718}
4719
4720fn map_path(map: &HashMap<String, Value>, path: &[String]) -> Option<Value> {
4721    let (name, rest) = path.split_first()?;
4722    value_path(map.get(name)?.clone(), rest)
4723}
4724
4725fn value_path(mut value: Value, path: &[String]) -> Option<Value> {
4726    for part in path {
4727        value = match value {
4728            Value::Object(map) => map.get(part)?.clone(),
4729            Value::Array(items) => items.get(part.parse::<usize>().ok()?)?.clone(),
4730            _ => return None,
4731        };
4732    }
4733    Some(value)
4734}
4735
4736fn token_list_path(tokens: &[Token], path: &[String]) -> Option<Value> {
4737    let (index, rest) = path.split_first()?;
4738    token_path(tokens.get(index.parse::<usize>().ok()?), rest)
4739}
4740
4741fn token_path(token: Option<&Token>, path: &[String]) -> Option<Value> {
4742    let token = token?;
4743    if path.is_empty() {
4744        let mut value = IndexMap::new();
4745        value.insert("tin".into(), Value::Number(token.tin as f64));
4746        value.insert("name".into(), Value::String(token.name.to_string()));
4747        value.insert("src".into(), Value::String(token.src.to_string()));
4748        value.insert("val".into(), token.val.clone());
4749        value.insert("why".into(), Value::String(token.why.to_string()));
4750        return Some(Value::object(value));
4751    }
4752    let (field, rest) = path.split_first()?;
4753    let value = match field.as_str() {
4754        "tin" => Value::Number(token.tin as f64),
4755        "name" => Value::String(token.name.to_string()),
4756        "src" => Value::String(token.src.to_string()),
4757        "val" => token.val.clone(),
4758        "why" => Value::String(token.why.to_string()),
4759        _ => return None,
4760    };
4761    value_path(value, rest)
4762}
4763
4764#[cfg(test)]
4765mod tests {
4766    use super::*;
4767
4768    /// `expected_tins`, `names` and `prepared` are derived from `rules` and
4769    /// positional in it, and `add_rule` is the only thing that writes any
4770    /// of the four. That is the whole reason `rules` is private: while it was
4771    /// public, an embedder inserting or replacing a rule straight into it
4772    /// left the derived tables describing the rule that used to be there,
4773    /// and lookahead went on gating the custom matchers on that rule's token
4774    /// identities. This asserts the invariant a second write path would
4775    /// break; making `add_rule` keep an existing entry instead of replacing
4776    /// it fails the second assertion.
4777    #[test]
4778    fn replacing_a_rule_replaces_the_tables_derived_from_it() {
4779        let mut parser = Parser::new(crate::Options::default());
4780
4781        let mut first = RuleSpec::new("val");
4782        first.bo.push("@enter".into());
4783        first.open.push(AltSpec {
4784            s: vec![vec![crate::TIN_NR]],
4785            a: vec!["@act".into()],
4786            ..Default::default()
4787        });
4788        parser.add_rule(first);
4789        let slot = parser
4790            .rules()
4791            .get_index_of("val")
4792            .expect("the rule was just installed");
4793        assert_eq!(parser.expected_tins[slot].at(true, 0), [crate::TIN_NR]);
4794        assert_eq!(&*parser.names[slot], "val");
4795        assert_eq!(parser.prepared[slot].before(true).len(), 1);
4796        assert_eq!(parser.prepared[slot].open[0].actions.len(), 1);
4797
4798        let mut second = RuleSpec::new("val");
4799        second.open.push(AltSpec {
4800            s: vec![vec![crate::TIN_ST]],
4801            ..Default::default()
4802        });
4803        parser.add_rule(second);
4804
4805        assert_eq!(parser.rules().len(), 1, "a replacement, not an addition");
4806        assert_eq!(
4807            parser.expected_tins[slot].at(true, 0),
4808            [crate::TIN_ST],
4809            "lookahead would still expect the replaced rule's tokens"
4810        );
4811        // The name table is positional now, so a replacement has to land on
4812        // the index the map kept for the key rather than append beside it:
4813        // an appended handle would leave `names` describing the wrong rule
4814        // at every index past this one.
4815        assert_eq!(parser.names.len(), 1, "one rule, one shared name");
4816        assert_eq!(parser.rules().get_index_of("val"), Some(slot));
4817        assert_eq!(&*parser.names[slot], "val");
4818        // The prepared table is positional for the same reason, and its
4819        // record has to describe the rule that is installed now: the parse
4820        // loop trusts a record only while its spec is the one the rule in
4821        // hand holds, so a record left pointing at the replaced spec is a
4822        // record the loop would stop using at all.
4823        assert_eq!(parser.prepared.len(), 1);
4824        assert_eq!(&*parser.prepared[slot].name, "val");
4825        assert!(Arc::ptr_eq(
4826            &parser.prepared[slot].spec,
4827            &parser.rules()["val"]
4828        ));
4829        // The action orders are derived from the same spec and go stale the
4830        // same way. The replacement declares neither the lifecycle action
4831        // nor the alternate action the first rule did, and an order left
4832        // over from that rule is one the loop would run for it.
4833        assert!(parser.prepared[slot].before(true).is_empty());
4834        assert!(parser.prepared[slot].open[0].actions.is_empty());
4835        assert!(!parser.prepared[slot].open[0].named);
4836    }
4837
4838    /// The accepted-token table is positional now, and the slot a rule
4839    /// carries is a hint rather than an authority: `name` is public and a
4840    /// callback may have written it between one token fetch and the next.
4841    /// What the rule is called is what decides which row answers, exactly
4842    /// as the name-keyed map this replaced decided it, and a name that is
4843    /// installed nowhere expects nothing rather than whatever happens to
4844    /// sit at its slot.
4845    #[test]
4846    fn expected_match_tins_follows_the_rule_name_when_the_slot_goes_stale() {
4847        fn rule_named(name: &str, tin: Tin) -> RuleSpec {
4848            let mut spec = RuleSpec::new(name);
4849            spec.open.push(AltSpec {
4850                s: vec![vec![tin]],
4851                ..Default::default()
4852            });
4853            spec
4854        }
4855
4856        let mut options = crate::Options::default();
4857        let tin = options.register_token("#QQ");
4858        options.match_tokens.insert(
4859            "#QQ".into(),
4860            crate::options::MatchToken {
4861                name: "#QQ".into(),
4862                tin,
4863                matcher: crate::options::MatchTokenMatcher::Regex(regex::Regex::new("^q").unwrap()),
4864                eager: false,
4865            },
4866        );
4867        let mut parser = Parser::new(options);
4868        parser.add_rule(rule_named("val", crate::TIN_NR));
4869        parser.add_rule(rule_named("other", crate::TIN_ST));
4870
4871        let val_slot = parser.rules().get_index_of("val").expect("installed");
4872        let other_slot = parser.rules().get_index_of("other").expect("installed");
4873        assert_ne!(val_slot, other_slot);
4874
4875        // Bound the way the parse loop binds it: slot, name and spec all
4876        // describe the same installed rule.
4877        let mut rule = Rule::new("val", Value::Undefined);
4878        rule.bind_spec(
4879            &parser.rules()["val"],
4880            parser.names[val_slot].clone(),
4881            val_slot,
4882        );
4883        assert_eq!(&*parser.expected_match_tins(&rule, 0), [crate::TIN_NR]);
4884
4885        // A callback renames the rule to another installed rule. The slot
4886        // still points at `val`, so the slot alone would answer with
4887        // `val`'s row; the name is what makes it `other`'s, which is what
4888        // the lookup by name always gave.
4889        rule.name = parser.names[other_slot].clone();
4890        assert_eq!(
4891            &*parser.expected_match_tins(&rule, 0),
4892            [crate::TIN_ST],
4893            "the rule is called `other` now, so `other`'s row answers"
4894        );
4895
4896        // A callback swaps the spec and leaves the name. Nothing about
4897        // which row answers depends on the spec, because the row is
4898        // derived from the name the rule was installed under.
4899        rule.name = parser.names[val_slot].clone();
4900        rule.spec = Arc::clone(&parser.rules()["other"]);
4901        assert_eq!(
4902            &*parser.expected_match_tins(&rule, 0),
4903            [crate::TIN_NR],
4904            "still called `val`, so still gated by `val`'s row"
4905        );
4906
4907        // A name installed nowhere expects nothing. Its slot is
4908        // `usize::MAX`, so nothing is in range to answer by accident.
4909        let ghost = Rule::new("ghost", Value::Undefined);
4910        assert_eq!(
4911            &*parser.expected_match_tins(&ghost, 0),
4912            &[] as &[Tin],
4913            "an uninstalled name has no row, not another rule's"
4914        );
4915    }
4916
4917    /// `expected_match_tins` exists to gate the custom matchers, so with no
4918    /// custom matcher registered it answers "nothing" without consulting
4919    /// the table -- the table is still built and still says what it said,
4920    /// and the moment a match token appears the same rule at the same slot
4921    /// gets the table's row again. The first assertion is what pins the
4922    /// short-circuit: were it dropped, the empty-matcher parser would
4923    /// return `[TIN_NR]` and the assertion would fail.
4924    #[test]
4925    fn expected_match_tins_is_empty_until_a_match_token_exists() {
4926        fn val_rule() -> RuleSpec {
4927            let mut spec = RuleSpec::new("val");
4928            spec.open.push(AltSpec {
4929                s: vec![vec![crate::TIN_NR]],
4930                ..Default::default()
4931            });
4932            spec
4933        }
4934        let rule = Rule::new("val", Value::Undefined);
4935
4936        let mut without = Parser::new(crate::Options::default());
4937        without.add_rule(val_rule());
4938        assert!(without.options.match_tokens.is_empty());
4939        assert_eq!(without.expected_tins[0].at(true, 0), [crate::TIN_NR]);
4940        assert_eq!(
4941            &*without.expected_match_tins(&rule, 0),
4942            &[] as &[Tin],
4943            "no custom matcher: nothing to gate, so nothing to look up"
4944        );
4945
4946        let mut options = crate::Options::default();
4947        let tin = options.register_token("#QQ");
4948        options.match_tokens.insert(
4949            "#QQ".into(),
4950            crate::options::MatchToken {
4951                name: "#QQ".into(),
4952                tin,
4953                matcher: crate::options::MatchTokenMatcher::Regex(regex::Regex::new("^q").unwrap()),
4954                eager: false,
4955            },
4956        );
4957        let mut with = Parser::new(options);
4958        with.add_rule(val_rule());
4959        assert_eq!(
4960            &*with.expected_match_tins(&rule, 0),
4961            [crate::TIN_NR],
4962            "a custom matcher is present, so the slot's tins gate it"
4963        );
4964        assert_eq!(
4965            &*with.expected_match_tins(&rule, 1),
4966            &[] as &[Tin],
4967            "a slot the rule never fills expects nothing"
4968        );
4969    }
4970}