kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-20 11:15:14 -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

96
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.
*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.
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.
Parser files *treesitter-parsers*
@ -49,10 +51,10 @@ Whenever you need to access the current syntax tree, parse the buffer: >
tstree = parser:parse()
<This will return a table of immutable trees 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,
<This will return a table of immutable trees 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
@ -63,7 +65,8 @@ should use a timer to throttle too frequent updates.
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): >
language injection. {region_list} should be of the form
(all zero-based): >
{
{node1, node2},
...
@ -157,20 +160,20 @@ tsnode:sexpr() *tsnode:sexpr()*
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.
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({start_row}, {start_col}, {end_row}, {end_col})
*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({start_row}, {start_col}, {end_row}, {end_col})
*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
@ -195,8 +198,8 @@ to a match.
Treesitter Query Predicates *lua-treesitter-predicates*
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
example, the |eq?| predicate : >
special scheme nodes that are evaluated 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.
@ -252,9 +255,9 @@ This lists the currently available predicates to use in queries.
Treesitter Query Directive *lua-treesitter-directives*
Treesitter queries can also contain `directives`. Directives store metadata for a node
or match and perform side effects. For example, the |set!| predicate sets metadata on
the match or node : >
Treesitter queries can also contain `directives`. Directives store metadata
for a node or match and perform side effects. For example, the |set!|
predicate sets metadata on the match or node : >
((identifier) @foo (#set! "type" "parameter"))
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
to it's range : >
((identifier) @constant (#offset! @constant 0 1 0 -1))
< This will generate a range object for the captured node with the
offsets applied. The arguments are
< 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".
@ -279,9 +282,9 @@ 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`
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()
@ -295,9 +298,9 @@ solution yet. What is documented here is a temporary interface intended
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
crate, with some limitations and additions. Set a highlight query for a
buffer with this code: >
Highlights are defined in the same query format as in the tree-sitter
highlight crate, with some limitations and additions. Set a highlight query
for a buffer with this code: >
local query = [[
"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
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: >
individual query pattern manually by setting its `"priority"` metadata
attribute: >
(
(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
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
in {query}. - `info.captures` also points to `captures` .
• `info.patterns` contains information about predicates.
@ -609,10 +613,9 @@ LanguageTree:children({self}) *LanguageTree:children()*
{self}
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: ~
{range} is contained in this language tree
This goes down the tree to recursively check children.
Parameters: ~
{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()*
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.
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}
@ -666,7 +670,8 @@ LanguageTree:invalidate({self}, {reload}) *LanguageTree:invalidate()*
{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 updated tree.
Determines whether this tree is valid. If the tree is invalid,
call `parse()` . This will return the updated tree.
Parameters: ~
{self}
@ -679,7 +684,7 @@ LanguageTree:lang({self}) *LanguageTree:lang()*
*LanguageTree:language_for_range()*
LanguageTree:language_for_range({self}, {range})
Gets the appropriate language that contains
Gets the appropriate language that contains {range}
Parameters: ~
{range} A text range, see |LanguageTree:contains|
@ -695,13 +700,22 @@ LanguageTree:parse({self}) *LanguageTree:parse()*
{self}
LanguageTree:register_cbs({self}, {cbs}) *LanguageTree:register_cbs()*
Registers callbacks for the parser
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.
{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_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:remove_child({self}, {lang}) *LanguageTree:remove_child()*

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

@ -76,8 +76,8 @@ function LanguageTree:lang()
end
--- Determines whether this tree is valid.
--- If the tree is invalid, `parse()` must be called
--- to get the updated tree.
--- If the tree is invalid, call `parse()`.
--- This will return the updated tree.
function LanguageTree:is_valid()
return self._valid
end
@ -234,7 +234,9 @@ end
--- 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.
---
--- Note:
--- This DOES NOT remove this tree from a parent. Instead,
--- `remove_child` must be called on the parent to remove it.
function LanguageTree:destroy()
-- Cleanup here
@ -448,14 +450,14 @@ function LanguageTree:_on_detach(...)
self:_do_callback('detach', ...)
end
--- Registers callbacks for the parser
---@param 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
--- Registers callbacks for the parser.
---@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_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.
--- - `on_child_added` : emitted when a child is added to the tree.
--- - `on_child_removed` : emitted when a child is removed from the tree.
function LanguageTree:register_cbs(cbs)
if not cbs then return end
@ -493,7 +495,7 @@ local function tree_contains(tree, range)
return false
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.
---
@ -508,7 +510,7 @@ function LanguageTree:contains(range)
return false
end
--- Gets the appropriate language that contains @param range
--- Gets the appropriate language that contains {range}
---
---@param range A text range, see |LanguageTree:contains|
function LanguageTree:language_for_range(range)

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

@ -152,7 +152,7 @@ local query_cache = setmetatable({}, {
--- 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}.
--- 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`.