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

runtime/lua/vim/highlight.lua

@@ -0,0 +1,41 @@
+local api = vim.api
+
+local highlight = {}
+
+--- Highlight the yanked region
+--
+--- use from init.vim via
+---   au TextYankPost * lua require'vim.highlight'.on_yank()
+--- customize highlight group and timeout via
+---   au TextYankPost * lua require'vim.highlight'.on_yank("IncSearch", 500)
+-- @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
+  if event.operator ~= 'y' or event.regtype == '' then return end
+  higroup = higroup or "IncSearch"
+  timeout = timeout or 500
+
+  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("'[")
+  local pos2 = vim.fn.getpos("']")
+
+  pos1 = {pos1[2] - 1, pos1[3] - 1 + pos1[4]}
+  pos2 = {pos2[2] - 1, pos2[3] - 1 + pos2[4]}
+
+  local region = vim.region(bufnr, pos1, pos2, event.regtype, event.inclusive)
+  for linenr, cols in pairs(region) do
+    api.nvim_buf_add_highlight(bufnr, yank_ns, higroup, linenr, cols[1], cols[2])
+  end
+
+  vim.defer_fn(
+    function() api.nvim_buf_clear_namespace(bufnr, yank_ns, 0, -1) end,
+    timeout
+  )
+end
+
+return highlight