Module dev.civl.abc
Package dev.civl.abc.ast.node.IF

Interface ASTNode

All Known Subinterfaces:
AbstractFunctionDefinitionNode, AlignOfNode, AllocationNode, AnyactNode, ArrayDesignatorNode, ArrayLambdaNode, ArrayTypeNode, ArrowNode, AssignsOrReadsNode, AssumesNode, AtomicNode, AtomicTypeNode, BasicTypeNode, BehaviorNode, BlockItemNode, CallEventNode, CastNode, CharacterConstantNode, ChooseStatementNode, CivlForNode, CompletenessNode, CompositeEventNode, CompoundInitializerNode, CompoundLiteralNode, CompoundStatementNode, ConstantNode, ContractNode, DeclarationListNode, DeclarationNode, DependsEventNode, DependsNode, DerivativeExpressionNode, DesignationNode, DesignatorNode, DomainTypeNode, DotNode, EnsuresNode, EnumerationConstantNode, EnumerationTypeNode, EnumeratorDeclarationNode, ExpressionNode, ExpressionStatementNode, ExtendedQuantifiedExpressionNode, FieldDeclarationNode, FieldDesignatorNode, FloatingConstantNode, FocusAssertTransformNode, FocusLoopTransformNode, FocusOrderedTransformNode, FocusTransformNode, ForLoopInitializerNode, ForLoopNode, FunctionCallNode, FunctionDeclarationNode, FunctionDefinitionNode, FunctionTypeNode, GenericAssociationNode, GenericSelectionNode, GotoNode, GuardsNode, HereOrRootNode, IdentifierExpressionNode, IdentifierNode, IfNode, InitializerNode, InsertTransformNode, IntegerConstantNode, InvariantNode, JumpNode, LabeledStatementNode, LabelNode, LambdaNode, LambdaTypeNode, LoopNode, MemoryEventNode, NoactNode, NothingNode, NullStatementNode, ObjectOrRegionOfNode, OmpAtomicNode, OmpDeclarativeNode, OmpEndNode, OmpExecutableNode, OmpForNode, OmpFunctionReductionNode, OmpNode, OmpParallelNode, OmpReductionNode, OmpSimdNode, OmpSymbolReductionNode, OmpSyncNode, OmpWorksharingNode, OperatorNode, OrdinaryDeclarationNode, OrdinaryLabelNode, PairNode<S,T>, PointerTypeNode, PragmaNode, PredicateNode, ProcnullNode, QuantifiedExpressionNode, RegularRangeNode, RemoteOnExpressionNode, RequiresNode, ResultNode, ReturnNode, RunNode, ScopeOfNode, ScopeParameterizedDeclarationNode, SelfNode, SequenceNode<T>, SizeableNode, SizeofNode, SpawnNode, StatementExpressionNode, StatementNode, StatenullNode, StaticAssertionNode, StringLiteralNode, StructureOrUnionTypeNode, SwitchLabelNode, SwitchNode, TransformNode, TypedefDeclarationNode, TypedefNameNode, TypeNode, TypeofNode, UpdateNode, VariableDeclarationNode, WhenNode, WildcardNode
public interface ASTNode

Root of the AST node type hierarchy. All AST nodes implement this interface.

An AST node has some number n of children. Each child is either an AST node or null. The children are arranged in an ordered sequences and numbered from 0.

Every AST node has at most one parent. If a node u has a (non- null) parent v, then it is guaranteed that u is a child of v. This class is designed so that it is not possible to violate these invariants.

Nodes are mutable objects. It is possible to modify various aspects of the node, to remove a node from its parent, to add new children to a node, and so on.

At any point in time, a node is either "owned" by an AST or it is "free". A node can be owned by at most one AST. A node starts out as free, and becomes owned by an AST when an AST is created and the node is reachable from the root node used to create the new AST. The nodes of an AST can become free by "releasing" the AST, which essentially dissolves the AST but leaves the nodes intact. Modifications to the tree structure (the parent and child relations) can only occur on free nodes, hence to modify an AST it is necessary to first release it. After the modifications are complete, a new AST can be formed from the modified nodes.

See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    ASTNode.NodeKind
    The different kind of AST nodes.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addAllTransformAnnotations(List<TransformNode> transforms)
     
    void
    addTransformAnnotation(TransformNode transform)
     
    ASTNode
    child(int index)
    Returns the index-th child node of this AST node.
    int
    childIndex()
    Returns the index of this node among the children of its parent.
    Iterable<ASTNode>
    children()
    Returns the sequence of children of this node as an iterable object.
    ASTNode
    copy()
    Returns a deep copy of this AST node.
    DifferenceObject
    diff(ASTNode that)
    Returns the first difference between this AST node and that node.
    boolean
    equiv(ASTNode that)
    Is the given AST node equivalent to me?
    Object
    getAttribute(AttributeKey key)
    Returns the attribute value associated to the given key, or null if no value has been set for that key.
    AST
    getOwner()
    Returns the "owner" of this AST, i.e., the AST to which this node belongs.
    Scope
    getScope()
    Gets the scope in which the syntactic element corresponding to this node occurs.
    Source
    getSource()
    Returns the source object that locates the origin of this program construct in the original source code.
    int
    id()
    ID number unique within the AST to which this node belongs, or -1 if the node is free (not owned by an AST).
    void
    keepOnly(NodePredicate keep)
    Removes all children that do not satisfy the predicate and applies this method recursively to the remaining children.
    ASTNode
    nextDFS()
    Finds next non-null node in AST in DFS order.
    ASTNode.NodeKind
    nodeKind()
    Returns the node kind: this is an element of the enumerated type ASTNode.NodeKind, which is used to categorize the different kinds of nodes.
    int
    numChildren()
    Returns the number of child nodes of this AST node.
    ASTNode
    parent()
    Returns the parent of this node, or null if this node has no parent.
    void
    prettyPrint(PrintStream out)
    Pretty-prints this AST node (and its descendants) in a form that should be similar to the actual programming language.
    StringBuffer
    prettyRepresentation()
    Returns the pretty representation of this AST node (and its descendants) in a form that should be similar to the actual programming language.
    StringBuffer
    prettyRepresentation(int maxLength)
    Returns the pretty representation of this AST node (and its descendants) in a form that should be similar to the actual programming language.
    void
    print(String prefix, PrintStream out, boolean includeSource)
    Prints a long-form textual representation of this node.
    void
    remove()
    Removes this node from its parent.
    ASTNode
    removeChild(int index)
    Removes the child at given index from this node.
    void
    removeTransformAnnotation(int index)
     
    void
    setAttribute(AttributeKey key, Object value)
    Sets the attribute value associated to the given key.
    ASTNode
    setChild(int index, ASTNode child)
    Sets the child node at the given index.
    void
    setId(int id)
    Sets the ID number of this node.
    void
    setOwner(AST owner)
    Sets the owner of this node to the given AST.
    void
    setScope(Scope scope)
    Sets the scope of this syntactic element.
    String
    toString()
    Returns a short textual representation of this node only.
    List<TransformNode>
    transformAnnotations()
     

  • Method Details

    • child

      ASTNode child(int index) throws NoSuchElementException
      Returns the index-th child node of this AST node. The children of a node are ordered and numbered starting from 0.
      Parameters:
      index - an integer in the range [0,n-1], where n is the number of children of this node, i.e., the value returned by numChildren()
      Returns:
      the index-th child of this node; note that this may be null.
      Throws:
      NoSuchElementException - if index is less than 0 or greater than or equal to the number of children

    • childIndex

      int childIndex()

      Returns the index of this node among the children of its parent.

      The children of a node are ordered and numbered from 0 to n-1, where n is the number of children. Since an AST is a tree, every node has at most one parent. If this node has a parent, this method returns the index of this node in its parent's children list. If this node does not have a parent, this method returns -1.

      Returns:
      the index of this node it its parent's child list, or -1 if it has no parent

    • children

      Iterable<ASTNode> children()
      Returns the sequence of children of this node as an iterable object. Do not attempt to cast the iterable to another type and/or modify it; if you do, all bets are off. Use it only to iterate over the children.
      Returns:
      the (ordered) sequence of children nodes of this node; may contain null values

    • copy

      ASTNode copy()
      Returns a deep copy of this AST node. The node and all of its descendants will be cloned. The cloning does not copy analysis or attribute information.
      Returns:
      deep copy of this node

    • getAttribute

      Object getAttribute(AttributeKey key)
      Returns the attribute value associated to the given key, or null if no value has been set for that key. Note that attribute keys are generated using method NodeFactory.newAttribute(String, Class).
      Parameters:
      key - an attribute key
      Returns:
      the value associated to the key by this node, or null

    • getOwner

      AST getOwner()
      Returns the "owner" of this AST, i.e., the AST to which this node belongs. This can be null, in which case we say this node is "free".
      Returns:
      the owner of this node or null

    • getScope

      Scope getScope()
      Gets the scope in which the syntactic element corresponding to this node occurs.
      Returns:
      the scope

    • getSource

      Source getSource()
      Returns the source object that locates the origin of this program construct in the original source code. This is used for reporting friendly messages to the user. The source element specifies a range of tokens in a token stream and can be used to display file name, line numbers, and character indexes to precisely target a source region.
      Returns:
      source object for this node

    • id

      int id()
      ID number unique within the AST to which this node belongs, or -1 if the node is free (not owned by an AST).
      Returns:
      if the node is owned by an AST, the node ID number, which is unique among all nodes in this AST; otherwise -1

    • keepOnly

      void keepOnly(NodePredicate keep)

      Removes all children that do not satisfy the predicate and applies this method recursively to the remaining children.

      "Removing a node" is interpreted as follows: if u is an instance of SequenceNode, and a child of u does not satisfy the predicate, then the child is removed and all subsequent elements of the sequence are shifted down to remove the gap. If u is not an instance of SequenceNode and the child does not satisfy the predicate then the child is replaced by null.

      Parameters:
      keep - a node predicate specifying which nodes to keep

    • nodeKind

      ASTNode.NodeKind nodeKind()
      Returns the node kind: this is an element of the enumerated type ASTNode.NodeKind, which is used to categorize the different kinds of nodes.
      Returns:
      The node kind

    • numChildren

      int numChildren()
      Returns the number of child nodes of this AST node. This includes children which are null!
      Returns:
      the number of child nodes of this node

    • parent

      ASTNode parent()
      Returns the parent of this node, or null if this node has no parent.
      Returns:
      parent node or null

    • print

      void print(String prefix, PrintStream out, boolean includeSource)
      Prints a long-form textual representation of this node. The form usually involves multiple lines.
      Parameters:
      prefix - a string which should be prepended to every line of output; typically something like "| | " which is used to control indentation
      out - stream to which to print
      includeSource - should the source information be included in the print-out? This incorporates the file name, line number(s), and start and end character indexes for the source code corresponding to this node

    • removeChild

      ASTNode removeChild(int index)

      Removes the child at given index from this node.

      The index must be in the range [0,n-1], where n is the value returned by numChildren() in the pre-state (i.e., before this method is invoked). If there is no child at the given index (i.e., child is null), this is a no-op.

      If the removed child is non-null, its parent is set to null.

      Parameters:
      index - nonnegative integer in the range [0,n-1], where n is the number of children before executing this method
      Returns:
      the child that was removed (may be null)
      Throws:
      ASTException - if this node is not free, or index is not in the range [0,n-1]

    • remove

      void remove()
      Removes this node from its parent. If the parent of this node is already null, this is a no-op.

    • setAttribute

      void setAttribute(AttributeKey key, Object value)
      Sets the attribute value associated to the given key. This method also checks that the value belongs to the correct class. Note that attribute keys are generated by calling method NodeFactory.newAttribute(String, Class).
      Parameters:
      key - the attribute key
      value - the attribute value

    • setChild

      ASTNode setChild(int index, ASTNode child)

      Sets the child node at the given index. This node (i.e., this) must be free (not owned by an AST) when this method is called.

      The child may be null or non-null. A non- null child must have a null parent, i.e., it must not be the child of another node.

      If there is already a non-null child of this node in position index, the old child is removed, i.e., its parent is set to null.

      The caller is responsible for ensuring that the child is of the appropriate kind and type.

      The index can be any nonnegative integer. The list of children will be expanded as necessary with null values in order to incorporate the index.

      To illustrate how this method could be used, consider the case of swapping two nodes. Supposed u1 and u2 are nodes, u1 has a non-null child in position i1, and u2 has a non-null child in position i2, and we wish to swap the two children. This could be accomplished with the following code: 

       ASTNode v1 = u1.removeChild(i1), v2 = u2.removeChild(i2);
 u1.setChild(i1, v2);
 u2.setChild(i2, v1);

      Parameters:
      index - any nonnegative integer
      child - a node (or null) to be made the index-th child of this node
      Returns:
      the old child in position index (may be null)
      Throws:
      ASTException - if any of the following hold: (1) this node is not free, (2) index is negative, or (3) child is not null and has a non-null parent.

    • setId

      void setId(int id)
      Sets the ID number of this node.
      Parameters:
      id - the ID number

    • setOwner

      void setOwner(AST owner)
      Sets the owner of this node to the given AST.
      Parameters:
      owner - the AST to make the owner of this node

    • setScope

      void setScope(Scope scope)
      Sets the scope of this syntactic element.
      Parameters:
      scope - the scope

    • addTransformAnnotation

      void addTransformAnnotation(TransformNode transform)

    • removeTransformAnnotation

      void removeTransformAnnotation(int index)

    • addAllTransformAnnotations

      void addAllTransformAnnotations(List<TransformNode> transforms)

    • transformAnnotations

      List<TransformNode> transformAnnotations()

    • equiv

      boolean equiv(ASTNode that)
      Is the given AST node equivalent to me?
      Parameters:
      that - The given AST node to be compared.
      Returns:
      True iff this AST node is equivalent with that AST node.

    • diff

      DifferenceObject diff(ASTNode that)
      Returns the first difference between this AST node and that node.
      Parameters:
      that - The given AST node to be compared.
      Returns:
      The difference of this AST node and that node, null if both nodes are equivalent.

    • toString

      String toString()
      Returns a short textual representation of this node only.
      Overrides:
      toString in class Object
      Returns:
      short textual representation of this node

    • nextDFS

      ASTNode nextDFS()
      Finds next non-null node in AST in DFS order.
      Returns:
      next non-null node in DFS order or null if there is none

    • prettyPrint

      void prettyPrint(PrintStream out)
      Pretty-prints this AST node (and its descendants) in a form that should be similar to the actual programming language.
      Parameters:
      out - stream to which output should be sent

    • prettyRepresentation

      StringBuffer prettyRepresentation()
      Returns the pretty representation of this AST node (and its descendants) in a form that should be similar to the actual programming language.
      Returns:
      the pretty representation of this AST node (and its descendants) in a form that should be similar to the actual programming language.

    • prettyRepresentation

      StringBuffer prettyRepresentation(int maxLength)
      Returns the pretty representation of this AST node (and its descendants) in a form that should be similar to the actual programming language.
      Parameters:
      maxLength - the maximal length of the string representation of this node; -1 if the length is unlimited
      Returns:
      the pretty representation of this AST node (and its descendants) in a form that should be similar to the actual programming language.