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