仓颉 std.ast 包 Node 类深度解析:语法树节点的统一基类与核心操作指南
仓颉 std.ast 包 Node 类深度解析:语法树节点的统一基类与核心操作指南
Node 是仓颉标准库 std.ast 包中所有抽象语法树(AST)节点的父类,为声明节点(Decl)、表达式节点(Expr)、模式节点(Pattern)、类型节点(TypeNode)等数百种节点提供了统一的通用接口。本文以 Node 类参考文档 为主体,结合 ast 包 API 说明 与官方示例,系统讲解 Node 的位置信息管理、树形打印、词法单元转换与 Visitor 遍历四大核心能力,并给出可复制的完整实战代码,帮助读者在宏开发、源码分析与文档工具链中熟练操作仓颉语法树。
Node 在仓颉 AST 体系中的定位
在 ast 包总览 中,std.ast 包承担着两大职责:一是提供仓颉源码的词法/语法解析函数,将源码的 Tokens(词法单元序列)解析为抽象语法树节点对象;二是提供一整套表示仓颉语法结构的节点类型,供宏展开、代码分析等场景使用。
Node 正是这一整套节点类型的根基。从 ast_package_classes.md 的类定义 可以看到其完整声明:
abstract sealed class Node <: ToTokens
这一声明透露了两个关键事实:
- abstract(抽象):Node 本身不能被实例化,它只定义所有节点共有的能力,实际使用中拿到的一定是其某个具体子类实例(如
VarDecl、ClassDecl、CallExpr等)。 - sealed(密封):Node 的直接子类集合是受限且确定的,主要在包内部派生,保证了节点类型体系的封闭性与可枚举性。
- <: ToTokens:Node 实现了 ToTokens 接口,这是节点能够参与
quote插值操作的前提。
从 ast 包的核心类列表(见 ast 包 readme)可以清晰看到 Node 之下的继承树主干:
| 一级子类 | 职责 | 典型节点 |
|---|---|---|
| Decl | 所有声明节点的父类 | ClassDecl、FuncDecl、VarDecl、EnumDecl、StructDecl、MacroDecl 等 |
| Expr | 所有表达式节点的父类 | CallExpr、BinaryExpr、AssignExpr、IfExpr、LambdaExpr 等 |
| Pattern | 所有模式匹配节点的父类 | VarPattern、TuplePattern、ConstPattern 等 |
| TypeNode | 所有类型节点的父类 | PrimitiveType、RefType、FuncType 等 |
| 其他节点 | 直接继承 Node | Body、Argument、Constructor、Modifier、Annotation、Tokens 等 |
无论拿到的是哪一层节点,都可以通过 Node 提供的统一接口进行位置查询、结构打印、词法转换与遍历访问,这正是 Node 作为“所有仓颉语法树节点的父类”的价值所在。
beginPos / endPos:节点在源码中的位置信息
Node 提供了两个可读可写的属性,用于记录节点在源文件中的精确位置:
| 属性 | 原型 | 说明 |
|---|---|---|
| beginPos | public mut prop beginPos: Position |
获取或设置当前节点的起始位置信息 |
| endPos | public mut prop endPos: Position |
获取或设置当前节点的终止位置信息 |
两个属性的类型都是 Position 结构体。Position 是一个轻量的位置数据结构,包含三个成员:
fileID: UInt32:文件 ID,用于区分不同源文件;line: Int32:行号;column: Int32:列号。
此外 Position 还提供 dump() 打印、isEmpty()(判断行号和列号是否同时为 0)以及 toBytes() 序列化等方法。Position 可以通过 init()(各成员为 0)或 init(fileID: UInt32, line: Int32, column: Int32) 构造。
位置信息在树形打印输出中会以 pos: 行号: 列号 的形式直观呈现。例如在 语法树节点打印示例 中,对 var demo: Int64 = 1 解析出的 VarDecl 节点,其内部每个 Token 都携带位置信息:
VarDecl {
-keyword: Token {
value: "var"
kind: VAR
pos: 3: 23
}
...
}
其中的 pos: 3: 23 表示该词法单元位于第 3 行第 23 列。借助 beginPos/endPos,开发者可以精确还原节点对应的源码片段,这在错误定位、代码格式化、源码级重构等工具中非常实用。
dump():将语法树打印为树形结构
由于 AST 节点种类丰富、不同节点间属性差异很大,使用过程中容易混淆节点结构。为此 Node 实现了 dump() 方法:
public func dump(): Unit
功能:将当前语法树节点转化为树形结构的形态并打印到标准输出。其输出格式遵循三条明确规则(见 dump 的格式说明):
- 以
-开头的字符串表示当前节点的公共属性,如-keyword、-identifier; - 节点属性后紧跟该属性的具体类型,如
-declType: PrimitiveType表示该属性是一个PrimitiveType节点; - 每个类型使用一对大括号
{ }表示其作用区间,内部缩进展示其子属性。
以下是从 语法树节点打印示例 摘录的完整可运行示例:
import std.ast.*
main() {
let input = quote(var demo: Int64 = 1) // 假设当前代码所在行数为:3
let varDecl = parseDecl(input)
varDecl.dump()
}
quote(...) 将源码文本转换为 Tokens,parseDecl 将 Tokens 解析为一个 Decl 节点(这里实际类型为 VarDecl),随后调用 dump() 输出:
VarDecl {
-keyword: Token {
value: "var"
kind: VAR
pos: 3: 23
}
-identifier: Token {
value: "demo"
kind: IDENTIFIER
pos: 3: 27
}
-declType: PrimitiveType {
-keyword: Token {
value: "Int64"
kind: INT64
pos: 3: 33
}
}
-assign: Token {
value: "="
kind: ASSIGN
pos: 3: 39
}
-expr: LitConstExpr {
-literal: Token {
value: "1"
kind: INTEGER_LITERAL
pos: 3: 41
}
}
}
对更复杂的结构,dump() 同样能完整呈现嵌套关系。例如 解析示例 中将一个含成员变量与构造函数的 class Data 解析为 ClassDecl 后打印,输出展示了 Body -> VarDecl / FuncDecl -> FuncParam / Block -> AssignExpr -> RefExpr 的完整层级,是理解节点组合关系的直观工具。调试宏或分析陌生源码时,dump() 能极大降低反复查阅文档的成本。
toTokens():语法树节点与词法单元的双向桥梁
public func toTokens(): Tokens
功能:将语法树节点转化为 Tokens 类型并返回。
toTokens() 是 Node 实现 ToTokens 接口 的具体体现。该接口定义为:
public interface ToTokens {
func toTokens(): Tokens
}
其核心用途是支持 quote 插值操作:在 quote(...) 代码块中,$(expr) 形式的插值要求被插入的对象具备 toTokens() 能力。由于 Node(及其全部子类)都实现了该接口,开发者可以自由地将任意 AST 节点拼回词法单元序列,再通过解析函数重新生成节点,实现“节点 → Tokens → 新节点”的灵活转换。
Tokens 本身是对 Token 序列的封装,提供 append、concat、get、remove、toString、迭代器以及 +、<a href="https://link.gitcode.com/i/aaeac45d12552626ca620c74f75b297f" target="_blank">] 等操作符重载(详见 [Tokens 类文档)。值得注意的是,ToTokens 接口不仅由 Node 实现,标准库还为 Bool、String、Token、Tokens、各数值类型、Rune 以及 Array<T>、ArrayList<T> 提供了扩展实现,其中 ArrayList<T> 支持 Decl、Node、Constructor、Argument、FuncParam、MatchCase、Modifier、Annotation、ImportList、Pattern、TypeNode 等节点类型的转换(见 ast_package_interfaces.md)。
在宏定义中,宏函数签名通常为 public macro M(input: Tokens): Tokens,其内部对 input 解析得到的节点,经修改后即可通过 toTokens() 还原为 Tokens 作为宏的返回结果,这正是节点与词法单元双向转换的典型应用场景。
traverse():基于 Visitor 的节点遍历
public func traverse(v: Visitor): Unit
功能:遍历当前语法树节点及其子节点。参数 v 是 Visitor 类 的实例。
Visitor 是一个抽象类,其内部默认定义了访问不同类型 AST 节点的 visit 函数,所有 visit 函数都有默认为空的实现,开发者可按需重写(见 Visitor 类定义)。该类必须被继承使用,子类可以重新定义访问函数。
traverse 与 visit 配合工作的典型模式是:子类继承 Visitor 并重写感兴趣的 visit 函数,将 visit 函数作为参数传入某个节点的 traverse,即可对该节点及其所有子节点实施自定义行为。若希望提前终止对某个节点子树的遍历,可在重写的 visit 函数中调用 breakTraverse() 函数。
下面是从 自定义访问函数遍历 AST 对象示例 摘录的完整示例——查找未初始化(未赋值)的变量声明:
import std.ast.*
class MyVisitor <: Visitor {
public var uninitializedVars = Tokens() // 存储变量词法单元
override public func visit(varDecl: VarDecl) {
try {
varDecl.expr
} catch (e: ASTException) {
uninitializedVars.append(varDecl.identifier)
}
breakTraverse() // 不会继续遍历 varDecl 的子节点
return
}
}
main(): Int64 {
let input = quote(
var a : Int64
)
let varDecl = parseDecl(input)
let visitor = MyVisitor() // MyVisitor中定义了对 varDecl 节点的处理
varDecl.traverse(visitor) // 实现对 varDecl 节点的处理
println("Uninitialized VarDecl size is ${visitor.uninitializedVars.size}")
0
}
运行结果:
Uninitialized VarDecl size is 1
该示例中有几个值得注意的细节:
varDecl.expr在未初始化时会抛出 ASTException,以此作为“未初始化”的判定手段;breakTraverse()用于终止对varDecl子节点的继续遍历,避免无谓开销;Traverse是深度优先的递归遍历,适合实现代码检查、节点收集、结构改写等工具。
实战:解析、遍历与操作 AST 的完整链路
将 Node 的几项能力串联起来,就构成了操作仓颉 AST 的标准工作流:词法转换(quote)→ 语法解析(parse)→ 结构打印(dump)→ 遍历访问(traverse)→ 增删改查(属性操作)。
在 操作 AST 对象示例 中,展示了如何对解析得到的节点进行“增”操作——向类体中追加一个成员函数:
import std.ast.*
main() {
let input: Tokens = quote(
class Data {
var a: Int32
init(a_: Int32) {
a = a_
}
}
)
let decl = parseDecl(input) // 获取一个 Decl 声明节点
var classDecl = match (decl as ClassDecl) { // decl 的具体类型为 ClassDecl, 将其进行类型转化。
case Some(v) => v
case None => throw Exception()
}
var identifier = classDecl.identifier
// 为该节点增加一个成员函数用于获取a的值
var funcdecl = FuncDecl(quote(func getValue() {a}))
classDecl.body.decls.add(funcdecl)
println("Identifier value is ${identifier.value}")
println("ClassDecl body size is ${classDecl.body.decls.size}")
0
}
运行结果:
Identifier value is Data
ClassDecl body size is 3
这段代码综合体现了 Node 生态的关键机制:
parseDecl返回Decl类型,需通过match (decl as ClassDecl)做类型检查与转换后才能访问ClassDecl特有的属性;- 节点属性(如
identifier、body.decls)均为可读写的mut prop,支持直接修改节点结构; - 新节点可通过
FuncDecl(quote(func getValue() {a}))从quote产生的 Tokens 构造,体现了节点与 Tokens 的相互转换; - 修改后的节点树可直接用于宏返回(调用
toTokens())或继续后续处理。
此外,parse 示例 还演示了 parseDecl 与 dump 的组合用于快速审查解析结果,而 Macro With Context 示例 则展示了宏展开阶段中基于 Tokens 的嵌套宏通信(assertParentContext、setItem、getChildMessages),这些能力都以 Node 统一的节点与词法单元模型为基础。
总结
Node 作为仓颉 std.ast 包所有语法树节点的父类,以 abstract sealed class Node <: ToTokens 的形式确立了统一的节点模型,并通过四个核心成员奠定了操作 AST 的基础:
- beginPos / endPos:以 Position(fileID、line、column)精确记录节点源码位置;
- dump():以规范的树形格式(
-属性+ 类型名 +{}作用区间)实时查看节点整体结构; - toTokens():实现 ToTokens 接口,打通节点与 Tokens 的双向转换,支撑
quote插值; - traverse(Visitor):配合 Visitor 的
visit函数与breakTraverse(),实现深度优先的节点遍历与定制化访问。
无论是编写仓颉宏、构建代码分析工具,还是排查语法树结构问题,掌握 Node 的这四项能力都是高效驾驭 std.ast 包的起点。更完整的节点清单与 API 细节,可继续查阅 ast 包 readme 及 类参考文档。