docs(frontend): explain parsing entry points and source diagnostics

This commit is contained in:
2026-11-15 18:38:22 +08:00
parent 5c079c6c58
commit 6da2e54bcf
8 changed files with 164 additions and 1 deletions
+1 -1
View File
@@ -27,7 +27,7 @@ pub struct CompileOptions {
/// 宿主及 compiler 集成测试的源码编译入口:按指定模式解析,再校验 AST、解析名称并生成模板。 /// 宿主及 compiler 集成测试的源码编译入口:按指定模式解析,再校验 AST、解析名称并生成模板。
/// source 提供文件身份与原始文本;mode 决定模块、表达式或交互根;options 声明额外宿主名称。 /// source 提供文件身份与原始文本;mode 决定模块、表达式或交互根;options 声明额外宿主名称。
/// 解析错误已有源码诊断;后续编译错误在这里附加同一源码的位置和片段,成功不执行任何 VM 指令。 /// 解析错误已有源码诊断;后续编译错误在这里附加同一源码的来源和行列位置,成功不执行任何 VM 指令。
pub fn compile_source( pub fn compile_source(
source: &SourceUnit, source: &SourceUnit,
mode: ParseMode, mode: ParseMode,
+12
View File
@@ -1,23 +1,33 @@
//! compiler 和宿主共用的语法树门面:生成类型、可定制访问器、版本化 JSON 文档及源码位置辅助接口。
//! AST types and walkers generated from the single Endor.asdl schema. //! AST types and walkers generated from the single Endor.asdl schema.
//! Runtime objects remain in the objects crate. //! Runtime objects remain in the objects crate.
// 类型及 Spanned 实现来自 Endor.asdl 对应生成器,避免前端与编辑器各维护一套结构。
mod generated; mod generated;
// 公开借用节点的遍历协议,文档校验和宿主工具可覆盖访问并积累自己的状态。
pub mod visitor; pub mod visitor;
// JSON 编解码、schema 和跨度/父子范围校验通过此模块实现。
mod wire; mod wire;
// 宿主和编译器从 ast 直接引用 Program/Expr/Stmt 等生成类型。
pub use generated::*; pub use generated::*;
// 文档验证失败使用统一错误类型,不等同于 VM 执行错误。
pub use wire::AstError; pub use wire::AstError;
use crate::{SourceLocation, Span}; use crate::{SourceLocation, Span};
/// A syntax node's half-open byte range in its original UTF-8 source. /// A syntax node's half-open byte range in its original UTF-8 source.
/// 生成 AST 节点实现的原文定位协议,编译分析、编辑器和测试用它取得字节范围或源片段。
pub trait Spanned { pub trait Spanned {
/// 具体节点实现返回存储的半开字节范围,不自行读取源码。
fn span(&self) -> Span; fn span(&self) -> Span;
/// 宿主/测试按节点范围借用原文;无效 UTF-8 边界或越界返回 None,不分配字符串。
fn source_text<'a>(&self, source: &'a str) -> Option<&'a str> { fn source_text<'a>(&self, source: &'a str) -> Option<&'a str> {
self.span().slice(source) self.span().slice(source)
} }
/// 宿主/测试从对应原文计算起点行列;范围不合法时返回 None。
fn location(&self, source: &str) -> Option<SourceLocation> { fn location(&self, source: &str) -> Option<SourceLocation> {
self.span().location(source) self.span().location(source)
} }
@@ -25,9 +35,11 @@ pub trait Spanned {
impl Program { impl Program {
/// Iterate the currently supported top-level function declarations. /// Iterate the currently supported top-level function declarations.
/// 前端 AST 测试或宿主只需顶层函数时使用;保持声明顺序,类及其方法不进入此迭代器。
pub fn functions(&self) -> impl Iterator<Item = &Function> { pub fn functions(&self) -> impl Iterator<Item = &Function> {
self.declarations self.declarations
.iter() .iter()
// 仅取函数声明借用,类仍保留在 declarations,调用方可另行遍历。
.filter_map(|declaration| match &declaration.kind { .filter_map(|declaration| match &declaration.kind {
DeclKind::Function(function) => Some(function), DeclKind::Function(function) => Some(function),
DeclKind::Class(_) => None, DeclKind::Class(_) => None,
+35
View File
@@ -1,3 +1,4 @@
//! lexer、parser、AST 与 compiler 共用的位置/错误协议;字节跨度与用户显示的 Unicode 行列分开保存。
use std::error::Error; use std::error::Error;
use std::fmt; use std::fmt;
@@ -5,55 +6,76 @@ use std::fmt;
/// the first and last syntax token. EOF has an empty range at source.len(). /// 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)] #[derive(Debug, Clone, Copy, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)] #[serde(deny_unknown_fields)]
/// 语法节点及 Token 的半开原文字节范围 [start,end),EOF 使用 source.len() 处的空区间。
pub struct Span { pub struct Span {
// 包含的起始字节偏移,应落在 UTF-8 字符边界。
pub start: usize, pub start: usize,
// 不包含的结束字节偏移,包含两端 Token 之间的注释/空白。
pub end: usize, pub end: usize,
} }
impl Span { impl Span {
/// 词法/语法规则及测试构造范围,仅保存偏移;合法性由 slice 或 AST 校验验证。
pub const fn new(start: usize, end: usize) -> Self { pub const fn new(start: usize, end: usize) -> Self {
Self { start, end } Self { start, end }
} }
/// Safely read this range, rejecting reversed, out-of-bounds or split UTF-8 ranges. /// 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> { pub fn slice(self, source: &str) -> Option<&str> {
source.get(self.start..self.end) source.get(self.start..self.end)
} }
/// AST Spanned::location 和编译器调用,先验证整个范围,再计算起点的显示行列。
pub fn location(self, source: &str) -> Option<SourceLocation> { pub fn location(self, source: &str) -> Option<SourceLocation> {
self.slice(source)?; self.slice(source)?;
Some(source_location(source, self.start)) Some(source_location(source, self.start))
} }
/// parser 组合左右节点及后缀范围时调用;沿用第一个起点和最后一个终点,不另做顺序检查。
pub(crate) fn through(self, last: Self) -> Self { pub(crate) fn through(self, last: Self) -> Self {
Self::new(self.start, last.end) Self::new(self.start, last.end)
} }
} }
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// 阶段分类供宿主和测试区分错误发生于分词、语法、名称分析还是生成。
pub enum DiagnosticKind { pub enum DiagnosticKind {
// 词法规则无法接受字符或字符串转义等输入。
Lexical, Lexical,
// Token 已合法,但无法匹配指定根的语法。
Syntax, Syntax,
// 编译名称/控制流分析拒绝重复、未知或未初始化读取。
Semantic, Semantic,
// AST 校验或指令生成/验证失败,尚未执行 VM。
Compilation, Compilation,
} }
/// Lines and Unicode scalar columns are one-based. CRLF counts as one newline. /// Lines and Unicode scalar columns are one-based. CRLF counts as one newline.
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// source_location 输出的一基位置;列按 Unicode 标量计数,CRLF 合并为一个换行。
pub struct SourceLocation { pub struct SourceLocation {
// 从一开始的逻辑行号,独立 CR 和 LF 均换行,CRLF 只换一次。
pub line: usize, pub line: usize,
// 从一开始的 Unicode 标量列,不是字节数、字素簇数或终端显示宽度。
pub column: usize, pub column: usize,
} }
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
/// 各阶段产生的不带来源快照的错误,SourceUnit::annotate 可补来源和行列。
pub struct Diagnostic { pub struct Diagnostic {
// 原始失败阶段,便于测试和宿主按类别处理。
pub kind: DiagnosticKind, pub kind: DiagnosticKind,
// 原源码字节位置,Display 直接显示这个范围。
pub span: Span, pub span: Span,
// 面向用户的说明,不含来源名及行列前缀。
pub message: String, pub message: String,
// 语法解析器报告的期望项;词法和编译器辅助构造通常留空。
pub expected: Vec<String>, pub expected: Vec<String>,
} }
impl Diagnostic { impl Diagnostic {
/// lexer 和词法规则共用的失败包装,统一设置 Lexical 类别并保留原文字节范围。
pub(crate) fn lexical(span: Span, message: impl Into<String>) -> Self { pub(crate) fn lexical(span: Span, message: impl Into<String>) -> Self {
Self { Self {
kind: DiagnosticKind::Lexical, kind: DiagnosticKind::Lexical,
@@ -63,12 +85,14 @@ impl Diagnostic {
} }
} }
/// SourceUnit::annotate 及宿主根据起始偏移计算位置;本入口不校验整个 span,调用方应传对应原文。
pub fn location(&self, source: &str) -> SourceLocation { pub fn location(&self, source: &str) -> SourceLocation {
source_location(source, self.span.start) source_location(source, self.span.start)
} }
} }
impl fmt::Display for Diagnostic { impl fmt::Display for Diagnostic {
/// 未绑定来源的错误显示说明及字节区间;来源行列由 SourceDiagnostic 的 Display 提供。
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!( write!(
formatter, formatter,
@@ -80,25 +104,36 @@ impl fmt::Display for Diagnostic {
impl Error for Diagnostic {} impl Error for Diagnostic {}
/// Span::location 和 Diagnostic::location 共用的纯文本扫描,计算 position 前缀的行列,不执行 IO。
/// 调用方应提供有效字节边界;此辅助函数只扫描到偏移或 EOF,不负责校验范围。
fn source_location(source: &str, position: usize) -> SourceLocation { fn source_location(source: &str, position: usize) -> SourceLocation {
// 空前缀位于第一行第一列,每消费一个普通 Unicode 标量才前进一列。
let mut location = SourceLocation { line: 1, column: 1 }; let mut location = SourceLocation { line: 1, column: 1 };
// 记录上一个已消费字符是否 CR,使紧随其后的 LF 不再次增加行号。
let mut previous_cr = false; let mut previous_cr = false;
// char_indices 同时提供字节边界和完整字符,避免把多字节字符算成多列。
for (offset, character) in source.char_indices() { for (offset, character) in source.char_indices() {
// 当前字符起点已到目标位置,不能把目标字符本身算进前缀。
if offset >= position { if offset >= position {
break; break;
} }
// 换行重置列;普通字符(包括 tab)仅按一个 Unicode 标量计列。
match character { match character {
// CR 自身就是换行,可能随后与 LF 配成一个换行。
'\r' => { '\r' => {
location.line += 1; location.line += 1;
location.column = 1; location.column = 1;
} }
// CR 已完成换行,这个 LF 不再增加行号。
'\n' if previous_cr => {} '\n' if previous_cr => {}
// 独立 LF 换到下一行第一列。
'\n' => { '\n' => {
location.line += 1; location.line += 1;
location.column = 1; location.column = 1;
} }
_ => location.column += 1, _ => location.column += 1,
} }
// 每轮都更新,只有紧邻 CR 的 LF 才会被合并。
previous_cr = character == '\r'; previous_cr = character == '\r';
} }
location location
+24
View File
@@ -1,31 +1,45 @@
//! parser 及宿主分词入口;每次交给 PEG 一个剩余源码前缀,再把相对跨度换回原文绝对字节位置。
use crate::{Diagnostic, Span, Token, TokenKind}; use crate::{Diagnostic, Span, Token, TokenKind};
/// Lex a reader snapshot and preserve provenance in any diagnostic. /// Lex a reader snapshot and preserve provenance in any diagnostic.
/// 宿主对 SourceUnit 分词时调用;失败以快照补来源及行列,成功 Token 仍仅存原文字节跨度。
pub fn lex_source(source: &crate::SourceUnit) -> Result<Vec<Token>, crate::SourceDiagnostic> { pub fn lex_source(source: &crate::SourceUnit) -> Result<Vec<Token>, crate::SourceDiagnostic> {
lex(source.text()).map_err(|error| source.annotate(error)) lex(source.text()).map_err(|error| source.annotate(error))
} }
/// Lex the basic Endorphin draft syntax without reading files or changing /// Lex the basic Endorphin draft syntax without reading files or changing
/// locale. Positions always refer to bytes in this exact UTF-8 source. /// locale. Positions always refer to bytes in this exact UTF-8 source.
/// parser 的各语法入口及词法测试调用;只消费传入文本,Token 不持有源码字符串。
pub fn lex(source: &str) -> Result<Vec<Token>, Diagnostic> { pub fn lex(source: &str) -> Result<Vec<Token>, Diagnostic> {
// 游标从原文零偏移开始,PEG 的每次扫描都在 offset 之后的后缀上进行。
let mut lexer = Lexer { source, offset: 0 }; let mut lexer = Lexer { source, offset: 0 };
// 按原输入顺序保存有效 Token,空白与行注释由词法规则跳过。
let mut tokens = Vec::new(); let mut tokens = Vec::new();
// next 返回 None 表示跳过末尾 trivia 后到 EOF;任一诊断立即中止整个分词。
while let Some(token) = lexer.next()? { while let Some(token) = lexer.next()? {
tokens.push(token); tokens.push(token);
} }
Ok(tokens) Ok(tokens)
} }
/// lex 内部的借用游标,原文保持不变,offset 始终对应已消费前缀的字节数。
struct Lexer<'source> { struct Lexer<'source> {
// 原始完整 UTF-8 文本,供后缀扫描和全局错误位置计算。
source: &'source str, source: &'source str,
// 下次扫描的原文起点,包含此前已跳过的空白/注释。
offset: usize, offset: usize,
} }
impl Lexer<'_> { impl Lexer<'_> {
/// lex 循环调用;分别处理 PEG 自身失败和词法动作返回的 Diagnostic,二者位置都换回全局偏移。
fn next(&mut self) -> Result<Option<Token>, Diagnostic> { fn next(&mut self) -> Result<Option<Token>, Diagnostic> {
// 保存本轮起点,不能用后面已经前进的 offset 修正当前 Token 或错误。
let base = self.offset; let base = self.offset;
// PEG 返回消费字节数与 Result<Option<Token>>;规则错误作为值保留,避免回溯改认其他 Token。
let (consumed, token) = lexical::next(&self.source[base..]).map_err(|error| { let (consumed, token) = lexical::next(&self.source[base..]).map_err(|error| {
// PEG 自身报错位置相对于后缀,加 base 得到完整原文偏移。
let start = base + error.location.offset; let start = base + error.location.offset;
// 覆盖当前一个完整 UTF-8 字符;EOF 没有字符,使用空范围。
let end = start let end = start
+ self.source[start..] + self.source[start..]
.chars() .chars()
@@ -33,8 +47,10 @@ impl Lexer<'_> {
.map_or(0, char::len_utf8); .map_or(0, char::len_utf8);
Diagnostic::lexical(Span::new(start, end), "unexpected source character") Diagnostic::lexical(Span::new(start, end), "unexpected source character")
})?; })?;
// consumed 包括本轮 trivia 和 Token;词法错误随后返回给 lex,不继续扫描。
self.offset += consumed; self.offset += consumed;
token token
// 成功且非 EOF 的 Token 才需要把两个端点加回原文起点。
.map(|token| { .map(|token| {
token.map(|mut token| { token.map(|mut token| {
token.span.start += base; token.span.start += base;
@@ -42,6 +58,7 @@ impl Lexer<'_> {
token token
}) })
}) })
// 词法动作返回的错误同样使用后缀坐标;转换后与 Token 遵循同一位置协议。
.map_err(|mut error| { .map_err(|mut error| {
error.span.start += base; error.span.start += base;
error.span.end += base; error.span.end += base;
@@ -50,11 +67,17 @@ impl Lexer<'_> {
} }
} }
/// grammar.peg 的字符串 primary 调用,raw 已去掉引号且转义由 lexer.peg 验证,只解码四种受支持转义。
pub(crate) fn decode_string(raw: &str) -> String { pub(crate) fn decode_string(raw: &str) -> String {
// AST 持有解码文本,和 Token 所指向的带引号原文分开保存。
let mut result = String::new(); let mut result = String::new();
// 按 Unicode 字符遍历,普通多字节字符不做额外转换。
let mut characters = raw.chars(); let mut characters = raw.chars();
// 遇反斜杠消耗下一个转义字符,其他字符原样追加。
while let Some(character) = characters.next() { while let Some(character) = characters.next() {
// lexer 已保证反斜杠后有合法转义;缺字符或未知字符表示内部阶段契约被破坏。
if character == '\\' { if character == '\\' {
// 只支持换行、制表、双引号和反斜杠,不解释额外 Unicode/数字转义。
result.push(match characters.next().expect("lexer validated escape") { result.push(match characters.next().expect("lexer validated escape") {
'n' => '\n', 'n' => '\n',
't' => '\t', 't' => '\t',
@@ -69,4 +92,5 @@ pub(crate) fn decode_string(raw: &str) -> String {
result result
} }
// 编译时引入 lexical::next 的 rust-peg 规则实现;运行时由 Lexer::next 调用。
include!("lexer.peg"); include!("lexer.peg");
+14
View File
@@ -1,23 +1,37 @@
//! 宿主、编译器与测试共用的前端门面:读取不可变源码快照,分词并构造拥有文本的 AST。
//! UTF-8 source reader and rust-peg rules for lexing and token-based parsing. //! UTF-8 source reader and rust-peg rules for lexing and token-based parsing.
//! Produces syntax only; it does not resolve types, generate code or execute VM //! Produces syntax only; it does not resolve types, generate code or execute VM
//! operations. AST data owns its text and does not borrow the source buffer. //! operations. AST data owns its text and does not borrow the source buffer.
// 公开语法树、访问器及 JSON 文档接口,供编译器分析和编辑器传输使用。
pub mod ast; pub mod ast;
// 统一维护半开字节跨度、Unicode 行列及阶段错误,避免词法/语法各自计算位置。
mod diagnostic; mod diagnostic;
// 把 UTF-8 文本转成 Token;rust-peg 词法规则由该模块引入。
mod lexer; mod lexer;
// 把 Token 序列转成模块、表达式或交互根,不执行类型解析和 VM 操作。
mod parser; mod parser;
// 从文本、流、文件或宿主提供的 endor URI 读取原样 UTF-8 快照。
mod reader; mod reader;
// 保存源码来源/版本标签及文本,错误附加来源和已经计算的行列位置。
mod source; mod source;
// Token 只存种类与原文跨度,具体文本由解析器从源码读取。
mod token; mod token;
// 宿主和编译器可沿用同一套位置与诊断数据结构。
pub use diagnostic::{Diagnostic, DiagnosticKind, SourceLocation, Span}; pub use diagnostic::{Diagnostic, DiagnosticKind, SourceLocation, Span};
// 同时公开裸文本和保留 SourceUnit 来源的分词入口。
pub use lexer::{lex, lex_source}; pub use lexer::{lex, lex_source};
// 公开各语法根及来源包装入口;ParseMode 选择语法单位,不维护 REPL 会话。
pub use parser::{ pub use parser::{
ParseMode, parse, parse_ast, parse_expression, parse_source, parse_source_ast, ParseMode, parse, parse_ast, parse_expression, parse_source, parse_source_ast,
parse_source_expression, parse_source_expression,
}; };
// 宿主实现 EndorSourceProvider 掌握 URI 授权与版本选择,前端只消费返回字节。
pub use reader::{ pub use reader::{
EndorReader, EndorSourceProvider, ResolvedEndorSource, SourceReadError, SourceReadErrorKind, EndorReader, EndorSourceProvider, ResolvedEndorSource, SourceReadError, SourceReadErrorKind,
}; };
// 源码快照和带来源诊断供跨读取/解析/编译阶段传递。
pub use source::{SourceDiagnostic, SourceOrigin, SourceUnit}; pub use source::{SourceDiagnostic, SourceOrigin, SourceUnit};
// 公开词法输出,供解析测试及直接 Token 使用者检查种类与字节位置。
pub use token::{Token, TokenKind}; pub use token::{Token, TokenKind};
+30
View File
@@ -1,3 +1,4 @@
//! compiler 与宿主使用的 Token 解析门面;grammar.peg 构造拥有文本的 AST,类型名及名称绑定留待编译分析。
use crate::ast::{ use crate::ast::{
Assignment, AstRoot, BinaryOp, Binding, Block, Class, Decl, DeclKind, Expr, ExprKind, Function, Assignment, AstRoot, BinaryOp, Binding, Block, Class, Decl, DeclKind, Expr, ExprKind, Function,
IfStatement, InteractiveInput, MemberAssignment, Name, Parameter, Program, ReturnStatement, IfStatement, InteractiveInput, MemberAssignment, Name, Parameter, Program, ReturnStatement,
@@ -8,17 +9,25 @@ use crate::{Diagnostic, DiagnosticKind, Span, Token, TokenKind, lex};
/// Select the syntax root without implying any execution or REPL session. /// Select the syntax root without implying any execution or REPL session.
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// parse_ast/parse_source_ast 调用方选择的语法根,不表示开启执行器或 REPL 状态。
pub enum ParseMode { pub enum ParseMode {
// 一个或多个顶层函数/类声明。
Module, Module,
// 恰好一个完整表达式,不能附带其他语句。
Expression, Expression,
// 一个完整的交互语句,可为声明、绑定、赋值、控制流或表达式。
Interactive, Interactive,
} }
/// compile_source 和语法测试调用,按 mode 返回 AstRoot;词法失败先返回,语法失败转换为原文跨度诊断。
pub fn parse_ast(source: &str, mode: ParseMode) -> Result<AstRoot, Diagnostic> { pub fn parse_ast(source: &str, mode: ParseMode) -> Result<AstRoot, Diagnostic> {
// 模块/表达式复用专门入口,交互入口直接调用对应 PEG 根规则。
match mode { match mode {
ParseMode::Module => parse(source).map(AstRoot::Module), ParseMode::Module => parse(source).map(AstRoot::Module),
ParseMode::Expression => parse_expression(source).map(AstRoot::Expression), ParseMode::Expression => parse_expression(source).map(AstRoot::Expression),
// 语法只收一个完整提交,不负责多次提交共享环境或未完成输入提示。
ParseMode::Interactive => { ParseMode::Interactive => {
// 先分词,保留 Token 的原文跨度,供语法错误从 Token 索引映射回字节。
let tokens = lex(source)?; let tokens = lex(source)?;
syntax::interactive(&tokens, source) syntax::interactive(&tokens, source)
.map(AstRoot::Interactive) .map(AstRoot::Interactive)
@@ -27,6 +36,7 @@ pub fn parse_ast(source: &str, mode: ParseMode) -> Result<AstRoot, Diagnostic> {
} }
} }
/// compiler 与宿主的快照入口;语法根由 mode 决定,错误增加该快照的来源和行列。
pub fn parse_source_ast( pub fn parse_source_ast(
source: &crate::SourceUnit, source: &crate::SourceUnit,
mode: ParseMode, mode: ParseMode,
@@ -35,10 +45,12 @@ pub fn parse_source_ast(
} }
/// Parse a reader snapshot, retaining its origin and resolved revision on error. /// Parse a reader snapshot, retaining its origin and resolved revision on error.
/// 宿主从 Reader 快照解析模块时调用,保留来源及 Endor 版本身份到错误包装。
pub fn parse_source(source: &crate::SourceUnit) -> Result<Program, crate::SourceDiagnostic> { pub fn parse_source(source: &crate::SourceUnit) -> Result<Program, crate::SourceDiagnostic> {
parse(source.text()).map_err(|error| source.annotate(error)) parse(source.text()).map_err(|error| source.annotate(error))
} }
/// 宿主从快照解析一个表达式时调用,与 parse_expression 共享语法,仅增加错误来源。
pub fn parse_source_expression( pub fn parse_source_expression(
source: &crate::SourceUnit, source: &crate::SourceUnit,
) -> Result<Expr, crate::SourceDiagnostic> { ) -> Result<Expr, crate::SourceDiagnostic> {
@@ -47,21 +59,28 @@ pub fn parse_source_expression(
/// Parse one or more typed function or class declarations. This is a syntax /// Parse one or more typed function or class declarations. This is a syntax
/// operation: type names and name references are retained without resolution. /// operation: type names and name references are retained without resolution.
/// parse_ast 的 Module 分支、parse_source 和语法测试调用;只构造声明树,不注册 VM 全局值。
pub fn parse(source: &str) -> Result<Program, Diagnostic> { pub fn parse(source: &str) -> Result<Program, Diagnostic> {
// 词法诊断原样传播;语法 PEG 处理的是 Token 序列,不直接按 UTF-8 字节推进。
let tokens = lex(source)?; let tokens = lex(source)?;
syntax::program(&tokens, source).map_err(|error| diagnostic(error, &tokens, source.len())) syntax::program(&tokens, source).map_err(|error| diagnostic(error, &tokens, source.len()))
} }
/// Parse exactly one complete expression, useful independently of declarations. /// Parse exactly one complete expression, useful independently of declarations.
/// parse_ast 的 Expression 分支、快照包装及表达式测试调用;要求整份 Token 输入被消费。
pub fn parse_expression(source: &str) -> Result<Expr, Diagnostic> { pub fn parse_expression(source: &str) -> Result<Expr, Diagnostic> {
// 词法诊断原样传播;语法 PEG 处理的是 Token 序列,不直接按 UTF-8 字节推进。
let tokens = lex(source)?; let tokens = lex(source)?;
syntax::expression(&tokens, source).map_err(|error| diagnostic(error, &tokens, source.len())) syntax::expression(&tokens, source).map_err(|error| diagnostic(error, &tokens, source.len()))
} }
/// 各 PEG 语法根的 map_err 调用,把失败 Token 索引映射为原文范围,并保留期望项列表。
fn diagnostic(error: peg::error::ParseError<usize>, tokens: &[Token], end: usize) -> Diagnostic { fn diagnostic(error: peg::error::ParseError<usize>, tokens: &[Token], end: usize) -> Diagnostic {
// 命中 Token 则定位该 Token,EOF 或越界索引使用原文尾部空范围。
let span = tokens let span = tokens
.get(error.location) .get(error.location)
.map_or(Span::new(end, end), |token| token.span); .map_or(Span::new(end, end), |token| token.span);
// PEG 期望项转成拥有字符串,既写入可读消息,也保留供宿主程序化显示。
let expected: Vec<String> = error.expected.tokens().map(str::to_owned).collect(); let expected: Vec<String> = error.expected.tokens().map(str::to_owned).collect();
Diagnostic { Diagnostic {
kind: DiagnosticKind::Syntax, kind: DiagnosticKind::Syntax,
@@ -71,6 +90,7 @@ fn diagnostic(error: peg::error::ParseError<usize>, tokens: &[Token], end: usize
} }
} }
/// grammar.peg 的交互绑定/局部绑定规则调用,复用 Binding 自身范围包装成语句节点。
fn binding_statement(binding: Binding) -> Stmt { fn binding_statement(binding: Binding) -> Stmt {
Stmt { Stmt {
span: binding.span, span: binding.span,
@@ -78,6 +98,7 @@ fn binding_statement(binding: Binding) -> Stmt {
} }
} }
/// grammar.peg 的优先级规则调用,把已解析左右操作数包装为二元节点;跨度覆盖两端及中间原文。
fn binary(left: Expr, operation: BinaryOp, right: Expr) -> Expr { fn binary(left: Expr, operation: BinaryOp, right: Expr) -> Expr {
Expr { Expr {
span: left.span.through(right.span), span: left.span.through(right.span),
@@ -89,17 +110,25 @@ fn binary(left: Expr, operation: BinaryOp, right: Expr) -> Expr {
} }
} }
/// grammar.peg 暂存一个后缀,postfix 按源码从左到右把链式成员/调用折叠成 AST。
enum Suffix { enum Suffix {
// 点后属性名节点,自身含原文字节跨度。
Member(Name), Member(Name),
// 参数表达式与右括号范围,后者用于延长整个调用节点的跨度。
Call(Vec<Expr>, Span), Call(Vec<Expr>, Span),
} }
/// grammar.peg 的 class_member 返回中间分类,再由 class 规则分别收集字段和方法。
enum ClassMember { enum ClassMember {
// 字段使用名称加类型名结构,与 Parameter 共用形状。
Field(Parameter), Field(Parameter),
// 类方法沿用函数 AST;显式 self 等约束由 compiler::analyze 检查。
Method(Function), Method(Function),
} }
/// grammar.peg 的 postfix_expression fold 调用;每步把前一个结果作为新的接收对象或被调表达式。
fn postfix(expression: Expr, suffix: Suffix) -> Expr { fn postfix(expression: Expr, suffix: Suffix) -> Expr {
// 成员节点延长到属性名末尾,调用节点延长到右括号,保持连续后缀完整跨度。
match suffix { match suffix {
Suffix::Member(name) => Expr { Suffix::Member(name) => Expr {
span: expression.span.through(name.span), span: expression.span.through(name.span),
@@ -118,4 +147,5 @@ fn postfix(expression: Expr, suffix: Suffix) -> Expr {
} }
} }
// 编译时引入 syntax 根规则;上述公开入口与 AST 构造辅助函数在规则中互相调用。
include!("grammar.peg"); include!("grammar.peg");
+22
View File
@@ -1,3 +1,4 @@
//! Reader 产生 SourceUnit,lexer/parser/compiler 借用其文本;错误在 annotate 时固化来源及行列。
use std::error::Error; use std::error::Error;
use std::fmt; use std::fmt;
use std::path::PathBuf; use std::path::PathBuf;
@@ -7,15 +8,22 @@ use crate::{Diagnostic, SourceLocation};
/// Source provenance, independent of filesystem layout or VM heap handles. /// Source provenance, independent of filesystem layout or VM heap handles.
/// Endor revisions are opaque labels supplied by the host, not verified hashes. /// Endor revisions are opaque labels supplied by the host, not verified hashes.
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
/// Reader 选择的来源身份,诊断和代码文件名显示使用;Endor revision 是宿主标签,不代表已验证哈希。
pub enum SourceOrigin { pub enum SourceOrigin {
// 内存文本的宿主显示名,不表示磁盘路径。
Text { name: String }, Text { name: String },
// 已读到 EOF 的字节流显示名,流本身不再存于快照。
Stream { name: String }, Stream { name: String },
// 实际读取时保存的路径,不要求规范化为绝对路径。
File { path: PathBuf }, File { path: PathBuf },
// 经宿主解析的 URI 与所选版本身份,前端不推断其命名空间或哈希算法。
Endor { uri: String, revision: String }, Endor { uri: String, revision: String },
} }
impl fmt::Display for SourceOrigin { impl fmt::Display for SourceOrigin {
/// 诊断与生成代码文件名调用 Display,按来源种类生成可读身份文本。
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
// 文本/流显示名称,文件显示路径,Endor 来源附带版本标签。
match self { match self {
Self::Text { name } | Self::Stream { name } => formatter.write_str(name), Self::Text { name } | Self::Stream { name } => formatter.write_str(name),
Self::File { path } => write!(formatter, "{}", path.display()), Self::File { path } => write!(formatter, "{}", path.display()),
@@ -27,25 +35,33 @@ impl fmt::Display for SourceOrigin {
/// An owned, immutable UTF-8 snapshot. Reader adapters preserve the text exactly /// An owned, immutable UTF-8 snapshot. Reader adapters preserve the text exactly
/// so token byte offsets still refer to the original decoded source. /// so token byte offsets still refer to the original decoded source.
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
/// EndorReader 构造的拥有型 UTF-8 快照;原文不规范化,以保持 Token 和 AST 字节跨度对应原输入。
pub struct SourceUnit { pub struct SourceUnit {
// 来源身份与文本一起保存,供错误和代码元数据使用。
origin: SourceOrigin, origin: SourceOrigin,
// 已验证 UTF-8 的原始文本,解析阶段只借用它,不修改换行或空白。
text: String, text: String,
} }
impl SourceUnit { impl SourceUnit {
/// Reader 适配器完成解码后调用;将来源及文本移入快照,不再读取外部数据。
pub(crate) fn new(origin: SourceOrigin, text: String) -> Self { pub(crate) fn new(origin: SourceOrigin, text: String) -> Self {
Self { origin, text } Self { origin, text }
} }
/// 编译器生成文件名、宿主检查来源时借用身份,保留 Endor 的已解析版本。
pub fn origin(&self) -> &SourceOrigin { pub fn origin(&self) -> &SourceOrigin {
&self.origin &self.origin
} }
/// lexer/parser/compiler 及位置校验借用 UTF-8 文本,返回生命周期依附当前快照。
pub fn text(&self) -> &str { pub fn text(&self) -> &str {
&self.text &self.text
} }
/// Bind a diagnostic to this snapshot before discarding its source buffer. /// Bind a diagnostic to this snapshot before discarding its source buffer.
/// lex_source、parse_source 系列及 compile_source 在失败时调用,把字节诊断绑定到此来源和行列。
/// 返回值保存来源、位置及原诊断,不保存源码全文;后续无需再次读源即可显示基本错误。
pub fn annotate(&self, diagnostic: Diagnostic) -> SourceDiagnostic { pub fn annotate(&self, diagnostic: Diagnostic) -> SourceDiagnostic {
SourceDiagnostic { SourceDiagnostic {
location: diagnostic.location(&self.text), location: diagnostic.location(&self.text),
@@ -56,13 +72,18 @@ impl SourceUnit {
} }
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
/// 带来源及预计算位置的阶段错误,由 SourceUnit::annotate 创建,交给宿主显示或追查底层 Diagnostic。
pub struct SourceDiagnostic { pub struct SourceDiagnostic {
// 错误对应的来源,独立于原快照生命周期。
pub origin: SourceOrigin, pub origin: SourceOrigin,
// annotate 当时根据原文计算的一基行列,后续 Display 不重新计算。
pub location: SourceLocation, pub location: SourceLocation,
// 原始字节跨度、阶段、说明及期望项,保留给程序化处理与 Error::source。
pub diagnostic: Box<Diagnostic>, pub diagnostic: Box<Diagnostic>,
} }
impl fmt::Display for SourceDiagnostic { impl fmt::Display for SourceDiagnostic {
/// 宿主显示错误时输出“来源:行:列:说明”,跨度及期望项仍可从 diagnostic 单独读取。
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!( write!(
formatter, formatter,
@@ -73,6 +94,7 @@ impl fmt::Display for SourceDiagnostic {
} }
impl Error for SourceDiagnostic { impl Error for SourceDiagnostic {
/// 标准错误链使用者调用,暴露原始阶段诊断作为本错误的直接原因。
fn source(&self) -> Option<&(dyn Error + 'static)> { fn source(&self) -> Option<&(dyn Error + 'static)> {
Some(self.diagnostic.as_ref()) Some(self.diagnostic.as_ref())
} }
+26
View File
@@ -1,35 +1,61 @@
//! lexer 产生、parser 消费的轻量 Token;文本通过 span 从原 SourceUnit 借取,不在 Token 中复制。
use crate::Span; use crate::Span;
/// Text is located by span in the original source. Names stay contextual: the /// Text is located by span in the original source. Names stay contextual: the
/// lexer does not turn syntax words into globally reserved keywords. /// lexer does not turn syntax words into globally reserved keywords.
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// lexer.peg 输出的种类;语法关键字仍是 Name,由 grammar.peg 按原文上下文识别。
pub enum TokenKind { pub enum TokenKind {
// Unicode 名称,包含上下文关键字;这里只区分词形,不决定语义用途。
Name, Name,
// 无符号十进制整数/小数拼写;负号是单独 Token,精确值由编译器构造。
Number, Number,
/// Span includes quotes. Escapes have been checked, not decoded. /// Span includes quotes. Escapes have been checked, not decoded.
// 含引号的字符串范围,转义已校验但未解码;解析时再生成拥有文本。
String, String,
// 左圆括号,用于参数、调用或括号表达式。
LeftParen, LeftParen,
// 右圆括号,调用范围在它之后结束。
RightParen, RightParen,
// 左花括号,开始类或语句块。
LeftBrace, LeftBrace,
// 右花括号,结束类或语句块。
RightBrace, RightBrace,
// 类型注解及继承声明的冒号。
Colon, Colon,
// 参数和实参间的分隔符。
Comma, Comma,
// 成员访问或符号字面量的点。
Dot, Dot,
// 单等号赋值,不与双等号比较混淆。
Equal, Equal,
// 双等号相等比较。
EqualEqual, EqualEqual,
// 不等比较。
NotEqual, NotEqual,
// 小于比较。
Less, Less,
// 小于等于比较。
LessEqual, LessEqual,
// 大于比较。
Greater, Greater,
// 大于等于比较。
GreaterEqual, GreaterEqual,
// 加法操作符。
Plus, Plus,
// 减法或一元取负,由语法上下文区分。
Minus, Minus,
// 乘法操作符。
Star, Star,
// 除法操作符;双斜杠行注释在 trivia 阶段跳过。
Slash, Slash,
} }
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
/// 一次词法输出;Token 可复制,但只保存种类和字节范围,调用方须保留匹配的原文以读取内容。
pub struct Token { pub struct Token {
// parser 按此选择语法分支,名称关键字额外检查原文。
pub kind: TokenKind, pub kind: TokenKind,
// 原始 UTF-8 输入的半开范围,不含前面被跳过的空白/注释。
pub span: Span, pub span: Span,
} }