Vim Highlighter

ver 1.62.5

Introduction

Highlighting keywords or lines can be useful when analyzing code, reviewing summaries, and quickly comparing spellings. This plugin provides easy commands and shortcuts to set and delete highlights, and additional features such as Move to Highlight, Save and Load, Find Pattern, and Customize Colors.

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

What's New ✨

| version | feature | key map | |:--:|:--|:--:| | 1.62 | [Jump to Highlight](#jump-to-highlight) of the same color | O | | 1.60 | [Sync Mode](#sync-mode) across all tab-pages | | | 1.58 | [Positional Highlight](#positional-highlight) associated with a buffer | O | | 1.56 | [One Time Highlight](#one-time-highlight) and **Jump** | | | 1.52 | [Find window](#find-window) key i for **View** | O | | 1.38 | [Input](#input) patterns in the command-line | | | 1.35 | [Multifunction keys](#configuration-examples) for **Find** | O |

Installation

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

vim-plug .vim

   Plug 'azabiong/vim-highlighter'

lazy.nvim .lua

   {
     "azabiong/vim-highlighter",
     init = function()
       -- settings
     end,
   },

or, Vim's built-in package feature:

>
> > |Linux, Mac| Windows | > |:--:|--| > |~/.vim| ~/vimfiles| > > in the terminal: > ```zsh > 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 mapping variables that work in both normal and visual modes, and each key can be easily defined in the configuration file.

.vim

```vim let HiSet = 'f' let HiErase = 'f' let HiClear = 'f' let HiFind = 'f' let HiSetSL = 't' ```

.lua

```lua vim.cmd([[ let HiSet = 'f' let HiErase = 'f' let HiClear = 'f' let HiFind = 'f' let HiSetSL = 't' ]]) ```

Default key mappings: f Enter, f Backspace, f Ctrl+L, f Tab and t Enter

In normal mode, HiSet and HiErase keys set or erase highlighting of the word under the cursor. HiClear key clears all highlights.

key_map

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 highlighting by entering a pattern:

  :Hi + pattern

Jump to Highlight

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

1. Pattern The Hi < and Hi > commands move the cursor back and forth to highlights that matches the pattern at the cursor position or to the recently set highlight.

2. Position The Hi { and Hi } commands, move the cursor to the nearest highlight, even if the pattern or type differs from the current selection.

3. Color The Hi [ and Hi ] commands support moving to highlights of the same color with different patterns or types, which can be useful when grouping highlights by content.

jump

You can easily define key mappings for these commands. For example:

   nn <CR>  <Cmd>Hi><CR>
   nn g<CR> <Cmd>Hi<<CR>

Alternatively, you can map the n and N keys to HiSearch() function, which automatically selects the search type between native search and jump commands. → Configuration

One Time Highlight

When you only need quick pattern matching at the cursor position without setting highlighting, One Time Highlight can be useful.

When the cursor is over a word or visual selection that is not highlighted, pressing HiErase key sets One Time Highlight. The highlight remains on while the cursor is stationary, and automatically turns off after the cursor moves.

onetime

One Time Highlight displays matches in all windows on the current tab-page, and Jump commands Hi<> and Hi[] are also supported.

Following Highlight

When you need automatic matching based on cursor movement, Following Highlight mode may 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

Following Highlight displays matches in all windows on the current tab-page, and Jump commands Hi<> and Hi[] are also supported.

cWORD matching

Sometimes, when comparing patterns consisting of letters and symbols, Vim's **``** matching option can be useful. cword

The following command toggles between the default **``** and **``** matching options: ```vim :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 patterns 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

```vim 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
`r`	Resize / Rotate
`i`	View
`s`	Split and View
`Enter`	Jump to position
`Ctrl`+`C`	Stop searching

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 would be convenient to define key mappings for these commands for easy navigation. 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.

Positional Highlight

There is another type of highlight that is set in a specific location.

Unlike pattern-based highlighting, Positional Highlight is set to a specific position in the buffer. Thanks to new APIs in Vim and Neovim, it's similar to coloring over text with a highlighter. The position is updated when inserting or deleting the line above.

To set a Positional Highlight on a specific line, press the HiSetSL key in normal or visual mode.
Multiline highlighting is now automatically set to positional highlighting.

positional

Jump commands Hi{} and Hi[] are supported after setting.

Save & Load

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: ```vim :Hi save ./name :Hi load ./ ```

Sync Mode

The plugin supports three highlight sync mode commands.

For each single window highlighting mode:

  :Hi =

To synchronize window highlighting on each tab-page:

  :Hi ==

When synchronizing window highlighting across all tab-pages:

  :Hi ===

The initial mode can be set using the HiSyncMode configuration variable.

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

> > 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. > ```vim > :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** > ```vim > :hi HiFind ctermfg=52 ctermbg=182 guifg=#570707 guibg=#e7bfe7 > ```

Multiline highlight color numbers start at 80, `HiColor80`.
## Configuration Examples

Summary

>
>

.vim

> > ```vim > " Unicode > " set encoding=utf-8 > > " default key mappings > " let HiSet = 'f' > " let HiErase = 'f' > " let HiClear = 'f' > " let HiFind = 'f' > " let HiSetSL = 't' > > " jump key mappings > nn Hi> > nn g Hi< > nn gl Hi} > nn gh Hi{ > nn gj Hi] > nn gk Hi[ > > " find key mappings > nn - Hi/next > nn _ Hi/previous > nn f Hi/older > nn f Hi/newer > > " sync mode > " let HiSyncMode = 1 > > " command abbreviations > ca HL Hi:load > ca HS Hi:save > > " directory to store highlight files > " let HiKeywords = '~/.config/keywords' > > " additional 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 > ``` >
>

> >

.lua

> > ```lua > vim.cmd([[ > " default key mappings > " let HiSet = 'f' > " let HiErase = 'f' > " let HiClear = 'f' > " let HiFind = 'f' > " let HiSetSL = 't' > > " jump key mappings > nn Hi> > nn g Hi< > nn gl Hi} > nn gh Hi{ > nn gj Hi] > nn gk Hi[ > > " find key mappings > nn - Hi/next > nn _ Hi/previous > nn f Hi/older > nn f Hi/newer > > " sync mode > " let HiSyncMode = 1 > > " directory to store highlight files > " let HiKeywords = '~/.config/keywords' > > " additional 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 > ]]) > ``` >

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: > ```vim > 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 > ``` > > You can now load colors using the **`colorscheme`** command: > ```vim > :colorscheme sample > ```

Multifunction keys for Find

> > The plugin's `HiFind()` function returns whether the **Find** window is visible. > The idea is to define different actions for the keys depending on whether the **Find** window is displayed or not. > > The following example defines the `-` `_` and `f-` keys to execute the **Hi** command while > the **Find** window is visible, otherwise execute the original function. > >

.vim

> > ```vim > " find key mappings > nn - call HiOptional('next', '-') > nn _ call HiOptional('previous', '_') > nn f- call HiOptional('close', 'f-') > > function s:HiOptional(cmd, key) > if HiFind() > exe "Hi" a:cmd > else > exe "normal!" a:key > endif > endfunction > ``` >
>

> >

.lua

> > ```lua > -- find key mappings > vim.cmd([[ > nn - call v:lua.hi_optional('next', '-') > nn _ call v:lua.hi_optional('previous', '_') > nn f- call v:lua.hi_optional('close', 'f-') > ]]) > > function _G.hi_optional(cmd, key) > if vim.fn.HiFind() == 1 then > vim.cmd('Hi '.. cmd) > else > vim.cmd('normal! '.. key) > end > end > ``` > >

Jump to Highlight with n and N keys

> > You can also define n and N keys for both the native search and the plugin's jump commands. > >

.vim

> > ```vim > " jump key mappings > nn n call HiSearch('n') > nn N call HiSearch('N') > ``` > While `hlsearch` is displayed, the function executes the native search command assigned to each key, > otherwise, it executes the `Hi>` or `Hi<` command. When switching from native search to jump mode, > you can simply turn off `hlsearch` using the **`:noh`** command. For example: > ```vim > nn n noh > ``` >
>

> >

.lua

> > ```lua > vim.cmd([[ > " jump key mappings > nn n call HiSearch('n') > nn N call HiSearch('N') > > " :noh commmand mapping, if there isn't > nn n noh > ]]) > ``` >

## Help tags For more information about commands and configurable options, please see: ```vim :h Hi ``` and ```vim :h Hi-Options ```
## 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

azabiong / vim-highlighter

readme

Vim Highlighter

ver 1.62.5

Introduction

Contents

Installation

Key Map

Visual Selection

Input

Jump to Highlight

One Time Highlight

Following Highlight

Find in Files Highlight

Search tool

Input

Expression

Examples

Visual selection

Find window

Navigation

🍏 Tip

Positional Highlight

Save & Load

Sync Mode

Customizing Colors