benbot/nvim-treesitter
1
0
Fork 0
mirror of https://github.com/nvim-treesitter/nvim-treesitter.git synced 2026-07-01 11:06:54 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions
nvim-treesitter/doc/nvim-treesitter.txt

711 lines
19 KiB
Text
Raw Blame History

*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 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 = "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` 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|.
- 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 informations 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*
*hl-TSAnnotation*
`TSAnnotation`
For C++/Dart attributes, annotations that can be attached to the code to
denote some kind of meta information.
*hl-TSAttribute*
`TSAttribute`
(unstable) TODO: docs
*hl-TSBoolean*
`TSBoolean`
For booleans.
*hl-TSCharacter*
`TSCharacter`
For characters.
*hl-TSComment*
`TSComment`
For comment blocks.
*hl-TSConditional*
`TSConditional`
For keywords related to conditionnals.
*hl-TSConstant*
`TSConstant`
For constants
*hl-TSConstBuiltin*
`TSConstBuiltin`
For constant that are built in the language: `nil` in Lua.
*hl-TSConstMacro*
`TSConstMacro`
For constants that are defined by macros: `NULL` in C.
*hl-TSConstructor*
`TSConstructor`
For constructor calls and definitions: `{}` in Lua, and Java constructors.
*hl-TSError*
`TSError`
For syntax/parser errors.
*hl-TSException*
`TSException`
For exception related keywords.
*hl-TSField*
`TSField`
For fields.
*hl-TSFloat*
`TSFloat`
For floats.
*hl-TSFunction*
`TSFunction`
For function (calls and definitions).
*hl-TSFuncBuiltin*
`TSFuncBuiltin`
For builtin functions: `table.insert` in Lua.
*hl-TSFuncMacro*
`TSFuncMacro`
For macro defined fuctions (calls and definitions): each `macro_rules` in
Rust.
*hl-TSInclude*
`TSInclude`
For includes: `#include` in C, `use` or `extern crate` in Rust, or `require`
in Lua.
*hl-TSKeyword*
`TSKeyword`
For keywords that don't fall in previous categories.
*hl-TSKeywordFunction*
`TSKeywordFunction`
For keywords used to define a fuction.
*hl-TSKeywordOperator*
`TSKeywordOperator`
for operators that are English words, e.g. `and`, `as`, `or`.
*hl-TSKeywordReturn*
`TSKeywordReturn`
for the `return` and `yield` keywords.
*hl-TSLabel*
`TSLabel`
For labels: `label:` in C and `:label:` in Lua.
*hl-TSMethod*
`TSMethod`
For method calls and definitions.
*hl-TSNamespace*
`TSNamespace`
For identifiers referring to modules and namespaces.
*hl-None*
`TSNone`
For no highlighting.
*hl-TSNumber*
`TSNumber`
For all numbers
*hl-TSOperator*
`TSOperator`
For any operator: `+`, but also `->` and `*` in C.
*hl-TSParameter*
`TSParameter`
For parameters of a function.
*hl-TSParameterReference*
`TSParameterReference`
For references to parameters of a function.
*hl-TSProperty*
`TSProperty`
Same as `TSField`.
*hl-TSPunctDelimiter*
`TSPunctDelimiter`
For delimiters ie: `.`
*hl-TSPunctBracket*
`TSPunctBracket`
For brackets and parens.
*hl-TSPunctSpecial*
`TSPunctSpecial`
For special punctutation that does not fall in the catagories before.
*hl-TSRepeat*
`TSRepeat`
For keywords related to loops.
*hl-TSString*
`TSString`
For strings.
*hl-TSStringRegex*
`TSStringRegex`
For regexes.
*hl-TSStringEscape*
`TSStringEscape`
For escape characters within a string.
*hl-TSStringSpecial*
`TSStringSpecial`
For strings with special meaning that don't fit into the above categories.
*hl-TSSymbol*
`TSSymbol`
For identifiers referring to symbols or atoms.
*hl-TSTag*
`TSTag`
Tags like html tag names.
*hl-TSTagAttribute*
`TSTagAttribute`
For html tag attributes.
*hl-TSTagDelimiter*
`TSTagDelimiter`
Tag delimiter like `<` `>` `/`
*hl-TSText*
`TSText`
For strings considered text in a markup language.
*hl-TSSTrong*
`TSStrong`
For text to be represented in bold.
*hl-TSEmphasis*
`TSEmphasis`
For text to be represented with emphasis.
*hl-TSUnderline*
`TSUnderline`
For text to be represented with an underline.
*hl-TSStrike*
`TSStrike`
For strikethrough text.
*hl-TSTitle*
`TSTitle`
Text that is part of a title.
*hl-TSLiteral*
`TSLiteral`
Literal text.
*hl-TSURI*
`TSURI`
Any URI like a link or email.
*hl-TSMath*
`TSMath`
For LaTex-like math environments.
*hl-TSTextReference*
`TSTextReference`
For footnotes, text references, citations.
*hl-TSEnvironment*
`TSEnvironment`
For text environments of markup languages.
*hl-TSEnvironmentName*
`TSEnvironmentName`
For the name/the string indicating the type of text environment.
*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`
For types.
*hl-TSTypeBuiltin*
`TSTypeBuiltin`
For builtin types.
*hl-TSVariable*
`TSVariable`
Any variable name that does not have another highlight.
*hl-TSVariableBuiltin*
`TSVariableBuiltin`
Variable names that are defined by the languages, like `this` or `self`.
==============================================================================
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:
Reference in a new issue View git blame Copy permalink