Home Explore Blog CI



neovim

20th chunk of `runtime/doc/treesitter.txt`
a686595ec7a4f75e7470ce0c8b1a2a2d9e5556abd37b3fc80000000100000fbc
 local tree = vim.treesitter.get_parser():parse()[1]
        for id, node, metadata in query:iter_captures(tree:root(), 0) do
           -- Print the node name and source text.
           vim.print({node:type(), vim.treesitter.get_node_text(node, vim.api.nvim_get_current_buf())})
        end
<

    Parameters: ~
      • {lang}   (`string`) Language to use for the query
      • {query}  (`string`) Query text, in s-expr syntax

    Return: ~
        (`vim.treesitter.Query`) Parsed query . See |vim.treesitter.Query|.

    See also: ~
      • |vim.treesitter.query.get()|

                                                       *Query:iter_captures()*
Query:iter_captures({node}, {source}, {start}, {stop}, {opts})
    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: >lua
        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
<

    Note: ~
      • Captures are only returned if the query pattern of a specific capture
        contained predicates.

    Parameters: ~
      • {node}    (`TSNode`) under which the search will occur
      • {source}  (`integer|string`) Source buffer or string to extract text
                  from
      • {start}   (`integer?`) Starting line for the search. Defaults to
                  `node:start()`.
      • {stop}    (`integer?`) Stopping line for the search (end-exclusive).
                  Defaults to `node:end_()`.
      • {opts}    (`table?`) Optional keyword arguments:
                  • max_start_depth (integer) if non-zero, sets the maximum
                    start depth for each match. This is used to prevent
                    traversing too deep into a tree.
                  • match_limit (integer) Set the maximum number of
                    in-progress matches (Default: 256).

    Return: ~
        (`fun(end_line: integer?): integer, TSNode, vim.treesitter.query.TSMetadata, TSQueryMatch, TSTree`)
        capture id, capture node, metadata, match, tree

                                                        *Query:iter_matches()*
Query:iter_matches({node}, {source}, {start}, {stop}, {opts})
    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: >lua
        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: ~
      • {node}

Title: Query:iter_captures() and Query:iter_matches() - Iterating over captures and matches in a tree
Summary
This section describes the `Query:iter_captures()` and `Query:iter_matches()` functions, which are used to iterate over captures and matches within a given node in a syntax tree. It explains their parameters, return values, and provides examples of how to use them to extract information from the tree, including capture names, node types, and ranges.