mirror of
https://github.com/nvim-treesitter/nvim-treesitter.git
synced 2026-07-01 19:17:02 -04:00
428 lines
11 KiB
Text
428 lines
11 KiB
Text
*nvim-treesitter*
|
|
|
|
Minimum version of neovim: nightly
|
|
|
|
Authors: Yazdani Kiyan <yazdani.kiyan@protonmail.com>, Vigouroux Thomas <tomvig38@gmail.com>
|
|
|
|
==============================================================================
|
|
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 support for features, in your `init.vim`:
|
|
|
|
>
|
|
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
|
|
}
|
|
}
|
|
},
|
|
textobjects = { -- syntax-aware textobjects
|
|
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"
|
|
}
|
|
},
|
|
ensure_installed = 'all' -- one of 'all', 'language', or a list of languages
|
|
}
|
|
EOF
|
|
<
|
|
|
|
==============================================================================
|
|
USER QUERY EXTENSIONS *nvim-treesitter-query-extensions*
|
|
|
|
You can add your own query files by placing a query file in vim's runtime path
|
|
after `nvim-treesitter` is sourced. If the language has a built in query file,
|
|
that file will be appended to or it will be used (useful for languages not yet
|
|
supported).
|
|
|
|
For example, you can add files to `<vim-config-dir>/after/queries/lua/highlights.scm`
|
|
to add more queries to lua highlights. You can also manually add query paths
|
|
to the runtime path by adding this to your vim config `set rtp+='path/to/queries'`.
|
|
|
|
|
|
==============================================================================
|
|
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
|
|
|
|
*: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.containing_scope*
|
|
containing_scope(node)~
|
|
|
|
Returns the smallest scope containing the node.
|
|
|
|
*ts_utils.parent_scope*
|
|
parent_scope(node, cursor_pos)~
|
|
|
|
Returns the parent scope of the current scope that contains the node.
|
|
`cursor_pos` should be `{ row = number, col = number }`
|
|
|
|
*ts_utils.nested_scope*
|
|
nested_scope(node, cursor_pos)~
|
|
|
|
Returns the first scope within current scope that contains the node.
|
|
`cursor_pos` should be `{ row = number, col = number }`
|
|
|
|
*ts_utils.next_scope*
|
|
next_scope(node)~
|
|
|
|
Returns the neighbour scope of the current node.
|
|
|
|
*ts_utils.previous_scope*
|
|
previous_scope(node)~
|
|
|
|
Returns the previous neighbour scope of the current node.
|
|
|
|
==============================================================================
|
|
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 optionnal. 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#foldexr()
|
|
<
|
|
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.
|
|
|
|
You can deactivate highlighting of syntax errors by adding this to your
|
|
init.vim: >
|
|
highlight link TSError Normal
|
|
|
|
`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.
|
|
|
|
`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.
|
|
|
|
`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
|
|
|
|
`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`
|
|
|
|
Text that is part of a title.
|
|
|
|
`TSLiteral`
|
|
*hl-TSLiteral*
|
|
Literal text.
|
|
|
|
`TSURI`
|
|
*hl-TSURI*
|
|
Any URI like a link or email.
|
|
|
|
vim:tw=78:ts=8:noet:ft=help:norl:
|