mirrors/neovim
1
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-10-26 12:27:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(treesitter): clean up and update treesitter.txt (#20142)

Browse Source 
* add type annotations to code
* clean up and expand static documentation
* consistent use of tags for static and generated docs
This commit is contained in:
Christian Clason
2022-09-14 11:08:31 +02:00
committed by GitHub
parent 8b0b0a5c32
commit ddb762f401
10 changed files with 581 additions and 531 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
runtime/doc/lua.txt
View File

@@ -1587,7 +1587,7 @@ defaulttable({create}) *vim.defaulttable()*
They mimic defaultdict in python.
If `create` is `nil`, this will create a defaulttable whose constructor
If {create} is `nil`, this will create a defaulttable whose constructor
function is this function, effectively allowing to create nested tables on
the fly:
>

730
runtime/doc/treesitter.txt
View File

File diff suppressed because it is too large Load Diff

2
runtime/lua/vim/shared.lua
View File

@@ -720,7 +720,7 @@ end
---
--- They mimic defaultdict in python.
---
--- If @p create is @c nil, this will create a defaulttable whose constructor function is
--- If {create} is `nil`, this will create a defaulttable whose constructor function is
--- this function, effectively allowing to create nested tables on the fly:
---
--- <pre>

85
runtime/lua/vim/treesitter.lua
View File

@@ -25,15 +25,15 @@ setmetatable(M, {
end,
})
--- Creates a new parser.
--- Creates a new parser
---
--- It is not recommended to use this, use vim.treesitter.get_parser() instead.
--- It is not recommended to use this; use |get_parser()| instead.
---
---@param bufnr string Buffer the parser will be tied to (0 for current buffer)
---@param lang string Language of the parser
---@param opts table|nil Options to pass to the created language tree
---@param opts (table|nil) Options to pass to the created language tree
---
---@returns table Created parser object
---@return LanguageTree |LanguageTree| object to use for parsing
function M._create_parser(bufnr, lang, opts)
language.require_language(lang)
if bufnr == 0 then
@@ -73,16 +73,15 @@ function M._create_parser(bufnr, lang, opts)
return self
end
--- Gets the parser for this bufnr / ft combination.
--- Returns the parser for a specific buffer and filetype and attaches it to the buffer
---
--- If needed this will create the parser.
--- Unconditionally attach the provided callback
--- If needed, this will create the parser.
---
---@param bufnr number|nil Buffer the parser should be tied to (default: current buffer)
---@param lang string |nil Filetype of this parser (default: buffer filetype)
---@param opts table|nil Options to pass to the created language tree
---@param bufnr (number|nil) Buffer the parser should be tied to (default: current buffer)
---@param lang (string|nil) Filetype of this parser (default: buffer filetype)
---@param opts (table|nil) Options to pass to the created language tree
---
---@returns table Parser object
---@return LanguageTree |LanguageTree| object to use for parsing
function M.get_parser(bufnr, lang, opts)
opts = opts or {}
@@ -102,11 +101,13 @@ function M.get_parser(bufnr, lang, opts)
return parsers[bufnr]
end
--- Gets a string parser
--- Returns a string parser
---
---@param str The string to parse
---@param lang The language of this string
---@param opts Options to pass to the created language tree
---@param str string Text to parse
---@param lang string Language of this string
---@param opts (table|nil) Options to pass to the created language tree
---
---@return LanguageTree |LanguageTree| object to use for parsing
function M.get_string_parser(str, lang, opts)
vim.validate({
str = { str, 'string' },
@@ -119,10 +120,10 @@ end
--- Determines whether a node is the ancestor of another
---
---@param dest table Possible ancestor
---@param source table Possible descendant node
---@param dest userdata Possible ancestor |tsnode|
---@param source userdata Possible descendant |tsnode|
---
---@returns (boolean) True if dest is an ancestor of source
---@return boolean True if {dest} is an ancestor of {source}
function M.is_ancestor(dest, source)
if not (dest and source) then
return false
@@ -140,11 +141,11 @@ function M.is_ancestor(dest, source)
return false
end
--- Get the node's range or unpack a range table
--- Returns the node's range or an unpacked range table
---
---@param node_or_range table
---@param node_or_range (userdata|table) |tsnode| or table of positions
---
---@returns table start_row, start_col, end_row, end_col
---@return table `{ start_row, start_col, end_row, end_col }`
function M.get_node_range(node_or_range)
if type(node_or_range) == 'table' then
return unpack(node_or_range)
@@ -155,11 +156,11 @@ end
---Determines whether (line, col) position is in node range
---
---@param node table Node defining the range
---@param node userdata |tsnode| defining the range
---@param line number Line (0-based)
---@param col number Column (0-based)
---
---@returns (boolean) True if the position is in node range
---@return boolean True if the position is in node range
function M.is_in_node_range(node, line, col)
local start_line, start_col, end_line, end_col = M.get_node_range(node)
if line >= start_line and line <= end_line then
@@ -178,10 +179,10 @@ function M.is_in_node_range(node, line, col)
end
---Determines if a node contains a range
---@param node table
---@param node userdata |tsnode|
---@param range table
---
---@returns (boolean) True if the node contains the range
---@return boolean True if the {node} contains the {range}
function M.node_contains(node, range)
local start_row, start_col, end_row, end_col = node:range()
local start_fits = start_row < range[1] or (start_row == range[1] and start_col <= range[2])
@@ -190,7 +191,8 @@ function M.node_contains(node, range)
return start_fits and end_fits
end
---Gets a list of captures for a given cursor position
---Returns a list of highlight captures at the given position
--
---@param bufnr number Buffer number (0 for current buffer)
---@param row number Position row
---@param col number Position column
@@ -199,7 +201,7 @@ end
---@param row number Position row
---@param col number Position column
---
---@returns (table) Table of captures
---@return table[] Captures of the form `{ capture = "capture name", priority = capture priority }`
function M.get_captures_at_position(bufnr, row, col)
if bufnr == 0 then
bufnr = a.nvim_get_current_buf()
@@ -246,11 +248,11 @@ function M.get_captures_at_position(bufnr, row, col)
return matches
end
---Gets a list of captures under the cursor
---Returns a list of highlight capture names under the cursor
---
---@param winnr number|nil Window handle or 0 for current window (default)
---@param winnr (number|nil) Window handle or 0 for current window (default)
---
---@returns (table) Named node under the cursor
---@return string[] List of capture names
function M.get_captures_at_cursor(winnr)
winnr = winnr or 0
local bufnr = a.nvim_win_get_buf(winnr)
@@ -267,7 +269,7 @@ function M.get_captures_at_cursor(winnr)
return captures
end
--- Gets the smallest named node at position
--- Returns the smallest named node at the given position
---
---@param bufnr number Buffer number (0 for current buffer)
---@param row number Position row
@@ -275,7 +277,7 @@ end
---@param opts table Optional keyword arguments:
--- - ignore_injections boolean Ignore injected languages (default true)
---
---@returns (table) Named node under the cursor
---@return userdata |tsnode| under the cursor
function M.get_node_at_position(bufnr, row, col, opts)
if bufnr == 0 then
bufnr = a.nvim_get_current_buf()
@@ -290,11 +292,11 @@ function M.get_node_at_position(bufnr, row, col, opts)
return root_lang_tree:named_node_for_range(ts_range, opts)
end
--- Gets the smallest named node under the cursor
--- Returns the smallest named node under the cursor
---
---@param winnr number|nil Window handle or 0 for current window (default)
---@param winnr (number|nil) Window handle or 0 for current window (default)
---
---@returns (string) Named node under the cursor
---@return string Name of node under the cursor
function M.get_node_at_cursor(winnr)
winnr = winnr or 0
local bufnr = a.nvim_win_get_buf(winnr)
@@ -304,15 +306,14 @@ function M.get_node_at_cursor(winnr)
:type()
end
--- Start treesitter highlighting for a buffer
--- Starts treesitter highlighting for a buffer
---
--- Can be used in an ftplugin or FileType autocommand
--- 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:
---
--- <pre>
--- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
--- callback = function(args)
@@ -322,8 +323,8 @@ end
--- })
--- </pre>
---
---@param bufnr number|nil Buffer to be highlighted (default: current buffer)
---@param lang string|nil Language of the parser (default: buffer filetype)
---@param bufnr (number|nil) Buffer to be highlighted (default: current buffer)
---@param lang (string|nil) Language of the parser (default: buffer filetype)
function M.start(bufnr, lang)
bufnr = bufnr or a.nvim_get_current_buf()
@@ -334,9 +335,9 @@ function M.start(bufnr, lang)
vim.b[bufnr].ts_highlight = true
end
---Stop treesitter highlighting for a buffer
--- Stops treesitter highlighting for a buffer
---
---@param bufnr number|nil Buffer to stop highlighting (default: current buffer)
---@param bufnr (number|nil) Buffer to stop highlighting (default: current buffer)
function M.stop(bufnr)
bufnr = bufnr or a.nvim_get_current_buf()

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

@@ -3,7 +3,7 @@ local ts = vim.treesitter
--- Lists the parsers currently installed
---
---@return A list of parsers
---@return string[] list of parser files
function M.list_parsers()
return vim.api.nvim_get_runtime_file('parser/*', true)
end

14
runtime/lua/vim/treesitter/highlighter.lua
View File

@@ -2,6 +2,7 @@ local a = vim.api
local query = require('vim.treesitter.query')
-- support reload for quick experimentation
---@class TSHighlighter
local TSHighlighter = rawget(vim.treesitter, 'TSHighlighter') or {}
TSHighlighter.__index = TSHighlighter
@@ -45,9 +46,10 @@ end
--- Creates a new highlighter using @param tree
---
---@param tree The language tree to use for highlighting
---@param opts Table used to configure the highlighter
--- - queries: Table to overwrite queries used by the highlighter
---@param tree LanguageTree |LanguageTree| parser object to use for highlighting
---@param opts (table|nil) Configuration of the highlighter:
--- - queries table overwrite queries used by the highlighter
---@return TSHighlighter Created highlighter object
function TSHighlighter.new(tree, opts)
local self = setmetatable({}, TSHighlighter)
@@ -149,8 +151,10 @@ function TSHighlighter:on_changedtree(changes)
end
--- Gets the query used for @param lang
---
---@param lang A language used by the highlighter.
--
---@private
---@param lang string Language used by the highlighter.
---@return Query
function TSHighlighter:get_query(lang)
if not self._queries[lang] then
self._queries[lang] = TSHighlighterQuery.new(lang)

16
runtime/lua/vim/treesitter/language.lua
View File

@@ -2,14 +2,15 @@ local a = vim.api
local M = {}
--- Asserts that the provided language is installed, and optionally provide a path for the parser
--- Asserts that a parser for the language {lang} is installed.
---
--- Parsers are searched in the `parser` runtime directory.
--- Parsers are searched in the `parser` runtime directory, or the provided {path}
---
---@param lang string The language the parser should parse
---@param path string|nil Optional path the parser is located at
---@param silent boolean|nil Don't throw an error if language not found
---@param symbol_name string|nil Internal symbol name for the language to load
---@param lang string Language the parser should parse
---@param path (string|nil) Optional path the parser is located at
---@param silent (boolean|nil) Don't throw an error if language not found
---@param symbol_name (string|nil) Internal symbol name for the language to load
---@return boolean If the specified language is installed
function M.require_language(lang, path, silent, symbol_name)
if vim._ts_has_language(lang) then
return true
@@ -42,7 +43,8 @@ end
---
--- Inspecting provides some useful information on the language like node names, ...
---
---@param lang The language.
---@param lang string Language
---@return table
function M.inspect_language(lang)
M.require_language(lang)
return vim._ts_inspect_language(lang)

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

@@ -2,19 +2,35 @@ local a = vim.api
local query = require('vim.treesitter.query')
local language = require('vim.treesitter.language')
---@class LanguageTree
---@field _callbacks function[] Callback handlers
---@field _children LanguageTree[] Injected languages
---@field _injection_query table Queries defining injected languages
---@field _opts table Options
---@field _parser userdata Parser for language
---@field _regions table List of regions this tree should manage and parse
---@field _lang string Language name
---@field _regions table
---@field _source (number|string) Buffer or string to parse
---@field _trees userdata[] Reference to parsed |tstree| (one for each language)
---@field _valid boolean If the parsed tree is valid
local LanguageTree = {}
LanguageTree.__index = LanguageTree
--- Represents a single treesitter parser for a language.
--- The language can contain child languages with in its range,
--- hence the tree.
--- 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).
---
---@param source Can be a bufnr or a string of text to parse
---@param lang The language this tree represents
---@param opts Options table
---@param 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.
---@param source (number|string) Buffer or a string of text to parse
---@param lang string Root language this tree represents
---@param 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
function LanguageTree.new(source, lang, opts)
language.require_language(lang)
opts = opts or {}
@@ -94,6 +110,9 @@ end
--- for the language this tree represents.
--- This will run the injection query for this language to
--- determine if any child languages should be created.
---
---@return userdata[] Table of parsed |tstree|
---@return table Change list
function LanguageTree:parse()
if self._valid then
return self._trees
@@ -167,10 +186,10 @@ function LanguageTree:parse()
return self._trees, changes
end
--- Invokes the callback for each LanguageTree and it's children recursively
--- Invokes the callback for each |LanguageTree| and its children recursively
---
---@param fn The function to invoke. This is invoked with arguments (tree: LanguageTree, lang: string)
---@param include_self Whether to include the invoking tree in the results.
---@param fn function(tree: LanguageTree, lang: string)
---@param include_self boolean Whether to include the invoking tree in the results
function LanguageTree:for_each_child(fn, include_self)
if include_self then
fn(self, self._lang)
@@ -181,12 +200,11 @@ function LanguageTree:for_each_child(fn, include_self)
end
end
--- Invokes the callback for each treesitter trees recursively.
--- Invokes the callback for each |LanguageTree| recursively.
---
--- Note, this includes the invoking language tree's trees as well.
--- Note: This includes the invoking tree's child trees as well.
---
---@param fn The callback to invoke. The callback is invoked with arguments
--- (tree: TSTree, languageTree: LanguageTree)
---@param fn function(tree: TSTree, languageTree: LanguageTree)
function LanguageTree:for_each_tree(fn)
for _, tree in ipairs(self._trees) do
fn(tree, self)
@@ -197,11 +215,13 @@ function LanguageTree:for_each_tree(fn)
end
end
--- Adds a child language to this tree.
--- Adds a child language to this |LanguageTree|.
---
--- If the language already exists as a child, it will first be removed.
---
---@param lang The language to add.
---@private
---@param lang string Language to add.
---@return LanguageTree Injected |LanguageTree|
function LanguageTree:add_child(lang)
if self._children[lang] then
self:remove_child(lang)
@@ -215,9 +235,10 @@ function LanguageTree:add_child(lang)
return self._children[lang]
end
--- Removes a child language from this tree.
--- Removes a child language from this |LanguageTree|.
---
---@param lang The language to remove.
---@private
---@param lang string Language to remove.
function LanguageTree:remove_child(lang)
local child = self._children[lang]
@@ -229,12 +250,11 @@ function LanguageTree:remove_child(lang)
end
end
--- Destroys this language tree and all its children.
--- 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,
--- 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
@@ -243,23 +263,24 @@ function LanguageTree:destroy()
end
end
--- Sets the included regions that should be parsed by this parser.
--- Sets the included regions that should be parsed by this |LanguageTree|.
--- 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
--- For example, `{ { node1 }, { node2} }` contains two separate regions.
--- They 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
--- On the other hand, `{ { 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.
--- Note: This call invalidates the tree and requires it to be parsed again.
---
---@param regions (table) list of regions this tree should manage and parse.
---@private
---@param regions table List of regions this tree should manage and parse.
function LanguageTree:set_included_regions(regions)
-- Transform the tables from 4 element long to 6 element long (with byte offset)
for _, region in ipairs(regions) do
@@ -288,7 +309,7 @@ function LanguageTree:set_included_regions(regions)
-- Trees are no longer valid now that we have changed regions.
-- TODO(vigoux,steelsojka): Look into doing this smarter so we can use some of the
-- old trees for incremental parsing. Currently, this only
-- effects injected languages.
-- affects injected languages.
self._trees = {}
self:invalidate()
end
@@ -493,8 +514,8 @@ function LanguageTree:_on_detach(...)
self:_do_callback('detach', ...)
end
--- Registers callbacks for the parser.
---@param cbs table An |nvim_buf_attach()|-like table argument with the following keys :
--- Registers callbacks for the |LanguageTree|.
---@param 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
@@ -536,9 +557,10 @@ local function tree_contains(tree, range)
return start_fits and end_fits
end
--- Determines whether {range} is contained in this language tree
--- Determines whether {range} is contained in the |LanguageTree|.
---
---@param range A range, that is a `{ start_line, start_col, end_line, end_col }` table.
---@param range table `{ start_line, start_col, end_line, end_col }`
---@return boolean
function LanguageTree:contains(range)
for _, tree in pairs(self._trees) do
if tree_contains(tree, range) then
@@ -549,11 +571,12 @@ function LanguageTree:contains(range)
return false
end
--- Gets the tree that contains {range}
--- Gets the tree that contains {range}.
---
---@param range table A text range
---@param opts table Options table
---@param opts.ignore_injections boolean (default true) Ignore injected languages.
---@param range table `{ start_line, start_col, end_line, end_col }`
---@param opts table|nil Optional keyword arguments:
--- - ignore_injections boolean Ignore injected languages (default true)
---@return userdata|nil Contained |tstree|
function LanguageTree:tree_for_range(range, opts)
opts = opts or {}
local ignore = vim.F.if_nil(opts.ignore_injections, true)
@@ -577,19 +600,21 @@ function LanguageTree:tree_for_range(range, opts)
return nil
end
--- Gets the smallest named node that contains {range}
--- Gets the smallest named node that contains {range}.
---
---@param range table A text range
---@param opts table Options table
---@param opts.ignore_injections boolean (default true) Ignore injected languages.
---@param range table `{ start_line, start_col, end_line, end_col }`
---@param opts table|nil Optional keyword arguments:
--- - ignore_injections boolean Ignore injected languages (default true)
---@return userdata|nil Found |tsnode|
function LanguageTree:named_node_for_range(range, opts)
local tree = self:tree_for_range(range, opts)
return tree:root():named_descendant_for_range(unpack(range))
end
--- Gets the appropriate language that contains {range}
--- Gets the appropriate language that contains {range}.
---
---@param range A text range, see |LanguageTree:contains|
---@param range table `{ start_line, start_col, end_line, end_col }`
---@return LanguageTree Managing {range}
function LanguageTree:language_for_range(range)
for _, child in pairs(self._children) do
if child:contains(range) then

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

@@ -3,6 +3,11 @@ local language = require('vim.treesitter.language')
-- query: pattern matching on trees
-- predicate matching is implemented in lua
--
---@class Query
---@field captures string[] List of captures used in query
---@field info table Contains used queries, predicates, directives
---@field query userdata Parsed query
local Query = {}
Query.__index = Query
@@ -35,9 +40,9 @@ local function safe_read(filename, read_quantifier)
end
---@private
--- Adds @p ilang to @p base_langs, only if @p ilang is different than @lang
--- Adds {ilang} to {base_langs}, only if {ilang} is different than {lang}
---
---@return boolean true it lang == ilang
---@return boolean true If lang == ilang
local function add_included_lang(base_langs, lang, ilang)
if lang == ilang then
return true
@@ -48,9 +53,10 @@ end
--- Gets the list of files used to make up a query
---
---@param lang The language
---@param query_name The name of the query to load
---@param is_included Internal parameter, most of the time left as `nil`
---@param lang string Language to get query for
---@param query_name string Name of the query to load (e.g., 'highlights')
---@param 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
function M.get_query_files(lang, query_name, is_included)
local query_path = string.format('queries/%s/%s.scm', lang, query_name)
local lang_files = dedupe_files(a.nvim_get_runtime_file(query_path, true))
@@ -150,24 +156,24 @@ local explicit_queries = setmetatable({}, {
end,
})
--- Sets the runtime query {query_name} for {lang}
--- Sets the runtime query named {query_name} for {lang}
---
--- This allows users to override any runtime files and/or configuration
--- set by plugins.
---
---@param lang string: The language to use for the query
---@param query_name string: The name of the query (i.e. "highlights")
---@param text string: The query text (unparsed).
---@param lang string Language to use for the query
---@param query_name string Name of the query (e.g., 'highlights')
---@param text string Query text (unparsed).
function M.set_query(lang, query_name, text)
explicit_queries[lang][query_name] = M.parse_query(lang, text)
end
--- Returns the runtime query {query_name} for {lang}.
---
---@param lang The language to use for the query
---@param query_name The name of the query (i.e. "highlights")
---@param lang string Language to use for the query
---@param query_name string Name of the query (e.g. 'highlights')
---
---@return The corresponding query, parsed.
---@return Query Parsed query
function M.get_query(lang, query_name)
if explicit_queries[lang][query_name] then
return explicit_queries[lang][query_name]
@@ -198,10 +204,10 @@ end)
--- -` info.captures` also points to `captures`.
--- - `info.patterns` contains information about predicates.
---
---@param lang string The language
---@param query string A string containing the query (s-expr syntax)
---@param lang string Language to use for the query
---@param query string Query in s-expr syntax
---
---@returns The query
---@return Query Parsed query
function M.parse_query(lang, query)
language.require_language(lang)
local cached = query_cache[lang][query]
@@ -219,10 +225,11 @@ end
--- Gets the text corresponding to a given node
---
---@param node table The node
---@param source table The buffer or string from which the node is extracted
---@param opts table Optional parameters.
--- - concat: (boolean default true) Concatenate result in a string
---@param node userdata |tsnode|
---@param source (number|string) Buffer or string from which the {node} is extracted
---@param opts (table|nil) Optional parameters.
--- - concat: (boolean) Concatenate result in a string (default true)
---@return (string[]|string)
function M.get_node_text(node, source, opts)
opts = opts or {}
local concat = vim.F.if_nil(opts.concat, true)
@@ -410,9 +417,8 @@ local directive_handlers = {
--- Adds a new predicate to be used in queries
---
---@param name the name of the predicate, without leading #
---@param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate)
---@param name string Name of the predicate, without leading #
---@param handler function(match:string, pattern:string, bufnr:number, predicate:function)
function M.add_predicate(name, handler, force)
if predicate_handlers[name] and not force then
error(string.format('Overriding %s', name))
@@ -428,9 +434,8 @@ end
--- can set node level data by using the capture id on the
--- metadata table `metadata[capture_id].key = value`
---
---@param name the name of the directive, without leading #
---@param handler the handler function to be used
--- signature will be (match, pattern, bufnr, predicate, metadata)
---@param name string Name of the directive, without leading #
---@param handler function(match:string, pattern:string, bufnr:number, predicate:function, metadata:table)
function M.add_directive(name, handler, force)
if directive_handlers[name] and not force then
error(string.format('Overriding %s', name))
@@ -440,12 +445,13 @@ function M.add_directive(name, handler, force)
end
--- Lists the currently available directives to use in queries.
---@return The list of supported directives.
---@return string[] List of supported directives.
function M.list_directives()
return vim.tbl_keys(directive_handlers)
end
---@return The list of supported predicates.
--- Lists the currently available predicates to use in queries.
---@return string[] List of supported predicates.
function M.list_predicates()
return vim.tbl_keys(predicate_handlers)
end
@@ -532,17 +538,16 @@ end
--- Iterate over all captures from all matches inside {node}
---
--- {source} is needed if the query contains predicates, then the caller
--- {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.
--- 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 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:
---
--- <pre>
--- 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
@@ -553,13 +558,14 @@ end
--- end
--- </pre>
---
---@param node The node under which the search will occur
---@param source The source buffer or string to extract text from
---@param start The starting line of the search
---@param stop The stopping line of the search (end-exclusive)
---@param node userdata |tsnode| under which the search will occur
---@param source (number|string) Source buffer or string to extract text from
---@param start number Starting line for the search
---@param stop number Stopping line for the search (end-exclusive)
---
---@returns The matching capture id
---@returns The captured node
---@return number capture Matching capture id
---@return table capture_node Capture for {node}
---@return table metadata for the {capture}
function Query:iter_captures(node, source, start, stop)
if type(source) == 'number' and source == 0 then
source = vim.api.nvim_get_current_buf()
@@ -589,14 +595,13 @@ end
--- Iterates the matches of self on a given range.
---
--- Iterate over all matches within a node. The arguments are the same as
--- 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,
--- 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:
---
--- Here is an example iterating over all captures in every match:
--- <pre>
--- for pattern, match, metadata in cquery:iter_matches(tree:root(), bufnr, first, last) do
--- for id, node in pairs(match) do
@@ -610,13 +615,14 @@ end
--- end
--- </pre>
---
---@param node The node under which the search will occur
---@param source The source buffer or string to search
---@param start The starting line of the search
---@param stop The stopping line of the search (end-exclusive)
---@param node userdata |tsnode| under which the search will occur
---@param source (number|string) Source buffer or string to search
---@param start number Starting line for the search
---@param stop number Stopping line for the search (end-exclusive)
---
---@returns The matching pattern id
---@returns The matching match
---@return number pattern id
---@return table match
---@return table metadata
function Query:iter_matches(node, source, start, stop)
if type(source) == 'number' and source == 0 then
source = vim.api.nvim_get_current_buf()

2
scripts/gen_vimdoc.py
View File

@@ -260,7 +260,7 @@ CONFIG = {
'helptag_fmt': lambda name: (
'*lua-treesitter-core*'
if name.lower() == 'treesitter'
else f'*treesitter-{name.lower()}*'),
else f'*lua-treesitter-{name.lower()}*'),
'fn_helptag_fmt': lambda fstem, name: (
f'*{name}()*'
if name != 'new'