Quick links: help overview · quick reference · user manual toc · reference manual toc
Go to keyword (shortcut: k)
Site search (shortcut: s)
treesitter.txt    Nvim


                            NVIM REFERENCE MANUAL


Treesitter integration                                 treesitter

Nvim integrates the tree-sitter library for incremental parsing of buffers:
https://tree-sitter.github.io/tree-sitter/

WARNING: Treesitter support is still experimental and subject to frequent
changes. This documentation may also not fully reflect the latest changes.

                                      Type gO to see the table of contents.

==============================================================================
PARSER FILES                                              treesitter-parsers

Parsers are the heart of treesitter. They are libraries that treesitter will
search for in the parser runtime directory.

Nvim includes these parsers:

- C
- Lua
- Markdown
- Vimscript
- Vimdoc
- Treesitter query files ft-query-plugin

You can install more parsers manually, or with a plugin like
https://github.com/nvim-treesitter/nvim-treesitter .

Parsers are searched for as parser/{lang}.* in any 'runtimepath' directory.
If multiple parsers for the same language are found, the first one is used.
(NOTE: This typically implies the priority "user config > plugins > bundled".)

To load a parser from its filepath: 

    vim.treesitter.language.add('python', { path = "/path/to/python.so" })

Parser names are assumed to be lower case if the file system is
case-sensitive.

To associate certain filetypes with a treesitter language (name of parser),
use vim.treesitter.language.register(). For example, to use the xml
treesitter parser for buffers with filetype svg or xslt, use: 

    vim.treesitter.language.register('xml', { 'svg', 'xslt' })


==============================================================================
TREESITTER TREES                                             treesitter-tree
                                                                      TSTree

A "treesitter tree" represents the parsed contents of a buffer, which can be
used to perform further analysis. It is a userdata reference to an object
held by the treesitter library.

An instance TSTree of a treesitter tree supports the following methods.

TSTree:root()                                           TSTree:root()
    Return the root node of this tree.

TSTree:copy()                                           TSTree:copy()
    Returns a copy of the TSTree.

==============================================================================
TREESITTER NODES                                             treesitter-node
                                                                      TSNode

A "treesitter node" represents one specific element of the parsed contents of
a buffer, which can be captured by a Query for, e.g., highlighting. It is
a userdata reference to an object held by the treesitter library.

An instance TSNode of a treesitter node supports the following methods.

TSNode:parent()                                         TSNode:parent()
    Get the node's immediate parent.

TSNode:next_sibling()                                   TSNode:next_sibling()
    Get the node's next sibling.

TSNode:prev_sibling()                                   TSNode:prev_sibling()
    Get the node's previous sibling.

TSNode:next_named_sibling()                       TSNode:next_named_sibling()
    Get the node's next named sibling.

TSNode:prev_named_sibling()                       TSNode:prev_named_sibling()
    Get the node's previous named sibling.

TSNode:iter_children()                                 TSNode:iter_children()
    Iterates over all the direct children of {TSNode}, regardless of whether
    they are named or not.
    Returns the child node plus the eventual field name corresponding to this
    child node.

TSNode:field({name})                                    TSNode:field()
    Returns a table of the nodes corresponding to the {name} field.

TSNode:child_count()                                    TSNode:child_count()
    Get the node's number of children.

TSNode:child({index})                                   TSNode:child()
    Get the node's child at the given {index}, where zero represents the first
    child.

TSNode:named_child_count()                         TSNode:named_child_count()
    Get the node's number of named children.

TSNode:named_child({index})                              TSNode:named_child()
    Get the node's named child at the given {index}, where zero represents the
    first named child.

TSNode:start()                                          TSNode:start()
    Get the node's start position. Return three values: the row, column and
    total byte count (all zero-based).

TSNode:end_()                                           TSNode:end_()
    Get the node's end position. Return three values: the row, column and
    total byte count (all zero-based).

TSNode:range({include_bytes})                           TSNode:range()
    Get the range of the node.

    Return four or six values:
        - start row
        - start column
        - start byte (if {include_bytes} is true)
        - end row
        - end column
        - end byte (if {include_bytes} is true)

TSNode:type()                                           TSNode:type()
    Get the node's type as a string.

TSNode:symbol()                                         TSNode:symbol()
    Get the node's type as a numerical id.

TSNode:named()                                          TSNode:named()
    Check if the node is named. Named nodes correspond to named rules in the
    grammar, whereas anonymous nodes correspond to string literals in the
    grammar.

TSNode:missing()                                        TSNode:missing()
    Check if the node is missing. Missing nodes are inserted by the parser in
    order to recover from certain kinds of syntax errors.

TSNode:extra()                                          TSNode:extra()
    Check if the node is extra. Extra nodes represent things like comments,
    which are not required by the grammar but can appear anywhere.

TSNode:has_changes()                                    TSNode:has_changes()
    Check if a syntax node has been edited.

TSNode:has_error()                                      TSNode:has_error()
    Check if the node is a syntax error or contains any syntax errors.

TSNode:sexpr()                                          TSNode:sexpr()
    Get an S-expression representing the node as a string.

TSNode:id()                                             TSNode:id()
    Get a unique identifier for the node inside its own tree.

    No guarantees are made about this identifier's internal representation,
    except for being a primitive Lua type with value equality (so not a
    table). Presently it is a (non-printable) string.

    Note: The id is not guaranteed to be unique for nodes from different
    trees.

TSNode:tree()                                           TSNode:tree()
    Get the TSTree of the node.
                                                TSNode:descendant_for_range()
TSNode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
    Get the smallest node within this node that spans the given range of (row,
    column) positions

                                          TSNode:named_descendant_for_range()
TSNode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
    Get the smallest named node within this node that spans the given range of
    (row, column) positions
                                                        TSNode:equal()
TSNode:equal({node})
    Check if {node} refers to the same node within the same tree.

                                                        TSNode:byte_length()
TSNode:byte_length()
    Return the number of bytes spanned by this node.

==============================================================================
TREESITTER QUERIES                                          treesitter-query

Treesitter queries are a way to extract information about a parsed TSTree,
e.g., for the purpose of highlighting. Briefly, a query consists of one or
more patterns. A pattern is defined over node types in the syntax tree. A
match corresponds to specific elements of the syntax tree which match a
pattern. Patterns may optionally define captures and predicates. A capture
allows you to associate names with a specific node in a pattern. A predicate
adds arbitrary metadata and conditional data to a match.

Queries are written in a lisp-like language documented in
https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax
Note: The predicates listed there page differ from those Nvim supports. See
treesitter-predicates for a complete list of predicates supported by Nvim.

Nvim looks for queries as *.scm files in a queries directory under
runtimepath, where each file contains queries for a specific language and
purpose, e.g., queries/lua/highlights.scm for highlighting Lua files.
By default, the first query on runtimepath is used (which usually implies
that user config takes precedence over plugins, which take precedence over
queries bundled with Nvim). If a query should extend other queries instead
of replacing them, use treesitter-query-modeline-extends.

See lua-treesitter-query for the list of available methods for working with
treesitter queries from Lua.


TREESITTER QUERY PREDICATES                            treesitter-predicates

Predicates are special scheme nodes that are evaluated to conditionally capture
nodes. For example, the eq? predicate can be used as follows: >query

    ((identifier) @variable.builtin
      (#eq? @variable.builtin "self"))
<
to only match identifier corresponding to the "self" text. Such queries can
be used to highlight built-in functions or variables differently, for instance.

The following predicates are built in:

    eq?                                            treesitter-predicate-eq?
        Match a string against the text corresponding to a node: >query
            ((identifier) @variable.builtin (#eq? @variable.builtin "self"))
            ((node1) @left (node2) @right (#eq? @left @right))
<
    any-eq?                                    treesitter-predicate-any-eq?
        Like eq?, but for quantified patterns only one captured node must
        match.

    match?                                      treesitter-predicate-match?
    vim-match?                              treesitter-predicate-vim-match?
         Match a regexp against the text corresponding to a node: >query
            ((identifier) @constant (#match? @constant "^[A-Z_]+$"))
<
         Note: The ^ and $ anchors will match the start and end of the
               node's text.

    any-match?                              treesitter-predicate-any-match?
    any-vim-match?                      treesitter-predicate-any-vim-match?
        Like match?, but for quantified patterns only one captured node must
        match.

    lua-match?                              treesitter-predicate-lua-match?
         Match lua-patterns against the text corresponding to a node,
         similar to match?

    any-lua-match?                      treesitter-predicate-any-lua-match?
         Like lua-match?, but for quantified patterns only one captured node
         must match.

    contains?                                treesitter-predicate-contains?
        Match a string against parts of the text corresponding to a node: >query
            ((identifier) @foo (#contains? @foo "foo"))
            ((identifier) @foo-bar (#contains? @foo-bar "foo" "bar"))
<
    any-contains?                        treesitter-predicate-any-contains?
        Like contains?, but for quantified patterns only one captured node
        must match.

    any-of?                                    treesitter-predicate-any-of?
        Match any of the given strings against the text corresponding to
        a node: >query
            ((identifier) @foo (#any-of? @foo "foo" "bar"))
<
        This is the recommended way to check if the node matches one of many
        keywords, as it has been optimized for this.

    has-ancestor?                        treesitter-predicate-has-ancestor?
        Match any of the given node types against all ancestors of a node: >query
            ((identifier) @variable.builtin
              (#any-of? @variable.builtin "begin" "end")
              (#has-ancestor? @variable.builtin range_expression))
<
    has-parent?                            treesitter-predicate-has-parent?
        Match any of the given node types against the direct ancestor of a
        node: >query
            (((field_expression
                 (field_identifier) @method)) @_parent
             (#has-parent? @_parent template_method function_declarator))
<
                                                 lua-treesitter-not-predicate
Each predicate has a not- prefixed predicate that is just the negation of
the predicate.

                                                 lua-treesitter-all-predicate
                                                 lua-treesitter-any-predicate
Queries can use quantifiers to capture multiple nodes. When a capture contains
multiple nodes, predicates match only if ALL nodes contained by the capture
match the predicate. Some predicates (`eq?`, match?, lua-match?,
contains?) accept an any- prefix to instead match if ANY of the nodes
contained by the capture match the predicate.

As an example, consider the following Lua code: 

  -- TODO: This is a
  -- very long
  -- comment (just imagine it)

using the following predicated query:
>query
    (((comment)+ @comment)
     (#match? @comment "TODO"))
<
This query will not match because not all of the nodes captured by @comment
match the predicate. Instead, use:
>query
    (((comment)+ @comment)
     (#any-match? @comment "TODO"))
<

Further predicates can be added via vim.treesitter.query.add_predicate().
Use vim.treesitter.query.list_predicates() to list all available predicates.


TREESITTER QUERY DIRECTIVES                            treesitter-directives

Treesitter directives store metadata for a node or match and perform side
effects. For example, the set! directive sets metadata on the match or node: >query

        ((identifier) @foo (#set! "type" "parameter"))
<
The following directives are built in:

    set!                                          treesitter-directive-set!
        Sets key/value metadata for a specific match or capture. Value is
        accessible as either metadata[key] (match specific) or
        metadata[capture_id][key] (capture specific).

        Parameters: 
            {capture_id} (optional)
            {key}
            {value}

        Examples: >query
            ((identifier) @foo (#set! @foo "kind" "parameter"))
            ((node1) @left (node2) @right (#set! "type" "pair"))
            ((codeblock) @markup.raw.block (#set! "priority" 90))
<
    offset!                                      treesitter-directive-offset!
        Takes the range of the captured node and applies an offset. This will
        set a new Range4 object for the captured node with capture_id as
        metadata[capture_id].range. Useful for treesitter-language-injections.

        Parameters: 
            {capture_id}
            {start_row}
            {start_col}
            {end_row}
            {end_col}

        Example: >query
            ((identifier) @constant (#offset! @constant 0 1 0 -1))
<
    gsub!                                          treesitter-directive-gsub!
        Transforms the content of the node using a lua-pattern. This will set
        a new metadata[capture_id].text.

        Parameters: 
            {capture_id}
            {pattern}
            {replacement}

        Example: >query
            (#gsub! @_node ".*%.(.*)" "%1")
<
    trim!                                          treesitter-directive-trim!
        Trim blank lines from the end of the node. This will set a new
        metadata[capture_id].range.

        Parameters: 
            {capture_id}

        Example: >query
            (#trim! @fold)
<
Further directives can be added via vim.treesitter.query.add_directive().
Use vim.treesitter.query.list_directives() to list all available directives.


TREESITTER QUERY MODELINES                          treesitter-query-modeline

Nvim supports to customize the behavior of the queries using a set of
"modelines", that is comments in the queries starting with ;. Here are the
currently supported modeline alternatives:

    `inherits: {lang}...`                     treesitter-query-modeline-inherits
        Specifies that this query should inherit the queries from {lang}.
        This will recursively descend in the queries of {lang} unless wrapped
        in parentheses: ({lang}).
        Note: This is meant to be used to include queries from another
        language. If you want your query to extend the queries of the same
        language, use extends.

    extends                                  treesitter-query-modeline-extends
        Specifies that this query should be used as an extension for the
        query, i.e. that it should be merged with the others.
        Note: The order of the extensions, and the query that will be used as
        a base depends on your 'runtimepath' value.

Note: These modeline comments must be at the top of the query, but can be
repeated, for example, the following two modeline blocks are both valid:
>query
    ;; inherits: typescript,jsx
    ;; extends
<
>query
    ;; extends
    ;;
    ;; inherits: css
<
==============================================================================
TREESITTER SYNTAX HIGHLIGHTING                          treesitter-highlight

Syntax highlighting is specified through queries named highlights.scm,
which match a TSNode in the parsed TSTree to a capture that can be
assigned a highlight group. For example, the query >query

    (parameters (identifier) @variable.parameter)
<
matches any identifier node inside a function parameters node to the
capture named @variable.parameter. For example, for a Lua code 

    function f(foo, bar) end

which will be parsed as (see :InspectTree): >query

    (function_declaration ; [1:1 - 24]
      name: (identifier) ; [1:10 - 10]
      parameters: (parameters ; [1:11 - 20]
        name: (identifier) ; [1:12 - 14]
        name: (identifier))) ; [1:17 - 19]
<
the above query will highlight foo and bar as @variable.parameter.

It is also possible to match literal expressions (provided the parser returns
them):
>query
    [
      "if"
      "else"
    ] @keyword.conditional
<
Assuming a suitable parser and highlights.scm query is found in runtimepath,
treesitter highlighting for the current buffer can be enabled simply via
vim.treesitter.start().

                                                 treesitter-highlight-groups
The capture names, prefixed with @, are directly usable as highlight groups.
For many commonly used captures, the corresponding highlight groups are linked
to Nvim's standard highlight-groups by default (e.g., @comment links to
Comment) but can be overridden in colorschemes.

A fallback system is implemented, so that more specific groups fallback to
more generic ones. For instance, in a language that has separate doc comments
(e.g., c, java, etc.), @comment.documentation could be used. If this group
is not defined, the highlighting for an ordinary @comment is used. This way,
existing color schemes already work out of the box, but it is possible to add
more specific variants for queries that make them available.

As an additional rule, capture highlights can always be specialized by
language, by appending the language name after an additional dot. For
instance, to highlight comments differently per language: 

    hi @comment.c guifg=Blue
    hi @comment.lua guifg=DarkBlue
    hi link @comment.documentation.java String

The following is a list of standard captures used in queries for Nvim,
highlighted according to the current colorscheme (use :Inspect on one to see
the exact definition):

@variable                       various variable names
@variable.builtin               built-in variable names (e.g. this, self)
@variable.parameter             parameters of a function
@variable.parameter.builtin     special parameters (e.g. _, it)
@variable.member                object and struct fields

@constant               constant identifiers
@constant.builtin       built-in constant values
@constant.macro         constants defined by the preprocessor

@module                 modules or namespaces
@module.builtin         built-in modules or namespaces
@label                  GOTO and other labels (e.g. label: in C), including heredoc labels

@string                 string literals
@string.documentation   string documenting code (e.g. Python docstrings)
@string.regexp          regular expressions
@string.escape          escape sequences
@string.special         other special strings (e.g. dates)
@string.special.symbol  symbols or atoms
@string.special.path    filenames
@string.special.url     URIs (e.g. hyperlinks)

@character              character literals
@character.special      special characters (e.g. wildcards)

@boolean                boolean literals
@number                 numeric literals
@number.float           floating-point number literals

@type                   type or class definitions and annotations
@type.builtin           built-in types
@type.definition        identifiers in type definitions (e.g. `typedef <type> <identifier>` in C)

@attribute              attribute annotations (e.g. Python decorators, Rust lifetimes)
@attribute.builtin      builtin annotations (e.g. @property in Python)
@property               the key in key/value pairs

@function               function definitions
@function.builtin       built-in functions
@function.call          function calls
@function.macro         preprocessor macros

@function.method        method definitions
@function.method.call   method calls

@constructor            constructor calls and definitions
@operator               symbolic operators (e.g. +, *)

@keyword                keywords not fitting into specific categories
@keyword.coroutine      keywords related to coroutines (e.g. go in Go, async/await in Python)
@keyword.function       keywords that define a function (e.g. func in Go, def in Python)
@keyword.operator       operators that are English words (e.g. and, or)
@keyword.import         keywords for including modules (e.g. import, from in Python)
@keyword.type           keywords defining composite types (e.g. struct, enum)
@keyword.modifier       keywords defining type modifiers (e.g. const, static, public)
@keyword.repeat         keywords related to loops (e.g. for, while)
@keyword.return         keywords like return and yield
@keyword.debug          keywords related to debugging
@keyword.exception      keywords related to exceptions (e.g. throw, catch)

@keyword.conditional         keywords related to conditionals (e.g. if, else)
@keyword.conditional.ternary ternary operator (e.g. ?, :)

@keyword.directive           various preprocessor directives and shebangs
@keyword.directive.define    preprocessor definition directives

@punctuation.delimiter  delimiters (e.g. ;, ., ,)
@punctuation.bracket    brackets (e.g. (), {}, [])
@punctuation.special    special symbols (e.g. {} in string interpolation)

@comment                line and block comments
@comment.documentation  comments documenting code

@comment.error          error-type comments (e.g. ERROR, FIXME, DEPRECATED)
@comment.warning        warning-type comments (e.g. WARNING, FIX, HACK)
@comment.todo           todo-type comments (e.g. TODO, WIP)
@comment.note           note-type comments (e.g. NOTE, INFO, XXX)

@markup.strong          bold text
@markup.italic          italic text
@markup.strikethrough   struck-through text
@markup.underline       underlined text (only for literal underline markup!)

@markup.heading         headings, titles (including markers)
@markup.heading.1       top-level heading
@markup.heading.2       section heading
@markup.heading.3       subsection heading
@markup.heading.4       and so on
@markup.heading.5       and so forth
@markup.heading.6       six levels ought to be enough for anybody

@markup.quote           block quotes
@markup.math            math environments (e.g. `$ ... $` in LaTeX)

@markup.link            text references, footnotes, citations, etc.
@markup.link.label      link, reference descriptions
@markup.link.url        URL-style links

@markup.raw             literal or verbatim text (e.g. inline code)
@markup.raw.block       literal or verbatim text as a stand-alone block

@markup.list            list markers
@markup.list.checked    checked todo-style list markers
@markup.list.unchecked  unchecked todo-style list markers

@diff.plus              added text (for diff files)
@diff.minus             deleted text (for diff files)
@diff.delta             changed text (for diff files)

@tag                    XML-style tag names (e.g. in XML, HTML, etc.)
@tag.builtin            XML-style tag names (e.g. HTML5 tags)
@tag.attribute          XML-style tag attributes
@tag.delimiter          XML-style tag delimiters

                                                  treesitter-highlight-spell
The special @spell capture can be used to indicate that a node should be
spell checked by Nvim's builtin spell checker. For example, the following
capture marks comments as to be checked: >query

    (comment) @spell
<

There is also @nospell which disables spellchecking regions with @spell.

                                                treesitter-highlight-conceal
Treesitter highlighting supports conceal via the conceal metadata. By
convention, nodes to be concealed are captured as @conceal, but any capture
can be used. For example, the following query can be used to hide code block
delimiters in Markdown: >query

    (fenced_code_block_delimiter @conceal (#set! conceal ""))
<
It is also possible to replace a node with a single character, which (unlike
legacy syntax) can be given a custom highlight. For example, the following
(ill-advised) query replaces the != operator by a Unicode glyph, which is
still highlighted the same as other operators: >query

    "!=" @operator (#set! conceal "≠")
<
Conceals specified in this way respect 'conceallevel'.

                                               treesitter-highlight-priority
Treesitter uses nvim_buf_set_extmark() to set highlights with a default
priority of 100. This enables plugins to set a highlighting priority lower or
higher than treesitter. It is also possible to change the priority of an
individual query pattern manually by setting its "priority" metadata
attribute: >query

    ((super_important_node) @superimportant (#set! "priority" 105))
<

==============================================================================
TREESITTER LANGUAGE INJECTIONS                treesitter-language-injections
<

Note the following information is adapted from:
  https://tree-sitter.github.io/tree-sitter/syntax-highlighting#language-injection

Some source files contain code written in multiple different languages.
Examples include:

    • HTML files, which can contain JavaScript inside of <script> tags and
      CSS inside of <style> tags
    • ERB files, which contain Ruby inside of <% %> tags, and HTML outside of
      those tags
    • PHP files, which can contain HTML between the <php tags
    • JavaScript files, which contain regular expression syntax within regex
      literals
    • Ruby, which can contain snippets of code inside of heredoc literals,
      where the heredoc delimiter often indicates the language
    • Lua, which can contain snippets of Vimscript inside vim.cmd() calls.
    • Vimscript, which can contain snippets of Lua inside :lua-heredoc
      blocks.

All of these examples can be modeled in terms of a parent syntax tree and one
or more injected syntax trees, which reside inside of certain nodes in the
parent tree. The language injection query allows you to specify these
“injections” using the following captures:

    • @injection.content - indicates that the captured node should have its
      contents re-parsed using another language.
    • @injection.language - indicates that the captured node’s text may
      contain the name of a language that should be used to re-parse the
      @injection.content.
    • @injection.filename - indicates that the captured node’s text may
      contain a filename; the corresponding filetype is then looked-up up via
      vim.filetype.match() and treated as the name of a language that should
      be used to re-parse the @injection.content.

The language injection behavior can also be configured by some properties
associated with patterns:

    • injection.language - can be used to hard-code the name of a specific
    language.
    • injection.combined - indicates that all of the matching nodes in the
    tree should have their content parsed as one nested document.
    • injection.include-children - indicates that the @injection.content
    node's entire text should be re-parsed, including the text of its child
    nodes. By default, child nodes' text will be excluded from the injected
    document.
    • injection.self - indicates that the node's text should be parsed with
      the same language as the node's LanguageTree.
    • injection.parent - indicates that the captured node’s text should
      be parsed with the same language as the node's parent LanguageTree.

==============================================================================
VIM.TREESITTER                                                lua-treesitter

The remainder of this document is a reference manual for the vim.treesitter
Lua module, which is the main interface for Nvim's treesitter integration.
Most of the following content is automatically generated from the function
documentation.


                                             vim.treesitter.language_version
The latest parser ABI version that is supported by the bundled treesitter
library.

                                     vim.treesitter.minimum_language_version
The earliest parser ABI version that is supported by the bundled treesitter
library.

==============================================================================
Lua module: vim.treesitter                               lua-treesitter-core

foldexpr({lnum})                                   vim.treesitter.foldexpr()
    Returns the fold level for {lnum} in the current buffer. Can be set
    directly to 'foldexpr': 
        vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'


    Parameters: {lnum}  (`integer?`) Line number to calculate fold level for

    Return: 
        (`string`)

                                     vim.treesitter.get_captures_at_cursor()
get_captures_at_cursor({winnr})
    Returns a list of highlight capture names under the cursor

    Parameters: {winnr}  (`integer?`) Window handle or 0 for current window (default)

    Return: 
        (`string[]`) List of capture names

                                        vim.treesitter.get_captures_at_pos()
get_captures_at_pos({bufnr}, {row}, {col})
    Returns a list of highlight captures at the given position

    Each capture is represented by a table containing the capture name as a
    string as well as a table of metadata (`priority`, conceal, ...; empty
    if none are defined).

    Parameters: {bufnr}  (`integer`) Buffer number (0 for current buffer)
      • {row}    (`integer`) Position row
      • {col}    (`integer`) Position column

    Return: 
        (`{capture: string, lang: string, metadata: table}[]`)

get_node({opts})                                   vim.treesitter.get_node()
    Returns the smallest named node at the given position

    NOTE: Calling this on an unparsed tree can yield an invalid node. If the
    tree is not known to be parsed by, e.g., an active highlighter, parse the
    tree first via 
        vim.treesitter.get_parser(bufnr):parse(range)


    Parameters: {opts}  (`table?`) Optional keyword arguments:
                • {bufnr} (`integer?`) Buffer number (nil or 0 for current
                  buffer)
                • {pos} (`{ [1]: integer, [2]: integer }?`) 0-indexed (row,
                  col) tuple. Defaults to cursor position in the current
                  window. Required if {bufnr} is not the current buffer
                • {lang} (`string?`) Parser language. (default: from buffer
                  filetype)
                • {ignore_injections} (`boolean?`) Ignore injected languages
                  (default true)

    Return: 
        (`TSNode?`) Node at the given position

get_node_range({node_or_range})              vim.treesitter.get_node_range()
    Returns the node's range or an unpacked range table

    Parameters: {node_or_range}  (`TSNode|table`) Node or table of positions

    Return (multiple): 
        (`integer`) start_row
        (`integer`) start_col
        (`integer`) end_row
        (`integer`) end_col

                                              vim.treesitter.get_node_text()
get_node_text({node}, {source}, {opts})
    Gets the text corresponding to a given node

    Parameters: {node}    (`TSNode`)
      • {source}  (`integer|string`) Buffer or string from which the {node} is
                  extracted
      • {opts}    (`table?`) Optional parameters.
                  • metadata (table) Metadata of a specific capture. This
                    would be set to metadata[capture_id] when using
                    vim.treesitter.query.add_directive().

    Return: 
        (`string`)

get_parser({bufnr}, {lang}, {opts})              vim.treesitter.get_parser()
    Returns the parser for a specific buffer and attaches it to the buffer

    If needed, this will create the parser.

    Parameters: {bufnr}  (`integer?`) Buffer the parser should be tied to (default:
                 current buffer)
      • {lang}   (`string?`) Language of this parser (default: from buffer
                 filetype)
      • {opts}   (`table?`) Options to pass to the created language tree

    Return: 
        (`vim.treesitter.LanguageTree`) object to use for parsing

get_range({node}, {source}, {metadata})           vim.treesitter.get_range()
    Get the range of a TSNode. Can also supply {source} and {metadata} to
    get the range with directives applied.

    Parameters: {node}      (`TSNode`)
      • {source}    (`integer|string?`) Buffer or string from which the {node}
                    is extracted
      • {metadata}  (`vim.treesitter.query.TSMetadata?`)

    Return: 
        (`Range6`)

                                          vim.treesitter.get_string_parser()
get_string_parser({str}, {lang}, {opts})
    Returns a string parser

    Parameters: {str}   (`string`) Text to parse
      • {lang}  (`string`) Language of this string{opts}  (`table?`) Options to pass to the created language tree

    Return: 
        (`vim.treesitter.LanguageTree`) object to use for parsing

inspect_tree({opts})                           vim.treesitter.inspect_tree()
    Open a window that displays a textual representation of the nodes in the
    language tree.

    While in the window, press "a" to toggle display of anonymous nodes, "I"
    to toggle the display of the source language of each node, "o" to toggle
    the query editor, and press <Enter> to jump to the node under the cursor
    in the source buffer. Folding also works (try zo, zc, etc.).

    Can also be shown with :InspectTree.                      :InspectTree

    Parameters: {opts}  (`table?`) Optional options table with the following possible
                keys:
                • lang (string|nil): The language of the source buffer. If
                  omitted, detect from the filetype of the source buffer.
                • bufnr (integer|nil): Buffer to draw the tree into. If
                  omitted, a new buffer is created.
                • winid (integer|nil): Window id to display the tree buffer
                  in. If omitted, a new window is created with {command}.
                • command (string|nil): Vimscript command to create the
                  window. Default value is "60vnew". Only used when {winid} is
                  nil.
                • title (stringfun(bufnr:integer):stringnil): Title of the
                  window. If a function, it accepts the buffer number of the
                  source buffer as its only argument and should return a
                  string.

is_ancestor({dest}, {source})                   vim.treesitter.is_ancestor()
    Determines whether a node is the ancestor of another

    Parameters: {dest}    (`TSNode`) Possible ancestor
      • {source}  (`TSNode`) Possible descendant

    Return: 
        (`boolean`) True if {dest} is an ancestor of {source}

                                           vim.treesitter.is_in_node_range()
is_in_node_range({node}, {line}, {col})
    Determines whether (line, col) position is in node range

    Parameters: {node}  (`TSNode`) defining the range
      • {line}  (`integer`) Line (0-based)
      • {col}   (`integer`) Column (0-based)

    Return: 
        (`boolean`) True if the position is in node range

node_contains({node}, {range})                vim.treesitter.node_contains()
    Determines if a node contains a range

    Parameters: {node}   (`TSNode`)
      • {range}  (`table`)

    Return: 
        (`boolean`) True if the {node} contains the {range}

start({bufnr}, {lang})                                vim.treesitter.start()
    Starts treesitter highlighting for a buffer

    Can be used in an ftplugin or FileType autocommand.

    Note: By default, disables regex syntax highlighting, which may be
    required for some plugins. In this case, add `vim.bo.syntax = 'on'` after
    the call to start.

    Example: 
        vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
            callback = function(args)
                vim.treesitter.start(args.buf, 'latex')
                vim.bo[args.buf].syntax = 'on'  -- only if additional legacy syntax is needed
            end
        })


    Parameters: {bufnr}  (`integer?`) Buffer to be highlighted (default: current
                 buffer)
      • {lang}   (`string?`) Language of the parser (default: from buffer
                 filetype)

stop({bufnr})                                          vim.treesitter.stop()
    Stops treesitter highlighting for a buffer

    Parameters: {bufnr}  (`integer?`) Buffer to stop highlighting (default: current
                 buffer)


==============================================================================
Lua module: vim.treesitter.language                  lua-treesitter-language

add({lang}, {opts})                            vim.treesitter.language.add()
    Load parser with name {lang}

    Parsers are searched in the parser runtime directory, or the provided
    {path}

    Parameters: {lang}  (`string`) Name of the parser (alphanumerical and _ only)
      • {opts}  (`table?`) Options:
                • {filetype}? (`string|string[]`, default: {lang}) Default
                  filetype the parser should be associated with.
                • {path}? (`string`) Optional path the parser is located at{symbol_name}? (`string`) Internal symbol name for the
                  language to load

get_filetypes({lang})                vim.treesitter.language.get_filetypes()
    Get the filetypes associated with the parser named {lang}.

    Parameters: {lang}  (`string`) Name of parser

    Return: 
        (`string[]`) filetypes

get_lang({filetype})                      vim.treesitter.language.get_lang()

    Parameters: {filetype}  (`string`)

    Return: 
        (`string?`)

inspect({lang})                            vim.treesitter.language.inspect()
    Inspects the provided language.

    Inspecting provides some useful information on the language like node
    names, ...

    Parameters: {lang}  (`string`) Language

    Return: 
        (`table`)

register({lang}, {filetype})              vim.treesitter.language.register()
    Register a parser named {lang} to be used for {filetype}(s).

    Note: this adds or overrides the mapping for {filetype}, any existing
    mappings from other filetypes to {lang} will be preserved.

    Parameters: {lang}      (`string`) Name of parser
      • {filetype}  (`string|string[]`) Filetype(s) to associate with lang


==============================================================================
Lua module: vim.treesitter.query                        lua-treesitter-query

                                        vim.treesitter.query.add_directive()
add_directive({name}, {handler}, {opts})
    Adds a new directive to be used in queries

    Handlers can set match level data by setting directly on the metadata
    object `metadata.key = value`. Additionally, handlers can set node level
    data by using the capture id on the metadata table
    `metadata[capture_id].key = value`

    Parameters: {name}     (`string`) Name of the directive, without leading #{handler}  (`fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)`)
                   • match: A table mapping capture IDs to a list of captured
                     nodes
                   • pattern: the index of the matching pattern in the query
                     file
                   • predicate: list of strings containing the full directive
                     being called, e.g. `(node (#set! conceal "-"))` would get
                     the predicate `{ "#set!", "conceal", "-" }`
      • {opts}     (`table`) A table with the following fields:
                   • {force}? (`boolean`) Override an existing predicate of
                     the same name
                   • {all}? (`boolean`) Use the correct implementation of the
                     match table where capture IDs map to a list of nodes
                     instead of a single node. Defaults to false (for backward
                     compatibility). This option will eventually become the
                     default and removed.

                                        vim.treesitter.query.add_predicate()
add_predicate({name}, {handler}, {opts})
    Adds a new predicate to be used in queries

    Parameters: {name}     (`string`) Name of the predicate, without leading #{handler}  (`fun(match: table<integer,TSNode[]>, pattern: integer, source: integer|string, predicate: any[], metadata: table)`)
                   • see vim.treesitter.query.add_directive() for argument
                     meanings
      • {opts}     (`table`) A table with the following fields:
                   • {force}? (`boolean`) Override an existing predicate of
                     the same name
                   • {all}? (`boolean`) Use the correct implementation of the
                     match table where capture IDs map to a list of nodes
                     instead of a single node. Defaults to false (for backward
                     compatibility). This option will eventually become the
                     default and removed.

edit({lang})                                     vim.treesitter.query.edit()
    Opens a live editor to query the buffer you started from.

    Can also be shown with *:EditQuery*.

    If you move the cursor to a capture name ("@foo"), text matching the
    capture is highlighted in the source buffer. The query editor is a scratch
    buffer, use :write to save it. You can find example queries at
    $VIMRUNTIME/queries/.

    Parameters: {lang}  (`string?`) language to open the query editor for. If omitted,
                inferred from the current buffer's filetype.

get({lang}, {query_name})                         vim.treesitter.query.get()
    Returns the runtime query {query_name} for {lang}.

    Parameters: {lang}        (`string`) Language to use for the query
      • {query_name}  (`string`) Name of the query (e.g. "highlights")

    Return: 
        (`vim.treesitter.Query?`) Parsed query. nil if no query files are
        found.

                                            vim.treesitter.query.get_files()
get_files({lang}, {query_name}, {is_included})
    Gets the list of files used to make up a query

    Parameters: {lang}         (`string`) Language to get query for{query_name}   (`string`) Name of the query to load (e.g.,
                       "highlights"){is_included}  (`boolean?`) Internal parameter, most of the time left
                       as nil

    Return: 
        (`string[]`) query_files List of files to load for given query and
        language

lint({buf}, {opts})                              vim.treesitter.query.lint()
    Lint treesitter queries using installed parser, or clear lint errors.

    Use treesitter-parsers in runtimepath to check the query file in {buf}
    for errors:
    • verify that used nodes are valid identifiers in the grammar.
    • verify that predicates and directives are valid.
    • verify that top-level s-expressions are valid.

    The found diagnostics are reported using diagnostic-api. By default, the
    parser used for verification is determined by the containing folder of the
    query file, e.g., if the path ends in /lua/highlights.scm, the parser
    for the lua language will be used.

    Parameters: {buf}   (`integer`) Buffer handle
      • {opts}  (`table?`) Optional keyword arguments:
                • {langs}? (`string|string[]`) Language(s) to use for checking
                  the query. If multiple languages are specified, queries are
                  validated for all of them
                • {clear} (`boolean`) Just clear current lint errors

list_directives()                     vim.treesitter.query.list_directives()
    Lists the currently available directives to use in queries.

    Return: 
        (`string[]`) Supported directives.

list_predicates()                     vim.treesitter.query.list_predicates()
    Lists the currently available predicates to use in queries.

    Return: 
        (`string[]`) Supported predicates.

omnifunc({findstart}, {base})                vim.treesitter.query.omnifunc()
    Omnifunc for completing node names and predicates in treesitter queries.

    Use via 
        vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc'


    Parameters: {findstart}  (`0|1`)
      • {base}       (`string`)

parse({lang}, {query})                          vim.treesitter.query.parse()
    Parse {query} as a string. (If the query is in a file, the caller should
    read the contents into a string before calling).

    Returns a Query (see lua-treesitter-query) object which can be used to
    search nodes in the syntax tree for the patterns defined in {query} using
    the iter_captures and iter_matches methods.

    Exposes info and captures with additional context about {query}.
    • captures contains the list of unique capture names defined in {query}.
    • info.captures also points to captures.
    • info.patterns contains information about predicates.

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

    Return: 
        (`vim.treesitter.Query`) Parsed query

    See also: vim.treesitter.query.get()

                                                       Query:iter_captures()
Query:iter_captures({node}, {source}, {start}, {stop})
    Iterate over all captures from all matches inside {node}

    {source} is needed 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: a numeric id identifying the capture,
    the captured node, metadata from any directives processing the match, and
    the match itself. The following example shows 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


    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_().

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

                                                        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.

    WARNING: Set all=true to ensure all matching nodes in a match are
    returned, otherwise only the last node in a match is returned, breaking
    captures involving quantifiers such as `(comment)+ @comment`. The default
    option all=false is only provided for backward compatibility and will be
    removed after Nvim 0.10.

    Example: 
        for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, 0, -1, { all = true }) 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}    (`TSNode`) under which the search will occur
      • {source}  (`integer|string`) Source buffer or string to search
      • {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).
                  • all (boolean) When set, the returned match table maps
                    capture IDs to a list of nodes. Older versions of
                    iter_matches incorrectly mapped capture IDs to a single
                    node, which is incorrect behavior. This option will
                    eventually become the default and removed.

    Return: 
        (`fun(): integer, table<integer, TSNode[]>, table`) pattern id, match,
        metadata

set({lang}, {query_name}, {text})                 vim.treesitter.query.set()
    Sets the runtime query named {query_name} for {lang}

    This allows users to override any runtime files and/or configuration set
    by plugins.

    Parameters: {lang}        (`string`) Language to use for the query
      • {query_name}  (`string`) Name of the query (e.g., "highlights"){text}        (`string`) Query text (unparsed).


==============================================================================
Lua module: vim.treesitter.languagetree          lua-treesitter-languagetree

A LanguageTree contains a tree of parsers: the root treesitter parser for
{lang} and any "injected" language parsers, which themselves may inject other
languages, recursively. For example a Lua buffer containing some Vimscript
commands needs multiple parsers to fully understand its contents.

To create a LanguageTree (parser object) for a given buffer and language, use: 
    local parser = vim.treesitter.get_parser(bufnr, lang)


(where bufnr=0 means current buffer). lang defaults to 'filetype'. Note:
currently the parser is retained for the lifetime of a buffer but this may
change; a plugin should keep a reference to the parser object if it wants
incremental updates.

Whenever you need to access the current syntax tree, parse the buffer: 
    local tree = parser:parse({ start_row, end_row })


This returns a table of immutable treesitter-tree objects representing the
current state of the buffer. When the plugin wants to access the state after a
(possible) edit it must call parse() again. If the buffer wasn't edited, the
same tree will be returned again without extra work. If the buffer was parsed
before, incremental parsing will be done of the changed parts.

Note: To use the parser directly inside a nvim_buf_attach() Lua callback,
you must call vim.treesitter.get_parser() before you register your callback.
But preferably parsing shouldn't be done directly in the change callback
anyway as they will be very frequent. Rather a plugin that does any kind of
analysis on a tree should use a timer to throttle too frequent updates.


LanguageTree:children()                              LanguageTree:children()
    Returns a map of language to child tree.

LanguageTree:contains({range})                       LanguageTree:contains()
    Determines whether {range} is contained in the LanguageTree.

    Parameters: {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`

    Return: 
        (`boolean`)

LanguageTree:destroy()                                LanguageTree:destroy()
    Destroys this LanguageTree and all its children.

    Any cleanup logic should be performed here.

    Note: This DOES NOT remove this tree from a parent. Instead,
    remove_child must be called on the parent to remove it.

LanguageTree:for_each_tree({fn})                LanguageTree:for_each_tree()
    Invokes the callback for each LanguageTree recursively.

    Note: This includes the invoking tree's child trees as well.

    Parameters: {fn}  (`fun(tree: TSTree, ltree: vim.treesitter.LanguageTree)`)

LanguageTree:included_regions()              LanguageTree:included_regions()
    Gets the set of included regions managed by this LanguageTree. This can be
    different from the regions set by injection query, because a partial
    LanguageTree:parse() drops the regions outside the requested range.

    Return: 
        (`table<integer, Range6[]>`)

LanguageTree:invalidate({reload})                  LanguageTree:invalidate()
    Invalidates this parser and its children.

    Should only be called when the tracked state of the LanguageTree is not
    valid against the parse tree in treesitter. Doesn't clear filesystem
    cache. Called often, so needs to be fast.

    Parameters: {reload}  (`boolean?`)

LanguageTree:is_valid({exclude_children})            LanguageTree:is_valid()
    Returns whether this LanguageTree is valid, i.e., LanguageTree:trees()
    reflects the latest state of the source. If invalid, user should call
    LanguageTree:parse().

    Parameters: {exclude_children}  (`boolean?`) whether to ignore the validity of
                            children (default false)

    Return: 
        (`boolean`)

LanguageTree:lang()                                      LanguageTree:lang()
    Gets the language of this tree node.

                                           LanguageTree:language_for_range()
LanguageTree:language_for_range({range})
    Gets the appropriate language that contains {range}.

    Parameters: {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`

    Return: 
        (`vim.treesitter.LanguageTree`) tree Managing {range}

                                         LanguageTree:named_node_for_range()
LanguageTree:named_node_for_range({range}, {opts})
    Gets the smallest named node that contains {range}.

    Parameters: {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
      • {opts}   (`table?`) A table with the following fields:
                 • {ignore_injections}? (`boolean`, default: true) Ignore
                   injected languages

    Return: 
        (`TSNode?`)

LanguageTree:parse({range})                             LanguageTree:parse()
    Recursively parse all regions in the language tree using
    treesitter-parsers for the corresponding languages and run injection
    queries on the parsed trees to determine whether child trees should be
    created and parsed.

    Any region with empty range (`{}`, typically only the root tree) is always
    parsed; otherwise (typically injections) only if it intersects {range} (or
    if {range} is true).

    Parameters: {range}  (`boolean|Range?`) Parse this range in the parser's source.
                 Set to true to run a complete parse of the source (Note:
                 Can be slow!) Set to false|nil to only parse regions with
                 empty ranges (typically only the root tree without
                 injections).

    Return: 
        (`table<integer, TSTree>`)

                                                 LanguageTree:register_cbs()
LanguageTree:register_cbs({cbs}, {recursive})
    Registers callbacks for the LanguageTree.

    Parameters: {cbs}        (`table<TSCallbackNameOn,function>`) An
                     nvim_buf_attach()-like table argument with the
                     following handlers:
                     • on_bytes : see nvim_buf_attach(), but this will be
                       called after the parsers callback.
                     • on_changedtree : a callback that will be called every
                       time the tree has syntactical changes. It will be
                       passed two arguments: a table of the ranges (as node
                       ranges) that changed and the changed tree.
                     • on_child_added : emitted when a child is added to the
                       tree.
                     • on_child_removed : emitted when a child is removed
                       from the tree.
                     • on_detach : emitted when the buffer is detached, see
                       nvim_buf_detach_event. Takes one argument, the number
                       of the buffer.
      • {recursive}  (`boolean?`) Apply callbacks recursively for all
                     children. Any new children will also inherit the
                     callbacks.

LanguageTree:source()                                  LanguageTree:source()
    Returns the source content of the language tree (bufnr or string).

                                               LanguageTree:tree_for_range()
LanguageTree:tree_for_range({range}, {opts})
    Gets the tree that contains {range}.

    Parameters: {range}  (`Range4`) `{ start_line, start_col, end_line, end_col }`
      • {opts}   (`table?`) A table with the following fields:
                 • {ignore_injections}? (`boolean`, default: true) Ignore
                   injected languages

    Return: 
        (`TSTree?`)

LanguageTree:trees()                                    LanguageTree:trees()
    Returns all trees of the regions parsed by this parser. Does not include
    child languages. The result is list-like if
    • this LanguageTree is the root, in which case the result is empty or a
      singleton list; or
    • the root LanguageTree is fully parsed.

    Return: 
        (`table<integer, TSTree>`)


 vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:


Quick links: help overview · quick reference · user manual toc · reference manual toc