lua: Add highlight.on_yank (#12279)

* add lua function to highlight yanked region

* extract namespace, better naming, default values

* add default for event argument

* free timer

* factor out mark to position calculation

* d'oh

* make sure timer stops before callback (cf. luv example)

* factor out timer, more documentation

* fixup

* validate function argument for schedule

* fix block selection past eol

* correct handling of multibyte characters

* move arguments around, some cleanup

* move utility functions to vim.lua

* use anonymous namespaces, avoid local api

* rename function

* add test for schedule_fn

* fix indent

* turn hl-yank into proper (hightlight) module

* factor out position-to-region function

mark extraction now part of highlight.on_yank

* rename schedule_fn to defer_fn

* add test for vim.region

* todo: handle double-width characters

* remove debug printout

* do not shadow arguments

* defer also callable table

* whitespace change

* move highlight to vim/highlight.lua

* add documentation

* add @return documentation

* test: add check before vim.defer fires

* doc: fixup

2 files changed, 33 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 09034353a3..2b83c35c90 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -693,6 +693,27 @@ identical identifiers, highlighting both as |hl-WarningMsg|: >
      (eq? @WarningMsg.left @WarningMsg.right))
 
 ------------------------------------------------------------------------------
+VIM.HIGHLIGHT                  				*lua-highlight*
+
+Nvim includes a function for highlighting a selection on yank (see for example
+https://github.com/machakann/vim-highlightedyank). To enable it, add
+>
+ au TextYankPost * silent! lua require'vim.highlight'.on_yank()
+<
+to your `init.vim`. You can customize the highlight group and the duration of
+the highlight via
+>
+ au TextYankPost * silent! lua require'vim.highlight'.on_yank("IncSearch", 500)
+<
+
+vim.highlight.on_yank([{higroup}, {timeout}, {event}]) 
+                                                    *vim.highlight.on_yank()*
+        Highlights the yanked text. Optional arguments are the highlight group
+        to use ({higroup}, default `"IncSearch"`), the duration of highlighting
+        in milliseconds ({timeout}, default `500`), and the event structure 
+        that is fired ({event}, default `vim.v.event`).
+
+------------------------------------------------------------------------------
 VIM.REGEX							*lua-regex*
 
 Vim regexes can be used directly from lua. Currently they only allow
@@ -758,6 +779,14 @@ vim.empty_dict()					    *vim.empty_dict()*
 	Note: if numeric keys are added to the table, the metatable will be
 	ignored and the dict converted to a list/array anyway.
 
+vim.region({bufnr}, {pos1}, {pos2}, {type}, {inclusive})       *vim.region()*
+        Converts a selection specified by the buffer ({bufnr}), starting
+        position ({pos1}, a zero-indexed pair `{line1,column1}`), ending
+        position ({pos2}, same format as {pos1}), the type of the register
+        for the selection ({type}, see |regtype|), and a boolean indicating
+        whether the selection is inclusive or not, into a zero-indexed table 
+        of linewise selections of the form `{linenr = {startcol, endcol}}` .
+
 vim.rpcnotify({channel}, {method}[, {args}...])		    *vim.rpcnotify()*
 	Sends {event} to {channel} via |RPC| and returns immediately.
 	If {channel} is 0, the event is broadcast to all channels.
diff --git a/runtime/doc/vim_diff.txt b/runtime/doc/vim_diff.txt
index 376375e4ef..24b562543e 100644
--- a/runtime/doc/vim_diff.txt
+++ b/runtime/doc/vim_diff.txt
@@ -116,6 +116,10 @@ backwards-compatibility cost. Some examples:
 - Directories for 'directory' and 'undodir' are auto-created.
 - Terminal features such as 'guicursor' are enabled where possible.
 
+Some features are built in that otherwise required external plugins:
+
+- Highlighting the yanked region, see |lua-highlight|.
+
 ARCHITECTURE ~
 
 External plugins run in separate processes. |remote-plugin| This improves