AstQuery (Groovy 6.0.0-alpha-2)

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

Summary:
Method

| Detail:
Method

[Java] Class AstQuery<T extends ASTNode>

Traversal and pruning

Notes

Methods Summary

Inherited Methods Summary

Method Detail

public AstQuery<T> andSelf()

public boolean any()

public long count()

public AstQuery<ASTNode> descendants()

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

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

public Optional<T> findFirst()

public T first()

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

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

public static AstQuery<ASTNode> from(ASTNode root)

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

public List<T> list()

public boolean none()

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

public Stream<T> stream()

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

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

[Java] Class AstQuery<T extends ASTNode>

Traversal and pruning

Notes

Methods Summary

Inherited Methods Summary

Method Detail

public AstQuery<T> andSelf()

public boolean any()

public long count()

public AstQuery<ASTNode> descendants()

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

@SafeVarargspublic final AstQuery<ASTNode> descendants(Class<? extends ASTNode> types)

public Optional<T> findFirst()

public T first()

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

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

public static AstQuery<ASTNode> from(ASTNode root)

@SafeVarargspublic final AstQuery<T> into(Class<? extends ASTNode> types)

public List<T> list()

public boolean none()

@SafeVarargspublic final AstQuery<T> notInto(Class<? extends ASTNode> boundary)

public Stream<T> stream()

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

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

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

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

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