1*pattern.txt* For Vim version 8.0. Last change: 2017 Jun 05 2 3 4 VIM REFERENCE MANUAL by Bram Moolenaar 5 6 7Patterns and search commands *pattern-searches* 8 9The very basics can be found in section |03.9| of the user manual. A few more 10explanations are in chapter 27 |usr_27.txt|. 11 121. Search commands |search-commands| 132. The definition of a pattern |search-pattern| 143. Magic |/magic| 154. Overview of pattern items |pattern-overview| 165. Multi items |pattern-multi-items| 176. Ordinary atoms |pattern-atoms| 187. Ignoring case in a pattern |/ignorecase| 198. Composing characters |patterns-composing| 209. Compare with Perl patterns |perl-patterns| 2110. Highlighting matches |match-highlight| 22 23============================================================================== 241. Search commands *search-commands* 25 26 */* 27/{pattern}[/]<CR> Search forward for the [count]'th occurrence of 28 {pattern} |exclusive|. 29 30/{pattern}/{offset}<CR> Search forward for the [count]'th occurrence of 31 {pattern} and go |{offset}| lines up or down. 32 |linewise|. 33 34 */<CR>* 35/<CR> Search forward for the [count]'th occurrence of the 36 latest used pattern |last-pattern| with latest used 37 |{offset}|. 38 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. 42 43 *?* 44?{pattern}[?]<CR> Search backward for the [count]'th previous 45 occurrence of {pattern} |exclusive|. 46 47?{pattern}?{offset}<CR> Search backward for the [count]'th previous 48 occurrence of {pattern} and go |{offset}| lines up or 49 down |linewise|. 50 51 *?<CR>* 52?<CR> Search backward for the [count]'th occurrence of the 53 latest used pattern |last-pattern| with latest used 54 |{offset}|. 55 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. 59 60 *n* 61n Repeat the latest "/" or "?" [count] times. 62 If the cursor doesn't move the search is repeated with 63 count + 1. 64 |last-pattern| {Vi: no count} 65 66 *N* 67N Repeat the latest "/" or "?" [count] times in 68 opposite direction. |last-pattern| {Vi: no count} 69 70 *star* *E348* *E349* 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 76 current line 77 3. the non-blank word under the cursor 78 4. the first non-blank word after the cursor, 79 in the current line 80 Only whole keywords are searched for, like with the 81 command "/\<keyword\>". |exclusive| {not in Vi} 82 'ignorecase' is used, 'smartcase' is not. 83 84 *#* 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} 89 90 *gstar* 91g* 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} 94 95 *g#* 96g# 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} 99 100 *gd* 101gd 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). 116 {not in Vi} 117 118 *gD* 119gD 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} 124 125 *1gd* 1261gd Like "gd", but ignore matches inside a {} block that 127 ends before the cursor position. {not in Vi} 128 129 *1gD* 1301gD Like "gD", but ignore matches inside a {} block that 131 ends before the cursor position. {not in Vi} 132 133 *CTRL-C* 134CTRL-C Interrupt current (search) command. Use CTRL-Break on 135 MS-DOS |dos-CTRL-Break|. 136 In Normal mode, any pending command is aborted. 137 138 *:noh* *:nohlsearch* 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. 146 147While 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 149command with <CR> to actually position the cursor at the displayed match. Or 150use <Esc> to abandon the search. 151 152All matches for the last used search pattern will be highlighted if you set 153the 'hlsearch' option. This can be suspended with the |:nohlsearch| command. 154 155When no match is found you get the error: *E486* Pattern not found 156Note that for the |:global| command this behaves like a normal message, for Vi 157compatibility. For the |:s| command the "e" flag can be used to avoid the 158error message |:s_flags|. 159 160 *search-offset* *{offset}* 161These commands search for the specified pattern. With "/" and "?" an 162additional offset may be given. There are two types of offsets: line offsets 163and character offsets. {the character offsets are not in Vi} 164 165The 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 |//;| 176 177If a '-' or '+' is given but [num] is omitted, a count of one will be used. 178When including an offset with 'e', the search becomes inclusive (the 179character the cursor lands on is included in operations). 180 181Examples: 182 183pattern 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" 188 189If one of these commands is used after an operator, the characters between 190the cursor position before and after the search is affected. However, if a 191line offset is given, the whole lines between the two cursor positions are 192affected. 193 194An example of how to search for matches with a pattern and change the match 195with another word: > 196 /foo<CR> find "foo" 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 202 etc. 203< 204 *//;* *E386* 205A very special offset is ';' followed by another search command. For example: > 206 207 /test 1/;/test 208 /test.*/+1;?ing? 209 210The first one first finds the next occurrence of "test 1", and then the first 211occurrence of "test" after that. 212 213This 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 216 search command. 217- When an error occurs the cursor is not moved at all. 218 219 *last-pattern* 220The last used pattern and offset are remembered. They can be used to repeat 221the search, possibly in another direction or with another count. Note that 222two patterns are remembered: One for 'normal' search commands and one for the 223substitute command ":s". Each time an empty pattern is given, the previously 224used pattern is used. However, if there is no previous search command, a 225previous substitute pattern is used, if possible. 226 227The 'magic' option sticks with the last used pattern. If you change 'magic', 228this will not change how the last used pattern will be interpreted. 229The 'ignorecase' option does not do this. When 'ignorecase' is changed, it 230will result in the pattern to match other text. 231 232All matches for the last used search pattern will be highlighted if you set 233the 'hlsearch' option. 234 235To clear the last used search pattern: > 236 :let @/ = "" 237This will not set the pattern to an empty string, because that would match 238everywhere. The pattern is really cleared, like when starting Vim. 239 240The search usually skips matches that don't move the cursor. Whether the next 241match 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 245The unpredictability with the 'c' flag is caused by starting the search in the 246first column, skipping matches until one is found past the cursor position. 247 248When 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 250cursor position is used. 251 252In Vi the ":tag" command sets the last search pattern when the tag is searched 253for. In Vim this is not done, the previous search pattern is still remembered, 254unless the 't' flag is present in 'cpoptions'. The search pattern is always 255put in the search history. 256 257If the 'wrapscan' option is on (which is the default), searches wrap around 258the end of the buffer. If 'wrapscan' is not set, the backward search stops 259at 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 261not found" is given, and the cursor will not be moved. If 'wrapscan' is not 262set the message becomes "search hit BOTTOM without match" when searching 263forward, or "search hit TOP without match" when searching backward. If 264wrapscan 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 266TOP" is given when searching backwards or forwards respectively. This can be 267switched off by setting the 's' flag in the 'shortmess' option. The highlight 268method 'w' is used for this message (default: standout). 269 270 *search-range* 271You 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 273line 300: > 274 /\%>199l\%<300llimit 275Also see |/\%>l|. 276 277Another way is to use the ":substitute" command with the 'c' flag. Example: > 278 :.,300s/Pattern//gc 279This 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 281stop at this match, type 'n' to find the next match. 282 283The "*", "#", "g*" and "g#" commands look for a word near the cursor in this 284order, 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. 289The keyword may only contain letters and characters in 'iskeyword'. 290The WORD may contain any non-blanks (<Tab>s and/or <Space>s). 291Note that if you type with ten fingers, the characters are easy to remember: 292the "#" is under your left hand middle finger (search to the left and up) and 293the "*" is under your right hand middle finger (search to the right and down). 294(this depends on your keyboard layout though). 295 296============================================================================== 2972. The definition of a pattern *search-pattern* *pattern* *[pattern]* 298 *regular-expression* *regexp* *Pattern* 299 *E76* *E383* *E476* 300 301For starters, read chapter 27 of the user manual |usr_27.txt|. 302 303 */bar* */\bar* */pattern* 3041. 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. 307 308 pattern ::= branch 309 or branch \| branch 310 or branch \| branch \| branch 311 etc. 312 313 */branch* */\&* 3142. 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 316 position. Examples: 317 "foobeep\&..." matches "foo" in "foobeep". 318 ".*Peter\&.*Bob" matches in a line containing both "Peter" and "Bob" 319 320 branch ::= concat 321 or concat \& concat 322 or concat \& concat \& concat 323 etc. 324 325 */concat* 3263. 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". 329 330 concat ::= piece 331 or piece piece 332 or piece piece piece 333 etc. 334 335 */piece* 3364. 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|. 339 340 piece ::= atom 341 or atom multi 342 343 */atom* 3445. 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. 348 349 atom ::= ordinary-atom |/ordinary-atom| 350 or \( pattern \) |/\(| 351 or \%( pattern \) |/\%(| 352 or \z( pattern \) |/\z(| 353 354 355 */\%#=* *two-engines* *NFA* 356Vim includes two regexp engines: 3571. An old, backtracking engine that supports everything. 3582. A new, NFA engine that works much faster on some patterns, possibly slower 359 on some patterns. 360 361Vim will automatically select the right engine for you. However, if you run 362into a problem or want to specifically select one engine or the other, you can 363prepend one of the following to the pattern: 364 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. 369 370You can also use the 'regexpengine' option to change the default. 371 372 *E864* *E868* *E874* *E875* *E876* *E877* *E878* 373If selecting the NFA engine and it runs into something that is not implemented 374the pattern will not match. This is only useful when debugging Vim. 375 376============================================================================== 3773. Magic */magic* 378 379Some characters in the pattern are taken literally. They match with the same 380character in the text. When preceded with a backslash however, these 381characters get a special meaning. 382 383Other characters have a special meaning without a backslash. They need to be 384preceded with a backslash to match literally. 385 386If a character is taken literally or not depends on the 'magic' option and the 387items mentioned next. 388 */\m* */\M* 389Use of "\m" makes the pattern after it be interpreted as if 'magic' is set, 390ignoring the actual value of the 'magic' option. 391Use of "\M" makes the pattern after it be interpreted as if 'nomagic' is used. 392 */\v* */\V* 393Use 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" 395 396Use of "\V" means that in the pattern after it only the backslash and the 397terminating character (/ or ?) has a special meaning. "very nomagic" 398 399Examples: 400after: \v \m \M \V matches ~ 401 'magic' 'nomagic' 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 411 \{ { { { literal '{' 412 a a a a literal 'a' 413 414{only Vim supports \m, \M, \v and \V} 415 416It is recommended to always keep the 'magic' option at the default setting, 417which is 'magic'. This avoids portability problems. To make a pattern immune 418to the 'magic' option being set or not, put "\m" or "\M" at the start of the 419pattern. 420 421============================================================================== 4224. Overview of pattern items *pattern-overview* 423 *E865* *E866* *E867* *E869* 424 425Overview of multi items. */multi* *E61* *E62* 426More explanation and examples below, follow the links. *E64* *E871* 427 428 multi ~ 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 (*) 434 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 *) (*) 440 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 (*) 446 447 *E59* 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| (*) 453 454(*) {not in Vi} 455 456 457Overview of ordinary atoms. */ordinary-atom* 458More explanation and examples below, follow the links. 459 460 ordinary atom ~ 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| 482 483Character 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) 514 515 magic nomagic matches ~ 516|/\e| \e \e <Esc> 517|/\t| \t \t <Tab> 518|/\r| \r \r <CR> 519|/\b| \b \b <BS> 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 \(\) 524 ... 525|/\9| \9 \9 Like "\1", but uses ninth \(\) 526 *E68* 527|/\z1| \z1 \z1 only for syntax highlighting, see |:syn-ext-match| 528 ... 529|/\z1| \z9 \z9 only for syntax highlighting, see |:syn-ext-match| 530 531 x x a character with no special meaning matches itself 532 533|/[]| [] \[] any character specified inside the [] 534|/\%[]| \%[] \%[] a sequence of optionally matched atoms 535 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. 540 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| 547 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 553 \%U12345678) 554|/\%C| \%C \%C match any composing characters 555 556Example matches ~ 557\<\I\i* or 558\<\h\w* 559\<[a-zA-Z_][a-zA-Z0-9_]* 560 An identifier (e.g., in a C program). 561 562\(\.$\|\. \) A period followed by <EOL> or a space. 563 564[.!?][])"']*\($\|[ ]\) A search pattern that finds the end of a sentence, 565 with almost the same definition as the ")" command. 566 567cat\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. 570 571 572============================================================================== 5735. Multi items *pattern-multi-items* 574 575An atom can be followed by an indication of how many times the atom can be 576matched and in what way. This is called a multi. See |/multi| for an 577overview. 578 579 */star* */\star* 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" 587 in the buffer 588 589 Exception: When "*" is used at the start of the pattern or just after 590 "^" it matches the star character. 591 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 597 character at a time. 598 599 */\+* 600\+ Matches 1 or more of the preceding atom, as many as possible. {not in 601 Vi} 602 Example matches ~ 603 ^.\+$ any non-empty line 604 \s\+ white space of at least one character 605 606 */\=* 607\= Matches 0 or 1 of the preceding atom, as many as possible. {not in Vi} 608 Example matches ~ 609 foo\= "fo" and "foo" 610 611 */\?* 612\? Just like \=. Cannot be used when searching backwards with the "?" 613 command. {not in Vi} 614 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 *) 621 */\{-* 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} 628 629 n and m are positive decimal numbers or zero 630 *non-greedy* 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". 636 637 Example matches ~ 638 ab\{2,3}c "abbc" or "abbbc" 639 a\{5} "aaaaa" 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" 646 647 The } may optionally be preceded with a backslash: \{n,m\}. 648 649 */\@=* 650\@= Matches the preceding atom with zero width. {not in Vi} 651 Like "(?=pattern)" in Perl. 652 Example matches ~ 653 foo\(bar\)\@= "foo" in "foobar" 654 foo\(bar\)\@=foo nothing 655 */zero-width* 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 661 "bar" matched. 662 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 665 braces. 666 667 668 */\@!* 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. 672 Example matches ~ 673 foo\(bar\)\@! any "foo" not followed by "bar" 674 a.\{-}p\@! "a", "ap", "app", "appp", etc. not immediately 675 followed by a "p" 676 if \(\(then\)\@!.\)*$ "if " not followed by "then" 677 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. 684 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". 690 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". 697 698 */\@<=* 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. 702 Example matches ~ 703 \(an\_s\+\)\@<=file "file" after "an" and white space or an 704 end-of-line 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: 707 an\_s\+\zsfile 708 At least set a limit for the look-behind, see below. 709 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. 715 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 719 way around: 720 Bad example matches ~ 721 \%#=1\1\@<=,\([a-z]\+\) ",abc" in "abc,abc" 722 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: 725 Example matches ~ 726 \([a-z]\+\)\zs,\1 ",abc" in "abc,abc" 727 728\@123<= 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": 732 /<\@1<=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. 739 740 */\@<!* 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. 750 Example matches ~ 751 \(foo\)\@<!bar any "bar" that's not in "foobar" 752 \(\/\/.*\)\@<!in "in" which is not after "//" 753 754\@123<! 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 757 slow. 758 759 */\@>* 760\@> Matches the preceding atom like matching a whole pattern. {not in Vi} 761 Like "(?>pattern)" in Perl. 762 Example matches ~ 763 \(a*\)\@>a nothing (the "a*" takes all the "a"'s, there can't be 764 another one following) 765 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. 772 773 774============================================================================== 7756. Ordinary atoms *pattern-atoms* 776 777An ordinary atom can be: 778 779 */^* 780^ At beginning of pattern or after "\|", "\(", "\%(" or "\n": matches 781 start-of-line; at other positions, matches literal '^'. |/zero-width| 782 Example matches ~ 783 ^beep( the start of the C function "beep" (probably). 784 785 */\^* 786\^ Matches literal '^'. Can be used at any position in the pattern. 787 788 */\_^* 789\_^ Matches start-of-line. |/zero-width| Can be used at any position in 790 the pattern. 791 Example matches ~ 792 \_s*\_^foo white space and blank lines and then "foo" at 793 start-of-line 794 795 */$* 796$ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): 797 matches end-of-line <EOL>; at other positions, matches literal '$'. 798 |/zero-width| 799 800 */\$* 801\$ Matches literal '$'. Can be used at any position in the pattern. 802 803 */\_$* 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|. 807 Example matches ~ 808 foo\_$\_s* "foo" at end-of-line and following white space and 809 blank lines 810 811. (with 'nomagic': \.) */.* */\.* 812 Matches any single character, but not an end-of-line. 813 814 */\_.* 815\_. Matches any single character or end-of-line. 816 Careful: "\_.*" matches all text to the end of the buffer! 817 818 */\<* 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. 821 |/zero-width| 822 823 */\>* 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. 826 |/zero-width| 827 828 */\zs* 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| 831 Example: > 832 /^\s*\zsif 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: > 836 /\(.\{-}\zsFab\)\{3} 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} 840 */\ze* 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 844 branch is used. 845 Example: "end\ze\(if\|for\)" matches the "end" in "endif" and 846 "endfor". 847 This cannot be followed by a multi. |E888| 848 {not in Vi} {not available when compiled without the |+syntax| feature} 849 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: > 854 /\%^\_.\{-}\zsVIM 855< 856 */\%$* *end-of-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: > 860 /VIM\_.\{-}\%$ 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! 867 868 */\%V* 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 873 the pattern, e.g.: > 874 /\%Vfoo.*ba\%Vr 875< This also works if only "foo bar" was Visually selected. This: > 876 /\%Vfoo.*bar\%V 877< would match "foo bar" if the Visual selection continues after the "r". 878 Only works for the current buffer. 879 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: > 890 /\k*\%#\k* 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. 893 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: > 899 /.\%>'s.*\%<'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. 903 {not in Vi} 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 "\%#" |/\%#|. 907 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 916 wrong. 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. 921 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 932 wrong. 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: > 938 /\%>43c.\%<46c 939< Note that "\%<46c" matches in column 45 when the "." matches a byte in 940 column 44. 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 954 becomes wrong. 955 Example, to highlight all the characters after virtual column 72: > 956 /\%>72v.* 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: > 960 /^.*\%17v 961< Column 17 is not included, because this is a |/zero-width| match. To 962 include the column use: > 963 /^.*\%17v. 964< This command does the same thing, but also matches when there is no 965 character in column 17: > 966 /^.*\%<18v. 967< Note that without the "^" to anchor the match in the first column, 968 this will also highlight column 17: > 969 /.*\%17v 970< Column 17 is highlighted by 'hlsearch' because there is another match 971 where ".*" matches zero characters. 972< 973 974Character 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* 983 984NOTE: the above also work for multi-byte characters. The ones below only 985match ASCII characters, as indicated by the range. 986 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* 1006 1007 NOTE: Using the atom is faster than the [] form. 1008 1009 NOTE: 'ignorecase', "\c" and "\C" are not used by character classes. 1010 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 1016 end-of-line added 1017(end of character classes) 1018 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. 1026 1027~ matches the last given substitute string */~* */\~* 1028 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* 1032 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* 1037 ... */\3* 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 1041 first. 1042 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. 1046 {not in Vi} 1047 1048x A single character, with no special meaning, matches itself 1049 1050 */\* */\\* 1051\x A backslash followed by a single character, with no special meaning, 1052 is reserved for future expansions 1053 1054[] (with 'nomagic': \[]) */[]* */\[]* */\_[]* */collection* 1055\_[] 1056 A collection. This is a sequence of characters enclosed in brackets. 1057 It matches any single character in the collection. 1058 Example matches ~ 1059 [xyz] any 'x', 'y' or 'z' 1060 [a-zA-Z]$ any alphabetic character at the end of a line 1061 \c[a-z]$ same 1062 [А-яЁё] Russian alphabet (with utf-8 and cp1251) 1063 1064 */[\n]* 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. 1071 *E769* 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"! 1078 1079 *E944* *E945* 1080 If the sequence begins with "^", it matches any single character NOT 1081 in the collection: "[^xyz]" matches anything but 'x', 'y' and 'z'. 1082 - If two characters in the sequence are separated by '-', this is 1083 shorthand for the full list of ASCII characters between them. E.g., 1084 "[0-9]" matches any decimal digit. If the starting character exceeds 1085 the ending character, e.g. [c-a], E944 occurs. Non-ASCII characters 1086 can be used, but the character values must not be more than 256 apart 1087 in the old regexp engine. For example, searching by [\u3000-\u4000] 1088 after setting re=1 emits a E945 error. Prepending \%#=2 will fix it. 1089 - A character class expression is evaluated to the set of characters 1090 belonging to that character class. The following character classes 1091 are supported: 1092 Name Func Contents ~ 1093*[:alnum:]* [:alnum:] isalnum ASCII letters and digits 1094*[:alpha:]* [:alpha:] isalpha ASCII letters 1095*[:blank:]* [:blank:] space and tab 1096*[:cntrl:]* [:cntrl:] iscntrl ASCII control characters 1097*[:digit:]* [:digit:] decimal digits '0' to '9' 1098*[:graph:]* [:graph:] isgraph ASCII printable characters excluding 1099 space 1100*[:lower:]* [:lower:] (1) lowercase letters (all letters when 1101 'ignorecase' is used) 1102*[:print:]* [:print:] (2) printable characters including space 1103*[:punct:]* [:punct:] ispunct ASCII punctuation characters 1104*[:space:]* [:space:] whitespace characters: space, tab, CR, 1105 NL, vertical tab, form feed 1106*[:upper:]* [:upper:] (3) uppercase letters (all letters when 1107 'ignorecase' is used) 1108*[:xdigit:]* [:xdigit:] hexadecimal digits: 0-9, a-f, A-F 1109*[:return:]* [:return:] the <CR> character 1110*[:tab:]* [:tab:] the <Tab> character 1111*[:escape:]* [:escape:] the <Esc> character 1112*[:backspace:]* [:backspace:] the <BS> character 1113 The brackets in character class expressions are additional to the 1114 brackets delimiting a collection. For example, the following is a 1115 plausible pattern for a UNIX filename: "[-./[:alnum:]_~]\+" That is, 1116 a list of at least one character, each of which is either '-', '.', 1117 '/', alphabetic, numeric, '_' or '~'. 1118 These items only work for 8-bit characters, except [:lower:] and 1119 [:upper:] also work for multi-byte characters when using the new 1120 regexp engine. See |two-engines|. In the future these items may 1121 work for multi-byte characters. For now, to get all "alpha" 1122 characters you can use: [[:lower:][:upper:]]. 1123 1124 The "Func" column shows what library function is used. The 1125 implementation depends on the system. Otherwise: 1126 (1) Uses islower() for ASCII and Vim builtin rules for other 1127 characters when built with the |+multi_byte| feature. 1128 (2) Uses Vim builtin rules 1129 (3) As with (1) but using isupper() 1130 */[[=* *[==]* 1131 - An equivalence class. This means that characters are matched that 1132 have almost the same meaning, e.g., when ignoring accents. This 1133 only works for Unicode, latin1 and latin9. The form is: 1134 [=a=] 1135 */[[.* *[..]* 1136 - A collation element. This currently simply accepts a single 1137 character in the form: 1138 [.a.] 1139 */\]* 1140 - To include a literal ']', '^', '-' or '\' in the collection, put a 1141 backslash before it: "[xyz\]]", "[\^xyz]", "[xy\-z]" and "[xyz\\]". 1142 (Note: POSIX does not support the use of a backslash this way). For 1143 ']' you can also make it the first character (following a possible 1144 "^"): "[]xyz]" or "[^]xyz]" {not in Vi}. 1145 For '-' you can also make it the first or last character: "[-xyz]", 1146 "[^-xyz]" or "[xyz-]". For '\' you can also let it be followed by 1147 any character that's not in "^]-\bdertnoUux". "[\xyz]" matches '\', 1148 'x', 'y' and 'z'. It's better to use "\\" though, future expansions 1149 may use other characters after '\'. 1150 - Omitting the trailing ] is not considered an error. "[]" works like 1151 "[]]", it matches the ']' character. 1152 - The following translations are accepted when the 'l' flag is not 1153 included in 'cpoptions' {not in Vi}: 1154 \e <Esc> 1155 \t <Tab> 1156 \r <CR> (NOT end-of-line!) 1157 \b <BS> 1158 \n line break, see above |/[\n]| 1159 \d123 decimal number of character 1160 \o40 octal number of character up to 0377 1161 \x20 hexadecimal number of character up to 0xff 1162 \u20AC hex. number of multibyte character up to 0xffff 1163 \U1234 hex. number of multibyte character up to 0xffffffff 1164 NOTE: The other backslash codes mentioned above do not work inside 1165 []! 1166 - Matching with a collection can be slow, because each character in 1167 the text has to be compared with each character in the collection. 1168 Use one of the other atoms above when possible. Example: "\d" is 1169 much faster than "[0-9]" and matches the same characters. 1170 1171 */\%[]* *E69* *E70* *E369* 1172\%[] A sequence of optionally matched atoms. This always matches. 1173 It matches as much of the list of atoms it contains as possible. Thus 1174 it stops at the first atom that doesn't match. For example: > 1175 /r\%[ead] 1176< matches "r", "re", "rea" or "read". The longest that matches is used. 1177 To match the Ex command "function", where "fu" is required and 1178 "nction" is optional, this would work: > 1179 /\<fu\%[nction]\> 1180< The end-of-word atom "\>" is used to avoid matching "fu" in "full". 1181 It gets more complicated when the atoms are not ordinary characters. 1182 You don't often have to use it, but it is possible. Example: > 1183 /\<r\%[[eo]ad]\> 1184< Matches the words "r", "re", "ro", "rea", "roa", "read" and "road". 1185 There can be no \(\), \%(\) or \z(\) items inside the [] and \%[] does 1186 not nest. 1187 To include a "[" use "[[]" and for "]" use []]", e.g.,: > 1188 /index\%[[[]0[]]] 1189< matches "index" "index[", "index[0" and "index[0]". 1190 {not available when compiled without the |+syntax| feature} 1191 1192 */\%d* */\%x* */\%o* */\%u* */\%U* *E678* 1193 1194\%d123 Matches the character specified with a decimal number. Must be 1195 followed by a non-digit. 1196\%o40 Matches the character specified with an octal number up to 0377. 1197 Numbers below 040 must be followed by a non-octal digit or a non-digit. 1198\%x2a Matches the character specified with up to two hexadecimal characters. 1199\%u20AC Matches the character specified with up to four hexadecimal 1200 characters. 1201\%U1234abcd Matches the character specified with up to eight hexadecimal 1202 characters. 1203 1204============================================================================== 12057. Ignoring case in a pattern */ignorecase* 1206 1207If the 'ignorecase' option is on, the case of normal letters is ignored. 1208'smartcase' can be set to ignore case when the pattern contains lowercase 1209letters only. 1210 */\c* */\C* 1211When "\c" appears anywhere in the pattern, the whole pattern is handled like 1212'ignorecase' is on. The actual value of 'ignorecase' and 'smartcase' is 1213ignored. "\C" does the opposite: Force matching case for the whole pattern. 1214{only Vim supports \c and \C} 1215Note that 'ignorecase', "\c" and "\C" are not used for the character classes. 1216 1217Examples: 1218 pattern 'ignorecase' 'smartcase' matches ~ 1219 foo off - foo 1220 foo on - foo Foo FOO 1221 Foo on off foo Foo FOO 1222 Foo on on Foo 1223 \cfoo - - foo Foo FOO 1224 foo\C - - foo 1225 1226Technical detail: *NL-used-for-Nul* 1227<Nul> characters in the file are stored as <NL> in memory. In the display 1228they are shown as "^@". The translation is done when reading and writing 1229files. To match a <Nul> with a search pattern you can just enter CTRL-@ or 1230"CTRL-V 000". This is probably just what you expect. Internally the 1231character is replaced with a <NL> in the search pattern. What is unusual is 1232that typing CTRL-V CTRL-J also inserts a <NL>, thus also searches for a <Nul> 1233in the file. {Vi cannot handle <Nul> characters in the file at all} 1234 1235 *CR-used-for-NL* 1236When 'fileformat' is "mac", <NL> characters in the file are stored as <CR> 1237characters internally. In the text they are shown as "^J". Otherwise this 1238works similar to the usage of <NL> for a <Nul>. 1239 1240When working with expression evaluation, a <NL> character in the pattern 1241matches a <NL> in the string. The use of "\n" (backslash n) to match a <NL> 1242doesn't work there, it only works to match text in the buffer. 1243 1244 *pattern-multi-byte* 1245Patterns will also work with multi-byte characters, mostly as you would 1246expect. But invalid bytes may cause trouble, a pattern with an invalid byte 1247will probably never match. 1248 1249============================================================================== 12508. Composing characters *patterns-composing* 1251 1252 */\Z* 1253When "\Z" appears anywhere in the pattern, all composing characters are 1254ignored. Thus only the base characters need to match, the composing 1255characters may be different and the number of composing characters may differ. 1256Only relevant when 'encoding' is "utf-8". 1257Exception: If the pattern starts with one or more composing characters, these 1258must match. 1259 */\%C* 1260Use "\%C" to skip any composing characters. For example, the pattern "a" does 1261not match in "càt" (where the a has the composing character 0x0300), but 1262"a\%C" does. Note that this does not match "cát" (where the á is character 12630xe1, it does not have a compositing character). It does match "cat" (where 1264the a is just an a). 1265 1266When a composing character appears at the start of the pattern of after an 1267item that doesn't include the composing character, a match is found at any 1268character that includes this composing character. 1269 1270When using a dot and a composing character, this works the same as the 1271composing character by itself, except that it doesn't matter what comes before 1272this. 1273 1274The order of composing characters does not matter. Also, the text may have 1275more composing characters than the pattern, it still matches. But all 1276composing characters in the pattern must be found in the text. 1277 1278Suppose B is a base character and x and y are composing characters: 1279 pattern text match ~ 1280 Bxy Bxy yes (perfect match) 1281 Bxy Byx yes (order ignored) 1282 Bxy By no (x missing) 1283 Bxy Bx no (y missing) 1284 Bx Bx yes (perfect match) 1285 Bx By no (x missing) 1286 Bx Bxy yes (extra y ignored) 1287 Bx Byx yes (extra y ignored) 1288 1289============================================================================== 12909. Compare with Perl patterns *perl-patterns* 1291 1292Vim's regexes are most similar to Perl's, in terms of what you can do. The 1293difference between them is mostly just notation; here's a summary of where 1294they differ: 1295 1296Capability in Vimspeak in Perlspeak ~ 1297---------------------------------------------------------------- 1298force case insensitivity \c (?i) 1299force case sensitivity \C (?-i) 1300backref-less grouping \%(atom\) (?:atom) 1301conservative quantifiers \{-n,m} *?, +?, ??, {}? 13020-width match atom\@= (?=atom) 13030-width non-match atom\@! (?!atom) 13040-width preceding match atom\@<= (?<=atom) 13050-width preceding non-match atom\@<! (?<!atom) 1306match without retry atom\@> (?>atom) 1307 1308Vim and Perl handle newline characters inside a string a bit differently: 1309 1310In Perl, ^ and $ only match at the very beginning and end of the text, 1311by default, but you can set the 'm' flag, which lets them match at 1312embedded newlines as well. You can also set the 's' flag, which causes 1313a . to match newlines as well. (Both these flags can be changed inside 1314a pattern using the same syntax used for the i flag above, BTW.) 1315 1316On the other hand, Vim's ^ and $ always match at embedded newlines, and 1317you get two separate atoms, \%^ and \%$, which only match at the very 1318start and end of the text, respectively. Vim solves the second problem 1319by giving you the \_ "modifier": put it in front of a . or a character 1320class, and they will match newlines as well. 1321 1322Finally, these constructs are unique to Perl: 1323- execution of arbitrary code in the regex: (?{perl code}) 1324- conditional expressions: (?(condition)true-expr|false-expr) 1325 1326...and these are unique to Vim: 1327- changing the magic-ness of a pattern: \v \V \m \M 1328 (very useful for avoiding backslashitis) 1329- sequence of optionally matching atoms: \%[atoms] 1330- \& (which is to \| what "and" is to "or"; it forces several branches 1331 to match at one spot) 1332- matching lines/columns by number: \%5l \%5c \%5v 1333- setting the start and end of the match: \zs \ze 1334 1335============================================================================== 133610. Highlighting matches *match-highlight* 1337 1338 *:mat* *:match* 1339:mat[ch] {group} /{pattern}/ 1340 Define a pattern to highlight in the current window. It will 1341 be highlighted with {group}. Example: > 1342 :highlight MyGroup ctermbg=green guibg=green 1343 :match MyGroup /TODO/ 1344< Instead of // any character can be used to mark the start and 1345 end of the {pattern}. Watch out for using special characters, 1346 such as '"' and '|'. 1347 1348 {group} must exist at the moment this command is executed. 1349 1350 The {group} highlighting still applies when a character is 1351 to be highlighted for 'hlsearch', as the highlighting for 1352 matches is given higher priority than that of 'hlsearch'. 1353 Syntax highlighting (see 'syntax') is also overruled by 1354 matches. 1355 1356 Note that highlighting the last used search pattern with 1357 'hlsearch' is used in all windows, while the pattern defined 1358 with ":match" only exists in the current window. It is kept 1359 when switching to another buffer. 1360 1361 'ignorecase' does not apply, use |/\c| in the pattern to 1362 ignore case. Otherwise case is not ignored. 1363 1364 'redrawtime' defines the maximum time searched for pattern 1365 matches. 1366 1367 When matching end-of-line and Vim redraws only part of the 1368 display you may get unexpected results. That is because Vim 1369 looks for a match in the line where redrawing starts. 1370 1371 Also see |matcharg()| and |getmatches()|. The former returns 1372 the highlight group and pattern of a previous |:match| 1373 command. The latter returns a list with highlight groups and 1374 patterns defined by both |matchadd()| and |:match|. 1375 1376 Highlighting matches using |:match| are limited to three 1377 matches (aside from |:match|, |:2match| and |:3match| are 1378 available). |matchadd()| does not have this limitation and in 1379 addition makes it possible to prioritize matches. 1380 1381 Another example, which highlights all characters in virtual 1382 column 72 and more: > 1383 :highlight rightMargin term=bold ctermfg=blue guifg=blue 1384 :match rightMargin /.\%>72v/ 1385< To highlight all character that are in virtual column 7: > 1386 :highlight col8 ctermbg=grey guibg=grey 1387 :match col8 /\%<8v.\%>7v/ 1388< Note the use of two items to also match a character that 1389 occupies more than one virtual column, such as a TAB. 1390 1391:mat[ch] 1392:mat[ch] none 1393 Clear a previously defined match pattern. 1394 1395 1396:2mat[ch] {group} /{pattern}/ *:2match* 1397:2mat[ch] 1398:2mat[ch] none 1399:3mat[ch] {group} /{pattern}/ *:3match* 1400:3mat[ch] 1401:3mat[ch] none 1402 Just like |:match| above, but set a separate match. Thus 1403 there can be three matches active at the same time. The match 1404 with the lowest number has priority if several match at the 1405 same position. 1406 The ":3match" command is used by the |matchparen| plugin. You 1407 are suggested to use ":match" for manual matching and 1408 ":2match" for another plugin. 1409 1410 1411 vim:tw=78:ts=8:ft=help:norl: 1412