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

Constructor Summary

Constructors

Constructor	Description
Query(Language language, String source)	Create a new query from a string containing one or more S-expression patterns.

Method Summary

Modifier and Type	Method	Description
void	close()
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.
int	getCaptureCount()	Deprecated. Use getCaptureNames().size() instead.
List<String>	getCaptureNames()	Get the names of the captures used in the query.
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.
List<String>	getStringValues()	Get the string literals used in the query.
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.
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

Constructor Details

Query

public Query(Language language,
 String source)
      throws QueryError

Create a new query from a string containing one or more S-expression patterns.

Throws:

QueryError - If an error occurred while creating the query.

Method Details

getPatternCount

@Unsigned
public int getPatternCount()

Get the number of patterns in the query.

getCaptureCount

@Deprecated(since="0.25.0")
@Unsigned
public int getCaptureCount()

Deprecated.

Use getCaptureNames().size() instead.

Get the number of captures in the query.

getCaptureNames

public List<String> getCaptureNames()

Get the names of the captures used in the query.

Since:

0.25.0

getStringValues

public List<String> getStringValues()

Get the string literals used in the query.

Since:

0.25.0

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! directive.

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.

close

public void close()
           throws RuntimeException

Specified by:

close in interface AutoCloseable

Throws:

RuntimeException

toString

public String toString()

Overrides:

toString in class Object