-
Notifications
You must be signed in to change notification settings - Fork 73
/
matchup.txt
1094 lines (809 loc) · 40.3 KB
/
matchup.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
*matchup.txt* modern matching words
*matchup* *match-up*
Author: Andy Massimino <a@normed.space>
Web: https://github.com/andymass/vim-matchup
Script ID: 5624
License: MIT license {{{
Copyright (c) 2021 Andy Massimino
Copyright (c) 2016 Karl Yngve Lervåg
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
IN THE SOFTWARE.
}}}
==============================================================================
CONTENTS *matchup-contents*
Introduction |matchup-introduction|
Feature overview |matchup-overview|
Usage |matchup-usage|
Default mappings |matchup-default-mappings|
Customizing mappings |matchup-custom-mappings|
Features |matchup-features|
Commands |matchup-commands|
Options |matchup-options|
File type options |matchup-file-types|
FAQ |matchup-faq|
Interoperability |matchup-interoperability|
Acknowledgments |matchup-acknowledgments|
Development |matchup-development|
==============================================================================
INTRODUCTION *matchup-introduction*
|match-up| is a plugin that lets you visualize, navigate, and operate on
matching sets of text. It is a replacement for the venerable vim plugin
|matchit|. match-up aims to replicate all of |matchit|'s features, fix a number
of its deficiencies and bugs, and add a few totally new features. It also
replaces the standard plugin |matchparen|, allowing all of |matchit|'s words to be
highlighted along with the 'matchpairs' symbols such as `()`, `{}`, and `[]`.
------------------------------------------------------------------------------
Feature overview~
*matchup-overview*
This plugin:
- Extends vim's |%| (see |matchup-%|) motion to language-specific words instead of
just single characters. The words depend on the specific |filetype| plugin
(|ftplugin|). The following built-in vim filetype plugins
currently provide support for match-up: >
abaqus, ada, aspvbs, c, clojure, cobol, config, context, csc, csh, dtd,
dtrace, eiffel, eruby, falcon, fortran, framescript, haml, hamster, hog,
html, ishd, j, jsp, kconfig, liquid, lua, make, matlab, mf, mp, ocaml,
pascal, pdf, perl, php, plaintex, postscr, ruby, sh, spec, sql, tex, vb,
verilog, vhdl, vim, xhtml, xml, zimbu, zsh
<
- Highlights symbols and words under the cursor along with their matches.
- Display off-screen matches in the |status-line|.
- Adds motions |g%|, |[%|, |]%|, and |z%|.
- Provides analogous text objects |i%| and |a%|.
==============================================================================
USAGE *matchup-usage*
------------------------------------------------------------------------------
Default mappings~
*matchup-default-mappings*
For customization, see |matchup-custom-mappings|.
*matchup-%*
% When on a recognized word, go forwards to its next
matching word. If at a close word, cycle back to the
corresponding open word. If the cursor is not on a
word, seek forwards to one and then jump to its match.
This is an |inclusive| motion.
*matchup-N%*
{count}% If {count} is less than 7, go forwards {count} times.
Otherwise, go to {count} percentage in the file (|N%|).
See |g:matchup_motion_override_Npercent|.
*g%*
g% When on a recognized word, go backwards to [count]th
previous matching word. If at an open word, cycle
around to the corresponding close word. If the cursor
is not on a word, seek forwards to one and then jump
to its match.
*[%*
[% Go to [count]th previous outer open word. Allows
navigation to the start of blocks surrounding the
cursor. This is similar to vim's built-in |[(| and |[{|
and is an |exclusive| motion (|matchup-feat-exclusive|).
*]%*
]% Go to [count]th next outer close word. Allows
navigation to the end of blocks surrounding the
cursor. This is similar to vim's built-in |])| and |]}|
and is an |exclusive| motion (|matchup-feat-exclusive|).
*z%*
z% Go to inside [count]th nearest block. This is an
|exclusive| motion when used with operators,
except it eats white-space. For example, where `█` is
the cursor position, >
█ call somefunction( param1, param2)
<
`dz%` produces >
param1, param2)
<
*v_a%* *a%*
a% Select an |any-block|.
This closely matches vim's built-in |ab|.
*v_Na%* *Na%*
{count}a% Select an |open-to-close-block|.
When {count} is greater than 1, select the {count}th
surrounding open-to-close block.
*v_i%* *i%*
i% Select the inside of an |any-block|.
This closely matches vim's built-in |ib|.
See also |matchup-feat-linewise|.
*v_Ni%* *Ni%*
{count}i% Select the inside of an |open-to-close-block|.
When {count} is greater than 1, select the inside of
the {count}th surrounding open-to-close block.
*ds%*
{count}ds% Delete {count}th surrounding matching words. This
only works for open and close words.
Requires |g:matchup_surround_enabled| = 1.
*cs%*
{count}cs% Change {count}th surrounding matching words. This
only works for open and close words. If vim-surround
is installed, you can type replacements according to
that plugin's rules. Otherwise, match-up will give
you the opportunity to type a single character. Some
simple replacement pairs are supported.
Requires |g:matchup_surround_enabled| = 1.
------------------------------------------------------------------------------
Customizing mappings~
*matchup-custom-mappings*
|match-up| provides a number of default mappings. Each right-hand side is
provided as a <plug>-mapping (see |using-<plug>|). For any given map, the
default mapping will only be created if it does not already exist. This means
that if a user defines a custom mapping, e.g., with >
nmap <leader>% <plug>(matchup-z%)
<
the corresponding default left-hand side will not be mapped.
-------------------------------------------------------------------------~
LHS RHS Mode Module
-------------------------------------------------------------------------~
% |<plug>(matchup-%)| nx motion
g% |<plug>(matchup-g%)| nx motion
[% |<plug>(matchup-[%)| nx motion
]% |<plug>(matchup-]%)| nx motion
z% |<plug>(matchup-z%)| nx motion
a% |<plug>(matchup-a%)| x text_obj
i% |<plug>(matchup-i%)| x text_obj
ds% |<plug>(matchup-ds%)| n surround
cs% |<plug>(matchup-cs%)| n surround
(none) |<plug>(matchup-hi-surround)| n matchparen
-------------------------------------------------------------------------~
Operator pending maps~
-------------------------------------------------------------------------~
% |<plug>(matchup-%)| o motion
... And so on for g%, [%, ]%, z%, a%, i% ...
Key: (n) normal, (x) visual, (o) operator-pending (|omap-info|).
Note: Prior to vim 8.1.0648, in order to support motion forcing (see |o_v|, |o_V|,
|o_CTRL-V|) for each operator-pending map, match-up made four maps corresponding
to each motion type:
-------------------------------------------------------------------------~
Obsolete operator pending maps~
-------------------------------------------------------------------------~
% |<plug>(matchup-o_)||<plug>(matchup-%)| o motion
v% |<plug>(matchup-o_v)||<plug>(matchup-%)| o motion
V% |<plug>(matchup-o_V)||<plug>(matchup-%)| o motion
<c-v>% |<plug>(matchup-o_<c-v>)||<plug>(matchup-%)| o motion
... And so on for g%, [%, ]%, z%, a%, i% ...
This meant, for example, `d2v%` would work (meaning delete 2 matches forward,
exclusively), but `dv2%` would not work as you would expect (the behavior is
undefined). After vim version 8.1.0648, this limitation of operator-pending
mapping was lifted and match-up is able to use simplified mappings.
------------------------------------------------------------------------------
Features~
*matchup-features*
What do we mean by open, close, mid? This depends on the specific file type
and is configured through the variable |b:match_words|. Here are a couple
of examples: >
if l:x == 1
call one()
elseif l:x == 2
call two()
else
call three()
endif
<
*any-block* *open-to-close-block*
For the vim-script language, match-up understands the words `if`, `else`, `elseif`,
`endif` and that they form a sequential construct. The "open" word is `if`, the
"close" word is `endif`, and the "mid" words are `else` and `elseif`. The `if`/`endif`
pair is called an "open-to-close" block and the `if`/`else`, `else`/`elsif`, and
`elseif`/`endif` are called "any" blocks.
C, C++: >
#if 0
#else
#endif
void some_func() {
if (true) {
one();
} else if (false && false) {
two();
} else {
three();
}
}
<
Since in C and C++, blocks are delimited using braces (`{` & `}`), match-up will
recognize `{` as the open word and `}` as the close word. It will ignore the if
and else if because they are not defined in vim's C file type plugin.
On the other hand, match-up will recognize the `#if`, `#else`, `#endif` preprocessor
directives.
See |matchup-feat-exclusive| and |matchup-feat-linewise| for some examples and
important special cases.
Highlighting matches~
To disable match highlighting at |startup|, use >
let g:matchup_matchparen_enabled = 0
>
in your vimrc. See |matchup-opts-matchparen| for more information and related
options.
You can enable highlighting on the fly using >
:DoMatchParen
<
Likewise, you can disable highlighting at any time using >
:NoMatchParen
<
After start-up, is better to use `:NoMatchParen` and `:DoMatchParen` to toggle
highlighting globally than setting the global variable since these commands
make sure not to leave stale matches around.
Display matches off screen~
If an open or close match which would have been highlighted is on a line
positioned outside of the current window, the match is shown in the status
line (the default). If both the open and close match are off-screen, the
close match is preferred.
See |g:matchup_matchparen_offscreen| for configuration.
*<plug>(matchup-hi-surround)*
Highlight surrounding~
To highlight the surrounding delimiters until the cursor moves, use a map such
as the following >
nmap <silent> <F7> <plug>(matchup-hi-surround)
<
There is no default map for this feature.
Parallel transmutation~
In insert mode, after changing text inside a word, matching words will be
changed in parallel. As an example, >
<pre>
text
</pre>
<
Changing `pre` to `div` and leaving insert mode will produce: >
<div>
text
</div>
<
Note: this currently only works for match words which define a backref
relation like `\1`. A wider set of transmutations are planned.
Parallel transmutation requires the matchparen module to be enabled.
*matchup-feat-exclusive*
Inclusive and exclusive motions~
In vim, character motions following operators (such as `d` for delete and `c` for
change) are either |inclusive| or |exclusive|. This means they either include
the ending position or not. Here, "ending position" means the line and column
closest to the end of the buffer of the region swept over by the motion.
match-up is designed so that `d]%` inside a set of parenthesis behaves exactly
like `d])`, except generalized to words.
Put differently, forward exclusive motions will not include the close word.
In this example, where `█` is the cursor position, >
if █x | continue | endif
<
pressing `d]%` will produce (cursor on the `e`) >
if endif
<
To include the close word, use either `dv]%` or `vd]%`. This is also
compatible with vim's `dv])` and `dv]}`.
Operators over backward exclusive motions will instead exclude the position
the cursor was on before the operator was invoked. For example, in >
if █x | continue | endif
<
pressing `d[%` will produce >
█x | continue | endif
<
This is compatible with vim's `d[(` and `d[{`.
*d%* *dg%*
Unlike `]%`, `%` is an |inclusive| motion. As a special case for the `d` (delete)
operator, if `d%` leaves behind lines white-space, they will be deleted also.
In effect, it will be operating line-wise. As an example, pressing `d%` will
leave behind nothing. >
█(
)
<
To operate character-wise in this situation, use `dv%` or `vd%`. This is vim
compatible with the built-in `d%` on items in 'matchpairs'.
*matchup-feat-linewise*
Line-wise operator/text-object combinations~
Normally, the text objects |i%| and |a%| work character-wise. However,
there are some special cases. For certain operators combined with |i%|,
under certain conditions, match-up will effectively operate line-wise
instead. For example, in >
if condition
█call one()
call two()
endif
<
pressing `di%` will produce >
if condition
endif
<
even though deleting ` condition` would be suggested by the object `i%`.
The intention is to make operators more useful in some cases. The
following rules apply:
1. The operator must be listed in |g:matchup_text_obj_linewise_operators|.
By default this is |d| and |y| (e.g., `di%` and `ya%`).
2. The outer block must span multiple lines.
3. The open and close delimiters must be more than one character long. In
particular, `di%` involving a `(`...`)` block will not be subject to
these special rules.
To prevent this behavior for a particular operation, use `vi%d`. Note that
special cases involving indentation still apply (like with |i)| etc).
To disable this entirely, remove the operator from the following variable, >
let g:matchup_text_obj_linewise_operators = [ 'y' ]
<
Note: unlike vim's built-in |i)|, |ab|, etc., |i%| does not make an existing visual
mode character-wise.
A second special case involves `da%`. In this example, >
if condition
█call one()
call two()
endif
<
pressing `da%` will delete all four lines and leave no white-space. This is
compatible with vim's `da(`, `dab`, etc.
------------------------------------------------------------------------------
Commands~
*matchup-commands*
*:NoMatchParen* *matchup-:NoMatchParen*
:NoMatchParen Disable matching after the plugin was loaded.
*:DoMatchParen* *matchup-:DoMatchParen*
:DoMatchParen Enable matching again.
*:MatchupShowTimes*
:MatchupShowTimes Display performance data, useful for debugging slow
matching. Shows last, average, and maximum times.
*:MatchupClearTimes*
:MatchupClearTimes Reset performance counters to zero.
*:MatchupWhereAmI*
:MatchupWhereAmI? Echos your position in code by finding successive matching
words, like doing `[%` repeatedly. Example:
>
1310 do_pending_operator( … { ⯈ if ((finish_op || VIsual_active) && oap- … {
<
Running this command twice in the same position will give
more verbose output.
:MatchupWhereAmI?? Be more verbose about your position in code by displaying
several lines. Example:
>
1310 do_pending_operator(cmdarg_T *cap, int old_col, int gui_yank) … {
1349 if ((finish_op || VIsual_active) && oap->op_type != OP_NOP) … {
<
*:MatchupReload*
:MatchupReload Reload the plugin, mostly for debugging. Note that
this does not reload 'matchpairs' or `b:match_word`.
------------------------------------------------------------------------------
Options~
*matchup-options*
*g:matchup_enabled*
Set to 0 to disable the plugin entirely.
Default: 1
*g:matchup_mappings_enabled* all mappings
|g:matchup_matchparen_enabled| match highlighting
*g:matchup_mouse_enabled* double click to select matches
*g:matchup_motion_enabled* |matchup-%|, |%|, |[%|, |]%|
*g:matchup_text_obj_enabled* |a%|, |i%|
Set to 0 to disable a particular module or feature.
Defaults: 1
*g:matchup_transmute_enabled*
Set to 1 to enable the experimental transmute feature (|matchup-transmute|).
Default: 0
*g:matchup_delim_stopline*
Configures the number of lines to search in either direction while using
motions and text objects. Does not apply to match highlighting
(see |g:matchup_matchparen_stopline| instead).
Default: 1500
*g:matchup_delim_noskips*
This option controls whether matching is done within strings and comments.
By default, it is set to 0 which means all valid matches are made within
strings and comments. If set to 1, symbols like `()` will still be matched
but words like `for` and `end` will not. If set to 2, nothing will be
matched within strings and comments. >
let g:matchup_delim_noskips = 1
let g:matchup_delim_noskips = 2
<
Default: 0 (matching enabled within strings and comments)
*g:matchup_delim_nomids*
If set to 1, middle words (like `return`) are not matched to start and
end words for higlighting and motions.
let g:matchup_delim_noskips = 0
<
Default: 0
*g:matchup_delim_start_plaintext*
When enabled (the default), the plugin will be loaded for all buffers,
including ones without a file type set. This allows matching to be done in
new buffers and plain text files but adds a small start-up cost to vim.
Default: 1
Variables~
*b:match_words*
*b:match_skip*
*b:match_ignorecase*
match-up understands these variables originally from matchit. These are set
in the respective |ftplugin| files. They may not exist for every file type.
To support a new file type, create a file `after/ftplugin/{filetype}.vim`
which sets them appropriately.
*matchup-opts-matchparen*
Module matchparen~
*g:matchup_matchparen_enabled*
This option will disable match highlighting at |startup|, e.g., use >
let g:matchup_matchparen_enabled = 0
<
in your vimrc.
Note: vim's built-in plugin |pi_paren| plugin is also disabled. The variable
`g:loaded_matchparen` has no effect on match-up.
Default: 1
You can also enable and disable highlighting for specific buffers using the
variable |b:matchup_matchparen_enabled|.
Customizing the highlighting colors~
match-up uses the |MatchParen| highlighting group by default, which can be
configured. For example, >
:hi MatchParen ctermbg=blue guibg=lightblue cterm=italic gui=italic
<
You may want to put this inside a |ColorScheme| |autocmd| so it is preserved
after colorscheme changes: >
augroup matchup_matchparen_highlight
autocmd!
autocmd ColorScheme * hi MatchParen guifg=red
augroup END
<
You can also highlight words differently than parentheses using the
`MatchWord` highlighting group. You might do this if you find the
`MatchParen` style distracting for large blocks. >
:hi MatchWord ctermfg=red guifg=blue cterm=underline gui=underline
<
There are also `MatchParenCur` and `MatchWordCur` which allow you to configure
the highlight separately for the match under the cursor. >
:hi MatchParenCur cterm=underline gui=underline
:hi MatchWordCur cterm=underline gui=underline
<
*b:matchup_matchparen_enabled*
Set to 0 to disable highlighting on a per-buffer basis (there is no command
for this). By default, when disabling highlighting for a particular buffer,
the standard plugin |pi_paren| will still be used for that buffer.
Default: undefined (equivalent to 1)
*b:matchup_matchparen_fallback*
If highlighting is disabled on a particular buffer, match-up will fall back
to the vim standard plugin |pi_paren|, which will highlight 'matchpairs' such
as `()`, `[]`, & `{}`. To disable this, set this option to 0.
Default: undefined (equivalent to 1)
A common usage of these options is to automatically disable matchparen for
particular file types: >
augroup matchup_matchparen_disable_ft
autocmd!
autocmd FileType tex let [b:matchup_matchparen_fallback,
\ b:matchup_matchparen_enabled] = [0, 0]
augroup END
<
*g:matchup_matchparen_singleton*
Whether or not to highlight recognized words even if there is no match.
Default: 0
*g:matchup_matchparen_offscreen*
Dictionary controlling the behavior with off-screen matches. If empty, this
feature is disabled. Else, it should contain the following optional keys:
method~
Sets the method to use to show off-screen matches.
Possible values are:
`'status'` (default): Replace the |status-line| for off-screen matches.
If a match is off of the screen, the line belonging to that match will be
displayed syntax-highlighted in the status line along with the line number
(if line numbers are enabled). If the match is above the screen border,
an additional Δ symbol will be shown to indicate that the matching line is
really above the cursor line.
`'status_manual'`: Compute the status-line but do not display it (future
extension).
`'popup'`: Use a popup window (requires at least vim 8.1.1406) or
a floating window (in neovim) to show the off-screen match.
scrolloff~
When enabled, off-screen matches will not be shown in the statusline while
the cursor is at the screen edge (respects the value of 'scrolloff').
This is intended to prevent flickering while scrolling with j and k.
Default: 0
highlight~
For popup method on vim only: set to a highlight group to override the
colors in the popup window. The default is to use *hl-Pmenu*. Example:
>
highlight! OffscreenPopup guibg=red guifg=blue
let g:matchup_matchparen_offscreen
\ = {'method': 'popup', 'highlight': 'OffscreenPopup'}
<
Default: `{'method': 'status'}`
*g:matchup_matchparen_stopline*
The number of lines to search in either direction while highlighting
matches. Set this conservatively since high values may cause performance
issues.
Default: 400
*g:matchup_matchparen_timeout*
*g:matchup_matchparen_insert_timeout*
Adjust the timeouts in milliseconds for highlighting.
Defaults: `g:matchparen_timeout`, `g:matchparen_insert_timeout`
(300, 60 respectively)
*b:matchup_matchparen_timeout*
*b:matchup_matchparen_insert_timeout*
Buffer local versions of the above.
*g:matchup_matchparen_deferred*
Deferred highlighting improves cursor movement performance (for example, when
using |hjkl|) by delaying highlighting for a short time and waiting to see if
the cursor continues moving.
Default: 0 (disabled)
Note: this feature is only available if your vim version has |timers| and
the function |timer_pause|, version 7.4.2180 and after. For neovim, this
will only work in nvim-0.2.1 and after.
*g:matchup_matchparen_deferred_show_delay*
Delay, in milliseconds, between when the cursor moves and when we start
checking if the cursor is on a match. Applies to both making highlights and
clearing them for deferred highlighting.
Note: these delays cannot be changed dynamically and should be configured
before the plugin loads (e.g., in your vimrc).
Default: 50
*g:matchup_matchparen_deferred_hide_delay*
If the cursor has not stopped moving, assume highlight is stale after this
many milliseconds. Stale highlights are hidden.
Note: this option cannot be changed dynamically.
Default: 700
*g:matchup_matchparen_deferred_fade_time* *matchup-fading*
When set to {time} in milliseconds, the deferred highlighting behavior
is changed in two ways:
1. Highlighting of matches is preserved for at least {time} even when
the cursor is moved away.
2. If the cursor stays on the same match for longer than {time},
highlighting is cleared.
The effect is that highlighting occurs momentarily and then disappears,
regardless of where the cursor is. It is possible that fading takes
longer than {time}, if vim is busy doing other things.
This value should be greater than the deferred show delay.
Note: this option cannot be changed dynamically.
Example: >
let g:matchup_matchparen_deferred = 1
let g:matchup_matchparen_deferred_fade_time = 450
<
Default: 0 (fading disabled)
*g:matchup_matchparen_pumvisible*
If set to 1, matches will be made even when the |popupmenu-completion| is
visible. If you use an auto-complete plugin which interacts badly with
matching, set this option to 0.
Default: 1
*g:matchup_matchparen_nomode*
When not empty, match highlighting will be disabled in the specified modes,
where each mode is a single character like in the |mode()| function. E.g., to
disable highlighting in insert mode,
>
let g:matchup_matchparen_nomode = 'i'
<
and in visual modes,
>
let g:matchup_matchparen_nomode = "vV\<c-v>"
<
Note: In visual modes, this takes effect only after moving the cursor.
Default: ''
*g:matchup_matchparen_hi_surround_always*
Always highlight the surrounding words, if possible. This is like
|<plug>(matchup-hi-surround)| but is updated each time the cursor moves.
This requires deferred matching (|g:matchup_matchparen_deferred| = 1).
Default: 0
*g:matchup_matchparen_hi_background*
Highlight buffer background between matches. This uses the `MatchBackground`
highlighting group and is linked to `ColorColumn` by default but can be
configured with >
:hi MatchBackground guibg=grey ctermbg=grey
<
Default: 0
Module motion~
*g:matchup_motion_override_Npercent*
In vim, {count}% goes to the {count} percentage in the file (see |N%|).
match-up overrides this motion for small {count} (by default, anything less
than 7). For example, to allow {count}% for {count} less than 12, >
let g:matchup_motion_override_Npercent = 11
<
To disable this feature, and restore vim's default {count}%, >
let g:matchup_motion_override_Npercent = 0
<
To always enable this feature, use any value greater than 99 >
let g:matchup_motion_override_Npercent = 100
<
Default: 6
*g:matchup_motion_cursor_end*
If enabled, cursor will land on the end of mid and close words while
moving downwards (|%|/|]%|). While moving upwards (|g%|, |[%|) the cursor
will land on the beginning. Set to 0 to disable.
Note: this has no effect on operators: `d%` will delete |inclusive| of the
ending word (this is compatible with matchit).
Default: 1
*g:matchup_delim_count_fail*
When disabled (default), giving an invalid count to the |[%| and |]%| motions
and the text objects |i%| and |a%| will cause the motion or operation to fail.
When enabled, they will move as far as possible.
Note: targeting high counts when this option is enabled can become slow
because many positions need to be tried before giving up.
Default: 0
Module text_obj~
*g:matchup_text_obj_linewise_operators*
Modifies the set of operators which may operate line-wise with |i%|
(see |matchup-feat-linewise|).
You may use 'v', 'V', and "\<c-v>" (i.e., an actual CTRL-V character) to the
specify the corresponding visual mode.
You can also specify custom plugin operators with 'g@' and optionally, an
expression separated by a comma. For example, to make |commentary|'s |gc|
mapping work likewise when used in the operator `gci%`, >
function! IsCommentaryOpFunc()
return &operatorfunc ==? matchstr(maparg('<Plug>Commentary', 'n'),
\ '\c<SNR>\w\+\ze()\|set op\%(erator\)\?func=\zs.\{-\}\ze<cr>')
endfunction
let g:matchup_text_obj_linewise_operators = ['d', 'y',
\ 'g@,IsCommentaryOpFunc()']
<
Default: `['d', 'y']`
Module surround~
*g:matchup_surround_enabled*
Enables the surround module which provides maps |ds%| and |cs%|.
Default: 0
------------------------------------------------------------------------------
File type options~
*matchup-file-types*
*matchup-latex*
LaTeX~
By default, match-up is disabled for tex files when the plugin |vimtex| is
detected. To enable match-up for tex files, use the following in your vimrc: >
let g:matchup_override_vimtex = 1
<
This will replace vimtex's built-in highlighting and `%` map.
Note: matching may be computationally intensive for complex LaTeX documents.
If you experience slowdowns, consider using the following option: >
let g:matchup_matchparen_deferred = 1
<
Match preferences~ *g:matchup_matchpref*
A limited number of common preferences are available which affect how
matching is done for a particular filetype. They may be set through the
`matchup_matchpref` dictionary: >
let g:matchup_matchpref[&filetype].option_name = 1
<
HTML
*g:matchup_matchpref.html.nolists*
When set to 1, this option disables matching and navigation between groups
of list items in HTML documents such as the following >
<ul>
<li>One</li>
<li>Two</li>
</ul>
<
By default, `%` will navigate from `<ul>` to `<li>` to `<li>` to `</ul>`.
Default: 0
*g:matchup_matchpref.html.tagnameonly*
When set to 1, only the tag name will be highlighted, not the rest of the
tag, e.g., the "a" in >
<a href="http://example.com">Link</a>
<
This works for xml, html, and some other html-based types.
Default: 0
Customization~
*g:matchup_hotfix[&filetype]* *matchup-hotfix*
For each file type, this option can be set to the string name of a function
which will be called when loading files, prior to checking |b:match_words|
and |b:match_skip|. This option can be used to quickly customize matching for
particular file types: >
function! VimHotfix()
" customization
endfunction
let g:matchup_hotfix['vim'] = 'VimHotfix'
*b:matchup_hotfix*
This is an alternative buffer-local name for adding customization.
*matchup#util#patch_match_words* *matchup-patch*
>
call matchup#util#patch_match_words(before, after)
<
This function replaces the literal string `before` contained in |b:match_words|
with the literal string `after`. When placed in an autocommand or in the file
`after/ftplugin/{&filetype}.vim`, it can be used to customize the matching
regular expressions for a particular file type.
*matchup#util#append_match_words* *matchup-append*
>
call matchup#util#append_match_words(str)
<
Adds a set of patterns to |b:match_words|, adding a comma if necessary.
==============================================================================
FAQ *matchup-faq*
Q match-up doesn't work
A This plugin requires at least vim 7.4. It should work in vim 7.4.898 but at
least vim 7.4.1689 is better. I recommend using the most recent version of
vim if possible.
If you have issues, please tell me your vim version and error messages. Try
updating vim and see if the problem persists.
Q Why does jumping not work for construct X in language Y?
A Please open a new issue
Q Highlighting is not correct for construct X
A match-up uses matchit's filetype-specific data, which may not give
enough information to create proper highlights. To fix this, you may
need to modify |b:match_words|.
For help, please open a new issue and be a specific as possible.
Q I'm having performance problems
A match-up aims to be as fast as possible, but highlighting matching words can
be intensive and may be slow on less powerful machines. There are a few
things you can try to improve performance:
- Update to a recent version of vim. Newer versions are faster, more
extensively tested, and better supported by match-up.
- Try deferred highlighting, which delays highlighting until the cursor is
stationary to improve cursor movement performance.
|g:matchup_matchparen_deferred|
- Lower the highlighting timeouts. If highlighting takes longer than the
timeout, highlighting will not be attempted again until the cursor moves.
|g:matchup_matchparen_timeout|, |g:matchup_matchparen_insert_timeout|
If are having any other performance issues, please open a new issue and
report the output of `:MatchupShowTimes`.
Q Why is there a weird entry on the status line?
A This is a feature which helps you see matches that are outside of the
vim screen, similar to some IDEs. If you wish to disable it, use >
let g:matchup_matchparen_offscreen = {}
<
Q Matching does not work when lines are too far apart.
A The number of search lines is limited for performance reasons. You may
increase the limits with the following options: >
let g:matchup_delim_stopline = 1500 " generally
let g:matchup_matchparen_stopline = 400 " for match highlighting only
<
Q The maps `1i%` and `1a%` are difficult to press.
A You may use the following maps `I%` and `A%` for convenience: >
function! s:matchup_convenience_maps()
xnoremap <sid>(std-I) I
xnoremap <sid>(std-A) A
xmap <expr> I mode()=='<c-v>'?'<sid>(std-I)':(v:count?'':'1').'i'
xmap <expr> A mode()=='<c-v>'?'<sid>(std-A)':(v:count?'':'1').'a'
for l:v in ['', 'v', 'V', '<c-v>']
execute 'omap <expr>' l:v.'I%' "(v:count?'':'1').'".l:v."i%'"
execute 'omap <expr>' l:v.'A%' "(v:count?'':'1').'".l:v."a%'"
endfor
endfunction