mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 11:15:14 -07:00
c032e83b22
Problem: Some injections (like markdown) allow specifying arbitrary language names for code blocks, which may be lead to errors when looking for a corresponding parser in runtime path. Solution: Validate that the language name only contains alphanumeric characters and `_` (e.g., for `c_sharp`) and error otherwise.
1080 lines
43 KiB
Plaintext
1080 lines
43 KiB
Plaintext
*treesitter.txt* Nvim
|
|
|
|
|
|
NVIM REFERENCE MANUAL
|
|
|
|
|
|
Treesitter integration *treesitter*
|
|
|
|
Nvim integrates the `tree-sitter` library for incremental parsing of buffers:
|
|
https://tree-sitter.github.io/tree-sitter/
|
|
|
|
WARNING: Treesitter support is still experimental and subject to frequent
|
|
changes. This documentation may also not fully reflect the latest changes.
|
|
|
|
Type |gO| to see the table of contents.
|
|
|
|
==============================================================================
|
|
PARSER FILES *treesitter-parsers*
|
|
|
|
Parsers are the heart of tree-sitter. They are libraries that tree-sitter will
|
|
search for in the `parser` runtime directory. By default, Nvim bundles only
|
|
parsers for C, Lua, and Vimscript, 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: >lua
|
|
|
|
vim.treesitter.require_language("python", "/path/to/python.so")
|
|
<
|
|
==============================================================================
|
|
LANGUAGE TREES *treesitter-languagetree*
|
|
*LanguageTree*
|
|
|
|
As buffers can contain multiple languages (e.g., Vimscript commands in a Lua
|
|
file), multiple parsers may be needed to parse the full buffer. These are
|
|
combined in a |LanguageTree| object.
|
|
|
|
To create a LanguageTree (parser object) for a buffer and a given language,
|
|
use >lua
|
|
|
|
tsparser = vim.treesitter.get_parser(bufnr, lang)
|
|
<
|
|
`bufnr=0` can be used for current buffer. `lang` will default to 'filetype'.
|
|
Currently, the parser will be retained for the lifetime of a buffer but this
|
|
is subject to change. A plugin should keep a reference to the parser object as
|
|
long as it wants incremental updates.
|
|
|
|
Whenever you need to access the current syntax tree, parse the buffer: >lua
|
|
|
|
tstree = tsparser:parse()
|
|
<
|
|
This will return a table of immutable |treesitter-tree|s that represent the
|
|
current state of the buffer. When the plugin wants to access the state after a
|
|
(possible) edit it should call `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.
|
|
|
|
Note: To use the parser directly inside a |nvim_buf_attach()| Lua callback,
|
|
you must call |vim.treesitter.get_parser()| before you register your callback.
|
|
But preferably parsing shouldn't be done directly in the change callback
|
|
anyway as they will be very frequent. Rather a plugin that does any kind of
|
|
analysis on a tree should use a timer to throttle too frequent updates.
|
|
|
|
See |lua-treesitter-languagetree| for the list of available methods.
|
|
|
|
==============================================================================
|
|
TREESITTER TREES *treesitter-tree*
|
|
*tstree*
|
|
|
|
A "treesitter tree" represents the parsed contents of a buffer, which can be
|
|
used to perform further analysis. It is a |luaref-userdata| reference to an
|
|
object held by the tree-sitter library.
|
|
|
|
An instance `tstree` of a treesitter tree supports the following methods.
|
|
|
|
tstree:root() *tstree:root()*
|
|
Return the root node of this tree.
|
|
|
|
tstree:copy() *tstree:copy()*
|
|
Returns a copy of the `tstree`.
|
|
|
|
==============================================================================
|
|
TREESITTER NODES *treesitter-node*
|
|
*tsnode*
|
|
|
|
A "treesitter node" represents one specific element of the parsed contents of
|
|
a buffer, which can be captured by a |Query| for, e.g., highlighting. It is a
|
|
|luaref-userdata| reference to an object held by the tree-sitter library.
|
|
|
|
An instance `tsnode` of a treesitter node supports the following methods.
|
|
|
|
tsnode:parent() *tsnode:parent()*
|
|
Get the node's immediate parent.
|
|
|
|
tsnode:next_sibling() *tsnode:next_sibling()*
|
|
Get the node's next sibling.
|
|
|
|
tsnode:prev_sibling() *tsnode:prev_sibling()*
|
|
Get the node's previous sibling.
|
|
|
|
tsnode:next_named_sibling() *tsnode:next_named_sibling()*
|
|
Get the node's next named sibling.
|
|
|
|
tsnode:prev_named_sibling() *tsnode:prev_named_sibling()*
|
|
Get the node's previous named sibling.
|
|
|
|
tsnode:iter_children() *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:field({name}) *tsnode:field()*
|
|
Returns a table of the nodes corresponding to the {name} field.
|
|
|
|
tsnode:child_count() *tsnode:child_count()*
|
|
Get the node's number of children.
|
|
|
|
tsnode:child({index}) *tsnode:child()*
|
|
Get the node's child at the given {index}, where zero represents the first
|
|
child.
|
|
|
|
tsnode:named_child_count() *tsnode:named_child_count()*
|
|
Get the node's number of named children.
|
|
|
|
tsnode:named_child({index}) *tsnode:named_child()*
|
|
Get the node's named child at the given {index}, where zero represents the
|
|
first named child.
|
|
|
|
tsnode:start() *tsnode:start()*
|
|
Get the node's start position. Return three values: the row, column and
|
|
total byte count (all zero-based).
|
|
|
|
tsnode:end_() *tsnode:end_()*
|
|
Get the node's end position. Return three values: the row, column and
|
|
total byte count (all zero-based).
|
|
|
|
tsnode:range() *tsnode:range()*
|
|
Get the range of the node. Return four values: the row, column of the
|
|
start position, then the row, column of the end position.
|
|
|
|
tsnode:type() *tsnode:type()*
|
|
Get the node's type as a string.
|
|
|
|
tsnode:symbol() *tsnode:symbol()*
|
|
Get the node's type as a numerical id.
|
|
|
|
tsnode:named() *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() *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:has_error() *tsnode:has_error()*
|
|
Check if the node is a syntax error or contains any syntax errors.
|
|
|
|
tsnode:sexpr() *tsnode:sexpr()*
|
|
Get an S-expression representing the node as a string.
|
|
|
|
tsnode:id() *tsnode:id()*
|
|
Get an unique identifier for the node inside its own tree.
|
|
|
|
No guarantees are made about this identifier's internal representation,
|
|
except for being a primitive Lua type with value equality (so not a
|
|
table). Presently it is a (non-printable) string.
|
|
|
|
Note: The `id` is not guaranteed to be unique for nodes from different
|
|
trees.
|
|
|
|
*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) positions
|
|
|
|
*tsnode: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
|
|
|
|
==============================================================================
|
|
TREESITTER QUERIES *treesitter-query*
|
|
|
|
Treesitter queries are a way to extract information about a parsed |tstree|,
|
|
e.g., for the purpose of highlighting. Briefly, a `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.
|
|
|
|
Queries are written in a lisp-like language documented in
|
|
https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax
|
|
Note: The predicates listed there page differ from those Nvim supports. See
|
|
|treesitter-predicates| for a complete list of predicates supported by Nvim.
|
|
|
|
Nvim looks for queries as `*.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 Neovim). If a query should extend other queries instead
|
|
of replacing them, use |treesitter-query-modeline-extends|.
|
|
|
|
See |lua-treesitter-query| for the list of available methods for working with
|
|
treesitter queries from Lua.
|
|
|
|
|
|
TREESITTER QUERY PREDICATES *treesitter-predicates*
|
|
|
|
Predicates are special scheme nodes that are evaluated to conditionally capture
|
|
nodes. For example, the `eq?` predicate can be used as follows: >
|
|
|
|
((identifier) @foo (#eq? @foo "foo"))
|
|
<
|
|
to only match identifier corresponding to the `"foo"` text.
|
|
|
|
The following predicates are built in:
|
|
|
|
`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_]+$"))
|
|
< Note: The `^` 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"))
|
|
<
|
|
This is the recommended way to check if the node matches one of many
|
|
keywords, as it has been optimized for this.
|
|
|
|
*lua-treesitter-not-predicate*
|
|
Each predicate has a `not-` prefixed predicate that is just the negation of
|
|
the predicate.
|
|
|
|
Further predicates can be added via |vim.treesitter.query.add_predicate()|.
|
|
Use |vim.treesitter.query.list_predicates()| to list all available
|
|
predicates.
|
|
|
|
|
|
TREESITTER QUERY DIRECTIVES *treesitter-directives*
|
|
|
|
Treesitter directives store metadata for a node or match and perform side
|
|
effects. For example, the `set!` directive sets metadata on the match or node: >
|
|
|
|
((identifier) @foo (#set! "type" "parameter"))
|
|
<
|
|
The following directives are built in:
|
|
|
|
`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).
|
|
|
|
Parameters: ~
|
|
{capture_id} (optional)
|
|
{key}
|
|
{value}
|
|
|
|
Examples: >
|
|
((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`.
|
|
|
|
Parameters: ~
|
|
{capture_id}
|
|
{start_row}
|
|
{start_col}
|
|
{end_row}
|
|
{end_col}
|
|
|
|
Example: >
|
|
((identifier) @constant (#offset! @constant 0 1 0 -1))
|
|
<
|
|
|
|
Further directives can be added via |vim.treesitter.query.add_directive()|.
|
|
Use |vim.treesitter.query.list_directives()| to list all available
|
|
directives.
|
|
|
|
|
|
TREESITTER QUERY MODELINES *treesitter-query-modeline*
|
|
|
|
Neovim supports to customize the behavior of the queries using a set of
|
|
"modelines", that is comments in the queries starting with `;`. 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.
|
|
|
|
Note: These modeline comments must be at the top of the query, but can be
|
|
repeated, for example, the following two modeline blocks are both valid: >
|
|
|
|
;; inherits: foo,bar
|
|
;; extends
|
|
|
|
;; extends
|
|
;;
|
|
;; inherits: baz
|
|
<
|
|
==============================================================================
|
|
TREESITTER SYNTAX HIGHLIGHTING *treesitter-highlight*
|
|
|
|
Syntax highlighting is specified through queries named `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)
|
|
<
|
|
matches any `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
|
|
<
|
|
Assuming a suitable parser and `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.
|
|
|
|
A fallback system is implemented, so that more specific groups fallback to
|
|
more generic ones. For instance, in a language that has separate doc comments,
|
|
`@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.
|
|
|
|
As an additional rule, capture highlights can always be specialized by
|
|
language, by appending the language name after an additional dot. For
|
|
instance, to highlight comments differently per language: >vim
|
|
|
|
hi @comment.c guifg=Blue
|
|
hi @comment.lua guifg=DarkBlue
|
|
hi link @comment.doc.java String
|
|
<
|
|
The following captures are linked by default to standard |group-name|s:
|
|
>
|
|
@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
|
|
<
|
|
|
|
There is also `@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 "")
|
|
<
|
|
It is also possible to replace a node with a single character, which (unlike
|
|
legacy syntax) can be given a custom highlight. For example, the following
|
|
(ill-advised) query replaces the `!=` operator by a Unicode glyph, which is
|
|
still highlighted the same as other operators: >
|
|
|
|
"!=" @operator (#set! conceal "≠")
|
|
<
|
|
Conceals specified in this way respect 'conceallevel'.
|
|
|
|
*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) @ImportantHighlight (#set! "priority" 105)
|
|
<
|
|
==============================================================================
|
|
VIM.TREESITTER *lua-treesitter*
|
|
|
|
The remainder of this document is a reference manual for the `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.
|
|
|
|
==============================================================================
|
|
Lua module: vim.treesitter *lua-treesitter-core*
|
|
|
|
*vim.treesitter.get_captures_at_cursor()*
|
|
get_captures_at_cursor({winnr})
|
|
Returns a list of highlight capture names under the cursor
|
|
|
|
Parameters: ~
|
|
• {winnr} (number|nil) Window handle or 0 for current window (default)
|
|
|
|
Return: ~
|
|
string[] List of capture names
|
|
|
|
*vim.treesitter.get_captures_at_pos()*
|
|
get_captures_at_pos({bufnr}, {row}, {col})
|
|
Returns a list of highlight captures at the given position
|
|
|
|
Each capture is represented by a table containing the capture name as a
|
|
string as well as a table of metadata (`priority`, `conceal`, ...; empty
|
|
if none are defined).
|
|
|
|
Parameters: ~
|
|
• {bufnr} (number) Buffer number (0 for current buffer)
|
|
• {row} (number) Position row
|
|
• {col} (number) Position column
|
|
|
|
Return: ~
|
|
table[] List of captures `{ capture = "capture name", metadata = { ...
|
|
} }`
|
|
|
|
get_node_at_cursor({winnr}) *vim.treesitter.get_node_at_cursor()*
|
|
Returns the smallest named node under the cursor
|
|
|
|
Parameters: ~
|
|
• {winnr} (number|nil) Window handle or 0 for current window (default)
|
|
|
|
Return: ~
|
|
(string) Name of node under the cursor
|
|
|
|
*vim.treesitter.get_node_at_pos()*
|
|
get_node_at_pos({bufnr}, {row}, {col}, {opts})
|
|
Returns the smallest named node at the given position
|
|
|
|
Parameters: ~
|
|
• {bufnr} (number) Buffer number (0 for current buffer)
|
|
• {row} (number) Position row
|
|
• {col} (number) Position column
|
|
• {opts} (table) Optional keyword arguments:
|
|
• lang string|nil Parser language
|
|
• ignore_injections boolean Ignore injected languages
|
|
(default true)
|
|
|
|
Return: ~
|
|
userdata|nil |tsnode| under the cursor
|
|
|
|
get_node_range({node_or_range}) *vim.treesitter.get_node_range()*
|
|
Returns the node's range or an unpacked range table
|
|
|
|
Parameters: ~
|
|
• {node_or_range} (userdata|table) |tsnode| or table of positions
|
|
|
|
Return: ~
|
|
(table) `{ start_row, start_col, end_row, end_col }`
|
|
|
|
get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
|
|
Returns the parser for a specific buffer and filetype and attaches it to
|
|
the buffer
|
|
|
|
If needed, this will create the parser.
|
|
|
|
Parameters: ~
|
|
• {bufnr} (number|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
|
|
|
|
Return: ~
|
|
LanguageTree |LanguageTree| object to use for parsing
|
|
|
|
*vim.treesitter.get_string_parser()*
|
|
get_string_parser({str}, {lang}, {opts})
|
|
Returns a string parser
|
|
|
|
Parameters: ~
|
|
• {str} (string) Text to parse
|
|
• {lang} (string) Language of this string
|
|
• {opts} (table|nil) Options to pass to the created language tree
|
|
|
|
Return: ~
|
|
LanguageTree |LanguageTree| object to use for parsing
|
|
|
|
is_ancestor({dest}, {source}) *vim.treesitter.is_ancestor()*
|
|
Determines whether a node is the ancestor of another
|
|
|
|
Parameters: ~
|
|
• {dest} userdata Possible ancestor |tsnode|
|
|
• {source} userdata Possible descendant |tsnode|
|
|
|
|
Return: ~
|
|
(boolean) True if {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
|
|
|
|
Parameters: ~
|
|
• {node} userdata |tsnode| defining the range
|
|
• {line} (number) Line (0-based)
|
|
• {col} (number) Column (0-based)
|
|
|
|
Return: ~
|
|
(boolean) True if the position is in node range
|
|
|
|
node_contains({node}, {range}) *vim.treesitter.node_contains()*
|
|
Determines if a node contains a range
|
|
|
|
Parameters: ~
|
|
• {node} userdata |tsnode|
|
|
• {range} (table)
|
|
|
|
Return: ~
|
|
(boolean) True if the {node} contains the {range}
|
|
|
|
show_tree({opts}) *vim.treesitter.show_tree()*
|
|
Open a window that displays a textual representation of the nodes in the
|
|
language tree.
|
|
|
|
While in the window, press "a" to toggle display of anonymous nodes, "I"
|
|
to toggle the display of the source language of each node, and press
|
|
<Enter> to jump to the node under the cursor in the source buffer.
|
|
|
|
Parameters: ~
|
|
• {opts} (table|nil) Optional options table with the following possible
|
|
keys:
|
|
• lang (string|nil): The language of the source buffer. If
|
|
omitted, the filetype of the source buffer is used.
|
|
• bufnr (number|nil): Buffer to draw the tree into. If
|
|
omitted, a new buffer is created.
|
|
• winid (number|nil): Window id to display the tree buffer in.
|
|
If omitted, a new window is created with {command}.
|
|
• command (string|nil): Vimscript command to create the
|
|
window. Default value is "topleft 60vnew". Only used when
|
|
{winid} is nil.
|
|
• title (string|fun(bufnr:number):string|nil): Title of the
|
|
window. If a function, it accepts the buffer number of the
|
|
source buffer as its only argument and should return a
|
|
string.
|
|
|
|
start({bufnr}, {lang}) *vim.treesitter.start()*
|
|
Starts treesitter highlighting for a buffer
|
|
|
|
Can be used in an ftplugin or FileType autocommand.
|
|
|
|
Note: By default, disables regex syntax highlighting, which may be
|
|
required for some plugins. In this case, add `vim.bo.syntax = 'on'` after
|
|
the call to `start`.
|
|
|
|
Example: >lua
|
|
|
|
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
|
|
})
|
|
<
|
|
|
|
Parameters: ~
|
|
• {bufnr} (number|nil) Buffer to be highlighted (default: current
|
|
buffer)
|
|
• {lang} (string|nil) Language of the parser (default: buffer
|
|
filetype)
|
|
|
|
stop({bufnr}) *vim.treesitter.stop()*
|
|
Stops treesitter highlighting for a buffer
|
|
|
|
Parameters: ~
|
|
• {bufnr} (number|nil) Buffer to stop highlighting (default: current
|
|
buffer)
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.treesitter.language *lua-treesitter-language*
|
|
|
|
inspect_language({lang}) *vim.treesitter.language.inspect_language()*
|
|
Inspects the provided language.
|
|
|
|
Inspecting provides some useful information on the language like node
|
|
names, ...
|
|
|
|
Parameters: ~
|
|
• {lang} (string) Language
|
|
|
|
Return: ~
|
|
(table)
|
|
|
|
*vim.treesitter.language.require_language()*
|
|
require_language({lang}, {path}, {silent}, {symbol_name})
|
|
Asserts that a parser for the language {lang} is installed.
|
|
|
|
Parsers are searched in the `parser` runtime directory, or the provided
|
|
{path}
|
|
|
|
Parameters: ~
|
|
• {lang} (string) Language the parser should parse
|
|
(alphanumerical and `_` only)
|
|
• {path} (string|nil) Optional path the parser is located at
|
|
• {silent} (boolean|nil) Don't throw an error if language not
|
|
found
|
|
• {symbol_name} (string|nil) Internal symbol name for the language to
|
|
load
|
|
|
|
Return: ~
|
|
(boolean) If the specified language is installed
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.treesitter.query *lua-treesitter-query*
|
|
|
|
*vim.treesitter.query.add_directive()*
|
|
add_directive({name}, {handler}, {force})
|
|
Adds a new directive to be used in queries
|
|
|
|
Handlers can set match level data by setting directly on the metadata
|
|
object `metadata.key = value`, additionally, handlers can set node level
|
|
data by using the capture id on the metadata table
|
|
`metadata[capture_id].key = value`
|
|
|
|
Parameters: ~
|
|
• {name} (string) Name of the directive, without leading #
|
|
• {handler} function(match:table, pattern:string, bufnr:number,
|
|
predicate:string[], metadata:table)
|
|
• match: see |treesitter-query|
|
|
• node-level data are accessible via `match[capture_id]`
|
|
|
|
• pattern: see |treesitter-query|
|
|
• predicate: list of strings containing the full directive
|
|
being called, e.g. `(node (#set! conceal "-"))` would get
|
|
the predicate `{ "#set!", "conceal", "-" }`
|
|
|
|
*vim.treesitter.query.add_predicate()*
|
|
add_predicate({name}, {handler}, {force})
|
|
Adds a new predicate to be used in queries
|
|
|
|
Parameters: ~
|
|
• {name} (string) Name of the predicate, without leading #
|
|
• {handler} function(match:table, pattern:string, bufnr:number,
|
|
predicate:string[])
|
|
• see |vim.treesitter.query.add_directive()| for argument
|
|
meanings
|
|
|
|
*vim.treesitter.query.get_node_text()*
|
|
get_node_text({node}, {source}, {opts})
|
|
Gets the text corresponding to a given node
|
|
|
|
Parameters: ~
|
|
• {node} userdata |tsnode|
|
|
• {source} (number|string) Buffer or string from which the {node} is
|
|
extracted
|
|
• {opts} (table|nil) Optional parameters.
|
|
• concat: (boolean) Concatenate result in a string (default
|
|
true)
|
|
|
|
Return: ~
|
|
(string[]|string)
|
|
|
|
get_query({lang}, {query_name}) *vim.treesitter.query.get_query()*
|
|
Returns the runtime query {query_name} for {lang}.
|
|
|
|
Parameters: ~
|
|
• {lang} (string) Language to use for the query
|
|
• {query_name} (string) Name of the query (e.g. "highlights")
|
|
|
|
Return: ~
|
|
Query Parsed query
|
|
|
|
*vim.treesitter.query.get_query_files()*
|
|
get_query_files({lang}, {query_name}, {is_included})
|
|
Gets the list of files used to make up a query
|
|
|
|
Parameters: ~
|
|
• {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`
|
|
|
|
Return: ~
|
|
string[] query_files List of files to load for given query and
|
|
language
|
|
|
|
list_directives() *vim.treesitter.query.list_directives()*
|
|
Lists the currently available directives to use in queries.
|
|
|
|
Return: ~
|
|
string[] List of supported directives.
|
|
|
|
list_predicates() *vim.treesitter.query.list_predicates()*
|
|
Lists the currently available predicates to use in queries.
|
|
|
|
Return: ~
|
|
string[] List of supported predicates.
|
|
|
|
parse_query({lang}, {query}) *vim.treesitter.query.parse_query()*
|
|
Parse {query} as a string. (If the query is in a file, the caller should
|
|
read the contents into a string before calling).
|
|
|
|
Returns a `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.
|
|
|
|
Exposes `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.
|
|
|
|
Parameters: ~
|
|
• {lang} (string) Language to use for the query
|
|
• {query} (string) Query in s-expr syntax
|
|
|
|
Return: ~
|
|
Query Parsed query
|
|
|
|
*Query:iter_captures()*
|
|
Query:iter_captures({self}, {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_row} and {end_row} 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 {end} row values are used from the given
|
|
node.
|
|
|
|
The iterator returns three values: a numeric id identifying the capture,
|
|
the captured node, and metadata from any directives processing the match.
|
|
The following example shows how to get captures by name: >lua
|
|
|
|
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
|
|
<
|
|
|
|
Parameters: ~
|
|
• {node} userdata |tsnode| under which the search will occur
|
|
• {source} (number|string) Source buffer or string to extract text from
|
|
• {start} (number) Starting line for the search
|
|
• {stop} (number) Stopping line for the search (end-exclusive)
|
|
• {self}
|
|
|
|
Return: ~
|
|
(number) capture Matching capture id
|
|
(table) capture_node Capture for {node}
|
|
(table) metadata for the {capture}
|
|
|
|
*Query:iter_matches()*
|
|
Query:iter_matches({self}, {node}, {source}, {start}, {stop})
|
|
Iterates the matches of self on a given range.
|
|
|
|
Iterate over all matches within a {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: >lua
|
|
|
|
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
|
|
<
|
|
|
|
Parameters: ~
|
|
• {node} userdata |tsnode| under which the search will occur
|
|
• {source} (number|string) Source buffer or string to search
|
|
• {start} (number) Starting line for the search
|
|
• {stop} (number) Stopping line for the search (end-exclusive)
|
|
• {self}
|
|
|
|
Return: ~
|
|
(number) pattern id
|
|
(table) match
|
|
(table) metadata
|
|
|
|
*vim.treesitter.query.set_query()*
|
|
set_query({lang}, {query_name}, {text})
|
|
Sets the runtime query named {query_name} for {lang}
|
|
|
|
This allows users to override any runtime files and/or configuration set
|
|
by plugins.
|
|
|
|
Parameters: ~
|
|
• {lang} (string) Language to use for the query
|
|
• {query_name} (string) Name of the query (e.g., "highlights")
|
|
• {text} (string) Query text (unparsed).
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.treesitter.highlighter *lua-treesitter-highlighter*
|
|
|
|
new({tree}, {opts}) *vim.treesitter.highlighter.new()*
|
|
Creates a new highlighter using
|
|
|
|
Parameters: ~
|
|
• {tree} LanguageTree |LanguageTree| parser object to use for highlighting
|
|
• {opts} (table|nil) Configuration of the highlighter:
|
|
• queries table overwrite queries used by the highlighter
|
|
|
|
Return: ~
|
|
TSHighlighter Created highlighter object
|
|
|
|
TSHighlighter:destroy({self}) *TSHighlighter:destroy()*
|
|
Removes all internal references to the highlighter
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
|
|
==============================================================================
|
|
Lua module: vim.treesitter.languagetree *lua-treesitter-languagetree*
|
|
|
|
LanguageTree:children({self}) *LanguageTree:children()*
|
|
Returns a map of language to child tree.
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
LanguageTree:contains({self}, {range}) *LanguageTree:contains()*
|
|
Determines whether {range} is contained in the |LanguageTree|.
|
|
|
|
Parameters: ~
|
|
• {range} (table) `{ start_line, start_col, end_line, end_col }`
|
|
• {self}
|
|
|
|
Return: ~
|
|
(boolean)
|
|
|
|
LanguageTree:destroy({self}) *LanguageTree:destroy()*
|
|
Destroys this |LanguageTree| and all its children.
|
|
|
|
Any cleanup logic should be performed here.
|
|
|
|
Note: This DOES NOT remove this tree from a parent. Instead, `remove_child` must be called on the parent to remove it.
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
*LanguageTree:for_each_child()*
|
|
LanguageTree:for_each_child({self}, {fn}, {include_self})
|
|
Invokes the callback for each |LanguageTree| and its children recursively
|
|
|
|
Parameters: ~
|
|
• {fn} function(tree: LanguageTree, lang: string)
|
|
• {include_self} (boolean) Whether to include the invoking tree in the
|
|
results
|
|
• {self}
|
|
|
|
LanguageTree:for_each_tree({self}, {fn}) *LanguageTree:for_each_tree()*
|
|
Invokes the callback for each |LanguageTree| recursively.
|
|
|
|
Note: This includes the invoking tree's child trees as well.
|
|
|
|
Parameters: ~
|
|
• {fn} function(tree: TSTree, languageTree: LanguageTree)
|
|
• {self}
|
|
|
|
LanguageTree:included_regions({self}) *LanguageTree:included_regions()*
|
|
Gets the set of included regions
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
LanguageTree:invalidate({self}, {reload}) *LanguageTree:invalidate()*
|
|
Invalidates this parser and all its children
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
LanguageTree:is_valid({self}) *LanguageTree:is_valid()*
|
|
Determines whether this tree is valid. If the tree is invalid, call `parse()` . This will return the updated tree.
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
LanguageTree:lang({self}) *LanguageTree:lang()*
|
|
Gets the language of this tree node.
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
*LanguageTree:language_for_range()*
|
|
LanguageTree:language_for_range({self}, {range})
|
|
Gets the appropriate language that contains {range}.
|
|
|
|
Parameters: ~
|
|
• {range} (table) `{ start_line, start_col, end_line, end_col }`
|
|
• {self}
|
|
|
|
Return: ~
|
|
LanguageTree Managing {range}
|
|
|
|
*LanguageTree:named_node_for_range()*
|
|
LanguageTree:named_node_for_range({self}, {range}, {opts})
|
|
Gets the smallest named node that contains {range}.
|
|
|
|
Parameters: ~
|
|
• {range} (table) `{ start_line, start_col, end_line, end_col }`
|
|
• {opts} (table|nil) Optional keyword arguments:
|
|
• ignore_injections boolean Ignore injected languages
|
|
(default true)
|
|
• {self}
|
|
|
|
Return: ~
|
|
userdata|nil Found |tsnode|
|
|
|
|
LanguageTree:parse({self}) *LanguageTree:parse()*
|
|
Parses all defined regions using a treesitter parser for the language this
|
|
tree represents. This will run the injection query for this language to
|
|
determine if any child languages should be created.
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
Return: ~
|
|
userdata[] Table of parsed |tstree|
|
|
(table) Change list
|
|
|
|
LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()*
|
|
Registers callbacks for the |LanguageTree|.
|
|
|
|
Parameters: ~
|
|
• {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 only be passed one
|
|
argument, which is a table of the ranges (as node ranges)
|
|
that changed.
|
|
• `on_child_added` : emitted when a child is added to the
|
|
tree.
|
|
• `on_child_removed` : emitted when a child is removed from
|
|
the tree.
|
|
• {self}
|
|
|
|
LanguageTree:source({self}) *LanguageTree:source()*
|
|
Returns the source content of the language tree (bufnr or string).
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
*LanguageTree:tree_for_range()*
|
|
LanguageTree:tree_for_range({self}, {range}, {opts})
|
|
Gets the tree that contains {range}.
|
|
|
|
Parameters: ~
|
|
• {range} (table) `{ start_line, start_col, end_line, end_col }`
|
|
• {opts} (table|nil) Optional keyword arguments:
|
|
• ignore_injections boolean Ignore injected languages
|
|
(default true)
|
|
• {self}
|
|
|
|
Return: ~
|
|
userdata|nil Contained |tstree|
|
|
|
|
LanguageTree:trees({self}) *LanguageTree:trees()*
|
|
Returns all trees this language tree contains. Does not include child
|
|
languages.
|
|
|
|
Parameters: ~
|
|
• {self}
|
|
|
|
new({source}, {lang}, {opts}) *vim.treesitter.languagetree.new()*
|
|
A |LanguageTree| holds the treesitter parser for a given language {lang}
|
|
used to parse a buffer. As the buffer may contain injected languages, the LanguageTree needs to store parsers for these child languages as well (which in turn
|
|
may contain child languages themselves, hence the name).
|
|
|
|
Parameters: ~
|
|
• {source} (number|string) Buffer or a string of text to parse
|
|
• {lang} (string) Root language this tree represents
|
|
• {opts} (table|nil) Optional keyword arguments:
|
|
• injections table Mapping language to injection query
|
|
strings. This is useful for overriding the built-in
|
|
runtime file searching for the injection language query
|
|
per language.
|
|
|
|
Return: ~
|
|
LanguageTree |LanguageTree| parser object
|
|
|
|
vim:tw=78:ts=8:sw=4:sts=4:et:ft=help:norl:
|