mirror of
https://github.com/neovim/neovim.git
synced 2024-12-25 13:45:15 -07:00
b9b408a56c
**Problem:** `vim.treesitter.get_parser` will throw an error if no parser can be found. - This means the caller is responsible for wrapping it in a `pcall`, which is easy to forget - It also makes it slightly harder to potentially memoize `get_parser` in the future - It's a bit unintuitive since many other `get_*` style functions conventionally return `nil` if no object is found (e.g. `get_node`, `get_lang`, `query.get`, etc.) **Solution:** Return `nil` if no parser can be found or created - This requires a function signature change, and some new assertions in places where the parser will always (or should always) be found. - This commit starts by making this change internally, since it is breaking. Eventually it will be rolled out to the public API.
499 lines
15 KiB
Lua
499 lines
15 KiB
Lua
local api = vim.api
|
|
|
|
---@type table<integer,vim.treesitter.LanguageTree>
|
|
local parsers = setmetatable({}, { __mode = 'v' })
|
|
|
|
local M = vim._defer_require('vim.treesitter', {
|
|
_fold = ..., --- @module 'vim.treesitter._fold'
|
|
_query_linter = ..., --- @module 'vim.treesitter._query_linter'
|
|
_range = ..., --- @module 'vim.treesitter._range'
|
|
dev = ..., --- @module 'vim.treesitter.dev'
|
|
highlighter = ..., --- @module 'vim.treesitter.highlighter'
|
|
language = ..., --- @module 'vim.treesitter.language'
|
|
languagetree = ..., --- @module 'vim.treesitter.languagetree'
|
|
query = ..., --- @module 'vim.treesitter.query'
|
|
})
|
|
|
|
local LanguageTree = M.languagetree
|
|
|
|
--- @nodoc
|
|
M.language_version = vim._ts_get_language_version()
|
|
|
|
--- @nodoc
|
|
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.
|
|
---
|
|
---@param bufnr integer 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
|
|
---
|
|
---@return vim.treesitter.LanguageTree object to use for parsing
|
|
function M._create_parser(bufnr, lang, opts)
|
|
if bufnr == 0 then
|
|
bufnr = vim.api.nvim_get_current_buf()
|
|
end
|
|
|
|
vim.fn.bufload(bufnr)
|
|
|
|
local self = LanguageTree.new(bufnr, lang, opts)
|
|
|
|
local function bytes_cb(_, ...)
|
|
self:_on_bytes(...)
|
|
end
|
|
|
|
local function detach_cb(_, ...)
|
|
if parsers[bufnr] == self then
|
|
parsers[bufnr] = nil
|
|
end
|
|
self:_on_detach(...)
|
|
end
|
|
|
|
local function reload_cb(_)
|
|
self:_on_reload()
|
|
end
|
|
|
|
local source = self:source() --[[@as integer]]
|
|
|
|
api.nvim_buf_attach(
|
|
source,
|
|
false,
|
|
{ on_bytes = bytes_cb, on_detach = detach_cb, on_reload = reload_cb, preview = true }
|
|
)
|
|
|
|
self:parse()
|
|
|
|
return self
|
|
end
|
|
|
|
local function valid_lang(lang)
|
|
return lang and lang ~= ''
|
|
end
|
|
|
|
--- Returns the parser for a specific buffer and attaches it to the buffer
|
|
---
|
|
--- If needed, this will create the parser. If no parser can be found or created, returns `nil`.
|
|
---
|
|
---@param bufnr (integer|nil) Buffer the parser should be tied to (default: current buffer)
|
|
---@param lang (string|nil) Language of this parser (default: from buffer filetype)
|
|
---@param opts (table|nil) Options to pass to the created language tree
|
|
---
|
|
---@return vim.treesitter.LanguageTree? object to use for parsing, or `nil` if not found
|
|
function M._get_parser(bufnr, lang, opts)
|
|
opts = opts or {}
|
|
|
|
if bufnr == nil or bufnr == 0 then
|
|
bufnr = api.nvim_get_current_buf()
|
|
end
|
|
|
|
if not valid_lang(lang) then
|
|
lang = M.language.get_lang(vim.bo[bufnr].filetype) or vim.bo[bufnr].filetype
|
|
end
|
|
|
|
if not valid_lang(lang) then
|
|
if not parsers[bufnr] then
|
|
return nil
|
|
end
|
|
elseif parsers[bufnr] == nil or parsers[bufnr]:lang() ~= lang then
|
|
local parser = vim.F.npcall(M._create_parser, bufnr, lang, opts)
|
|
if not parser then
|
|
return nil
|
|
end
|
|
parsers[bufnr] = parser
|
|
end
|
|
|
|
parsers[bufnr]:register_cbs(opts.buf_attach_cbs)
|
|
|
|
return parsers[bufnr]
|
|
end
|
|
|
|
--- Returns the parser for a specific buffer and attaches it to the buffer
|
|
---
|
|
--- If needed, this will create the parser.
|
|
---
|
|
---@param bufnr (integer|nil) Buffer the parser should be tied to (default: current buffer)
|
|
---@param lang (string|nil) Language of this parser (default: from buffer filetype)
|
|
---@param opts (table|nil) Options to pass to the created language tree
|
|
---
|
|
---@return vim.treesitter.LanguageTree object to use for parsing
|
|
function M.get_parser(bufnr, lang, opts)
|
|
-- TODO(ribru17): Remove _get_parser and move that logic back here once the breaking function
|
|
-- signature change is acceptable.
|
|
local parser = M._get_parser(bufnr, lang, opts)
|
|
if not parser then
|
|
vim.notify_once(
|
|
'WARNING: vim.treesitter.get_parser will return nil instead of raising an error in Neovim 0.12',
|
|
vim.log.levels.WARN
|
|
)
|
|
error('Parser not found.')
|
|
end
|
|
return parser
|
|
end
|
|
|
|
--- Returns a string parser
|
|
---
|
|
---@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 vim.treesitter.LanguageTree object to use for parsing
|
|
function M.get_string_parser(str, lang, opts)
|
|
vim.validate({
|
|
str = { str, 'string' },
|
|
lang = { lang, 'string' },
|
|
})
|
|
|
|
return LanguageTree.new(str, lang, opts)
|
|
end
|
|
|
|
--- Determines whether a node is the ancestor of another
|
|
---
|
|
---@param dest TSNode Possible ancestor
|
|
---@param source TSNode Possible descendant
|
|
---
|
|
---@return boolean True if {dest} is an ancestor of {source}
|
|
function M.is_ancestor(dest, source)
|
|
if not (dest and source) then
|
|
return false
|
|
end
|
|
|
|
local current = source ---@type TSNode?
|
|
while current ~= nil do
|
|
if current == dest then
|
|
return true
|
|
end
|
|
|
|
current = current:parent()
|
|
end
|
|
|
|
return false
|
|
end
|
|
|
|
--- Returns the node's range or an unpacked range table
|
|
---
|
|
---@param node_or_range (TSNode | table) Node or table of positions
|
|
---
|
|
---@return integer start_row
|
|
---@return integer start_col
|
|
---@return integer end_row
|
|
---@return integer end_col
|
|
function M.get_node_range(node_or_range)
|
|
if type(node_or_range) == 'table' then
|
|
return unpack(node_or_range)
|
|
else
|
|
return node_or_range: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 vim.treesitter.query.TSMetadata|nil
|
|
---@return Range6
|
|
function M.get_range(node, source, metadata)
|
|
if metadata and metadata.range then
|
|
assert(source)
|
|
return M._range.add_bytes(source, metadata.range)
|
|
end
|
|
return { node:range(true) }
|
|
end
|
|
|
|
---@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 = M._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 = api.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 = 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_()))
|
|
end
|
|
|
|
--- Determines whether (line, col) position is in node range
|
|
---
|
|
---@param node TSNode defining the range
|
|
---@param line integer Line (0-based)
|
|
---@param col integer Column (0-based)
|
|
---
|
|
---@return boolean True if the position is in node range
|
|
function M.is_in_node_range(node, line, col)
|
|
return M.node_contains(node, { line, col, line, col + 1 })
|
|
end
|
|
|
|
--- Determines if a node contains a range
|
|
---
|
|
---@param node TSNode
|
|
---@param range table
|
|
---
|
|
---@return boolean True if the {node} contains the {range}
|
|
function M.node_contains(node, range)
|
|
vim.validate({
|
|
-- allow a table so nodes can be mocked
|
|
node = { node, { 'userdata', 'table' } },
|
|
range = { range, M._range.validate, 'integer list with 4 or 6 elements' },
|
|
})
|
|
return M._range.contains({ node:range() }, range)
|
|
end
|
|
|
|
--- Returns a list of highlight captures at the given position
|
|
---
|
|
--- Each capture is represented by a table containing the capture name as a string as
|
|
--- well as a table of metadata (`priority`, `conceal`, ...; empty if none are defined).
|
|
---
|
|
---@param bufnr integer Buffer number (0 for current buffer)
|
|
---@param row integer Position row
|
|
---@param col integer Position column
|
|
---
|
|
---@return {capture: string, lang: string, metadata: table}[]
|
|
function M.get_captures_at_pos(bufnr, row, col)
|
|
if bufnr == 0 then
|
|
bufnr = api.nvim_get_current_buf()
|
|
end
|
|
local buf_highlighter = M.highlighter.active[bufnr]
|
|
|
|
if not buf_highlighter then
|
|
return {}
|
|
end
|
|
|
|
local matches = {}
|
|
|
|
buf_highlighter.tree:for_each_tree(function(tstree, tree)
|
|
if not tstree then
|
|
return
|
|
end
|
|
|
|
local root = tstree:root()
|
|
local root_start_row, _, root_end_row, _ = root:range()
|
|
|
|
-- Only worry about trees within the line range
|
|
if root_start_row > row or root_end_row < row then
|
|
return
|
|
end
|
|
|
|
local q = buf_highlighter:get_query(tree:lang())
|
|
|
|
-- Some injected languages may not have highlight queries.
|
|
if not q:query() then
|
|
return
|
|
end
|
|
|
|
local iter = q:query():iter_captures(root, buf_highlighter.bufnr, row, row + 1)
|
|
|
|
for capture, node, metadata in iter do
|
|
if M.is_in_node_range(node, row, col) then
|
|
---@diagnostic disable-next-line: invisible
|
|
local c = q._query.captures[capture] -- name of the capture in the query
|
|
if c ~= nil then
|
|
table.insert(matches, { capture = c, metadata = metadata, lang = tree:lang() })
|
|
end
|
|
end
|
|
end
|
|
end)
|
|
return matches
|
|
end
|
|
|
|
--- Returns a list of highlight capture names under the cursor
|
|
---
|
|
---@param winnr (integer|nil) Window handle or 0 for current window (default)
|
|
---
|
|
---@return string[] List of capture names
|
|
function M.get_captures_at_cursor(winnr)
|
|
winnr = winnr or 0
|
|
local bufnr = api.nvim_win_get_buf(winnr)
|
|
local cursor = api.nvim_win_get_cursor(winnr)
|
|
|
|
local data = M.get_captures_at_pos(bufnr, cursor[1] - 1, cursor[2])
|
|
|
|
local captures = {}
|
|
|
|
for _, capture in ipairs(data) do
|
|
table.insert(captures, capture.capture)
|
|
end
|
|
|
|
return captures
|
|
end
|
|
|
|
--- Optional keyword arguments:
|
|
--- @class vim.treesitter.get_node.Opts : vim.treesitter.LanguageTree.tree_for_range.Opts
|
|
--- @inlinedoc
|
|
---
|
|
--- Buffer number (nil or 0 for current buffer)
|
|
--- @field bufnr integer?
|
|
---
|
|
--- 0-indexed (row, col) tuple. Defaults to cursor position in the
|
|
--- current window. Required if {bufnr} is not the current buffer
|
|
--- @field pos [integer, integer]?
|
|
---
|
|
--- Parser language. (default: from buffer filetype)
|
|
--- @field lang string?
|
|
---
|
|
--- Ignore injected languages (default true)
|
|
--- @field ignore_injections boolean?
|
|
---
|
|
--- Include anonymous nodes (default false)
|
|
--- @field include_anonymous boolean?
|
|
|
|
--- Returns the smallest named node at the given position
|
|
---
|
|
--- NOTE: Calling this on an unparsed tree can yield an invalid node.
|
|
--- If the tree is not known to be parsed by, e.g., an active highlighter,
|
|
--- parse the tree first via
|
|
---
|
|
--- ```lua
|
|
--- vim.treesitter.get_parser(bufnr):parse(range)
|
|
--- ```
|
|
---
|
|
---@param opts vim.treesitter.get_node.Opts?
|
|
---
|
|
---@return TSNode | nil Node at the given position
|
|
function M.get_node(opts)
|
|
opts = opts or {}
|
|
|
|
local bufnr = opts.bufnr
|
|
|
|
if not bufnr or bufnr == 0 then
|
|
bufnr = api.nvim_get_current_buf()
|
|
end
|
|
|
|
local row, col --- @type integer, integer
|
|
if opts.pos then
|
|
assert(#opts.pos == 2, 'Position must be a (row, col) tuple')
|
|
row, col = opts.pos[1], opts.pos[2]
|
|
else
|
|
assert(
|
|
bufnr == api.nvim_get_current_buf(),
|
|
'Position must be explicitly provided when not using the current buffer'
|
|
)
|
|
local pos = api.nvim_win_get_cursor(0)
|
|
-- Subtract one to account for 1-based row indexing in nvim_win_get_cursor
|
|
row, col = pos[1] - 1, pos[2]
|
|
end
|
|
|
|
assert(row >= 0 and col >= 0, 'Invalid position: row and col must be non-negative')
|
|
|
|
local ts_range = { row, col, row, col }
|
|
|
|
local root_lang_tree = M._get_parser(bufnr, opts.lang)
|
|
if not root_lang_tree then
|
|
return
|
|
end
|
|
|
|
if opts.include_anonymous then
|
|
return root_lang_tree:node_for_range(ts_range, opts)
|
|
end
|
|
return root_lang_tree:named_node_for_range(ts_range, opts)
|
|
end
|
|
|
|
--- Starts treesitter highlighting for a buffer
|
|
---
|
|
--- 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:
|
|
---
|
|
--- ```lua
|
|
--- vim.api.nvim_create_autocmd( 'FileType', { pattern = 'tex',
|
|
--- callback = function(args)
|
|
--- vim.treesitter.start(args.buf, 'latex')
|
|
--- vim.bo[args.buf].syntax = 'on' -- only if additional legacy syntax is needed
|
|
--- end
|
|
--- })
|
|
--- ```
|
|
---
|
|
---@param bufnr (integer|nil) Buffer to be highlighted (default: current buffer)
|
|
---@param lang (string|nil) Language of the parser (default: from buffer filetype)
|
|
function M.start(bufnr, lang)
|
|
bufnr = bufnr or api.nvim_get_current_buf()
|
|
local parser = M._get_parser(bufnr, lang)
|
|
if not parser then
|
|
vim.notify('No parser for the given buffer.', vim.log.levels.WARN)
|
|
return
|
|
end
|
|
M.highlighter.new(parser)
|
|
end
|
|
|
|
--- Stops treesitter highlighting for a buffer
|
|
---
|
|
---@param bufnr (integer|nil) Buffer to stop highlighting (default: current buffer)
|
|
function M.stop(bufnr)
|
|
bufnr = (bufnr and bufnr ~= 0) and bufnr or api.nvim_get_current_buf()
|
|
|
|
if M.highlighter.active[bufnr] then
|
|
M.highlighter.active[bufnr]:destroy()
|
|
end
|
|
end
|
|
|
|
--- Open a window that displays a textual representation of the nodes in the language tree.
|
|
---
|
|
--- While in the window, press "a" to toggle display of anonymous nodes, "I" to toggle the
|
|
--- display of the source language of each node, "o" to toggle the query editor, and press
|
|
--- [<Enter>] to jump to the node under the cursor in the source buffer. Folding also works
|
|
--- (try |zo|, |zc|, etc.).
|
|
---
|
|
--- Can also be shown with `:InspectTree`. [:InspectTree]()
|
|
---
|
|
---@param opts table|nil Optional options table with the following possible keys:
|
|
--- - lang (string|nil): The language of the source buffer. If omitted, detect
|
|
--- from the filetype of the source buffer.
|
|
--- - bufnr (integer|nil): Buffer to draw the tree into. If omitted, a new
|
|
--- buffer is created.
|
|
--- - winid (integer|nil): Window id to display the tree buffer in. If omitted,
|
|
--- a new window is created with {command}.
|
|
--- - command (string|nil): Vimscript command to create the window. Default
|
|
--- value is "60vnew". Only used when {winid} is nil.
|
|
--- - title (string|fun(bufnr:integer):string|nil): Title of the window. If a
|
|
--- function, it accepts the buffer number of the source buffer as its only
|
|
--- argument and should return a string.
|
|
function M.inspect_tree(opts)
|
|
---@diagnostic disable-next-line: invisible
|
|
M.dev.inspect_tree(opts)
|
|
end
|
|
|
|
--- Returns the fold level for {lnum} in the current buffer. Can be set directly to 'foldexpr':
|
|
---
|
|
--- ```lua
|
|
--- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
|
|
--- ```
|
|
---
|
|
---@param lnum integer|nil Line number to calculate fold level for
|
|
---@return string
|
|
function M.foldexpr(lnum)
|
|
return M._fold.foldexpr(lnum)
|
|
end
|
|
|
|
return M
|