docs(frontend): persist generated AST and visitor annotations

This commit is contained in:
2026-11-15 19:06:33 +08:00
parent 89f6aaecf7
commit 52e62d5839
4 changed files with 788 additions and 16 deletions
+136
View File
@@ -2,23 +2,33 @@
use super::Spanned;
use crate::Span;
/// wire/编辑器核对的协议身份,来自 ASDL 原文哈希;生成节点注释不参与此值。
pub const AST_SCHEMA_ID: &str =
"urn:endor:ast:sha256:21b0349ac295d9bc8cedcad8f07d8e2d45cf220e19e7c2fad10269555fcfd71a";
/// 宿主/编辑器传输的版本化语法文档,wire 校验后供 compiler 使用。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct AstDocument {
/// 协议身份,wire 按 AST_SCHEMA_ID 核对;不是源码内容哈希。
pub schema: String,
/// 拥有的语法根,文档校验及编译从这里递归。
pub root: AstRoot,
}
/// parse_ast 按模式构造的模块、表达式或交互根,compiler 据此选择生成入口。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum AstRoot {
/// 模块根,包含函数/类声明。
Module(Program),
/// 表达式根,编译后直接返回求值结果。
Expression(Expr),
/// 交互根,包含一次完整提交。
Interactive(InteractiveInput),
}
impl Spanned for AstRoot {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
// 按实际构造器取得唯一可定位子节点的范围。
match self {
Self::Module(node) => node.span(),
Self::Expression(node) => node.span(),
@@ -26,129 +36,184 @@ impl Spanned for AstRoot {
}
}
}
/// parser 复制的名称文本与位置,用于声明、类型注解或属性名。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Name {
/// 拥有名称文本,不依赖输入缓冲存活。
pub text: String,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Name {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 模块声明序列,compiler 先注册全部顶层名称再分析各函数体。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Program {
/// 按源码顺序的声明;源码模块解析要求非空,文档结构本身不限制数量。
pub declarations: Vec<Decl>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Program {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 顶层/交互声明的种类及完整范围,compiler 按函数或类分派。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Decl {
/// 函数/类声明载荷,JSON 和类型采用 kind/data 标签。
pub kind: DeclKind,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Decl {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 函数与类声明的判别载荷,外层 Decl 另外保存完整跨度。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum DeclKind {
/// 显式参数/返回注解与函数体,compiler 生成独立模板及源码签名;解析本身不调用函数。
Function(Function),
/// 类名、可选基类、字段和方法,compiler 检查成员后生成构类指令。
Class(Class),
}
impl Spanned for DeclKind {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
// 按实际构造器取得唯一可定位子节点的范围。
match self {
Self::Function(node) => node.span(),
Self::Class(node) => node.span(),
}
}
}
/// 类名、可选基类、字段和方法,compiler 检查成员后生成构类指令。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Class {
/// 类声明名与精确位置。
pub name: Name,
/// 显式基类名,可省略;当前 compiler 对省略项使用 Object。
pub base: Option<Name>,
/// 按出现顺序的字段名称/类型注解,不含方法。
pub fields: Vec<Parameter>,
/// 按出现顺序的方法;显式 self 约束由 compiler 检查。
pub methods: Vec<Function>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Class {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 显式参数/返回注解与函数体,compiler 生成独立模板及源码签名;解析本身不调用函数。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Function {
/// 函数/方法名,代码模板沿用为诊断名称。
pub name: Name,
/// 位置参数列表,compiler 依次分配前部局部槽。
pub parameters: Vec<Parameter>,
/// 返回类型名,生成源码签名后由运行时解析。
pub return_type: Name,
/// 独立函数作用域的语句体,当前源码不支持嵌套声明闭包。
pub body: Block,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Function {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 函数参数或类字段共用的名称/类型注解,实际类型身份由运行时环境解析。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Parameter {
/// 参数/字段名,用于布局和重复检查。
pub name: Name,
/// 声明类型名,前端只保留文本与位置。
pub type_name: Name,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Parameter {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 顺序语句块,compiler 检查确定初始化并按语句生成指令。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Block {
/// 有序语句列表,不引入独立块级局部作用域。
pub statements: Vec<Stmt>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Block {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 语句种类及原文范围,compiler 处理副作用、控制流或返回。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Stmt {
/// 具体语句载荷,外层另存整句范围。
pub kind: StmtKind,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Stmt {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 语句判别载荷,parser 选择分支,compiler 按绑定、赋值、控制流等规则处理。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum StmtKind {
/// let 新绑定,compiler 检查重名并分析右值后才标记目标已初始化。
Binding(Binding),
/// 普通名称赋值,compiler 按作用域写局部槽或全局环境。
Assignment(Assignment),
/// 成员写入的对象、属性名与右值,compiler 生成 StoreAttr。
MemberAssignment(MemberAssignment),
/// 条件、then 和可选 else,compiler 合并继续路径的初始化集合并生成跳转。
If(IfStatement),
/// 循环条件与体,compiler 生成回边并处理循环可能零次执行。
While(WhileStatement),
/// 函数返回,compiler 对缺省值补 Nil;当前源码语法要求 return 后有表达式。
Return(ReturnStatement),
/// 表达式载荷及完整范围,compiler 生成留下一个结果的求值序列。
Expression(Expr),
/// 顶层/交互声明的种类及完整范围,compiler 按函数或类分派。
Declaration(Decl),
}
impl Spanned for StmtKind {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
// 按实际构造器取得唯一可定位子节点的范围。
match self {
Self::Binding(node) => node.span(),
Self::Assignment(node) => node.span(),
@@ -161,141 +226,212 @@ impl Spanned for StmtKind {
}
}
}
/// let 新绑定,compiler 检查重名并分析右值后才标记目标已初始化。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Binding {
/// let 目标名,重复声明由语义分析拒绝。
pub name: Name,
/// 绑定右值,本局部不能在初始化前读取自身。
pub value: Expr,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Binding {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 普通名称赋值,compiler 按作用域写局部槽或全局环境。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Assignment {
/// 普通赋值目标,函数内首次赋值可预分配局部槽。
pub name: Name,
/// 先求右值再更新目标。
pub value: Expr,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Assignment {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 成员写入的对象、属性名与右值,compiler 生成 StoreAttr。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MemberAssignment {
/// 属性写入接收对象表达式,前端不求值。
pub object: Expr,
/// 待写属性名,compiler 加入名字表。
pub name: Name,
/// 待写右值,当前 compiler 先于接收对象生成求值以匹配 VM 栈布局。
pub value: Expr,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for MemberAssignment {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 条件、then 和可选 else,compiler 合并继续路径的初始化集合并生成跳转。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IfStatement {
/// 条件表达式,运行时按真值协议选择分支。
pub condition: Expr,
/// 条件为真的 then 块。
pub body: Block,
/// 可选 else 块,缺省时存在直接继续路径。
pub otherwise: Option<Block>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for IfStatement {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 循环条件与体,compiler 生成回边并处理循环可能零次执行。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct WhileStatement {
/// 每轮重新求值的条件,假值退出。
pub condition: Expr,
/// 循环体,可能一次也不执行。
pub body: Block,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for WhileStatement {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 函数返回,compiler 对缺省值补 Nil;当前源码语法要求 return 后有表达式。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ReturnStatement {
/// 可选返回表达式,手工 AST 缺省时由 compiler 补 Nil。
pub value: Option<Expr>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for ReturnStatement {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 单次交互提交容器,parser 产生一条语句,compiler 也检查数量,不保存宿主会话环境。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct InteractiveInput {
/// 当前 parse/compile 约定恰好一个完整提交的语句。
pub statements: Vec<Stmt>,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for InteractiveInput {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 表达式载荷及完整范围,compiler 生成留下一个结果的求值序列。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Expr {
/// 求值形状,不缓存名称解析或运行时类型。
pub kind: ExprKind,
/// 原始 UTF-8 文本的半开字节范围,定位与父子范围校验共用;不是字符列。
pub span: Span,
}
impl Spanned for Expr {
/// 原文切片、定位和 Visitor 节点钩子调用,返回存储范围或被包装节点的范围。
fn span(&self) -> Span {
self.span
}
}
/// 名称、字面量、等待、运算和调用等表达式载荷,范围由外层 Expr 提供。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "kind", content = "data", deny_unknown_fields)]
pub enum ExprKind {
/// 变量引用文本,compiler 决定局部槽或全局索引。
Name(String),
/// 原始十进制拼写,保留全部位数、前导零及尾零,不转浮点。
Number(String),
/// 已解码受支持转义的拥有文本,原引号范围在外层 Expr。
String(String),
/// 点开头的符号名,前端可表示,当前 compiler 拒绝生成运行时值。
Symbol(Name),
/// 等待子表达式,VM 执行上下文决定是否允许停放。
Await(Box<Expr>),
/// 一元取负,可在纯数值链上合并符号。
Unary {
/// 运算种类,决定算术、比较或取负指令。
operation: UnaryOp,
/// 一元子表达式,Rust 的递归回边间接存储。
operand: Box<Expr>,
},
/// 左右操作数及算术/比较种类,保留解析优先级树。
Binary {
/// 运算种类,决定算术、比较或取负指令。
operation: BinaryOp,
/// 二元左操作数,当前 compiler 先于右侧求值。
left: Box<Expr>,
/// 二元右操作数,与左侧一起被运行时运算消费。
right: Box<Expr>,
},
/// 接收对象及属性名的读取。
Member {
/// 成员读取接收对象。
object: Box<Expr>,
/// 成员或符号名,不是已解析的运行时属性句柄。
name: Name,
},
/// 被调用表达式与位置实参,由 VM 实际求值。
Call {
/// 调用目标,先于实参求值。
callee: Box<Expr>,
/// 有序位置实参,AST 不隐式添加接收者。
arguments: Vec<Expr>,
},
}
/// 一元运算种类,compiler 合并纯数值负号或生成运行时取负。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Copy)]
pub enum UnaryOp {
/// 一元取负。
Negate,
}
/// 二元算术/比较种类,parser 保留优先级树,compiler 映射为对应 VM 操作。
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Copy)]
pub enum BinaryOp {
/// 加法。
Add,
/// 减法。
Subtract,
/// 乘法。
Multiply,
/// 除法。
Divide,
/// 相等比较。
Equal,
/// 不等比较。
NotEqual,
/// 小于比较。
Less,
/// 小于等于比较。
LessEqual,
/// 大于比较。
Greater,
/// 大于等于比较。
GreaterEqual,
}
+186
View File
@@ -6,382 +6,566 @@ use super::{
ReturnStatement, Spanned, Stmt, StmtKind, UnaryOp, WhileStatement,
};
use crate::Span;
/// wire 校验与宿主分析实现的借用节点访问协议;默认按 ASDL 字段顺序递归,不修改树。
/// 覆盖 visit 方法后可显式调用对应 walk 继续子遍历;walk 本身不执行当前节点的进入/退出钩子。
pub trait Visitor {
/// 实现者选择的错误类型,任一子访问失败即向上返回。
type Error;
/// 默认可定位 visit 在遍历前调用;失败时本节点尚未成功进入,不再调用它的 leave_node。
fn enter_node(&mut self, _span: Span) -> Result<(), Self::Error> {
Ok(())
}
/// 已成功进入节点的遍历结束后调用,子节点错误也需退出;默认无操作。
fn leave_node(&mut self) {}
/// walk 遇到显式 span 字段时调用,默认不处理;区别于围绕整个节点的 enter_node。
fn visit_span(&mut self, _span: &Span) -> Result<(), Self::Error> {
Ok(())
}
/// 上层 walk 或宿主调用的 AstDocument 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_ast_document(&mut self, node: &AstDocument) -> Result<(), Self::Error> {
walk_ast_document(self, node)
}
/// 上层 walk 或宿主调用的 AstRoot 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_ast_root(&mut self, node: &AstRoot) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_ast_root(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Name 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_name(&mut self, node: &Name) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_name(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Program 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_program(&mut self, node: &Program) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_program(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Decl 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_decl(&mut self, node: &Decl) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_decl(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 DeclKind 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_decl_kind(&mut self, node: &DeclKind) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_decl_kind(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Class 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_class(&mut self, node: &Class) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_class(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Function 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_function(&mut self, node: &Function) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_function(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Parameter 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_parameter(&mut self, node: &Parameter) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_parameter(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Block 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_block(&mut self, node: &Block) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_block(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Stmt 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_stmt(&mut self, node: &Stmt) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_stmt(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 StmtKind 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_stmt_kind(&mut self, node: &StmtKind) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_stmt_kind(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Binding 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_binding(&mut self, node: &Binding) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_binding(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Assignment 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_assignment(&mut self, node: &Assignment) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_assignment(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 MemberAssignment 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_member_assignment(&mut self, node: &MemberAssignment) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_member_assignment(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 IfStatement 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_if_statement(&mut self, node: &IfStatement) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_if_statement(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 WhileStatement 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_while_statement(&mut self, node: &WhileStatement) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_while_statement(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 ReturnStatement 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_return_statement(&mut self, node: &ReturnStatement) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_return_statement(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 InteractiveInput 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_interactive_input(&mut self, node: &InteractiveInput) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_interactive_input(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 Expr 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_expr(&mut self, node: &Expr) -> Result<(), Self::Error> {
// 先进入;进入失败则不启动子遍历。
self.enter_node(node.span())?;
// 保存子遍历结果,不在此使用 ?,确保失败时仍退出已进入节点。
let result = walk_expr(self, node);
self.leave_node();
result
}
/// 上层 walk 或宿主调用的 ExprKind 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_expr_kind(&mut self, node: &ExprKind) -> Result<(), Self::Error> {
walk_expr_kind(self, node)
}
/// 上层 walk 或宿主调用的 UnaryOp 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_unary_op(&mut self, node: &UnaryOp) -> Result<(), Self::Error> {
walk_unary_op(self, node)
}
/// 上层 walk 或宿主调用的 BinaryOp 入口;默认继续对应子结构,可覆盖此方法收集/校验节点。
fn visit_binary_op(&mut self, node: &BinaryOp) -> Result<(), Self::Error> {
walk_binary_op(self, node)
}
}
/// 默认 visit_ast_document 或自定义访问器调用,按字段顺序借用 AstDocument 的子结构;本函数不进入/退出当前节点。
pub fn walk_ast_document<V: Visitor + ?Sized>(
visitor: &mut V,
node: &AstDocument,
) -> Result<(), V::Error> {
// 访问 &node.root 的 AstRoot 子结构或跨度,借用不转移节点所有权。
visitor.visit_ast_root(&node.root)?;
Ok(())
}
/// 默认 visit_ast_root 或自定义访问器调用,按字段顺序借用 AstRoot 的子结构;本函数不进入/退出当前节点。
pub fn walk_ast_root<V: Visitor + ?Sized>(visitor: &mut V, node: &AstRoot) -> Result<(), V::Error> {
// 按构造器只递归当前实际载荷,字符串等标量没有语法子节点。
match node {
// 模块根,包含函数/类声明。
AstRoot::Module(value) => {
// 访问 value 的 Program 子结构或跨度,借用不转移节点所有权。
visitor.visit_program(value)?;
}
// 表达式根,编译后直接返回求值结果。
AstRoot::Expression(value) => {
// 访问 value 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(value)?;
}
// 交互根,包含一次完整提交。
AstRoot::Interactive(value) => {
// 访问 value 的 InteractiveInput 子结构或跨度,借用不转移节点所有权。
visitor.visit_interactive_input(value)?;
}
}
Ok(())
}
/// 默认 visit_name 或自定义访问器调用,按字段顺序借用 Name 的子结构;本函数不进入/退出当前节点。
pub fn walk_name<V: Visitor + ?Sized>(visitor: &mut V, node: &Name) -> Result<(), V::Error> {
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_program 或自定义访问器调用,按字段顺序借用 Program 的子结构;本函数不进入/退出当前节点。
pub fn walk_program<V: Visitor + ?Sized>(visitor: &mut V, node: &Program) -> Result<(), V::Error> {
// 按顺序借用 &node.declarations 中每个 Decl,任一访问失败立即向上传播。
for value in &node.declarations {
visitor.visit_decl(value)?;
}
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_decl 或自定义访问器调用,按字段顺序借用 Decl 的子结构;本函数不进入/退出当前节点。
pub fn walk_decl<V: Visitor + ?Sized>(visitor: &mut V, node: &Decl) -> Result<(), V::Error> {
// 访问 &node.kind 的 DeclKind 子结构或跨度,借用不转移节点所有权。
visitor.visit_decl_kind(&node.kind)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_decl_kind 或自定义访问器调用,按字段顺序借用 DeclKind 的子结构;本函数不进入/退出当前节点。
pub fn walk_decl_kind<V: Visitor + ?Sized>(
visitor: &mut V,
node: &DeclKind,
) -> Result<(), V::Error> {
// 按构造器只递归当前实际载荷,字符串等标量没有语法子节点。
match node {
// 显式参数/返回注解与函数体,compiler 生成独立模板及源码签名;解析本身不调用函数。
DeclKind::Function(value) => {
// 访问 value 的 Function 子结构或跨度,借用不转移节点所有权。
visitor.visit_function(value)?;
}
// 类名、可选基类、字段和方法,compiler 检查成员后生成构类指令。
DeclKind::Class(value) => {
// 访问 value 的 Class 子结构或跨度,借用不转移节点所有权。
visitor.visit_class(value)?;
}
}
Ok(())
}
/// 默认 visit_class 或自定义访问器调用,按字段顺序借用 Class 的子结构;本函数不进入/退出当前节点。
pub fn walk_class<V: Visitor + ?Sized>(visitor: &mut V, node: &Class) -> Result<(), V::Error> {
// 访问 &node.name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.name)?;
// &node.base 是可选字段,仅 Some 时访问其 Name 子节点。
if let Some(value) = &node.base {
visitor.visit_name(value)?;
}
// 按顺序借用 &node.fields 中每个 Parameter,任一访问失败立即向上传播。
for value in &node.fields {
visitor.visit_parameter(value)?;
}
// 按顺序借用 &node.methods 中每个 Function,任一访问失败立即向上传播。
for value in &node.methods {
visitor.visit_function(value)?;
}
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_function 或自定义访问器调用,按字段顺序借用 Function 的子结构;本函数不进入/退出当前节点。
pub fn walk_function<V: Visitor + ?Sized>(
visitor: &mut V,
node: &Function,
) -> Result<(), V::Error> {
// 访问 &node.name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.name)?;
// 按顺序借用 &node.parameters 中每个 Parameter,任一访问失败立即向上传播。
for value in &node.parameters {
visitor.visit_parameter(value)?;
}
// 访问 &node.return_type 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.return_type)?;
// 访问 &node.body 的 Block 子结构或跨度,借用不转移节点所有权。
visitor.visit_block(&node.body)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_parameter 或自定义访问器调用,按字段顺序借用 Parameter 的子结构;本函数不进入/退出当前节点。
pub fn walk_parameter<V: Visitor + ?Sized>(
visitor: &mut V,
node: &Parameter,
) -> Result<(), V::Error> {
// 访问 &node.name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.name)?;
// 访问 &node.type_name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.type_name)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_block 或自定义访问器调用,按字段顺序借用 Block 的子结构;本函数不进入/退出当前节点。
pub fn walk_block<V: Visitor + ?Sized>(visitor: &mut V, node: &Block) -> Result<(), V::Error> {
// 按顺序借用 &node.statements 中每个 Stmt,任一访问失败立即向上传播。
for value in &node.statements {
visitor.visit_stmt(value)?;
}
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_stmt 或自定义访问器调用,按字段顺序借用 Stmt 的子结构;本函数不进入/退出当前节点。
pub fn walk_stmt<V: Visitor + ?Sized>(visitor: &mut V, node: &Stmt) -> Result<(), V::Error> {
// 访问 &node.kind 的 StmtKind 子结构或跨度,借用不转移节点所有权。
visitor.visit_stmt_kind(&node.kind)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_stmt_kind 或自定义访问器调用,按字段顺序借用 StmtKind 的子结构;本函数不进入/退出当前节点。
pub fn walk_stmt_kind<V: Visitor + ?Sized>(
visitor: &mut V,
node: &StmtKind,
) -> Result<(), V::Error> {
// 按构造器只递归当前实际载荷,字符串等标量没有语法子节点。
match node {
// let 新绑定,compiler 检查重名并分析右值后才标记目标已初始化。
StmtKind::Binding(value) => {
// 访问 value 的 Binding 子结构或跨度,借用不转移节点所有权。
visitor.visit_binding(value)?;
}
// 普通名称赋值,compiler 按作用域写局部槽或全局环境。
StmtKind::Assignment(value) => {
// 访问 value 的 Assignment 子结构或跨度,借用不转移节点所有权。
visitor.visit_assignment(value)?;
}
// 成员写入的对象、属性名与右值,compiler 生成 StoreAttr。
StmtKind::MemberAssignment(value) => {
// 访问 value 的 MemberAssignment 子结构或跨度,借用不转移节点所有权。
visitor.visit_member_assignment(value)?;
}
// 条件、then 和可选 else,compiler 合并继续路径的初始化集合并生成跳转。
StmtKind::If(value) => {
// 访问 value 的 IfStatement 子结构或跨度,借用不转移节点所有权。
visitor.visit_if_statement(value)?;
}
// 循环条件与体,compiler 生成回边并处理循环可能零次执行。
StmtKind::While(value) => {
// 访问 value 的 WhileStatement 子结构或跨度,借用不转移节点所有权。
visitor.visit_while_statement(value)?;
}
// 函数返回,compiler 对缺省值补 Nil;当前源码语法要求 return 后有表达式。
StmtKind::Return(value) => {
// 访问 value 的 ReturnStatement 子结构或跨度,借用不转移节点所有权。
visitor.visit_return_statement(value)?;
}
// 表达式载荷及完整范围,compiler 生成留下一个结果的求值序列。
StmtKind::Expression(value) => {
// 访问 value 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(value)?;
}
// 顶层/交互声明的种类及完整范围,compiler 按函数或类分派。
StmtKind::Declaration(value) => {
// 访问 value 的 Decl 子结构或跨度,借用不转移节点所有权。
visitor.visit_decl(value)?;
}
}
Ok(())
}
/// 默认 visit_binding 或自定义访问器调用,按字段顺序借用 Binding 的子结构;本函数不进入/退出当前节点。
pub fn walk_binding<V: Visitor + ?Sized>(visitor: &mut V, node: &Binding) -> Result<(), V::Error> {
// 访问 &node.name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.name)?;
// 访问 &node.value 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(&node.value)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_assignment 或自定义访问器调用,按字段顺序借用 Assignment 的子结构;本函数不进入/退出当前节点。
pub fn walk_assignment<V: Visitor + ?Sized>(
visitor: &mut V,
node: &Assignment,
) -> Result<(), V::Error> {
// 访问 &node.name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.name)?;
// 访问 &node.value 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(&node.value)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_member_assignment 或自定义访问器调用,按字段顺序借用 MemberAssignment 的子结构;本函数不进入/退出当前节点。
pub fn walk_member_assignment<V: Visitor + ?Sized>(
visitor: &mut V,
node: &MemberAssignment,
) -> Result<(), V::Error> {
// 访问 &node.object 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(&node.object)?;
// 访问 &node.name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(&node.name)?;
// 访问 &node.value 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(&node.value)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_if_statement 或自定义访问器调用,按字段顺序借用 IfStatement 的子结构;本函数不进入/退出当前节点。
pub fn walk_if_statement<V: Visitor + ?Sized>(
visitor: &mut V,
node: &IfStatement,
) -> Result<(), V::Error> {
// 访问 &node.condition 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(&node.condition)?;
// 访问 &node.body 的 Block 子结构或跨度,借用不转移节点所有权。
visitor.visit_block(&node.body)?;
// &node.otherwise 是可选字段,仅 Some 时访问其 Block 子节点。
if let Some(value) = &node.otherwise {
visitor.visit_block(value)?;
}
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_while_statement 或自定义访问器调用,按字段顺序借用 WhileStatement 的子结构;本函数不进入/退出当前节点。
pub fn walk_while_statement<V: Visitor + ?Sized>(
visitor: &mut V,
node: &WhileStatement,
) -> Result<(), V::Error> {
// 访问 &node.condition 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(&node.condition)?;
// 访问 &node.body 的 Block 子结构或跨度,借用不转移节点所有权。
visitor.visit_block(&node.body)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_return_statement 或自定义访问器调用,按字段顺序借用 ReturnStatement 的子结构;本函数不进入/退出当前节点。
pub fn walk_return_statement<V: Visitor + ?Sized>(
visitor: &mut V,
node: &ReturnStatement,
) -> Result<(), V::Error> {
// &node.value 是可选字段,仅 Some 时访问其 Expr 子节点。
if let Some(value) = &node.value {
visitor.visit_expr(value)?;
}
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_interactive_input 或自定义访问器调用,按字段顺序借用 InteractiveInput 的子结构;本函数不进入/退出当前节点。
pub fn walk_interactive_input<V: Visitor + ?Sized>(
visitor: &mut V,
node: &InteractiveInput,
) -> Result<(), V::Error> {
// 按顺序借用 &node.statements 中每个 Stmt,任一访问失败立即向上传播。
for value in &node.statements {
visitor.visit_stmt(value)?;
}
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_expr 或自定义访问器调用,按字段顺序借用 Expr 的子结构;本函数不进入/退出当前节点。
pub fn walk_expr<V: Visitor + ?Sized>(visitor: &mut V, node: &Expr) -> Result<(), V::Error> {
// 访问 &node.kind 的 ExprKind 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr_kind(&node.kind)?;
// 访问 &node.span 的 span 子结构或跨度,借用不转移节点所有权。
visitor.visit_span(&node.span)?;
Ok(())
}
/// 默认 visit_expr_kind 或自定义访问器调用,按字段顺序借用 ExprKind 的子结构;本函数不进入/退出当前节点。
pub fn walk_expr_kind<V: Visitor + ?Sized>(
visitor: &mut V,
node: &ExprKind,
) -> Result<(), V::Error> {
// 按构造器只递归当前实际载荷,字符串等标量没有语法子节点。
match node {
// 变量引用文本,compiler 决定局部槽或全局索引。
ExprKind::Name(_) => {}
// 原始十进制拼写,保留全部位数、前导零及尾零,不转浮点。
ExprKind::Number(_) => {}
// 已解码受支持转义的拥有文本,原引号范围在外层 Expr。
ExprKind::String(_) => {}
// 点开头的符号名,前端可表示,当前 compiler 拒绝生成运行时值。
ExprKind::Symbol(value) => {
// 访问 value 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(value)?;
}
// 等待子表达式,VM 执行上下文决定是否允许停放。
ExprKind::Await(value) => {
// 访问 value 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(value)?;
}
// 一元取负,可在纯数值链上合并符号。
ExprKind::Unary {
operation, operand, ..
} => {
// 访问 operation 的 UnaryOp 子结构或跨度,借用不转移节点所有权。
visitor.visit_unary_op(operation)?;
// 访问 operand 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(operand)?;
}
// 左右操作数及算术/比较种类,保留解析优先级树。
ExprKind::Binary {
operation,
left,
right,
..
} => {
// 访问 operation 的 BinaryOp 子结构或跨度,借用不转移节点所有权。
visitor.visit_binary_op(operation)?;
// 访问 left 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(left)?;
// 访问 right 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(right)?;
}
// 接收对象及属性名的读取。
ExprKind::Member { object, name, .. } => {
// 访问 object 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(object)?;
// 访问 name 的 Name 子结构或跨度,借用不转移节点所有权。
visitor.visit_name(name)?;
}
// 被调用表达式与位置实参,由 VM 实际求值。
ExprKind::Call {
callee, arguments, ..
} => {
// 访问 callee 的 Expr 子结构或跨度,借用不转移节点所有权。
visitor.visit_expr(callee)?;
// 按顺序借用 arguments 中每个 Expr,任一访问失败立即向上传播。
for value in arguments {
visitor.visit_expr(value)?;
}
@@ -389,12 +573,14 @@ pub fn walk_expr_kind<V: Visitor + ?Sized>(
}
Ok(())
}
/// 默认 visit_unary_op 或自定义访问器调用,按字段顺序借用 UnaryOp 的子结构;本函数不进入/退出当前节点。
pub fn walk_unary_op<V: Visitor + ?Sized>(
_visitor: &mut V,
_node: &UnaryOp,
) -> Result<(), V::Error> {
Ok(())
}
/// 默认 visit_binary_op 或自定义访问器调用,按字段顺序借用 BinaryOp 的子结构;本函数不进入/退出当前节点。
pub fn walk_binary_op<V: Visitor + ?Sized>(
_visitor: &mut V,
_node: &BinaryOp,