-
Notifications
You must be signed in to change notification settings - Fork 12
/
Copy pathesearch.txt
1634 lines (1434 loc) · 77.8 KB
/
esearch.txt
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
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
*esearch.txt* Neovim/Vim plugin for `e`asy async `search` and replace across multiple
files.
CONTENTS *esearch-help-contents*
Features overview |esearch-features|
Install |esearch-install|
Quick start |esearch-quickstart|
Global |esearch-global|
Keymaps |esearch-global-map|
Configurations |esearch-global-config|
Search window |esearch-win|
Keymaps |esearch-win-map|
Configurations |esearch-win-config|
Preview |esearch-win-preview|
Editing |esearch-win-editing|
Commandline |esearch-cmdline|
Prompt |esearch-cmdline-prompt|
Menu |esearch-cmdline-menu|
Appearance |esearch-appearance|
Performance |esearch-performance|
API |esearch-api|
Global functions |esearch-api-global-functions|
Local functions |esearch-api-local-functions|
Events |esearch-api-events|
Usage examples |esearch-api-examples|
Troubleshooting |esearch-troubleshooting|
Licence |esearch-licence|
================================================================================
FEATURES OVERVIEW *esearch-features*
- Simplicity (works out of the box, pattern are auto-escaped).
- High performance:
- Fully async functioning using neovim/vim8 jobs api.
- Fast lua-based rendering (up to 40k lines in less than a second).
- Viewport position-based highlights (neovim only).
- Adaptive disabling of certain highlights on a large number of lines.
- In-place modifying and saving changes into files.
- Filetype-dependent syntax highlights for better navigation.
- Input prompt interface instead of using |:| commandline:
- Search patterns can be pasted as is
- Pcre-to-vim regex translation to highlight matches.
- 2 preview modes using both neovim floating windows or plain split windows.
- Interactions are done via API methods, that can be modified or reused to
personalize the workflow.
- Third party plugins integration:
- vim-visual-multi (multiple cursors plugin) is guarded against editing
filenames and line numbers.
- NerdTree, Dirvish, NetRanger, Fern, Defx file browsers can be used to
specify search paths.
================================================================================
INSTALL *esearch-install*
Add one of the following lines depending on your plugin manager:
>
call minpac#add('eugen0329/vim-esearch')
call dein#add('eugen0329/vim-esearch')
Plug 'eugen0329/vim-esearch'
Plugin 'eugen0329/vim-esearch'
<
Recommended: install [rg], [ag], [ack] or [pt] for faster searching and extra
features. Install [semgrep] and [gogrep] for semantic searching. Otherwise,
grep or git-grep will be used.
[rg] https://github.com/BurntSushi/ripgrep#installation
[ag] https://github.com/ggreer/the_silver_searcher#installing
[ack] https://beyondgrep.com/install/
[pt] https://github.com/monochromegane/the_platinum_searcher#user
[semgrep] https://github.com/returntocorp/semgrep
[gogrep] https://github.com/mvdan/gogrep
================================================================================
QUICK START *esearch-quickstart*
Start searching~
Type `<leader>ff` keys (`<leader>` is `\` unless redefined) to open the
input prompt. Use `<c-r><c-r>`, `<c-s><c-s>` and `<c-t><c-t>` within the
prompt to cycle through regex, case-sensitive and text-objects matching
modes or use `<c-o>` to open a menu to set searching paths, filetypes or
other configs.
Navigation~
Within the search window use `J` and `K` to jump between entries or `{`
and `}` to jump between filenames. Use `(` and `)` to jump between filenames from
different directories.
Open files~
To open a line in a file press `<enter>` (open in the current window), `o`
(open in a split), `s` (split vertically) or `t` to open in a new tab. Use
the keys with shift pressed (`O`, `S` and `T`) to open staying in the
search window.
Edit results~
Modify or delete results right inside the search window. Press <enter> in
|Insert| mode to add new lines below or above the line with results. Use `im`
and `am` text-objects to jump to the following match and start operating on
it (works similar to |gn| sequence). E.g. use `cim` and type the replacement.
Press `.` to repeat the replacement on the further matches.
Write changes~
Type `:write<cr>` to save changes into files. Use undo followed by `:write<cr>`
to revert changes made earlier.
Preview~
Press `p` to open a preview window. Use multiple `p` to zoom it and capital
`P` to enter the preview for superficial changes (without moving to a separate
split window).
================================================================================
GLOBAL *esearch-global*
GLOBAL KEYMAPS *esearch-global-map*
*esearch-global-map-overview*
*<plug>(esearch)* *<plug>(operator-esearch-exec)*
*<plug>(operator-esearch-prefill)*
Keymap Default What does ~
---------------------------------+------------+----------------------------------------------
<plug>(esearch) | <leader>ff | Start the input prompt
<plug>(operator-esearch-prefill) | <leader>f | Start the prompt prefilled with a text-object
<plug>(operator-esearch-exec) | | Start searching for a text-object
---------------------------------+------------+----------------------------------------------
Example custom configuration: >
nmap <c-f><c-f> <plug>(esearch)
map <c-f> <plug>(operator-esearch-prefill)
map <c-m-f> <plug>(operator-esearch-exec)
<
In NORMAL mode press:
- <c-f><c-f> (double control-f) to start the input prompt prefilled using one
of specified strategies, e.g. clipboard, word under the cursor etc.
(see |g:esearch.prefill|)
- <c-f>i" to start the prompt prefilled with double quotes inner text.
- <c-m-f>iw to start searching for the current word instantly (works the
same as <c-f>iw<enter>, but requires less keystrokes).
In VISUAL mode press:
- <c-f> to start the input prompt, prefilled using the selected text.
- <c-m-f> to start searching for the selected text instantly.
Another simplified example: >
nmap <m-f> <plug>(esearch)
vmap <m-f> <plug>(operator-esearch-exec)
autocmd FileType nerdtree map <buffer> <m-f> <Plug>(operator-esearch-prefill)
<
In NORMAL mode press:
- <m-f> (meta-f or alt-f) to start the input prompt.
In VISUAL mode press:
- <m-f> to start searching for the selected text instantly.
Withing NERDTree buffer:
- <m-f> to prefill searching directories with selected nodes.
See also: |object-select|, |operator|.
________________________________________________________________________________~
GLOBAL CONFIGURATIONS *esearch-global-config*
*g:esearch*
Configurations are scoped within `g:esearch` dictionary to make them easier to
review and to not create mess within the global namespace. This dictionary
will be inherited by any new search request.
To customize the plugin you must initialize it first with:
>
let g:esearch = {}
<
*esearch-global-config-overview*
Property What contains~
-------------------------+-----------------------------------------------------
`.regex` | Regex matching mode (fixed strings, PCRE etc.)
`.case` | Case matching mode (smart, sensitive etc.)
`.textobj` | Text-objects matching mode (whole words, lines etc.)
`.prefill` | List of strategies to prefill the prompt input
`.root_markers` | List of filenames to determine the project root
`.filetypes` | String with filetypes to search in (space separated)
`.paths` | String with paths to search in using shell syntax
`.live_update` | Start and update the output while you're typing
`.write_cb()` | Callback to write a buffer after applying changes
`.select_prefilled` | Flag to visually select a prefilled prompt text
`.default_mappings` | Flag to toggle all default keymaps
`.adapter` | Search util (ag, rg, grep etc.) adapter name
`.backend` | Processing backend (|job-control|, |system()| etc.) name
`.out` | Output target name (window or quickfix list)
`.git_dir()` | |Funcref| to extract git repository path
`.git_url()` | |Funcref| to generate urls for blobs viewing
`.filemanager_integration` | Flag to toggle capturing paths from filemanagers
-------------------------+-----------------------------------------------------
g:esearch.default_mappings *g:esearch.default_mappings*
Flag to disable all default keymaps including both global and search
window local keymaps.
Type: |Boolean|
Default: 0
Example:~
>
let g:esearch.default_mappings = 1
<
g:esearch.regex *g:esearch.regex*
Regex matching mode. You can specify explicitly what regex engine to use
depending on what search util is set in |g:esearch.adapter| or use boolean
values to choose automatically. E.g. if |g:esearch.adapter| is set or
automatically resolved to `'grep'` you can set `'extended'` mode to use
extended regex engine, `'pcre'` to use perl compatible regex etc.
Type: |Boolean| or |String|
Allowed values: `1`, `0` or engine name string
Default: 0
Example:~
>
let g:esearch.regex = 1
<
Regex engine names of adapters:
Adapter Allowed g:esearch.regex values ~
-------+----------------------------------------------------------------
`'rg'` | `'literal'`, `'default'`, `'auto'`, `'pcre'`
`'ag'` | `'literal'`, `'pcre'`
`'ack'` | `'literal'`, `'pcre'`
`'pt'` | `'literal'`, `'re2'`
`'git'` | `'literal'`, `'basic'`, `'extended'`, `'pcre'`
`'grep'` | `'literal'`, `'basic'`, `'extended'`, `'pcre'`
-------+----------------------------------------------------------------
NOTE Older versions of [rg] may not have `'pcre'` and `'auto'` available.
`'git'` and `'grep'` may also have some engines missing depending on what
installation options were used, so it's recommended to update the util
you're going to use or rebuild them with pcre support to unlock all the
features.
g:esearch.case *g:esearch.case*
Case matching mode.
Type: |Boolean| or |String|
Allowed values: `0`, `1`, `'ignore'` (same as `0`), `'sensitive'` (same as `1`) or
`'smart'`
Default: 0
Example:~
>
let g:esearch.case = 'smart'
<
g:esearch.textobj *g:esearch.textobj*
Text-objects matching mode (e.g. whole lines or whole words).
Type: |Boolean| or |String|
Allowed values: `0`, `'none'` (same as `0`), `'word'` or `'line'`
Default: 0
Example:~
>
let g:esearch.case = 'word'
<
NOTE Only [grep] and [rg] support `'line'`.
g:esearch.prefill *g:esearch.prefill*
List of strategies to set the initial value of the prompt.
Allowed list elements: `'clipboard'` (prefills with |clipboard| content),
`'hlsearch'` (currently highlighted pattern searched with `/`), `'last'`
(last pattern search using the plugin), `'cword'` (word under the
cursor), `'current'` (if within the search window) or a function
reference, that returns a string with a pattern or an empty value to
proceed to the next strategy.
Type: |List| of |String| and |Funcref|s
Default: `['hlsearch', 'current', 'last']`
Example:~
>
let g:esearch.prefill = ['hlsearch', 'cword', {-> 'custom text' }]
<
NOTE The order of listed strategies matters.
g:esearch.root_markers *g:esearch.root_markers*
List of file and directory names to use to determine the project root.
Type: |List| of |String|s
Default: `['.git', '.hg', '.svn', '.bzr', '_darcs']`
Example:~
>
let g:esearch.root_markers = ['.git', 'Makefile', 'node_modules']
<
g:esearch.filetypes *g:esearch.filetypes*
Space-separated filetype names to search in.
Type: |String|
Default: `''` (search in any filetype)
Example:~
>
let g:esearch.filetypes = 'python css js'
<
NOTE Supported only by [ag], [rg] and [ack].
g:esearch.live_update *g:esearch.live_update*
Start the search instantly and update the output while you're typing
using the currently inputted pattern.
Type: ||Boolean|
Default: 1
Example:~
>
let g:esearch.live_update = 0
<
NOTE To increase the timeout after which the output is updated see
|g:esearch.live_update_debounce_wait| variable.
NOTE To configure the number of chars after which a new search is
started see |g:esearch.live_update_min_len| variable.
g:esearch.write_cb({buf}, {bang}) *g:esearch.write_cb()*
|Funcref| that is invoked after applying changes to each buffer while
writing changes using |:write| command.
Type: |Funcref|
Default: function that writes changes in the background
Parameters:~
{buf} Modified buffer handle.
{bang} Shows whether |:write| command was executed with a "!"
Example:~
>
let g:esearch.write_cb =
\ {buf, bang -> buf.write(bang) && buf.open('$tabnew')}
<
Example above configures the writer to write changes and open buffers
for reviewing them.
See also: |g:esearch.write_cb()-examples|.
{buf} props What they are used for ~
--------------------+---------------------------------------------------------
`.existed` | Shows whether |bufexists()| returned |TRUE| before loading
`.bufnr` | Buffer number
`.filename` | Opened file absolute path
`.text` | First changed line text (for passing to |setqflist()|)
`.lnum` | First changed line number (for passing to |setqflist()|)
`.write([{bang}]`) | Invokes |:write| for the buffer with optional ! applied
`.open({opener}`) | Open buffer using {opener} command |String| or |Funcref|
`.bdelete([{bang}]`) | Invokes |:bdelete| for the buffer with optional ! applied
`.bwipeout([{bang}]`) | Invokes |:bwipeout| for the buffer with optional ! applied
--------------------+---------------------------------------------------------
*esearch-backticks*
g:esearch.paths *g:esearch.paths*
Paths listed using shell syntax to search in.
Type: ||String|
Default: `''` (search in any path within the cwd)
Example:~
>
let g:esearch.filetypes = 'node_modules/ configs/**/*.yml'
<
NOTE To use all globbing features make ensure that 'shell' option
contains required arguments. E.g. for bash globbing add to your vimrc:
`set shell=bash\ -O\ globstar -O\ extglob`
If you use OSX, install the latest bash version first using:
`:!brew install bash`
NOTE For POSIX compliant shells `` backticks can be used to use
evaluated results as paths. See also: |esearch-git-examples|.
g:esearch.select_prefilled *g:esearch.select_prefilled*
Flag to use a visual-like selection of a prefilled text in the prompt.
Initial selection can be blanked if a regular char or <Del>-like chars
are typed and is cancelled if any special character like arrow keys,
<c-e> or others are used.
Type: |Boolean|
Default: 1
Example:~
>
let g:esearch.select_initial = 0
<
g:esearch.before *g:esearch.before*
g:esearch.after *g:esearch.after*
g:esearch.context *g:esearch.context*
Number of lines to insert before, after or around of a matched line.
Type: |Number|
Allowed values: > 0
Default: 0
Example:~
>
let g:esearch.before = 1
let g:esearch.after = 2
<
g:esearch.remember *g:esearch.remember*
List of configuration names to remember for later search requests.
Configurations not listed there will be reset to initial when the prompt
is closed.
Type: |List| of |String|s
Allowed values: a list of |g:esearch| field names
Default: >
['case', 'textobj', 'regex', 'before',
\ 'filetypes', 'paths', 'after', 'context', 'last_pattern']
< Example:~
>
let g:esearch.remember = ['case', 'regex', 'filetypes']
<
g:esearch.adapter *g:esearch.adapter*
Name of a search util to use.
Type: |String|
Allowed values:
`'rg'`, `'ag'`, `'ack'`, `'pt'`, `'git'`, `'gogrep'`, `'semgrep'` or `'grep'`
Default: depends on executables availability.
Example:~
>
let g:esearch.adapter = 'grep'
<
g:esearch.backend *g:esearch.backend*
Name of a processing backend to use.
Type: |String|
Allowed values: `'nvim'`, `'vim8'`, `'system'`
Default: depends on editor features.
Example:~
>
let g:esearch.backend = 'system'
<
g:esearch.out *g:esearch.out*
Name of a target to output results.
Type: |String|
Allowed values: `'win'`, `'qflist'`
Default: `'win'`
Example:~
>
let g:esearch.out = 'qflist'
<
NOTE Quickfix list output contains far less features as it's vim's
builtin.
g:esearch.git_dir({cwd}) *g:esearch.git_dir()*
Function to extract git repository path.
Type: |Funcref|
Default: function that searches up for .git/HEAD file
Parameters:~
{cwd} |String| with directory used for .git extraction
Example:~
>
let g:esearch.git_dir = {cwd -> FugitiveExtractGitDir(cwd)}
<
g:esearch.git_url({path}, {dir}) *g:esearch.git_url()*
Function to generate urls for blobs viewing.
Type: |Funcref|
Default: function that generates blob filenames used internally
Parameters:~
{path} |String| with path in rev:filename format
{dir} |String| with extracted git directory
Example:~
>
let g:esearch.git_url = {path, dir -> FugitiveFind(path, dir)}
<
g:esearch.filemanager_integration *g:esearch.filemanager_integration*
Flag to toggle integration with filemanagers (nerdtree, dirvish,
netranger, fern, defx). If withing a filemanager window, the plugin will
start the prompt using a directory under the cursor or using files and
directories selected in |Visual| mode.
Type: |Boolean|
Default: 1
Example:~
>
let g:esearch.filemanager_integration = 0
<
================================================================================
SEARCH WINDOW *esearch-win*
SEARCH WINDOW KEYMAPS *esearch-win-map*
*esearch-win-map-overview*
*esearch-win-map-defaults*
Keymaps, that can be used to customize the behavior by adding elements with
keymaps definitions to |g:esearch.win_map| list:
Keymap Default What does~
--------------------------------------+------+----------------------------------------------------------
<plug>(esearch-win-reload) | R | Reload current search
<plug>(esearch-win-tabopen) | t | Open a file under the cursor in a tab
<plug>(esearch-win-tabopen:stay) | T | Open in a tab and stay within the win
<plug>(esearch-win-split) | o | Open a file under the cursor in a split
<plug>(esearch-win-split:reuse:stay) | O | Open in a reusable split and stay within the win
<plug>(esearch-win-vsplit) | s | Open a file under the cursor in a vertical split
<plug>(esearch-win-vsplit:reuse:stay) | S | Open in a reusable vertical split and stay within the win
<plug>(esearch-win-open) | <cr> | Open a file under the cursor in the window
<plug>(esearch-win-preview) | p | Open the preview window
<plug>(esearch-win-preview:enter) | P | Open the preview window and enter it
<plug>(esearch-win-jump:entry:down) | J | Jump down to the next outputted line
<plug>(esearch-win-jump:entry:up) | K | Jump up to the previous outputted line
<plug>(esearch-win-jump:filename:down) | } | Jump down to the next filename
<plug>(esearch-win-jump:filename:up) | { | Jump up to the previous filename
<plug>(esearch-win-jump:dirname:down) | ) | Jump down to the filename from another directory
<plug>(esearch-win-jump:dirname:up) | ( | Jump up to the filename from another directory
<plug>(textobj-esearch-match-i) | im | Seek forward and operate the next match
<plug>(textobj-esearch-match-a) | am | Same as above, but also capture surrounding spaces
<plug>(esearch-za) | za | Toggle the fold. See also: |za|.
<plug>(esearch-zc) | zc | Close the fold under the cursor. See also: |zc|.
<plug>(esearch-zM) | zM | Close all folds. See also: |zM|.
--------------------------------------+------+----------------------------------------------------------
g:esearch.win_map *g:esearch.win_map*
List of keymap definitions in builtin |nvim_set_keymap()| function
arguments format to extend default keymaps. To override default
keymaps use it with |g:esearch.default_mappings| set to `0`.
Type: |List| of |List|s
Default: see |esearch-win-map-defaults| table above
Format: >
let g:esearch.win_map = [[{modes}, {lhs}, {rhs}, {opts}], ...]
<
Parameters:~
{modes} |String| with mode characters (`'n'` for |Normal|, `'v'` for |Visual|,
`' '` to use as |:map| command etc.)
{lhs} Left-hand side of the keymap
{rhs} Right-hand side of the keymap
{opts} |Dict| of |:map-arguments| names. Use `{'noremap': 1}` - to define
as |:noremap| in a specified mode, `{'unique': 1}` to define
with |:map-<unique>| argument etc (optional)
Example:~
>
let g:esearch = {}
let g:esearch.win_map = [
\ ['n', 'e', '<plug>(esearch-win-vsplit)' ],
\ ['n', 'E', '<plug>(esearch-win-vsplit:stay)', {'nowait': 1}],
\ ['nx', '-', ':call CustomFunction(mode())<cr>', {'noremap': 1}],
\]
<
NOTE Multiple mode characters are specified for `'-'` key to define the
same keymap for multiple modes and to not-repeat-yourself.
The example above is equivalent to using |esearch_win_config| autocommand
and vim |:map| command.
>
autocmd User esearch_win_config call s:esearch_win_config()
function! s:esearch_win_config() abort
nmap <silent><buffer> e <plug>(esearch-win-vsplit)
nmap <silent><buffer><nowait> E <plug>(esearch-win-vsplit:stay)
nnoremap <silent><buffer> - :call CustomFunction(mode())<cr>
xnoremap <silent><buffer> - :call CustomFunction(mode())<cr>
endfunction
<
NOTE Arguments `{'silent': 1, 'buffer': 1}` in |g:esearch.win_map| elements
are merged automatically with user defined pairs. Don't override them
to avoid side effects.
See also: |nvim_set_keymap()| for list elements syntax.
<plug>(esearch-win-reload) *<plug>(esearch-win-reload)*
Reload the current search window.
<plug>(esearch-win-open) *<plug>(esearch-win-open)*
Open a line in the file under the cursor.
Default: see |esearch-win-map-defaults|
Example:~
>
let g:esearch.win_map = [['n', 'e', '<plug>(esearch-win-open)']]
<
NOTE To return to the search window |CTRL-O| can be used (the builtin vim
command to jump to older cursor positions).
<plug>(esearch-win-tabopen) *<plug>(esearch-win-tabopen)*
<plug>(esearch-win-tabopen:stay) *<plug>(esearch-win-tabopen:stay)*
Open a line in the file under the cursor using new tab. If `:stay` is
used - stay in the search window.
Default: see |esearch-win-map-defaults|
<plug>(esearch-win-split) *<plug>(esearch-win-split)*
<plug>(esearch-win-split:stay) *<plug>(esearch-win-split:stay)*
<plug>(esearch-win-split:reuse) *<plug>(esearch-win-split:reuse)*
<plug>(esearch-win-split:reuse:stay) *<plug>(esearch-win-split:reuse:stay)*
Open a line under the cursor in the file using horizontal split. If
`:stay` is used - stay in the search window. If `:reuse` is used - reuse the
opened window for all further opens in the horizontal split.
Default: see |esearch-win-map-defaults|
<plug>(esearch-win-vsplit) *<plug>(esearch-win-vsplit)*
<plug>(esearch-win-vsplit:stay) *<plug>(esearch-win-vsplit:stay)*
<plug>(esearch-win-vsplit:reuse) *<plug>(esearch-win-vsplit:reuse)*
<plug>(esearch-win-vsplit:reuse:stay) *<plug>(esearch-win-vsplit:reuse:stay)*
Open a line under the cursor in the file using vertical split. If
`:stay` is used - stay in the search window. If `:reuse` is used -
reuse the opened window for further opens in the vertical split.
Default: see |esearch-win-map-defaults|
<plug>(esearch-win-preview) *<plug>(esearch-win-preview)*
<plug>(esearch-win-preview:enter) *<plug>(esearch-win-preview:enter)*
<plug>(esearch-win-preview:close) *<plug>(esearch-win-preview:close)*
Show the line under the cursor in the file using preview window. If
`:enter` is used - put the cursor into the opened preview window. Prefix
it with |[count]| to multiple the window size.
Default: see |esearch-win-map-defaults|
NOTE Floating preview is only supported in neovim >=0.4.0. For vanilla
vim split window will be used instead.
See also: |esearch-autopreview|.
<plug>(esearch-win-jump:filename:up) *<plug>(esearch-win-jump:filename:up)*
<plug>(esearch-win-jump:filename:down) *<plug>(esearch-win-jump:filename:down)*
Move cursor to a filename up or down. Prefix it with |[count]| to jump
through multiple filenames.
Default: `{` and `}`
Example:~
>
let g:esearch.win_map = [
\ [' ', ']f', '<plug>(esearch-win-jump:filename:down)zz'],
\ [' ', '[f', '<plug>(esearch-win-jump:filename:up)zz']
\]
<
The example above defines `]f` and `[f` keymaps to jump between filenames
center the screen after a jump.
NOTE `' '` is used to create a keymap using regular |:map| command.
NOTE When jumping from the header <plug>(esearch-win-jump:filename:down)
navigates the 2nd filename for convenience reasons, as opening when the
cursor is above the header leads to opening the 1st file.
Use <plug>(esearch-win-jump:filename:up) to focus the 1st filename.
See also: |nvim_set_keymap()|.
<plug>(esearch-win-jump:dirname:up) *<plug>(esearch-win-jump:dirname:up)*
<plug>(esearch-win-jump:dirname:down) *<plug>(esearch-win-jump:dirname:down)*
Move cursor to the filename from a different directory up or down.
Prefix it with |[count]| to jump through multiple dirnames.
Default: `(` and `)`
Example:~
>
let s:echo_dir = ':<c-u>echo fnamemodify(b:esearch.filename(), ":h")<cr>'
let g:esearch.win_map = [
\ [' ', ']]', '<plug>(esearch-win-jump:dirname:down)'.s:echo_dir],
\ [' ', '[[', '<plug>(esearch-win-jump:dirname:up)'.s:echo_dir]
\]
<
The example above defines `[[` and `]]` keymaps to jump between filenames
from different directories and print a hovered directory after the jump.
NOTE `' '` is used to create a keymap using regular |:map| command.
NOTE When jumping from the header <plug>(esearch-win-jump:dirname:down)
jumps to the 2nd directory filename for convenience reasons, as opening
when the cursor is above the header leads to opening a file from the 1st
directory.
Use <plug>(esearch-win-jump:dirname:up) to focus the 1st filename.
See also: |nvim_set_keymap()|.
<plug>(esearch-win-jump:entry:up) *<plug>(esearch-win-jump:entry:up)*
<plug>(esearch-win-jump:entry:down) *<plug>(esearch-win-jump:entry:down)*
Move cursor to an outputted text line up or down. Prefix it with |[count]|
to jump through multiple entries.
Example:~
>
let g:esearch.win_map = [
\ [' ', '<c-p>', '<plug>(esearch-win-jump:entry:up)'],
\ [' ', '<c-n>', '<plug>(esearch-win-jump:entry:down)']
\]
<
NOTE `' '` is used to create a keymap using regular |:map| command.
NOTE <plug>(esearch-win-jump:entry:down) jumps to the 2nd entry for
convenience reasons, as opening when the cursor is above the header
leads to opening the first entry.
Use <plug>(esearch-win-jump:entry:up) to focus the 1st entry.
See also: |nvim_set_keymap()|.
<plug>(textobj-esearch-match-i) *<plug>(textobj-esearch-match-i)*
<plug>(textobj-esearch-match-a) *<plug>(textobj-esearch-match-a)*
Seek a match under the cursor or on a line forward to execute an
operator on it. <plug>(textobj-esearch-match-i) captures highlighted
regions, while <plug>(textobj-esearch-match-a) additionally trailing or
leading spaces like |aw| text-object do.
Usage example: press `dam` to delete "a match" under the cursor or located
on any line further with leading or trailing spaces or `cim` to delete
"inner match" and start the insert mode.
Default: see |esearch-win-map-defaults|
Example:~
>
let g:esearch.win_map = [
\ ['ov', 'ir', '<plug>(textobj-esearch-match-i)'],
\ ['ov', 'ar', '<plug>(textobj-esearch-match-a)']
\]
<
NOTE Multiple mode chars are used to define the same keymaps for both
|Visual| and |Operator-pending| modes.
See also: |operator|, |text-objects|.
<plug>(esearch-za) *<plug>(esearch-za)*
<plug>(esearch-zc) *<plug>(esearch-zc)*
<plug>(esearch-zM) *<plug>(esearch-zM)*
Fast folds handling using |fold-manual| method with ranges defined
automatically. Folds entire file contexts for regular files and group
multiple files under a single fold if they are git blobs.
See also: |za|, |zc|, |zM|, |esearch-git-show-preview-example|.
================================================================================
SEARCH WINDOW CONFIGURATIONS *esearch-win-config*
Search window-related configurations are added to |g:esearch| dictionary.
*esearch-win-config-overview*
Property What contains~
-----------------------------+-------------------------------------------------
`.win_new()` | Funcref to open a new window with search results
`.win_map` | List of window-local keymaps
`.win_contexts_syntax` | Flag to use filetype-aware syntax highlights
`.win_context_len_annotations` | Flag to show outputted lines count of a context
`.win_cursor_linenr_highlight` | Funcref to open a new window with search results
-----------------------------+-------------------------------------------------
g:esearch.win_new({esearch}) *g:esearch.win_new()*
Function to open a new search window.
Type: |Funcref|
Default: function that reuse windows with the same patterns
Parameters:~
{esearch} Facade object inherited from |g:esearch| and extended with
|esearch#init()| {opts} parameter to be written to |b:esearch|
buffer-local variable after |g:esearch.win_new()| call
Example:~
>
let g:esearch.win_new =
\ {esearch -> esearch#buf#goto_or_open(esearch.name, 'vnew') }
<
Example above will use a single window for any search request in a
vertical split and reuse it for further searches.
See also: |g:esearch.win_new()-examples|, |esearch#buf#goto_or_open()|
g:esearch.win_contexts_syntax *g:esearch.win_contexts_syntax*
Flag to toggle filetype-dependent syntax.
Type: |Boolean|
Default: 1
Example:~
>
let g:esearch.win_contexts_syntax = 1
g:esearch.win_context_len_annotations *g:esearch.win_context_len_annotations*
Flag to toggle annotations to the right of a filename, that show the
number of outputted lines.
Type: |Boolean|
Default: 1
Example:~
>
let g:esearch.win_context_len_annotations = 1
<
NOTE Neovim >=0.4.3 is required.
g:esearch.win_cursor_linenr_highlight *g:esearch.win_cursor_linenr_highlight*
Flag to toggle virtual UI cursor line numbers highlight, similar to
how it's done in regular buffers.
Type: |Boolean|
Default: depends on 'cursorline' builtin option value
Example:~
>
let g:esearch.win_cursor_linenr_highlight = 1
<
________________________________________________________________________________~
SEARCH WINDOW PREVIEW *esearch-win-preview*
*esearch-win-split-preview*
The plugin has two option for previewing the results:
- floating preview (using neovim floating windows).
- split preview (using regular split windows).
Preview window is opened with `p` key or using |<plug>(esearch-win-preview)|
key if remapped. If neovim, floating window is used by default. To zoom floating
preview window press `p` key multiple times. To enter the preview window press
capital `P`. Use |<plug>(esearch-win-preview:enter)| to map a custom key to enter
the preview window.
See also: |g:esearch.win_map| for keymaps customization.
________________________________________________________________________________~
SEARCH WINDOW EDITING *esearch-win-editing*
*<plug>(esearch-I)* *<plug>(esearch-cr)* *<plug>(esearch-d)*
*<plug>(esearch-dd)* *<plug>(esearch-c)* *<plug>(esearch-.)*
*<plug>(esearch-cc)* *<plug>(esearch-C)* *<plug>(esearch-D)*
*<plug>(esearch-@:)*
Builtin keymaps are redefined within the search buffer to track changes and help
modifying search results. Default definitions:
>
let g:esearch.win_map = [
\ ['n', 'I', '<plug>(esearch-I)' ],
\ ['ic', '<cr>', '<plug>(esearch-cr)', {'nowait': 1}],
\ ['x', 'x', '<plug>(esearch-d)' ],
\ ['nx', 'd', '<plug>(esearch-d)' ],
\ ['n', 'dd', '<plug>(esearch-dd)' ],
\ ['nx', 'c', '<plug>(esearch-c)' ],
\ ['n', 'cc', '<plug>(esearch-cc)' ],
\ ['nx', 'C', '<plug>(esearch-C)' ],
\ ['nx', 'D', '<plug>(esearch-D)' ],
\ ['x', 's', '<plug>(esearch-c)' ],
\ ['n', '.', '<plug>(esearch-.)' ],
\ ['n', '@:', '<plug>(esearch-@:)' ],
\]
<
Keymap What does ~
-------------------+-----------------------------------------------------------
<plug>(esearch-I) | Starts insert mode at the beginning of the text after the
| virtual line number
<plug>(esearch-cr) | In |Insert| mode: inserts signs before virtual line numbers
| to append or prepend new lines when |:w| the window;
| in |Command-line| mode: makes |esearch-editing-commands| safe.
Others ... | Register deleted lines, set repeats and execute default
| commands of the same name. See |dd|, |@:| or others for help.
See also: |g:esearch.win_map| for keymaps customization syntax.
*esearch-editing-commands*
Recognized commands syntax, that will be handled on <plug>(esearch-cr) press
in |Command-line| mode within the search buffer:
>
<substitute> ::= s%[ubstitute] | sno%[magic] | sm%[agic]
<global> ::= g%[lobal] | v%[global] | g%[lobal]!
<delete> ::= d%[elete]
:<delete> ...
:<substitute> ...
:<global> ...
:<global>/pattern/<delete> ...
:<global>/pattern/<substitute> ...
:<global>/pattern/<global> ...
:<global>/pattern/...
<
If |:delete| is submitted, corresponding lines are tracked as deleted.
If any form of <substitute> or <global> is submitted, the pattern will be
modified atuomatically to prevent matching the header, filenames and virtual
line numbers.
If commands are separated with |<bar>| or passed into |:execute|, they won't be
recongnized and will be executed as is.
See also: |:delete|, |:substitute| and |:global| builtin commands syntax.
================================================================================
APPEARANCE *esearch-appearance*
Example to make the search window look minimalistic by removing any visual
distractions:
>
" Make header less colorful
highlight link esearchHeader Comment
" Don't emphasize numbers lines/files count in the header with colors
highlight link esearchStatistics esearchHeader
highlight link esearchFilename Function
" Don't emphasize basename with bold text attribute
highlight link esearchBasename esearchFilename
highlight link esearchMatch String
let g:esearch = extend(get(g:, 'esearch', {}), {
\ 'win_context_len_annotations': 0,
\ 'win_contexts_syntax': 0,
\})
<
See also: |highlight-ctermfg|, |highlight-guifg|, |highlight-groups|.
*esearch-appearance-overview*
esearchHeader
v-----------------------------------v
.--------.---------------------- esearchStatistics
v v
Matches in `2` lines, `1` file. Finished.
v------v---------------------- esearchBasename
.-------> /path/to/file.txt `2 lines` <------------ Annotation {2}
| .-------> 1 `matched text`
| | .-----> `2` another line wit`|`h `matched text`
| | | .-> `+` 2 Appended line ^ ^----.-----^
| | | | | |
| | | | | esearchMatch
| | | | Cursor position {1}
| | | esearchDiffAdd
| | esearchCursorLineNr
| esearchLineNr
esearchFilename
{1} Vim cursor position that affects whether
|hl-esearchCursorLineNr| or |hl-esearchLineNr|
is used
{2} See |g:esearch.win_context_len_annotations|
esearchHeader *hl-esearchHeader*
First window line highlight. Contains statistics, spinner and request
status information.
Default: |hl-Normal| with "bold" attribute
esearchStatistics *hl-esearchStatistics*
Information about outputted lines and files count highlight. Contained
in the header.
Default: link to Number
esearchFilename *hl-esearchFilename*
Filename above each context highlight.
Default: link to |hl-Directory|
esearchBasename *hl-esearchBasename*
Basename of the current filename. Neovim only.
Default: |esearchFilename| with |bald| attribute set
esearchLineNr *hl-esearchLineNr*
Virtual UI line number highlight.
Default: link to |hl-LineNr|
esearchCursorLineNr *hl-esearchCursorLineNr*
Virtual UI line number highlight when the cursor is on the line.
Default: link to |hl-CursorLineNr|
esearchDiffAdd *hl-esearchDiffAdd*
Virtual UI sign before virtual line number to indicate appended and
prepended lines.
Default: |hl-DiffAdd| without background.
esearchMatch *hl-esearchMatch*
Matched text highlight.
Default: guessed using |hl-Normal| color by adjusting the brightness.
================================================================================
PERFORMANCE *esearch-performance*
Jump to |esearch-performance-config-overview| for available configurations.
Example configuration to make the search window faster (by sacrificing some
features):
>
let g:esearch = extend(get(g:, 'esearch', {}), {
\ 'win_update_throttle_wait': 200,
\ 'win_matches_highlight_debounce_wait': 200,
\ 'win_viewport_off_screen_margin': &lines / 2,
\ 'win_cursor_linenr_highlight': 0
\})
" Disable filetype-dependent syntaxes
let g:esearch.win_contexts_syntax = 0
" or make them faster
let g:esearch.win_contexts_syntax_sync_minlines = 100
let g:esearch.win_context_syntax_clear_on_line_len = 200
let g:esearch.win_contexts_syntax_clear_on_line_len = 100
let g:esearch.win_contexts_syntax_clear_on_files_count = 100
<
Reasons the plugin works slowly and possible solutions:
- When searching:
- Lua is missing: install vim/neovim with lua support. To verify use
`:echo esearch#has#lua`
- Too slow adapter: if |g:esearch.adapter| is set/resolved to `'grep'`,
try to use [ag], [rg], [pt] or [ack] instead.
- Too low throttling timeout: increase |g:esearch.win_update_throttle_wait|
- When scrolling:
- Vim |matchadd()| regex matches highlights are used: try to set
|g:esearch.win_matches_highlight_strategy| to ``'viewport'` (neovim only)
or `'hlsearch'`
- Long line is encountered: try to set lower values of
|g:esearch.win_context_syntax_clear_on_line_len| and
|g:esearch.win_contexts_syntax_clear_on_line_len|
- Too many files are outputted: try to set a lower value of
|g:esearch.win_contexts_syntax_clear_on_files_count|
- Outputted files contain too many lines: try to set a lower value of
|g:esearch.win_contexts_syntax_sync_minlines|
- Vim regex-based syntax is used: consider to try neovim.
See also: |g:esearch.win_ui_nvim_syntax| for details.
- On reloading/searching the same pattern:
- Search util fetches data from it's cache: no solution for now
(job control stdout callbacks aren't throttled, but it can be mitigated
using remote plugin (todo)).
*esearch-performance-config-overview*
Performance configurations:
Property What contains~
------------------------------------------+------------------------------------------------------
`.live_update_debounce_wait` | Live update start debouncing timeout (ms)
`.live_update_min_len` | Number of chars after which live update starts
`.win_update_throttle_wait` | Update throttling timeout (ms)
`.win_matches_highlight_debounce_wait` | Viewport matches highlight debouncing timeout (ms)
`.win_contexts_syntax_debounce_wait` | Viewport filetypes highlight debouncing timeout (ms)
`.win_viewport_off_screen_margin` | Number of lines to extend the viewport height
`.win_matches_highlight_strategy` | Strategy name to highlight matched text
`.win_contexts_syntax_sync_minlines` | See :help |:syn-sync-minlines| for details
`.win_context_syntax_clear_on_line_len` | Max line len before a filetype syntax is cleared
`.win_contexts_syntax_clear_on_line_len` | Max line len before all syntaxes are cleared
`.win_contexts_syntax_clear_on_files_count` | Max files count before filetype syntaxes are cleared
`.win_ui_nvim_syntax` | Flag to use position based syntax with (neovim only)
`.batch_size` | Number of lines to render per callback invocation
`.final_batch_size` | Number of lines to render before the finish
`.early_finish_wait` | Timeout to avoid screen blinks when few results (ms)
------------------------------------------+------------------------------------------------------
g:esearch.live_update_debounce_wait *g:esearch.live_update_debounce_wait*
Live update start timeout in milliseconds after which the output is
updated. The bigger this value, the lower slowdowns while you typing,
but also the later a new search with the latest pattern will be started.
Type: |Number|
Allowed values: > 0
Default: 150
g:esearch.live_update_min_len *g:esearch.live_update_min_len*
Minimum (inclusive) search pattern length to start live update.
Type: |Number|
Allowed values: > 0
Default: 3
g:esearch.win_update_throttle_wait *g:esearch.win_update_throttle_wait*
Window updates timeout in milliseconds. The bigger this value, the lower
slowdowns, but also the later the search finish.
Type: |Number|
Allowed values: >= 0
Default: 100
*g:esearch.win_matches_highlight_debounce_wait*
g:esearch.win_matches_highlight_debounce_wait
Debounce (trailing edge) timeout in milliseconds, used to prevent
slowdowns on scrolls.
Type: |Number|
Allowed values: >= 0
Default: 100