std.ast

Functionality Overview

The ast package primarily contains the syntax parser for Cangjie source code and Cangjie syntax tree nodes, providing syntax parsing functions. It can parse lexical units (Tokens) of Cangjie source code into Abstract Syntax Tree (AST) node objects.

For iOS platform scenarios, this package only supports running on iOS 12 and above.

The Cangjie ast package provides Macro With Context related functions for obtaining contextual information during macro expansion. In nested macro scenarios, inner macros can call the library function assertParentContext(String) to ensure the inner macro call is always nested within a specific outer macro call. If this function is called without being nested within the given outer macro call, it will throw an error. Additionally, the function insideParentContext(String) checks whether an inner macro call is nested within a specific outer macro call, returning a boolean value. Macro With Context related functions can only be called directly as functions and cannot be assigned to variables, passed as arguments, or returned as values.

Macro With Context related functions include:

• assertParentContext(String)
• getChildMessages(String)
• insideParentContext(String)
• setItem(String, Bool)
• setItem(String, Int64)
• setItem(String, String)
• setItem(String, Tokens)

API List

Functions

Function Name	Description
assertParentContext(String)	Checks whether the current macro call is within a specific macro call. If the check fails, the compiler generates an error message.
cangjieLex(String)	Converts a string to the Tokens type.
cangjieLex(String, Bool)	Converts a string to the Tokens type.
compareTokens(Tokens, Tokens)	Compares whether two Tokens are identical.
diagReport(DiagReportLevel, Tokens, String, String)	Error reporting interface that outputs diagnostic messages during the macro expansion phase of compilation, supporting WARNING and ERROR levels.
getChildMessages(String)	Retrieves messages sent by specific inner macros.
getTokenKind(UInt16)	Converts a lexical unit type number to TokenKind.
insideParentContext(String)	Checks whether the current macro call is within a specific macro call, returning a boolean value.
parseDecl(Tokens, String)	Parses a set of lexical units to obtain a Decl-type node.
parseDeclFragment(Tokens, Int64)	Parses a set of lexical units to obtain a Decl-type node and the index for continued parsing.
parseExpr(Tokens)	Parses a set of lexical units to obtain an Expr-type node.
parseExprFragment(Tokens, Int64)	Parses a set of lexical units to obtain an Expr-type node and the index for continued parsing.
parsePattern(Tokens)	Parses a set of lexical units to obtain a Pattern-type node.
parsePatternFragment(Tokens, Int64)	Parses a set of lexical units to obtain a Pattern-type node and the index for continued parsing.
parseProgram(Tokens)	Parses the source code of a single Cangjie file to obtain a Program-type node.
parseType(Tokens)	Parses a set of lexical units to obtain a TypeNode-type node.
parseTypeFragment(Tokens, Int64)	Parses a set of lexical units to obtain a TypeNode-type node and the index for continued parsing.
setItem(String, Bool)	Inner macros use this interface to send Bool-type messages to outer macros.
setItem(String, Int64)	Inner macros use this interface to send Int64-type messages to outer macros.
setItem(String, String)	Inner macros use this interface to send String-type messages to outer macros.
setItem(String, Tokens)	Inner macros use this interface to send Tokens-type messages to outer macros.

Interfaces

Interface Name	Description
ToBytes	Provides serialization functionality for corresponding types.
ToTokens	Interface for converting instances of corresponding types to Tokens, required for supporting quote interpolation operations.

Classes

Class Name	Description
Annotation	Represents compiler-built annotation nodes.
Argument	Represents function call argument nodes.
ArrayLiteral	Represents Array literal nodes.
AsExpr	Represents a type-checking expression.
AssignExpr	Represents assignment expression nodes.
BinaryExpr	Represents binary operation expression nodes.
Block	Represents block nodes.
Body	Represents structures composed of {} and internal declaration nodes in Class, Struct, Interface, and extension types.
CallExpr	Represents function call nodes.
ClassDecl	Class definition nodes.
CommandTypePattern	Represents a command pattern with type annotations.
ConstPattern	Represents constant pattern nodes.
Constructor	Represents Constructor nodes in enum types.
Decl	Parent class of all declaration nodes, inheriting from Node, providing common interfaces for all declaration nodes.
DoWhileExpr	Represents do-while expressions.
EnumDecl	Represents Enum definition nodes.
EnumPattern	Represents enum pattern nodes.
ExceptTypePattern	Represents nodes used in exception pattern states.
Expr	Parent class of all expression nodes, inheriting from Node.
ExtendDecl	Represents extension definition nodes.
FeatureId	Represents a feature name node.
FeaturesDirective	Represents a features directive node.
FeaturesSet	Represents a features set which contains names of featurs.
ForInExpr	Represents for-in expressions.
FuncDecl	Represents function definition nodes.
FuncParam	Represents function parameter nodes, including unnamed and named parameters.
FuncType	Represents function type nodes.
GenericConstraint	Represents generic constraint nodes.
GenericParam	Represents type parameter nodes.
Handler	Represents a handle clause.
IfExpr	Represents conditional expressions.
ImportContent	Represents import items in package import nodes.
ImportList	Represents package import nodes.
IncOrDecExpr	Represents expressions containing increment (++) or decrement (--) operators.
InterfaceDecl	Represents interface definition nodes.
IsExpr	Represents a type-checking expression.
JumpExpr	Represents break and continue in loop expression bodies.
LambdaExpr	Represents Lambda expressions, which are anonymous functions.
LetPatternExpr	Represents destructuring pattern matching nodes in let declarations.
LitConstExpr	Represents constant expression nodes.
MacroDecl	Represents macro definition nodes.
MacroExpandDecl	Represents macro call nodes.
MacroExpandExpr	Represents macro call nodes.
MacroExpandParam	Represents macro call nodes.
MacroMessage	Records messages sent by inner macros.
MainDecl	Represents main function definition nodes.
MatchCase	Represents case nodes in match expressions.
MatchExpr	Represents pattern-matching expressions.
MemberAccess	Represents member access expressions.
Modifier	Indicates that a definition has certain characteristics, typically placed at the beginning of the definition.
Node	Parent class of all Cangjie syntax tree nodes.
OptionalExpr	Represents expression nodes with question mark operators.
PackageHeader	Represents package declaration nodes.
ParenExpr	Represents parenthesized expression nodes, which are expressions enclosed in parentheses.
ParenType	Represents parenthesized type nodes.
Pattern	Parent class of all pattern-matching nodes, inheriting from Node.
PerformExpr	Represents a perform expression node.
PrefixType	Represents prefix type nodes with question marks.
PrimaryCtorDecl	Represents primary constructor nodes.
PrimitiveType	Represents primitive type nodes.
PrimitiveTypeExpr	Represents primitive type expression nodes.
Program	Represents Cangjie source file nodes.
PropDecl	Represents property definition nodes.
QualifiedType	Represents user-defined member types.
QuoteExpr	Represents quote expression nodes.
QuoteToken	Represents any valid token within quote expression nodes.
RangeExpr	Represents expressions containing range operators.
RefExpr	Represents expression nodes related to custom type nodes.
RefType	Represents user-defined type nodes.
ResumeExpr	Represents a resume expression node.
ReturnExpr	Represents return expression nodes.
SpawnExpr	Represents Spawn expressions.
StructDecl	Represents Struct nodes.
SubscriptExpr	Represents index access expressions.
SynchronizedExpr	Represents synchronized expressions.
ThisType	Represents This type nodes.
ThrowExpr	Represents throw expression nodes.
Tokens	A type that encapsulates Token sequences.
TokensIterator	Implements iterator functionality for Tokens.
TrailingClosureExpr	Represents trailing Lambda nodes.
TryExpr	Represents try expression nodes.
TupleLiteral	Represents tuple literal nodes.
TuplePattern	Represents tuple pattern nodes.
TupleType	Represents tuple type nodes.
TypeAliasDecl	Represents a type alias node.
TypeConvExpr	Represents a type conversion expression.
TypeNode	The parent class of all type nodes, inherits from Node.
TypePattern	Represents a type pattern node.
UnaryExpr	Represents a unary operation expression node.
VArrayExpr	Represents an instance node of VArray.
VArrayType	Represents a VArray type node.
VarDecl	Represents a variable declaration node.
VarOrEnumPattern	Represents a node when the pattern identifier is an Enum constructor.
VarPattern	Represents a binding pattern node.
Visitor	An abstract class that internally defines default visit functions for accessing different types of AST nodes.
WhileExpr	Represents a while expression.
WildcardExpr	Represents a wildcard expression node.
WildcardPattern	Represents a wildcard pattern node.

Enumeration

Enumeration Name	Functionality
DiagReportLevel	Indicates the information level of error reporting interface, supporting ERROR and WARNING formats.
ImportKind	Represents the type of import statements, including single import, alias import, full import, and multiple imports.
TokenKind	Represents all lexical structures in Cangjie compilation, including symbols, keywords, identifiers, line breaks, etc.

Structures

Structure Name	Functionality
Position	Data structure representing position information, containing file ID, line number, and column number.
Token	Lexical unit type.

Exception Classes

Exception Class Name	Functionality
ASTException	Exception class for the AST library, used when exceptions occur during AST library calls.
MacroContextException	Context macro exception class for the AST library, used when exceptions occur in context macro-related interfaces.
ParseASTException	Parsing exception class for the AST library, used when exceptions occur during node parsing.