freemarker 0.1.1

//! 词法器 —— 对应 Java `freemarker.core.FMParserTokenManager`（FTL.jj TOKEN 块）
//!
//! JavaCC 正文实际 7 个词法状态（FTL.jj:585 注释陈旧，SwitchTo 实证；
//! parser spec §2.1 与 Java 上游报告 §12 已修正）在本实现中由调用上下文隐式表达：
//! - `DEFAULT`：模板文本扫描（`scan_text_chunk`，识别 `<#`/`<@`/`${`/`<#--` 等）；
//! - `FM_EXPRESSION` / `NO_SPACE_EXPRESSION` / `NAMED_PARAMETER_EXPRESSION`：
//!   `next_expr_token(ExprCtx)` 按表达式上下文出 token（三个状态的差异在本实现中
//!   表现为 `ExprCtx` 与括号深度，语义等价，见 docs/03 §2.3 规则 1/3/6）；
//! - `IN_PAREN`：括号深度 > 0 时 `>`/`>=` 为比较运算符而非标签结束（`parenthesisNesting`）；
//! - `NO_PARSE`：`<#-- -->` 注释、`<#comment>`、`<#noparse>` 内容（`scan_comment`/`scan_unparsed`）。
//!
//! 词法特殊规则（docs/03 §2.3）：
//! 1. `<` 歧义：`<` 仅在后跟 `#`/`@`/`/`（严格语法）或已知指令名（非严格语法）时为标签开头，
//!    否则为文本（`a < b` 原样输出）；
//! 2. `$${` 转义为字面 `$` + 插值（`scan_text_chunk` 中把前一个 `$` 并入文本）；
//! 3. `[#` 为方括号指令语法，`[` 后非 `#` 为文本（表达式状态中 `[` 是列表字面量）；
//! 4. 注释 `<#-- -->` 在文本与表达式状态均可出现；
//! 5. 字符串插值 `"a${x}b"` 的原始扫描与 `${`/`#{` 起始检测（解码与插值在 grammar.rs）；
//! 6. 数字后缀 `L/F/D/B`、`0x` 十六进制、指数（超出 JavaCC 的 INTEGER/DECIMAL 的扩展，
//!    对应 value.rs 的 TNumber 映射契约）；
//! 7. 指令名大小写不敏感（`<#IF>` 合法，FTL.jj 中大小写敏感，此处按项目规范放宽）；
//! 8. 空白剥离标记在 grammar.rs 解析期完成；
//! 9. `[#ftl]` 头部仅在模板首行有效（grammar.rs 的 Root 产生式处理）。
use crate::error::{Result, TemplateError};

/// 标签语法（对应 `Configuration.TAG_SYNTAX`，首个标签自动检测）
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum TagSyntax {
    /// `<>` 尖括号语法（默认）
    Angle,
    /// `[]` 方括号语法
    Square,
}

/// 表达式词法上下文（对应 JavaCC 词法状态：标签参数区 vs 插值内部）
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ExprCtx {
    /// 指令标签参数区：括号深度 0 时 `>`（或方括号语法下 `]`）结束标签；
    /// 对应 FM_EXPRESSION / NO_SPACE_EXPRESSION / NAMED_PARAMETER_EXPRESSION / IN_PAREN
    Tag { square: bool },
    /// `${...}` / `#{...}` 插值内部：`}` 结束插值，`>` 为普通比较符；
    /// 对应 FM_EXPRESSION 的 postInterpolationLexState 语义
    Interp,
}

/// 表达式 token（对应 FTL.jj `<FM_EXPRESSION, ...> TOKEN` 块）
#[derive(Debug, Clone, PartialEq)]
pub(crate) enum Tok {
    /// 标识符（含非 ASCII 与 `\` 转义字符，如 `a\-b` → "a-b"）
    Ident(String),
    /// 数字字面量原始文本（含 0x/指数/后缀，未转换；转换在 grammar.rs）
    Number(String),
    /// 字符串字面量原始内容（含转义序列，未解码；不含引号）
    Str(String),
    /// 原始字符串 `r"..."` 内容（无转义、无插值）
    RawStr(String),
    True,
    False,
    In,
    As,
    Using,
    /// `lt` / `\lt` / `<` / `&lt;`（LESS_THAN）
    Lt,
    /// `lte` / `\lte` / `<=` / `&lt;=`
    Lte,
    /// `gt` / `\gt` / `&gt;`（NATURAL_GT 仅括号内/插值内；标签内 `>` 是结束符）
    Gt,
    /// `gte` / `\gte` / `&gt;=`
    Gte,
    Plus,
    Minus,
    Times,
    /// `**`（DOUBLE_STAR）
    DoubleStar,
    Divide,
    Percent,
    PlusEq,
    MinusEq,
    TimesEq,
    DivEq,
    ModEq,
    PlusPlus,
    MinusMinus,
    /// `=` 或 `==`（DOUBLE_EQUALS 与 EQUALS 语义合一）
    Eq,
    NotEq,
    /// `!`（EXCLAM，默认值/逻辑非共用）
    Exclam,
    /// `??`（EXISTS）
    Exists,
    /// `?`（BUILT_IN）
    Builtin,
    /// `&` / `&&` / `&amp;&amp;` / `\and`
    And,
    /// `|` / `||`
    Or,
    /// `->` / `-&gt;`
    LambdaArrow,
    Dot,
    DotDot,
    /// `..<` 或 `..!`（排端范围）
    DotDotLess,
    /// `..*`（无界范围）
    DotDotStar,
    /// `...`（宏 catch-all 参数）
    Ellipsis,
    Comma,
    Semicolon,
    Colon,
    OpenParen,
    CloseParen,
    OpenBracket,
    CloseBracket,
    OpenCurly,
    CloseCurly,
    /// 标签结束 `>` / `]`（括号深度 0；对应 DIRECTIVE_END）
    TagEnd,
    /// 标签结束 `/>` / `/]`（对应 EMPTY_DIRECTIVE_END）
    EmptyTagEnd,
    /// 插值结束 `}`（对应 CLOSING_CURLY_BRACKET 的 endInterpolation 分支）
    InterpEnd,
    Eof,
}

/// 文本扫描的停止原因（DEFAULT 状态出口）
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum TextStop {
    /// 文本结束（模板文件尾）
    Eof,
    /// 遇到标签开头（`<#`/`<@`/`</#`/`<#--` 等，或非严格语法的 `<name`）
    Tag,
    /// 遇到 `${` / `#{`（插值开始；`$${` 时前一个 `$` 已并入文本）
    Interp,
}

/// 标签开头（`read_tag_open` 消费后的分类）
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum TagOpen {
    /// `<#name` / `[#name` 指令开始
    Dir { square: bool },
    /// `<@name` / `[@name` 用户指令（宏）调用开始
    Call { square: bool },
    /// `</#name` / `[/#name` 指令结束标签
    EndDir { square: bool },
    /// `</@name` / `[/@name` 调用结束标签
    EndCall { square: bool },
    /// `<#--` / `[#--` 简洁注释（TERSE_COMMENT）
    TerseComment { square: bool },
}

/// 可保存/恢复的词法位置（用于前瞻：named-args 判定、非严格标签判定等）
#[derive(Debug, Clone, Copy)]
pub(crate) struct LexerPos {
    pos: usize,
    line: u32,
    col: u32,
    paren_depth: u32,
    bracket_depth: u32,
    curly_depth: u32,
}

/// 词法器状态（对应 FMParserTokenManager 的字段）
pub(crate) struct Lexer {
    chars: Vec<char>,
    pos: usize,
    line: u32,
    col: u32,
    /// 括号嵌套深度（对应 parenthesisNesting；> 0 时 `>` 是 NATURAL_GT）
    pub(crate) paren_depth: u32,
    /// 方括号嵌套深度（对应 bracketNesting；> 0 时 `]` 关闭列表字面量）
    pub(crate) bracket_depth: u32,
    /// 花括号嵌套深度（对应 curlyBracketNesting；> 0 时 `}` 关闭哈希字面量）
    pub(crate) curly_depth: u32,
    /// 严格语法模式（对应 token_source.strictSyntaxMode；`<#ftl strict_syntax=false>` 可关闭；
    /// 初始值取 Configuration.settings.strict_syntax）
    pub(crate) strict_syntax: bool,
    /// 已确立的标签语法（对应 squBracTagSyntax + autodetectTagSyntax；首标签决定）
    pub(crate) tag_syntax: Option<TagSyntax>,
    /// 模板名（错误消息用）
    name: String,
}

// 实现按职责拆分（#[path] 聚合，参照 grammar.rs 模式）：
// - lexer_expr.rs —— 表达式 token 主循环与核心分发表
// - lexer_scan.rs —— 数字/字符串/标识符/注释/noparse 内容扫描
// - lexer_tests.rs —— 测试（#[cfg(test)]）
#[path = "lexer_expr.rs"]
mod lexer_expr;
#[path = "lexer_scan.rs"]
mod lexer_scan;
#[cfg(test)]
#[path = "lexer_tests.rs"]
mod lexer_tests;

impl Lexer {
    pub(crate) fn new(name: &str, text: &str, strict_syntax: bool) -> Self {
        Lexer {
            chars: text.chars().collect(),
            pos: 0,
            line: 1,
            col: 1,
            paren_depth: 0,
            bracket_depth: 0,
            curly_depth: 0,
            strict_syntax,
            tag_syntax: None,
            name: name.to_string(),
        }
    }

    pub(crate) fn save(&self) -> LexerPos {
        LexerPos {
            pos: self.pos,
            line: self.line,
            col: self.col,
            paren_depth: self.paren_depth,
            bracket_depth: self.bracket_depth,
            curly_depth: self.curly_depth,
        }
    }

    pub(crate) fn restore(&mut self, p: &LexerPos) {
        self.pos = p.pos;
        self.line = p.line;
        self.col = p.col;
        self.paren_depth = p.paren_depth;
        self.bracket_depth = p.bracket_depth;
        self.curly_depth = p.curly_depth;
    }

    /// 当前字符（不消费）
    pub(crate) fn peek(&self) -> Option<char> {
        self.chars.get(self.pos).copied()
    }

    /// 当前字符后第 offset 个字符（不消费）
    pub(crate) fn peek_at(&self, offset: usize) -> Option<char> {
        self.chars.get(self.pos + offset).copied()
    }

    /// 消费一个字符并维护行列（`\n`、`\r`、`\r\n` 计为换行）
    pub(crate) fn bump(&mut self) -> Option<char> {
        let c = self.chars.get(self.pos).copied()?;
        self.pos += 1;
        match c {
            '\n' => {
                self.line += 1;
                self.col = 1;
            }
            '\r' => {
                // \r\n 视为单个换行：\r 自身不计数，紧随的 \n 由 \n 分支计数（共 +1 行）
                self.col = 1;
            }
            _ => {
                self.col += 1;
            }
        }
        Some(c)
    }

    /// 当前行列（1-based）
    pub(crate) fn line_col(&self) -> (u32, u32) {
        (self.line, self.col)
    }

    /// 解析错误：Syntax error in template "<name>" in line L, column C: <details>
    /// （Java ParseException.getMessage 格式，jar 实测）
    pub(crate) fn err(&self, line: u32, col: u32, details: impl Into<String>) -> TemplateError {
        TemplateError::Parse {
            template: self.name.clone(),
            line,
            col,
            message: details.into(),
        }
    }

    /// 跳过空白（表达式状态 SKIP：空格/制表/换行/回车）
    pub(crate) fn skip_ws(&mut self) {
        while let Some(c) = self.peek() {
            if c == ' ' || c == '\t' || c == '\n' || c == '\r' {
                self.bump();
            } else {
                break;
            }
        }
    }

    /// 当前字符是否可能开始一个标签（DEFAULT 状态的 `<`/`[` 歧义判定，docs/03 §2.3 规则 1/3）
    pub(crate) fn starts_tag(&mut self) -> bool {
        let save = self.save();
        let r = self.starts_tag_inner();
        self.restore(&save);
        r
    }

    fn starts_tag_inner(&mut self) -> bool {
        match self.peek() {
            Some('<') => match self.peek_at(1) {
                // `<#name` / `<#--`：`<#` 后必须是字母/下划线或 `--`（注释），否则是文本
                Some('#') => match self.peek_at(2) {
                    Some(c) if c.is_ascii_alphabetic() || c == '_' => true,
                    Some('-') => self.peek_at(3) == Some('-'),
                    _ => false,
                },
                // `<@name`
                Some('@') => true,
                // `</#` / `</@` / 非严格语法的 `</name`
                Some('/') => match self.peek_at(2) {
                    Some('#') | Some('@') => true,
                    _ => {
                        if !self.strict_syntax {
                            self.bump();
                            self.bump();
                            return self.non_strict_tag_name(true);
                        }
                        false
                    }
                },
                // 非严格语法：`<name`（已知指令名 + 合法形状）
                Some(c) if c.is_ascii_alphabetic() || c == '_' => {
                    if self.strict_syntax {
                        false
                    } else {
                        self.bump();
                        self.non_strict_tag_name(false)
                    }
                }
                _ => false,
            },
            Some('[') => match self.peek_at(1) {
                // `[#name` / `[#--`（方括号语法；`[` 后非 `#`/`@` 为文本）
                Some('#') => match self.peek_at(2) {
                    Some(c) if c.is_ascii_alphabetic() || c == '_' => true,
                    Some('-') => self.peek_at(3) == Some('-'),
                    _ => false,
                },
                Some('@') => true,
                Some('/') => matches!(self.peek_at(2), Some('#') | Some('@')),
                _ => false,
            },
            _ => false,
        }
    }

    /// 非严格语法：`<`（或 `</`）已消费，当前位于指令名首字符。
    /// 要求：已知指令名（大小写不敏感）且形状合法 —— 需要参数的指令后跟空白；
    /// 简单指令与结束标签后跟空白*闭合符。返回是否应视为标签
    /// （JavaCC 最长匹配失败则回落为文本）。
    fn non_strict_tag_name(&mut self, is_end: bool) -> bool {
        let name = self.read_name();
        let Some(name) = name else { return false };
        if !DIRECTIVE_NAMES.contains(&name.as_str()) || name == "ftl" {
            // `<ftl>` 不是 FTL_HEADER（FTL.jj 仅 `<#ftl`/`[#ftl`），按 Java 语义为文本
            return false;
        }
        if is_end {
            // `</if>` 等结束标签：空白*闭合符（END_xxx token 用 CLOSE_TAG1）
            self.skip_ws();
            return matches!(self.peek(), Some('>') | Some(']'))
                || (self.peek() == Some('/') && matches!(self.peek_at(1), Some('>') | Some(']')));
        }
        let param_required = PARAM_DIRECTIVES.contains(&name.as_str());
        if param_required {
            // `<if x>` 合法；`<if>`/`<ifx>` 为文本（IF token 需要 BLANK）
            matches!(self.peek(), Some(c) if c == ' ' || c == '\t' || c == '\n' || c == '\r')
        } else {
            // `<else>`/`<break>` 等：空白*（`/`）?（`>`|`]`）
            self.skip_ws();
            match self.peek() {
                Some('>') | Some(']') => true,
                Some('/') => matches!(self.peek_at(1), Some('>') | Some(']')),
                _ => false,
            }
        }
    }

    /// 读取标签/指令名（字母与下划线；对应 UNKNOWN_DIRECTIVE 的 `[A-Za-z_]+`）
    pub(crate) fn read_name(&mut self) -> Option<String> {
        let mut s = String::new();
        while let Some(c) = self.peek() {
            if c.is_ascii_alphabetic() || c == '_' {
                s.push(c);
                self.bump();
            } else {
                break;
            }
        }
        if s.is_empty() {
            None
        } else {
            Some(s)
        }
    }

    /// 消费 `<`/`[` 标签开头并分类（调用前必须 starts_tag() == true）
    pub(crate) fn read_tag_open(&mut self) -> TagOpen {
        let square = self.peek() == Some('[');
        self.bump(); // < 或 [
        match self.peek() {
            Some('#') => {
                self.bump();
                if self.peek() == Some('-') && self.peek_at(1) == Some('-') {
                    self.bump();
                    self.bump();
                    TagOpen::TerseComment { square }
                } else {
                    TagOpen::Dir { square }
                }
            }
            Some('@') => {
                self.bump();
                TagOpen::Call { square }
            }
            Some('/') => {
                self.bump();
                match self.peek() {
                    Some('@') => {
                        self.bump();
                        TagOpen::EndCall { square }
                    }
                    // `</#name` 或非严格语法 `</name`（`#` 可选）
                    Some('#') => {
                        self.bump();
                        TagOpen::EndDir { square }
                    }
                    _ => TagOpen::EndDir { square },
                }
            }
            // 非严格语法 `<name`：START_TAG "<" 后直接跟指令名（starts_tag 已保证合法）
            Some(c) if c.is_ascii_alphabetic() || c == '_' => TagOpen::Dir { square },
            _ => unreachable!("starts_tag 已保证标签开头"),
        }
    }

    /// 消费标签/指令结束符 `>`、`/>`、`]`、`/]`（允许任意组合，宽于 JavaCC 的
    /// CLOSE_TAG1/CLOSE_TAG2 区分；文档化偏差）。返回 false 表示不匹配。
    pub(crate) fn try_read_tag_end(&mut self) -> Option<bool> {
        // 跳过前面空白：FreeMarker 允许 `</#if >` 的 `>` 前有空格
        // （Java FTL.jj LOOKAHEAD 在标签结束匹配 `>` 时隐含允许空白）
        while let Some(c) = self.peek() {
            if c == ' ' || c == '\t' || c == '\n' || c == '\r' {
                self.bump();
            } else {
                break;
            }
        }
        // 返回 Some(true) = `/>`（自闭合），Some(false) = `>`
        match self.peek() {
            Some('>') => {
                self.bump();
                Some(false)
            }
            Some(']') => {
                self.bump();
                Some(false)
            }
            Some('/') => match self.peek_at(1) {
                Some('>') | Some(']') => {
                    self.bump();
                    self.bump();
                    Some(true)
                }
                _ => None,
            },
            _ => None,
        }
    }

    /// 扫描一段模板文本（DEFAULT 状态），直到标签/插值开头或文件尾。
    /// `$${` 时前一个 `$` 并入文本（docs/03 §2.3 规则 2）。
    pub(crate) fn scan_text_chunk(&mut self) -> Result<(String, TextStop)> {
        let mut text = String::new();
        loop {
            match self.peek() {
                None => return Ok((text, TextStop::Eof)),
                Some('<') | Some('[') => {
                    if self.starts_tag() {
                        return Ok((text, TextStop::Tag));
                    }
                    text.push(self.bump().unwrap());
                }
                Some('$') => {
                    if self.peek_at(1) == Some('{') {
                        return Ok((text, TextStop::Interp));
                    }
                    if self.peek_at(1) == Some('$') && self.peek_at(2) == Some('{') {
                        // `$${`：字面 `$` + 插值开始
                        text.push(self.bump().unwrap());
                        continue;
                    }
                    text.push(self.bump().unwrap());
                }
                Some('#') => {
                    if self.peek_at(1) == Some('{') {
                        // 传统数值插值 `#{expr}`（legacy NumericalOutput，契约坍缩为 Interpolation）
                        return Ok((text, TextStop::Interp));
                    }
                    text.push(self.bump().unwrap());
                }
                Some(c) => {
                    text.push(c);
                    self.bump();
                }
            }
        }
    }
}

/// 标识符起始字符（ID_START_CHAR 近似：字母（含非 ASCII）、`$`、`_`、`@`；
/// Java isLegacyFTLIdStartChar 的 `@`..`Z` 区间 = `@` + A-Z，identifierChars
/// 生成器见 FTL.jj:1427；`\` 转义字符在 scan_ident 内处理）
fn is_ident_start(c: char) -> bool {
    c.is_alphabetic() || c == '$' || c == '_' || c == '@'
}

/// 标识符续字符（ID_START_CHAR 或 ASCII 数字）
fn is_ident_continue(c: char) -> bool {
    is_ident_start(c) || c.is_ascii_digit()
}

/// 全部内置指令名（大小写不敏感匹配；对应 _CoreAPI.ALL_BUILT_IN_DIRECTIVE_NAMES 的
/// 本实现子集 —— 仅包含本解析器支持的指令）
pub(crate) const DIRECTIVE_NAMES: &[&str] = &[
    "attempt",
    "recover",
    "if",
    "elseif",
    "else",
    "list",
    "items",
    "sep",
    "switch",
    "case",
    "default",
    "assign",
    "global",
    "local",
    "include",
    "import",
    "macro",
    "function",
    "stop",
    "return",
    "break",
    "continue",
    "nested",
    "flush",
    "t",
    "lt",
    "rt",
    "nt",
    "compress",
    "comment",
    "noparse",
    "escape",
    "noescape",
    "trim",
    "autoesc",
    "noautoesc",
    "outputformat",
    "setting",
    "call",
    "foreach",
    "transform",
    "visit",
    "recurse",
    "on",
    "fallback",
    "ftl",
];

/// 需要参数（后跟空白）的指令 —— 非严格语法下 `<name>` 判定用（IF/LIST 等 token 需 BLANK）
pub(crate) const PARAM_DIRECTIVES: &[&str] = &[
    "if",
    "elseif",
    "list",
    "items",
    "switch",
    "case",
    "assign",
    "global",
    "local",
    "include",
    "import",
    "macro",
    "function",
    "stop",
    "return",
    "nested",
    "escape",
    "setting",
    "call",
    "foreach",
    "transform",
    "visit",
    "recurse",
    "on",
    "outputformat",
    "ftl",
];