lua_lex/

lib.rs

//! Lexical analyzer — port of `llex.c` + `llex.h`.
//!
//! Provides the Lua 5.4 lexer: character-by-character scanning of a [`ZIO`]
//! input stream into [`Token`] values, with one-token lookahead.  The
//! `llex.h` header is merged here per PORTING.md §1.
//!
//! # C source files
//! - `reference/lua-5.4.7/src/llex.c`  (581 lines, 24 functions)
//! - `reference/lua-5.4.7/src/llex.h`  (91 lines; merged here)
//!
//! # Design notes
//! - `LexState.L` (back-pointer to `lua_State`) is removed.  All functions
//!   that need `LuaState` receive it as `state: &mut LuaState`.
//! - `Token.token` is `i32` in Phase A (matching the C `int token` field).
//!   Single-byte tokens are their ASCII values; reserved-word tokens start at
//!   `FIRST_RESERVED` (257).  A proper `TokenKind` enum is deferred to Phase B.
//! - `save` / `save_and_next` are now fallible (`Result<(), LuaError>`); the
//!   `?` operator replaces the C noreturn `lexerror` call on buffer overflow.
//! - The `goto read_save / only_save / no_save` pattern in `read_string` is
//!   translated via the local `EscapeResult` enum.

// TODO(port): resolve remaining cross-crate calls (intern_str, table anchor,
// number parsing, utf8 encoding) in Phase B.  Canonical cross-crate type
// imports are now in place per harness/type-vocabulary.tsv (see below).

use std::io::Write as IoWrite;

// PORT NOTE: GcRef<T> = Rc<T> in Phases A–C; replaced by real GC pointer in Phase D.
use lua_types::gc::GcRef;

// Canonical cross-crate types: imported from owner crates per
// harness/type-vocabulary.tsv.  See PORTING.md §7.
pub use lua_types::LuaError;
pub use lua_types::LuaString;
pub use lua_vm::state::LuaState;
pub use lua_vm::table::LuaTable;

/// Placeholder for `LexBuffer` from `lua_vm::zio`.
/// TODO(port): replace with `use lua_vm::zio::LexBuffer` in Phase B.
/// types.tsv: Mbuffer → LexBuffer
pub struct LexBuffer {
    buffer: Vec<u8>,
}

impl LexBuffer {
    pub fn new() -> Self {
        LexBuffer { buffer: Vec::new() }
    }

    /// macros.tsv: luaZ_bufflen → buf.len()
    pub fn len(&self) -> usize {
        self.buffer.len()
    }

    /// macros.tsv: luaZ_sizebuffer → buf.capacity()
    pub fn capacity(&self) -> usize {
        self.buffer.capacity()
    }

    /// macros.tsv: luaZ_buffer → buf.as_mut_slice()
    pub fn as_slice(&self) -> &[u8] {
        &self.buffer
    }

    /// macros.tsv: luaZ_resetbuffer → buf.clear()
    pub fn clear(&mut self) {
        self.buffer.clear();
    }

    /// macros.tsv: luaZ_buffremove → buf.truncate_by(i)
    pub fn truncate_by(&mut self, i: usize) {
        let new_len = self.buffer.len().saturating_sub(i);
        self.buffer.truncate(new_len);
    }

    /// allocated capacity. In C this changes `buffsize`, not the live byte
    /// count `n`. The Rust analogue therefore manipulates `Vec::capacity`,
    /// never `Vec::len` (otherwise `push_byte` would write past the live
    /// content and leave embedded zero padding inside the token text).
    pub fn resize(&mut self, _state: &mut LuaState, size: usize) -> Result<(), LuaError> {
        if size < self.buffer.len() {
            self.buffer.truncate(size);
        }
        if size > self.buffer.capacity() {
            let extra = size - self.buffer.capacity();
            self.buffer.reserve_exact(extra);
        }
        Ok(())
    }

    /// Append one byte to the live contents.  Panics if capacity exceeded
    /// (callers must pre-check via `save`).
    fn push_byte(&mut self, c: u8) {
        self.buffer.push(c);
    }
}

impl Default for LexBuffer {
    fn default() -> Self {
        Self::new()
    }
}

/// Placeholder for `ZIO` from `lua_vm::zio`.
/// TODO(port): replace with `use lua_vm::zio::ZIO` in Phase B.
/// types.tsv: Zio → ZIO
pub struct ZIO {
    // TODO(port): full ZIO implementation lives in lua_vm::zio; this is a stub.
    reader: Box<dyn FnMut() -> Option<Vec<u8>>>,
    n: usize,
    p: usize,
    current_chunk: Vec<u8>,
}

impl ZIO {
    /// Construct a ZIO from a reader callback that yields successive chunks.
    pub fn new(reader: Box<dyn FnMut() -> Option<Vec<u8>>>) -> Self {
        ZIO { reader, n: 0, p: 0, current_chunk: Vec::new() }
    }

    /// Construct a ZIO that yields the supplied bytes once and then EOZ.
    pub fn from_bytes(bytes: Vec<u8>) -> Self {
        let mut once = Some(bytes);
        ZIO::new(Box::new(move || once.take()))
    }

    /// macros.tsv: zgetc → z.getc()
    pub fn getc(&mut self) -> i32 {
        if self.n > 0 {
            self.n -= 1;
            let b = self.current_chunk[self.p] as u8;
            self.p += 1;
            b as i32
        } else {
            self.fill()
        }
    }

    fn fill(&mut self) -> i32 {
        match (self.reader)() {
            None => EOZ,
            Some(chunk) if chunk.is_empty() => EOZ,
            Some(chunk) => {
                self.n = chunk.len() - 1;
                self.current_chunk = chunk;
                self.p = 0;
                let b = self.current_chunk[self.p] as u8;
                self.p += 1;
                b as i32
            }
        }
    }
}

// ── Constants ─────────────────────────────────────────────────────────────────

// macros.tsv: FIRST_RESERVED → const FIRST_RESERVED: i32 = 257
/// First token kind value that is not a single-byte character.
/// Single-byte tokens are represented by their ASCII value (0-255).
pub const FIRST_RESERVED: i32 = 257;

// macros.tsv: LUA_ENV → const LUA_ENV: &[u8] = b"_ENV"
/// Name of the global environment upvalue.
pub const LUA_ENV: &[u8] = b"_ENV";

// macros.tsv: NUM_RESERVED → const NUM_RESERVED: usize = (TK_WHILE - FIRST_RESERVED + 1) as usize
/// Number of reserved words (keywords).
pub const NUM_RESERVED: usize = (TK_WHILE - FIRST_RESERVED + 1) as usize;

// macros.tsv: EOZ → const EOZ: i32 = -1
/// End-of-stream sentinel returned by ZIO::getc.
pub const EOZ: i32 = -1;

// macros.tsv: MAX_SIZE → const MAX_SIZE: usize = ...
const MAX_SIZE: usize = if std::mem::size_of::<usize>() < std::mem::size_of::<i64>() {
    usize::MAX
} else {
    i64::MAX as usize
};

// macros.tsv: LUA_MIN_BUFFER → const LUA_MIN_BUFFER: usize = 32
const LUA_MIN_BUFFER: usize = 32;

// ── Token kind constants (ORDER RESERVED — matches C enum RESERVED) ───────────
//
// In C these are enum values.  In Rust we use i32 constants for Phase A
// (faithful to `Token.token: int` in C) with a TODO for a proper enum in Phase B.
//

/// `and`
pub const TK_AND: i32 = 257;
/// `break`
pub const TK_BREAK: i32 = 258;
/// `do`
pub const TK_DO: i32 = 259;
/// `else`
pub const TK_ELSE: i32 = 260;
/// `elseif`
pub const TK_ELSEIF: i32 = 261;
/// `end`
pub const TK_END: i32 = 262;
/// `false`
pub const TK_FALSE: i32 = 263;
/// `for`
pub const TK_FOR: i32 = 264;
/// `function`
pub const TK_FUNCTION: i32 = 265;
/// `goto`
pub const TK_GOTO: i32 = 266;
/// `if`
pub const TK_IF: i32 = 267;
/// `in`
pub const TK_IN: i32 = 268;
/// `local`
pub const TK_LOCAL: i32 = 269;
/// `nil`
pub const TK_NIL: i32 = 270;
/// `not`
pub const TK_NOT: i32 = 271;
/// `or`
pub const TK_OR: i32 = 272;
/// `repeat`
pub const TK_REPEAT: i32 = 273;
/// `return`
pub const TK_RETURN: i32 = 274;
/// `then`
pub const TK_THEN: i32 = 275;
/// `true`
pub const TK_TRUE: i32 = 276;
/// `until`
pub const TK_UNTIL: i32 = 277;
/// `while`  (last keyword; NUM_RESERVED = TK_WHILE - FIRST_RESERVED + 1 = 22)
pub const TK_WHILE: i32 = 278;
/// `//`  (floor division)
pub const TK_IDIV: i32 = 279;
/// `..`  (concatenation)
pub const TK_CONCAT: i32 = 280;
/// `...` (vararg)
pub const TK_DOTS: i32 = 281;
/// `==`
pub const TK_EQ: i32 = 282;
/// `>=`
pub const TK_GE: i32 = 283;
/// `<=`
pub const TK_LE: i32 = 284;
/// `~=`
pub const TK_NE: i32 = 285;
/// `<<`
pub const TK_SHL: i32 = 286;
/// `>>`
pub const TK_SHR: i32 = 287;
/// `::`
pub const TK_DBCOLON: i32 = 288;
/// `<eof>`
pub const TK_EOS: i32 = 289;
/// `<number>`  (float literal)
pub const TK_FLT: i32 = 290;
/// `<integer>` (integer literal)
pub const TK_INT: i32 = 291;
/// `<name>`    (identifier)
pub const TK_NAME: i32 = 292;
/// `<string>`  (string literal)
pub const TK_STRING: i32 = 293;

// ORDER RESERVED — index 0 = TK_AND - FIRST_RESERVED, etc.
/// Display strings for tokens, indexed by `token - FIRST_RESERVED`.
pub static LUAX_TOKENS: &[&[u8]] = &[
    // keywords (indices 0-21)
    b"and", b"break", b"do", b"else", b"elseif",
    b"end", b"false", b"for", b"function", b"goto", b"if",
    b"in", b"local", b"nil", b"not", b"or", b"repeat",
    b"return", b"then", b"true", b"until", b"while",
    // other terminal symbols (indices 22-35)
    b"//", b"..", b"...", b"==", b">=", b"<=", b"~=",
    b"<<", b">>", b"::", b"<eof>",
    b"<number>", b"<integer>", b"<name>", b"<string>",
];

// ── SemInfo / TokenValue ───────────────────────────────────────────────────────

// types.tsv: SemInfo → TokenValue
/// Semantic payload carried by a token.
///
/// Corresponds to `SemInfo` (a C union) in `llex.h`.  In Rust this is a
/// discriminated union (enum).
///
/// # C mapping
/// ```text
/// SemInfo.r   → TokenValue::Float(f64)      (lua_Number)
/// SemInfo.i   → TokenValue::Int(i64)        (lua_Integer)
/// SemInfo.ts  → TokenValue::Str(GcRef<LuaString>)
/// (no C field) → TokenValue::None           (default / unset)
/// ```
#[derive(Clone)]
pub enum TokenValue {
    /// No semantic value (default; used for single-byte and most multi-char tokens).
    None,
    /// Float literal payload.  C: `seminfo.r` (`lua_Number`).
    Float(f64),
    /// Integer literal payload.  C: `seminfo.i` (`lua_Integer`).
    Int(i64),
    /// String/name payload.  C: `seminfo.ts` (`TString *`).
    Str(GcRef<LuaString>),
}

// ── Token ─────────────────────────────────────────────────────────────────────

// types.tsv: Token → Token;  Token.token → i32 (Phase A; TODO: TokenKind enum Phase B)
/// A single lexed token with its semantic payload.
///
/// `kind` is an `i32` whose value is either an ASCII byte code (for single-byte
/// tokens like `+`, `-`, `[`) or one of the `TK_*` constants (for reserved
/// words, multi-char symbols, and literals).
///
/// TODO(port): Phase B — replace `kind: i32` with a proper `TokenKind` enum
/// covering both single-byte and named tokens (e.g. `TokenKind::Char(u8)` +
/// named variants).
#[derive(Clone)]
pub struct Token {
    pub kind: i32,
    pub value: TokenValue,
}

impl Token {
    /// Construct a token with no semantic value.
    pub fn new(kind: i32) -> Self {
        Token { kind, value: TokenValue::None }
    }

    /// The end-of-stream sentinel token.
    pub fn eos() -> Self {
        Token::new(TK_EOS)
    }
}

// ── LexState ──────────────────────────────────────────────────────────────────

// types.tsv: LexState → LexState;  LexState.L removed (thread via &mut LuaState)
/// Per-chunk lexer (and shared parser) state.
///
/// Corresponds to `LexState` in `llex.h`.  Owns the input stream, token
/// buffer, and current/lookahead tokens.
///
/// # C mapping (types.tsv)
/// ```text
/// LexState.current    → current: i32        (charint; -1 = EOZ)
/// LexState.linenumber → linenumber: i32
/// LexState.lastline   → lastline: i32
/// LexState.t          → t: Token            (current token)
/// LexState.lookahead  → lookahead: Token    (one-token lookahead)
/// LexState.fs         → fs: Option<Box<FuncState>>   (parser state)
/// LexState.L          → (removed; callers pass &mut LuaState)
/// LexState.z          → z: ZIO              (owned input stream)
/// LexState.buff       → buff: LexBuffer     (owned token-text buffer)
/// LexState.h          → h: GcRef<LuaTable>  (string-anchor table)
/// LexState.dyd        → dyd: DynData        (parser dynamic data)
/// LexState.source     → source: GcRef<LuaString>
/// LexState.envn       → envn: GcRef<LuaString>
/// ```
pub struct LexState {
    pub current: i32,
    pub linenumber: i32,
    pub lastline: i32,
    pub t: Token,
    pub lookahead: Token,
    // TODO(port): Box<FuncState> once FuncState lands in lua-parse (Phase B)
    pub fs: Option<()>,
    // PORT NOTE: C held a pointer; Rust owns the ZIO directly per types.tsv.
    pub z: ZIO,
    // PORT NOTE: C held a pointer; Rust owns the LexBuffer directly per types.tsv.
    pub buff: LexBuffer,
    // TODO(port): GcRef<LuaTable> once LuaTable is defined in Phase B
    pub h: Option<GcRef<LuaTable>>,
    /// Per-parse-session anchor for long strings. C-Lua's `ls->h` is a Lua
    /// table that deduplicates all literal strings within a chunk (both short
    /// and long), so e.g. `local s1 <const>="..."` and `local s2 <const>="..."`
    /// with identical 50-byte payloads share one `TString` object — which is
    /// what makes `string.format("%p", s1) == string.format("%p", s2)` hold.
    /// Short strings already share identity via the global `interned_lt` pool,
    /// but long strings (>LUAI_MAXSHORTLEN = 40) are not globally interned and
    /// need this session-level map. Keyed by the string bytes; populated lazily
    /// by `new_string`.
    pub long_str_anchor: std::collections::HashMap<Vec<u8>, GcRef<LuaString>>,
    // TODO(port): DynData once parser types land in Phase B
    pub dyd: Option<()>,
    pub source: GcRef<LuaString>,
    pub envn: GcRef<LuaString>,
}

// ── Character-classification helpers ─────────────────────────────────────────
//
// These are simplified ASCII implementations for Phase A.
// TODO(port): import from lua_vm::ctype in Phase B; the full table handles
// the LUA_UCID (Unicode identifiers) flag and matches the C bit-table exactly.
//
// PORT NOTE: the C macros take `int` (not `char`) so they handle EOZ (-1) safely.
// These Rust fns match that contract: EOZ returns false for all predicates.

#[inline]
fn is_digit(c: i32) -> bool {
    c >= b'0' as i32 && c <= b'9' as i32
}

#[inline]
fn is_xdigit(c: i32) -> bool {
    (c >= b'0' as i32 && c <= b'9' as i32)
        || (c >= b'a' as i32 && c <= b'f' as i32)
        || (c >= b'A' as i32 && c <= b'F' as i32)
}

// ALPHABIT: ASCII letters + '_'
#[inline]
fn is_lalpha(c: i32) -> bool {
    (c >= b'a' as i32 && c <= b'z' as i32)
        || (c >= b'A' as i32 && c <= b'Z' as i32)
        || c == b'_' as i32
}

#[inline]
fn is_lalnum(c: i32) -> bool {
    is_lalpha(c) || is_digit(c)
}

#[inline]
fn is_space(c: i32) -> bool {
    matches!(c, 9 | 10 | 11 | 12 | 13 | 32) // \t \n \v \f \r space
}

// PRINTBIT: printable ASCII (graph + space), i.e. 0x20-0x7E
#[inline]
fn is_print(c: i32) -> bool {
    c >= 0x20 && c <= 0x7E
}

#[inline]
fn curr_is_newline(ls: &LexState) -> bool {
    ls.current == b'\n' as i32 || ls.current == b'\r' as i32
}

// ── Low-level stream helpers ───────────────────────────────────────────────────

/// Advance the lexer by one character.
///
/// Corresponds to the `next(ls)` macro.  Named `advance` to avoid collision
/// with Rust's iterator method.
#[inline]
fn advance(ls: &mut LexState) {
    // macros.tsv: zgetc → z.getc()
    ls.current = ls.z.getc();
}

/// Append character `c` to the token buffer, growing it if necessary.
///
/// On overflow calls [`lex_error`] which becomes `Err(LuaError::Syntax(...))`.
///
/// # C source
/// ```c
///
/// //   Mbuffer *b = ls->buff;
/// //   if (luaZ_bufflen(b) + 1 > luaZ_sizebuffer(b)) {
/// //     size_t newsize;
/// //     if (luaZ_sizebuffer(b) >= MAX_SIZE/2)
/// //       lexerror(ls, "lexical element too long", 0);
/// //     newsize = luaZ_sizebuffer(b) * 2;
/// //     luaZ_resizebuffer(ls->L, b, newsize);
/// //   }
/// //   b->buffer[luaZ_bufflen(b)++] = cast_char(c);
/// // }
/// ```
fn save(ls: &mut LexState, state: &mut LuaState, c: i32) -> Result<(), LuaError> {
    // macros.tsv: luaZ_bufflen → buf.len(); luaZ_sizebuffer → buf.capacity()
    if ls.buff.len() + 1 > ls.buff.capacity() {
        if ls.buff.capacity() >= MAX_SIZE / 2 {
            return Err(lex_error(ls, b"lexical element too long", 0));
        }
        //    luaZ_resizebuffer(ls->L, b, newsize);
        // macros.tsv: luaZ_resizebuffer → buf.resize(state, size)?
        let newsize = ls.buff.capacity() * 2;
        ls.buff.resize(state, newsize)?;
    }
    // macros.tsv: cast_char → x as i8  (C char is signed; Lua bytes stored as-is)
    // PORT NOTE: we store the byte value directly; the i8 cast in C is for the
    // C char type but the data is read back as unsigned via cast_uchar everywhere.
    ls.buff.push_byte(c as u8);
    Ok(())
}

/// Save the current character into the token buffer, then advance the stream.
///
/// Corresponds to the `save_and_next(ls)` macro.  Fallible because `save`
/// may need to grow the buffer.
#[inline]
fn save_and_next(ls: &mut LexState, state: &mut LuaState) -> Result<(), LuaError> {
    let c = ls.current;
    save(ls, state, c)?;
    advance(ls);
    Ok(())
}

// ── Error helpers ─────────────────────────────────────────────────────────────

// l_noret → -> !  but in Rust we return LuaError (callers wrap in Err(...))
// error_sites.tsv: luaX_lexerror → return Err(LuaError::syntax_at(ls, "msg", token))
/// Build a syntax error, optionally annotated with the offending token text.
///
/// Corresponds to the static `lexerror` function in `llex.c`.  In C this is
/// `l_noret` (diverges via `luaD_throw`); in Rust it returns a `LuaError`
/// value that callers wrap in `Err(...)`.
///
/// # C source
/// ```c
///
/// //   msg = luaG_addinfo(ls->L, msg, ls->source, ls->linenumber);
/// //   if (token)
/// //     luaO_pushfstring(ls->L, "%s near %s", msg, txtToken(ls, token));
/// //   luaD_throw(ls->L, LUA_ERRSYNTAX);
/// // }
/// ```
pub fn lex_error(ls: &mut LexState, msg: &[u8], token: i32) -> LuaError {
    const LUA_IDSIZE: usize = 60;
    let mut buff = [0u8; LUA_IDSIZE];
    let n = lua_vm::object::chunk_id(&mut buff[..], ls.source.as_bytes());
    let src_part = &buff[..n];

    let mut full_msg: Vec<u8> = Vec::new();
    full_msg.extend_from_slice(src_part);
    let _ = write!(full_msg, ":{}: ", ls.linenumber);
    full_msg.extend_from_slice(msg);

    if token != 0 {
        let tok_text = txt_token(ls, token);
        full_msg.extend_from_slice(b" near ");
        full_msg.extend_from_slice(&tok_text);
    }

    LuaError::syntax_raw(&full_msg)
}

// LUAI_FUNC → pub(crate)
// error_sites.tsv: luaX_syntaxerror → return Err(LuaError::syntax(format_args!("msg")))
/// Report a syntax error at the current token.
///
/// # C source
/// ```c
///
/// //   lexerror(ls, msg, ls->t.token);
/// // }
/// ```
pub fn syntax_error(ls: &mut LexState, msg: &[u8]) -> LuaError {
    let token = ls.t.kind;
    lex_error(ls, msg, token)
}

/// Produce a human-readable representation of `token` for error messages.
///
/// For `TK_NAME`, `TK_STRING`, `TK_FLT`, `TK_INT`: formats the current
/// token buffer contents as `'<text>'`.  For everything else, delegates to
/// [`token2str`].
///
/// # C source
/// ```c
///
/// //   switch (token) {
/// //     case TK_NAME: case TK_STRING:
/// //     case TK_FLT: case TK_INT:
/// //       save(ls, '\0');
/// //       return luaO_pushfstring(ls->L, "'%s'", luaZ_buffer(ls->buff));
/// //     default:
/// //       return luaX_token2str(ls, token);
/// //   }
/// // }
/// ```
///
/// PORT NOTE: C calls `luaO_pushfstring` which pushes the string onto the
/// Lua stack (stack-anchored temporary).  Rust returns `Vec<u8>` directly
/// since there is no stack-based string lifecycle for error formatting.
fn txt_token(ls: &mut LexState, token: i32) -> Vec<u8> {
    match token {
        t if t == TK_NAME || t == TK_STRING || t == TK_FLT || t == TK_INT => {
            let mut v: Vec<u8> = Vec::new();
            v.push(b'\'');
            let buff = ls.buff.as_slice();
            let trimmed = if buff.last() == Some(&0) { &buff[..buff.len() - 1] } else { buff };
            v.extend_from_slice(trimmed);
            v.push(b'\'');
            v
        }
        _ => token2str_raw(token),
    }
}

// LUAI_FUNC → pub(crate)
/// Produce a human-readable token description (for error messages and the parser).
///
/// Single-byte printable tokens are formatted as `'X'`; non-printable as
/// `'<\N>'`.  Reserved words and multi-char symbols are formatted as `'kw'`.
/// Literal tokens (`<name>`, `<string>`, etc.) return the bare label.
///
/// # C source
/// ```c
///
/// //   if (token < FIRST_RESERVED) {
/// //     if (lisprint(token))
/// //       return luaO_pushfstring(ls->L, "'%c'", token);
/// //     else
/// //       return luaO_pushfstring(ls->L, "'<\\%d>'", token);
/// //   }
/// //   else {
/// //     const char *s = luaX_tokens[token - FIRST_RESERVED];
/// //     if (token < TK_EOS)
/// //       return luaO_pushfstring(ls->L, "'%s'", s);
/// //     else
/// //       return s;
/// //   }
/// // }
/// ```
///
/// PORT NOTE: The `LexState` parameter is retained in the signature for API
/// parity with the C export, but is unused in Rust because we don't push onto
/// the Lua stack.  The real formatting is in [`token2str_raw`].
pub fn token2str(_ls: &LexState, token: i32) -> Vec<u8> {
    token2str_raw(token)
}

/// Inner implementation of [`token2str`] that does not need `LexState`.
fn token2str_raw(token: i32) -> Vec<u8> {
    if token < FIRST_RESERVED {
        if is_print(token) {
            vec![b'\'', token as u8, b'\'']
        } else {
            // PORT NOTE: uses write! to Vec<u8> to avoid String allocation for Lua data.
            let mut v: Vec<u8> = Vec::new();
            v.extend_from_slice(b"'<\\");
            let _ = write!(&mut v, "{}", token);
            v.extend_from_slice(b">'");
            v
        }
    } else {
        let idx = (token - FIRST_RESERVED) as usize;
        let s = LUAX_TOKENS[idx];
        if token < TK_EOS {
            let mut v: Vec<u8> = Vec::with_capacity(s.len() + 2);
            v.push(b'\'');
            v.extend_from_slice(s);
            v.push(b'\'');
            v
        } else {
            s.to_vec()
        }
    }
}

// ── Public init / setup ───────────────────────────────────────────────────────

// LUAI_FUNC → pub(crate)
/// Initialise the lexer subsystem: intern all reserved words and fix them
/// in the GC so they are never collected.
///
/// Must be called exactly once during VM startup via `luaX_init`.
///
/// # C source
/// ```c
///
/// //   int i;
/// //   TString *e = luaS_newliteral(L, LUA_ENV);  /* create env name */
/// //   luaC_fix(L, obj2gco(e));  /* never collect this name */
/// //   for (i=0; i<NUM_RESERVED; i++) {
/// //     TString *ts = luaS_new(L, luaX_tokens[i]);
/// //     luaC_fix(L, obj2gco(ts));  /* reserved words are never collected */
/// //     ts->extra = cast_byte(i+1);  /* reserved word */
/// //   }
/// // }
/// ```
pub fn init(state: &mut LuaState) -> Result<(), LuaError> {
    // macros.tsv: luaS_newliteral → state.intern_str(b"...")
    // TODO(port): call state.intern_str(LUA_ENV) once LuaState has that method (Phase B)
    let _e = intern_str_stub(state, LUA_ENV)?;

    // macros.tsv: luaC_objbarrier / luaC_fix — GC fix; no-op in Phases A-C
    // TODO(port): state.gc().fix(e) in Phase D

    for i in 0..NUM_RESERVED {
        // macros.tsv: luaS_new → state.intern_str(...)
        // TODO(port): call state.intern_str(LUAX_TOKENS[i]) in Phase B
        let ts = intern_str_stub(state, LUAX_TOKENS[i])?;

        // TODO(port): state.gc().fix(ts.clone()) in Phase D

        // macros.tsv: cast_byte → x as u8
        // PORT NOTE: LuaString.extra uses Cell<u8> interior mutability.
        // TODO(port): ts.set_extra((i + 1) as u8) — needs pub accessor on LuaString
        let _ = ts; // suppress unused warning until Phase B
    }

    Ok(())
}

// LUAI_FUNC → pub(crate)
/// Initialise `ls` for lexing a new chunk from stream `z`.
///
/// # C source
/// ```c
///
/// //                         TString *source, int firstchar) {
/// //   ls->t.token = 0;
/// //   ls->L = L;
/// //   ls->current = firstchar;
/// //   ls->lookahead.token = TK_EOS;  /* no look-ahead token */
/// //   ls->z = z;
/// //   ls->fs = NULL;
/// //   ls->linenumber = 1;
/// //   ls->lastline = 1;
/// //   ls->source = source;
/// //   ls->envn = luaS_newliteral(L, LUA_ENV);  /* get env name */
/// //   luaZ_resizebuffer(ls->L, ls->buff, LUA_MINBUFFER);
/// // }
/// ```
pub fn set_input(
    state: &mut LuaState,
    ls: &mut LexState,
    z: ZIO,
    source: GcRef<LuaString>,
    firstchar: i32,
) -> Result<(), LuaError> {
    ls.t = Token::new(0);
    ls.current = firstchar;
    ls.lookahead = Token::eos();
    ls.z = z;
    ls.fs = None;
    ls.linenumber = 1;
    ls.lastline = 1;
    ls.source = source;
    // macros.tsv: luaS_newliteral → state.intern_str(b"...")
    // TODO(port): state.intern_str(LUA_ENV) in Phase B
    ls.envn = intern_str_stub(state, LUA_ENV)?;
    // macros.tsv: luaZ_resizebuffer → buf.resize(state, size)?
    ls.buff.resize(state, LUA_MIN_BUFFER)?;
    Ok(())
}

// LUAI_FUNC → pub(crate)
/// Create (or retrieve) a Lua string and anchor it in the parser's GC-protection
/// table `ls.h` so it cannot be collected before the end of compilation.
///
/// Also internalises long strings so that each unique content has exactly one
/// copy in memory.  The table `ls.h` is used as a set: the string is both the
/// key and the value.
///
/// # C source
/// ```c
///
/// //   lua_State *L = ls->L;
/// //   TString *ts = luaS_newlstr(L, str, l);
/// //   const TValue *o = luaH_getstr(ls->h, ts);
/// //   if (!ttisnil(o))  /* string already present? */
/// //     ts = keystrval(nodefromval(o));  /* get saved copy */
/// //   else {
/// //     TValue *stv = s2v(L->top.p++);  /* reserve stack space */
/// //     setsvalue(L, stv, ts);           /* anchor the string */
/// //     luaH_finishset(L, ls->h, stv, o, stv);  /* t[string] = string */
/// //     luaC_checkGC(L);
/// //     L->top.p--;                       /* remove string from stack */
/// //   }
/// //   return ts;
/// // }
/// ```
pub(crate) fn new_string(
    state: &mut LuaState,
    ls: &mut LexState,
    bytes: &[u8],
) -> Result<GcRef<LuaString>, LuaError> {
    // PORT NOTE: in C, the anchor table ls->h is a Lua table mapping the string
    // to itself so a second occurrence of the same literal in the chunk returns
    // the originally-created TString. We use a plain HashMap on LexState
    // (`long_str_anchor`) for the equivalent dedup — sufficient because Phase
    // A-C `GcRef<T>` is `Rc<T>` and identity is determined by the `Rc`
    // allocation. Short strings already share identity via the global pool;
    // long strings (>LUAI_MAXSHORTLEN) need this session-level map.
    if let Some(existing) = ls.long_str_anchor.get(bytes) {
        return Ok(existing.clone());
    }
    let ts = intern_str_stub(state, bytes)?;
    ls.long_str_anchor.insert(bytes.to_vec(), ts.clone());
    Ok(ts)
}

// ── Public advance / lookahead ─────────────────────────────────────────────────

// LUAI_FUNC → pub(crate)
/// Consume the current token; load the next one from the stream.
///
/// If a lookahead token was set, it becomes the current token without re-reading
/// from the stream.
///
/// # C source
/// ```c
///
/// //   ls->lastline = ls->linenumber;
/// //   if (ls->lookahead.token != TK_EOS) {
/// //     ls->t = ls->lookahead;
/// //     ls->lookahead.token = TK_EOS;
/// //   }
/// //   else
/// //     ls->t.token = llex(ls, &ls->t.seminfo);
/// // }
/// ```
pub fn next(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<(), LuaError> {
    ls.lastline = ls.linenumber;

    if ls.lookahead.kind != TK_EOS {
        // Clone to avoid borrow conflict; LuaString inside TokenValue is GcRef (Rc).
        ls.t = ls.lookahead.clone();
        ls.lookahead = Token::eos();
    } else {
        let mut val = TokenValue::None;
        let kind = llex(state, ls, &mut val)?;
        ls.t = Token { kind, value: val };
    }
    Ok(())
}

// LUAI_FUNC → pub(crate)
/// Peek at the next token without consuming the current one.
///
/// The lookahead token is cached in `ls.lookahead` and returned.  Only one
/// token of lookahead is supported; calling this twice without an intervening
/// [`next`] is a logic error (asserted in debug builds).
///
/// # C source
/// ```c
///
/// //   lua_assert(ls->lookahead.token == TK_EOS);
/// //   ls->lookahead.token = llex(ls, &ls->lookahead.seminfo);
/// //   return ls->lookahead.token;
/// // }
/// ```
pub fn lookahead(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<i32, LuaError> {
    // macros.tsv: lua_assert → debug_assert!
    debug_assert!(
        ls.lookahead.kind == TK_EOS,
        "luaX_lookahead: lookahead already set"
    );

    let mut val = TokenValue::None;
    let kind = llex(state, ls, &mut val)?;
    ls.lookahead = Token { kind, value: val };

    Ok(ls.lookahead.kind)
}

// ── Private lexer helpers ──────────────────────────────────────────────────────

/// If the current character equals `c`, advance and return `true`.
///
/// # C source
/// ```c
///
/// //   if (ls->current == c) { next(ls); return 1; }
/// //   else return 0;
/// // }
/// ```
fn check_next1(ls: &mut LexState, c: i32) -> bool {
    if ls.current == c {
        advance(ls);
        true
    } else {
        false
    }
}

/// If the current character is either of the two bytes in `set`, save-and-advance
/// and return `true`.
///
/// # C source
/// ```c
///
/// //   lua_assert(set[2] == '\0');
/// //   if (ls->current == set[0] || ls->current == set[1]) {
/// //     save_and_next(ls);
/// //     return 1;
/// //   }
/// //   else return 0;
/// // }
/// ```
fn check_next2(
    ls: &mut LexState,
    state: &mut LuaState,
    set: &[u8; 2],
) -> Result<bool, LuaError> {
    if ls.current == set[0] as i32 || ls.current == set[1] as i32 {
        save_and_next(ls, state)?;
        Ok(true)
    } else {
        Ok(false)
    }
}

/// Increment the line counter and consume the newline sequence.
///
/// Handles `\n`, `\r`, `\n\r`, and `\r\n`.
///
/// # C source
/// ```c
///
/// //   int old = ls->current;
/// //   lua_assert(currIsNewline(ls));
/// //   next(ls);  /* skip '\n' or '\r' */
/// //   if (currIsNewline(ls) && ls->current != old)
/// //     next(ls);  /* skip '\n\r' or '\r\n' */
/// //   if (++ls->linenumber >= MAX_INT)
/// //     lexerror(ls, "chunk has too many lines", 0);
/// // }
/// ```
fn inc_line_number(ls: &mut LexState, _state: &mut LuaState) -> Result<(), LuaError> {
    // macros.tsv: lua_assert → debug_assert!
    debug_assert!(curr_is_newline(ls), "inc_line_number: not at a newline");

    let old = ls.current;
    advance(ls);

    if curr_is_newline(ls) && ls.current != old {
        advance(ls);
    }

    // macros.tsv: MAX_INT → i32::MAX
    ls.linenumber += 1;
    if ls.linenumber >= i32::MAX {
        return Err(lex_error(ls, b"chunk has too many lines", 0));
    }
    Ok(())
}

/// Scan a numeric literal (integer or float, decimal or hex).
///
/// The caller may have already read an initial dot.  Accepts the pattern:
/// `%d(%x|%.|(Ee[+-]?))*` or `0[Xx](%x|%.|(Pp[+-]?))*`.
///
/// Returns `TK_INT` for integers, `TK_FLT` for floats.
///
/// # C source
/// ```c
///
/// //   TValue obj;
/// //   const char *expo = "Ee";
/// //   int first = ls->current;
/// //   lua_assert(lisdigit(ls->current));
/// //   save_and_next(ls);
/// //   if (first == '0' && check_next2(ls, "xX"))  /* hexadecimal? */
/// //     expo = "Pp";
/// //   for (;;) {
/// //     if (check_next2(ls, expo))
/// //       check_next2(ls, "-+");
/// //     else if (lisxdigit(ls->current) || ls->current == '.')
/// //       save_and_next(ls);
/// //     else break;
/// //   }
/// //   if (lislalpha(ls->current))  /* numeral touching a letter? */
/// //     save_and_next(ls);         /* force an error */
/// //   save(ls, '\0');
/// //   if (luaO_str2num(luaZ_buffer(ls->buff), &obj) == 0)
/// //     lexerror(ls, "malformed number", TK_FLT);
/// //   if (ttisinteger(&obj)) { seminfo->i = ivalue(&obj); return TK_INT; }
/// //   else { seminfo->r = fltvalue(&obj); return TK_FLT; }
/// // }
/// ```
fn read_numeral(
    state: &mut LuaState,
    ls: &mut LexState,
    seminfo: &mut TokenValue,
) -> Result<i32, LuaError> {
    let mut expo: &[u8; 2] = b"Ee";

    let first = ls.current;

    debug_assert!(is_digit(ls.current), "read_numeral: not at a digit");

    save_and_next(ls, state)?;

    if first == b'0' as i32 && check_next2(ls, state, b"xX")? {
        expo = b"Pp";
    }

    loop {
        if check_next2(ls, state, expo)? {
            check_next2(ls, state, b"-+")?;
        } else if is_xdigit(ls.current) || ls.current == b'.' as i32 {
            //      save_and_next(ls);
            save_and_next(ls, state)?;
        } else {
            break;
        }
    }

    if is_lalpha(ls.current) {
        save_and_next(ls, state)?;
    }

    // In Rust, luaO_str2num will receive a byte slice; NUL is not needed.
    // We save 0 for parity with C, but our str2num stub ignores it.
    save(ls, state, 0)?;

    //        lexerror(ls, "malformed number", TK_FLT);
    // macros.tsv: luaZ_buffer → buf.as_mut_slice()
    let buf = ls.buff.as_slice();
    let num_bytes = if buf.last() == Some(&0) { &buf[..buf.len() - 1] } else { buf };
    let mut obj = lua_types::LuaValue::Nil;
    if lua_vm::object::str2num(num_bytes, &mut obj) == 0 {
        return Err(lex_error(ls, b"malformed number", TK_FLT));
    }
    match obj {
        lua_types::LuaValue::Int(i) => {
            *seminfo = TokenValue::Int(i);
            Ok(TK_INT)
        }
        lua_types::LuaValue::Float(f) => {
            *seminfo = TokenValue::Float(f);
            Ok(TK_FLT)
        }
        _ => unreachable!("str2num returned non-numeric LuaValue"),
    }
}

/// Scan a `[=*[` or `]=*]` sequence; leave the last bracket as current char.
///
/// Returns:
/// - `count + 2` if well-formed (where `count` is the number of `=` signs),
/// - `1` if a single bracket with no `=`s and no second bracket,
/// - `0` if malformed (e.g. `[==` with no closing bracket).
///
/// # C source
/// ```c
///
/// //   size_t count = 0;
/// //   int s = ls->current;
/// //   lua_assert(s == '[' || s == ']');
/// //   save_and_next(ls);
/// //   while (ls->current == '=') {
/// //     save_and_next(ls);
/// //     count++;
/// //   }
/// //   return (ls->current == s) ? count + 2
/// //          : (count == 0) ? 1
/// //          : 0;
/// // }
/// ```
fn skip_sep(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<usize, LuaError> {
    let mut count: usize = 0;
    let s = ls.current;
    debug_assert!(s == b'[' as i32 || s == b']' as i32, "skip_sep: not at bracket");

    save_and_next(ls, state)?;

    while ls.current == b'=' as i32 {
        save_and_next(ls, state)?;
        count += 1;
    }

    if ls.current == s {
        Ok(count + 2)
    } else if count == 0 {
        Ok(1)
    } else {
        Ok(0)
    }
}

/// Scan a long string or long comment delimited by `[=*[` … `]=*]`.
///
/// `seminfo` is `Some` when reading a string literal; `None` when skipping a
/// long comment.  When `None`, buffer contents are discarded on each newline
/// to avoid wasting memory.
///
/// # C source
/// ```c
///
/// //   int line = ls->linenumber;
/// //   save_and_next(ls);  /* skip 2nd '[' */
/// //   if (currIsNewline(ls)) inclinenumber(ls);
/// //   for (;;) {
/// //     switch (ls->current) {
/// //       case EOZ: { /* error */
/// //         const char *what = (seminfo ? "string" : "comment");
/// //         const char *msg = luaO_pushfstring(..., what, line);
/// //         lexerror(ls, msg, TK_EOS);
/// //         break;
/// //       }
/// //       case ']': {
/// //         if (skip_sep(ls) == sep) {
/// //           save_and_next(ls);  /* skip 2nd ']' */
/// //           goto endloop;
/// //         }
/// //         break;
/// //       }
/// //       case '\n': case '\r': {
/// //         save(ls, '\n');
/// //         inclinenumber(ls);
/// //         if (!seminfo) luaZ_resetbuffer(ls->buff);
/// //         break;
/// //       }
/// //       default: {
/// //         if (seminfo) save_and_next(ls);
/// //         else next(ls);
/// //       }
/// //     }
/// //   } endloop:
/// //   if (seminfo)
/// //     seminfo->ts = luaX_newstring(ls, luaZ_buffer(ls->buff) + sep,
/// //                                      luaZ_bufflen(ls->buff) - 2 * sep);
/// // }
/// ```
fn read_long_string(
    state: &mut LuaState,
    ls: &mut LexState,
    seminfo: Option<&mut TokenValue>,
    sep: usize,
) -> Result<(), LuaError> {
    let line = ls.linenumber;

    save_and_next(ls, state)?;

    if curr_is_newline(ls) {
        inc_line_number(ls, state)?;
    }

    // is_string: whether we are reading a string (true) or a comment (false)
    let is_string = seminfo.is_some();

    loop {
        match ls.current {
            c if c == EOZ => {
                let what: &[u8] = if is_string { b"string" } else { b"comment" };
                // PORT NOTE: build message as Vec<u8> to avoid String allocation.
                let mut msg: Vec<u8> = Vec::new();
                msg.extend_from_slice(b"unfinished long ");
                msg.extend_from_slice(what);
                msg.extend_from_slice(b" (starting at line ");
                let _ = write!(&mut msg, "{}", line);
                msg.push(b')');
                return Err(lex_error(ls, &msg, TK_EOS));
            }
            c if c == b']' as i32 => {
                let s = skip_sep(state, ls)?;
                if s == sep {
                    save_and_next(ls, state)?;
                    break;
                }
                // else: the ']' sequence wasn't the closing delimiter; continue
            }
            c if c == b'\n' as i32 || c == b'\r' as i32 => {
                save(ls, state, b'\n' as i32)?;
                inc_line_number(ls, state)?;
                // macros.tsv: luaZ_resetbuffer → buf.clear()
                if !is_string {
                    ls.buff.clear();
                }
            }
            _ => {
                if is_string {
                    save_and_next(ls, state)?;
                } else {
                    advance(ls);
                }
            }
        }
    }

    //      seminfo->ts = luaX_newstring(ls, luaZ_buffer(ls->buff) + sep,
    //                                       luaZ_bufflen(ls->buff) - 2 * sep);
    if let Some(out) = seminfo {
        // The buffer contains: sep bytes of '[=' + content + sep bytes of '=]'
        // We want the content in between.
        // PORT NOTE: per PORTING.md §4.3, capture the slice into an owned
        // Vec so the immutable borrow of ls.buff is dropped before the
        // mutable borrow needed by new_string.
        let buf = ls.buff.as_slice();
        let content: Vec<u8> = buf[sep..buf.len() - sep].to_vec();
        let ts = new_string(state, ls, &content)?;
        *out = TokenValue::Str(ts);
    }
    Ok(())
}

/// Check `c` is non-zero (truthy); if not, save the current char and raise a
/// string-escape error.
///
/// # C source
/// ```c
///
/// //   if (!c) {
/// //     if (ls->current != EOZ)
/// //       save_and_next(ls);  /* add current to buffer for error message */
/// //     lexerror(ls, msg, TK_STRING);
/// //   }
/// // }
/// ```
fn esc_check(
    state: &mut LuaState,
    ls: &mut LexState,
    ok: bool,
    msg: &[u8],
) -> Result<(), LuaError> {
    if !ok {
        if ls.current != EOZ {
            save_and_next(ls, state)?;
        }
        return Err(lex_error(ls, msg, TK_STRING));
    }
    Ok(())
}

/// Save-and-advance, then verify the new current char is a hex digit; return
/// its numeric value (0-15).
///
/// # C source
/// ```c
///
/// //   save_and_next(ls);
/// //   esccheck (ls, lisxdigit(ls->current), "hexadecimal digit expected");
/// //   return luaO_hexavalue(ls->current);
/// // }
/// ```
fn get_hexa(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<u32, LuaError> {
    save_and_next(ls, state)?;
    esc_check(state, ls, is_xdigit(ls.current), b"hexadecimal digit expected")?;
    // TODO(port): call lua_vm::object::hex_value in Phase B
    Ok(hex_value_stub(ls.current))
}

/// Scan a `\xNN` hex escape; return the decoded byte value.
///
/// # C source
/// ```c
///
/// //   int r = gethexa(ls);
/// //   r = (r << 4) + gethexa(ls);
/// //   luaZ_buffremove(ls->buff, 2);  /* remove saved chars from buffer */
/// //   return r;
/// // }
/// ```
fn read_hex_esc(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<u32, LuaError> {
    let r = get_hexa(state, ls)?;
    let r = (r << 4) + get_hexa(state, ls)?;
    // macros.tsv: luaZ_buffremove → buf.truncate_by(i)
    ls.buff.truncate_by(2);
    Ok(r)
}

/// Scan a `\u{XXXXXX}` UTF-8 escape; return the Unicode codepoint.
///
/// # C source
/// ```c
///
/// //   unsigned long r;
/// //   int i = 4;  /* chars to remove: '\', 'u', '{', first digit */
/// //   save_and_next(ls);  /* skip 'u' */
/// //   esccheck(ls, ls->current == '{', "missing '{'");
/// //   r = gethexa(ls);  /* must have at least one digit */
/// //   while (cast_void(save_and_next(ls)), lisxdigit(ls->current)) {
/// //     i++;
/// //     esccheck(ls, r <= (0x7FFFFFFFu >> 4), "UTF-8 value too large");
/// //     r = (r << 4) + luaO_hexavalue(ls->current);
/// //   }
/// //   esccheck(ls, ls->current == '}', "missing '}'");
/// //   next(ls);  /* skip '}' */
/// //   luaZ_buffremove(ls->buff, i);
/// //   return r;
/// // }
/// ```
fn read_utf8_esc(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<u32, LuaError> {
    let mut i: usize = 4;

    save_and_next(ls, state)?;

    esc_check(state, ls, ls.current == b'{' as i32, b"missing '{'")?;

    let mut r = get_hexa(state, ls)?;

    // cast_void: discard return value
    loop {
        save_and_next(ls, state)?;
        if !is_xdigit(ls.current) {
            break;
        }
        i += 1;
        esc_check(state, ls, r <= (0x7FFF_FFFFu32 >> 4), b"UTF-8 value too large")?;
        // TODO(port): lua_vm::object::hex_value in Phase B
        r = (r << 4) + hex_value_stub(ls.current);
    }

    esc_check(state, ls, ls.current == b'}' as i32, b"missing '}'")?;

    advance(ls);

    ls.buff.truncate_by(i);

    Ok(r)
}

/// Scan `\u{...}` and append the UTF-8 encoding of the codepoint to the buffer.
///
/// # C source
/// ```c
///
/// //   char buff[UTF8BUFFSZ];
/// //   int n = luaO_utf8esc(buff, readutf8esc(ls));
/// //   for (; n > 0; n--)
/// //     save(ls, buff[UTF8BUFFSZ - n]);
/// // }
/// ```
fn utf8_esc(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<(), LuaError> {
    let codepoint = read_utf8_esc(state, ls)?;

    // macros.tsv: UTF8BUFFSZ → const UTF8_BUF_SZ: usize = 8
    // TODO(port): call lua_vm::object::utf8_esc_encode(codepoint) in Phase B.
    // For Phase A, encode directly here.
    let encoded = utf8_encode_stub(codepoint);

    for &b in &encoded {
        save(ls, state, b as i32)?;
    }
    Ok(())
}

/// Scan a decimal escape `\ddd` (up to 3 digits); return the byte value.
///
/// # C source
/// ```c
///
/// //   int i;
/// //   int r = 0;
/// //   for (i = 0; i < 3 && lisdigit(ls->current); i++) {
/// //     r = 10*r + ls->current - '0';
/// //     save_and_next(ls);
/// //   }
/// //   esccheck(ls, r <= UCHAR_MAX, "decimal escape too large");
/// //   luaZ_buffremove(ls->buff, i);  /* remove read digits from buffer */
/// //   return r;
/// // }
/// ```
fn read_dec_esc(
    state: &mut LuaState,
    ls: &mut LexState,
) -> Result<u32, LuaError> {
    let mut i: usize = 0;
    let mut r: u32 = 0;

    while i < 3 && is_digit(ls.current) {
        r = 10 * r + (ls.current as u32 - b'0' as u32);
        save_and_next(ls, state)?;
        i += 1;
    }

    // UCHAR_MAX = 255 = u8::MAX
    esc_check(state, ls, r <= u8::MAX as u32, b"decimal escape too large")?;

    ls.buff.truncate_by(i);
    Ok(r)
}

/// Scan a short (single/double-quoted) string literal.
///
/// The C function uses `goto read_save / only_save / no_save` for escape
/// handling.  In Rust this is replaced by the `EscapeResult` enum.
///
/// # C source (see llex.c lines 382-442 for full listing)
fn read_string(
    state: &mut LuaState,
    ls: &mut LexState,
    del: i32,
    seminfo: &mut TokenValue,
) -> Result<(), LuaError> {
    // Encoding for what the escape sequence handler needs to do after decoding.
    //
    // read_save:  advance(ls), remove '\' from buffer, save decoded byte
    // only_save:  remove '\' from buffer, save decoded byte (no advance)
    // no_save:    nothing (just break from the escape case)
    enum EscapeResult {
        ReadSave(i32),
        OnlySave(i32),
        NoSave,
    }

    save_and_next(ls, state)?;

    while ls.current != del {
        match ls.current {
            c if c == EOZ => {
                return Err(lex_error(ls, b"unfinished string", TK_EOS));
            }
            c if c == b'\n' as i32 || c == b'\r' as i32 => {
                return Err(lex_error(ls, b"unfinished string", TK_STRING));
            }
            c if c == b'\\' as i32 => {
                save_and_next(ls, state)?;

                // Inner switch on the escape character
                let esc = match ls.current {
                    c if c == b'a' as i32 => EscapeResult::ReadSave(b'\x07' as i32),
                    c if c == b'b' as i32 => EscapeResult::ReadSave(b'\x08' as i32),
                    c if c == b'f' as i32 => EscapeResult::ReadSave(b'\x0C' as i32),
                    c if c == b'n' as i32 => EscapeResult::ReadSave(b'\n' as i32),
                    c if c == b'r' as i32 => EscapeResult::ReadSave(b'\r' as i32),
                    c if c == b't' as i32 => EscapeResult::ReadSave(b'\t' as i32),
                    c if c == b'v' as i32 => EscapeResult::ReadSave(b'\x0B' as i32),
                    c if c == b'x' as i32 => {
                        let decoded = read_hex_esc(state, ls)?;
                        EscapeResult::ReadSave(decoded as i32)
                    }
                    c if c == b'u' as i32 => {
                        utf8_esc(state, ls)?;
                        EscapeResult::NoSave
                    }
                    c if c == b'\n' as i32 || c == b'\r' as i32 => {
                        inc_line_number(ls, state)?;
                        EscapeResult::OnlySave(b'\n' as i32)
                    }
                    c if c == b'\\' as i32 || c == b'"' as i32 || c == b'\'' as i32 => {
                        EscapeResult::ReadSave(c)
                    }
                    c if c == EOZ => EscapeResult::NoSave,
                    c if c == b'z' as i32 => {
                        ls.buff.truncate_by(1);
                        advance(ls);
                        while is_space(ls.current) {
                            if curr_is_newline(ls) {
                                inc_line_number(ls, state)?;
                            } else {
                                advance(ls);
                            }
                        }
                        EscapeResult::NoSave
                    }
                    _ => {
                        esc_check(
                            state, ls,
                            is_digit(ls.current),
                            b"invalid escape sequence",
                        )?;
                        let decoded = read_dec_esc(state, ls)?;
                        EscapeResult::OnlySave(decoded as i32)
                    }
                };

                // Dispatch the C goto targets as match arms.
                match esc {
                    EscapeResult::ReadSave(c) => {
                        advance(ls);
                        ls.buff.truncate_by(1);
                        save(ls, state, c)?;
                    }
                    EscapeResult::OnlySave(c) => {
                        ls.buff.truncate_by(1);
                        save(ls, state, c)?;
                    }
                    EscapeResult::NoSave => {}
                }
            }
            _ => {
                save_and_next(ls, state)?;
            }
        }
    }

    save_and_next(ls, state)?;

    //                                     luaZ_bufflen(ls->buff) - 2);
    // Buffer contains: delimiter + content + delimiter; strip both delimiters.
    // PORT NOTE: capture into owned Vec to drop the borrow before new_string.
    let buf = ls.buff.as_slice();
    let content: Vec<u8> = if buf.len() >= 2 {
        buf[1..buf.len() - 1].to_vec()
    } else {
        Vec::new()
    };
    let ts = new_string(state, ls, &content)?;
    *seminfo = TokenValue::Str(ts);
    Ok(())
}

/// Core lexer dispatch: consume and return the next raw token kind.
///
/// This is the heart of the lexer: a large `for`-`switch` loop that classifies
/// the current character and dispatches to the appropriate scanner.
///
/// # C source (see llex.c lines 445-562 for full listing)
fn llex(
    state: &mut LuaState,
    ls: &mut LexState,
    seminfo: &mut TokenValue,
) -> Result<i32, LuaError> {
    // macros.tsv: luaZ_resetbuffer → buf.clear()
    ls.buff.clear();

    loop {
        match ls.current {
            c if c == b'\n' as i32 || c == b'\r' as i32 => {
                inc_line_number(ls, state)?;
                // PORT NOTE: skipcomment-equivalent. luaL_loadfile in C-Lua
                // strips a leading '#' line (Unix shebang). Our test harness
                // prepends a global-setup preamble to every official test, so
                // the script's '#' line is not at byte zero. Apply the same
                // rule at any token-scan line start: treat a line whose first
                // character is '#' as a single-line comment. This sits in
                // llex's dispatch loop (not inc_line_number) so it does not
                // affect newlines inside long-bracket strings.
                if ls.current == b'#' as i32 {
                    while !curr_is_newline(ls) && ls.current != EOZ {
                        advance(ls);
                    }
                }
            }

            c if c == b' ' as i32
                || c == b'\x0C' as i32
                || c == b'\t' as i32
                || c == b'\x0B' as i32 =>
            {
                advance(ls);
            }

            c if c == b'-' as i32 => {
                advance(ls);
                if ls.current != b'-' as i32 {
                    return Ok(b'-' as i32);
                }
                advance(ls);

                if ls.current == b'[' as i32 {
                    let sep = skip_sep(state, ls)?;
                    ls.buff.clear();
                    if sep >= 2 {
                        read_long_string(state, ls, None, sep)?;
                        ls.buff.clear();
                        continue;
                    }
                }
                while !curr_is_newline(ls) && ls.current != EOZ {
                    advance(ls);
                }
                // loop continues (no token emitted for comments)
            }

            c if c == b'[' as i32 => {
                let sep = skip_sep(state, ls)?;
                if sep >= 2 {
                    read_long_string(state, ls, Some(seminfo), sep)?;
                    return Ok(TK_STRING);
                } else if sep == 0 {
                    return Err(lex_error(ls, b"invalid long string delimiter", TK_STRING));
                }
                // sep == 1: plain '[', no long string
                return Ok(b'[' as i32);
            }

            c if c == b'=' as i32 => {
                advance(ls);
                if check_next1(ls, b'=' as i32) {
                    return Ok(TK_EQ);
                }
                return Ok(b'=' as i32);
            }

            c if c == b'<' as i32 => {
                advance(ls);
                if check_next1(ls, b'=' as i32) {
                    return Ok(TK_LE);
                } else if check_next1(ls, b'<' as i32) {
                    return Ok(TK_SHL);
                }
                return Ok(b'<' as i32);
            }

            c if c == b'>' as i32 => {
                advance(ls);
                if check_next1(ls, b'=' as i32) {
                    return Ok(TK_GE);
                } else if check_next1(ls, b'>' as i32) {
                    return Ok(TK_SHR);
                }
                return Ok(b'>' as i32);
            }

            c if c == b'/' as i32 => {
                advance(ls);
                if check_next1(ls, b'/' as i32) {
                    return Ok(TK_IDIV);
                }
                return Ok(b'/' as i32);
            }

            c if c == b'~' as i32 => {
                advance(ls);
                if check_next1(ls, b'=' as i32) {
                    return Ok(TK_NE);
                }
                return Ok(b'~' as i32);
            }

            c if c == b':' as i32 => {
                advance(ls);
                if check_next1(ls, b':' as i32) {
                    return Ok(TK_DBCOLON);
                }
                return Ok(b':' as i32);
            }

            c if c == b'"' as i32 || c == b'\'' as i32 => {
                let del = ls.current;
                read_string(state, ls, del, seminfo)?;
                return Ok(TK_STRING);
            }

            c if c == b'.' as i32 => {
                save_and_next(ls, state)?;
                if check_next1(ls, b'.' as i32) {
                    if check_next1(ls, b'.' as i32) {
                        return Ok(TK_DOTS);
                    }
                    return Ok(TK_CONCAT);
                } else if !is_digit(ls.current) {
                    return Ok(b'.' as i32);
                } else {
                    return read_numeral(state, ls, seminfo);
                }
            }

            c if is_digit(c) => {
                return read_numeral(state, ls, seminfo);
            }

            c if c == EOZ => {
                return Ok(TK_EOS);
            }

            c => {
                if is_lalpha(c) {
                    loop {
                        save_and_next(ls, state)?;
                        if !is_lalnum(ls.current) {
                            break;
                        }
                    }

                    // PORT NOTE: copy buffer bytes to drop borrow before new_string.
                    let content: Vec<u8> = ls.buff.as_slice().to_vec();
                    let ts = new_string(state, ls, &content)?;

                    // PORT NOTE: canonical `lua_types::LuaString` lacks the `extra`
                    // byte that C-Lua uses to mark reserved words. Recover the
                    // keyword index directly from the interned bytes via the
                    // `LUAX_TOKENS` table; the first `NUM_RESERVED` entries are
                    // the keywords in declaration order, so token id =
                    // `FIRST_RESERVED + index`.
                    let reserved_token: Option<i32> = LUAX_TOKENS[..NUM_RESERVED]
                        .iter()
                        .position(|kw| *kw == content.as_slice())
                        .map(|i| FIRST_RESERVED + i as i32);
                    *seminfo = TokenValue::Str(ts);

                    if let Some(tk) = reserved_token {
                        return Ok(tk);
                    } else {
                        return Ok(TK_NAME);
                    }
                } else {
                    let tok = ls.current;
                    advance(ls);
                    return Ok(tok);
                }
            }
        }
    }
}

// ── Phase A stubs for cross-crate helpers ──────────────────────────────────────
//
// The functions below stand in for cross-crate calls that cannot resolve in
// Phase A.  They will be replaced by proper imports in Phase B.

// TODO(port): replace with state.intern_str(bytes) once LuaState gains that
// method (from lua_vm::string::new_lstr wired in Phase B).
// TODO_ARCH(phase-b-reconcile): canonical LuaString is constructed via
// from_bytes; once LuaState::intern_str is wired, route through there instead.
fn intern_str_stub(
    state: &mut LuaState,
    bytes: &[u8],
) -> Result<GcRef<LuaString>, LuaError> {
    state.intern_str(bytes)
}

// TODO(port): replace with lua_vm::object::hex_value(c) in Phase B.
fn hex_value_stub(c: i32) -> u32 {
    match c {
        c if c >= b'0' as i32 && c <= b'9' as i32 => (c - b'0' as i32) as u32,
        c if c >= b'a' as i32 && c <= b'f' as i32 => (c - b'a' as i32 + 10) as u32,
        c if c >= b'A' as i32 && c <= b'F' as i32 => (c - b'A' as i32 + 10) as u32,
        _ => 0,
    }
}

// TODO(port): replace with lua_vm::object::utf8_esc_encode(codepoint) in Phase B.
/// Encode a Unicode codepoint as a Lua-extended UTF-8 byte sequence (1 to 6 bytes).
///
/// Faithful port of `luaO_utf8esc` from lobject.c.  Lua permits codepoints up
/// to `0x7FFFFFFF` (5- and 6-byte sequences are non-strict UTF-8 but accepted
/// by `\u{...}` escapes per literals.lua test cases).
fn utf8_encode_stub(codepoint: u32) -> Vec<u8> {
    debug_assert!(codepoint <= 0x7FFF_FFFF);
    if codepoint < 0x80 {
        return vec![codepoint as u8];
    }
    let mut x = codepoint;
    let mut mfb: u32 = 0x3f;
    let mut buf: Vec<u8> = Vec::with_capacity(8);
    loop {
        buf.push(0x80 | ((x & 0x3f) as u8));
        x >>= 6;
        mfb >>= 1;
        if x <= mfb {
            break;
        }
    }
    buf.push(((!mfb << 1) | x) as u8);
    buf.reverse();
    buf
}

// ──────────────────────────────────────────────────────────────────────────────
// PORT STATUS
//   source:        src/llex.c  (581 lines, 24 functions)
//                  src/llex.h  (91 lines; merged)
//   target_crate:  lua-lex
//   confidence:    medium
//   todos:         18
//   port_notes:    12
//   unsafe_blocks: 0   (must be 0 outside explicit unsafe-budget crates)
//   notes:         Logic is faithful to the C.  The main structural differences:
//                  (1) LexState.L removed — state threaded via fn params;
//                  (2) save/save_and_next/inclinenumber/helpers are all fallible
//                  (Result<_, LuaError>) because lexerror is no longer noreturn;
//                  (3) goto read_save/only_save/no_save in read_string replaced
//                  by EscapeResult enum; (4) Cross-crate calls (intern_str,
//                  luaH_getstr/finishset, luaG_addinfo, luaO_str2num,
//                  luaO_hexavalue, luaO_utf8esc, luaC_fix, luaC_checkGC) are
//                  stubbed with TODO; (5) LuaError, LuaString, ZIO, LexBuffer,
//                  LuaState defined as local stubs — Phase B replaces with real
//                  imports once the crate graph is wired.  Key Phase B tasks:
//                  wire import paths; move LuaString.extra accessor to pub;
//                  implement luaX_newstring anchor-table logic.  Numeric
//                  literal parsing now delegates to lua_vm::object::str2num
//                  (handles hex integers with wrap-around and hex floats).
// ──────────────────────────────────────────────────────────────────────────────