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

100 files changed, 12817 insertions, 10494 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})