Package org.codehaus.groovy.syntax

# Class CSTNode

java.lang.Object
org.codehaus.groovy.syntax.CSTNode

Direct Known Subclasses:
  `Reduction`, `Token`

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`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CSTNode()`

- ## Method Summary

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

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Constructor Details

  - ### CSTNode

    public CSTNode()

- ## Method Details

  - ### getMeaning

    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`

  - ### setMeaning

    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

  - ### getType

    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`

  - ### canMean

    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

  - ### isA

    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

  - ### isOneOf

    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

  - ### isAllOf

    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

  - ### getMeaningAs

    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

  - ### isEmpty

    public boolean isEmpty()
    Returns `true` if this node is completely empty (no root element).
    Returns:
      `true` if empty, `false` otherwise

  - ### size

    public abstract int size()
    Returns the number of elements in this node (including the root).
    Returns:
      the number of elements

  - ### hasChildren

    public boolean hasChildren()
    Returns `true` if this node has any children (non-root elements).
    Returns:
      `true` if the node has children

  - ### children

    public int children()
    Returns the number of child elements (excluding the root).
    Returns:
      the number of children

  - ### get

    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`

  - ### get

    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`

  - ### getRoot

    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

  - ### getRoot

    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

  - ### getRootText

    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

  - ### getDescription

    public String getDescription()
    Returns a human-readable description of this node's semantic meaning.
    Returns:
      a description string from `Types`

  - ### getStartLine

    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

  - ### getStartColumn

    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

  - ### markAsExpression

    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

  - ### isAnExpression

    public boolean isAnExpression()
    Returns `true` if this node represents a complete expression.
    Returns:
      `true` if this is an expression

  - ### add

    public CSTNode add(CSTNode element)
    Adds an element to this node. Not all node types support this operation.
    Parameters:
      `element` - the element to add
    Returns:
      the added element
    Throws:
      `GroovyBugError` - if this node type does not support adding

  - ### addChildrenOf

    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

  - ### set

    public CSTNode set(int index, CSTNode element)
    Sets the element at the specified index. Not all node types support this operation.
    Parameters:
      `index` - the element index
      `element` - the element to set
    Returns:
      the set element
    Throws:
      `GroovyBugError` - if this node type does not support setting

  - ### asReduction

    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

  - ### toString

    public String toString()
    Returns a formatted string representation of this node and its children.
    Overrides:
      `toString` in class `Object`
    Returns:
      the formatted node tree as a string

  - ### write

    public void write(PrintWriter writer)
    Writes a formatted representation of this node to the specified writer.
    Parameters:
      `writer` - the `PrintWriter` to write to

  - ### write

    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