aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--runtime/doc/api.txt75
-rw-r--r--runtime/doc/develop.txt81
-rw-r--r--runtime/doc/eval.txt13
-rw-r--r--runtime/doc/if_lua.txt111
-rw-r--r--runtime/doc/index.txt2
-rw-r--r--runtime/doc/motion.txt16
-rw-r--r--runtime/doc/options.txt16
-rw-r--r--src/nvim/api/buffer.c49
-rw-r--r--src/nvim/api/vim.c5
-rw-r--r--src/nvim/lua/vim.lua14
-rw-r--r--test/functional/lua/utility_functions_spec.lua2
-rw-r--r--test/functional/terminal/tui_spec.lua2
12 files changed, 278 insertions, 108 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index 98dd330b48..d6e420c427 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -850,10 +850,10 @@ nvim_open_win({buffer}, {enter}, {config}) *nvim_open_win()*
{enter} Enter the window (make it the current window)
{config} Map defining the window configuration. Keys:
• `relative` : Sets the window layout to "floating", placed
- at (row,col) coordinates relative to one of:
+ at (row,col) coordinates relative to:
• "editor" The global editor grid
• "win" Window given by the `win` field, or
- current window by default.
+ current window.
• "cursor" Cursor position in current window.
• `win` : |window-ID| for relative="win".
@@ -1476,45 +1476,66 @@ nvim_buf_line_count({buffer}) *nvim_buf_line_count()*
Line count, or 0 for unloaded buffer. |api-buffer|
nvim_buf_attach({buffer}, {send_buffer}, {opts}) *nvim_buf_attach()*
- Activates buffer-update events on a channel, or as lua
+ Activates buffer-update events on a channel, or as Lua
callbacks.
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
- {send_buffer} Set to true if the initial notification
- should contain the whole buffer. If so, the
- first notification will be a
- `nvim_buf_lines_event` . Otherwise, the
- first notification will be a
- `nvim_buf_changedtick_event` . Not used for
- lua callbacks.
+ {send_buffer} True if the initial notification should
+ contain the whole buffer: first
+ notification will be `nvim_buf_lines_event`
+ . Else the first notification will be
+ `nvim_buf_changedtick_event` . Not for Lua
+ callbacks.
{opts} Optional parameters.
- • `on_lines` : lua callback received on
- change.
- • `on_changedtick` : lua callback received
- on changedtick increment without text
- change.
- • `utf_sizes` : include UTF-32 and UTF-16
- size of the replaced region. See
- |api-buffer-updates-lua| for more
- information
+ • on_lines: Lua callback invoked on change.
+ Return `true` to detach. Args:
+ • buffer handle
+ • b:changedtick
+ • first line that changed (zero-indexed)
+ • last line that was changed
+ • last line in the updated range
+ • byte count of previous contents
+ • deleted_codepoints (if `utf_sizes` is
+ true)
+ • deleted_codeunits (if `utf_sizes` is
+ true)
+
+ • on_changedtick: Lua callback invoked on
+ changedtick increment without text
+ change. Args:
+ • buffer handle
+ • b:changedtick
+
+ • on_detach: Lua callback invoked on
+ detach. Args:
+ • buffer handle
+
+ • utf_sizes: include UTF-32 and UTF-16 size
+ of the replaced region, as args to
+ `on_lines` .
+
+ Return: ~
+ False if attach failed (invalid parameter, or buffer isn't
+ loaded); otherwise True. TODO: LUA_API_NO_EVAL
- Return: ~
- False when updates couldn't be enabled because the buffer
- isn't loaded or `opts` contained an invalid key; otherwise
- True. TODO: LUA_API_NO_EVAL
+ See also: ~
+ |nvim_buf_detach()|
+ |api-buffer-updates-lua|
nvim_buf_detach({buffer}) *nvim_buf_detach()*
Deactivates buffer-update events on the channel.
- For Lua callbacks see |api-lua-detach|.
-
Parameters: ~
{buffer} Buffer handle, or 0 for current buffer
Return: ~
- False when updates couldn't be disabled because the buffer
- isn't loaded; otherwise True.
+ False if detach failed (because the buffer isn't loaded);
+ otherwise True.
+
+ See also: ~
+ |nvim_buf_attach()|
+ |api-lua-detach| for detaching Lua callbacks
*nvim_buf_get_lines()*
nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
diff --git a/runtime/doc/develop.txt b/runtime/doc/develop.txt
index 90c2e30771..ba887a83c8 100644
--- a/runtime/doc/develop.txt
+++ b/runtime/doc/develop.txt
@@ -143,6 +143,87 @@ DOCUMENTATION *dev-doc*
/// @param dirname The path fragment before `pend`
<
+C docstrings ~
+
+Nvim API documentation lives in the source code, as docstrings (Doxygen
+comments) on the function definitions. The |api| :help is generated
+from the docstrings defined in src/nvim/api/*.c.
+
+Docstring format:
+- Lines start with `///`
+- Special tokens start with `@` followed by the token name:
+ `@note`, `@param`, `@returns`
+- Limited markdown is supported.
+ - List-items start with `-` (useful to nest or "indent")
+- Use `<pre>` for code samples.
+
+Example: the help for |nvim_open_win()| is generated from a docstring defined
+in src/nvim/api/vim.c like this: >
+
+ /// Opens a new window.
+ /// ...
+ ///
+ /// Example (Lua): window-relative float
+ /// <pre>
+ /// vim.api.nvim_open_win(0, false,
+ /// {relative='win', row=3, col=3, width=12, height=3})
+ /// </pre>
+ ///
+ /// @param buffer Buffer to display
+ /// @param enter Enter the window
+ /// @param config Map defining the window configuration. Keys:
+ /// - relative: Sets the window layout, relative to:
+ /// - "editor" The global editor grid.
+ /// - "win" Window given by the `win` field.
+ /// - "cursor" Cursor position in current window.
+ /// ...
+ /// @param[out] err Error details, if any
+ ///
+ /// @return Window handle, or 0 on error
+
+
+Lua docstrings ~
+ *dev-lua-doc*
+Lua documentation lives in the source code, as docstrings on the function
+definitions. The |lua-vim| :help is generated from the docstrings.
+
+Docstring format:
+- Lines in the main description start with `---`
+- Special tokens start with `--@` followed by the token name:
+ `--@see`, `--@param`, `--@returns`
+- Limited markdown is supported.
+ - List-items start with `-` (useful to nest or "indent")
+- Use `<pre>` for code samples.
+
+Example: the help for |vim.paste()| is generated from a docstring decorating
+vim.paste in src/nvim/lua/vim.lua like this: >
+
+ --- Paste handler, invoked by |nvim_paste()| when a conforming UI
+ --- (such as the |TUI|) pastes text into the editor.
+ ---
+ --- Example: To remove ANSI color codes when pasting:
+ --- <pre>
+ --- vim.paste = (function()
+ --- local overridden = vim.paste
+ --- ...
+ --- end)()
+ --- </pre>
+ ---
+ --@see |paste|
+ ---
+ --@param lines ...
+ --@param phase ...
+ --@returns false if client should cancel the paste.
+
+
+LUA *dev-lua*
+
+- Keep the core Lua modules |lua-stdlib| simple. Avoid elaborate OOP or
+ pseudo-OOP designs. Plugin authors just want functions to call, they don't
+ want to learn a big, fancy inheritance hierarchy. So we should avoid complex
+ objects: tables are usually better.
+
+
API *dev-api*
Use this template to name new API functions:
diff --git a/runtime/doc/eval.txt b/runtime/doc/eval.txt
index d21e441888..1eb873a5b4 100644
--- a/runtime/doc/eval.txt
+++ b/runtime/doc/eval.txt
@@ -1217,7 +1217,7 @@ lambda expression *expr-lambda* *lambda*
{args -> expr1} lambda expression
A lambda expression creates a new unnamed function which returns the result of
-evaluating |expr1|. Lambda expressions differ from |user-functions| in
+evaluating |expr1|. Lambda expressions differ from |user-function|s in
the following ways:
1. The body of the lambda expression is an |expr1| and not a sequence of |Ex|
@@ -1986,9 +1986,12 @@ v:windowid Application-specific window "handle" which may be set by any
|window-ID|.
==============================================================================
-4. Builtin Functions *functions*
+4. Builtin Functions *vim-function* *functions*
-See |function-list| for a list grouped by what the function is used for.
+The Vimscript subsystem (referred to as "eval" internally) provides the
+following builtin functions. Scripts can also define |user-function|s.
+
+See |function-list| to browse functions by topic.
(Use CTRL-] on the function name to jump to the full explanation.)
@@ -3543,7 +3546,7 @@ exists({expr}) The result is a Number, which is |TRUE| if {expr} is
string)
*funcname built-in function (see |functions|)
or user defined function (see
- |user-functions|). Also works for a
+ |user-function|). Also works for a
variable that is a Funcref.
varname internal variable (see
|internal-variables|). Also works
@@ -9243,7 +9246,7 @@ Don't forget that "^" will only match at the first character of the String and
"\n".
==============================================================================
-5. Defining functions *user-functions*
+5. Defining functions *user-function*
New functions can be defined. These can be called just like builtin
functions. The function executes a sequence of Ex commands. Normal mode
diff --git a/runtime/doc/if_lua.txt b/runtime/doc/if_lua.txt
index d527a91a93..97d851a20f 100644
--- a/runtime/doc/if_lua.txt
+++ b/runtime/doc/if_lua.txt
@@ -285,7 +285,7 @@ Example: >
Lua tables are used as both dictionaries and lists, so it is impossible to
determine whether empty table is meant to be empty list or empty dictionary.
-Additionally lua does not have integer numbers. To distinguish between these
+Additionally Lua does not have integer numbers. To distinguish between these
cases there is the following agreement:
0. Empty table is empty list.
@@ -300,7 +300,7 @@ cases there is the following agreement:
4. Table with `vim.type_idx` key may be a dictionary, a list or floating-point
value:
- `{[vim.type_idx]=vim.types.float, [vim.val_idx]=1}` is converted to
- a floating-point 1.0. Note that by default integral lua numbers are
+ a floating-point 1.0. Note that by default integral Lua numbers are
converted to |Number|s, non-integral are converted to |Float|s. This
variant allows integral |Float|s.
- `{[vim.type_idx]=vim.types.dictionary}` is converted to an empty
@@ -321,10 +321,10 @@ Examples: >
: endfunction
:echo Rand(1,10)
-Note that currently second argument to `luaeval` undergoes VimL to lua
-conversion, so changing containers in lua do not affect values in VimL. Return
-value is also always converted. When converting, |msgpack-special-dict|s are
-treated specially.
+Note: second argument to `luaeval` undergoes VimL to Lua conversion
+("marshalled"), so changes to Lua containers do not affect values in VimL.
+Return value is also always converted. When converting,
+|msgpack-special-dict|s are treated specially.
==============================================================================
Lua standard modules *lua-stdlib*
@@ -355,22 +355,12 @@ Result is something like this: >
To find documentation on e.g. the "deepcopy" function: >
- :help vim.deepcopy
+ :help vim.deepcopy()
Note that underscore-prefixed functions (e.g. "_os_proc_children") are
internal/private and must not be used by plugins.
------------------------------------------------------------------------------
-VIM.API *lua-api* *vim.api*
-
-`vim.api` exposes the full Nvim |API| as a table of Lua functions.
-
-Example: to use the "nvim_get_current_line()" API function, call
-"vim.api.nvim_get_current_line()": >
-
- print(tostring(vim.api.nvim_get_current_line()))
-
-------------------------------------------------------------------------------
VIM.LOOP *lua-loop* *vim.loop*
`vim.loop` exposes all features of the Nvim event-loop. This is a low-level
@@ -416,20 +406,46 @@ Example: repeating timer
print('sleeping');
+Example: File-change detection *file-change-detect*
+ 1. Save this code to a file.
+ 2. Execute it with ":luafile %".
+ 3. Use ":Watch %" to watch any file.
+ 4. Try editing the file from another text editor.
+ 5. Observe that the file reloads in Nvim (because on_change() calls
+ |:checktime|). >
+
+ local w = vim.loop.new_fs_event()
+ local function on_change(err, fname, status)
+ -- Do work...
+ vim.api.nvim_command('checktime')
+ -- Debounce: stop/start.
+ w:stop()
+ watch_file(fname)
+ end
+ function watch_file(fname)
+ local fullpath = vim.api.nvim_call_function(
+ 'fnamemodify', {fname, ':p'})
+ w:start(fullpath, {}, vim.schedule_wrap(function(...)
+ on_change(...) end))
+ end
+ vim.api.nvim_command(
+ "command! -nargs=1 Watch call luaeval('watch_file(_A)', expand('<args>'))")
+
+
Example: TCP echo-server *tcp-server*
1. Save this code to a file.
2. Execute it with ":luafile %".
3. Note the port number.
4. Connect from any TCP client (e.g. "nc 0.0.0.0 36795"): >
- local function create_server(host, port, on_connection)
+ local function create_server(host, port, on_connect)
local server = vim.loop.new_tcp()
server:bind(host, port)
server:listen(128, function(err)
assert(not err, err) -- Check for errors.
local sock = vim.loop.new_tcp()
server:accept(sock) -- Accept client connection.
- on_connection(sock) -- Start reading messages.
+ on_connect(sock) -- Start reading messages.
end)
return server
end
@@ -477,7 +493,7 @@ it should call `parse()` again. If the buffer wasn't edited, the same tree will
be returned again without extra work. If the buffer was parsed before,
incremental parsing will be done of the changed parts.
-NB: to use the parser directly inside a |nvim_buf_attach| lua callback, you must
+NB: to use the parser directly inside a |nvim_buf_attach| Lua callback, you must
call `get_parser()` before you register your callback. But preferably parsing
shouldn't be done directly in the change callback anyway as they will be very
frequent. Rather a plugin that does any kind of analysis on a tree should use
@@ -552,7 +568,17 @@ tsnode:named_descendant_for_range(start_row, start_col, end_row, end_col)
range of (row, column) positions
------------------------------------------------------------------------------
-VIM *lua-util*
+VIM *lua-builtin*
+
+vim.api.{func}({...}) *vim.api*
+ Invokes Nvim |API| function {func} with arguments {...}.
+ Example: call the "nvim_get_current_line()" API function: >
+ print(tostring(vim.api.nvim_get_current_line()))
+
+vim.call({func}, {...}) *vim.call()*
+ Invokes |vim-function| or |user-function| {func} with arguments {...}.
+ See also |vim.fn|. Equivalent to: >
+ vim.fn[func]({...})
vim.in_fast_event() *vim.in_fast_event()*
Returns true if the code is executing as part of a "fast" event
@@ -588,26 +614,23 @@ vim.schedule({callback}) *vim.schedule()*
Schedules {callback} to be invoked soon by the main event-loop. Useful
to avoid |textlock| or other temporary restrictions.
-vim.fn.{func}({...})
- Call vimL function {func} with arguments. {func} can be both builtin
- functions and user functions. To call autoload functions, use the
- syntax `vim.fn['some#function']({...})`
-
- Note: unlike vim.api.|nvim_call_function| this converts values directly
- between vimL values and lua values. If the vimL function returns a
- float, it will be representeted directly as a lua number. Both empty
- lists and dictonaries will be represented by an empty table.
-
- Note: vim.fn keys are generated on demand. So `pairs(vim.fn)`
- does NOT work to enumerate all functions.
+vim.fn.{func}({...}) *vim.fn*
+ Invokes |vim-function| or |user-function| {func} with arguments {...}.
+ To call autoload functions, use the syntax: >
+ vim.fn['some#function']({...})
+<
+ Unlike vim.api.|nvim_call_function| this converts directly between Vim
+ objects and Lua objects. If the Vim function returns a float, it will
+ be represented directly as a Lua number. Empty lists and dictionaries
+ both are represented by an empty table.
-vim.call({func}, {...})
- Call vim script function {func}. Equivalent to `vim.fn[func]({...})`
+ Note: vim.fn keys are generated lazily, thus `pairs(vim.fn)` only
+ enumerates functions that were called at least once.
vim.type_idx *vim.type_idx*
Type index for use in |lua-special-tbl|. Specifying one of the
values from |vim.types| allows typing the empty table (it is
- unclear whether empty lua table represents empty list or empty array)
+ unclear whether empty Lua table represents empty list or empty array)
and forcing integral numbers to be |Float|. See |lua-special-tbl| for
more details.
@@ -631,7 +654,7 @@ vim.types *vim.types*
`vim.types.array` and `vim.types.dictionary` fall under only two
following assumptions:
1. Value may serve both as a key and as a value in a table. Given the
- properties of lua tables this basically means “value is not `nil`”.
+ properties of Lua tables this basically means “value is not `nil`”.
2. For each value in `vim.types` table `vim.types[vim.types[value]]`
is the same as `value`.
No other restrictions are put on types, and it is not guaranteed that
@@ -653,6 +676,20 @@ paste({lines}, {phase}) *vim.paste()*
Paste handler, invoked by |nvim_paste()| when a conforming UI
(such as the |TUI|) pastes text into the editor.
+ Example: To remove ANSI color codes when pasting: >
+
+ vim.paste = (function()
+ local overridden = vim.paste
+ return function(lines, phase)
+ for i,line in ipairs(lines) do
+ -- Scrub ANSI color codes from paste input.
+ lines[i] = line:gsub('\27%[[0-9;mK]+', '')
+ end
+ overridden(lines, phase)
+ end
+ end)()
+<
+
Parameters: ~
{lines} |readfile()|-style list of lines to paste.
|channel-lines|
diff --git a/runtime/doc/index.txt b/runtime/doc/index.txt
index 7221888074..211b7be2cc 100644
--- a/runtime/doc/index.txt
+++ b/runtime/doc/index.txt
@@ -1170,7 +1170,7 @@ tag command action ~
|:caddfile| :caddf[ile] add error message to current quickfix list
|:call| :cal[l] call a function
|:catch| :cat[ch] part of a :try command
-|:cbelow| :cbe[low] got to error below current line
+|:cbelow| :cbe[low] go to error below current line
|:cbottom| :cbo[ttom] scroll to the bottom of the quickfix window
|:cbuffer| :cb[uffer] parse error messages and jump to first error
|:cc| :cc go to specific error
diff --git a/runtime/doc/motion.txt b/runtime/doc/motion.txt
index 9e24ee0320..e93c833c76 100644
--- a/runtime/doc/motion.txt
+++ b/runtime/doc/motion.txt
@@ -418,35 +418,35 @@ between Vi and Vim.
5. Text object motions *object-motions*
*(*
-( [count] sentences backward. |exclusive| motion.
+( [count] |sentence|s backward. |exclusive| motion.
*)*
-) [count] sentences forward. |exclusive| motion.
+) [count] |sentence|s forward. |exclusive| motion.
*{*
-{ [count] paragraphs backward. |exclusive| motion.
+{ [count] |paragraph|s backward. |exclusive| motion.
*}*
-} [count] paragraphs forward. |exclusive| motion.
+} [count] |paragraph|s forward. |exclusive| motion.
*]]*
-]] [count] sections forward or to the next '{' in the
+]] [count] |section|s forward or to the next '{' in the
first column. When used after an operator, then also
stops below a '}' in the first column. |exclusive|
Note that |exclusive-linewise| often applies.
*][*
-][ [count] sections forward or to the next '}' in the
+][ [count] |section|s forward or to the next '}' in the
first column. |exclusive|
Note that |exclusive-linewise| often applies.
*[[*
-[[ [count] sections backward or to the previous '{' in
+[[ [count] |section|s backward or to the previous '{' in
the first column. |exclusive|
Note that |exclusive-linewise| often applies.
*[]*
-[] [count] sections backward or to the previous '}' in
+[] [count] |section|s backward or to the previous '}' in
the first column. |exclusive|
Note that |exclusive-linewise| often applies.
diff --git a/runtime/doc/options.txt b/runtime/doc/options.txt
index e12a7d4986..52d8624935 100644
--- a/runtime/doc/options.txt
+++ b/runtime/doc/options.txt
@@ -6159,14 +6159,14 @@ A jump table for the options with a short description can be found at |Q_op|.
match Match case
smart Ignore case unless an upper case letter is used
- *'tagfunc'* *'tfu'*
- 'tagfunc' 'tfu' string (default: empty)
- local to buffer
- This option specifies a function to be used to perform tag searches.
- The function gets the tag pattern and should return a List of matching
- tags. See |tag-function| for an explanation of how to write the
- function and an example.
-
+ *'tagfunc'* *'tfu'*
+'tagfunc' 'tfu' string (default: empty)
+ local to buffer
+ This option specifies a function to be used to perform tag searches.
+ The function gets the tag pattern and should return a List of matching
+ tags. See |tag-function| for an explanation of how to write the
+ function and an example.
+
*'taglength'* *'tl'*
'taglength' 'tl' number (default 0)
global
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index 3e1209d1b1..cb74c4227b 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -101,25 +101,39 @@ String buffer_get_line(Buffer buffer, Integer index, Error *err)
return rv;
}
-/// Activates buffer-update events on a channel, or as lua callbacks.
+/// Activates buffer-update events on a channel, or as Lua callbacks.
+///
+/// @see |nvim_buf_detach()|
+/// @see |api-buffer-updates-lua|
///
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
-/// @param send_buffer Set to true if the initial notification should contain
-/// the whole buffer. If so, the first notification will be a
-/// `nvim_buf_lines_event`. Otherwise, the first notification will be
-/// a `nvim_buf_changedtick_event`. Not used for lua callbacks.
+/// @param send_buffer True if the initial notification should contain the
+/// whole buffer: first notification will be `nvim_buf_lines_event`.
+/// Else the first notification will be `nvim_buf_changedtick_event`.
+/// Not for Lua callbacks.
/// @param opts Optional parameters.
-/// - `on_lines`: lua callback received on change.
-/// - `on_changedtick`: lua callback received on changedtick
-/// increment without text change.
-/// - `utf_sizes`: include UTF-32 and UTF-16 size of
-/// the replaced region.
-/// See |api-buffer-updates-lua| for more information
+/// - on_lines: Lua callback invoked on change.
+/// Return `true` to detach. Args:
+/// - buffer handle
+/// - b:changedtick
+/// - first line that changed (zero-indexed)
+/// - last line that was changed
+/// - last line in the updated range
+/// - byte count of previous contents
+/// - deleted_codepoints (if `utf_sizes` is true)
+/// - deleted_codeunits (if `utf_sizes` is true)
+/// - on_changedtick: Lua callback invoked on changedtick
+/// increment without text change. Args:
+/// - buffer handle
+/// - b:changedtick
+/// - on_detach: Lua callback invoked on detach. Args:
+/// - buffer handle
+/// - utf_sizes: include UTF-32 and UTF-16 size of the replaced
+/// region, as args to `on_lines`.
/// @param[out] err Error details, if any
-/// @return False when updates couldn't be enabled because the buffer isn't
-/// loaded or `opts` contained an invalid key; otherwise True.
-/// TODO: LUA_API_NO_EVAL
+/// @return False if attach failed (invalid parameter, or buffer isn't loaded);
+/// otherwise True. TODO: LUA_API_NO_EVAL
Boolean nvim_buf_attach(uint64_t channel_id,
Buffer buffer,
Boolean send_buffer,
@@ -183,13 +197,14 @@ error:
/// Deactivates buffer-update events on the channel.
///
-/// For Lua callbacks see |api-lua-detach|.
+/// @see |nvim_buf_attach()|
+/// @see |api-lua-detach| for detaching Lua callbacks
///
/// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer
/// @param[out] err Error details, if any
-/// @return False when updates couldn't be disabled because the buffer
-/// isn't loaded; otherwise True.
+/// @return False if detach failed (because the buffer isn't loaded);
+/// otherwise True.
Boolean nvim_buf_detach(uint64_t channel_id,
Buffer buffer,
Error *err)
diff --git a/src/nvim/api/vim.c b/src/nvim/api/vim.c
index 59761c13e7..0e64658f36 100644
--- a/src/nvim/api/vim.c
+++ b/src/nvim/api/vim.c
@@ -1040,10 +1040,9 @@ fail:
/// @param enter Enter the window (make it the current window)
/// @param config Map defining the window configuration. Keys:
/// - `relative`: Sets the window layout to "floating", placed at (row,col)
-/// coordinates relative to one of:
+/// coordinates relative to:
/// - "editor" The global editor grid
-/// - "win" Window given by the `win` field, or current window by
-/// default.
+/// - "win" Window given by the `win` field, or current window.
/// - "cursor" Cursor position in current window.
/// - `win`: |window-ID| for relative="win".
/// - `anchor`: Decides which corner of the float to place at (row,col):
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index 5514819a02..adb90084db 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -165,6 +165,20 @@ end
--- Paste handler, invoked by |nvim_paste()| when a conforming UI
--- (such as the |TUI|) pastes text into the editor.
---
+--- Example: To remove ANSI color codes when pasting:
+--- <pre>
+--- vim.paste = (function()
+--- local overridden = vim.paste
+--- return function(lines, phase)
+--- for i,line in ipairs(lines) do
+--- -- Scrub ANSI color codes from paste input.
+--- lines[i] = line:gsub('\27%[[0-9;mK]+', '')
+--- end
+--- overridden(lines, phase)
+--- end
+--- end)()
+--- </pre>
+---
--@see |paste|
---
--@param lines |readfile()|-style list of lines to paste. |channel-lines|
diff --git a/test/functional/lua/utility_functions_spec.lua b/test/functional/lua/utility_functions_spec.lua
index 0b789e84b0..6aeea5fc4f 100644
--- a/test/functional/lua/utility_functions_spec.lua
+++ b/test/functional/lua/utility_functions_spec.lua
@@ -301,7 +301,7 @@ describe('lua stdlib', function()
pcall_err(exec_lua, [[return vim.pesc(2)]]))
end)
- it('vim.call and vim.fn', function()
+ it('vim.call, vim.fn', function()
eq(true, exec_lua([[return vim.call('sin', 0.0) == 0.0 ]]))
eq(true, exec_lua([[return vim.fn.sin(0.0) == 0.0 ]]))
-- compat: nvim_call_function uses "special" value for vimL float
diff --git a/test/functional/terminal/tui_spec.lua b/test/functional/terminal/tui_spec.lua
index 5ac2ffb611..831d3939df 100644
--- a/test/functional/terminal/tui_spec.lua
+++ b/test/functional/terminal/tui_spec.lua
@@ -535,7 +535,7 @@ describe('TUI', function()
|
{4:~ }|
{5: }|
- {8:paste: Error executing lua: vim.lua:197: Vim:E21: }|
+ {8:paste: Error executing lua: vim.lua:211: Vim:E21: }|
{8:Cannot make changes, 'modifiable' is off} |
{10:Press ENTER or type command to continue}{1: } |
{3:-- TERMINAL --} |