feat(treesitter)!: deprecate top level indexes to modules (#22761)

The following top level Treesitter functions have been moved:
  - vim.treesitter.inspect_language() -> vim.treesitter.language.inspect()
  - vim.treesitter.get_query_files() -> vim.treesitter.query.get_files()
  - vim.treesitter.set_query() -> vim.treesitter.query.set()
  - vim.treesitter.query.set_query() -> vim.treesitter.query.set()
  - vim.treesitter.get_query() -> vim.treesitter.query.get()
  - vim.treesitter.query.get_query() -> vim.treesitter.query.get()
  - vim.treesitter.parse_query() -> vim.treesitter.query.parse()
  - vim.treesitter.query.parse_query() -> vim.treesitter.query.parse()
  - vim.treesitter.add_predicate() -> vim.treesitter.query.add_predicate()
  - vim.treesitter.add_directive() -> vim.treesitter.query.add_directive()
  - vim.treesitter.list_predicates() -> vim.treesitter.query.list_predicates()
  - vim.treesitter.list_directives() -> vim.treesitter.query.list_directives()
  - vim.treesitter.query.get_range() -> vim.treesitter.get_range()
  - vim.treesitter.query.get_node_text() -> vim.treesitter.get_node_text()
This commit is contained in:
Lewis Russell 2023-03-24 14:43:14 +00:00 committed by GitHub
parent ee5008f878
commit cbbf8bd666
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 258 additions and 177 deletions

View File

@ -122,7 +122,7 @@ LSP FUNCTIONS
or |vim.lsp.buf.format()| instead.
TREESITTER FUNCTIONS
- *vim.treesitter.language.require_language()* Use |vim.treesitter.add()|
- *vim.treesitter.language.require_language()* Use |vim.treesitter.language.add()|
instead.
- *vim.treesitter.get_node_at_pos()* Use |vim.treesitter.get_node()|
instead.

View File

@ -180,9 +180,9 @@ The following new APIs or features were added.
more complicated dynamic language injections.
• |vim.treesitter.get_node_text()| now accepts a `metadata` option for
writing custom directives using |vim.treesitter.add_directive()|.
writing custom directives using |vim.treesitter.query.add_directive()|.
• |vim.treesitter.add()| replaces `vim.treesitter.language.require_language`.
• |vim.treesitter.language.add()| replaces `vim.treesitter.language.require_language`.
• `require'bit'` is now always available |lua-bit|
@ -275,11 +275,27 @@ DEPRECATIONS *news-deprecations*
The following functions are now deprecated and will be removed in the next
release.
• |vim.treesitter.add()| replaces `vim.treesitter.language.require_language()`
• |vim.treesitter.language.add()| replaces `vim.treesitter.language.require_language()`
• |vim.treesitter.get_node_at_pos()| and |vim.treesitter.get_node_at_cursor()|
are both deprecated in favor of |vim.treesitter.get_node()|.
• `vim.api.nvim_get_hl_by_name()`, `vim.api.nvim_get_hl_by_id()` were deprecated, use |nvim_get_hl()| instead.
• The following top level Treesitter functions have been moved:
`vim.treesitter.inspect_language()` -> `vim.treesitter.language.inspect()`
`vim.treesitter.get_query_files()` -> `vim.treesitter.query.get_files()`
`vim.treesitter.set_query()` -> `vim.treesitter.query.set()`
`vim.treesitter.query.set_query()` -> `vim.treesitter.query.set()`
`vim.treesitter.get_query()` -> `vim.treesitter.query.get()`
`vim.treesitter.query.get_query()` -> `vim.treesitter.query.get()`
`vim.treesitter.parse_query()` -> `vim.treesitter.query.parse()`
`vim.treesitter.query.parse_query()` -> `vim.treesitter.query.parse()`
`vim.treesitter.add_predicate()` -> `vim.treesitter.query.add_predicate()`
`vim.treesitter.add_directive()` -> `vim.treesitter.query.add_directive()`
`vim.treesitter.list_predicates()` -> `vim.treesitter.query.list_predicates()`
`vim.treesitter.list_directives()` -> `vim.treesitter.query.list_directives()`
`vim.treesitter.query.get_range()` -> `vim.treesitter.get_range()`
`vim.treesitter.query.get_node_text()` -> `vim.treesitter.get_node_text()`
vim:tw=78:ts=8:sw=2:et:ft=help:norl:

View File

@ -26,7 +26,7 @@ If multiple parsers for the same language are found, the first one is used.
(This typically implies the priority "user config > plugins > bundled".
A parser can also be loaded manually using a full path: >lua
vim.treesitter.require_language("python", "/path/to/python.so")
vim.treesitter.language.add('python', { path = "/path/to/python.so" })
<
==============================================================================
TREESITTER TREES *treesitter-tree*
@ -236,8 +236,8 @@ The following predicates are built in:
Each predicate has a `not-` prefixed predicate that is just the negation of
the predicate.
Further predicates can be added via |vim.treesitter.add_predicate()|.
Use |vim.treesitter.list_predicates()| to list all available predicates.
Further predicates can be added via |vim.treesitter.query.add_predicate()|.
Use |vim.treesitter.query.list_predicates()| to list all available predicates.
TREESITTER QUERY DIRECTIVES *treesitter-directives*
@ -279,8 +279,8 @@ The following directives are built in:
((identifier) @constant (#offset! @constant 0 1 0 -1))
<
Further directives can be added via |vim.treesitter.add_directive()|.
Use |vim.treesitter.list_directives()| to list all available directives.
Further directives can be added via |vim.treesitter.query.add_directive()|.
Use |vim.treesitter.query.list_directives()| to list all available directives.
TREESITTER QUERY MODELINES *treesitter-query-modeline*
@ -575,6 +575,22 @@ get_node_range({node_or_range}) *vim.treesitter.get_node_range()*
(integer) end_row
(integer) end_col
*vim.treesitter.get_node_text()*
get_node_text({node}, {source}, {opts})
Gets the text corresponding to a given node
Parameters: ~
• {node} |TSNode|
• {source} (integer|string) Buffer or string from which the {node} is
extracted
• {opts} (table|nil) Optional parameters.
• metadata (table) Metadata of a specific capture. This
would be set to `metadata[capture_id]` when using
|vim.treesitter.query.add_directive()|.
Return: ~
(string)
get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
Returns the parser for a specific buffer and filetype and attaches it to
the buffer
@ -591,6 +607,19 @@ get_parser({bufnr}, {lang}, {opts}) *vim.treesitter.get_parser()*
Return: ~
|LanguageTree| object to use for parsing
get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()*
Get the range of a |TSNode|. Can also supply {source} and {metadata} to
get the range with directives applied.
Parameters: ~
• {node} |TSNode|
• {source} integer|string|nil Buffer or string from which the {node}
is extracted
• {metadata} TSMetadata|nil
Return: ~
(table)
*vim.treesitter.get_string_parser()*
get_string_parser({str}, {lang}, {opts})
Returns a string parser
@ -698,7 +727,7 @@ stop({bufnr}) *vim.treesitter.stop()*
==============================================================================
Lua module: vim.treesitter.language *lua-treesitter-language*
add({lang}, {opts}) *vim.treesitter.add()*
add({lang}, {opts}) *vim.treesitter.language.add()*
Asserts that a parser for the language {lang} is installed.
Parsers are searched in the `parser` runtime directory, or the provided
@ -716,14 +745,14 @@ add({lang}, {opts}) *vim.treesitter.add()*
• symbol_name (string|nil) Internal symbol name for the
language to load
get_lang({filetype}) *vim.treesitter.get_lang()*
get_lang({filetype}) *vim.treesitter.language.get_lang()*
Parameters: ~
• {filetype} (string)
Return: ~
(string|nil)
inspect_language({lang}) *vim.treesitter.inspect_language()*
inspect({lang}) *vim.treesitter.language.inspect()*
Inspects the provided language.
Inspecting provides some useful information on the language like node
@ -735,7 +764,7 @@ inspect_language({lang}) *vim.treesitter.inspect_language()*
Return: ~
(table)
register({lang}, {filetype}) *vim.treesitter.register()*
register({lang}, {filetype}) *vim.treesitter.language.register()*
Register a lang to be used for a filetype (or list of filetypes).
Parameters: ~
@ -746,7 +775,7 @@ register({lang}, {filetype}) *vim.treesitter.register()*
==============================================================================
Lua module: vim.treesitter.query *lua-treesitter-query*
*vim.treesitter.add_directive()*
*vim.treesitter.query.add_directive()*
add_directive({name}, {handler}, {force})
Adds a new directive to be used in queries
@ -768,7 +797,7 @@ add_directive({name}, {handler}, {force})
the predicate `{ "#set!", "conceal", "-" }`
• {force} (boolean|nil)
*vim.treesitter.add_predicate()*
*vim.treesitter.query.add_predicate()*
add_predicate({name}, {handler}, {force})
Adds a new predicate to be used in queries
@ -776,27 +805,11 @@ add_predicate({name}, {handler}, {force})
• {name} (string) Name of the predicate, without leading #
• {handler} function(match:table<string,|TSNode|>, pattern:string,
bufnr:integer, predicate:string[])
• see |vim.treesitter.add_directive()| for argument
• see |vim.treesitter.query.add_directive()| for argument
meanings
• {force} (boolean|nil)
*vim.treesitter.get_node_text()*
get_node_text({node}, {source}, {opts})
Gets the text corresponding to a given node
Parameters: ~
• {node} |TSNode|
• {source} (integer|string) Buffer or string from which the {node} is
extracted
• {opts} (table|nil) Optional parameters.
• metadata (table) Metadata of a specific capture. This
would be set to `metadata[capture_id]` when using
|vim.treesitter.add_directive()|.
Return: ~
(string)
get_query({lang}, {query_name}) *vim.treesitter.get_query()*
get({lang}, {query_name}) *vim.treesitter.query.get()*
Returns the runtime query {query_name} for {lang}.
Parameters: ~
@ -806,8 +819,8 @@ get_query({lang}, {query_name}) *vim.treesitter.get_query()*
Return: ~
Query|nil Parsed query
*vim.treesitter.get_query_files()*
get_query_files({lang}, {query_name}, {is_included})
*vim.treesitter.query.get_files()*
get_files({lang}, {query_name}, {is_included})
Gets the list of files used to make up a query
Parameters: ~
@ -820,32 +833,19 @@ get_query_files({lang}, {query_name}, {is_included})
string[] query_files List of files to load for given query and
language
get_range({node}, {source}, {metadata}) *vim.treesitter.get_range()*
Get the range of a |TSNode|. Can also supply {source} and {metadata} to
get the range with directives applied.
Parameters: ~
• {node} |TSNode|
• {source} integer|string|nil Buffer or string from which the {node}
is extracted
• {metadata} TSMetadata|nil
Return: ~
(table)
list_directives() *vim.treesitter.list_directives()*
list_directives() *vim.treesitter.query.list_directives()*
Lists the currently available directives to use in queries.
Return: ~
string[] List of supported directives.
list_predicates() *vim.treesitter.list_predicates()*
list_predicates() *vim.treesitter.query.list_predicates()*
Lists the currently available predicates to use in queries.
Return: ~
string[] List of supported predicates.
parse_query({lang}, {query}) *vim.treesitter.parse_query()*
parse({lang}, {query}) *vim.treesitter.query.parse()*
Parse {query} as a string. (If the query is in a file, the caller should
read the contents into a string before calling).
@ -935,7 +935,7 @@ Query:iter_matches({self}, {node}, {source}, {start}, {stop})
(fun(): integer, table<integer,TSNode>, table): pattern id, match,
metadata
set_query({lang}, {query_name}, {text}) *vim.treesitter.set_query()*
set({lang}, {query_name}, {text}) *vim.treesitter.query.set()*
Sets the runtime query named {query_name} for {lang}
This allows users to override any runtime files and/or configuration set

View File

@ -1,6 +1,4 @@
local a = vim.api
local query = require('vim.treesitter.query')
local language = require('vim.treesitter.language')
local LanguageTree = require('vim.treesitter.languagetree')
local Range = require('vim.treesitter._range')
@ -9,12 +7,9 @@ local parsers = setmetatable({}, { __mode = 'v' })
---@class TreesitterModule
---@field highlighter TSHighlighter
local M = vim.tbl_extend('error', query, language)
M.language_version = vim._ts_get_language_version()
M.minimum_language_version = vim._ts_get_minimum_language_version()
setmetatable(M, {
---@field query TSQueryModule
---@field language TSLanguageModule
local M = setmetatable({}, {
__index = function(t, k)
---@diagnostic disable:no-unknown
if k == 'highlighter' then
@ -27,9 +22,26 @@ setmetatable(M, {
t[k] = require('vim.treesitter.query')
return t[k]
end
local query = require('vim.treesitter.query')
if query[k] then
vim.deprecate('vim.treesitter.' .. k .. '()', 'vim.treesitter.query.' .. k .. '()', '0.10')
t[k] = query[k]
return t[k]
end
local language = require('vim.treesitter.language')
if language[k] then
vim.deprecate('vim.treesitter.' .. k .. '()', 'vim.treesitter.language.' .. k .. '()', '0.10')
t[k] = language[k]
return t[k]
end
end,
})
M.language_version = vim._ts_get_language_version()
M.minimum_language_version = vim._ts_get_minimum_language_version()
--- Creates a new parser
---
--- It is not recommended to use this; use |get_parser()| instead.
@ -47,7 +59,7 @@ function M._create_parser(bufnr, lang, opts)
vim.fn.bufload(bufnr)
local ft = vim.bo[bufnr].filetype
language.add(lang, { filetype = ft ~= '' and ft or nil })
M.language.add(lang, { filetype = ft ~= '' and ft or nil })
local self = LanguageTree.new(bufnr, lang, opts)
@ -101,7 +113,7 @@ function M.get_parser(bufnr, lang, opts)
if lang == nil then
local ft = vim.bo[bufnr].filetype
if ft ~= '' then
lang = language.get_lang(ft) or ft
lang = M.language.get_lang(ft) or ft
-- TODO(lewis6991): we should error here and not default to ft
-- if not lang then
-- error(string.format('filetype %s of buffer %d is not associated with any lang', ft, bufnr))
@ -152,7 +164,7 @@ function M.get_string_parser(str, lang, opts)
str = { str, 'string' },
lang = { lang, 'string' },
})
language.add(lang)
M.language.add(lang)
return LanguageTree.new(str, lang, opts)
end
@ -196,6 +208,61 @@ function M.get_node_range(node_or_range)
end
end
---Get the range of a |TSNode|. Can also supply {source} and {metadata}
---to get the range with directives applied.
---@param node TSNode
---@param source integer|string|nil Buffer or string from which the {node} is extracted
---@param metadata TSMetadata|nil
---@return Range6
function M.get_range(node, source, metadata)
if metadata and metadata.range then
assert(source)
return Range.add_bytes(source, metadata.range)
end
return { node:range(true) }
end
---@private
---@param buf integer
---@param range Range
---@returns string
local function buf_range_get_text(buf, range)
local start_row, start_col, end_row, end_col = Range.unpack4(range)
if end_col == 0 then
if start_row == end_row then
start_col = -1
start_row = start_row - 1
end
end_col = -1
end_row = end_row - 1
end
local lines = a.nvim_buf_get_text(buf, start_row, start_col, end_row, end_col, {})
return table.concat(lines, '\n')
end
--- Gets the text corresponding to a given node
---
---@param node TSNode
---@param source (integer|string) Buffer or string from which the {node} is extracted
---@param opts (table|nil) Optional parameters.
--- - metadata (table) Metadata of a specific capture. This would be
--- set to `metadata[capture_id]` when using |vim.treesitter.query.add_directive()|.
---@return string
function M.get_node_text(node, source, opts)
opts = opts or {}
local metadata = opts.metadata or {}
if metadata.text then
return metadata.text
elseif type(source) == 'number' then
local range = vim.treesitter.get_range(node, source, metadata)
return buf_range_get_text(source, range)
end
---@cast source string
return source:sub(select(3, node:start()) + 1, select(3, node:end_()))
end
--- Determines whether (line, col) position is in node range
---
---@param node TSNode defining the range

View File

@ -1,5 +1,5 @@
local a = vim.api
local query = require('vim.treesitter.query')
local query = vim.treesitter.query
---@alias TSHlIter fun(): integer, TSNode, TSMetadata
@ -45,9 +45,9 @@ function TSHighlighterQuery.new(lang, query_string)
})
if query_string then
self._query = query.parse_query(lang, query_string)
self._query = query.parse(lang, query_string)
else
self._query = query.get_query(lang, 'highlights')
self._query = query.get(lang, 'highlights')
end
return self

View File

@ -1,5 +1,6 @@
local a = vim.api
---@class TSLanguageModule
local M = {}
---@type table<string,string>
@ -111,9 +112,19 @@ end
---
---@param lang string Language
---@return table
function M.inspect_language(lang)
function M.inspect(lang)
M.add(lang)
return vim._ts_inspect_language(lang)
end
---@deprecated
function M.inspect_language(...)
vim.deprecate(
'vim.treesitter.language.inspect_language()',
'vim.treesitter.language.inspect()',
'0.10'
)
return M.inspect(...)
end
return M

View File

@ -99,8 +99,8 @@ function LanguageTree.new(source, lang, opts)
_regions = {},
_trees = {},
_opts = opts,
_injection_query = injections[lang] and query.parse_query(lang, injections[lang])
or query.get_query(lang, 'injections'),
_injection_query = injections[lang] and query.parse(lang, injections[lang])
or query.get(lang, 'injections'),
_valid = false,
_parser = vim._create_ts_parser(lang),
_callbacks = {
@ -482,7 +482,7 @@ end
---@param metadata TSMetadata
---@return Range6[]
local function get_node_ranges(node, source, metadata, include_children)
local range = query.get_range(node, source, metadata)
local range = vim.treesitter.get_range(node, source, metadata)
if include_children then
return { range }
@ -562,7 +562,7 @@ function LanguageTree:_get_injection(match, metadata)
-- Lang should override any other language tag
if name == 'injection.language' then
lang = query.get_node_text(node, self._source, { metadata = metadata[id] })
lang = vim.treesitter.get_node_text(node, self._source, { metadata = metadata[id] })
elseif name == 'injection.content' then
ranges = get_node_ranges(node, self._source, metadata[id], include_children)
end
@ -609,11 +609,11 @@ function LanguageTree:_get_injection_deprecated(match, metadata)
-- Lang should override any other language tag
if name == 'language' and not lang then
lang = query.get_node_text(node, self._source, { metadata = metadata[id] })
lang = vim.treesitter.get_node_text(node, self._source, { metadata = metadata[id] })
elseif name == 'combined' then
combined = true
elseif name == 'content' and #ranges == 0 then
ranges[#ranges + 1] = query.get_range(node, self._source, metadata[id])
ranges[#ranges + 1] = vim.treesitter.get_range(node, self._source, metadata[id])
-- Ignore any tags that start with "_"
-- Allows for other tags to be used in matches
elseif string.sub(name, 1, 1) ~= '_' then
@ -622,7 +622,7 @@ function LanguageTree:_get_injection_deprecated(match, metadata)
end
if #ranges == 0 then
ranges[#ranges + 1] = query.get_range(node, self._source, metadata[id])
ranges[#ranges + 1] = vim.treesitter.get_range(node, self._source, metadata[id])
end
end
end

View File

@ -1,8 +1,6 @@
local a = vim.api
local language = require('vim.treesitter.language')
local Range = require('vim.treesitter._range')
---@class Query
---@field captures string[] List of captures used in query
---@field info TSQueryInfo Contains used queries, predicates, directives
@ -14,6 +12,7 @@ Query.__index = Query
---@field captures table
---@field patterns table<string,any[][]>
---@class TSQueryModule
local M = {}
---@private
@ -57,22 +56,14 @@ local function add_included_lang(base_langs, lang, ilang)
return false
end
---@private
---@param buf integer
---@param range Range
---@returns string
local function buf_range_get_text(buf, range)
local start_row, start_col, end_row, end_col = Range.unpack4(range)
if end_col == 0 then
if start_row == end_row then
start_col = -1
start_row = start_row - 1
end
end_col = -1
end_row = end_row - 1
end
local lines = a.nvim_buf_get_text(buf, start_row, start_col, end_row, end_col, {})
return table.concat(lines, '\n')
---@deprecated
function M.get_query_files(...)
vim.deprecate(
'vim.treesitter.query.get_query_files()',
'vim.treesitter.query.get_files()',
'0.10'
)
return M.get_files(...)
end
--- Gets the list of files used to make up a query
@ -81,7 +72,7 @@ end
---@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)
function M.get_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))
@ -153,7 +144,7 @@ function M.get_query_files(lang, query_name, is_included)
local query_files = {}
for _, base_lang in ipairs(base_langs) do
local base_files = M.get_query_files(base_lang, query_name, true)
local base_files = M.get_files(base_lang, query_name, true)
vim.list_extend(query_files, base_files)
end
vim.list_extend(query_files, { base_query })
@ -175,7 +166,7 @@ local function read_query_files(filenames)
return table.concat(contents, '')
end
-- The explicitly set queries from |vim.treesitter.query.set_query()|
-- The explicitly set queries from |vim.treesitter.query.set()|
---@type table<string,table<string,Query>>
local explicit_queries = setmetatable({}, {
__index = function(t, k)
@ -186,6 +177,12 @@ local explicit_queries = setmetatable({}, {
end,
})
---@deprecated
function M.set_query(...)
vim.deprecate('vim.treesitter.query.set_query()', 'vim.treesitter.query.set()', '0.10')
M.set(...)
end
--- Sets the runtime query named {query_name} for {lang}
---
--- This allows users to override any runtime files and/or configuration
@ -194,8 +191,17 @@ local explicit_queries = setmetatable({}, {
---@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)
function M.set(lang, query_name, text)
explicit_queries[lang][query_name] = M.parse(lang, text)
end
---@deprecated
---@param lang string Language to use for the query
---@param query_name string Name of the query (e.g. "highlights")
---
---@return Query|nil Parsed query
function M.get_query(lang, query_name)
return M.get(lang, query_name)
end
--- Returns the runtime query {query_name} for {lang}.
@ -204,16 +210,16 @@ end
---@param query_name string Name of the query (e.g. "highlights")
---
---@return Query|nil Parsed query
function M.get_query(lang, query_name)
function M.get(lang, query_name)
if explicit_queries[lang][query_name] then
return explicit_queries[lang][query_name]
end
local query_files = M.get_query_files(lang, query_name)
local query_files = M.get_files(lang, query_name)
local query_string = read_query_files(query_files)
if #query_string > 0 then
return M.parse_query(lang, query_string)
return M.parse(lang, query_string)
end
end
@ -222,6 +228,12 @@ local query_cache = vim.defaulttable(function()
return setmetatable({}, { __mode = 'v' })
end)
---@deprecated
function M.parse_query(...)
vim.deprecate('vim.treesitter.query.parse_query()', 'vim.treesitter.query.parse()', '0.10')
return M.parse(...)
end
--- Parse {query} as a string. (If the query is in a file, the caller
--- should read the contents into a string before calling).
---
@ -239,7 +251,7 @@ end)
---@param query string Query in s-expr syntax
---
---@return Query Parsed query
function M.parse_query(lang, query)
function M.parse(lang, query)
language.add(lang)
local cached = query_cache[lang][query]
if cached then
@ -254,41 +266,16 @@ function M.parse_query(lang, query)
return self
end
---Get the range of a |TSNode|. Can also supply {source} and {metadata}
---to get the range with directives applied.
---@param node TSNode
---@param source integer|string|nil Buffer or string from which the {node} is extracted
---@param metadata TSMetadata|nil
---@return Range6
function M.get_range(node, source, metadata)
if metadata and metadata.range then
assert(source)
return Range.add_bytes(source, metadata.range)
end
return { node:range(true) }
---@deprecated
function M.get_range(...)
vim.deprecate('vim.treesitter.query.get_range()', 'vim.treesitter.get_range()', '0.10')
return vim.treesitter.get_range(...)
end
--- Gets the text corresponding to a given node
---
---@param node TSNode
---@param source (integer|string) Buffer or string from which the {node} is extracted
---@param opts (table|nil) Optional parameters.
--- - metadata (table) Metadata of a specific capture. This would be
--- set to `metadata[capture_id]` when using |vim.treesitter.add_directive()|.
---@return string
function M.get_node_text(node, source, opts)
opts = opts or {}
local metadata = opts.metadata or {}
if metadata.text then
return metadata.text
elseif type(source) == 'number' then
local range = M.get_range(node, source, metadata)
return buf_range_get_text(source, range)
end
---@cast source string
return source:sub(select(3, node:start()) + 1, select(3, node:end_()))
---@deprecated
function M.get_node_text(...)
vim.deprecate('vim.treesitter.query.get_node_text()', 'vim.treesitter.get_node_text()', '0.10')
return vim.treesitter.get_node_text(...)
end
---@alias TSMatch table<integer,TSNode>
@ -304,7 +291,7 @@ local predicate_handlers = {
if not node then
return true
end
local node_text = M.get_node_text(node, source)
local node_text = vim.treesitter.get_node_text(node, source)
local str ---@type string
if type(predicate[3]) == 'string' then
@ -312,7 +299,7 @@ local predicate_handlers = {
str = predicate[3]
else
-- (#eq? @aa @bb)
str = M.get_node_text(match[predicate[3]], source)
str = vim.treesitter.get_node_text(match[predicate[3]], source)
end
if node_text ~= str or str == nil then
@ -328,7 +315,7 @@ local predicate_handlers = {
return true
end
local regex = predicate[3]
return string.find(M.get_node_text(node, source), regex) ~= nil
return string.find(vim.treesitter.get_node_text(node, source), regex) ~= nil
end,
['match?'] = (function()
@ -357,7 +344,7 @@ local predicate_handlers = {
end
---@diagnostic disable-next-line no-unknown
local regex = compiled_vim_regexes[pred[3]]
return regex:match_str(M.get_node_text(node, source))
return regex:match_str(vim.treesitter.get_node_text(node, source))
end
end)(),
@ -366,7 +353,7 @@ local predicate_handlers = {
if not node then
return true
end
local node_text = M.get_node_text(node, source)
local node_text = vim.treesitter.get_node_text(node, source)
for i = 3, #predicate do
if string.find(node_text, predicate[i], 1, true) then
@ -382,7 +369,7 @@ local predicate_handlers = {
if not node then
return true
end
local node_text = M.get_node_text(node, source)
local node_text = vim.treesitter.get_node_text(node, source)
-- Since 'predicate' will not be used by callers of this function, use it
-- to store a string set built from the list of words to check against.
@ -468,7 +455,7 @@ local directive_handlers = {
assert(type(id) == 'number')
local node = match[id]
local text = M.get_node_text(node, bufnr, { metadata = metadata[id] }) or ''
local text = vim.treesitter.get_node_text(node, bufnr, { metadata = metadata[id] }) or ''
if not metadata[id] then
metadata[id] = {}
@ -486,7 +473,7 @@ local directive_handlers = {
---
---@param name string Name of the predicate, without leading #
---@param handler function(match:table<string,TSNode>, pattern:string, bufnr:integer, predicate:string[])
--- - see |vim.treesitter.add_directive()| for argument meanings
--- - see |vim.treesitter.query.add_directive()| for argument meanings
---@param force boolean|nil
function M.add_predicate(name, handler, force)
if predicate_handlers[name] and not force then

View File

@ -290,7 +290,7 @@ CONFIG = {
if fstem == 'treesitter'
else f'*{name}()*'
if name[0].isupper()
else f'*vim.treesitter.{name}()*'),
else f'*vim.treesitter.{fstem}.{name}()*'),
'module_override': {},
'append_only': [],
}

View File

@ -376,7 +376,7 @@ describe('treesitter highlighting', function()
exec_lua [[
parser = vim.treesitter.get_parser(0, "c")
query = vim.treesitter.parse_query("c", "(declaration) @decl")
query = vim.treesitter.query.parse("c", "(declaration) @decl")
local nodes = {}
for _, node in query:iter_captures(parser:parse()[1]:root(), 0, 0, 19) do
@ -481,8 +481,8 @@ describe('treesitter highlighting', function()
exec_lua [[
local injection_query = "(preproc_def (preproc_arg) @c) (preproc_function_def value: (preproc_arg) @c)"
require('vim.treesitter.query').set_query("c", "highlights", hl_query)
require('vim.treesitter.query').set_query("c", "injections", injection_query)
vim.treesitter.query.set("c", "highlights", hl_query)
vim.treesitter.query.set("c", "injections", injection_query)
vim.treesitter.highlighter.new(vim.treesitter.get_parser(0, "c"))
]]

View File

@ -18,27 +18,27 @@ describe('treesitter language API', function()
-- actual message depends on platform
matches("Failed to load parser for language 'borklang': uv_dlopen: .+",
pcall_err(exec_lua, "parser = vim.treesitter.add('borklang', { path = 'borkbork.so' })"))
pcall_err(exec_lua, "parser = vim.treesitter.language.add('borklang', { path = 'borkbork.so' })"))
eq(false, exec_lua("return pcall(vim.treesitter.add, 'borklang')"))
eq(false, exec_lua("return pcall(vim.treesitter.language.add, 'borklang')"))
eq(false, exec_lua("return pcall(vim.treesitter.add, 'borklang', { path = 'borkbork.so' })"))
eq(false, exec_lua("return pcall(vim.treesitter.language.add, 'borklang', { path = 'borkbork.so' })"))
eq(".../language.lua:0: no parser for 'borklang' language, see :help treesitter-parsers",
pcall_err(exec_lua, "parser = vim.treesitter.inspect_language('borklang')"))
pcall_err(exec_lua, "parser = vim.treesitter.language.inspect('borklang')"))
matches("Failed to load parser: uv_dlsym: .+",
pcall_err(exec_lua, 'vim.treesitter.add("c", { symbol_name = "borklang" })'))
pcall_err(exec_lua, 'vim.treesitter.language.add("c", { symbol_name = "borklang" })'))
end)
it('shows error for invalid language name', function()
eq(".../language.lua:0: '/foo/' is not a valid language name",
pcall_err(exec_lua, 'vim.treesitter.add("/foo/")'))
pcall_err(exec_lua, 'vim.treesitter.language.add("/foo/")'))
end)
it('inspects language', function()
local keys, fields, symbols = unpack(exec_lua([[
local lang = vim.treesitter.inspect_language('c')
local lang = vim.treesitter.language.inspect('c')
local keys, symbols = {}, {}
for k,_ in pairs(lang) do
keys[k] = true

View File

@ -26,7 +26,7 @@ describe('treesitter node API', function()
parser = vim.treesitter.get_parser(0, "c")
tree = parser:parse()[1]
root = tree:root()
lang = vim.treesitter.inspect_language('c')
lang = vim.treesitter.language.inspect('c')
function node_text(node)
return query.get_node_text(node, 0)

View File

@ -23,7 +23,7 @@ describe('treesitter parser API', function()
parser = vim.treesitter.get_parser(0, "c")
tree = parser:parse()[1]
root = tree:root()
lang = vim.treesitter.inspect_language('c')
lang = vim.treesitter.language.inspect('c')
]])
eq("<tree>", exec_lua("return tostring(tree)"))
@ -171,7 +171,7 @@ void ui_refresh(void)
it("supports runtime queries", function()
local ret = exec_lua [[
return require"vim.treesitter.query".get_query("c", "highlights").captures[1]
return vim.treesitter.query.get("c", "highlights").captures[1]
]]
eq('variable', ret)
@ -184,7 +184,7 @@ void ui_refresh(void)
local query, n = ...
local before = vim.loop.hrtime()
for i=1,n,1 do
cquery = vim.treesitter.parse_query("c", ...)
cquery = vim.treesitter.query.parse("c", ...)
end
local after = vim.loop.hrtime()
return after - before
@ -203,7 +203,7 @@ void ui_refresh(void)
insert(test_text)
local res = exec_lua([[
cquery = vim.treesitter.parse_query("c", ...)
cquery = vim.treesitter.query.parse("c", ...)
parser = vim.treesitter.get_parser(0, "c")
tree = parser:parse()[1]
res = {}
@ -232,7 +232,7 @@ void ui_refresh(void)
insert(test_text)
local res = exec_lua([[
cquery = vim.treesitter.parse_query("c", ...)
cquery = vim.treesitter.query.parse("c", ...)
parser = vim.treesitter.get_parser(0, "c")
tree = parser:parse()[1]
res = {}
@ -326,7 +326,7 @@ end]]
insert('char* astring = "\\n"; (1 + 1) * 2 != 2;')
local res = exec_lua([[
cquery = vim.treesitter.parse_query("c", '([_] @plus (#vim-match? @plus "^\\\\+$"))'..
cquery = vim.treesitter.query.parse("c", '([_] @plus (#vim-match? @plus "^\\\\+$"))'..
'([_] @times (#vim-match? @times "^\\\\*$"))'..
'([_] @paren (#vim-match? @paren "^\\\\($"))'..
'([_] @escape (#vim-match? @escape "^\\\\\\\\n$"))'..
@ -376,7 +376,7 @@ end]]
]])
exec_lua([[
function get_query_result(query_text)
cquery = vim.treesitter.parse_query("c", query_text)
cquery = vim.treesitter.query.parse("c", query_text)
parser = vim.treesitter.get_parser(0, "c")
tree = parser:parse()[1]
res = {}
@ -416,7 +416,7 @@ end]]
insert('char* astring = "Hello World!";')
local res = exec_lua([[
cquery = vim.treesitter.parse_query("c", '([_] @quote (#vim-match? @quote "^\\"$")) ([_] @quote (#lua-match? @quote "^\\"$"))')
cquery = vim.treesitter.query.parse("c", '([_] @quote (#vim-match? @quote "^\\"$")) ([_] @quote (#lua-match? @quote "^\\"$"))')
parser = vim.treesitter.get_parser(0, "c")
tree = parser:parse()[1]
res = {}
@ -449,7 +449,7 @@ end]]
local custom_query = "((identifier) @main (#is-main? @main))"
local res = exec_lua([[
local query = require"vim.treesitter.query"
local query = vim.treesitter.query
local function is_main(match, pattern, bufnr, predicate)
local node = match[ predicate[2] ]
@ -461,7 +461,7 @@ end]]
query.add_predicate("is-main?", is_main)
local query = query.parse_query("c", ...)
local query = query.parse("c", ...)
local nodes = {}
for _, node in query:iter_captures(parser:parse()[1]:root(), 0) do
@ -474,7 +474,7 @@ end]]
eq({{0, 4, 0, 8}}, res)
local res_list = exec_lua[[
local query = require'vim.treesitter.query'
local query = vim.treesitter.query
local list = query.list_predicates()
@ -533,7 +533,7 @@ end]]
local res = exec_lua [[
parser = vim.treesitter.get_parser(0, "c")
query = vim.treesitter.parse_query("c", "(declaration) @decl")
query = vim.treesitter.query.parse("c", "(declaration) @decl")
local nodes = {}
for _, node in query:iter_captures(parser:parse()[1]:root(), 0) do
@ -581,7 +581,7 @@ end]]
local parser = vim.treesitter.get_string_parser(str, "c")
local nodes = {}
local query = vim.treesitter.parse_query("c", '((identifier) @id (eq? @id "foo"))')
local query = vim.treesitter.query.parse("c", '((identifier) @id (eq? @id "foo"))')
for _, node in query:iter_captures(parser:parse()[1]:root(), str) do
table.insert(nodes, { node:range() })
@ -603,7 +603,7 @@ end]]
local parser = vim.treesitter.get_string_parser(str, "c")
local nodes = {}
local query = vim.treesitter.parse_query("c", '((identifier) @foo)')
local query = vim.treesitter.query.parse("c", '((identifier) @foo)')
local first_child = parser:parse()[1]:root():child(1)
for _, node in query:iter_captures(first_child, str) do
@ -703,7 +703,7 @@ int x = INT_MAX;
describe("when providing parsing information through a directive", function()
it("should inject a language", function()
exec_lua([=[
vim.treesitter.add_directive("inject-clang!", function(match, _, _, pred, metadata)
vim.treesitter.query.add_directive("inject-clang!", function(match, _, _, pred, metadata)
metadata.language = "c"
metadata.combined = true
metadata.content = pred[2]
@ -741,7 +741,7 @@ int x = INT_MAX;
it("should not inject bad languages", function()
exec_lua([=[
vim.treesitter.add_directive("inject-bad!", function(match, _, _, pred, metadata)
vim.treesitter.query.add_directive("inject-bad!", function(match, _, _, pred, metadata)
metadata.language = "{"
metadata.combined = true
metadata.content = pred[2]
@ -774,7 +774,7 @@ int x = INT_MAX;
end)
it("should list all directives", function()
local res_list = exec_lua[[
local query = require'vim.treesitter.query'
local query = vim.treesitter.query
local list = query.list_directives()
@ -820,7 +820,7 @@ int x = INT_MAX;
local result = exec_lua([[
local result
query = vim.treesitter.parse_query("c", '((number_literal) @number (#set! "key" "value"))')
query = vim.treesitter.query.parse("c", '((number_literal) @number (#set! "key" "value"))')
parser = vim.treesitter.get_parser(0, "c")
for pattern, match, metadata in query:iter_matches(parser:parse()[1]:root(), 0) do
@ -840,10 +840,10 @@ int x = INT_MAX;
]])
local result = exec_lua([[
local query = require("vim.treesitter.query")
local query = vim.treesitter.query
local value
query = vim.treesitter.parse_query("c", '((number_literal) @number (#set! @number "key" "value"))')
query = vim.treesitter.query.parse("c", '((number_literal) @number (#set! @number "key" "value"))')
parser = vim.treesitter.get_parser(0, "c")
for pattern, match, metadata in query:iter_matches(parser:parse()[1]:root(), 0) do
@ -862,10 +862,10 @@ int x = INT_MAX;
]])
local result = exec_lua([[
local query = require("vim.treesitter.query")
local query = vim.treesitter.query
local result
query = vim.treesitter.parse_query("c", '((number_literal) @number (#set! @number "key" "value") (#set! @number "key2" "value2"))')
query = vim.treesitter.query.parse("c", '((number_literal) @number (#set! @number "key" "value") (#set! @number "key2" "value2"))')
parser = vim.treesitter.get_parser(0, "c")
for pattern, match, metadata in query:iter_matches(parser:parse()[1]:root(), 0) do