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

  • 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:

    • close

      public void close() throws RuntimeException
      Specified by:
      close in interface AutoCloseable
      Throws:
      RuntimeException