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.

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

    • setContainingByteRange

      public QueryCursor setContainingByteRange(@Unsigned int startByte, @Unsigned int endByte) throws IllegalArgumentException
      Set the byte range within which all matches must be fully contained.

      In contrast to setByteRange(int, int), this will restrict the query cursor to only return matches where all nodes are fully contained within the given range. Both functions can be used together, e.g. to search for any matches that intersect line 5000, as long as they are fully contained within lines 4500-5500.

      Throws:
      IllegalArgumentException - If endByte > startByte.
      Since:
      0.26.0

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

    • setContainingPointRange

      public QueryCursor setContainingPointRange(Point startPoint, Point endPoint) throws IllegalArgumentException
      Set the point range within which all matches must be fully contained.

      In contrast to setPointRange(Point, Point), this will restrict the query cursor to only return matches where all nodes are fully contained within the given range. Both functions can be used together, e.g. to search for any matches that intersect line 5000, as long as they are fully contained within lines 4500-5500.

      Throws:
      IllegalArgumentException - If endPoint > startPoint.
      Since:
      0.26.0

    • 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.
      options - The options of the query cursor.
      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, @Nullable 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.
      options - The options of the query cursor.

    • 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.
      options - The options of the query cursor.
      Implementation Note:
      The lifetime of the matches is bound to that of the cursor.

    • findMatches

      public Stream<QueryMatch> findMatches(Node node, SegmentAllocator allocator, @Nullable 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.
      options - The options of the query cursor.
      See Also:

    • close

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