NAME

Text::Treesitter::QueryCursor - stores the result of a tree-sitter node query

SYNOPSIS

   use Text::Treesitter;
   use Text::Treesitter::QueryCursor;

   my $ts = Text::Treesitter->new(
      lang_name => "perl",
   );

   my $query = $ts->load_query_string( "path/to/query.scm" );

   my $tree = $ts->parse_string( $input );

   my $qc = Text::Treesitter::_QueryCursor->new;

   $qc->exec( $query, $tree->root_node );

   ...

DESCRIPTION

Instances of this class store the result of performing a query pattern match operation against the node tree of a parse result. Once executed it will contain the matched patterns and captured nodes, which can then be queried.

CONSTRUCTOR

new

   $qc = Text::Treesitter::QueryCursor->new;

Returns a new blank instance.

METHODS

exec

   $qc->exec( $query, $node );

Performs the query pattern-matching operation by attempting to match node subtrees from the given (root) node, against patterns defined by the query.

This method does not return a result; instead the matches are stored within the object itself and can be iterated using "next_match".

next_match

   $match = $qc->next_match;

Returns the next stored match from the most recent "exec" operation, or undef if there are no more matches. The match is returned as an instance of Text::Treesitter::QueryMatch.

next_match_captures

   $captures = $qc->next_match_captures( %options );

Since version 0.10.

A convenience wrapper around "next_match" for applying predicate tests and extracting the nodes corresponding to each capture.

Matches that fail the test_predicates_for_match are skipped. The next match that passes then has its captures extracted into a hash; with keys of the hash being the capture names, and the values containing the nodes.

If the multi option is true then each value of the returned hash will be an array reference containing every node that was captured at that name. If the option is false then it will contain just the final capture (which is normally fine because most patterns do not capture multiple nodes).

Since version 0.12 the returned captures hash may also contain plain-text strings that are the result of #set! directives found in the query.

TODO

The following C library functions are currently unhandled:

   ts_query_cursor_...
   ts_query_cursor_exec
   ts_query_cursor_did_exceed_match_limit
   ts_query_cursor_match_limit
   ts_query_cursor_set_match_limit
   ts_query_cursor_set_byte_range
   ts_query_cursor_set_point_range
   ts_query_cursor_next_match
   ts_query_cursor_remove_match
   ts_query_cursor_next_capture

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>