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