aboutsummaryrefslogtreecommitdiff
path: root/runtime/lua/vim/_meta
diff options
context:
space:
mode:
authorJosh Rahm <joshuarahm@gmail.com>2024-05-24 19:18:11 +0000
committerJosh Rahm <joshuarahm@gmail.com>2024-05-24 19:18:11 +0000
commitff7ed8f586589d620a806c3758fac4a47a8e7e15 (patch)
tree729bbcb92231538fa61dab6c3d890b025484b7f5 /runtime/lua/vim/_meta
parent376914f419eb08fdf4c1a63a77e1f035898a0f10 (diff)
parent28c04948a1c887a1cc0cb64de79fa32631700466 (diff)
downloadrneovim-ff7ed8f586589d620a806c3758fac4a47a8e7e15.tar.gz
rneovim-ff7ed8f586589d620a806c3758fac4a47a8e7e15.tar.bz2
rneovim-ff7ed8f586589d620a806c3758fac4a47a8e7e15.zip
Merge remote-tracking branch 'upstream/master' into mix_20240309
Diffstat (limited to 'runtime/lua/vim/_meta')
-rw-r--r--runtime/lua/vim/_meta/api.lua128
-rw-r--r--runtime/lua/vim/_meta/api_keysets.lua13
-rw-r--r--runtime/lua/vim/_meta/api_keysets_extra.lua2
-rw-r--r--runtime/lua/vim/_meta/base64.lua4
-rw-r--r--runtime/lua/vim/_meta/builtin.lua28
-rw-r--r--runtime/lua/vim/_meta/builtin_types.lua8
-rw-r--r--runtime/lua/vim/_meta/diff.lua85
-rw-r--r--runtime/lua/vim/_meta/lpeg.lua7
-rw-r--r--runtime/lua/vim/_meta/options.lua60
-rw-r--r--runtime/lua/vim/_meta/re.lua12
-rw-r--r--runtime/lua/vim/_meta/spell.lua6
-rw-r--r--runtime/lua/vim/_meta/vimfn.lua116
-rw-r--r--runtime/lua/vim/_meta/vvars.lua8
13 files changed, 296 insertions, 181 deletions
diff --git a/runtime/lua/vim/_meta/api.lua b/runtime/lua/vim/_meta/api.lua
index cb4c8749b8..6edf2a5a96 100644
--- a/runtime/lua/vim/_meta/api.lua
+++ b/runtime/lua/vim/_meta/api.lua
@@ -14,14 +14,21 @@ function vim.api.nvim__buf_debug_extmarks(buffer, keys, dot) end
--- @private
--- @param buffer integer
---- @param first integer
---- @param last integer
-function vim.api.nvim__buf_redraw_range(buffer, first, last) end
+--- @return table<string,any>
+function vim.api.nvim__buf_stats(buffer) end
--- @private
---- @param buffer integer
+--- EXPERIMENTAL: this API may change in the future.
+---
+--- Sets info for the completion item at the given index. If the info text was
+--- shown in a window, returns the window and buffer ids, or empty dict if not
+--- shown.
+---
+--- @param index integer Completion candidate index
+--- @param opts vim.api.keyset.complete_set Optional parameters.
+--- • info: (string) info text.
--- @return table<string,any>
-function vim.api.nvim__buf_stats(buffer) end
+function vim.api.nvim__complete_set(index, opts) end
--- @private
--- @return string
@@ -93,6 +100,32 @@ function vim.api.nvim__inspect_cell(grid, row, col) end
function vim.api.nvim__invalidate_glyph_cache() end
--- @private
+--- EXPERIMENTAL: this API may change in the future.
+---
+--- Instruct Nvim to redraw various components.
+---
+--- @param opts vim.api.keyset.redraw Optional parameters.
+--- • win: Target a specific `window-ID` as described below.
+--- • buf: Target a specific buffer number as described below.
+--- • flush: Update the screen with pending updates.
+--- • valid: When present mark `win`, `buf`, or all windows for
+--- redraw. When `true`, only redraw changed lines (useful for
+--- decoration providers). When `false`, forcefully redraw.
+--- • range: Redraw a range in `buf`, the buffer in `win` or the
+--- current buffer (useful for decoration providers). Expects a
+--- tuple `[first, last]` with the first and last line number of
+--- the range, 0-based end-exclusive `api-indexing`.
+--- • cursor: Immediately update cursor position on the screen in
+--- `win` or the current window.
+--- • statuscolumn: Redraw the 'statuscolumn' in `buf`, `win` or
+--- all windows.
+--- • statusline: Redraw the 'statusline' in `buf`, `win` or all
+--- windows.
+--- • winbar: Redraw the 'winbar' in `buf`, `win` or all windows.
+--- • tabline: Redraw the 'tabline'.
+function vim.api.nvim__redraw(opts) end
+
+--- @private
--- @return any[]
function vim.api.nvim__runtime_inspect() end
@@ -111,6 +144,36 @@ function vim.api.nvim__stats() end
--- @return any
function vim.api.nvim__unpack(str) end
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Scopes a namespace to the a window, so extmarks in the namespace will be
+--- active only in the given window.
+---
+--- @param window integer Window handle, or 0 for current window
+--- @param ns_id integer Namespace
+--- @return boolean
+function vim.api.nvim__win_add_ns(window, ns_id) end
+
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Unscopes a namespace (un-binds it from the given scope).
+---
+--- @param window integer Window handle, or 0 for current window
+--- @param ns_id integer the namespace to remove
+--- @return boolean
+function vim.api.nvim__win_del_ns(window, ns_id) end
+
+--- @private
+--- EXPERIMENTAL: this API will change in the future.
+---
+--- Gets the namespace scopes for a given window.
+---
+--- @param window integer Window handle, or 0 for current window
+--- @return integer[]
+function vim.api.nvim__win_get_ns(window) end
+
--- Adds a highlight to buffer.
---
--- Useful for plugins that dynamically generate highlights to a buffer (like
@@ -623,8 +686,8 @@ function vim.api.nvim_buf_line_count(buffer) end
--- • url: A URL to associate with this extmark. In the TUI, the
--- OSC 8 control sequence is used to generate a clickable
--- hyperlink to this URL.
---- • scoped: boolean that indicates that the extmark should only
---- be displayed in the namespace scope. (experimental)
+--- • scoped: boolean (EXPERIMENTAL) enables "scoping" for the
+--- extmark. See `nvim__win_add_ns()`
--- @return integer
function vim.api.nvim_buf_set_extmark(buffer, ns_id, line, col, opts) end
@@ -669,7 +732,7 @@ function vim.api.nvim_buf_set_lines(buffer, start, end_, strict_indexing, replac
--- @return boolean
function vim.api.nvim_buf_set_mark(buffer, name, line, col, opts) end
---- Sets the full file name for a buffer
+--- Sets the full file name for a buffer, like `:file_f`
---
--- @param buffer integer Buffer handle, or 0 for current buffer
--- @param name string Buffer name
@@ -822,16 +885,6 @@ function vim.api.nvim_command(command) end
--- @return string
function vim.api.nvim_command_output(command) end
---- Set info for the completion candidate index. if the info was shown in a
---- window, then the window and buffer ids are returned for further
---- customization. If the text was not shown, an empty dict is returned.
----
---- @param index integer the completion candidate index
---- @param opts vim.api.keyset.complete_set Optional parameters.
---- • info: (string) info text.
---- @return table<string,any>
-function vim.api.nvim_complete_set(index, opts) end
-
--- Create or get an autocommand group `autocmd-groups`.
---
--- To get an existing group id, do:
@@ -897,8 +950,8 @@ function vim.api.nvim_create_augroup(name, opts) end
--- • callback (function|string) optional: Lua function (or
--- Vimscript function name, if string) called when the event(s)
--- is triggered. Lua callback can return a truthy value (not
---- `false` or `nil`) to delete the autocommand. Receives a
---- table argument with these keys:
+--- `false` or `nil`) to delete the autocommand. Receives one
+--- argument, a table with these keys: *event-args*
--- • id: (number) autocommand id
--- • event: (string) name of the triggered event
--- `autocmd-events`
@@ -907,7 +960,7 @@ function vim.api.nvim_create_augroup(name, opts) end
--- • buf: (number) expanded value of <abuf>
--- • file: (string) expanded value of <afile>
--- • data: (any) arbitrary data passed from
---- `nvim_exec_autocmds()`
+--- `nvim_exec_autocmds()` *event-data*
--- • command (string) optional: Vim command to execute on event.
--- Cannot be used with {callback}
--- • once (boolean) optional: defaults to false. Run the
@@ -1718,9 +1771,8 @@ function vim.api.nvim_open_term(buffer, opts) end
--- • footer_pos: Footer position. Must be set with `footer`
--- option. Value can be one of "left", "center", or "right".
--- Default is `"left"`.
---- • noautocmd: If true then no buffer-related autocommand
---- events such as `BufEnter`, `BufLeave` or `BufWinEnter` may
---- fire from calling this function.
+--- • noautocmd: If true then all autocommands are blocked for
+--- the duration of the call.
--- • fixed: If true when anchor is NW or SW, the float window
--- would be kept fixed even if the window would be truncated.
--- • hide: If true the floating window will be hidden.
@@ -2092,13 +2144,6 @@ function vim.api.nvim_tabpage_set_var(tabpage, name, value) end
--- @param win integer Window handle, must already belong to {tabpage}
function vim.api.nvim_tabpage_set_win(tabpage, win) end
---- Adds the namespace scope to the window.
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer the namespace to add
---- @return boolean
-function vim.api.nvim_win_add_ns(window, ns_id) end
-
--- Calls a function with window as temporary current window.
---
--- @param window integer Window handle, or 0 for current window
@@ -2151,12 +2196,6 @@ function vim.api.nvim_win_get_cursor(window) end
--- @return integer
function vim.api.nvim_win_get_height(window) end
---- Gets all the namespaces scopes associated with a window.
----
---- @param window integer Window handle, or 0 for current window
---- @return integer[]
-function vim.api.nvim_win_get_ns(window) end
-
--- Gets the window number
---
--- @param window integer Window handle, or 0 for current window
@@ -2210,24 +2249,17 @@ function vim.api.nvim_win_hide(window) end
--- @return boolean
function vim.api.nvim_win_is_valid(window) end
---- Removes the namespace scope from the window.
----
---- @param window integer Window handle, or 0 for current window
---- @param ns_id integer the namespace to remove
---- @return boolean
-function vim.api.nvim_win_remove_ns(window, ns_id) end
-
--- Sets the current buffer in a window, without side effects
---
--- @param window integer Window handle, or 0 for current window
--- @param buffer integer Buffer handle
function vim.api.nvim_win_set_buf(window, buffer) end
---- Configures window layout. Currently only for floating and external windows
---- (including changing a split window to those layouts).
+--- Configures window layout. Cannot be used to move the last window in a
+--- tabpage to a different one.
---
---- When reconfiguring a floating window, absent option keys will not be
---- changed. `row`/`col` and `relative` must be reconfigured together.
+--- When reconfiguring a window, absent option keys will not be changed.
+--- `row`/`col` and `relative` must be reconfigured together.
---
--- @param window integer Window handle, or 0 for current window
--- @param config vim.api.keyset.win_config Map defining the window configuration, see `nvim_open_win()`
diff --git a/runtime/lua/vim/_meta/api_keysets.lua b/runtime/lua/vim/_meta/api_keysets.lua
index 37e4372196..f7cd92a3b2 100644
--- a/runtime/lua/vim/_meta/api_keysets.lua
+++ b/runtime/lua/vim/_meta/api_keysets.lua
@@ -207,6 +207,18 @@ error('Cannot require a meta file')
--- @field buf? integer
--- @field filetype? string
+--- @class vim.api.keyset.redraw
+--- @field flush? boolean
+--- @field cursor? boolean
+--- @field valid? boolean
+--- @field statuscolumn? boolean
+--- @field statusline? boolean
+--- @field tabline? boolean
+--- @field winbar? boolean
+--- @field range? any[]
+--- @field win? integer
+--- @field buf? integer
+
--- @class vim.api.keyset.runtime
--- @field is_lua? boolean
--- @field do_source? boolean
@@ -253,7 +265,6 @@ error('Cannot require a meta file')
--- @field undo_restore? boolean
--- @field url? string
--- @field scoped? boolean
---- @field _subpriority? integer
--- @class vim.api.keyset.user_command
--- @field addr? any
diff --git a/runtime/lua/vim/_meta/api_keysets_extra.lua b/runtime/lua/vim/_meta/api_keysets_extra.lua
index d61dd2c02f..76b56b04e7 100644
--- a/runtime/lua/vim/_meta/api_keysets_extra.lua
+++ b/runtime/lua/vim/_meta/api_keysets_extra.lua
@@ -124,7 +124,7 @@ error('Cannot require a meta file')
--- @field commalist boolean
--- @field flaglist boolean
--- @field was_set boolean
---- @field last_set_id integer
+--- @field last_set_sid integer
--- @field last_set_linenr integer
--- @field last_set_chan integer
--- @field type 'string'|'boolean'|'number'
diff --git a/runtime/lua/vim/_meta/base64.lua b/runtime/lua/vim/_meta/base64.lua
index f25b4af234..8ba59e1703 100644
--- a/runtime/lua/vim/_meta/base64.lua
+++ b/runtime/lua/vim/_meta/base64.lua
@@ -3,11 +3,11 @@
--- Encode {str} using Base64.
---
--- @param str string String to encode
---- @return string Encoded string
+--- @return string : Encoded string
function vim.base64.encode(str) end
--- Decode a Base64 encoded string.
---
--- @param str string Base64 encoded string
---- @return string Decoded string
+--- @return string : Decoded string
function vim.base64.decode(str) end
diff --git a/runtime/lua/vim/_meta/builtin.lua b/runtime/lua/vim/_meta/builtin.lua
index 9a67667f02..75737bd040 100644
--- a/runtime/lua/vim/_meta/builtin.lua
+++ b/runtime/lua/vim/_meta/builtin.lua
@@ -115,19 +115,19 @@ function vim.stricmp(a, b) end
--- Convert UTF-32 or UTF-16 {index} to byte index. If {use_utf16} is not
--- supplied, it defaults to false (use UTF-32). Returns the byte index.
---
---- Invalid UTF-8 and NUL is treated like by |vim.str_byteindex()|.
+--- Invalid UTF-8 and NUL is treated like in |vim.str_utfindex()|.
--- An {index} in the middle of a UTF-16 sequence is rounded upwards to
--- the end of that sequence.
--- @param str string
---- @param index number
---- @param use_utf16? any
+--- @param index integer
+--- @param use_utf16? boolean
function vim.str_byteindex(str, index, use_utf16) end
--- Gets a list of the starting byte positions of each UTF-8 codepoint in the given string.
---
--- Embedded NUL bytes are treated as terminating the string.
--- @param str string
---- @return table
+--- @return integer[]
function vim.str_utf_pos(str) end
--- Gets the distance (in bytes) from the starting byte of the codepoint (character) that {index}
@@ -148,8 +148,8 @@ function vim.str_utf_pos(str) end
--- ```
---
--- @param str string
---- @param index number
---- @return number
+--- @param index integer
+--- @return integer
function vim.str_utf_start(str, index) end
--- Gets the distance (in bytes) from the last byte of the codepoint (character) that {index} points
@@ -168,8 +168,8 @@ function vim.str_utf_start(str, index) end
--- ```
---
--- @param str string
---- @param index number
---- @return number
+--- @param index integer
+--- @return integer
function vim.str_utf_end(str, index) end
--- Convert byte index to UTF-32 and UTF-16 indices. If {index} is not
@@ -180,7 +180,7 @@ function vim.str_utf_end(str, index) end
--- {index} in the middle of a UTF-8 sequence is rounded upwards to the end of
--- that sequence.
--- @param str string
---- @param index? number
+--- @param index? integer
--- @return integer UTF-32 index
--- @return integer UTF-16 index
function vim.str_utfindex(str, index) end
@@ -193,15 +193,14 @@ function vim.str_utfindex(str, index) end
--- can accept, see ":Man 3 iconv".
---
--- @param str string Text to convert
---- @param from number Encoding of {str}
---- @param to number Target encoding
---- @param opts? table<string,any>
---- @return string|nil Converted string if conversion succeeds, `nil` otherwise.
+--- @param from string Encoding of {str}
+--- @param to string Target encoding
+--- @return string? : Converted string if conversion succeeds, `nil` otherwise.
function vim.iconv(str, from, to, opts) end
--- Schedules {fn} to be invoked soon by the main event-loop. Useful
--- to avoid |textlock| or other temporary restrictions.
---- @param fn function
+--- @param fn fun()
function vim.schedule(fn) end
--- Wait for {time} in milliseconds until {callback} returns `true`.
@@ -215,7 +214,6 @@ function vim.schedule(fn) end
--- Examples:
---
--- ```lua
----
--- ---
--- -- Wait for 100 ms, allowing other events to process
--- vim.wait(100, function() end)
diff --git a/runtime/lua/vim/_meta/builtin_types.lua b/runtime/lua/vim/_meta/builtin_types.lua
index 0bbc3e9bc8..9f0d2e7038 100644
--- a/runtime/lua/vim/_meta/builtin_types.lua
+++ b/runtime/lua/vim/_meta/builtin_types.lua
@@ -127,3 +127,11 @@
--- @field skipcol integer
--- @field topfill integer
--- @field topline integer
+
+--- @class vim.fn.getscriptinfo.ret
+--- @field autoload false
+--- @field functions? string[]
+--- @field name string
+--- @field sid string
+--- @field variables? table<string, any>
+--- @field version 1
diff --git a/runtime/lua/vim/_meta/diff.lua b/runtime/lua/vim/_meta/diff.lua
index f265139448..617bc87f59 100644
--- a/runtime/lua/vim/_meta/diff.lua
+++ b/runtime/lua/vim/_meta/diff.lua
@@ -1,5 +1,46 @@
---@meta
+--- Optional parameters:
+--- @class vim.diff.Opts
+--- @inlinedoc
+---
+--- Invoked for each hunk in the diff. Return a negative number
+--- to cancel the callback for any remaining hunks.
+--- Arguments:
+--- - `start_a` (`integer`): Start line of hunk in {a}.
+--- - `count_a` (`integer`): Hunk size in {a}.
+--- - `start_b` (`integer`): Start line of hunk in {b}.
+--- - `count_b` (`integer`): Hunk size in {b}.
+--- @field on_hunk fun(start_a: integer, count_a: integer, start_b: integer, count_b: integer): integer
+---
+--- Form of the returned diff:
+--- - `unified`: String in unified format.
+--- - `indices`: Array of hunk locations.
+--- Note: This option is ignored if `on_hunk` is used.
+--- (default: `'unified'`)
+--- @field result_type 'unified'|'indices'
+---
+--- Run linematch on the resulting hunks from xdiff. When integer, only hunks
+--- upto this size in lines are run through linematch.
+--- Requires `result_type = indices`, ignored otherwise.
+--- @field linematch boolean|integer
+---
+--- Diff algorithm to use. Values:
+--- - `myers`: the default algorithm
+--- - `minimal`: spend extra time to generate the smallest possible diff
+--- - `patience`: patience diff algorithm
+--- - `histogram`: histogram diff algorithm
+--- (default: `'myers'`)
+--- @field algorithm 'myers'|'minimal'|'patience'|'histogram'
+--- @field ctxlen integer Context length
+--- @field interhunkctxlen integer Inter hunk context length
+--- @field ignore_whitespace boolean Ignore whitespace
+--- @field ignore_whitespace_change boolean Ignore whitespace change
+--- @field ignore_whitespace_change_at_eol boolean Ignore whitespace change at end-of-line.
+--- @field ignore_cr_at_eol boolean Ignore carriage return at end-of-line
+--- @field ignore_blank_lines boolean Ignore blank lines
+--- @field indent_heuristic boolean Use the indent heuristic for the internal diff library.
+
-- luacheck: no unused args
--- Run diff on strings {a} and {b}. Any indices returned by this function,
@@ -24,47 +65,7 @@
---
---@param a string First string to compare
---@param b string Second string to compare
----@param opts table<string,any> Optional parameters:
---- - `on_hunk` (callback):
---- Invoked for each hunk in the diff. Return a negative number
---- to cancel the callback for any remaining hunks.
---- Args:
---- - `start_a` (integer): Start line of hunk in {a}.
---- - `count_a` (integer): Hunk size in {a}.
---- - `start_b` (integer): Start line of hunk in {b}.
---- - `count_b` (integer): Hunk size in {b}.
---- - `result_type` (string): Form of the returned diff:
---- - "unified": (default) String in unified format.
---- - "indices": Array of hunk locations.
---- Note: This option is ignored if `on_hunk` is used.
---- - `linematch` (boolean|integer): Run linematch on the resulting hunks
---- from xdiff. When integer, only hunks upto this size in
---- lines are run through linematch. Requires `result_type = indices`,
---- ignored otherwise.
---- - `algorithm` (string):
---- Diff algorithm to use. Values:
---- - "myers" the default algorithm
---- - "minimal" spend extra time to generate the
---- smallest possible diff
---- - "patience" patience diff algorithm
---- - "histogram" histogram diff algorithm
---- - `ctxlen` (integer): Context length
---- - `interhunkctxlen` (integer):
---- Inter hunk context length
---- - `ignore_whitespace` (boolean):
---- Ignore whitespace
---- - `ignore_whitespace_change` (boolean):
---- Ignore whitespace change
---- - `ignore_whitespace_change_at_eol` (boolean)
---- Ignore whitespace change at end-of-line.
---- - `ignore_cr_at_eol` (boolean)
---- Ignore carriage return at end-of-line
---- - `ignore_blank_lines` (boolean)
---- Ignore blank lines
---- - `indent_heuristic` (boolean):
---- Use the indent heuristic for the internal
---- diff library.
----
----@return string|table|nil
+---@param opts vim.diff.Opts
+---@return string|integer[][]?
--- See {opts.result_type}. `nil` if {opts.on_hunk} is given.
function vim.diff(a, b, opts) end
diff --git a/runtime/lua/vim/_meta/lpeg.lua b/runtime/lua/vim/_meta/lpeg.lua
index 1ce40f3340..73b3375c82 100644
--- a/runtime/lua/vim/_meta/lpeg.lua
+++ b/runtime/lua/vim/_meta/lpeg.lua
@@ -6,11 +6,10 @@ error('Cannot require a meta file')
-- with types being renamed to include the vim namespace and with some descriptions made less verbose.
--- @brief <pre>help
---- LPeg is a pattern-matching library for Lua, based on
---- Parsing Expression Grammars (https://bford.info/packrat/) (PEGs).
+--- LPeg is a pattern-matching library for Lua, based on Parsing Expression
+--- Grammars (PEGs). https://bford.info/packrat/
---
---- *lua-lpeg*
---- *vim.lpeg.Pattern*
+--- *lua-lpeg* *vim.lpeg.Pattern*
--- The LPeg library for parsing expression grammars is included as `vim.lpeg`
--- (https://www.inf.puc-rio.br/~roberto/lpeg/).
---
diff --git a/runtime/lua/vim/_meta/options.lua b/runtime/lua/vim/_meta/options.lua
index 757720d8fb..428b7c4d4f 100644
--- a/runtime/lua/vim/_meta/options.lua
+++ b/runtime/lua/vim/_meta/options.lua
@@ -11,10 +11,9 @@ vim.bo = vim.bo
---@field [integer] vim.wo
vim.wo = vim.wo
---- Allow CTRL-_ in Insert and Command-line mode. This is default off, to
---- avoid that users that accidentally type CTRL-_ instead of SHIFT-_ get
---- into reverse Insert mode, and don't know how to get out. See
---- 'revins'.
+--- Allow CTRL-_ in Insert mode. This is default off, to avoid that users
+--- that accidentally type CTRL-_ instead of SHIFT-_ get into reverse
+--- Insert mode, and don't know how to get out. See 'revins'.
---
--- @type boolean
vim.o.allowrevins = false
@@ -975,7 +974,7 @@ vim.bo.comments = vim.o.comments
vim.bo.com = vim.bo.comments
--- A template for a comment. The "%s" in the value is replaced with the
---- comment text. For example, C uses "/*%s*/". Currently only used to
+--- comment text. For example, C uses "/*%s*/". Used for `commenting` and to
--- add markers for folding, see `fold-marker`.
---
--- @type string
@@ -2626,6 +2625,8 @@ vim.go.gd = vim.go.gdefault
--- This is a scanf-like string that uses the same format as the
--- 'errorformat' option: see `errorformat`.
---
+--- If ripgrep ('grepprg') is available, this option defaults to `%f:%l:%c:%m`.
+---
--- @type string
vim.o.grepformat = "%f:%l:%m,%f:%l%m,%f %l%m"
vim.o.gfm = vim.o.grepformat
@@ -2637,12 +2638,6 @@ vim.go.gfm = vim.go.grepformat
--- line. The placeholder "$*" is allowed to specify where the arguments
--- will be included. Environment variables are expanded `:set_env`. See
--- `option-backslash` about including spaces and backslashes.
---- When your "grep" accepts the "-H" argument, use this to make ":grep"
---- also work well with a single file:
----
---- ```vim
---- set grepprg=grep\ -nH
---- ```
--- Special value: When 'grepprg' is set to "internal" the `:grep` command
--- works like `:vimgrep`, `:lgrep` like `:lvimgrep`, `:grepadd` like
--- `:vimgrepadd` and `:lgrepadd` like `:lvimgrepadd`.
@@ -2650,9 +2645,19 @@ vim.go.gfm = vim.go.grepformat
--- apply equally to 'grepprg'.
--- This option cannot be set from a `modeline` or in the `sandbox`, for
--- security reasons.
----
---- @type string
-vim.o.grepprg = "grep -n $* /dev/null"
+--- This option defaults to:
+--- - `rg --vimgrep -uu ` if ripgrep is available (`:checkhealth`),
+--- - `grep -HIn $* /dev/null` on Unix,
+--- - `findstr /n $* nul` on Windows.
+--- Ripgrep can perform additional filtering such as using .gitignore rules
+--- and skipping hidden files. This is disabled by default (see the -u option)
+--- to more closely match the behaviour of standard grep.
+--- You can make ripgrep match Vim's case handling using the
+--- -i/--ignore-case and -S/--smart-case options.
+--- An `OptionSet` autocmd can be used to set it up to match automatically.
+---
+--- @type string
+vim.o.grepprg = "grep -HIn $* /dev/null"
vim.o.gp = vim.o.grepprg
vim.bo.grepprg = vim.o.grepprg
vim.bo.gp = vim.bo.grepprg
@@ -5195,9 +5200,6 @@ vim.wo.scr = vim.wo.scroll
--- Minimum is 1, maximum is 100000.
--- Only in `terminal` buffers.
---
---- Note: Lines that are not visible and kept in scrollback are not
---- reflown when the terminal buffer is resized horizontally.
----
--- @type integer
vim.o.scrollback = -1
vim.o.scbk = vim.o.scrollback
@@ -6079,8 +6081,7 @@ vim.go.sta = vim.go.smarttab
--- highlighted with `hl-NonText`.
--- You may also want to add "lastline" to the 'display' option to show as
--- much of the last line as possible.
---- NOTE: only partly implemented, currently works with CTRL-E, CTRL-Y
---- and scrolling with the mouse.
+--- NOTE: partly implemented, doesn't work yet for `gj` and `gk`.
---
--- @type boolean
vim.o.smoothscroll = false
@@ -6746,6 +6747,8 @@ vim.bo.swf = vim.bo.swapfile
--- "split" when both are present.
--- uselast If included, jump to the previously used window when
--- jumping to errors with `quickfix` commands.
+--- If a window has 'winfixbuf' enabled, 'switchbuf' is currently not
+--- applied to the split window.
---
--- @type string
vim.o.switchbuf = "uselast"
@@ -6847,7 +6850,7 @@ vim.go.tpm = vim.go.tabpagemax
--- appear wrong in many places.
--- The value must be more than 0 and less than 10000.
---
---- There are four main ways to use tabs in Vim:
+--- There are five main ways to use tabs in Vim:
--- 1. Always keep 'tabstop' at 8, set 'softtabstop' and 'shiftwidth' to 4
--- (or 3 or whatever you prefer) and use 'noexpandtab'. Then Vim
--- will use a mix of tabs and spaces, but typing <Tab> and <BS> will
@@ -7443,6 +7446,7 @@ vim.bo.vts = vim.bo.vartabstop
---
--- Level Messages ~
--- ----------------------------------------------------------------------
+--- 1 Enables Lua tracing (see above). Does not produce messages.
--- 2 When a file is ":source"'ed, or `shada` file is read or written.
--- 3 UI info, terminal capabilities.
--- 4 Shell commands.
@@ -7863,8 +7867,8 @@ vim.wo.winbl = vim.wo.winblend
--- will scroll 'window' minus two lines, with a minimum of one.
--- When 'window' is equal to 'lines' minus one CTRL-F and CTRL-B scroll
--- in a much smarter way, taking care of wrapping lines.
---- When resizing the Vim window, the value is smaller than 1 or more than
---- or equal to 'lines' it will be set to 'lines' minus 1.
+--- When resizing the Vim window, and the value is smaller than 1 or more
+--- than or equal to 'lines' it will be set to 'lines' minus 1.
--- Note: Do not confuse this with the height of the Vim window, use
--- 'lines' for that.
---
@@ -7874,6 +7878,18 @@ vim.o.wi = vim.o.window
vim.go.window = vim.o.window
vim.go.wi = vim.go.window
+--- If enabled, the window and the buffer it is displaying are paired.
+--- For example, attempting to change the buffer with `:edit` will fail.
+--- Other commands which change a window's buffer such as `:cnext` will
+--- also skip any window with 'winfixbuf' enabled. However if an Ex
+--- command has a "!" modifier, it can force switching buffers.
+---
+--- @type boolean
+vim.o.winfixbuf = false
+vim.o.wfb = vim.o.winfixbuf
+vim.wo.winfixbuf = vim.o.winfixbuf
+vim.wo.wfb = vim.wo.winfixbuf
+
--- Keep the window height when windows are opened or closed and
--- 'equalalways' is set. Also for `CTRL-W_=`. Set by default for the
--- `preview-window` and `quickfix-window`.
diff --git a/runtime/lua/vim/_meta/re.lua b/runtime/lua/vim/_meta/re.lua
index 14c94c7824..d16751fbbf 100644
--- a/runtime/lua/vim/_meta/re.lua
+++ b/runtime/lua/vim/_meta/re.lua
@@ -8,11 +8,11 @@ error('Cannot require a meta file')
-- See 'lpeg.html' for license
--- @brief
---- The `vim.re` module provides a conventional regex-like syntax for pattern usage
---- within LPeg |vim.lpeg|.
+--- The `vim.re` module provides a conventional regex-like syntax for pattern usage within LPeg
+--- |vim.lpeg|. (Unrelated to |vim.regex| which provides Vim |regexp| from Lua.)
---
---- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original
---- documentation including regex syntax and more concrete examples.
+--- See https://www.inf.puc-rio.br/~roberto/lpeg/re.html for the original documentation including
+--- regex syntax and examples.
--- Compiles the given {string} and returns an equivalent LPeg pattern. The given string may define
--- either an expression or a grammar. The optional {defs} table provides extra Lua values to be used
@@ -30,8 +30,8 @@ function vim.re.compile(string, defs) end
--- @param subject string
--- @param pattern vim.lpeg.Pattern|string
--- @param init? integer
---- @return integer|nil the index where the occurrence starts, nil if no match
---- @return integer|nil the index where the occurrence ends, nil if no match
+--- @return integer|nil : the index where the occurrence starts, nil if no match
+--- @return integer|nil : the index where the occurrence ends, nil if no match
function vim.re.find(subject, pattern, init) end
--- Does a global substitution, replacing all occurrences of {pattern} in the given {subject} by
diff --git a/runtime/lua/vim/_meta/spell.lua b/runtime/lua/vim/_meta/spell.lua
index 57f2180895..c636db3b53 100644
--- a/runtime/lua/vim/_meta/spell.lua
+++ b/runtime/lua/vim/_meta/spell.lua
@@ -3,11 +3,11 @@
-- luacheck: no unused args
--- Check {str} for spelling errors. Similar to the Vimscript function
---- |spellbadword()|.
+--- [spellbadword()].
---
--- Note: The behaviour of this function is dependent on: 'spelllang',
--- 'spellfile', 'spellcapcheck' and 'spelloptions' which can all be local to
---- the buffer. Consider calling this with |nvim_buf_call()|.
+--- the buffer. Consider calling this with [nvim_buf_call()].
---
--- Example:
---
@@ -20,7 +20,7 @@
--- ```
---
--- @param str string
---- @return {[1]: string, [2]: string, [3]: string}[]
+--- @return {[1]: string, [2]: 'bad'|'rare'|'local'|'caps', [3]: integer}[]
--- List of tuples with three items:
--- - The badly spelled word.
--- - The type of the spelling error:
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
index ac25547212..f4daacfb7d 100644
--- a/runtime/lua/vim/_meta/vimfn.lua
+++ b/runtime/lua/vim/_meta/vimfn.lua
@@ -1598,11 +1598,10 @@ function vim.fn.eventhandler() end
--- The result is a Number:
--- 1 exists
--- 0 does not exist
---- -1 not implemented on this system
--- |exepath()| can be used to get the full path of an executable.
---
--- @param expr any
---- @return 0|1|-1
+--- @return 0|1
function vim.fn.executable(expr) end
--- Execute {command} and capture its output.
@@ -1959,6 +1958,7 @@ function vim.fn.extendnew(expr1, expr2, expr3) end
--- 't' Handle keys as if typed; otherwise they are handled as
--- if coming from a mapping. This matters for undo,
--- opening folds, etc.
+--- 'L' Lowlevel input. Other flags are not used.
--- 'i' Insert the string instead of appending (see above).
--- 'x' Execute commands until typeahead is empty. This is
--- similar to using ":normal!". You can call feedkeys()
@@ -2703,14 +2703,14 @@ function vim.fn.getcellwidths() end
function vim.fn.getchangelist(buf) end
--- Get a single character from the user or input stream.
---- If [expr] is omitted, wait until a character is available.
---- If [expr] is 0, only get a character when one is available.
+--- If {expr} is omitted, wait until a character is available.
+--- If {expr} is 0, only get a character when one is available.
--- Return zero otherwise.
---- If [expr] is 1, only check if a character is available, it is
+--- If {expr} is 1, only check if a character is available, it is
--- not consumed. Return zero if no character available.
--- If you prefer always getting a string use |getcharstr()|.
---
---- Without [expr] and when [expr] is 0 a whole character or
+--- Without {expr} and when {expr} is 0 a whole character or
--- special key is returned. If it is a single character, the
--- result is a Number. Use |nr2char()| to convert it to a String.
--- Otherwise a String is returned with the encoded character.
@@ -2720,11 +2720,11 @@ function vim.fn.getchangelist(buf) end
--- also a String when a modifier (shift, control, alt) was used
--- that is not included in the character.
---
---- When [expr] is 0 and Esc is typed, there will be a short delay
+--- When {expr} is 0 and Esc is typed, there will be a short delay
--- while Vim waits to see if this is the start of an escape
--- sequence.
---
---- When [expr] is 1 only the first byte is returned. For a
+--- When {expr} is 1 only the first byte is returned. For a
--- one-byte character it is the character itself as a number.
--- Use nr2char() to convert it to a String.
---
@@ -2828,10 +2828,10 @@ function vim.fn.getcharsearch() end
--- Get a single character from the user or input stream as a
--- string.
---- If [expr] is omitted, wait until a character is available.
---- If [expr] is 0 or false, only get a character when one is
+--- If {expr} is omitted, wait until a character is available.
+--- If {expr} is 0 or false, only get a character when one is
--- available. Return an empty string otherwise.
---- If [expr] is 1 or true, only check if a character is
+--- If {expr} is 1 or true, only check if a character is
--- available, it is not consumed. Return an empty string
--- if no character is available.
--- Otherwise this works like |getchar()|, except that a number
@@ -3581,6 +3581,43 @@ function vim.fn.getreginfo(regname) end
--- @return string[]
function vim.fn.getregion(pos1, pos2, opts) end
+--- Same as |getregion()|, but returns a list of positions
+--- describing the buffer text segments bound by {pos1} and
+--- {pos2}.
+--- The segments are a pair of positions for every line: >
+--- [[{start_pos}, {end_pos}], ...]
+--- <
+--- The position is a |List| with four numbers:
+--- [bufnum, lnum, col, off]
+--- "bufnum" is the buffer number.
+--- "lnum" and "col" are the position in the buffer. The first
+--- column is 1.
+--- If the "off" number of a starting position is non-zero, it is
+--- the offset in screen columns from the start of the character.
+--- E.g., a position within a <Tab> or after the last character.
+--- If the "off" number of an ending position is non-zero, it is
+--- the offset of the character's first cell not included in the
+--- selection, otherwise all its cells are included.
+---
+--- Apart from the options supported by |getregion()|, {opts} also
+--- supports the following:
+---
+--- eol If |TRUE|, indicate positions beyond
+--- the end of a line with "col" values
+--- one more than the length of the line.
+--- If |FALSE|, positions are limited
+--- within their lines, and if a line is
+--- empty or the selection is entirely
+--- beyond the end of a line, a "col"
+--- value of 0 is used for both positions.
+--- (default: |FALSE|)
+---
+--- @param pos1 table
+--- @param pos2 table
+--- @param opts? table
+--- @return integer[][][]
+function vim.fn.getregionpos(pos1, pos2, opts) end
+
--- The result is a String, which is type of register {regname}.
--- The value will be one of:
--- "v" for |charwise| text
@@ -3628,11 +3665,11 @@ function vim.fn.getregtype(regname) end
---
--- Examples: >vim
--- echo getscriptinfo({'name': 'myscript'})
---- echo getscriptinfo({'sid': 15}).variables
+--- echo getscriptinfo({'sid': 15})[0].variables
--- <
---
--- @param opts? table
---- @return any
+--- @return vim.fn.getscriptinfo.ret[]
function vim.fn.getscriptinfo(opts) end
--- If {tabnr} is not specified, then information about all the
@@ -5993,7 +6030,7 @@ function vim.fn.min(expr) end
function vim.fn.mkdir(name, flags, prot) end
--- Return a string that indicates the current mode.
---- If [expr] is supplied and it evaluates to a non-zero Number or
+--- If {expr} is supplied and it evaluates to a non-zero Number or
--- a non-empty String (|non-zero-arg|), then the full mode is
--- returned, otherwise only the first letter is returned.
--- Also see |state()|.
@@ -6520,6 +6557,9 @@ function vim.fn.prevnonblank(lnum) end
--- echo printf("%1$*2$.*3$f", 1.4142135, 6, 2)
--- < 1.41
---
+--- You will get an overflow error |E1510|, when the field-width
+--- or precision will result in a string longer than 6400 chars.
+---
--- *E1500*
--- You cannot mix positional and non-positional arguments: >vim
--- echo printf("%s%1$s", "One", "Two")
@@ -6580,7 +6620,7 @@ function vim.fn.prevnonblank(lnum) end
---
--- @param fmt any
--- @param expr1? any
---- @return any
+--- @return string
function vim.fn.printf(fmt, expr1) end
--- Returns the effective prompt text for buffer {buf}. {buf} can
@@ -7259,6 +7299,7 @@ function vim.fn.screenstring(row, col) end
--- When a match has been found its line number is returned.
--- If there is no match a 0 is returned and the cursor doesn't
--- move. No error message is given.
+--- To get the matched string, use |matchbufline()|.
---
--- {flags} is a String, which can contain these character flags:
--- 'b' search Backward instead of forward
@@ -8289,10 +8330,11 @@ function vim.fn.sha256(string) end
--- Otherwise encloses {string} in single-quotes and replaces all
--- "'" with "'\''".
---
---- If {special} is a |non-zero-arg|:
---- - Special items such as "!", "%", "#" and "<cword>" will be
---- preceded by a backslash. The backslash will be removed again
---- by the |:!| command.
+--- The {special} argument adds additional escaping of keywords
+--- used in Vim commands. If it is a |non-zero-arg|:
+--- - Special items such as "!", "%", "#" and "<cword>" (as listed
+--- in |expand()|) will be preceded by a backslash.
+--- The backslash will be removed again by the |:!| command.
--- - The <NL> character is escaped.
---
--- If 'shell' contains "csh" in the tail:
@@ -8796,7 +8838,8 @@ function vim.fn.sinh(expr) end
--- Similar to using a |slice| "expr[start : end]", but "end" is
--- used exclusive. And for a string the indexes are used as
--- character indexes instead of byte indexes.
---- Also, composing characters are not counted.
+--- Also, composing characters are treated as a part of the
+--- preceding base character.
--- When {end} is omitted the slice continues to the last item.
--- When {end} is -1 the last item is omitted.
--- Returns an empty value if {start} or {end} are invalid.
@@ -9204,8 +9247,8 @@ function vim.fn.strcharlen(string) end
--- of byte index and length.
--- When {skipcc} is omitted or zero, composing characters are
--- counted separately.
---- When {skipcc} set to 1, Composing characters are ignored,
---- similar to |slice()|.
+--- When {skipcc} set to 1, composing characters are treated as a
+--- part of the preceding base character, similar to |slice()|.
--- When a character index is used where a character does not
--- exist it is omitted and counted as one character. For
--- example: >vim
@@ -9225,7 +9268,7 @@ function vim.fn.strcharpart(src, start, len, skipcc) end
--- in String {string}.
--- When {skipcc} is omitted or zero, composing characters are
--- counted separately.
---- When {skipcc} set to 1, Composing characters are ignored.
+--- When {skipcc} set to 1, composing characters are ignored.
--- |strcharlen()| always does this.
---
--- Returns zero on error.
@@ -9348,10 +9391,10 @@ function vim.fn.stridx(haystack, needle, start) end
--- for infinite and NaN floating-point values representations
--- which use |str2float()|. Strings are also dumped literally,
--- only single quote is escaped, which does not allow using YAML
---- for parsing back binary strings. |eval()| should always work for
---- strings and floats though and this is the only official
---- method, use |msgpackdump()| or |json_encode()| if you need to
---- share data with other application.
+--- for parsing back binary strings. |eval()| should always work
+--- for strings and floats though, and this is the only official
+--- method. Use |msgpackdump()| or |json_encode()| if you need to
+--- share data with other applications.
---
--- @param expr any
--- @return string
@@ -9747,6 +9790,10 @@ function vim.fn.synIDtrans(synID) end
--- synconcealed(lnum, 5) [1, 'X', 2]
--- synconcealed(lnum, 6) [0, '', 0]
---
+--- Note: Doesn't consider |matchadd()| highlighting items,
+--- since syntax and matching highlighting are two different
+--- mechanisms |syntax-vs-match|.
+---
--- @param lnum integer
--- @param col integer
--- @return {[1]: integer, [2]: string, [3]: integer}
@@ -10591,17 +10638,16 @@ function vim.fn.win_move_statusline(nr, offset) end
--- [1, 1], unless there is a tabline, then it is [2, 1].
--- {nr} can be the window number or the |window-ID|. Use zero
--- for the current window.
---- Returns [0, 0] if the window cannot be found in the current
---- tabpage.
+--- Returns [0, 0] if the window cannot be found.
---
--- @param nr integer
--- @return any
function vim.fn.win_screenpos(nr) end
---- Move the window {nr} to a new split of the window {target}.
---- This is similar to moving to {target}, creating a new window
---- using |:split| but having the same contents as window {nr}, and
---- then closing {nr}.
+--- Temporarily switch to window {target}, then move window {nr}
+--- to a new split adjacent to {target}.
+--- Unlike commands such as |:split|, no new windows are created
+--- (the |window-ID| of window {nr} is unchanged after the move).
---
--- Both {nr} and {target} can be window numbers or |window-ID|s.
--- Both must be in the current tab page.
@@ -10724,7 +10770,9 @@ function vim.fn.winline() end
--- # the number of the last accessed window (where
--- |CTRL-W_p| goes to). If there is no previous
--- window or it is in another tab page 0 is
---- returned.
+--- returned. May refer to the current window in
+--- some cases (e.g. when evaluating 'statusline'
+--- expressions).
--- {N}j the number of the Nth window below the
--- current window (where |CTRL-W_j| goes to).
--- {N}k the number of the Nth window above the current
diff --git a/runtime/lua/vim/_meta/vvars.lua b/runtime/lua/vim/_meta/vvars.lua
index ee6d8ddf35..e00402ab3f 100644
--- a/runtime/lua/vim/_meta/vvars.lua
+++ b/runtime/lua/vim/_meta/vvars.lua
@@ -54,9 +54,10 @@ vim.v.cmdbang = ...
--- @type string
vim.v.collate = ...
---- Dictionary containing the most recent `complete-items` after
---- `CompleteDone`. Empty if the completion failed, or after
---- leaving and re-entering insert mode.
+--- Dictionary containing the `complete-items` for the most
+--- recently completed word after `CompleteDone`. Empty if the
+--- completion failed, or after leaving and re-entering insert
+--- mode.
--- Note: Plugins can modify the value to emulate the builtin
--- `CompleteDone` event behavior.
--- @type any
@@ -194,6 +195,7 @@ vim.v.errors = ...
--- changed_window Is `v:true` if the event fired while
--- changing window (or tab) on `DirChanged`.
--- status Job status or exit code, -1 means "unknown". `TermClose`
+--- reason Reason for completion being done. `CompleteDone`
--- @type any
vim.v.event = ...