Repository navigation
Expand file tree
/
Copy pathmini-input.txt
More file actions
932 lines (755 loc) · 38.3 KB
/
Copy pathmini-input.txt
File metadata and controls
932 lines (755 loc) · 38.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
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
*mini.input* Get user input
MIT License Copyright (c) 2026 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniInput*
Features:
- Get user input with fully customizable key and view handling.
- Built-in configurable views as floating window, statusline/tabline/winbar,
virtual line/text.
- Implementation is non-blocking but waits to return the input. It also works
in any mode without requiring mode change. See |MiniInput-lifecycle|.
- |vim.ui.input()| implementation. To adjust, use |MiniInput.ui_input()| or
save-restore `vim.ui.input` manually after calling |MiniInput.setup()|.
Sources with more details:
- |MiniInput.get()|
- |MiniInput.default_key()|
- |MiniInput-state|
- |MiniInput-examples|
- |MiniInput-in-other-plugins| (for plugin authors)
# Setup ~
This module needs a setup with `require('mini.input').setup({})` (replace `{}`
with your `config` table). It will create global Lua table `MiniInput` which
you can use for scripting or manually (with `:lua MiniInput.*`).
See |MiniInput.config| for `config` structure and default values.
You can override runtime config settings locally to buffer inside
`vim.b.miniinput_config` which should have same structure as
`MiniInput.config`. See |mini.nvim-buffer-local-config| for more details.
# Comparisons ~
- [folke/snacks.nvim#input](https://github.com/folke/snacks.nvim):
- Both provide |vim.ui.input()| implementation.
- Has asynchronous implementation (i.e. does not wait for user to finish
input), while this module has synchronous non-blocking implementation.
- Uses floating window and forced Insert mode. This module allows more
view customizations and can be used in any mode without interruptions.
- |input()|:
- Both are synchronous.
- Both allow custom highlight and completion.
- This module also allows supplying input scope and visibility,
customizing keys and view.
# Highlight groups ~
*MiniInput-hl-groups*
- `MiniInputAdded` - added text during completion navigation.
- `MiniInputBorder` - border of a |MiniInput.gen_view.floatwin()| handler.
- `MiniInputCaret` - caret symbol shown in a prompt area.
- `MiniInputHide` - input is hidden, usually used instead of `MiniInputPrompt`.
- `MiniInputHint` - hints shown during completion navigation.
- `MiniInputNormal` - basic foreground/background.
- `MiniInputPrompt` - input prompt (intention of the input).
- `MiniInputSpecial` - special keys (like literal `\t`, `\n`, etc.) in input.
# Using in other plugins ~
*MiniInput-in-other-plugins*
- Prefer using |vim.ui.input()| for more user coverage. Use |MiniInput.get()|
only when getting input synchronously is absolutely necessary.
- Perform a `_G.MiniInput ~= nil` check before using any feature. This ensures
that user explicitly set up the module.
------------------------------------------------------------------------------
*MiniInput-state*
Information about the state of the input. It is passed as a handler argument.
Use |MiniInput.get_state()| to get information about the current state (if any).
A table with the following fields:
- <caret> `(number)` - character (not byte) index at which to modify input.
Should be from 1 (prepend input) to "input width plus 1" (append input).
- <complete> `(table|nil)` - information about active completion navigation.
If present, it means that completion navigation is in action.
Its fields describe the state of navigation:
- <base> `(string)` - reference text to the left of caret at the start
of completion. Used to compute candidates. Can be empty string.
- <id> `(number)` - identifier of current completion item. Can be zero to
mean that the base is shown. If not zero, must mean that a `items[id]`
candidate is now shown to the left of caret as the part of the input.
- <items> `(table)` - string array of completion candidates. May be empty.
Are intended to fully replace <base>, so should contain it in any sense.
- <method> `(string)` - completion method. Like `"default"`, `"history"`, etc.
Can be `""` (empty string) to mean "default method of complete handler".
- <data> `(table)` - any information to be reused within the same input session.
Note: handlers should not change fields that they don't "own".
- <errmsg> `(errmsg)` - first error message caught during input process.
- <highlight> `(table|nil)` - information about current input highlighting.
If absent, the whole input is highlighted using `MiniInputNormal` group.
Should be an array of highlight ranges. They might be not ordered, overlap,
go outside of input width. It is up to the view handler to decide how to
interpret them. See |MiniInput.state_to_chunks()| for a helper.
Fields of a single highlight range:
- <from> `(number)` - character index (one-indexed) of range start.
- <to> `(number)` - character index (one-indexed) of range end (inclusive).
Should not be smaller than <from>. Can be |math.huge|.
- <hl> `(string)` - highlight group to use for highlighting.
- <input> `(string)` - current user input. Returned by |MiniInput.get()|.
- <opts> `(table)` - input options, same as in |MiniInput.get()|.
- <prompt> `(string)` - intention of the input. May be empty.
- <status> `(string)` - one of `"start"`, `"progress"`, `"accept"`, `"cancel"`.
------------------------------------------------------------------------------
*MiniInput-examples*
# General ~
## Initial input ~
Use `opts.init_keys` to imitate the initial state of the input: >lua
MiniInput.get({ init_keys = { 'Default' } })
<
## Custom mappings ~
Override `handlers.key` in |MiniInput.config|: >lua
local key_handler = function(state, key)
-- <C-a> - move caret to start of line
if key == '\1' then
state.caret = 1
-- <S-BS> - clear all input
elseif key == vim.keycode('<S-BS>') then
state.input, state.caret = '', 1
else
-- IMPORTANT: Fall back to processing as usual
return MiniInput.default_key(state, key)
end
end
require('mini.input').setup({ handlers = { key = key_handler } })
<
## Basic command line ~
An alternative |Command-line| with highlighting and completion: >lua
-- Construct reusable `MiniInput.get()` options
local cmdline_opts = { prompt = 'Command', scope = 'editor' }
-- - Highlight using bundled Vim tree-sitter parser and default handler
local highlight_vim = MiniInput.gen_highlight.treesitter('vim')
local highlight_cmdline = function(state)
state = highlight_vim(state) or state
return MiniInput.default_highlight(state) or state
end
cmdline_opts.handlers = { highlight = highlight_cmdline }
-- - Complete as if it is Command line input
cmdline_opts.completion = 'cmdline'
-- Create a mapping for `:`
local input_cmdline = function()
local cmd = MiniInput.get(cmdline_opts)
if cmd ~= nil then vim.cmd(cmd) end
end
vim.keymap.set('n', ':', input_cmdline)
<
# Handlers ~
## Key ~
Perform custom actions based on arbitrary conditions: >lua
local key_handler = function(state, key)
-- Adjust prompt
state.opts.prompt = state.opts.prompt:gsub('[?:]%s*$', '')
-- Adjust scope
if state.opts.prompt == 'Editor action' then
state.opts.scope = 'editor'
end
-- Hide from view and history
if state.opts.prompt:find('[Pp]assword') ~= nil then
state.opts.hide = true
end
-- IMPORTANT: Process as usual
state = MiniInput.default_key(state, key) or state
-- Auto fill and accept
if state.input == 'AF' then
state.input, state.status = 'Autofilled input', 'accept'
end
end
require('mini.input').setup({ handlers = { key = key_handler } })
<
## View ~
Show no view: >lua
require('mini.input').setup({ handlers = { view = function() end } })
<
Compute initial style depending on scope: >lua
local input = require('mini.input')
local view_virtline = input.gen_view.virtual({ style = 'above' })
local view_tabline = input.gen_view.uiline({ style = 'tabline' })
local view_winbar = input.gen_view.uiline({ style = 'winbar' })
local view_handler = function(state)
-- NOTE: does not support interactive scope change
local scope, view = state.opts.scope, view_tabline
if scope == 'buffer' or scope == 'window' then view = view_winbar end
if scope == 'cursor' or scope == 'line' then view = view_virtline end
return view(state)
end
input.setup({ handlers = { view = view_handler } })
<
Change symbols for caret and hidden input: see |MiniInput.gen_view|.
------------------------------------------------------------------------------
*MiniInput.setup()*
`MiniInput.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniInput.config|.
Usage ~
>lua
require('mini.input').setup() -- use default config
-- OR
require('mini.input').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniInput.config*
`MiniInput.config`
Defaults ~
>lua
MiniInput.config = {
-- Functions that control input lifecycle
handlers = {
-- Compute completion candidates
complete = nil,
-- Compute highlighting of current input
highlight = nil,
-- Handle input start, every key press, and input end
key = nil,
-- Show current input state
view = nil,
},
-- Default input scope: cursor/line/buffer/window/tabpage/editor/project
scope = 'editor',
}
<
# Handlers ~
*MiniInput.config.handlers*
`config.handlers` defines functions that are applied during |MiniInput-lifecycle|.
Every handler takes |MiniInput-state| as the first argument and is expected to
either modify it in place or return a new state table.
Use |MiniInput.apply_handler()| to apply a handler for a given |MiniInput-state|.
They can be set up as part of the config (will be used as default) or passed
directly as a part of |MiniInput.get()| call.
## Complete ~
`handlers.complete` is a handler intended to compute completion suggestions.
Takes |MiniInput-state| and `method` as arguments and is expected to modify
<complete> field. Default: |MiniInput.default_complete()|.
Only `complete.base` and `complete.items` are expected to be set by a complete
handler. Setting and modifying other fields (`complete.id` and `complete.method`)
is done in other handlers and as part of |MiniInput.apply_handler()|. Actually
showing completion information is up to the view handler.
This handler is usually applied manually inside a key handler via using
`MiniInput.apply_handler(state, 'complete', method)`. Like, for example,
in |MiniInput.default_key()| after <Tab> or <Up>.
Here is an example of a simple demo complete handler: >lua
local complete_handler = function(state, method)
if method == '' or method == 'xy' then
local text = vim.fn.strcharpart(state.input, 0, state.caret - 1)
local base = text:match('%S*$')
state.complete = { base = base, items = { base .. 'x', base .. 'y' } }
return
end
return MiniInput.default_complete(state, method)
end
require('mini.input').setup({ handlers = { complete = complete_handler } })
<
## Key ~
`handlers.key` is a handler intended to process every user key press.
Takes |MiniInput-state| and `key` as arguments. Argument `key` represents a key
that needs to be processed: a string if from the user input or `nil` if input
needs to be set up, refreshed, or torn down. Default: |MiniInput.default_key()|.
A string `key` can be two kinds:
- Forwarded from |getcharstr()| verbatim as a result of interactive key press.
Meaning it will be in escaped form and not as a |key-notation|: i.e. `"\r"`
and not `"<CR>"`. It also means that all kinds of combos (`<M-...>`, `<C-S-...>`),
mouse clicks, and wheel scrolls are also forwarded to key handler.
- Any string as part of `opts.init_keys` in |MiniInput.get()|. If a string
doesn't look like it came from |getcharstr()|, it is usually a good idea
to insert this string at caret as is.
The suggested overall approach for custom key handler is "if `key` is special -
act on it, if can be used in the input - insert at caret, ignore otherwise".
It is also important to never change the current mode (as in |vim-modes|)
for |MiniInput.get()| to work as expected.
Here is an example of a basic custom key handler: >lua
local custom_actions = {
[vim.keycode('<Left>')] = function(state)
state.caret = math.max(state.caret - 1, 1)
end,
[vim.keycode('<Right>')] = function(state)
local input_width = vim.fn.strchars(state.input)
state.caret = math.min(state.caret + 1, input_width + 1)
end,
[vim.keycode('<CR>')] = function(state) state.status = 'accept' end,
[vim.keycode('<Esc>')] = function(state) state.status = 'cancel' end,
}
local key_handler = function(state, key)
-- No need for special setup or teardown
if key == nil then return end
-- If key is special - act on it
if custom_actions[key] then return custom_actions[key](state) end
-- If key is not printable - do nothing
if vim.fn.match(key, '^[[:print:]]\\+$') < 0 then return end
-- Insert at caret
local caret, input = state.caret, state.input
local before_caret = vim.fn.strcharpart(input, 0, caret - 1)
local after_caret = vim.fn.strcharpart(input, caret - 1)
state.input = before_caret .. key .. after_caret
state.caret = caret + vim.fn.strchars(key)
-- No need to return anything as `state` is modified in place
end
require('mini.input').setup({ handlers = { key = key_handler } })
<
## Highlight ~
`handlers.highlight` is a handler intended to compute and set highlight info
about the current input. Takes |MiniInput-state| as the only argument and is
expected to modify <highlight> field. Default: |MiniInput.default_highlight()|.
See |MiniInput.gen_highlight| for built-in highlight handler generators.
It is usually a good idea to append to a <highlight> if it already exists.
This makes it work more robustly when combining highlights.
Here is a basic example that highlights all letters `a`: >lua
local hl_handler = function(state)
local highlight = {}
for col in string.gmatch(state.input, '()a') do
-- NOTE: range should use character (not byte) indexes
local char_col = vim.fn.charidx(state.input, col)
local range = { from = char_col, to = char_col, hl = 'Special' }
table.insert(highlight, range)
end
state.highlight = vim.list_extend(state.highlight or {}, highlight)
-- Possibly also apply default handler afterwards
return MiniInput.default_highlight(state)
end
require('mini.input').setup({ handlers = { highlight = hl_handler } })
<
## View ~
`handlers.view` is a handler intended to show the input state on screen.
Takes |MiniInput-state| as the only argument. Default: |MiniInput.default_view()|.
See |MiniInput.gen_view| for built-in view handler generators.
Example of view that uses |nvim_echo()| to show the input: >lua
local view_handler = function(state)
-- Process start and end of the input lifecycle
local is_start = state.status == 'start'
local is_end = state.status == 'accept' or state.status == 'cancel'
if is_start or is_end then vim.cmd('mode') end
if is_end then return end
-- Compute text-hl chunks that fit and show them
local chunks = MiniInput.state_to_chunks(state, vim.v.echospace)
vim.api.nvim_echo(chunks, false, {})
end
require('mini.input').setup({ handlers = { view = view_handler } })
<
# Scope ~
`config.scope` is a string that defines an input scope. It is meant as an extra
information for handlers to tweak their behavior (`view` style, etc.). Possible
values: `"cursor"`, `"line"`, `"buffer"`, `"window"`, `"tabpage"`, `"editor"`, `"project"`.
------------------------------------------------------------------------------
*MiniInput.get()*
`MiniInput.get`({opts})
Get input from the user
# Lifecycle ~
*MiniInput-lifecycle*
This module implements custom lifecycle to interact with the user. It starts
when calling |MiniInput.get()| and ends when a value is returned.
Only one active input is allowed simultaneously.
The basic cycle unit is a step that processes a `key` (string or `nil`). It is
done by calling relevant handlers in order: key handler with `key` as a second
argument, highlight handler, view handler. |MiniInput.apply_handler()| is used
to apply each handler and the output of one is used as the input for the next.
During a step some state fields are automatically removed:
- <highlight> is removed before applying a key handler to always have the most
up to date highlighting.
- <complete> is removed if it was not changed after applying a key handler but
something else in the state besides <highlight> did change. This is meant as
an automatic stop of completion when it is not advancing.
If a step sets an ending state <status> (i.e. `"accept"` or `"cancel"`), the input
is finished by extra finishing step (see below).
The order of operations is as follows:
- Create initial |MiniInput-state| based on the input `opts`, with defaults
inferred from |MiniInput.config|, and `vim.b.miniinput_config`.
- Set <status> to `"start"`.
- Advance one step with `key=nil`. This is meant as a "setup" step for handlers.
- Set <status> to `"progress"`.
- Process `opts.init_keys` one item per step with `key` set to the string item.
- Wait for user to press a key (via |getcharstr()|). The key string (in escaped
form and not as a |key-notation|; i.e. `"\r"` and not `"<CR>"`) is then used
to advance a step. Note: <C-c> is hard coded to cancel the input.
- Repeat previous step until the ending <status> (`"accept"` or `"cancel"`).
- Finish the input:
- Perform a "teardown" step with `key=nil`.
- If <errmsg> is set, throw an |error()|.
- If input is accepted (even if empty) and not hidden, add <input> to
the history. Get the whole history with |MiniInput.get_history()|.
- Return <input> if <status> is `"accept"`, `nil` otherwise.
Parameters ~
{opts} `(table|nil)` Options. Possible fields:
- <completion> `(string)` - completion method. Default: `''` to use default
completion method of the `complete` handler.
- <handlers> `(table)` - same as in |MiniInput.config.handlers|, used only for
the duration of the current input.
- <hide> `(boolean)` - whether input should be hidden. Default: `false`.
Note: this does not guarantee a total security of the input, only that
the typed characters are expected to not be shown on screen and not added
to the history. If set:
- The `view` handler is expected to not directly show current input.
Like replace characters with pre-defined string or fully not show.
- The `complete` and `highlight` handlers are not called.
- Accepted input will not be added to the history.
- <init_keys> `(table)` - array of string keys that are emulated before asking
for the user input. Using values that can be an output of |getcharstr()|
should be preferred, but a key handler should work with any string.
Default: `{}`.
- <prompt> `(string)` - intention of the input, same as in |input()|.
Default: `"Input"`.
- <scope> `(string)` - same as in |MiniInput.config|. Default: the value from
`MiniInput.config` with some hard coded exceptions (on Neovim<0.12.3):
- |vim.lsp.buf.rename()| will use `"cursor"` if no `new_name` is supplied.
Return ~
`(string|nil)` User input (from the <input> state field) if accepted, even if
empty. `nil` if canceled or there was an active input.
Usage ~
>lua
local input = MiniInput.get({
-- Intention of the input
prompt = 'New value',
-- The input is for something at cursor
scope = 'cursor',
-- Emulate pressing `a`, `<BS>`, and `b`
init_keys = { 'a', vim.keycode('<BS>'), 'b' },
})
<
------------------------------------------------------------------------------
*MiniInput.ui_input()*
`MiniInput.ui_input`({opts}, {on_confirm})
A |vim.ui.input()| implementation
Function which can be used to directly override |vim.ui.input()| to use this
module functionality. Set automatically in |MiniInput.setup()|.
Usage ~
To preserve original `vim.ui.input()`: >lua
local ui_input_orig = vim.ui.input
require('mini.input').setup()
vim.ui.input = ui_input_orig
<
------------------------------------------------------------------------------
*MiniInput.get_state()*
`MiniInput.get_state`()
Get current input state
Return ~
`(table|nil)` Current |MiniInput-state| if input is active, `nil` otherwise. Notes:
- For hidden input (`state.opts.hide=true`), both <caret> and <input> are `nil`
to actually hide the input.
------------------------------------------------------------------------------
*MiniInput.get_history()*
`MiniInput.get_history`()
Get input history
Return ~
`(table)` Array with data about all previous non-hidden inputs (from earliest
to latest). Each element is a table with the following fields:
- <cwd> `(string)` - |current-directory| at the time of input's end.
- <input> `(string)` - input result.
- <prompt> `(string)` - `opts.prompt` supplied in |MiniInput.get()|.
- <scope> `(string)` - `opts.scope` supplied in |MiniInput.get()|.
------------------------------------------------------------------------------
*MiniInput.set_history()*
`MiniInput.set_history`({history})
Set input history
Parameters ~
{history} `(table)` Array describing all previous inputs. Same structure
as |MiniInput.get_history()| output.
------------------------------------------------------------------------------
*MiniInput.refresh()*
`MiniInput.refresh`()
Refresh active input
Performs one step of |MiniInput-lifecycle| with `key=nil`.
------------------------------------------------------------------------------
*MiniInput.gen_highlight*
`MiniInput.gen_highlight`
Highlight generators
This is a table with function elements. Call to actually get a view function.
------------------------------------------------------------------------------
*MiniInput.gen_highlight.treesitter()*
`MiniInput.gen_highlight.treesitter`({lang})
Highlight with tree-sitter
Parameters ~
{lang} `(string)` A language of tree-sitter parser to use.
Return ~
`(function)` A highlight handler. Seem |MiniInput.config.handlers|.
------------------------------------------------------------------------------
*MiniInput.gen_view*
`MiniInput.gen_view`
View generators
This is a table with function elements. Call to actually get a view function.
Each element accepts <style> option which fine tunes the input view.
With default key handler (|MiniInput.default_key()|) it can be adjusted
interactively by pressing <C-s>.
Each element also accepts <to_chunks> option. It is a function that takes
a |MiniInput-state| and `max_width` arguments and returns an array of `{ text, hl }`
chunks that fit into `max_width` display width (as in |strdisplaywidth()|).
This is a way to adjust how input is shown. Like caret/hide symbols, etc.
By default uses |MiniInput.state_to_chunks()|, which also means:
- All control characters (like literal `\t`, `\n`, etc.) will be translated
via |keytrans()|.
Example: >lua
local input = require('mini.input')
-- Adjust how state is converted to text-hl chunks
local to_chunks_opts = {
symbol_caret = '_',
symbol_hide = '*',
-- Do not include prompt and hint in `floatwin` handler
include_prompt = false,
include_hint = false,
}
local to_chunks = function(state, max_width)
return MiniInput.state_to_chunks(state, max_width, to_chunks_opts)
end
-- Supply custom `to_chunks` as an option
local view_opts = { to_chunks = to_chunks }
input.setup({ handlers = { view = input.gen_view.floatwin(view_opts) } })
<
------------------------------------------------------------------------------
*MiniInput.gen_view.floatwin()*
`MiniInput.gen_view.floatwin`({opts})
Floating window view
Show input inside a floating window. Prompt and completion hints are shown
in title and footer.
Window position and dimensions are computed based on state's <scope> and
`opts.style`:
- `scope="cursor"` is shown near the cursor. For example, `style="BL"` will
have bottom left corner at nearest top right cell relative to the cursor.
- `scope="line"` is shown near the current line. For example, `style="BL"` will
have bottom left corner at left side above the line.
- `scope="buffer"` and `scope="window"` will be shown relative to the current
window. For example, `style="BL"` will be shown in the bottom left corner.
- `scope="tabpage"`, `scope="editor"`, `scope="project"` will be shown relative to
the overall Neovim instance. For example, `style="BL"` will be shown in the
bottom left corner.
Identifiers of floating window and its buffer are stored as `floatwin_win_id`
and `floatwin_buf_id` in |MiniInput-state| <data> field. Floating window is
not focused and cursor position is not the same as caret position.
Parameters ~
{opts} `(table|nil)` Options. Possible fields:
- <adjust_config> `(function)` - function to adjust default config. Will be
called with two arguments: current |MiniInput-state| and a window config
(always with `relative="editor"` and `anchor="NW"`) computed based
on `opts.style`. Should return an adjusted window config.
Default: `function(state, config) return config end`.
- <style> `(string)` - a two character description of how to show the window.
Default: `"BL"`.
First character describes vertical position:
- `"T"` - top window border will be at scope's reference top border.
- `"M"` - middle between top and bottom window borders will be at the
middle of scope's reference top and bottom borders.
- `"B"` - bottom window border will be at scope's reference bottom border.
Second character describes horizontal position:
- `"L"` - left window border will be at scope's reference left border.
- `"M"` - middle between left and right window borders will be at the
middle of scope's reference left and right borders.
- `"R"` - right window border will be at scope's reference right border.
- <to_chunks> `(function)` - a function that takes |MiniInput-state| and
`max_width` arguments and returns an array of `{ text, hl }` chunks that fit
into `max_width` display width. See |MiniInput.state_to_chunks()|.
Usage ~
>lua
local input = require('mini.input')
-- Use border different from 'winborder'
local adjust_config = function(_, config)
config.border = 'double'
return config
end
-- Choose initial style based on the scope
local floatwin = input.gen_view.floatwin
local view_tm = floatwin({ style = 'TM', adjust_config = adjust_config })
local view_bl = floatwin({ style = 'BL', adjust_config = adjust_config })
local view_handler = function(state)
local scope, view = state.opts.scope, view_tm
if scope == 'cursor' or scope == 'line' then view = view_bl end
return view(state)
end
input.setup({ handlers = { view = view_handler } })
<
------------------------------------------------------------------------------
*MiniInput.gen_view.uiline()*
`MiniInput.gen_view.uiline`({opts})
UI line (statusline, tabline, winbar) view
Parameters ~
{opts} `(table|nil)` Options. Possible fields:
- <style> `(string)` - which UI line to use. One of `"statusline"`,
`"tabline"`, `"winbar"`. Default: `"statusline"`.
- <to_chunks> `(function)` - a function that takes |MiniInput-state| and
`max_width` arguments and returns an array of `{ text, hl }` chunks that fit
into `max_width` display width. See |MiniInput.state_to_chunks()|.
Usage ~
>lua
local input = require('mini.input')
-- Choose initial style based on the scope
local view_tabline = input.gen_view.uiline({ style = 'tabline' })
local view_winbar = input.gen_view.uiline({ style = 'winbar' })
local view_handler = function(state)
local scope, view = state.opts.scope, view_winbar
if scope == 'tabpage' or scope == 'editor' or scope == 'project' then
view = view_tabline
end
return view(state)
end
input.setup({ handlers = { view = view_handler } })
<
------------------------------------------------------------------------------
*MiniInput.gen_view.virtual()*
`MiniInput.gen_view.virtual`({opts})
Virtual (line, text) view
Parameters ~
{opts} `(table|nil)` O
1061A
ptions. Possible fields:
- <style> `(string)` - how to display virtual text. One of `"above"`, `"below"`,
`"inline"`. Default: `"above"`.
- <to_chunks> `(function)` - a function that takes |MiniInput-state| and
`max_width` arguments and returns an array of `{ text, hl }` chunks that fit
into `max_width` display width. See |MiniInput.state_to_chunks()|.
Usage ~
>lua
-- Choose different initial style
local input = require('mini.input')
local view_handler = input.gen_view.virtual({ style = 'inline' })
input.setup({ handlers = { view = view_handler } })
<
------------------------------------------------------------------------------
*MiniInput.default_key()*
`MiniInput.default_key`({state}, {key}, {opts})
Default key handler
Emulates most of |Command-line-mode| editing (|cmdline-editing|):
- Accept: <CR>. To insert literal newline, type `<C-j>`.
- Cancel: <Esc> or <C-c>.
- Move caret:
- <Left>, <Right> - one character to left / right.
- <M-h>, <M-l> - one character to left / right.
- <S-Left>, <S-Right> - one word to left / right.
- <C-b>, <C-e> (if no completion) - to start / end of input.
- <Home>, <End> - to start / end of input.
- Delete:
- <BS> / <C-h> - to caret's left. If `opts.autopair` is enabled, also delete
a character to caret's right if it formed a respected character pair.
See "Autopair".
- <Del> - at caret.
- <C-u> - from start to caret. As |c_CTRL-U|.
- <C-w> - contiguous keyword or non-keyword to caret's left. As |c_CTRL-W|.
- Insert at caret:
- <C-k> - digraph based on the next two pressed keys. As |c_CTRL-K|.
- <C-r> - content of a register. As |c_CTRL-R| including support for
special <C-a>, <C-f>, <C-l>, <C-w> keys for a register.
- <C-v>, <C-q> - next key literally. As |c_CTRL-V| and |i_CTRL-V_digit|
(all digits must be typed in full or stopped with <C-c>).
- Pasting from system |clipboard| is supported for "non-streaming" paste (as
described in |vim.paste()|).
- Autopair (if `opts.autopair` is set) is similar to |mini.pairs|:
- Opening characters `(`, `[`, `{` always insert a `()`, `[]`, `{}` pair and places
caret inside of it.
- Closing characters `)`, `]`, `}` move caret to the right if there is the same
character to the right.
- Closeopen characters single+double quotes and backtick perform "close"
action if possible and "open" action if not.
- In all cases press <C-v> before special character to insert it verbatim.
- Completion:
- <Tab>, <S-Tab> - start with `state.opts.completion` method if not active
and advance through active completion (i.e. replace currently displayed
at caret item with the next one).
Note: type `<C-v><Tab>` to insert literal `\t`.
- <C-n>, <C-p>, <Up>, <Down> - start with `"history"` method if not active
and advance through active completion.
- <C-e> - cancel and return to initial input and caret.
- <C-y> - accept current candidate. Note: it will also be accepted after
any key that doesn't advance completion.
- Miscellaneous:
- <C-o> - change scope of the input. Cycles through all available ones.
- <C-s> - change view style. Works only with |MiniInput.gen_view| view
handlers. Cycles through all available ones.
- <C-x> - toggle hide/unhide of the input.
- Special keys (combo, mouse, but not whitespace) not listed above - ignored.
Anything else (even more than a single character) - inserted at caret.
Parameters ~
{state} `(table)` Current |MiniInput-state|.
{key} `(string|nil)` A key to process. Should be escaped (`"\r"`, not `"<CR>"`).
See |vim.keycode()|.
{opts} `(table|nil)` Options. Possible fields:
- <autopair> `(boolean)` - whether perform add autopair. Default: `false`.
------------------------------------------------------------------------------
*MiniInput.default_highlight()*
`MiniInput.default_highlight`({state})
Default highlight handler
During active completion highlights added (computed via |matchfuzzy()|)
characters with `MiniInputAdded` group.
Parameters ~
{state} `(table)` Current |MiniInput-state|.
------------------------------------------------------------------------------
*MiniInput.default_view()*
`MiniInput.default_view`({state})
Default view handler
Same as |MiniInput.gen_view.floatwin()| with default options.
Parameters ~
{state} `(table)` Current |MiniInput-state|.
------------------------------------------------------------------------------
*MiniInput.default_complete()*
`MiniInput.default_complete`({state}, {method}, {opts})
Default complete handler
Supported methods:
- `""` (default) - complete with buffer keywords (|'iskeyword'|) that match
a keyword at caret's left.
- `"history"` - complete with |MiniInput.get_history()| inputs that have current
input to caret's left as a prefix. If `opts.precise_history`, only use history
entries that have all info fields same as the current state. Orders from
earliest to latest. To initiate with the latest history match, press
<Up> or <C-p> with default key handler.
- `"cmdline"` - treat input as |Command-line| text and show completions at caret.
Note: as there is no |getcmdcomplpat()| variant to use outside of Command-line
mode, the base is inferred from |getcompletion()| output as the widest text to
caret's left that matches all candidates: fuzzily if |'wildoptions'| contains
`fuzzy`, as a prefix otherwise (respecting |'ignorecase'| and |'smartcase'|).
If none - use empty string. There are limitations, but this is good enough.
- Every method supported by |getcompletion()|. Base is computed as the keyword
at caret's left.
Parameters ~
{state} `(table)` Current |MiniInput-state|.
{method} `(string)` Completion method.
{opts} `(table|nil)` Options. Possible fields:
- <precise_history> `(boolean)` - whether for `method='history'` try to match
only entries that have <cwd> as |current-directory|, same <scope> and
<prompt> as in current state. Default: `true`.
Usage ~
>lua
-- Do not match history precisely
local complete_opts = { precise_history = false }
local complete_handler = function(state, method)
return MiniInput.default_complete(state, method, complete_opts)
end
require('mini.input').setup({ handlers = { complete = complete_handler } })
<
------------------------------------------------------------------------------
*MiniInput.state_to_chunks()*
`MiniInput.state_to_chunks`({state}, {max_width}, {opts})
Convert state into text-hl chunks
- Treat `state.highlight` elements in increasing priority, i.e. later ones
are placed "on top" of the previous ones if they overlap.
- Uses |MiniInput-hl-groups|.
- Multiline input (i.e. with newline characters `\n`) is shown as a single line.
- Treats `max_width` as display width (|strdisplaywidth()|).
- Truncates output chunks trying to center the caret.
Parameters ~
{state} `(table)` A |MiniInput-state|.
{max_width} `(number|nil)` Maximum allowed display width. Can be |math.huge|.
{opts} `(table|nil)` Options. Possible fields:
- <keytrans> `(boolean)` - whether to translate control characters (escaped
version of `<C-...>`). Default: `true`.
- <include_prompt> `(boolean)` - whether to start chunks with state prompt.
Default: `true`.
- <include_hint> `(boolean)` - whether to show complete hint to caret's right.
Default: `true`.
- <symbol_caret> `(string)` - string to use for caret. Default: `"▏"`.
- <symbol_hide> `(string)` - string to use for each input character when
input is hidden. Default: `"•"`.
Return ~
`(table)` An array of text-hl chunks that fit `max_width` display width.
------------------------------------------------------------------------------
*MiniInput.apply_handler()*
`MiniInput.apply_handler`({state}, {name}, {arg})
Apply state's handler
Given |MiniInput-state|, apply its handler (from `state.opts.handlers`) and
return the modified state.
Notes:
- Nothing is done for highlight and complete handlers when input is hidden.
- Applying complete handler ensures that <complete> state field has <id> set
to 0 (as it assumes new completion) and <method> to the input argument
(empty string if there was no argument).
- Error during handler application is stored as <errmsg> field of output state
if there is an active input. It is propagated via |error()| otherwise.
- Handler output is validated to be a valid |MiniInput-state|. If not - return
input `state`. Note: it still could be changed if handler modified in place.
Parameters ~
{state} `(table)` A |MiniInput-state|.
{name} `(string)` Valid handler name.
{arg} `(any)` Extra handler argument: like `key` for key handler and `method`
for complete handler.
Return ~
`(table)` A |MiniInput-state| as a result of applied handler. If handler returned
nothing, the input `state` is returned (assumes it was modified in place).
vim:tw=78:ts=8:noet:ft=help:norl: