1 *pattern.txt* For Vim version 8.0. Last change: 2017 Mar 29
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Patterns and search commands *pattern-searches*
9 The very basics can be found in section |03.9| of the user manual. A few more
10 explanations are in chapter 27 |usr_27.txt|.
12 1. Search commands |search-commands|
13 2. The definition of a pattern |search-pattern|
15 4. Overview of pattern items |pattern-overview|
16 5. Multi items |pattern-multi-items|
17 6. Ordinary atoms |pattern-atoms|
18 7. Ignoring case in a pattern |/ignorecase|
19 8. Composing characters |patterns-composing|
20 9. Compare with Perl patterns |perl-patterns|
21 10. Highlighting matches |match-highlight|
23 ==============================================================================
24 1. Search commands *search-commands*
27 /{pattern}[/]<CR> Search forward for the [count]'th occurrence of
28 {pattern} |exclusive|.
30 /{pattern}/{offset}<CR> Search forward for the [count]'th occurrence of
31 {pattern} and go |{offset}| lines up or down.
35 /<CR> Search forward for the [count]'th occurrence of the
36 latest used pattern |last-pattern| with latest used
39 //{offset}<CR> Search forward for the [count]'th occurrence of the
40 latest used pattern |last-pattern| with new
41 |{offset}|. If {offset} is empty no offset is used.
44 ?{pattern}[?]<CR> Search backward for the [count]'th previous
45 occurrence of {pattern} |exclusive|.
47 ?{pattern}?{offset}<CR> Search backward for the [count]'th previous
48 occurrence of {pattern} and go |{offset}| lines up or
52 ?<CR> Search backward for the [count]'th occurrence of the
53 latest used pattern |last-pattern| with latest used
56 ??{offset}<CR> Search backward for the [count]'th occurrence of the
57 latest used pattern |last-pattern| with new
58 |{offset}|. If {offset} is empty no offset is used.
61 n Repeat the latest "/" or "?" [count] times.
62 If the cursor doesn't move the search is repeated with
64 |last-pattern| {Vi: no count}
67 N Repeat the latest "/" or "?" [count] times in
68 opposite direction. |last-pattern| {Vi: no count}
71 * Search forward for the [count]'th occurrence of the
72 word nearest to the cursor. The word used for the
73 search is the first of:
74 1. the keyword under the cursor |'iskeyword'|
75 2. the first keyword after the cursor, in the
77 3. the non-blank word under the cursor
78 4. the first non-blank word after the cursor,
80 Only whole keywords are searched for, like with the
81 command "/\<keyword\>". |exclusive| {not in Vi}
82 'ignorecase' is used, 'smartcase' is not.
85 # Same as "*", but search backward. The pound sign
86 (character 163) also works. If the "#" key works as
87 backspace, try using "stty erase <BS>" before starting
88 Vim (<BS> is CTRL-H or a real backspace). {not in Vi}
91 g* Like "*", but don't put "\<" and "\>" around the word.
92 This makes the search also find matches that are not a
93 whole word. {not in Vi}
96 g# Like "#", but don't put "\<" and "\>" around the word.
97 This makes the search also find matches that are not a
98 whole word. {not in Vi}
101 gd Goto local Declaration. When the cursor is on a local
102 variable, this command will jump to its declaration.
103 First Vim searches for the start of the current
104 function, just like "[[". If it is not found the
105 search stops in line 1. If it is found, Vim goes back
106 until a blank line is found. From this position Vim
107 searches for the keyword under the cursor, like with
108 "*", but lines that look like a comment are ignored
109 (see 'comments' option).
110 Note that this is not guaranteed to work, Vim does not
111 really check the syntax, it only searches for a match
112 with the keyword. If included files also need to be
113 searched use the commands listed in |include-search|.
114 After this command |n| searches forward for the next
115 match (not backward).
119 gD Goto global Declaration. When the cursor is on a
120 global variable that is defined in the file, this
121 command will jump to its declaration. This works just
122 like "gd", except that the search for the keyword
123 always starts in line 1. {not in Vi}
126 1gd Like "gd", but ignore matches inside a {} block that
127 ends before the cursor position. {not in Vi}
130 1gD Like "gD", but ignore matches inside a {} block that
131 ends before the cursor position. {not in Vi}
134 CTRL-C Interrupt current (search) command. Use CTRL-Break on
135 MS-DOS |dos-CTRL-Break|.
136 In Normal mode, any pending command is aborted.
139 :noh[lsearch] Stop the highlighting for the 'hlsearch' option. It
140 is automatically turned back on when using a search
141 command, or setting the 'hlsearch' option.
142 This command doesn't work in an autocommand, because
143 the highlighting state is saved and restored when
144 executing autocommands |autocmd-searchpat|.
145 Same thing for when invoking a user function.
147 While typing the search pattern the current match will be shown if the
148 'incsearch' option is on. Remember that you still have to finish the search
149 command with <CR> to actually position the cursor at the displayed match. Or
150 use <Esc> to abandon the search.
152 All matches for the last used search pattern will be highlighted if you set
153 the 'hlsearch' option. This can be suspended with the |:nohlsearch| command.
155 When no match is found you get the error: *E486* Pattern not found
156 Note that for the |:global| command this behaves like a normal message, for Vi
157 compatibility. For the |:s| command the "e" flag can be used to avoid the
158 error message |:s_flags|.
160 *search-offset* *{offset}*
161 These commands search for the specified pattern. With "/" and "?" an
162 additional offset may be given. There are two types of offsets: line offsets
163 and character offsets. {the character offsets are not in Vi}
165 The offset gives the cursor position relative to the found match:
166 [num] [num] lines downwards, in column 1
167 +[num] [num] lines downwards, in column 1
168 -[num] [num] lines upwards, in column 1
169 e[+num] [num] characters to the right of the end of the match
170 e[-num] [num] characters to the left of the end of the match
171 s[+num] [num] characters to the right of the start of the match
172 s[-num] [num] characters to the left of the start of the match
173 b[+num] [num] identical to s[+num] above (mnemonic: begin)
174 b[-num] [num] identical to s[-num] above (mnemonic: begin)
175 ;{pattern} perform another search, see |//;|
177 If a '-' or '+' is given but [num] is omitted, a count of one will be used.
178 When including an offset with 'e', the search becomes inclusive (the
179 character the cursor lands on is included in operations).
183 pattern cursor position ~
184 /test/+1 one line below "test", in column 1
185 /test/e on the last t of "test"
186 /test/s+2 on the 's' of "test"
187 /test/b-3 three characters before "test"
189 If one of these commands is used after an operator, the characters between
190 the cursor position before and after the search is affected. However, if a
191 line offset is given, the whole lines between the two cursor positions are
194 An example of how to search for matches with a pattern and change the match
197 c//e<CR> change until end of match
198 bar<Esc> type replacement
199 //<CR> go to start of next match
200 c//e<CR> change until end of match
201 beep<Esc> type another replacement
205 A very special offset is ';' followed by another search command. For example: >
210 The first one first finds the next occurrence of "test 1", and then the first
211 occurrence of "test" after that.
213 This is like executing two search commands after each other, except that:
214 - It can be used as a single motion command after an operator.
215 - The direction for a following "n" or "N" command comes from the first
217 - When an error occurs the cursor is not moved at all.
220 The last used pattern and offset are remembered. They can be used to repeat
221 the search, possibly in another direction or with another count. Note that
222 two patterns are remembered: One for 'normal' search commands and one for the
223 substitute command ":s". Each time an empty pattern is given, the previously
224 used pattern is used. However, if there is no previous search command, a
225 previous substitute pattern is used, if possible.
227 The 'magic' option sticks with the last used pattern. If you change 'magic',
228 this will not change how the last used pattern will be interpreted.
229 The 'ignorecase' option does not do this. When 'ignorecase' is changed, it
230 will result in the pattern to match other text.
232 All matches for the last used search pattern will be highlighted if you set
233 the 'hlsearch' option.
235 To clear the last used search pattern: >
237 This will not set the pattern to an empty string, because that would match
238 everywhere. The pattern is really cleared, like when starting Vim.
240 The search usually skips matches that don't move the cursor. Whether the next
241 match is found at the next character or after the skipped match depends on the
242 'c' flag in 'cpoptions'. See |cpo-c|.
243 with 'c' flag: "/..." advances 1 to 3 characters
244 without 'c' flag: "/..." advances 1 character
245 The unpredictability with the 'c' flag is caused by starting the search in the
246 first column, skipping matches until one is found past the cursor position.
248 When searching backwards, searching starts at the start of the line, using the
249 'c' flag in 'cpoptions' as described above. Then the last match before the
250 cursor position is used.
252 In Vi the ":tag" command sets the last search pattern when the tag is searched
253 for. In Vim this is not done, the previous search pattern is still remembered,
254 unless the 't' flag is present in 'cpoptions'. The search pattern is always
255 put in the search history.
257 If the 'wrapscan' option is on (which is the default), searches wrap around
258 the end of the buffer. If 'wrapscan' is not set, the backward search stops
259 at the beginning and the forward search stops at the end of the buffer. If
260 'wrapscan' is set and the pattern was not found the error message "pattern
261 not found" is given, and the cursor will not be moved. If 'wrapscan' is not
262 set the message becomes "search hit BOTTOM without match" when searching
263 forward, or "search hit TOP without match" when searching backward. If
264 wrapscan is set and the search wraps around the end of the file the message
265 "search hit TOP, continuing at BOTTOM" or "search hit BOTTOM, continuing at
266 TOP" is given when searching backwards or forwards respectively. This can be
267 switched off by setting the 's' flag in the 'shortmess' option. The highlight
268 method 'w' is used for this message (default: standout).
271 You can limit the search command "/" to a certain range of lines by including
272 \%>l items. For example, to match the word "limit" below line 199 and above
277 Another way is to use the ":substitute" command with the 'c' flag. Example: >
279 This command will search from the cursor position until line 300 for
280 "Pattern". At the match, you will be asked to type a character. Type 'q' to
281 stop at this match, type 'n' to find the next match.
283 The "*", "#", "g*" and "g#" commands look for a word near the cursor in this
284 order, the first one that is found is used:
285 - The keyword currently under the cursor.
286 - The first keyword to the right of the cursor, in the same line.
287 - The WORD currently under the cursor.
288 - The first WORD to the right of the cursor, in the same line.
289 The keyword may only contain letters and characters in 'iskeyword'.
290 The WORD may contain any non-blanks (<Tab>s and/or <Space>s).
291 Note that if you type with ten fingers, the characters are easy to remember:
292 the "#" is under your left hand middle finger (search to the left and up) and
293 the "*" is under your right hand middle finger (search to the right and down).
294 (this depends on your keyboard layout though).
296 ==============================================================================
297 2. The definition of a pattern *search-pattern* *pattern* *[pattern]*
298 *regular-expression* *regexp* *Pattern*
301 For starters, read chapter 27 of the user manual |usr_27.txt|.
303 */bar* */\bar* */pattern*
304 1. A pattern is one or more branches, separated by "\|". It matches anything
305 that matches one of the branches. Example: "foo\|beep" matches "foo" and
306 matches "beep". If more than one branch matches, the first one is used.
310 or branch \| branch \| branch
314 2. A branch is one or more concats, separated by "\&". It matches the last
315 concat, but only if all the preceding concats also match at the same
317 "foobeep\&..." matches "foo" in "foobeep".
318 ".*Peter\&.*Bob" matches in a line containing both "Peter" and "Bob"
322 or concat \& concat \& concat
326 3. A concat is one or more pieces, concatenated. It matches a match for the
327 first piece, followed by a match for the second piece, etc. Example:
328 "f[0-9]b", first matches "f", then a digit and then "b".
336 4. A piece is an atom, possibly followed by a multi, an indication of how many
337 times the atom can be matched. Example: "a*" matches any sequence of "a"
338 characters: "", "a", "aa", etc. See |/multi|.
344 5. An atom can be one of a long list of items. Many atoms match one character
345 in the text. It is often an ordinary character or a character class.
346 Braces can be used to make a pattern into an atom. The "\z(\)" construct
347 is only for syntax highlighting.
349 atom ::= ordinary-atom |/ordinary-atom|
350 or \( pattern \) |/\(|
351 or \%( pattern \) |/\%(|
352 or \z( pattern \) |/\z(|
355 */\%#=* *two-engines* *NFA*
356 Vim includes two regexp engines:
357 1. An old, backtracking engine that supports everything.
358 2. A new, NFA engine that works much faster on some patterns, possibly slower
361 Vim will automatically select the right engine for you. However, if you run
362 into a problem or want to specifically select one engine or the other, you can
363 prepend one of the following to the pattern:
365 \%#=0 Force automatic selection. Only has an effect when
366 'regexpengine' has been set to a non-zero value.
367 \%#=1 Force using the old engine.
368 \%#=2 Force using the NFA engine.
370 You can also use the 'regexpengine' option to change the default.
372 *E864* *E868* *E874* *E875* *E876* *E877* *E878*
373 If selecting the NFA engine and it runs into something that is not implemented
374 the pattern will not match. This is only useful when debugging Vim.
376 ==============================================================================
379 Some characters in the pattern are taken literally. They match with the same
380 character in the text. When preceded with a backslash however, these
381 characters get a special meaning.
383 Other characters have a special meaning without a backslash. They need to be
384 preceded with a backslash to match literally.
386 If a character is taken literally or not depends on the 'magic' option and the
387 items mentioned next.
389 Use of "\m" makes the pattern after it be interpreted as if 'magic' is set,
390 ignoring the actual value of the 'magic' option.
391 Use of "\M" makes the pattern after it be interpreted as if 'nomagic' is used.
393 Use of "\v" means that in the pattern after it all ASCII characters except
394 '0'-'9', 'a'-'z', 'A'-'Z' and '_' have a special meaning. "very magic"
396 Use of "\V" means that in the pattern after it only the backslash and the
397 terminating character (/ or ?) has a special meaning. "very nomagic"
400 after: \v \m \M \V matches ~
402 $ $ $ \$ matches end-of-line
403 . . \. \. matches any character
404 * * \* \* any number of the previous atom
405 ~ ~ \~ \~ latest substitute string
406 () \(\) \(\) \(\) grouping into an atom
407 | \| \| \| separating alternatives
408 \a \a \a \a alphabetic character
409 \\ \\ \\ \\ literal backslash
410 \. \. . . literal dot
414 {only Vim supports \m, \M, \v and \V}
416 It is recommended to always keep the 'magic' option at the default setting,
417 which is 'magic'. This avoids portability problems. To make a pattern immune
418 to the 'magic' option being set or not, put "\m" or "\M" at the start of the
421 ==============================================================================
422 4. Overview of pattern items *pattern-overview*
423 *E865* *E866* *E867* *E869*
425 Overview of multi items. */multi* *E61* *E62*
426 More explanation and examples below, follow the links. *E64* *E871*
429 'magic' 'nomagic' matches of the preceding atom ~
430 |/star| * \* 0 or more as many as possible
431 |/\+| \+ \+ 1 or more as many as possible (*)
432 |/\=| \= \= 0 or 1 as many as possible (*)
433 |/\?| \? \? 0 or 1 as many as possible (*)
435 |/\{| \{n,m} \{n,m} n to m as many as possible (*)
436 \{n} \{n} n exactly (*)
437 \{n,} \{n,} at least n as many as possible (*)
438 \{,m} \{,m} 0 to m as many as possible (*)
439 \{} \{} 0 or more as many as possible (same as *) (*)
441 |/\{-| \{-n,m} \{-n,m} n to m as few as possible (*)
442 \{-n} \{-n} n exactly (*)
443 \{-n,} \{-n,} at least n as few as possible (*)
444 \{-,m} \{-,m} 0 to m as few as possible (*)
445 \{-} \{-} 0 or more as few as possible (*)
448 |/\@>| \@> \@> 1, like matching a whole pattern (*)
449 |/\@=| \@= \@= nothing, requires a match |/zero-width| (*)
450 |/\@!| \@! \@! nothing, requires NO match |/zero-width| (*)
451 |/\@<=| \@<= \@<= nothing, requires a match behind |/zero-width| (*)
452 |/\@<!| \@<! \@<! nothing, requires NO match behind |/zero-width| (*)
457 Overview of ordinary atoms. */ordinary-atom*
458 More explanation and examples below, follow the links.
461 magic nomagic matches ~
462 |/^| ^ ^ start-of-line (at start of pattern) |/zero-width|
463 |/\^| \^ \^ literal '^'
464 |/\_^| \_^ \_^ start-of-line (used anywhere) |/zero-width|
465 |/$| $ $ end-of-line (at end of pattern) |/zero-width|
466 |/\$| \$ \$ literal '$'
467 |/\_$| \_$ \_$ end-of-line (used anywhere) |/zero-width|
468 |/.| . \. any single character (not an end-of-line)
469 |/\_.| \_. \_. any single character or end-of-line
470 |/\<| \< \< beginning of a word |/zero-width|
471 |/\>| \> \> end of a word |/zero-width|
472 |/\zs| \zs \zs anything, sets start of match
473 |/\ze| \ze \ze anything, sets end of match
474 |/\%^| \%^ \%^ beginning of file |/zero-width| *E71*
475 |/\%$| \%$ \%$ end of file |/zero-width|
476 |/\%V| \%V \%V inside Visual area |/zero-width|
477 |/\%#| \%# \%# cursor position |/zero-width|
478 |/\%'m| \%'m \%'m mark m position |/zero-width|
479 |/\%l| \%23l \%23l in line 23 |/zero-width|
480 |/\%c| \%23c \%23c in column 23 |/zero-width|
481 |/\%v| \%23v \%23v in virtual column 23 |/zero-width|
483 Character classes {not in Vi}: */character-classes*
484 magic nomagic matches ~
485 |/\i| \i \i identifier character (see 'isident' option)
486 |/\I| \I \I like "\i", but excluding digits
487 |/\k| \k \k keyword character (see 'iskeyword' option)
488 |/\K| \K \K like "\k", but excluding digits
489 |/\f| \f \f file name character (see 'isfname' option)
490 |/\F| \F \F like "\f", but excluding digits
491 |/\p| \p \p printable character (see 'isprint' option)
492 |/\P| \P \P like "\p", but excluding digits
493 |/\s| \s \s whitespace character: <Space> and <Tab>
494 |/\S| \S \S non-whitespace character; opposite of \s
495 |/\d| \d \d digit: [0-9]
496 |/\D| \D \D non-digit: [^0-9]
497 |/\x| \x \x hex digit: [0-9A-Fa-f]
498 |/\X| \X \X non-hex digit: [^0-9A-Fa-f]
499 |/\o| \o \o octal digit: [0-7]
500 |/\O| \O \O non-octal digit: [^0-7]
501 |/\w| \w \w word character: [0-9A-Za-z_]
502 |/\W| \W \W non-word character: [^0-9A-Za-z_]
503 |/\h| \h \h head of word character: [A-Za-z_]
504 |/\H| \H \H non-head of word character: [^A-Za-z_]
505 |/\a| \a \a alphabetic character: [A-Za-z]
506 |/\A| \A \A non-alphabetic character: [^A-Za-z]
507 |/\l| \l \l lowercase character: [a-z]
508 |/\L| \L \L non-lowercase character: [^a-z]
509 |/\u| \u \u uppercase character: [A-Z]
510 |/\U| \U \U non-uppercase character [^A-Z]
511 |/\_| \_x \_x where x is any of the characters above: character
512 class with end-of-line included
513 (end of character classes)
515 magic nomagic matches ~
520 |/\n| \n \n end-of-line
521 |/~| ~ \~ last given substitute string
522 |/\1| \1 \1 same string as matched by first \(\) {not in Vi}
523 |/\2| \2 \2 Like "\1", but uses second \(\)
525 |/\9| \9 \9 Like "\1", but uses ninth \(\)
527 |/\z1| \z1 \z1 only for syntax highlighting, see |:syn-ext-match|
529 |/\z1| \z9 \z9 only for syntax highlighting, see |:syn-ext-match|
531 x x a character with no special meaning matches itself
533 |/[]| [] \[] any character specified inside the []
534 |/\%[]| \%[] \%[] a sequence of optionally matched atoms
536 |/\c| \c \c ignore case, do not use the 'ignorecase' option
537 |/\C| \C \C match case, do not use the 'ignorecase' option
538 |/\Z| \Z \Z ignore differences in Unicode "combining characters".
539 Useful when searching voweled Hebrew or Arabic text.
541 magic nomagic matches ~
542 |/\m| \m \m 'magic' on for the following chars in the pattern
543 |/\M| \M \M 'magic' off for the following chars in the pattern
544 |/\v| \v \v the following chars in the pattern are "very magic"
545 |/\V| \V \V the following chars in the pattern are "very nomagic"
546 |/\%#=| \%#=1 \%#=1 select regexp engine |/zero-width|
548 |/\%d| \%d \%d match specified decimal character (eg \%d123)
549 |/\%x| \%x \%x match specified hex character (eg \%x2a)
550 |/\%o| \%o \%o match specified octal character (eg \%o040)
551 |/\%u| \%u \%u match specified multibyte character (eg \%u20ac)
552 |/\%U| \%U \%U match specified large multibyte character (eg
554 |/\%C| \%C \%C match any composing characters
559 \<[a-zA-Z_][a-zA-Z0-9_]*
560 An identifier (e.g., in a C program).
562 \(\.$\|\. \) A period followed by <EOL> or a space.
564 [.!?][])"']*\($\|[ ]\) A search pattern that finds the end of a sentence,
565 with almost the same definition as the ")" command.
567 cat\Z Both "cat" and "càt" ("a" followed by 0x0300)
568 Does not match "càt" (character 0x00e0), even
569 though it may look the same.
572 ==============================================================================
573 5. Multi items *pattern-multi-items*
575 An atom can be followed by an indication of how many times the atom can be
576 matched and in what way. This is called a multi. See |/multi| for an
580 * (use \* when 'magic' is not set)
581 Matches 0 or more of the preceding atom, as many as possible.
582 Example 'nomagic' matches ~
583 a* a\* "", "a", "aa", "aaa", etc.
584 .* \.\* anything, also an empty string, no end-of-line
585 \_.* \_.\* everything up to the end of the buffer
586 \_.*END \_.\*END everything up to and including the last "END"
589 Exception: When "*" is used at the start of the pattern or just after
590 "^" it matches the star character.
592 Be aware that repeating "\_." can match a lot of text and take a long
593 time. For example, "\_.*END" matches all text from the current
594 position to the last occurrence of "END" in the file. Since the "*"
595 will match as many as possible, this first skips over all lines until
596 the end of the file and then tries matching "END", backing up one
600 \+ Matches 1 or more of the preceding atom, as many as possible. {not in
603 ^.\+$ any non-empty line
604 \s\+ white space of at least one character
607 \= Matches 0 or 1 of the preceding atom, as many as possible. {not in Vi}
612 \? Just like \=. Cannot be used when searching backwards with the "?"
615 */\{* *E60* *E554* *E870*
616 \{n,m} Matches n to m of the preceding atom, as many as possible
617 \{n} Matches n of the preceding atom
618 \{n,} Matches at least n of the preceding atom, as many as possible
619 \{,m} Matches 0 to m of the preceding atom, as many as possible
620 \{} Matches 0 or more of the preceding atom, as many as possible (like *)
622 \{-n,m} matches n to m of the preceding atom, as few as possible
623 \{-n} matches n of the preceding atom
624 \{-n,} matches at least n of the preceding atom, as few as possible
625 \{-,m} matches 0 to m of the preceding atom, as few as possible
626 \{-} matches 0 or more of the preceding atom, as few as possible
627 {Vi does not have any of these}
629 n and m are positive decimal numbers or zero
631 If a "-" appears immediately after the "{", then a shortest match
632 first algorithm is used (see example below). In particular, "\{-}" is
633 the same as "*" but uses the shortest match first algorithm. BUT: A
634 match that starts earlier is preferred over a shorter match: "a\{-}b"
635 matches "aaab" in "xaaab".
638 ab\{2,3}c "abbc" or "abbbc"
640 ab\{2,}c "abbc", "abbbc", "abbbbc", etc.
641 ab\{,3}c "ac", "abc", "abbc" or "abbbc"
642 a[bc]\{3}d "abbbd", "abbcd", "acbcd", "acccd", etc.
643 a\(bc\)\{1,2}d "abcd" or "abcbcd"
644 a[bc]\{-}[cd] "abc" in "abcd"
645 a[bc]*[cd] "abcd" in "abcd"
647 The } may optionally be preceded with a backslash: \{n,m\}.
650 \@= Matches the preceding atom with zero width. {not in Vi}
651 Like "(?=pattern)" in Perl.
653 foo\(bar\)\@= "foo" in "foobar"
654 foo\(bar\)\@=foo nothing
656 When using "\@=" (or "^", "$", "\<", "\>") no characters are included
657 in the match. These items are only used to check if a match can be
658 made. This can be tricky, because a match with following items will
659 be done in the same position. The last example above will not match
660 "foobarfoo", because it tries match "foo" in the same position where
663 Note that using "\&" works the same as using "\@=": "foo\&.." is the
664 same as "\(foo\)\@=..". But using "\&" is easier, you don't need the
669 \@! Matches with zero width if the preceding atom does NOT match at the
670 current position. |/zero-width| {not in Vi}
671 Like "(?!pattern)" in Perl.
673 foo\(bar\)\@! any "foo" not followed by "bar"
674 a.\{-}p\@! "a", "ap", "app", "appp", etc. not immediately
676 if \(\(then\)\@!.\)*$ "if " not followed by "then"
678 Using "\@!" is tricky, because there are many places where a pattern
679 does not match. "a.*p\@!" will match from an "a" to the end of the
680 line, because ".*" can match all characters in the line and the "p"
681 doesn't match at the end of the line. "a.\{-}p\@!" will match any
682 "a", "ap", "app", etc. that isn't followed by a "p", because the "."
683 can match a "p" and "p\@!" doesn't match after that.
685 You can't use "\@!" to look for a non-match before the matching
686 position: "\(foo\)\@!bar" will match "bar" in "foobar", because at the
687 position where "bar" matches, "foo" does not match. To avoid matching
688 "foobar" you could use "\(foo\)\@!...bar", but that doesn't match a
689 bar at the start of a line. Use "\(foo\)\@<!bar".
691 Useful example: to find "foo" in a line that does not contain "bar": >
692 /^\%(.*bar\)\@!.*\zsfoo
693 < This pattern first checks that there is not a single position in the
694 line where "bar" matches. If ".*bar" matches somewhere the \@! will
695 reject the pattern. When there is no match any "foo" will be found.
696 The "\zs" is to have the match start just before "foo".
699 \@<= Matches with zero width if the preceding atom matches just before what
700 follows. |/zero-width| {not in Vi}
701 Like "(?<=pattern)" in Perl, but Vim allows non-fixed-width patterns.
703 \(an\_s\+\)\@<=file "file" after "an" and white space or an
705 For speed it's often much better to avoid this multi. Try using "\zs"
706 instead |/\zs|. To match the same as the above example:
708 At least set a limit for the look-behind, see below.
710 "\@<=" and "\@<!" check for matches just before what follows.
711 Theoretically these matches could start anywhere before this position.
712 But to limit the time needed, only the line where what follows matches
713 is searched, and one line before that (if there is one). This should
714 be sufficient to match most things and not be too slow.
716 In the old regexp engine the part of the pattern after "\@<=" and
717 "\@<!" are checked for a match first, thus things like "\1" don't work
718 to reference \(\) inside the preceding atom. It does work the other
720 Bad example matches ~
721 \%#=1\1\@<=,\([a-z]\+\) ",abc" in "abc,abc"
723 However, the new regexp engine works differently, it is better to not
724 rely on this behavior, do not use \@<= if it can be avoided:
726 \([a-z]\+\)\zs,\1 ",abc" in "abc,abc"
729 Like "\@<=" but only look back 123 bytes. This avoids trying lots
730 of matches that are known to fail and make executing the pattern very
731 slow. Example, check if there is a "<" just before "span":
733 This will try matching "<" only one byte before "span", which is the
734 only place that works anyway.
735 After crossing a line boundary, the limit is relative to the end of
736 the line. Thus the characters at the start of the line with the match
737 are not counted (this is just to keep it simple).
738 The number zero is the same as no limit.
741 \@<! Matches with zero width if the preceding atom does NOT match just
742 before what follows. Thus this matches if there is no position in the
743 current or previous line where the atom matches such that it ends just
744 before what follows. |/zero-width| {not in Vi}
745 Like "(?<!pattern)" in Perl, but Vim allows non-fixed-width patterns.
746 The match with the preceding atom is made to end just before the match
747 with what follows, thus an atom that ends in ".*" will work.
748 Warning: This can be slow (because many positions need to be checked
749 for a match). Use a limit if you can, see below.
751 \(foo\)\@<!bar any "bar" that's not in "foobar"
752 \(\/\/.*\)\@<!in "in" which is not after "//"
755 Like "\@<!" but only look back 123 bytes. This avoids trying lots of
756 matches that are known to fail and make executing the pattern very
760 \@> Matches the preceding atom like matching a whole pattern. {not in Vi}
761 Like "(?>pattern)" in Perl.
763 \(a*\)\@>a nothing (the "a*" takes all the "a"'s, there can't be
764 another one following)
766 This matches the preceding atom as if it was a pattern by itself. If
767 it doesn't match, there is no retry with shorter sub-matches or
768 anything. Observe this difference: "a*b" and "a*ab" both match
769 "aaab", but in the second case the "a*" matches only the first two
770 "a"s. "\(a*\)\@>ab" will not match "aaab", because the "a*" matches
771 the "aaa" (as many "a"s as possible), thus the "ab" can't match.
774 ==============================================================================
775 6. Ordinary atoms *pattern-atoms*
777 An ordinary atom can be:
780 ^ At beginning of pattern or after "\|", "\(", "\%(" or "\n": matches
781 start-of-line; at other positions, matches literal '^'. |/zero-width|
783 ^beep( the start of the C function "beep" (probably).
786 \^ Matches literal '^'. Can be used at any position in the pattern.
789 \_^ Matches start-of-line. |/zero-width| Can be used at any position in
792 \_s*\_^foo white space and blank lines and then "foo" at
796 $ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on):
797 matches end-of-line <EOL>; at other positions, matches literal '$'.
801 \$ Matches literal '$'. Can be used at any position in the pattern.
804 \_$ Matches end-of-line. |/zero-width| Can be used at any position in the
805 pattern. Note that "a\_$b" never matches, since "b" cannot match an
806 end-of-line. Use "a\nb" instead |/\n|.
808 foo\_$\_s* "foo" at end-of-line and following white space and
811 . (with 'nomagic': \.) */.* */\.*
812 Matches any single character, but not an end-of-line.
815 \_. Matches any single character or end-of-line.
816 Careful: "\_.*" matches all text to the end of the buffer!
819 \< Matches the beginning of a word: The next char is the first char of a
820 word. The 'iskeyword' option specifies what is a word character.
824 \> Matches the end of a word: The previous char is the last char of a
825 word. The 'iskeyword' option specifies what is a word character.
829 \zs Matches at any position, and sets the start of the match there: The
830 next char is the first char of the whole match. |/zero-width|
833 < matches an "if" at the start of a line, ignoring white space.
834 Can be used multiple times, the last one encountered in a matching
835 branch is used. Example: >
837 < Finds the third occurrence of "Fab".
838 This cannot be followed by a multi. *E888*
839 {not in Vi} {not available when compiled without the |+syntax| feature}
841 \ze Matches at any position, and sets the end of the match there: The
842 previous char is the last char of the whole match. |/zero-width|
843 Can be used multiple times, the last one encountered in a matching
845 Example: "end\ze\(if\|for\)" matches the "end" in "endif" and
847 This cannot be followed by a multi. |E888|
848 {not in Vi} {not available when compiled without the |+syntax| feature}
850 */\%^* *start-of-file*
851 \%^ Matches start of the file. When matching with a string, matches the
852 start of the string. {not in Vi}
853 For example, to find the first "VIM" in a file: >
857 \%$ Matches end of the file. When matching with a string, matches the
858 end of the string. {not in Vi}
859 Note that this does NOT find the last "VIM" in a file: >
861 < It will find the next VIM, because the part after it will always
862 match. This one will find the last "VIM" in the file: >
863 /VIM\ze\(\(VIM\)\@!\_.\)*\%$
864 < This uses |/\@!| to ascertain that "VIM" does NOT match in any
865 position after the first "VIM".
866 Searching from the end of the file backwards is easier!
869 \%V Match inside the Visual area. When Visual mode has already been
870 stopped match in the area that |gv| would reselect.
871 This is a |/zero-width| match. To make sure the whole pattern is
872 inside the Visual area put it at the start and just before the end of
875 < This also works if only "foo bar" was Visually selected. This: >
877 < would match "foo bar" if the Visual selection continues after the "r".
878 Only works for the current buffer.
880 */\%#* *cursor-position*
881 \%# Matches with the cursor position. Only works when matching in a
882 buffer displayed in a window. {not in Vi}
883 WARNING: When the cursor is moved after the pattern was used, the
884 result becomes invalid. Vim doesn't automatically update the matches.
885 This is especially relevant for syntax highlighting and 'hlsearch'.
886 In other words: When the cursor moves the display isn't updated for
887 this change. An update is done for lines which are changed (the whole
888 line is updated) or when using the |CTRL-L| command (the whole screen
889 is updated). Example, to highlight the word under the cursor: >
891 < When 'hlsearch' is set and you move the cursor around and make changes
892 this will clearly show when the match is updated or not.
894 */\%'m* */\%<'m* */\%>'m*
895 \%'m Matches with the position of mark m.
896 \%<'m Matches before the position of mark m.
897 \%>'m Matches after the position of mark m.
898 Example, to highlight the text from mark 's to 'e: >
900 < Note that two dots are required to include mark 'e in the match. That
901 is because "\%<'e" matches at the character before the 'e mark, and
902 since it's a |/zero-width| match it doesn't include that character.
904 WARNING: When the mark is moved after the pattern was used, the result
905 becomes invalid. Vim doesn't automatically update the matches.
906 Similar to moving the cursor for "\%#" |/\%#|.
908 */\%l* */\%>l* */\%<l*
909 \%23l Matches in a specific line.
910 \%<23l Matches above a specific line (lower line number).
911 \%>23l Matches below a specific line (higher line number).
912 These three can be used to match specific lines in a buffer. The "23"
913 can be any line number. The first line is 1. {not in Vi}
914 WARNING: When inserting or deleting lines Vim does not automatically
915 update the matches. This means Syntax highlighting quickly becomes
917 Example, to highlight the line where the cursor currently is: >
918 :exe '/\%' . line(".") . 'l.*'
919 < When 'hlsearch' is set and you move the cursor around and make changes
920 this will clearly show when the match is updated or not.
922 */\%c* */\%>c* */\%<c*
923 \%23c Matches in a specific column.
924 \%<23c Matches before a specific column.
925 \%>23c Matches after a specific column.
926 These three can be used to match specific columns in a buffer or
927 string. The "23" can be any column number. The first column is 1.
928 Actually, the column is the byte number (thus it's not exactly right
929 for multi-byte characters). {not in Vi}
930 WARNING: When inserting or deleting text Vim does not automatically
931 update the matches. This means Syntax highlighting quickly becomes
933 Example, to highlight the column where the cursor currently is: >
934 :exe '/\%' . col(".") . 'c'
935 < When 'hlsearch' is set and you move the cursor around and make changes
936 this will clearly show when the match is updated or not.
937 Example for matching a single byte in column 44: >
939 < Note that "\%<46c" matches in column 45 when the "." matches a byte in
941 */\%v* */\%>v* */\%<v*
942 \%23v Matches in a specific virtual column.
943 \%<23v Matches before a specific virtual column.
944 \%>23v Matches after a specific virtual column.
945 These three can be used to match specific virtual columns in a buffer
946 or string. When not matching with a buffer in a window, the option
947 values of the current window are used (e.g., 'tabstop').
948 The "23" can be any column number. The first column is 1.
949 Note that some virtual column positions will never match, because they
950 are halfway through a tab or other character that occupies more than
951 one screen character. {not in Vi}
952 WARNING: When inserting or deleting text Vim does not automatically
953 update highlighted matches. This means Syntax highlighting quickly
955 Example, to highlight all the characters after virtual column 72: >
957 < When 'hlsearch' is set and you move the cursor around and make changes
958 this will clearly show when the match is updated or not.
959 To match the text up to column 17: >
961 < Column 17 is not included, because this is a |/zero-width| match. To
962 include the column use: >
964 < This command does the same thing, but also matches when there is no
965 character in column 17: >
967 < Note that without the "^" to anchor the match in the first column,
968 this will also highlight column 17: >
970 < Column 17 is highlighted by 'hlsearch' because there is another match
971 where ".*" matches zero characters.
974 Character classes: {not in Vi}
975 \i identifier character (see 'isident' option) */\i*
976 \I like "\i", but excluding digits */\I*
977 \k keyword character (see 'iskeyword' option) */\k*
978 \K like "\k", but excluding digits */\K*
979 \f file name character (see 'isfname' option) */\f*
980 \F like "\f", but excluding digits */\F*
981 \p printable character (see 'isprint' option) */\p*
982 \P like "\p", but excluding digits */\P*
984 NOTE: the above also work for multi-byte characters. The ones below only
985 match ASCII characters, as indicated by the range.
987 *whitespace* *white-space*
988 \s whitespace character: <Space> and <Tab> */\s*
989 \S non-whitespace character; opposite of \s */\S*
990 \d digit: [0-9] */\d*
991 \D non-digit: [^0-9] */\D*
992 \x hex digit: [0-9A-Fa-f] */\x*
993 \X non-hex digit: [^0-9A-Fa-f] */\X*
994 \o octal digit: [0-7] */\o*
995 \O non-octal digit: [^0-7] */\O*
996 \w word character: [0-9A-Za-z_] */\w*
997 \W non-word character: [^0-9A-Za-z_] */\W*
998 \h head of word character: [A-Za-z_] */\h*
999 \H non-head of word character: [^A-Za-z_] */\H*
1000 \a alphabetic character: [A-Za-z] */\a*
1001 \A non-alphabetic character: [^A-Za-z] */\A*
1002 \l lowercase character: [a-z] */\l*
1003 \L non-lowercase character: [^a-z] */\L*
1004 \u uppercase character: [A-Z] */\u*
1005 \U non-uppercase character: [^A-Z] */\U*
1007 NOTE: Using the atom is faster than the [] form.
1009 NOTE: 'ignorecase', "\c" and "\C" are not used by character classes.
1011 */\_* *E63* */\_i* */\_I* */\_k* */\_K* */\_f* */\_F*
1012 */\_p* */\_P* */\_s* */\_S* */\_d* */\_D* */\_x* */\_X*
1013 */\_o* */\_O* */\_w* */\_W* */\_h* */\_H* */\_a* */\_A*
1014 */\_l* */\_L* */\_u* */\_U*
1015 \_x Where "x" is any of the characters above: The character class with
1017 (end of character classes)
1019 \e matches <Esc> */\e*
1020 \t matches <Tab> */\t*
1021 \r matches <CR> */\r*
1022 \b matches <BS> */\b*
1023 \n matches an end-of-line */\n*
1024 When matching in a string instead of buffer text a literal newline
1025 character is matched.
1027 ~ matches the last given substitute string */~* */\~*
1029 \(\) A pattern enclosed by escaped parentheses. */\(* */\(\)* */\)*
1030 E.g., "\(^a\)" matches 'a' at the start of a line.
1031 *E51* *E54* *E55* *E872* *E873*
1033 \1 Matches the same string that was matched by */\1* *E65*
1034 the first sub-expression in \( and \). {not in Vi}
1035 Example: "\([a-z]\).\1" matches "ata", "ehe", "tot", etc.
1036 \2 Like "\1", but uses second sub-expression, */\2*
1038 \9 Like "\1", but uses ninth sub-expression. */\9*
1039 Note: The numbering of groups is done based on which "\(" comes first
1040 in the pattern (going left to right), NOT based on what is matched
1043 \%(\) A pattern enclosed by escaped parentheses. */\%(\)* */\%(* *E53*
1044 Just like \(\), but without counting it as a sub-expression. This
1045 allows using more groups and it's a little bit faster.
1048 x A single character, with no special meaning, matches itself
1051 \x A backslash followed by a single character, with no special meaning,
1052 is reserved for future expansions
1054 [] (with 'nomagic': \[]) */[]* */\[]* */\_[]* */collection*
1056 A collection. This is a sequence of characters enclosed in brackets.
1057 It matches any single character in the collection.
1059 [xyz] any 'x', 'y' or 'z'
1060 [a-zA-Z]$ any alphabetic character at the end of a line
1062 [А-яЁё] Russian alphabet (with utf-8 and cp1251)
1065 With "\_" prepended the collection also includes the end-of-line.
1066 The same can be done by including "\n" in the collection. The
1067 end-of-line is also matched when the collection starts with "^"! Thus
1068 "\_[^ab]" matches the end-of-line and any character but "a" and "b".
1069 This makes it Vi compatible: Without the "\_" or "\n" the collection
1070 does not match an end-of-line.
1072 When the ']' is not there Vim will not give an error message but
1073 assume no collection is used. Useful to search for '['. However, you
1074 do get E769 for internal searching. And be aware that in a
1075 `:substitute` command the whole command becomes the pattern. E.g.
1076 ":s/[/x/" searches for "[/x" and replaces it with nothing. It does
1077 not search for "[" and replaces it with "x"!
1079 If the sequence begins with "^", it matches any single character NOT
1080 in the collection: "[^xyz]" matches anything but 'x', 'y' and 'z'.
1081 - If two characters in the sequence are separated by '-', this is
1082 shorthand for the full list of ASCII characters between them. E.g.,
1083 "[0-9]" matches any decimal digit. Non-ASCII characters can be
1084 used, but the character values must not be more than 256 apart.
1085 - A character class expression is evaluated to the set of characters
1086 belonging to that character class. The following character classes
1088 Name Func Contents ~
1089 *[:alnum:]* [:alnum:] isalnum ASCII letters and digits
1090 *[:alpha:]* [:alpha:] isalpha ASCII letters
1091 *[:blank:]* [:blank:] space and tab
1092 *[:cntrl:]* [:cntrl:] iscntrl ASCII control characters
1093 *[:digit:]* [:digit:] decimal digits '0' to '9'
1094 *[:graph:]* [:graph:] isgraph ASCII printable characters excluding
1096 *[:lower:]* [:lower:] (1) lowercase letters (all letters when
1097 'ignorecase' is used)
1098 *[:print:]* [:print:] (2) printable characters including space
1099 *[:punct:]* [:punct:] ispunct ASCII punctuation characters
1100 *[:space:]* [:space:] whitespace characters: space, tab, CR,
1101 NL, vertical tab, form feed
1102 *[:upper:]* [:upper:] (3) uppercase letters (all letters when
1103 'ignorecase' is used)
1104 *[:xdigit:]* [:xdigit:] hexadecimal digits: 0-9, a-f, A-F
1105 *[:return:]* [:return:] the <CR> character
1106 *[:tab:]* [:tab:] the <Tab> character
1107 *[:escape:]* [:escape:] the <Esc> character
1108 *[:backspace:]* [:backspace:] the <BS> character
1109 The brackets in character class expressions are additional to the
1110 brackets delimiting a collection. For example, the following is a
1111 plausible pattern for a UNIX filename: "[-./[:alnum:]_~]\+" That is,
1112 a list of at least one character, each of which is either '-', '.',
1113 '/', alphabetic, numeric, '_' or '~'.
1114 These items only work for 8-bit characters, except [:lower:] and
1115 [:upper:] also work for multi-byte characters when using the new
1116 regexp engine. See |two-engines|. In the future these items may
1117 work for multi-byte characters. For now, to get all "alpha"
1118 characters you can use: [[:lower:][:upper:]].
1120 The "Func" column shows what library function is used. The
1121 implementation depends on the system. Otherwise:
1122 (1) Uses islower() for ASCII and Vim builtin rules for other
1123 characters when built with the |+multi_byte| feature.
1124 (2) Uses Vim builtin rules
1125 (3) As with (1) but using isupper()
1127 - An equivalence class. This means that characters are matched that
1128 have almost the same meaning, e.g., when ignoring accents. This
1129 only works for Unicode, latin1 and latin9. The form is:
1132 - A collation element. This currently simply accepts a single
1133 character in the form:
1136 - To include a literal ']', '^', '-' or '\' in the collection, put a
1137 backslash before it: "[xyz\]]", "[\^xyz]", "[xy\-z]" and "[xyz\\]".
1138 (Note: POSIX does not support the use of a backslash this way). For
1139 ']' you can also make it the first character (following a possible
1140 "^"): "[]xyz]" or "[^]xyz]" {not in Vi}.
1141 For '-' you can also make it the first or last character: "[-xyz]",
1142 "[^-xyz]" or "[xyz-]". For '\' you can also let it be followed by
1143 any character that's not in "^]-\bdertnoUux". "[\xyz]" matches '\',
1144 'x', 'y' and 'z'. It's better to use "\\" though, future expansions
1145 may use other characters after '\'.
1146 - Omitting the trailing ] is not considered an error. "[]" works like
1147 "[]]", it matches the ']' character.
1148 - The following translations are accepted when the 'l' flag is not
1149 included in 'cpoptions' {not in Vi}:
1152 \r <CR> (NOT end-of-line!)
1154 \n line break, see above |/[\n]|
1155 \d123 decimal number of character
1156 \o40 octal number of character up to 0377
1157 \x20 hexadecimal number of character up to 0xff
1158 \u20AC hex. number of multibyte character up to 0xffff
1159 \U1234 hex. number of multibyte character up to 0xffffffff
1160 NOTE: The other backslash codes mentioned above do not work inside
1162 - Matching with a collection can be slow, because each character in
1163 the text has to be compared with each character in the collection.
1164 Use one of the other atoms above when possible. Example: "\d" is
1165 much faster than "[0-9]" and matches the same characters.
1167 */\%[]* *E69* *E70* *E369*
1168 \%[] A sequence of optionally matched atoms. This always matches.
1169 It matches as much of the list of atoms it contains as possible. Thus
1170 it stops at the first atom that doesn't match. For example: >
1172 < matches "r", "re", "rea" or "read". The longest that matches is used.
1173 To match the Ex command "function", where "fu" is required and
1174 "nction" is optional, this would work: >
1176 < The end-of-word atom "\>" is used to avoid matching "fu" in "full".
1177 It gets more complicated when the atoms are not ordinary characters.
1178 You don't often have to use it, but it is possible. Example: >
1180 < Matches the words "r", "re", "ro", "rea", "roa", "read" and "road".
1181 There can be no \(\), \%(\) or \z(\) items inside the [] and \%[] does
1183 To include a "[" use "[[]" and for "]" use []]", e.g.,: >
1185 < matches "index" "index[", "index[0" and "index[0]".
1186 {not available when compiled without the |+syntax| feature}
1188 */\%d* */\%x* */\%o* */\%u* */\%U* *E678*
1190 \%d123 Matches the character specified with a decimal number. Must be
1191 followed by a non-digit.
1192 \%o40 Matches the character specified with an octal number up to 0377.
1193 Numbers below 040 must be followed by a non-octal digit or a non-digit.
1194 \%x2a Matches the character specified with up to two hexadecimal characters.
1195 \%u20AC Matches the character specified with up to four hexadecimal
1197 \%U1234abcd Matches the character specified with up to eight hexadecimal
1200 ==============================================================================
1201 7. Ignoring case in a pattern */ignorecase*
1203 If the 'ignorecase' option is on, the case of normal letters is ignored.
1204 'smartcase' can be set to ignore case when the pattern contains lowercase
1207 When "\c" appears anywhere in the pattern, the whole pattern is handled like
1208 'ignorecase' is on. The actual value of 'ignorecase' and 'smartcase' is
1209 ignored. "\C" does the opposite: Force matching case for the whole pattern.
1210 {only Vim supports \c and \C}
1211 Note that 'ignorecase', "\c" and "\C" are not used for the character classes.
1214 pattern 'ignorecase' 'smartcase' matches ~
1216 foo on - foo Foo FOO
1217 Foo on off foo Foo FOO
1219 \cfoo - - foo Foo FOO
1222 Technical detail: *NL-used-for-Nul*
1223 <Nul> characters in the file are stored as <NL> in memory. In the display
1224 they are shown as "^@". The translation is done when reading and writing
1225 files. To match a <Nul> with a search pattern you can just enter CTRL-@ or
1226 "CTRL-V 000". This is probably just what you expect. Internally the
1227 character is replaced with a <NL> in the search pattern. What is unusual is
1228 that typing CTRL-V CTRL-J also inserts a <NL>, thus also searches for a <Nul>
1229 in the file. {Vi cannot handle <Nul> characters in the file at all}
1232 When 'fileformat' is "mac", <NL> characters in the file are stored as <CR>
1233 characters internally. In the text they are shown as "^J". Otherwise this
1234 works similar to the usage of <NL> for a <Nul>.
1236 When working with expression evaluation, a <NL> character in the pattern
1237 matches a <NL> in the string. The use of "\n" (backslash n) to match a <NL>
1238 doesn't work there, it only works to match text in the buffer.
1240 *pattern-multi-byte*
1241 Patterns will also work with multi-byte characters, mostly as you would
1242 expect. But invalid bytes may cause trouble, a pattern with an invalid byte
1243 will probably never match.
1245 ==============================================================================
1246 8. Composing characters *patterns-composing*
1249 When "\Z" appears anywhere in the pattern, all composing characters are
1250 ignored. Thus only the base characters need to match, the composing
1251 characters may be different and the number of composing characters may differ.
1252 Only relevant when 'encoding' is "utf-8".
1253 Exception: If the pattern starts with one or more composing characters, these
1256 Use "\%C" to skip any composing characters. For example, the pattern "a" does
1257 not match in "càt" (where the a has the composing character 0x0300), but
1258 "a\%C" does. Note that this does not match "cát" (where the á is character
1259 0xe1, it does not have a compositing character). It does match "cat" (where
1260 the a is just an a).
1262 When a composing character appears at the start of the pattern of after an
1263 item that doesn't include the composing character, a match is found at any
1264 character that includes this composing character.
1266 When using a dot and a composing character, this works the same as the
1267 composing character by itself, except that it doesn't matter what comes before
1270 The order of composing characters does not matter. Also, the text may have
1271 more composing characters than the pattern, it still matches. But all
1272 composing characters in the pattern must be found in the text.
1274 Suppose B is a base character and x and y are composing characters:
1275 pattern text match ~
1276 Bxy Bxy yes (perfect match)
1277 Bxy Byx yes (order ignored)
1278 Bxy By no (x missing)
1279 Bxy Bx no (y missing)
1280 Bx Bx yes (perfect match)
1281 Bx By no (x missing)
1282 Bx Bxy yes (extra y ignored)
1283 Bx Byx yes (extra y ignored)
1285 ==============================================================================
1286 9. Compare with Perl patterns *perl-patterns*
1288 Vim's regexes are most similar to Perl's, in terms of what you can do. The
1289 difference between them is mostly just notation; here's a summary of where
1292 Capability in Vimspeak in Perlspeak ~
1293 ----------------------------------------------------------------
1294 force case insensitivity \c (?i)
1295 force case sensitivity \C (?-i)
1296 backref-less grouping \%(atom\) (?:atom)
1297 conservative quantifiers \{-n,m} *?, +?, ??, {}?
1298 0-width match atom\@= (?=atom)
1299 0-width non-match atom\@! (?!atom)
1300 0-width preceding match atom\@<= (?<=atom)
1301 0-width preceding non-match atom\@<! (?<!atom)
1302 match without retry atom\@> (?>atom)
1304 Vim and Perl handle newline characters inside a string a bit differently:
1306 In Perl, ^ and $ only match at the very beginning and end of the text,
1307 by default, but you can set the 'm' flag, which lets them match at
1308 embedded newlines as well. You can also set the 's' flag, which causes
1309 a . to match newlines as well. (Both these flags can be changed inside
1310 a pattern using the same syntax used for the i flag above, BTW.)
1312 On the other hand, Vim's ^ and $ always match at embedded newlines, and
1313 you get two separate atoms, \%^ and \%$, which only match at the very
1314 start and end of the text, respectively. Vim solves the second problem
1315 by giving you the \_ "modifier": put it in front of a . or a character
1316 class, and they will match newlines as well.
1318 Finally, these constructs are unique to Perl:
1319 - execution of arbitrary code in the regex: (?{perl code})
1320 - conditional expressions: (?(condition)true-expr|false-expr)
1322 ...and these are unique to Vim:
1323 - changing the magic-ness of a pattern: \v \V \m \M
1324 (very useful for avoiding backslashitis)
1325 - sequence of optionally matching atoms: \%[atoms]
1326 - \& (which is to \| what "and" is to "or"; it forces several branches
1327 to match at one spot)
1328 - matching lines/columns by number: \%5l \%5c \%5v
1329 - setting the start and end of the match: \zs \ze
1331 ==============================================================================
1332 10. Highlighting matches *match-highlight*
1335 :mat[ch] {group} /{pattern}/
1336 Define a pattern to highlight in the current window. It will
1337 be highlighted with {group}. Example: >
1338 :highlight MyGroup ctermbg=green guibg=green
1339 :match MyGroup /TODO/
1340 < Instead of // any character can be used to mark the start and
1341 end of the {pattern}. Watch out for using special characters,
1342 such as '"' and '|'.
1344 {group} must exist at the moment this command is executed.
1346 The {group} highlighting still applies when a character is
1347 to be highlighted for 'hlsearch', as the highlighting for
1348 matches is given higher priority than that of 'hlsearch'.
1349 Syntax highlighting (see 'syntax') is also overruled by
1352 Note that highlighting the last used search pattern with
1353 'hlsearch' is used in all windows, while the pattern defined
1354 with ":match" only exists in the current window. It is kept
1355 when switching to another buffer.
1357 'ignorecase' does not apply, use |/\c| in the pattern to
1358 ignore case. Otherwise case is not ignored.
1360 'redrawtime' defines the maximum time searched for pattern
1363 When matching end-of-line and Vim redraws only part of the
1364 display you may get unexpected results. That is because Vim
1365 looks for a match in the line where redrawing starts.
1367 Also see |matcharg()| and |getmatches()|. The former returns
1368 the highlight group and pattern of a previous |:match|
1369 command. The latter returns a list with highlight groups and
1370 patterns defined by both |matchadd()| and |:match|.
1372 Highlighting matches using |:match| are limited to three
1373 matches (aside from |:match|, |:2match| and |:3match| are
1374 available). |matchadd()| does not have this limitation and in
1375 addition makes it possible to prioritize matches.
1377 Another example, which highlights all characters in virtual
1378 column 72 and more: >
1379 :highlight rightMargin term=bold ctermfg=blue guifg=blue
1380 :match rightMargin /.\%>72v/
1381 < To highlight all character that are in virtual column 7: >
1382 :highlight col8 ctermbg=grey guibg=grey
1383 :match col8 /\%<8v.\%>7v/
1384 < Note the use of two items to also match a character that
1385 occupies more than one virtual column, such as a TAB.
1389 Clear a previously defined match pattern.
1392 :2mat[ch] {group} /{pattern}/ *:2match*
1395 :3mat[ch] {group} /{pattern}/ *:3match*
1398 Just like |:match| above, but set a separate match. Thus
1399 there can be three matches active at the same time. The match
1400 with the lowest number has priority if several match at the
1402 The ":3match" command is used by the |matchparen| plugin. You
1403 are suggested to use ":match" for manual matching and
1404 ":2match" for another plugin.
1407 vim:tw=78:ts=8:ft=help:norl: