├── LICENSE
├── README.md
├── doc
    └── mini-hipatterns.txt
└── lua
    └── mini
        └── hipatterns.lua


/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2021 Evgeni Chasnovski
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | <p align="center"> <img src="https://github.com/nvim-mini/assets/blob/main/logo-2/logo-hipatterns_readme.png?raw=true" alt="mini.hipatterns" style="max-width:100%;border:solid 2px"/> </p>
  2 | 
  3 | ### Highlight patterns in text
  4 | 
  5 | See more details in [Features](#features) and [Documentation](doc/mini-hipatterns.txt).
  6 | 
  7 | ---
  8 | 
  9 | > [!NOTE]
 10 | > This was previously hosted at a personal `echasnovski` GitHub account. It was transferred to a dedicated organization to improve long term project stability. See more details [here](https://github.com/nvim-mini/mini.nvim/discussions/1970).
 11 | 
 12 | ⦿ This is a part of [mini.nvim](https://nvim-mini.org/mini.nvim) library. Please use [this link](https://nvim-mini.org/mini.nvim/readmes/mini-hipatterns) if you want to mention this module.
 13 | 
 14 | ⦿ All contributions (issues, pull requests, discussions, etc.) are done inside of 'mini.nvim'.
 15 | 
 16 | ⦿ See [whole library documentation](https://nvim-mini.org/mini.nvim/doc/mini-nvim) to learn about general design principles, disable/configuration recipes, and more.
 17 | 
 18 | ⦿ See [MiniMax](https://nvim-mini.org/MiniMax) for a full config example that uses this module.
 19 | 
 20 | ---
 21 | 
 22 | If you want to help this project grow but don't know where to start, check out [contributing guides of 'mini.nvim'](https://nvim-mini.org/mini.nvim/CONTRIBUTING) or leave a Github star for 'mini.nvim' project and/or any its standalone Git repositories.
 23 | 
 24 | ## Demo
 25 | 
 26 | <!-- Demo source: https://github.com/nvim-mini/assets/blob/main/demo/demo-hipatterns.mp4 -->
 27 | https://github.com/nvim-mini/mini.nvim/assets/24854248/130374e2-4e6c-43cf-af33-43d816b4fa32
 28 | 
 29 | ## Features
 30 | 
 31 | - Highlight text with configurable patterns and highlight groups (can be string or callable).
 32 | 
 33 | - Highlighting is updated asynchronously with configurable debounce delay.
 34 | 
 35 | - Function to get matches in a buffer.
 36 | 
 37 | See `:h MiniHipatterns-examples` for examples of common use cases.
 38 | 
 39 | Notes:
 40 | 
 41 | - It does not define any highlighters by default. Add to `config.highlighters` to have a visible effect.
 42 | 
 43 | ## Example usage
 44 | 
 45 | ```lua
 46 | local hipatterns = require('mini.hipatterns')
 47 | hipatterns.setup({
 48 |   highlighters = {
 49 |     -- Highlight standalone 'FIXME', 'HACK', 'TODO', 'NOTE'
 50 |     fixme = { pattern = '%f[%w]()FIXME()%f[%W]', group = 'MiniHipatternsFixme' },
 51 |     hack  = { pattern = '%f[%w]()HACK()%f[%W]',  group = 'MiniHipatternsHack'  },
 52 |     todo  = { pattern = '%f[%w]()TODO()%f[%W]',  group = 'MiniHipatternsTodo'  },
 53 |     note  = { pattern = '%f[%w]()NOTE()%f[%W]',  group = 'MiniHipatternsNote'  },
 54 | 
 55 |     -- Highlight hex color strings (`#rrggbb`) using that color
 56 |     hex_color = hipatterns.gen_highlighter.hex_color(),
 57 |   },
 58 | })
 59 | ```
 60 | 
 61 | ## Installation
 62 | 
 63 | This plugin can be installed as part of 'mini.nvim' library (**recommended**) or as a standalone Git repository.
 64 | 
 65 | There are two branches to install from:
 66 | 
 67 | - `main` (default, **recommended**) will have latest development version of plugin. All changes since last stable release should be perceived as being in beta testing phase (meaning they already passed alpha-testing and are moderately settled).
 68 | - `stable` will be updated only upon releases with code tested during public beta-testing phase in `main` branch.
 69 | 
 70 | Here are code snippets for some common installation methods (use only one):
 71 | 
 72 | <details>
 73 | <summary>With <a href="https://nvim-mini.org/mini.nvim/readmes/mini-deps">mini.deps</a></summary>
 74 | 
 75 | - 'mini.nvim' library:
 76 | 
 77 |     | Branch | Code snippet                                  |
 78 |     |--------|-----------------------------------------------|
 79 |     | Main   | *Follow recommended ‘mini.deps’ installation* |
 80 |     | Stable | *Follow recommended ‘mini.deps’ installation* |
 81 | 
 82 | - Standalone plugin:
 83 | 
 84 |     | Branch | Code snippet                                                         |
 85 |     |--------|----------------------------------------------------------------------|
 86 |     | Main   | `add(‘nvim-mini/mini.hipatterns’)`                                   |
 87 |     | Stable | `add({ source = ‘nvim-mini/mini.hipatterns’, checkout = ‘stable’ })` |
 88 | 
 89 | </details>
 90 | 
 91 | <details>
 92 | <summary>With <a href="https://github.com/folke/lazy.nvim">folke/lazy.nvim</a></summary>
 93 | 
 94 | - 'mini.nvim' library:
 95 | 
 96 |     | Branch | Code snippet                                  |
 97 |     |--------|-----------------------------------------------|
 98 |     | Main   | `{ 'nvim-mini/mini.nvim', version = false },` |
 99 |     | Stable | `{ 'nvim-mini/mini.nvim', version = '*' },`   |
100 | 
101 | - Standalone plugin:
102 | 
103 |     | Branch | Code snippet                                        |
104 |     |--------|-----------------------------------------------------|
105 |     | Main   | `{ 'nvim-mini/mini.hipatterns', version = false },` |
106 |     | Stable | `{ 'nvim-mini/mini.hipatterns', version = '*' },`   |
107 | 
108 | </details>
109 | 
110 | <details>
111 | <summary>With <a href="https://github.com/junegunn/vim-plug">junegunn/vim-plug</a></summary>
112 | 
113 | - 'mini.nvim' library:
114 | 
115 |     | Branch | Code snippet                                         |
116 |     |--------|------------------------------------------------------|
117 |     | Main   | `Plug 'nvim-mini/mini.nvim'`                         |
118 |     | Stable | `Plug 'nvim-mini/mini.nvim', { 'branch': 'stable' }` |
119 | 
120 | - Standalone plugin:
121 | 
122 |     | Branch | Code snippet                                               |
123 |     |--------|------------------------------------------------------------|
124 |     | Main   | `Plug 'nvim-mini/mini.hipatterns'`                         |
125 |     | Stable | `Plug 'nvim-mini/mini.hipatterns', { 'branch': 'stable' }` |
126 | 
127 | </details>
128 | 
129 | **Important**: don't forget to call `require('mini.hipatterns').setup()` with non-empty `highlighters` to auto-enable highlighting in all normal buffers.
130 | 
131 | **Note**: if you are on Windows, there might be problems with too long file paths (like `error: unable to create file <some file name>: Filename too long`). Try doing one of the following:
132 | 
133 | - Enable corresponding git global config value: `git config --system core.longpaths true`. Then try to reinstall.
134 | - Install plugin in other place with shorter path.
135 | 
136 | ## Default config
137 | 
138 | ```lua
139 | -- No need to copy this inside `setup()`. Will be used automatically.
140 | {
141 |   -- Table with highlighters (see |MiniHipatterns.config| for more details).
142 |   -- Nothing is defined by default. Add manually for visible effect.
143 |   highlighters = {},
144 | 
145 |   -- Delays (in ms) defining asynchronous highlighting process
146 |   delay = {
147 |     -- How much to wait for update after every text change
148 |     text_change = 200,
149 | 
150 |     -- How much to wait for update after window scroll
151 |     scroll = 50,
152 |   },
153 | 
154 | }
155 | ```
156 | 
157 | ## Similar plugins
158 | 
159 | - [folke/todo-comments.nvim](https://github.com/folke/todo-comments.nvim)
160 | - [folke/paint.nvim](https://github.com/folke/paint.nvim)
161 | - [NvChad/nvim-colorizer.lua](https://github.com/NvChad/nvim-colorizer.lua)
162 | - [uga-rosa/ccc.nvim](https://github.com/uga-rosa/ccc.nvim)
163 | 


--------------------------------------------------------------------------------
/doc/mini-hipatterns.txt:
--------------------------------------------------------------------------------
  1 | *mini.hipatterns* Highlight patterns in text
  2 | 
  3 | MIT License Copyright (c) 2023 Evgeni Chasnovski
  4 | 
  5 | ------------------------------------------------------------------------------
  6 |                                                                 *MiniHipatterns*
  7 | Features:
  8 | - Highlight text with configurable patterns and highlight groups (can be
  9 |   string or callable).
 10 | 
 11 | - Highlighting is updated asynchronously with configurable debounce delay.
 12 | 
 13 | - Function to get matches in a buffer (see |MiniHipatterns.get_matches()|).
 14 | 
 15 | See |MiniHipatterns-examples| for common configuration examples.
 16 | 
 17 | Notes:
 18 | - It does not define any highlighters by default. Add to `config.highlighters`
 19 |   to have a visible effect.
 20 | 
 21 | - Sometimes (especially during frequent buffer updates on same line numbers)
 22 |   highlighting can be outdated or not applied when it should be. This is due
 23 |   to asynchronous nature of updates reacting to text changes (via
 24 |   `on_lines` of |nvim_buf_attach()|).
 25 |   To make them up to date, use one of the following:
 26 |     - Scroll window (for example, with |CTRL-E| / |CTRL-Y|). This will ensure
 27 |       up to date highlighting inside window view.
 28 |     - Hide and show buffer.
 29 |     - Execute `:edit` (if you enabled highlighting with |MiniHipatterns.setup()|).
 30 |     - Manually call |MiniHipatterns.update()|.
 31 | 
 32 | - If you experience flicker when typing near highlighted pattern in Insert
 33 |   mode, it might be due to `delay` configuration of |mini.completion| or
 34 |   using built-in completion.
 35 |   For better experience with 'mini.completion', make sure that its
 36 |   `delay.completion` is less than this module's `delay.text_change` (which
 37 |   it is by default).
 38 |   The reason for this is (currently unresolvable) limitations of Neovim's
 39 |   built-in completion implementation.
 40 | 
 41 | # Setup ~
 42 | 
 43 | Setting up highlights can be done in two ways:
 44 | - Manually for every buffer with `require('mini.hipatterns').enable()`.
 45 |   This will enable highlighting only in one particular buffer until it is
 46 |   unloaded (which also includes calling `:edit` on current file).
 47 | 
 48 | - Globally with `require('mini.hipatterns').setup({})` (replace `{}` with
 49 |   your `config` table). This will auto-enable highlighting in "normal"
 50 |   buffers (see 'buftype'). Use |MiniHipatterns.enable()| to manually enable
 51 |   in other buffers.
 52 |   It will also create global Lua table `MiniHipatterns` which you can use
 53 |   for scripting or manually (with `:lua MiniHipatterns.*`).
 54 | 
 55 | See |MiniHipatterns.config| for `config` structure and default values.
 56 | 
 57 | You can override runtime config settings (like highlighters and delays)
 58 | locally to buffer inside `vim.b.minihipatterns_config` which should have
 59 | same structure as `MiniHipatterns.config`.
 60 | See |mini.nvim-buffer-local-config| for more details.
 61 | 
 62 | # Comparisons ~
 63 | 
 64 | - [folke/todo-comments](https://github.com/folke/todo-comments):
 65 |     - Oriented for "TODO", "NOTE", "FIXME" like patterns, while this module
 66 |       can work with any Lua patterns and computable highlight groups.
 67 |     - Has functionality beyond text highlighting (sign placing,
 68 |       "telescope.nvim" extension, etc.), while this module only focuses on
 69 |       highlighting text.
 70 | - [folke/paint.nvim](https://github.com/folke/paint.nvim):
 71 |     - Mostly similar to this module, but with slightly less functionality,
 72 |       such as computed pattern and highlight group, asynchronous delay, etc.
 73 | - [NvChad/nvim-colorizer.lua](https://github.com/NvChad/nvim-colorizer.lua):
 74 |     - Oriented for color highlighting, while this module can work with any
 75 |       Lua patterns and computable highlight groups.
 76 |     - Has more built-in color spaces to highlight, while this module out of
 77 |       the box provides only hex color highlighting
 78 |       (see |MiniHipatterns.gen_highlighter.hex_color()|). Other types are
 79 |       also possible to implement.
 80 | - [uga-rosa/ccc.nvim](https://github.com/uga-rosa/ccc.nvim):
 81 |     - Has more than color highlighting functionality, which is compared to
 82 |       this module in the same way as 'NvChad/nvim-colorizer.lua'.
 83 | 
 84 | # Highlight groups ~
 85 | 
 86 | - `MiniHipatternsFixme` - suggested group to use for `FIXME`-like patterns.
 87 | - `MiniHipatternsHack` - suggested group to use for `HACK`-like patterns.
 88 | - `MiniHipatternsTodo` - suggested group to use for `TODO`-like patterns.
 89 | - `MiniHipatternsNote` - suggested group to use for `NOTE`-like patterns.
 90 | 
 91 | To change any highlight group, set it directly with |nvim_set_hl()|.
 92 | 
 93 | # Disabling ~
 94 | 
 95 | This module can be disabled in three ways:
 96 | - Globally: set `vim.g.minihipatterns_disable` to `true`.
 97 | - Locally for buffer permanently: set `vim.b.minihipatterns_disable` to `true`.
 98 | - Locally for buffer temporarily (until next auto-enabling event if set up
 99 |   with |MiniHipatterns.setup()|): call |MiniHipatterns.disable()|.
100 | 
101 | Considering high number of different scenarios and customization
102 | intentions, writing exact rules for disabling module's functionality is
103 | left to user. See |mini.nvim-disabling-recipes| for common recipes.
104 | 
105 | ------------------------------------------------------------------------------
106 |                                                        *MiniHipatterns-examples*
107 | # Common configuration examples ~
108 | 
109 | - Special words used to convey different level of attention: >lua
110 | 
111 |   require('mini.hipatterns').setup({
112 |     highlighters = {
113 |       fixme = { pattern = 'FIXME', group = 'MiniHipatternsFixme' },
114 |       hack  = { pattern = 'HACK',  group = 'MiniHipatternsHack'  },
115 |       todo  = { pattern = 'TODO',  group = 'MiniHipatternsTodo'  },
116 |       note  = { pattern = 'NOTE',  group = 'MiniHipatternsNote'  },
117 |     }
118 |   })
119 | <
120 | - To match only when pattern appears as a standalone word, use frontier
121 |   patterns `%f`. For example, instead of `'TODO'` pattern use
122 |   `'%f[%w]()TODO()%f[%W]'`. In this case, for example, 'TODOING' or 'MYTODO'
123 |   won't match, but 'TODO' and 'TODO:' will.
124 | 
125 | - Color hex (like `#rrggbb`) highlighting: >lua
126 | 
127 |   local hipatterns = require('mini.hipatterns')
128 |   hipatterns.setup({
129 |     highlighters = {
130 |       hex_color = hipatterns.gen_highlighter.hex_color(),
131 |     }
132 |   })
133 | <
134 |   You can customize which part of hex color is highlighted by using `style`
135 |   field of input options. See |MiniHipatterns.gen_highlighter.hex_color()|.
136 | 
137 | - Colored words: >lua
138 | 
139 |   local words = { red = '#ff0000', green = '#00ff00', blue = '#0000ff' }
140 |   local word_color_group = function(_, match)
141 |     local hex = words[match]
142 |     if hex == nil then return nil end
143 |     return MiniHipatterns.compute_hex_color_group(hex, 'bg')
144 |   end
145 | 
146 |   local hipatterns = require('mini.hipatterns')
147 |   hipatterns.setup({
148 |     highlighters = {
149 |       word_color = { pattern = '%S+', group = word_color_group },
150 |     },
151 |   })
152 | <
153 | - Trailing whitespace (if don't want to use more specific |mini.trailspace|): >lua
154 | 
155 |   { pattern = '%f[%s]%s*$', group = 'Error' }
156 | <
157 | - Censor certain sensitive information: >lua
158 | 
159 |   local censor_extmark_opts = function(_, match, _)
160 |     local mask = string.rep('x', vim.fn.strchars(match))
161 |     return {
162 |       virt_text = { { mask, 'Comment' } }, virt_text_pos = 'overlay',
163 |       priority = 200, right_gravity = false,
164 |     }
165 |   end
166 | 
167 |   require('mini.hipatterns').setup({
168 |     highlighters = {
169 |       censor = {
170 |         pattern = 'password: ()%S+()',
171 |         group = '',
172 |         extmark_opts = censor_extmark_opts,
173 |       },
174 |     },
175 |   })
176 | <
177 | - Enable only in certain filetypes. There are at least these ways to do it:
178 |     - (Suggested) With `vim.b.minihipatterns_config` in |filetype-plugin|.
179 |       Basically, create "after/ftplugin/<filetype>.lua" file in your config
180 |       directory (see |$XDG_CONFIG_HOME|) and define `vim.b.minihipatterns_config`
181 |       there with filetype specific highlighters.
182 | 
183 |       This assumes `require('mini.hipatterns').setup()` call.
184 | 
185 |       For example, to highlight keywords in EmmyLua comments in Lua files,
186 |       create "after/ftplugin/lua.lua" with the following content: >lua
187 | 
188 |         vim.b.minihipatterns_config = {
189 |           highlighters = {
190 |             emmylua = { pattern = '^%s*%-%-%-()@%w+()', group = 'Special' }
191 |           }
192 |         }
193 | <
194 |     - Use callable `pattern` with condition. For example: >lua
195 | 
196 |       require('mini.hipatterns').setup({
197 |         highlighters = {
198 |           emmylua = {
199 |             pattern = function(buf_id)
200 |               if vim.bo[buf_id].filetype ~= 'lua' then return nil end
201 |               return '^%s*%-%-%-()@%w+()'
202 |             end,
203 |             group = 'Special',
204 |           },
205 |         },
206 |       })
207 | <
208 | - Disable only in certain filetypes. Enable with |MiniHipatterns.setup()|
209 |   and set `vim.b.minihipatterns_disable` buffer-local variable to `true` for
210 |   buffer you want disabled. See |mini.nvim-disabling-recipes| for more examples.
211 | 
212 | ------------------------------------------------------------------------------
213 |                                                         *MiniHipatterns.setup()*
214 |                         `MiniHipatterns.setup`({config})
215 | Module setup
216 | 
217 | Parameters ~
218 | {config} `(table|nil)` Module config table. See |MiniHipatterns.config|.
219 | 
220 | Usage ~
221 | >lua
222 |   require('mini.hipatterns').setup({}) -- replace {} with your config table
223 |                                        -- needs `highlighters` field present
224 | <
225 | ------------------------------------------------------------------------------
226 |                                                          *MiniHipatterns.config*
227 |                             `MiniHipatterns.config`
228 | Defaults ~
229 | >lua
230 |   MiniHipatterns.config = {
231 |     -- Table with highlighters (see |MiniHipatterns.config| for more details).
232 |     -- Nothing is defined by default. Add manually for visible effect.
233 |     highlighters = {},
234 | 
235 |     -- Delays (in ms) defining asynchronous highlighting process
236 |     delay = {
237 |       -- How much to wait for update after every text change
238 |       text_change = 200,
239 | 
240 |       -- How much to wait for update after window scroll
241 |       scroll = 50,
242 |     },
243 |   }
244 | <
245 | # Highlighters ~
246 | 
247 | `highlighters` table defines which patterns will be highlighted by placing
248 | |extmark| at the match start. It might or might not have explicitly named
249 | fields, but having them is recommended and is required for proper use of
250 | `vim.b.minihipatterns_config` as buffer-local config. By default it is
251 | empty expecting user definition.
252 | 
253 | Each entry defines single highlighter as a table with the following fields:
254 | - <pattern> `(string|function|table)` - Lua pattern to highlight. Can be
255 |   either string, callable returning the string, or an array of those.
256 |   If string:
257 |     - It can have submatch delimited by placing `()` on start and end, NOT
258 |       by surrounding it with parenthesis (results in an error containing
259 |       `number expected, got string`). Example: `xx()abcd()xx` will match
260 |       `abcd` only if `xx` is placed before and after it.
261 | 
262 |   If callable:
263 |     - It will be called for every enabled buffer with its identifier as input.
264 |       Should return single string pattern or `nil` (meaning this particular
265 |       highlighter will not work in this particular buffer).
266 | 
267 |   If array:
268 |     - Each element is matched and highlighted with the same highlight group.
269 | 
270 |     Note: matching does not result in overlapping (sub)matches (similarly
271 |     to how |cpo-c| works). For example, with line `xxxxxxx`:
272 |     - Pattern `xxx` matches columns 1-3, 4-6.
273 |     - Pattern `()xx()x` matches columns 1-2, 3-4, 5-6.
274 |     - Pattern `x()xx()` matches columns 2-3, 5-6.
275 |     - Pattern `x()x()x` matches columns 2-2, 4-4, 6-6.
276 | 
277 | - <group> `(string|function)` - name of highlight group to use. Can be either
278 |   string or callable returning the string.
279 |   If callable:
280 |     - It will be called for every pattern match with the following arguments:
281 |         - `buf_id` - buffer identifier.
282 |         - `match` - string pattern match to be highlighted.
283 |         - `data` - extra table with information about the match.
284 |           It has at least these fields:
285 |             - <full_match> - string with full pattern match.
286 |             - <line> - match line number (1-indexed).
287 |             - <from_col> - match starting byte column (1-indexed).
288 |             - <to_col> - match ending byte column (1-indexed, inclusive).
289 | 
290 |     - It can return `nil` meaning this particular match will not be highlighted.
291 | 
292 | - <extmark_opts> `(table|function|nil)` - optional extra options
293 |   for |nvim_buf_set_extmark()|. If callable, will be called in the same way
294 |   as callable <group> (`data` will also contain `hl_group` key with <group>
295 |   value) and should return a table with all options for extmark (including
296 |   `end_row`, `end_col`, `hl_group`, and `priority`).
297 | 
298 | See "Common use cases" section for the examples.
299 | 
300 | # Delay ~
301 | 
302 | `delay` is a table defining delays in milliseconds used for asynchronous
303 | highlighting process.
304 | 
305 | `delay.text_change` is used to delay highlighting updates by accumulating
306 | them (in debounce fashion). Smaller values will lead to faster response but
307 | more frequent updates. Bigger - slower response but less frequent updates.
308 | 
309 | `delay.scroll` is used to delay updating highlights in current window view
310 | during scrolling (see |WinScrolled| event). These updates are present to
311 | ensure up to date highlighting after scroll.
312 | 
313 | ------------------------------------------------------------------------------
314 |                                                        *MiniHipatterns.enable()*
315 |                   `MiniHipatterns.enable`({buf_id}, {config})
316 | Enable highlighting in buffer
317 | 
318 | Notes:
319 | - With default config it will highlight nothing, as there are no default
320 |   highlighters.
321 | 
322 | - Buffer highlighting is enabled until buffer is unloaded from memory
323 |   or |MiniHipatterns.disable()| on this buffer is called.
324 | 
325 | - `:edit` disables this, as it is mostly equivalent to closing and opening
326 |   buffer. In order for highlighting to persist after `:edit`, call
327 |   |MiniHipatterns.setup()|.
328 | 
329 | Parameters ~
330 | {buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
331 |   Default: 0 for current buffer.
332 | {config} `(table|nil)` Optional buffer-local config. Should have the same
333 |   structure as |MiniHipatterns.config|. Values will be taken in this order:
334 |   - From this `config` argument (if supplied).
335 |   - From buffer-local config in `vim.b.minihipatterns_config` (if present).
336 |   - From global config (if |MiniHipatterns.setup()| was called).
337 |   - From default values.
338 | 
339 | ------------------------------------------------------------------------------
340 |                                                       *MiniHipatterns.disable()*
341 |                        `MiniHipatterns.disable`({buf_id})
342 | Disable highlighting in buffer
343 | 
344 | Note that if |MiniHipatterns.setup()| was called, the effect is present
345 | until the next auto-enabling event. To permanently disable highlighting in
346 | buffer, set `vim.b.minihipatterns_disable` to `true`
347 | 
348 | Parameters ~
349 | {buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
350 |   Default: 0 for current buffer.
351 | 
352 | ------------------------------------------------------------------------------
353 |                                                        *MiniHipatterns.toggle()*
354 |                   `MiniHipatterns.toggle`({buf_id}, {config})
355 | Toggle highlighting in buffer
356 | 
357 | Call |MiniHipatterns.disable()| if enabled; |MiniHipatterns.enable()| otherwise.
358 | 
359 | Parameters ~
360 | {buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
361 |   Default: 0 for current buffer.
362 | {config} `(table|nil)` Forwarded to |MiniHipatterns.enable()|.
363 | 
364 | ------------------------------------------------------------------------------
365 |                                                        *MiniHipatterns.update()*
366 |            `MiniHipatterns.update`({buf_id}, {from_line}, {to_line})
367 | Update highlighting in range
368 | 
369 | Works only in buffer with enabled highlighting. Effect takes immediately
370 | without delay.
371 | 
372 | Parameters ~
373 | {buf_id} `(number|nil)` Buffer identifier in which to enable highlighting.
374 |   Default: 0 for current buffer.
375 | {from_line} `(number|nil)` Start line from which to update (1-indexed).
376 | {to_line} `(number|nil)` End line from which to update (1-indexed, inclusive).
377 | 
378 | ------------------------------------------------------------------------------
379 |                                           *MiniHipatterns.get_enabled_buffers()*
380 |                      `MiniHipatterns.get_enabled_buffers`()
381 | Get an array of enabled buffers
382 | 
383 | Return ~
384 | `(table)` Array of buffer identifiers with enabled highlighting.
385 | 
386 | ------------------------------------------------------------------------------
387 |                                                   *MiniHipatterns.get_matches()*
388 |              `MiniHipatterns.get_matches`({buf_id}, {highlighters})
389 | Get buffer matches
390 | 
391 | Parameters ~
392 | {buf_id} `(number|nil)` Buffer identifier for which to return matches.
393 |   Default: `nil` for current buffer.
394 | {highlighters} `(table|nil)` Array of highlighter identifiers (as in
395 |   `highlighters` field of |MiniHipatterns.config|) for which to return matches.
396 |   Default: all available highlighters (ordered by string representation).
397 | 
398 | Return ~
399 | `(table)` Array of buffer matches which are tables with following fields:
400 |   - <bufnr> `(number)` - buffer identifier of a match.
401 |   - <highlighter> `(any)` - highlighter identifier which produced the match.
402 |   - <lnum> `(number)` - line number of the match start (starts with 1).
403 |   - <col> `(number)` - column number of the match start (starts with 1).
404 |   - <end_lnum> `(number|nil)` - line number of the match end (starts with 1).
405 |   - <end_col> `(number|nil)` - column number next to the match end
406 |     (implements end-exclusive region; starts with 1).
407 |   - <hl_group> `(string|nil)` - name of match's highlight group.
408 | 
409 |   Matches are ordered first by supplied `highlighters`, then by line and
410 |   column of match start.
411 | 
412 | ------------------------------------------------------------------------------
413 |                                                 *MiniHipatterns.gen_highlighter*
414 |                         `MiniHipatterns.gen_highlighter`
415 | Generate builtin highlighters
416 | 
417 | This is a table with function elements. Call to actually get highlighter.
418 | 
419 | ------------------------------------------------------------------------------
420 |                                     *MiniHipatterns.gen_highlighter.hex_color()*
421 |                `MiniHipatterns.gen_highlighter.hex_color`({opts})
422 | Highlight hex color string
423 | 
424 | This will match color hex string in format `#rrggbb` and highlight it
425 | according to `opts.style` displaying matched color.
426 | 
427 | Highlight group is computed using |MiniHipatterns.compute_hex_color_group()|,
428 | so all its usage notes apply here.
429 | 
430 | Parameters ~
431 | {opts} `(table|nil)` Options. Possible fields:
432 |   - <style> `(string)` - one of:
433 |       - `'full'` -  highlight background of whole hex string with it. Default.
434 |       - `'#'` - highlight background of only `#`.
435 |       - `'line'` - highlight underline with that color.
436 |       - `'inline'` - highlight text of <inline_text>.
437 |         Note: requires Neovim>=0.10.
438 |   - <priority> `(number)` - priority of highlighting. Default: 200.
439 |   - <filter> `(function)` - callable object used to filter buffers in which
440 |     highlighting will take place. It should take buffer identifier as input
441 |     and return `false` or `nil` to not highlight inside this buffer.
442 |   - <inline_text> `(string)` - string to be placed and highlighted with color
443 |     to the right of match in case <style> is "inline". Default: "█".
444 | 
445 | Return ~
446 | `(table)` Highlighter table ready to be used as part of `config.highlighters`.
447 |   Both `pattern` and `group` are callable.
448 | 
449 | Usage ~
450 | >lua
451 |   local hipatterns = require('mini.hipatterns')
452 |   hipatterns.setup({
453 |     highlighters = {
454 |       hex_color = hipatterns.gen_highlighter.hex_color(),
455 |     }
456 |   })
457 | <
458 | ------------------------------------------------------------------------------
459 |                                       *MiniHipatterns.compute_hex_color_group()*
460 |          `MiniHipatterns.compute_hex_color_group`({hex_color}, {style})
461 | Compute and create group to highlight hex color string
462 | 
463 | Notes:
464 | - This works properly only with enabled |'termguicolors'|.
465 | 
466 | - To increase performance, it caches highlight groups per `hex_color` and
467 |   `style` combination. Needs a call to |MiniHipatterns.setup()| to have
468 |   these groups be persistent across color scheme changes.
469 | 
470 | Parameters ~
471 | {hex_color} `(string)` Hex color string in format `#rrggbb`.
472 | {style|nil} `(string)` One of:
473 |   - `'bg'` - highlight background with `hex_color` and foreground with black or
474 |     white (whichever is more visible). Default.
475 |   - `'fg'` - highlight foreground with `hex_color`.
476 |   - `'line'` - highlight underline with `hex_color`.
477 | 
478 | Return ~
479 | `(string)` Name of created highlight group appropriate to show `hex_color`.
480 | 
481 | 
482 |  vim:tw=78:ts=8:noet:ft=help:norl:


--------------------------------------------------------------------------------
/lua/mini/hipatterns.lua:
--------------------------------------------------------------------------------
   1 | --- *mini.hipatterns* Highlight patterns in text
   2 | ---
   3 | --- MIT License Copyright (c) 2023 Evgeni Chasnovski
   4 | 
   5 | --- Features:
   6 | --- - Highlight text with configurable patterns and highlight groups (can be
   7 | ---   string or callable).
   8 | ---
   9 | --- - Highlighting is updated asynchronously with configurable debounce delay.
  10 | ---
  11 | --- - Function to get matches in a buffer (see |MiniHipatterns.get_matches()|).
  12 | ---
  13 | --- See |MiniHipatterns-examples| for common configuration examples.
  14 | ---
  15 | --- Notes:
  16 | --- - It does not define any highlighters by default. Add to `config.highlighters`
  17 | ---   to have a visible effect.
  18 | ---
  19 | --- - Sometimes (especially during frequent buffer updates on same line numbers)
  20 | ---   highlighting can be outdated or not applied when it should be. This is due
  21 | ---   to asynchronous nature of updates reacting to text changes (via
  22 | ---   `on_lines` of |nvim_buf_attach()|).
  23 | ---   To make them up to date, use one of the following:
  24 | ---     - Scroll window (for example, with |CTRL-E| / |CTRL-Y|). This will ensure
  25 | ---       up to date highlighting inside window view.
  26 | ---     - Hide and show buffer.
  27 | ---     - Execute `:edit` (if you enabled highlighting with |MiniHipatterns.setup()|).
  28 | ---     - Manually call |MiniHipatterns.update()|.
  29 | ---
  30 | --- - If you experience flicker when typing near highlighted pattern in Insert
  31 | ---   mode, it might be due to `delay` configuration of |mini.completion| or
  32 | ---   using built-in completion.
  33 | ---   For better experience with 'mini.completion', make sure that its
  34 | ---   `delay.completion` is less than this module's `delay.text_change` (which
  35 | ---   it is by default).
  36 | ---   The reason for this is (currently unresolvable) limitations of Neovim's
  37 | ---   built-in completion implementation.
  38 | ---
  39 | --- # Setup ~
  40 | ---
  41 | --- Setting up highlights can be done in two ways:
  42 | --- - Manually for every buffer with `require('mini.hipatterns').enable()`.
  43 | ---   This will enable highlighting only in one particular buffer until it is
  44 | ---   unloaded (which also includes calling `:edit` on current file).
  45 | ---
  46 | --- - Globally with `require('mini.hipatterns').setup({})` (replace `{}` with
  47 | ---   your `config` table). This will auto-enable highlighting in "normal"
  48 | ---   buffers (see 'buftype'). Use |MiniHipatterns.enable()| to manually enable
  49 | ---   in other buffers.
  50 | ---   It will also create global Lua table `MiniHipatterns` which you can use
  51 | ---   for scripting or manually (with `:lua MiniHipatterns.*`).
  52 | ---
  53 | --- See |MiniHipatterns.config| for `config` structure and default values.
  54 | ---
  55 | --- You can override runtime config settings (like highlighters and delays)
  56 | --- locally to buffer inside `vim.b.minihipatterns_config` which should have
  57 | --- same structure as `MiniHipatterns.config`.
  58 | --- See |mini.nvim-buffer-local-config| for more details.
  59 | ---
  60 | --- # Comparisons ~
  61 | ---
  62 | --- - [folke/todo-comments](https://github.com/folke/todo-comments):
  63 | ---     - Oriented for "TODO", "NOTE", "FIXME" like patterns, while this module
  64 | ---       can work with any Lua patterns and computable highlight groups.
  65 | ---     - Has functionality beyond text highlighting (sign placing,
  66 | ---       "telescope.nvim" extension, etc.), while this module only focuses on
  67 | ---       highlighting text.
  68 | --- - [folke/paint.nvim](https://github.com/folke/paint.nvim):
  69 | ---     - Mostly similar to this module, but with slightly less functionality,
  70 | ---       such as computed pattern and highlight group, asynchronous delay, etc.
  71 | --- - [NvChad/nvim-colorizer.lua](https://github.com/NvChad/nvim-colorizer.lua):
  72 | ---     - Oriented for color highlighting, while this module can work with any
  73 | ---       Lua patterns and computable highlight groups.
  74 | ---     - Has more built-in color spaces to highlight, while this module out of
  75 | ---       the box provides only hex color highlighting
  76 | ---       (see |MiniHipatterns.gen_highlighter.hex_color()|). Other types are
  77 | ---       also possible to implement.
  78 | --- - [uga-rosa/ccc.nvim](https://github.com/uga-rosa/ccc.nvim):
  79 | ---     - Has more than color highlighting functionality, which is compared to
  80 | ---       this module in the same way as 'NvChad/nvim-colorizer.lua'.
  81 | ---
  82 | --- # Highlight groups ~
  83 | ---
  84 | --- - `MiniHipatternsFixme` - suggested group to use for `FIXME`-like patterns.
  85 | --- - `MiniHipatternsHack` - suggested group to use for `HACK`-like patterns.
  86 | --- - `MiniHipatternsTodo` - suggested group to use for `TODO`-like patterns.
  87 | --- - `MiniHipatternsNote` - suggested group to use for `NOTE`-like patterns.
  88 | ---
  89 | --- To change any highlight group, set it directly with |nvim_set_hl()|.
  90 | ---
  91 | --- # Disabling ~
  92 | ---
  93 | --- This module can be disabled in three ways:
  94 | --- - Globally: set `vim.g.minihipatterns_disable` to `true`.
  95 | --- - Locally for buffer permanently: set `vim.b.minihipatterns_disable` to `true`.
  96 | --- - Locally for buffer temporarily (until next auto-enabling event if set up
  97 | ---   with |MiniHipatterns.setup()|): call |MiniHipatterns.disable()|.
  98 | ---
  99 | --- Considering high number of different scenarios and customization
 100 | --- intentions, writing exact rules for disabling module's functionality is
 101 | --- left to user. See |mini.nvim-disabling-recipes| for common recipes.
 102 | ---@tag MiniHipatterns
 103 | 
 104 | --- # Common configuration examples ~
 105 | ---
 106 | --- - Special words used to convey different level of attention: >lua
 107 | ---
 108 | ---   require('mini.hipatterns').setup({
 109 | ---     highlighters = {
 110 | ---       fixme = { pattern = 'FIXME', group = 'MiniHipatternsFixme' },
 111 | ---       hack  = { pattern = 'HACK',  group = 'MiniHipatternsHack'  },
 112 | ---       todo  = { pattern = 'TODO',  group = 'MiniHipatternsTodo'  },
 113 | ---       note  = { pattern = 'NOTE',  group = 'MiniHipatternsNote'  },
 114 | ---     }
 115 | ---   })
 116 | --- <
 117 | --- - To match only when pattern appears as a standalone word, use frontier
 118 | ---   patterns `%f`. For example, instead of `'TODO'` pattern use
 119 | ---   `'%f[%w]()TODO()%f[%W]'`. In this case, for example, 'TODOING' or 'MYTODO'
 120 | ---   won't match, but 'TODO' and 'TODO:' will.
 121 | ---
 122 | --- - Color hex (like `#rrggbb`) highlighting: >lua
 123 | ---
 124 | ---   local hipatterns = require('mini.hipatterns')
 125 | ---   hipatterns.setup({
 126 | ---     highlighters = {
 127 | ---       hex_color = hipatterns.gen_highlighter.hex_color(),
 128 | ---     }
 129 | ---   })
 130 | --- <
 131 | ---   You can customize which part of hex color is highlighted by using `style`
 132 | ---   field of input options. See |MiniHipatterns.gen_highlighter.hex_color()|.
 133 | ---
 134 | --- - Colored words: >lua
 135 | ---
 136 | ---   local words = { red = '#ff0000', green = '#00ff00', blue = '#0000ff' }
 137 | ---   local word_color_group = function(_, match)
 138 | ---     local hex = words[match]
 139 | ---     if hex == nil then return nil end
 140 | ---     return MiniHipatterns.compute_hex_color_group(hex, 'bg')
 141 | ---   end
 142 | ---
 143 | ---   local hipatterns = require('mini.hipatterns')
 144 | ---   hipatterns.setup({
 145 | ---     highlighters = {
 146 | ---       word_color = { pattern = '%S+', group = word_color_group },
 147 | ---     },
 148 | ---   })
 149 | --- <
 150 | --- - Trailing whitespace (if don't want to use more specific |mini.trailspace|): >lua
 151 | ---
 152 | ---   { pattern = '%f[%s]%s*$', group = 'Error' }
 153 | --- <
 154 | --- - Censor certain sensitive information: >lua
 155 | ---
 156 | ---   local censor_extmark_opts = function(_, match, _)
 157 | ---     local mask = string.rep('x', vim.fn.strchars(match))
 158 | ---     return {
 159 | ---       virt_text = { { mask, 'Comment' } }, virt_text_pos = 'overlay',
 160 | ---       priority = 200, right_gravity = false,
 161 | ---     }
 162 | ---   end
 163 | ---
 164 | ---   require('mini.hipatterns').setup({
 165 | ---     highlighters = {
 166 | ---       censor = {
 167 | ---         pattern = 'password: ()%S+()',
 168 | ---         group = '',
 169 | ---         extmark_opts = censor_extmark_opts,
 170 | ---       },
 171 | ---     },
 172 | ---   })
 173 | --- <
 174 | --- - Enable only in certain filetypes. There are at least these ways to do it:
 175 | ---     - (Suggested) With `vim.b.minihipatterns_config` in |filetype-plugin|.
 176 | ---       Basically, create "after/ftplugin/<filetype>.lua" file in your config
 177 | ---       directory (see |$XDG_CONFIG_HOME|) and define `vim.b.minihipatterns_config`
 178 | ---       there with filetype specific highlighters.
 179 | ---
 180 | ---       This assumes `require('mini.hipatterns').setup()` call.
 181 | ---
 182 | ---       For example, to highlight keywords in EmmyLua comments in Lua files,
 183 | ---       create "after/ftplugin/lua.lua" with the following content: >lua
 184 | ---
 185 | ---         vim.b.minihipatterns_config = {
 186 | ---           highlighters = {
 187 | ---             emmylua = { pattern = '^%s*%-%-%-()@%w+()', group = 'Special' }
 188 | ---           }
 189 | ---         }
 190 | --- <
 191 | ---     - Use callable `pattern` with condition. For example: >lua
 192 | ---
 193 | ---       require('mini.hipatterns').setup({
 194 | ---         highlighters = {
 195 | ---           emmylua = {
 196 | ---             pattern = function(buf_id)
 197 | ---               if vim.bo[buf_id].filetype ~= 'lua' then return nil end
 198 | ---               return '^%s*%-%-%-()@%w+()'
 199 | ---             end,
 200 | ---             group = 'Special',
 201 | ---           },
 202 | ---         },
 203 | ---       })
 204 | --- <
 205 | --- - Disable only in certain filetypes. Enable with |MiniHipatterns.setup()|
 206 | ---   and set `vim.b.minihipatterns_disable` buffer-local variable to `true` for
 207 | ---   buffer you want disabled. See |mini.nvim-disabling-recipes| for more examples.
 208 | ---@tag MiniHipatterns-examples
 209 | 
 210 | ---@alias __hipatterns_buf_id number|nil Buffer identifier in which to enable highlighting.
 211 | ---   Default: 0 for current buffer.
 212 | 
 213 | ---@diagnostic disable:undefined-field
 214 | ---@diagnostic disable:discard-returns
 215 | ---@diagnostic disable:unused-local
 216 | 
 217 | -- Module definition ==========================================================
 218 | local MiniHipatterns = {}
 219 | local H = {}
 220 | 
 221 | --- Module setup
 222 | ---
 223 | ---@param config table|nil Module config table. See |MiniHipatterns.config|.
 224 | ---
 225 | ---@usage >lua
 226 | ---   require('mini.hipatterns').setup({}) -- replace {} with your config table
 227 | ---                                        -- needs `highlighters` field present
 228 | --- <
 229 | MiniHipatterns.setup = function(config)
 230 |   -- Export module
 231 |   _G.MiniHipatterns = MiniHipatterns
 232 | 
 233 |   -- Setup config
 234 |   config = H.setup_config(config)
 235 | 
 236 |   -- Apply config
 237 |   H.apply_config(config)
 238 | 
 239 |   -- Define behavior
 240 |   H.create_autocommands()
 241 |   for _, win_id in ipairs(vim.api.nvim_list_wins()) do
 242 |     H.auto_enable({ buf = vim.api.nvim_win_get_buf(win_id) })
 243 |   end
 244 | 
 245 |   -- Create default highlighting
 246 |   H.create_default_hl()
 247 | end
 248 | 
 249 | --- Defaults ~
 250 | ---@eval return MiniDoc.afterlines_to_code(MiniDoc.current.eval_section)
 251 | ---@text # Highlighters ~
 252 | ---
 253 | --- `highlighters` table defines which patterns will be highlighted by placing
 254 | --- |extmark| at the match start. It might or might not have explicitly named
 255 | --- fields, but having them is recommended and is required for proper use of
 256 | --- `vim.b.minihipatterns_config` as buffer-local config. By default it is
 257 | --- empty expecting user definition.
 258 | ---
 259 | --- Each entry defines single highlighter as a table with the following fields:
 260 | --- - <pattern> `(string|function|table)` - Lua pattern to highlight. Can be
 261 | ---   either string, callable returning the string, or an array of those.
 262 | ---   If string:
 263 | ---     - It can have submatch delimited by placing `()` on start and end, NOT
 264 | ---       by surrounding it with parenthesis (results in an error containing
 265 | ---       `number expected, got string`). Example: `xx()abcd()xx` will match
 266 | ---       `abcd` only if `xx` is placed before and after it.
 267 | ---
 268 | ---   If callable:
 269 | ---     - It will be called for every enabled buffer with its identifier as input.
 270 | ---       Should return single string pattern or `nil` (meaning this particular
 271 | ---       highlighter will not work in this particular buffer).
 272 | ---
 273 | ---   If array:
 274 | ---     - Each element is matched and highlighted with the same highlight group.
 275 | ---
 276 | ---     Note: matching does not result in overlapping (sub)matches (similarly
 277 | ---     to how |cpo-c| works). For example, with line `xxxxxxx`:
 278 | ---     - Pattern `xxx` matches columns 1-3, 4-6.
 279 | ---     - Pattern `()xx()x` matches columns 1-2, 3-4, 5-6.
 280 | ---     - Pattern `x()xx()` matches columns 2-3, 5-6.
 281 | ---     - Pattern `x()x()x` matches columns 2-2, 4-4, 6-6.
 282 | ---
 283 | --- - <group> `(string|function)` - name of highlight group to use. Can be either
 284 | ---   string or callable returning the string.
 285 | ---   If callable:
 286 | ---     - It will be called for every pattern match with the following arguments:
 287 | ---         - `buf_id` - buffer identifier.
 288 | ---         - `match` - string pattern match to be highlighted.
 289 | ---         - `data` - extra table with information about the match.
 290 | ---           It has at least these fields:
 291 | ---             - <full_match> - string with full pattern match.
 292 | ---             - <line> - match line number (1-indexed).
 293 | ---             - <from_col> - match starting byte column (1-indexed).
 294 | ---             - <to_col> - match ending byte column (1-indexed, inclusive).
 295 | ---
 296 | ---     - It can return `nil` meaning this particular match will not be highlighted.
 297 | ---
 298 | --- - <extmark_opts> `(table|function|nil)` - optional extra options
 299 | ---   for |nvim_buf_set_extmark()|. If callable, will be called in the same way
 300 | ---   as callable <group> (`data` will also contain `hl_group` key with <group>
 301 | ---   value) and should return a table with all options for extmark (including
 302 | ---   `end_row`, `end_col`, `hl_group`, and `priority`).
 303 | ---
 304 | --- See "Common use cases" section for the examples.
 305 | ---
 306 | --- # Delay ~
 307 | ---
 308 | --- `delay` is a table defining delays in milliseconds used for asynchronous
 309 | --- highlighting process.
 310 | ---
 311 | --- `delay.text_change` is used to delay highlighting updates by accumulating
 312 | --- them (in debounce fashion). Smaller values will lead to faster response but
 313 | --- more frequent updates. Bigger - slower response but less frequent updates.
 314 | ---
 315 | --- `delay.scroll` is used to delay updating highlights in current window view
 316 | --- during scrolling (see |WinScrolled| event). These updates are present to
 317 | --- ensure up to date highlighting after scroll.
 318 | MiniHipatterns.config = {
 319 |   -- Table with highlighters (see |MiniHipatterns.config| for more details).
 320 |   -- Nothing is defined by default. Add manually for visible effect.
 321 |   highlighters = {},
 322 | 
 323 |   -- Delays (in ms) defining asynchronous highlighting process
 324 |   delay = {
 325 |     -- How much to wait for update after every text change
 326 |     text_change = 200,
 327 | 
 328 |     -- How much to wait for update after window scroll
 329 |     scroll = 50,
 330 |   },
 331 | }
 332 | --minidoc_afterlines_end
 333 | 
 334 | --- Enable highlighting in buffer
 335 | ---
 336 | --- Notes:
 337 | --- - With default config it will highlight nothing, as there are no default
 338 | ---   highlighters.
 339 | ---
 340 | --- - Buffer highlighting is enabled until buffer is unloaded from memory
 341 | ---   or |MiniHipatterns.disable()| on this buffer is called.
 342 | ---
 343 | --- - `:edit` disables this, as it is mostly equivalent to closing and opening
 344 | ---   buffer. In order for highlighting to persist after `:edit`, call
 345 | ---   |MiniHipatterns.setup()|.
 346 | ---
 347 | ---@param buf_id __hipatterns_buf_id
 348 | ---@param config table|nil Optional buffer-local config. Should have the same
 349 | ---   structure as |MiniHipatterns.config|. Values will be taken in this order:
 350 | ---   - From this `config` argument (if supplied).
 351 | ---   - From buffer-local config in `vim.b.minihipatterns_config` (if present).
 352 | ---   - From global config (if |MiniHipatterns.setup()| was called).
 353 | ---   - From default values.
 354 | MiniHipatterns.enable = function(buf_id, config)
 355 |   buf_id = H.validate_buf_id(buf_id)
 356 |   config = H.validate_config_arg(config)
 357 | 
 358 |   -- Don't enable more than once
 359 |   if H.is_buf_enabled(buf_id) then return end
 360 | 
 361 |   -- Register enabled buffer with cached data for performance
 362 |   H.update_cache(buf_id, config)
 363 | 
 364 |   -- Add buffer watchers
 365 |   vim.api.nvim_buf_attach(buf_id, false, {
 366 |     -- Called on every text change (`:h nvim_buf_lines_event`)
 367 |     on_lines = function(_, _, _, from_line, _, to_line)
 368 |       local buf_cache = H.cache[buf_id]
 369 |       -- Properly detach if highlighting is disabled
 370 |       if buf_cache == nil then return true end
 371 |       H.process_lines(buf_id, from_line + 1, to_line, buf_cache.delay.text_change)
 372 |     end,
 373 | 
 374 |     -- Called when buffer content is changed outside of current session
 375 |     on_reload = function() pcall(MiniHipatterns.update, buf_id) end,
 376 | 
 377 |     -- Called when buffer is unloaded from memory (`:h nvim_buf_detach_event`),
 378 |     -- **including** `:edit` command
 379 |     on_detach = function() MiniHipatterns.disable(buf_id) end,
 380 |   })
 381 | 
 382 |   -- Add buffer autocommands
 383 |   local augroup = vim.api.nvim_create_augroup('MiniHipatternsBuffer' .. buf_id, { clear = true })
 384 |   H.cache[buf_id].augroup = augroup
 385 | 
 386 |   local update_buf = vim.schedule_wrap(function()
 387 |     if not H.is_buf_enabled(buf_id) then return end
 388 | 
 389 |     H.update_cache(buf_id, config)
 390 | 
 391 |     local delay_ms = H.cache[buf_id].delay.text_change
 392 |     H.process_lines(buf_id, 1, vim.api.nvim_buf_line_count(buf_id), delay_ms)
 393 |   end)
 394 | 
 395 |   vim.api.nvim_create_autocmd(
 396 |     { 'BufWinEnter', 'FileType' },
 397 |     { group = augroup, buffer = buf_id, callback = update_buf, desc = 'Update highlighting for whole buffer' }
 398 |   )
 399 | 
 400 |   vim.api.nvim_create_autocmd(
 401 |     'WinScrolled',
 402 |     { group = augroup, buffer = buf_id, callback = H.update_view, desc = 'Update highlighting in view' }
 403 |   )
 404 | 
 405 |   -- Add highlighting to whole buffer
 406 |   H.process_lines(buf_id, 1, vim.api.nvim_buf_line_count(buf_id), 0)
 407 | end
 408 | 
 409 | --- Disable highlighting in buffer
 410 | ---
 411 | --- Note that if |MiniHipatterns.setup()| was called, the effect is present
 412 | --- until the next auto-enabling event. To permanently disable highlighting in
 413 | --- buffer, set `vim.b.minihipatterns_disable` to `true`
 414 | ---
 415 | ---@param buf_id __hipatterns_buf_id
 416 | MiniHipatterns.disable = function(buf_id)
 417 |   buf_id = H.validate_buf_id(buf_id)
 418 | 
 419 |   local buf_cache = H.cache[buf_id]
 420 |   if buf_cache == nil then return end
 421 |   H.cache[buf_id] = nil
 422 | 
 423 |   vim.api.nvim_del_augroup_by_id(buf_cache.augroup)
 424 |   for _, ns in pairs(H.ns_id) do
 425 |     H.clear_namespace(buf_id, ns, 0, -1)
 426 |   end
 427 | end
 428 | 
 429 | --- Toggle highlighting in buffer
 430 | ---
 431 | --- Call |MiniHipatterns.disable()| if enabled; |MiniHipatterns.enable()| otherwise.
 432 | ---
 433 | ---@param buf_id __hipatterns_buf_id
 434 | ---@param config table|nil Forwarded to |MiniHipatterns.enable()|.
 435 | MiniHipatterns.toggle = function(buf_id, config)
 436 |   buf_id = H.validate_buf_id(buf_id)
 437 |   config = H.validate_config_arg(config)
 438 | 
 439 |   if H.is_buf_enabled(buf_id) then
 440 |     MiniHipatterns.disable(buf_id)
 441 |   else
 442 |     MiniHipatterns.enable(buf_id, config)
 443 |   end
 444 | end
 445 | 
 446 | --- Update highlighting in range
 447 | ---
 448 | --- Works only in buffer with enabled highlighting. Effect takes immediately
 449 | --- without delay.
 450 | ---
 451 | ---@param buf_id __hipatterns_buf_id
 452 | ---@param from_line number|nil Start line from which to update (1-indexed).
 453 | ---@param to_line number|nil End line from which to update (1-indexed, inclusive).
 454 | MiniHipatterns.update = function(buf_id, from_line, to_line)
 455 |   buf_id = H.validate_buf_id(buf_id)
 456 | 
 457 |   if not H.is_buf_enabled(buf_id) then H.error(string.format('Buffer %d is not enabled.', buf_id)) end
 458 | 
 459 |   from_line = from_line or 1
 460 |   if type(from_line) ~= 'number' then H.error('`from_line` should be a number.') end
 461 |   to_line = to_line or vim.api.nvim_buf_line_count(buf_id)
 462 |   if type(to_line) ~= 'number' then H.error('`to_line` should be a number.') end
 463 | 
 464 |   -- Process lines immediately without delay
 465 |   H.process_lines(buf_id, from_line, to_line, 0)
 466 | end
 467 | 
 468 | --- Get an array of enabled buffers
 469 | ---
 470 | ---@return table Array of buffer identifiers with enabled highlighting.
 471 | MiniHipatterns.get_enabled_buffers = function()
 472 |   local res = {}
 473 |   for buf_id, _ in pairs(H.cache) do
 474 |     if vim.api.nvim_buf_is_valid(buf_id) then
 475 |       table.insert(res, buf_id)
 476 |     else
 477 |       -- Clean up if buffer is invalid and for some reason is still enabled
 478 |       H.cache[buf_id] = nil
 479 |     end
 480 |   end
 481 | 
 482 |   -- Ensure consistent order
 483 |   table.sort(res)
 484 | 
 485 |   return res
 486 | end
 487 | 
 488 | --- Get buffer matches
 489 | ---
 490 | ---@param buf_id number|nil Buffer identifier for which to return matches.
 491 | ---   Default: `nil` for current buffer.
 492 | ---@param highlighters table|nil Array of highlighter identifiers (as in
 493 | ---   `highlighters` field of |MiniHipatterns.config|) for which to return matches.
 494 | ---   Default: all available highlighters (ordered by string representation).
 495 | ---
 496 | ---@return table Array of buffer matches which are tables with following fields:
 497 | ---   - <bufnr> `(number)` - buffer identifier of a match.
 498 | ---   - <highlighter> `(any)` - highlighter identifier which produced the match.
 499 | ---   - <lnum> `(number)` - line number of the match start (starts with 1).
 500 | ---   - <col> `(number)` - column number of the match start (starts with 1).
 501 | ---   - <end_lnum> `(number|nil)` - line number of the match end (starts with 1).
 502 | ---   - <end_col> `(number|nil)` - column number next to the match end
 503 | ---     (implements end-exclusive region; starts with 1).
 504 | ---   - <hl_group> `(string|nil)` - name of match's highlight group.
 505 | ---
 506 | ---   Matches are ordered first by supplied `highlighters`, then by line and
 507 | ---   column of match start.
 508 | MiniHipatterns.get_matches = function(buf_id, highlighters)
 509 |   buf_id = (buf_id == nil or buf_id == 0) and vim.api.nvim_get_current_buf() or buf_id
 510 |   if not (type(buf_id) == 'number' and vim.api.nvim_buf_is_valid(buf_id)) then
 511 |     H.error('`buf_id` is not valid buffer identifier.')
 512 |   end
 513 | 
 514 |   local all_highlighters = H.get_all_highlighters()
 515 |   highlighters = highlighters or all_highlighters
 516 |   if not H.islist(highlighters) then H.error('`highlighters` should be an array.') end
 517 |   highlighters = vim.tbl_filter(function(x) return vim.tbl_contains(all_highlighters, x) end, highlighters)
 518 | 
 519 |   local position_compare = function(a, b) return a[2] < b[2] or (a[2] == b[2] and a[3] < b[3]) end
 520 |   local res = {}
 521 |   for _, hi_id in ipairs(highlighters) do
 522 |     local extmarks = H.get_extmarks(buf_id, H.ns_id[hi_id], 0, -1, { details = true })
 523 |     table.sort(extmarks, position_compare)
 524 | 
 525 |     for _, extmark in ipairs(extmarks) do
 526 |       local end_lnum, end_col = extmark[4].end_row, extmark[4].end_col
 527 |       end_lnum = type(end_lnum) == 'number' and (end_lnum + 1) or end_lnum
 528 |       end_col = type(end_col) == 'number' and (end_col + 1) or end_col
 529 |       --stylua: ignore
 530 |       local entry = {
 531 |         bufnr = buf_id,        highlighter = hi_id,
 532 |         lnum = extmark[2] + 1, col = extmark[3] + 1,
 533 |         end_lnum = end_lnum,   end_col = end_col,
 534 |         hl_group = extmark[4].hl_group,
 535 |       }
 536 |       table.insert(res, entry)
 537 |     end
 538 |   end
 539 |   return res
 540 | end
 541 | 
 542 | --- Generate builtin highlighters
 543 | ---
 544 | --- This is a table with function elements. Call to actually get highlighter.
 545 | MiniHipatterns.gen_highlighter = {}
 546 | 
 547 | --- Highlight hex color string
 548 | ---
 549 | --- This will match color hex string in format `#rrggbb` and highlight it
 550 | --- according to `opts.style` displaying matched color.
 551 | ---
 552 | --- Highlight group is computed using |MiniHipatterns.compute_hex_color_group()|,
 553 | --- so all its usage notes apply here.
 554 | ---
 555 | ---@param opts table|nil Options. Possible fields:
 556 | ---   - <style> `(string)` - one of:
 557 | ---       - `'full'` -  highlight background of whole hex string with it. Default.
 558 | ---       - `'#'` - highlight background of only `#`.
 559 | ---       - `'line'` - highlight underline with that color.
 560 | ---       - `'inline'` - highlight text of <inline_text>.
 561 | ---         Note: requires Neovim>=0.10.
 562 | ---   - <priority> `(number)` - priority of highlighting. Default: 200.
 563 | ---   - <filter> `(function)` - callable object used to filter buffers in which
 564 | ---     highlighting will take place. It should take buffer identifier as input
 565 | ---     and return `false` or `nil` to not highlight inside this buffer.
 566 | ---   - <inline_text> `(string)` - string to be placed and highlighted with color
 567 | ---     to the right of match in case <style> is "inline". Default: "█".
 568 | ---
 569 | ---@return table Highlighter table ready to be used as part of `config.highlighters`.
 570 | ---   Both `pattern` and `group` are callable.
 571 | ---
 572 | ---@usage >lua
 573 | ---   local hipatterns = require('mini.hipatterns')
 574 | ---   hipatterns.setup({
 575 | ---     highlighters = {
 576 | ---       hex_color = hipatterns.gen_highlighter.hex_color(),
 577 | ---     }
 578 | ---   })
 579 | --- <
 580 | MiniHipatterns.gen_highlighter.hex_color = function(opts)
 581 |   local default_opts = { style = 'full', priority = 200, filter = H.always_true, inline_text = '█' }
 582 |   opts = vim.tbl_deep_extend('force', default_opts, opts or {})
 583 | 
 584 |   local style = opts.style
 585 |   if style == 'inline' and vim.fn.has('nvim-0.10') == 0 then
 586 |     H.error('Style "inline" in `gen_highlighter.hex_color()` requires Neovim>=0.10.')
 587 |   end
 588 | 
 589 |   local pattern = style == '#' and '()#()%x%x%x%x%x%x%f[%X]' or '#%x%x%x%x%x%x%f[%X]'
 590 |   local hl_style = ({ full = 'bg', ['#'] = 'bg', line = 'line', inline = 'fg' })[style] or 'bg'
 591 | 
 592 |   local extmark_opts = { priority = opts.priority }
 593 |   if opts.style == 'inline' then
 594 |     local priority, inline_text = opts.priority, opts.inline_text
 595 |     ---@diagnostic disable:cast-local-type
 596 |     extmark_opts = function(_, _, data)
 597 |       local virt_text = { { inline_text, data.hl_group } }
 598 |       return { virt_text = virt_text, virt_text_pos = 'inline', priority = priority, right_gravity = false }
 599 |     end
 600 |   end
 601 | 
 602 |   return {
 603 |     pattern = H.wrap_pattern_with_filter(pattern, opts.filter),
 604 |     group = function(_, _, data) return MiniHipatterns.compute_hex_color_group(data.full_match, hl_style) end,
 605 |     extmark_opts = extmark_opts,
 606 |   }
 607 | end
 608 | 
 609 | --- Compute and create group to highlight hex color string
 610 | ---
 611 | --- Notes:
 612 | --- - This works properly only with enabled |'termguicolors'|.
 613 | ---
 614 | --- - To increase performance, it caches highlight groups per `hex_color` and
 615 | ---   `style` combination. Needs a call to |MiniHipatterns.setup()| to have
 616 | ---   these groups be persistent across color scheme changes.
 617 | ---
 618 | ---@param hex_color string Hex color string in format `#rrggbb`.
 619 | ---@param style|nil string One of:
 620 | ---   - `'bg'` - highlight background with `hex_color` and foreground with black or
 621 | ---     white (whichever is more visible). Default.
 622 | ---   - `'fg'` - highlight foreground with `hex_color`.
 623 | ---   - `'line'` - highlight underline with `hex_color`.
 624 | ---
 625 | ---@return string Name of created highlight group appropriate to show `hex_color`.
 626 | MiniHipatterns.compute_hex_color_group = function(hex_color, style)
 627 |   style = style or 'bg'
 628 |   local hex = hex_color:lower():sub(2)
 629 |   local group_name = string.format('MiniHipatterns_%s_%s', hex, style)
 630 | 
 631 |   -- Use manually tracked table instead of `vim.fn.hlexists()` because the
 632 |   -- latter still returns true for cleared highlights
 633 |   if H.hex_color_groups[group_name] then return group_name end
 634 | 
 635 |   -- Define highlight group if it is not already defined
 636 |   if style == 'bg' then
 637 |     -- Compute opposite color based on Oklab lightness (for better contrast)
 638 |     local opposite = H.compute_opposite_color(hex)
 639 |     vim.api.nvim_set_hl(0, group_name, { fg = opposite, bg = hex_color })
 640 |   end
 641 | 
 642 |   if style == 'fg' then vim.api.nvim_set_hl(0, group_name, { fg = hex_color }) end
 643 | 
 644 |   if style == 'line' then vim.api.nvim_set_hl(0, group_name, { sp = hex_color, underline = true }) end
 645 | 
 646 |   -- Keep track of created groups to properly react on `:hi clear`
 647 |   H.hex_color_groups[group_name] = true
 648 | 
 649 |   return group_name
 650 | end
 651 | 
 652 | -- Helper data ================================================================
 653 | -- Module default config
 654 | H.default_config = vim.deepcopy(MiniHipatterns.config)
 655 | 
 656 | -- Timers
 657 | H.timer_debounce = vim.loop.new_timer()
 658 | H.timer_view = vim.loop.new_timer()
 659 | 
 660 | -- Namespaces per highlighter name
 661 | H.ns_id = {}
 662 | 
 663 | -- Cache of queued changes used for debounced highlighting
 664 | H.change_queue = {}
 665 | 
 666 | -- Cache per enabled buffer
 667 | H.cache = {}
 668 | 
 669 | -- Data about created highlight groups for hex colors
 670 | H.hex_color_groups = {}
 671 | 
 672 | -- Helper functionality =======================================================
 673 | -- Settings -------------------------------------------------------------------
 674 | H.setup_config = function(config)
 675 |   H.check_type('config', config, 'table', true)
 676 |   config = vim.tbl_deep_extend('force', vim.deepcopy(H.default_config), config or {})
 677 | 
 678 |   H.check_type('highlighters', config.highlighters, 'table')
 679 | 
 680 |   H.check_type('delay', config.delay, 'table')
 681 |   H.check_type('delay.text_change', config.delay.text_change, 'number')
 682 |   H.check_type('delay.scroll', config.delay.scroll, 'number')
 683 | 
 684 |   return config
 685 | end
 686 | 
 687 | H.apply_config = function(config) MiniHipatterns.config = config end
 688 | 
 689 | H.create_autocommands = function()
 690 |   local gr = vim.api.nvim_create_augroup('MiniHipatterns', {})
 691 | 
 692 |   local au = function(event, pattern, callback, desc)
 693 |     vim.api.nvim_create_autocmd(event, { group = gr, pattern = pattern, callback = callback, desc = desc })
 694 |   end
 695 | 
 696 |   au('BufEnter', '*', H.auto_enable, 'Enable highlighting')
 697 |   au('ColorScheme', '*', H.create_default_hl, 'Ensure colors')
 698 |   au('ColorScheme', '*', H.on_colorscheme, 'Reload all enabled pattern highlighters')
 699 | end
 700 | 
 701 | H.create_default_hl = function()
 702 |   local hi_link_bold_reverse = function(to, from)
 703 |     local data = vim.api.nvim_get_hl(0, { name = from, link = false })
 704 |     data.default, data.bold, data.reverse = true, true, true
 705 |     data.cterm = { bold = true, reverse = true }
 706 |     vim.api.nvim_set_hl(0, to, data)
 707 |   end
 708 |   hi_link_bold_reverse('MiniHipatternsFixme', 'DiagnosticError')
 709 |   hi_link_bold_reverse('MiniHipatternsHack', 'DiagnosticWarn')
 710 |   hi_link_bold_reverse('MiniHipatternsTodo', 'DiagnosticInfo')
 711 |   hi_link_bold_reverse('MiniHipatternsNote', 'DiagnosticHint')
 712 | end
 713 | 
 714 | H.is_disabled = function(buf_id)
 715 |   local buf_disable = H.get_buf_var(buf_id, 'minihipatterns_disable')
 716 |   return vim.g.minihipatterns_disable == true or buf_disable == true
 717 | end
 718 | 
 719 | H.get_config = function(config, buf_id)
 720 |   local buf_config = H.get_buf_var(buf_id, 'minihipatterns_config') or {}
 721 |   return vim.tbl_deep_extend('force', MiniHipatterns.config, buf_config, config or {})
 722 | end
 723 | 
 724 | H.get_buf_var = function(buf_id, name)
 725 |   if not vim.api.nvim_buf_is_valid(buf_id) then return nil end
 726 |   return vim.b[buf_id or 0][name]
 727 | end
 728 | 
 729 | -- Autocommands ---------------------------------------------------------------
 730 | H.auto_enable = vim.schedule_wrap(function(data)
 731 |   local buf = data.buf
 732 |   if not (vim.api.nvim_buf_is_loaded(buf) and vim.bo[buf].buftype == '') then return end
 733 |   MiniHipatterns.enable(buf)
 734 | end)
 735 | 
 736 | H.update_view = vim.schedule_wrap(function(data)
 737 |   -- Update view only in enabled buffers
 738 |   local buf_cache = H.cache[data.buf]
 739 |   if buf_cache == nil then return end
 740 | 
 741 |   -- NOTE: due to scheduling (which is necessary for better performance),
 742 |   -- current buffer can be not the target one. But as there is no proper (easy
 743 |   -- and/or fast) way to get the view of certain buffer (except the current)
 744 |   -- accept this approach. The main problem of current buffer having not
 745 |   -- enabled highlighting is solved during processing buffer highlighters.
 746 | 
 747 |   -- Debounce without aggregating redraws (only last view should be updated)
 748 |   H.timer_view:stop()
 749 |   H.timer_view:start(buf_cache.delay.scroll, 0, H.process_view)
 750 | end)
 751 | 
 752 | H.on_colorscheme = function()
 753 |   -- Reset created highlight groups for hex colors, as they are probably
 754 |   -- cleared after `:hi clear`
 755 |   H.hex_color_groups = {}
 756 | 
 757 |   -- Reload all currently enabled buffers
 758 |   for buf_id, _ in pairs(H.cache) do
 759 |     MiniHipatterns.disable(buf_id)
 760 |     MiniHipatterns.enable(buf_id)
 761 |   end
 762 | end
 763 | 
 764 | -- Validators -----------------------------------------------------------------
 765 | H.validate_buf_id = function(x)
 766 |   if x == nil or x == 0 then return vim.api.nvim_get_current_buf() end
 767 | 
 768 |   if not (type(x) == 'number' and vim.api.nvim_buf_is_valid(x)) then
 769 |     H.error('`buf_id` should be `nil` or valid buffer id.')
 770 |   end
 771 | 
 772 |   return x
 773 | end
 774 | 
 775 | H.validate_config_arg = function(x)
 776 |   if x == nil or type(x) == 'table' then return x or {} end
 777 |   H.error('`config` should be `nil` or table.')
 778 | end
 779 | 
 780 | H.validate_string = function(x, name)
 781 |   if type(x) == 'string' then return x end
 782 |   H.error(string.format('`%s` should be string.'))
 783 | end
 784 | 
 785 | -- Enabling -------------------------------------------------------------------
 786 | H.is_buf_enabled = function(buf_id) return H.cache[buf_id] ~= nil end
 787 | 
 788 | H.update_cache = function(buf_id, config)
 789 |   local buf_cache = H.cache[buf_id] or {}
 790 |   local buf_config = H.get_config(config, buf_id)
 791 |   buf_cache.highlighters = H.normalize_highlighters(buf_config.highlighters)
 792 |   buf_cache.delay = buf_config.delay
 793 | 
 794 |   H.cache[buf_id] = buf_cache
 795 | end
 796 | 
 797 | H.normalize_highlighters = function(highlighters)
 798 |   local res = {}
 799 |   for hi_name, hi in pairs(highlighters) do
 800 |     -- Allow pattern to be string, callable, or array of those. Convert all
 801 |     -- valid cases into array of callables.
 802 |     local pattern = type(hi.pattern) == 'string' and function() return hi.pattern end or hi.pattern
 803 |     if vim.is_callable(pattern) then pattern = { pattern } end
 804 |     local is_pattern_ok = H.islist(pattern)
 805 |     if is_pattern_ok then
 806 |       for i, pat in ipairs(pattern) do
 807 |         pattern[i] = type(pat) == 'string' and function() return pat end or pat
 808 |         is_pattern_ok = is_pattern_ok and vim.is_callable(pattern[i])
 809 |       end
 810 |     end
 811 | 
 812 |     local group = type(hi.group) == 'string' and function() return hi.group end or hi.group
 813 | 
 814 |     local extmark_opts = hi.extmark_opts or { priority = 200 }
 815 |     if type(extmark_opts) == 'table' then
 816 |       local t = extmark_opts
 817 |       ---@diagnostic disable:cast-local-type
 818 |       extmark_opts = function(_, _, data)
 819 |         local opts = vim.deepcopy(t)
 820 |         opts.hl_group = opts.hl_group or data.hl_group
 821 |         opts.end_row = opts.end_row or (data.line - 1)
 822 |         opts.end_col = opts.end_col or data.to_col
 823 |         return opts
 824 |       end
 825 |     end
 826 | 
 827 |     if is_pattern_ok and vim.is_callable(group) and vim.is_callable(extmark_opts) then
 828 |       res[hi_name] = { pattern = pattern, group = group, extmark_opts = extmark_opts }
 829 |       H.ns_id[hi_name] = vim.api.nvim_create_namespace('MiniHipatterns-' .. hi_name)
 830 |     end
 831 |   end
 832 | 
 833 |   return res
 834 | end
 835 | 
 836 | H.get_all_highlighters = function()
 837 |   local hi_arr = vim.tbl_map(function(x) return { x, tostring(x) } end, vim.tbl_keys(H.ns_id))
 838 |   table.sort(hi_arr, function(a, b) return a[2] < b[2] end)
 839 |   return vim.tbl_map(function(x) return x[1] end, hi_arr)
 840 | end
 841 | 
 842 | -- Processing -----------------------------------------------------------------
 843 | H.process_lines = vim.schedule_wrap(function(buf_id, from_line, to_line, delay_ms)
 844 |   -- Make sure that that at least one line is processed (important to react
 845 |   -- after deleting line with extmark non-trivial `extmark_opts`)
 846 |   table.insert(H.change_queue, { buf_id, math.min(from_line, to_line), math.max(from_line, to_line) })
 847 | 
 848 |   -- Debounce
 849 |   H.timer_debounce:stop()
 850 |   H.timer_debounce:start(delay_ms, 0, H.process_change_queue)
 851 | end)
 852 | 
 853 | H.process_view = vim.schedule_wrap(function()
 854 |   table.insert(H.change_queue, { vim.api.nvim_get_current_buf(), vim.fn.line('w0'), vim.fn.line('w$') })
 855 | 
 856 |   -- Process immediately assuming debouncing should be already done
 857 |   H.process_change_queue()
 858 | end)
 859 | 
 860 | H.process_change_queue = vim.schedule_wrap(function()
 861 |   local queue = H.normalize_change_queue()
 862 | 
 863 |   for buf_id, lines_to_process in pairs(queue) do
 864 |     H.process_buffer_changes(buf_id, lines_to_process)
 865 |   end
 866 | 
 867 |   H.change_queue = {}
 868 | end)
 869 | 
 870 | H.normalize_change_queue = function()
 871 |   local res = {}
 872 |   for _, change in ipairs(H.change_queue) do
 873 |     -- `change` is { buf_id, from_line, to_line }; lines are already 1-indexed
 874 |     local buf_id = change[1]
 875 | 
 876 |     local buf_lines_to_process = res[buf_id] or {}
 877 |     for i = change[2], change[3] do
 878 |       buf_lines_to_process[i] = true
 879 |     end
 880 | 
 881 |     res[buf_id] = buf_lines_to_process
 882 |   end
 883 | 
 884 |   return res
 885 | end
 886 | 
 887 | H.process_buffer_changes = vim.schedule_wrap(function(buf_id, lines_to_process)
 888 |   -- Return early if buffer is not proper.
 889 |   -- Also check if buffer is enabled here mostly for better resilience. It
 890 |   -- might be actually needed due to various `schedule_wrap`s leading to change
 891 |   -- queue entry with not target (and improper) buffer.
 892 |   local buf_cache = H.cache[buf_id]
 893 |   if not vim.api.nvim_buf_is_valid(buf_id) or H.is_disabled(buf_id) or buf_cache == nil then return end
 894 | 
 895 |   -- Optimizations are done assuming small-ish number of highlighters and
 896 |   -- large-ish number of lines to process
 897 | 
 898 |   -- Process highlighters
 899 |   for hi_name, hi in pairs(buf_cache.highlighters) do
 900 |     -- Remove current highlights
 901 |     local ns = H.ns_id[hi_name]
 902 |     for l_num, _ in pairs(lines_to_process) do
 903 |       H.clear_namespace(buf_id, ns, l_num - 1, l_num)
 904 |     end
 905 | 
 906 |     -- Add new highlights
 907 |     for _, pattern in ipairs(hi.pattern) do
 908 |       H.apply_highlighter_pattern(pattern(buf_id), hi, buf_id, ns, lines_to_process)
 909 |     end
 910 |   end
 911 | end)
 912 | 
 913 | H.apply_highlighter_pattern = vim.schedule_wrap(function(pattern, hi, buf_id, ns, lines_to_process)
 914 |   -- Check again because buffer might have become invalid since latest check
 915 |   if not vim.api.nvim_buf_is_valid(buf_id) then return end
 916 | 
 917 |   if type(pattern) ~= 'string' then return end
 918 |   local group, extmark_opts = hi.group, hi.extmark_opts
 919 |   local pattern_has_line_start = pattern:sub(1, 1) == '^'
 920 | 
 921 |   -- Apply per proper line
 922 |   for l_num, _ in pairs(lines_to_process) do
 923 |     local line = H.get_line(buf_id, l_num)
 924 |     local from, to, sub_from, sub_to = line:find(pattern)
 925 | 
 926 |     while from and (from <= to) do
 927 |       -- Compute full pattern match
 928 |       local full_match = line:sub(from, to)
 929 | 
 930 |       -- Compute (possibly inferred) submatch
 931 |       sub_from, sub_to = sub_from or from, sub_to or (to + 1)
 932 |       -- - Make last column end-inclusive
 933 |       sub_to = sub_to - 1
 934 |       local match = line:sub(sub_from, sub_to)
 935 | 
 936 |       -- Set extmark based on submatch
 937 |       local data = { full_match = full_match, line = l_num, from_col = sub_from, to_col = sub_to }
 938 |       local hl_group = group(buf_id, match, data)
 939 |       if hl_group ~= nil then
 940 |         data.hl_group = hl_group
 941 |         H.set_extmark(buf_id, ns, l_num - 1, sub_from - 1, extmark_opts(buf_id, match, data))
 942 |       end
 943 | 
 944 |       -- Overcome an issue that `string.find()` doesn't recognize `^` when
 945 |       -- `init` is more than 1
 946 |       if pattern_has_line_start then break end
 947 | 
 948 |       from, to, sub_from, sub_to = line:find(pattern, sub_to + 1)
 949 |     end
 950 |   end
 951 | end)
 952 | 
 953 | -- Built-in highlighters ------------------------------------------------------
 954 | H.wrap_pattern_with_filter = function(pattern, filter)
 955 |   return function(...)
 956 |     if not filter(...) then return nil end
 957 |     return pattern
 958 |   end
 959 | end
 960 | 
 961 | H.compute_opposite_color = function(hex)
 962 |   local dec = tonumber(hex, 16)
 963 |   local b = H.correct_channel(math.fmod(dec, 256) / 255)
 964 |   local g = H.correct_channel(math.fmod((dec - b) / 256, 256) / 255)
 965 |   local r = H.correct_channel(math.floor(dec / 65536) / 255)
 966 | 
 967 |   local l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b
 968 |   local m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b
 969 |   local s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b
 970 | 
 971 |   local l_, m_, s_ = H.cuberoot(l), H.cuberoot(m), H.cuberoot(s)
 972 | 
 973 |   local L = H.correct_lightness(0.2104542553 * l_ + 0.7936177850 * m_ - 0.0040720468 * s_)
 974 | 
 975 |   return L < 0.5 and '#ffffff' or '#000000'
 976 | end
 977 | 
 978 | -- Function for RGB channel correction. Assumes input in [0; 1] range
 979 | -- https://bottosson.github.io/posts/colorwrong/#what-can-we-do%3F
 980 | H.correct_channel = function(x) return 0.04045 < x and math.pow((x + 0.055) / 1.055, 2.4) or (x / 12.92) end
 981 | 
 982 | -- Function for lightness correction
 983 | -- https://bottosson.github.io/posts/colorpicker/#intermission---a-new-lightness-estimate-for-oklab
 984 | H.correct_lightness = function(x)
 985 |   local k1, k2 = 0.206, 0.03
 986 |   local k3 = (1 + k1) / (1 + k2)
 987 | 
 988 |   return 0.5 * (k3 * x - k1 + math.sqrt((k3 * x - k1) ^ 2 + 4 * k2 * k3 * x))
 989 | end
 990 | 
 991 | -- Utilities ------------------------------------------------------------------
 992 | H.error = function(msg) error('(mini.hipatterns) ' .. msg, 0) end
 993 | 
 994 | H.check_type = function(name, val, ref, allow_nil)
 995 |   if type(val) == ref or (ref == 'callable' and vim.is_callable(val)) or (allow_nil and val == nil) then return end
 996 |   H.error(string.format('`%s` should be %s, not %s', name, ref, type(val)))
 997 | end
 998 | 
 999 | H.get_line = function(buf_id, line_num)
1000 |   return vim.api.nvim_buf_get_lines(buf_id, line_num - 1, line_num, false)[1] or ''
1001 | end
1002 | 
1003 | H.set_extmark = function(...) pcall(vim.api.nvim_buf_set_extmark, ...) end
1004 | 
1005 | H.get_extmarks = function(...)
1006 |   local ok, res = pcall(vim.api.nvim_buf_get_extmarks, ...)
1007 |   if not ok then return {} end
1008 |   return res
1009 | end
1010 | 
1011 | H.clear_namespace = function(...) pcall(vim.api.nvim_buf_clear_namespace, ...) end
1012 | 
1013 | H.always_true = function() return true end
1014 | 
1015 | H.cuberoot = function(x) return math.pow(x, 0.333333) end
1016 | 
1017 | -- TODO: Remove after compatibility with Neovim=0.9 is dropped
1018 | H.islist = vim.fn.has('nvim-0.10') == 1 and vim.islist or vim.tbl_islist
1019 | 
1020 | return MiniHipatterns
1021 | 


--------------------------------------------------------------------------------