Package io.github.treesitter.jtreesitter

Class Query

java.lang.Object

io.github.treesitter.jtreesitter.Query

All Implemented Interfaces:

AutoCloseable

@NullMarked
public final class Query
extends Object
implements AutoCloseable

A class that represents a set of patterns which match nodes in a syntax tree.

See Also:

• Query Syntax

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.
void	disableCapture(String name)	Disable a certain capture within a query.
void	disablePattern(int index)	Disable a certain pattern within a query.
int	endByteForPattern(int index)	Get the byte offset where the given pattern ends in the query's source.
Stream<QueryMatch>	findMatches(Node node)	Iterate over all the matches in the order that they were found.
Stream<QueryMatch>	findMatches(Node node, @Nullable BiPredicate<QueryPredicate,QueryMatch> predicate)	Iterate over all the matches in the order that they were found.
int	getCaptureCount()	Get the number of captures in the query.
int	getMatchLimit()	Get the maximum number of in-progress matches.
Map<String,Optional<String>>	getPatternAssertions(int index, boolean positive)	Get the property assertions for the given pattern index.
int	getPatternCount()	Get the number of patterns in the query.
Map<String,Optional<String>>	getPatternSettings(int index)	Get the property settings for the given pattern index.
long	getTimeoutMicros()	Get the maximum duration in microseconds that query execution should be allowed to take before halting.
boolean	isPatternGuaranteedAtStep(int offset)	Check if a pattern is guaranteed to match once a given byte offset is reached.
boolean	isPatternNonLocal(int index)	Check if the pattern with the given index is "non-local".
boolean	isPatternRooted(int index)	Check if the pattern with the given index has a single root node.
Query	setByteRange(int startByte, int endByte)	Set the range of bytes in which the query will be executed.
Query	setMatchLimit(int matchLimit)	Get the maximum number of in-progress matches.
Query	setMaxStartDepth(int maxStartDepth)	Set the maximum start depth for the query.
Query	setPointRange(Point startPoint, Point endPoint)	Set the range of points in which the query will be executed.
Query	setTimeoutMicros(long timeoutMicros)	Set the maximum duration in microseconds that query execution should be allowed to take before halting.
int	startByteForPattern(int index)	Get the byte offset where the given pattern starts in the query's source.
String	toString()

Methods inherited from class java.lang.Object

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

Method Details

getPatternCount

@Unsigned
public int getPatternCount()

Get the number of patterns in the query.

getCaptureCount

@Unsigned
public int getCaptureCount()

Get the number of captures in the query.

getMatchLimit

@Unsigned
public int getMatchLimit()

Get the maximum number of in-progress matches.

API Note:

Defaults to -1 (unlimited).

setMatchLimit

public Query setMatchLimit(@Unsigned
 int matchLimit)
                    throws IllegalArgumentException

Get the maximum number of in-progress matches.

Throws:

IllegalArgumentException - If matchLimit == 0.

getTimeoutMicros

@Unsigned
public long getTimeoutMicros()

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

Since:

0.23.1

API Note:

Defaults to 0 (unlimited).

setTimeoutMicros

public Query setTimeoutMicros(@Unsigned
 long timeoutMicros)

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

Since:

0.23.1

setMaxStartDepth

public Query 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 Query setByteRange(@Unsigned
 int startByte,
 @Unsigned
 int endByte)

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

setPointRange

public Query setPointRange(Point startPoint,
 Point endPoint)

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

didExceedMatchLimit

public boolean didExceedMatchLimit()

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

disablePattern

public void disablePattern(@Unsigned
 int index)
                    throws IndexOutOfBoundsException

Disable a certain pattern within a query.

Throws:

IndexOutOfBoundsException - If the index exceeds the pattern count.

API Note:

This prevents the pattern from matching and removes most of the overhead associated with the pattern. Currently, there is no way to undo this.

disableCapture

public void disableCapture(String name)
                    throws NoSuchElementException

Disable a certain capture within a query.

Throws:

NoSuchElementException - If the capture does not exist.

API Note:

This prevents the capture from being returned in matches, and also avoids most resource usage associated with recording the capture. Currently, there is no way to undo this.

startByteForPattern

@Unsigned
public int startByteForPattern(@Unsigned
 int index)
                        throws IndexOutOfBoundsException

Get the byte offset where the given pattern starts in the query's source.

Throws:

IndexOutOfBoundsException - If the index exceeds the pattern count.

endByteForPattern

@Unsigned
public int endByteForPattern(@Unsigned
 int index)
                      throws IndexOutOfBoundsException

Get the byte offset where the given pattern ends in the query's source.

Throws:

IndexOutOfBoundsException - If the index exceeds the pattern count.

Since:

0.23.0

isPatternRooted

public boolean isPatternRooted(@Unsigned
 int index)
                        throws IndexOutOfBoundsException

Check if the pattern with the given index has a single root node.

Throws:

IndexOutOfBoundsException - If the index exceeds the pattern count.

isPatternNonLocal

public boolean isPatternNonLocal(@Unsigned
 int index)
                          throws IndexOutOfBoundsException

Check if the pattern with the given index is "non-local".

A non-local pattern has multiple root nodes and can match within a repeating sequence of nodes, as specified by the grammar. Non-local patterns disable certain optimizations that would otherwise be possible when executing a query on a specific range of a syntax tree.

Throws:

IndexOutOfBoundsException - If the index exceeds the pattern count.

isPatternGuaranteedAtStep

public boolean isPatternGuaranteedAtStep(@Unsigned
 int offset)
                                  throws IndexOutOfBoundsException

Check if a pattern is guaranteed to match once a given byte offset is reached.

Throws:

IndexOutOfBoundsException - If the offset exceeds the source length.

getPatternSettings

public Map<String,Optional<String>> getPatternSettings(@Unsigned
 int index)
                                                throws IndexOutOfBoundsException

Get the property settings for the given pattern index.

Properties are set using the #set! predicate.

Parameters:

index - The index of a pattern within the query.

Returns:

A map of property keys with optional values.

Throws:

IndexOutOfBoundsException - If the index exceeds the pattern count.

getPatternAssertions

public Map<String,Optional<String>> getPatternAssertions(@Unsigned
 int index,
 boolean positive)
                                                  throws IndexOutOfBoundsException

Get the property assertions for the given pattern index.

Assertions are performed using the #is? (positive) and #is-not? (negative) predicates.

Parameters:

index - The index of a pattern within the query.

positive - Indicates whether to include positive or negative assertions.

Returns:

A map of property keys with optional values.

Throws:

IndexOutOfBoundsException - If the index exceeds the pattern count.

findMatches

public Stream<QueryMatch> findMatches(Node node)

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

Parameters:

node - The node that the query will run on.

findMatches

public Stream<QueryMatch> findMatches(Node node,
 @Nullable BiPredicate<QueryPredicate,QueryMatch> predicate)

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

Predicate Example

Stream<QueryMatch> matches = query.findMatches(tree.getRootNode(), (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());
 });

Parameters:

node - The node that the query will run on.

predicate - A function that handles custom predicates.

close

public void close()
           throws RuntimeException

Specified by:

close in interface AutoCloseable

Throws:

RuntimeException

toString

public String toString()

Overrides:

toString in class Object