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.

Key Map
Sync Mode
Save & Load Highlights One Time Highlight Following Highlight Find in Files Highlight
Customizing Colors
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 and f 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 default 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.

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.

Matching option

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 with Tab 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

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.

Tip

To enter the current file name, typing % Tab would be convenient.

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"
color codes such as: #e3d3b7, #AFD9D9
 :Hi/Find  -i  #[A-F0-9]{6}
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

It will be handy to use keyboard shortcuts for the following commands to easily navigate the search results.

Hi/next and Hi/previous commands jump to the file.

Hi/older and Hi/newer commands navigate the search history.

Key-mapping 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 the Hi/next command invokes a special function that jumps to the first item in the search results. For example, in the mapping above, entering 1- 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 14 + 3 default colors.

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=#af00ff
Now, move the cursor to any word, and then input the number 21 and HiSet key. Does it work? if you press HiSet key again, the next HiColor22 will be set.

You can try different values to change the color, and see the result instantly. You can store colors in the configuration file using this format.

Example 2

The following command changes the color of 'Find in Files Highlight'
 :hi HiFind ctermfg=52 ctermbg=182 guifg=#570707 guibg=#e7bfe7

Reference

This tool will be helpful when editing colors.

xterm-color-table.vim

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

neobundle

Vundle.vim

Vim 8 native

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.

GitHub - azabiong/vim-highlighter: Highlight words and expressions