benbot/nvim-treesitter
1
0
Fork 0
mirror of https://github.com/nvim-treesitter/nvim-treesitter.git synced 2026-07-19 11:50:09 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Docs: documentation for modules/submodules

Browse source
This commit is contained in:
Santos Gallegos 2020-08-09 11:39:51 -05:00 • committed by Kiyan Yazdani
parent 393900b387
commit 7f81df4409
2 changed files with 694 additions and 311 deletions
Download patch file Download diff file Expand all files Collapse all files

392
README.md
View file

@ -1,7 +1,6 @@
![Linting and style checking](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Linting%20and%20style%20checking/badge.svg?branch=master) [![Zulip chat](https://img.shields.io/badge/zulip-join_chat-brightgreen.svg)](https://nvim-treesitter.zulipchat.com/)
![Check loading of syntax files](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Check%20loading%20of%20syntax%20files/badge.svg) [![Linting and style](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Linting%20and%20style%20checking/badge.svg?branch=master)](https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Linting+and+style+checking%22+branch%3Amaster)
[![Syntax files](https://github.com/nvim-treesitter/nvim-treesitter/workflows/Check%20loading%20of%20syntax%20files/badge.svg)](https://github.com/nvim-treesitter/nvim-treesitter/actions?query=workflow%3A%22Check+loading+of+syntax+files%22+branch%3Amaster)
[Join us on Zulip !](https://nvim-treesitter.zulipchat.com/join/1twnvjqumn0t97p65eragu5o/)
# nvim-treesitter # nvim-treesitter
@ -28,7 +27,7 @@ You can install `nvim-treesitter` with your favorite package manager, or using t
### Using a package manager ### Using a package manager
Simply add these lines to your `init.vim` : If you are using [vim-plug](https://github.com/junegunn/vim-plug), put this in your `init.vim` file:
```vim ```vim
Plug 'nvim-treesitter/nvim-treesitter' Plug 'nvim-treesitter/nvim-treesitter'
@ -53,7 +52,7 @@ provides two command to tackle this issue:
`TSInstall <tab>` will give you a list of supported languages, or select `all` to install them all. `TSInstall <tab>` will give you a list of supported languages, or select `all` to install them all.
- `TSInstallInfo` to know which parser is installed. - `TSInstallInfo` to know which parser is installed.
Let's say you need parsers for `lua`, this is how you do with these commands: Let's say you need parsers for `lua`, this is how you install it:
```vim ```vim
:TSInstall lua :TSInstall lua
@ -78,92 +77,198 @@ And now you should be ready to use every functionality `nvim-treesitter` provide
## Setup ## Setup
All modules are disabled by default, All modules are disabled by default,
so you'll need to activate them by putting this in your `init.vim`: so you'll need to activate them by putting this in your `init.vim` file:
```lua
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
```
Check [`:h nvim-treesitter-modules`](doc/nvim-treesitter.txt)
for a list of available modules and its options.
# Available Modules
## Highlight
Consistent syntax highlighting.
```lua ```lua
lua <<EOF lua <<EOF
require'nvim-treesitter.configs'.setup { require'nvim-treesitter.configs'.setup {
highlight = { highlight = {
enable = true, -- false will disable the whole extension enable = true,
disable = { "c", "rust" }, -- list of language that will be disabled custom_captures = {
custom_captures = { -- mapping of user defined captures to highlight groups -- Highlight the @foo.bar capture group with the "Identifier" highlight group.
-- ["foo.bar"] = "Identifier" -- highlight own capture @foo.bar with highlight group "Identifier", see :h nvim-treesitter-query-extensions ["foo.bar"] = "Identifier",
}, },
}, },
}
EOF
```
## Incremental selection
Incremental selection based on the named nodes from the grammar.
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
incremental_selection = { incremental_selection = {
enable = true, enable = true,
disable = { "cpp", "lua" }, keymaps = {
keymaps = { -- mappings for incremental selection (visual mappings) init_selection = "gnn",
init_selection = "gnn", -- maps in normal mode to init the node/scope selection node_incremental = "grn",
node_incremental = "grn", -- increment to the upper named parent scope_incremental = "grc",
scope_incremental = "grc", -- increment to the upper scope (as defined in locals.scm) node_decremental = "grm",
node_decremental = "grm", -- decrement to the previous node },
},
} }
}, EOF
```
## Refactor: highlight definitions
Highlights definition and usages of the current symbol under the cursor.
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
refactor = { refactor = {
highlight_definitions = { highlight_definitions = { enable = true },
enable = true
}, },
highlight_current_scope = { }
enable = true EOF
```
## Refactor: highlight current scope
Highlights the block from the current scope where the cursor is.
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
refactor = {
highlight_current_scope = { enable = true },
}, },
}
EOF
```
## Refactor: smart rename
Renames the symbol under the cursor within the current scope (and current file).
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
refactor = {
smart_rename = { smart_rename = {
enable = true, enable = true,
keymaps = { keymaps = {
smart_rename = "grr" -- mapping to rename reference under cursor smart_rename = "grr",
}
}, },
},
},
}
EOF
```
## Refactor: navigation
Provides "go to definition" for the symbol under the cursor,
and lists the definitions from the current file.
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
refactor = {
navigation = { navigation = {
enable = true, enable = true,
keymaps = { keymaps = {
goto_definition = "gnd", -- mapping to go to definition of symbol under cursor goto_definition = "gnd",
list_definitions = "gnD" -- mapping to list all definitions in current file list_definitions = "gnD",
}
}
}, },
textobjects = { -- syntax-aware textobjects },
},
}
EOF
```
## Text objects: select
Define your own text objects mappings
similar to `ip` (inner paragraph) and `ap` (a paragraph).
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
textobjects = {
select = {
enable = true, enable = true,
disable = {},
keymaps = { keymaps = {
["iL"] = { -- you can define your own textobjects directly here -- 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", python = "(function_definition) @function",
cpp = "(function_definition) @function", cpp = "(function_definition) @function",
c = "(function_definition) @function", c = "(function_definition) @function",
java = "(method_declaration) @function" java = "(method_declaration) @function",
}, },
-- or you use the queries from supported languages with textobjects.scm
["af"] = "@function.outer",
["if"] = "@function.inner",
["aC"] = "@class.outer",
["iC"] = "@class.inner",
["ac"] = "@conditional.outer",
["ic"] = "@conditional.inner",
["ae"] = "@block.outer",
["ie"] = "@block.inner",
["al"] = "@loop.outer",
["il"] = "@loop.inner",
["is"] = "@statement.inner",
["as"] = "@statement.outer",
["ad"] = "@comment.outer",
["am"] = "@call.outer",
["im"] = "@call.inner"
}, },
-- swap parameters (keymap -> textobject query) },
},
}
EOF
```
## Text objects: swap
Define your own mappings to swap the node under the cursor with the next or previous one,
like function parameters or arguments.
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
textobjects = {
swap = {
enable = true,
swap_next = { swap_next = {
["<a-p>"] = "@parameter.inner", ["<leader>a"] = "@parameter.inner",
}, },
swap_previous = { swap_previous = {
["<a-P>"] = "@parameter.inner", ["<leader>A"] = "@parameter.inner",
}, },
-- set mappings to go to start/end of adjacent textobjects (keymap -> textobject query)
goto_previous_start = {
["[m"] = "@function.outer",
["[["] = "@class.outer",
}, },
goto_previous_end = {
["[M"] = "@function.outer",
["[]"] = "@class.outer",
}, },
}
EOF
```
## Text objects: move
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.
```lua
lua <<EOF
require'nvim-treesitter.configs'.setup {
textobjects = {
move {
enable = true,
goto_next_start = { goto_next_start = {
["]m"] = "@function.outer", ["]m"] = "@function.outer",
["]]"] = "@class.outer", ["]]"] = "@class.outer",
@ -172,13 +277,37 @@ require'nvim-treesitter.configs'.setup {
["]M"] = "@function.outer", ["]M"] = "@function.outer",
["]["] = "@class.outer", ["]["] = "@class.outer",
}, },
goto_previous_start = {
["[m"] = "@function.outer",
["[["] = "@class.outer",
},
goto_previous_end = {
["[M"] = "@function.outer",
["[]"] = "@class.outer",
},
},
}, },
ensure_installed = "all" -- one of "all", "language", or a list of languages
} }
EOF EOF
``` ```
## Commands # Extra features
- Syntax based code folding
```vim
set foldmethod=expr
set foldexpr=nvim_treesitter#foldexpr()
```
- Statusline indicator
```vim
echo nvim_treesitter#statusline(90) " 90 can be any length
module->expression_statement->call->identifier
```
# Commands
Each feature can be enabled or disabled by different means: Each feature can be enabled or disabled by different means:
@ -190,77 +319,9 @@ Each feature can be enabled or disabled by different means:
:TSModuleInfo [{module}] " list information about modules state for each filetype :TSModuleInfo [{module}] " list information about modules state for each filetype
``` ```
## Features and Roadmap Check [`:h nvim-treesitter-commands`](doc/nvim-treesitter.txt) for a list of all available commands.
The goal of `nvim-treesitter` is both to provide a simple and easy way to use the interface for Treesitter in Neovim, # Supported Languages
but also to add some functionalities to it:
Some of these features are:
- [x] Incremental selection
- [x] Syntax based code folding (`set foldmethod=expr foldexpr=nvim_treesitter#foldexpr()`)
- [x] Consistent syntax highlighting (the api is not quite stable yet)
- [x] Statusline indicator (`require'nvim-treesitter'.statusline(size)`)
You can find the roadmap [here](https://github.com/nvim-treesitter/nvim-treesitter/projects/1).
The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!
## Available Modules
- `highlight`: Consistent syntax highlighting.
- `incremental_selection`: Syntax based selection.
- `refactor.highlight_definitions`: Syntax based definition and usage highlighting.
- `refactor.smart_rename`: Syntax based definition and usage renaming.
- `refactor.navigation`: Syntax based definition listing and navigation.
* List all definitions
* Go to definition
- `textobjects`: Vim textobjects defined by treesitter queries
## Defining Modules
Users and plugin authors can take advantage of modules by creating their own. Modules provide:
- Treesitter language detection support
- Attach and detach to buffers
- Works with all nvim-treesitter commands
You can use the `define_modules` function to define one or more modules or module groups.
```lua
require 'nvim-treesitter'.define_modules {
my_cool_plugin = {
attach = function(bufnr, lang)
-- Do cool stuff here
end,
detach = function(bufnr)
-- Undo cool stuff here
end,
is_supported = function(lang)
-- Check if the language is supported
end
}
}
```
Modules can consist of the following properties:
- `module_path`: A require path (string) that exports a module with an `attach` and `detach` function. This is not required if the functions are on this definition.
- `enable`: Determines if the module is enabled by default. This is usually overridden by the user.
- `disable`: A list of languages that this module is disabled for. This is usually overridden by the user.
- `is_supported`: A function that takes a language and determines if this module supports that language.
- `attach`: A function that attaches to a buffer. This is required if `module_path` is not provided.
- `detach`: A function that detaches from a buffer. This is required if `module_path` is not provided.
## Utils
You can get some utility functions with
```lua
local ts_utils = require 'nvim-treesitter.ts_utils'
```
More information is available in the help file (`:help nvim-treesitter-utils`).
## Supported Languages
For `nvim-treesitter` to work, we need to use query files such as those you can find in For `nvim-treesitter` to work, we need to use query files such as those you can find in
`queries/{lang}/{locals,highlights,textobjects}.scm` `queries/{lang}/{locals,highlights,textobjects}.scm`
@ -304,7 +365,60 @@ List of currently supported languages:
- [ ] vue - [ ] vue
- [ ] yaml - [ ] yaml
## User Query Extensions # Roadmap
The goal of `nvim-treesitter` is both to provide a simple and easy way to use the interface for Treesitter in Neovim,
but also to add some functionalities to it.
You can find the roadmap [here](https://github.com/nvim-treesitter/nvim-treesitter/projects/1).
The roadmap and all features of this plugin are open to change, and any suggestion will be highly appreciated!
# Defining Modules
Users and plugin authors can take advantage of modules by creating their own. Modules provide:
- Treesitter language detection support
- Attach and detach to buffers
- Works with all nvim-treesitter commands
You can use the `define_modules` function to define one or more modules or module groups.
```lua
require'nvim-treesitter'.define_modules {
my_cool_plugin = {
attach = function(bufnr, lang)
-- Do cool stuff here
end,
detach = function(bufnr)
-- Undo cool stuff here
end,
is_supported = function(lang)
-- Check if the language is supported
end
}
}
```
Modules can consist of the following properties:
- `module_path`: A require path (string) that exports a module with an `attach` and `detach` function. This is not required if the functions are on this definition.
- `enable`: Determines if the module is enabled by default. This is usually overridden by the user.
- `disable`: A list of languages that this module is disabled for. This is usually overridden by the user.
- `is_supported`: A function that takes a language and determines if this module supports that language.
- `attach`: A function that attaches to a buffer. This is required if `module_path` is not provided.
- `detach`: A function that detaches from a buffer. This is required if `module_path` is not provided.
# Utils
You can get some utility functions with
```lua
local ts_utils = require 'nvim-treesitter.ts_utils'
```
Check [`:h nvim-treesitter-utils`](doc/nvim-treesitter.txt) for more information.
# User Query Extensions
Queries are what `nvim-treesitter` uses to extract informations from the syntax tree, and they are 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). located in the `queries/{lang}/*` runtime directories (like the `queries` folder of this plugin).
@ -322,12 +436,12 @@ use is :
- If you want to override a part of a query (only one match for example), use the `after/queries` - If you want to override a part of a query (only one match for example), use the `after/queries`
directory. directory.
## Troubleshooting # Troubleshooting
Before doing anything make sure you have the latest version of this plugin and run `:checkhealth nvim_treesitter`. Before doing anything make sure you have the latest version of this plugin and run `:checkhealth nvim_treesitter`.
This will help you find where the bug might come from. This will help you find where the bug might come from.
### Feature `X` does not work for `{language}`... ## Feature `X` does not work for `{language}`...
First, check the `## {language} parser healthcheck` section of `:checkhealth` if you have any warning. First, check the `## {language} parser healthcheck` section of `:checkhealth` if you have any warning.
If you do, it's highly possible that this is the cause of the problem. If you do, it's highly possible that this is the cause of the problem.
@ -335,14 +449,22 @@ If everything is okay, then it might be an actual error.
In both cases, feel free to [open an issue here](https://github.com/nvim-treesitter/nvim-treesitter/issues/new/choose). In both cases, feel free to [open an issue here](https://github.com/nvim-treesitter/nvim-treesitter/issues/new/choose).
### I get `Error detected while processing .../plugin/nvim-treesitter.vim` everytime I open Neovim ### While typing my code is marked as red
You can deactivate highlighting of syntax errors by adding this to your `init.vim` file:
```vim
highlight link TSError Normal
```
## I get `Error detected while processing .../plugin/nvim-treesitter.vim` every time I open Neovim
This is probably due to a change in a parser's grammar or its queries. This is probably due to a change in a parser's grammar or its queries.
Try updating the parser that you suspect has changed (`:TSUpdate {language}`) or all of them (`:TSUpdate`). Try updating the parser that you suspect has changed (`:TSUpdate {language}`) or all of them (`:TSUpdate`).
If the error persists after updating all parsers, If the error persists after updating all parsers,
please [open an issue](https://github.com/nvim-treesitter/nvim-treesitter/issues/new/choose). please [open an issue](https://github.com/nvim-treesitter/nvim-treesitter/issues/new/choose).
### I experience weird highlighting issues similar to [#78](https://github.com/nvim-treesitter/nvim-treesitter/issues/78) ## I experience weird highlighting issues similar to [#78](https://github.com/nvim-treesitter/nvim-treesitter/issues/78)
This is a well known issue, which arise when the tree and the buffer are getting out of sync. This is a well known issue, which arise when the tree and the buffer are getting out of sync.
As this issue comes from upstream, we don't have any finite fix. To get around this, you can force reparsing the buffer with this command: As this issue comes from upstream, we don't have any finite fix. To get around this, you can force reparsing the buffer with this command:

379
doc/nvim-treesitter.txt
View file

@ -2,13 +2,18 @@
Minimum version of neovim: nightly Minimum version of neovim: nightly
Authors: Yazdani Kiyan <yazdani.kiyan@protonmail.com>, Vigouroux Thomas <tomvig38@gmail.com> 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* INTRODUCTION *nvim-treesitter-intro*
nvim-treesitter wraps the neovim treesitter api to provide functionnalities such nvim-treesitter wraps the Neovim treesitter API to provide functionnalities
as highlighting and incremental selection, and a command to easily install parsers. such as highlighting and incremental selection, and a command to easily
install parsers.
============================================================================== ==============================================================================
QUICK START *nvim-treesitter-quickstart* QUICK START *nvim-treesitter-quickstart*
@ -25,92 +30,340 @@ To get a list of supported languages
:TSInstallInfo :TSInstallInfo
< <
By default, everything is disabled. To enable support for features, in your `init.vim`: 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 lua <<EOF
require'nvim-treesitter.configs'.setup { require'nvim-treesitter.configs'.setup {
highlight = { highlight = {
enable = true, -- false will disable the whole extension
disable = { "c", "rust" }, -- list of language that will be disabled
custom_captures = { -- mapping of user defined captures to highlight groups
-- ["foo.bar"] = "Identifier" -- highlight own capture @foo.bar with highlight group "Identifier", see :h nvim-treesitter-query-extensions
},
},
incremental_selection = {
enable = true, enable = true,
disable = { "cpp", "lua" }, disable = { "cpp", "lua" },
keymaps = { -- mappings for incremental selection (visual mappings) },
init_selection = 'gnn', -- maps in normal mode to init the node/scope selection
node_incremental = "grn", -- increment to the upper named parent
scope_incremental = "grc", -- increment to the upper scope (as defined in locals.scm)
node_decremental = "grm", -- decrement to the previous node
} }
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 = { refactor = {
highlight_definitions = { highlight_definitions = { enable = true },
enable = true
}, },
highlight_current_scope = { }
enable = true EOF
<
*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 = { smart_rename = {
enable = true, enable = true,
keymaps = { keymaps = {
smart_rename = "grr" -- mapping to rename reference under cursor 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`.
- list_definitions: list all definitions from the current file.
Defaults to `gnD`.
>
lua <<EOF
require'nvim-treesitter.configs'.setup {
refactor = {
navigation = { navigation = {
enable = true, enable = true,
keymaps = { keymaps = {
goto_definition = "gnd", -- mapping to go to definition of symbol under cursor goto_definition = "gnd",
list_definitions = "gnD" -- mapping to list all definitions in current file list_definitions = "gnD",
}
}
}, },
textobjects = { -- syntax-aware textobjects },
},
}
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, enable = true,
disable = {},
keymaps = { keymaps = {
["iL"] = { -- you can define your own textobjects directly here -- 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", python = "(function_definition) @function",
cpp = "(function_definition) @function", cpp = "(function_definition) @function",
c = "(function_definition) @function", c = "(function_definition) @function",
java = "(method_declaration) @function" java = "(method_declaration) @function",
}, },
-- or you use the queries from supported languages with textobjects.scm
["af"] = "@function.outer",
["if"] = "@function.inner",
["aC"] = "@class.outer",
["iC"] = "@class.inner",
["ac"] = "@conditional.outer",
["ic"] = "@conditional.inner",
["ae"] = "@block.outer",
["ie"] = "@block.inner",
["al"] = "@loop.outer",
["il"] = "@loop.inner",
["is"] = "@statement.inner",
["as"] = "@statement.outer",
["ad"] = "@comment.outer",
["am"] = "@call.outer",
["im"] = "@call.inner"
}, },
-- swap parameters (keymap -> textobject query) },
},
}
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 = { swap_next = {
["<a-p>"] = "@parameter.inner", ["<leader>a"] = "@parameter.inner",
}, },
swap_previous = { swap_previous = {
["<a-P>"] = "@parameter.inner", ["<leader>A"] = "@parameter.inner",
}, },
-- set mappings to go to start/end of adjacent textobjects (keymap -> textobject query)
goto_previous_start = {
["[m"] = "@function.outer",
["[["] = "@class.outer",
}, },
goto_previous_end = {
["[M"] = "@function.outer",
["[]"] = "@class.outer",
}, },
}
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 = { goto_next_start = {
["]m"] = "@function.outer", ["]m"] = "@function.outer",
["]]"] = "@class.outer", ["]]"] = "@class.outer",
@ -119,8 +372,16 @@ By default, everything is disabled. To enable support for features, in your `ini
["]M"] = "@function.outer", ["]M"] = "@function.outer",
["]["] = "@class.outer", ["]["] = "@class.outer",
}, },
goto_previous_start = {
["[m"] = "@function.outer",
["[["] = "@class.outer",
},
goto_previous_end = {
["[M"] = "@function.outer",
["[]"] = "@class.outer",
},
},
}, },
ensure_installed = "all" -- one of "all", "language", or a list of languages
} }
EOF EOF
< <
@ -260,7 +521,7 @@ nvim_treesitter#statusline(size)~
Returns a string describing the current position in the syntax tree. This Returns a string describing the current position in the syntax tree. This
could be used as a statusline indicator. could be used as a statusline indicator.
Note: The `size` argument is optionnal. When specified, the string will not be Note: The `size` argument is optional. When specified, the string will not be
longer than `size`. longer than `size`.
*nvim_treesitter#foldexpr()* *nvim_treesitter#foldexpr()*
@ -475,4 +736,4 @@ the cursor.
*hl-TSCurrentScope* *hl-TSCurrentScope*
Used by refactor.highlight_current_scope to highlight the current scope. Used by refactor.highlight_current_scope to highlight the current scope.
vim:tw=78:ts=8:noet:ft=help:norl: vim:tw=78:ts=8:expandtab:noet:ft=help:norl: