仓颉 std.ast 异常体系深度解析:ASTException、ParseASTException 与 MacroContextException 使用指南

原创2026-10-14 13:42:291,884 阅读
文章标签:编程语言语言运行时标准库内存管理OpenHarmony

仓颉 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}")
    }
}

实操建议:

  1. 区分捕获类型:解析入口(parseDecl、parseExpr、parseType、parsePattern、parseProgram 及其 Fragment 变体)优先捕获 ParseASTException;节点构造、Token 校验与 diagReport 参数校验捕获 ASTException;上下文宏嵌套断言捕获 MacroContextException;
  2. 兜底捕获:由于三者都继承自 Exception,可在最后以 catch (e: Exception) 兜底,避免未知异常导致宏展开崩溃;
  3. 善用异常消息:ParseASTException 的消息往往直接透传 C++ 解析器的诊断文本(如语法错误位置提示),可直接用于向用户呈现错误,或结合 diagReport 接口以编译器原生错误格式输出(支持 ERROR 与 WARNING 两种级别);
  4. 注意 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。

登录后查看全文
cangjie_runtime