Repository navigation
Expand file tree
/
Copy pathmini-keymap.txt
More file actions
449 lines (371 loc) · 22 KB
/
Copy pathmini-keymap.txt
File metadata and controls
449 lines (371 loc) · 22 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
*mini.keymap* Special key mappings
MIT License Copyright (c) 2025 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniKeymap*
Features:
- Map keys to perform configurable multi-step actions: if condition for step
one is true - execute step one action, else check step two, and so on until
falling back to executing original keys. This is usually referred to as
"smart" keys (like "smart tab"). See |MiniKeymap.map_multistep()|.
There are many built-in steps targeted for Insert mode mappings of special
keys like <Tab>, <S-Tab>, <CR>, and <BS>:
- Navigate and accept |popupmenu-completion|. Useful for |mini.completion|.
- Navigate and expand |mini.snippets|.
- Execute <CR> and <BS> respecting |mini.pairs|.
- Jump before/after current tree-sitter node.
- Jump before opening and after closing characters (brackets and quotes).
- Increase/decrease indent when cursor is inside of it.
- Delete all whitespace to the left ("hungry backspace").
- Navigate |vim.snippet|.
- Navigate and accept in [hrsh7th/nvim-cmp](https://github.com/hrsh7th/nvim-cmp) completion.
- Navigate and accept in [Saghen/blink.cmp](https://github.com/Saghen/blink.cmp) completion.
- Navigate and expand [L3MON4D3/LuaSnip](https://github.com/L3MON4D3/LuaSnip) snippets.
- Execute <CR> and <BS> respecting [windwp/nvim-autopairs](https://github.com/windwp/nvim-autopairs).
- Map keys as "combo": each key acts immediately plus execute extra action if
all are typed within configurable delay between each other.
See |MiniKeymap.map_combo()|. Some of the common use cases include:
- Map insertable keys (like "jk", "kj") in Insert and Command-line mode
to exit into Normal mode.
- Fight against bad habits of pressing the same navigation key by showing
a notification if there are too many of them pressed in a row.
Sources with more details:
- |MiniKeymap-examples|
# Setup ~
This module doesn't need setup, but it can be done to improve usability.
Setup with `require('mini.keymap').setup({})` (replace `{}` with your `config`
table). It will create global Lua table `MiniKeymap` which you can use for
scripting or manually (with `:lua MiniKeymap.*`).
See |MiniKeymap.config| for `config` structure and default values.
This module doesn't have runtime options, so using `vim.b.minikeymap_config`
will have no effect here.
# Comparisons ~
- [max397574/better-escape.nvim](https://github.com/max397574/better-escape.nvim):
- Mostly similar to |MiniKeymap.map_combo()| with a different approach
to creating mappings.
- Mostly targeted for Insert mode mappings as pressed keys get removed
automatically after typed. This module allows more general cases while
requiring explicit removal of keys (usually via explicit `<BS><BS>`).
- [abecodes/tabout.nvim](https://github.com/abecodes/tabout.nvim):
- Similar general idea as in `'jump_{after,before}_tsnode'` steps
of |MiniKeymap.map_multistep()|.
- Works only with enabled tree-sitter parser. This module provides
fallback via 'jump_after_close' and 'jump_before_open' that work
without tree-sitter parser.
- 'tabout.nvim' has finer control of how the tree-sitter node movement
is done, while this module has "jump outside of current node" behavior.
# Disabling ~
To disable acting in mappings, set `vim.g.minikeymap_disable` (globally) or
`vim.b.minikeymap_disable` (for a buffer) to `true`. 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.
------------------------------------------------------------------------------
*MiniKeymap-examples*
# Multi-step ~
See |MiniKeymap.map_multistep()| for a general description of how multi-step
mappings work and what built-in steps are available.
Setup that works well with |mini.completion| and |mini.pairs|: >lua
local map_multistep = require('mini.keymap').map_multistep
map_multistep('i', '<Tab>', { 'pmenu_next' })
map_multistep('i', '<S-Tab>', { 'pmenu_prev' })
map_multistep('i', '<CR>', { 'pmenu_accept', 'minipairs_cr' })
map_multistep('i', '<BS>', { 'minipairs_bs' })
<
Use <Tab> / <S-Tab> to also navigate and expand |mini.snippets|: >lua
local map_multistep = require('mini.keymap').map_multistep
local tab_steps = { 'minisnippets_next','minisnippets_expand','pmenu_next' }
map_multistep('i', '<Tab>', tab_steps)
local shifttab_steps = { 'minisnippets_prev', 'pmenu_prev' }
map_multistep('i', '<S-Tab>', shifttab_steps)
<
An extra smart <Tab> and <S-Tab>: >lua
local map_multistep = require('mini.keymap').map_multistep
-- NOTE: this will never insert tab, press <C-v><Tab> for that
local tab_steps = {
'minisnippets_next', 'minisnippets_expand', 'pmenu_next',
'jump_after_tsnode', 'jump_after_close',
}
map_multistep('i', '<Tab>', tab_steps)
local shifttab_steps = {
'minisnippets_prev', 'pmenu_prev',
'jump_before_tsnode', 'jump_before_open',
}
map_multistep('i', '<S-Tab>', shifttab_steps)
<
Navigation in active |vim.snippet| session also requires mapping in |Select-mode|: >lua
local map_multistep = require('mini.keymap').map_multistep
map_multistep({ 'i', 's' }, '<Tab>', { 'vimsnippet_next', 'pmenu_next' })
map_multistep({ 'i', 's' }, '<S-Tab>', { 'vimsnippet_prev', 'pmenu_prev' })
<
# Combos ~
See |MiniKeymap.map_combo()| for a general description of what is a combo and
more caveats about its usage.
All combos require their left hand side keys to be typed relatively quickly.
To adjust the delay between keys, add `{ delay = 500 }` (use custom value) as
fourth argument.
## "Better escape" to Normal mode ~
Leave into |Normal-mode| without having to reach for <Esc> key: >lua
-- Support most common modes. This can also contain 't', but would
-- only mean to press `<Esc>` inside terminal.
local mode = { 'i', 'c', 'x', 's' }
require('mini.keymap').map_combo(mode, 'jk', '<BS><BS><Esc>')
-- To not have to worry about the order of keys, also map "kj"
require('mini.keymap').map_combo(mode, 'kj', '<BS><BS><Esc>')
-- Escape into Normal mode from Terminal mode
require('mini.keymap').map_combo('t', 'jk', '<BS><BS><C-\\><C-n>')
require('mini.keymap').map_combo('t', 'kj', '<BS><BS><C-\\><C-n>')
<
## Show bad navigation habits ~
Show notification if there is too much movement by repeating same key: >lua
local notify_many_keys = function(key)
local lhs = string.rep(key, 5)
local action = function() vim.notify('Too many ' .. key) end
require('mini.keymap').map_combo({ 'n', 'x' }, lhs, action)
end
notify_many_keys('h')
notify_many_keys('j')
notify_many_keys('k')
notify_many_keys('l')
<
## Fix previous spelling mistake ~
Fix previous spelling mistake (see |[s| and |z=|) without manually leaving
Insert mode: >lua
local action = '<BS><BS><Esc>[s1z=gi<Right>'
require('mini.keymap').map_combo('i', 'kk', action)
<
## Hide search highlighting ~
Use double <Esc><Esc> to execute |:nohlsearch|. Although this can also be done
with `nmap <Esc> <Cmd>nohl<CR>`, the combo approach also exists and can be used
to free <Esc> mapping in Normal mode for something else. >lua
local action = function() vim.cmd('nohlsearch') end
require('mini.keymap').map_combo({ 'n','i','x','c' }, '<Esc><Esc>', action)
<
## Buffer navigation ~
Replace some movements with easier to type alternatives: >lua
local map_combo = require('mini.keymap').map_combo
map_combo({ 'n', 'x' }, 'll', 'g$')
map_combo({ 'n', 'x' }, 'hh', 'g^')
map_combo({ 'n', 'x' }, 'jj', '}')
map_combo({ 'n', 'x' }, 'kk', '{')
<
------------------------------------------------------------------------------
*MiniKeymap.setup()*
`MiniKeymap.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniKeymap.config|.
Usage ~
>lua
require('mini.keymap').setup({}) -- replace {} with your config table
-- needs `keymap` field present
<
------------------------------------------------------------------------------
*MiniKeymap.config*
`MiniKeymap.config`
Defaults ~
>lua
MiniKeymap.config = {}
<
------------------------------------------------------------------------------
*MiniKeymap.map_multistep()*
`MiniKeymap.map_multistep`({mode}, {lhs}, {steps}, {opts})
Map multi-step action
Mapping of a multi-step action is an expression mapping (|:map-expression|).
Executing a multi-step action is essentially:
- Check condition for step one. If `true` - execute step one action and stop.
- Check condition for step two, and so on.
- If there is no more steps, fall back to returning mapped key.
For better user experience there are many built-in steps mostly designed
to create Insert mode "smart" mappings of <Tab>, <S-Tab>, <CR>, and <BS>.
Available built-in steps ("For key" is a suggestion, any can be used):
>
┌─────────────────────┬────────────────┬──────────────────────────┬─────────┐
│ Step name │ Condition │ Action │ For key │
├─────────────────────┴────────────────┴──────────────────────────┴─────────┤
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |ins-completion-menu| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ pmenu_next │ Pmenu visible │ Select next (as <C-n>) │ <Tab> │
│ pmenu_prev │ Pmenu visible │ Select prev (as <C-p>) │ <S-Tab> │
│ pmenu_accept │ Item selected │ Accept (as <C-y>) │ <CR> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |mini.snippets| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ minisnippets_next │ Session active │ Jump to next tabstop │ <Tab> │
│ minisnippets_prev │ Session active │ Jump to prev tabstop │ <S-Tab> │
│ minisnippets_expand │ Can expand │ Expand snippet at cursor │ <Tab> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |mini.pairs| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ minipairs_cr │ Module set up │ <CR> respecting pairs │ <CR> │
│ minipairs_bs │ Module set up │ <BS> respecting pairs │ <BS> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ Jump around in Insert mode ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ jump_after_tsnode │ TS parser │ Jump after node end │ <Tab> │
│ jump_before_tsnode │ TS parser │ Jump before node start │ <S-Tab> │
│ jump_after_close │ Insert mode │ Jump after )]}"'` │ <Tab> │
│ jump_before_open │ Insert mode │ Jump before ([{"'` │ <S-Tab> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ Work with whitespace ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ increase_indent │ Is on indent │ Increase indent │ <Tab> │
│ decrease_indent │ Is on indent │ Decrease indent │ <S-Tab> │
│ hungry_bs │ Space to left │ Delete all space to left │ <BS> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ |vim.snippet| ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ vimsnippet_next │ Session active │ Jump to next tabstop │ <Tab> │
│ vimsnippet_prev │ Session active │ Jump to prev tabstop │ <S-Tab> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'hrsh7th/nvim-cmp' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ cmp_next │ Menu visible │ Select next item │ <Tab> │
│ cmp_prev │ Menu visible │ Select prev item │ <S-Tab> │
│ cmp_accept │ Item selected │ Accept selected item │ <CR> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'Saghen/blink.cmp' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ blink_next │ Menu visible │ Select next item │ <Tab> │
│ blink_prev │ Menu visible │ Select prev item │ <S-Tab> │
│ blink_accept │ Item selected │ Accept selected item │ <CR> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'L3MON4D3/LuaSnip' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ luasnip_next │ Session active │ Jump to next tabstop │ <Tab> │
│ luasnip_prev │ Session active │ Jump to prev tabstop │ <S-Tab> │
│ luasnip_expand │ Can expand │ Expand snippet at cursor │ <Tab> │
├┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈ 'windwp/nvim-autopairs' ┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┈┤
│ nvimautopairs_cr │ Module present │ <CR> respecting pairs │ <CR> │
│ nvimautopairs_bs │ Module present │ <BS> respecting pairs │ <BS> │
└─────────────────────┴────────────────┴──────────────────────────┴─────────┘
<
Notes:
- Executing action has limitations of |:map-expression| (like not allowed text
or buffer changes, etc.). To execute complex lua code, use |vim.schedule()|
inside action, return the code as string in |:map-cmd| format, or return
a function to be later executed. See usage examples.
- Some mapped keys (like <Tab>, <CR>) might require disabling smart presets
in plugins (like 'nvim-cmp', 'blink-cmp', 'nvim-autopairs').
Parameters ~
{mode} `(string|table)` Same as for |vim.keymap.set()|.
{lhs} `(string)` Same as for |vim.keymap.set()|.
{steps} `(table)` Array of steps. Each step can be a string with the name
of built-in step or a table with two callable methods (will be called
without arguments):
- <condition> - return `true` if the action should be executed.
- <action> - action to be executed if <condition> returns `true`.
For more flexibility, it can also return a value which can be:
- String - will be returned as expression output. Can be something like
`"<Tab>"` (treat as <Tab> key) or `"<Cmd>lua vim.notify('Hello')<CR>"`.
Should not escape keycodes (i.e. return "<Tab>" and not "\t").
To undo already done escape, use |keytrans()|.
- Function - will be executed as if `"<Cmd>lua f()<CR>"`, but does not
need to create a global function for that.
- `false` - do not stop going through steps.
{opts} `(table|nil)` Same as for |vim.keymap.set()|.
Usage ~
See |MiniKeymap-examples| for practical examples.
Some illustrative examples: >lua
_G.log = {}
local steps = {}
steps[1] = {
condition = function() table.insert(_G.log, 'C1'); return _G.cond1 end,
-- Compute and return keys. Will be emulated as pressed.
action = function() table.insert(_G.log, 'A1'); return 'hello' end,
}
steps[2] = {
condition = function() table.insert(_G.log, 'C2'); return _G.cond2 end,
-- Perform action immediately, return `false` to keep asking other steps
action = function() table.insert(_G.log, 'A2'); return false end,
}
steps[3] = {
condition = function() table.insert(_G.log, 'C3'); return _G.cond3 end,
-- Perform action later (to overcom expression mapping limitations)
action = function()
table.insert(_G.log, 'A3_1')
return function() table.insert(_G.log, 'A3_2') end
end,
}
-- Make Insert mode <Tab> mapping
require('mini.keymap').map_multistep('i', '<Tab>', steps)
-- Pressing <Tab> inserts fallback `\t`; logs C1+C2+C3
_G.cond1, _G.cond2, _G.cond3 = false, false, false
-- Pressing <Tab> inserts `hello`; logs C1+A1
_G.cond1, _G.cond2, _G.cond3 = true, false, false
-- Pressing <Tab> inserts nothing; logs C1+C2+A2+C3+A3_1+A3_2
_G.cond1, _G.cond2, _G.cond3 = false, true, true
<
------------------------------------------------------------------------------
*MiniKeymap.gen_step*
`MiniKeymap.gen_step`
Generate step for multi-step mappings
This is a table with function elements. Call to actually get a step.
------------------------------------------------------------------------------
*MiniKeymap.gen_step.search_pattern()*
`MiniKeymap.gen_step.search_pattern`({pattern}, {flags}, {opts})
Search pattern step
Use |search()| to jump to pattern match. Possibly adjust final position to
be just to the right of the match (useful in Insert mode).
Parameters ~
{pattern} `(string)` Same as for |search()|.
{flags} `(string|nil)` Same as for |search()|.
{opts} `(table|nil)` Options. Possible fields:
- <side> `(string)` - one of `"before"` (default) or `"after"`.
- <stopline> `(number|function)` - forwarded to |search()| (as number or
as function's output after calling it before every search).
- <timeout> `(number)` - forwarded to |search()|.
- <skip> `(string|function)` - forwarded to |search()|.
Return ~
`(table)` Step which searches pattern.
Usage ~
Built-in |MiniKeymap.map_multistep()| steps "jump_after_close" and
"jump_before_open" use this, but only in Insert mode.
Steps that jump before/after all consecutive brackets in several modes: >lua
local keymap = require('mini.keymap')
local tab_step_insert = keymap.gen_step.search_pattern(
-- Need to use 'c' flag and 'after' side for robust "chaining"
[=[[)\]}]\+]=], 'ceW', { side = 'after' }
)
keymap.map_multistep('i', '<Tab>', { tab_step_insert })
local tab_step = keymap.gen_step.search_pattern([=[[)\]}]\+]=], 'eW')
keymap.map_multistep({ 'n', 'x' }, '<Tab>', { tab_step })
local stab_step = keymap.gen_step.search_pattern([=[[(\[{]\+]=], 'bW')
keymap.map_multistep({ 'i', 'n', 'x' }, '<S-Tab>', { stab_step })
<
------------------------------------------------------------------------------
*MiniKeymap.map_combo()*
`MiniKeymap.map_combo`({mode}, {lhs}, {action}, {opts})
Map combo post action
Create a combo: sequence of keys where each acts immediately plus execute
an extra action if all are typed within configurable delay between each other.
Example for Insert mode "better escape" `jk` combo with `<BS><BS><Esc>` action:
- Press `j`. It is visible immediately without any side effects.
- Quickly (no more than default 200 ms after) press `k`. This triggers the
action which is equivalent to typing <BS><BS> (delete already present `jk`)
and <Esc> to exit into Normal mode.
Notes:
- IMPORTANT! Combo is not a regular mapping but a separate key tracking
with |vim.on_key()|. This is important as combos will not be visible and
can not be managed as regular mappings. Instead each combo is associated
with a dedicated |namespace| (named for human readability). However, it is not
really expected to manage them on the fly after they are created.
- String action is executed with |nvim_input()|, i.e. emulated keys will
respect custom mappings.
- Different combos are tracked and act independent of each other. For example,
if there are combos for `jjk` and `jk` keys, fast typing `jjk` will execute both.
- Neovim>=0.11 is recommended due to |vim.on_key()| improvement to allow
watching for keys as they are typed and not as if coming from mappings.
For example, this matters when creating a `jk` combo for Visual mode while
also having `xnoremap j gj` style of remaps. On Neovim<0.11 the fix is to
use `gjgk` as combo's left hand side.
- Each combo adds very small but non-zero overhead on each keystroke.
Usually about 1-3 microseconds (i.e. 0.001-0.003 ms), which should be
fast enough for most setups. For a "normal, real world" coding session
with a total of ~20000 keystrokes it results in extra ~40ms of overhead
for a single created combo. Create many combos with caution.
Parameters ~
{mode} `(string|table)` String or array of string mode id (like "n", "i", etc.).
Array of several modes is more performant than several single mode combos.
{lhs} `(string|table)` String with tracked key sequence or an array of
tracked keys (one element - one key).
{action} `(string|function)` Action to perform after key sequence is detected.
If string, treated as keys and emulated with |nvim_input()|.
If function, executed in |vim.schedule()|. Can return string keys which will
be emulated.
{opts} `(table|nil)` Options. Possible fields:
- <delay> `(number)` - delay in milliseconds within which keys should be
pressed to detect a key sequence. Default: 200.
Usage ~
See |MiniKeymap-examples| for practical examples.
Some illustrative examples: >lua
local map_combo = require('mini.keymap').map_combo
-- In Insert mode pressing `x` followed by `x` within 1 second logs 'A'
-- and emulates extra pressing of `yy`
_G.log = {}
local action = function() table.insert(_G.log, 'A'); return 'yy' end
map_combo('i', 'xx', action, { delay = 1000 })
<
vim:tw=78:ts=8:noet:ft=help:norl: