path: root/doc/nvim-treesitter.txt

*nvim-treesitter*

Minimum version of neovim: nightly

Authors: Yazdani Kiyan <yazdani.kiyan@protonmail.com>
         Vigouroux Thomas <tomvig38@gmail.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 functionnalities
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 = "all",     -- one of "all", "language", or a list of languages
    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 },
    refactor = {
      highlight_definitions = { enable = true },
      smart_rename = { enable = true },
      navigation = { enable = true },
    },
    textobjects = { enable = true },
  }
  EOF
<

All modules share some common options, like `enable` and `disable`.
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.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    highlight = {
      enable = true,
      disable = { "cpp", "lua" },
    },
  }
  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|.

>
  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",
      },
    },
  }
  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
<

------------------------------------------------------------------------------
REFACTOR                                        *nvim-treesitter-refactor-mod*

                                *nvim-treesitter-highlight-definitions-submod*
Highlight definitions~

Highlights definition and usages of the current symbol under the cursor.

Query files: `locals.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    refactor = {
      highlight_definitions = { enable = true },
    },
  }
  EOF
<

Note: this makes use of the |CursorHold| event, so the highlight is
triggered after 'updatetime'.

                              *nvim-treesitter-highlight-current-scope-submod*
Highlight current scope~

Highlights the block from the current scope where the cursor is.

Query files: `locals.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    refactor = {
      highlight_current_scope = { enable = true },
    },
  }
  EOF
<

                                         *nvim-treesitter-smart-rename-submod*
Smart rename~

Renames the symbol under the cursor within the current scope (and current file).

Query files: `locals.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- keymaps:
  - smart_rename: rename symbol under the cursor.
    Defaults to `grr`.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    refactor = {
      smart_rename = {
        enable = true,
        keymaps = {
          smart_rename = "grr",
        },
      },
    },
  }
  EOF
<

                                           *nvim-treesitter-navigation-submod*
Navigation~

Provides "go to definition" for the symbol under the cursor,
and lists the definitions from the current file.

Query files: `locals.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- keymaps:
  - goto_definition: go to the definition of the symbol under the cursor.
    Defaults to `gnd`.
  - goto_definition_lsp_fallback: go to the definition of the symbol under
    the cursor or use vim.lsp.buf.definition if the symbol can not be
    resolved. You can use your own fallback function if create a mapping for
    `lua require'nvim-treesitter.refactor.navigation(nil, fallback_function)<cr>` .
    No default mapping
  - list_definitions: list all definitions from the current file.
    Defaults to `gnD`.
  - goto_next_usage: go to next usage of identifier under the cursor.
    Defaults to `<a-*>`.
  - goto_previous_usage: go to previous usage of identifier.
    Defaults to `<a-#>`.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    refactor = {
      navigation = {
        enable = true,
        keymaps = {
          goto_definition = "gnd",
          list_definitions = "gnD",
          goto_next_usage = "<a-*>",
          goto_previous_usage = "<a-#>",
        },
      },
    },
  }
  EOF
<

------------------------------------------------------------------------------
TEXT OBJECTS                                 *nvim-treesitter-textobjects-mod*

Syntax aware |text-objects|.

                                  *nvim-treesitter-text-objects-select-submod*
Text object selection~

Define your own text objects mappings
similar to `ip` (inner paragraph) and `ap` (a paragraph).

Query files: `textobjects.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- keymaps: map of keymaps to a tree-sitter query
  (`(function_definition) @function`) or capture group (`@function.inner`).

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    textobjects = {
      select = {
        enable = true,
        keymaps = {
          -- You can use the capture groups defined in textobjects.scm
          ["af"] = "@function.outer",
          ["if"] = "@function.inner",
          ["ac"] = "@class.outer",
          ["ic"] = "@class.inner",

          -- Or you can define your own textobjects like this
          ["iF"] = {
            python = "(function_definition) @function",
            cpp = "(function_definition) @function",
            c = "(function_definition) @function",
            java = "(method_declaration) @function",
          },
        },
      },
    },
  }
  EOF
<

                                    *nvim-treesitter-text-objects-swap-submod*
Swap text objects~

Define your own mappings to swap the node under the cursor with the next or previous one,
like function parameters or arguments.

Query files: `textobjects.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- swap_next: map of keymaps to a tree-sitter capture group (`@parameter.inner`).
- swap_previous: same as swap_next.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    textobjects = {
      swap = {
        enable = true,
        swap_next = {
          ["<leader>a"] = "@parameter.inner",
        },
        swap_previous = {
          ["<leader>A"] = "@parameter.inner",
        },
      },
    },
  }
  EOF
<

                                    *nvim-treesitter-text-objects-move-submod*
Go to next/previous text object~

Define your own mappings to jump to the next or previous text object.
This is similar to |]m|, |[m|, |]M|, |[M| Neovim's mappings to jump to the next
or previous function.

Query files: `textobjects.scm`.
Supported options:
- enable: `true` or `false`.
- disable: list of languages.
- goto_next_start: map of keymaps to a tree-sitter capture group (`@function.outer`).
- goto_next_end: same as goto_next_start, but it jumps to the start of
  the text object.
- goto_previous_start: same as goto_next_start, but it jumps to the previous
  text object.
- goto_previous_end: same as goto_next_end, but it jumps to the previous
  text object.

>
  lua <<EOF
  require'nvim-treesitter.configs'.setup {
    textobjects = {
      move = {
        enable = true,
        goto_next_start = {
          ["]m"] = "@function.outer",
          ["]]"] = "@class.outer",
        },
        goto_next_end = {
          ["]M"] = "@function.outer",
          ["]["] = "@class.outer",
        },
        goto_previous_start = {
          ["[m"] = "@function.outer",
          ["[["] = "@class.outer",
        },
        goto_previous_end = {
          ["[M"] = "@function.outer",
          ["[]"] = "@class.outer",
        },
      },
    },
  }
  EOF
<

==============================================================================
USER QUERY EXTENSIONS                        *nvim-treesitter-query-extensions*

Queries are what `nvim-treesitter` uses to extract informations from the syntax tree, and they are
located in the `queries/{lang}/*` runtime directories (like the `queries` folder of this plugin).

`nvim-treesitter` considers queries as any runtime file (see `:h rtp`), that is :

- if the file is in any `after/queries/` folder, then it will be used to extend the already defined
  queries.
- Otherwise, it will be used as a base to define the query, the first query found (with the highest
  priority) will be the only one to be used.

This hybrid approach is the most standard way, and according to that, here is some ideas on how to
use is :
- If you want to rewrite (or write) a query, don't use `after/queries`.
- If you want to override a part of a query (only one match for example), use the `after/queries`
  directory.

==============================================================================
COMMANDS                                            *nvim-treesitter-commands*

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

Install one or more treesitter parsers.
You can use |:TSInstall| `all` to install all parsers.

                                                              *:TSInstallInfo*
:TSInstallInfo~

List informations about currently installed parsers

                                                                   *:TSUpdate*
:TSUpdate {language}~

Update the installed parser of {language} or all installed parsers
if {language} is omitted.

                                                                *:TSUninstall*
:TSUninstall {language}~

Deletes the parser for corresponding {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|

                                                             *:TSBufEnableAll*
:TSBufEnableAll {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|

                                                            *:TSBufDisableAll*
:TSBufDisableAll {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|

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

List modules state for the current session.

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

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

                                                *nvim_treesitter#statusline()*
nvim_treesitter#statusline(size)~

Returns a string describing the current position in the syntax tree. This
could be used as a statusline indicator.
Note: The `size` argument is optional. When specified, the string will not be
      longer than `size`.

                                                  *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 'foldnestmax' setting.

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*

`TSError`
                                                                  *hl-TSError*
For syntax/parser errors.

`TSPunctDelimiter`
                                                         *hl-TSPunctDelimiter*
For delimiters ie: `.`

`TSPunctBracket`
                                                           *hl-TSPunctBracket*
For brackets and parens.

`TSPunctSpecial`
                                                           *hl-TSPunctSpecial*
For special punctutation that does not fall in the catagories before.

`TSConstant`
                                                               *hl-TSConstant*
For constants

`TSConstBuiltin`
                                                           *hl-TSConstBuiltin*
For constant that are built in the language: `nil` in Lua.

`TSConstMacro`
                                                             *hl-TSConstMacro*
For constants that are defined by macros: `NULL` in C.

`TSString`
                                                                 *hl-TSString*
For strings.

`TSStringRegex`
                                                            *hl-TSStringRegex*
For regexes.

`TSStringEscape`
                                                           *hl-TSStringEscape*
For escape characters within a string.

`TSCharacter`
                                                              *hl-TSCharacter*
For characters.

`TSNumber`
                                                                 *hl-TSNumber*
For integers.

`TSBoolean`
                                                                *hl-TSBoolean*
For booleans.

`TSFloat`
                                                                  *hl-TSFloat*
For floats.

`TSFunction`
                                                               *hl-TSFunction*
For function (calls and definitions).

`TSFuncBuiltin`
                                                            *hl-TSFuncBuiltin*
For builtin functions: `table.insert` in Lua.

`TSFuncMacro`
                                                              *hl-TSFuncMacro*
For macro defined fuctions (calls and definitions): each `macro_rules` in
Rust.

`TSParameter`
                                                              *hl-TSParameter*
For parameters of a function.

`TSParameterReference`
                                                     *hl-TSParameterReference*
For references to parameters of a function.

`TSMethod`
                                                                 *hl-TSMethod*
For method calls and definitions.

`TSField`
                                                                  *hl-TSField*
For fields.

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

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

`TSConditional`
                                                            *hl-TSConditional*
For keywords related to conditionnals.

`TSRepeat`
                                                                 *hl-TSRepeat*
For keywords related to loops.

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

`TSOperator`
                                                               *hl-TSOperator*
For any operator: `+`, but also `->` and `*` in C.

`TSKeyword`
                                                                *hl-TSKeyword*
For keywords that don't fall in previous categories.

`TSKeywordFunction`
                                                        *hl-TSKeywordFunction*
For keywords used to define a fuction.

`TSException`
                                                              *hl-TSException*
For exception related keywords.

`TSType`
                                                                   *hl-TSType*
For types.

`TSTypeBuiltin`
                                                            *hl-TSTypeBuiltin*
For builtin types (you guessed it, right ?).

`TSStructure`
                                                              *hl-TSStructure*
This is left as an exercise for the reader.

`TSInclude`
                                                                *hl-TSInclude*
For includes: `#include` in C, `use` or `extern crate` in Rust, or `require`
in Lua.

`TSAnnotation`
                                                             *hl-TSAnnotation*
For C++/Dart attributes, annotations that can be attached to the code to
denote some kind of meta information.

`TSText`
                                                                   *hl-TSText*
For strings considered text in a markup language.

`TSStrong`
                                                                 *hl-TSStrong*
For text to be represented with strong.

`TSEmphasis`
                                                               *hl-TSEmphasis*
For text to be represented with emphasis.

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

`TSTitle`
                                                                  *hl-TSTitle*

Text that is part of a title.

`TSLiteral`
                                                                *hl-TSLiteral*
Literal text.

`TSURI`
                                                                    *hl-TSURI*
Any URI like a link or email.

`TSVariable`
                                                               *hl-TSVariable*
Any variable name that does not have another highlight.

`TSVariableBuiltin`
                                                        *hl-TSVariableBuiltin*
Variable names that are defined by the languages, like `this` or `self`.

==============================================================================
MODULE-HIGHLIGHTS                          *nvim-treesitter-module-highlights*

Apart from the general purpose highlights in |nvim-treesitter-highlights|,
some submodules use their own highlight groups to visualize additional
information.

`TSDefinition`
                                                              *hl-TSDefinition*
Used by refactor.highlight_definitions to highlight the definition of the
symbol under the cursor.

`TSDefinitionUsage`
                                                         *hl-TSDefinitionUsage*
Used by refactor.highlight_definitions to highlight usages of the symbol under
the cursor.

`TSCurrentScope`
                                                            *hl-TSCurrentScope*
Used by refactor.highlight_current_scope to highlight the current scope.

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