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:

  • 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