1*pattern.txt* For Vim version 8.2. Last change: 2021 May 02 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| 2211. Fuzzy matching |fuzzy-match| 23 24============================================================================== 251. Search commands *search-commands* 26 27 */* 28/{pattern}[/]<CR> Search forward for the [count]'th occurrence of 29 {pattern} |exclusive|. 30 31/{pattern}/{offset}<CR> Search forward for the [count]'th occurrence of 32 {pattern} and go |{offset}| lines up or down. 33 |linewise|. 34 35 */<CR>* 36/<CR> Search forward for the [count]'th occurrence of the 37 latest used pattern |last-pattern| with latest used 38 |{offset}|. 39 40//{offset}<CR> Search forward for the [count]'th occurrence of the 41 latest used pattern |last-pattern| with new 42 |{offset}|. If {offset} is empty no offset is used. 43 44 *?* 45?{pattern}[?]<CR> Search backward for the [count]'th previous 46 occurrence of {pattern} |exclusive|. 47 48?{pattern}?{offset}<CR> Search backward for the [count]'th previous 49 occurrence of {pattern} and go |{offset}| lines up or 50 down |linewise|. 51 52 *?<CR>* 53?<CR> Search backward for the [count]'th occurrence of the 54 latest used pattern |last-pattern| with latest used 55 |{offset}|. 56 57??{offset}<CR> Search backward for the [count]'th occurrence of the 58 latest used pattern |last-pattern| with new 59 |{offset}|. If {offset} is empty no offset is used. 60 61 *n* 62n Repeat the latest "/" or "?" [count] times. 63 If the cursor doesn't move the search is repeated with 64 count + 1. 65 |last-pattern| 66 67 *N* 68N Repeat the latest "/" or "?" [count] times in 69 opposite direction. |last-pattern| 70 71 *star* *E348* *E349* 72* Search forward for the [count]'th occurrence of the 73 word nearest to the cursor. The word used for the 74 search is the first of: 75 1. the keyword under the cursor |'iskeyword'| 76 2. the first keyword after the cursor, in the 77 current line 78 3. the non-blank word under the cursor 79 4. the first non-blank word after the cursor, 80 in the current line 81 Only whole keywords are searched for, like with the 82 command "/\<keyword\>". |exclusive| 83 'ignorecase' is used, 'smartcase' is not. 84 85 *#* 86# Same as "*", but search backward. The pound sign 87 (character 163) also works. If the "#" key works as 88 backspace, try using "stty erase <BS>" before starting 89 Vim (<BS> is CTRL-H or a real backspace). 90 91 *gstar* 92g* Like "*", but don't put "\<" and "\>" around the word. 93 This makes the search also find matches that are not a 94 whole word. 95 96 *g#* 97g# Like "#", but don't put "\<" and "\>" around the word. 98 This makes the search also find matches that are not a 99 whole word. 100 101 *gd* 102gd Goto local Declaration. When the cursor is on a local 103 variable, this command will jump to its declaration. 104 First Vim searches for the start of the current 105 function, just like "[[". If it is not found the 106 search stops in line 1. If it is found, Vim goes back 107 until a blank line is found. From this position Vim 108 searches for the keyword under the cursor, like with 109 "*", but lines that look like a comment are ignored 110 (see 'comments' option). 111 Note that this is not guaranteed to work, Vim does not 112 really check the syntax, it only searches for a match 113 with the keyword. If included files also need to be 114 searched use the commands listed in |include-search|. 115 After this command |n| searches forward for the next 116 match (not backward). 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. 124 125 *1gd* 1261gd Like "gd", but ignore matches inside a {} block that 127 ends before the cursor position. 128 129 *1gD* 1301gD Like "gD", but ignore matches inside a {} block that 131 ends before the cursor position. 132 133 *CTRL-C* 134CTRL-C Interrupt current (search) command. Use CTRL-Break on 135 MS-Windows |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 'shortmess' does not include the "S" flag, Vim will automatically show an 156index, on which the cursor is. This can look like this: > 157 158 [1/5] Cursor is on first of 5 matches. 159 [1/>99] Cursor is on first of more than 99 matches. 160 [>99/>99] Cursor is after 99 match of more than 99 matches. 161 [?/??] Unknown how many matches exists, generating the 162 statistics was aborted because of search timeout. 163 164Note: the count does not take offset into account. 165 166When no match is found you get the error: *E486* Pattern not found 167Note that for the |:global| command this behaves like a normal message, for Vi 168compatibility. For the |:s| command the "e" flag can be used to avoid the 169error message |:s_flags|. 170 171 *search-offset* *{offset}* 172These commands search for the specified pattern. With "/" and "?" an 173additional offset may be given. There are two types of offsets: line offsets 174and character offsets. 175 176The offset gives the cursor position relative to the found match: 177 [num] [num] lines downwards, in column 1 178 +[num] [num] lines downwards, in column 1 179 -[num] [num] lines upwards, in column 1 180 e[+num] [num] characters to the right of the end of the match 181 e[-num] [num] characters to the left of the end of the match 182 s[+num] [num] characters to the right of the start of the match 183 s[-num] [num] characters to the left of the start of the match 184 b[+num] [num] identical to s[+num] above (mnemonic: begin) 185 b[-num] [num] identical to s[-num] above (mnemonic: begin) 186 ;{pattern} perform another search, see |//;| 187 188If a '-' or '+' is given but [num] is omitted, a count of one will be used. 189When including an offset with 'e', the search becomes inclusive (the 190character the cursor lands on is included in operations). 191 192Examples: 193 194pattern cursor position ~ 195/test/+1 one line below "test", in column 1 196/test/e on the last t of "test" 197/test/s+2 on the 's' of "test" 198/test/b-3 three characters before "test" 199 200If one of these commands is used after an operator, the characters between 201the cursor position before and after the search is affected. However, if a 202line offset is given, the whole lines between the two cursor positions are 203affected. 204 205An example of how to search for matches with a pattern and change the match 206with another word: > 207 /foo<CR> find "foo" 208 c//e<CR> change until end of match 209 bar<Esc> type replacement 210 //<CR> go to start of next match 211 c//e<CR> change until end of match 212 beep<Esc> type another replacement 213 etc. 214< 215 *//;* *E386* 216A very special offset is ';' followed by another search command. For example: > 217 218 /test 1/;/test 219 /test.*/+1;?ing? 220 221The first one first finds the next occurrence of "test 1", and then the first 222occurrence of "test" after that. 223 224This is like executing two search commands after each other, except that: 225- It can be used as a single motion command after an operator. 226- The direction for a following "n" or "N" command comes from the first 227 search command. 228- When an error occurs the cursor is not moved at all. 229 230 *last-pattern* 231The last used pattern and offset are remembered. They can be used to repeat 232the search, possibly in another direction or with another count. Note that 233two patterns are remembered: One for "normal" search commands and one for the 234substitute command ":s". Each time an empty pattern is given, the previously 235used pattern is used. However, if there is no previous search command, a 236previous substitute pattern is used, if possible. 237 238The 'magic' option sticks with the last used pattern. If you change 'magic', 239this will not change how the last used pattern will be interpreted. 240The 'ignorecase' option does not do this. When 'ignorecase' is changed, it 241will result in the pattern to match other text. 242 243All matches for the last used search pattern will be highlighted if you set 244the 'hlsearch' option. 245 246To clear the last used search pattern: > 247 :let @/ = "" 248This will not set the pattern to an empty string, because that would match 249everywhere. The pattern is really cleared, like when starting Vim. 250 251The search usually skips matches that don't move the cursor. Whether the next 252match is found at the next character or after the skipped match depends on the 253'c' flag in 'cpoptions'. See |cpo-c|. 254 with 'c' flag: "/..." advances 1 to 3 characters 255 without 'c' flag: "/..." advances 1 character 256The unpredictability with the 'c' flag is caused by starting the search in the 257first column, skipping matches until one is found past the cursor position. 258 259When searching backwards, searching starts at the start of the line, using the 260'c' flag in 'cpoptions' as described above. Then the last match before the 261cursor position is used. 262 263In Vi the ":tag" command sets the last search pattern when the tag is searched 264for. In Vim this is not done, the previous search pattern is still remembered, 265unless the 't' flag is present in 'cpoptions'. The search pattern is always 266put in the search history. 267 268If the 'wrapscan' option is on (which is the default), searches wrap around 269the end of the buffer. If 'wrapscan' is not set, the backward search stops 270at the beginning and the forward search stops at the end of the buffer. If 271'wrapscan' is set and the pattern was not found the error message "pattern 272not found" is given, and the cursor will not be moved. If 'wrapscan' is not 273set the message becomes "search hit BOTTOM without match" when searching 274forward, or "search hit TOP without match" when searching backward. If 275wrapscan is set and the search wraps around the end of the file the message 276"search hit TOP, continuing at BOTTOM" or "search hit BOTTOM, continuing at 277TOP" is given when searching backwards or forwards respectively. This can be 278switched off by setting the 's' flag in the 'shortmess' option. The highlight 279method 'w' is used for this message (default: standout). 280 281 *search-range* 282You can limit the search command "/" to a certain range of lines by including 283\%>l items. For example, to match the word "limit" below line 199 and above 284line 300: > 285 /\%>199l\%<300llimit 286Also see |/\%>l|. 287 288Another way is to use the ":substitute" command with the 'c' flag. Example: > 289 :.,300s/Pattern//gc 290This command will search from the cursor position until line 300 for 291"Pattern". At the match, you will be asked to type a character. Type 'q' to 292stop at this match, type 'n' to find the next match. 293 294The "*", "#", "g*" and "g#" commands look for a word near the cursor in this 295order, the first one that is found is used: 296- The keyword currently under the cursor. 297- The first keyword to the right of the cursor, in the same line. 298- The WORD currently under the cursor. 299- The first WORD to the right of the cursor, in the same line. 300The keyword may only contain letters and characters in 'iskeyword'. 301The WORD may contain any non-blanks (<Tab>s and/or <Space>s). 302Note that if you type with ten fingers, the characters are easy to remember: 303the "#" is under your left hand middle finger (search to the left and up) and 304the "*" is under your right hand middle finger (search to the right and down). 305(this depends on your keyboard layout though). 306 307 *E956* 308In very rare cases a regular expression is used recursively. This can happen 309when executing a pattern takes a long time and when checking for messages on 310channels a callback is invoked that also uses a pattern or an autocommand is 311triggered. In most cases this should be fine, but if a pattern is in use when 312it's used again it fails. Usually this means there is something wrong with 313the pattern. 314 315============================================================================== 3162. The definition of a pattern *search-pattern* *pattern* *[pattern]* 317 *regular-expression* *regexp* *Pattern* 318 *E76* *E383* *E476* 319 320For starters, read chapter 27 of the user manual |usr_27.txt|. 321 322 */bar* */\bar* */pattern* 3231. A pattern is one or more branches, separated by "\|". It matches anything 324 that matches one of the branches. Example: "foo\|beep" matches "foo" and 325 matches "beep". If more than one branch matches, the first one is used. 326 327 pattern ::= branch 328 or branch \| branch 329 or branch \| branch \| branch 330 etc. 331 332 */branch* */\&* 3332. A branch is one or more concats, separated by "\&". It matches the last 334 concat, but only if all the preceding concats also match at the same 335 position. Examples: 336 "foobeep\&..." matches "foo" in "foobeep". 337 ".*Peter\&.*Bob" matches in a line containing both "Peter" and "Bob" 338 339 branch ::= concat 340 or concat \& concat 341 or concat \& concat \& concat 342 etc. 343 344 */concat* 3453. A concat is one or more pieces, concatenated. It matches a match for the 346 first piece, followed by a match for the second piece, etc. Example: 347 "f[0-9]b", first matches "f", then a digit and then "b". 348 349 concat ::= piece 350 or piece piece 351 or piece piece piece 352 etc. 353 354 */piece* 3554. A piece is an atom, possibly followed by a multi, an indication of how many 356 times the atom can be matched. Example: "a*" matches any sequence of "a" 357 characters: "", "a", "aa", etc. See |/multi|. 358 359 piece ::= atom 360 or atom multi 361 362 */atom* 3635. An atom can be one of a long list of items. Many atoms match one character 364 in the text. It is often an ordinary character or a character class. 365 Parentheses can be used to make a pattern into an atom. The "\z(\)" 366 construct is only for syntax highlighting. 367 368 atom ::= ordinary-atom |/ordinary-atom| 369 or \( pattern \) |/\(| 370 or \%( pattern \) |/\%(| 371 or \z( pattern \) |/\z(| 372 373 374 */\%#=* *two-engines* *NFA* 375Vim includes two regexp engines: 3761. An old, backtracking engine that supports everything. 3772. A new, NFA engine that works much faster on some patterns, possibly slower 378 on some patterns. 379 380Vim will automatically select the right engine for you. However, if you run 381into a problem or want to specifically select one engine or the other, you can 382prepend one of the following to the pattern: 383 384 \%#=0 Force automatic selection. Only has an effect when 385 'regexpengine' has been set to a non-zero value. 386 \%#=1 Force using the old engine. 387 \%#=2 Force using the NFA engine. 388 389You can also use the 'regexpengine' option to change the default. 390 391 *E864* *E868* *E874* *E875* *E876* *E877* *E878* 392If selecting the NFA engine and it runs into something that is not implemented 393the pattern will not match. This is only useful when debugging Vim. 394 395============================================================================== 3963. Magic */magic* 397 398Some characters in the pattern, such as letters, are taken literally. They 399match exactly the same character in the text. When preceded with a backslash 400however, these characters may get a special meaning. For example, "a" matches 401the letter "a", while "\a" matches any alphabetic character. 402 403Other characters have a special meaning without a backslash. They need to be 404preceded with a backslash to match literally. For example "." matches any 405character while "\." matches a dot. 406 407If a character is taken literally or not depends on the 'magic' option and the 408items in the pattern mentioned next. The 'magic' option should always be set, 409but it can be switched off for Vi compatibility. We mention the effect of 410'nomagic' here for completeness, but we recommend against using that. 411 */\m* */\M* 412Use of "\m" makes the pattern after it be interpreted as if 'magic' is set, 413ignoring the actual value of the 'magic' option. 414Use of "\M" makes the pattern after it be interpreted as if 'nomagic' is used. 415 */\v* */\V* 416Use of "\v" means that after it, all ASCII characters except '0'-'9', 'a'-'z', 417'A'-'Z' and '_' have special meaning: "very magic" 418 419Use of "\V" means that after it, only a backslash and the terminating 420character (usually / or ?) have special meaning: "very nomagic" 421 422Examples: 423after: \v \m \M \V matches ~ 424 'magic' 'nomagic' 425 a a a a literal 'a' 426 \a \a \a \a any alphabetic character 427 . . \. \. any character 428 \. \. . . literal dot 429 $ $ $ \$ end-of-line 430 * * \* \* any number of the previous atom 431 ~ ~ \~ \~ latest substitute string 432 () \(\) \(\) \(\) group as an atom 433 | \| \| \| nothing: separates alternatives 434 \\ \\ \\ \\ literal backslash 435 \{ { { { literal curly brace 436 437{only Vim supports \m, \M, \v and \V} 438 439If you want to you can make a pattern immune to the 'magic' option being set 440or not by putting "\m" or "\M" at the start of the pattern. 441 442============================================================================== 4434. Overview of pattern items *pattern-overview* 444 *E865* *E866* *E867* *E869* 445 446Overview of multi items. */multi* *E61* *E62* 447More explanation and examples below, follow the links. *E64* *E871* 448 449 multi ~ 450 'magic' 'nomagic' matches of the preceding atom ~ 451|/star| * \* 0 or more as many as possible 452|/\+| \+ \+ 1 or more as many as possible 453|/\=| \= \= 0 or 1 as many as possible 454|/\?| \? \? 0 or 1 as many as possible 455 456|/\{| \{n,m} \{n,m} n to m as many as possible 457 \{n} \{n} n exactly 458 \{n,} \{n,} at least n as many as possible 459 \{,m} \{,m} 0 to m as many as possible 460 \{} \{} 0 or more as many as possible (same as *) 461 462|/\{-| \{-n,m} \{-n,m} n to m as few as possible 463 \{-n} \{-n} n exactly 464 \{-n,} \{-n,} at least n as few as possible 465 \{-,m} \{-,m} 0 to m as few as possible 466 \{-} \{-} 0 or more as few as possible 467 468 *E59* 469|/\@>| \@> \@> 1, like matching a whole pattern 470|/\@=| \@= \@= nothing, requires a match |/zero-width| 471|/\@!| \@! \@! nothing, requires NO match |/zero-width| 472|/\@<=| \@<= \@<= nothing, requires a match behind |/zero-width| 473|/\@<!| \@<! \@<! nothing, requires NO match behind |/zero-width| 474 475 476Overview of ordinary atoms. */ordinary-atom* 477More explanation and examples below, follow the links. 478 479 ordinary atom ~ 480 magic nomagic matches ~ 481|/^| ^ ^ start-of-line (at start of pattern) |/zero-width| 482|/\^| \^ \^ literal '^' 483|/\_^| \_^ \_^ start-of-line (used anywhere) |/zero-width| 484|/$| $ $ end-of-line (at end of pattern) |/zero-width| 485|/\$| \$ \$ literal '$' 486|/\_$| \_$ \_$ end-of-line (used anywhere) |/zero-width| 487|/.| . \. any single character (not an end-of-line) 488|/\_.| \_. \_. any single character or end-of-line 489|/\<| \< \< beginning of a word |/zero-width| 490|/\>| \> \> end of a word |/zero-width| 491|/\zs| \zs \zs anything, sets start of match 492|/\ze| \ze \ze anything, sets end of match 493|/\%^| \%^ \%^ beginning of file |/zero-width| *E71* 494|/\%$| \%$ \%$ end of file |/zero-width| 495|/\%V| \%V \%V inside Visual area |/zero-width| 496|/\%#| \%# \%# cursor position |/zero-width| 497|/\%'m| \%'m \%'m mark m position |/zero-width| 498|/\%l| \%23l \%23l in line 23 |/zero-width| 499|/\%c| \%23c \%23c in column 23 |/zero-width| 500|/\%v| \%23v \%23v in virtual column 23 |/zero-width| 501 502Character classes: */character-classes* 503 magic nomagic matches ~ 504|/\i| \i \i identifier character (see 'isident' option) 505|/\I| \I \I like "\i", but excluding digits 506|/\k| \k \k keyword character (see 'iskeyword' option) 507|/\K| \K \K like "\k", but excluding digits 508|/\f| \f \f file name character (see 'isfname' option) 509|/\F| \F \F like "\f", but excluding digits 510|/\p| \p \p printable character (see 'isprint' option) 511|/\P| \P \P like "\p", but excluding digits 512|/\s| \s \s whitespace character: <Space> and <Tab> 513|/\S| \S \S non-whitespace character; opposite of \s 514|/\d| \d \d digit: [0-9] 515|/\D| \D \D non-digit: [^0-9] 516|/\x| \x \x hex digit: [0-9A-Fa-f] 517|/\X| \X \X non-hex digit: [^0-9A-Fa-f] 518|/\o| \o \o octal digit: [0-7] 519|/\O| \O \O non-octal digit: [^0-7] 520|/\w| \w \w word character: [0-9A-Za-z_] 521|/\W| \W \W non-word character: [^0-9A-Za-z_] 522|/\h| \h \h head of word character: [A-Za-z_] 523|/\H| \H \H non-head of word character: [^A-Za-z_] 524|/\a| \a \a alphabetic character: [A-Za-z] 525|/\A| \A \A non-alphabetic character: [^A-Za-z] 526|/\l| \l \l lowercase character: [a-z] 527|/\L| \L \L non-lowercase character: [^a-z] 528|/\u| \u \u uppercase character: [A-Z] 529|/\U| \U \U non-uppercase character [^A-Z] 530|/\_| \_x \_x where x is any of the characters above: character 531 class with end-of-line included 532(end of character classes) 533 534 magic nomagic matches ~ 535|/\e| \e \e <Esc> 536|/\t| \t \t <Tab> 537|/\r| \r \r <CR> 538|/\b| \b \b <BS> 539|/\n| \n \n end-of-line 540|/~| ~ \~ last given substitute string 541|/\1| \1 \1 same string as matched by first \(\) 542|/\2| \2 \2 Like "\1", but uses second \(\) 543 ... 544|/\9| \9 \9 Like "\1", but uses ninth \(\) 545 *E68* 546|/\z1| \z1 \z1 only for syntax highlighting, see |:syn-ext-match| 547 ... 548|/\z1| \z9 \z9 only for syntax highlighting, see |:syn-ext-match| 549 550 x x a character with no special meaning matches itself 551 552|/[]| [] \[] any character specified inside the [] 553|/\%[]| \%[] \%[] a sequence of optionally matched atoms 554 555|/\c| \c \c ignore case, do not use the 'ignorecase' option 556|/\C| \C \C match case, do not use the 'ignorecase' option 557|/\Z| \Z \Z ignore differences in Unicode "combining characters". 558 Useful when searching voweled Hebrew or Arabic text. 559 560 magic nomagic matches ~ 561|/\m| \m \m 'magic' on for the following chars in the pattern 562|/\M| \M \M 'magic' off for the following chars in the pattern 563|/\v| \v \v the following chars in the pattern are "very magic" 564|/\V| \V \V the following chars in the pattern are "very nomagic" 565|/\%#=| \%#=1 \%#=1 select regexp engine |/zero-width| 566 567|/\%d| \%d \%d match specified decimal character (eg \%d123) 568|/\%x| \%x \%x match specified hex character (eg \%x2a) 569|/\%o| \%o \%o match specified octal character (eg \%o040) 570|/\%u| \%u \%u match specified multibyte character (eg \%u20ac) 571|/\%U| \%U \%U match specified large multibyte character (eg 572 \%U12345678) 573|/\%C| \%C \%C match any composing characters 574 575Example matches ~ 576\<\I\i* or 577\<\h\w* 578\<[a-zA-Z_][a-zA-Z0-9_]* 579 An identifier (e.g., in a C program). 580 581\(\.$\|\. \) A period followed by <EOL> or a space. 582 583[.!?][])"']*\($\|[ ]\) A search pattern that finds the end of a sentence, 584 with almost the same definition as the ")" command. 585 586cat\Z Both "cat" and "càt" ("a" followed by 0x0300) 587 Does not match "càt" (character 0x00e0), even 588 though it may look the same. 589 590 591============================================================================== 5925. Multi items *pattern-multi-items* 593 594An atom can be followed by an indication of how many times the atom can be 595matched and in what way. This is called a multi. See |/multi| for an 596overview. 597 598 */star* */\star* 599* (use \* when 'magic' is not set) 600 Matches 0 or more of the preceding atom, as many as possible. 601 Example 'nomagic' matches ~ 602 a* a\* "", "a", "aa", "aaa", etc. 603 .* \.\* anything, also an empty string, no end-of-line 604 \_.* \_.\* everything up to the end of the buffer 605 \_.*END \_.\*END everything up to and including the last "END" 606 in the buffer 607 608 Exception: When "*" is used at the start of the pattern or just after 609 "^" it matches the star character. 610 611 Be aware that repeating "\_." can match a lot of text and take a long 612 time. For example, "\_.*END" matches all text from the current 613 position to the last occurrence of "END" in the file. Since the "*" 614 will match as many as possible, this first skips over all lines until 615 the end of the file and then tries matching "END", backing up one 616 character at a time. 617 618 */\+* 619\+ Matches 1 or more of the preceding atom, as many as possible. 620 Example matches ~ 621 ^.\+$ any non-empty line 622 \s\+ white space of at least one character 623 624 */\=* 625\= Matches 0 or 1 of the preceding atom, as many as possible. 626 Example matches ~ 627 foo\= "fo" and "foo" 628 629 */\?* 630\? Just like \=. Cannot be used when searching backwards with the "?" 631 command. 632 633 */\{* *E60* *E554* *E870* 634\{n,m} Matches n to m of the preceding atom, as many as possible 635\{n} Matches n of the preceding atom 636\{n,} Matches at least n of the preceding atom, as many as possible 637\{,m} Matches 0 to m of the preceding atom, as many as possible 638\{} Matches 0 or more of the preceding atom, as many as possible (like *) 639 */\{-* 640\{-n,m} matches n to m of the preceding atom, as few as possible 641\{-n} matches n of the preceding atom 642\{-n,} matches at least n of the preceding atom, as few as possible 643\{-,m} matches 0 to m of the preceding atom, as few as possible 644\{-} matches 0 or more of the preceding atom, as few as possible 645 646 n and m are positive decimal numbers or zero 647 *non-greedy* 648 If a "-" appears immediately after the "{", then a shortest match 649 first algorithm is used (see example below). In particular, "\{-}" is 650 the same as "*" but uses the shortest match first algorithm. BUT: A 651 match that starts earlier is preferred over a shorter match: "a\{-}b" 652 matches "aaab" in "xaaab". 653 654 Example matches ~ 655 ab\{2,3}c "abbc" or "abbbc" 656 a\{5} "aaaaa" 657 ab\{2,}c "abbc", "abbbc", "abbbbc", etc. 658 ab\{,3}c "ac", "abc", "abbc" or "abbbc" 659 a[bc]\{3}d "abbbd", "abbcd", "acbcd", "acccd", etc. 660 a\(bc\)\{1,2}d "abcd" or "abcbcd" 661 a[bc]\{-}[cd] "abc" in "abcd" 662 a[bc]*[cd] "abcd" in "abcd" 663 664 The } may optionally be preceded with a backslash: \{n,m\}. 665 666 */\@=* 667\@= Matches the preceding atom with zero width. 668 Like "(?=pattern)" in Perl. 669 Example matches ~ 670 foo\(bar\)\@= "foo" in "foobar" 671 foo\(bar\)\@=foo nothing 672 */zero-width* 673 When using "\@=" (or "^", "$", "\<", "\>") no characters are included 674 in the match. These items are only used to check if a match can be 675 made. This can be tricky, because a match with following items will 676 be done in the same position. The last example above will not match 677 "foobarfoo", because it tries match "foo" in the same position where 678 "bar" matched. 679 680 Note that using "\&" works the same as using "\@=": "foo\&.." is the 681 same as "\(foo\)\@=..". But using "\&" is easier, you don't need the 682 parentheses. 683 684 685 */\@!* 686\@! Matches with zero width if the preceding atom does NOT match at the 687 current position. |/zero-width| 688 Like "(?!pattern)" in Perl. 689 Example matches ~ 690 foo\(bar\)\@! any "foo" not followed by "bar" 691 a.\{-}p\@! "a", "ap", "app", "appp", etc. not immediately 692 followed by a "p" 693 if \(\(then\)\@!.\)*$ "if " not followed by "then" 694 695 Using "\@!" is tricky, because there are many places where a pattern 696 does not match. "a.*p\@!" will match from an "a" to the end of the 697 line, because ".*" can match all characters in the line and the "p" 698 doesn't match at the end of the line. "a.\{-}p\@!" will match any 699 "a", "ap", "app", etc. that isn't followed by a "p", because the "." 700 can match a "p" and "p\@!" doesn't match after that. 701 702 You can't use "\@!" to look for a non-match before the matching 703 position: "\(foo\)\@!bar" will match "bar" in "foobar", because at the 704 position where "bar" matches, "foo" does not match. To avoid matching 705 "foobar" you could use "\(foo\)\@!...bar", but that doesn't match a 706 bar at the start of a line. Use "\(foo\)\@<!bar". 707 708 Useful example: to find "foo" in a line that does not contain "bar": > 709 /^\%(.*bar\)\@!.*\zsfoo 710< This pattern first checks that there is not a single position in the 711 line where "bar" matches. If ".*bar" matches somewhere the \@! will 712 reject the pattern. When there is no match any "foo" will be found. 713 The "\zs" is to have the match start just before "foo". 714 715 */\@<=* 716\@<= Matches with zero width if the preceding atom matches just before what 717 follows. |/zero-width| 718 Like "(?<=pattern)" in Perl, but Vim allows non-fixed-width patterns. 719 Example matches ~ 720 \(an\_s\+\)\@<=file "file" after "an" and white space or an 721 end-of-line 722 For speed it's often much better to avoid this multi. Try using "\zs" 723 instead |/\zs|. To match the same as the above example: 724 an\_s\+\zsfile 725 At least set a limit for the look-behind, see below. 726 727 "\@<=" and "\@<!" check for matches just before what follows. 728 Theoretically these matches could start anywhere before this position. 729 But to limit the time needed, only the line where what follows matches 730 is searched, and one line before that (if there is one). This should 731 be sufficient to match most things and not be too slow. 732 733 In the old regexp engine the part of the pattern after "\@<=" and 734 "\@<!" are checked for a match first, thus things like "\1" don't work 735 to reference \(\) inside the preceding atom. It does work the other 736 way around: 737 Bad example matches ~ 738 \%#=1\1\@<=,\([a-z]\+\) ",abc" in "abc,abc" 739 740 However, the new regexp engine works differently, it is better to not 741 rely on this behavior, do not use \@<= if it can be avoided: 742 Example matches ~ 743 \([a-z]\+\)\zs,\1 ",abc" in "abc,abc" 744 745\@123<= 746 Like "\@<=" but only look back 123 bytes. This avoids trying lots 747 of matches that are known to fail and make executing the pattern very 748 slow. Example, check if there is a "<" just before "span": 749 /<\@1<=span 750 This will try matching "<" only one byte before "span", which is the 751 only place that works anyway. 752 After crossing a line boundary, the limit is relative to the end of 753 the line. Thus the characters at the start of the line with the match 754 are not counted (this is just to keep it simple). 755 The number zero is the same as no limit. 756 757 */\@<!* 758\@<! Matches with zero width if the preceding atom does NOT match just 759 before what follows. Thus this matches if there is no position in the 760 current or previous line where the atom matches such that it ends just 761 before what follows. |/zero-width| 762 Like "(?<!pattern)" in Perl, but Vim allows non-fixed-width patterns. 763 The match with the preceding atom is made to end just before the match 764 with what follows, thus an atom that ends in ".*" will work. 765 Warning: This can be slow (because many positions need to be checked 766 for a match). Use a limit if you can, see below. 767 Example matches ~ 768 \(foo\)\@<!bar any "bar" that's not in "foobar" 769 \(\/\/.*\)\@<!in "in" which is not after "//" 770 771\@123<! 772 Like "\@<!" but only look back 123 bytes. This avoids trying lots of 773 matches that are known to fail and make executing the pattern very 774 slow. 775 776 */\@>* 777\@> Matches the preceding atom like matching a whole pattern. 778 Like "(?>pattern)" in Perl. 779 Example matches ~ 780 \(a*\)\@>a nothing (the "a*" takes all the "a"'s, there can't be 781 another one following) 782 783 This matches the preceding atom as if it was a pattern by itself. If 784 it doesn't match, there is no retry with shorter sub-matches or 785 anything. Observe this difference: "a*b" and "a*ab" both match 786 "aaab", but in the second case the "a*" matches only the first two 787 "a"s. "\(a*\)\@>ab" will not match "aaab", because the "a*" matches 788 the "aaa" (as many "a"s as possible), thus the "ab" can't match. 789 790 791============================================================================== 7926. Ordinary atoms *pattern-atoms* 793 794An ordinary atom can be: 795 796 */^* 797^ At beginning of pattern or after "\|", "\(", "\%(" or "\n": matches 798 start-of-line; at other positions, matches literal '^'. |/zero-width| 799 Example matches ~ 800 ^beep( the start of the C function "beep" (probably). 801 802 */\^* 803\^ Matches literal '^'. Can be used at any position in the pattern, but 804 not inside []. 805 806 */\_^* 807\_^ Matches start-of-line. |/zero-width| Can be used at any position in 808 the pattern, but not inside []. 809 Example matches ~ 810 \_s*\_^foo white space and blank lines and then "foo" at 811 start-of-line 812 813 */$* 814$ At end of pattern or in front of "\|", "\)" or "\n" ('magic' on): 815 matches end-of-line <EOL>; at other positions, matches literal '$'. 816 |/zero-width| 817 818 */\$* 819\$ Matches literal '$'. Can be used at any position in the pattern, but 820 not inside []. 821 822 */\_$* 823\_$ Matches end-of-line. |/zero-width| Can be used at any position in the 824 pattern, but not inside []. Note that "a\_$b" never matches, since 825 "b" cannot match an end-of-line. Use "a\nb" instead |/\n|. 826 Example matches ~ 827 foo\_$\_s* "foo" at end-of-line and following white space and 828 blank lines 829 830. (with 'nomagic': \.) */.* */\.* 831 Matches any single character, but not an end-of-line. 832 833 */\_.* 834\_. Matches any single character or end-of-line. 835 Careful: "\_.*" matches all text to the end of the buffer! 836 837 */\<* 838\< Matches the beginning of a word: The next char is the first char of a 839 word. The 'iskeyword' option specifies what is a word character. 840 |/zero-width| 841 842 */\>* 843\> Matches the end of a word: The previous char is the last char of a 844 word. The 'iskeyword' option specifies what is a word character. 845 |/zero-width| 846 847 */\zs* 848\zs Matches at any position, but not inside [], and sets the start of the 849 match there: The next char is the first char of the whole match. 850 |/zero-width| 851 Example: > 852 /^\s*\zsif 853< matches an "if" at the start of a line, ignoring white space. 854 Can be used multiple times, the last one encountered in a matching 855 branch is used. Example: > 856 /\(.\{-}\zsFab\)\{3} 857< Finds the third occurrence of "Fab". 858 This cannot be followed by a multi. *E888* 859 {not available when compiled without the |+syntax| feature} 860 */\ze* 861\ze Matches at any position, but not inside [], and sets the end of the 862 match there: The previous char is the last char of the whole match. 863 |/zero-width| 864 Can be used multiple times, the last one encountered in a matching 865 branch is used. 866 Example: "end\ze\(if\|for\)" matches the "end" in "endif" and 867 "endfor". 868 This cannot be followed by a multi. |E888| 869 {not available when compiled without the |+syntax| feature} 870 871 */\%^* *start-of-file* 872\%^ Matches start of the file. When matching with a string, matches the 873 start of the string. 874 For example, to find the first "VIM" in a file: > 875 /\%^\_.\{-}\zsVIM 876< 877 */\%$* *end-of-file* 878\%$ Matches end of the file. When matching with a string, matches the 879 end of the string. 880 Note that this does NOT find the last "VIM" in a file: > 881 /VIM\_.\{-}\%$ 882< It will find the next VIM, because the part after it will always 883 match. This one will find the last "VIM" in the file: > 884 /VIM\ze\(\(VIM\)\@!\_.\)*\%$ 885< This uses |/\@!| to ascertain that "VIM" does NOT match in any 886 position after the first "VIM". 887 Searching from the end of the file backwards is easier! 888 889 */\%V* 890\%V Match inside the Visual area. When Visual mode has already been 891 stopped match in the area that |gv| would reselect. 892 This is a |/zero-width| match. To make sure the whole pattern is 893 inside the Visual area put it at the start and just before the end of 894 the pattern, e.g.: > 895 /\%Vfoo.*ba\%Vr 896< This also works if only "foo bar" was Visually selected. This: > 897 /\%Vfoo.*bar\%V 898< would match "foo bar" if the Visual selection continues after the "r". 899 Only works for the current buffer. 900 901 */\%#* *cursor-position* 902\%# Matches with the cursor position. Only works when matching in a 903 buffer displayed in a window. 904 WARNING: When the cursor is moved after the pattern was used, the 905 result becomes invalid. Vim doesn't automatically update the matches. 906 This is especially relevant for syntax highlighting and 'hlsearch'. 907 In other words: When the cursor moves the display isn't updated for 908 this change. An update is done for lines which are changed (the whole 909 line is updated) or when using the |CTRL-L| command (the whole screen 910 is updated). Example, to highlight the word under the cursor: > 911 /\k*\%#\k* 912< When 'hlsearch' is set and you move the cursor around and make changes 913 this will clearly show when the match is updated or not. 914 915 */\%'m* */\%<'m* */\%>'m* 916\%'m Matches with the position of mark m. 917\%<'m Matches before the position of mark m. 918\%>'m Matches after the position of mark m. 919 Example, to highlight the text from mark 's to 'e: > 920 /.\%>'s.*\%<'e.. 921< Note that two dots are required to include mark 'e in the match. That 922 is because "\%<'e" matches at the character before the 'e mark, and 923 since it's a |/zero-width| match it doesn't include that character. 924 WARNING: When the mark is moved after the pattern was used, the result 925 becomes invalid. Vim doesn't automatically update the matches. 926 Similar to moving the cursor for "\%#" |/\%#|. 927 928 */\%l* */\%>l* */\%<l* *E951* 929\%23l Matches in a specific line. 930\%<23l Matches above a specific line (lower line number). 931\%>23l Matches below a specific line (higher line number). 932 These three can be used to match specific lines in a buffer. The "23" 933 can be any line number. The first line is 1. 934 WARNING: When inserting or deleting lines Vim does not automatically 935 update the matches. This means Syntax highlighting quickly becomes 936 wrong. 937 Example, to highlight the line where the cursor currently is: > 938 :exe '/\%' . line(".") . 'l.*' 939< When 'hlsearch' is set and you move the cursor around and make changes 940 this will clearly show when the match is updated or not. 941 942 */\%c* */\%>c* */\%<c* 943\%23c Matches in a specific column. 944\%<23c Matches before a specific column. 945\%>23c Matches after a specific column. 946 These three can be used to match specific columns in a buffer or 947 string. The "23" can be any column number. The first column is 1. 948 Actually, the column is the byte number (thus it's not exactly right 949 for multibyte characters). 950 WARNING: When inserting or deleting text Vim does not automatically 951 update the matches. This means Syntax highlighting quickly becomes 952 wrong. 953 Example, to highlight the column where the cursor currently is: > 954 :exe '/\%' . col(".") . 'c' 955< When 'hlsearch' is set and you move the cursor around and make changes 956 this will clearly show when the match is updated or not. 957 Example for matching a single byte in column 44: > 958 /\%>43c.\%<46c 959< Note that "\%<46c" matches in column 45 when the "." matches a byte in 960 column 44. 961 */\%v* */\%>v* */\%<v* 962\%23v Matches in a specific virtual column. 963\%<23v Matches before a specific virtual column. 964\%>23v Matches after a specific virtual column. 965 These three can be used to match specific virtual columns in a buffer 966 or string. When not matching with a buffer in a window, the option 967 values of the current window are used (e.g., 'tabstop'). 968 The "23" can be any column number. The first column is 1. 969 Note that some virtual column positions will never match, because they 970 are halfway through a tab or other character that occupies more than 971 one screen character. 972 WARNING: When inserting or deleting text Vim does not automatically 973 update highlighted matches. This means Syntax highlighting quickly 974 becomes wrong. 975 Example, to highlight all the characters after virtual column 72: > 976 /\%>72v.* 977< When 'hlsearch' is set and you move the cursor around and make changes 978 this will clearly show when the match is updated or not. 979 To match the text up to column 17: > 980 /^.*\%17v 981< Column 17 is not included, because this is a |/zero-width| match. To 982 include the column use: > 983 /^.*\%17v. 984< This command does the same thing, but also matches when there is no 985 character in column 17: > 986 /^.*\%<18v. 987< Note that without the "^" to anchor the match in the first column, 988 this will also highlight column 17: > 989 /.*\%17v 990< Column 17 is highlighted by 'hlsearch' because there is another match 991 where ".*" matches zero characters. 992< 993 994Character classes: 995\i identifier character (see 'isident' option) */\i* 996\I like "\i", but excluding digits */\I* 997\k keyword character (see 'iskeyword' option) */\k* 998\K like "\k", but excluding digits */\K* 999\f file name character (see 'isfname' option) */\f* 1000\F like "\f", but excluding digits */\F* 1001\p printable character (see 'isprint' option) */\p* 1002\P like "\p", but excluding digits */\P* 1003 1004NOTE: the above also work for multibyte characters. The ones below only 1005match ASCII characters, as indicated by the range. 1006 1007 *whitespace* *white-space* 1008\s whitespace character: <Space> and <Tab> */\s* 1009\S non-whitespace character; opposite of \s */\S* 1010\d digit: [0-9] */\d* 1011\D non-digit: [^0-9] */\D* 1012\x hex digit: [0-9A-Fa-f] */\x* 1013\X non-hex digit: [^0-9A-Fa-f] */\X* 1014\o octal digit: [0-7] */\o* 1015\O non-octal digit: [^0-7] */\O* 1016\w word character: [0-9A-Za-z_] */\w* 1017\W non-word character: [^0-9A-Za-z_] */\W* 1018\h head of word character: [A-Za-z_] */\h* 1019\H non-head of word character: [^A-Za-z_] */\H* 1020\a alphabetic character: [A-Za-z] */\a* 1021\A non-alphabetic character: [^A-Za-z] */\A* 1022\l lowercase character: [a-z] */\l* 1023\L non-lowercase character: [^a-z] */\L* 1024\u uppercase character: [A-Z] */\u* 1025\U non-uppercase character: [^A-Z] */\U* 1026 1027 NOTE: Using the atom is faster than the [] form. 1028 1029 NOTE: 'ignorecase', "\c" and "\C" are not used by character classes. 1030 1031 */\_* *E63* */\_i* */\_I* */\_k* */\_K* */\_f* */\_F* 1032 */\_p* */\_P* */\_s* */\_S* */\_d* */\_D* */\_x* */\_X* 1033 */\_o* */\_O* */\_w* */\_W* */\_h* */\_H* */\_a* */\_A* 1034 */\_l* */\_L* */\_u* */\_U* 1035\_x Where "x" is any of the characters above: The character class with 1036 end-of-line added 1037(end of character classes) 1038 1039\e matches <Esc> */\e* 1040\t matches <Tab> */\t* 1041\r matches <CR> */\r* 1042\b matches <BS> */\b* 1043\n matches an end-of-line */\n* 1044 When matching in a string instead of buffer text a literal newline 1045 character is matched. 1046 1047~ matches the last given substitute string */~* */\~* 1048 1049\(\) A pattern enclosed by escaped parentheses. */\(* */\(\)* */\)* 1050 E.g., "\(^a\)" matches 'a' at the start of a line. 1051 *E51* *E54* *E55* *E872* *E873* 1052 1053\1 Matches the same string that was matched by */\1* *E65* 1054 the first sub-expression in \( and \). 1055 Example: "\([a-z]\).\1" matches "ata", "ehe", "tot", etc. 1056\2 Like "\1", but uses second sub-expression, */\2* 1057 ... */\3* 1058\9 Like "\1", but uses ninth sub-expression. */\9* 1059 Note: The numbering of groups is done based on which "\(" comes first 1060 in the pattern (going left to right), NOT based on what is matched 1061 first. 1062 1063\%(\) A pattern enclosed by escaped parentheses. */\%(\)* */\%(* *E53* 1064 Just like \(\), but without counting it as a sub-expression. This 1065 allows using more groups and it's a little bit faster. 1066 1067x A single character, with no special meaning, matches itself 1068 1069 */\* */\\* 1070\x A backslash followed by a single character, with no special meaning, 1071 is reserved for future expansions 1072 1073[] (with 'nomagic': \[]) */[]* */\[]* */\_[]* */collection* 1074\_[] 1075 A collection. This is a sequence of characters enclosed in square 1076 brackets. It matches any single character in the collection. 1077 Example matches ~ 1078 [xyz] any 'x', 'y' or 'z' 1079 [a-zA-Z]$ any alphabetic character at the end of a line 1080 \c[a-z]$ same 1081 [А-яЁё] Russian alphabet (with utf-8 and cp1251) 1082 1083 */[\n]* 1084 With "\_" prepended the collection also includes the end-of-line. 1085 The same can be done by including "\n" in the collection. The 1086 end-of-line is also matched when the collection starts with "^"! Thus 1087 "\_[^ab]" matches the end-of-line and any character but "a" and "b". 1088 This makes it Vi compatible: Without the "\_" or "\n" the collection 1089 does not match an end-of-line. 1090 *E769* 1091 When the ']' is not there Vim will not give an error message but 1092 assume no collection is used. Useful to search for '['. However, you 1093 do get E769 for internal searching. And be aware that in a 1094 `:substitute` command the whole command becomes the pattern. E.g. 1095 ":s/[/x/" searches for "[/x" and replaces it with nothing. It does 1096 not search for "[" and replaces it with "x"! 1097 1098 *E944* *E945* 1099 If the sequence begins with "^", it matches any single character NOT 1100 in the collection: "[^xyz]" matches anything but 'x', 'y' and 'z'. 1101 - If two characters in the sequence are separated by '-', this is 1102 shorthand for the full list of ASCII characters between them. E.g., 1103 "[0-9]" matches any decimal digit. If the starting character exceeds 1104 the ending character, e.g. [c-a], E944 occurs. Non-ASCII characters 1105 can be used, but the character values must not be more than 256 apart 1106 in the old regexp engine. For example, searching by [\u3000-\u4000] 1107 after setting re=1 emits a E945 error. Prepending \%#=2 will fix it. 1108 - A character class expression is evaluated to the set of characters 1109 belonging to that character class. The following character classes 1110 are supported: 1111 Name Func Contents ~ 1112*[:alnum:]* [:alnum:] isalnum ASCII letters and digits 1113*[:alpha:]* [:alpha:] isalpha ASCII letters 1114*[:blank:]* [:blank:] space and tab 1115*[:cntrl:]* [:cntrl:] iscntrl ASCII control characters 1116*[:digit:]* [:digit:] decimal digits '0' to '9' 1117*[:graph:]* [:graph:] isgraph ASCII printable characters excluding 1118 space 1119*[:lower:]* [:lower:] (1) lowercase letters (all letters when 1120 'ignorecase' is used) 1121*[:print:]* [:print:] (2) printable characters including space 1122*[:punct:]* [:punct:] ispunct ASCII punctuation characters 1123*[:space:]* [:space:] whitespace characters: space, tab, CR, 1124 NL, vertical tab, form feed 1125*[:upper:]* [:upper:] (3) uppercase letters (all letters when 1126 'ignorecase' is used) 1127*[:xdigit:]* [:xdigit:] hexadecimal digits: 0-9, a-f, A-F 1128*[:return:]* [:return:] the <CR> character 1129*[:tab:]* [:tab:] the <Tab> character 1130*[:escape:]* [:escape:] the <Esc> character 1131*[:backspace:]* [:backspace:] the <BS> character 1132*[:ident:]* [:ident:] identifier character (same as "\i") 1133*[:keyword:]* [:keyword:] keyword character (same as "\k") 1134*[:fname:]* [:fname:] file name character (same as "\f") 1135 The square brackets in character class expressions are additional to 1136 the square brackets delimiting a collection. For example, the 1137 following is a plausible pattern for a UNIX filename: 1138 "[-./[:alnum:]_~]\+". That is, a list of at least one character, 1139 each of which is either '-', '.', '/', alphabetic, numeric, '_' or 1140 '~'. 1141 These items only work for 8-bit characters, except [:lower:] and 1142 [:upper:] also work for multibyte characters when using the new 1143 regexp engine. See |two-engines|. In the future these items may 1144 work for multibyte characters. For now, to get all "alpha" 1145 characters you can use: [[:lower:][:upper:]]. 1146 1147 The "Func" column shows what library function is used. The 1148 implementation depends on the system. Otherwise: 1149 (1) Uses islower() for ASCII and Vim builtin rules for other 1150 characters. 1151 (2) Uses Vim builtin rules 1152 (3) As with (1) but using isupper() 1153 */[[=* *[==]* 1154 - An equivalence class. This means that characters are matched that 1155 have almost the same meaning, e.g., when ignoring accents. This 1156 only works for Unicode, latin1 and latin9. The form is: 1157 [=a=] 1158 */[[.* *[..]* 1159 - A collation element. This currently simply accepts a single 1160 character in the form: 1161 [.a.] 1162 */\]* 1163 - To include a literal ']', '^', '-' or '\' in the collection, put a 1164 backslash before it: "[xyz\]]", "[\^xyz]", "[xy\-z]" and "[xyz\\]". 1165 (Note: POSIX does not support the use of a backslash this way). For 1166 ']' you can also make it the first character (following a possible 1167 "^"): "[]xyz]" or "[^]xyz]". 1168 For '-' you can also make it the first or last character: "[-xyz]", 1169 "[^-xyz]" or "[xyz-]". For '\' you can also let it be followed by 1170 any character that's not in "^]-\bdertnoUux". "[\xyz]" matches '\', 1171 'x', 'y' and 'z'. It's better to use "\\" though, future expansions 1172 may use other characters after '\'. 1173 - Omitting the trailing ] is not considered an error. "[]" works like 1174 "[]]", it matches the ']' character. 1175 - The following translations are accepted when the 'l' flag is not 1176 included in 'cpoptions': 1177 \e <Esc> 1178 \t <Tab> 1179 \r <CR> (NOT end-of-line!) 1180 \b <BS> 1181 \n line break, see above |/[\n]| 1182 \d123 decimal number of character 1183 \o40 octal number of character up to 0o377 1184 \x20 hexadecimal number of character up to 0xff 1185 \u20AC hex. number of multibyte character up to 0xffff 1186 \U1234 hex. number of multibyte character up to 0xffffffff 1187 NOTE: The other backslash codes mentioned above do not work inside 1188 []! 1189 - Matching with a collection can be slow, because each character in 1190 the text has to be compared with each character in the collection. 1191 Use one of the other atoms above when possible. Example: "\d" is 1192 much faster than "[0-9]" and matches the same characters. However, 1193 the new |NFA| regexp engine deals with this better than the old one. 1194 1195 */\%[]* *E69* *E70* *E369* 1196\%[] A sequence of optionally matched atoms. This always matches. 1197 It matches as much of the list of atoms it contains as possible. Thus 1198 it stops at the first atom that doesn't match. For example: > 1199 /r\%[ead] 1200< matches "r", "re", "rea" or "read". The longest that matches is used. 1201 To match the Ex command "function", where "fu" is required and 1202 "nction" is optional, this would work: > 1203 /\<fu\%[nction]\> 1204< The end-of-word atom "\>" is used to avoid matching "fu" in "full". 1205 It gets more complicated when the atoms are not ordinary characters. 1206 You don't often have to use it, but it is possible. Example: > 1207 /\<r\%[[eo]ad]\> 1208< Matches the words "r", "re", "ro", "rea", "roa", "read" and "road". 1209 There can be no \(\), \%(\) or \z(\) items inside the [] and \%[] does 1210 not nest. 1211 To include a "[" use "[[]" and for "]" use []]", e.g.,: > 1212 /index\%[[[]0[]]] 1213< matches "index" "index[", "index[0" and "index[0]". 1214 {not available when compiled without the |+syntax| feature} 1215 1216 */\%d* */\%x* */\%o* */\%u* */\%U* *E678* 1217 1218\%d123 Matches the character specified with a decimal number. Must be 1219 followed by a non-digit. 1220\%o40 Matches the character specified with an octal number up to 0o377. 1221 Numbers below 0o40 must be followed by a non-octal digit or a 1222 non-digit. 1223\%x2a Matches the character specified with up to two hexadecimal characters. 1224\%u20AC Matches the character specified with up to four hexadecimal 1225 characters. 1226\%U1234abcd Matches the character specified with up to eight hexadecimal 1227 characters, up to 0x7fffffff 1228 1229============================================================================== 12307. Ignoring case in a pattern */ignorecase* 1231 1232If the 'ignorecase' option is on, the case of normal letters is ignored. 1233'smartcase' can be set to ignore case when the pattern contains lowercase 1234letters only. 1235 */\c* */\C* 1236When "\c" appears anywhere in the pattern, the whole pattern is handled like 1237'ignorecase' is on. The actual value of 'ignorecase' and 'smartcase' is 1238ignored. "\C" does the opposite: Force matching case for the whole pattern. 1239{only Vim supports \c and \C} 1240Note that 'ignorecase', "\c" and "\C" are not used for the character classes. 1241 1242Examples: 1243 pattern 'ignorecase' 'smartcase' matches ~ 1244 foo off - foo 1245 foo on - foo Foo FOO 1246 Foo on off foo Foo FOO 1247 Foo on on Foo 1248 \cfoo - - foo Foo FOO 1249 foo\C - - foo 1250 1251Technical detail: *NL-used-for-Nul* 1252<Nul> characters in the file are stored as <NL> in memory. In the display 1253they are shown as "^@". The translation is done when reading and writing 1254files. To match a <Nul> with a search pattern you can just enter CTRL-@ or 1255"CTRL-V 000". This is probably just what you expect. Internally the 1256character is replaced with a <NL> in the search pattern. What is unusual is 1257that typing CTRL-V CTRL-J also inserts a <NL>, thus also searches for a <Nul> 1258in the file. 1259 1260 *CR-used-for-NL* 1261When 'fileformat' is "mac", <NL> characters in the file are stored as <CR> 1262characters internally. In the text they are shown as "^J". Otherwise this 1263works similar to the usage of <NL> for a <Nul>. 1264 1265When working with expression evaluation, a <NL> character in the pattern 1266matches a <NL> in the string. The use of "\n" (backslash n) to match a <NL> 1267doesn't work there, it only works to match text in the buffer. 1268 1269 *pattern-multi-byte* *pattern-multibyte* 1270Patterns will also work with multibyte characters, mostly as you would 1271expect. But invalid bytes may cause trouble, a pattern with an invalid byte 1272will probably never match. 1273 1274============================================================================== 12758. Composing characters *patterns-composing* 1276 1277 */\Z* 1278When "\Z" appears anywhere in the pattern, all composing characters are 1279ignored. Thus only the base characters need to match, the composing 1280characters may be different and the number of composing characters may differ. 1281Only relevant when 'encoding' is "utf-8". 1282Exception: If the pattern starts with one or more composing characters, these 1283must match. 1284 */\%C* 1285Use "\%C" to skip any composing characters. For example, the pattern "a" does 1286not match in "càt" (where the a has the composing character 0x0300), but 1287"a\%C" does. Note that this does not match "cát" (where the á is character 12880xe1, it does not have a compositing character). It does match "cat" (where 1289the a is just an a). 1290 1291When a composing character appears at the start of the pattern or after an 1292item that doesn't include the composing character, a match is found at any 1293character that includes this composing character. 1294 1295When using a dot and a composing character, this works the same as the 1296composing character by itself, except that it doesn't matter what comes before 1297this. 1298 1299The order of composing characters does not matter. Also, the text may have 1300more composing characters than the pattern, it still matches. But all 1301composing characters in the pattern must be found in the text. 1302 1303Suppose B is a base character and x and y are composing characters: 1304 pattern text match ~ 1305 Bxy Bxy yes (perfect match) 1306 Bxy Byx yes (order ignored) 1307 Bxy By no (x missing) 1308 Bxy Bx no (y missing) 1309 Bx Bx yes (perfect match) 1310 Bx By no (x missing) 1311 Bx Bxy yes (extra y ignored) 1312 Bx Byx yes (extra y ignored) 1313 1314============================================================================== 13159. Compare with Perl patterns *perl-patterns* 1316 1317Vim's regexes are most similar to Perl's, in terms of what you can do. The 1318difference between them is mostly just notation; here's a summary of where 1319they differ: 1320 1321Capability in Vimspeak in Perlspeak ~ 1322---------------------------------------------------------------- 1323force case insensitivity \c (?i) 1324force case sensitivity \C (?-i) 1325backref-less grouping \%(atom\) (?:atom) 1326conservative quantifiers \{-n,m} *?, +?, ??, {}? 13270-width match atom\@= (?=atom) 13280-width non-match atom\@! (?!atom) 13290-width preceding match atom\@<= (?<=atom) 13300-width preceding non-match atom\@<! (?<!atom) 1331match without retry atom\@> (?>atom) 1332 1333Vim and Perl handle newline characters inside a string a bit differently: 1334 1335In Perl, ^ and $ only match at the very beginning and end of the text, 1336by default, but you can set the 'm' flag, which lets them match at 1337embedded newlines as well. You can also set the 's' flag, which causes 1338a . to match newlines as well. (Both these flags can be changed inside 1339a pattern using the same syntax used for the i flag above, BTW.) 1340 1341On the other hand, Vim's ^ and $ always match at embedded newlines, and 1342you get two separate atoms, \%^ and \%$, which only match at the very 1343start and end of the text, respectively. Vim solves the second problem 1344by giving you the \_ "modifier": put it in front of a . or a character 1345class, and they will match newlines as well. 1346 1347Finally, these constructs are unique to Perl: 1348- execution of arbitrary code in the regex: (?{perl code}) 1349- conditional expressions: (?(condition)true-expr|false-expr) 1350 1351...and these are unique to Vim: 1352- changing the magic-ness of a pattern: \v \V \m \M 1353 (very useful for avoiding backslashitis) 1354- sequence of optionally matching atoms: \%[atoms] 1355- \& (which is to \| what "and" is to "or"; it forces several branches 1356 to match at one spot) 1357- matching lines/columns by number: \%5l \%5c \%5v 1358- setting the start and end of the match: \zs \ze 1359 1360============================================================================== 136110. Highlighting matches *match-highlight* 1362 1363 *:mat* *:match* 1364:mat[ch] {group} /{pattern}/ 1365 Define a pattern to highlight in the current window. It will 1366 be highlighted with {group}. Example: > 1367 :highlight MyGroup ctermbg=green guibg=green 1368 :match MyGroup /TODO/ 1369< Instead of // any character can be used to mark the start and 1370 end of the {pattern}. Watch out for using special characters, 1371 such as '"' and '|'. 1372 1373 {group} must exist at the moment this command is executed. 1374 1375 The {group} highlighting still applies when a character is 1376 to be highlighted for 'hlsearch', as the highlighting for 1377 matches is given higher priority than that of 'hlsearch'. 1378 Syntax highlighting (see 'syntax') is also overruled by 1379 matches. 1380 1381 Note that highlighting the last used search pattern with 1382 'hlsearch' is used in all windows, while the pattern defined 1383 with ":match" only exists in the current window. It is kept 1384 when switching to another buffer. 1385 1386 'ignorecase' does not apply, use |/\c| in the pattern to 1387 ignore case. Otherwise case is not ignored. 1388 1389 'redrawtime' defines the maximum time searched for pattern 1390 matches. 1391 1392 When matching end-of-line and Vim redraws only part of the 1393 display you may get unexpected results. That is because Vim 1394 looks for a match in the line where redrawing starts. 1395 1396 Also see |matcharg()| and |getmatches()|. The former returns 1397 the highlight group and pattern of a previous |:match| 1398 command. The latter returns a list with highlight groups and 1399 patterns defined by both |matchadd()| and |:match|. 1400 1401 Highlighting matches using |:match| are limited to three 1402 matches (aside from |:match|, |:2match| and |:3match| are 1403 available). |matchadd()| does not have this limitation and in 1404 addition makes it possible to prioritize matches. 1405 1406 Another example, which highlights all characters in virtual 1407 column 72 and more: > 1408 :highlight rightMargin term=bold ctermfg=blue guifg=blue 1409 :match rightMargin /.\%>72v/ 1410< To highlight all character that are in virtual column 7: > 1411 :highlight col8 ctermbg=grey guibg=grey 1412 :match col8 /\%<8v.\%>7v/ 1413< Note the use of two items to also match a character that 1414 occupies more than one virtual column, such as a TAB. 1415 1416:mat[ch] 1417:mat[ch] none 1418 Clear a previously defined match pattern. 1419 1420 1421:2mat[ch] {group} /{pattern}/ *:2match* 1422:2mat[ch] 1423:2mat[ch] none 1424:3mat[ch] {group} /{pattern}/ *:3match* 1425:3mat[ch] 1426:3mat[ch] none 1427 Just like |:match| above, but set a separate match. Thus 1428 there can be three matches active at the same time. The match 1429 with the lowest number has priority if several match at the 1430 same position. 1431 The ":3match" command is used by the |matchparen| plugin. You 1432 are suggested to use ":match" for manual matching and 1433 ":2match" for another plugin. 1434 1435============================================================================== 143611. Fuzzy matching *fuzzy-match* 1437 1438Fuzzy matching refers to matching strings using a non-exact search string. 1439Fuzzy matching will match a string, if all the characters in the search string 1440are present anywhere in the string in the same order. Case is ignored. In a 1441matched string, other characters can be present between two consecutive 1442characters in the search string. If the search string has multiple words, then 1443each word is matched separately. So the words in the search string can be 1444present in any order in a string. 1445 1446Fuzzy matching assigns a score for each matched string based on the following 1447criteria: 1448 - The number of sequentially matching characters. 1449 - The number of characters (distance) between two consecutive matching 1450 characters. 1451 - Matches at the beginning of a word 1452 - Matches after a camel case character or a path separator or a hyphen. 1453 - The number of unmatched characters in a string. 1454The matching string with the highest score is returned first. 1455 1456For example, when you search for the "get pat" string using fuzzy matching, it 1457will match the strings "GetPattern", "PatternGet", "getPattern", "patGetter", 1458"getSomePattern", "MatchpatternGet" etc. 1459 1460The functions |matchfuzzy()| and |matchfuzzypos()| can be used to fuzzy search 1461a string in a List of strings. The matchfuzzy() function returns a List of 1462matching strings. The matchfuzzypos() functions returns the List of matches, 1463the matching positions and the fuzzy match scores. 1464 1465The "f" flag of `:vimgrep` enables fuzzy matching. 1466 1467 1468 1469 vim:tw=78:ts=8:noet:ft=help:norl: 1470