1*pattern.txt* For Vim version 8.2. Last change: 2021 Jul 16 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\%.l Matches at the cursor line. 933\%<.l Matches above the cursor line. 934\%>.l Matches below the cursor line. 935 These six can be used to match specific lines in a buffer. The "23" 936 can be any line number. The first line is 1. 937 WARNING: When inserting or deleting lines Vim does not automatically 938 update the matches. This means Syntax highlighting quickly becomes 939 wrong. Also when referring to the cursor position (".") and 940 the cursor moves the display isn't updated for this change. An update 941 is done when using the |CTRL-L| command (the whole screen is updated). 942 Example, to highlight the line where the cursor currently is: > 943 :exe '/\%' . line(".") . 'l' 944< Alternatively use: > 945 /\%.l 946< When 'hlsearch' is set and you move the cursor around and make changes 947 this will clearly show when the match is updated or not. 948 949 */\%c* */\%>c* */\%<c* 950\%23c Matches in a specific column. 951\%<23c Matches before a specific column. 952\%>23c Matches after a specific column. 953\%.c Matches at the cursor column. 954\%<.c Matches before the cursor column. 955\%>.c Matches after the cursor column. 956 These six can be used to match specific columns in a buffer or string. 957 The "23" can be any column number. The first column is 1. Actually, 958 the column is the byte number (thus it's not exactly right for 959 multibyte characters). 960 WARNING: When inserting or deleting text Vim does not automatically 961 update the matches. This means Syntax highlighting quickly becomes 962 wrong. Also when referring to the cursor position (".") and 963 the cursor moves the display isn't updated for this change. An update 964 is done when using the |CTRL-L| command (the whole screen is updated). 965 Example, to highlight the column where the cursor currently is: > 966 :exe '/\%' . col(".") . 'c' 967< Alternatively use: > 968 /\%.c 969< When 'hlsearch' is set and you move the cursor around and make changes 970 this will clearly show when the match is updated or not. 971 Example for matching a single byte in column 44: > 972 /\%>43c.\%<46c 973< Note that "\%<46c" matches in column 45 when the "." matches a byte in 974 column 44. 975 */\%v* */\%>v* */\%<v* 976\%23v Matches in a specific virtual column. 977\%<23v Matches before a specific virtual column. 978\%>23v Matches after a specific virtual column. 979\%.v Matches at the current virtual column. 980\%<.v Matches before the current virtual column. 981\%>.v Matches after the current virtual column. 982 These six can be used to match specific virtual columns in a buffer or 983 string. When not matching with a buffer in a window, the option 984 values of the current window are used (e.g., 'tabstop'). 985 The "23" can be any column number. The first column is 1. 986 Note that some virtual column positions will never match, because they 987 are halfway through a tab or other character that occupies more than 988 one screen character. 989 WARNING: When inserting or deleting text Vim does not automatically 990 update highlighted matches. This means Syntax highlighting quickly 991 becomes wrong. Also when referring to the cursor position (".") and 992 the cursor moves the display isn't updated for this change. An update 993 is done when using the |CTRL-L| command (the whole screen is updated). 994 Example, to highlight all the characters after virtual column 72: > 995 /\%>72v.* 996< When 'hlsearch' is set and you move the cursor around and make changes 997 this will clearly show when the match is updated or not. 998 To match the text up to column 17: > 999 /^.*\%17v 1000< To match all characters after the current virtual column (where the 1001 cursor is): > 1002 /\%>.v.* 1003< Column 17 is not included, because this is a |/zero-width| match. To 1004 include the column use: > 1005 /^.*\%17v. 1006< This command does the same thing, but also matches when there is no 1007 character in column 17: > 1008 /^.*\%<18v. 1009< Note that without the "^" to anchor the match in the first column, 1010 this will also highlight column 17: > 1011 /.*\%17v 1012< Column 17 is highlighted by 'hlsearch' because there is another match 1013 where ".*" matches zero characters. 1014 1015 1016Character classes: 1017\i identifier character (see 'isident' option) */\i* 1018\I like "\i", but excluding digits */\I* 1019\k keyword character (see 'iskeyword' option) */\k* 1020\K like "\k", but excluding digits */\K* 1021\f file name character (see 'isfname' option) */\f* 1022\F like "\f", but excluding digits */\F* 1023\p printable character (see 'isprint' option) */\p* 1024\P like "\p", but excluding digits */\P* 1025 1026NOTE: the above also work for multibyte characters. The ones below only 1027match ASCII characters, as indicated by the range. 1028 1029 *whitespace* *white-space* 1030\s whitespace character: <Space> and <Tab> */\s* 1031\S non-whitespace character; opposite of \s */\S* 1032\d digit: [0-9] */\d* 1033\D non-digit: [^0-9] */\D* 1034\x hex digit: [0-9A-Fa-f] */\x* 1035\X non-hex digit: [^0-9A-Fa-f] */\X* 1036\o octal digit: [0-7] */\o* 1037\O non-octal digit: [^0-7] */\O* 1038\w word character: [0-9A-Za-z_] */\w* 1039\W non-word character: [^0-9A-Za-z_] */\W* 1040\h head of word character: [A-Za-z_] */\h* 1041\H non-head of word character: [^A-Za-z_] */\H* 1042\a alphabetic character: [A-Za-z] */\a* 1043\A non-alphabetic character: [^A-Za-z] */\A* 1044\l lowercase character: [a-z] */\l* 1045\L non-lowercase character: [^a-z] */\L* 1046\u uppercase character: [A-Z] */\u* 1047\U non-uppercase character: [^A-Z] */\U* 1048 1049 NOTE: Using the atom is faster than the [] form. 1050 1051 NOTE: 'ignorecase', "\c" and "\C" are not used by character classes. 1052 1053 */\_* *E63* */\_i* */\_I* */\_k* */\_K* */\_f* */\_F* 1054 */\_p* */\_P* */\_s* */\_S* */\_d* */\_D* */\_x* */\_X* 1055 */\_o* */\_O* */\_w* */\_W* */\_h* */\_H* */\_a* */\_A* 1056 */\_l* */\_L* */\_u* */\_U* 1057\_x Where "x" is any of the characters above: The character class with 1058 end-of-line added 1059(end of character classes) 1060 1061\e matches <Esc> */\e* 1062\t matches <Tab> */\t* 1063\r matches <CR> */\r* 1064\b matches <BS> */\b* 1065\n matches an end-of-line */\n* 1066 When matching in a string instead of buffer text a literal newline 1067 character is matched. 1068 1069~ matches the last given substitute string */~* */\~* 1070 1071\(\) A pattern enclosed by escaped parentheses. */\(* */\(\)* */\)* 1072 E.g., "\(^a\)" matches 'a' at the start of a line. 1073 *E51* *E54* *E55* *E872* *E873* 1074 1075\1 Matches the same string that was matched by */\1* *E65* 1076 the first sub-expression in \( and \). 1077 Example: "\([a-z]\).\1" matches "ata", "ehe", "tot", etc. 1078\2 Like "\1", but uses second sub-expression, */\2* 1079 ... */\3* 1080\9 Like "\1", but uses ninth sub-expression. */\9* 1081 Note: The numbering of groups is done based on which "\(" comes first 1082 in the pattern (going left to right), NOT based on what is matched 1083 first. 1084 1085\%(\) A pattern enclosed by escaped parentheses. */\%(\)* */\%(* *E53* 1086 Just like \(\), but without counting it as a sub-expression. This 1087 allows using more groups and it's a little bit faster. 1088 1089x A single character, with no special meaning, matches itself 1090 1091 */\* */\\* 1092\x A backslash followed by a single character, with no special meaning, 1093 is reserved for future expansions 1094 1095[] (with 'nomagic': \[]) */[]* */\[]* */\_[]* */collection* 1096\_[] 1097 A collection. This is a sequence of characters enclosed in square 1098 brackets. It matches any single character in the collection. 1099 Example matches ~ 1100 [xyz] any 'x', 'y' or 'z' 1101 [a-zA-Z]$ any alphabetic character at the end of a line 1102 \c[a-z]$ same 1103 [А-яЁё] Russian alphabet (with utf-8 and cp1251) 1104 1105 */[\n]* 1106 With "\_" prepended the collection also includes the end-of-line. 1107 The same can be done by including "\n" in the collection. The 1108 end-of-line is also matched when the collection starts with "^"! Thus 1109 "\_[^ab]" matches the end-of-line and any character but "a" and "b". 1110 This makes it Vi compatible: Without the "\_" or "\n" the collection 1111 does not match an end-of-line. 1112 *E769* 1113 When the ']' is not there Vim will not give an error message but 1114 assume no collection is used. Useful to search for '['. However, you 1115 do get E769 for internal searching. And be aware that in a 1116 `:substitute` command the whole command becomes the pattern. E.g. 1117 ":s/[/x/" searches for "[/x" and replaces it with nothing. It does 1118 not search for "[" and replaces it with "x"! 1119 1120 *E944* *E945* 1121 If the sequence begins with "^", it matches any single character NOT 1122 in the collection: "[^xyz]" matches anything but 'x', 'y' and 'z'. 1123 - If two characters in the sequence are separated by '-', this is 1124 shorthand for the full list of ASCII characters between them. E.g., 1125 "[0-9]" matches any decimal digit. If the starting character exceeds 1126 the ending character, e.g. [c-a], E944 occurs. Non-ASCII characters 1127 can be used, but the character values must not be more than 256 apart 1128 in the old regexp engine. For example, searching by [\u3000-\u4000] 1129 after setting re=1 emits a E945 error. Prepending \%#=2 will fix it. 1130 - A character class expression is evaluated to the set of characters 1131 belonging to that character class. The following character classes 1132 are supported: 1133 Name Func Contents ~ 1134*[:alnum:]* [:alnum:] isalnum ASCII letters and digits 1135*[:alpha:]* [:alpha:] isalpha ASCII letters 1136*[:blank:]* [:blank:] space and tab 1137*[:cntrl:]* [:cntrl:] iscntrl ASCII control characters 1138*[:digit:]* [:digit:] decimal digits '0' to '9' 1139*[:graph:]* [:graph:] isgraph ASCII printable characters excluding 1140 space 1141*[:lower:]* [:lower:] (1) lowercase letters (all letters when 1142 'ignorecase' is used) 1143*[:print:]* [:print:] (2) printable characters including space 1144*[:punct:]* [:punct:] ispunct ASCII punctuation characters 1145*[:space:]* [:space:] whitespace characters: space, tab, CR, 1146 NL, vertical tab, form feed 1147*[:upper:]* [:upper:] (3) uppercase letters (all letters when 1148 'ignorecase' is used) 1149*[:xdigit:]* [:xdigit:] hexadecimal digits: 0-9, a-f, A-F 1150*[:return:]* [:return:] the <CR> character 1151*[:tab:]* [:tab:] the <Tab> character 1152*[:escape:]* [:escape:] the <Esc> character 1153*[:backspace:]* [:backspace:] the <BS> character 1154*[:ident:]* [:ident:] identifier character (same as "\i") 1155*[:keyword:]* [:keyword:] keyword character (same as "\k") 1156*[:fname:]* [:fname:] file name character (same as "\f") 1157 The square brackets in character class expressions are additional to 1158 the square brackets delimiting a collection. For example, the 1159 following is a plausible pattern for a UNIX filename: 1160 "[-./[:alnum:]_~]\+". That is, a list of at least one character, 1161 each of which is either '-', '.', '/', alphabetic, numeric, '_' or 1162 '~'. 1163 These items only work for 8-bit characters, except [:lower:] and 1164 [:upper:] also work for multibyte characters when using the new 1165 regexp engine. See |two-engines|. In the future these items may 1166 work for multibyte characters. For now, to get all "alpha" 1167 characters you can use: [[:lower:][:upper:]]. 1168 1169 The "Func" column shows what library function is used. The 1170 implementation depends on the system. Otherwise: 1171 (1) Uses islower() for ASCII and Vim builtin rules for other 1172 characters. 1173 (2) Uses Vim builtin rules 1174 (3) As with (1) but using isupper() 1175 */[[=* *[==]* 1176 - An equivalence class. This means that characters are matched that 1177 have almost the same meaning, e.g., when ignoring accents. This 1178 only works for Unicode, latin1 and latin9. The form is: 1179 [=a=] 1180 */[[.* *[..]* 1181 - A collation element. This currently simply accepts a single 1182 character in the form: 1183 [.a.] 1184 */\]* 1185 - To include a literal ']', '^', '-' or '\' in the collection, put a 1186 backslash before it: "[xyz\]]", "[\^xyz]", "[xy\-z]" and "[xyz\\]". 1187 (Note: POSIX does not support the use of a backslash this way). For 1188 ']' you can also make it the first character (following a possible 1189 "^"): "[]xyz]" or "[^]xyz]". 1190 For '-' you can also make it the first or last character: "[-xyz]", 1191 "[^-xyz]" or "[xyz-]". For '\' you can also let it be followed by 1192 any character that's not in "^]-\bdertnoUux". "[\xyz]" matches '\', 1193 'x', 'y' and 'z'. It's better to use "\\" though, future expansions 1194 may use other characters after '\'. 1195 - Omitting the trailing ] is not considered an error. "[]" works like 1196 "[]]", it matches the ']' character. 1197 - The following translations are accepted when the 'l' flag is not 1198 included in 'cpoptions': 1199 \e <Esc> 1200 \t <Tab> 1201 \r <CR> (NOT end-of-line!) 1202 \b <BS> 1203 \n line break, see above |/[\n]| 1204 \d123 decimal number of character 1205 \o40 octal number of character up to 0o377 1206 \x20 hexadecimal number of character up to 0xff 1207 \u20AC hex. number of multibyte character up to 0xffff 1208 \U1234 hex. number of multibyte character up to 0xffffffff 1209 NOTE: The other backslash codes mentioned above do not work inside 1210 []! 1211 - Matching with a collection can be slow, because each character in 1212 the text has to be compared with each character in the collection. 1213 Use one of the other atoms above when possible. Example: "\d" is 1214 much faster than "[0-9]" and matches the same characters. However, 1215 the new |NFA| regexp engine deals with this better than the old one. 1216 1217 */\%[]* *E69* *E70* *E369* 1218\%[] A sequence of optionally matched atoms. This always matches. 1219 It matches as much of the list of atoms it contains as possible. Thus 1220 it stops at the first atom that doesn't match. For example: > 1221 /r\%[ead] 1222< matches "r", "re", "rea" or "read". The longest that matches is used. 1223 To match the Ex command "function", where "fu" is required and 1224 "nction" is optional, this would work: > 1225 /\<fu\%[nction]\> 1226< The end-of-word atom "\>" is used to avoid matching "fu" in "full". 1227 It gets more complicated when the atoms are not ordinary characters. 1228 You don't often have to use it, but it is possible. Example: > 1229 /\<r\%[[eo]ad]\> 1230< Matches the words "r", "re", "ro", "rea", "roa", "read" and "road". 1231 There can be no \(\), \%(\) or \z(\) items inside the [] and \%[] does 1232 not nest. 1233 To include a "[" use "[[]" and for "]" use []]", e.g.,: > 1234 /index\%[[[]0[]]] 1235< matches "index" "index[", "index[0" and "index[0]". 1236 {not available when compiled without the |+syntax| feature} 1237 1238 */\%d* */\%x* */\%o* */\%u* */\%U* *E678* 1239 1240\%d123 Matches the character specified with a decimal number. Must be 1241 followed by a non-digit. 1242\%o40 Matches the character specified with an octal number up to 0o377. 1243 Numbers below 0o40 must be followed by a non-octal digit or a 1244 non-digit. 1245\%x2a Matches the character specified with up to two hexadecimal characters. 1246\%u20AC Matches the character specified with up to four hexadecimal 1247 characters. 1248\%U1234abcd Matches the character specified with up to eight hexadecimal 1249 characters, up to 0x7fffffff 1250 1251============================================================================== 12527. Ignoring case in a pattern */ignorecase* 1253 1254If the 'ignorecase' option is on, the case of normal letters is ignored. 1255'smartcase' can be set to ignore case when the pattern contains lowercase 1256letters only. 1257 */\c* */\C* 1258When "\c" appears anywhere in the pattern, the whole pattern is handled like 1259'ignorecase' is on. The actual value of 'ignorecase' and 'smartcase' is 1260ignored. "\C" does the opposite: Force matching case for the whole pattern. 1261{only Vim supports \c and \C} 1262Note that 'ignorecase', "\c" and "\C" are not used for the character classes. 1263 1264Examples: 1265 pattern 'ignorecase' 'smartcase' matches ~ 1266 foo off - foo 1267 foo on - foo Foo FOO 1268 Foo on off foo Foo FOO 1269 Foo on on Foo 1270 \cfoo - - foo Foo FOO 1271 foo\C - - foo 1272 1273Technical detail: *NL-used-for-Nul* 1274<Nul> characters in the file are stored as <NL> in memory. In the display 1275they are shown as "^@". The translation is done when reading and writing 1276files. To match a <Nul> with a search pattern you can just enter CTRL-@ or 1277"CTRL-V 000". This is probably just what you expect. Internally the 1278character is replaced with a <NL> in the search pattern. What is unusual is 1279that typing CTRL-V CTRL-J also inserts a <NL>, thus also searches for a <Nul> 1280in the file. 1281 1282 *CR-used-for-NL* 1283When 'fileformat' is "mac", <NL> characters in the file are stored as <CR> 1284characters internally. In the text they are shown as "^J". Otherwise this 1285works similar to the usage of <NL> for a <Nul>. 1286 1287When working with expression evaluation, a <NL> character in the pattern 1288matches a <NL> in the string. The use of "\n" (backslash n) to match a <NL> 1289doesn't work there, it only works to match text in the buffer. 1290 1291 *pattern-multi-byte* *pattern-multibyte* 1292Patterns will also work with multibyte characters, mostly as you would 1293expect. But invalid bytes may cause trouble, a pattern with an invalid byte 1294will probably never match. 1295 1296============================================================================== 12978. Composing characters *patterns-composing* 1298 1299 */\Z* 1300When "\Z" appears anywhere in the pattern, all composing characters are 1301ignored. Thus only the base characters need to match, the composing 1302characters may be different and the number of composing characters may differ. 1303Only relevant when 'encoding' is "utf-8". 1304Exception: If the pattern starts with one or more composing characters, these 1305must match. 1306 */\%C* 1307Use "\%C" to skip any composing characters. For example, the pattern "a" does 1308not match in "càt" (where the a has the composing character 0x0300), but 1309"a\%C" does. Note that this does not match "cát" (where the á is character 13100xe1, it does not have a compositing character). It does match "cat" (where 1311the a is just an a). 1312 1313When a composing character appears at the start of the pattern or after an 1314item that doesn't include the composing character, a match is found at any 1315character that includes this composing character. 1316 1317When using a dot and a composing character, this works the same as the 1318composing character by itself, except that it doesn't matter what comes before 1319this. 1320 1321The order of composing characters does not matter. Also, the text may have 1322more composing characters than the pattern, it still matches. But all 1323composing characters in the pattern must be found in the text. 1324 1325Suppose B is a base character and x and y are composing characters: 1326 pattern text match ~ 1327 Bxy Bxy yes (perfect match) 1328 Bxy Byx yes (order ignored) 1329 Bxy By no (x missing) 1330 Bxy Bx no (y missing) 1331 Bx Bx yes (perfect match) 1332 Bx By no (x missing) 1333 Bx Bxy yes (extra y ignored) 1334 Bx Byx yes (extra y ignored) 1335 1336============================================================================== 13379. Compare with Perl patterns *perl-patterns* 1338 1339Vim's regexes are most similar to Perl's, in terms of what you can do. The 1340difference between them is mostly just notation; here's a summary of where 1341they differ: 1342 1343Capability in Vimspeak in Perlspeak ~ 1344---------------------------------------------------------------- 1345force case insensitivity \c (?i) 1346force case sensitivity \C (?-i) 1347backref-less grouping \%(atom\) (?:atom) 1348conservative quantifiers \{-n,m} *?, +?, ??, {}? 13490-width match atom\@= (?=atom) 13500-width non-match atom\@! (?!atom) 13510-width preceding match atom\@<= (?<=atom) 13520-width preceding non-match atom\@<! (?<!atom) 1353match without retry atom\@> (?>atom) 1354 1355Vim and Perl handle newline characters inside a string a bit differently: 1356 1357In Perl, ^ and $ only match at the very beginning and end of the text, 1358by default, but you can set the 'm' flag, which lets them match at 1359embedded newlines as well. You can also set the 's' flag, which causes 1360a . to match newlines as well. (Both these flags can be changed inside 1361a pattern using the same syntax used for the i flag above, BTW.) 1362 1363On the other hand, Vim's ^ and $ always match at embedded newlines, and 1364you get two separate atoms, \%^ and \%$, which only match at the very 1365start and end of the text, respectively. Vim solves the second problem 1366by giving you the \_ "modifier": put it in front of a . or a character 1367class, and they will match newlines as well. 1368 1369Finally, these constructs are unique to Perl: 1370- execution of arbitrary code in the regex: (?{perl code}) 1371- conditional expressions: (?(condition)true-expr|false-expr) 1372 1373...and these are unique to Vim: 1374- changing the magic-ness of a pattern: \v \V \m \M 1375 (very useful for avoiding backslashitis) 1376- sequence of optionally matching atoms: \%[atoms] 1377- \& (which is to \| what "and" is to "or"; it forces several branches 1378 to match at one spot) 1379- matching lines/columns by number: \%5l \%5c \%5v 1380- setting the start and end of the match: \zs \ze 1381 1382============================================================================== 138310. Highlighting matches *match-highlight* 1384 1385 *:mat* *:match* 1386:mat[ch] {group} /{pattern}/ 1387 Define a pattern to highlight in the current window. It will 1388 be highlighted with {group}. Example: > 1389 :highlight MyGroup ctermbg=green guibg=green 1390 :match MyGroup /TODO/ 1391< Instead of // any character can be used to mark the start and 1392 end of the {pattern}. Watch out for using special characters, 1393 such as '"' and '|'. 1394 1395 {group} must exist at the moment this command is executed. 1396 1397 The {group} highlighting still applies when a character is 1398 to be highlighted for 'hlsearch', as the highlighting for 1399 matches is given higher priority than that of 'hlsearch'. 1400 Syntax highlighting (see 'syntax') is also overruled by 1401 matches. 1402 1403 Note that highlighting the last used search pattern with 1404 'hlsearch' is used in all windows, while the pattern defined 1405 with ":match" only exists in the current window. It is kept 1406 when switching to another buffer. 1407 1408 'ignorecase' does not apply, use |/\c| in the pattern to 1409 ignore case. Otherwise case is not ignored. 1410 1411 'redrawtime' defines the maximum time searched for pattern 1412 matches. 1413 1414 When matching end-of-line and Vim redraws only part of the 1415 display you may get unexpected results. That is because Vim 1416 looks for a match in the line where redrawing starts. 1417 1418 Also see |matcharg()| and |getmatches()|. The former returns 1419 the highlight group and pattern of a previous |:match| 1420 command. The latter returns a list with highlight groups and 1421 patterns defined by both |matchadd()| and |:match|. 1422 1423 Highlighting matches using |:match| are limited to three 1424 matches (aside from |:match|, |:2match| and |:3match| are 1425 available). |matchadd()| does not have this limitation and in 1426 addition makes it possible to prioritize matches. 1427 1428 Another example, which highlights all characters in virtual 1429 column 72 and more: > 1430 :highlight rightMargin term=bold ctermfg=blue guifg=blue 1431 :match rightMargin /.\%>72v/ 1432< To highlight all character that are in virtual column 7: > 1433 :highlight col8 ctermbg=grey guibg=grey 1434 :match col8 /\%<8v.\%>7v/ 1435< Note the use of two items to also match a character that 1436 occupies more than one virtual column, such as a TAB. 1437 1438:mat[ch] 1439:mat[ch] none 1440 Clear a previously defined match pattern. 1441 1442 1443:2mat[ch] {group} /{pattern}/ *:2match* 1444:2mat[ch] 1445:2mat[ch] none 1446:3mat[ch] {group} /{pattern}/ *:3match* 1447:3mat[ch] 1448:3mat[ch] none 1449 Just like |:match| above, but set a separate match. Thus 1450 there can be three matches active at the same time. The match 1451 with the lowest number has priority if several match at the 1452 same position. 1453 The ":3match" command is used by the |matchparen| plugin. You 1454 are suggested to use ":match" for manual matching and 1455 ":2match" for another plugin. 1456 1457============================================================================== 145811. Fuzzy matching *fuzzy-match* 1459 1460Fuzzy matching refers to matching strings using a non-exact search string. 1461Fuzzy matching will match a string, if all the characters in the search string 1462are present anywhere in the string in the same order. Case is ignored. In a 1463matched string, other characters can be present between two consecutive 1464characters in the search string. If the search string has multiple words, then 1465each word is matched separately. So the words in the search string can be 1466present in any order in a string. 1467 1468Fuzzy matching assigns a score for each matched string based on the following 1469criteria: 1470 - The number of sequentially matching characters. 1471 - The number of characters (distance) between two consecutive matching 1472 characters. 1473 - Matches at the beginning of a word 1474 - Matches at a camel case character (e.g. Case in CamelCase) 1475 - Matches after a path separator or a hyphen. 1476 - The number of unmatched characters in a string. 1477The matching string with the highest score is returned first. 1478 1479For example, when you search for the "get pat" string using fuzzy matching, it 1480will match the strings "GetPattern", "PatternGet", "getPattern", "patGetter", 1481"getSomePattern", "MatchpatternGet" etc. 1482 1483The functions |matchfuzzy()| and |matchfuzzypos()| can be used to fuzzy search 1484a string in a List of strings. The matchfuzzy() function returns a List of 1485matching strings. The matchfuzzypos() functions returns the List of matches, 1486the matching positions and the fuzzy match scores. 1487 1488The "f" flag of `:vimgrep` enables fuzzy matching. 1489 1490 1491 1492 vim:tw=78:ts=8:noet:ft=help:norl: 1493