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

1 files changed, 439 insertions, 306 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 95a929b808..ba3b7c0915 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -7,7 +7,7 @@
 Nvim API                                                           *API* *api*
 
 Nvim exposes a powerful API that can be used by plugins and external processes
-via |RPC|, |Lua| and VimL (|eval-api|).
+via |RPC|, |Lua| and Vimscript (|eval-api|).
 
 Applications can also embed libnvim to work with the C API directly.
 
@@ -17,8 +17,15 @@ Applications can also embed libnvim to work with the C API directly.
 API Usage                                               *api-rpc* *RPC* *rpc*
 
                                                         *msgpack-rpc*
-RPC is the typical way to control Nvim programmatically.  Nvim implements the
-MessagePack-RPC protocol:
+RPC is the main way to control Nvim programmatically.  Nvim implements the
+MessagePack-RPC protocol with these extra (out-of-spec) constraints:
+
+1. Responses must be given in reverse order of requests (like "unwinding
+   a stack").
+2. Nvim processes all messages (requests and notifications) in the order they
+   are received.
+
+MessagePack-RPC specification:
   https://github.com/msgpack-rpc/msgpack-rpc/blob/master/spec.md
   https://github.com/msgpack/msgpack/blob/0b8f5ac/spec.md
 
@@ -202,7 +209,7 @@ any of these approaches:
      nvim --api-info | python -c 'import msgpack, sys, yaml; yaml.dump(msgpack.unpackb(sys.stdin.buffer.read()), sys.stdout)'
 <
   3. Use the |api_info()| Vimscript function. >vim
-     :lua print(vim.inspect(vim.fn.api_info()))
+     :lua vim.print(vim.fn.api_info())
 <     Example using |filter()| to exclude non-deprecated API functions: >vim
      :new|put =map(filter(api_info().functions, '!has_key(v:val,''deprecated_since'')'), 'v:val.name')
 
@@ -273,7 +280,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata},
     changed but not the buffer contents. {linedata} contains the changed
     screen lines. This happens when 'inccommand' shows a buffer preview.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
 
         {changedtick} value of |b:changedtick| for the buffer. If you send an
@@ -306,7 +313,7 @@ nvim_buf_changedtick_event[{buf}, {changedtick}]  *nvim_buf_changedtick_event*
     When |b:changedtick| was incremented but no text was changed. Relevant for
     undo/redo.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
         {changedtick} new value of |b:changedtick| for the buffer
 
@@ -319,7 +326,7 @@ nvim_buf_detach_event[{buf}]                           *nvim_buf_detach_event*
       |:checktime| or 'autoread'.
     - Generally: whenever the buffer contents are unloaded from memory.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
 
 
@@ -356,6 +363,7 @@ In-process Lua plugins can receive buffer updates in the form of Lua
 callbacks. These callbacks are called frequently in various contexts;
 |textlock| prevents changing buffer contents and window layout (use
 |vim.schedule()| to defer such operations to the main loop instead).
+Moving the cursor is allowed, but it is restored afterwards.
 
 |nvim_buf_attach()| will take keyword args for the callbacks. "on_lines" will
 receive parameters ("lines", {buf}, {changedtick}, {firstline}, {lastline},
@@ -399,6 +407,23 @@ external highlighter plugin wants to add many highlights in a batch,
 performance can be improved by calling |nvim_buf_add_highlight()| as an
 asynchronous notification, after first (synchronously) requesting a source id.
 
+|nvim_buf_add_highlight()| adds highlights as |extmarks|. If highlights need to
+be tracked or manipulated after adding them, it is better to use
+|nvim_buf_set_extmark()| directly, as this function returns the placed |extmark|
+id. Thus, instead of >lua
+  vim.api.nvim_buf_add_highlight(buf, ns_id, hl_group, line, col_start, col_end)
+<
+use >lua
+  -- create the highlight through an extmark
+  extid = vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = hl_group})
+
+  -- example: modify the extmark's highlight group
+  vim.api.nvim_buf_set_extmark(buf, ns_id, line, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})
+
+  -- example: change the highlight's position
+  vim.api.nvim_buf_set_extmark(buf, ns_id, NEW_LINE, col_start, {end_col = col_end, hl_group = NEW_HL_GROUP, id = extid})
+<
+
 Example using the Python API client (|pynvim|):
 >python
     src = vim.new_highlight_source()
@@ -451,6 +476,11 @@ Buffer text can be highlighted by typical mechanisms (syntax highlighting,
 options from the current window; specify `style=minimal` in |nvim_open_win()|
 to disable various visual features such as the 'number' column.
 
+Other highlight groups specific to floating windows:
+- |hl-FloatBorder| for window's border
+- |hl-FloatTitle| for window's title
+- |hl-FloatFooter| for window's footer
+
 Currently, floating windows don't support some widgets like scrollbar.
 
 The output of |:mksession| does not include commands for restoring floating
@@ -464,7 +494,7 @@ Example: create a float with scratch buffer: >vim
         \ 'row': 1, 'anchor': 'NW', 'style': 'minimal'}
     let win = nvim_open_win(buf, 0, opts)
     " optional: change highlight, otherwise Pmenu is used
-    call nvim_win_set_option(win, 'winhl', 'Normal:MyHighlight')
+    call nvim_set_option_value('winhl', 'Normal:MyHighlight', {'win': win})
 <
 
 ==============================================================================
@@ -558,7 +588,7 @@ nvim__get_runtime({pat}, {all}, {*opts})                 *nvim__get_runtime()*
     Parameters: ~
       • {pat}   pattern of files to search for
       • {all}   whether to return all matches or only the first
-      • {opts}  is_lua: only search lua subdirs
+      • {opts}  is_lua: only search Lua subdirs
 
     Return: ~
         list of absolute paths to the found files
@@ -615,6 +645,10 @@ nvim__inspect_cell({grid}, {row}, {col})                *nvim__inspect_cell()*
     NB: if your UI doesn't use hlstate, this will not return hlstate first
     time.
 
+nvim__invalidate_glyph_cache()                *nvim__invalidate_glyph_cache()*
+    For testing. The condition in schar_cache_clear_if_full is hard to reach,
+    so this function can be used to force a cache clear in a test.
+
 nvim__stats()                                                  *nvim__stats()*
     Gets internal stats.
 
@@ -679,7 +713,7 @@ nvim_create_buf({listed}, {scratch})                       *nvim_create_buf()*
         Buffer handle, or 0 on error
 
     See also: ~
-        buf_open_scratch
+      • buf_open_scratch
 
 nvim_del_current_line()                              *nvim_del_current_line()*
     Deletes the current line.
@@ -693,13 +727,13 @@ nvim_del_keymap({mode}, {lhs})                             *nvim_del_keymap()*
     To unmap a buffer-local mapping, use |nvim_buf_del_keymap()|.
 
     See also: ~
-        |nvim_set_keymap()|
+      • |nvim_set_keymap()|
 
 nvim_del_mark({name})                                        *nvim_del_mark()*
     Deletes an uppercase/file named mark. See |mark-motions|.
 
-    Note:
-        fails with error if a lowercase or buffer local named mark is used.
+    Note: ~
+      • Lowercase name (or other buffer-local mark) is an error.
 
     Parameters: ~
       • {name}  Mark name
@@ -708,8 +742,8 @@ nvim_del_mark({name})                                        *nvim_del_mark()*
         true if the mark was deleted, else false.
 
     See also: ~
-        |nvim_buf_del_mark()|
-        |nvim_get_mark()|
+      • |nvim_buf_del_mark()|
+      • |nvim_get_mark()|
 
 nvim_del_var({name})                                          *nvim_del_var()*
     Removes a global (g:) variable.
@@ -746,7 +780,7 @@ nvim_err_writeln({str})                                   *nvim_err_writeln()*
       • {str}  Message
 
     See also: ~
-        nvim_err_write()
+      • nvim_err_write()
 
 nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
     Evaluates statusline string.
@@ -768,6 +802,8 @@ nvim_eval_statusline({str}, {*opts})                  *nvim_eval_statusline()*
                 • use_tabline: (boolean) Evaluate tabline instead of
                   statusline. When true, {winid} is ignored. Mutually
                   exclusive with {use_winbar}.
+                • use_statuscol_lnum: (number) Evaluate statuscolumn for this
+                  line number instead of statusline.
 
     Return: ~
         Dictionary containing statusline information, with these keys:
@@ -820,8 +856,8 @@ nvim_feedkeys({keys}, {mode}, {escape_ks})                   *nvim_feedkeys()*
                      true otherwise.
 
     See also: ~
-        feedkeys()
-        vim_strsave_escape_ks
+      • feedkeys()
+      • vim_strsave_escape_ks
 
 nvim_get_api_info()                                      *nvim_get_api_info()*
     Returns a 2-tuple (Array), where item 0 is the current channel id and item
@@ -918,37 +954,48 @@ nvim_get_current_win()                                *nvim_get_current_win()*
     Return: ~
         Window handle
 
-nvim_get_hl_by_id({hl_id}, {rgb})                        *nvim_get_hl_by_id()*
-    Gets a highlight definition by id. |hlID()|
-
-    Parameters: ~
-      • {hl_id}  Highlight id as returned by |hlID()|
-      • {rgb}    Export RGB colors
-
-    Return: ~
-        Highlight definition map
-
-    See also: ~
-        nvim_get_hl_by_name
+nvim_get_hl({ns_id}, {*opts})                                  *nvim_get_hl()*
+    Gets all or specific highlight groups in a namespace.
 
-nvim_get_hl_by_name({name}, {rgb})                     *nvim_get_hl_by_name()*
-    Gets a highlight definition by name.
+    Note: ~
+      • When the `link` attribute is defined in the highlight definition map,
+        other attributes will not be taking effect (see |:hi-link|).
 
     Parameters: ~
-      • {name}  Highlight group name
-      • {rgb}   Export RGB colors
+      • {ns_id}  Get highlight groups for namespace ns_id
+                 |nvim_get_namespaces()|. Use 0 to get global highlight groups
+                 |:highlight|.
+      • {opts}   Options dict:
+                 • name: (string) Get a highlight definition by name.
+                 • id: (integer) Get a highlight definition by id.
+                 • link: (boolean, default true) Show linked group name
+                   instead of effective definition |:hi-link|.
+                 • create: (boolean, default true) When highlight group
+                   doesn't exist create it.
 
     Return: ~
-        Highlight definition map
-
-    See also: ~
-        nvim_get_hl_by_id
+        Highlight groups as a map from group name to a highlight definition
+        map as in |nvim_set_hl()|, or only a single highlight definition map
+        if requested by name or id.
 
 nvim_get_hl_id_by_name({name})                      *nvim_get_hl_id_by_name()*
     Gets a highlight group by name
 
     similar to |hlID()|, but allocates a new ID if not present.
 
+nvim_get_hl_ns({*opts})                                     *nvim_get_hl_ns()*
+    Gets the active highlight namespace.
+
+    Parameters: ~
+      • {opts}  Optional parameters
+                • winid: (number) |window-ID| for retrieving a window's
+                  highlight namespace. A value of -1 is returned when
+                  |nvim_win_set_hl_ns()| has not been called for the window
+                  (or was called with a namespace of -1).
+
+    Return: ~
+        Namespace id, or -1
+
 nvim_get_keymap({mode})                                    *nvim_get_keymap()*
     Gets a list of global (non-buffer-local) |mapping| definitions.
 
@@ -960,13 +1007,14 @@ nvim_get_keymap({mode})                                    *nvim_get_keymap()*
         "buffer" key is always zero.
 
 nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
-    Return a tuple (row, col, buffer, buffername) representing the position of
-    the uppercase/file named mark. See |mark-motions|.
+    Returns a `(row, col, buffer, buffername)` tuple representing the position
+    of the uppercase/file named mark. "End of line" column position is
+    returned as |v:maxcol| (big number). See |mark-motions|.
 
     Marks are (1,0)-indexed. |api-indexing|
 
-    Note:
-        fails with error if a lowercase or buffer local named mark is used.
+    Note: ~
+      • Lowercase name (or other buffer-local mark) is an error.
 
     Parameters: ~
       • {name}  Mark name
@@ -977,8 +1025,8 @@ nvim_get_mark({name}, {opts})                                *nvim_get_mark()*
         not set.
 
     See also: ~
-        |nvim_buf_set_mark()|
-        |nvim_del_mark()|
+      • |nvim_buf_set_mark()|
+      • |nvim_del_mark()|
 
 nvim_get_mode()                                              *nvim_get_mode()*
     Gets the current mode. |mode()| "blocking" is true if Nvim is waiting for
@@ -1047,12 +1095,10 @@ nvim_input({keys})                                              *nvim_input()*
 
     On execution error: does not fail, but updates v:errmsg.
 
-    Note:
-        |keycodes| like <CR> are translated, so "<" is special. To input a
+    Note: ~
+      • |keycodes| like <CR> are translated, so "<" is special. To input a
         literal "<", send <LT>.
-
-    Note:
-        For mouse events use |nvim_input_mouse()|. The pseudokey form
+      • For mouse events use |nvim_input_mouse()|. The pseudokey form
         "<LeftMouse><col,row>" is deprecated since |api-level| 6.
 
     Attributes: ~
@@ -1072,8 +1118,8 @@ nvim_input_mouse({button}, {action}, {modifier}, {grid}, {row}, {col})
     Non-blocking: does not wait on any result, but queues the event to be
     processed soon by the event loop.
 
-    Note:
-        Currently this doesn't support "scripting" multiple mouse events by
+    Note: ~
+      • Currently this doesn't support "scripting" multiple mouse events by
         calling it multiple times in a loop: the intermediate mouse positions
         will be ignored. It should be used to implement real-time mouse input
         in a GUI. The deprecated pseudokey form ("<LeftMouse><col,row>") of
@@ -1113,7 +1159,7 @@ nvim_list_chans()                                          *nvim_list_chans()*
         specified at |nvim_get_chan_info()|.
 
 nvim_list_runtime_paths()                          *nvim_list_runtime_paths()*
-    Gets the paths contained in 'runtimepath'.
+    Gets the paths contained in |runtime-search-path|.
 
     Return: ~
         List of paths
@@ -1173,10 +1219,13 @@ nvim_open_term({buffer}, {opts})                            *nvim_open_term()*
     |nvim_chan_send()| can be called immediately to process sequences in a
     virtual terminal having the intended size.
 
+    Attributes: ~
+        not allowed when |textlock| is active
+
     Parameters: ~
       • {buffer}  the buffer to use (expected to be empty)
       • {opts}    Optional parameters.
-                  • on_input: lua callback for input sent, i e keypresses in
+                  • on_input: Lua callback for input sent, i e keypresses in
                     terminal mode. Note: keypresses are sent raw as they would
                     be to the pty master end. For instance, a carriage return
                     is sent as a "\r", not as a "\n". |textlock| applies. It
@@ -1252,8 +1301,8 @@ nvim_replace_termcodes({str}, {from_part}, {do_lt}, {special})
       • {special}    Replace |keycodes|, e.g. <CR> becomes a "\r" char.
 
     See also: ~
-        replace_termcodes
-        cpoptions
+      • replace_termcodes
+      • cpoptions
 
                                                 *nvim_select_popupmenu_item()*
 nvim_select_popupmenu_item({item}, {insert}, {finish}, {opts})
@@ -1286,8 +1335,8 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
     appropriate. Example: library first identifies the channel, then a plugin
     using that library later identifies itself.
 
-    Note:
-        "Something is better than nothing". You don't need to include all the
+    Note: ~
+      • "Something is better than nothing". You don't need to include all the
         fields.
 
     Attributes: ~
@@ -1307,7 +1356,11 @@ nvim_set_client_info({name}, {version}, {type}, {methods}, {attributes})
       • {type}        Must be one of the following values. Client libraries
                       should default to "remote" unless overridden by the
                       user.
-                      • "remote" remote client connected to Nvim.
+                      • "remote" remote client connected "Nvim flavored"
+                        MessagePack-RPC (responses must be in reverse order of
+                        requests). |msgpack-rpc|
+                      • "msgpack-rpc" remote client connected to Nvim via
+                        fully MessagePack-RPC compliant protocol.
                       • "ui" gui frontend
                       • "embedder" application using Nvim as a component (for
                         example, IDE/editor implementing a vim mode).
@@ -1338,7 +1391,7 @@ nvim_set_current_buf({buffer})                        *nvim_set_current_buf()*
     Sets the current buffer.
 
     Attributes: ~
-        not allowed when |textlock| is active
+        not allowed when |textlock| is active or in the |cmdwin|
 
     Parameters: ~
       • {buffer}  Buffer handle
@@ -1362,7 +1415,7 @@ nvim_set_current_tabpage({tabpage})               *nvim_set_current_tabpage()*
     Sets the current tabpage.
 
     Attributes: ~
-        not allowed when |textlock| is active
+        not allowed when |textlock| is active or in the |cmdwin|
 
     Parameters: ~
       • {tabpage}  Tabpage handle
@@ -1371,7 +1424,7 @@ nvim_set_current_win({window})                        *nvim_set_current_win()*
     Sets the current window.
 
     Attributes: ~
-        not allowed when |textlock| is active
+        not allowed when |textlock| is active or in the |cmdwin|
 
     Parameters: ~
       • {window}  Window handle
@@ -1379,21 +1432,24 @@ nvim_set_current_win({window})                        *nvim_set_current_win()*
 nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
     Sets a highlight group.
 
-    Note:
-        Unlike the `:highlight` command which can update a highlight group,
-        this function completely replaces the definition. For example:
+    Note: ~
+      • Unlike the `:highlight` command which can update a highlight group, this
+        function completely replaces the definition. For example:
         `nvim_set_hl(0, 'Visual', {})` will clear the highlight group
         'Visual'.
-
-    Note:
-        The fg and bg keys also accept the string values `"fg"` or `"bg"`
-        which act as aliases to the corresponding foreground and background
-        values of the Normal group. If the Normal group has not been defined,
-        using these values results in an error.
+      • The fg and bg keys also accept the string values `"fg"` or `"bg"` which
+        act as aliases to the corresponding foreground and background values
+        of the Normal group. If the Normal group has not been defined, using
+        these values results in an error.
+      • If `link` is used in combination with other attributes; only the `link`
+        will take effect (see |:hi-link|).
 
     Parameters: ~
       • {ns_id}  Namespace id for this highlight |nvim_create_namespace()|.
                  Use 0 to set a highlight group globally |:highlight|.
+                 Highlights from non-global namespaces are not active by
+                 default, use |nvim_set_hl_ns()| or |nvim_win_set_hl_ns()| to
+                 activate them.
       • {name}   Highlight group name, e.g. "ErrorMsg"
       • {val}    Highlight definition map, accepts the following keys:
                  • fg (or foreground): color name or "#RRGGBB", see note.
@@ -1419,16 +1475,19 @@ nvim_set_hl({ns_id}, {name}, {*val})                           *nvim_set_hl()*
                  • cterm: cterm attribute map, like |highlight-args|. If not
                    set, cterm attributes will match those from the attribute
                    map documented above.
+                 • force: if true force update the highlight group when it
+                   exists.
 
 nvim_set_hl_ns({ns_id})                                     *nvim_set_hl_ns()*
-    Set active namespace for highlights. This can be set for a single window,
-    see |nvim_win_set_hl_ns()|.
+    Set active namespace for highlights defined with |nvim_set_hl()|. This can
+    be set for a single window, see |nvim_win_set_hl_ns()|.
 
     Parameters: ~
       • {ns_id}  the namespace to use
 
 nvim_set_hl_ns_fast({ns_id})                           *nvim_set_hl_ns_fast()*
-    Set active namespace for highlights while redrawing.
+    Set active namespace for highlights defined with |nvim_set_hl()| while
+    redrawing.
 
     This function meant to be called while redrawing, primarily from
     |nvim_set_decoration_provider()| on_win and on_line callbacks, which are
@@ -1458,19 +1517,20 @@ nvim_set_keymap({mode}, {lhs}, {rhs}, {*opts})             *nvim_set_keymap()*
 
     Parameters: ~
       • {mode}  Mode short-name (map command prefix: "n", "i", "v", "x", …) or
-                "!" for |:map!|, or empty string for |:map|.
+                "!" for |:map!|, or empty string for |:map|. "ia", "ca" or
+                "!a" for abbreviation in Insert mode, Cmdline mode, or both,
+                respectively
       • {lhs}   Left-hand-side |{lhs}| of the mapping.
       • {rhs}   Right-hand-side |{rhs}| of the mapping.
-      • {opts}  Optional parameters map: keys are |:map-arguments|, values are
-                booleans (default false). Accepts all |:map-arguments| as keys
-                excluding |<buffer>| but including |:noremap| and "desc".
-                Unknown key is an error. "desc" can be used to give a
-                description to the mapping. When called from Lua, also accepts
-                a "callback" key that takes a Lua function to call when the
-                mapping is executed. When "expr" is true, "replace_keycodes"
-                (boolean) can be used to replace keycodes in the resulting
-                string (see |nvim_replace_termcodes()|), and a Lua callback
-                returning `nil` is equivalent to returning an empty string.
+      • {opts}  Optional parameters map: Accepts all |:map-arguments| as keys
+                except |<buffer>|, values are booleans (default false). Also:
+                • "noremap" disables |recursive_mapping|, like |:noremap|
+                • "desc" human-readable description.
+                • "callback" Lua function called in place of {rhs}.
+                • "replace_keycodes" (boolean) When "expr" is true, replace
+                  keycodes in the resulting string (see
+                  |nvim_replace_termcodes()|). Returning nil from the Lua
+                  "callback" is equivalent to returning an empty string.
 
 nvim_set_var({name}, {value})                                 *nvim_set_var()*
     Sets a global (g:) variable.
@@ -1520,22 +1580,22 @@ Vimscript Functions                                            *api-vimscript*
 
                                                    *nvim_call_dict_function()*
 nvim_call_dict_function({dict}, {fn}, {args})
-    Calls a VimL |Dictionary-function| with the given arguments.
+    Calls a Vimscript |Dictionary-function| with the given arguments.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {dict}  Dictionary, or String evaluating to a VimL |self| dict
-      • {fn}    Name of the function defined on the VimL dict
+      • {dict}  Dictionary, 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
 
     Return: ~
         Result of the function call
 
 nvim_call_function({fn}, {args})                        *nvim_call_function()*
-    Calls a VimL function with the given arguments.
+    Calls a Vimscript function with the given arguments.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
       • {fn}    Function to call
@@ -1547,54 +1607,56 @@ nvim_call_function({fn}, {args})                        *nvim_call_function()*
 nvim_command({command})                                       *nvim_command()*
     Executes an Ex command.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
-    Prefer using |nvim_cmd()| or |nvim_exec()| over this. To evaluate multiple
-    lines of Vim script or an Ex command directly, use |nvim_exec()|. To
-    construct an Ex command using a structured format and then execute it, use
-    |nvim_cmd()|. To modify an Ex command before evaluating it, use
-    |nvim_parse_cmd()| in conjunction with |nvim_cmd()|.
+    Prefer using |nvim_cmd()| or |nvim_exec2()| over this. To evaluate
+    multiple lines of Vim script or an Ex command directly, use
+    |nvim_exec2()|. To construct an Ex command using a structured format and
+    then execute it, use |nvim_cmd()|. To modify an Ex command before
+    evaluating it, use |nvim_parse_cmd()| in conjunction with |nvim_cmd()|.
 
     Parameters: ~
       • {command}  Ex command string
 
 nvim_eval({expr})                                                *nvim_eval()*
-    Evaluates a VimL |expression|. Dictionaries and Lists are recursively
+    Evaluates a Vimscript |expression|. Dictionaries and Lists are recursively
     expanded.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {expr}  VimL expression string
+      • {expr}  Vimscript expression string
 
     Return: ~
         Evaluation result or expanded object
 
-nvim_exec({src}, {output})                                       *nvim_exec()*
+nvim_exec2({src}, {*opts})                                      *nvim_exec2()*
     Executes Vimscript (multiline block of Ex commands), like anonymous
     |:source|.
 
     Unlike |nvim_command()| this function supports heredocs, script-scope
     (s:), etc.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
-      • {src}     Vimscript code
-      • {output}  Capture and return all (non-error, non-shell |:!|) output
+      • {src}   Vimscript code
+      • {opts}  Optional parameters.
+                • output: (boolean, default false) Whether to capture and
+                  return all (non-error, non-shell |:!|) output.
 
     Return: ~
-        Output (non-error, non-shell |:!|) if `output` is true, else empty
-        string.
+        Dictionary containing information about execution, with these keys:
+        • output: (string|nil) Output if `opts.output` is true.
 
     See also: ~
-        |execute()|
-        |nvim_command()|
-        |nvim_cmd()|
+      • |execute()|
+      • |nvim_command()|
+      • |nvim_cmd()|
 
                                                      *nvim_parse_expression()*
 nvim_parse_expression({expr}, {flags}, {highlight})
-    Parse a VimL expression.
+    Parse a Vimscript expression.
 
     Attributes: ~
         |api-fast|
@@ -1638,8 +1700,8 @@ nvim_parse_expression({expr}, {flags}, {highlight})
               stringified without "kExprNode" prefix.
             • "start": a pair [line, column] describing where node is
               "started" where "line" is always 0 (will not be 0 if you will be
-              using nvim_parse_viml() on e.g. ":let", but that is not present
-              yet). Both elements are Integers.
+              using this API on e.g. ":let", but that is not present yet).
+              Both elements are Integers.
             • "len": “length” of the node. This and "start" are there for
               debugging purposes primary (debugging parser and providing debug
               information).
@@ -1678,13 +1740,13 @@ Command Functions                                                *api-command*
 
                                               *nvim_buf_create_user_command()*
 nvim_buf_create_user_command({buffer}, {name}, {command}, {*opts})
-    Create a new user command |user-commands| in the given buffer.
+    Creates a buffer-local command |user-commands|.
 
     Parameters: ~
       • {buffer}  Buffer handle, or 0 for current buffer.
 
     See also: ~
-        nvim_create_user_command
+      • nvim_create_user_command
 
                                                  *nvim_buf_del_user_command()*
 nvim_buf_del_user_command({buffer}, {name})
@@ -1722,7 +1784,7 @@ nvim_cmd({*cmd}, {*opts})                                         *nvim_cmd()*
     example, instead of `vim.cmd.bdelete{ count = 2 }`, you may do
     `vim.cmd.bdelete(2)`.
 
-    On execution error: fails with VimL error, updates v:errmsg.
+    On execution error: fails with Vimscript error, updates v:errmsg.
 
     Parameters: ~
       • {cmd}   Command to execute. Must be a Dictionary that can contain the
@@ -1738,22 +1800,19 @@ nvim_cmd({*cmd}, {*opts})                                         *nvim_cmd()*
         empty string.
 
     See also: ~
-        |nvim_exec()|
-        |nvim_command()|
+      • |nvim_exec2()|
+      • |nvim_command()|
 
                                                   *nvim_create_user_command()*
 nvim_create_user_command({name}, {command}, {*opts})
-    Create a new user command |user-commands|
+    Creates a global |user-commands| command.
 
-    {name} is the name of the new command. The name must begin with an
-    uppercase letter.
-
-    {command} is the replacement text or Lua function to execute.
+    For Lua usage see |lua-guide-commands-create|.
 
     Example: >vim
-       :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {})
-       :SayHello
-       Hello world!
+        :call nvim_create_user_command('SayHello', 'echo "Hello world!"', {'bang': v:true})
+        :SayHello
+        Hello world!
 <
 
     Parameters: ~
@@ -1769,6 +1828,7 @@ nvim_create_user_command({name}, {command}, {*opts})
                    • fargs: (table) The args split by unescaped whitespace
                      (when more than one argument is allowed), if any
                      |<f-args>|
+                   • nargs: (string) Number of arguments |:command-nargs|
                    • bang: (boolean) "true" if the command was executed with a
                      ! modifier |<bang>|
                    • line1: (number) The starting line of the command range
@@ -1783,19 +1843,20 @@ nvim_create_user_command({name}, {command}, {*opts})
                    • smods: (table) Command modifiers in a structured format.
                      Has the same structure as the "mods" key of
                      |nvim_parse_cmd()|.
-      • {opts}     Optional command attributes. See |command-attributes| for
-                   more details. To use boolean attributes (such as
-                   |:command-bang| or |:command-bar|) set the value to "true".
-                   In addition to the string options listed in
-                   |:command-complete|, the "complete" key also accepts a Lua
-                   function which works like the "customlist" completion mode
-                   |:command-completion-customlist|. Additional parameters:
-                   • desc: (string) Used for listing the command when a Lua
-                     function is used for {command}.
-                   • force: (boolean, default true) Override any previous
-                     definition.
-                   • preview: (function) Preview callback for 'inccommand'
-                     |:command-preview|
+      • {opts}     Optional |command-attributes|.
+                   • Set boolean attributes such as |:command-bang| or
+                     |:command-bar| to true (but not |:command-buffer|, use
+                     |nvim_buf_create_user_command()| instead).
+                   • "complete" |:command-complete| also accepts a Lua
+                     function which works like
+                     |:command-completion-customlist|.
+                   • Other parameters:
+                     • desc: (string) Used for listing the command when a Lua
+                       function is used for {command}.
+                     • force: (boolean, default true) Override any previous
+                       definition.
+                     • preview: (function) Preview callback for 'inccommand'
+                       |:command-preview|
 
 nvim_del_user_command({name})                        *nvim_del_user_command()*
     Delete a user-defined command.
@@ -1814,6 +1875,9 @@ nvim_get_commands({*opts})                               *nvim_get_commands()*
     Return: ~
         Map of maps describing commands.
 
+    See also: ~
+      • |nvim_get_all_options_info()|
+
 nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
     Parse command line.
 
@@ -1889,45 +1953,20 @@ nvim_parse_cmd({str}, {opts})                               *nvim_parse_cmd()*
 ==============================================================================
 Options Functions                                                *api-options*
 
-nvim_buf_get_option({buffer}, {name})                  *nvim_buf_get_option()*
-    Gets a buffer option value
-
-    Parameters: ~
-      • {buffer}  Buffer handle, or 0 for current buffer
-      • {name}    Option name
-
-    Return: ~
-        Option value
-
-nvim_buf_set_option({buffer}, {name}, {value})         *nvim_buf_set_option()*
-    Sets a buffer option value. Passing `nil` as value deletes the option
-    (only works if there's a global fallback)
-
-    Parameters: ~
-      • {buffer}  Buffer handle, or 0 for current buffer
-      • {name}    Option name
-      • {value}   Option value
-
 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_info()|.
+    dictionaries as detailed at |nvim_get_option_info2()|.
 
     Return: ~
         dictionary of all options
 
-nvim_get_option({name})                                    *nvim_get_option()*
-    Gets the global value of an option.
-
-    Parameters: ~
-      • {name}  Option name
-
-    Return: ~
-        Option value (global)
+    See also: ~
+      • |nvim_get_commands()|
 
-nvim_get_option_info({name})                          *nvim_get_option_info()*
-    Gets the option information for one option
+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:
     • name: Name of the option (like 'filetype')
@@ -1943,8 +1982,19 @@ nvim_get_option_info({name})                          *nvim_get_option_info()*
     • commalist: List of comma separated values
     • flaglist: List of single char flags
 
+    When {scope} is not provided, the last set information applies to the
+    local value in the current buffer or window if it is available, otherwise
+    the global value information is returned. This behavior can be disabled by
+    explicitly specifying {scope} in the {opts} table.
+
     Parameters: ~
       • {name}  Option name
+      • {opts}  Optional parameters
+                • scope: One of "global" or "local". Analogous to |:setglobal|
+                  and |:setlocal|, respectively.
+                • win: |window-ID|. Used for getting window local options.
+                • buf: Buffer number. Used for getting buffer local options.
+                  Implies {scope} is "local".
 
     Return: ~
         Option Information
@@ -1963,17 +2013,14 @@ nvim_get_option_value({name}, {*opts})               *nvim_get_option_value()*
                 • win: |window-ID|. Used for getting window local options.
                 • buf: Buffer number. Used for getting buffer local options.
                   Implies {scope} is "local".
+                • filetype: |filetype|. Used to get the default option for a
+                  specific filetype. Cannot be used with any other option.
+                  Note: this will trigger |ftplugin| and all |FileType|
+                  autocommands for the corresponding filetype.
 
     Return: ~
         Option value
 
-nvim_set_option({name}, {value})                           *nvim_set_option()*
-    Sets the global value of an option.
-
-    Parameters: ~
-      • {name}   Option name
-      • {value}  New option value
-
                                                      *nvim_set_option_value()*
 nvim_set_option_value({name}, {value}, {*opts})
     Sets the value of an option. The behavior of this function matches that of
@@ -1991,25 +2038,6 @@ nvim_set_option_value({name}, {value}, {*opts})
                  • win: |window-ID|. Used for setting window local option.
                  • buf: Buffer number. Used for setting buffer local option.
 
-nvim_win_get_option({window}, {name})                  *nvim_win_get_option()*
-    Gets a window option value
-
-    Parameters: ~
-      • {window}  Window handle, or 0 for current window
-      • {name}    Option name
-
-    Return: ~
-        Option value
-
-nvim_win_set_option({window}, {name}, {value})         *nvim_win_set_option()*
-    Sets a window option value. Passing `nil` as value deletes the option
-    (only works if there's a global fallback)
-
-    Parameters: ~
-      • {window}  Window handle, or 0 for current window
-      • {name}    Option name
-      • {value}   Option value