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