Gaze/SpaceVim
1
0
Fork 0
mirror of https://github.com/SpaceVim/SpaceVim.git synced 2025-01-24 06:10:05 +08:00
Code Issues Projects Releases Wiki Activity
ff1f770ca9
SpaceVim/bundle/vim-matchup/doc/matchup.txt
Wang Shidong aebee1b28b
Add bundle dir (#3542)
2020-06-13 14:06:35 +08:00

1081 lines
40 KiB
Plaintext
Raw Blame History

*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) 2020 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 6, 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 open 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-%)| x text_obj
i% |<plug>(matchup-%)| 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_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} up to 11, >
let g:matchup_motion_override_Npercent = 11
<
To disable this feature, and restore vim's default {count}%, >
let g:matchup_motion_override_Npercent = 0
<
*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
call s:matchup_convenience_maps()
<
Note: this is not compatible with the plugin targets.vim.
Q How can I contribute?
A Read the contribution guidelines (CONTRIBUTING.md) and issue template
(ISSUE_TEMPLATE.md). Be as precise and detailed as possible when submitting
issues and pull requests.
==============================================================================
INTEROPERABILITY *matchup-interoperability*
vimtex, for LaTeX documents~
By default, match-up will be disabled automatically for tex files when vimtex
is detected. To enable match-up for tex files, use >
let g:matchup_override_vimtex = 1
<
match-up's matching engine is more advanced than vimtex's and supports middle
delimiters such as `\middle|` and `\else`. The exact set of delimiters recognized
may differ between the two plugins. For example, the mappings `da%` and `dad`
will not always match, particularly if you have customized vimtex's delimiters.
Matchit~
matchit.vim should not be loaded. If it is loaded, it must be loaded after
match-up (in this case, matchit.vim will be disabled). Note that some plugins,
such as vim-sensible, load matchit.vim so these must also be initialized after
match-up.
Matchparen emulation~
match-up loads |matchparen| if it is not already loaded. Ordinarily, match-up
disables matchparen's highlighting and emulates it to highlight the symbol
contained in the 'matchpairs' option (by default `()`, `[]`, and `{}`). If match-up
is disabled per-buffer using |b:matchup_matchparen_enabled|, match-up will use
matchparen instead of its own highlighting. See |b:matchup_matchparen_fallback|
for more information.
Other plugins~
match-up does not currently provide support for auto-completion. The
following plugins may be useful for this:
- |vim-endwise| https://github.com/tpope/vim-endwise
- |auto-pairs| https://github.com/jiangmiao/auto-pairs
- |delimitMate| https://github.com/Raimondi/delimitMate
- |splitjoin.vim| https://github.com/AndrewRadev/splitjoin.vim
There is basic support for deleting and changing surroundings, but you may
prefer to use one of the following:
- |vim-surround| https://github.com/tpope/vim-surround
- |vim-sandwich| https://github.com/machakann/vim-sandwich
==============================================================================
ACKNOWLEDGMENTS *matchup-acknowledgments*
Origins~
|match-up| was originally based on Karl Yngve Lervåg's |vimtex|. The concept
and style of this plugin and its development are heavily influenced by vimtex.
[vimtex]: https://github.com/lervag/vimtex
Other inspirations~
- |matchit|
- |matchparen|
- |MatchTag| https://github.com/gregsexton/MatchTag
- |MatchTagAlways| https://github.com/Valloric/MatchTagAlways
==============================================================================
DEVELOPMENT *matchup-development*
Development is tracked at https://github.com/andymass/vim-matchup.
Reporting problems~
This is a new plugin and there are likely to be some bugs. Thorough
issue reports are encouraged. Please read the issue template first
(ISSUE_TEMPLATE.md). Be as precise and detailed as possible when submitting
issues.
Feature requests are also welcome.
Contributing~
Please read the contribution guidelines (CONTRIBUTING.md) before contributing.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker
Reference in New Issue View Git Blame Copy Permalink