std.ast 包

功能介绍

ast 包主要包含了仓颉源码的语法解析器和仓颉语法树节点，提供语法解析函数。可将仓颉源码的词法单元 (Tokens) 解析为抽象语法树 (Abstract Syntax Tree) 节点对象。

仓颉 ast 包提供了 Macro With Context 的相关函数，用于在宏展开时获取展开过程中的上下文相关信息。在嵌套宏场景下，内层宏可以调用库函数 assertParentContext(String) 来保证内层宏调用一定嵌套在特定的外层宏调用中。如果内层宏调用这个函数时没有嵌套在给定的外层宏调用中，该函数将抛出一个错误。同时，函数 insideParentContext(String) 也用于检查内层宏调用是否嵌套在特定的外层宏调用中，但是返回一个布尔值。Macro With Context 的相关函数只能作为函数被直接调用，不能赋值给变量，不能作为实参或返回值使用。

Macro With Context 相关函数如下：

API 列表

函数

函数名功能
getTokenKind(UInt16)将词法单元种类序号转化为 TokenKind。
compareTokens(Tokens, Tokens)用于比较两个Tokens是否一致。
cangjieLex(String)将字符串转换为 Tokens 类型。
cangjieLex(String, Bool)将字符串转换为 Tokens 类型。
parseProgram(Tokens)用于解析单个仓颉文件的源码，获取一个 Program 类型的节点。
parseDecl(Tokens, String)用于解析一组词法单元，获取一个 Decl 类型的节点。
parseDeclFragment(Tokens, Int64)用于解析一组词法单元，获取一个 Decl 类型的节点和继续解析节点的索引。
parseExpr(Tokens)用于解析一组词法单元，获取一个 Expr 类型的节点。
parseExprFragment(Tokens, Int64)用于解析一组词法单元，获取一个 Expr 类型的节点和继续解析节点的索引。
assertParentContext(String)检查当前宏调用是否在特定的宏调用内;若检查不符合预期，编译器出现一个错误提示。
insideParentContext(String)检查当前宏调用是否在特定的宏调用内，返回一个布尔值。
setItem(String, String)内层宏通过该接口发送 string 类型的信息到外层宏。
setItem(String, Int64)内层宏通过该接口发送 Int64 类型的信息到外层宏。
setItem(String, Bool)内层宏通过该接口发送 Bool 类型的信息到外层宏。
getChildMessages(String)获取特定内层宏发送的信息。
diagReport(DiagReportLevel, Tokens, String, String)报错接口，在编译过程的宏展开阶段输出错误提示信息，支持 WARNING 和 ERROR 两个等级的报错。

接口

接口名功能
ToTokens实现对应类型的实例到 Tokens 类型转换的接口，作为支持quote插值操作必须实现的接口。
ToBytes提供对应类型的序列化功能。

类

类名功能
Annotation表示编译器内置的注解节点。
Argument表示函数调用的实参节点。
Body表示 Class 类型、 Struct 类型、 Interface 类型以及扩展中由 {} 和内部的一组声明节点组成的结构。
Constructor表示 enum 类型中的 Constructor 节点。
GenericConstraint表示一个泛型约束节点。
GenericParam表示一个类型形参节点.
ImportContent表示包导入节点中的导入项。
ImportList表示包导入节点。
MacroMessage记录内层宏发送的信息。
MatchCase表示一个 MatchCase 类型。
Modifier表示该定义具备某些特性，通常放在定义处的最前端。
Node所有仓颉语法树节点的父类。
PackageHeader表示包声明节点。
Program表示一个仓颉源码文件节点。
Tokens对 Token 序列进行封装的类型。
TokensIterator实现 Tokens 的迭代器功能。
Decl所有声明节点的父类，继承自 Node 节点，提供了所有声明节点的通用接口。
ClassDecl类定义节点。
EnumDecl表示一个 Enum 定义节点。
ExtendDecl表示一个扩展定义节点。
FuncParam表示函数参数节点，包括非命名参数和命名参数。
MacroExpandParam表示宏调用节点。
FuncDecl表示一个函数定义节点。
InterfaceDecl表示接口定义节点。
MacroDecl表示一个宏定义节点。
MacroExpandDecl表示宏调用节点。
MainDecl表示一个 main 函数定义节点。
PrimaryCtorDecl表示一个主构造函数节点。
PropDecl表示一个属性定义节点。
StructDecl表示一个 Struct 节点。
TypeAliasDecl表示类型别名节点。
VarDecl表示变量定义节点。
TypeNode所有类型节点的父类，继承自 Node。
PrimitiveType表示一个基本类型节点。
RefType表示一个用户自定义类型节点。
QualifiedType表示一个用户自定义成员类型。
ParenType表示括号类型节点。
TupleType表示元组类型节点。
ThisType表示 This 类型节点。
PrefixType表示带问号的前缀类型节点。
FuncType表示函数类型节点。
VArrayType表示 VArray 类型节点。
Pattern所有模式匹配节点的父类，继承自 Node 节点。
ConstPattern表示常量模式节点。
WildcardPattern表示通配符模式节点。
VarPattern表示绑定模式节点。
VarOrEnumPattern表示当模式的标识符为 Enum 构造器时的节点。
TypePattern表示当类型模式节点。
EnumPattern表示 enum 模式节点。
TuplePattern表示 Tuple 模式节点。
ExceptTypePattern表示一个用于异常模式状态下的节点。
Expr所有表达式节点的父类，继承自 Node 节点。
Block表示块节点。
ArrayLiteral表示 Array 字面量节点。
AsExpr表示一个类型检查表达式。
AssignExpr表示赋值表达式节点。
BinaryExpr表示一个二元操作表达式节点。
CallExpr表示函数调用节点节点。
DoWhileExpr表示 do-while 表达式。
ForInExpr表示 for-in 表达式。
UnaryExpr表示一个一元操作表达式节点。
IsExpr表示一个类型检查表达式。
ParenExpr表示一个括号表达式节点，是指使用圆括号括起来的表达式。
LitConstExpr表示一个常量表达式节点。
RefExpr表示一个使用自定义类型节点相关的表达式节点。
ReturnExpr表示 return 表达式节点。
ThrowExpr表示 throw 表达式节点。
MemberAccess表示成员访问表达式。
OptionalExpr表示一个带有问号操作符的表达式节点。
IfExpr表示条件表达式。
LetPatternExpr表示 let 声明的解构匹配节点。
MatchExpr表示模式匹配表达式实现模式匹配。
WhileExpr表示 while 表达式。
LambdaExpr表示 Lambda 表达式，是一个匿名的函数。
SpawnExpr表示 Spawn 表达式。
SynchronizedExpr表示 synchronized 表达式。
TrailingClosureExpr表示尾随 Lambda 节点。
TypeConvExpr表示类型转换表达式。
PrimitiveTypeExpr表示基本类型表达式节点。
TupleLiteral表示元组字面量节点。
RangeExpr表示包含区间操作符的表达式。
SubscriptExpr表示索引访问表达式。
JumpExpr表示循环表达式的循环体中的 break 和 continue。
IncOrDecExpr表示包含自增操作符（++）或自减操作符（--）的表达式。
TryExpr表示 try 表达式节点。
QuoteExpr表示 quote 表达式节点。
QuoteToken表示 quote 表达式节点内任意合法的 token。
MacroExpandExpr表示宏调用节点。
WildcardExpr表示通配符表达式节点。
VArrayExpr表示 VArray 的实例节点。
Visitor一个抽象类，其内部默认定义了访问不同类型 AST 节点访问（visit）函数。

枚举

枚举名功能
DiagReportLevel表示报错接口的信息等级，支持 ERROR 和 WARNING 两种格式。
ImportKind表示导入语句的类型，包括单导入、别名导入、全导入和多导入四种类型。
TokenKind表示仓颉编译内部所有的词法结构，包括符号、关键字、标识符、换行等。

结构体

结构体名功能
Position表示位置信息的数据结构，包含文件ID，行号和列号。
Token词法单元类型。

异常类

异常类名功能
class ASTExceptionast 库的异常类，在 ast 库调用过程中发生异常时使用。
class ParseASTExceptionast 库的解析异常类，在节点解析过程中发生异常时使用。
class MacroContextExceptionast 库的上下文宏异常类，在上下文宏的相关接口中发生异常时使用。