lua: add options to highlight.on_yank (#12549)

NOTE: Configuration options have  changed for highlight.on_yank.

Check help for |:help highlight.on_yank()|

3 files changed, 41 insertions, 21 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 002fc523a1..0ee63eb523 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -711,25 +711,26 @@ 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()
+ au TextYankPost * silent! lua 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)
+ au TextYankPost * silent! lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
 <
 If you want to exclude visual selections from highlighting on yank, use
 >
-au TextYankPost * silent! lua return (not vim.v.event.visual) and require'vim.highlight'.on_yank()
+ au TextYankPost * silent! lua vim.highlight.on_yank {on_visual=false}
 <
 
-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.highlight.on_yank({opts})                         *vim.highlight.on_yank()*
+        Highlights the yanked text. The fields of the optional dict {opts}
+        control the highlight:
+          - {higroup} highlight group for yanked region (default `"IncSearch"`)
+          - {timeout} time in ms before highlight is cleared (default `150`)
+          - {on_macro} highlight when executing macro (default `false`)
+          - {on_visual} highlight when yanking visual selection (default `true`)
+          - {event} event structure (default `vim.v.event`)
 
 vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclusive})
                                                        *vim.highlight.range()*
@@ -739,7 +740,6 @@ vim.highlight.range({bufnr}, {ns}, {higroup}, {start}, {finish}, {rtype}, {inclu
         or blockwise, see |setreg|; default to characterwise) and whether the
         range is inclusive (default false).
 
-
 ------------------------------------------------------------------------------
 VIM.REGEX							*lua-regex*
 
diff --git a/runtime/lua/vim/highlight.lua b/runtime/lua/vim/highlight.lua
index 69c3c8a4dc..ce0a3de520 100644
--- a/runtime/lua/vim/highlight.lua
+++ b/runtime/lua/vim/highlight.lua
@@ -23,24 +23,41 @@ function highlight.range(bufnr, ns, higroup, start, finish, rtype, inclusive)
 
 end
 
+local yank_ns = api.nvim_create_namespace('hlyank')
 --- Highlight the yanked region
 ---
 --- use from init.vim via
----   au TextYankPost * lua require'vim.highlight'.on_yank()
+---   au TextYankPost * lua vim.highlight.on_yank()
 --- customize highlight group and timeout via
----   au TextYankPost * lua require'vim.highlight'.on_yank("IncSearch", 500)
+---   au TextYankPost * lua vim.highlight.on_yank {higroup="IncSearch", timeout=150}
+--- customize conditions (here: do not highlight a visual selection) via
+---   au TextYankPost * lua vim.highlight.on_yank {on_visual=false}
 ---
--- @param higroup highlight group for yanked region
--- @param timeout time in ms before highlight is cleared
--- @param event event structure
-function highlight.on_yank(higroup, timeout, event)
-  event = event or vim.v.event
+-- @param opts dictionary with options controlling the highlight:
+--              - higroup   highlight group for yanked region (default "IncSearch")
+--              - timeout   time in ms before highlight is cleared (default 150)
+--              - on_macro  highlight when executing macro (default false)
+--              - on_visual highlight when yanking visual selection (default true)
+--              - event     event structure (default vim.v.event)
+function highlight.on_yank(opts)
+  vim.validate {
+    opts = { opts,
+    function(t) if t == nil then return true else return type(t) == 'table' end end,
+    'a table or nil to configure options (see `:h highlight.on_yank`)',
+  }}
+  opts = opts or {}
+  local event = opts.event or vim.v.event
+  local on_macro = opts.on_macro or false
+  local on_visual = (opts.on_visual ~= false)
+
+  if (not on_macro) and vim.fn.reg_executing() ~= '' then return end
   if event.operator ~= 'y' or event.regtype == '' then return end
-  higroup = higroup or "IncSearch"
-  timeout = timeout or 500
+  if (not on_visual) and event.visual then return end
+
+  local higroup = opts.higroup or "IncSearch"
+  local timeout = opts.timeout or 150
 
   local bufnr = api.nvim_get_current_buf()
-  local yank_ns = api.nvim_create_namespace('')
   api.nvim_buf_clear_namespace(bufnr, yank_ns, 0, -1)
 
   local pos1 = vim.fn.getpos("'[")
diff --git a/src/nvim/lua/vim.lua b/src/nvim/lua/vim.lua
index 047ce1ad43..771ec971b7 100644
--- a/src/nvim/lua/vim.lua
+++ b/src/nvim/lua/vim.lua
@@ -288,6 +288,9 @@ local function __index(t, key)
   elseif key == 'lsp' then
     t.lsp = require('vim.lsp')
     return t.lsp
+  elseif key == 'highlight' then
+    t.highlight = require('vim.highlight')
+    return t.highlight
   end
 end