Package io.github.treesitter.jtreesitter
Class Query
java.lang.Object
io.github.treesitter.jtreesitter.Query
- All Implemented Interfaces:
AutoCloseable
A class that represents a set of patterns which match
nodes in a syntax tree.
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionvoid
close()
boolean
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.findMatches
(Node node) Iterate over all the matches in the order that they were found.findMatches
(Node node, @Nullable BiPredicate<QueryPredicate, QueryMatch> predicate) Iterate over all the matches in the order that they were found.int
Get the number of captures in the query.int
Get the maximum number of in-progress matches.getPatternAssertions
(int index, boolean positive) Get the property assertions for the given pattern index.int
Get the number of patterns in the query.getPatternSettings
(int index) Get the property settings for the given pattern index.long
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.setByteRange
(int startByte, int endByte) Set the range of bytes in which the query will be executed.setMatchLimit
(int matchLimit) Get the maximum number of in-progress matches.setMaxStartDepth
(int maxStartDepth) Set the maximum start depth for the query.setPointRange
(Point startPoint, Point endPoint) Set the range of points in which the query will be executed.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.toString()
-
Method Details
-
getPatternCount
Get the number of patterns in the query. -
getCaptureCount
Get the number of captures in the query. -
getMatchLimit
Get the maximum number of in-progress matches.- API Note:
- Defaults to
-1
(unlimited).
-
setMatchLimit
Get the maximum number of in-progress matches.- Throws:
IllegalArgumentException
- IfmatchLimit == 0
.
-
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
-
setMaxStartDepth
-
setByteRange
-
setPointRange
-
didExceedMatchLimit
public boolean didExceedMatchLimit()Check if the query exceeded its maximum number of in-progress matches during its last execution. -
disablePattern
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
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
Get the byte offset where the given pattern starts in the query's source.- Throws:
IndexOutOfBoundsException
- If the index exceeds the pattern count.
-
endByteForPattern
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
Check if the pattern with the given index has a single root node.- Throws:
IndexOutOfBoundsException
- If the index exceeds the pattern count.
-
isPatternNonLocal
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
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
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
- Specified by:
close
in interfaceAutoCloseable
- Throws:
RuntimeException
-
toString
-