nvim-treesitter/doc/nvim-treesitter.txt

*nvim-treesitter*  Treesitter configurations and abstraction layer for Neovim.

Minimum version of neovim: nightly

Authors:
  Kiyan Yazdani <yazdani.kiyan@protonmail.com>
  Thomas Vigouroux <tomvig38@gmail.com>
  Stephan Seitz <stephan.seitz@fau.de>
  Steven Sojka <Steven.Sojka@tdameritrade.com>
  Santos Gallegos <stsewd@protonmail.com>
  https://github.com/nvim-treesitter/nvim-treesitter/graphs/contributors

                                       Type |gO| to see the table of contents.

==============================================================================
INTRODUCTION                                           *nvim-treesitter-intro*

nvim-treesitter wraps the Neovim treesitter API to provide functionalities
such as highlighting and incremental selection, and a command to easily
install parsers.

==============================================================================
QUICK START                                       *nvim-treesitter-quickstart*

Install the parser for your language

>
  :TSInstall {language}
<

To get a list of supported languages

>
  :TSInstallInfo
<

By default, everything is disabled.
To enable supported features, put this in your `init.vim` file:

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    ensure_installed = "maintained", -- one of "all", "maintained" (parsers with maintainers), or a list of languages
    ignore_install = { "javascript" }, -- List of parsers to ignore installing
    highlight = {
      enable = true,              -- false will disable the whole extension
      disable = { "c", "rust" },  -- list of language that will be disabled
    },
  }
  EOF
<

See |nvim-treesitter-modules| for a list of all available modules and its options.

==============================================================================
MODULES                                              *nvim-treesitter-modules*

|nvim-treesitter| provides several functionalities via modules (and submodules),
each module makes use of the query files defined for each language,
you can add your own queries too, see |nvim-treesitter-query-extensions|.

All modules are disabled by default, and some provide default keymaps.
Each module corresponds to an entry in the dictionary passed to the
`nvim-treesitter.configs.setup` function, this should be in your `init.vim` file.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    -- Modules and its options go here
    highlight = { enable = true },
    incremental_selection = { enable = true },
    textobjects = { enable = true },
  }
  EOF
<

All modules share some common options, like `enable`, `disable`, and
`condition`.
When `enable` is `true` this will enable the module for all supported languages,
if you want to disable the module for some languages you can pass a list to the `disable` option.
For more fine-grained control, `condition` takes a function and whenever it returns
`false` the module is disabled for that buffer.
The `condition` function is called once when a module starts in a buffer and
received the language and the buffer number as arguments.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    highlight = {
      enable = true,
      disable = { "cpp", "lua" },
      condition = function(lang, bufnr) -- Disable in large C++ buffers
        return not (lang == "cpp" and api.nvim_buf_line_count(bufnr) > 50000)
      end,
    },
  }
  EOF
<

Options that define or accept a keymap use the same format you use to define
keymaps in Neovim, so you can write keymaps as  `gd`, `<space>a`, `<leader>a`
`<C-a>` (control + a), `<A-n>` (alt + n), `<CR>` (enter), etc.

External plugins can provide their own modules with their own options,
those can also be configured using the `nvim-treesitter.configs.setup`
function.

------------------------------------------------------------------------------
HIGHLIGHT                                      *nvim-treesitter-highlight-mod*

Consistent syntax highlighting.

Query files: `highlights.scm`.
Supported options:

- enable: `true` or `false`.
- disable: list of languages.
- custom_captures: A map of user defined capture groups to highlight groups.
  See |nvim-treesitter-query-extensions|.
- additional_vim_regex_highlighting: `true` or `false`, or a list of languages.
  Set this to `true` if you depend on 'syntax' being enabled
  (like for indentation). Using this option may slow down your editor,
  and you may see some duplicate highlights.
  Defaults to `false`.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    highlight = {
      enable = true,
      custom_captures = {
        -- Highlight the @foo.bar capture group with the "Identifier" highlight group.
        ["foo.bar"] = "Identifier",
      },
      -- Setting this to true or a list of languages will run `:h syntax` and tree-sitter at the same time.
      additional_vim_regex_highlighting = false,
    },
  }
  EOF
<
Note: The api is not stable yet.

------------------------------------------------------------------------------
INCREMENTAL SELECTION              *nvim-treesitter-incremental-selection-mod*

Incremental selection based on the named nodes from the grammar.

Query files: `locals.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- keymaps:
  - init_selection: in normal mode, start incremental selection.
    Defaults to `gnn`.
  - node_incremental: in visual mode, increment to the upper named parent.
    Defaults to `grn`.
  - scope_incremental: in visual mode, increment to the upper scope
    (as defined in `locals.scm`). Defaults to `grc`.
  - node_decremental: in visual mode, decrement to the previous named node.
    Defaults to `grm`.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    incremental_selection = {
      enable = true,
      keymaps = {
        init_selection = "gnn",
        node_incremental = "grn",
        scope_incremental = "grc",
        node_decremental = "grm",
      },
    },
  }
  EOF
<

------------------------------------------------------------------------------
INDENTATION                                  *nvim-treesitter-indentation-mod*

Indentation based on treesitter for the |=| operator.
NOTE: this is an experimental feature.

Query files: `indents.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    indent = {
      enable = true
    },
  }
  EOF
<
==============================================================================
COMMANDS                                            *nvim-treesitter-commands*

								  *:TSInstall*
:TSInstall {language} ...~

Install one or more treesitter parsers.
You can use |:TSInstall| `all` to install all parsers. Use |:TSInstall!| to
force the reinstallation of already installed parsers.
							      *:TSInstallSync*
:TSInstallSync {language} ...~

Perform the |:TSInstall| operation synchronously.

							      *:TSInstallInfo*
:TSInstallInfo~

List information about currently installed parsers

								   *:TSUpdate*
:TSUpdate {language} ...~

Update the installed parser for one more {language} or all installed parsers
if {language} is omitted. The specified parser is installed if it is not already
installed.

							       *:TSUpdateSync*
:TSUpdateSync {language} ...~

Perform the |:TSUpdate| operation synchronously.

								*:TSUninstall*
:TSUninstall {language} ...~

Deletes the parser for one or more {language}. You can use 'all' for language
to uninstall all parsers.

								*:TSBufEnable*
:TSBufEnable {module}~

Enable {module} on the current buffer.
A list of modules can be found at |:TSModuleInfo|

							       *:TSBufDisable*
:TSBufDisable {module}~

Disable {module} on the current buffer.
A list of modules can be found at |:TSModuleInfo|

								*:TSBufToggle*
:TSBufToggle {module}~

Toggle (enable if disabled, disable if enabled) {module} on the current
buffer.
A list of modules can be found at |:TSModuleInfo|

								*:TSEnableAll*
:TSEnableAll {module} [{language}]~

Enable {module} for the session.
If {language} is specified, enable module for the session only for this
particular language.
A list of modules can be found at |:TSModuleInfo|
A list of languages can be found at |:TSInstallInfo|

							       *:TSDisableAll*
:TSDisableAll {module} [{language}]~

Disable {module} for the session.
If {language} is specified, disable module for the session only for this
particular language.
A list of modules can be found at |:TSModuleInfo|
A list of languages can be found at |:TSInstallInfo|

								*:TSToggleAll*
:TSToggleAll {module} [{language}]~

Toggle (enable if disabled, disable if enabled) {module} for the session.
If {language} is specified, toggle module for the session only for this
particular language.
A list of modules can be found at |:TSModuleInfo|
A list of languages can be found at |:TSInstallInfo|

							       *:TSModuleInfo*
:TSModuleInfo [{module}]~

List the state for the given module or all modules for the current session in
a new buffer.

These highlight groups are used by default:
>
    highlight default TSModuleInfoGood guifg=LightGreen gui=bold
    highlight default TSModuleInfoBad  guifg=Crimson
    highlight default link TSModuleInfoHeader    Type
    highlight default link TSModuleInfoNamespace Statement
    highlight default link TSModuleInfoParser    Identifier
<

								*:TSEditQuery*
:TSEditQuery {query-group} [{lang}]~

Edit the query file for a {query-group} (e.g. highlights, locals) for given
{lang}.  If there are multiple the user is prompted to select one of them.
If no such file exists, a buffer for a new file in the user's config directory
is created.  If {lang} is not specified, the language of the current buffer
is used.

						       *:TSEditQueryUserAfter*
:TSEditQueryUserAfter {query-group} [{lang}]~

Same as |:TSEditQuery| but edits a file in the `after` directory of the
user's config directory. Useful to add custom extensions for the queries
provided by a plugin.

==============================================================================
UTILS                                                  *nvim-treesitter-utils*

Nvim treesitter has some wrapper functions that you can retrieve with:
>
    local ts_utils = require 'nvim-treesitter.ts_utils'
<
Methods
						 *ts_utils.get_node_at_cursor*
get_node_at_cursor(winnr)~

`winnr` will be 0 if nil.
Returns the node under the cursor.

						      *ts_utils.get_node_text*
get_node_text(node, bufnr)~

Returns the text content of a `node`.

							  *ts_utils.is_parent*
is_parent(dest, source)~

Determines whether `dest` is a parent of `source`.
Returns a boolean.

						 *ts_utils.get_named_children*
get_named_children(node)~

Returns a table of named children of `node`.

						      *ts_utils.get_next_node*
get_next_node(node, allow_switch_parent, allow_next_parent)~

Returns the next node within the same parent.
If no node is found, returns `nil`.
If `allow_switch_parent` is true, it will allow switching parent
when the node is the last node.
If `allow_next_parent` is true, it will allow next parent if
the node is the last node and the next parent doesn't have children.

						  *ts_utils.get_previous_node*
get_previous_node(node, allow_switch_parents, allow_prev_parent)~

Returns the previous node within the same parent.
`allow_switch_parent` and `allow_prev_parent` follow the same rule
as |ts_utils.get_next_node| but if the node is the first node.

							  *ts_utils.goto_node*
goto_node(node, goto_end, avoid_set_jump)~

Sets cursor to the position of `node` in the current windows.
If `goto_end` is truthy, the cursor is set to the end the node range.
Setting `avoid_set_jump` to `true`, avoids setting the current cursor position
to the jump list.

							 *ts_utils.swap_nodes*
swap_nodes(node_or_range1, node_or_range2, bufnr, cursor_to_second)~

Swaps the nodes or ranges.
set `cursor_to_second`  to true to move the cursor to the second node

						*ts_utils.memoize_by_buf_tick*
memoize_by_buf_tick(fn, options)~

Caches the return value for a function and returns the cache value if the tick
of the buffer has not changed from the previous.

		`fn`: a function that takes any arguments
		and returns a value to store.
		`options?`: <table>
                 - `bufnr`: a function/value that extracts the bufnr from the given arguments.
                 - `key`: a function/value that extracts the cache key from the given arguments.
		`returns`: a function to call with bufnr as argument to
		retrieve the value from the cache

						  *ts_utils.node_to_lsp_range*
node_to_lsp_range(node)~

Get an lsp formatted range from a node range

						     *ts_utils.get_node_range*
get_node_range(node_or_range)~

Get the range from either a node or a range

							*ts_utils.node_length*
node_length(node)~

Get the byte length of node range

						   *ts_utils.update_selection*
update_selection(buf, node)~

Set the selection to the node range

						    *ts_utils.highlight_range*
highlight_range(range, buf, hl_namespace, hl_group)~

Set a highlight that spans the given range

						     *ts_utils.highlight_node*
highlight_node(node, buf, hl_namespace, hl_group)~

Set a highlight that spans the given node's range

==============================================================================
FUNCTIONS                                          *nvim-treesitter-functions*

						*nvim_treesitter#statusline()*
nvim_treesitter#statusline(opts)~

Returns a string describing the current position in the file. This
could be used as a statusline indicator.
Default options (lua syntax):
>
  {
    indicator_size = 100,
    type_patterns = {'class', 'function', 'method'},
    transform_fn = function(line) return line:gsub('%s*[%[%(%{]*%s*$', '') end,
    separator = ' -> '
  }
<
- `indicator_size` - How long should the string be. If longer, it is cut from
  the beginning.
- `type_patterns` - Which node type patterns to match.
- `transform_fn` - Function used to transform the single item in line. By
  default removes opening brackets and spaces from end.
- `separator` - Separator between nodes.

						  *nvim_treesitter#foldexpr()*
nvim_treesitter#foldexpr()~

Functions to be used to determine the fold level at a given line number.
To use it: >
  set foldmethod=expr
  set foldexpr=nvim_treesitter#foldexpr()
<

This will respect your 'foldminlines' and 'foldnestmax' settings.

Note: This is highly experimental, and folding can break on some types of
      edits. If you encounter such breakage, hiting `zx` should fix folding.
      In any case, feel free to open an issue with the reproducing steps.

==============================================================================
HIGHLIGHTS                                        *nvim-treesitter-highlights*

The following is a list of highlights groups, the syntactic elements they
apply to, and some examples.

							      *hl-TSAttribute*
`TSAttribute`
Annotations that can be attached to the code to denote some kind of meta
information. e.g. C++/Dart attributes.

								*hl-TSBoolean*
`TSBoolean`
Boolean literals: `True` and `False` in Python.

							      *hl-TSCharacter*
`TSCharacter`
Character literals: `'a'` in C.

								*hl-TSComment*
`TSComment`
Line comments and block comments.

							    *hl-TSConditional*
`TSConditional`
Keywords related to conditionals: `if`, `when`, `cond`, etc.

							       *hl-TSConstant*
`TSConstant`
Constants identifiers. These might not be semantically constant.
E.g. uppercase variables in Python.

							   *hl-TSConstBuiltin*
`TSConstBuiltin`
Built-in constant values: `nil` in Lua.

							     *hl-TSConstMacro*
`TSConstMacro`
Constants defined by macros: `NULL` in C.

							    *hl-TSConstructor*
`TSConstructor`
Constructor calls and definitions: `{}` in Lua, and Java constructors.

								  *hl-TSError*
`TSError`
Syntax/parser errors. This might highlight large sections of code while the
user is typing still incomplete code, use a sensible highlight.

							      *hl-TSException*
`TSException`
Exception related keywords: `try`, `except`, `finally` in Python.

								  *hl-TSField*
`TSField`
Object and struct fields.

								  *hl-TSFloat*
`TSFloat`
Floating-point number literals.

							       *hl-TSFunction*
`TSFunction`
Function calls and definitions.

							    *hl-TSFuncBuiltin*
`TSFuncBuiltin`
Built-in functions: `print` in Lua.

							      *hl-TSFuncMacro*
`TSFuncMacro`
Macro defined functions (calls and definitions): each `macro_rules` in
Rust.

								*hl-TSInclude*
`TSInclude`
File or module inclusion keywords: `#include` in C, `use` or `extern crate` in
Rust.

								*hl-TSKeyword*
`TSKeyword`
Keywords that don't fit into other categories.

							*hl-TSKeywordFunction*
`TSKeywordFunction`
Keywords used to define a function: `function` in Lua, `def` and `lambda` in
Python.

							*hl-TSKeywordOperator*
`TSKeywordOperator`
Unary and binary operators that are English words: `and`, `or` in Python;
`sizeof` in C.

							  *hl-TSKeywordReturn*
`TSKeywordReturn`
Keywords like `return` and `yield`.

								  *hl-TSLabel*
`TSLabel`
GOTO labels: `label:` in C, and `::label::` in Lua.

								 *hl-TSMethod*
`TSMethod`
Method calls and definitions.

							      *hl-TSNamespace*
`TSNamespace`
Identifiers referring to modules and namespaces.

								     *hl-None*
`TSNone`
No highlighting (sets all highlight arguments to `NONE`). this group is used
to clear certain ranges, for example, string interpolations. Don't change the
values of this highlight group.

								 *hl-TSNumber*
`TSNumber`
Numeric literals that don't fit into other categories.

							       *hl-TSOperator*
`TSOperator`
Binary or unary operators: `+`, and also `->` and `*` in C.

							      *hl-TSParameter*
`TSParameter`
Parameters of a function.

						     *hl-TSParameterReference*
`TSParameterReference`
References to parameters of a function.

							       *hl-TSProperty*
`TSProperty`
Same as `TSField`.

							 *hl-TSPunctDelimiter*
`TSPunctDelimiter`
Punctuation delimiters: Periods, commas, semicolons, etc.

							   *hl-TSPunctBracket*
`TSPunctBracket`
Brackets, braces, parentheses, etc.

							   *hl-TSPunctSpecial*
`TSPunctSpecial`
Special punctuation that doesn't fit into the previous categories.

								 *hl-TSRepeat*
`TSRepeat`
Keywords related to loops: `for`, `while`, etc.

								 *hl-TSString*
`TSString`
String literals.

							    *hl-TSStringRegex*
`TSStringRegex`
Regular expression literals.

							   *hl-TSStringEscape*
`TSStringEscape`
Escape characters within a string: `\n`, `\t`, etc.

							  *hl-TSStringSpecial*
`TSStringSpecial`
Strings with special meaning that don't fit into the previous categories.

								 *hl-TSSymbol*
`TSSymbol`
Identifiers referring to symbols or atoms.

								    *hl-TSTag*
`TSTag`
Tags like HTML tag names.

							   *hl-TSTagAttribute*
`TSTagAttribute`
HTML tag attributes.

							   *hl-TSTagDelimiter*
`TSTagDelimiter`
Tag delimiters like `<` `>` `/`.

								   *hl-TSText*
`TSText`
Non-structured text. Like text in a markup language.

								 *hl-TSSTrong*
`TSStrong`
Text to be represented in bold.

							       *hl-TSEmphasis*
`TSEmphasis`
Text to be represented with emphasis.

							      *hl-TSUnderline*
`TSUnderline`
Text to be represented with an underline.

								 *hl-TSStrike*
`TSStrike`
Strikethrough text.

								  *hl-TSTitle*
`TSTitle`
Text that is part of a title.

								*hl-TSLiteral*
`TSLiteral`
Literal or verbatim text.

								    *hl-TSURI*
`TSURI`
URIs like hyperlinks or email addresses.

								   *hl-TSMath*
`TSMath`
Math environments like LaTeX's `$ ... $`

							  *hl-TSTextReference*
`TSTextReference`
Footnotes, text references, citations, etc.

							     *hl-TSEnvironment*
`TSEnvironment`
Text environments of markup languages.

							 *hl-TSEnvironmentName*
`TSEnvironmentName`
Text/string indicating the type of text environment. Like the name of a
`\begin` block in LaTeX.

								   *hl-TSNote*
`TSNote`
Text representation of an informational note.

								   *TSWarning*
`TSWarning`
Text representation of a warning note.

								    *TSDanger*
`TSDanger`
Text representation of a danger note.

								   *hl-TSType*
`TSType`
Type (and class) definitions and annotations.

							    *hl-TSTypeBuiltin*
`TSTypeBuiltin`
Built-in types: `i32` in Rust.

							       *hl-TSVariable*
`TSVariable`
Variable names that don't fit into other categories.

							*hl-TSVariableBuiltin*
`TSVariableBuiltin`
Variable names defined by the language: `this` or `self` in Javascript.

==============================================================================
PERFORMANCE                                      *nvim-treesitter-performance*

`nvim-treesitter` checks the 'runtimepath' on startup in order to discover
available parsers and queries and index them. As a consequence, a very long
'runtimepath' might result in delayed startup times.


vim:tw=78:ts=8:expandtab:noet:ft=help:norl: