8000 mini.nvim/doc/mini-keymap.txt at main · max-farver/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content

mini-keymap.txt

Latest commit

 

History

History
449 lines (371 loc) · 22 KB

mini-keymap.txt

File metadata and controls

449 lines (371 loc) · 22 KB
Raw
------------------------------------------------------------------------------
*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:
0