nvim_runtime_lua

vim.treesitter.Query

Parsed query, see |vim.treesitter.query.parse()|

Methods3 

function Query._process_patterns() -> nil

Splits the query patterns into predicates and directives.

function Query.iter_captures(node: TSNode, source: string | integer, start_row: nil | integer, end_row: nil | integer, opts: nil | table) -> fun(end_line: nil | integer, end_col: nil | integer) -> ...integer

Iterates over all captures from all matches in {node}.

{source} is required if the query contains predicates; then the caller must ensure to use a freshly parsed tree consistent with the current text of the buffer (if relevant). {start} and {stop} can be used to limit matches inside a row range (this is typically used with root node as the {node}, i.e., to get syntax highlight matches in the current viewport). When omitted, the {start} and {stop} row values are used from the given node.

The iterator returns four values:

  1. the numeric id identifying the capture
  2. the captured node
  3. metadata from any directives processing the match
  4. the match itself

Example: how to get captures by name:

for id, node, metadata, match in query:iter_captures(tree:root(), bufnr, first, last) do
  local name = query.captures[id] -- name of the capture in the query
  -- typically useful info about the node:
  local type = node:type() -- type of the captured node
  local row1, col1, row2, col2 = node:range() -- range of the capture
  -- ... use the info here ...
end
Parameters
nodeTSNode

under which the search will occur

sourcestring | integer

Source buffer or string to extract text from

start_rownil | integer

Starting line for the search. Defaults to node:start().

end_rownil | integer

Stopping line for the search (end-inclusive, unless stop_col is provided). Defaults to node:end_().

optsnil | table

Optional keyword arguments:

  • end_col (integer) Stopping column for the search (end-exclusive).
  • match_limit (integer) Set the maximum number of in-progress matches (Default: none).
  • maxstartdepth (integer) if non-zero, sets the maximum start depth

    • for each match. This is used to prevent traversing too deep into a tree.

  • start_col (integer) Starting column for the search.
Returns
fun(end_line: nil | integer, end_col: nil | integer) -> ...integer

: capture-id, capture-node, metadata, match, tree

@note Captures are only returned if the query pattern of a specific capture contained predicates.

function Query.iter_matches(node: TSNode, source: string | integer, start: nil | integer, stop: nil | integer, opts: nil | table) -> fun() -> ...integer

Iterates the matches of self on a given range.

Iterate over all matches within a {node}. The arguments are the same as for |Query:iter_captures()| but the iterated values are different: an (1-based) index of the pattern in the query, a table mapping capture indices to a list of nodes, and metadata from any directives processing the match.

Example:

for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, 0, -1) do
  for id, nodes in pairs(match) do
    local name = query.captures[id]
    for _, node in ipairs(nodes) do
      -- `node` was captured by the `name` capture in the match

      local node_data = metadata[id] -- Node level metadata
      -- ... use the info here ...
    end
  end
end
Parameters
nodeTSNode

under which the search will occur

sourcestring | integer

Source buffer or string to search

startnil | integer

Starting line for the search. Defaults to node:start().

stopnil | integer

Stopping line for the search (end-exclusive). Defaults to node:end_().

optsnil | table

Optional keyword arguments:

  • match_limit (integer) Set the maximum number of in-progress matches (Default: none).
  • maxstartdepth (integer) if non-zero, sets the maximum start depth

    • for each match. This is used to prevent traversing too deep into a tree.

Returns
fun() -> ...integer

: pattern-id, match, metadata, tree

Fields7

Query.lang : string

parser language name

Query.captures : string[]

list of (unique) capture names defined in query

Query.info : vim.treesitter.QueryInfo

query context (e.g. captures, predicates, directives)

Query.has_conceal_line : boolean

whether the query sets conceal_lines metadata

Query.has_combined_injections : boolean

whether the query contains combined injections

Query.query : TSQuery

userdata query object

Query.__index : vim.treesitter.Query