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

annotate runtime/pack/dist/opt/matchit/doc/matchit.txt @ 29659:2198955f9e27

Update runtime files Commit: https://github.com/vim/vim/commit/48c3f4e0bff7efd289a7001b68c777b6f89a7057 Author: Bram Moolenaar <Bram@vim.org> Date: Mon Aug 8 15:42:38 2022 +0100 Update runtime files

author	Bram Moolenaar <Bram@vim.org>
date	Mon, 08 Aug 2022 16:45:05 +0200
parents	f0d7cb510ce3
children	ea044451c98f

rev	line source
26148 624439a39432 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 25402 diff changeset	1 matchit.txt Extended "%" matching
8720 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
26708 f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	7 For Vim version 8.2. Last change: 2021 Dec 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
26708 f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	151 To use the matching plugin after startup, you can use this command (note the
f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	152 omitted '!'): >
f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	153 packadd matchit
f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	154
f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	155 To use the matchit plugin after Vim has started, execute this command: >
f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	156 packadd matchit
f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	157
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	158 (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	159 \|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	160 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	161 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	162
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	163 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	164 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	165 let b:match_words = '\<foo\>:\<bar\>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	166 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	167 this variable is interpreted.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	168
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	169 TROUBLESHOOTING matchit-troubleshoot
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	170
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	171 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	172 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	173 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	174 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	175 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	176 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	177 defined automatically.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	178
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	179 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	180 3. Configuration matchit-configure
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 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	183 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	184 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	185 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	186 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	187 \|b:match_words\| or "on the fly."
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	188
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	189 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	190 supporting a new language.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	191
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	192 MatchError matchit-hl matchit-highlight
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	193 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	194 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	195 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	196 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	197 can do >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	198 :hi MatchError guifg=white guibg=white
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	199 <
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	200 b:match_ignorecase
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	201 If you >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	202 :let b:match_ignorecase = 1
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	203 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	204 are equivalent. If you >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	205 :let b:match_ignorecase = 0
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	206 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	207 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	208
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	209 b:match_debug
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	210 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	211 \|matchit-debug\|, below.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	212
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	213 b:match_skip
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	214 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	215 \|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	216 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	217 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	218 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	219 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	220 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	221 supported by matchit.vim:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	222 s:foo becomes (current syntax item) =~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	223 S:foo becomes (current syntax item) !~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	224 r:foo becomes (line before cursor) =~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	225 R:foo becomes (line before cursor) !~ foo
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	226 (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	227 "regular expression".)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	228
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	229 Examples:
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	230
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	231 You can get the default behavior with >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	232 :let b:match_skip = 's:comment\\|string'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	233 <
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	234 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	235 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	236 :let b:match_skip = 'R:^\s*'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	237 < 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	238 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	239
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	240 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	241 :let b:match_skip = 'r:%'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	242 < Unfortunately, this will skip anything after "\%", an escaped "%". To
11442 d183d629509e Update runtime files. Christian Brabandt <cb@256bit.org> parents: 8795 diff changeset	243 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	244 comment character) you can >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	245 :let b:match_skip = 'r:\(^\\|[^\\]\)\(\\\\\)*%'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	246 <
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	247 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	248 4. Supporting a New Language matchit-newlang
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	249 b:match_words
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	250 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	251 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	252 \|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	253 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	254 Vim's \|regular-expression\|s.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	255
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	256 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	257 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	258 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	259 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	260 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	261 A simple example is >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	262 :let b:match_words = '\<if\>:\<endif\>,'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	263 \ . '\<while\>:\<continue\>:\<break\>:\<endwhile\>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	264 (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	265 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	266 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	267 "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	268 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	269 (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	270
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	271 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	272 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	273 :let b:match_words = 'GetMatchWords()'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	274 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	275 on the current syntax, for example.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	276
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	277 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	278 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	279 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	280 definition to a \|filetype-plugin\| file.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	281
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	282 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	283 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	284 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	285 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	286 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	287 "</tag>".
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	288
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	289 matchit-spaces matchit-s:notend
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	290 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	291 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	292 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	293 :let s:notend = '\%(\<end\s\+\)\@<!'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	294 :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	295 < matchit-s:sol
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	296 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	297 \|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	298 expression >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	299 :let s:sol = '\%(^\\|;\)\s*'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	300 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	301 semicolon (;), with optional white space.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	302
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	303 matchit-backref matchit-\1
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	304 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	305 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	306 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	307 :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	308 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	309 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	310 "\(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	311 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	312 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	313 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	314 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	315 defined by \|\%(\)\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	316
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	317 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	318 group. For example, >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	319 :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	320 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	321 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	322 :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	323 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	324 this has not been thoroughly tested.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	325
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	326 You can use \|zero-width\| patterns such as \|\@<=\| and \|\zs\|. (The latter has
25402 bdda48f01a68 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 19574 diff changeset	327 not been thoroughly tested in matchit.vim.) For example, if the keyword "if"
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	328 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	329 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	330 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	331 one could >
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	332 :let b:match_words = '<:>,<\@<=tag>:<\@<=/tag>'
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	333 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	334 "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	335 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	336 back to where you started.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	337
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	338 DEBUGGING matchit-debug :MatchDebug
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	339
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	340 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	341 \|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	342 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	343 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	344 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	345 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	346 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	347 \|matchit-details\| above.
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 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	350 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	351 if \|b:match_words\| includes \|backref\|s.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	352
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	353 b:match_pat
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	354 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	355 b:match_match
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	356 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	357 match.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	358 b:match_col
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	359 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	360 matching text.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	361 b:match_wholeBR
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	362 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	363 that matches, with \|backref\|s unparsed.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	364 b:match_iniBR
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	365 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	366 b:match_ini
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	367 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	368 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	369 b:match_tail
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	370 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	371 \|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	372 b:match_word
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	373 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	374 matches \|b:match_match\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	375 b:match_table
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	376 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	377 \|b:match_word\|.
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	378
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	379 ==============================================================================
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	380 5. Known Bugs and Limitations matchit-bugs
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	381
18456 6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	382 Repository: https://github.com/chrisbra/matchit/
26708 f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	383 Bugs can be reported at the repository and the latest development snapshot can
f0d7cb510ce3 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 26148 diff changeset	384 also be downloaded there.
18456 6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	385
8720 9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	386 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	387 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	388 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	389 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	390
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	391 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	392 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	393 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	394 you might think!)
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	395
9380c37723f8 commit https://github.com/vim/vim/commit/aedfcbe1e6c7df6edcd6756d7601bfdec7dd2087 Christian Brabandt <cb@256bit.org> parents: diff changeset	396 ==============================================================================
18456 6d11fc4aa683 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 16610 diff changeset	397 vim:tw=78:ts=8:fo=tcq2:ft=help:

Mercurial > vim

annotate runtime/pack/dist/opt/matchit/doc/matchit.txt @ 29659:2198955f9e27