retrovim 0.0.3

package/nvim/plugins/mini.nvim/lua/mini/cursorword.lua

@@ -0,0 +1,311 @@
+--- *mini.cursorword* Autohighlight word under cursor
+---
+--- MIT License Copyright (c) 2021 Evgeni Chasnovski
+
+--- Features:
+--- - Autohighlight word under cursor with customizable delay.
+---
+--- - Current word under cursor can be highlighted differently.
+---
+--- - Highlighting is triggered only if current cursor character is a |[:keyword:]|.
+---
+--- - Highlighting stops in insert and terminal modes.
+---
+--- - "Word under cursor" is meant as in Vim's |<cword>|: something user would
+---   get as |iw| text object.
+---
+--- # Setup ~
+---
+--- This module needs a setup with `require('mini.cursorword').setup({})`
+--- (replace `{}` with your `config` table). It will create global Lua table
+--- `MiniCursorword` which you can use for scripting or manually (with
+--- `:lua MiniCursorword.*`).
+---
+--- See |MiniCursorword.config| for `config` structure and default values.
+---
+--- You can override runtime config settings locally to buffer inside
+--- `vim.b.minicursorword_config` which should have same structure as
+--- `MiniCursorword.config`. See |mini.nvim-buffer-local-config| for more details.
+---
+--- # Highlight groups ~
+--- *MiniCursorword-hl-groups*
+---
+--- - `MiniCursorword` - highlight group of a non-current cursor word.
+---   Default: plain underline.
+---
+--- - `MiniCursorwordCurrent` - highlight group of a current word under cursor.
+---   Default: links to `MiniCursorword` (so `:hi clear MiniCursorwordCurrent`
+---   will lead to showing `MiniCursorword` highlight group).
+---   Note: To not highlight it, use the following Lua code: >lua
+---
+---   vim.api.nvim_set_hl(0, 'MiniCursorwordCurrent', {})
+--- <
+--- To change any highlight group, set it directly with |nvim_set_hl()|.
+---
+--- # Disabling ~
+---
+--- To disable core functionality, set `vim.g.minicursorword_disable` (globally) or
+--- `vim.b.minicursorword_disable` (for a buffer) to `true`. Considering high
+--- number of different scenarios and customization intentions, writing exact
+--- rules for disabling module's functionality is left to user. See
+--- |mini.nvim-disabling-recipes| for common recipes. Note: after disabling
+--- there might be highlighting left; it will be removed after next
+--- highlighting update.
+---
+--- Module-specific disabling:
+--- - Don't show highlighting if cursor is on the word that is in a blocklist
+---   of current filetype. In this example, blocklist for "lua" is "local" and
+---   "require" words, for "javascript" - "import": >lua
+---
+---   _G.cursorword_blocklist = function()
+---     local curword = vim.fn.expand('<cword>')
+---     local filetype = vim.bo.filetype
+---
+---     -- Add any disabling global or filetype-specific logic here
+---     local blocklist = {}
+---     if filetype == 'lua' then
+---       blocklist = { 'local', 'require' }
+---     elseif filetype == 'javascript' then
+---       blocklist = { 'import' }
+---     end
+---
+---     vim.b.minicursorword_disable = vim.tbl_contains(blocklist, curword)
+---   end
+---
+---   -- Make sure to add this autocommand *before* calling module's `setup()`.
+---   vim.cmd('au CursorMoved * lua _G.cursorword_blocklist()')
+--- <
+---@tag MiniCursorword
+
+-- Module definition ==========================================================
+local MiniCursorword = {}
+local H = {}
+
+--- Module setup
+---
+---@param config table|nil Module config table. See |MiniCursorword.config|.
+---
+---@usage >lua
+---   require('mini.cursorword').setup() -- use default config
+---   -- OR
+---   require('mini.cursorword').setup({}) -- replace {} with your config table
+--- <
+MiniCursorword.setup = function(config)
+  -- TODO: Remove after Neovim=0.9 support is dropped
+  if vim.fn.has('nvim-0.10') == 0 then
+    vim.notify(
+      '(mini.cursorword) Neovim<0.10 is soft deprecated (module works but is not supported).'
+        .. " It will be deprecated after the next 'mini.nvim' release (module might not work)."
+        .. ' Please update your Neovim version.'
+    )
+  end
+
+  -- Export module
+  _G.MiniCursorword = MiniCursorword
+
+  -- Setup config
+  config = H.setup_config(config)
+
+  -- Apply config
+  H.apply_config(config)
+
+  -- Define behavior
+  H.create_autocommands()
+
+  -- Create default highlighting
+  H.create_default_hl()
+end
+
+--- Defaults ~
+---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
+MiniCursorword.config = {
+  -- Delay (in ms) between when cursor moved and when highlighting appeared
+  delay = 100,
+}
+--minidoc_afterlines_end
+
+-- Module functionality =======================================================
+
+-- Helper data ================================================================
+-- Module default config
+H.default_config = vim.deepcopy(MiniCursorword.config)
+
+-- Delay timer
+H.timer = vim.loop.new_timer()
+
+-- Information about last match highlighting (stored *per window*):
+-- - Key: windows' unique buffer identifiers.
+-- - Value: table with:
+--     - `id` field for match id (from `vim.fn.matchadd()`).
+--     - `word` field for matched word.
+H.window_matches = {}
+
+-- Helper functionality =======================================================
+-- Settings -------------------------------------------------------------------
+H.setup_config = function(config)
+  H.check_type('config', config, 'table', true)
+  config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})
+
+  H.check_type('delay', config.delay, 'number')
+
+  return config
+end
+
+H.apply_config = function(config)
+  MiniCursorword.config = config
+
+  -- Make `setup()` to proper reset module
+  for _, m in ipairs(vim.fn.getmatches()) do
+    if vim.startswith(m.group, 'MiniCursorword') then vim.fn.matchdelete(m.id) end
+  end
+end
+
+H.create_autocommands = function()
+  local gr = vim.api.nvim_create_augroup('MiniCursorword', {})
+
+  local au = function(event, pattern, callback, desc)
+    vim.api.nvim_create_autocmd(event, { group = gr, pattern = pattern, callback = callback, desc = desc })
+  end
+
+  au('CursorMoved', '*', H.auto_highlight, 'Auto highlight cursorword')
+  au({ 'InsertEnter', 'TermEnter', 'QuitPre' }, '*', H.auto_unhighlight, 'Auto unhighlight cursorword')
+  au('ModeChanged', '*:[^i]', H.auto_highlight, 'Auto highlight cursorword')
+
+  au('ColorScheme', '*', H.create_default_hl, 'Ensure colors')
+  au('FileType', 'TelescopePrompt', function() vim.b.minicursorword_disable = true end, 'Disable locally')
+end
+
+--stylua: ignore
+H.create_default_hl = function()
+  vim.api.nvim_set_hl(0, 'MiniCursorword',        { default = true, underline = true })
+  vim.api.nvim_set_hl(0, 'MiniCursorwordCurrent', { default = true, link = 'MiniCursorword' })
+end
+
+H.is_disabled = function() return vim.g.minicursorword_disable == true or vim.b.minicursorword_disable == true end
+
+H.get_config = function(config)
+  return vim.tbl_deep_extend('force', MiniCursorword.config, vim.b.minicursorword_config or {}, config or {})
+end
+
+-- Autocommands ---------------------------------------------------------------
+H.auto_highlight = function()
+  -- Stop any possible previous delayed highlighting
+  H.timer:stop()
+
+  -- Stop highlighting immediately if module is disabled when cursor is not on
+  -- 'keyword'
+  if not H.should_highlight() then return H.unhighlight() end
+
+  -- Get current information
+  local win_id = vim.api.nvim_get_current_win()
+  local win_match = H.window_matches[win_id] or {}
+  local curword = H.get_cursor_word()
+
+  -- Only immediately update highlighting of current word under cursor if
+  -- currently highlighted word equals one under cursor
+  if win_match.word == curword then
+    H.unhighlight(true)
+    H.highlight(true)
+    return
+  end
+
+  -- Stop highlighting previous match (if it exists)
+  H.unhighlight()
+
+  -- Delay highlighting
+  H.timer:start(
+    H.get_config().delay,
+    0,
+    vim.schedule_wrap(function()
+      -- Ensure that always only one word is highlighted
+      H.unhighlight()
+      H.highlight()
+    end)
+  )
+end
+
+H.auto_unhighlight = function()
+  -- Stop any possible previous delayed highlighting
+  H.timer:stop()
+  H.unhighlight()
+end
+
+-- Highlighting ---------------------------------------------------------------
+---@param only_current boolean|nil Whether to forcefully highlight only current word
+---   under cursor.
+---@private
+H.highlight = function(only_current)
+  -- A modified version of https://stackoverflow.com/a/25233145
+  -- Using `matchadd()` instead of a simpler `:match` to tweak priority of
+  -- 'current word' highlighting: with `:match` it is higher than for
+  -- `incsearch` which is not convenient.
+  local win_id = vim.api.nvim_get_current_win()
+  if not vim.api.nvim_win_is_valid(win_id) then return end
+
+  if not H.should_highlight() then return end
+
+  H.window_matches[win_id] = H.window_matches[win_id] or {}
+
+  -- Add match highlight for current word under cursor
+  local current_word_pattern = [[\k*\%#\k*]]
+  local match_id_current = vim.fn.matchadd('MiniCursorwordCurrent', current_word_pattern, -1)
+  H.window_matches[win_id].id_current = match_id_current
+
+  -- Don't add main match id if not needed or if one is already present
+  if only_current or H.window_matches[win_id].id ~= nil then return end
+
+  -- Add match highlight for non-current word under cursor. NOTEs:
+  -- - Using `\(...\)\@!` allows to not match current word.
+  -- - Using 'very nomagic' ('\V') allows not escaping.
+  -- - Using `\<` and `\>` matches whole word (and not as part).
+  local curword = H.get_cursor_word()
+  local pattern = string.format([[\(%s\)\@!\&\V\<%s\>]], current_word_pattern, curword)
+  local match_id = vim.fn.matchadd('MiniCursorword', pattern, -1)
+
+  -- Store information about highlight
+  H.window_matches[win_id].id = match_id
+  H.window_matches[win_id].word = curword
+end
+
+---@param only_current boolean|nil Whether to remove highlighting only of current
+---   word under cursor.
+---@private
+H.unhighlight = function(only_current)
+  -- Don't do anything if there is no valid information to act upon
+  local win_id = vim.api.nvim_get_current_win()
+  local win_match = H.window_matches[win_id]
+  if not vim.api.nvim_win_is_valid(win_id) or win_match == nil then return end
+
+  -- Use `pcall` because there is an error if match id is not present. It can
+  -- happen if something else called `clearmatches`.
+  pcall(vim.fn.matchdelete, win_match.id_current)
+  H.window_matches[win_id].id_current = nil
+
+  if not only_current then
+    pcall(vim.fn.matchdelete, win_match.id)
+    H.window_matches[win_id] = nil
+  end
+end
+
+H.should_highlight = function() return not H.is_disabled() and H.is_cursor_on_keyword() end
+
+-- Utilities ------------------------------------------------------------------
+H.error = function(msg) error('(mini.cursorword) ' .. msg, 0) end
+
+H.check_type = function(name, val, ref, allow_nil)
+  if type(val) == ref or (ref == 'callable' and vim.is_callable(val)) or (allow_nil and val == nil) then return end
+  H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
+end
+
+H.is_cursor_on_keyword = function()
+  local col = vim.fn.col('.')
+  local curchar = vim.api.nvim_get_current_line():sub(col, col)
+
+  -- Use `pcall()` to catch `E5108` (can happen in binary files, see #112)
+  local ok, match_res = pcall(vim.fn.match, curchar, '[[:keyword:]]')
+  return ok and match_res >= 0
+end
+
+H.get_cursor_word = function() return vim.fn.escape(vim.fn.expand('<cword>'), [[\/]]) end
+
+return MiniCursorword