Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
tree-sitter
library for incremental parsing of buffers:
https://tree-sitter.github.io/tree-sitter/parser
runtime directory. By default, Nvim bundles parsers
for C, Lua, Vimscript, Vimdoc and Treesitter query files, but parsers can be
installed manually or via a plugin like
https://github.com/nvim-treesitter/nvim-treesitter. Parsers are searched for
as parser/{lang}.*
in any 'runtimepath' directory. If multiple parsers for
the same language are found, the first one is used. (This typically implies
the priority "user config > plugins > bundled".
A parser can also be loaded manually using a full path:vim.treesitter.language.add('python', { path = "/path/to/python.so" })
TSTree
TSTree
of a treesitter tree supports the following methods.TSTree:root()
Return the root node of this tree.TSTree:copy()
Returns a copy of the TSTree
.TSNode
TSNode
of a treesitter node supports the following methods.TSNode:parent()
Get the node's immediate parent.TSNode:next_sibling()
Get the node's next sibling.TSNode:prev_sibling()
Get the node's previous sibling.TSNode:next_named_sibling()
Get the node's next named sibling.TSNode:prev_named_sibling()
Get the node's previous named sibling.TSNode:iter_children()
Iterates over all the direct children of {TSNode}
, regardless of whether
they are named or not.
Returns the child node plus the eventual field name corresponding to this
child node.TSNode:child_count()
Get the node's number of children.{index}
) TSNode:child()
Get the node's child at the given {index}
, where zero represents the first
child.TSNode:named_child_count()
Get the node's number of named children.{index}
) TSNode:named_child()
Get the node's named child at the given {index}
, where zero represents the
first named child.TSNode:start()
Get the node's start position. Return three values: the row, column and
total byte count (all zero-based).TSNode:end_()
Get the node's end position. Return three values: the row, column and
total byte count (all zero-based).{include_bytes}
) TSNode:range()
Get the range of the node.{include_bytes}
is true
)
{include_bytes}
is true
)
TSNode:type()
Get the node's type as a string.TSNode:symbol()
Get the node's type as a numerical id.TSNode:named()
Check if the node is named. Named nodes correspond to named rules in the
grammar, whereas anonymous nodes correspond to string literals in the
grammar.TSNode:missing()
Check if the node is missing. Missing nodes are inserted by the parser in
order to recover from certain kinds of syntax errors.TSNode:extra()
Check if the node is extra. Extra nodes represent things like comments,
which are not required by the grammar but can appear anywhere.TSNode:has_changes()
Check if a syntax node has been edited.TSNode:has_error()
Check if the node is a syntax error or contains any syntax errors.TSNode:sexpr()
Get an S-expression representing the node as a string.TSNode:id()
Get an unique identifier for the node inside its own tree.id
is not guaranteed to be unique for nodes from different
trees.TSNode:tree()
Get the TSTree of the node.
TSNode:descendant_for_range()
TSNode:descendant_for_range({start_row}
, {start_col}
, {end_row}
, {end_col}
)
Get the smallest node within this node that spans the given range of (row,
column) positionsTSNode:named_descendant_for_range()
TSNode:named_descendant_for_range({start_row}
, {start_col}
, {end_row}
, {end_col}
)
Get the smallest named node within this node that spans the given range of
(row, column) positions
TSNode:equal()
TSNode:equal({node}
)
Check if {node}
refers to the same node within the same tree.query
consists of one or
more patterns. A pattern
is defined over node types in the syntax tree. A
match
corresponds to specific elements of the syntax tree which match a
pattern. Patterns may optionally define captures and predicates. A capture
allows you to associate names with a specific node in a pattern. A predicate
adds arbitrary metadata and conditional data to a match.*.scm
files in a queries
directory under
runtimepath
, where each file contains queries for a specific language and
purpose, e.g., queries/lua/highlights.scm
for highlighting Lua files.
By default, the first query on runtimepath
is used (which usually implies
that user config takes precedence over plugins, which take precedence over
queries bundled with Nvim). If a query should extend other queries instead
of replacing them, use treesitter-query-modeline-extends.eq?
predicate can be used as follows:((identifier) @foo (#eq? @foo "foo"))
"foo"
text.eq?
treesitter-predicate-eq?
Match a string against the text corresponding to a node:((identifier) @foo (#eq? @foo "foo"))
((node1) @left (node2) @right (#eq? @left @right))
match?
treesitter-predicate-match?
vim-match?
treesitter-predicate-vim-match?
Match a regexp against the text corresponding to a node:((identifier) @constant (#match? @constant "^[A-Z_]+$"))
^
and $
anchors will match the start and end of the
node's text.lua-match?
treesitter-predicate-lua-match?
Match lua-patterns against the text corresponding to a node,
similar to match?
contains?
treesitter-predicate-contains?
Match a string against parts of the text corresponding to a node:((identifier) @foo (#contains? @foo "foo"))
((identifier) @foo-bar (#contains? @foo-bar "foo" "bar"))
any-of?
treesitter-predicate-any-of?
Match any of the given strings against the text corresponding to
a node:((identifier) @foo (#any-of? @foo "foo" "bar"))
has-ancestor?
treesitter-predicate-has-ancestor?
Match any of the given node types against all ancestors of a node:((identifier) @variable.builtin
(#any-of? @variable.builtin "begin" "end")
(#has-ancestor? @variable.builtin range_expression))
has-parent?
treesitter-predicate-has-parent?
Match any of the given node types against the direct ancestor of a
node:(((field_expression
(field_identifier) @method)) @_parent
(#has-parent? @_parent template_method function_declarator))
lua-treesitter-not-predicate
Each predicate has a not-
prefixed predicate that is just the negation of
the predicate.set!
directive sets metadata on the match or node:((identifier) @foo (#set! "type" "parameter"))
set!
treesitter-directive-set!
Sets key/value metadata for a specific match or capture. Value is
accessible as either metadata[key]
(match specific) or
metadata[capture_id][key]
(capture specific).{capture_id}
(optional)
{key}
{value}
((identifier) @foo (#set! @foo "kind" "parameter"))
((node1) @left (node2) @right (#set! "type" "pair"))
offset!
treesitter-directive-offset!
Takes the range of the captured node and applies an offset. This will
generate a new range object for the captured node as
metadata[capture_id].range
.{capture_id}
{start_row}
{start_col}
{end_row}
{end_col}
((identifier) @constant (#offset! @constant 0 1 0 -1))
gsub!
treesitter-directive-gsub!
Transforms the content of the node using a Lua pattern. This will set
a new metadata[capture_id].text
.{capture_id}
{pattern}
(#gsub! @_node ".*%.(.*)" "%1")
trim!
treesitter-directive-trim!
Trim blank lines from the end of the node. This will set a new
metadata[capture_id].range
.{capture_id}
(#trim! @fold)
;
. Here are the
currently supported modeline alternatives:inherits: {lang}...
treesitter-query-modeline-inherits
Specifies that this query should inherit the queries from {lang}
.
This will recursively descend in the queries of {lang}
unless wrapped
in parentheses: ({lang})
.
Note: This is meant to be used to include queries from another
language. If you want your query to extend the queries of the same
language, use extends
.extends
treesitter-query-modeline-extends
Specifies that this query should be used as an extension for the
query, i.e. that it should be merged with the others.
Note: The order of the extensions, and the query that will be used as
a base depends on your 'runtimepath' value.;; inherits: foo,bar
;; extends
;; extends
;;
;; inherits: baz
highlights.scm
,
which match a TSNode in the parsed TSTree to a capture
that can be
assigned a highlight group. For example, the query(parameters (identifier) @parameter)
identifier
node inside a function parameter
node (e.g., the
bar
in foo(bar)
) to the capture named @parameter
. It is also possible to
match literal expressions (provided the parser returns them):"return" @keyword.return
highlights.scm
query is found in runtimepath,
treesitter highlighting for the current buffer can be enabled simply via
vim.treesitter.start().treesitter-highlight-groups
The capture names, with @
included, are directly usable as highlight groups.
For many commonly used captures, the corresponding highlight groups are linked
to Nvim's standard highlight-groups by default but can be overridden in
colorschemes.@comment.doc
could be used. If this group is not defined, the highlighting
for an ordinary @comment
is used. This way, existing color schemes already
work out of the box, but it is possible to add more specific variants for
queries that make them available.hi @comment.c guifg=Blue
hi @comment.lua guifg=DarkBlue
hi link @comment.doc.java String
@text.literal Comment @text.reference Identifier @text.title Title @text.uri Underlined @text.underline Underlined @text.todo Todo @comment Comment @punctuation Delimiter @constant Constant @constant.builtin Special @constant.macro Define @define Define @macro Macro @string String @string.escape SpecialChar @string.special SpecialChar @character Character @character.special SpecialChar @number Number @boolean Boolean @float Float @function Function @function.builtin Special @function.macro Macro @parameter Identifier @method Function @field Identifier @property Identifier @constructor Special @conditional Conditional @repeat Repeat @label Label @operator Operator @keyword Keyword @exception Exception @variable Identifier @type Type @type.definition Typedef @storageclass StorageClass @structure Structure @namespace Identifier @include Include @preproc PreProc @debug Debug @tag Tag
treesitter-highlight-spell
The special @spell
capture can be used to indicate that a node should be
spell checked by Nvim's builtin spell checker. For example, the following
capture marks comments as to be checked:(comment) @spell
@nospell
which disables spellchecking regions with @spell
.treesitter-highlight-conceal
Treesitter highlighting supports conceal via the conceal
metadata. By
convention, nodes to be concealed are captured as @conceal
, but any capture
can be used. For example, the following query can be used to hide code block
delimiters in Markdown:(fenced_code_block_delimiter @conceal (#set! conceal ""))
!=
operator by a Unicode glyph, which is
still highlighted the same as other operators:"!=" @operator (#set! conceal "≠")
treesitter-highlight-priority
Treesitter uses nvim_buf_set_extmark() to set highlights with a default
priority of 100. This enables plugins to set a highlighting priority lower or
higher than tree-sitter. It is also possible to change the priority of an
individual query pattern manually by setting its "priority"
metadata
attribute:((super_important_node) @superimportant (#set! "priority" 105))
<script>
tags and
CSS inside of <style>
tags
<%
%>
tags, and HTML outside of
those tags
<php
tags
@injection.content
- indicates that the captured node should have its
contents re-parsed using another language.
@injection.language
- indicates that the captured node’s text may
contain the name of a language that should be used to re-parse the
@injection.content
.
injection.language
- can be used to hard-code the name of a specific
language.
injection.combined
- indicates that all of the matching nodes in the
tree should have their content parsed as one nested document.
injection.include-children
- indicates that the @injection.content
node's entire text should be re-parsed, including the text of its child
nodes. By default, child nodes' text will be excluded from the injected
document.
injection.self
- indicates that the node's text should be parsed with
the same language as the node's LanguageTree.
injection.parent
- indicates that the captured node’s text should
be parsed with the same language as the node's parent LanguageTree.
vim.treesitter
Lua module, which is the main interface for Nvim's tree-sitter integration.
Most of the following content is automatically generated from the function
documentation.vim.treesitter.language_version
The latest parser ABI version that is supported by the bundled tree-sitter
library.vim.treesitter.minimum_language_version
The earliest parser ABI version that is supported by the bundled tree-sitter
library.{lnum}
) vim.treesitter.foldexpr()
Returns the fold level for {lnum}
in the current buffer. Can be set
directly to 'foldexpr':vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
{lnum}
(integer|nil) Line number to calculate fold level for
vim.treesitter.get_captures_at_cursor()
get_captures_at_cursor({winnr}
)
Returns a list of highlight capture names under the cursor{winnr}
(integer|nil) Window handle or 0 for current window (default)
vim.treesitter.get_captures_at_pos()
get_captures_at_pos({bufnr}
, {row}
, {col}
)
Returns a list of highlight captures at the given positionpriority
, conceal
, ...; empty
if none are defined).{bufnr}
(integer) Buffer number (0 for current buffer)
{row}
(integer) Position row
{col}
(integer) Position column
{ capture = "name", metadata = { ... } }
{opts}
) vim.treesitter.get_node()
Returns the smallest named node at the given position{opts}
(table|nil) Optional keyword arguments:
{bufnr}
is not
the current buffer
{node_or_range}
) vim.treesitter.get_node_range()
Returns the node's range or an unpacked range table{node_or_range}
(TSNode | table) Node or table of positions
vim.treesitter.get_node_text()
get_node_text({node}
, {source}
, {opts}
)
Gets the text corresponding to a given node{node}
TSNode
{source}
(integer|string) Buffer or string from which the {node}
is
extracted
{opts}
(table|nil) Optional parameters.
metadata[capture_id]
when using
vim.treesitter.query.add_directive().
{bufnr}
, {lang}
, {opts}
) vim.treesitter.get_parser()
Returns the parser for a specific buffer and attaches it to the buffer{bufnr}
(integer|nil) Buffer the parser should be tied to (default:
current buffer)
{lang}
(string|nil) Filetype of this parser (default: buffer
filetype)
{opts}
(table|nil) Options to pass to the created language tree
{node}
, {source}
, {metadata}
) vim.treesitter.get_range()
Get the range of a TSNode. Can also supply {source}
and {metadata}
to
get the range with directives applied.{node}
TSNode
{source}
integer|string|nil Buffer or string from which the {node}
is extracted
{metadata}
TSMetadata|nil
{str}
(string) Text to parse
{lang}
(string) Language of this string
{opts}
(table|nil) Options to pass to the created language tree
{opts}
) vim.treesitter.inspect_tree()
Open a window that displays a textual representation of the nodes in the
language tree.<Enter>
to jump to the node under the cursor
in the source buffer.:InspectTree
. :InspectTree
{opts}
(table|nil) Optional options table with the following possible
keys:
{command}
.
{winid}
is
nil.
{dest}
, {source}
) vim.treesitter.is_ancestor()
Determines whether a node is the ancestor of another{dest}
is an ancestor of {source}
vim.treesitter.is_in_node_range()
is_in_node_range({node}
, {line}
, {col}
)
Determines whether (line, col) position is in node range{node}
TSNode defining the range
{line}
(integer) Line (0-based)
{col}
(integer) Column (0-based)
{node}
contains the {range}
vim.bo.syntax = 'on'
after
the call to start
.vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
callback = function(args)
vim.treesitter.start(args.buf, 'latex')
vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed
end
})
{bufnr}
(integer|nil) Buffer to be highlighted (default: current
buffer)
{lang}
(string|nil) Language of the parser (default: buffer
filetype)
{bufnr}
) vim.treesitter.stop()
Stops treesitter highlighting for a buffer{bufnr}
(integer|nil) Buffer to stop highlighting (default: current
buffer)
parser
runtime directory, or the provided
{path}
{lang}
(string) Name of the parser (alphanumerical and _
only)
{opts}
(table|nil) Options:
{lang}
.
{lang}
) vim.treesitter.language.get_filetypes()
Get the filetypes associated with the parser named {lang}
.{lang}
(string) Name of parser
{lang}
) vim.treesitter.language.inspect()
Inspects the provided language.{lang}
(string) Language
{lang}
, {filetype}
) vim.treesitter.language.register()
Register a parser named {lang}
to be used for {filetype}
(s).{lang}
(string) Name of parser
{filetype}
string|string[] Filetype(s) to associate with lang
vim.treesitter.query.add_directive()
add_directive({name}
, {handler}
, {force}
)
Adds a new directive to be used in queriesmetadata.key = value
, additionally, handlers can set node level
data by using the capture id on the metadata table
metadata[capture_id].key = value
{name}
(string) Name of the directive, without leading #
{handler}
function(match:table<string,TSNode>, pattern:string,
bufnr:integer, predicate:string[], metadata:table)
match[capture_id]
(node (#set! conceal "-"))
would get
the predicate { "#set!", "conceal", "-" }
{force}
(boolean|nil)
vim.treesitter.query.add_predicate()
add_predicate({name}
, {handler}
, {force}
)
Adds a new predicate to be used in queries{name}
(string) Name of the predicate, without leading #
{handler}
function(match:table<string,TSNode>, pattern:string,
bufnr:integer, predicate:string[])
{force}
(boolean|nil)
{lang}
) vim.treesitter.query.edit()
Opens a live editor to query the buffer you started from.:EditQuery
.:write
to save it. You can find example queries at
$VIMRUNTIME/queries/
.{lang}
(string|nil) language to open the query editor for. If
omitted, inferred from the current buffer's filetype.
{lang}
, {query_name}
) vim.treesitter.query.get()
Returns the runtime query {query_name}
for {lang}
.{lang}
(string) Language to use for the query
{query_name}
(string) Name of the query (e.g. "highlights")
vim.treesitter.query.get_files()
get_files({lang}
, {query_name}
, {is_included}
)
Gets the list of files used to make up a query{lang}
(string) Language to get query for
{query_name}
(string) Name of the query to load (e.g., "highlights")
{is_included}
(boolean|nil) Internal parameter, most of the time left
as nil
{buf}
, {opts}
) vim.treesitter.query.lint()
Lint treesitter queries using installed parser, or clear lint errors.{buf}
for errors:/lua/highlights.scm
, the parser for the lua
language will be used.{buf}
(integer) Buffer handle
{opts}
(QueryLinterOpts|nil) Optional keyword arguments:
true
, just clear current lint errors
vim.treesitter.query.list_directives()
Lists the currently available directives to use in queries.vim.treesitter.query.list_predicates()
Lists the currently available predicates to use in queries.{findstart}
, {base}
) vim.treesitter.query.omnifunc()
Omnifunc for completing node names and predicates in treesitter queries.vim.bo.omnifunc = 'v:lua.vim.treesitter.query.omnifunc'
{lang}
, {query}
) vim.treesitter.query.parse()
Parse {query}
as a string. (If the query is in a file, the caller should
read the contents into a string before calling).Query
(see lua-treesitter-query) object which can be used to search nodes in
the syntax tree for the patterns defined in {query}
using iter_*
methods below.info
and captures
with additional context about {query}
.
captures
contains the list of unique capture names defined in {query}
.
-`info.captures` also points to captures
.
info.patterns
contains information about predicates.
{lang}
(string) Language to use for the query
{query}
(string) Query in s-expr syntax
Query:iter_captures()
Query:iter_captures({node}
, {source}
, {start}
, {stop}
)
Iterate over all captures from all matches inside {node}
{source}
is needed if the query contains predicates; then the caller must
ensure to use a freshly parsed tree consistent with the current text of
the buffer (if relevant). {start}
and {stop}
can be used to limit matches
inside a row range (this is typically used with root node as the {node}
,
i.e., to get syntax highlight matches in the current viewport). When
omitted, the {start}
and {stop}
row values are used from the given node.for id, node, metadata in query:iter_captures(tree:root(), bufnr, first, last) do
local name = query.captures[id] -- name of the capture in the query
-- typically useful info about the node:
local type = node:type() -- type of the captured node
local row1, col1, row2, col2 = node:range() -- range of the capture
-- ... use the info here ...
end
{node}
TSNode under which the search will occur
{source}
(integer|string) Source buffer or string to extract text
from
{start}
(integer) Starting line for the search
{stop}
(integer) Stopping line for the search (end-exclusive)
Query:iter_matches()
Query:iter_matches({node}
, {source}
, {start}
, {stop}
, {opts}
)
Iterates the matches of self on a given range.{node}
. The arguments are the same as
for Query:iter_captures() but the iterated values are different: an
(1-based) index of the pattern in the query, a table mapping capture
indices to nodes, and metadata from any directives processing the match.
If the query has more than one pattern, the capture table might be sparse
and e.g. pairs()
method should be used over ipairs
. Here is an example
iterating over all captures in every match:for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
for id, node in pairs(match) do
local name = query.captures[id]
-- `node` was captured by the `name` capture in the match
local node_data = metadata[id] -- Node level metadata
-- ... use the info here ...
end
end
{node}
TSNode under which the search will occur
{source}
(integer|string) Source buffer or string to search
{start}
(integer) Starting line for the search
{stop}
(integer) Stopping line for the search (end-exclusive)
{opts}
(table|nil) Options:
{lang}
, {query_name}
, {text}
) vim.treesitter.query.set()
Sets the runtime query named {query_name}
for {lang}
{lang}
(string) Language to use for the query
{query_name}
(string) Name of the query (e.g., "highlights")
{text}
(string) Query text (unparsed).
LanguageTree
contains a tree of parsers: the root treesitter parser
for {lang}
and any "injected" language parsers, which themselves may
inject other languages, recursively. For example a Lua buffer containing
some Vimscript commands needs multiple parsers to fully understand its
contents.local parser = vim.treesitter.get_parser(bufnr, lang)
bufnr=0
means current buffer). lang
defaults to 'filetype'.
Note: currently the parser is retained for the lifetime of a buffer but
this may change; a plugin should keep a reference to the parser object if
it wants incremental updates.local tree = parser:parse({ start_row, end_row })
parse()
again. If the buffer wasn't
edited, the same tree will be returned again without extra work. If the
buffer was parsed before, incremental parsing will be done of the changed
parts.LanguageTree:children()
Returns a map of language to child tree.{range}
) LanguageTree:contains()
Determines whether {range}
is contained in the LanguageTree.{range}
(table) { start_line, start_col, end_line, end_col }
LanguageTree:destroy()
Destroys this LanguageTree and all its children.remove_child
must be called on the parent to remove it.{fn}
) LanguageTree:for_each_tree()
Invokes the callback for each LanguageTree recursively.{fn}
fun(tree: TSTree, ltree: LanguageTree)
LanguageTree:included_regions()
Gets the set of included regions managed by this LanguageTree . This can be different from the regions set by injection query, because a
partial LanguageTree:parse() drops the regions outside the requested
range.{reload}
) LanguageTree:invalidate()
Invalidates this parser and all its children{reload}
(boolean|nil)
{exclude_children}
) LanguageTree:is_valid()
Returns whether this LanguageTree is valid, i.e., LanguageTree:trees() reflects the latest state of the
source. If invalid, user should call LanguageTree:parse().{exclude_children}
(boolean|nil) whether to ignore the validity of
children (default false
)
LanguageTree:lang()
Gets the language of this tree node.LanguageTree:language_for_range()
LanguageTree:language_for_range({range}
)
Gets the appropriate language that contains {range}
.{range}
(table) { start_line, start_col, end_line, end_col }
LanguageTree:named_node_for_range()
LanguageTree:named_node_for_range({range}
, {opts}
)
Gets the smallest named node that contains {range}
.{range}
(table) { start_line, start_col, end_line, end_col }
{opts}
(table|nil) Optional keyword arguments:
{range}
) LanguageTree:parse()
Recursively parse all regions in the language tree using
treesitter-parsers for the corresponding languages and run injection
queries on the parsed trees to determine whether child trees should be
created and parsed.{}
, typically only the root tree) is always
parsed; otherwise (typically injections) only if it intersects {range}
(or
if {range}
is true
).{range}
boolean|Range|nil: Parse this range in the parser's source.
Set to true
to run a complete parse of the source (Note:
Can be slow!) Set to false|nil
to only parse regions with
empty ranges (typically only the root tree without
injections).
LanguageTree:register_cbs()
LanguageTree:register_cbs({cbs}
, {recursive}
)
Registers callbacks for the LanguageTree.{cbs}
(table) An nvim_buf_attach()-like table argument with
the following handlers:
on_bytes
: see nvim_buf_attach(), but this will be called after the parsers callback.
on_changedtree
: a callback that will be called every
time the tree has syntactical changes. It will be
passed two arguments: a table of the ranges (as node
ranges) that changed and the changed tree.
on_child_added
: emitted when a child is added to the
tree.
on_child_removed
: emitted when a child is removed
from the tree.
on_detach
: emitted when the buffer is detached, see
nvim_buf_detach_event. Takes one argument, the number
of the buffer.
{recursive}
(boolean|nil) Apply callbacks recursively for all
children. Any new children will also inherit the
callbacks.
LanguageTree:source()
Returns the source content of the language tree (bufnr or string).LanguageTree:tree_for_range()
LanguageTree:tree_for_range({range}
, {opts}
)
Gets the tree that contains {range}
.{range}
(table) { start_line, start_col, end_line, end_col }
{opts}
(table|nil) Optional keyword arguments:
LanguageTree:trees()
Returns all trees of the regions parsed by this parser. Does not include
child languages. The result is list-like if