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

67 files changed, 5741 insertions, 1360 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 2aa147770d..dee0324a5b 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -42,9 +42,9 @@ The RPC API is like a more powerful version of Vim's "clientserver" feature.
 CONNECTING                                              *rpc-connecting*
 
 See |channel-intro| for various ways to open a channel. Channel-opening
-functions take an `rpc` key in the options dictionary. RPC channels can also
-be opened by other processes connecting to TCP/IP sockets or named pipes
-listened to by Nvim.
+functions take an `rpc` key in the options dict. RPC channels can also be
+opened by other processes connecting to TCP/IP sockets or named pipes listened
+to by Nvim.
 
 Nvim creates a default RPC socket at |startup|, given by |v:servername|. To
 start with a TCP/IP socket instead, use |--listen| with a TCP-style address: >
@@ -108,9 +108,9 @@ Basic types ~
   Integer (signed 64-bit integer)       int64_t
   Float (IEEE 754 double precision)     double
   String                                {char* data, size_t size} struct
-  Array
-  Dictionary (msgpack: map)
-  Object
+  Array                                 kvec
+  Dict (msgpack: map)                   kvec
+  Object                                any of the above
 <
   Note:
     - Empty Array is accepted as a valid Dictionary parameter.
@@ -708,12 +708,12 @@ nvim_eval_statusline({str}, {opts})                   *nvim_eval_statusline()*
                   line number instead of statusline.
 
     Return: ~
-        Dictionary containing statusline information, with these keys:
+        Dict containing statusline information, with these keys:
         • str: (string) Characters that will be displayed on the statusline.
         • width: (number) Display width of the statusline.
         • highlights: Array containing highlight information of the
           statusline. Only included when the "highlights" key in {opts} is
-          true. Each element of the array is a |Dictionary| with these keys:
+          true. Each element of the array is a |Dict| with these keys:
           • start: (number) Byte index (0-based) of first character that uses
             the highlight.
           • group: (string) Name of highlight group.
@@ -763,7 +763,7 @@ nvim_feedkeys({keys}, {mode}, {escape_ks})                   *nvim_feedkeys()*
 
 nvim_get_api_info()                                      *nvim_get_api_info()*
     Returns a 2-tuple (Array), where item 0 is the current channel id and item
-    1 is the |api-metadata| map (Dictionary).
+    1 is the |api-metadata| map (Dict).
 
     Attributes: ~
         |api-fast|
@@ -779,7 +779,7 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
       • {chan}  channel_id, or 0 for current channel
 
     Return: ~
-        Dictionary describing a channel, with these keys:
+        Channel info dict with these keys:
         • "id" Channel id.
         • "argv" (optional) Job arguments list.
         • "stream" Stream underlying the channel.
@@ -792,11 +792,11 @@ nvim_get_chan_info({chan})                              *nvim_get_chan_info()*
           • "terminal" |terminal| instance interprets ASCII sequences.
           • "rpc" |RPC| communication on the channel is active.
         • "pty" (optional) Name of pseudoterminal. On a POSIX system this is a
-          device path like "/dev/pts/1". If the name is unknown, the key will
-          still be present if a pty is used (e.g. for conpty on Windows).
-        • "buffer" (optional) Buffer with connected |terminal| instance.
+          device path like "/dev/pts/1". If unknown, the key will still be
+          present if a pty is used (e.g. for conpty on Windows).
+        • "buffer" (optional) Buffer connected to |terminal| instance.
         • "client" (optional) Info about the peer (client on the other end of
-          the RPC channel), if provided by it via |nvim_set_client_info()|.
+          the RPC channel), which it provided via |nvim_set_client_info()|.
 
 nvim_get_color_by_name({name})                      *nvim_get_color_by_name()*
     Returns the 24-bit RGB value of a |nvim_get_color_map()| color name or
@@ -939,7 +939,7 @@ nvim_get_mode()                                              *nvim_get_mode()*
         |api-fast|
 
     Return: ~
-        Dictionary { "mode": String, "blocking": Boolean }
+        Dict { "mode": String, "blocking": Boolean }
 
 nvim_get_proc({pid})                                         *nvim_get_proc()*
     Gets info describing process `pid`.
@@ -954,11 +954,11 @@ nvim_get_proc_children({pid})                       *nvim_get_proc_children()*
         Array of child process ids, empty if process not found.
 
 nvim_get_runtime_file({name}, {all})                 *nvim_get_runtime_file()*
-    Find files in runtime directories
+    Finds files in runtime directories, in 'runtimepath' order.
 
     "name" can contain wildcards. For example
-    nvim_get_runtime_file("colors/*.vim", true) will return all color scheme
-    files. Always use forward slashes (/) in the search pattern for
+    `nvim_get_runtime_file("colors/*.{vim,lua}", true)` will return all color
+    scheme files. Always use forward slashes (/) in the search pattern for
     subdirectories regardless of platform.
 
     It is not an error to not find any files. An empty array is returned then.
@@ -996,6 +996,9 @@ nvim_input({keys})                                              *nvim_input()*
     input buffer and the call is non-blocking (input is processed
     asynchronously by the eventloop).
 
+    To input blocks of text, |nvim_paste()| is much faster and should be
+    preferred.
+
     On execution error: does not fail, but updates v:errmsg.
 
     Note: ~
@@ -1148,21 +1151,35 @@ nvim_out_write({str})                                       *nvim_out_write()*
       • {str}  Message
 
 nvim_paste({data}, {crlf}, {phase})                             *nvim_paste()*
-    Pastes at cursor, in any mode.
+    Pastes at cursor (in any mode), and sets "redo" so dot (|.|) will repeat
+    the input. UIs call this to implement "paste", but it's also intended for
+    use by scripts to input large, dot-repeatable blocks of text (as opposed
+    to |nvim_input()| which is subject to mappings/events and is thus much
+    slower).
 
-    Invokes the `vim.paste` handler, which handles each mode appropriately.
-    Sets redo/undo. Faster than |nvim_input()|. Lines break at LF ("\n").
+    Invokes the |vim.paste()| handler, which handles each mode appropriately.
 
     Errors ('nomodifiable', `vim.paste()` failure, …) are reflected in `err`
     but do not affect the return value (which is strictly decided by
-    `vim.paste()`). On error, subsequent calls are ignored ("drained") until
-    the next paste is initiated (phase 1 or -1).
+    `vim.paste()`). On error or cancel, subsequent calls are ignored
+    ("drained") until the next paste is initiated (phase 1 or -1).
+
+    Useful in mappings and scripts to insert multiline text. Example: >lua
+        vim.keymap.set('n', 'x', function()
+          vim.api.nvim_paste([[
+            line1
+            line2
+            line3
+          ]], false, -1)
+        end, { buffer = true })
+<
 
     Attributes: ~
         not allowed when |textlock| is active
 
     Parameters: ~
-      • {data}   Multiline input. May be binary (containing NUL bytes).
+      • {data}   Multiline input. Lines break at LF ("\n"). May be binary
+                 (containing NUL bytes).
       • {crlf}   Also break lines at CR and CRLF.
       • {phase}  -1: paste in a single call (i.e. without streaming). To
                  "stream" a paste, call `nvim_paste` sequentially with these
@@ -1173,10 +1190,11 @@ nvim_paste({data}, {crlf}, {phase})                             *nvim_paste()*
 
     Return: ~
         • true: Client may continue pasting.
-        • false: Client must cancel the paste.
+        • false: Client should cancel the paste.
 
 nvim_put({lines}, {type}, {after}, {follow})                      *nvim_put()*
-    Puts text at cursor, in any mode.
+    Puts text at cursor, in any mode. For dot-repeatable input, use
+    |nvim_paste()|.
 
     Compare |:put| and |p| which are always linewise.
 
@@ -1249,8 +1267,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
 
     Parameters: ~
       • {name}        Short name for the connected client
-      • {version}     Dictionary describing the version, with these (optional)
-                      keys:
+      • {version}     Dict describing the version, with these (optional) keys:
                       • "major" major version (defaults to 0 if not set, for
                         no release yet)
                       • "minor" minor version
@@ -1285,6 +1302,7 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
                         inclusive.
       • {attributes}  Arbitrary string:string map of informal client
                       properties. Suggested keys:
+                      • "pid": Process id.
                       • "website": Client homepage URL (e.g. GitHub
                         repository)
                       • "license": License description ("Apache 2", "GPLv3",
@@ -1474,7 +1492,7 @@ nvim__complete_set({index}, {opts})                     *nvim__complete_set()*
                  • info: (string) info text.
 
     Return: ~
-        Dictionary containing these keys:
+        Dict containing these keys:
         • winid: (number) floating window id
         • bufnr: (number) buffer id in floating window
 
@@ -1516,14 +1534,14 @@ nvim__id_array({arr})                                       *nvim__id_array()*
     Return: ~
         its argument.
 
-nvim__id_dictionary({dct})                             *nvim__id_dictionary()*
-    Returns dictionary given as argument.
+nvim__id_dict({dct})                                         *nvim__id_dict()*
+    Returns dict given as argument.
 
     This API function is used for testing. One should not rely on its presence
     in plugins.
 
     Parameters: ~
-      • {dct}  Dictionary to return.
+      • {dct}  Dict to return.
 
     Return: ~
         its argument.
@@ -1594,7 +1612,7 @@ nvim_call_dict_function({dict}, {fn}, {args})
     On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {dict}  Dictionary, or String evaluating to a Vimscript |self| dict
+      • {dict}  Dict, or String evaluating to a Vimscript |self| dict
       • {fn}    Name of the function defined on the Vimscript dict
       • {args}  Function arguments packed in an Array
 
@@ -1628,7 +1646,7 @@ nvim_command({command})                                       *nvim_command()*
       • {command}  Ex command string
 
 nvim_eval({expr})                                                *nvim_eval()*
-    Evaluates a Vimscript |expression|. Dictionaries and Lists are recursively
+    Evaluates a Vimscript |expression|. Dicts and Lists are recursively
     expanded.
 
     On execution error: fails with Vimscript error, updates v:errmsg.
@@ -1655,7 +1673,7 @@ nvim_exec2({src}, {opts})                                       *nvim_exec2()*
                   return all (non-error, non-shell |:!|) output.
 
     Return: ~
-        Dictionary containing information about execution, with these keys:
+        Dict containing information about execution, with these keys:
         • output: (string|nil) Output if `opts.output` is true.
 
     See also: ~
@@ -1692,9 +1710,9 @@ nvim_parse_expression({expr}, {flags}, {highlight})
                      region [start_col, end_col)).
 
     Return: ~
-        • AST: top-level dictionary with these keys:
-          • "error": Dictionary with error, present only if parser saw some
-            error. Contains the following keys:
+        • AST: top-level dict with these keys:
+          • "error": Dict with error, present only if parser saw some error.
+            Contains the following keys:
             • "message": String, error message in printf format, translated.
               Must contain exactly one "%.*s".
             • "arg": String, error message argument.
@@ -1702,7 +1720,7 @@ nvim_parse_expression({expr}, {flags}, {highlight})
             that should be equal to the length of expr string. ("Successfully
             parsed" here means "participated in AST creation", not "till the
             first error".)
-          • "ast": AST, either nil or a dictionary with these keys:
+          • "ast": AST, either nil or a dict with these keys:
             • "type": node type, one of the value names from ExprASTNodeType
               stringified without "kExprNode" prefix.
             • "start": a pair `[line, column]` describing where node is
@@ -1778,8 +1796,8 @@ nvim_buf_get_commands({buffer}, {opts})              *nvim_buf_get_commands()*
 nvim_cmd({cmd}, {opts})                                           *nvim_cmd()*
     Executes an Ex command.
 
-    Unlike |nvim_command()| this command takes a structured Dictionary instead
-    of a String. This allows for easier construction and manipulation of an Ex
+    Unlike |nvim_command()| this command takes a structured Dict instead of a
+    String. This allows for easier construction and manipulation of an Ex
     command. This also allows for things such as having spaces inside a
     command argument, expanding filenames in a command that otherwise doesn't
     expand filenames, etc. Command arguments may also be Number, Boolean or
@@ -1793,8 +1811,8 @@ nvim_cmd({cmd}, {opts})                                           *nvim_cmd()*
     On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {cmd}   Command to execute. Must be a Dictionary that can contain the
-                same values as the return value of |nvim_parse_cmd()| except
+      • {cmd}   Command to execute. Must be a Dict that can contain the same
+                values as the return value of |nvim_parse_cmd()| except
                 "addr", "nargs" and "nextcmd" which are ignored if provided.
                 All values except for "cmd" are optional.
       • {opts}  Optional parameters.
@@ -1896,7 +1914,7 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
       • {opts}  Optional parameters. Reserved for future use.
 
     Return: ~
-        Dictionary containing command information, with these keys:
+        Dict containing command information, with these keys:
         • cmd: (string) Command name.
         • range: (array) (optional) Command range (<line1> <line2>). Omitted
           if command doesn't accept a range. Otherwise, has no elements if no
@@ -1913,15 +1931,15 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
         • nargs: (string) Value of |:command-nargs|.
         • nextcmd: (string) Next command if there are multiple commands
           separated by a |:bar|. Empty if there isn't a next command.
-        • magic: (dictionary) Which characters have special meaning in the
-          command arguments.
+        • magic: (dict) Which characters have special meaning in the command
+          arguments.
           • file: (boolean) The command expands filenames. Which means
             characters such as "%", "#" and wildcards are expanded.
           • bar: (boolean) The "|" character is treated as a command separator
             and the double quote character (") is treated as the start of a
             comment.
-        • mods: (dictionary) |:command-modifiers|.
-          • filter: (dictionary) |:filter|.
+        • mods: (dict) |:command-modifiers|.
+          • filter: (dict) |:filter|.
             • pattern: (string) Filter pattern. Empty string if there is no
               filter.
             • force: (boolean) Whether filter is inverted or not.
@@ -1958,11 +1976,11 @@ Options Functions                                                *api-options*
 nvim_get_all_options_info()                      *nvim_get_all_options_info()*
     Gets the option information for all options.
 
-    The dictionary has the full option names as keys and option metadata
-    dictionaries as detailed at |nvim_get_option_info2()|.
+    The dict has the full option names as keys and option metadata dicts as
+    detailed at |nvim_get_option_info2()|.
 
     Return: ~
-        dictionary of all options
+        dict of all options
 
     See also: ~
       • |nvim_get_commands()|
@@ -1970,7 +1988,7 @@ nvim_get_all_options_info()                      *nvim_get_all_options_info()*
 nvim_get_option_info2({name}, {opts})                *nvim_get_option_info2()*
     Gets the option information for one option from arbitrary buffer or window
 
-    Resulting dictionary has keys:
+    Resulting dict has keys:
     • name: Name of the option (like 'filetype')
     • shortname: Shortened name of the option (like 'ft')
     • type: type of option ("string", "number" or "boolean")
@@ -2138,14 +2156,14 @@ nvim_buf_attach({buffer}, {send_buffer}, {opts})           *nvim_buf_attach()*
       • |api-buffer-updates-lua|
 
 nvim_buf_call({buffer}, {fun})                               *nvim_buf_call()*
-    call a function with buffer as temporary current buffer
+    Call a function with buffer as temporary current buffer.
 
     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
-    One of these windows will be set as current window temporarily. Otherwise
-    a temporary scratch window (called the "autocmd window" for historical
-    reasons) will be used.
+    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.
+    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()|.
@@ -2460,10 +2478,11 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
     `start_row = end_row = row` and `start_col = end_col = col`. To delete the
     text in a range, use `replacement = {}`.
 
-    Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire
-    lines.
-
-    Prefer |nvim_put()| if you want to insert text at the cursor position.
+    Note: ~
+      • Prefer |nvim_buf_set_lines()| (for performance) to add or delete
+        entire lines.
+      • Prefer |nvim_paste()| or |nvim_put()| to insert (instead of replace)
+        text at cursor.
 
     Attributes: ~
         not allowed when |textlock| is active
@@ -2476,10 +2495,6 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col},
       • {end_col}      Ending column (byte offset) on last line, exclusive
       • {replacement}  Array of lines to use as replacement
 
-    See also: ~
-      • |nvim_buf_set_lines()|
-      • |nvim_put()|
-
 nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
     Sets a buffer-scoped (b:) variable
 
@@ -2758,8 +2773,6 @@ nvim_buf_set_extmark({buffer}, {ns_id}, {line}, {col}, {opts})
                   • 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 (EXPERIMENTAL) enables "scoping" for the
-                    extmark. See |nvim__win_add_ns()|
 
     Return: ~
         Id of the created/updated extmark
@@ -2802,7 +2815,7 @@ nvim_set_decoration_provider({ns_id}, {opts})
     Note: this function should not be called often. Rather, the callbacks
     themselves can be used to throttle unneeded callbacks. the `on_start`
     callback can return `false` to disable the provider until the next redraw.
-    Similarly, return `false` in `on_win` will skip the `on_lines` calls for
+    Similarly, return `false` in `on_win` will skip the `on_line` calls for
     that window (but any extmarks set in `on_win` will still be used). A
     plugin managing multiple sources of decoration should ideally only set one
     provider, and merge the sources internally. You can use multiple `ns_id`
@@ -2811,10 +2824,10 @@ nvim_set_decoration_provider({ns_id}, {opts})
     Note: doing anything other than setting extmarks is considered
     experimental. Doing things like changing options are not explicitly
     forbidden, but is likely to have unexpected consequences (such as 100% CPU
-    consumption). doing `vim.rpcnotify` should be OK, but `vim.rpcrequest` is
+    consumption). Doing `vim.rpcnotify`