public interface CtQuery extends CtQueryable
CtQuery represents a query, which can be used to traverse a spoon model and collect children elements in several ways.
Creation: A query is created either from a CtElement
, or it can be defined first from Factory.createQuery()
and bound to root elements
afterwards using setInput(Object...)
.
Chaining: In a query several steps can be chained, by chaining calls to map functions. The non-null outputs of one step are given as input to the next step. An iterable or array output is considered as a set of different inputs for the next step.
Evaluation: A CtQuery is lazily evaluated once list()
or forEach(CtConsumer)
are called.
Modifier and Type | Method and Description |
---|---|
CtQuery |
failurePolicy(QueryFailurePolicy policy)
Defines whether this query will throw
ClassCastException
when the output of the previous step cannot be cast to type of input of next step. |
<R extends CtElement> |
filterChildren(Filter<R> filter)
Recursively scans all children elements of an input element.
|
<R> R |
first()
Actually evaluates the query and returns first elements produced in the last step.
After the first element is found, the query evaluation is terminated. |
<R> R |
first(java.lang.Class<R> itemClass)
Same as
first() , but with static typing on the return type
and the final filtering, which matches only the first result, which is assignable from that return type. |
<R> void |
forEach(CtConsumer<R> consumer)
Actually evaluates the query and for each produced output element of the last step,
calls `consumer.accept(outputElement)`.
|
boolean |
isTerminated() |
<R> java.util.List<R> |
list()
Actually evaluates the query and returns all the elements produced in the last step.
Note: The type R of the list is not checked by the query. |
<R> java.util.List<R> |
list(java.lang.Class<R> itemClass)
Same as
list() , but with static typing on the return type
and the final filtering, which matches only results, which are assignable from that return type. |
<I> CtQuery |
map(CtConsumableFunction<I> queryStep)
Same as
map(CtFunction) , but the returned object is not handled
by java's return statement, but by a call to CtConsumer.accept(Object) , this
allows efficient and easy to write chained processing, see CtConsumableFunction . |
<I,R> CtQuery |
map(CtFunction<I,R> function)
Query elements based on a function, the behavior depends on the return type of the function.
|
CtQuery |
name(java.lang.String name)
Sets the name of current query, to identify the current step during debugging of a query
|
<R extends CtElement> |
select(Filter<R> filter)
The matched element for which (filter.matches(element)==true) is sent to the next query step.
|
<T extends CtQuery> |
setInput(java.lang.Object... input)
Sets (binds) the input of the query.
|
void |
terminate()
Terminates the evaluation of this query.
|
<R extends CtElement> CtQuery filterChildren(Filter<R> filter)
CtElement.getElements(Filter)
but more powerful, because it
can be chained with other subsequent queries.
Note: the input element (the root of the query, `this` if you're in CtElement
) is also checked and may thus be also sent to the next step.
The elements which throw ClassCastException
during Filter.matches(CtElement)
are considered as **not matching**, ie. are excluded.filterChildren
in interface CtQueryable
filter
- used to filter scanned children elements of the AST tree.
If null then all children elements pass to next step.filterChildren(Filter)
<R extends CtElement> CtQuery select(Filter<R> filter)
ClassCastException
during Filter.matches(CtElement)
are considered as **not matching**, ie. are excluded.filter
- used to detect if input element can pass to next query step<I,R> CtQuery map(CtFunction<I,R> function)
Return type of `function` | Behavior |
Boolean | Select elements if the returned value of `function` is true (as for Filter ). |
? extends Object | Send the returned value of `function` to the next step |
Iterable | Send each item of the collection to the next step |
Object [] | Send each item of the array to the next step |
map
in interface CtQueryable
function
- a Function with one parameter of type I returning a value of type Rmap(CtFunction)
<T extends CtQuery> T setInput(java.lang.Object... input)
CtQueryable.map(spoon.reflect.visitor.chain.CtFunction<I, R>)
or CtQueryable.filterChildren(Filter)
,
then the query is already bound to this element.
A new call of setInput(Object...)
is always possible, it resets the current binding and sets the new one.input
- <R> void forEach(CtConsumer<R> consumer)
consumer
- The consumer which accepts the results of the query<R> java.util.List<R> list()
for an efficient way of manipulating the elements without creating an intermediate list.
<R> java.util.List<R> list(java.lang.Class<R> itemClass)
list()
, but with static typing on the return type
and the final filtering, which matches only results, which are assignable from that return type.<R> R first()
<R> R first(java.lang.Class<R> itemClass)
first()
, but with static typing on the return type
and the final filtering, which matches only the first result, which is assignable from that return type.CtQuery failurePolicy(QueryFailurePolicy policy)
ClassCastException
when the output of the previous step cannot be cast to type of input of next step.
The default value is QueryFailurePolicy.FAIL
, which means than exception is thrown when there is a mismatchCtQueryable.filterChildren(Filter)
step never throws ClassCastException
policy
- the policyCtQuery name(java.lang.String name)
name
- <I> CtQuery map(CtConsumableFunction<I> queryStep)
map(CtFunction)
, but the returned object is not handled
by java's return statement, but by a call to CtConsumer.accept(Object)
, this
allows efficient and easy to write chained processing, see CtConsumableFunction
.map
in interface CtQueryable
queryStep
- map(CtConsumableFunction)
void terminate()
boolean isTerminated()
Copyright © 2007–2021 Inria. All rights reserved.