kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-29 14:41:06 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: treesitter.txt - fix overflowing lines, document minimum_language_version (#17286)

Browse Source
This commit is contained in:
Chinmay Dalal 2022-02-13 19:13:25 +05:30 committed by GitHub
parent c5f5c0d4da
commit e481901748
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 88 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

128
runtime/doc/treesitter.txt
View File

@ -14,10 +14,12 @@ VIM.TREESITTER *lua-treesitter*
Nvim integrates the tree-sitter library for incremental parsing of buffers. Nvim integrates the tree-sitter library for incremental parsing of buffers.
*vim.treesitter.language_version* *vim.treesitter.language_version*
To check which language version is compiled with neovim, the number is stored The latest parser ABI version that is supported by the bundled tree-sitter
within `vim.treesitter.language_version`. This number is not too helpful library.
unless you are wondering about compatibility between different versions of
compiled grammars. *vim.treesitter.minimum_language_version*
The earliest parser ABI version that is supported by the bundled tree-sitter
library.
Parser files *treesitter-parsers* Parser files *treesitter-parsers*
@ -49,10 +51,10 @@ Whenever you need to access the current syntax tree, parse the buffer: >
tstree = parser:parse() tstree = parser:parse()
<This will return a table of immutable trees that represent the current state of the <This will return a table of immutable trees that represent the current state
buffer. When the plugin wants to access the state after a (possible) edit of the buffer. When the plugin wants to access the state after a (possible)
it should call `parse()` again. If the buffer wasn't edited, the same tree will edit it should call `parse()` again. If the buffer wasn't edited, the same tree
be returned again without extra work. If the buffer was parsed before, will be returned again without extra work. If the buffer was parsed before,
incremental parsing will be done of the changed parts. incremental parsing will be done of the changed parts.
Note: to use the parser directly inside a |nvim_buf_attach| Lua callback, you Note: to use the parser directly inside a |nvim_buf_attach| Lua callback, you
@ -61,9 +63,10 @@ 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 be very frequent. Rather a plugin that does any kind of analysis on a tree
should use a timer to throttle too frequent updates. should use a timer to throttle too frequent updates.
tsparser:set_included_regions({region_list}) *tsparser:set_included_regions()* tsparser:set_included_regions({region_list}) *tsparser:set_included_regions()*
Changes the regions the parser should consider. This is used for Changes the regions the parser should consider. This is used for
language injection. {region_list} should be of the form (all zero-based): > language injection. {region_list} should be of the form
(all zero-based): >
{ {
{node1, node2}, {node1, node2},
... ...
@ -92,13 +95,13 @@ tsnode:next_sibling() *tsnode:next_sibling()*
tsnode:prev_sibling() *tsnode:prev_sibling()* tsnode:prev_sibling() *tsnode:prev_sibling()*
Get the node's previous sibling. Get the node's previous sibling.
tsnode:next_named_sibling() *tsnode:next_named_sibling()* tsnode:next_named_sibling() *tsnode:next_named_sibling()*
Get the node's next named sibling. Get the node's next named sibling.
tsnode:prev_named_sibling() *tsnode:prev_named_sibling()* tsnode:prev_named_sibling() *tsnode:prev_named_sibling()*
Get the node's previous named sibling. Get the node's previous named sibling.
tsnode:iter_children() *tsnode:iter_children()* tsnode:iter_children() *tsnode:iter_children()*
Iterates over all the direct children of {tsnode}, regardless of Iterates over all the direct children of {tsnode}, regardless of
whether they are named or not. whether they are named or not.
Returns the child node plus the eventual field name corresponding to Returns the child node plus the eventual field name corresponding to
@ -114,10 +117,10 @@ tsnode:child({index}) *tsnode:child()*
Get the node's child at the given {index}, where zero represents the Get the node's child at the given {index}, where zero represents the
first child. first child.
tsnode:named_child_count() *tsnode:named_child_count()* tsnode:named_child_count() *tsnode:named_child_count()*
Get the node's number of named children. Get the node's number of named children.
tsnode:named_child({index}) *tsnode:named_child()* tsnode:named_child({index}) *tsnode:named_child()*
Get the node's named child at the given {index}, where zero represents Get the node's named child at the given {index}, where zero represents
the first named child. the first named child.
@ -157,20 +160,20 @@ tsnode:sexpr() *tsnode:sexpr()*
tsnode:id() *tsnode:id()* tsnode:id() *tsnode:id()*
Get an unique identifier for the node inside its own tree. Get an unique identifier for the node inside its own tree.
No guarantees are made about this identifier's internal representation, No guarantees are made about this identifier's internal
except for being a primitive lua type with value equality (so not a table). representation, except for being a primitive lua type with value
Presently it is a (non-printable) string. 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 Note: the id is not guaranteed to be unique for nodes from different
trees. trees.
*tsnode:descendant_for_range()*
tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) tsnode:descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
*tsnode:descendant_for_range()*
Get the smallest node within this node that spans the given range of Get the smallest node within this node that spans the given range of
(row, column) positions (row, column) positions
*tsnode:named_descendant_for_range()*
tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col}) tsnode:named_descendant_for_range({start_row}, {start_col}, {end_row}, {end_col})
*tsnode:named_descendant_for_range()*
Get the smallest named node within this node that spans the given Get the smallest named node within this node that spans the given
range of (row, column) positions range of (row, column) positions
@ -192,11 +195,11 @@ and predicates. A `capture` allows you to associate names with a specific
node in a pattern. A `predicate` adds arbitrary metadata and conditional data node in a pattern. A `predicate` adds arbitrary metadata and conditional data
to a match. to a match.
Treesitter Query Predicates *lua-treesitter-predicates* Treesitter Query Predicates *lua-treesitter-predicates*
When writing queries for treesitter, one might use `predicates`, that is, When writing queries for treesitter, one might use `predicates`, that is,
special scheme nodes that are evaluated to verify things on a captured node for special scheme nodes that are evaluated to verify things on a captured node
example, the |eq?| predicate : > for example, the |eq?| predicate : >
((identifier) @foo (#eq? @foo "foo")) ((identifier) @foo (#eq? @foo "foo"))
This will only match identifier corresponding to the `"foo"` text. This will only match identifier corresponding to the `"foo"` text.
@ -209,24 +212,24 @@ Here is a list of built-in predicates :
((node1) @left (node2) @right (#eq? @left @right)) ((node1) @left (node2) @right (#eq? @left @right))
< <
`match?` *ts-predicate-match?* `match?` *ts-predicate-match?*
`vim-match?` *ts-predicate-vim-match?* `vim-match?` *ts-predicate-vim-match?*
This will match if the provided vim regex matches the text This will match if the provided vim regex matches the text
corresponding to a node : > corresponding to a node : >
((identifier) @constant (#match? @constant "^[A-Z_]+$")) ((identifier) @constant (#match? @constant "^[A-Z_]+$"))
< Note: the `^` and `$` anchors will respectively match the < Note: the `^` and `$` anchors will respectively match the
start and end of the node's text. start and end of the node's text.
`lua-match?` *ts-predicate-lua-match?* `lua-match?` *ts-predicate-lua-match?*
This will match the same way than |match?| but using lua This will match the same way than |match?| but using lua
regexes. regexes.
`contains?` *ts-predicate-contains?* `contains?` *ts-predicate-contains?*
Will check if any of the following arguments appears in the Will check if any of the following arguments appears in the
text corresponding to the node : > text corresponding to the node : >
((identifier) @foo (#contains? @foo "foo")) ((identifier) @foo (#contains? @foo "foo"))
((identifier) @foo-bar (#contains @foo-bar "foo" "bar")) ((identifier) @foo-bar (#contains @foo-bar "foo" "bar"))
< <
`any-of?` *ts-predicate-any-of?* `any-of?` *ts-predicate-any-of?*
Will check if the text is the same as any of the following. Will check if the text is the same as any of the following.
This is the recommended way to check if the node matches one This is the recommended way to check if the node matches one
of many keywords for example, as it has been optimized for of many keywords for example, as it has been optimized for
@ -234,27 +237,27 @@ Here is a list of built-in predicates :
arguments : > arguments : >
((identifier) @foo (#any-of? @foo "foo" "bar")) ((identifier) @foo (#any-of? @foo "foo" "bar"))
< <
*lua-treesitter-not-predicate* *lua-treesitter-not-predicate*
Each predicate has a `not-` prefixed predicate that is just the negation of Each predicate has a `not-` prefixed predicate that is just the negation of
the predicate. the predicate.
*vim.treesitter.query.add_predicate()* *vim.treesitter.query.add_predicate()*
vim.treesitter.query.add_predicate({name}, {handler}) vim.treesitter.query.add_predicate({name}, {handler})
This adds a predicate with the name {name} to be used in queries. This adds a predicate with the name {name} to be used in queries.
{handler} should be a function whose signature will be : > {handler} should be a function whose signature will be : >
handler(match, pattern, bufnr, predicate) handler(match, pattern, bufnr, predicate)
< <
*vim.treesitter.query.list_predicates()* *vim.treesitter.query.list_predicates()*
vim.treesitter.query.list_predicates() vim.treesitter.query.list_predicates()
This lists the currently available predicates to use in queries. This lists the currently available predicates to use in queries.
Treesitter Query Directive *lua-treesitter-directives* Treesitter Query Directive *lua-treesitter-directives*
Treesitter queries can also contain `directives`. Directives store metadata for a node Treesitter queries can also contain `directives`. Directives store metadata
or match and perform side effects. For example, the |set!| predicate sets metadata on for a node or match and perform side effects. For example, the |set!|
the match or node : > predicate sets metadata on the match or node : >
((identifier) @foo (#set! "type" "parameter")) ((identifier) @foo (#set! "type" "parameter"))
Here is a list of built-in directives: Here is a list of built-in directives:
@ -268,8 +271,8 @@ Here is a list of built-in directives:
Takes the range of the captured node and applies the offsets Takes the range of the captured node and applies the offsets
to it's range : > to it's range : >
((identifier) @constant (#offset! @constant 0 1 0 -1)) ((identifier) @constant (#offset! @constant 0 1 0 -1))
< This will generate a range object for the captured node with the < This will generate a range object for the captured node with
offsets applied. The arguments are the offsets applied. The arguments are
`({capture_id}, {start_row}, {start_col}, {end_row}, {end_col}, {key?})` `({capture_id}, {start_row}, {start_col}, {end_row}, {end_col}, {key?})`
The default key is "offset". The default key is "offset".
@ -279,25 +282,25 @@ vim.treesitter.query.add_directive({name}, {handler})
This adds a directive with the name {name} to be used in queries. This adds a directive with the name {name} to be used in queries.
{handler} should be a function whose signature will be : > {handler} should be a function whose signature will be : >
handler(match, pattern, bufnr, predicate, metadata) 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 match level data by setting directly on the metadata object
Handlers can set node level data by using the capture id on the metadata table `metadata.key = value` Handlers can set node level data by using the capture
`metadata[capture_id].key = value` id on the metadata table `metadata[capture_id].key = value`
*vim.treesitter.query.list_directives()* *vim.treesitter.query.list_directives()*
vim.treesitter.query.list_directives() vim.treesitter.query.list_directives()
This lists the currently available directives to use in queries. This lists the currently available directives to use in queries.
Treesitter syntax highlighting (WIP) *lua-treesitter-highlight* Treesitter syntax highlighting (WIP) *lua-treesitter-highlight*
NOTE: This is a partially implemented feature, and not usable as a default NOTE: This is a partially implemented feature, and not usable as a default
solution yet. What is documented here is a temporary interface intended solution yet. What is documented here is a temporary interface intended
for those who want to experiment with this feature and contribute to for those who want to experiment with this feature and contribute to
its development. its development.
Highlights are defined in the same query format as in the tree-sitter highlight Highlights are defined in the same query format as in the tree-sitter
crate, with some limitations and additions. Set a highlight query for a highlight crate, with some limitations and additions. Set a highlight query
buffer with this code: > for a buffer with this code: >
local query = [[ local query = [[
"for" @keyword "for" @keyword
@ -338,7 +341,8 @@ Treesitter Highlighting Priority *lua-treesitter-highlight-priority*
Tree-sitter uses |nvim_buf_set_extmark()| to set highlights with a default 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 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 higher than tree-sitter. It is also possible to change the priority of an
individual query pattern manually by setting its `"priority"` metadata attribute: > individual query pattern manually by setting its `"priority"` metadata
attribute: >
( (
(super_important_node) @ImportantHighlight (super_important_node) @ImportantHighlight
@ -461,7 +465,7 @@ parse_query({lang}, {query}) *parse_query()*
can be used to search nodes in the syntax tree for the can be used to search nodes in the syntax tree for the
patterns defined in {query} using `iter_*` methods below. patterns defined in {query} using `iter_*` methods below.
Exposes `info` and `captures` with additional information about the {query}. Exposes `info` and `captures` with additional context about {query}.
• `captures` contains the list of unique capture names defined • `captures` contains the list of unique capture names defined
in {query}. - `info.captures` also points to `captures` . in {query}. - `info.captures` also points to `captures` .
• `info.patterns` contains information about predicates. • `info.patterns` contains information about predicates.
@ -609,10 +613,9 @@ LanguageTree:children({self}) *LanguageTree:children()*
{self} {self}
LanguageTree:contains({self}, {range}) *LanguageTree:contains()* LanguageTree:contains({self}, {range}) *LanguageTree:contains()*
Determines whether This goes down the tree to recursively check children. Determines whether {range} is contained in this language tree
Parameters: ~ This goes down the tree to recursively check children.
{range} is contained in this language tree
Parameters: ~ Parameters: ~
{range} A range, that is a `{ start_line, start_col, {range} A range, that is a `{ start_line, start_col,
@ -622,8 +625,9 @@ LanguageTree:contains({self}, {range}) *LanguageTree:contains()*
LanguageTree:destroy({self}) *LanguageTree:destroy()* LanguageTree:destroy({self}) *LanguageTree:destroy()*
Destroys this language tree and all its children. Destroys this language tree and all its children.
Any cleanup logic should be performed here. Note, this DOES Any cleanup logic should be performed here.
NOT remove this tree from a parent. `remove_child` must be called on the parent to remove it.
Note: This DOES NOT remove this tree from a parent. Instead, `remove_child` must be called on the parent to remove it.
Parameters: ~ Parameters: ~
{self} {self}
@ -666,7 +670,8 @@ LanguageTree:invalidate({self}, {reload}) *LanguageTree:invalidate()*
{self} {self}
LanguageTree:is_valid({self}) *LanguageTree:is_valid()* 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 updated tree. Determines whether this tree is valid. If the tree is invalid,
call `parse()` . This will return the updated tree.
Parameters: ~ Parameters: ~
{self} {self}
@ -679,7 +684,7 @@ LanguageTree:lang({self}) *LanguageTree:lang()*
*LanguageTree:language_for_range()* *LanguageTree:language_for_range()*
LanguageTree:language_for_range({self}, {range}) LanguageTree:language_for_range({self}, {range})
Gets the appropriate language that contains Gets the appropriate language that contains {range}
Parameters: ~ Parameters: ~
{range} A text range, see |LanguageTree:contains| {range} A text range, see |LanguageTree:contains|
@ -695,13 +700,22 @@ LanguageTree:parse({self}) *LanguageTree:parse()*
{self} {self}
LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()* LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()*
Registers callbacks for the parser Registers callbacks for the parser.
Parameters: ~ 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 {cbs} table An |nvim_buf_attach()|-like table argument
tree has syntactical changes. it will only be with the following keys :
passed one argument, that is a table of the ranges • `on_bytes` : see |nvim_buf_attach()|, but this will be
(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. 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} {self}
LanguageTree:remove_child({self}, {lang}) *LanguageTree:remove_child()* LanguageTree:remove_child({self}, {lang}) *LanguageTree:remove_child()*

28
runtime/lua/vim/treesitter/languagetree.lua
View File

@ -76,8 +76,8 @@ function LanguageTree:lang()
end end
--- Determines whether this tree is valid. --- Determines whether this tree is valid.
--- If the tree is invalid, `parse()` must be called --- If the tree is invalid, call `parse()`.
--- to get the updated tree. --- This will return the updated tree.
function LanguageTree:is_valid() function LanguageTree:is_valid()
return self._valid return self._valid
end end
@ -234,7 +234,9 @@ end
--- Destroys this language tree and all its children. --- Destroys this language tree and all its children.
--- ---
--- Any cleanup logic should be performed here. --- Any cleanup logic should be performed here.
--- Note, this DOES NOT remove this tree from a parent. ---
--- Note:
--- This DOES NOT remove this tree from a parent. Instead,
--- `remove_child` must be called on the parent to remove it. --- `remove_child` must be called on the parent to remove it.
function LanguageTree:destroy() function LanguageTree:destroy()
-- Cleanup here -- Cleanup here
@ -448,14 +450,14 @@ function LanguageTree:_on_detach(...)
self:_do_callback('detach', ...) self:_do_callback('detach', ...)
end end
--- Registers callbacks for the parser --- Registers callbacks for the parser.
---@param cbs An `nvim_buf_attach`-like table argument with the following keys : ---@param cbs table 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_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. --- - `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 --- It will only be passed one argument, which is a table of the ranges (as node ranges) that
--- changed. --- changed.
--- `on_child_added` : emitted when a child is added to the 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_child_removed` : emitted when a child is removed from the tree.
function LanguageTree:register_cbs(cbs) function LanguageTree:register_cbs(cbs)
if not cbs then return end if not cbs then return end
@ -493,7 +495,7 @@ local function tree_contains(tree, range)
return false return false
end end
--- Determines whether @param range is contained in this language tree --- Determines whether {range} is contained in this language tree
--- ---
--- This goes down the tree to recursively check children. --- This goes down the tree to recursively check children.
--- ---
@ -508,7 +510,7 @@ function LanguageTree:contains(range)
return false return false
end end
--- Gets the appropriate language that contains @param range --- Gets the appropriate language that contains {range}
--- ---
---@param range A text range, see |LanguageTree:contains| ---@param range A text range, see |LanguageTree:contains|
function LanguageTree:language_for_range(range) function LanguageTree:language_for_range(range)

4
runtime/lua/vim/treesitter/query.lua
View File

@ -146,13 +146,13 @@ local query_cache = setmetatable({}, {
}) })
--- Parse {query} as a string. (If the query is in a file, the caller --- Parse {query} as a string. (If the query is in a file, the caller
--- should read the contents into a string before calling). --- should read the contents into a string before calling).
--- ---
--- Returns a `Query` (see |lua-treesitter-query|) object which can be used to --- 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} --- search nodes in the syntax tree for the patterns defined in {query}
--- using `iter_*` methods below. --- using `iter_*` methods below.
--- ---
--- Exposes `info` and `captures` with additional information about the {query}. --- Exposes `info` and `captures` with additional context about {query}.
--- - `captures` contains the list of unique capture names defined in --- - `captures` contains the list of unique capture names defined in
--- {query}. --- {query}.
--- -` info.captures` also points to `captures`. --- -` info.captures` also points to `captures`.