1*usr_27.txt* For Vim version 7.3. Last change: 2010 Mar 28 2 3 VIM USER MANUAL - by Bram Moolenaar 4 5 Search commands and patterns 6 7 8In chapter 3 a few simple search patterns were mentioned |03.9|. Vim can do 9much more complex searches. This chapter explains the most often used ones. 10A detailed specification can be found here: |pattern| 11 12|27.1| Ignoring case 13|27.2| Wrapping around the file end 14|27.3| Offsets 15|27.4| Matching multiple times 16|27.5| Alternatives 17|27.6| Character ranges 18|27.7| Character classes 19|27.8| Matching a line break 20|27.9| Examples 21 22 Next chapter: |usr_28.txt| Folding 23 Previous chapter: |usr_26.txt| Repeating 24Table of contents: |usr_toc.txt| 25 26============================================================================== 27*27.1* Ignoring case 28 29By default, Vim's searches are case sensitive. Therefore, "include", 30"INCLUDE", and "Include" are three different words and a search will match 31only one of them. 32 Now switch on the 'ignorecase' option: > 33 34 :set ignorecase 35 36Search for "include" again, and now it will match "Include", "INCLUDE" and 37"InClUDe". (Set the 'hlsearch' option to quickly see where a pattern 38matches.) 39 You can switch this off again with: > 40 41 :set noignorecase 42 43But let's keep it set, and search for "INCLUDE". It will match exactly the 44same text as "include" did. Now set the 'smartcase' option: > 45 46 :set ignorecase smartcase 47 48If you have a pattern with at least one uppercase character, the search 49becomes case sensitive. The idea is that you didn't have to type that 50uppercase character, so you must have done it because you wanted case to 51match. That's smart! 52 With these two options set you find the following matches: 53 54 pattern matches ~ 55 word word, Word, WORD, WoRd, etc. 56 Word Word 57 WORD WORD 58 WoRd WoRd 59 60 61CASE IN ONE PATTERN 62 63If you want to ignore case for one specific pattern, you can do this by 64prepending the "\c" string. Using "\C" will make the pattern to match case. 65This overrules the 'ignorecase' and 'smartcase' options, when "\c" or "\C" is 66used their value doesn't matter. 67 68 pattern matches ~ 69 \Cword word 70 \CWord Word 71 \cword word, Word, WORD, WoRd, etc. 72 \cWord word, Word, WORD, WoRd, etc. 73 74A big advantage of using "\c" and "\C" is that it sticks with the pattern. 75Thus if you repeat a pattern from the search history, the same will happen, no 76matter if 'ignorecase' or 'smartcase' was changed. 77 78 Note: 79 The use of "\" items in search patterns depends on the 'magic' option. 80 In this chapter we will assume 'magic' is on, because that is the 81 standard and recommended setting. If you would change 'magic', many 82 search patterns would suddenly become invalid. 83 84 Note: 85 If your search takes much longer than you expected, you can interrupt 86 it with CTRL-C on Unix and CTRL-Break on MS-DOS and MS-Windows. 87 88============================================================================== 89*27.2* Wrapping around the file end 90 91By default, a forward search starts searching for the given string at the 92current cursor location. It then proceeds to the end of the file. If it has 93not found the string by that time, it starts from the beginning and searches 94from the start of the file to the cursor location. 95 Keep in mind that when repeating the "n" command to search for the next 96match, you eventually get back to the first match. If you don't notice this 97you keep searching forever! To give you a hint, Vim displays this message: 98 99 search hit BOTTOM, continuing at TOP ~ 100 101If you use the "?" command, to search in the other direction, you get this 102message: 103 104 search hit TOP, continuing at BOTTOM ~ 105 106Still, you don't know when you are back at the first match. One way to see 107this is by switching on the 'ruler' option: > 108 109 :set ruler 110 111Vim will display the cursor position in the lower righthand corner of the 112window (in the status line if there is one). It looks like this: 113 114 101,29 84% ~ 115 116The first number is the line number of the cursor. Remember the line number 117where you started, so that you can check if you passed this position again. 118 119 120NOT WRAPPING 121 122To turn off search wrapping, use the following command: > 123 124 :set nowrapscan 125 126Now when the search hits the end of the file, an error message displays: 127 128 E385: search hit BOTTOM without match for: forever ~ 129 130Thus you can find all matches by going to the start of the file with "gg" and 131keep searching until you see this message. 132 If you search in the other direction, using "?", you get: 133 134 E384: search hit TOP without match for: forever ~ 135 136============================================================================== 137*27.3* Offsets 138 139By default, the search command leaves the cursor positioned on the beginning 140of the pattern. You can tell Vim to leave it some other place by specifying 141an offset. For the forward search command "/", the offset is specified by 142appending a slash (/) and the offset: > 143 144 /default/2 145 146This command searches for the pattern "default" and then moves to the 147beginning of the second line past the pattern. Using this command on the 148paragraph above, Vim finds the word "default" in the first line. Then the 149cursor is moved two lines down and lands on "an offset". 150 151If the offset is a simple number, the cursor will be placed at the beginning 152of the line that many lines from the match. The offset number can be positive 153or negative. If it is positive, the cursor moves down that many lines; if 154negative, it moves up. 155 156 157CHARACTER OFFSETS 158 159The "e" offset indicates an offset from the end of the match. It moves the 160cursor onto the last character of the match. The command: > 161 162 /const/e 163 164puts the cursor on the "t" of "const". 165 From that position, adding a number moves forward that many characters. 166This command moves to the character just after the match: > 167 168 /const/e+1 169 170A positive number moves the cursor to the right, a negative number moves it to 171the left. For example: > 172 173 /const/e-1 174 175moves the cursor to the "s" of "const". 176 177If the offset begins with "b", the cursor moves to the beginning of the 178pattern. That's not very useful, since leaving out the "b" does the same 179thing. It does get useful when a number is added or subtracted. The cursor 180then goes forward or backward that many characters. For example: > 181 182 /const/b+2 183 184Moves the cursor to the beginning of the match and then two characters to the 185right. Thus it lands on the "n". 186 187 188REPEATING 189 190To repeat searching for the previously used search pattern, but with a 191different offset, leave out the pattern: > 192 193 /that 194 //e 195 196Is equal to: > 197 198 /that/e 199 200To repeat with the same offset: > 201 202 / 203 204"n" does the same thing. To repeat while removing a previously used offset: > 205 206 // 207 208 209SEARCHING BACKWARDS 210 211The "?" command uses offsets in the same way, but you must use "?" to separate 212the offset from the pattern, instead of "/": > 213 214 ?const?e-2 215 216The "b" and "e" keep their meaning, they don't change direction with the use 217of "?". 218 219 220START POSITION 221 222When starting a search, it normally starts at the cursor position. When you 223specify a line offset, this can cause trouble. For example: > 224 225 /const/-2 226 227This finds the next word "const" and then moves two lines up. If you 228use "n" to search again, Vim could start at the current position and find the same 229"const" match. Then using the offset again, you would be back where you started. 230You would be stuck! 231 It could be worse: Suppose there is another match with "const" in the next 232line. Then repeating the forward search would find this match and move two 233lines up. Thus you would actually move the cursor back! 234 235When you specify a character offset, Vim will compensate for this. Thus the 236search starts a few characters forward or backward, so that the same match 237isn't found again. 238 239============================================================================== 240*27.4* Matching multiple times 241 242The "*" item specifies that the item before it can match any number of times. 243Thus: > 244 245 /a* 246 247matches "a", "aa", "aaa", etc. But also "" (the empty string), because zero 248times is included. 249 The "*" only applies to the item directly before it. Thus "ab*" matches 250"a", "ab", "abb", "abbb", etc. To match a whole string multiple times, it 251must be grouped into one item. This is done by putting "\(" before it and 252"\)" after it. Thus this command: > 253 254 /\(ab\)* 255 256Matches: "ab", "abab", "ababab", etc. And also "". 257 258To avoid matching the empty string, use "\+". This makes the previous item 259match one or more times. > 260 261 /ab\+ 262 263Matches "ab", "abb", "abbb", etc. It does not match "a" when no "b" follows. 264 265To match an optional item, use "\=". Example: > 266 267 /folders\= 268 269Matches "folder" and "folders". 270 271 272SPECIFIC COUNTS 273 274To match a specific number of items use the form "\{n,m}". "n" and "m" are 275numbers. The item before it will be matched "n" to "m" times |inclusive|. 276Example: > 277 278 /ab\{3,5} 279 280matches "abbb", "abbbb" and "abbbbb". 281 When "n" is omitted, it defaults to zero. When "m" is omitted it defaults 282to infinity. When ",m" is omitted, it matches exactly "n" times. 283Examples: 284 285 pattern match count ~ 286 \{,4} 0, 1, 2, 3 or 4 287 \{3,} 3, 4, 5, etc. 288 \{0,1} 0 or 1, same as \= 289 \{0,} 0 or more, same as * 290 \{1,} 1 or more, same as \+ 291 \{3} 3 292 293 294MATCHING AS LITTLE AS POSSIBLE 295 296The items so far match as many characters as they can find. To match as few 297as possible, use "\{-n,m}". It works the same as "\{n,m}", except that the 298minimal amount possible is used. 299 For example, use: > 300 301 /ab\{-1,3} 302 303Will match "ab" in "abbb". Actually, it will never match more than one b, 304because there is no reason to match more. It requires something else to force 305it to match more than the lower limit. 306 The same rules apply to removing "n" and "m". It's even possible to remove 307both of the numbers, resulting in "\{-}". This matches the item before it 308zero or more times, as few as possible. The item by itself always matches 309zero times. It is useful when combined with something else. Example: > 310 311 /a.\{-}b 312 313This matches "axb" in "axbxb". If this pattern would be used: > 314 315 /a.*b 316 317It would try to match as many characters as possible with ".*", thus it 318matches "axbxb" as a whole. 319 320============================================================================== 321*27.5* Alternatives 322 323The "or" operator in a pattern is "\|". Example: > 324 325 /foo\|bar 326 327This matches "foo" or "bar". More alternatives can be concatenated: > 328 329 /one\|two\|three 330 331Matches "one", "two" and "three". 332 To match multiple times, the whole thing must be placed in "\(" and "\)": > 333 334 /\(foo\|bar\)\+ 335 336This matches "foo", "foobar", "foofoo", "barfoobar", etc. 337 Another example: > 338 339 /end\(if\|while\|for\) 340 341This matches "endif", "endwhile" and "endfor". 342 343A related item is "\&". This requires that both alternatives match in the 344same place. The resulting match uses the last alternative. Example: > 345 346 /forever\&... 347 348This matches "for" in "forever". It will not match "fortuin", for example. 349 350============================================================================== 351*27.6* Character ranges 352 353To match "a", "b" or "c" you could use "/a\|b\|c". When you want to match all 354letters from "a" to "z" this gets very long. There is a shorter method: > 355 356 /[a-z] 357 358The [] construct matches a single character. Inside you specify which 359characters to match. You can include a list of characters, like this: > 360 361 /[0123456789abcdef] 362 363This will match any of the characters included. For consecutive characters 364you can specify the range. "0-3" stands for "0123". "w-z" stands for "wxyz". 365Thus the same command as above can be shortened to: > 366 367 /[0-9a-f] 368 369To match the "-" character itself make it the first or last one in the range. 370These special characters are accepted to make it easier to use them inside a 371[] range (they can actually be used anywhere in the search pattern): 372 373 \e <Esc> 374 \t <Tab> 375 \r <CR> 376 \b <BS> 377 378There are a few more special cases for [] ranges, see |/[]| for the whole 379story. 380 381 382COMPLEMENTED RANGE 383 384To avoid matching a specific character, use "^" at the start of the range. 385The [] item then matches everything but the characters included. Example: > 386 387 /"[^"]*" 388< 389 " a double quote 390 [^"] any character that is not a double quote 391 * as many as possible 392 " a double quote again 393 394This matches "foo" and "3!x", including the double quotes. 395 396 397PREDEFINED RANGES 398 399A number of ranges are used very often. Vim provides a shortcut for these. 400For example: > 401 402 /\a 403 404Finds alphabetic characters. This is equal to using "/[a-zA-Z]". Here are a 405few more of these: 406 407 item matches equivalent ~ 408 \d digit [0-9] 409 \D non-digit [^0-9] 410 \x hex digit [0-9a-fA-F] 411 \X non-hex digit [^0-9a-fA-F] 412 \s white space [ ] (<Tab> and <Space>) 413 \S non-white characters [^ ] (not <Tab> and <Space>) 414 \l lowercase alpha [a-z] 415 \L non-lowercase alpha [^a-z] 416 \u uppercase alpha [A-Z] 417 \U non-uppercase alpha [^A-Z] 418 419 Note: 420 Using these predefined ranges works a lot faster than the character 421 range it stands for. 422 These items can not be used inside []. Thus "[\d\l]" does NOT work to 423 match a digit or lowercase alpha. Use "\(\d\|\l\)" instead. 424 425See |/\s| for the whole list of these ranges. 426 427============================================================================== 428*27.7* Character classes 429 430The character range matches a fixed set of characters. A character class is 431similar, but with an essential difference: The set of characters can be 432redefined without changing the search pattern. 433 For example, search for this pattern: > 434 435 /\f\+ 436 437The "\f" items stands for file name characters. Thus this matches a sequence 438of characters that can be a file name. 439 Which characters can be part of a file name depends on the system you are 440using. On MS-Windows, the backslash is included, on Unix it is not. This is 441specified with the 'isfname' option. The default value for Unix is: > 442 443 :set isfname 444 isfname=@,48-57,/,.,-,_,+,,,#,$,%,~,= 445 446For other systems the default value is different. Thus you can make a search 447pattern with "\f" to match a file name, and it will automatically adjust to 448the system you are using it on. 449 450 Note: 451 Actually, Unix allows using just about any character in a file name, 452 including white space. Including these characters in 'isfname' would 453 be theoretically correct. But it would make it impossible to find the 454 end of a file name in text. Thus the default value of 'isfname' is a 455 compromise. 456 457The character classes are: 458 459 item matches option ~ 460 \i identifier characters 'isident' 461 \I like \i, excluding digits 462 \k keyword characters 'iskeyword' 463 \K like \k, excluding digits 464 \p printable characters 'isprint' 465 \P like \p, excluding digits 466 \f file name characters 'isfname' 467 \F like \f, excluding digits 468 469============================================================================== 470*27.8* Matching a line break 471 472Vim can find a pattern that includes a line break. You need to specify where 473the line break happens, because all items mentioned so far don't match a line 474break. 475 To check for a line break in a specific place, use the "\n" item: > 476 477 /the\nword 478 479This will match at a line that ends in "the" and the next line starts with 480"word". To match "the word" as well, you need to match a space or a line 481break. The item to use for it is "\_s": > 482 483 /the\_sword 484 485To allow any amount of white space: > 486 487 /the\_s\+word 488 489This also matches when "the " is at the end of a line and " word" at the 490start of the next one. 491 492"\s" matches white space, "\_s" matches white space or a line break. 493Similarly, "\a" matches an alphabetic character, and "\_a" matches an 494alphabetic character or a line break. The other character classes and ranges 495can be modified in the same way by inserting a "_". 496 497Many other items can be made to match a line break by prepending "\_". For 498example: "\_." matches any character or a line break. 499 500 Note: 501 "\_.*" matches everything until the end of the file. Be careful with 502 this, it can make a search command very slow. 503 504Another example is "\_[]", a character range that includes a line break: > 505 506 /"\_[^"]*" 507 508This finds a text in double quotes that may be split up in several lines. 509 510============================================================================== 511*27.9* Examples 512 513Here are a few search patterns you might find useful. This shows how the 514items mentioned above can be combined. 515 516 517FINDING A CALIFORNIA LICENSE PLATE 518 519A sample license plate number is "1MGU103". It has one digit, three uppercase 520letters and three digits. Directly putting this into a search pattern: > 521 522 /\d\u\u\u\d\d\d 523 524Another way is to specify that there are three digits and letters with a 525count: > 526 527 /\d\u\{3}\d\{3} 528 529Using [] ranges instead: > 530 531 /[0-9][A-Z]\{3}[0-9]\{3} 532 533Which one of these you should use? Whichever one you can remember. The 534simple way you can remember is much faster than the fancy way that you can't. 535If you can remember them all, then avoid the last one, because it's both more 536typing and slower to execute. 537 538 539FINDING AN IDENTIFIER 540 541In C programs (and many other computer languages) an identifier starts with a 542letter and further consists of letters and digits. Underscores can be used 543too. This can be found with: > 544 545 /\<\h\w*\> 546 547"\<" and "\>" are used to find only whole words. "\h" stands for "[A-Za-z_]" 548and "\w" for "[0-9A-Za-z_]". 549 550 Note: 551 "\<" and "\>" depend on the 'iskeyword' option. If it includes "-", 552 for example, then "ident-" is not matched. In this situation use: > 553 554 /\w\@<!\h\w*\w\@! 555< 556 This checks if "\w" does not match before or after the identifier. 557 See |/\@<!| and |/\@!|. 558 559============================================================================== 560 561Next chapter: |usr_28.txt| Folding 562 563Copyright: see |manual-copyright| vim:tw=78:ts=8:ft=help:norl: 564