//! lexer、parser、AST 与 compiler 共用的位置/错误协议;字节跨度与用户显示的 Unicode 行列分开保存。 use std::error::Error; use std::fmt; /// Half-open UTF-8 byte range in the original source, including trivia between /// the first and last syntax token. EOF has an empty range at source.len(). #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)] #[serde(deny_unknown_fields)] /// 语法节点及 Token 的半开原文字节范围 [start,end),EOF 使用 source.len() 处的空区间。 pub struct Span { // 包含的起始字节偏移,应落在 UTF-8 字符边界。 pub start: usize, // 不包含的结束字节偏移,包含两端 Token 之间的注释/空白。 pub end: usize, } impl Span { /// 词法/语法规则及测试构造范围,仅保存偏移;合法性由 slice 或 AST 校验验证。 pub const fn new(start: usize, end: usize) -> Self { Self { start, end } } /// Safely read this range, rejecting reversed, out-of-bounds or split UTF-8 ranges. /// AST Spanned::source_text 及文档校验调用;安全拒绝倒序、越界或切断 UTF-8 字符的范围。 pub fn slice(self, source: &str) -> Option<&str> { source.get(self.start..self.end) } /// AST Spanned::location 和编译器调用,先验证整个范围,再计算起点的显示行列。 pub fn location(self, source: &str) -> Option { self.slice(source)?; Some(source_location(source, self.start)) } /// parser 组合左右节点及后缀范围时调用;沿用第一个起点和最后一个终点,不另做顺序检查。 pub(crate) fn through(self, last: Self) -> Self { Self::new(self.start, last.end) } } #[derive(Debug, Clone, Copy, PartialEq, Eq)] /// 阶段分类供宿主和测试区分错误发生于分词、语法、名称分析还是生成。 pub enum DiagnosticKind { // 词法规则无法接受字符或字符串转义等输入。 Lexical, // Token 已合法,但无法匹配指定根的语法。 Syntax, // 编译名称/控制流分析拒绝重复、未知或未初始化读取。 Semantic, // AST 校验或指令生成/验证失败,尚未执行 VM。 Compilation, } /// Lines and Unicode scalar columns are one-based. CRLF counts as one newline. #[derive(Debug, Clone, Copy, PartialEq, Eq)] /// source_location 输出的一基位置;列按 Unicode 标量计数,CRLF 合并为一个换行。 pub struct SourceLocation { // 从一开始的逻辑行号,独立 CR 和 LF 均换行,CRLF 只换一次。 pub line: usize, // 从一开始的 Unicode 标量列,不是字节数、字素簇数或终端显示宽度。 pub column: usize, } #[derive(Debug, Clone, PartialEq, Eq)] /// 各阶段产生的不带来源快照的错误,SourceUnit::annotate 可补来源和行列。 pub struct Diagnostic { // 原始失败阶段,便于测试和宿主按类别处理。 pub kind: DiagnosticKind, // 原源码字节位置,Display 直接显示这个范围。 pub span: Span, // 面向用户的说明,不含来源名及行列前缀。 pub message: String, // 语法解析器报告的期望项;词法和编译器辅助构造通常留空。 pub expected: Vec, } impl Diagnostic { /// lexer 和词法规则共用的失败包装,统一设置 Lexical 类别并保留原文字节范围。 pub(crate) fn lexical(span: Span, message: impl Into) -> Self { Self { kind: DiagnosticKind::Lexical, span, message: message.into(), expected: Vec::new(), } } /// SourceUnit::annotate 及宿主根据起始偏移计算位置;本入口不校验整个 span,调用方应传对应原文。 pub fn location(&self, source: &str) -> SourceLocation { source_location(source, self.span.start) } } impl fmt::Display for Diagnostic { /// 未绑定来源的错误显示说明及字节区间;来源行列由 SourceDiagnostic 的 Display 提供。 fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { write!( formatter, "{} at bytes {}..{}", self.message, self.span.start, self.span.end ) } } impl Error for Diagnostic {} /// Span::location 和 Diagnostic::location 共用的纯文本扫描,计算 position 前缀的行列,不执行 IO。 /// 调用方应提供有效字节边界;此辅助函数只扫描到偏移或 EOF,不负责校验范围。 fn source_location(source: &str, position: usize) -> SourceLocation { // 空前缀位于第一行第一列,每消费一个普通 Unicode 标量才前进一列。 let mut location = SourceLocation { line: 1, column: 1 }; // 记录上一个已消费字符是否 CR,使紧随其后的 LF 不再次增加行号。 let mut previous_cr = false; // char_indices 同时提供字节边界和完整字符,避免把多字节字符算成多列。 for (offset, character) in source.char_indices() { // 当前字符起点已到目标位置,不能把目标字符本身算进前缀。 if offset >= position { break; } // 换行重置列;普通字符(包括 tab)仅按一个 Unicode 标量计列。 match character { // CR 自身就是换行,可能随后与 LF 配成一个换行。 '\r' => { location.line += 1; location.column = 1; } // CR 已完成换行,这个 LF 不再增加行号。 '\n' if previous_cr => {} // 独立 LF 换到下一行第一列。 '\n' => { location.line += 1; location.column = 1; } _ => location.column += 1, } // 每轮都更新,只有紧邻 CR 的 LF 才会被合并。 previous_cr = character == '\r'; } location }