docs: explain graphics resources and runtime dispatch lifecycles
This commit is contained in:
+47
-14
@@ -1,9 +1,9 @@
|
||||
//! 区分完整 Module 与顶层 Script,并保留输入源码位置。
|
||||
//! 解析包装或片段拼接产生的 span 偏移要递归修正,保证诊断和 Sources 视图仍指向用户原始行列。
|
||||
//!
|
||||
//! Feed a source snapshot to Aster's existing module or interactive entry points.
|
||||
//! Statement syntax, tokens and ASTs all remain Aster-owned. The host only batches
|
||||
//! complete interactive inputs, just as a REPL feeds consecutive inputs to a VM.
|
||||
//! runtime::endor_host 的一次性 compile 和持久会话加载调用 parse,再按 roots 进行 AST 预算检查与编译。
|
||||
//! 语句、词法和 AST 定义属于 Aster;这里只把完整源码组织成 Module 或连续 Interactive 输入。
|
||||
//! 片段先用局部字节位置解析,shift_* 递归加回起点,编译错误和 Sources 浏览才能仍对应原文件。
|
||||
use anyhow::Result;
|
||||
use frontend::{
|
||||
ParseMode, SourceUnit, Span, TokenKind,
|
||||
@@ -12,41 +12,54 @@ use frontend::{
|
||||
|
||||
/// 待编译输入是完整模块还是顶层脚本;两者保留不同根结构但使用统一后续接口。
|
||||
pub enum SourcePlan {
|
||||
// 保留 Aster 完整模块根,后续作为一个编译/执行单元,不拆开函数或类的定义体。
|
||||
Module(AstRoot),
|
||||
// 顶层脚本按完整交互输入连续执行;各段仍共享所属运行时的全局环境,而非各建一个 VM。
|
||||
Script(Vec<AstRoot>),
|
||||
}
|
||||
|
||||
impl SourcePlan {
|
||||
/// 按输入计划返回需要编译的语法根,隐藏 Script 与 Module 组织差异。
|
||||
/// endor_host 的 AST 预算访问和 compile_plan 调用,借用统一根切片,不克隆 AST 或重新解析。
|
||||
pub fn roots(&self) -> &[AstRoot] {
|
||||
match self {
|
||||
// 单模块以单元素切片适配,让调用方不必维护两套遍历分支。
|
||||
Self::Module(root) => std::slice::from_ref(root),
|
||||
// 脚本直接保留原输入段顺序,声明和后续使用语句的先后关系不能重排。
|
||||
Self::Script(roots) => roots,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// 优先解析完整模块,否则按可完成的交互输入分段为 Script,并将 AST/诊断位置映回原文。
|
||||
/// endor_host 执行入口调用,优先接受完整 Module,失败则按顶层换行候选边界拼出 Aster 可解析的交互输入。
|
||||
/// 模块解析失败本身不立即作为最终错误:普通顶层脚本本就需要走后面的 Interactive 解析路径。
|
||||
pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
|
||||
// 完整模块优先;只有模块解析失败才退回连续交互输入模式,宿主不自行实现 Endor 语法。
|
||||
if let Ok(module) = frontend::parse_source_ast(source, ParseMode::Module) {
|
||||
// 模块成功就不再按行切分,避免破坏跨行声明与完整模块语义。
|
||||
return Ok(SourcePlan::Module(module));
|
||||
}
|
||||
// 一次词法分析获得原始字节 span,候选分段依赖 token 之间的实际换行而非直接按行切字符串。
|
||||
let tokens = frontend::lex_source(source)?;
|
||||
// 只保存已被 Aster 成功接受的交互根,失败候选不留下半棵 AST。
|
||||
let mut roots = Vec::new();
|
||||
// start 为当前待解析片段在原文件中的字节起点,仅在候选成功时前移。
|
||||
let mut start = 0;
|
||||
// 深度只是候选边界启发式;括号失配是否合法仍由 Aster 判定,不在宿主偷偷修正。
|
||||
let mut depth = 0_i64;
|
||||
for (index, token) in tokens.iter().enumerate() {
|
||||
// 追踪圆/花括号嵌套,括号内换行不能直接结束输入;最终语法是否合法仍交给 Aster。
|
||||
match token.kind {
|
||||
// token 已由词法器识别,字符串/注释里的括号不会当作结构括号改变深度。
|
||||
TokenKind::LeftParen | TokenKind::LeftBrace => depth += 1,
|
||||
TokenKind::RightParen | TokenKind::RightBrace => depth -= 1,
|
||||
// 其他 token 不改变边界嵌套,不能靠普通字符扫描替代此判断。
|
||||
_ => {}
|
||||
}
|
||||
// token 尾为原文本字节位置,用它取与下一 token 之间的空白/注释区域查换行。
|
||||
let end = token.span.end;
|
||||
// 末尾 token 总是尝试解析;非末尾要求顶层换行,且下一 token 不像成员访问、调用或算术续接。
|
||||
let boundary = tokens.get(index + 1).is_none_or(|next| {
|
||||
// 尚在括号内,或下一 token 明显续接上个表达式时,不尝试提前提交当前交互片段。
|
||||
depth == 0
|
||||
&& source.text()[end..next.span.start].contains(['\r', '\n'])
|
||||
&& !matches!(
|
||||
@@ -60,11 +73,13 @@ pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
|
||||
)
|
||||
});
|
||||
if !boundary {
|
||||
// 保留 start,之后尝试更长的片段;不是丢弃当前 token 对应源码。
|
||||
continue;
|
||||
}
|
||||
// 当前片段从上一次成功边界 start 开始,保留期间的空白与注释;解析器看到的是片段局部字节位置。
|
||||
match frontend::parse_ast(&source.text()[start..end], ParseMode::Interactive) {
|
||||
Ok(mut root) => {
|
||||
// Interactive 模式的成功根必须为 Interactive;违反是前端接口不变量错误。
|
||||
let AstRoot::Interactive(input) = &mut root else {
|
||||
unreachable!("interactive mode");
|
||||
};
|
||||
@@ -73,10 +88,9 @@ pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
|
||||
roots.push(root);
|
||||
start = end;
|
||||
}
|
||||
// An incomplete interactive input can continue on the next line.
|
||||
// Only Aster decides whether its combined syntax is valid.
|
||||
// 错误恰在片段末尾且还有 token 时,视为可能未完成的交互输入,保持 start 不动继续拼接。
|
||||
Err(diagnostic) if index + 1 < tokens.len() && diagnostic.span.start == end - start => {
|
||||
// 只有“诊断正好指向片段末尾”才暂缓,下一候选会连同当前片段一起再交 Aster 解析。
|
||||
}
|
||||
Err(mut diagnostic) => {
|
||||
// 其他语法错误立即恢复原始偏移,再用 SourceUnit 添加原文件来源与行列诊断。
|
||||
@@ -87,20 +101,20 @@ pub fn parse(source: &SourceUnit) -> Result<SourcePlan> {
|
||||
}
|
||||
// 空输入不能静默产生空计划;再次委托交互入口给出解析器自己的空输入诊断与来源。
|
||||
if roots.is_empty() {
|
||||
// Produce Aster's original empty-input diagnostic and provenance.
|
||||
// 不自造宿主错误字符串,保留前端对空输入的原始诊断和 SourceUnit 来源信息。
|
||||
frontend::parse_source_ast(source, ParseMode::Interactive)?;
|
||||
}
|
||||
Ok(SourcePlan::Script(roots))
|
||||
}
|
||||
|
||||
/// 为单个半开字节范围加回片段起始偏移,不处理其所属节点的子节点。
|
||||
/// 下方所有 shift_* 调用的基本操作,给单个半开字节范围加偏移,不递归、不改变源码内容。
|
||||
fn shift_span(span: &mut Span, offset: usize) {
|
||||
// span 采用原文本字节偏移,start/end 同增 offset 保持长度;不是按字符数或行数偏移。
|
||||
span.start += offset;
|
||||
span.end += offset;
|
||||
}
|
||||
|
||||
/// 递归调整对应语法节点的源码范围,保持片段解析后的错误位置仍指向原输入。
|
||||
/// parse 在接受一个 Interactive 根后调用,平移交互根范围,再把语句交给 shift_statement 递归。
|
||||
fn shift_input(input: &mut InteractiveInput, offset: usize) {
|
||||
shift_span(&mut input.span, offset);
|
||||
// 根范围之外,逐条语句递归处理所有内层节点,避免错误只在顶层位置正确。
|
||||
@@ -109,18 +123,21 @@ fn shift_input(input: &mut InteractiveInput, offset: usize) {
|
||||
}
|
||||
}
|
||||
|
||||
/// 递归调整对应语法节点的源码范围,保持片段解析后的错误位置仍指向原输入。
|
||||
/// shift_input/函数体/分支体的递归入口,按语句种类平移自己的范围和所有内嵌表达式/声明。
|
||||
fn shift_statement(statement: &mut Stmt, offset: usize) {
|
||||
shift_span(&mut statement.span, offset);
|
||||
match &mut statement.kind {
|
||||
StmtKind::If(branch) => {
|
||||
// If 节点、条件、then 块各有独立 span,平移外层 Stmt 不能自动更新它们。
|
||||
shift_span(&mut branch.span, offset);
|
||||
shift_expression(&mut branch.condition, offset);
|
||||
shift_span(&mut branch.body.span, offset);
|
||||
for s in &mut branch.body.statements {
|
||||
// then 内可能继续嵌套 if/while/声明,不能只调整第一层语句外框。
|
||||
shift_statement(s, offset);
|
||||
}
|
||||
if let Some(body) = &mut branch.otherwise {
|
||||
// else 可省略;存在时块范围和其中每条语句都使用同一个原片段偏移。
|
||||
shift_span(&mut body.span, offset);
|
||||
for s in &mut body.statements {
|
||||
shift_statement(s, offset);
|
||||
@@ -128,6 +145,7 @@ fn shift_statement(statement: &mut Stmt, offset: usize) {
|
||||
}
|
||||
}
|
||||
StmtKind::While(loop_) => {
|
||||
// while 条件和循环体均可含更深的调用/控制流,沿各自 AST 子结构递归而非重新扫描文本。
|
||||
shift_span(&mut loop_.span, offset);
|
||||
shift_expression(&mut loop_.condition, offset);
|
||||
shift_span(&mut loop_.body.span, offset);
|
||||
@@ -136,11 +154,13 @@ fn shift_statement(statement: &mut Stmt, offset: usize) {
|
||||
}
|
||||
}
|
||||
StmtKind::Binding(binding) => {
|
||||
// 新绑定独立保存名字和右值范围,诊断未定义符号时需要内部表达式位置正确。
|
||||
shift_span(&mut binding.span, offset);
|
||||
shift_span(&mut binding.name.span, offset);
|
||||
shift_expression(&mut binding.value, offset);
|
||||
}
|
||||
StmtKind::Assignment(assignment) => {
|
||||
// 赋值不同于声明,但同样保留名字与右值两个来源范围,不能仅平移整个语句。
|
||||
shift_span(&mut assignment.span, offset);
|
||||
shift_span(&mut assignment.name.span, offset);
|
||||
shift_expression(&mut assignment.value, offset);
|
||||
@@ -153,41 +173,49 @@ fn shift_statement(statement: &mut Stmt, offset: usize) {
|
||||
shift_expression(&mut assignment.value, offset);
|
||||
}
|
||||
StmtKind::Return(returned) => {
|
||||
// return 自身 span 必须平移;无返回表达式的 Unit 返回不能访问不存在的 value。
|
||||
shift_span(&mut returned.span, offset);
|
||||
if let Some(expression) = &mut returned.value {
|
||||
// 返回值可以是任意复合调用/算术表达式,继续下钻到全部名称和实参。
|
||||
shift_expression(expression, offset);
|
||||
}
|
||||
}
|
||||
// 表达式语句复用完整表达式递归,避免调用参数中的错误仍显示片段局部行列。
|
||||
StmtKind::Expression(expression) => shift_expression(expression, offset),
|
||||
// 顶层/局部声明转交类与函数专用入口,处理参数、类型名及函数体。
|
||||
StmtKind::Declaration(declaration) => shift_declaration(declaration, offset),
|
||||
}
|
||||
}
|
||||
|
||||
/// 递归调整对应语法节点的源码范围,保持片段解析后的错误位置仍指向原输入。
|
||||
/// shift_statement 在声明语句中调用,平移 Decl 外层,再区分函数定义与类定义的内部位置。
|
||||
fn shift_declaration(declaration: &mut Decl, offset: usize) {
|
||||
shift_span(&mut declaration.span, offset);
|
||||
match &mut declaration.kind {
|
||||
// 普通函数和类方法使用相同函数结构,统一由 shift_function 平移签名和函数体。
|
||||
DeclKind::Function(function) => shift_function(function, offset),
|
||||
// 类的名称、基类、字段类型和方法均保存独立 span,不能仅移动声明外层范围。
|
||||
DeclKind::Class(class) => {
|
||||
shift_span(&mut class.span, offset);
|
||||
shift_span(&mut class.name.span, offset);
|
||||
if let Some(base) = &mut class.base {
|
||||
// 无显式基类时不新增默认基类 span,保留前端原始 AST 的可选结构。
|
||||
shift_span(&mut base.span, offset);
|
||||
}
|
||||
for field in &mut class.fields {
|
||||
// 字段节点整体、字段名、类型名分别保存位置,错误类型注解必须指回原文件。
|
||||
shift_span(&mut field.span, offset);
|
||||
shift_span(&mut field.name.span, offset);
|
||||
shift_span(&mut field.type_name.span, offset);
|
||||
}
|
||||
for method in &mut class.methods {
|
||||
// 方法体可能包含更多声明,沿同一套递归入口继续处理。
|
||||
shift_function(method, offset);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// 递归调整对应语法节点的源码范围,保持片段解析后的错误位置仍指向原输入。
|
||||
/// shift_declaration 调用,平移函数名、参数/返回注解和函数体,供编译器类型错误使用原输入坐标。
|
||||
fn shift_function(function: &mut frontend::ast::Function, offset: usize) {
|
||||
shift_span(&mut function.span, offset);
|
||||
shift_span(&mut function.name.span, offset);
|
||||
@@ -200,11 +228,12 @@ fn shift_function(function: &mut frontend::ast::Function, offset: usize) {
|
||||
}
|
||||
shift_span(&mut function.body.span, offset);
|
||||
for statement in &mut function.body.statements {
|
||||
// 函数体内每条语句继续按 kind 递归,不能用整体函数范围覆盖内部诊断。
|
||||
shift_statement(statement, offset);
|
||||
}
|
||||
}
|
||||
|
||||
/// 递归调整对应语法节点的源码范围,保持片段解析后的错误位置仍指向原输入。
|
||||
/// 语句/函数递归助手调用,平移表达式与名称成员的范围;语义值和运算符本身保持不变。
|
||||
fn shift_expression(expression: &mut Expr, offset: usize) {
|
||||
shift_span(&mut expression.span, offset);
|
||||
match &mut expression.kind {
|
||||
@@ -212,13 +241,16 @@ fn shift_expression(expression: &mut Expr, offset: usize) {
|
||||
ExprKind::Name(_) | ExprKind::Number(_) | ExprKind::String(_) => {}
|
||||
ExprKind::Symbol(name) => shift_span(&mut name.span, offset),
|
||||
ExprKind::Unary { operand, .. } | ExprKind::Await(operand) => {
|
||||
// unary 与 await 都只有一个子表达式,操作符来源已在外层表达式 span 覆盖。
|
||||
shift_expression(operand, offset)
|
||||
}
|
||||
ExprKind::Binary { left, right, .. } => {
|
||||
// 两侧都可能含复合表达式,不能只调整最终报错概率更高的右侧。
|
||||
shift_expression(left, offset);
|
||||
shift_expression(right, offset);
|
||||
}
|
||||
ExprKind::Member { object, name } => {
|
||||
// object 可能是调用返回值,name 则是独立标识符,分别调整两类来源。
|
||||
shift_expression(object, offset);
|
||||
shift_span(&mut name.span, offset);
|
||||
}
|
||||
@@ -226,6 +258,7 @@ fn shift_expression(expression: &mut Expr, offset: usize) {
|
||||
ExprKind::Call { callee, arguments } => {
|
||||
shift_expression(callee, offset);
|
||||
for argument in arguments {
|
||||
// 保持实参顺序和值不变,只平移每个实参树内部保存的字节位置。
|
||||
shift_expression(argument, offset);
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user