mini-cursorword.txt

*mini.cursorword* Autohighlight word under cursor
*MiniCursorword*

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` - 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, modify it directly with |:highlight|.

# 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()')
<
------------------------------------------------------------------------------
                                                        *MiniCursorword.setup()*
                        `MiniCursorword.setup`({config})
Module setup

Parameters ~
{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.config*
                            `MiniCursorword.config`
Module config

Default values:
>lua
  MiniCursorword.config = {
    -- Delay (in ms) between when cursor moved and when highlighting appeared
    delay = 100,
  }
<

 vim:tw=78:ts=8:noet:ft=help:norl: