Package net.sourceforge.pmd.lang.ast

Interface Node

All Superinterfaces:
Reportable
All Known Subinterfaces:
AntlrNode<N>, CommentNode, GenericNode<N>, JjtreeNode<N>, RootNode, ScopedNode, TextAvailableNode, TextNode
All Known Implementing Classes:
AbstractJjtreeNode, AbstractNode, BaseAntlrErrorNode, BaseAntlrInnerNode, BaseAntlrNode, BaseAntlrTerminalNode, PlainTextLanguage.PlainTextFile
public interface Node extends Reportable
Root interface for all AST nodes. This interface provides only the API shared by all AST implementations in PMD language modules. This includes for now:

Every language implementation must publish a sub-interface of Node which serves as a supertype for all nodes of that language (e.g. pmd-java provides JavaNode, pmd-apex provides ApexNode, etc.). It is assumed in many places that the getChild(int) and getParent() method return an instance of this sub-interface. For example, no JSP node should have a Java node as its child. Embedding nodes from different languages will not be done via these methods, and conforming implementations should ensure that every node returned by these methods are indeed of the same type.

  • Field Details

    • COORDS_COMPARATOR

      static final Comparator<Node> COORDS_COMPARATOR
      Compares nodes according to their location in the file. Note that this comparator is not consistent with equals (see Comparator) as some nodes have the same location.

  • Method Details

    • getImage

      default String getImage()
      Returns a string token, usually filled-in by the parser, which describes some textual characteristic of this node. This is usually an identifier, but you should check that using the Designer. On most nodes though, this method returns null.

      Note: This method will be deprecated in the future (#4787). It will be replaced with methods that have more specific names in node classes. In some cases, there are already alternatives available that should be used.

    • hasImageEqualTo

      default boolean hasImageEqualTo(String image)
      Returns true if this node's image is equal to the given string.

      Note: This method will be deprecated in the future (#4787). See getImage().

      Parameters:
      image - The image to check

    • compareLocation

      default int compareLocation(Node other)
      Compare the coordinates of this node with the other one as if with COORDS_COMPARATOR. The result is useless if both nodes are not from the same tree.
      Parameters:
      other - Other node
      Returns:
      A positive integer if this node comes AFTER the other, 0 if they have the same position, a negative integer if this node comes BEFORE the other

    • getReportLocation

      default FileLocation getReportLocation()
      Returns the location at which this element should be reported.

      Use this instead of getBeginColumn()/getBeginLine(), etc. This is not necessarily the exact boundaries of the node in the text. Nodes that can provide exact position information do so using a TextRegion, by implementing TextAvailableNode.

      Use this instead of getBeginColumn()/getBeginLine(), etc.

      Specified by:
      getReportLocation in interface Reportable

    • getTextRegion

      TextRegion getTextRegion()
      Returns a region of text delimiting the node in the underlying text document. This does not necessarily match the report location.

    • getBeginLine

      default int getBeginLine()

    • getBeginColumn

      default int getBeginColumn()

    • getEndLine

      default int getEndLine()

    • getEndColumn

      default int getEndColumn()

    • isFindBoundary

      @NoAttribute default boolean isFindBoundary()
      Returns true if this node is considered a boundary by traversal methods. Traversal methods such as descendants() don't look past such boundaries by default, which is usually the expected thing to do. For example, in Java, lambdas and nested classes are considered find boundaries.
      Returns:
      True if this node is a find boundary
      See Also:

    • getUserMap

      DataMap<DataMap.DataKey<?,?>> getUserMap()
      Returns a data map used to store additional information on this node.
      Returns:
      The user data map of this node
      Since:
      6.22.0

    • getTextDocument

      default @NonNull TextDocument getTextDocument()
      Returns the text document from which this tree was parsed. This means, that the whole file text is in memory while the AST is.
      Returns:
      The text document

    • getParent

      Node getParent()
      Returns the parent of this node, or null if this is the root of the tree.
      Returns:
      The parent of this node
      Since:
      6.21.0

    • getChild

      Node getChild(int index)
      Returns the child of this node at the given index.
      Throws:
      IndexOutOfBoundsException - if the index is negative or greater than getNumChildren().
      Since:
      6.21.0

    • getNumChildren

      int getNumChildren()
      Returns the number of children of this node.
      Since:
      6.21.0

    • getIndexInParent

      int getIndexInParent()
      Returns the index of this node in its parent's children. If this node is a root node, returns -1.
      Returns:
      The index of this node in its parent's children
      Since:
      6.21.0

    • acceptVisitor

      default <P, R> R acceptVisitor(AstVisitor<? super P,? extends R> visitor, P data)
      Calls back the visitor's visit method corresponding to the runtime type of this Node. This should usually be preferred to calling a visit method directly (usually the only calls to those are in the implementations of this acceptVisitor method).
      Implementation Requirements:
      A typical implementation will check the type of the visitor to be that of the language specific visitor, then call the most specific visit method of this Node. This is typically implemented by having a different override per concrete node class (no shortcuts). The default implementation calls back AstVisitor.cannotVisit(Node, Object).
      Type Parameters:
      P - Parameter type of the visitor
      R - Return type of the visitor
      Parameters:
      visitor - Visitor to dispatch
      data - Parameter to the visit
      Returns:
      What the visitor returned. If this node doesn't recognize the type of the visitor, returns visitor.cannotVisit(this, data).
      Since:
      7.0.0

    • getAstInfo

      default AstInfo<? extends RootNode> getAstInfo()
      Returns the AstInfo for this root node.
      Implementation Note:
      This default implementation can not work unless overridden in the root node.

    • getXPathNodeName

      String getXPathNodeName()
      Gets the name of the node that is used to match it with XPath queries.
      Returns:
      The XPath node name

    • getXPathAttributesIterator

      default Iterator<Attribute> getXPathAttributesIterator()
      Returns an iterator enumerating all the attributes that are available from XPath for this node.
      Returns:
      An attribute iterator for this node
      See Also:

    • getFirstChild

      default @Nullable Node getFirstChild()
      Returns the first child of this node, or null if it doesn't exist.
      Since:
      7.0.0

    • getLastChild

      default @Nullable Node getLastChild()
      Returns the first last of this node, or null if it doesn't exist.
      Since:
      7.0.0

    • getPreviousSibling

      default @Nullable Node getPreviousSibling()
      Returns the previous sibling of this node, or null if it does not exist.
      Since:
      7.0.0

    • getNextSibling

      default @Nullable Node getNextSibling()
      Returns the next sibling of this node, or null if it does not exist.
      Since:
      7.0.0

    • asStream

      default NodeStream<? extends Node> asStream()
      Returns a node stream containing only this node. NodeStream.of(Node) is a null-safe version of this method.
      Returns:
      A node stream containing only this node
      Since:
      7.0.0
      See Also:

    • children

      default NodeStream<? extends Node> children()
      Returns a node stream containing all the children of this node. This method does not provide much type safety, you'll probably want to use children(Class).
      Since:
      7.0.0
      See Also:

    • descendants

      default NodeStream.DescendantNodeStream<? extends Node> descendants()
      Returns a node stream containing all the descendants of this node. See NodeStream.DescendantNodeStream for details.
      Returns:
      A node stream of the descendants of this node
      Since:
      7.0.0
      See Also:

    • descendantsOrSelf

      default NodeStream.DescendantNodeStream<? extends Node> descendantsOrSelf()
      Returns a node stream containing this node, then all its descendants. See NodeStream.DescendantNodeStream for details.
      Returns:
      A node stream of the whole subtree topped by this node
      Since:
      7.0.0
      See Also:

    • ancestors

      default NodeStream<? extends Node> ancestors()
      Returns a node stream containing all the strict ancestors of this node, in innermost to outermost order. The returned stream doesn't contain this node, and is empty if this node has no parent.
      Returns:
      A node stream of the ancestors of this node
      Since:
      7.0.0
      See Also:

    • ancestorsOrSelf

      default NodeStream<? extends Node> ancestorsOrSelf()
      Returns a node stream containing this node and its ancestors. The nodes of the returned stream are yielded in a depth-first fashion.
      Returns:
      A stream of ancestors
      Since:
      7.0.0
      See Also:

    • children

      default <R extends Node> NodeStream<R> children(Class<? extends R> rClass)
      Returns a node stream of the children of this node that are of the given type.
      Type Parameters:
      R - Type of node the returned stream should contain
      Parameters:
      rClass - Type of node the returned stream should contain
      Returns:
      A new node stream
      Since:
      7.0.0
      See Also:

    • firstChild

      default <R extends Node> @Nullable R firstChild(Class<? extends R> rClass)
      Returns the first child of this node that has the given type. Returns null if no such child exists.

      If you want to process this element as a node stream, use asStream().firstChild(rClass) instead, which returns a node stream.

      Type Parameters:
      R - Type of the child to find
      Parameters:
      rClass - Type of the child to find
      Returns:
      A child, or null
      Since:
      7.0.0

    • descendants

      default <R extends Node> NodeStream.DescendantNodeStream<R> descendants(Class<? extends R> rClass)
      Returns a node stream of the descendants of this node that are of the given type. See NodeStream.DescendantNodeStream for details.
      Type Parameters:
      R - Type of node the returned stream should contain
      Parameters:
      rClass - Type of node the returned stream should contain
      Returns:
      A new node stream
      Since:
      7.0.0
      See Also:

    • ancestors

      default <R extends Node> NodeStream<R> ancestors(Class<? extends R> rClass)
      Returns the ancestor stream of this node filtered by the given node type.
      Type Parameters:
      R - Type of node the returned stream should contain
      Parameters:
      rClass - Type of node the returned stream should contain
      Returns:
      A new node stream
      Since:
      7.0.0
      See Also:

    • getRoot

      default @NonNull RootNode getRoot()
      Returns the root of the tree this node is declared in.
      Since:
      7.0.0

    • getLanguageVersion

      default LanguageVersion getLanguageVersion()
      Returns the language version of this node.