vim: runtime/pack/dist/opt/matchit/doc/matchit.txt annotate

annotate runtime/pack/dist/opt/matchit/doc/matchit.txt @ 18456:6d11fc4aa683

Update runtime files Commit: https://github.com/vim/vim/commit/96f45c0b6fc9e9d404e6805593ed1e0e6795e470 Author: Bram Moolenaar <Bram@vim.org> Date: Sat Oct 26 19:53:45 2019 +0200 Update runtime files

author	Bram Moolenaar <Bram@vim.org>
date	Sat, 26 Oct 2019 20:00:04 +0200
parents	1eaf34420bb3
children	d4deb2e50667

rev	line source
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	1 matchit.txt Extended "%" matching
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	2
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	3 For instructions on installing this file, type
15729 fe57e4f0eac1 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	4 `:help matchit-install`
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	5 inside Vim.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	6
18456 6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	7 For Vim version 8.1. Last change: 2019 Oct 24
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	8
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	9
15729 fe57e4f0eac1 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	10 VIM REFERENCE MANUAL by Benji Fisher et al
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	11
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	12 matchit matchit.vim
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	13
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	14 1. Extended matching with "%" \|matchit-intro\|
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	15 2. Activation \|matchit-activate\|
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	16 3. Configuration \|matchit-configure\|
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	17 4. Supporting a New Language \|matchit-newlang\|
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	18 5. Known Bugs and Limitations \|matchit-bugs\|
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	19
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	20 The functionality mentioned here is a plugin, see \|add-plugin\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	21 This plugin is only available if 'compatible' is not set.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	22
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	23 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	24 1. Extended matching with "%" matchit-intro
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	25
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	26 matchit-%
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	27 % Cycle forward through matching groups, such as "if", "else", "endif",
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	28 as specified by \|b:match_words\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	29
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	30 g% v_g% o_g%
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	31 g% Cycle backwards through matching groups, as specified by
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	32 \|b:match_words\|. For example, go from "if" to "endif" to "else".
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	33
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	34 [% v_[% o_[%
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	35 [% Go to [count] previous unmatched group, as specified by
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	36 \|b:match_words\|. Similar to \|[{\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	37
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	38 ]% v_]% o_]%
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	39 ]% Go to [count] next unmatched group, as specified by
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	40 \|b:match_words\|. Similar to \|]}\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	41
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	42 v_a%
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	43 a% In Visual mode, select the matching group, as specified by
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	44 \|b:match_words\|, containing the cursor. Similar to \|v_a[\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	45 A [count] is ignored, and only the first character of the closing
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	46 pattern is selected.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	47
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	48 In Vim, as in plain vi, the percent key, \|%\|, jumps the cursor from a brace,
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	49 bracket, or paren to its match. This can be configured with the 'matchpairs'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	50 option. The matchit plugin extends this in several ways:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	51
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	52 You can match whole words, such as "if" and "endif", not just
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	53 single characters. You can also specify a \|regular-expression\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	54 You can define groups with more than two words, such as "if",
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	55 "else", "endif". Banging on the "%" key will cycle from the "if" to
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	56 the first "else", the next "else", ..., the closing "endif", and back
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	57 to the opening "if". Nested structures are skipped. Using \|g%\| goes
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	58 in the reverse direction.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	59 By default, words inside comments and strings are ignored, unless
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	60 the cursor is inside a comment or string when you type "%". If the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	61 only thing you want to do is modify the behavior of "%" so that it
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	62 behaves this way, you do not have to define \|b:match_words\|, since the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	63 script uses the 'matchpairs' option as well as this variable.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	64
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	65 See \|matchit-details\| for details on what the script does, and \|b:match_words\|
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	66 for how to specify matching patterns.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	67
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	68 MODES: matchit-modes matchit-v_% matchit-o_%
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	69
15729 fe57e4f0eac1 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	70 Mostly, % and related motions (\|g%\| and \|[%\| and \|]%\|) should just work like built-in
fe57e4f0eac1 Update runtime files. Bram Moolenaar <Bram@vim.org> parents: 15334 diff changeset	71 \|motion\| commands in \|Operator-pending\| and \|Visual\| modes (as of 8.1.648)
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	72
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	73 LANGUAGES: matchit-languages
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	74
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	75 Currently, the following languages are supported: Ada, ASP with VBS, Csh,
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	76 DTD, Entity, Essbase, Fortran, HTML, JSP (same as HTML), LaTeX, Lua, Pascal,
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	77 SGML, Shell, Tcsh, Vim, XML. Other languages may already have support via
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	78 the default \|filetype-plugin\|s in the standard vim distribution.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	79
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	80 To support a new language, see \|matchit-newlang\| below.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	81
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	82 DETAILS: matchit-details matchit-parse
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	83
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	84 Here is an outline of what matchit.vim does each time you hit the "%" key. If
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	85 there are \|backref\|s in \|b:match_words\| then the first step is to produce a
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	86 version in which these back references have been eliminated; if there are no
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	87 \|backref\|s then this step is skipped. This step is called parsing. For
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	88 example, "$foo\\|bar$:end\1" is parsed to yield
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	89 "$foo\\|bar$:end$foo\\|bar$". This can get tricky, especially if there are
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	90 nested groups. If debugging is turned on, the parsed version is saved as
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	91 \|b:match_pat\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	92
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	93 matchit-choose
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	94 Next, the script looks for a word on the current line that matches the pattern
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	95 just constructed. It includes the patterns from the 'matchpairs' option.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	96 The goal is to do what you expect, which turns out to be a little complicated.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	97 The script follows these rules:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	98
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	99 Insist on a match that ends on or after the cursor.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	100 Prefer a match that includes the cursor position (that is, one that
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	101 starts on or before the cursor).
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	102 Prefer a match that starts as close to the cursor as possible.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	103 If more than one pattern in \|b:match_words\| matches, choose the one
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	104 that is listed first.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	105
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	106 Examples:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	107
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	108 Suppose you >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	109 :let b:match_words = '<:>,<tag>:</tag>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	110 < and hit "%" with the cursor on or before the "<" in "a <tag> is born".
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	111 The pattern '<' comes first, so it is preferred over '<tag>', which
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	112 also matches. If the cursor is on the "t", however, then '<tag>' is
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	113 preferred, because this matches a bit of text containing the cursor.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	114 If the two groups of patterns were reversed then '<' would never be
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	115 preferred.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	116
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	117 Suppose you >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	118 :let b:match_words = 'if:end if'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	119 < (Note the space!) and hit "%" with the cursor at the end of "end if".
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	120 Then "if" matches, which is probably not what you want, but if the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	121 cursor starts on the "end " then "end if" is chosen. (You can avoid
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	122 this problem by using a more complicated pattern.)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	123
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	124 If there is no match, the cursor does not move. (Before version 1.13 of the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	125 script, it would fall back on the usual behavior of \|%\|). If debugging is
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	126 turned on, the matched bit of text is saved as \|b:match_match\| and the cursor
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	127 column of the start of the match is saved as \|b:match_col\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	128
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	129 Next, the script looks through \|b:match_words\| (original and parsed versions)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	130 for the group and pattern that match. If debugging is turned on, the group is
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	131 saved as \|b:match_ini\| (the first pattern) and \|b:match_tail\| (the rest). If
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	132 there are \|backref\|s then, in addition, the matching pattern is saved as
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	133 \|b:match_word\| and a table of translations is saved as \|b:match_table\|. If
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	134 there are \|backref\|s, these are determined from the matching pattern and
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	135 \|b:match_match\| and substituted into each pattern in the matching group.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	136
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	137 The script decides whether to search forwards or backwards and chooses
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	138 arguments for the \|searchpair()\| function. Then, the cursor is moved to the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	139 start of the match, and \|searchpair()\| is called. By default, matching
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	140 structures inside strings and comments are ignored. This can be changed by
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	141 setting \|b:match_skip\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	142
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	143 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	144 2. Activation matchit-activate
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	145
8795 aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354 Christian Brabandt <cb@256bit.org> parents: 8720 diff changeset	146 To use the matchit plugin add this line to your \|vimrc\|: >
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354 Christian Brabandt <cb@256bit.org> parents: 8720 diff changeset	147 packadd! matchit
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354 Christian Brabandt <cb@256bit.org> parents: 8720 diff changeset	148
aba2d0a01290 commit https://github.com/vim/vim/commit/7db8f6f4f85e5d0526d23107b2a5e2334dc23354 Christian Brabandt <cb@256bit.org> parents: 8720 diff changeset	149 The script should start working the next time you start Vim.
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	150
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	151 (Earlier versions of the script did nothing unless a \|buffer-variable\| named
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	152 \|b:match_words\| was defined. Even earlier versions contained autocommands
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	153 that set this variable for various file types. Now, \|b:match_words\| is
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	154 defined in many of the default \|filetype-plugin\|s instead.)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	155
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	156 For a new language, you can add autocommands to the script or to your vimrc
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	157 file, but the recommended method is to add a line such as >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	158 let b:match_words = '\<foo\>:\<bar\>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	159 to the \|filetype-plugin\| for your language. See \|b:match_words\| below for how
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	160 this variable is interpreted.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	161
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	162 TROUBLESHOOTING matchit-troubleshoot
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	163
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	164 The script should work in most installations of Vim. It may not work if Vim
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	165 was compiled with a minimal feature set, for example if the \|+syntax\| option
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	166 was not enabled. If your Vim has support for syntax compiled in, but you do
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	167 not have \|syntax\| highlighting turned on, matchit.vim should work, but it may
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	168 fail to skip matching groups in comments and strings. If the \|filetype\|
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	169 mechanism is turned off, the \|b:match_words\| variable will probably not be
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	170 defined automatically.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	171
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	172 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	173 3. Configuration matchit-configure
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	174
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	175 There are several variables that govern the behavior of matchit.vim. Note
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	176 that these are variables local to the buffer, not options, so use \|:let\| to
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	177 define them, not \|:set\|. Some of these variables have values that matter; for
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	178 others, it only matters whether the variable has been defined. All of these
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	179 can be defined in the \|filetype-plugin\| or autocommand that defines
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	180 \|b:match_words\| or "on the fly."
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	181
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	182 The main variable is \|b:match_words\|. It is described in the section below on
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	183 supporting a new language.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	184
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	185 MatchError matchit-hl matchit-highlight
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	186 MatchError is the highlight group for error messages from the script. By
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	187 default, it is linked to WarningMsg. If you do not want to be bothered by
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	188 error messages, you can define this to be something invisible. For example,
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	189 if you use the GUI version of Vim and your command line is normally white, you
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	190 can do >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	191 :hi MatchError guifg=white guibg=white
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	192 <
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	193 b:match_ignorecase
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	194 If you >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	195 :let b:match_ignorecase = 1
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	196 then matchit.vim acts as if 'ignorecase' is set: for example, "end" and "END"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	197 are equivalent. If you >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	198 :let b:match_ignorecase = 0
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	199 then matchit.vim treats "end" and "END" differently. (There will be no
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	200 b:match_infercase option unless someone requests it.)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	201
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	202 b:match_debug
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	203 Define b:match_debug if you want debugging information to be saved. See
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	204 \|matchit-debug\|, below.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	205
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	206 b:match_skip
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	207 If b:match_skip is defined, it is passed as the skip argument to
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	208 \|searchpair()\|. This controls when matching structures are skipped, or
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	209 ignored. By default, they are ignored inside comments and strings, as
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	210 determined by the \|syntax\| mechanism. (If syntax highlighting is turned off,
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	211 nothing is skipped.) You can set b:match_skip to a string, which evaluates to
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	212 a non-zero, numerical value if the match is to be skipped or zero if the match
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	213 should not be skipped. In addition, the following special values are
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	214 supported by matchit.vim:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	215 s:foo becomes (current syntax item) =~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	216 S:foo becomes (current syntax item) !~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	217 r:foo becomes (line before cursor) =~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	218 R:foo becomes (line before cursor) !~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	219 (The "s" is meant to suggest "syntax", and the "r" is meant to suggest
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	220 "regular expression".)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	221
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	222 Examples:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	223
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	224 You can get the default behavior with >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	225 :let b:match_skip = 's:comment\\|string'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	226 <
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	227 If you want to skip matching structures unless they are at the start
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	228 of the line (ignoring whitespace) then you can >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	229 :let b:match_skip = 'R:^\s*'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	230 < Do not do this if strings or comments can span several lines, since
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	231 the normal syntax checking will not be done if you set b:match_skip.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	232
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	233 In LaTeX, since "%" is used as the comment character, you can >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	234 :let b:match_skip = 'r:%'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	235 < Unfortunately, this will skip anything after "\%", an escaped "%". To
11442 d183d629509e Update runtime files. Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	236 allow for this, and also "\\%" (an escaped backslash followed by the
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	237 comment character) you can >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	238 :let b:match_skip = 'r:$^\\|[^\\]$$\\\\$*%'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	239 <
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	240 See the $VIMRUNTIME/ftplugin/vim.vim for an example that uses both
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	241 syntax and a regular expression.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	242
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	243 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	244 4. Supporting a New Language matchit-newlang
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	245 b:match_words
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	246 In order for matchit.vim to support a new language, you must define a suitable
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	247 pattern for \|b:match_words\|. You may also want to set some of the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	248 \|matchit-configure\| variables, as described above. If your language has a
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	249 complicated syntax, or many keywords, you will need to know something about
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	250 Vim's \|regular-expression\|s.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	251
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	252 The format for \|b:match_words\| is similar to that of the 'matchpairs' option:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	253 it is a comma (,)-separated list of groups; each group is a colon(:)-separated
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	254 list of patterns (regular expressions). Commas and backslashes that are part
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	255 of a pattern should be escaped with backslashes ('\:' and '\,'). It is OK to
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	256 have only one group; the effect is undefined if a group has only one pattern.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	257 A simple example is >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	258 :let b:match_words = '\<if\>:\<endif\>,'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	259 \ . '\<while\>:\<continue\>:\<break\>:\<endwhile\>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	260 (In Vim regular expressions, \|\<\| and \|\>\| denote word boundaries. Thus "if"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	261 matches the end of "endif" but "\<if\>" does not.) Then banging on the "%"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	262 key will bounce the cursor between "if" and the matching "endif"; and from
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	263 "while" to any matching "continue" or "break", then to the matching "endwhile"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	264 and back to the "while". It is almost always easier to use \|literal-string\|s
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	265 (single quotes) as above: '\<if\>' rather than "\\<if\\>" and so on.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	266
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	267 Exception: If the ":" character does not appear in b:match_words, then it is
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	268 treated as an expression to be evaluated. For example, >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	269 :let b:match_words = 'GetMatchWords()'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	270 allows you to define a function. This can return a different string depending
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	271 on the current syntax, for example.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	272
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	273 Once you have defined the appropriate value of \|b:match_words\|, you will
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	274 probably want to have this set automatically each time you edit the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	275 appropriate file type. The recommended way to do this is by adding the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	276 definition to a \|filetype-plugin\| file.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	277
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	278 Tips: Be careful that your initial pattern does not match your final pattern.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	279 See the example above for the use of word-boundary expressions. It is usually
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	280 better to use ".\{-}" (as many as necessary) instead of ".*" (as many as
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	281 possible). See \|\{-\|. For example, in the string "<tag>label</tag>", "<.*>"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	282 matches the whole string whereas "<.\{-}>" and "<[^>]*>" match "<tag>" and
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	283 "</tag>".
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	284
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	285 matchit-spaces matchit-s:notend
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	286 If "if" is to be paired with "end if" (Note the space!) then word boundaries
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	287 are not enough. Instead, define a regular expression s:notend that will match
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	288 anything but "end" and use it as follows: >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	289 :let s:notend = '\%(\<end\s\+\)\@<!'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	290 :let b:match_words = s:notend . '\<if\>:\<end\s\+if\>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	291 < matchit-s:sol
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	292 This is a simplified version of what is done for Ada. The s:notend is a
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	293 \|script-variable\|. Similarly, you may want to define a start-of-line regular
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	294 expression >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	295 :let s:sol = '\%(^\\|;\)\s*'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	296 if keywords are only recognized after the start of a line or after a
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	297 semicolon (;), with optional white space.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	298
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	299 matchit-backref matchit-\1
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	300 In any group, the expressions \|\1\|, \|\2\|, ..., \|\9\| refer to parts of the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	301 INITIAL pattern enclosed in \|$\|escaped parentheses\|$\|. These are referred
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	302 to as back references, or backrefs. For example, >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	303 :let b:match_words = '\<b$o\+$\>:$h$\1\>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	304 means that "bo" pairs with "ho" and "boo" pairs with "hoo" and so on. Note
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	305 that "\1" does not refer to the "$h$" in this example. If you have
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	306 "$nested \(parentheses$\) then "\d" refers to the d-th "\(" and everything
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	307 up to and including the matching "\)": in "$nested\(parentheses$\)", "\1"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	308 refers to everything and "\2" refers to "$parentheses$". If you use a
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	309 variable such as \|s:notend\| or \|s:sol\| in the previous paragraph then remember
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	310 to count any "\(" patterns in this variable. You do not have to count groups
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	311 defined by \|\%(\)\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	312
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	313 It should be possible to resolve back references from any pattern in the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	314 group. For example, >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	315 :let b:match_words = '$foo$$bar$:more\1:and\2:end\1\2'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	316 would not work because "\2" cannot be determined from "morefoo" and "\1"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	317 cannot be determined from "andbar". On the other hand, >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	318 :let b:match_words = '$\(foo$$bar$\):\3\2:end\1'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	319 should work (and have the same effect as "foobar:barfoo:endfoobar"), although
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	320 this has not been thoroughly tested.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	321
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	322 You can use \|zero-width\| patterns such as \|\@<=\| and \|\zs\|. (The latter has
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	323 not been thouroughly tested in matchit.vim.) For example, if the keyword "if"
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	324 must occur at the start of the line, with optional white space, you might use
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	325 the pattern "$^\s*$\@<=if" so that the cursor will end on the "i" instead of
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	326 at the start of the line. For another example, if HTML had only one tag then
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	327 one could >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	328 :let b:match_words = '<:>,<\@<=tag>:<\@<=/tag>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	329 so that "%" can bounce between matching "<" and ">" pairs or (starting on
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	330 "tag" or "/tag") between matching tags. Without the \|\@<=\|, the script would
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	331 bounce from "tag" to the "<" in "</tag>", and another "%" would not take you
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	332 back to where you started.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	333
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	334 DEBUGGING matchit-debug :MatchDebug
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	335
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	336 If you are having trouble figuring out the appropriate definition of
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	337 \|b:match_words\| then you can take advantage of the same information I use when
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	338 debugging the script. This is especially true if you are not sure whether
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	339 your patterns or my script are at fault! To make this more convenient, I have
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	340 made the command :MatchDebug, which defines the variable \|b:match_debug\| and
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	341 creates a Matchit menu. This menu makes it convenient to check the values of
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	342 the variables described below. You will probably also want to read
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	343 \|matchit-details\| above.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	344
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	345 Defining the variable \|b:match_debug\| causes the script to set the following
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	346 variables, each time you hit the "%" key. Several of these are only defined
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	347 if \|b:match_words\| includes \|backref\|s.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	348
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	349 b:match_pat
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	350 The b:match_pat variable is set to \|b:match_words\| with \|backref\|s parsed.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	351 b:match_match
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	352 The b:match_match variable is set to the bit of text that is recognized as a
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	353 match.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	354 b:match_col
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	355 The b:match_col variable is set to the cursor column of the start of the
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	356 matching text.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	357 b:match_wholeBR
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	358 The b:match_wholeBR variable is set to the comma-separated group of patterns
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	359 that matches, with \|backref\|s unparsed.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	360 b:match_iniBR
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	361 The b:match_iniBR variable is set to the first pattern in \|b:match_wholeBR\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	362 b:match_ini
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	363 The b:match_ini variable is set to the first pattern in \|b:match_wholeBR\|,
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	364 with \|backref\|s resolved from \|b:match_match\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	365 b:match_tail
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	366 The b:match_tail variable is set to the remaining patterns in
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	367 \|b:match_wholeBR\|, with \|backref\|s resolved from \|b:match_match\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	368 b:match_word
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	369 The b:match_word variable is set to the pattern from \|b:match_wholeBR\| that
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	370 matches \|b:match_match\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	371 b:match_table
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	372 The back reference '\'.d refers to the same thing as '\'.b:match_table[d] in
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	373 \|b:match_word\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	374
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	375 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	376 5. Known Bugs and Limitations matchit-bugs
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	377
18456 6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	378 Repository: https://github.com/chrisbra/matchit/
6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	379 Bugs can be reported at the repository (alternatively you can send me a mail).
6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	380 The latest development snapshot can also be downloaded there.
6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	381
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	382 Just because I know about a bug does not mean that it is on my todo list. I
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	383 try to respond to reports of bugs that cause real problems. If it does not
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	384 cause serious problems, or if there is a work-around, a bug may sit there for
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	385 a while. Moral: if a bug (known or not) bothers you, let me know.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	386
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	387 It would be nice if "\0" were recognized as the entire pattern. That is, it
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	388 would be nice if "foo:\end\0" had the same effect as "$foo$:\end\1". I may
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	389 try to implement this in a future version. (This is not so easy to arrange as
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	390 you might think!)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	391
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	392 ==============================================================================
18456 6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	393 vim:tw=78:ts=8:fo=tcq2:ft=help:

Mercurial > vim

annotate runtime/pack/dist/opt/matchit/doc/matchit.txt @ 18456:6d11fc4aa683