仓颉 std.ast 异常体系深度解析:ASTException、ParseASTException 与 MacroContextException 使用指南
仓颉 std.ast 异常体系深度解析:ASTException、ParseASTException 与 MacroContextException 使用指南
导读:
std.ast是仓颉标准库中负责语法解析与抽象语法树(AST)构建的包,为宏编程提供词法分析、节点解析与上下文宏(Macro With Context)能力。本文以官方 API 文档为主线,系统讲解该包内三个核心异常类——ASTException、ParseASTException与MacroContextException的职责边界、构造方式与触发场景,并结合仓库源码(stdlib/libs/std/ast/exception.cj、ffi.cj、native/ast_api.cpp)剖析其底层实现原理,帮助读者在编写宏或调用 AST 解析接口时准确识别、捕获与处理各类异常。
一、异常体系概览:三个异常类的职责划分
std.ast 包共定义了三个公开异常类,全部直接继承自核心库的 Exception(所有异常类的父类,支持消息设置、堆栈追踪与字符串化)。它们分别对应 AST 库调用过程中三类不同的失败场景:
| 异常类 | 职责定位 | 典型触发阶段 |
|---|---|---|
ASTException |
AST 库调用通用异常,调用 AST 库接口出错时使用 | 节点构造、Token 合法性校验、诊断上报参数校验 |
ParseASTException |
节点解析异常,解析 Token 序列构建语法树节点失败时使用 | parseExpr、parseDecl、parseType、parsePattern 等解析入口 |
MacroContextException |
上下文宏异常,上下文宏相关接口出错时使用 | assertParentContext 嵌套上下文校验失败 |
从源码结构看,三个异常类的声明与实现分散在两处:exception.cj 定义了 ASTException 与 ParseASTException,而 ffi.cj 在 "Macro with context related API" 注释段之后定义了 MacroContextException,与 assertParentContext、insideParentContext 等上下文宏函数放置在一起——这一组织方式也从侧面印证了 MacroContextException 与上下文宏功能的高度绑定。
二、ASTException:AST 库调用的通用异常
2.1 类定义与构造函数
public class ASTException <: Exception {
public init()
public init(message: String)
}
ASTException 是 AST 库所有非解析类调用失败的通用出口,提供两个构造函数:
init():构造一个不带任何附加信息的默认ASTException对象;init(message: String):构造携带异常信息的ASTException对象,其中message为<a href="https://link.gitcode.com/i/371d5081db6e34fe6e048aae4fca29cb" target="_blank">String</a>类型的异常消息,用于描述失败原因。
2.2 源码实现与消息输出
在 exception.cj 中,该类的实现非常精简:两个构造函数分别透传给父类 Exception 的无参构造与带消息构造,同时重写 protected override func getClassName() 返回 "ASTException",使异常在字符串化与堆栈打印时展示正确的类名。
2.3 实际触发场景(源码佐证)
从源码检索结果看,ASTException 贯穿 AST 库的节点构造与校验逻辑,典型场景包括:
- 节点构造失败:在各节点类的
init构造器中,当必需的子节点缺失或输入不合法时抛出。例如nodes.cj中"Cannot construct the 'Annotation' node."、decls.cj中"Cannot construct the 'ClassDecl' node."、exprs.cj中"Cannot construct the 'BinaryExpr' node."等; - Token 类型校验失败:当传入的 Token 类型不符合接口预期时抛出,如
common.cj的"Illegal token kind: expected '${kind}', got '${tk.kind}'."、nodes.cj的注解 Token 校验等; - 诊断上报参数校验:
diag_report.cj中,当diagReport的输入 Token 跨多个文件、非法、超出宏调用范围或不属于宏调用文件时,均抛出带明确描述的ASTException。
从这些触发点可以推断:ASTException 更多面向"构造/校验类"失败,即开发者已持有语法树节点或 Token 数据、但在进一步加工(构造、转换、上报诊断)时发生的逻辑错误。
三、ParseASTException:节点解析异常
3.1 类定义与构造函数
public class ParseASTException <: Exception {
public init()
public init(message: String)
}
ParseASTException 专用于"节点解析"失败场景——即把词法单元(Tokens)解析为 AST 节点(Decl、Expr、Pattern、TypeNode、Program 等)的过程中发生的错误。同样提供默认构造与带消息构造两种方式,message 为异常描述字符串。
3.2 解析失败的传播链路(底层原理)
std.ast 的解析能力由 FFI 声明调用 CJC 前端静态库的 C++ API 实现。在 ffi.cj 中通过 foreign 块声明了 CJ_AST_ParseExpr、CJ_AST_ParseDecl、CJ_AST_ParsePattern、CJ_AST_ParseType、CJ_AST_ParseTopLevel 等原生函数,它们返回一个 ParseRes 结构体,其中包含解析得到的节点指针与错误消息字符串:
@C
struct ParseRes {
let node: CPointer<UInt8> = CPointer<UInt8>()
let errMsg: CString = CString(CPointer<UInt8>())
}
在 C++ 侧(native/ast_api.cpp),每个 CJ_AST_ParseXxx 函数在解析失败时会将诊断引擎收集到的错误文本写入 ParseRes.eMsg。Cangjie 侧的统一收口函数 getParsedNodeAndReleaseParseResult 会检查 errMsg:若错误消息非空,则释放相关内存并抛出 ParseASTException(errorMsg)——从而把 C++ 解析器的原始诊断文本原样上抛为 Cangjie 异常。此外,当原生调用返回空指针(如内存分配或解析结果获取失败)时,parse 与 parseFragment 也会分别抛出 ParseASTException("Failed to get parse result in 'parse'.") 与 ParseASTException("Failed to get parse result in 'parseFragment'.")。
3.3 各解析入口的异常触发点
- 表达式解析:
parse_expr.cj中,parseExpr解析失败时抛出"Failed to parse expr.",parseExprFragment失败时抛出"Failed to parse expr fragment.",解析到未知节点类型时抛出"Unsupported expr node kind: '${astKind}'."; - 声明解析:
parse_decl.cj中对应"Failed to parse decl."、"Failed to parse decl fragment."、"Unsupported decl node kind: '${astKind}'."等消息; - 类型解析:
parse_type.cj中对应"Failed to parse type."、"Failed to parse type fragment."、"Unsupported type node kind: '${astKind}'."; - 模式解析:
parse_pattern.cj中对应"Failed to parse pattern."、"Failed to parse pattern fragment.",以及对各类模式节点内部信息缺失的细化描述(如"Failed to get the var pattern."、"Constructor of 'EnumPattern' is not a 'RefExpr'."); - 程序整体解析:
parse_node.cj中parseProgram失败时抛出"Failed to parse program."/"Failed to obtain the 'Program' node."。
可以总结出一条规律:凡是通过 parseXxx 系列函数把 Tokens 转为 AST 节点的过程,失败时抛出的都是 ParseASTException;而解析完成后对节点做进一步构造或校验时抛出的则是 ASTException。理解这一分工,是编写健壮宏代码的关键。
四、MacroContextException:上下文宏异常
4.1 类定义与构造函数
public class MacroContextException <: Exception {
public init()
public init(message: String)
}
MacroContextException 是 std.ast 的上下文宏(Macro With Context)相关接口专用异常。上下文宏能力允许宏在展开期间获取调用上下文:内部宏可以通过 assertParentContext(String) 断言自己必须嵌套在某个指定外部宏调用之内,若断言失败则抛出异常;insideParentContext 则提供不抛异常、仅返回 Bool 的温和查询版本。
该异常同样提供默认构造与带消息构造两种方式。
4.2 源码实现与唯一触发点
在 ffi.cj 中,MacroContextException 的实现与其余两个异常类一致,但 getClassName() 返回的是 "MacroAssertParentException"(注意:该字符串与类名不一致,属源码现状,异常字符串化时以该值为准)。
其唯一抛出位置在 assertParentContext 函数内:该函数通过线程局部变量 MACRO_OBJECT 获取当前宏对象指针,调用原生函数 CJ_CheckParentContext(macroObjPtr, pStr, true) 校验嵌套关系,当返回 false 时抛出:
throw MacroContextException("Parent macro context check failed for macro '${parentMacroName}'.")
4.3 触发示例:宏嵌套上下文校验失败
以下示例取自官方上下文宏样例(stdlib/doc/libs/std_en/ast/ast_samples/context.md)的改编:
// macro_definition.cj
macro package macro_definition
import std.ast.*
public macro Outter(input: Tokens): Tokens {
return input
}
public macro Inner(input: Tokens): Tokens {
assertParentContext("Outter") // 断言 Inner 必须嵌套在 Outter 宏调用内
return input
}
// macro_call.cj
package macro_calling
import macro_definition.*
main() {
@Outter var a = 0
@Inner var b = 0 // error: The macro call 'Inner' should with the surround code contains a call 'Outter'.
}
编译时,cjc macro_definition.cj --compile-macro 先编译宏定义,再 cjc macro_call.cj -o demo 编译调用方。由于第二个调用中 @Inner 并未嵌套在 @Outter 调用内,assertParentContext 校验失败,抛出 MacroContextException,编译器据此报告宏调用上下文错误。若在宏定义中使用 insideParentContext("Outter") 则可避免抛异常,仅返回 false 供宏自行决策。
五、异常捕获与处理实践
由于三个异常类同属 Exception 的子类,捕获方式与仓颉通用异常处理完全一致。以下给出一个综合了 parseDecl 解析与 try-catch 处理的完整示例(改编自官方解析样例 stdlib/doc/libs/std_en/ast/ast_samples/parse.md):
import std.ast.*
main() {
let input: Tokens = quote(
class Data {
var a: Int32
init(a_: Int32) {
a = a_
}
}
)
try {
let decl = parseDecl(input) // 解析失败时抛出 ParseASTException
var classDecl = match (decl as ClassDecl) {
case Some(v) => v
case None => throw Exception()
}
classDecl.dump()
} catch (e: ParseASTException) {
println("解析失败:${e.message}")
} catch (e: ASTException) {
println("AST 库调用错误:${e.message}")
}
}
实操建议:
- 区分捕获类型:解析入口(
parseDecl、parseExpr、parseType、parsePattern、parseProgram及其 Fragment 变体)优先捕获ParseASTException;节点构造、Token 校验与diagReport参数校验捕获ASTException;上下文宏嵌套断言捕获MacroContextException; - 兜底捕获:由于三者都继承自
Exception,可在最后以catch (e: Exception)兜底,避免未知异常导致宏展开崩溃; - 善用异常消息:
ParseASTException的消息往往直接透传 C++ 解析器的诊断文本(如语法错误位置提示),可直接用于向用户呈现错误,或结合diagReport接口以编译器原生错误格式输出(支持ERROR与WARNING两种级别); - 注意 iOS 平台限制:根据包级文档(
stdlib/doc/libs/std_en/ast/ast_package_overview.md),std.ast在 iOS 平台仅支持 iOS 12 及以上版本,涉及异常场景的宏代码需确认目标环境满足该前提。
六、总结
std.ast 的三个异常类构成了 AST 库统一的失败上报体系:
ASTException:节点构造、Token 校验、诊断上报等 AST 库调用层面的通用异常;ParseASTException:parseXxx系列解析接口将Tokens转为 AST 节点失败时的专用异常,消息透传自 C++ 解析器诊断文本;MacroContextException:上下文宏嵌套断言(assertParentContext)失败时抛出的专用异常。
三者共享同一套精简实现模式(默认构造 + 带消息构造 + 重写 getClassName),根类均为核心库的 Exception。在宏编程实践中,依据"解析 vs 构造/校验 vs 上下文断言"的失败来源选择正确的异常类型进行捕获,即可快速定位问题、向用户呈现可读的错误信息,并利用 diagReport 生成与编译器原生格式一致的诊断输出。相关接口的完整签名与全部节点类说明,可进一步查阅 ast_package_classes.md 与 ast_package_funcs.md。