diff options
Diffstat (limited to 'runtime/doc/usr_27.txt')
| -rw-r--r-- | runtime/doc/usr_27.txt | 563 |
1 files changed, 563 insertions, 0 deletions
diff --git a/runtime/doc/usr_27.txt b/runtime/doc/usr_27.txt new file mode 100644 index 0000000..bb5b565 --- /dev/null +++ b/runtime/doc/usr_27.txt @@ -0,0 +1,563 @@ +*usr_27.txt* For Vim version 9.1. Last change: 2019 Jul 14 + + VIM USER MANUAL - by Bram Moolenaar + + Search commands and patterns + + +In chapter 3 a few simple search patterns were mentioned |03.9|. Vim can do +much more complex searches. This chapter explains the most often used ones. +A detailed specification can be found here: |pattern| + +|27.1| Ignoring case +|27.2| Wrapping around the file end +|27.3| Offsets +|27.4| Matching multiple times +|27.5| Alternatives +|27.6| Character ranges +|27.7| Character classes +|27.8| Matching a line break +|27.9| Examples + + Next chapter: |usr_28.txt| Folding + Previous chapter: |usr_26.txt| Repeating +Table of contents: |usr_toc.txt| + +============================================================================== +*27.1* Ignoring case + +By default, Vim's searches are case sensitive. Therefore, "include", +"INCLUDE", and "Include" are three different words and a search will match +only one of them. + Now switch on the 'ignorecase' option: > + + :set ignorecase + +Search for "include" again, and now it will match "Include", "INCLUDE" and +"InClUDe". (Set the 'hlsearch' option to quickly see where a pattern +matches.) + You can switch this off again with: > + + :set noignorecase + +But let's keep it set, and search for "INCLUDE". It will match exactly the +same text as "include" did. Now set the 'smartcase' option: > + + :set ignorecase smartcase + +If you have a pattern with at least one uppercase character, the search +becomes case sensitive. The idea is that you didn't have to type that +uppercase character, so you must have done it because you wanted case to +match. That's smart! + With these two options set you find the following matches: + + pattern matches ~ + word word, Word, WORD, WoRd, etc. + Word Word + WORD WORD + WoRd WoRd + + +CASE IN ONE PATTERN + +If you want to ignore case for one specific pattern, you can do this by +prepending the "\c" string. Using "\C" will make the pattern to match case. +This overrules the 'ignorecase' and 'smartcase' options, when "\c" or "\C" is +used their value doesn't matter. + + pattern matches ~ + \Cword word + \CWord Word + \cword word, Word, WORD, WoRd, etc. + \cWord word, Word, WORD, WoRd, etc. + +A big advantage of using "\c" and "\C" is that it sticks with the pattern. +Thus if you repeat a pattern from the search history, the same will happen, no +matter if 'ignorecase' or 'smartcase' was changed. + + Note: + The use of "\" items in search patterns depends on the 'magic' option. + In this chapter we will assume 'magic' is on, because that is the + standard and recommended setting. If you would change 'magic', many + search patterns would suddenly become invalid. + + Note: + If your search takes much longer than you expected, you can interrupt + it with CTRL-C on Unix and CTRL-Break on MS-Windows. + +============================================================================== +*27.2* Wrapping around the file end + +By default, a forward search starts searching for the given string at the +current cursor location. It then proceeds to the end of the file. If it has +not found the string by that time, it starts from the beginning and searches +from the start of the file to the cursor location. + Keep in mind that when repeating the "n" command to search for the next +match, you eventually get back to the first match. If you don't notice this +you keep searching forever! To give you a hint, Vim displays this message: + + search hit BOTTOM, continuing at TOP ~ + +If you use the "?" command, to search in the other direction, you get this +message: + + search hit TOP, continuing at BOTTOM ~ + +Still, you don't know when you are back at the first match. One way to see +this is by switching on the 'ruler' option: > + + :set ruler + +Vim will display the cursor position in the lower righthand corner of the +window (in the status line if there is one). It looks like this: + + 101,29 84% ~ + +The first number is the line number of the cursor. Remember the line number +where you started, so that you can check if you passed this position again. + + +NOT WRAPPING + +To turn off search wrapping, use the following command: > + + :set nowrapscan + +Now when the search hits the end of the file, an error message displays: + + E385: search hit BOTTOM without match for: forever ~ + +Thus you can find all matches by going to the start of the file with "gg" and +keep searching until you see this message. + If you search in the other direction, using "?", you get: + + E384: search hit TOP without match for: forever ~ + +============================================================================== +*27.3* Offsets + +By default, the search command leaves the cursor positioned on the beginning +of the pattern. You can tell Vim to leave it some other place by specifying +an offset. For the forward search command "/", the offset is specified by +appending a slash (/) and the offset: > + + /default/2 + +This command searches for the pattern "default" and then moves to the +beginning of the second line past the pattern. Using this command on the +paragraph above, Vim finds the word "default" in the first line. Then the +cursor is moved two lines down and lands on "an offset". + +If the offset is a simple number, the cursor will be placed at the beginning +of the line that many lines from the match. The offset number can be positive +or negative. If it is positive, the cursor moves down that many lines; if +negative, it moves up. + + +CHARACTER OFFSETS + +The "e" offset indicates an offset from the end of the match. It moves the +cursor onto the last character of the match. The command: > + + /const/e + +puts the cursor on the "t" of "const". + From that position, adding a number moves forward that many characters. +This command moves to the character just after the match: > + + /const/e+1 + +A positive number moves the cursor to the right, a negative number moves it to +the left. For example: > + + /const/e-1 + +moves the cursor to the "s" of "const". + +If the offset begins with "b", the cursor moves to the beginning of the +pattern. That's not very useful, since leaving out the "b" does the same +thing. It does get useful when a number is added or subtracted. The cursor +then goes forward or backward that many characters. For example: > + + /const/b+2 + +Moves the cursor to the beginning of the match and then two characters to the +right. Thus it lands on the "n". + + +REPEATING + +To repeat searching for the previously used search pattern, but with a +different offset, leave out the pattern: > + + /that + //e + +Is equal to: > + + /that/e + +To repeat with the same offset: > + + / + +"n" does the same thing. To repeat while removing a previously used offset: > + + // + + +SEARCHING BACKWARDS + +The "?" command uses offsets in the same way, but you must use "?" to separate +the offset from the pattern, instead of "/": > + + ?const?e-2 + +The "b" and "e" keep their meaning, they don't change direction with the use +of "?". + + +START POSITION + +When starting a search, it normally starts at the cursor position. When you +specify a line offset, this can cause trouble. For example: > + + /const/-2 + +This finds the next word "const" and then moves two lines up. If you +use "n" to search again, Vim could start at the current position and find the +same "const" match. Then using the offset again, you would be back where you +started. You would be stuck! + It could be worse: Suppose there is another match with "const" in the next +line. Then repeating the forward search would find this match and move two +lines up. Thus you would actually move the cursor back! + +When you specify a character offset, Vim will compensate for this. Thus the +search starts a few characters forward or backward, so that the same match +isn't found again. + +============================================================================== +*27.4* Matching multiple times + +The "*" item specifies that the item before it can match any number of times. +Thus: > + + /a* + +matches "a", "aa", "aaa", etc. But also "" (the empty string), because zero +times is included. + The "*" only applies to the item directly before it. Thus "ab*" matches +"a", "ab", "abb", "abbb", etc. To match a whole string multiple times, it +must be grouped into one item. This is done by putting "\(" before it and +"\)" after it. Thus this command: > + + /\(ab\)* + +Matches: "ab", "abab", "ababab", etc. And also "". + +To avoid matching the empty string, use "\+". This makes the previous item +match one or more times. > + + /ab\+ + +Matches "ab", "abb", "abbb", etc. It does not match "a" when no "b" follows. + +To match an optional item, use "\=". Example: > + + /folders\= + +Matches "folder" and "folders". + + +SPECIFIC COUNTS + +To match a specific number of items use the form "\{n,m}". "n" and "m" are +numbers. The item before it will be matched "n" to "m" times |inclusive|. +Example: > + + /ab\{3,5} + +matches "abbb", "abbbb" and "abbbbb". + When "n" is omitted, it defaults to zero. When "m" is omitted it defaults +to infinity. When ",m" is omitted, it matches exactly "n" times. +Examples: + + pattern match count ~ + \{,4} 0, 1, 2, 3 or 4 + \{3,} 3, 4, 5, etc. + \{0,1} 0 or 1, same as \= + \{0,} 0 or more, same as * + \{1,} 1 or more, same as \+ + \{3} 3 + + +MATCHING AS LITTLE AS POSSIBLE + +The items so far match as many characters as they can find. To match as few +as possible, use "\{-n,m}". It works the same as "\{n,m}", except that the +minimal amount possible is used. + For example, use: > + + /ab\{-1,3} + +Will match "ab" in "abbb". Actually, it will never match more than one b, +because there is no reason to match more. It requires something else to force +it to match more than the lower limit. + The same rules apply to removing "n" and "m". It's even possible to remove +both of the numbers, resulting in "\{-}". This matches the item before it +zero or more times, as few as possible. The item by itself always matches +zero times. It is useful when combined with something else. Example: > + + /a.\{-}b + +This matches "axb" in "axbxb". If this pattern would be used: > + + /a.*b + +It would try to match as many characters as possible with ".*", thus it +matches "axbxb" as a whole. + +============================================================================== +*27.5* Alternatives + +The "or" operator in a pattern is "\|". Example: > + + /foo\|bar + +This matches "foo" or "bar". More alternatives can be concatenated: > + + /one\|two\|three + +Matches "one", "two" and "three". + To match multiple times, the whole thing must be placed in "\(" and "\)": > + + /\(foo\|bar\)\+ + +This matches "foo", "foobar", "foofoo", "barfoobar", etc. + Another example: > + + /end\(if\|while\|for\) + +This matches "endif", "endwhile" and "endfor". + +A related item is "\&". This requires that both alternatives match in the +same place. The resulting match uses the last alternative. Example: > + + /forever\&... + +This matches "for" in "forever". It will not match "fortuin", for example. + +============================================================================== +*27.6* Character ranges + +To match "a", "b" or "c" you could use "/a\|b\|c". When you want to match all +letters from "a" to "z" this gets very long. There is a shorter method: > + + /[a-z] + +The [] construct matches a single character. Inside you specify which +characters to match. You can include a list of characters, like this: > + + /[0123456789abcdef] + +This will match any of the characters included. For consecutive characters +you can specify the range. "0-3" stands for "0123". "w-z" stands for "wxyz". +Thus the same command as above can be shortened to: > + + /[0-9a-f] + +To match the "-" character itself make it the first or last one in the range. +These special characters are accepted to make it easier to use them inside a +[] range (they can actually be used anywhere in the search pattern): + + \e <Esc> + \t <Tab> + \r <CR> + \b <BS> + +There are a few more special cases for [] ranges, see |/[]| for the whole +story. + + +COMPLEMENTED RANGE + +To avoid matching a specific character, use "^" at the start of the range. +The [] item then matches everything but the characters included. Example: > + + /"[^"]*" +< + " a double quote + [^"] any character that is not a double quote + * as many as possible + " a double quote again + +This matches "foo" and "3!x", including the double quotes. + + +PREDEFINED RANGES + +A number of ranges are used very often. Vim provides a shortcut for these. +For example: > + + /\a + +Finds alphabetic characters. This is equal to using "/[a-zA-Z]". Here are a +few more of these: + + item matches equivalent ~ + \d digit [0-9] + \D non-digit [^0-9] + \x hex digit [0-9a-fA-F] + \X non-hex digit [^0-9a-fA-F] + \s white space [ ] (<Tab> and <Space>) + \S non-white characters [^ ] (not <Tab> and <Space>) + \l lowercase alpha [a-z] + \L non-lowercase alpha [^a-z] + \u uppercase alpha [A-Z] + \U non-uppercase alpha [^A-Z] + + Note: + Using these predefined ranges works a lot faster than the character + range it stands for. + These items can not be used inside []. Thus "[\d\l]" does NOT work to + match a digit or lowercase alpha. Use "\(\d\|\l\)" instead. + +See |/\s| for the whole list of these ranges. + +============================================================================== +*27.7* Character classes + +The character range matches a fixed set of characters. A character class is +similar, but with an essential difference: The set of characters can be +redefined without changing the search pattern. + For example, search for this pattern: > + + /\f\+ + +The "\f" item stands for file name characters. Thus this matches a sequence +of characters that can be a file name. + Which characters can be part of a file name depends on the system you are +using. On MS-Windows, the backslash is included, on Unix it is not. This is +specified with the 'isfname' option. The default value for Unix is: > + + :set isfname + isfname=@,48-57,/,.,-,_,+,,,#,$,%,~,= + +For other systems the default value is different. Thus you can make a search +pattern with "\f" to match a file name, and it will automatically adjust to +the system you are using it on. + + Note: + Actually, Unix allows using just about any character in a file name, + including white space. Including these characters in 'isfname' would + be theoretically correct. But it would make it impossible to find the + end of a file name in text. Thus the default value of 'isfname' is a + compromise. + +The character classes are: + + item matches option ~ + \i identifier characters 'isident' + \I like \i, excluding digits + \k keyword characters 'iskeyword' + \K like \k, excluding digits + \p printable characters 'isprint' + \P like \p, excluding digits + \f file name characters 'isfname' + \F like \f, excluding digits + +============================================================================== +*27.8* Matching a line break + +Vim can find a pattern that includes a line break. You need to specify where +the line break happens, because all items mentioned so far don't match a line +break. + To check for a line break in a specific place, use the "\n" item: > + + /one\ntwo + +This will match at a line that ends in "one" and the next line starts with +"two". To match "one two" as well, you need to match a space or a line +break. The item to use for it is "\_s": > + + /one\_stwo + +To allow any amount of white space: > + + /one\_s\+two + +This also matches when "one " is at the end of a line and " two" at the +start of the next one. + +"\s" matches white space, "\_s" matches white space or a line break. +Similarly, "\a" matches an alphabetic character, and "\_a" matches an +alphabetic character or a line break. The other character classes and ranges +can be modified in the same way by inserting a "_". + +Many other items can be made to match a line break by prepending "\_". For +example: "\_." matches any character or a line break. + + Note: + "\_.*" matches everything until the end of the file. Be careful with + this, it can make a search command very slow. + +Another example is "\_[]", a character range that includes a line break: > + + /"\_[^"]*" + +This finds a text in double quotes that may be split up in several lines. + +============================================================================== +*27.9* Examples + +Here are a few search patterns you might find useful. This shows how the +items mentioned above can be combined. + + +FINDING A CALIFORNIA LICENSE PLATE + +A sample license plate number is "1MGU103". It has one digit, three uppercase +letters and three digits. Directly putting this into a search pattern: > + + /\d\u\u\u\d\d\d + +Another way is to specify that there are three digits and letters with a +count: > + + /\d\u\{3}\d\{3} + +Using [] ranges instead: > + + /[0-9][A-Z]\{3}[0-9]\{3} + +Which one of these you should use? Whichever one you can remember. The +simple way you can remember is much faster than the fancy way that you can't. +If you can remember them all, then avoid the last one, because it's both more +typing and slower to execute. + + +FINDING AN IDENTIFIER + +In C programs (and many other computer languages) an identifier starts with a +letter and further consists of letters and digits. Underscores can be used +too. This can be found with: > + + /\<\h\w*\> + +"\<" and "\>" are used to find only whole words. "\h" stands for "[A-Za-z_]" +and "\w" for "[0-9A-Za-z_]". + + Note: + "\<" and "\>" depend on the 'iskeyword' option. If it includes "-", + for example, then "ident-" is not matched. In this situation use: > + + /\w\@<!\h\w*\w\@! +< + This checks if "\w" does not match before or after the identifier. + See |/\@<!| and |/\@!|. + +============================================================================== + +Next chapter: |usr_28.txt| Folding + +Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: |