//! lexer 产生、parser 消费的轻量 Token；文本通过 span 从原 SourceUnit 借取，不在 Token 中复制。
use crate::Span;

/// Text is located by span in the original source. Names stay contextual: the
/// lexer does not turn syntax words into globally reserved keywords.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// lexer.peg 输出的种类；语法关键字仍是 Name，由 grammar.peg 按原文上下文识别。
pub enum TokenKind {
    // Unicode 名称，包含上下文关键字；这里只区分词形，不决定语义用途。
    Name,
    // 无符号十进制整数/小数拼写；负号是单独 Token，精确值由编译器构造。
    Number,
    /// Span includes quotes. Escapes have been checked, not decoded.
    // 含引号的字符串范围，转义已校验但未解码；解析时再生成拥有文本。
    String,
    // 左圆括号，用于参数、调用或括号表达式。
    LeftParen,
    // 右圆括号，调用范围在它之后结束。
    RightParen,
    // 左花括号，开始类或语句块。
    LeftBrace,
    // 右花括号，结束类或语句块。
    RightBrace,
    // 类型注解及继承声明的冒号。
    Colon,
    // 参数和实参间的分隔符。
    Comma,
    // 成员访问或符号字面量的点。
    Dot,
    // 单等号赋值，不与双等号比较混淆。
    Equal,
    // 双等号相等比较。
    EqualEqual,
    // 不等比较。
    NotEqual,
    // 小于比较。
    Less,
    // 小于等于比较。
    LessEqual,
    // 大于比较。
    Greater,
    // 大于等于比较。
    GreaterEqual,
    // 加法操作符。
    Plus,
    // 减法或一元取负，由语法上下文区分。
    Minus,
    // 乘法操作符。
    Star,
    // 除法操作符；双斜杠行注释在 trivia 阶段跳过。
    Slash,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// 一次词法输出；Token 可复制，但只保存种类和字节范围，调用方须保留匹配的原文以读取内容。
pub struct Token {
    // parser 按此选择语法分支，名称关键字额外检查原文。
    pub kind: TokenKind,
    // 原始 UTF-8 输入的半开范围，不含前面被跳过的空白/注释。
    pub span: Span,
}