/*
* Copyright (C) [2020] Futurewei Technologies, Inc. All rights reverved.
*
* OpenArkFE is licensed under the Mulan PSL v1.
* You can use this software according to the terms and conditions of the Mulan PSL v1.
* You may obtain a copy of Mulan PSL v1 at:
*
*  http://license.coscl.org.cn/MulanPSL
*
* THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, WITHOUT WARRANTIES OF ANY KIND, EITHER
* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO NON-INFRINGEMENT, MERCHANTABILITY OR
* FIT FOR A PARTICULAR PURPOSE.
* See the Mulan PSL v1 for more details.
*/
This file defines Rule Actions supported in both Autogen and Parser. The cooperation between
all modules are as below.
1. The Action names in .spec files should be one of Actions below.
2. Autogen generates rule tables in gen_xxx.h/cpp files. It user ActionId.
3. AST maintains a table which is basically a mapping between ActionId and the corresponding
   utility functions.
4. The utility functions will (1) do the validation (2) create the tree node.

[NOTE] This file only contains actions to create common tree node seen in most programming
       languages. If a language has tree nodes not covered here, they can be defined in its
       dedicated directory.

[Format] The Format tells the parameters it needs when writing .spec files.
         It also shows the internal parameters when parser creates the AST tree node.

* BuildBlock
  Format: BuildBlock(block-tree)
  Block is widely used in many scenarios, like function body, class body, or just a block.
  It only takes one parameter which is the root node of block tree.

* BuildBinaryOperation
  Format: BuildBinaryOperation(Left operand, Operator, Right Operand)

* BuildUnaryOperation
  Format: BuildUnaryOperation(Operator, Operand)
  This is the prefix unary operation. It's the default mode of a unary operation. So we don't
  give it a name like BuildPreUnaryOperation...

* BuildPostfixOperation
  Format: BuildPostfixOperation(Operator, Operand)
  This is the postfix unary operation.

* AddLabel
  Format: AddLabel(Stmt-or-expr, Label)
  It returns the statment or expr with label attached.

* BuildAssignment
  Format: BuildAssignment(Left operand, Operator, Right Operand)
          The operator is the assignment in the language
  The reason we take Operator as an operand is there could be different types of assignment,
  like +=, -=, etc.

* BuildReturn
  Format: BuildReturn(return-value)

* BuildCondBranch
  Format: BuildCondBranch(cond-expre)

* AddCondBranchTrueStatement
  Format: BuildCondBranch(true-expre)

* AddCondBranchFalseStatement
  Format: BuildFalseBranch(false-expre)

* BuildBreak
  BuildBreak(break-identifier)
  Build a break statement. The break point could be an identifier or empty.

* BuildForLoop
  BuildForLoop(init, cond, update, body)
  Build a common for loop. 'init' could be a list of expression, 'cond' should be boolean
  expression, 'update' could be a list of expression. 'body' could be a single statement
  or a block or empty.

* BuildWhileLoop
  Format : BuildWhileLoop(cond, body)

* BuildDoLoop
  Format : BuildDoLoop(cond, body)

* BuildSwitchLabel
  BuildSwitchLabel(const-expr)
  The only argument is the expression of 'case'.

* BuildDefaultSwitchLabel
  Format: BuildDefaultSwitchLabel()
  It takes NO argument. This is to build 'default' label.

* BuildOneCase
  Format : BuildOneCase(label, statement)
  It takes two arguments. First is the tree node of label built by BuildSwitchLabel.
  The second the statements under this label.

* BuildAllCases
  Format : BuildAllCases(list-of-cases)
  It builds the body of the switch statement. It includes all cases.
  The only argument is the tree node of all-cases.

* BuildSwitch
  Format : BuildSwitch(cond-expr, all-cases)

* BuildDecl
  Format: BuildDecl(Type, Variable)

  The Decl will be added to its scope. Every Decl has a scope which is the nearest one
  enclosing it.

* BuildVarList
  Format: BuildVarlList(Variable_A, Variable_B)

  1) This is the build a list of variables. This could be used in multiple place, as long as
     they have the syntax like: a, b, c. For example, in variable declarations like
       int a, b;
     or in function parameters like
       foo (a ,b);
     Right now we only support two parameters. It can be extended later if needed.

  2) The ',' in between is a separator which could be varied between different languages. some
     language may use whitespace as separator between variables.
  3) The result will be a VariableListNode, which contains a list of IdentifierNode (Variable).
  4) If a variable is a tree containing multiple variables, the function will do a consolidatation
     to put all the variables in the list, and removing the tree from the resulting tree.
  5) If a variable is a already a VariableListNode, 4) is applied too.

* BuildClass
  Format: BuildClass(classIdentifier)

* AddSuperClass
  Format: AddSuperClass(superclassIdentifier)

* AddSuperInterface
  Format: AddSuperInterface(superInterfaceIdentifier)

* AddClassBody
  Format: AddClassBody(classbody)
  Add a classbody to mLastTreeNode, which should be a ClassNode.
  'classbody' is usually a Block which is generated by BuildBlock.

* AddAttribute
  Format: AddAttribute(Attribute list)
  AddAttribute is attached together with its previous BuildDecl. They should inside the same Rule.
  The attributes will be applied to the tree node of BuildDecl().

* AddAttributeTo
  Format: AddAttributeTo(Tree, Attribute list)
  This is another format of adding attribute. The first argument is the target of attribute. This
  function doesn't depend on any already built declarator. An example is
    rule VariableDeclarator : VariableDeclaratorId + ZEROORONE('=' + VariableInitializer)
      attr.action: AddAttributeTo(%1, %2)

* AddInitTo
  Format: AddInitTo(Target, InitValue)
  The first argument is the target declarator, or expression, or etc. The second is the init value.
  An example is
    rule VariableDeclarator : VariableDeclaratorId + ZEROORONE('=' + VariableInitializer)
      attr.action: AddInitTo(%1, %2)

* BuildAnnotationType
  Format: BuildAnnotationType(annotation-name)

* BuildAnnotation
  Format: BuildAnnotation(annotation-name)

* AddAnnotationTypeBody
  Format: AddAnnotationTypeBody(annotation-type-body)

* BuildDim
  Format: BuildDim(annotation-of-dim)
  Build one dimension with possible annotation

* BuildDims
  Format: BuildDims(the-first-set-of-dims, the-rest-dims)
  Build multiple dimensions. The first set of dimensions is the first parameter, this could be
  multiple dimension already. The second parameter tells the rest of dimensions.

* AddDims
  Format: AddDims(dims)
  Add the dimensions into the mLastTreeNode.

* AddDimsTo
  Format: AddDimsTo(var, dims)
  Add the dimensions into var.

* BuildFunction
  Format: BuildFunction(function-Identifier)

* BuildConstructor
  Format: BuildConstructor(function-Identifier)
  This is almost the same as BuildFunction, except it has no return type.

* BuildInstInit
  Format: BuildInstInit(block-tree, or an existing block node)
  It takes one argument, either a tree, or an existing block node.
  This is the same as BuildBlock, except setting it's a instance initializer.
  This is to accomadate Java spec. C++ has different syntax/semantic regarding
  instance initializer.

* AddFunctionBody
  Format: AddFunctionBody(funcbody)
  Add a funcbody to mLastTreeNode, which should be a FunctionNode.
  'funcbody' is usually a Block which is generated by BuildBlock.

* AddFunctionBodyTo
  Format: AddFunctionBodyTo(func, funcbody)
  Add a funcbody to func, which should be a FunctionNode.
  'funcbody' is usually a Block which is generated by BuildBlock.

* AddTypeTo
  Format: AddTypeTo(tree, type)

* BuildThrows
  Format: BuildThrows(tree)
  It builds a list of thrown exceptions. It's actually a PassNode.

* AddThrowsTo
  Format: AddThrowsTo(tree, throws)
  It builds a list of thrown exceptions. It's actually a PassNode with >1 exception,
  or just a simple IdentifierNode with exception name. It returns the tree with
  throws attached.