diff options
Diffstat (limited to 'runtime/lua/vim')
65 files changed, 4289 insertions, 2105 deletions
diff --git a/runtime/lua/vim/_defaults.lua b/runtime/lua/vim/_defaults.lua index 06f6ed6829..69204e3fe6 100644 --- a/runtime/lua/vim/_defaults.lua +++ b/runtime/lua/vim/_defaults.lua @@ -49,10 +49,10 @@ do vim.keymap.set('x', '*', function() return _visual_search('/') - end, { desc = ':help v_star-default', expr = true, silent = true }) + end, { desc = ':help v_star-default', expr = true, replace_keycodes = false }) vim.keymap.set('x', '#', function() return _visual_search('?') - end, { desc = ':help v_#-default', expr = true, silent = true }) + end, { desc = ':help v_#-default', expr = true, replace_keycodes = false }) end --- Map Y to y$. This mimics the behavior of D and C. See |Y-default| @@ -222,9 +222,9 @@ do --- Execute a command and print errors without a stacktrace. --- @param opts table Arguments to |nvim_cmd()| local function cmd(opts) - local _, err = pcall(vim.api.nvim_cmd, opts, {}) - if err then - vim.api.nvim_err_writeln(err:sub(#'Vim:' + 1)) + local ok, err = pcall(vim.api.nvim_cmd, opts, {}) + if not ok then + vim.api.nvim_echo({ { err:sub(#'Vim:' + 1) } }, true, { err = true }) end end @@ -412,7 +412,7 @@ do end end - local nvim_popupmenu_augroup = vim.api.nvim_create_augroup('nvim_popupmenu', {}) + local nvim_popupmenu_augroup = vim.api.nvim_create_augroup('nvim.popupmenu', {}) vim.api.nvim_create_autocmd('MenuPopup', { pattern = '*', group = nvim_popupmenu_augroup, @@ -429,13 +429,13 @@ end --- Default autocommands. See |default-autocmds| do - local nvim_terminal_augroup = vim.api.nvim_create_augroup('nvim_terminal', {}) + local nvim_terminal_augroup = vim.api.nvim_create_augroup('nvim.terminal', {}) vim.api.nvim_create_autocmd('BufReadCmd', { pattern = 'term://*', group = nvim_terminal_augroup, desc = 'Treat term:// buffers as terminal buffers', nested = true, - command = "if !exists('b:term_title')|call termopen(matchstr(expand(\"<amatch>\"), '\\c\\mterm://\\%(.\\{-}//\\%(\\d\\+:\\)\\?\\)\\?\\zs.*'), {'cwd': expand(get(matchlist(expand(\"<amatch>\"), '\\c\\mterm://\\(.\\{-}\\)//'), 1, ''))})", + command = "if !exists('b:term_title')|call jobstart(matchstr(expand(\"<amatch>\"), '\\c\\mterm://\\%(.\\{-}//\\%(\\d\\+:\\)\\?\\)\\?\\zs.*'), {'term': v:true, 'cwd': expand(get(matchlist(expand(\"<amatch>\"), '\\c\\mterm://\\(.\\{-}\\)//'), 1, ''))})", }) vim.api.nvim_create_autocmd({ 'TermClose' }, { @@ -492,6 +492,10 @@ do vim.bo.textwidth = 0 vim.wo[0][0].wrap = false vim.wo[0][0].list = false + vim.wo[0][0].number = false + vim.wo[0][0].relativenumber = false + vim.wo[0][0].signcolumn = 'no' + vim.wo[0][0].foldcolumn = '0' -- This is gross. Proper list options support when? local winhl = vim.o.winhighlight @@ -505,14 +509,14 @@ do vim.api.nvim_create_autocmd('CmdwinEnter', { pattern = '[:>]', desc = 'Limit syntax sync to maxlines=1 in the command window', - group = vim.api.nvim_create_augroup('nvim_cmdwin', {}), + group = vim.api.nvim_create_augroup('nvim.cmdwin', {}), command = 'syntax sync minlines=1 maxlines=1', }) vim.api.nvim_create_autocmd('SwapExists', { pattern = '*', desc = 'Skip the swapfile prompt when the swapfile is owned by a running Nvim process', - group = vim.api.nvim_create_augroup('nvim_swapfile', {}), + group = vim.api.nvim_create_augroup('nvim.swapfile', {}), callback = function() local info = vim.fn.swapinfo(vim.v.swapname) local user = vim.uv.os_get_passwd().username @@ -539,15 +543,16 @@ do end if tty then - local group = vim.api.nvim_create_augroup('nvim_tty', {}) + local group = vim.api.nvim_create_augroup('nvim.tty', {}) --- Set an option after startup (so that OptionSet is fired), but only if not --- already set by the user. --- --- @param option string Option name --- @param value any Option value - local function setoption(option, value) - if vim.api.nvim_get_option_info2(option, {}).was_set then + --- @param force boolean? Always set the value, even if already set + local function setoption(option, value, force) + if not force and vim.api.nvim_get_option_info2(option, {}).was_set then -- Don't do anything if option is already set return end @@ -563,7 +568,7 @@ do once = true, nested = true, callback = function() - setoption(option, value) + setoption(option, value, force) end, }) end @@ -645,11 +650,15 @@ do return nil, nil, nil end - local timer = assert(vim.uv.new_timer()) - + -- This autocommand updates the value of 'background' anytime we receive + -- an OSC 11 response from the terminal emulator. If the user has set + -- 'background' explicitly then we will delete this autocommand, + -- effectively disabling automatic background setting. + local force = false local id = vim.api.nvim_create_autocmd('TermResponse', { group = group, nested = true, + desc = "Update the value of 'background' automatically based on the terminal emulator's background color", callback = function(args) local resp = args.data ---@type string local r, g, b = parseosc11(resp) @@ -661,27 +670,33 @@ do if rr and gg and bb then local luminance = (0.299 * rr) + (0.587 * gg) + (0.114 * bb) local bg = luminance < 0.5 and 'dark' or 'light' - setoption('background', bg) + setoption('background', bg, force) + + -- On the first query response, don't force setting the option in + -- case the user has already set it manually. If they have, then + -- this autocommand will be deleted. If they haven't, then we do + -- want to force setting the option to override the value set by + -- this autocommand. + if not force then + force = true + end end + end + end, + }) - return true + vim.api.nvim_create_autocmd('VimEnter', { + group = group, + nested = true, + once = true, + callback = function() + if vim.api.nvim_get_option_info2('background', {}).was_set then + vim.api.nvim_del_autocmd(id) end end, }) io.stdout:write('\027]11;?\007') - - timer:start(1000, 0, function() - -- Delete the autocommand if no response was received - vim.schedule(function() - -- Suppress error if autocommand has already been deleted - pcall(vim.api.nvim_del_autocmd, id) - end) - - if not timer:is_closing() then - timer:close() - end - end) end --- If the TUI (term_has_truecolor) was able to determine that the host diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index 44f17b3f85..a77ea9bb91 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -58,6 +58,7 @@ vim._extra = { --- @private vim.log = { + --- @enum vim.log.levels levels = { TRACE = 0, DEBUG = 1, @@ -92,7 +93,7 @@ local utfs = { --- --- -- Runs synchronously: --- local obj = vim.system({'echo', 'hello'}, { text = true }):wait() ---- -- { code = 0, signal = 0, stdout = 'hello', stderr = '' } +--- -- { code = 0, signal = 0, stdout = 'hello\n', stderr = '' } --- --- ``` --- @@ -390,7 +391,7 @@ end local VIM_CMD_ARG_MAX = 20 ---- Executes Vim script commands. +--- Executes Vimscript (|Ex-commands|). --- --- Note that `vim.cmd` can be indexed with a command name to return a callable function to the --- command. @@ -424,8 +425,9 @@ local VIM_CMD_ARG_MAX = 20 --- vim.cmd.colorscheme('blue') --- ``` --- +---@diagnostic disable-next-line: undefined-doc-param ---@param command string|table Command(s) to execute. ---- If a string, executes multiple lines of Vim script at once. In this +--- If a string, executes multiple lines of Vimscript at once. In this --- case, it is an alias to |nvim_exec2()|, where `opts.output` is set --- to false. Thus it works identical to |:source|. --- If a table, executes a single command. In this case, it is an alias @@ -440,10 +442,12 @@ vim.cmd = setmetatable({}, { return '' end end, + --- @param t table<string,function> __index = function(t, command) t[command] = function(...) - local opts + local opts --- @type vim.api.keyset.cmd if select('#', ...) == 1 and type(select(1, ...)) == 'table' then + --- @type vim.api.keyset.cmd opts = select(1, ...) -- Move indexed positions in opts to opt.args @@ -454,6 +458,7 @@ vim.cmd = setmetatable({}, { break end opts.args[i] = opts[i] + --- @diagnostic disable-next-line: no-unknown opts[i] = nil end end @@ -528,7 +533,7 @@ function vim.region(bufnr, pos1, pos2, regtype, inclusive) end if pos1[1] > pos2[1] or (pos1[1] == pos2[1] and pos1[2] > pos2[2]) then - pos1, pos2 = pos2, pos1 + pos1, pos2 = pos2, pos1 --- @type [integer, integer], [integer, integer] end -- getpos() may return {0,0,0,0} @@ -620,13 +625,8 @@ end ---@param opts table|nil Optional parameters. Unused by default. ---@diagnostic disable-next-line: unused-local function vim.notify(msg, level, opts) -- luacheck: no unused args - if level == vim.log.levels.ERROR then - vim.api.nvim_err_writeln(msg) - elseif level == vim.log.levels.WARN then - vim.api.nvim_echo({ { msg, 'WarningMsg' } }, true, {}) - else - vim.api.nvim_echo({ { msg } }, true, {}) - end + local chunks = { { msg, level == vim.log.levels.WARN and 'WarningMsg' or nil } } + vim.api.nvim_echo(chunks, true, { err = level == vim.log.levels.ERROR }) end do @@ -705,6 +705,7 @@ function vim._on_key(buf, typed_buf) local discard = false for k, v in pairs(on_key_cbs) do local fn = v[1] + --- @type boolean, any local ok, rv = xpcall(function() return fn(buf, typed_buf) end, debug.traceback) @@ -832,6 +833,7 @@ function vim.str_utfindex(s, encoding, index, strict_indexing) -- Return (multiple): ~ -- (`integer`) UTF-32 index -- (`integer`) UTF-16 index + --- @diagnostic disable-next-line: redundant-return-value return col32, col16 end @@ -1004,7 +1006,7 @@ function vim._expand_pat(pat, env) or vim.v == final_env and { 'v:', 'var' } or { nil, nil } ) - assert(prefix, "Can't resolve final_env") + assert(prefix and type, "Can't resolve final_env") local vars = vim.fn.getcompletion(prefix .. match_part, type) --- @type string[] insert_keys(vim .iter(vars) diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua index fccf4b8dbe..35063dffca 100644 --- a/runtime/lua/vim/_inspector.lua +++ b/runtime/lua/vim/_inspector.lua @@ -1,3 +1,5 @@ +--- @diagnostic disable:no-unknown + --- @class vim._inspector.Filter --- @inlinedoc --- @@ -53,7 +55,7 @@ function vim.inspect_pos(bufnr, row, col, filter) local cursor = vim.api.nvim_win_get_cursor(win) row, col = cursor[1] - 1, cursor[2] end - bufnr = bufnr == 0 and vim.api.nvim_get_current_buf() or bufnr + bufnr = vim._resolve_bufnr(bufnr) local results = { treesitter = {}, --- @type table[] @@ -78,6 +80,7 @@ function vim.inspect_pos(bufnr, row, col, filter) -- treesitter if filter.treesitter then for _, capture in pairs(vim.treesitter.get_captures_at_pos(bufnr, row, col)) do + --- @diagnostic disable-next-line: inject-field capture.hl_group = '@' .. capture.capture .. '.' .. capture.lang results.treesitter[#results.treesitter + 1] = resolve_hl(capture) end @@ -128,13 +131,13 @@ function vim.inspect_pos(bufnr, row, col, filter) if filter.semantic_tokens then results.semantic_tokens = vim.tbl_filter(function(extmark) - return extmark.ns:find('vim_lsp_semantic_tokens') == 1 + return extmark.ns:find('nvim.lsp.semantic_tokens') == 1 end, extmarks) end if filter.extmarks then results.extmarks = vim.tbl_filter(function(extmark) - return extmark.ns:find('vim_lsp_semantic_tokens') ~= 1 + return extmark.ns:find('nvim.lsp.semantic_tokens') ~= 1 and (filter.extmarks == 'all' or extmark.opts.hl_group) end, extmarks) end @@ -146,6 +149,13 @@ end --- ---Can also be shown with `:Inspect`. [:Inspect]() --- +---Example: To bind this function to the vim-scriptease +---inspired `zS` in Normal mode: +--- +---```lua +---vim.keymap.set('n', 'zS', vim.show_pos) +---``` +--- ---@since 11 ---@param bufnr? integer defaults to the current buffer ---@param row? integer row to inspect, 0-based. Defaults to the row of the current cursor @@ -171,7 +181,7 @@ function vim.show_pos(bufnr, row, col, filter) if data.hl_group ~= data.hl_group_link then append('links to ', 'MoreMsg') append(data.hl_group_link, data.hl_group_link) - append(' ') + append(' ') end if comment then append(comment, 'Comment') @@ -184,7 +194,14 @@ function vim.show_pos(bufnr, row, col, filter) append('Treesitter', 'Title') nl() for _, capture in ipairs(items.treesitter) do - item(capture, capture.lang) + item( + capture, + string.format( + 'priority: %d language: %s', + capture.metadata.priority or vim.hl.priorities.treesitter, + capture.lang + ) + ) end nl() end diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua index 3c9b9d4f44..3d10729d23 100644 --- a/runtime/lua/vim/_meta/api.lua +++ b/runtime/lua/vim/_meta/api.lua @@ -3,6 +3,10 @@ -- DO NOT EDIT error('Cannot require a meta file') +--- This file embeds vimdoc as the function descriptions +--- so ignore any doc related errors. +--- @diagnostic disable: undefined-doc-name,luadoc-miss-symbol + vim.api = {} --- @private @@ -163,35 +167,14 @@ function vim.api.nvim__stats() end --- @return any function vim.api.nvim__unpack(str) end ---- Adds a highlight to buffer. ---- ---- Useful for plugins that dynamically generate highlights to a buffer ---- (like a semantic highlighter or linter). The function adds a single ---- highlight to a buffer. Unlike `matchaddpos()` highlights follow changes to ---- line numbering (as lines are inserted/removed above the highlighted line), ---- like signs and marks do. ---- ---- Namespaces are used for batch deletion/updating of a set of highlights. To ---- create a namespace, use `nvim_create_namespace()` which returns a namespace ---- id. Pass it in to this function as `ns_id` to add highlights to the ---- namespace. All highlights in the same namespace can then be cleared with ---- single call to `nvim_buf_clear_namespace()`. If the highlight never will be ---- deleted by an API call, pass `ns_id = -1`. ---- ---- As a shorthand, `ns_id = 0` can be used to create a new namespace for the ---- highlight, the allocated id is then returned. If `hl_group` is the empty ---- string no highlight is added, but a new `ns_id` is still returned. This is ---- supported for backwards compatibility, new code should use ---- `nvim_create_namespace()` to create a new empty namespace. ---- ---- @param buffer integer Buffer handle, or 0 for current buffer ---- @param ns_id integer namespace to use or -1 for ungrouped highlight ---- @param hl_group string Name of the highlight group to use ---- @param line integer Line to highlight (zero-indexed) ---- @param col_start integer Start of (byte-indexed) column range to highlight ---- @param col_end integer End of (byte-indexed) column range to highlight, ---- or -1 to highlight to end of line ---- @return integer # The ns_id that was used +--- @deprecated +--- @param buffer integer +--- @param ns_id integer +--- @param hl_group string +--- @param line integer +--- @param col_start integer +--- @param col_end integer +--- @return integer function vim.api.nvim_buf_add_highlight(buffer, ns_id, hl_group, line, col_start, col_end) end --- Activates buffer-update events on a channel, or as Lua callbacks. @@ -272,12 +255,12 @@ function vim.api.nvim_buf_attach(buffer, send_buffer, opts) end --- This temporarily switches current buffer to "buffer". --- If the current window already shows "buffer", the window is not switched. --- If a window inside the current tabpage (including a float) already shows the ---- buffer, then one of these windows will be set as current window temporarily. +--- buffer, then one of those windows will be set as current window temporarily. --- Otherwise a temporary scratch window (called the "autocmd window" for --- historical reasons) will be used. --- --- This is useful e.g. to call Vimscript functions that only work with the ---- current buffer/window currently, like `termopen()`. +--- current buffer/window currently, like `jobstart(…, {'term': v:true})`. --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param fun function Function to call inside the buffer (currently Lua callable @@ -452,7 +435,7 @@ function vim.api.nvim_buf_get_extmarks(buffer, ns_id, start, end_, opts) end --- --- @param buffer integer Buffer handle, or 0 for current buffer --- @param mode string Mode short-name ("n", "i", "v", ...) ---- @return vim.api.keyset.keymap[] # Array of |maparg()|-like dictionaries describing mappings. +--- @return vim.api.keyset.get_keymap[] # Array of |maparg()|-like dictionaries describing mappings. --- The "buffer" key holds the associated buffer handle. function vim.api.nvim_buf_get_keymap(buffer, mode) end @@ -595,6 +578,9 @@ function vim.api.nvim_buf_line_count(buffer) end --- - hl_group : highlight group used for the text range. This and below --- highlight groups can be supplied either as a string or as an integer, --- the latter of which can be obtained using `nvim_get_hl_id_by_name()`. +--- +--- Multiple highlight groups can be stacked by passing an array (highest +--- priority last). --- - hl_eol : when true, for a multiline highlight covering the --- EOL of a line, continue the highlight for the rest --- of the screen line (just like for diff and @@ -607,6 +593,15 @@ function vim.api.nvim_buf_line_count(buffer) end --- (highest priority last). --- - virt_text_pos : position of virtual text. Possible values: --- - "eol": right after eol character (default). +--- - "eol_right_align": display right aligned in the window +--- unless the virtual text is longer than +--- the space available. If the virtual +--- text is too long, it is truncated to +--- fit in the window after the EOL +--- character. If the line is wrapped, the +--- virtual text is shown after the end of +--- the line rather than the previous +--- screen line. --- - "overlay": display over the specified column, without --- shifting the underlying text. --- - "right_align": display right aligned in the window. @@ -885,10 +880,8 @@ function vim.api.nvim_cmd(cmd, opts) end --- --- On execution error: fails with Vimscript error, updates v:errmsg. --- ---- Prefer using `nvim_cmd()` or `nvim_exec2()` over this. To evaluate multiple lines of Vim script ---- or an Ex command directly, use `nvim_exec2()`. To construct an Ex command using a structured ---- format and then execute it, use `nvim_cmd()`. To modify an Ex command before evaluating it, use ---- `nvim_parse_cmd()` in conjunction with `nvim_cmd()`. +--- Prefer `nvim_cmd()` or `nvim_exec2()` instead. To modify an Ex command in a structured way +--- before executing it, modify the result of `nvim_parse_cmd()` then pass it to `nvim_cmd()`. --- --- @param command string Ex command string function vim.api.nvim_command(command) end @@ -963,9 +956,9 @@ function vim.api.nvim_create_augroup(name, opts) end --- - id: (number) autocommand id --- - event: (string) name of the triggered event `autocmd-events` --- - group: (number|nil) autocommand group id, if any ---- - match: (string) expanded value of [<amatch>] ---- - buf: (number) expanded value of [<abuf>] ---- - file: (string) expanded value of [<afile>] +--- - file: (string) [<afile>] (not expanded to a full path) +--- - match: (string) [<amatch>] (expanded to a full path) +--- - buf: (number) [<abuf>] --- - data: (any) arbitrary data passed from [nvim_exec_autocmds()] [event-data]() --- - command (string) optional: Vim command to execute on event. Cannot be used with --- {callback} @@ -989,7 +982,7 @@ function vim.api.nvim_create_buf(listed, scratch) end --- Creates a new namespace or gets an existing one. [namespace]() --- --- Namespaces are used for buffer highlights and virtual text, see ---- `nvim_buf_add_highlight()` and `nvim_buf_set_extmark()`. +--- `nvim_buf_set_extmark()`. --- --- Namespaces can be named or anonymous. If `name` matches an existing --- namespace, the associated id is returned. If `name` is an empty string @@ -1012,7 +1005,7 @@ function vim.api.nvim_create_namespace(name) end --- ``` --- --- @param name string Name of the new user command. Must begin with an uppercase letter. ---- @param command any Replacement command to execute when this user command is executed. When called +--- @param command string|fun(args: vim.api.keyset.create_user_command.command_args) Replacement command to execute when this user command is executed. When called --- from Lua, the command can also be a Lua function. The function is called with a --- single table argument that contains the following keys: --- - name: (string) Command name @@ -1099,29 +1092,28 @@ function vim.api.nvim_del_user_command(name) end --- @param name string Variable name function vim.api.nvim_del_var(name) end ---- Echo a message. +--- Prints a message given by a list of `[text, hl_group]` "chunks". +--- +--- Example: +--- ```lua +--- vim.api.nvim_echo({ { 'chunk1-line1\nchunk1-line2\n' }, { 'chunk2-line1' } }, true, {}) +--- ``` --- ---- @param chunks any[] A list of `[text, hl_group]` arrays, each representing a ---- text chunk with specified highlight group name or ID. ---- `hl_group` element can be omitted for no highlight. +--- @param chunks any[] List of `[text, hl_group]` pairs, where each is a `text` string highl |