mini.nvim/doc/mini-keymap.txt at main · Groctel/mini.nvim

Repository navigation

History

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

*mini.keymap* Special key mappings

*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' completion.

- Navigate and accept in 'Saghen/blink.cmp' completion.

- Navigate and expand 'L3MON4D3/LuaSnip' snippets.

- Execute <CR> and <BS> respecting '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':

- 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':

- 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`

Module config

Default values:

>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:

FilesExpand file tree

mini-keymap.txt

Latest commit

History

mini-keymap.txt

File metadata and controls