*matchit.txt* Extended |%| matching
For instructions on installing this file, type
`:help matchit-install`
inside Vim.
For Vim version 9.1. Last change: 2024 May 20
VIM REFERENCE MANUAL by Benji Fisher et al
*matchit* *matchit.vim*
1. Extended matching with "%" |matchit-intro|
2. Activation |matchit-activate|
3. Configuration |matchit-configure|
4. Supporting a New Language |matchit-newlang|
5. Known Bugs and Limitations |matchit-bugs|
The functionality mentioned here is a plugin, see |add-plugin|.
You can avoid loading this plugin by setting the "loaded_matchit" variable
in your |vimrc| file: >
:let loaded_matchit = 1
==============================================================================
1. Extended matching with "%" *matchit-intro*
*matchit-%*
% Cycle forward through matching groups, such as "if", "else", "endif",
as specified by |b:match_words|.
*g%* *v_g%* *o_g%*
g% Cycle backwards through matching groups, as specified by
|b:match_words|. For example, go from "if" to "endif" to "else".
*[%* *v_[%* *o_[%*
[% Go to [count] previous unmatched group, as specified by
|b:match_words|. Similar to |[{|.
*]%* *v_]%* *o_]%*
]% Go to [count] next unmatched group, as specified by
|b:match_words|. Similar to |]}|.
*v_a%*
a% In Visual mode, select the matching group, as specified by
|b:match_words|, containing the cursor. Similar to |v_a[|.
A [count] is ignored, and only the first character of the closing
pattern is selected.
In Vim, as in plain vi, the percent key, |%|, jumps the cursor from a brace,
bracket, or paren to its match. This can be configured with the 'matchpairs'
option. The matchit plugin extends this in several ways:
You can match whole words, such as "if" and "endif", not just
single characters. You can also specify a |regular-expression|.
You can define groups with more than two words, such as "if",
"else", "endif". Banging on the "%" key will cycle from the "if" to
the first "else", the next "else", ..., the closing "endif", and back
to the opening "if". Nested structures are skipped. Using |g%| goes
in the reverse direction.
By default, words inside comments and strings are ignored, unless
the cursor is inside a comment or string when you type "%". If the
only thing you want to do is modify the behavior of "%" so that it
behaves this way, you do not have to define |b:match_words|, since the
script uses the 'matchpairs' option as well as this variable.
See |matchit-details| for details on what the script does, and |b:match_words|
for how to specify matching patterns.
MODES: *matchit-modes* *matchit-v_%* *matchit-o_%*
Mostly, % and related motions (|g%| and |[%| and |]%|) should just work like built-in
|motion| commands in |Operator-pending| and |Visual| modes (as of 8.1.648)
LANGUAGES: *matchit-languages*
Currently, the following languages are supported: Ada, ASP with VBS, Csh,
DTD, Entity, Essbase, Fortran, HTML, JSP (same as HTML), LaTeX, Lua, Pascal,
SGML, Shell, Tcsh, Vim, XML. Other languages may already have support via
the default |filetype-plugin|s in the standard vim distribution.
To support a new language, see |matchit-newlang| below.
DETAILS: *matchit-details* *matchit-parse*
Here is an outline of what matchit.vim does each time you hit the "%" key. If
there are |backref|s in |b:match_words| then the first step is to produce a
version in which these back references have been eliminated; if there are no
|backref|s then this step is skipped. This step is called parsing. For
example, "\(foo\|bar\):end\1" is parsed to yield
"\(foo\|bar\):end\(foo\|bar\)". This can get tricky, especially if there are
nested groups. If debugging is turned on, the parsed version is saved as
|b:match_pat|.
*matchit-choose*
Next, the script looks for a word on the current line that matches the pattern
just constructed. It includes the patterns from the 'matchpairs' option.