Function

func assertParentContext(String)

public func assertParentContext(parentMacroName: String): Unit

Description: Checks whether the current macro call is within a specific macro call. If the check result does not meet the expectation, the compiler displays an error message.

Note:

This function can only be directly called as a function and cannot be assigned to a variable or used as an actual parameter or a return value.

Parameters:

• parentMacroName: String: name of the outer macro call to be checked

func cangjieLex(String)

public func cangjieLex(code: String): Tokens

Description: Converts a string to a Tokens object.

Parameters:

• code: String: string pending lexical parsing

Returns:

• Tokens: Tokens obtained by lexical parsing

Throws:

• IllegalMemoryException: When the memory fails to be allocated, this exception is thrown.
• IllegalArgumentException: When the input code cannot be correctly parsed as a Tokens object, this exception is thrown.

func cangjieLex(String, Bool)

public func cangjieLex(code: String, truncated: Bool): Tokens

Description: Converts a string to a Tokens object.

Parameters:

• code: String: string pending lexical parsing
• truncated: Bool: whether to delete Token(END) in the parsed Tokens

Returns:

• Tokens: Tokens obtained by lexical parsing

Throws:

• IllegalMemoryException: When the memory fails to be allocated, this exception is thrown.
• IllegalArgumentException: When the input code cannot be correctly parsed as a Tokens object, this exception is thrown.

func compareTokens(Tokens, Tokens)

public func compareTokens(tokens1: Tokens, tokens2: Tokens): Bool

Description: Checks whether two Tokens instances are the same.

Parameters:

• tokens1: Tokens: one Tokens instance for comparison
• tokens2: Tokens: the other Tokens instance for comparison

Returns:

• Bool: If the contents (except the newline character, end character, and location information) of the two Tokens instances are the same, true is returned.

func diagReport(DiagReportLevel, Tokens, String, String)

public func diagReport(level: DiagReportLevel, tokens: Tokens, message: String, hint: String): Unit

Description: Specifies the error reporting API used to output error messages during macro expansion in the compilation process, which supports outputting errors of the WARNING and ERROR levels.

Note:

• For this API, the compilation process is terminated when the error level is ERROR, but the macro expansion process is not terminated. You are advised to directly perform the return operation or throw an exception to terminate the macro expansion process after this API is called.
• This API lists the code in the line where the input tokens are located based on the cjc standard error reporting API and marks content of tokens with wavy lines. The message information is displayed in the first line, and the hint information is displayed following the wavy lines.
• The source code content referenced in the error information is determined only based on the start location of the first Token instance and the end location of the last Token instance. Consistency of the location information of intermediate Token instances is not verified.
• Calling this API is valid only during macro expansion. For details, see [Sample Code](../ast_samples/report.md#Call Example Not in Macro Expansion).

Parameters:

• level: DiagReportLevel: error information level
• tokens: Tokens: Tokens corresponding to the source code content referenced in the error information
• message: String: main information of the error information
• hint: String: auxiliary prompt information

Throws:

• ASTException: This exception is thrown when the input Tokens instance has any of the following errors:

  • The input Tokens instance is empty.
  • Token instances in the input Tokens instance are from different source files.
  • In the input Tokens instance, the first Token instance is placed before the last Token instance.
  • The location range of the Token instance in the input Tokens instance is beyond the location range of the macro call.

func getChildMessages(String)

public func getChildMessages(children:String): ArrayList<MacroMessage>

Description: Obtains information sent by a specific inner macro.

Note:

This function can only be directly called as a function and cannot be assigned to a variable or used as an actual parameter or a return value.

Parameters:

• children: String: name of the inner macro to which information is to be sent

Returns:

• ArrayList<MacroMessage>: group of MacroMessage objects

func getTokenKind(UInt16)

public func getTokenKind(no: UInt16): TokenKind

Description: Converts a lexical unit type sequence number to TokenKind.

Parameters:

• no: UInt16: sequence number to be converted

Returns:

• TokenKind: TokenKind corresponding to the lexical unit type sequence number

func insideParentContext(String)

public func insideParentContext(parentMacroName: String): Bool

Description: Checks whether the current macro call is within a specific macro call and returns a Boolean value.

Note:

• In a nested macro scenario, an inner macro can also communicate with an outer macro by sending a key-value pair. When inner macros are executed, the standard library function setItem is called to send information to outer macros. Then, when the outer macros are executed, the standard library function getChildMessages is called to receive information (a group of key-value pair mappings) sent by each inner macro.
• This function can only be directly called as a function and cannot be assigned to a variable or used as an actual parameter or a return value.

Parameters:

• parentMacroName: String: name of the outer macro call to be checked

Returns:

• Bool: true is returned if the current macro is nested within a specific macro call.

func parseDecl(Tokens, String)

public func parseDecl(input: Tokens, astKind!: String = ""): Decl

Description: Parses a group of lexical units to obtain a node of the Decl type.

Parameters:

• input: Tokens: lexical unit pending source code parsing
• astKind!: String: Specifies the type of the node to be parsed. The valid values are PrimaryCtorDecl and PropMemberDecl.
  • PrimaryCtorDecl: Parses the primary constructor.
  • PropMemberDecl: Parses the getter and setter functions declared with prop.

Returns:

• Decl: node of the Decl type

Throws:

• ParseASTException: If the input Tokens instance cannot be constructed as a Decl node, this exception is thrown.

Example:

1. The following code shows the case where astKind is set to PropMemberDecl. In this case, parseDecl can be used to parse the getter and setter functions declared with prop. The parsing results are of the FuncDecl type. If astKind is not set, the parsing fails because there is no func keyword.

   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())
   }
   

   Running result:

   {
       _val
   }
   
   {
       _val = v
   }
   

2. The following code shows the case where astKind is set to PrimaryCtorDecl. In this case, parseDecl can be used to parse the primary constructor node. The parsing result is of the PrimaryCtorDecl type. If astKind is not set, the parsing fails because there is no func keyword.

   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())
   }
   

   Running result:

   true
   Point(var x: Int32, var y: Int32) {
   }
   

func parseDeclFragment(Tokens, Int64)

public func parseDeclFragment(input: Tokens, startFrom !: Int64 = 0): (Decl, Int64)

Description: Parses a group of lexical units to obtain a node of the Decl type and an index used to continue parsing.

Parameters:

• input: Tokens: lexical unit pending source code parsing
• startFrom!: Int64: start location

Returns:

• (Decl, Int64): (syntax tree node, location to continue parsing)

Throws:

• ParseASTException: If the input Tokens instance cannot be constructed as a Decl node, this exception is thrown.

func parseExpr(Tokens)

public func parseExpr(input: Tokens): Expr

Description: Parses a group of lexical units to obtain a node of the Expr type.

Parameters:

• input: Tokens: lexical unit pending source code parsing

Returns:

• Expr: node of the Expr type

Throws:

• ParseASTException: If the input Tokens instance cannot be constructed as an Expr node, this exception is thrown.

func parseExprFragment(Tokens, Int64)

public func parseExprFragment(input: Tokens, startFrom !: Int64 = 0): (Expr, Int64)

Description: Parses a group of lexical units to obtain a node of the Expr type and an index used to continue parsing.

Parameters:

• input: Tokens: lexical unit pending source code parsing
• startFrom!: Int64: start location

Returns:

• (Expr, Int64): (syntax tree node, location to continue parsing)

Throws:

• ParseASTException: If the input Tokens instance cannot be constructed as an Expr node, this exception is thrown.

func parseProgram(Tokens)

public func parseProgram(input: Tokens): Program

Description: Parses the source codes of a single Cangjie file to obtain a node of the Program type.

Parameters:

• input: Tokens: lexical unit pending source code parsing

Returns:

• Program: node of the Program type

Throws:

• ParseASTException: If the input Tokens instance cannot be constructed as a Program node, this exception is thrown.

func setItem(String, Bool)

public func setItem(key: String, value: Bool): Unit

Description: Sends information of the Bool type from an inner macro to an outer macro.

Note:

This function can only be directly called as a function and cannot be assigned to a variable or used as an actual parameter or a return value.

Parameters:

• key: String: keyword to be sent, used for information search
• value: Bool: information of the Bool type to be sent

func setItem(String, Int64)

public func setItem(key: String, value: Int64): Unit

Description: Sends information of the Int64 type from an inner macro to an outer macro.

Note:

This function can only be directly called as a function and cannot be assigned to a variable or used as an actual parameter or a return value.

Parameters:

• key: String: keyword to be sent, used for information search
• value: Int64: information of the Int64 type to be sent

func setItem(String, String)

public func setItem(key: String, value: String): Unit

Description: Sends information of the String type from an inner macro to an outer macro.

Note:

This function can only be directly called as a function and cannot be assigned to a variable or used as an actual parameter or a return value.

Parameters:

• key: String: keyword to be sent, used for information search
• value: String: information of the String type to be sent