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 jump to highlights, saving and loading, finding patterns, and customizing colors.

   Installation
   Key Map
   Sync Mode
   Jump to Highlights     Save & Load     One Time Highlight     Following Highlight    Find in Files Highlight
   Customizing Colors
   Configuration

What's New

version	feature	key map
1.52	Find window View `i`	O
1.50	Jump to Highlights	O
1.38	Input patterns in the command-line
1.35	Multifunction keys when using Find	O

Installation

You can use your preferred plugin manager using the string 'azabiong/vim-highlighter'. For example:

  Plug 'azabiong/vim-highlighter'

or, Vim 8 pack feature:

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

Key Map

The plugin uses the following default key mappings which you can assign in the configuration file.

  let HiSet   = 'f<CR>'
  let HiErase = 'f<BS>'
  let HiClear = 'f<C-L>'
  let HiFind  = 'f<Tab>'

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 partial pattern from the selection and applied to other words.

visual

You can also select an entire line and highlight it.

visual_line

Input

To set highlights using a pattern:

 :Hi + pattern

Sync Mode

When you want to synchronize highlighting of the current window with other split windows, you can use:

 :Hi ==

and to switch back to single window highlighting mode:

 :Hi =

'Sync Mode' applies to all windows in the current tab-page, and can be set differently for each tab-page.

Jump to Highlights

The plugin supports jumping to highlights using two sets of commands.

The Hi < and Hi > commands move the cursor back and forth to recently highlighted words or matching highlights at the cursor position.

The Hi { and Hi } commands, on the other hand, move the cursor to the nearest highlighted word, even if the pattern differs from the current selection.

jump

It will be handy to use key mappings for these commands. For example:

  nn <CR>   <Cmd>Hi><CR>
  nn g<CR>  <Cmd>Hi<<CR>
  nn [<CR>  <Cmd>Hi{<CR>
  nn ]<CR>  <Cmd>Hi}<CR>

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

relative path

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.

onetime

'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.

cword

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.

find

Search tool

If one of the tools listed above is in the $PATH, the plugin can run it using default options. You can also set your preferred search 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.

Find window

The following keys and functions are available in the Find window.

key	function
`Ctrl`+`C`	Stop searching
`r`	Resize / Rotate
`s`	Split and View
`i`	View
`Enter`	Jump to position

Navigation

Additional commands are supported to quickly navigate through search results.

Hi/next and Hi/previous commands jump directly to the location of the file.

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

It will be handy to use key mappings for these commands to easily navigate the search results. For example:

  nn -        <Cmd>Hi/next<CR>
  nn _        <Cmd>Hi/previous<CR>
  nn f<Left>  <Cmd>Hi/older<CR>
  nn f<Right> <Cmd>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.

Customizing Colors

The plugin provides two default color sets which are automatically loaded based on the current background mode.

You can use the hi command to add, change, rearrange colors, and save them to the configuration file or color scheme.

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

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>'

" jump key mappings
nn <CR>     <Cmd>Hi><CR>
nn g<CR>    <Cmd>Hi<<CR>
nn [<CR>    <Cmd>Hi{<CR>
nn ]<CR>    <Cmd>Hi}<CR>

" find key mappings
nn -        <Cmd>Hi/next<CR>
nn _        <Cmd>Hi/previous<CR>
nn f<Left>  <Cmd>Hi/older<CR>
nn f<Right> <Cmd>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

nvim .lua

-- jump and find key mappings
vim.cmd([[
  nn <CR>     <Cmd>Hi><CR>
  nn g<CR>    <Cmd>Hi<<CR>
  nn [<CR>    <Cmd>Hi{<CR>
  nn ]<CR>    <Cmd>Hi}<CR>

  nn -        <Cmd>Hi/next<CR>
  nn _        <Cmd>Hi/previous<CR>
  nn f<Left>  <Cmd>Hi/older<CR>
  nn f<Right> <Cmd>Hi/newer<CR>
]])

-- directory to store highlight files
vim.g.HiKeywords = '~/.vim/after/vim-highlighter'

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=bold
You can now load colors using the colorscheme command:
:colorscheme sample

Multifunction keys

The plugin's HiFind() function returns whether the Find window is visible. The idea is to assign some convenient keys for navigating the find results while the Find window is displayed, and then restore the keys after the window is closed.

The following example defines the - _ and f- keys to execute the Hi command while the Find window is visible, otherwise execute the original function.
" find key mappings
nn -   <Cmd>call <SID>HiOptional('next', '-')<CR>
nn _   <Cmd>call <SID>HiOptional('previous', '_')<CR>
nn f-  <Cmd>call <SID>HiOptional('close', 'f-')<CR>

function s:HiOptional(cmd, key)
  if HiFind()
    exe "Hi" a:cmd
  else
    exe "normal!" a:key
  endif
endfunction
nvim .lua
-- find key mappings
vim.cmd([[
  nn -   <Cmd>call v:lua.hi_optional('next', '-')<CR>
  nn _   <Cmd>call v:lua.hi_optional('previous', '_')<CR>
  nn f-  <Cmd>call v:lua.hi_optional('close', 'f-')<CR>
]])

function _G.hi_optional(cmd, key)
  if vim.fn.HiFind() == 1 then
    vim.cmd('Hi '.. cmd)
  else
    vim.cmd('normal! '.. key)
  end
end

Help tags

For more information about commands and options, please refer to:

 :h HI

Tested

  Linux   Vim 8.2
  Windows gVim 8.2
  Mac     neovim 0.5.0  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

vim-highlighter
vim-highlighter copied to clipboard

Metadata

Vim Highlighter

Introduction

Contents

Installation

Key Map

Visual Selection

Input

Sync Mode

Jump to Highlights

Save & Load Highlights

One Time Highlight

Following Highlight

Find in Files Highlight

Search tool

Input

Expression

Examples

Visual selection

Find window

Navigation

🍏 Tip

Customizing Colors

Configuration Examples

Help tags

Tested

Issues

License

← Metadata

Owner

Metadata

vim-highlighter vim-highlighter copied to clipboard

Metadata

Vim Highlighter

Introduction

Contents

Installation

Key Map

Visual Selection

Input

Sync Mode

Jump to Highlights

Save & Load Highlights

One Time Highlight

Following Highlight

Find in Files Highlight

Search tool

Input

Expression

Examples

Visual selection

Find window

Navigation

🍏 Tip

Customizing Colors

Configuration Examples

Help tags

Tested

Issues

License

← Metadata

Owner

Metadata

vim-highlighter
vim-highlighter copied to clipboard