Repository navigation
Expand file tree
/
Copy pathmini-cmdline.txt
More file actions
10000
391 lines (310 loc) · 15.8 KB
/
Copy pathmini-cmdline.txt
File metadata and controls
391 lines (310 loc) · 15.8 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
*mini.cmdline* Command line tweaks
MIT License Copyright (c) 2025 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniCmdline*
Features:
- Autocomplete with customizable delay. Enhances |cmdline-completion| and
manual |'wildchar'| pressing experience.
Requires Neovim>=0.11, though Neovim>=0.12 is recommended.
- Autocorrect words as-you-type. Only words that must come from a fixed set of
candidates (like commands and options) are autocorrected by default.
- Autopeek command range as-you-type. Shows a floating window with range lines
along with customizable context lines.
What it doesn't do:
- Customization of command line UI. Use |vim._extui| (on Neovim>=0.12).
- Customization of autocompletion candidates. They are computed
via |cmdline-completion|.
# Setup ~
This module needs a setup with `require('mini.cmdline').setup({})` (replace `{}`
with your `config` table). It will create global Lua table `MiniCmdline` which
you can use for scripting or manually (with `:lua MiniCmdline.*`).
See |MiniCmdline.config| for `config` structure and default values.
You can override runtime config settings locally to buffer inside
`vim.b.minicmdline_config` which should have same structure as
`MiniCmdline.config`. See |mini.nvim-buffer-local-config| for more details.
# Suggested option values ~
Some options are set automatically (if not set before |MiniCmdline.setup()|):
- |'wildmode'| is set to "noselect,full" for less intrusive autocompletion.
Requires Neovim>=0.11 and enabled `config.autocomplete`.
- |'wildoptions'| is set to "pum,fuzzy" to enable fuzzy matching.
# Comparisons ~
- [folke/noice.nvim](https://github.com/folke/noice.nvim):
- Mostly focuses on visual aspects of the Command line.
This modules is aimed to improve its workflow without changing UI.
- [nacro90/numb.nvim](https://github.com/nacro90/numb.nvim):
- Designed to preview only a single line range defined by numbers.
This module handles any form of |:range| and |:range-offset| for both
one and two line ranges.
- Shows target line directly in the normal window.
This module uses a dedicated floating window.
- Built-in |cmdline-autocompletion| (on Neovim>=0.12):
- This module on Neovim>=0.12 uses that as its base for autocompletion.
Ont top of that it also provides customizable delay and predicate.
- Built-in |vim._extui| (on Neovim>=0.12):
- Mostly focuses on visual aspects of the Command line.
This modules is aimed to improve its workflow without changing UI.
# Highlight groups ~
- `MiniCmdlinePeekBorder` - border of autopeek window.
- `MiniCmdlinePeekLineNr` - line numbers in autopeek window.
- `MiniCmdlinePeekNormal` - basic foreground/background of autopeek window.
- `MiniCmdlinePeekSep` - statuscolumn separator in autopeek window.
- `MiniCmdlinePeekSign` - signs in autopeek window.
- `MiniCmdlinePeekTitle` - title of autopeek window.
# Disabling ~
To disable acting in mappings, set `vim.g.minicmdline_disable` (globally) or
`vim.b.minicmdline_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.
------------------------------------------------------------------------------
*MiniCmdline.setup()*
`MiniCmdline.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniCmdline.config|.
Usage ~
>lua
require('mini.cmdline').setup() -- use default config
-- OR
require('mini.cmdline').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniCmdline.config*
`MiniCmdline.config`
Defaults ~
>lua
MiniCmdline.config = {
-- Autocompletion: show `:h 'wildmenu'` as you type
autocomplete = {
enable = true,
-- Delay (in ms) after which to trigger completion
-- Neovim>=0.12 is recommended for positive values
delay = 0,
-- Custom rule of when to trigger completion
predicate = nil,
-- Whether to map arrow keys for more consistent wildmenu behavior
map_arrows = true,
},
-- Autocorrection: adjust non-existing words (commands, options, etc.)
autocorrect = {
enable = true,
-- Custom autocorrection rule
func = nil,
},
-- Autopeek: show command's target range in a floating window
autopeek = {
enable = true,
-- Number of lines to show above and below range lines
n_context = 1,
-- Custom rule of when to show peek window
predicate = nil,
-- Window options
window = {
-- Floating window config
config = {},
-- Function to render statuscolumn
statuscolumn = nil,
},
},
}
<
# General ~
- Each feature is configured via separate table.
- Use `enable = false` to disable a feature.
Autocomplete ~
`config.autocomplete` is used to configure autocompletion: automatic show
of |'wildmenu'|.
`autocomplete.delay` defines a (debounce style) delay after which |'wildchar'|
is triggered to show wildmenu.
Default: 0. Note: Neovim>=0.12 is recommended for positive values if you
want to reduce flicker (thanks to |wildtrigger()|).
`autocomplete.predicate` defines a condition of whether to trigger completion
at the current command line state. Takes a table with input data and should
return `true` to show completion and `false` otherwise. Will be called before
the possible delay at current command line state.
Default: |MiniCmdline.default_autocomplete_predicate()|.
Input data fields:
- <line> `(string)` - current command line text. See |getcmdline()|.
- <pos> `(number)` - current command line column. See |getcmdpos()|.
- <line_prev> `(string)` - command line text before the latest change.
- <pos_prev> `(number)` - command line column before the latest cursor move.
Example of blocking completion based on completion type (as some may be slow): >lua
local block_compltype = { shellcmd = true }
require('mini.cmdline').setup({
autocomplete = {
predicate = function()
return not block_compltype[vim.fn.getcmdcompltype()]
end,
},
})
<
Similar approach can be used to enable completion only for normal Ex commands.
Use `return vim.fn.getcmdtype() == ':'` as a predicate output.
Autocorrect ~
`config.autocorrect` is used to configure autocorrection: automatic adjustment
of bad words as you type them. This works only when appending single character
at the end of the command line. Editing already typed words does not trigger
autocorrect (allows correcting the autocorrection).
When to autocorrect is computed automatically based on |getcmdcomplpat()| after
every key press: if it doesn't add the character to completion pattern, then
the pattern before the key press is attempted to be corrected.
There is also an autocorrection attempt for the last word just before
executing the command.
Notes:
- This is intended mostly for fixing typos and not as a shortcut for fuzzy
matching. Performing the latter automatically is too intrusive. Explicitly
use fuzzy completion for that (set up by default).
- Default autocorrection is done only for words that must come from a fixed
set of candidates (like commands and options) by choosing the one with
the lowest string distance.
See |MiniCmdline.default_autocorrect_func()| for details.
- Word that matches some Command-line |abbreviation| is not autocorrected.
- If current command expects only a single argument (like |:colorscheme|), then
autocorrection will happen only just before executing the command.
`autocorrect.func` is a function that can be used to customize autocorrection.
Takes a table with input data and should return a string with the correct word
or `nil` for no autocorrection. Default: |MiniCmdline.default_autocorrect_func()|.
Input data fields:
- <word> `(string)` - word to be autocorrected. Never empty string.
- <type> `(string)` - word type. Output of |getcmdcompltype()|.
Autopeek ~
`config.autopeek` is used to configure automatic peeking: show command's target
range in a floating window. The window will appear above command line and show
current buffer with the focus on left and right (if present and differs from
left) range lines.
`autopeek.n_context` defines how many lines to show above and below the target.
The range itself is visualized by default with the statuscolumn signs.
Default: 1.
`autopeek.predicate` defines a condition of whether to show peek window at
the current command line state. Takes a table with input data and should
return `true` to peek and `false` otherwise.
Will be called only if it is possible to parse range from the current command
line text and it is for buffer lines (no command or |:command-addr| is `lines`)
Default: |MiniCmdline.default_autopeek_predicate()|.
Input data fields:
- <left> `(number)` - left range edge. Not necessarily smallest.
- <right> `(number)` - right range edge. Same as `left` for a single line range.
- <cmd> `(string)` - full command name. Can be empty string if no valid
command is (yet) entered.
`autopeek.window` defines behavior of a peek window.
`autopeek.window.config` is a table defining floating window characteristics
or a callable returning such table.
It should have the same structure as in |nvim_open_win()|.
`autopeek.window.statuscolumn` is a special function that can be used to
customize |'statuscolumn'| value for the peek window. Takes a table with input
data and should return a string to display for line |v:lnum|.
Default: |MiniCmdline.default_autopeek_statuscolumn()|.
Input data fields are the same as for `autopeek.predicate`.
Example of showing `<` and `>` signs on range lines: >lua
function(data)
local n, l, r = vim.v.lnum, data.left, data.right
local s = n == l and (n == r and '* ' or '< ') or n == r and '> ' or ''
-- Needs explicit highlighting via `:h 'statusline'` syntax
return '%#MiniCmdlinePeekSign#' .. s
end
<
Notes:
- Peek window directly shows current buffer, which means that all its
extmarks, virtual text, virtual lines, etc. are also shown.
- Non-zero context might work unreliably if there are virtual lines.
- Peeking intentionally hides Visual selection if Command-line mode is entered
directly from it. Peeking `'<,'>` range already visualizes the selection.
To disable autopeek for this case, add the following code BEFORE
executing `require('mini.cmdline').setup()`: >lua
local disable = vim.schedule_wrap(function()
local is_from_visual = vim.startswith(vim.fn.getcmdline(), "'<,'>")
MiniCmdline.config.autopeek.enable = not is_from_visual
end)
local reenable = function() MiniCmdline.config.autopeek.enable = true end
vim.api.nvim_create_autocmd('CmdlineEnter', { callback = disable })
vim.api.nvim_create_autocmd('CmdlineLeave', { callback = reenable })
<
------------------------------------------------------------------------------
*MiniCmdline.default_autocomplete_predicate()*
`MiniCmdline.default_autocomplete_predicate`({data}, {opts})
Default autocompletion predicate
Parameters ~
{data} `(table)` Input autocompletion data. As described in |MiniCmdline.config|.
{opts} `(table|nil)` Options. Reserved for future use.
Return ~
`(boolean)` If command line does not (yet) contain a letter - `false`,
otherwise - `true`. This makes autopeek easier to use for a numerical range.
------------------------------------------------------------------------------
*MiniCmdline.default_autocorrect_func()*
`MiniCmdline.default_autocorrect_func`({data}, {opts})
Default autocorrection function
- Return input word if `opts.strict_type=true` and input `type` is not proper.
- Get candidates via `opts.get_candidates()`.
Default: mostly via |getcompletion()| with empty pattern and input `type`.
Exceptions are `help` and `option` types: both list all available candidates
in their own ways.
- Choose the candidate with the lowest Damerau–Levenshtein distance
(smallest number of deletion/insertion/substitution/transposition needed
to transform one word into another; slightly prefers transposition).
Notes:
- Type `'command'` also chooses from all valid candidate abbreviations.
- Comparison is done both respecting and ignoring case.
Parameters ~
{data} `(table)` Input autocorrection data. As described in |MiniCmdline.config|.
{opts} `(table|nil)` Options. Possible fields:
- <strict_type> `(boolean)` - whether to restrict output only for types which
must have words from a fixed set of candidates (like command or option
names). Note: does not include `help` type since |:help| already has
"sophisticated algorithm" to handle typos. Default: `true`.
- <get_candidates> `(function)` - source of candidates. Will be called
with `data` as argument and should return array of string candidates to
choose from.
Default: for most types - |getcompletion()| with empty pattern and
input `type`; for `help` and `option` type - all available help tags and
option names (long and short) respectively.
Return ~
`(string)` Autocorrected word.
------------------------------------------------------------------------------
*MiniCmdline.default_autopeek_predicate()*
`MiniCmdline.default_autopeek_predicate`({data}, {opts})
Default autopeek predicate
Parameters ~
{data} `(table)` Input autopeek data. As described in |MiniCmdline.config|.
{opts} `(table|nil)` Options. Reserved for future use.
Return ~
`(boolean)` If command defines |:command-preview| - `false`, otherwise - `true`.
This makes autopeek easier to use for commands like |:substitute|,
especially if |'inccommand'| is set to `split`.
------------------------------------------------------------------------------
*MiniCmdline.default_autopeek_statuscolumn()*
`MiniCmdline.default_autopeek_statuscolumn`({data}, {opts})
Default autopeek statuscolumn
- Show signs next to lines depending on their relation to peeked range.
Highlighted with `MiniCmdlinePeekSign` group.
- Show line numbers for left and right parts of the range.
Highlighted with `MiniCmdlinePeekLineNr` group.
- Separate statuscolumn and buffer text with dedicated separator character.
Highlighted with `MiniCmdlinePeekSep` group.
Notes:
- Intended to only be used as a part of |'statuscolumn'| function, as it
uses |v:lnum| and |v:virtnum| to compute the output.
Example of adjusting a `mid` sign: >lua
local peek_stc_opts = { signs = { mid = '+' } }
local peek_stc = function(data)
return MiniCmdline.default_autopeek_statuscolumn(data, peek_stc_opts)
end
require('mini.cmdline').setup({
autopeek = { window = { statuscolumn = peek_stc } },
})
<
Parameters ~
{data} `(table)` Input peek data. As described in |MiniCmdline.config|.
{opts} `(table|nil)` Options. Possible fields:
- <signs> `(table)` - signs to show. Possible fields:
- <same> `(string)` - on range if `left=right`. Default: `'🭬'`.
- <left> `(string)` - on `left` line. Default: `'┌'`.
- <mid> `(string)` - inside range. Default: `'┊'`.
- <right> `(string)` - on `right` line. Default: `'└'`.
- <out> `(string)` - outside of range. Default: `''` (no sign).
- <virt> `(string)` - virtual line. Default: `'•'`.
- <wrap> `(string)` - wrapped line. Default: `'↳'`.
- <sep> `(string)` - string to put at the end to separate statuscolumn and
buffer text. Default: `'│'`
Note: Any sign and separator should have every `%` escaped as `%%` (due to its
special meaning in |'statuscolumn'|).
vim:tw=78:ts=8:noet:ft=help:norl: