aboutsummaryrefslogtreecommitdiffstats
path: root/doc/nvim-treesitter.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/nvim-treesitter.txt')
-rw-r--r--doc/nvim-treesitter.txt571
1 files changed, 416 insertions, 155 deletions
diff --git a/doc/nvim-treesitter.txt b/doc/nvim-treesitter.txt
index 096d8698c..bc70d6d6c 100644
--- a/doc/nvim-treesitter.txt
+++ b/doc/nvim-treesitter.txt
@@ -2,16 +2,21 @@
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
-as highlighting and incremental selection, and a command to easily install parsers.
+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*
+QUICK START *nvim-treesitter-quickstart*
Install the parser for your language
@@ -25,108 +30,364 @@ To get a list of supported languages
: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 {
- 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,
- 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
- }
- },
- refactor = {
- highlight_definitions = {
- enable = true
- },
- highlight_current_scope = {
- enable = true
- },
- smart_rename = {
- enable = true,
- keymaps = {
- smart_rename = "grr" -- mapping to rename reference under cursor
- }
- },
- navigation = {
- enable = true,
- keymaps = {
- goto_definition = "gnd", -- mapping to go to definition of symbol under cursor
- list_definitions = "gnD" -- mapping to list all definitions in current file
- }
- }
+ 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",
},
- textobjects = { -- syntax-aware textobjects
+ },
+ }
+ 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,
- disable = {},
keymaps = {
- ["iL"] = { -- you can define your own textobjects directly here
- python = "(function_definition) @function",
- cpp = "(function_definition) @function",
- c = "(function_definition) @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)
- swap_next = {
- ["<a-p>"] = "@parameter.inner",
- },
- swap_previous = {
- ["<a-P>"] = "@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",
- },
- goto_next_start = {
- ["]m"] = "@function.outer",
- ["]]"] = "@class.outer",
- },
- goto_next_end = {
- ["]M"] = "@function.outer",
- ["]["] = "@class.outer",
- },
+ 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
+<
+
+ *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`.
+ - list_definitions: list all definitions from the current file.
+ Defaults to `gnD`.
+
+>
+ lua <<EOF
+ require'nvim-treesitter.configs'.setup {
+ refactor = {
+ navigation = {
+ enable = true,
+ keymaps = {
+ goto_definition = "gnd",
+ list_definitions = "gnD",
+ },
+ },
+ },
+ }
+ 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",
+ },
},
- ensure_installed = "all" -- one of "all", "language", or a list of languages
+ },
}
EOF
<
==============================================================================
-USER QUERY EXTENSIONS *nvim-treesitter-query-extensions*
+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).
@@ -145,44 +406,44 @@ use is :
directory.
==============================================================================
-COMMANDS *nvim-treesitter-commands*
+COMMANDS *nvim-treesitter-commands*
- *:TSInstall*
+ *:TSInstall*
:TSInstall| {language} ...~
Install one or more treesitter parsers.
You can use |:TSInstall| `all` to install all parsers.
- *:TSInstallInfo*
+ *:TSInstallInfo*
:TSInstallInfo~
List informations about currently installed parsers
- *:TSUpdate*
+ *:TSUpdate*
:TSUpdate {language}~
Update the installed parser of {language} or all installed parsers
if {language} is omitted.
- *:TSUninstall*
+ *:TSUninstall*
:TSUninstall {language}~
Deletes the parser for corresponding {language}. You can use 'all' for
language to uninstall all parsers.
- *:TSBufEnable*
+ *:TSBufEnable*
:TSBufEnable {module}~
Enable {module} on the current buffer.
A list of modules can be found at |:TSModuleInfo|
- *:TSBufDisable*
+ *:TSBufDisable*
:TSBufDisable {module}~
Disable {module} on the current buffer
A list of modules can be found at |:TSModuleInfo|
- *:TSBufEnableAll*
+ *:TSBufEnableAll*
:TSBufEnableAll {module} [{language}]~
Enable {module} for the session
@@ -191,7 +452,7 @@ particular language.
A list of modules can be found at |:TSModuleInfo|
A list of languages can be found at |:TSInstallInfo|
- *:TSBufDisableAll*
+ *:TSBufDisableAll*
:TSBufDisableAll {module} [{language}]~
Disable {module} for the session
@@ -200,42 +461,42 @@ particular language.
A list of modules can be found at |:TSModuleInfo|
A list of languages can be found at |:TSInstallInfo|
- *:TSModuleInfo*
+ *:TSModuleInfo*
:TSModuleInfo [{module}]~
List modules state for the current session.
==============================================================================
-UTILS *nvim-treesitter-utils*
+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*
+ *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*
+ *ts_utils.get_node_text*
get_node_text(node, bufnr)~
Returns the text content of a `node`.
- *ts_utils.is_parent*
+ *ts_utils.is_parent*
is_parent(dest, source)~
Determines whether `dest` is a parent of `source`.
Returns a boolean.
- *ts_utils.get_named_children*
+ *ts_utils.get_named_children*
get_named_children(node)~
Returns a table of named children of `node`.
- *ts_utilsiget_next_node*
+ *ts_utilsiget_next_node*
get_next_node(node, allow_switch_parent, allow_next_parent)~
Returns the next node within the same parent.
@@ -245,7 +506,7 @@ 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*
+ *ts_utils.get_previous_node*
get_previous_node(node, allow_switch_parents, allow_prev_parent)~
Returns the previous node within the same parent.
@@ -255,15 +516,15 @@ as |ts_utils.get_next_node| but if the node is the first node.
==============================================================================
FUNCTIONS *nvim-treesitter-functions*
- *nvim_treesitter#statusline()*
+ *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 optionnal. When specified, the string will not be
+Note: The `size` argument is optional. When specified, the string will not be
longer than `size`.
- *nvim_treesitter#foldexpr()*
+ *nvim_treesitter#foldexpr()*
nvim_treesitter#foldexpr()~
Functions to be used to determine the fold level at a given line number.
@@ -279,7 +540,7 @@ Note: This is highly experimental, and folding can break on some types of
HIGHLIGHTS *nvim-treesitter-highlights*
`TSError`
- *hl-TSError*
+ *hl-TSError*
For syntax/parser errors.
You can deactivate highlighting of syntax errors by adding this to your
@@ -287,112 +548,112 @@ init.vim: >
highlight link TSError Normal
`TSPunctDelimiter`
- *hl-TSPunctDelimiter*
+ *hl-TSPunctDelimiter*
For delimiters ie: `.`
`TSPunctBracket`
- *hl-TSPunctBracket*
+ *hl-TSPunctBracket*
For brackets and parens.
`TSPunctSpecial`
- *hl-TSPunctSpecial*
+ *hl-TSPunctSpecial*
For special punctutation that does not fall in the catagories before.
`TSConstant`
- *hl-TSConstant*
+ *hl-TSConstant*
For constants
`TSConstBuiltin`
- *hl-TSConstBuiltin*
+ *hl-TSConstBuiltin*
For constant that are built in the language: `nil` in Lua.
`TSConstMacro`
- *hl-TSConstMacro*
+ *hl-TSConstMacro*
For constants that are defined by macros: `NULL` in C.
`TSString`
- *hl-TSString*
+ *hl-TSString*
For strings.
`TSStringRegex`
- *hl-TSStringRegex*
+ *hl-TSStringRegex*
For regexes.
`TSStringEscape`
- *hl-TSStringEscape*
+ *hl-TSStringEscape*
For escape characters within a string.
`TSCharacter`
- *hl-TSCharacter*
+ *hl-TSCharacter*
For characters.
`TSNumber`
- *hl-TSNumber*
+ *hl-TSNumber*
For integers.
`TSBoolean`
- *hl-TSBoolean*
+ *hl-TSBoolean*
For booleans.
`TSFloat`
- *hl-TSFloat*
+ *hl-TSFloat*
For floats.
`TSFunction`
- *hl-TSFunction*
+ *hl-TSFunction*
For function (calls and definitions).
`TSFuncBuiltin`
- *hl-TSFuncBuiltin*
+ *hl-TSFuncBuiltin*
For builtin functions: `table.insert` in Lua.
`TSFuncMacro`
- *hl-TSFuncMacro*
+ *hl-TSFuncMacro*
For macro defined fuctions (calls and definitions): each `macro_rules` in
Rust.
`TSParameter`
- *hl-TSParameter*
+ *hl-TSParameter*
For parameters of a function.
`TSParameterReference`
- *hl-TSParameterReference*
+ *hl-TSParameterReference*
For references to parameters of a function.
`TSMethod`
- *hl-TSMethod*
+ *hl-TSMethod*
For method calls and definitions.
`TSField`
- *hl-TSField*
+ *hl-TSField*
For fields.
`TSProperty`
- *hl-TSProperty*
+ *hl-TSProperty*
Same as `TSField`.
`TSConstructor`
- *hl-TSConstructor*
+ *hl-TSConstructor*
For constructor calls and definitions: `{}` in Lua, and Java constructors.
`TSConditional`
- *hl-TSConditional*
+ *hl-TSConditional*
For keywords related to conditionnals.
`TSRepeat`
- *hl-TSRepeat*
+ *hl-TSRepeat*
For keywords related to loops.
`TSLabel`
- *hl-TSLabel*
+ *hl-TSLabel*
For labels: `label:` in C and `:label:` in Lua.
`TSOperator`
- *hl-TSOperator*
+ *hl-TSOperator*
For any operator: `+`, but also `->` and `*` in C.
`TSKeyword`
- *hl-TSKeyword*
+ *hl-TSKeyword*
For keywords that don't fall in previous categories.
`TSKeywordFunction`
@@ -400,23 +661,23 @@ For keywords that don't fall in previous categories.
For keywords used to define a fuction.
`TSException`
- *hl-TSException*
+ *hl-TSException*
For exception related keywords.
`TSType`
- *hl-TSType*
+ *hl-TSType*
For types.
`TSTypeBuiltin`
- *hl-TSTypeBuiltin*
+ *hl-TSTypeBuiltin*
For builtin types (you guessed it, right ?).
`TSStructure`
- *hl-TSStructure*
+ *hl-TSStructure*
This is left as an exercise for the reader.
`TSInclude`
- *hl-TSInclude*
+ *hl-TSInclude*
For includes: `#include` in C, `use` or `extern crate` in Rust, or `require`
in Lua.
@@ -426,32 +687,32 @@ For C++/Dart attributes, annotations that can be attached to the code to
denote some kind of meta information.
`TSText`
- *hl-TSText*
+ *hl-TSText*
For strings considered text in a markup language.
`TSStrong`
- *hl-TSStrong*
+ *hl-TSStrong*
For text to be represented with strong.
`TSEmphasis`
- *hl-TSEmphasis*
+ *hl-TSEmphasis*
For text to be represented with emphasis.
`TSUnderline`
- *hl-TSUnderline*
+ *hl-TSUnderline*
For text to be represented with an underline.
`TSTitle`
- *hl-TSTitle*
+ *hl-TSTitle*
Text that is part of a title.
`TSLiteral`
- *hl-TSLiteral*
+ *hl-TSLiteral*
Literal text.
`TSURI`
- *hl-TSURI*
+ *hl-TSURI*
Any URI like a link or email.
==============================================================================
@@ -475,4 +736,4 @@ the cursor.
*hl-TSCurrentScope*
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:
generated by cgit v1.2.3-70-g09d2 (git 2.52.0) at 2026-01-01 21:00:54 +0000