Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/azabiong/vim-highlighter
Highlight words and expressions
https://github.com/azabiong/vim-highlighter
grep highlighter neovim vim
Last synced: about 2 months ago
JSON representation
Highlight words and expressions
- Host: GitHub
- URL: https://github.com/azabiong/vim-highlighter
- Owner: azabiong
- License: mit
- Created: 2021-05-07T17:30:59.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-07-23T14:21:42.000Z (2 months ago)
- Last Synced: 2024-07-23T16:43:11.722Z (2 months ago)
- Topics: grep, highlighter, neovim, vim
- Language: Vim Script
- Homepage:
- Size: 226 KB
- Stars: 223
- Watchers: 4
- Forks: 8
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vim Highlighter
ver 1.62
Introduction
Highlighting keywords or lines can be useful when analyzing code, reviewing summaries, and quickly comparing spellings.
This plugin provides easy commands and shortcuts for setting and deleting highlights, and additional features such as Move to Highlight, Save and Load, Find Pattern, and Customize Colors.
### Contents
[Installation](#installation)
[Key Map](#key-map)
[Jump to Highlight](#jump-to-highlight)
[One Time Highlight](#one-time-highlight)
[Following Highlight](#following-highlight)
[Find in Files Highlight](#find-in-files-highlight)
[Positional Highlight](#positional-highlight)
[Save & Load](#save--load)
[Sync Mode](#sync-mode)
[Customizing Colors](#customizing-colors)
[Configuration](#configuration-examples)
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 `
```vim
Plug 'azabiong/vim-highlighter'
```
**lazy.nvim** ` .lua `
```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 assigned 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.
### Visual Selection
In visual mode, the highlight is selected as a partial pattern from the selection and applied to other words.
You can also select an entire line and highlight it.
### Input
To set highlighting by entering a pattern:
```vim
: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.
You can easily define key mappings for these commands. For example:
```vim
nn Hi>
nn g Hi<
```
> 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](#configuration-examples)
## One Time Highlight
When you only need one quick scan at the cursor position without setting the highlight, **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.
**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 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 on the current tab-page, and
**Jump** commands `Hi<` and `Hi>` are also supported.
cWORD matching
Sometimes, when comparing variables consisting of letters and symbols, Vim's **``** matching option can be useful.
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 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.
### 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:
```vim
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:
```vim
nn - Hi/next
nn _ Hi/previous
nn f Hi/older
nn f Hi/newer
```
#### 🍏 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.
**Jump** commands `Hi{}` and `Hi[]` are also supported after setting.
## Save & Load
Sometimes when you want to save highlights of the current window and reload them next time, you can use:
```vim
:Hi save
```
and when loading:
```vim
:Hi load
```
You can name the file when saving, and use tab-completion when loading. For example:
```vim
:Hi save name
:Hi load
```
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:
```vim
: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:
```vim
:Hi =
```
To synchronize window highlighting on each tab-page:
```vim
:Hi ==
```
When synchronizing window highlighting across all tab-pages:
```vim
: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
>
> 
>
> 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