函数
func assertParentContext(String)
public func assertParentContext(parentMacroName: String): Unit
功能:检查当前宏调用是否在特定的宏调用内。若检查不符合预期,编译器出现一个错误提示。
注意:
该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。
参数:
- parentMacroName: String - 待检查的外层宏调用的名字。
func cangjieLex(String)
public func cangjieLex(code: String): Tokens
功能:将字符串转换为 Tokens 对象。
参数:
- code: String - 待词法解析的字符串。
返回值:
异常:
- IllegalMemoryException - 当申请内存失败时,抛出异常。
- IllegalArgumentException - 当输入的 code 无法被正确的解析为 Tokens 时,抛出异常。
func cangjieLex(String, Bool)
public func cangjieLex(code: String, truncated: Bool): Tokens
功能:将字符串转换为 Tokens 对象。
参数:
返回值:
异常:
- IllegalMemoryException - 当申请内存失败,抛出异常时,抛出异常。
- IllegalArgumentException - 当输入的 code 无法被正确的解析为 Tokens 时,抛出异常。
func compareTokens(Tokens, Tokens)
public func compareTokens(tokens1: Tokens, tokens2: Tokens): Bool
功能:用于比较两个Tokens是否一致。
参数:
返回值:
func diagReport(DiagReportLevel, Tokens, String, String)
public func diagReport(level: DiagReportLevel, tokens: Tokens, message: String, hint: String): Unit
功能:报错接口,在编译过程的宏展开阶段输出错误提示信息,支持 WARNING
和 ERROR
两个等级的报错。
注意:
参数:
- level: DiagReportLevel - 报错信息等级。
- tokens: Tokens - 报错信息中所引用源码内容对应的 Tokens。
- message: String - 报错的主信息。
- hint: String - 辅助提示信息。
异常:
-
ASTException - 当输入的 Tokens 存在以下错误时,抛出异常。
func getChildMessages(String)
public func getChildMessages(children:String): ArrayList<MacroMessage>
功能:获取特定内层宏发送的信息。
注意:
该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。
参数:
- children: String - 待接收信息的内层宏名称。
返回值:
- ArrayList<MacroMessage> - 返回一组 MacroMessage 的对象。
func getTokenKind(UInt16)
public func getTokenKind(no: UInt16): TokenKind
功能:将词法单元种类序号转化为 TokenKind。
参数:
- no: UInt16 - 需要转换的序号。
返回值:
func insideParentContext(String)
public func insideParentContext(parentMacroName: String): Bool
功能:检查当前宏调用是否在特定的宏调用内,返回一个布尔值。
注意:
- 在嵌套宏场景下,内层宏也可以通过发送键/值对的方式与外层宏通信。当内层宏执行时,通过调用标准库函数 setItem 向外层宏发送信息;随后,当外层宏执行时,调用标准库函数 getChildMessages 接收每一个内层宏发送的信息(一组键/值对映射)。
- 该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。
参数:
- parentMacroName: String - 待检查的外层宏调用的名字。
返回值:
- Bool - 若当前宏嵌套在特定的宏调用内,返回 true。
func parseDecl(Tokens, String)
public func parseDecl(input: Tokens, astKind!: String = ""): Decl
功能:用于解析一组词法单元,获取一个 Decl 类型的节点。
参数:
- input: Tokens - 待解析源码的词法单元。
- astKind!: String - 用于指定解析特定的节点类型,有效支持的值为:
PrimaryCtorDecl
和PropMemberDecl
。PrimaryCtorDecl
: 解析主构造函数。PropMemberDecl
: 解析prop声明的getter和setter函数。
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 Decl 节点时,抛出异常。
示例:
-
以下代码展示
astKind
设为PropMemberDecl
的案例。在这个参数下,可以使用parseDecl
解析prop
的getter和setter函数,解析结果为FuncDecl
类型(如果不设置astKind
,则会因为没有func
关键字而无法解析)。import std.ast.* main() { let getter = quote( get() { _val } ) let setter = quote( set(v) { _val = v }) let getterDecl = parseDecl(getter, astKind: "PropMemberDecl") let setterDecl = parseDecl(setter, astKind: "PropMemberDecl") println((getterDecl as FuncDecl).getOrThrow().block.toTokens()) println((setterDecl as FuncDecl).getOrThrow().block.toTokens()) }
运行结果:
{ _val } { _val = v }
-
以下代码展示
astKind
设为PrimaryCtorDecl
的案例。在这个参数下,可以使用parseDecl
解析主构造函数节点,解析结果为PrimaryCtorDecl
类型(如果不设置astKind
,则会因为没有func
关键字而无法解析)。import std.ast.* main() { let ctor = quote( Point(var x: Int32, var y: Int32) {} ) let ctorDecl = parseDecl(ctor, astKind: "PrimaryCtorDecl") println(ctorDecl is PrimaryCtorDecl) println(ctorDecl.toTokens()) }
运行结果:
true Point(var x: Int32, var y: Int32) { }
func parseDeclFragment(Tokens, Int64)
public func parseDeclFragment(input: Tokens, startFrom !: Int64 = 0): (Decl, Int64)
功能:用于解析一组词法单元,获取一个 Decl 类型的节点和继续解析节点的索引。
参数:
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 Decl 节点时,抛出异常。
func parseExpr(Tokens)
public func parseExpr(input: Tokens): Expr
功能:用于解析一组词法单元,获取一个 Expr 类型的节点。
参数:
- input: Tokens - 待解析源码的词法单元。
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 Expr 节点时,抛出异常。
func parseExprFragment(Tokens, Int64)
public func parseExprFragment(input: Tokens, startFrom !: Int64 = 0): (Expr, Int64)
功能:用于解析一组词法单元,获取一个 Expr 类型的节点和继续解析节点的索引。
参数:
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 Expr 节点时,抛出异常。
func parsePattern(Tokens)
public func parsePattern(input: Tokens): Pattern
功能:用于解析一组词法单元,获取一个 Pattern 类型的节点。
参数:
- input: Tokens - 待解析源码的词法单元。
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 Pattern 节点时,抛出异常。
func parsePatternFragment(Tokens, Int64)
public func parsePatternFragment(input: Tokens, startFrom !: Int64 = 0): (Pattern, Int64)
功能:用于解析一组词法单元,获取一个 Pattern 类型的节点和继续解析节点的索引。
参数:
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 Pattern 节点时,抛出异常。
func parseProgram(Tokens)
public func parseProgram(input: Tokens): Program
功能:用于解析单个仓颉文件的源码,获取一个 Program 类型的节点。
参数:
- input: Tokens - 待解析源码的词法单元。
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 Program 节点时,抛出异常。
func parseType(Tokens)
public func parseType(input: Tokens): TypeNode
功能:用于解析一组词法单元,获取一个 TypeNode 类型的节点。
参数:
- input: Tokens - 待解析源码的词法单元。
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 TypeNode 节点时,抛出异常。
func parseTypeFragment(Tokens, Int64)
public func parseTypeFragment(input: Tokens, startFrom !: Int64 = 0): (TypeNode, Int64)
功能:用于解析一组词法单元,获取一个 TypeNode 类型的节点和继续解析节点的索引。
参数:
返回值:
异常:
- ParseASTException - 当输入的 Tokens 类型无法构造为 TypeNode 节点时,抛出异常。
func setItem(String, Bool)
public func setItem(key: String, value: Bool): Unit
功能:内层宏通过该接口发送 Bool 类型的信息到外层宏。
注意:
该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。
参数:
func setItem(String, Int64)
public func setItem(key: String, value: Int64): Unit
功能:内层宏通过该接口发送 Int64 类型的信息到外层宏。
注意:
该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。
参数:
func setItem(String, String)
public func setItem(key: String, value: String): Unit
功能:内层宏通过该接口发送 String 类型的信息到外层宏。
注意:
该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。
参数:
func setItem(String, Tokens)
public func setItem(key: String, value: Tokens): Unit
功能:内层宏通过该接口发送 Tokens 类型的信息到外层宏。
注意:
该函数只能作为函数被直接调用,不能作为赋值给变量,不能作为实参或返回值使用。
参数: