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