Merge remote-tracking branch 'upstream/master' into mix_20240309

1 files changed, 82 insertions, 34 deletions

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