344 lines
11 KiB
Plaintext
344 lines
11 KiB
Plaintext
*illuminate.txt* For NVIM v0.8.0 Last change: 2023 March 19
|
||
|
||
==============================================================================
|
||
Table of Contents *illuminate-table-of-contents*
|
||
|
||
1. Overview |illuminate-overview|
|
||
2. Quickstart |illuminate-quickstart|
|
||
3. Configuration |illuminate-configuration|
|
||
4. Highlight Groups |illuminate-highlight-groups|
|
||
5. Commands |illuminate-commands|
|
||
6. Functions |illuminate-functions|
|
||
7. Vim Users |illuminate-vim-users|
|
||
|
||
==============================================================================
|
||
1. Overview *illuminate-overview*
|
||
|
||
Vim plugin for automatically highlighting other uses of the word under the
|
||
cursor using either LSP, Tree-sitter, or regex matching.
|
||
|
||
|
||
==============================================================================
|
||
2. Quickstart *illuminate-quickstart*
|
||
|
||
Just install the plugin and things will work _just work_, no configuration
|
||
needed.
|
||
|
||
You’ll also get `<a-n>` and `<a-p>` as keymaps to move between references and
|
||
`<a-i>` as a textobject for the reference illuminated under the cursor.
|
||
|
||
|
||
==============================================================================
|
||
3. Configuration *illuminate-configuration*
|
||
|
||
>lua
|
||
-- default configuration
|
||
require('illuminate').configure({
|
||
-- providers: provider used to get references in the buffer, ordered by priority
|
||
providers = {
|
||
'lsp',
|
||
'treesitter',
|
||
'regex',
|
||
},
|
||
-- delay: delay in milliseconds
|
||
delay = 100,
|
||
-- filetype_overrides: filetype specific overrides.
|
||
-- The keys are strings to represent the filetype while the values are tables that
|
||
-- supports the same keys passed to .configure except for filetypes_denylist and filetypes_allowlist
|
||
filetype_overrides = {},
|
||
-- filetypes_denylist: filetypes to not illuminate, this overrides filetypes_allowlist
|
||
filetypes_denylist = {
|
||
'dirvish',
|
||
'fugitive',
|
||
},
|
||
-- filetypes_allowlist: filetypes to illuminate, this is overriden by filetypes_denylist
|
||
filetypes_allowlist = {},
|
||
-- modes_denylist: modes to not illuminate, this overrides modes_allowlist
|
||
-- See `:help mode()` for possible values
|
||
modes_denylist = {},
|
||
-- modes_allowlist: modes to illuminate, this is overriden by modes_denylist
|
||
-- See `:help mode()` for possible values
|
||
modes_allowlist = {},
|
||
-- providers_regex_syntax_denylist: syntax to not illuminate, this overrides providers_regex_syntax_allowlist
|
||
-- Only applies to the 'regex' provider
|
||
-- Use :echom synIDattr(synIDtrans(synID(line('.'), col('.'), 1)), 'name')
|
||
providers_regex_syntax_denylist = {},
|
||
-- providers_regex_syntax_allowlist: syntax to illuminate, this is overriden by providers_regex_syntax_denylist
|
||
-- Only applies to the 'regex' provider
|
||
-- Use :echom synIDattr(synIDtrans(synID(line('.'), col('.'), 1)), 'name')
|
||
providers_regex_syntax_allowlist = {},
|
||
-- under_cursor: whether or not to illuminate under the cursor
|
||
under_cursor = true,
|
||
-- large_file_cutoff: number of lines at which to use large_file_config
|
||
-- The `under_cursor` option is disabled when this cutoff is hit
|
||
large_file_cutoff = nil,
|
||
-- large_file_config: config to use for large files (based on large_file_cutoff).
|
||
-- Supports the same keys passed to .configure
|
||
-- If nil, vim-illuminate will be disabled for large files.
|
||
large_file_overrides = nil,
|
||
-- min_count_to_highlight: minimum number of matches required to perform highlighting
|
||
min_count_to_highlight = 1,
|
||
})
|
||
<
|
||
|
||
|
||
==============================================================================
|
||
4. Highlight Groups *illuminate-highlight-groups*
|
||
|
||
|
||
ILLUMINATEDWORDTEXT
|
||
|
||
Default highlight group used for references if no kind information is
|
||
available.
|
||
|
||
>vim
|
||
hi def IlluminatedWordText gui=underline
|
||
<
|
||
|
||
|
||
ILLUMINATEDWORDREAD
|
||
|
||
Highlight group used for references of kind read.
|
||
|
||
>vim
|
||
hi def IlluminatedWordRead gui=underline
|
||
<
|
||
|
||
|
||
ILLUMINATEDWORDWRITE
|
||
|
||
Highlight group used for references of kind write.
|
||
|
||
>vim
|
||
hi def IlluminatedWordWrite gui=underline
|
||
<
|
||
|
||
|
||
==============================================================================
|
||
5. Commands *illuminate-commands*
|
||
|
||
|
||
:ILLUMINATEPAUSE
|
||
|
||
Globally pause vim-illuminate.
|
||
|
||
|
||
:ILLUMINATERESUME
|
||
|
||
Globally resume vim-illuminate.
|
||
|
||
|
||
:ILLUMINATETOGGLE
|
||
|
||
Globally toggle the pause/resume for vim-illuminate.
|
||
|
||
|
||
:ILLUMINATEPAUSEBUF
|
||
|
||
Buffer-local pause of vim-illuminate.
|
||
|
||
|
||
:ILLUMINATERESUMEBUF
|
||
|
||
Buffer-local resume of vim-illuminate.
|
||
|
||
|
||
:ILLUMINATETOGGLEBUF
|
||
|
||
Buffer-local toggle of the pause/resume for vim-illuminate.
|
||
|
||
|
||
==============================================================================
|
||
6. Functions *illuminate-functions*
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).CONFIGURE(CONFIG)
|
||
|
||
Override the default configuration with `config`
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).PAUSE()
|
||
|
||
Globally pause vim-illuminate.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).RESUME()
|
||
|
||
Globally resume vim-illuminate.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).TOGGLE()
|
||
|
||
Globally toggle the pause/resume for vim-illuminate.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).TOGGLE_BUF()
|
||
|
||
Buffer-local toggle of the pause/resume for vim-illuminate.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).PAUSE_BUF()
|
||
|
||
Buffer-local pause of vim-illuminate.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).RESUME_BUF()
|
||
|
||
Buffer-local resume of vim-illuminate.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).FREEZE_BUF()
|
||
|
||
Freeze the illumination on the buffer, this won’t clear the highlights.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).UNFREEZE_BUF()
|
||
|
||
Unfreeze the illumination on the buffer.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).TOGGLE_FREEZE_BUF()
|
||
|
||
Toggle the frozen state of the buffer.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).INVISIBLE_BUF()
|
||
|
||
Turn off the highlighting for the buffer, this won’t stop the engine from
|
||
running so you can still use `<c-n>` and `<c-p>`.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).VISIBLE_BUF()
|
||
|
||
Turn on the highlighting for the buffer, this is only needed if you’ve
|
||
previous called `require('illuminate').invisible_buf()`.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).TOGGLE_VISIBILITY_BUF()
|
||
|
||
Toggle the visibility of highlights in the buffer.
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).GOTO_NEXT_REFERENCE(WRAP)
|
||
|
||
Move the cursor to the closest references after the cursor which it is not
|
||
currently on. Wraps the buffer if on the last reference.
|
||
|
||
Wraps the references unless `wrap` is false (defaults to **‘wrapscan’**).
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).GOTO_PREV_REFERENCE(WRAP)
|
||
|
||
Move the cursor to the closest references before the cursor which it is not
|
||
currently on. Wraps the buffer if on the first reference.
|
||
|
||
Wraps the references unless `wrap` is false (defaults to **‘wrapscan’**).
|
||
|
||
|
||
REQUIRE(‘ILLUMINATE’).TEXTOBJ_SELECT()
|
||
|
||
Selects the reference the cursor is currently on for use as a text-object.
|
||
|
||
|
||
==============================================================================
|
||
7. Vim Users *illuminate-vim-users*
|
||
|
||
**Note:** This section is deprecated for Neovim users, Neovim users can use the
|
||
newer version of the plugin. Neovim users can force this old version of the
|
||
plugin by adding `let g:Illuminate_useDeprecated = 1` to their `init.vim`.
|
||
|
||
Illuminate will delay before highlighting, this is not lag, it is to avoid the
|
||
jarring experience of things illuminating too fast. This can be controlled with
|
||
`g:Illuminate_delay` (which is default to 0 milliseconds):
|
||
|
||
**Note**: Delay only works for Vim8 and Neovim.
|
||
|
||
>vim
|
||
" Time in milliseconds (default 0)
|
||
let g:Illuminate_delay = 0
|
||
<
|
||
|
||
Illuminate will by default highlight the word under the cursor to match the
|
||
behaviour seen in Intellij and VSCode. However, to make it not highlight the
|
||
word under the cursor, use the following:
|
||
|
||
>vim
|
||
" Don't highlight word under cursor (default: 1)
|
||
let g:Illuminate_highlightUnderCursor = 0
|
||
<
|
||
|
||
By default illuminate will highlight all words the cursor passes over, but for
|
||
many languages, you will only want to highlight certain highlight-groups. You
|
||
can determine the highlight-group of a symbol under your cursor with `:echo
|
||
synIDattr(synID(line("."), col("."), 1), "name")`.
|
||
|
||
You can define which highlight groups you want the illuminating to apply to.
|
||
This can be done with a dict mapping a filetype to a list of highlight-groups
|
||
in your vimrc such as:
|
||
|
||
>vim
|
||
let g:Illuminate_ftHighlightGroups = {
|
||
\ 'vim': ['vimVar', 'vimString', 'vimLineComment',
|
||
\ 'vimFuncName', 'vimFunction', 'vimUserFunc', 'vimFunc']
|
||
\ }
|
||
<
|
||
|
||
A blacklist of highlight groups can also be setup by adding the suffix
|
||
`:blacklist` to the filetype. However, if the whitelist for that filetype
|
||
already exists, it will override the blacklist.
|
||
|
||
>vim
|
||
let g:Illuminate_ftHighlightGroups = {
|
||
\ 'vim:blacklist': ['vimVar', 'vimString', 'vimLineComment',
|
||
\ 'vimFuncName', 'vimFunction', 'vimUserFunc', 'vimFunc']
|
||
\ }
|
||
<
|
||
|
||
illuminate can also be disabled for various filetypes using the following:
|
||
|
||
>vim
|
||
let g:Illuminate_ftblacklist = ['nerdtree']
|
||
<
|
||
|
||
Or you can enable it only for certain filetypes with:
|
||
|
||
>vim
|
||
let g:Illuminate_ftwhitelist = ['vim', 'sh', 'python']
|
||
<
|
||
|
||
By default the highlighting will be done with the highlight-group `CursorLine`
|
||
since that is in my opinion the nicest. It can however be overridden using the
|
||
following (use standard Vim highlighting syntax): Note: It must be in an
|
||
autocmd to get around a weird Neovim behaviour.
|
||
|
||
>vim
|
||
augroup illuminate_augroup
|
||
autocmd!
|
||
autocmd VimEnter * hi link illuminatedWord CursorLine
|
||
augroup END
|
||
|
||
augroup illuminate_augroup
|
||
autocmd!
|
||
autocmd VimEnter * hi illuminatedWord cterm=underline gui=underline
|
||
augroup END
|
||
<
|
||
|
||
Lastly, you can also specify a specific highlight for the word under the cursor
|
||
so it differs from all other matches using the following higlight group:
|
||
|
||
>vim
|
||
augroup illuminate_augroup
|
||
autocmd!
|
||
autocmd VimEnter * hi illuminatedCurWord cterm=italic gui=italic
|
||
augroup END
|
||
<
|
||
|
||
==============================================================================
|
||
8. Links *illuminate-links*
|
||
|
||
1. *gif*: https://media.giphy.com/media/mSG0nwAHDt3Fl7WyoL/giphy.gif
|
||
|
||
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
|
||
|
||
vim:tw=78:ts=8:noet:ft=help:norl:
|