diff options
39 files changed, 328 insertions, 517 deletions
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt index db878ac304..f36ef1df0a 100644 --- a/runtime/doc/develop.txt +++ b/runtime/doc/develop.txt @@ -233,6 +233,8 @@ Docstring format: - List-items start with `-` (useful to nest or "indent") - Use `<pre>` for code samples. Code samples can be annotated as `vim` or `lua` +- Use `@nodoc` to prevent documentation generation. +- Files which has `@meta` are only used for typing and documentation. Example: the help for |vim.paste()| is generated from a docstring decorating vim.paste in runtime/lua/vim/_editor.lua like this: > diff --git a/runtime/doc/lsp.txt b/runtime/doc/lsp.txt index fa109dbc26..edc9f50c8d 100644 --- a/runtime/doc/lsp.txt +++ b/runtime/doc/lsp.txt @@ -758,6 +758,24 @@ client_is_stopped({client_id}) *vim.lsp.client_is_stopped()* Return: ~ (boolean) stopped true if client is stopped, false otherwise. +commands *vim.lsp.commands* + Registry for client side commands. This is an extension point for plugins + to handle custom commands which are not part of the core language server + protocol specification. + + The registry is a table where the key is a unique command name, and the + value is a function which is called if any LSP action (code action, code + lenses, ...) triggers the command. + + If a LSP response contains a command for which no matching entry is + available in this registry, the command will be executed via the LSP + server using `workspace/executeCommand`. + + The first argument to the function will be the `Command`: Command title: + String command: String arguments?: any[] + + The second argument is the `ctx` of |lsp-handler| + formatexpr({opts}) *vim.lsp.formatexpr()* Provides an interface between the built-in client and a `formatexpr` function. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index ac40d61e20..0b894897d1 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -591,16 +591,6 @@ If you want to exclude visual selections from highlighting on yank, use: >vim au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false} < -vim.highlight.priorities *vim.highlight.priorities* - - Table with default priorities used for highlighting: - • `syntax`: `50`, used for standard syntax highlighting - • `treesitter`: `100`, used for tree-sitter-based highlighting - • `semantic_tokens`: `125`, used for LSP semantic token highlighting - • `diagnostics`: `150`, used for code analysis such as diagnostics - • `user`: `200`, used for user-triggered highlights such as LSP document - symbols or `on_yank` autocommands - vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* Highlight the yanked text @@ -616,6 +606,15 @@ vim.highlight.on_yank({opts}) *vim.highlight.on_yank()* • priority integer priority (default |vim.highlight.priorities|`.user`) +vim.highlight.priorities *vim.highlight.priorities* + Table with default priorities used for highlighting: + • `syntax`: `50`, used for standard syntax highlighting + • `treesitter`: `100`, used for tree-sitter-based highlighting + • `semantic_tokens`: `125`, used for LSP semantic token highlighting + • `diagnostics`: `150`, used for code analysis such as diagnostics + • `user`: `200`, used for user-triggered highlights such as LSP document + symbols or `on_yank` autocommands + *vim.highlight.range()* vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {opts}) Apply highlight group to range of text. @@ -1189,15 +1188,6 @@ vim.v *vim.v* |v:| variables. Invalid or unset key returns `nil`. -vim.env *vim.env* - Environment variables defined in the editor session. - See |expand-env| and |:let-environment| for the Vimscript behavior. - Invalid or unset key returns `nil`. - Example: >lua - vim.env.FOO = 'bar' - print(vim.env.TERM) -< - ` ` *lua-options* *lua-vim-options* *lua-vim-set* @@ -1221,62 +1211,6 @@ window-scoped options. Note that this must NOT be confused with |local-options| and |:setlocal|. There is also |vim.go| that only accesses the global value of a |global-local| option, see |:setglobal|. -vim.o *vim.o* - Get or set |options|. Like `:set`. Invalid key is an error. - - Note: this works on both buffer-scoped and window-scoped options using the - current buffer and window. - - Example: >lua - vim.o.cmdheight = 4 - print(vim.o.columns) - print(vim.o.foo) -- error: invalid key -< - -vim.go *vim.go* - Get or set global |options|. Like `:setglobal`. Invalid key is - an error. - - Note: this is different from |vim.o| because this accesses the global - option value and thus is mostly useful for use with |global-local| - options. - - Example: >lua - vim.go.cmdheight = 4 - print(vim.go.columns) - print(vim.go.bar) -- error: invalid key -< - -vim.bo[{bufnr}] *vim.bo* - Get or set buffer-scoped |options| for the buffer with number {bufnr}. - Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current - buffer is used. Invalid {bufnr} or key is an error. - - Note: this is equivalent to both `:set` and `:setlocal`. - - Example: >lua - local bufnr = vim.api.nvim_get_current_buf() - vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true - print(vim.bo.comments) - print(vim.bo.baz) -- error: invalid key - -vim.wo[{winid}][{bufnr}] *vim.wo* - Get or set window-scoped |options| for the window with handle {winid} and - buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like - `:set` otherwise. If [{winid}] is omitted then the current window is - used. Invalid {winid}, {bufnr} or key is an error. - - Note: only {bufnr} with value `0` (the current buffer in the window) is - supported. - - Example: >lua - local winid = vim.api.nvim_get_current_win() - vim.wo[winid].number = true -- same as vim.wo.number = true - print(vim.wo.foldmarker) - print(vim.wo.quux) -- error: invalid key - vim.wo[winid][0].spell = false -- like ':setlocal nospell' -< - ` ` *vim.opt_local* *vim.opt_global* *vim.opt* @@ -1419,11 +1353,81 @@ Option:remove({value}) *vim.opt:remove()* Parameters: ~ • {value} (string) Value to remove +vim.bo *vim.bo* + Get or set buffer-scoped |options| for the buffer with number {bufnr}. + Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current + buffer is used. Invalid {bufnr} or key is an error. + + Note: this is equivalent to both `:set` and `:setlocal`. + + Example: >lua + local bufnr = vim.api.nvim_get_current_buf() + vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true + print(vim.bo.comments) + print(vim.bo.baz) -- error: invalid key +< + + Parameters: ~ + • {bufnr} (integer|nil) + +vim.env *vim.env* + Environment variables defined in the editor session. See |expand-env| and + |:let-environment| for the Vimscript behavior. Invalid or unset key + returns `nil` . Example: >lua + vim.env.FOO = 'bar' + print(vim.env.TERM) +< + + Parameters: ~ + • {var} (string) + +vim.go *vim.go* + Get or set global |options|. Like `:setglobal`. Invalid key is an error. + + Note: this is different from |vim.o| because this accesses the global + option value and thus is mostly useful for use with |global-local| + options. + + Example: >lua + vim.go.cmdheight = 4 + print(vim.go.columns) + print(vim.go.bar) -- error: invalid key +< + +vim.o *vim.o* + Get or set |options|. Like `:set`. Invalid key is an error. + + Note: this works on both buffer-scoped and window-scoped options using the + current buffer and window. + + Example: >lua + vim.o.cmdheight = 4 + print(vim.o.columns) + print(vim.o.foo) -- error: invalid key +< + +vim.wo *vim.wo* + Get or set window-scoped |options| for the window with handle {winid} and + buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like + `:set` otherwise. If [{winid}] is omitted then the current window is used. + Invalid {winid}, {bufnr} or key is an error. + + Note: only {bufnr} with value `0` (the current buffer in the window) is + supported. + + Example: >lua + local winid = vim.api.nvim_get_current_win() + vim.wo[winid].number = true -- same as vim.wo.number = true + print(vim.wo.foldmarker) + print(vim.wo.quux) -- error: invalid key + vim.wo[winid][0].spell = false -- like ':setlocal nospell' +< + ============================================================================== Lua module: vim *lua-vim* -vim.cmd({command}) *vim.cmd()* +vim.cmd *vim.cmd()* Execute Vim script commands. Note that `vim.cmd` can be indexed with a command name to return a @@ -1468,10 +1472,6 @@ vim.cmd({command}) *vim.cmd()* See also: ~ • |ex-cmd-index| - *vim.connection_failure_errmsg()* -vim.connection_failure_errmsg({consequence}) - TODO: Documentation - vim.defer_fn({fn}, {timeout}) *vim.defer_fn()* Defers calling {fn} until {timeout} ms passes. @@ -1501,7 +1501,7 @@ vim.deprecate({name}, {alternative}, {version}, {plugin}, {backtrace}) Return: ~ (string|nil) # Deprecated message, or nil if no message was shown. -vim.inspect({object}, {options}) *vim.inspect()* +vim.inspect *vim.inspect()* Gets a human-readable representation of the given object. See also: ~ diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua index bb0aa97a0d..4372aef7b3 100644 --- a/runtime/lua/vim/_editor.lua +++ b/runtime/lua/vim/_editor.lua @@ -54,6 +54,7 @@ vim._extra = { inspect_pos = true, } +--- @private vim.log = { levels = { TRACE = 0, @@ -187,9 +188,7 @@ end ---@see |vim.print()| ---@see https://github.com/kikito/inspect.lua ---@see https://github.com/mpeterv/vinspect -local function inspect(object, options) -- luacheck: no unused - error(object, options) -- Stub for gen_vimdoc.py -end +vim.inspect = vim.inspect do local tdots, tick, got_line1, undo_started, trailing_nl = 0, 0, false, false, false @@ -328,6 +327,7 @@ function vim.schedule_wrap(cb) end -- vim.fn.{func}(...) +---@private vim.fn = setmetatable({}, { __index = function(t, key) local _fn @@ -345,10 +345,13 @@ vim.fn = setmetatable({}, { end, }) +--- @private vim.funcref = function(viml_func_name) return vim.fn[viml_func_name] end +local VIM_CMD_ARG_MAX = 20 + --- Execute Vim script commands. --- --- Note that `vim.cmd` can be indexed with a command name to return a callable function to the @@ -389,12 +392,6 @@ end --- If a table, executes a single command. In this case, it is an alias --- to |nvim_cmd()| where `opts` is empty. ---@see |ex-cmd-index| -function vim.cmd(command) -- luacheck: no unused - error(command) -- Stub for gen_vimdoc.py -end - -local VIM_CMD_ARG_MAX = 20 - vim.cmd = setmetatable({}, { __call = function(_, command) if type(command) == 'table' then @@ -435,7 +432,6 @@ vim.cmd = setmetatable({}, { do local validate = vim.validate - ---@private local function make_dict_accessor(scope, handle) validate({ scope = { scope, 's' }, @@ -745,7 +741,6 @@ function vim._expand_pat(pat, env) end local keys = {} - ---@private local function insert_keys(obj) for k, _ in pairs(obj) do if type(k) == 'string' and string.sub(k, 1, string.len(match_part)) == match_part then @@ -1008,7 +1003,6 @@ end function vim._init_default_mappings() -- mappings - ---@private local function region_chunks(region) local chunks = {} local maxcol = vim.v.maxcol @@ -1020,7 +1014,6 @@ function vim._init_default_mappings() return chunks end - ---@private local function _visual_search(cmd) assert(cmd == '/' or cmd == '?') vim.api.nvim_feedkeys('\27', 'nx', true) -- Escape visual mode. @@ -1037,7 +1030,6 @@ function vim._init_default_mappings() vim.api.nvim_feedkeys(search_cmd, 'nx', true) end - ---@private local function map(mode, lhs, rhs) vim.keymap.set(mode, lhs, rhs, { desc = 'Nvim builtin' }) end diff --git a/runtime/lua/vim/_inspector.lua b/runtime/lua/vim/_inspector.lua index ecd39c35bc..3f7b9d2c23 100644 --- a/runtime/lua/vim/_inspector.lua +++ b/runtime/lua/vim/_inspector.lua @@ -56,7 +56,6 @@ function vim.inspect_pos(bufnr, row, col, filter) } -- resolve hl links - ---@private local function resolve_hl(data) if data.hl_group then local hlid = vim.api.nvim_get_hl_id_by_name(data.hl_group) @@ -91,7 +90,6 @@ function vim.inspect_pos(bufnr, row, col, filter) end --- Convert an extmark tuple into a table - --- @private local function to_map(extmark) extmark = { id = extmark[1], @@ -107,7 +105,6 @@ function vim.inspect_pos(bufnr, row, col, filter) end --- Check if an extmark overlaps this position - --- @private local function is_here(extmark) return (row >= extmark.row and row <= extmark.end_row) -- within the rows of the extmark and (row > extmark.row or col >= extmark.col) -- either not the first row, or in range of the col @@ -148,17 +145,14 @@ function vim.show_pos(bufnr, row, col, filter) local lines = { {} } - ---@private local function append(str, hl) table.insert(lines[#lines], { str, hl }) end - ---@private local function nl() table.insert(lines, {}) end - ---@private local function item(data, comment) append(' - ') append(data.hl_group, data.hl_group) diff --git a/runtime/lua/vim/_options.lua b/runtime/lua/vim/_options.lua index 6dbe4cf64a..d54e8b447c 100644 --- a/runtime/lua/vim/_options.lua +++ b/runtime/lua/vim/_options.lua @@ -92,15 +92,6 @@ ---vim.v *vim.v* --- |v:| variables. --- Invalid or unset key returns `nil`. ---- ----vim.env *vim.env* ---- Environment variables defined in the editor session. ---- See |expand-env| and |:let-environment| for the Vimscript behavior. ---- Invalid or unset key returns `nil`. ---- Example: >lua ---- vim.env.FOO = 'bar' ---- print(vim.env.TERM) ----< ---</pre> local api = vim.api @@ -118,7 +109,6 @@ local key_value_options = { --- Convert a vimoption_T style dictionary to the correct OptionType associated with it. ---@return string ----@private local function get_option_metatype(name, info) if info.type == 'string' then if info.flaglist then @@ -143,6 +133,14 @@ local options_info = setmetatable({}, { end, }) +---Environment variables defined in the editor session. +---See |expand-env| and |:let-environment| for the Vimscript behavior. +---Invalid or unset key returns `nil`. +---Example: <pre>lua +--- vim.env.FOO = 'bar' +--- print(vim.env.TERM) +---</pre> +---@param var string vim.env = setmetatable({}, { __index = function(_, k) local v = vim.fn.getenv(k) @@ -157,7 +155,6 @@ vim.env = setmetatable({}, { end, }) ----@private local function opt_validate(option_name, target_scope) local scope = options_info[option_name].scope if scope ~= target_scope then @@ -174,7 +171,6 @@ local function opt_validate(option_name, target_scope) end end ----@private local function new_buf_opt_accessor(bufnr) return setmetatable({}, { __index = function(_, k) @@ -192,7 +188,6 @@ local function new_buf_opt_accessor(bufnr) }) end ----@private local function new_win_opt_accessor(winid, bufnr) return setmetatable({}, { __index = function(_, k) @@ -253,19 +248,15 @@ end ---global value of a |global-local| option, see |:setglobal|. ---</pre> ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.o *vim.o* ---- Get or set |options|. Like `:set`. Invalid key is an error. +---Get or set |options|. Like `:set`. Invalid key is an error. --- ---- Note: this works on both buffer-scoped and window-scoped options using the ---- current buffer and window. +---Note: this works on both buffer-scoped and window-scoped options using the +---current buffer and window. --- ---- Example: >lua ---- vim.o.cmdheight = 4 ---- print(vim.o.columns) ---- print(vim.o.foo) -- error: invalid key ----< +---Example: <pre>lua +--- vim.o.cmdheight = 4 +--- print(vim.o.columns) +--- print(vim.o.foo) -- error: invalid key ---</pre> vim.o = setmetatable({}, { __index = function(_, k) @@ -276,21 +267,17 @@ vim.o = setmetatable({}, { end, }) ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.go *vim.go* ---- Get or set global |options|. Like `:setglobal`. Invalid key is ---- an error. ---- ---- Note: this is different from |vim.o| because this accesses the global ---- option value and thus is mostly useful for use with |global-local| ---- options. ---- ---- Example: >lua ---- vim.go.cmdheight = 4 ---- print(vim.go.columns) ---- print(vim.go.bar) -- error: invalid key ----< +---Get or set global |options|. Like `:setglobal`. Invalid key is +---an error. +--- +---Note: this is different from |vim.o| because this accesses the global +---option value and thus is mostly useful for use with |global-local| +---options. +--- +---Example: <pre>lua +--- vim.go.cmdheight = 4 +--- print(vim.go.columns) +--- print(vim.go.bar) -- error: invalid key ---</pre> vim.go = setmetatable({}, { __index = function(_, k) @@ -301,41 +288,36 @@ vim.go = setmetatable({}, { end, }) ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.bo[{bufnr}] *vim.bo* ---- Get or set buffer-scoped |options| for the buffer with number {bufnr}. ---- Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current ---- buffer is used. Invalid {bufnr} or key is an error. ---- ---- Note: this is equivalent to both `:set` and `:setlocal`. ---- ---- Example: >lua ---- local bufnr = vim.api.nvim_get_current_buf() ---- vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true ---- print(vim.bo.comments) ---- print(vim.bo.baz) -- error: invalid key +---Get or set buffer-scoped |options| for the buffer with number {bufnr}. +---Like `:set` and `:setlocal`. If [{bufnr}] is omitted then the current +---buffer is used. Invalid {bufnr} or key is an error. +--- +---Note: this is equivalent to both `:set` and `:setlocal`. +--- +---Example: <pre>lua +--- local bufnr = vim.api.nvim_get_current_buf() +--- vim.bo[bufnr].buflisted = true -- same as vim.bo.buflisted = true +--- print(vim.bo.comments) +--- print(vim.bo.baz) -- error: invalid key ---</pre> +---@param bufnr integer|nil vim.bo = new_buf_opt_accessor() ----@addtogroup lua-vimscript ----@brief <pre>help ----vim.wo[{winid}][{bufnr}] *vim.wo* ---- Get or set window-scoped |options| for the window with handle {winid} and ---- buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like ---- `:set` otherwise. If [{winid}] is omitted then the current window is ---- used. Invalid {winid}, {bufnr} or key is an error. ---- ---- Note: only {bufnr} with value `0` (the current buffer in the window) is ---- supported. ---- ---- Example: >lua ---- local winid = vim.api.nvim_get_current_win() ---- vim.wo[winid].number = true -- same as vim.wo.number = true ---- print(vim.wo.foldmarker) ---- print(vim.wo.quux) -- error: invalid key ---- vim.wo[winid][0].spell = false -- like ':setlocal nospell' ----< +---Get or set window-scoped |options| for the window with handle {winid} and +---buffer with number {bufnr}. Like `:setlocal` if {bufnr} is provided, like +---`:set` otherwise. If [{winid}] is omitted then the current window is +---used. Invalid {winid}, {bufnr} or key is an error. +--- +---Note: only {bufnr} with value `0` (the current buffer in the window) is +---supported. +--- +---Example: <pre>lua +--- local winid = vim.api.nvim_get_current_win() +--- vim.wo[winid].number = true -- same as vim.wo.number = true +--- print(vim.wo.foldmarker) +--- print(vim.wo.quux) -- error: invalid key +--- vim.wo[winid][0].spell = false -- like ':setlocal nospell' +--- ---</pre> vim.wo = new_win_opt_accessor() @@ -348,7 +330,6 @@ vim.wo = new_win_opt_accessor() ---@brief ]] --- Preserves the order and does not mutate the original list ---- @private local function remove_duplicate_values(t) local result, seen = {}, {} for _, v in ipairs(t) do @@ -364,7 +345,6 @@ end -- Check whether the OptionTypes is allowed for vim.opt -- If it does not match, throw an error which indicates which option causes the error. ---- @private local function assert_valid_value(name, value, types) local type_of_value = type(value) for _, valid_type in ipairs(types) do @@ -383,17 +363,14 @@ local function assert_valid_value(name, value, types) ) end ---- @private local function passthrough(_, x) return x end ---- @private local function tbl_merge(left, right) return vim.tbl_extend('force', left, right) end ---- @private local function tbl_remove(t, value) if type(value) == 'string' then t[value] = nil @@ -475,7 +452,6 @@ local to_vim_value = { } --- Convert a Lua value to a vimoption_T value ---- @private local function convert_value_to_vim(name, info, value) if value == nil then return vim.NIL @@ -591,7 +567,6 @@ local to_lua_value = { } --- Converts a vimoption_T style value to a Lua value ---- @private local function convert_value_to_lua(info, option_value) return to_lua_value[info.metatype](info, option_value) end @@ -618,7 +593,6 @@ local prepend_methods = { } --- Handles the '^' operator ---- @private local function prepend_value(info, current, new) return prepend_methods[info.metatype]( convert_value_to_lua(info, current), @@ -648,7 +622,6 @@ local add_methods = { } --- Handles the '+' operator ---- @private local function add_value(info, current, new) return add_methods[info.metatype]( convert_value_to_lua(info, current), @@ -656,7 +629,6 @@ local function add_value(info, current, new) ) end ---- @private local function remove_one_item(t, val) if vim.tbl_islist(t) then local remove_index = nil @@ -700,16 +672,13 @@ local remove_methods = { } --- Handles the '-' operator ---- @private local function remove_value(info, current, new) return remove_methods[info.metatype](convert_value_to_lua(info, current), new) end ---- @private local function create_option_accessor(scope) local option_mt - --- @private local function make_option(name, value) local info = assert(options_info[name], 'Not a valid option name: ' .. name) @@ -923,6 +892,11 @@ function Option:prepend(value) end -- luacheck: no unused ---@diagnostic disable-next-line:unused-local used for gen_vimdoc function Option:remove(value) end -- luacheck: no unused +---@private vim.opt = create_option_accessor() + +---@private vim.opt_local = create_option_accessor('local') + +---@private vim.opt_global = create_option_accessor('global') diff --git a/runtime/lua/vim/_system.lua b/runtime/lua/vim/_system.lua index ff566866c0..e6dab90425 100644 --- a/runtime/lua/vim/_system.lua +++ b/runtime/lua/vim/_system.lua @@ -30,7 +30,6 @@ local uv = vim.uv --- @field cmd string[] --- @field result? SystemCompleted ----@private ---@param state SystemState local function close_handles(state) for _, handle in pairs({ state.handle, state.stdin, state.stdout, state.stderr }) do @@ -128,7 +127,6 @@ function SystemObj:is_closing() return handle == nil or handle:is_closing() end ----@private ---@param output function|'false' ---@return uv_stream_t? ---@return function? Handler @@ -145,7 +143,6 @@ local function setup_output(output) return nil, nil end ----@private ---@param input string|string[]|true|nil ---@return uv_stream_t? ---@return string|string[]? diff --git a/runtime/lua/vim/_watch.lua b/runtime/lua/vim/_watch.lua index 00b74160 |