tabnas/

lexer.rs

// Copyright (c) 2013-2026 Richard Rodger, MIT License

use crate::error::TabnasError;
use crate::options::{LexCheck, LexCheckResult, MatchTokenMatcher, Options};
use crate::token::{
    Point, Token, TIN_BD, TIN_CM, TIN_LN, TIN_NR, TIN_SP, TIN_ST, TIN_TX, TIN_VL, TIN_ZZ,
};
use crate::value::Value;
use regex::Regex;
use std::panic::{catch_unwind, AssertUnwindSafe};
use std::sync::Arc;

pub struct Lexer<'a> {
    src: &'a str,
    chars: Vec<char>,
    byte_indices: Vec<usize>,
    char_len: usize,
    idx: usize,
    ri: usize,
    ci: usize,
    options: Arc<Options>,
    ignore_tins: Vec<crate::Tin>,
    char_sets: crate::text::CharSets,
    err: Option<TabnasError>,
    end_reached: bool,
    /// `number.exclude`, compiled once per grammar and shared by the
    /// parser that owns it; see [`compile_number_exclude`].
    exclude_regex: Option<Arc<Regex>>,
    want: Option<Vec<crate::Tin>>,
    standalone: Option<(crate::Rule, crate::Context)>,
}

#[derive(Clone)]
pub(crate) struct LexerState {
    idx: usize,
    ri: usize,
    ci: usize,
    err: Option<TabnasError>,
    end_reached: bool,
}

/// Opaque snapshot returned by [`Lexer::relex_for_rule`]. Pass it to
/// [`Lexer::unrelex`] if the caller later rejects the committed recut.
#[derive(Clone)]
pub struct RelexCheckpoint {
    state: LexerState,
    replay: std::collections::VecDeque<Token>,
}

enum CheckFlow {
    Continue,
    Skip,
    Token(Box<Token>),
}

/// The result the lexer passes through its own internals.
///
/// `TabnasError` is 664 bytes, so `LexResult<Token>` is 664 bytes
/// too: three times the token it carries, and moved on the SUCCESS path
/// through every frame of the lexer chain. Boxing the error inside the
/// engine makes those results the size of a token again, and costs an
/// allocation only when there is an error to report, which is the path that
/// is already building a 664-byte diagnostic.
///
/// The public entry points still hand back an unboxed `TabnasError`, so no
/// caller of this crate sees the box.
type LexResult<T> = Result<T, Box<TabnasError>>;

/// The compiled form of `number.exclude`, or `None` when there is no
/// pattern or it does not compile (an invalid pattern excludes nothing,
/// as it always has).
///
/// Compiling a regex costs about 700K instructions, which is more than
/// a small document costs to parse, so the parser compiles it once per
/// grammar and hands every lexer the same automaton through the `Arc`.
/// Cloning a `Regex` would not do: it shares the automaton but builds a
/// fresh scratch-cache pool, and the first search from each clone fills
/// it. Go and TypeScript compile the pattern once, at configuration time.
pub(crate) fn compile_number_exclude(options: &Options) -> Option<Arc<Regex>> {
    let pattern = options.number.exclude.as_deref()?;
    Regex::new(pattern).ok().map(Arc::new)
}

impl<'a> Lexer<'a> {
    pub fn new(src: &'a str, mut options: Options) -> Self {
        if let Err(error) = options.validate_comment_definitions() {
            panic!("invalid options: {error}");
        }
        // A lexer built directly may be handed options nobody has
        // ordered yet. The parser's own lexer comes through
        // `with_shared`, whose options were ordered when they were
        // prepared, and whose exclude pattern was compiled then too.
        options.sort_for_lexing();
        let exclude_regex = compile_number_exclude(&options);
        Self::with_shared(src, Arc::new(options), exclude_regex)
    }

    /// Lex against options the parser already owns and has ordered, with
    /// the `number.exclude` pattern it compiled from them.
    pub(crate) fn with_shared(
        src: &'a str,
        options: Arc<Options>,
        exclude_regex: Option<Arc<Regex>>,
    ) -> Self {
        let mut chars = Vec::new();
        let mut byte_indices = Vec::new();
        for (b_idx, c) in src.char_indices() {
            chars.push(c);
            byte_indices.push(b_idx);
        }
        let char_len = chars.len();

        Lexer {
            src,
            chars,
            byte_indices,
            char_len,
            idx: 0,
            ri: 1,
            ci: 1,
            ignore_tins: options.ignore_tins(),
            char_sets: options.char_sets(),
            options,
            err: None,
            end_reached: false,
            exclude_regex,
            want: None,
            standalone: None,
        }
    }

    fn current_point(&self) -> Point {
        Point {
            len: self.src.len(),
            site: crate::Site {
                si: self.byte_position(),
                pos: self.idx,
                ri: self.ri,
                ci: self.ci,
            },
        }
    }

    /// The source from char index `start` up to `end`, clipped to the end
    /// of the source: the span of a bad token, cut as TypeScript's
    /// `lex.bad(why, pstart, pend)` cuts it (`ts/src/lexer.ts`).
    ///
    /// Only the END is clipped. The caller must supply `start <= end`
    /// and `start <= self.char_len`, or the indexing panics. Every call
    /// site below passes `esc_point.site.pos - 1`, which additionally
    /// needs `1 <= pos`; that holds because `esc_point` is captured
    /// after the escape character has been consumed. These three are
    /// the preconditions `rs/verus/lexer_span.rs` ASSUMES: it proves the
    /// span arithmetic is in bounds given them, and does not model the
    /// call sites, so nothing machine-checks that they hold here. A
    /// refactor that captured the point before the advance would still
    /// pass `rs/verus/run.sh`.
    fn source_span(&self, start: usize, end: usize) -> String {
        self.chars[start..end.min(self.char_len)].iter().collect()
    }

    fn state(&self) -> LexerState {
        LexerState {
            idx: self.idx,
            ri: self.ri,
            ci: self.ci,
            err: self.err.clone(),
            end_reached: self.end_reached,
        }
    }

    /// Full immutable source supplied to this lexer.
    pub fn source(&self) -> &str {
        self.src
    }

    /// Source remaining at the live cursor.
    pub fn remaining(&self) -> &str {
        &self.src[self.byte_position()..]
    }

    /// Return at most `max_chars` Unicode scalar values from the live cursor.
    /// This is the Rust counterpart of the public `lex.fwd`/`Lex.Fwd` helper.
    pub fn forward(&self, max_chars: usize) -> &str {
        let remaining = self.remaining();
        let end = remaining
            .char_indices()
            .nth(max_chars)
            .map_or(remaining.len(), |(index, _)| index);
        &remaining[..end]
    }

    /// Snapshot the live cursor for token construction.
    pub fn point(&self) -> Point {
        self.current_point()
    }

    /// Advance by Unicode scalar values. Returns false without moving when
    /// the requested count extends beyond end-of-source.
    pub fn advance_chars(&mut self, count: usize) -> bool {
        if self.idx.saturating_add(count) > self.char_len {
            return false;
        }
        for _ in 0..count {
            self.advance();
        }
        true
    }

    /// Construct a token from a point captured before cursor advancement.
    pub fn token(
        &self,
        name: impl AsRef<str>,
        tin: crate::Tin,
        value: Value,
        source: impl Into<crate::TokenText>,
        point: Point,
    ) -> Token {
        Token::new(name, tin, value, source, point)
    }

    /// Resolve or allocate a token identity in this lexer's configuration.
    pub fn token_tin(&mut self, name: impl Into<String>) -> crate::Tin {
        Arc::make_mut(&mut self.options).register_token(name)
    }

    /// Resolve a token identity back to its configured name.
    pub fn token_name(&self, tin: crate::Tin) -> String {
        self.options.token_name(tin)
    }

    /// Whether the options this lexer runs under enable `alt`: not when
    /// `rule.exclude` names one of its groups, nor when `rule.include`
    /// lists groups and it declares none of them. The parser skips such an
    /// alternate, and TypeScript removes it from the rule spec
    /// (`filterRules`) before anything reads the spec, so a custom matcher
    /// that reads a rule's alternates, to tell a key position from a value
    /// one, asks this to see the same alternates TypeScript does.
    pub fn alt_enabled(&self, alt: &crate::AltSpec) -> bool {
        crate::parser::groups_enabled(alt, &self.options)
    }

    /// Construct a bad token at the current cursor.
    ///
    /// A custom matcher that returns it reports a lexer fault, which the
    /// parser handles as it handles its own lexer's: a rule's fetch raises
    /// it at once with `why` as the code, at this position, or, under
    /// recovery, records it, coalescing a run of them into one error, and
    /// moves the cursor past its source; relexing leaves it for an
    /// alternate to re-cut. The cursor need not be advanced here.
    pub fn bad(&self, why: impl Into<String>) -> Token {
        let point = self.current_point();
        let source = self
            .peek()
            .map_or_else(String::new, |character| character.to_string());
        let mut token = Token::new("#BD", TIN_BD, Value::Undefined, source, point);
        token.err = crate::TokenCode::from(why.into());
        token.why = token.err.clone();
        token
    }

    /// Construct a bad token whose displayed source is a scalar-indexed span.
    /// As in TypeScript, the diagnostic point remains the live cursor.
    /// Returned from a matcher it is handled as [`Lexer::bad`] describes;
    /// recovery steps past the span, counted from that cursor.
    pub fn bad_span(&self, why: impl Into<String>, start: usize, end: usize) -> Token {
        let point = self.current_point();
        let source = if start <= end && end <= self.char_len {
            let start_byte = self
                .byte_indices
                .get(start)
                .copied()
                .unwrap_or(self.src.len());
            let end_byte = self
                .byte_indices
                .get(end)
                .copied()
                .unwrap_or(self.src.len());
            self.src[start_byte..end_byte].to_string()
        } else {
            self.peek()
                .map_or_else(String::new, |character| character.to_string())
        };
        let mut token = Token::new("#BD", TIN_BD, Value::Undefined, source, point);
        token.err = crate::TokenCode::from(why.into());
        token.why = token.err.clone();
        token
    }

    fn byte_position(&self) -> usize {
        self.byte_indices
            .get(self.idx)
            .copied()
            .unwrap_or(self.src.len())
    }

    fn advance(&mut self) -> Option<char> {
        if self.idx < self.char_len {
            let c = self.chars[self.idx];
            self.idx += 1;
            if self.char_sets.row.contains(c) {
                self.ri += 1;
                self.ci = 1;
            } else {
                self.ci += 1;
            }
            Some(c)
        } else {
            None
        }
    }

    /// Step over one character of a string body, counting a column and
    /// never a row. `advance` counts a row for any character in
    /// `line.rowChars`, which is right between tokens and wrong inside a
    /// string: TypeScript's `buildStringBodySpec` (ts/src/lexer.ts) makes
    /// a row character plain body there unless the string is multi-line
    /// and the character is in `line.chars` as well, which is
    /// [`Lexer::advance_string_line`].
    fn advance_body(&mut self) -> Option<char> {
        let c = self.peek()?;
        self.idx += 1;
        self.ci += 1;
        Some(c)
    }

    /// Step over a line character inside a multi-line string: the column
    /// resets, and a character in `line.rowChars` counts a row, as
    /// TypeScript's string-body classes LINE and LINE+ROW do
    /// (`STRING_BODY_TABLE` in ts/src/lexer.ts) and as Go's
    /// `BuildStringBodySpec` ports them.
    fn advance_string_line(&mut self) -> Option<char> {
        let c = self.peek()?;
        self.idx += 1;
        if self.char_sets.row.contains(c) {
            self.ri += 1;
        }
        self.ci = 1;
        Some(c)
    }

    fn peek(&self) -> Option<char> {
        if self.idx < self.char_len {
            Some(self.chars[self.idx])
        } else {
            None
        }
    }

    fn peek_at(&self, offset: usize) -> Option<char> {
        let i = self.idx + offset;
        if i < self.char_len {
            Some(self.chars[i])
        } else {
            None
        }
    }

    fn wants(&self, tin: crate::Tin) -> bool {
        self.want
            .as_ref()
            .is_none_or(|wanted| wanted.contains(&tin))
    }

    /// Bring a fetch's point and current character up to the live cursor.
    ///
    /// A custom matcher, or an imperative check, may move the cursor and
    /// then decline: xml's steps over a byte-order mark and goes on to
    /// look for a tag. Every matcher after it starts where it left the
    /// cursor, as TypeScript's do (each reads `lex.pnt`) and Go's do (each
    /// reads `l.pnt`), and the current character is `None` once the cursor
    /// is at the end of the source. Reading the character the fetch began
    /// on instead put the built-in matchers' tokens at the wrong place,
    /// sent them looking for a character that was no longer there, and,
    /// when the matcher had stepped over the LAST character, panicked on
    /// the missing one.
    #[inline]
    fn resync(&self, point: &mut Point, current: &mut Option<char>) {
        if self.idx != point.site.pos {
            *point = self.current_point();
            *current = self.peek();
        }
    }

    /// Whether TypeScript would try a built-in matcher at all in a fetch
    /// that began on `first` and whose cursor has since been moved by a
    /// matcher that declined.
    ///
    /// TypeScript chooses the matchers a fetch tries from a table indexed
    /// by the character the fetch begins on (`buildLexDispatch` in
    /// ts/src/utility.ts, read in `Lex.next`): a built-in is listed for a
    /// Latin-1 character only when a token it makes could start with it,
    /// unless it carries a check, and every built-in is listed for a
    /// character from U+0100 up. The table is not consulted again when a
    /// custom matcher moves the cursor, so this asks it about `first`, and
    /// the matcher then tests the character under the cursor as usual.
    /// Before the cursor moves the two are the same character and the
    /// matcher's own test is the whole answer, so this is `true`.
    #[inline]
    fn listed(
        &self,
        entry: usize,
        first: char,
        has_check: bool,
        could_start: impl FnOnce(char) -> bool,
    ) -> bool {
        self.idx == entry || u32::from(first) >= 256 || has_check || could_start(first)
    }

    fn run_check(&mut self, check: Option<LexCheck>, point: Point) -> CheckFlow {
        let Some(check) = check else {
            return CheckFlow::Continue;
        };
        let remaining = &self.src[self.byte_position()..];
        let result = check
            .run_imperative(self)
            .or_else(|| check.run(remaining))
            .unwrap_or(LexCheckResult::Continue);
        match result {
            LexCheckResult::Continue => CheckFlow::Continue,
            LexCheckResult::Skip => CheckFlow::Skip,
            LexCheckResult::NativeToken(token) => CheckFlow::Token(token),
            LexCheckResult::Token(token)
                if !token.source.is_empty() && remaining.starts_with(&token.source) =>
            {
                let tin = if token.tin < 0 {
                    self.options.token(&token.name).unwrap_or(token.tin)
                } else {
                    token.tin
                };
                if tin < 0 {
                    return CheckFlow::Skip;
                }
                for _ in token.source.chars() {
                    self.advance();
                }
                CheckFlow::Token(Box::new(Token::new(
                    token.name,
                    tin,
                    token.value,
                    token.source,
                    point,
                )))
            }
            LexCheckResult::Token(_) => CheckFlow::Skip,
        }
    }

    /// Give any plugin matcher whose order is below `before` its turn.
    ///
    /// Nine sites in the lexer call this per token, once at each stage a
    /// matcher is allowed to intervene. A grammar with no custom matcher,
    /// which is most of them, was paying nine index lookups per token to be
    /// told nine times that there is nothing to run. The guard is inline so
    /// those sites skip the call itself; the walk stays out of line.
    #[inline]
    fn run_custom_matchers(
        &mut self,
        index: &mut usize,
        before: f64,
        plugin: &mut Option<(&mut crate::Rule, &mut crate::Context)>,
    ) -> Option<Token> {
        if *index >= self.options.lex.matchers.len() {
            return None;
        }
        self.run_remaining_custom_matchers(index, before, plugin)
    }

    #[inline(never)]
    fn run_remaining_custom_matchers(
        &mut self,
        index: &mut usize,
        before: f64,
        plugin: &mut Option<(&mut crate::Rule, &mut crate::Context)>,
    ) -> Option<Token> {
        while let Some(matcher) = self
            .options
            .lex
            .matchers
            .get_index(*index)
            .map(|(_, matcher)| matcher)
            .filter(|matcher| matcher.order < before)
            .cloned()
        {
            *index += 1;
            // Each matcher starts where the one before it left the cursor:
            // one may step over a character and decline, as xml's does over
            // a byte-order mark, and TypeScript's matchers all read the
            // live `lex.pnt`.
            let point = self.current_point();
            let remaining = &self.src[self.byte_position()..];
            let saved = self.state();
            let token = if let Some(callback) = matcher.imperative.as_ref() {
                let Some((rule, context)) = plugin.as_mut() else {
                    continue;
                };
                callback(self, rule, context)
            } else {
                matcher
                    .matcher
                    .as_ref()
                    .and_then(|callback| callback(remaining))
                    .filter(|token| {
                        !token.source.is_empty() && remaining.starts_with(&token.source)
                    })
                    .map(|token| {
                        Token::new(token.name, token.tin, token.value, token.source, point)
                    })
            };
            let Some(mut token) = token else {
                if self.want.is_some() {
                    self.rewind(saved);
                }
                continue;
            };

            // TypeScript and Go run opaque custom matchers speculatively for
            // a negotiated cut. An unwanted result rolls back locally so a
            // later matcher can still satisfy the request.
            let tin = if token.tin < 0 {
                self.options.token(&token.name).unwrap_or(token.tin)
            } else {
                token.tin
            };
            if tin < 0 || !self.wants(tin) {
                self.rewind(saved);
                continue;
            }
            if matcher.imperative.is_none() {
                for _ in token.src.chars() {
                    self.advance();
                }
            }
            token.tin = tin;
            return Some(token);
        }
        None
    }

    fn is_text_delimiter_here(&self) -> bool {
        self.is_text_delimiter_at(self.idx)
    }

    fn is_text_delimiter_at(&self, index: usize) -> bool {
        let Some(ch) = self.chars.get(index).copied() else {
            return true;
        };
        let remaining = &self.src[self.byte_indices[index]..];
        (self.options.space.lex && self.char_sets.space.contains(ch))
            || (self.options.fixed.lex
                && self
                    .options
                    .fixed
                    .tokens
                    .values()
                    .any(|token| !token.source.is_empty() && remaining.starts_with(&token.source)))
            || (self.options.line.lex
                && (self.char_sets.line_ends.contains(ch) || matches!(ch, '\u{2028}' | '\u{2029}')))
            || (self.options.comment.lex
                && self.options.comment.definitions.values().any(|definition| {
                    definition.lex
                        && !definition.start.is_empty()
                        && remaining.starts_with(&definition.start)
                }))
            || self
                .options
                .ender
                .iter()
                .any(|ender| !ender.is_empty() && remaining.starts_with(ender))
    }

    /// Fetches the next non-IGNORE token (skipping spaces, lines, comments).
    pub fn next_token(&mut self) -> Result<Token, TabnasError> {
        let point = self.current_point();
        let result = match catch_unwind(AssertUnwindSafe(|| {
            if let Some(ref error) = self.err {
                return Err(Box::new(error.clone()));
            }

            loop {
                let token = self.next_raw(None)?;
                if !self.ignore_tins.contains(&token.tin) {
                    return Ok(token);
                }
            }
        })) {
            Ok(result) => result,
            Err(payload) => self.record_panic(payload, "Lexer::next_token", point),
        };
        // The box is internal to the engine; a caller gets the error itself.
        result.map_err(|error| *error)
    }

    /// Fetch the next token without discarding whitespace, line, or comment tokens.
    pub fn next_raw_token(&mut self) -> Result<Token, TabnasError> {
        let point = self.current_point();
        let result = match catch_unwind(AssertUnwindSafe(|| self.next_raw(None))) {
            Ok(result) => result,
            Err(payload) => self.record_panic(payload, "Lexer::next_raw_token", point),
        };
        result.map_err(|error| *error)
    }

    /// Fetch one token for an imperative parser callback, preserving ignored
    /// space/line/comment tokens just like TypeScript's public `lex.next`.
    /// Replayed tokens produced by `Context::rewind` are served first.
    pub fn next_raw_for_rule(
        &mut self,
        rule: &mut crate::Rule,
        context: &mut crate::Context,
    ) -> LexResult<Token> {
        if let Some(token) = context.next_replay() {
            Ok(token)
        } else {
            self.next_raw_with(None, Some((rule, context)))
        }
    }

    /// Fetch the next non-ignored token for an imperative parser callback.
    pub fn next_for_rule(
        &mut self,
        rule: &mut crate::Rule,
        context: &mut crate::Context,
    ) -> LexResult<Token> {
        loop {
            let token = self.next_raw_for_rule(rule, context)?;
            if !self.ignore_tins.contains(&token.tin) {
                return Ok(token);
            }
        }
    }

    /// Public negotiated-relex entry point for native parser callbacks.
    /// A successful recut commits the lexer cursor and returns an opaque undo
    /// checkpoint; a failed recut restores all lexer state before returning.
    pub fn relex_for_rule(
        &mut self,
        from: &Token,
        wanted: &[crate::Tin],
        rule: &mut crate::Rule,
        context: &mut crate::Context,
    ) -> Option<(Token, RelexCheckpoint)> {
        self.relex(from, wanted, rule, context)
    }

    /// Undo a committed [`Lexer::relex_for_rule`] operation, including the
    /// pending tokens hidden while the replacement cut was negotiated.
    pub fn unrelex(&mut self, checkpoint: RelexCheckpoint, context: &mut crate::Context) {
        self.restore(checkpoint.state);
        context.restore_replay(checkpoint.replay);
    }

    fn record_panic(
        &mut self,
        payload: Box<dyn std::any::Any + Send>,
        api: &str,
        point: Point,
    ) -> LexResult<Token> {
        let error = TabnasError::from_panic(
            payload,
            api,
            self.src,
            point.site.pos,
            point.site.ri,
            point.site.ci,
            &self.options,
        );
        self.err = Some(error.clone());
        Err(Box::new(error))
    }

    /// Fetch a raw token while restricting non-eager custom token matchers to
    /// the exact tins accepted at the parser slot being filled. Builtin and
    /// fixed-token matchers are unaffected by this gate.
    pub(crate) fn next_rule_token(
        &mut self,
        expected_match_tins: &[crate::Tin],
        rule: &mut crate::Rule,
        context: &mut crate::Context,
    ) -> LexResult<Token> {
        self.next_raw_with(Some(expected_match_tins), Some((rule, context)))
    }

    /// Step past a bad token the parser has absorbed or skipped, as
    /// TypeScript's `advanceLexPast` does (ts/src/rules.ts): a bad token
    /// does not advance the cursor by itself, so recovery moves it to the
    /// end of the token's span, never backwards, and, for a fault raised
    /// inside a compound construct, on past the next row character so
    /// lexing resumes on a fresh row. The lexer's own faults latch until
    /// this clears them.
    pub(crate) fn skip_bad(&mut self, token: &Token, to_line_end: bool) {
        let span = token.src.chars().count().max(1);
        let mut target = self.idx.max(token.site.pos.saturating_add(span));
        if to_line_end {
            let mut end = target;
            while end < self.char_len && !self.char_sets.row.contains(self.chars[end]) {
                end += 1;
            }
            target = target.max(self.char_len.min(end + 1));
        }
        while self.idx < target && self.idx < self.char_len {
            self.advance();
        }
        self.err = None;
        if self.idx < self.char_len {
            self.end_reached = false;
        }
    }

    /// Re-cut an already buffered source span, constrained to the token
    /// identities requested by one alternate. On success the cursor remains
    /// after the new cut; the returned state can restore the original cut if
    /// that alternate later fails.
    pub(crate) fn relex(
        &mut self,
        from: &Token,
        wanted: &[crate::Tin],
        rule: &mut crate::Rule,
        context: &mut crate::Context,
    ) -> Option<(Token, RelexCheckpoint)> {
        if from.src.is_empty() || from.site.pos > self.char_len || wanted.is_empty() {
            return None;
        }
        // The standing error, if any, is moved into the checkpoint rather
        // than copied: the cut below clears it anyway, and a copy is the
        // length of the source (`full_source`) for every cut attempted.
        let err = self.err.take();
        let saved = LexerState {
            err,
            ..self.state()
        };
        // TypeScript temporarily replaces the lexer's pending-token queue
        // with an empty queue for a negotiated cut. Rust keeps that queue on
        // Context, so hide it explicitly and preserve it in the checkpoint.
        let replay = context.take_replay();
        self.idx = from.site.pos;
        self.ri = from.site.ri;
        self.ci = from.site.ci;
        self.err = None;
        self.end_reached = false;
        self.want = Some(wanted.to_vec());
        // Straight to the matchers, past `next_raw_with`: an error here only
        // rejects the cut, and the restore below puts back the lexer's own,
        // so the source it would attach, and the copy it would keep, are
        // never seen. With them, every rejected cut cost the length of the
        // source, and a flat stylesheet parsed in quadratic time.
        let recut = self.next_raw_inner(None, Some((rule, context))).ok();
        self.want = None;
        match recut.filter(|token| wanted.contains(&token.tin)) {
            Some(mut token) => {
                token.ignored = from.ignored.clone();
                Some((
                    token,
                    RelexCheckpoint {
                        state: saved,
                        replay,
                    },
                ))
            }
            None => {
                self.restore(saved);
                // Discard any speculative replay generated by an imperative
                // matcher and restore the queue that preceded the attempt.
                context.restore_replay(replay);
                None
            }
        }
    }

    pub(crate) fn restore(&mut self, state: LexerState) {
        self.idx = state.idx;
        self.ri = state.ri;
        self.ci = state.ci;
        self.err = state.err;
        self.end_reached = state.end_reached;
        self.want = None;
    }

    /// Put the cursor back after a custom matcher's speculative attempt and
    /// keep the request being negotiated, as TypeScript's `Lex.speculate`
    /// restores the point and leaves `want` alone. [`Lexer::restore`] ends
    /// a negotiation, so the first custom matcher to decline during a
    /// re-cut used to lift the request for every matcher after it, and a
    /// string matcher could then cut the `#ST` the re-cut was there to
    /// avoid.
    fn rewind(&mut self, state: LexerState) {
        let want = self.want.take();
        self.restore(state);
        self.want = want;
    }

    fn next_raw(&mut self, expected_match_tins: Option<&[crate::Tin]>) -> LexResult<Token> {
        // Only a lexer being driven directly needs these, and building
        // them costs a whole `Options` clone. A parse reaches the lexer
        // through `next_rule_token`, which brings the real rule and
        // context with it, so it never wants them at all.
        let (mut rule, mut context) = match self.standalone.take() {
            Some(pair) => pair,
            None => (
                crate::Rule::new("#NORULE", Value::Undefined),
                crate::Context::new(
                    self.options.rewind.history,
                    self.src,
                    Value::Undefined,
                    Arc::clone(&self.options),
                    crate::InstanceInfo::default(),
                ),
            ),
        };
        let result = self.next_raw_with(expected_match_tins, Some((&mut rule, &mut context)));
        self.standalone = Some((rule, context));
        result
    }

    fn modify_text_value(
        &mut self,
        mut value: Value,
        plugin: &mut Option<(&mut crate::Rule, &mut crate::Context)>,
    ) -> Value {
        if self.options.text.modify.is_empty() {
            return value;
        }
        let modifiers = self.options.text.modify.clone();
        let options = self.options.clone();
        let Some((rule, context)) = plugin.as_mut() else {
            panic!("imperative text modifier requires an active lexer context");
        };
        for modifier in modifiers {
            value = modifier.run(value, self, rule, context, &options);
        }
        value
    }

    fn next_raw_with(
        &mut self,
        expected_match_tins: Option<&[crate::Tin]>,
        plugin: Option<(&mut crate::Rule, &mut crate::Context)>,
    ) -> LexResult<Token> {
        let result = self.next_raw_inner(expected_match_tins, plugin);
        match result {
            Ok(token) => Ok(token),
            Err(mut error) => {
                // The matchers build their errors without the source, and it
                // is attached here, where an error leaves the lexer: a
                // negotiated cut (`relex`) rejects many candidates, each an
                // error nobody sees, and a copy of the whole source apiece
                // made that quadratic.
                error.full_source = self.src.to_string();
                error.apply_options(&self.options);
                self.err = Some((*error).clone());
                Err(error)
            }
        }
    }

    fn next_raw_inner(
        &mut self,
        expected_match_tins: Option<&[crate::Tin]>,
        mut plugin: Option<(&mut crate::Rule, &mut crate::Context)>,
    ) -> LexResult<Token> {
        if self.end_reached {
            return Ok(Token::new(
                "#ZZ",
                TIN_ZZ,
                Value::Undefined,
                "",
                self.current_point(),
            ));
        }

        if self.idx >= self.char_len {
            self.end_reached = true;
            return Ok(Token::new(
                "#ZZ",
                TIN_ZZ,
                Value::Undefined,
                "",
                self.current_point(),
            ));
        }

        // The fetch begins on `first`, at `entry`. `pnt` and `c`, the point
        // a token starts at and the character under the cursor, follow the
        // cursor whenever a custom matcher or a check moves it and declines
        // (`resync`); `c` is `None` once the cursor is at the end.
        let entry = self.idx;
        let first = self.chars[entry];
        let mut pnt = self.current_point();
        let mut c = Some(first);
        let mut custom_index = 0;

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 1_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // User-declared match tokens occupy the 1e6 matcher priority band.
        let match_skipped = if self.options.match_lex
            && (!self.options.match_values.is_empty()
                || self
                    .options
                    .match_tokens
                    .values()
                    .any(|matcher| self.wants(matcher.tin)))
        {
            match self.run_check(self.options.match_check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        let remaining = &self.src[self.byte_position()..];
        let custom_value = (self.options.match_lex && !match_skipped && self.want.is_none())
            .then(|| {
                self.options
                    .match_values
                    .values()
                    .find_map(|matcher| match &matcher.matcher {
                        MatchTokenMatcher::Callback(callback) => callback(remaining)
                            .filter(|result| {
                                !result.source.is_empty() && remaining.starts_with(&result.source)
                            })
                            .map(|result| (result.source, result.value)),
                        MatchTokenMatcher::Regex(regex) => {
                            let captures = regex.captures(remaining)?;
                            let found = captures
                                .get(0)
                                .filter(|found| found.start() == 0 && !found.as_str().is_empty())?;
                            let source = found.as_str().to_string();
                            let value = matcher.transform.as_ref().map_or_else(
                                || {
                                    matcher
                                        .val
                                        .clone()
                                        .unwrap_or_else(|| Value::String(source.clone()))
                                },
                                |transform| {
                                    let groups = captures
                                        .iter()
                                        .map(|capture| {
                                            capture.map_or_else(String::new, |value| {
                                                value.as_str().into()
                                            })
                                        })
                                        .collect::<Vec<_>>();
                                    transform(&groups)
                                },
                            );
                            Some((source, value))
                        }
                    })
            })
            .flatten();
        if let Some((source, value)) = custom_value {
            for _ in source.chars() {
                self.advance();
            }
            return Ok(Token::new("#VL", TIN_VL, value, source, pnt));
        }

        let remaining = &self.src[self.byte_position()..];
        // With no custom matcher there is nothing for the band to do: both
        // passes walk an empty table and yield nothing, and `fix_len` is
        // read only by that walk. Most grammars register none, and every
        // token fetch of theirs paid the eager pass's scan of the fixed
        // table (one closure call per fixed literal) to arrive at the
        // `None` this guard now hands over directly. TS `makeMatchMatcher`
        // returns null on an empty table (ts/src/lexer.ts) and the band is
        // never installed; Go reaches the same place by defaulting
        // `MatchLex` off unless `Options.Match` is set. Rust defaults
        // `match_lex` true as TS does, so the guard is the parity.
        let custom = (self.options.match_lex
            && !match_skipped
            && !self.options.match_tokens.is_empty())
        .then(|| {
            // Two passes, position-expected before eager, as go/lexer.go
            // matchMatch and ts/src/lexer.ts makeMatchMatcher both make.
            // One tin-ordered pass in which eagerness merely bypassed the
            // slot gate let an eager matcher EARLIER in tin order win over
            // an expected one later: with `p = %x31-39` beside
            // `d = %x30-39`, the `2` of `12` lexed as the narrower class
            // the `*d` loop never asked for. Eagerness is for firing where
            // the slot's list is narrower than the grammar, never for
            // outbidding what the slot names.
            //
            // Under a want the alternate's own tin list is the sharper
            // gate, so one filtered pass is the whole search. With no
            // expected list at all (a standalone lexer, no rule) nothing
            // constrains the caller and every matcher is eligible in the
            // first pass.
            // The longest FIXED literal this slot expects that matches
            // here, or 0. Only the eager pass consults it: there, a
            // literal the slot names beats an eager-only matcher that
            // cuts no further than it does. Without this, a character
            // class that CONTAINS a literal the grammar also uses
            // swallows it wherever the class is eager (`num = "0" /
            // posdigit *digit` beside `digit = %x30-39` rejected
            // `0.0.0`). LENGTH decides, not mere existence, so a keyword
            // literal cannot truncate a longer word: ties go to the
            // literal, and an eager matcher that cuts further still
            // wins. TS and Go do the same, in makeMatchMatcher and
            // matchMatch.
            //
            // Computed once per fetch and only when a regex matcher in the
            // eager pass has something to weigh against it, as TS
            // `expectedFixedLen` does (`fixLen = -1` until asked). The
            // scan is the whole fixed table against the slot's list; an
            // expected matcher that wins in pass 0, or a fetch under a
            // want, never needs it. Nothing the scan reads changes
            // between the two passes, so lazy equals eager.
            let mut fix_len: Option<usize> = None;
            let compute_fix_len = || {
                if self.want.is_none() && self.options.fixed.lex {
                    expected_match_tins.map_or(0, |expected| {
                        self.options
                            .fixed
                            .tokens
                            .values()
                            .filter(|token| {
                                !token.source.is_empty()
                                    && expected.contains(&token.tin)
                                    && remaining.starts_with(&token.source)
                            })
                            .map(|token| token.source.len())
                            .max()
                            .unwrap_or(0)
                    })
                } else {
                    0
                }
            };
            let passes = if self.want.is_some() { 1 } else { 2 };
            (0..passes).find_map(|pass| {
                self.options.match_tokens.values().find_map(|matcher| {
                    if !self.wants(matcher.tin) {
                        return None;
                    }
                    if self.want.is_none() {
                        let expected = expected_match_tins
                            .is_none_or(|expected| expected.contains(&matcher.tin));
                        if pass == 0 {
                            if !expected {
                                return None;
                            }
                        } else if expected || !matcher.eager {
                            return None;
                        }
                    }
                    let result = match &matcher.matcher {
                        MatchTokenMatcher::Regex(regex) => regex
                            .find(remaining)
                            .filter(|found| found.start() == 0)
                            // The eager pass yields to an expected
                            // literal it cannot out-cut; the fixed
                            // matcher (2e6) runs next and takes it. See
                            // `fix_len` above.
                            .filter(|found| {
                                pass == 0 || {
                                    let fix_len = *fix_len.get_or_insert_with(compute_fix_len);
                                    fix_len == 0 || found.len() > fix_len
                                }
                            })
                            .map(|found| {
                                let source = found.as_str().to_string();
                                (source.clone(), Value::String(source))
                            }),
                        MatchTokenMatcher::Callback(callback) => callback(remaining)
                            .filter(|result| {
                                !result.source.is_empty() && remaining.starts_with(&result.source)
                            })
                            .map(|result| (result.source, result.value)),
                    };
                    result.map(|(source, value)| (matcher.name.clone(), matcher.tin, source, value))
                })
            })
        });
        if let Some(Some((name, tin, matched, value))) = custom {
            for _ in matched.chars() {
                self.advance();
            }
            return Ok(Token::new(name, tin, value, matched, pnt));
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 2_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // Fixed literals occupy the 2e6 band and use longest-match wins.
        let fixed_skipped = if self.options.fixed.lex {
            match self.run_check(self.options.fixed.check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        let fixed_skipped = fixed_skipped
            || !self.listed(entry, first, self.options.fixed.check.is_some(), |ch| {
                self.options
                    .fixed
                    .tokens
                    .values()
                    .any(|token| token.source.starts_with(ch))
            });
        let remaining = &self.src[self.byte_position()..];
        // The winner is carried out of the table as its position, not as a
        // copy of its text. `Token::new` takes the name and the source text
        // by reference and stores both inline, so the only owned copy the
        // token needs is the one inside `Value::String`. Naming the match
        // as three owned values cost three `String` allocations per fixed
        // token, two of them freed again before the token was built.
        // The first byte decides almost every entry. Asking `wants` and then
        // `starts_with` of each fixed token in turn ran a tin lookup and a
        // `memcmp` per token in the grammar per token in the input, and a
        // grammar with fifty fixed tokens pays fifty of each to reject
        // forty-nine. One byte answers the same question, and an empty
        // source is kept out by its own check, which only entries that
        // already matched the byte ever reach.
        let first_byte = remaining.as_bytes().first().copied();
        let fixed = (self.options.fixed.lex && !fixed_skipped)
            .then(|| {
                self.options
                    .fixed
                    .tokens
                    .values()
                    .enumerate()
                    .filter(|(_, token)| {
                        token.source.as_bytes().first().copied() == first_byte
                            && !token.source.is_empty()
                            && self.wants(token.tin)
                            && remaining.starts_with(&token.source)
                    })
                    .max_by_key(|(_, token)| token.source.len())
                    .map(|(index, token)| (index, token.source.chars().count()))
            })
            .flatten();
        if let Some((index, source_chars)) = fixed {
            for _ in 0..source_chars {
                self.advance();
            }
            let (_, token) = self
                .options
                .fixed
                .tokens
                .get_index(index)
                .expect("index came from this table, which nothing writes to mid-parse");
            return Ok(Token::new(
                &token.name,
                token.tin,
                Value::String(token.source.clone()),
                token.source.as_str(),
                pnt,
            ));
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 3_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // 1. Whitespace
        let space_skipped = if self.options.space.lex && self.wants(TIN_SP) {
            match self.run_check(self.options.space.check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        if self.options.space.lex
            && !space_skipped
            && self.wants(TIN_SP)
            && c.is_some_and(|ch| self.char_sets.space.contains(ch))
            && self.listed(entry, first, self.options.space.check.is_some(), |ch| {
                self.char_sets.space.contains(ch)
            })
        {
            let mut src = String::new();
            while let Some(ch) = self.peek() {
                if self.char_sets.space.contains(ch) {
                    src.push(ch);
                    self.advance();
                } else {
                    break;
                }
            }
            return Ok(Token::new(
                "#SP",
                TIN_SP,
                Value::String(src.clone()),
                src,
                pnt,
            ));
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 4_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // 2. Line ending
        let line_skipped = if self.options.line.lex && self.wants(TIN_LN) {
            match self.run_check(self.options.line.check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        let line_skipped = line_skipped
            || !self.listed(entry, first, self.options.line.check.is_some(), |ch| {
                self.char_sets.line_ends.contains(ch)
            });
        if self.options.line.lex
            && !line_skipped
            && self.wants(TIN_LN)
            && c.is_some_and(|ch| self.char_sets.line_ends.contains(ch))
        {
            let mut src = String::new();
            let mut seen = std::collections::HashSet::new();
            while let Some(ch) = self.peek() {
                if !self.char_sets.line_ends.contains(ch) {
                    break;
                }
                if self.options.line.single && !seen.insert(ch) {
                    break;
                }
                src.push(self.advance().expect("peeked character must advance"));
            }
            self.ci = 1;
            return Ok(Token::new(
                "#LN",
                TIN_LN,
                Value::String(src.clone()),
                src,
                pnt,
            ));
        }

        if let Some(bad_char @ ('\u{2028}' | '\u{2029}')) = c {
            if self.options.line.lex && !line_skipped && self.wants(TIN_LN) {
                self.advance();
                let err = TabnasError::new(
                    "unexpected",
                    bad_char.to_string(),
                    "",
                    pnt.site.pos,
                    pnt.site.ri,
                    pnt.site.ci,
                );
                self.err = Some(err.clone());
                return Err(Box::new(err));
            }
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 5_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // 3. Quoted strings. These precede comments in the canonical matcher
        // order, so an overlapping quote/comment opener is a string unless
        // string matching explicitly abandons the malformed candidate.
        let string_skipped = if self.options.string.lex && self.wants(TIN_ST) {
            match self.run_check(self.options.string.check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        let quote = c.filter(|ch| self.char_sets.string.contains(*ch));
        if let Some(quote) = quote.filter(|_| {
            self.options.string.lex
                && !string_skipped
                && self.wants(TIN_ST)
                && self.listed(entry, first, self.options.string.check.is_some(), |ch| {
                    self.char_sets.string.contains(ch)
                })
        }) {
            let start = (self.idx, self.ri, self.ci);
            match self.match_string(quote, pnt) {
                result @ Ok(_) => return result,
                Err(error) if !self.options.string.abandon => return Err(error),
                Err(_) => {
                    (self.idx, self.ri, self.ci) = start;
                    self.err = None;
                }
            }
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 6_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // 4. Comments (longest opening marker wins; ties sort by name).
        let comment_skipped = if self.options.comment.lex && self.wants(TIN_CM) {
            match self.run_check(self.options.comment.check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        if self.options.comment.lex
            && !comment_skipped
            && self.wants(TIN_CM)
            && self.listed(entry, first, self.options.comment.check.is_some(), |ch| {
                self.options
                    .comment
                    .definitions
                    .values()
                    .any(|definition| definition.start.starts_with(ch))
            })
        {
            if let Some(token) = self.match_comment(pnt)? {
                return Ok(token);
            }
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 7_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // 5. Numbers
        let number_skipped = if self.options.number.lex && self.wants(TIN_NR) {
            match self.run_check(self.options.number.check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        let could_start_number =
            |ch: char| ch == '-' || ch == '+' || ch == '.' || ch.is_ascii_digit();
        if self.options.number.lex
            && !number_skipped
            && self.wants(TIN_NR)
            && c.is_some_and(could_start_number)
            && self.listed(
                entry,
                first,
                self.options.number.check.is_some(),
                could_start_number,
            )
        {
            if let Some(tkn) = self.match_number(pnt)? {
                return Ok(tkn);
            }
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, 8_000_000.0, &mut plugin) {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // 6. Text and named/regex values share the same delimited run.
        // Negotiated lexing gates this combined family by its primary token
        // identity (#TX), matching the TypeScript and Go dispatchers. Once
        // entered, an exact or regexp value definition may still produce
        // #VL; the caller rejects and rolls that cut back when #VL was not
        // requested.
        let text_matcher_wanted = self.wants(TIN_TX);
        let value_lex = self.options.value.lex && text_matcher_wanted;
        let text_lex = self.options.text.lex && text_matcher_wanted;
        let text_skipped = if text_lex || value_lex {
            match self.run_check(self.options.text.check.clone(), pnt) {
                CheckFlow::Continue => false,
                CheckFlow::Skip => true,
                CheckFlow::Token(token) => return Ok(*token),
            }
        } else {
            false
        };
        self.resync(&mut pnt, &mut c);
        if (text_lex || value_lex) && !text_skipped && !self.is_text_delimiter_here() {
            let start = (self.idx, self.ri, self.ci);
            // Only a `value` definition declaring `consume` looks at the
            // rest of the document, and the JSON grammar has none -- but
            // this ran for every text token, copying the whole tail of the
            // input each time. `self.src` is borrowed from the caller for
            // `'a` and is never reassigned, so reading the reference out
            // before the scan below gives a slice that does not borrow
            // `self` and survives the `&mut self` the scan needs.
            let source: &'a str = self.src;
            let remaining = &source[self.byte_position()..];
            let mut src = String::new();
            while let Some(ch) = self.peek() {
                if self.is_text_delimiter_here() {
                    break;
                }
                src.push(ch);
                self.advance();
            }

            let mut output = None;
            if value_lex {
                if let Some(definition) = self
                    .options
                    .value
                    .definitions
                    .get(&src)
                    .filter(|definition| definition.matcher.is_none())
                    .cloned()
                {
                    output = Some(Token::new(
                        "#VL",
                        TIN_VL,
                        definition
                            .val
                            .clone()
                            .unwrap_or_else(|| Value::String(src.clone())),
                        src.clone(),
                        pnt,
                    ));
                }

                if output.is_none() {
                    let mut definitions: Vec<_> = self
                        .options
                        .value
                        .definitions
                        .iter()
                        .filter(|(_, definition)| definition.matcher.is_some())
                        .map(|(name, definition)| (name.clone(), definition.clone()))
                        .collect();
                    definitions.sort_by(|(name_a, _), (name_b, _)| name_a.cmp(name_b));
                    for (_, definition) in definitions {
                        let regex = definition.matcher.as_ref().expect("filtered matcher");
                        let target: &str = if definition.consume { remaining } else { &src };
                        let Some(captures) = regex.captures(target) else {
                            continue;
                        };
                        let Some(found) = captures.get(0).filter(|found| found.start() == 0) else {
                            continue;
                        };
                        if !definition.consume && found.end() != target.len() {
                            continue;
                        }
                        let matched = found.as_str().to_string();
                        let value = definition.transform.as_ref().map_or_else(
                            || {
                                definition
                                    .val
                                    .clone()
                                    .unwrap_or_else(|| Value::String(matched.clone()))
                            },
                            |transform| {
                                let groups = captures
                                    .iter()
                                    .map(|capture| {
                                        capture
                                            .map_or_else(String::new, |value| value.as_str().into())
                                    })
                                    .collect::<Vec<_>>();
                                transform(&groups)
                            },
                        );
                        if definition.consume {
                            (self.idx, self.ri, self.ci) = start;
                            for _ in matched.chars() {
                                self.advance();
                            }
                        }
                        output = Some(Token::new("#VL", TIN_VL, value, matched, pnt));
                        break;
                    }
                }
            }

            if output.is_none() && (!text_lex || text_skipped) {
                (self.idx, self.ri, self.ci) = start;
            } else if output.is_none() {
                output = Some(Token::new(
                    "#TX",
                    TIN_TX,
                    Value::String(src.clone()),
                    src,
                    pnt,
                ));
            }

            if let Some(mut token) = output {
                let value = std::mem::replace(&mut token.val, Value::Undefined);
                token.val = self.modify_text_value(value, &mut plugin);
                return Ok(token);
            }
        }

        if let Some(token) = self.run_custom_matchers(&mut custom_index, f64::INFINITY, &mut plugin)
        {
            return Ok(token);
        }
        self.resync(&mut pnt, &mut c);

        // 7. Unclaimed character -> Error: unexpected, raised where the
        // cursor stands, as TypeScript's `Lex.next` builds its #BD at the
        // live `pnt` and Go's `nextUnfiltered2` at `l.pnt`. A matcher that
        // stepped over the last character and declined leaves no character
        // to name: the error then names none, at the end of the source, as
        // it does in both. This took a character unconditionally, and so
        // panicked on a lone byte-order mark under the xml plugin, whose
        // matcher steps over a mark at the start of the source.
        let bad_source = self.advance().map_or_else(String::new, String::from);
        let err = TabnasError::new(
            "unexpected",
            bad_source,
            "",
            pnt.site.pos,
            pnt.site.ri,
            pnt.site.ci,
        );
        self.err = Some(err.clone());
        Err(Box::new(err))
    }

    fn match_comment(&mut self, pnt: Point) -> LexResult<Option<Token>> {
        let remaining = &self.src[self.byte_position()..];
        let mut definitions: Vec<_> = self
            .options
            .comment
            .definitions
            .iter()
            .filter(|(_, definition)| {
                // Same first-byte test as the fixed-token scan above.
                definition.start.as_bytes().first().copied()
                    == remaining.as_bytes().first().copied()
                    && !definition.start.is_empty()
                    && definition.lex
                    && remaining.starts_with(&definition.start)
            })
            .collect();
        definitions.sort_by(|(name_a, a), (name_b, b)| {
            b.start
                .len()
                .cmp(&a.start.len())
                .then_with(|| name_a.cmp(name_b))
        });
        let Some((_, definition)) = definitions.first() else {
            return Ok(None);
        };
        let definition = (*definition).clone();
        let mut src = String::new();
        for _ in definition.start.chars() {
            src.push(self.advance().expect("comment marker must advance"));
        }

        let mut terminated_by_suffix = false;
        let mut closed = definition.line;
        loop {
            let remainder = &self.src[self.byte_position()..];
            let suffix = definition
                .suffixes
                .iter()
                .filter(|suffix| !suffix.is_empty() && remainder.starts_with(*suffix))
                .max_by_key(|suffix| suffix.len())
                .cloned();
            let suffix = suffix.or_else(|| {
                let matcher = definition.suffix_matcher.as_ref()?;
                let effect = matcher.run(remainder);
                if effect.is_some() {
                    return effect;
                }
                let saved = self.state();
                let wanted = self.want.clone();
                let token = matcher.run_imperative(self);
                self.restore(saved);
                self.want = wanted;
                token.map(|token| token.src.to_string())
            });
            let remainder = &self.src[self.byte_position()..];
            let suffix =
                suffix.filter(|suffix| !suffix.is_empty() && remainder.starts_with(suffix));
            if let Some(suffix) = suffix {
                for _ in suffix.chars() {
                    src.push(self.advance().expect("comment suffix must advance"));
                }
                terminated_by_suffix = true;
                closed = true;
                break;
            }
            if !definition.line
                && !definition.end.is_empty()
                && remainder.starts_with(&definition.end)
            {
                for _ in definition.end.chars() {
                    src.push(self.advance().expect("comment end must advance"));
                }
                closed = true;
                break;
            }
            let Some(ch) = self.peek() else {
                break;
            };
            if definition.line && (self.char_sets.line_ends.contains(ch)) {
                break;
            }
            src.push(self.advance().expect("comment body must advance"));
        }

        if !closed {
            let err = TabnasError::new(
                "unterminated_comment",
                src,
                "",
                pnt.site.pos,
                pnt.site.ri,
                pnt.site.ci,
            );
            self.err = Some(err.clone());
            return Err(Box::new(err));
        }

        if definition.eat_line && !terminated_by_suffix {
            while let Some(ch) = self.peek() {
                if !self.char_sets.line_ends.contains(ch) {
                    break;
                }
                src.push(self.advance().expect("comment line tail must advance"));
            }
        }

        Ok(Some(Token::new(
            "#CM",
            TIN_CM,
            Value::String(src.clone()),
            src,
            pnt,
        )))
    }

    fn match_number(&mut self, pnt: Point) -> LexResult<Option<Token>> {
        let start_idx = self.idx;
        let mut src = String::new();

        // Optional sign.
        if matches!(self.peek(), Some('-' | '+')) {
            src.push(self.advance().unwrap());
        }

        // Base-prefixed integers are complete at the final valid digit.
        if self.peek() == Some('0') {
            if let Some(prefix) = self.peek_at(1) {
                let radix = match prefix {
                    'x' | 'X' if self.options.number.hex => Some(16),
                    'o' | 'O' if self.options.number.oct => Some(8),
                    'b' | 'B' if self.options.number.bin => Some(2),
                    _ => None,
                };
                if let Some(radix) = radix {
                    src.push(self.advance().expect("peeked zero"));
                    src.push(self.advance().expect("peeked base prefix"));
                    let mut saw_digit = false;
                    while let Some(ch) = self.peek() {
                        if ch.is_digit(radix) {
                            saw_digit = true;
                            src.push(self.advance().expect("peeked base digit"));
                        } else if self
                            .options
                            .number
                            .sep
                            .as_ref()
                            .is_some_and(|separator| separator.contains(ch))
                        {
                            src.push(self.advance().expect("peeked base digit"));
                        } else {
                            break;
                        }
                    }
                    if saw_digit && self.is_text_delimiter_here() {
                        if self
                            .exclude_regex
                            .as_ref()
                            .is_some_and(|regex| regex.is_match(&src))
                        {
                            self.reset_number(start_idx, pnt);
                            return Ok(None);
                        }
                        if self.options.value.lex {
                            if let Some(definition) = self
                                .options
                                .value
                                .definitions
                                .get(&src)
                                .filter(|definition| definition.matcher.is_none())
                            {
                                return Ok(Some(Token::new(
                                    "#VL",
                                    TIN_VL,
                                    definition
                                        .val
                                        .clone()
                                        .unwrap_or_else(|| Value::String(src.clone())),
                                    src,
                                    pnt,
                                )));
                            }
                        }
                        // The digits of the literal, prefix, sign and any
                        // separators removed, folded as they are read. The
                        // fold keeps a bounded head, a digit count and a
                        // sticky bit, so a literal of any length costs the
                        // same handful of bytes: buffering the digits
                        // instead would let one long token multiply the
                        // memory the source already holds.
                        let mut fold = DigitFold::new(radix.trailing_zeros());
                        for ch in src.chars().skip_while(|ch| matches!(ch, '-' | '+')).skip(2) {
                            if self
                                .options
                                .number
                                .sep
                                .as_ref()
                                .is_some_and(|separator| separator.contains(ch))
                            {
                                continue;
                            }
                            fold.push(ch.to_digit(radix).expect("validated base digit"));
                        }
                        let mut value = fold.finish();
                        if src.starts_with('-') {
                            value = -value;
                        }
                        return Ok(Some(Token::new(
                            "#NR",
                            TIN_NR,
                            Value::Number(value),
                            src,
                            pnt,
                        )));
                    }
                    self.reset_number(start_idx, pnt);
                    return Ok(None);
                }
            }
        }

        let Some(ch) = self.peek() else {
            self.reset_number(start_idx, pnt);
            return Ok(None);
        };
        if ch == '.' {
            if !self.peek_at(1).is_some_and(|next| next.is_ascii_digit()) {
                self.reset_number(start_idx, pnt);
                return Ok(None);
            }
            src.push(self.advance().expect("peeked leading decimal point"));
        } else if !ch.is_ascii_digit() {
            self.reset_number(start_idx, pnt);
            return Ok(None);
        }

        let (has_digits, edge_separator) = self.scan_number_digits(&mut src);
        if !has_digits || edge_separator {
            self.reset_number(start_idx, pnt);
            return Ok(None);
        }

        // The canonical regexp admits a trailing decimal point and an
        // exponent after it (`2.e3`), but declines `0.a` as one text run.
        if self.peek() == Some('.') {
            let next = self.peek_at(1);
            let exponent_after_dot = matches!(next, Some('e' | 'E'))
                && match self.peek_at(2) {
                    Some('+' | '-') => self.peek_at(3).is_some_and(|ch| ch.is_ascii_digit()),
                    Some(ch) => ch.is_ascii_digit(),
                    None => false,
                };
            if next.is_some_and(|ch| ch.is_ascii_digit()) {
                src.push(self.advance().expect("peeked decimal point"));
                let (_, edge_separator) = self.scan_number_digits(&mut src);
                if edge_separator {
                    self.reset_number(start_idx, pnt);
                    return Ok(None);
                }
            } else if next.is_some()
                && !self.is_text_delimiter_at(self.idx + 1)
                && next != Some('.')
                && !exponent_after_dot
            {
                self.reset_number(start_idx, pnt);
                return Ok(None);
            } else {
                src.push(self.advance().expect("peeked trailing decimal point"));
            }
        }

        if matches!(self.peek(), Some('e' | 'E')) {
            let exponent_start = self.idx;
            let source_len = src.len();
            src.push(self.advance().expect("peeked exponent marker"));
            if matches!(self.peek(), Some('+' | '-')) {
                src.push(self.advance().expect("peeked exponent sign"));
            }
            let (has_exponent_digits, edge_separator) = self.scan_number_digits(&mut src);
            if edge_separator {
                self.reset_number(start_idx, pnt);
                return Ok(None);
            }
            if !has_exponent_digits {
                self.idx = exponent_start;
                src.truncate(source_len);
            }
        }

        if !self.is_text_delimiter_here() {
            self.reset_number(start_idx, pnt);
            return Ok(None);
        }

        // Check exclusion regex (e.g. ^00+)
        if let Some(ref re) = self.exclude_regex {
            if re.is_match(&src) {
                // Number is excluded, backtrack
                self.reset_number(start_idx, pnt);
                return Ok(None);
            }
        }

        if self.options.value.lex {
            if let Some(definition) = self
                .options
                .value
                .definitions
                .get(&src)
                .filter(|definition| definition.matcher.is_none())
            {
                return Ok(Some(Token::new(
                    "#VL",
                    TIN_VL,
                    definition
                        .val
                        .clone()
                        .unwrap_or_else(|| Value::String(src.clone())),
                    src,
                    pnt,
                )));
            }
        }

        // Parse float
        let parse_src = self.options.number.sep.as_ref().map_or_else(
            || src.clone(),
            |separator| src.chars().filter(|ch| !separator.contains(*ch)).collect(),
        );
        match parse_src.parse::<f64>() {
            Ok(num) => Ok(Some(Token::new(
                "#NR",
                TIN_NR,
                Value::Number(num),
                src,
                pnt,
            ))),
            Err(_) => {
                self.reset_number(start_idx, pnt);
                Ok(None)
            }
        }
    }

    fn reset_number(&mut self, start_idx: usize, pnt: Point) {
        self.idx = start_idx;
        self.ri = pnt.site.ri;
        self.ci = pnt.site.ci;
    }

    /// Consume a decimal digit/separator run. Separators are legal only
    /// between digits; a leading or trailing separator makes the whole run
    /// fall through to text, matching the TypeScript regexp and Go scanner.
    fn scan_number_digits(&mut self, src: &mut String) -> (bool, bool) {
        // The run is measured before any of it is consumed. Advancing
        // as it goes would hold `&mut self` across a read of
        // `self.options.number.sep`, and the way that used to be settled
        // was to clone the separator — an allocation and a free for
        // every number in the input, for a value that cannot change
        // while one number is being scanned.
        let run_start = self.idx;
        let mut saw_digit = false;
        let mut last_was_separator = false;
        let mut end = run_start;
        {
            let separator = self.options.number.sep.as_deref();
            while let Some(ch) = self.chars.get(end).copied() {
                if ch.is_ascii_digit() {
                    saw_digit = true;
                    last_was_separator = false;
                } else if separator.is_some_and(|separator| separator.contains(ch)) {
                    last_was_separator = true;
                } else {
                    break;
                }
                end += 1;
            }
        }
        while self.idx < end {
            src.push(self.advance().expect("scanned number character"));
        }
        let starts_with_separator = self.idx > run_start
            && self.options.number.sep.as_deref().is_some_and(|separator| {
                self.chars[run_start..self.idx]
                    .first()
                    .is_some_and(|ch| separator.contains(*ch))
            });
        (saw_digit, starts_with_separator || last_was_separator)
    }

    fn match_string(&mut self, quote: char, pnt: Point) -> LexResult<Token> {
        let quote_char = self.advance().unwrap();
        let mut out_str = String::new();
        let mut raw_src = String::new();
        raw_src.push(quote_char);

        let mut pending_high_surrogate: Option<u16> = None;

        // The body classes of TypeScript's `buildStringBodySpec`
        // (ts/src/lexer.ts), which Go's `BuildStringBodySpec` ports: a
        // line character is LINE or LINE+ROW only inside a multi-line
        // string, where it resets the column and, in `line.rowChars`,
        // counts a row; anywhere else in a body it is plain content,
        // counted as a column, unless it is a control character, which
        // stops the body as `unprintable`. This loop used to count a row
        // for any row character it stepped over, string body or not, and
        // to refuse any line character inside a single-line string: with
        // json5's U+2028 and U+2029 as row characters, `y` in
        // `"a<U+2028>b" y` sat on row 2 here and on row 1 in TypeScript
        // and Go, and with the two in `line.chars` as well the string was
        // `unprintable` (tabnas/parser#263).
        let multi_line = self.options.string.multi_chars.contains(quote);

        while let Some(c) = self.peek() {
            if c == quote {
                raw_src.push(self.advance().unwrap());
                // Rust strings cannot represent a lone UTF-16 surrogate, so
                // preserve the Go-port behavior and fold it to U+FFFD.
                self.flush_surrogate(&mut pending_high_surrogate, &mut out_str);
                return Ok(Token::new(
                    "#ST",
                    TIN_ST,
                    Value::String(out_str),
                    raw_src,
                    pnt,
                ));
            }

            if let Some(replacement) = self.options.string.replace.get(&c).cloned() {
                raw_src.push(self.advance().expect("peeked character must advance"));
                self.flush_surrogate(&mut pending_high_surrogate, &mut out_str);
                out_str.push_str(&replacement);
                continue;
            }

            if multi_line && self.char_sets.line.contains(c) {
                raw_src.push(
                    self.advance_string_line()
                        .expect("peeked character must advance"),
                );
                out_str.push(c);
                continue;
            }

            // A control character stops the body: a line character
            // always, since a single-line string cannot hold one, and any
            // other unless `string.allowControl` admits it. Sited ON the
            // character, as TypeScript does (`pnt.sI = sI; pnt.cI = cI`
            // before its `bad()` call, ts/src/lexer.ts). `pnt` is the
            // opening quote, and reporting that put every embedded
            // newline at the start of its string.
            if (c as u32) < 32
                && (self.char_sets.line.contains(c) || !self.options.string.allow_control)
            {
                let site = self.current_point().site;
                let err =
                    TabnasError::new("unprintable", c.to_string(), "", site.pos, site.ri, site.ci);
                self.err = Some(err.clone());
                return Err(Box::new(err));
            }

            if c == self.options.string.escape_char {
                raw_src.push(self.advance().unwrap());
                let esc_point = self.current_point();
                if let Some(esc) = self.advance() {
                    raw_src.push(esc);
                    if let Some(replacement) = self.options.string.escape.get(&esc).cloned() {
                        self.flush_surrogate(&mut pending_high_surrogate, &mut out_str);
                        out_str.push_str(&replacement);
                        continue;
                    }
                    match esc {
                        'u' => {
                            // Unicode escape: \uXXXX or \u{X...}. An
                            // invalid one is reported on the backslash
                            // with the span TypeScript cuts: six source
                            // characters for the fixed-width form, four
                            // for `\x`, and through the closing brace
                            // (or to the end of the source) for the
                            // braced form -- clipped, never padded, so a
                            // truncated escape at end of input reports
                            // exactly the characters that are there.
                            if self.peek() == Some('{') && !self.options.string.escape_strict {
                                raw_src.push(self.advance().unwrap()); // '{'
                                let mut hex = String::new();
                                let mut closed = false;
                                while let Some(h) = self.peek() {
                                    if h == '}' {
                                        raw_src.push(self.advance().unwrap());
                                        closed = true;
                                        break;
                                    }
                                    raw_src.push(self.advance().unwrap());
                                    hex.push(h);
                                }

                                if !closed
                                    || hex.is_empty()
                                    || hex.len() > 6
                                    || !hex.chars().all(|ch| ch.is_ascii_hexdigit())
                                {
                                    let err = TabnasError::new(
                                        "invalid_unicode",
                                        self.source_span(esc_point.site.pos - 1, self.idx),
                                        "",
                                        esc_point.site.pos - 1,
                                        esc_point.site.ri,
                                        esc_point.site.ci - 1,
                                    );
                                    self.err = Some(err.clone());
                                    return Err(Box::new(err));
                                }

                                let cp = match u32::from_str_radix(&hex, 16) {
                                    Ok(val) if val <= 0x10FFFF => val,
                                    _ => {
                                        let err = TabnasError::new(
                                            "invalid_unicode",
                                            self.source_span(esc_point.site.pos - 1, self.idx),
                                            "",
                                            esc_point.site.pos - 1,
                                            esc_point.site.ri,
                                            esc_point.site.ci - 1,
                                        );
                                        self.err = Some(err.clone());
                                        return Err(Box::new(err));
                                    }
                                };

                                self.emit_unicode_escape(
                                    cp,
                                    &mut pending_high_surrogate,
                                    &mut out_str,
                                );
                            } else {
                                // Exactly 4 hex digits: \uXXXX
                                let mut hex = String::new();
                                for _ in 0..4 {
                                    if let Some(h) = self.peek() {
                                        if h.is_ascii_hexdigit() {
                                            raw_src.push(self.advance().unwrap());
                                            hex.push(h);
                                        } else {
                                            break;
                                        }
                                    } else {
                                        break;
                                    }
                                }

                                if hex.len() != 4 {
                                    let err = TabnasError::new(
                                        "invalid_unicode",
                                        self.source_span(
                                            esc_point.site.pos - 1,
                                            esc_point.site.pos + 5,
                                        ),
                                        "",
                                        esc_point.site.pos - 1,
                                        esc_point.site.ri,
                                        esc_point.site.ci - 1,
                                    );
                                    self.err = Some(err.clone());
                                    return Err(Box::new(err));
                                }

                                let cp = u16::from_str_radix(&hex, 16).map_err(|_| {
                                    let err = TabnasError::new(
                                        "invalid_unicode",
                                        self.source_span(
                                            esc_point.site.pos - 1,
                                            esc_point.site.pos + 5,
                                        ),
                                        "",
                                        esc_point.site.pos - 1,
                                        esc_point.site.ri,
                                        esc_point.site.ci - 1,
                                    );
                                    self.err = Some(err.clone());
                                    err
                                })?;

                                self.emit_unicode_escape(
                                    u32::from(cp),
                                    &mut pending_high_surrogate,
                                    &mut out_str,
                                );
                            }
                        }
                        'x' if !self.options.string.escape_strict => {
                            let mut hex = String::new();
                            for _ in 0..2 {
                                if let Some(h) = self.peek() {
                                    if h.is_ascii_hexdigit() {
                                        raw_src.push(
                                            self.advance().expect("peeked character must advance"),
                                        );
                                        hex.push(h);
                                    }
                                }
                            }
                            if hex.len() != 2 {
                                let err = TabnasError::new(
                                    "invalid_ascii",
                                    self.source_span(
                                        esc_point.site.pos - 1,
                                        esc_point.site.pos + 3,
                                    ),
                                    "",
                                    esc_point.site.pos - 1,
                                    esc_point.site.ri,
                                    esc_point.site.ci - 1,
                                );
                                self.err = Some(err.clone());
                                return Err(Box::new(err));
                            }
                            let byte = u8::from_str_radix(&hex, 16).expect("validated ASCII hex");
                            self.flush_surrogate(&mut pending_high_surrogate, &mut out_str);
                            out_str.push(char::from(byte));
                        }
                        other => {
                            if !self.options.string.allow_unknown {
                                // Sited on the escape CHARACTER with a
                                // one-character span, as TypeScript
                                // (`pnt.sI = sI; pnt.cI = cI; lex.bad(
                                // S.unexpected, sI, sI + 1)`) and Go do;
                                // the other escape errors sit on the
                                // backslash and span the construct.
                                let err = TabnasError::new(
                                    "unexpected",
                                    other.to_string(),
                                    "",
                                    esc_point.site.pos,
                                    esc_point.site.ri,
                                    esc_point.site.ci,
                                );
                                self.err = Some(err.clone());
                                return Err(Box::new(err));
                            }
                            self.flush_surrogate(&mut pending_high_surrogate, &mut out_str);
                            out_str.push(other);
                        }
                    }
                } else {
                    let err = TabnasError::new(
                        "unterminated_string",
                        raw_src,
                        "",
                        pnt.site.pos,
                        pnt.site.ri,
                        pnt.site.ci,
                    );
                    self.err = Some(err.clone());
                    return Err(Box::new(err));
                }
            } else {
                self.flush_surrogate(&mut pending_high_surrogate, &mut out_str);
                raw_src.push(self.advance_body().expect("peeked character must advance"));
                out_str.push(c);
            }
        }

        let err = TabnasError::new(
            "unterminated_string",
            raw_src,
            "",
            pnt.site.pos,
            pnt.site.ri,
            pnt.site.ci,
        );
        self.err = Some(err.clone());
        Err(Box::new(err))
    }

    fn flush_surrogate(&self, pending: &mut Option<u16>, out: &mut String) {
        if pending.take().is_some() {
            out.push('\u{FFFD}');
        }
    }

    /// Emit one decoded Unicode escape while pairing UTF-16 surrogate code
    /// units across both `\\uXXXX` and `\\u{...}` spellings.
    fn emit_unicode_escape(&self, cp: u32, pending: &mut Option<u16>, out: &mut String) {
        if (0xD800..=0xDBFF).contains(&cp) {
            self.flush_surrogate(pending, out);
            *pending = Some(cp as u16);
        } else if (0xDC00..=0xDFFF).contains(&cp) {
            if let Some(high) = pending.take() {
                let scalar = 0x10000 + (((u32::from(high)) - 0xD800) << 10) + (cp - 0xDC00);
                out.push(char::from_u32(scalar).expect("paired surrogates form a Unicode scalar"));
            } else {
                out.push('\u{FFFD}');
            }
        } else {
            self.flush_surrogate(pending, out);
            out.push(char::from_u32(cp).expect("validated escape is a Unicode scalar"));
        }
    }
}

// ---------------------------------------------------------------------------
// Base-prefixed integer literals.
//
// A `0x`, `0o` or `0b` literal is read as an EXACT integer and rounded to
// a double ONCE. The obvious fold -- `value = value * radix + digit` in
// `f64` -- rounds at every digit, and past the 53-bit exact integer range
// those roundings accumulate: `0Xa6f2f78f4f9bf44` came out as
// `43a4de5ef1e9f37e` where canonical TypeScript and the Go port both
// answer `43a4de5ef1e9f37f`, one unit in the last place low. That is
// silently altered data, not a formatting difference.
//
// TypeScript coerces the literal with unary `+`, whose StringNumericValue
// is the exact mathematical value of the digits rounded once, half to
// even; Go reads it through `big.Int` and `big.Float.Float64()`, which is
// the same rule. These reproduce it. Only the VALUE is affected: which
// literals are accepted, and the token they become, are settled by
// `match_number` before any of this runs.
//
// The decimal path needs none of it -- `str::parse::<f64>` is correctly
// rounded for a digit string of any length.
// ---------------------------------------------------------------------------

/// `2^k` for a non-negative `k`, exactly, saturating to infinity above the
/// double range. A repeated multiply would round on the way up.
fn pow2(k: i64) -> f64 {
    debug_assert!(k >= 0, "only non-negative exponents arise here");
    if k > 1023 {
        f64::INFINITY
    } else {
        f64::from_bits(((k + 1023) as u64) << 52)
    }
}

/// Folds the digits of a base-prefixed literal into the NEAREST double,
/// rounding half to even, without holding the digits.
///
/// `bits` is the width of one digit, so the base is a power of two: 1 for
/// binary, 3 for octal, 4 for hexadecimal. Those are the only bases
/// `match_number` reads, which is what lets a `u128` head plus a sticky
/// bit stand in for arbitrary-precision arithmetic.
///
/// Only three things about a literal can change the answer: the top
/// `128 / bits` significant digits, how many digits follow them, and
/// whether any of those is non-zero. This keeps exactly those, so the
/// space it costs does not grow with the literal, however long an
/// untrusted document makes one.
struct DigitFold {
    bits: u32,
    /// The significant digits packed so far, at most `head_len` of them.
    head: u128,
    /// How many significant digits have been pushed, head and tail alike.
    len: usize,
    /// Whether any digit past the head was non-zero.
    sticky: bool,
    /// Whether a non-zero digit has been seen. Leading zeros carry no
    /// value, and dropping them is what makes the head wider than the 54
    /// significant bits the rounding needs.
    started: bool,
}

impl DigitFold {
    fn new(bits: u32) -> Self {
        debug_assert!(
            (1..=4).contains(&bits),
            "only the power-of-two bases the lexer reads"
        );
        DigitFold {
            bits,
            head: 0,
            len: 0,
            sticky: false,
            started: false,
        }
    }

    /// A `u128` holds exactly this many digits of the base.
    fn head_len(&self) -> usize {
        (128 / self.bits) as usize
    }

    fn push(&mut self, digit: u32) {
        if !self.started {
            if 0 == digit {
                return;
            }
            self.started = true;
        }
        if self.len < self.head_len() {
            self.head = (self.head << self.bits) | u128::from(digit);
        } else if 0 != digit {
            self.sticky = true;
        }
        self.len += 1;
    }

    fn finish(&self) -> f64 {
        if !self.started {
            return 0.0;
        }
        let head_len = self.head_len();
        if self.len <= head_len {
            // A `u128` to `f64` cast rounds to nearest, ties to even, which
            // is the rule the canonical runtime follows.
            return self.head as f64;
        }

        // Longer than a u128: the head holds the top `head_len` digits and
        // `sticky` remembers whether anything below them was set. Those two
        // are all the rounding can depend on. The leading digit is
        // non-zero, so the head is at least 121 bits wide in every base
        // here and `shift` is comfortably positive.
        let dropped = i64::from(self.bits) * (self.len - head_len) as i64;
        let shift = 128 - self.head.leading_zeros() - 53;

        let mut mantissa = (self.head >> shift) as u64;
        let half = (self.head >> (shift - 1)) & 1 == 1;
        let sticky = self.head & ((1u128 << (shift - 1)) - 1) != 0 || self.sticky;
        if half && (sticky || mantissa & 1 == 1) {
            // At most 2^53, which is still an exact double.
            mantissa += 1;
        }
        // The mantissa carries at most 53 significant bits, so the scaling
        // is exact inside the double range and overflows to infinity
        // outside it.
        mantissa as f64 * pow2(dropped + i64::from(shift))
    }
}