*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: >lua

    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: >lua

    vim.treesitter.language.register('xml', { 'svg', 'xslt' })
<
                                                    *treesitter-parsers-wasm*

If Nvim is built with `ENABLE_WASMTIME`, then wasm parsers can also be
loaded: >lua

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

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

The Lua interface is described at |lua-treesitter-query|.


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: