Package: org.codehaus.groovy.syntax

## [Java] Class CSTNode

- org.codehaus.groovy.syntax.CSTNode

-     public abstract class CSTNode
      extends Object

  Abstract base class for nodes in the concrete syntax tree (CST) produced by parsing. Every CST node has a Token as its root element, which indicates the node's type. This class provides methods for querying node meaning, type, structure, and converting between different node representations.

  See Also:
    Token
    Reduction
    Types

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public CSTNode` | `add(CSTNode element)` Adds an element to this node.
    `` | `public void` | `addChildrenOf(CSTNode of)` Adds all children of the specified node to this node.
    `` | `public abstract Reduction` | `asReduction()` Converts this node to a Reduction.
    `` | `public boolean` | `canMean(int type)` Returns `true` if this node can be coerced to the specified type.
    `` | `public int` | `children()` Returns the number of child elements (excluding the root).
    `` | `public abstract CSTNode` | `get(int index)` Returns the element at the specified index, or `null` if not found.
    `` | `public CSTNode` | `get(int index, boolean safe)` Returns the element at the specified index, or Token.NULL if the element is not found and `safe` is `true`.
    `` | `public String` | `getDescription()` Returns a human-readable description of this node's semantic meaning.
    `` | `public int` | `getMeaning()` Returns the current semantic meaning (interpretation) of this node.
    `` | `public int` | `getMeaningAs(int[] types)` Returns the first matching meaning of the specified types.
    `` | `public abstract Token` | `getRoot()` Returns the root token of this node.
    `` | `public Token` | `getRoot(boolean safe)` Returns the root token of this node, returning Token.NULL if the actual root is `null` and `safe` is `true`.
    `` | `public String` | `getRootText()` Returns the text content of the root token.
    `` | `public int` | `getStartColumn()` Returns the starting column number of this node in the source.
    `` | `public int` | `getStartLine()` Returns the starting line number of this node in the source.
    `` | `public int` | `getType()` Returns the actual syntactic type of this node as determined by the parser.
    `` | `public boolean` | `hasChildren()` Returns `true` if this node has any children (non-root elements).
    `` | `public boolean` | `isA(int type)` Returns `true` if this node's meaning matches the specified type.
    `` | `public boolean` | `isAllOf(int[] types)` Returns `true` if this node's meaning matches all of the specified types.
    `` | `public boolean` | `isAnExpression()` Returns `true` if this node represents a complete expression.
    `` | `public boolean` | `isEmpty()` Returns `true` if this node is completely empty (no root element).
    `` | `public boolean` | `isOneOf(int[] types)` Returns `true` if this node's meaning matches any of the specified types.
    `` | `public void` | `markAsExpression()` Marks this node as a complete expression.
    `` | `public CSTNode` | `set(int index, CSTNode element)` Sets the element at the specified index.
    `` | `public CSTNode` | `setMeaning(int meaning)` Sets the semantic meaning (interpretation) of this node.
    `` | `public abstract int` | `size()` Returns the number of elements in this node (including the root).
    `` | `public String` | `toString()` Returns a formatted string representation of this node and its children.
    `` | `public void` | `write(PrintWriter writer)` Writes a formatted representation of this node to the specified writer.
    `` | `protected void` | `write(PrintWriter writer, String indent)` Writes a formatted representation of this node to the specified writer, with indentation for readability.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### public CSTNode add(CSTNode element)

      Adds an element to this node. Not all node types support this operation.

      throws:
        GroovyBugError if this node type does not support adding
      Parameters:
        `element` - the element to add
      Returns:
        the added element

    - #### public void addChildrenOf(CSTNode of)

      Adds all children of the specified node to this node. Skips the root element and copies only the children.

      Parameters:
        `of` - the source node whose children are to be copied

    - #### public abstract Reduction asReduction()

      Converts this node to a Reduction. If this node is already a Reduction, returns itself.

      Returns:
        this node as a Reduction

    - #### public boolean canMean(int type)

      Returns `true` if this node can be coerced to the specified type. This is determined by the type hierarchy defined in Types.

      Parameters:
        `type` - the type to check against
      Returns:
        `true` if coercion is possible

    - #### public int children()

      Returns the number of child elements (excluding the root).

      Returns:
        the number of children

    - #### public abstract CSTNode get(int index)

      Returns the element at the specified index, or `null` if not found.

      Parameters:
        `index` - the element index (0 for root)
      Returns:
        the element at the index, or `null`

    - #### public CSTNode get(int index, boolean safe)

      Returns the element at the specified index, or Token.NULL if the element is not found and `safe` is `true`.

      Parameters:
        `index` - the element index
        `safe` - if `true`, returns Token.NULL instead of `null` for missing elements
      Returns:
        the element at the index, Token.NULL if safe and missing, or `null`

    - #### public String getDescription()

      Returns a human-readable description of this node's semantic meaning.

      Returns:
        a description string from Types

    - #### public int getMeaning()

      Returns the current semantic meaning (interpretation) of this node. For nodes without a root, returns Types.UNKNOWN.

      Returns:
        the node's meaning type from Types

    - #### public int getMeaningAs(int[] types)

      Returns the first matching meaning of the specified types. Useful for determining which of several possible meanings this node has.

      Parameters:
        `types` - an array of types to check
      Returns:
        the first matching type, or Types.UNKNOWN if no match is found

    - #### public abstract Token getRoot()

      Returns the root token of this node. By convention, all nodes have a Token as their root element (at index 0), which indicates the syntactic type of the node.

      Returns:
        the root token, or `null` if the node is empty

    - #### public Token getRoot(boolean safe)

      Returns the root token of this node, returning Token.NULL if the actual root is `null` and `safe` is `true`.

      Parameters:
        `safe` - if `true`, returns Token.NULL instead of `null`
      Returns:
        the root token

    - #### public String getRootText()

      Returns the text content of the root token. Uses `getRoot(true)` to ensure a non-null root.

      Returns:
        the text of the root token

    - #### public int getStartColumn()

      Returns the starting column number of this node in the source.

      Returns:
        the column number (1-based), or -1 if not known

    - #### public int getStartLine()

      Returns the starting line number of this node in the source.

      Returns:
        the line number (1-based), or -1 if not known

    - #### public int getType()

      Returns the actual syntactic type of this node as determined by the parser. For nodes without a root, returns Types.UNKNOWN.

      Returns:
        the node's type from Types

    - #### public boolean hasChildren()

      Returns `true` if this node has any children (non-root elements).

      Returns:
        `true` if the node has children

    - #### public boolean isA(int type)

      Returns `true` if this node's meaning matches the specified type.

      Parameters:
        `type` - the type to check
      Returns:
        `true` if the node's meaning is of the specified type

    - #### public boolean isAllOf(int[] types)

      Returns `true` if this node's meaning matches all of the specified types.

      Parameters:
        `types` - an array of types to check
      Returns:
        `true` if the node's meaning matches all of the types

    - #### public boolean isAnExpression()

      Returns `true` if this node represents a complete expression.

      Returns:
        `true` if this is an expression

    - #### public boolean isEmpty()

      Returns `true` if this node is completely empty (no root element).

      Returns:
        `true` if empty, `false` otherwise

    - #### public boolean isOneOf(int[] types)

      Returns `true` if this node's meaning matches any of the specified types.

      Parameters:
        `types` - an array of types to check
      Returns:
        `true` if the node's meaning matches at least one of the types

    - #### public void markAsExpression()

      Marks this node as a complete expression. Not all node types support this operation.

      throws:
        GroovyBugError if this node type does not support marking

    - #### public CSTNode set(int index, CSTNode element)

      Sets the element at the specified index. Not all node types support this operation.

      throws:
        GroovyBugError if this node type does not support setting
      Parameters:
        `index` - the element index
        `element` - the element to set
      Returns:
        the set element

    - #### public CSTNode setMeaning(int meaning)

      Sets the semantic meaning (interpretation) of this node. The meaning may differ from the node's actual type and is often assigned during semantic analysis after parsing.

      Parameters:
        `meaning` - the new meaning type from Types
      Returns:
        this node for convenience chaining

    - #### public abstract int size()

      Returns the number of elements in this node (including the root).

      Returns:
        the number of elements

    - #### public String toString()

      Returns a formatted string representation of this node and its children.

      Returns:
        the formatted node tree as a string

    - #### public void write(PrintWriter writer)

      Writes a formatted representation of this node to the specified writer.

      Parameters:
        `writer` - the PrintWriter to write to

    - #### protected void write(PrintWriter writer, String indent)

      Writes a formatted representation of this node to the specified writer, with indentation for readability. The indentation is increased for each level of recursion to show the tree structure.

      Parameters:
        `writer` - the PrintWriter to write to
        `indent` - the indentation string to prepend to each line