Package io.github.treesitter.jtreesitter

Class QueryCursor

java.lang.Object

io.github.treesitter.jtreesitter.QueryCursor

All Implemented Interfaces:

AutoCloseable

@NullMarked
public class QueryCursor
extends Object
implements AutoCloseable

A class that can be used to execute a query on a syntax tree.

Since:

0.25.0

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	QueryCursor.Options	A class representing the query cursor options.
static final class	QueryCursor.State	A class representing the current state of the query cursor.

Constructor Summary

Constructors

Constructor	Description
QueryCursor(Query query)	Create a new cursor for the given query.

Method Summary

Modifier and Type	Method	Description
void	close()
boolean	didExceedMatchLimit()	Check if the query exceeded its maximum number of in-progress matches during its last execution.
Stream<AbstractMap.SimpleImmutableEntry<Integer,QueryMatch>>	findCaptures(Node node)	Iterate over all the captures in the order that they were found.
Stream<AbstractMap.SimpleImmutableEntry<Integer,QueryMatch>>	findCaptures(Node node, QueryCursor.Options options)	Iterate over all the captures in the order that they were found.
Stream<AbstractMap.SimpleImmutableEntry<Integer,QueryMatch>>	findCaptures(Node node, SegmentAllocator allocator, QueryCursor.Options options)	Iterate over all the captures in the order that they were found.
Stream<QueryMatch>	findMatches(Node node)	Iterate over all the matches in the order that they were found.
Stream<QueryMatch>	findMatches(Node node, QueryCursor.Options options)	Iterate over all the matches in the order that they were found.
Stream<QueryMatch>	findMatches(Node node, SegmentAllocator allocator, QueryCursor.Options options)	Iterate over all the matches in the order that they were found, using the given allocator.
int	getMatchLimit()	Get the maximum number of in-progress matches.
long	getTimeoutMicros()	Deprecated. Use QueryCursor.Options instead.
QueryCursor	setByteRange(int startByte, int endByte)	Set the range of bytes in which the query will be executed.
QueryCursor	setMatchLimit(int matchLimit)	Get the maximum number of in-progress matches.
QueryCursor	setMaxStartDepth(int maxStartDepth)	Set the maximum start depth for the query.
QueryCursor	setPointRange(Point startPoint, Point endPoint)	Set the range of points in which the query will be executed.
QueryCursor	setTimeoutMicros(long timeoutMicros)	Deprecated. Use QueryCursor.Options instead.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

QueryCursor

public QueryCursor(Query query)

Create a new cursor for the given query.

Method Details

getMatchLimit

@Unsigned
public int getMatchLimit()

Get the maximum number of in-progress matches.

API Note:

Defaults to -1 (unlimited).

setMatchLimit

public QueryCursor setMatchLimit(@Unsigned
 int matchLimit)
                          throws IllegalArgumentException

Get the maximum number of in-progress matches.

Throws:

IllegalArgumentException - If matchLimit == 0.

getTimeoutMicros

@Deprecated(since="0.25.0")
@Unsigned
public long getTimeoutMicros()

Deprecated.

Use QueryCursor.Options instead.

Get the maximum duration in microseconds that query execution should be allowed to take before halting.

API Note:

Defaults to 0 (unlimited).

setTimeoutMicros

@Deprecated(since="0.25.0")
public QueryCursor setTimeoutMicros(@Unsigned
 long timeoutMicros)

Deprecated.

Use QueryCursor.Options instead.

Set the maximum duration in microseconds that query execution should be allowed to take before halting.

setMaxStartDepth

public QueryCursor setMaxStartDepth(@Unsigned
 int maxStartDepth)

Set the maximum start depth for the query.

This prevents cursors from exploring children nodes at a certain depth.
Note that if a pattern includes many children, then they will still be checked.

setByteRange

public QueryCursor setByteRange(@Unsigned
 int startByte,
 @Unsigned
 int endByte)
                         throws IllegalArgumentException

Set the range of bytes in which the query will be executed.

The query cursor will return matches that intersect with the given range. This means that a match may be returned even if some of its captures fall outside the specified range, as long as at least part of the match overlaps with the range.

For example, if a query pattern matches a node that spans a larger area than the specified range, but part of that node intersects with the range, the entire match will be returned.

Throws:

IllegalArgumentException - If `endByte > startByte`.

setPointRange

public QueryCursor setPointRange(Point startPoint,
 Point endPoint)
                          throws IllegalArgumentException

Set the range of points in which the query will be executed.

The query cursor will return matches that intersect with the given range. This means that a match may be returned even if some of its captures fall outside the specified range, as long as at least part of the match overlaps with the range.

For example, if a query pattern matches a node that spans a larger area than the specified range, but part of that node intersects with the range, the entire match will be returned.

Throws:

IllegalArgumentException - If `endPoint > startPoint`.

didExceedMatchLimit

public boolean didExceedMatchLimit()

Check if the query exceeded its maximum number of in-progress matches during its last execution.

findCaptures

public Stream<AbstractMap.SimpleImmutableEntry<Integer,QueryMatch>> findCaptures(Node node)

Iterate over all the captures in the order that they were found.

This is useful if you don't care about which pattern matched, and just want a single, ordered sequence of captures.

Parameters:

node - The node that the query will run on.

Implementation Note:

The lifetime of the matches is bound to that of the cursor.

findCaptures

public Stream<AbstractMap.SimpleImmutableEntry<Integer,QueryMatch>> findCaptures(Node node,
 QueryCursor.Options options)

Iterate over all the captures in the order that they were found.

This is useful if you don't care about which pattern matched, and just want a single, ordered sequence of captures.

Parameters:

node - The node that the query will run on.

Implementation Note:

The lifetime of the matches is bound to that of the cursor.

findCaptures

public Stream<AbstractMap.SimpleImmutableEntry<Integer,QueryMatch>> findCaptures(Node node,
 SegmentAllocator allocator,
 QueryCursor.Options options)

Iterate over all the captures in the order that they were found.

This is useful if you don't care about which pattern matched, and just want a single, ordered sequence of captures.

Parameters:

node - The node that the query will run on.

findMatches

public Stream<QueryMatch> findMatches(Node node)

Iterate over all the matches in the order that they were found.

Because multiple patterns can match the same set of nodes, one match may contain captures that appear before some of the captures from a previous match.

Parameters:

node - The node that the query will run on.

Implementation Note:

The lifetime of the matches is bound to that of the cursor.

findMatches

public Stream<QueryMatch> findMatches(Node node,
 QueryCursor.Options options)

Iterate over all the matches in the order that they were found.

Because multiple patterns can match the same set of nodes, one match may contain captures that appear before some of the captures from a previous match.

Predicate Example

 QueryCursor.Options options = new QueryCursor.Options((predicate, match) -> {
     if (!predicate.getName().equals("ieq?")) return true;
     List<QueryPredicateArg> args = predicate.getArgs();
     Node node = match.findNodes(args.getFirst().value()).getFirst();
     return args.getLast().value().equalsIgnoreCase(node.getText());
 });
 Stream<QueryMatch> matches = self.findMatches(tree.getRootNode(), options);

Parameters:

node - The node that the query will run on.

Implementation Note:

The lifetime of the matches is bound to that of the cursor.

findMatches

public Stream<QueryMatch> findMatches(Node node,
 SegmentAllocator allocator,
 QueryCursor.Options options)

Iterate over all the matches in the order that they were found, using the given allocator.

Because multiple patterns can match the same set of nodes, one match may contain captures that appear before some of the captures from a previous match.

Parameters:

node - The node that the query will run on.

See Also:

• findMatches(Node, Options)

close

public void close()
           throws RuntimeException

Specified by:

close in interface AutoCloseable

Throws:

RuntimeException