Package: org.codehaus.groovy.ast.query

## [Java] Class AstQuery<T extends ASTNode>

- org.codehaus.groovy.ast.query.AstQuery

-     public final class AstQuery<T extends ASTNode>
      extends Object

  A small, read-only, fluent query API over a Groovy AST subtree.

  An `AstQuery` selects descendant nodes of a root, optionally filtered by type and by an arbitrary predicate, and exposes terminal operations that collect or test the matches. It is a declarative alternative to hand-writing a ClassCodeVisitorSupport subclass for the common "find / collect / detect" cases.

       import org.codehaus.groovy.ast.query.AstQuery
       import org.codehaus.groovy.ast.expr.MethodCallExpression
       import org.codehaus.groovy.ast.builder.AstBuilder

       def code = new AstBuilder().buildFromString('foo(); bar()')[0]
       assert AstQuery.from(code).descendants(MethodCallExpression).count() == 2

  ## Traversal and pruning

  By default the traversal descends through closures but does not descend into nested classes, mirroring ClassCodeVisitorSupport. Use notInto(Class[]) to stop descending at a boundary type (for example `ClosureExpression`) and into(Class[]) to opt back in past a default boundary. Nested classes are currently the only default boundary, so `into(ClassNode.class)` is the only case in which into(Class[]) has an effect.

  ## Notes

  - The query is read-only; it never mutates the AST.
  - Matches are produced in document (pre-)order.
  - Instances are immutable and re-runnable: each builder method returns a new query and each terminal performs a fresh traversal, short-circuiting where it can (for example any() and findFirst()).
  Type Parameters:
    `T` - the node type produced by this query
  Since:
    6.0.0

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public AstQuery<T>` | `andSelf()` Includes the root node itself as a candidate (it is excluded by default).
    `` | `public boolean` | `any()` Returns: `true` if at least one node matches; stops at the first match
    `` | `public long` | `count()` Returns: the number of matching nodes
    `` | `public AstQuery<ASTNode>` | `descendants()` Selects all descendant nodes regardless of type.
    `<U extends ASTNode>` | `public AstQuery<U>` | `descendants(Class<U> type)` Selects descendant nodes that are instances of the given type.
    `` | `public final AstQuery<ASTNode>` | `descendants(Class<? extends ASTNode> types)` Selects descendant nodes that are instances of any of the given types.
    `` | `public Optional<T>` | `findFirst()` Returns: the first match in document order, if any; stops at the first match
    `` | `public T` | `first()` Returns: the first match in document order, or `null`; stops at the first match
    `` | `public void` | `forEach(Consumer<? super T> action)` Performs the given action for each match in document order.
    `` | `public void` | `forEach(BiConsumer<? super T, AstContext> action)` Performs the given action, with enclosing context, for each match in document order.
    `` | `public static AstQuery<ASTNode>` | `from(ASTNode root)` Starts a query rooted at the given node.
    `` | `public final AstQuery<T>` | `into(Class<? extends ASTNode> types)` Opts the traversal in to descending past a default boundary.
    `` | `public List<T>` | `list()` Collects all matches in document order.
    `` | `public boolean` | `none()` Returns: `true` if no node matches; stops at the first match
    `` | `public final AstQuery<T>` | `notInto(Class<? extends ASTNode> boundary)` Stops the traversal from descending into the subtrees rooted at nodes of the given types.
    `` | `public Stream<T>` | `stream()` Returns: a sequential Stream of the matches in document order
    `` | `public AstQuery<T>` | `where(Predicate<? super T> p)` Restricts the selection to nodes satisfying the predicate.
    `` | `public AstQuery<T>` | `where(BiPredicate<? super T, AstContext> p)` Restricts the selection to nodes satisfying a predicate that also inspects the enclosing AstContext.

  - ### Inherited Methods Summary

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

- - ### Method Detail

    - #### public AstQuery<T> andSelf()

      Includes the root node itself as a candidate (it is excluded by default).

      Returns:
        a query that also considers the root

    - #### public boolean any()

      Returns:
        `true` if at least one node matches; stops at the first match

    - #### public long count()

      Returns:
        the number of matching nodes

    - #### public AstQuery<ASTNode> descendants()

      Selects all descendant nodes regardless of type.

      Returns:
        a query over every descendant

    - #### <U extends ASTNode> public AstQuery<U> descendants(Class<U> type)

      Selects descendant nodes that are instances of the given type.

      Parameters:
        `type` - the node type to match
      Type Parameters:
        `U` - the node type
      Returns:
        a query over descendants of that type

    - #### @SafeVarargs
      public final AstQuery<ASTNode> descendants(Class<? extends ASTNode> types)

      Selects descendant nodes that are instances of any of the given types.

      Parameters:
        `types` - the node types to match (logical OR)
      Returns:
        a query over descendants matching any type

    - #### public Optional<T> findFirst()

      Returns:
        the first match in document order, if any; stops at the first match

    - #### public T first()

      Returns:
        the first match in document order, or `null`; stops at the first match

    - #### public void forEach(Consumer<? super T> action)

      Performs the given action for each match in document order.

      Parameters:
        `action` - the action

    - #### public void forEach(BiConsumer<? super T, AstContext> action)

      Performs the given action, with enclosing context, for each match in document order.

      Parameters:
        `action` - the action receiving the node and its AstContext

    - #### public static AstQuery<ASTNode> from(ASTNode root)

      Starts a query rooted at the given node.

      Parameters:
        `root` - the subtree root to query; must not be `null`
      Returns:
        a query selecting (by default) all descendants of `root`

    - #### @SafeVarargs
      public final AstQuery<T> into(Class<? extends ASTNode> types)

      Opts the traversal in to descending past a default boundary. Currently the only default boundary is nested classes, so `into(ClassNode.class)` makes the traversal recurse into inner classes.

      Parameters:
        `types` - the boundary types to descend into
      Returns:
        the query with the boundaries opened

    - #### public List<T> list()

      Collects all matches in document order.

      Returns:
        the matching nodes

    - #### public boolean none()

      Returns:
        `true` if no node matches; stops at the first match

    - #### @SafeVarargs
      public final AstQuery<T> notInto(Class<? extends ASTNode> boundary)

      Stops the traversal from descending into the subtrees rooted at nodes of the given types. The boundary nodes themselves are still candidates; only their contents are skipped.

      Parameters:
        `boundary` - the boundary types (for example `ClosureExpression.class`)
      Returns:
        the query with the added boundaries

    - #### public Stream<T> stream()

      Returns:
        a sequential Stream of the matches in document order

    - #### public AstQuery<T> where(Predicate<? super T> p)

      Restricts the selection to nodes satisfying the predicate. Multiple `where` calls are combined with logical AND.

      Parameters:
        `p` - the predicate (a Groovy `Closure` coerces to this functional type)
      Returns:
        the refined query

    - #### public AstQuery<T> where(BiPredicate<? super T, AstContext> p)

      Restricts the selection to nodes satisfying a predicate that also inspects the enclosing AstContext. Combined with logical AND with any other refinements.

      Parameters:
        `p` - the contextual predicate (a two-argument Groovy `Closure` coerces to it)
      Returns:
        the refined query