docs(frontend): explain parsing entry points and source diagnostics
This commit is contained in:
@@ -1,3 +1,4 @@
|
||||
//! lexer、parser、AST 与 compiler 共用的位置/错误协议;字节跨度与用户显示的 Unicode 行列分开保存。
|
||||
use std::error::Error;
|
||||
use std::fmt;
|
||||
|
||||
@@ -5,55 +6,76 @@ use std::fmt;
|
||||
/// 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<SourceLocation> {
|
||||
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<String>,
|
||||
}
|
||||
|
||||
impl Diagnostic {
|
||||
/// lexer 和词法规则共用的失败包装,统一设置 Lexical 类别并保留原文字节范围。
|
||||
pub(crate) fn lexical(span: Span, message: impl Into<String>) -> Self {
|
||||
Self {
|
||||
kind: DiagnosticKind::Lexical,
|
||||
@@ -63,12 +85,14 @@ impl Diagnostic {
|
||||
}
|
||||
}
|
||||
|
||||
/// 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,
|
||||
@@ -80,25 +104,36 @@ impl fmt::Display for Diagnostic {
|
||||
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user