Vim Highlighter
Introduction
Highlighting keywords or lines can be useful when analyzing code, reviewing summaries, and quickly comparing spellings. This plugin extends Vim's highlighting capabilities with additional features such as saving and loading highlights, finding variables, and customizing colors.
Contents
Key Map
Sync Mode
Save & Load Highlights
One Time Highlight
Following Highlight
Find in Files Highlight
Customizing Colors
Configuration
Installation
Key Map
The plugin uses the following default key mappings which you can assign in the configuration file.
let HiSet = 'f<CR>' " normal, visual
let HiErase = 'f<BS>' " normal, visual
let HiClear = 'f<C-L>' " normal
let HiFind = 'f<Tab>' " normal, visual
Default key mappings:
f Enter
,f Backspace
,f Ctrl+L
andf Tab
In normal mode, HiSet
and HiErase
keys set or erase highlights of the word under the cursor. HiClear
key clears all highlights.
Visual Selection
In visual mode, the highlight is selected as a pattern from the selection and applied to other words.
You can also select an entire line and highlight it.
Sync Mode
You can synchronize highlighting of the current window with other split windows with the command:
:Hi ==
and switch back to single window highlighting mode using:
:Hi =
'Sync Mode' applies to all windows in the current tab-page, and can be set differently for each tab-page.
Save & Load Highlights
Sometimes when you want to save highlights of the current window and reload them next time, you can use:
:Hi save
and when loading:
:Hi load
You can name the file when saving, and use tab-completion when loading. For example:
:Hi save name
:Hi load <Tab>
Highlight files are stored in a user configurable HiKeywords
directory. To browse and manage files in the directory, you can open netrw using the command:
:Hi ls
You can also use relative paths. For example, to save and load a highlight file in the current directory:
:Hi save ./name
:Hi load ./<Tab>
One Time Highlight
The plugin has an automatic feature to clear highlights after use. This can be useful when you only need one quick scan from the cursor position.
When the cursor is over a word or visual selection that is not highlighted, pressing HiErase
key sets 'One Time Highlight'. The highlight stays on while the cursor is not moving, and automatically turns off after the cursor moves.
'One Time Highlight' displays matches in all windows of the current tab-page.
Following Highlight
When you need automatic matching based on cursor movement, 'Following Highlight' mode can be useful.
Pressing HiSet
key over 'One Time Highlight' without moving the cursor sets 'Following Highlight' mode.
The highlight follows the cursor. Pressing HiEarase
key turns off the mode.
'Following Highlight' displays matches in all windows of the current tab-page.
cWORD matching
Sometimes, when comparing variables consisting of letters and symbols, Vim's <cWORD>
matching option can be useful.
The following command toggles between the default <cword>
and <cWORD>
matching options:
:Hi <>
Find in Files Highlight
If you have installed hi-performance search tools such as ag, rg, ack, sift, or grep, the plugin can run it when looking for symbols based on the current directory. And when the given expression is simple, the plugin can highlight patterns to make them easier to find.
HiFind
key brings up the Find command prompt.
The new version uses the
Hi/Find
command prompt withTab
key completion support.
Search tool
If one of the tools listed above is in the $PATH, the plugin can run it using default options. You can set your preferred tool and options in the HiFindTool
variable. For example:
let HiFindTool = 'grep -H -EnrI --exclude-dir=.git'
Tools
let HiFindTool = 'ag --nocolor --noheading --column --nobreak'
let HiFindTool = 'rg -H --color=never --no-heading --column --smart-case'
let HiFindTool = 'ack -H --nocolor --noheading --column --smart-case'
let HiFindTool = 'sift --no-color --line-number --column --binary-skip --git --smart-case'
let HiFindTool = 'ggrep -H -EnrI --exclude-dir=.git'
let HiFindTool = 'git grep -EnI --no-color --column'
Input
You can use general order of passing arguments to search tools:
:Hi/Find [options] expression [directories_or_files]
Tab
key completion for long options, directory and file names is supported.
Expression
Among various regular expression options in Vim, the plugin uses "very magic" style syntax which uses the standard regex syntax with fewer escape sequences.
Examples
searching for "red" or "blue":
:Hi/Find red|blue
pattern with spaces:
:Hi/Find "pattern with spaces"
class types or variables that start with an uppercase letter A or S: Array, Set, String, Symbol...
:Hi/Find \b[AS]\w+
Fixed string or Literal option
This option treats the input as a literal string, which is useful when searching for codes with symbols.
ag, rg, grep, git -F --fixed-strings ack, sift -Q --literal
Example: searching for
item[i+1].size() * 2
:Hi/Find -F 'item[i+1].size() * 2'
Visual selection
When searching for parts of a string in a file as is, visual selection would be useful.
After selecting the part, press HiFind
key. The plugin will escape the pattern properly.
Navigation
Hi/next
and Hi/previous
commands jump to files from search results.
Hi/older
and Hi/newer
commands navigate the search history.
It will be handy to use keyboard shortcuts for these commands to easily navigate the search results. For example:
nn <silent>- :<C-U> Hi/next<CR>
nn <silent>_ :<C-U> Hi/previous<CR>
nn f<Left> :<C-U> Hi/older<CR>
nn f<Right> :<C-U> Hi/newer<CR>
🍏 Tip
Pressing the number
1
before theHi/next
command invokes a special function that jumps to the first item in the search results. For example, in the mapping above, entering1-
will jump to the first item.
Find window
The following keys and functions are available in the Find window.
key | function |
---|---|
Ctrl+C | Stop searching |
r | Rotate Find window |
s | Split and Jump to file |
Enter | Jump to file |
Windows Unicode
The following option may be useful for correctly displaying Unicode characters output.
:set encoding=utf-8
Customizing Colors
The plugin provides two default color sets which are automatically loaded based on the current background
mode.
You can add, change, reorder, and save colors using Vim's native hi
command, and see the changes in real time.
Example 1
This example adds two custom colors in 256 or 24-bit colors mode.
If the plugin is installed and working, copy the following lines one by one, and then run it in the Vim's command window.
:hi HiColor21 ctermfg=20 ctermbg=159 guifg=#0000df guibg=#afffff :hi HiColor22 ctermfg=228 ctermbg=129 guifg=#ffff87 guibg=#af00ffNow, move the cursor to any word, and then input the number
21
andHiSet
key. Does it work? if you pressHiSet
key again, the nextHiColor22
will be set. You can try different values while seeing the results immediately.
Example 2
The following command changes the color of 'Find in Files Highlight'
:hi HiFind ctermfg=52 ctermbg=182 guifg=#570707 guibg=#e7bfe7
Reference
The following tools will be useful when editing colors.
Saving colors
Highlight colors can be saved in the configuration file or color scheme file using the format above.
Configuration Examples
Basic
" Unicode set encoding=utf-8 " default key mappings " let HiSet = 'f<CR>' " let HiErase = 'f<BS>' " let HiClear = 'f<C-L>' " let HiFind = 'f<Tab>' " find key mappings nn <silent>- :<C-U> Hi/next<CR> nn <silent>_ :<C-U> Hi/previous<CR> nn f<Left> :<C-U> Hi/older<CR> nn f<Right> :<C-U> Hi/newer<CR> " command abbreviations ca HL Hi:load ca HS Hi:save " directory to store highlight files " let HiKeywords = '~/.vim/after/vim-highlighter' " highlight colors " hi HiColor21 ctermfg=52 ctermbg=181 guifg=#8f5f5f guibg=#d7cfbf cterm=bold gui=bold " hi HiColor22 ctermfg=254 ctermbg=246 guifg=#e7efef guibg=#979797 cterm=bold gui=bold " hi HiColor30 ctermfg=none cterm=bold guifg=none gui=bold
Color scheme
Highlight colors can also be included in a unified color scheme theme or saved as a separate file in your colors directory.~/.vim/colors
or~/vimfiles/colors
For example, you can create a 'sample.vim' file in the colors directory, and store some colors:hi HiColor21 ctermfg=52 ctermbg=181 guifg=#8f5f5f guibg=#d7cfbf cterm=bold gui=bold hi HiColor22 ctermfg=254 ctermbg=246 guifg=#e7efef guibg=#979797 cterm=bold gui=bold hi HiColor30 ctermfg=none cterm=bold guifg=none gui=boldYou can now load colors using the
colorscheme
command::colorscheme sample
Multifunction keys
Some find keys can be defined as multifunctional using theHiFind()
function.The
HiFind()
function returns whether the Find window is visible, and can be used to define optional actions based on its state. The following example defines the_
andf-
keys to execute the Hi command while the Find window is visible, otherwise execute the original function." find key mappings nn <silent>_ :<C-U> call <SID>HiOptional('previous', '_')<CR> nn <silent>f- :<C-U> call <SID>HiOptional('close', 'f-')<CR> function s:HiOptional(cmd, key) if HiFind() exe "Hi" a:cmd else exe "normal!" a:key endif endfunction
Help tags
For more information about commands and options, please refer to:
:h HI
Installation
There are several options. Please choose your convenient way.
vim-plug
in the Vim's command window::Plug 'azabiong/vim-highlighter' :PlugInstall
copy the first line, and then insert it between the following section in your configuration file.
call plug#begin() call plug#end()
neobundle
in the Vim's command window::NeoBundle 'azabiong/vim-highlighter' :NeoBundleInstall
copy the first line, and then insert it between the following section in your configuration file.
call neobundle#begin() call neobundle#end()
Vundle.vim
in the Vim's command window::Plugin 'azabiong/vim-highlighter' :PluginInstallcopy the first line, and then insert it between the following section in your configuration file.
call vundle#begin() call vundle#end()
Vim 8 native
default install directory:
Linux, Mac Windows ~/.vim ~/vimfiles in the terminal:
cd ~/.vim && git clone --depth=1 https://github.com/azabiong/vim-highlighter.git pack/azabiong/start/vim-highlighter cd ~/.vim && vim -u NONE -c "helptags pack/azabiong/start/vim-highlighter/doc" -c q
Tested
Linux Vim 8.2
Windows gVim 8.2
Mac neovim 0.4.4 macVim 8.2
Issues
If you have any issues that need fixing, comments or new features you would like to add, please feel free to open an issue.
License
MIT