2020-09-14 10:04:33 -07:00
*treesitter.txt* Nvim
NVIM REFERENCE MANUAL
Tree-sitter integration *treesitter*
Type |gO| to see the table of contents.
------------------------------------------------------------------------------
VIM.TREESITTER *lua-treesitter*
Nvim integrates the tree-sitter library for incremental parsing of buffers.
2021-03-30 13:40:29 -07:00
*vim.treesitter.language_version*
To check which language version is compiled with neovim, the number is stored
within `vim.treesitter.language_version`. This number is not too helpful
unless you are wondering about compatibility between different versions of
compiled grammars.
2020-09-14 10:04:33 -07:00
Parser files *treesitter-parsers*
Parsers are the heart of tree-sitter. They are libraries that tree-sitter will
2021-06-16 10:06:29 -07:00
search for in the `parser` runtime directory. Currently Nvim does not provide
the tree-sitter parsers, instead these must be built separately, for instance
using the tree-sitter utility. The only exception is a C parser being included
in official builds for testing purposes. Parsers are searched for as
`parser/{lang}.*` in any 'runtimepath' directory.
A parser can also be loaded manually using a full path: >
vim.treesitter.require_language("python", "/path/to/python.so")
<Create a parser for a buffer and a given language (if another plugin uses the
same buffer/language combination, it will be safely reused). Use >
parser = 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.
2020-09-14 10:04:33 -07:00
Parser methods *lua-treesitter-parser*
tsparser:parse() *tsparser:parse()*
Whenever you need to access the current syntax tree, parse the buffer: >
tstree = parser:parse()
2020-11-24 19:56:47 -07:00
<This will return a table of immutable trees that represent the current state of the
2020-09-14 10:04:33 -07:00
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.
2021-06-16 10:06:29 -07:00
Note: to use the parser directly inside a |nvim_buf_attach| Lua callback, you
must call `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.
2020-09-14 10:04:33 -07:00
2020-11-04 10:03:36 -07:00
tsparser:set_included_regions({region_list}) *tsparser:set_included_regions()*
Changes the regions the parser should consider. This is used for
language injection. {region_list} should be of the form (all zero-based): >
2020-09-14 10:04:33 -07:00
{
2020-11-04 10:03:36 -07:00
{node1, node2},
2020-09-14 10:04:33 -07:00
...
}
<
2020-11-04 10:03:36 -07:00
`node1` and `node2` are both considered part of the same region and
will be parsed together with the parser in the same context.
2020-09-14 10:04:33 -07:00
Tree methods *lua-treesitter-tree*
tstree:root() *tstree:root()*
Return the root node of this tree.
2020-11-03 10:43:41 -07:00
tstree:copy() *tstree:copy()*
Returns a copy of the `tstree`.
2020-09-14 10:04:33 -07:00
Node methods *lua-treesitter-node*
tsnode:parent() *tsnode:parent()*
Get the node's immediate parent.
2021-08-19 22:35:25 -07:00
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.
2020-09-14 10:04:33 -07:00
tsnode:iter_children() *tsnode:iter_children()*
Iterates over all the direct children of {tsnode}, regardless of
wether 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.
2021-05-01 05:19:48 -07:00
tsnode:child({index}) *tsnode:child()*
2020-09-14 10:04:33 -07:00
Get the node's child at the given {index}, where zero represents the
first child.
2021-05-01 05:19:48 -07:00
tsnode:named_child_count() *tsnode:named_child_count()*
2020-09-14 10:04:33 -07:00
Get the node's number of named children.
2021-05-01 05:19:48 -07:00
tsnode:named_child({index}) *tsnode:named_child()*
2020-09-14 10:04:33 -07:00
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.
2021-05-01 05:19:48 -07:00
tsnode:id() *tsnode:id()*
2020-10-30 02:51:41 -07:00
Get an unique identier for the node inside its own tree.
No guarantees are made about this identifer's internal representation,
except for being a primitive lua type with value equality (so not a table).
Presently it is a (non-printable) string.
2021-06-16 10:06:29 -07:00
Note: the id is not guaranteed to be unique for nodes from different
trees.
2020-10-30 02:51:41 -07:00
2020-09-14 10:04:33 -07:00
tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
2021-05-01 05:19:48 -07:00
*tsnode:descendant_for_range()*
2020-09-14 10:04:33 -07:00
Get the smallest node within this node that spans the given range of
(row, column) positions
tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
2021-05-01 05:19:48 -07:00
*tsnode:named_descendant_for_range()*
2020-09-14 10:04:33 -07:00
Get the smallest named node within this node that spans the given
range of (row, column) positions
2021-05-01 05:19:48 -07:00
Query *lua-treesitter-query*
2020-09-14 10:04:33 -07:00
2021-06-16 10:06:29 -07:00
Tree-sitter queries are supported, they are a way to do pattern-matching over
2021-06-16 10:10:15 -07:00
a tree, using a simple to write lisp-like format. See
https://tree-sitter.github.io/tree-sitter/using-parsers#query-syntax for more
information on how to write queries.
2021-07-14 11:41:53 -07:00
Note: The predicates listed in the web page above differ from those Neovim
2021-06-16 10:10:15 -07:00
supports. See |lua-treesitter-predicates| for a complete list of predicates
supported by Neovim.
2020-09-14 10:04:33 -07:00
2020-11-04 12:55:12 -07:00
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
2020-11-04 10:13:00 -07:00
syntax tree which match a pattern. Patterns may optionally define captures
2020-11-04 12:55:12 -07:00
and predicates. A `capture` allows you to associate names with a specific
node in a pattern. A `predicate` adds arbitrary metadata and conditional data
2020-11-04 10:13:00 -07:00
to a match.
2020-09-14 10:04:33 -07:00
Treesitter Query Predicates *lua-treesitter-predicates*
When writing queries for treesitter, one might use `predicates`, that is,
special scheme nodes that are evaluted to verify things on a captured node for
example, the |eq?| predicate : >
((identifier) @foo (#eq? @foo "foo"))
This will only match identifier corresponding to the `"foo"` text.
Here is a list of built-in predicates :
`eq?` *ts-predicate-eq?*
This predicate will check text correspondance between nodes or
strings : >
((identifier) @foo (#eq? @foo "foo"))
((node1) @left (node2) @right (#eq? @left @right))
<
`match?` *ts-predicate-match?*
`vim-match?` *ts-predicate-vim-match?*
This will match if the provived vim regex matches the text
corresponding to a node : >
((idenfitier) @constant (#match? @constant "^[A-Z_]+$"))
< Note: the `^` and `$` anchors will respectively match the
start and end of the node's text.
`lua-match?` *ts-predicate-lua-match?*
This will match the same way than |match?| but using lua
regexes.
2020-11-04 10:03:36 -07:00
2020-09-14 10:04:33 -07:00
`contains?` *ts-predicate-contains?*
Will check if any of the following arguments appears in the
text corresponding to the node : >
((identifier) @foo (#contains? @foo "foo"))
((identifier) @foo-bar (#contains @foo-bar "foo" "bar"))
2021-05-14 08:41:20 -07:00
<
`any-of?` *ts-predicate-any-of?*
2021-08-01 08:09:19 -07:00
Will check if the text is the same as any of the following.
2021-06-16 10:06:29 -07:00
This is the recommended way to check if the node matches one
2021-08-01 08:09:19 -07:00
of many keywords for example, as it has been optimized for
2021-06-16 10:06:29 -07:00
this.
2021-05-14 08:41:20 -07:00
arguments : >
((identifier) @foo (#any-of? @foo "foo" "bar"))
2020-09-14 10:04:33 -07:00
<
*lua-treesitter-not-predicate*
Each predicate has a `not-` prefixed predicate that is just the negation of
the predicate.
2021-04-11 12:05:22 -07:00
*vim.treesitter.query.add_predicate()*
vim.treesitter.query.add_predicate({name}, {handler})
This adds a predicate with the name {name} to be used in queries.
{handler} should be a function whose signature will be : >
handler(match, pattern, bufnr, predicate)
<
*vim.treesitter.query.list_predicates()*
vim.treesitter.query.list_predicates()
This lists the currently available predicates to use in queries.
2020-11-24 07:50:33 -07:00
Treesitter Query Directive *lua-treesitter-directives*
Treesitter queries can also contain `directives`. Directives store metadata for a node
2021-08-01 08:09:19 -07:00
or match and perform side effects. For example, the |set!| predicate sets metadata on
2020-11-24 07:50:33 -07:00
the match or node : >
((identifier) @foo (#set! "type" "parameter"))
Here is a list of built-in directives:
`set!` *ts-directive-set!*
Sets key/value metadata for a specific node or match : >
((identifier) @foo (#set! @foo "kind" "parameter"))
((node1) @left (node2) @right (#set! "type" "pair"))
<
`offset!` *ts-predicate-offset!*
Takes the range of the captured node and applies the offsets
to it's range : >
((idenfitier) @constant (#offset! @constant 0 1 0 -1))
< This will generate a range object for the captured node with the
offsets applied. The arguments are
`({capture_id}, {start_row}, {start_col}, {end_row}, {end_col}, {key?})`
The default key is "offset".
2021-04-11 11:53:52 -07:00
*vim.treesitter.query.add_directive()*
vim.treesitter.query.add_directive({name}, {handler})
This adds a directive with the name {name} to be used in queries.
{handler} should be a function whose signature will be : >
handler(match, pattern, bufnr, predicate, metadata)
Handlers can set match level data by setting directly on the metadata object `metadata.key = value`
Handlers can set node level data by using the capture id on the metadata table
`metadata[capture_id].key = value`
*vim.treesitter.query.list_directives()*
vim.treesitter.query.list_directives()
This lists the currently available directives to use in queries.
2020-09-14 10:04:33 -07:00
Treesitter syntax highlighting (WIP) *lua-treesitter-highlight*
NOTE: This is a partially implemented feature, and not usable as a default
2020-12-07 00:08:23 -07:00
solution yet. What is documented here is a temporary interface intended
2020-09-14 10:04:33 -07:00
for those who want to experiment with this feature and contribute to
its development.
Highlights are defined in the same query format as in the tree-sitter highlight
2021-09-10 06:59:17 -07:00
crate, with some limitations and additions. Set a highlight query for a
2020-09-14 10:04:33 -07:00
buffer with this code: >
local query = [[
"for" @keyword
"if" @keyword
"return" @keyword
(string_literal) @string
(number_literal) @number
(comment) @comment
(preproc_function_def name: (identifier) @function)
; ... more definitions
]]
highlighter = vim.treesitter.TSHighlighter.new(query, bufnr, lang)
-- alternatively, to use the current buffer and its filetype:
-- highlighter = vim.treesitter.TSHighlighter.new(query)
-- Don't recreate the highlighter for the same buffer, instead
-- modify the query like this:
local query2 = [[ ... ]]
highlighter:set_query(query2)
As mentioned above the supported predicate is currently only `eq?`. `match?`
predicates behave like matching always fails. As an addition a capture which
begin with an upper-case letter like `@WarningMsg` will map directly to this
highlight group, if defined. Also if the predicate begins with upper-case and
contains a dot only the part before the first will be interpreted as the
highlight group. As an example, this warns of a binary expression with two
identical identifiers, highlighting both as |hl-WarningMsg|: >
((binary_expression left: (identifier) @WarningMsg.left right: (identifier) @WarningMsg.right)
(eq? @WarningMsg.left @WarningMsg.right))
2021-05-01 05:19:48 -07:00
<
2021-07-18 06:27:54 -07:00
Treesitter Highlighting Priority *lua-treesitter-highlight-priority*
Tree-sitter 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
; Give the whole query highlight priority higher than the default (100)
(set! "priority" 105)
)
<
2020-09-14 10:04:33 -07:00
2021-05-01 05:19:48 -07:00
==============================================================================
Lua module: vim.treesitter *lua-treesitter-core*
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
get_parser({bufnr}, {lang}, {opts}) *get_parser()*
Gets the parser for this bufnr / ft combination.
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
If needed this will create the parser. Unconditionnally attach
the provided callback
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Parameters: ~
{bufnr} The buffer the parser should be tied to
{lang} The filetype of this parser
{opts} Options object to pass to the created language
tree
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Return: ~
The parser
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
get_string_parser({str}, {lang}, {opts}) *get_string_parser()*
Gets a string parser
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Parameters: ~
{str} The string to parse
{lang} The language of this string
{opts} Options to pass to the created language tree
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
==============================================================================
Lua module: vim.treesitter.language *treesitter-language*
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
inspect_language({lang}) *inspect_language()*
Inspects the provided language.
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Inspecting provides some useful informations on the language
like node names, ...
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Parameters: ~
{lang} The language.
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
require_language({lang}, {path}, {silent}) *require_language()*
Asserts that the provided language is installed, and
optionally provide a path for the parser
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Parsers are searched in the `parser` runtime directory.
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Parameters: ~
{lang} The language the parser should parse
{path} Optional path the parser is located at
{silent} Don't throw an error if language not found
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
==============================================================================
Lua module: vim.treesitter.query *treesitter-query*
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
add_directive({name}, {handler}, {force}) *add_directive()*
Adds a new directive to be used in queries
Parameters: ~
{name} the name of the directive, without leading #
{handler} the handler function to be used signature will
be (match, pattern, bufnr, predicate)
add_predicate({name}, {handler}, {force}) *add_predicate()*
Adds a new predicate to be used in queries
Parameters: ~
{name} the name of the predicate, without leading #
{handler} the handler function to be used signature will
be (match, pattern, bufnr, predicate)
get_node_text({node}, {source}) *get_node_text()*
Gets the text corresponding to a given node
Parameters: ~
{node} the node
{bsource} The buffer or string from which the node is
extracted
get_query({lang}, {query_name}) *get_query()*
Returns the runtime query {query_name} for {lang}.
Parameters: ~
{lang} The language to use for the query
{query_name} The name of the query (i.e. "highlights")
Return: ~
The corresponding query, parsed.
*get_query_files()*
get_query_files({lang}, {query_name}, {is_included})
Gets the list of files used to make up a query
Parameters: ~
{lang} The language
{query_name} The name of the query to load
{is_included} Internal parameter, most of the time left
as `nil`
2021-07-25 11:47:24 -07:00
list_directives() *list_directives()*
Return: ~
The list of supported directives.
2021-05-01 05:19:48 -07:00
list_predicates() *list_predicates()*
2021-07-25 11:47:24 -07:00
Return: ~
The list of supported predicates.
2021-05-01 05:19:48 -07:00
parse_query({lang}, {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 information about the {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} The language
{query} A string containing the query (s-expr syntax)
Return: ~
The 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 relevent). {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:
>
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} The node under which the search will occur
{source} The source buffer or string to exctract text
from
{start} The starting line of the search
{stop} The stopping line of the search (end-exclusive)
{self}
Return: ~
The matching capture id
The captured node
*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 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
2021-08-29 09:38:11 -07:00
local node_data = metadata[id] -- Node level metadata
2021-05-01 05:19:48 -07:00
... use the info here ...
end
end
<
Parameters: ~
{node} The node under which the search will occur
{source} The source buffer or string to search
{start} The starting line of the search
{stop} The stopping line of the search (end-exclusive)
{self}
Return: ~
The matching pattern id
The matching match
set_query({lang}, {query_name}, {text}) *set_query()*
Sets the runtime query {query_name} for {lang}
This allows users to override any runtime files and/or
configuration set by plugins.
Parameters: ~
{lang} string: The language to use for the query
{query_name} string: The name of the query (i.e.
"highlights")
{text} string: The query text (unparsed).
==============================================================================
Lua module: vim.treesitter.highlighter *treesitter-highlighter*
new({tree}, {opts}) *highlighter.new()*
Creates a new highlighter using
Parameters: ~
{tree} The language tree to use for highlighting
{opts} Table used to configure the highlighter
• queries: Table to overwrite queries used by the
highlighter
TSHighlighter:destroy({self}) *TSHighlighter:destroy()*
Removes all internal references to the highlighter
Parameters: ~
{self}
TSHighlighter:get_query({self}, {lang}) *TSHighlighter:get_query()*
Gets the query used for
Parameters: ~
{lang} A language used by the highlighter.
{self}
==============================================================================
Lua module: vim.treesitter.languagetree *treesitter-languagetree*
LanguageTree:add_child({self}, {lang}) *LanguageTree:add_child()*
Adds a child language to this tree.
If the language already exists as a child, it will first be
removed.
Parameters: ~
{lang} The language to add.
{self}
LanguageTree:children({self}) *LanguageTree:children()*
Returns a map of language to child tree.
Parameters: ~
{self}
LanguageTree:contains({self}, {range}) *LanguageTree:contains()*
Determines wether This goes down the tree to recursively check childs.
Parameters: ~
{range} is contained in this language tree
Parameters: ~
{range} A range, that is a `{ start_line, start_col,
end_line, end_col }` table.
{self}
LanguageTree:destroy({self}) *LanguageTree:destroy()*
Destroys this language tree and all its children.
Any cleanup logic should be performed here. Note, this DOES
NOT remove this tree from a parent. `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 it's children
recursively
Parameters: ~
{fn} The function to invoke. This is invoked
with arguments (tree: LanguageTree, lang:
string)
{include_self} 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 treesitter trees recursively.
Note, this includes the invoking language tree's trees as
well.
Parameters: ~
{fn} The callback to invoke. The callback is invoked
with arguments (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, `parse()` must be called to get the an 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
Parameters: ~
{range} A text range, see |LanguageTree:contains|
{self}
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}
LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()*
Registers callbacks for the parser
Parameters: ~
{cbs} An `nvim_buf_attach` -like table argument with the following keys : `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, that 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:remove_child({self}, {lang}) *LanguageTree:remove_child()*
Removes a child language from this tree.
Parameters: ~
{lang} The language to remove.
{self}
*LanguageTree:set_included_regions()*
LanguageTree:set_included_regions({self}, {regions})
Sets the included regions that should be parsed by this
parser. A region is a set of nodes and/or ranges that will be
parsed in the same context.
For example, `{ { node1 }, { node2} }` is two separate
regions. This will be parsed by the parser in two different
contexts... thus resulting in two separate trees.
`{ { node1, node2 } }` is a single region consisting of two
nodes. This will be parsed by the parser in a single
context... thus resulting in a single tree.
This allows for embedded languages to be parsed together
across different nodes, which is useful for templating
languages like ERB and EJS.
Note, this call invalidates the tree and requires it to be
parsed again.
Parameters: ~
{regions} A list of regions this tree should manage and
parse.
{self}
LanguageTree:source({self}) *LanguageTree:source()*
Returns the source content of the language tree (bufnr or
string).
Parameters: ~
{self}
LanguageTree:trees({self}) *LanguageTree:trees()*
Returns all trees this language tree contains. Does not
include child languages.
Parameters: ~
{self}
new({source}, {lang}, {opts}) *languagetree.new()*
Represents a single treesitter parser for a language. The
language can contain child languages with in its range, hence
the tree.
2021-03-02 12:51:08 -07:00
2021-05-01 05:19:48 -07:00
Parameters: ~
{source} Can be a bufnr or a string of text to
parse
{lang} The language this tree represents
{opts} Options table
{opts.injections} A table of language to injection query
strings. This is useful for overriding
the built-in runtime file searching for
the injection language query per
language.
2021-03-02 12:51:08 -07:00
2020-09-14 10:04:33 -07:00
vim:tw=78:ts=8:ft=help:norl:
