| blob | 753d746f0882f1f8c4806b79c688431520f36942 |
1 *pattern.txt* For Vim version 5.8. Last change: 2000 Sep 21
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Patterns and search commands *pattern-searches*
9 1. Search commands |search-commands|
10 2. The definition of a pattern |search-pattern|
12 ==============================================================================
13 1. Search commands *search-commands*
15 */*
16 /{pattern}[/]<CR> Search forward for the [count]'th occurrence of
17 {pattern} (exclusive).
19 /{pattern}/{offset}<CR> Search forward for the [count]'th occurrence of
20 {pattern} and go |{offset}| lines up or down.
21 (linewise).
23 */<CR>*
24 /<CR> Search forward for the [count]'th latest used
25 pattern |last-pattern| with latest used |{offset}|.
27 //{offset}<CR> Search forward for the [count]'th latest used
28 pattern |last-pattern| with new |{offset}|. If
29 {offset} is empty no offset is used.
31 *?*
32 ?{pattern}[?]<CR> Search backward for the [count]'th previous
33 occurrence of {pattern} (exclusive).
35 ?{pattern}?{offset}<CR> Search backward for the [count]'th previous
36 occurrence of {pattern} and go |{offset}| lines up or
37 down (linewise).
39 *?<CR>*
40 ?<CR> Search backward for the [count]'th latest used
41 pattern |last-pattern| with latest used |{offset}|.
43 ??{offset}<CR> Search backward for the [count]'th latest used
44 pattern |last-pattern| with new |{offset}|. If
45 {offset} is empty no offset is used.
47 *n*
48 n Repeat the latest "/" or "?" [count] times.
49 |last-pattern| {Vi: no count}
51 *N*
52 N Repeat the latest "/" or "?" [count] times in
53 opposite direction. |last-pattern| {Vi: no count}
55 *star*
56 * Search forward for the [count]'th occurrence of the
57 word nearest to the cursor. The word used for the
58 search is the first of:
59 1. the keyword under the cursor |'iskeyword'|
60 2. the first keyword after the cursor, in the
61 current line
62 3. the non-blank word under the cursor
63 4. the first non-blank word after the cursor,
64 in the current line
65 Only whole keywords are searched for, like with the
66 command "/\<keyword\>". (exclusive) {not in Vi}
68 *#*
69 # Same as "*", but search backward. The pound sign
70 (character 163) also works. If the "#" key works as
71 backspace, try using "stty erase <BS>" before starting
72 Vim (<BS> is CTRL-H or a real backspace). {not in Vi}
74 *gstar*
75 g* Like "*", but don't put "\<" and "\>" around the word.
76 This makes the search also find matches that are not a
77 whole word. {not in Vi}
79 *g#*
80 g# Like "#", but don't put "\<" and "\>" around the word.
81 This makes the search also find matches that are not a
82 whole word. {not in Vi}
84 *gd*
85 gd Goto local Declaration. When the cursor is on a local
86 variable, this command will jump to its declaration.
87 First Vim searches for the start of the current
88 function, just like "[[". If it is not found the
89 search stops in line 1. If it is found, Vim goes back
90 until a blank line is found. From this position Vim
91 searches for the keyword under the cursor, like with
92 "*", but lines that look like a comment are ignored
93 (see 'comments' option).
94 Note that this is not guaranteed to work, Vim does not
95 really check the syntax, it only searches for a match
96 with the keyword. If included files also need to be
97 searched use the commands listed in |include-search|.
98 {not in Vi}
100 *gD*
101 gD Goto global Declaration. When the cursor is on a
102 global variable that is defined in the file, this
103 command will jump to its declaration. This works just
104 like "gd", except that the search for the keyword
105 always starts in line 1. {not in Vi}
107 *CTRL-C*
108 CTRL-C Interrupt current (search) command. Use CTRL-Break on
109 MS-DOS |dos-CTRL-Break|.
110 In Normal mode, any pending command is aborted.
112 *:noh* *:nohlsearch*
113 :noh[lsearch] Stop the highlighting for the 'hlsearch' option. It
114 is automatically turned back on when using a search
115 command, or setting the 'hlsearch' option.
116 This command doesn't work in an autocommand, because
117 the highlighting state is saved and restored when
118 executing autocommands |autocmd-searchpat|.
120 While typing the search pattern the current match will be shown if the
121 'incsearch' option is on. Remember that you still have to finish the search
122 command with <CR> to actually position the cursor at the displayed match. Or
123 use <Esc> to abandon the search.
125 All matches for the last used search pattern will be highlighted if you set
126 the 'hlsearch' option. This can be suspended with the |:nohlsearch| command.
128 *search-offset* *{offset}*
129 These commands search for the specified pattern. With "/" and "?" an
130 additional offset may be given. There are two types of offsets: line offsets
131 and character offsets. {the character offsets are not in Vi}
133 The offset gives the cursor position relative to the found match:
134 [num] [num] lines downwards, in column 1
135 +[num] [num] lines downwards, in column 1
136 -[num] [num] lines upwards, in column 1
137 e[+num] [num] characters to the right of the end of the match
138 e[-num] [num] characters to the left of the end of the match
139 s[+num] [num] characters to the right of the start of the match
140 s[-num] [num] characters to the left of the start of the match
141 b[+num] [num] characters to the right of the start (begin) of the match
142 b[-num] [num] characters to the left of the start (begin) of the match
144 If a '-' or '+' is given but [num] is omitted, a count of one will be used.
145 When including an offset with 'e', the search becomes inclusive (the
146 character the cursor lands on is included in operations).
148 Examples:
150 pattern cursor position ~
151 /test/+1 one line below "test", in column 1
152 /test/e on the last t of "test"
153 /test/s+2 on the 's' of "test"
154 /test/b-3 three characters before "test"
156 If one of these commands is used after an operator, the characters between
157 the cursor position before and after the search is affected. However, if a
158 line offset is given, the whole lines between the two cursor positions are
159 affected.
161 *//;*
162 A very special offset is ';' followed by another search command. For example:
164 > /test 1/;/test
165 > /test.*/+1;?ing?
167 The first one first finds the next occurrence of "test 1", and then the first
168 occurrence of "test" after that.
170 This is like executing two search commands after each other, except that:
171 - It can be used as a single motion command after an operator.
172 - The direction for a following "n" or "N" command comes from the first
173 search command.
174 - When an error occurs the cursor is not moved at all.
176 *last-pattern*
177 The last used pattern and offset are remembered. They can be used to repeat
178 the search, possibly in another direction or with another count. Note that
179 two patterns are remembered: One for 'normal' search commands and one for the
180 substitute command ":s". Each time an empty pattern is given, the previously
181 used pattern is used.
183 The 'magic' option sticks with the last used pattern. If you change 'magic',
184 this will not change how the last used pattern will be interpreted.
185 The 'ignorecase' option does not do this. When 'ignorecase' is changed, it
186 will result in the pattern to match other text.
188 All matches for the last used search pattern will be highlighted if you set
189 the 'hlsearch' option.
191 In Vi the ":tag" command sets the last search pattern when the tag is searched
192 for. In Vim this is not done, the previous search pattern is still remembered,
193 unless the 't' flag is present in 'cpoptions'. The search pattern is always
194 put in the search history.
196 If the 'wrapscan' option is on (which is the default), searches wrap around
197 the end of the buffer. If 'wrapscan' is not set, the backward search stops
198 at the beginning and the forward search stops at the end of the buffer. If
199 'wrapscan' is set and the pattern was not found the error message "pattern
200 not found" is given, and the cursor will not be moved. If 'wrapscan' is not
201 set the message becomes "search hit BOTTOM without match" when searching
202 forward, or "search hit TOP without match" when searching backward. If
203 wrapscan is set and the search wraps around the end of the file the message
204 "search hit TOP, continuing at BOTTOM" or "search hit BOTTOM, continuing at
205 TOP" is given when searching backwards or forwards respectively. This can be
206 switched off by setting the 's' flag in the 'shortmess' option. The highlight
207 method 'w' is used for this message (default: standout).
209 *search-range*
210 You cannot limit the search command "/" to a certain range of lines. A trick
211 to do this anyway is to use the ":substitute" command with the 'c' flag.
212 Example:
213 > :.,300s/Pattern//gc
214 This command will search from the cursor position until line 300 for
215 "Pattern". At the match, you will be asked to type a character. Type 'q' to
216 stop at this match, type 'n' to find the next match.
218 The "*", "#", "g*" and "g#" commands look for a word near the cursor in this
219 order, the first one that is found is used:
220 - The keyword currently under the cursor.
221 - The first keyword to the right of the cursor, in the same line.
222 - The WORD currently under the cursor.
223 - The first WORD to the right of the cursor, in the same line.
224 The keyword may only contain letters and characters in 'iskeyword'.
225 The WORD may contain any non-blanks (<Tab>s and/or <Space>s).
226 Note that if you type with ten fingers, the characters are easy to remember:
227 the "#" is under your left hand middle finger (search to the left and up) and
228 the "*" is under your right hand middle finger (search to the right and down).
230 ==============================================================================
231 2. The definition of a pattern *search-pattern* *pattern* *[pattern]*
232 *regular-expression* *regexp* *Pattern*
234 Patterns may contain special characters, depending on the setting of the
235 'magic' option. It is recommended to always use the default setting, which is
236 'magic'. This avoids portability problems.
238 */bar* */\bar*
239 1. A pattern is one or more branches, separated by "\|". It matches anything
240 that matches one of the branches. Example: "foo\|beep" matches "foo" and
241 "beep". If more than one branch matches, the first one is used.
243 2. A branch is one or more pieces, concatenated. It matches a match for the
244 first, followed by a match for the second, etc. Example: "foo[0-9]beep",
245 first match "foo", then a digit and then "beep".
247 3. A piece is an atom, possibly followed by:
248 'magic' 'nomagic' ~
249 */star* */\star*
250 * \* matches 0 or more of the preceding atom, as much as
251 possible (maximum 32767)
252 */\+*
253 \+ \+ matches 1 or more of the preceding atom, as much as
254 possible (maximum 32767) {not in Vi}
255 */\=*
256 \= \= matches 0 or 1 of the preceding atom, as much as
257 possible {not in Vi}
258 */\{*
259 \{n,m} \{n,m} matches n to m of the preceding atom, as much as
260 possible {not in Vi}
261 \{n} \{n} matches n of the preceding atom {not in Vi}
262 \{n,} \{n,} matches at least n of the preceding atom, as much as
263 possible {not in Vi}
264 \{,m} \{,m} matches 0 to m of the preceding atom, as much as
265 possible {not in Vi}
266 \{} \{} matches 0 or more of the preceding atom, as much as
267 possible (same as *) {not in Vi}
268 */\{-*
269 \{-n,m} \{-n,m} matches n to m of the preceding atom, as few as
270 possible {not in Vi}
271 \{-n} \{-n} matches n of the preceding atom {not in Vi}
272 \{-n,} \{-n,} matches at least n of the preceding atom, as few as
273 possible {not in Vi}
274 \{-,m} \{-,m} matches 0 to m of the preceding atom, as few as
275 possible {not in Vi}
276 \{-} \{-} matches 0 or more of the preceding atom, as few as
277 possible {not in Vi}
279 (n and m are decimal numbers between 1 and 32767)
281 If a "-" appears immediately after the "{", then a shortest
282 match first algorithm is used (see example below). In
283 particular, "\{-}" is the same as "*" but uses the shortest
284 match first algorithm. BUT: A match that starts earlier is
285 preferred over a shorter match: "a\{-}b" matches "aaab" in
286 "xaaab".
288 Examples:
289 .* .\* matches anything, also empty string
290 ^.\+$ ^.\+$ matches any non-empty line
291 foo\= foo\= matches "fo" and "foo"
292 ab\{2,3}c matches "abbc" or "abbbc"
293 a\{5} matches "aaaaa".
294 ab\{2,}c matches "abbc", "abbbc", "abbbbc", etc
295 ab\{,3}c matches "ac", "abc", "abbc" or "abbbc".
296 a[bc]\{3}d matches "abbbd", "abbcd", "acbcd", "acccd", etc.
297 a\(bc\)\{1,2}d matches "abcd" or "abcbcd"
298 a[bc]\{-}[cd] matches "abc" in "abcd"
299 a[bc]*[cd] matches "abcd" in "abcd"
302 4. An atom can be:
303 magic nomagic ~
304 ^ ^ at beginning of pattern or after "\|" or */^*
305 "\(", matches start of line; at other
306 positions, matches literal '^'
307 \^ \^ at any position, matches literal '^' */\^*
308 $ $ at end of pattern or in front of "\|" or */$*
309 "\)", matches end-of-line <EOL>; at other
310 positions, matches literal '$'
311 \$ \$ at any position, matches literal '$' */\$*
312 . \. matches any single character */.* */\.*
313 \< \< matches the beginning of a word */\<*
314 \> \> matches the end of a word */\>*
316 Character classes {not in Vi}:
317 \i \i identifier character (see 'isident' option) */\i*
318 \I \I like "\i", but excluding digits */\I*
319 \k \k keyword character (see 'iskeyword' option) */\k*
320 \K \K like "\k", but excluding digits */\K*
321 \f \f file name character (see 'isfname' option) */\f*
322 \F \F like "\f", but excluding digits */\F*
323 \p \p printable character (see 'isprint' option) */\p*
324 \P \P like "\p", but excluding digits */\P*
326 *whitespace* *white-space*
327 \s \s whitespace character: <Space> and <Tab> */\s*
328 \S \S non-whitespace character; opposite of \s */\S*
329 \d \d digit: [0-9] */\d*
330 \D \D non-digit: [^0-9] */\D*
331 \x \x hex digit: [0-9A-Fa-f] */\x*
332 \X \X non-hex digit: [^0-9A-Fa-f] */\X*
333 \o \o octal digit: [0-7] */\o*
334 \O \O non-octal digit: [^0-7] */\O*
335 \w \w word character: [0-9A-Za-z_] */\w*
336 \W \W non-word character: [^0-9A-Za-z_] */\W*
337 \h \h head of word character: [A-Za-z_] */\h*
338 \H \H non-head of word character: [^A-Za-z_] */\H*
339 \a \a alphabetic character: [A-Za-z] */\a*
340 \A \A non-alphabetic character: [^A-Za-z] */\A*
341 \l \l lowercase character: [a-z] */\l*
342 \L \L non-lowercase character: [^a-z] */\L*
343 \u \u uppercase character: [A-Z] */\u*
344 \U \U non-uppercase character [^A-Z] */\U*
345 NOTE: using the atom is faster than the [] form
346 NOTE: 'ignorecase' is not used by character classes
347 (end of character classes)
349 \e \e matches <Esc> */\e*
350 \t \t matches <Tab> */\t*
351 \r \r matches <CR> */\r*
352 \b \b matches <BS> */\b*
353 \n \n matches <NL> Not available yet! Will be used */\n*
354 for multi-line patterns
355 ~ \~ matches the last given substitute string */~* */\~*
356 \(\) \(\) A pattern enclosed by escaped parentheses */\(\)*
357 (e.g., "\(^a\)") matches that pattern */\)*
358 \1 \1 Matches the same string that was matched by */\1*
359 the first sub-expression in \( and \). {not in Vi}
360 Example: "\([a-z]\).\1" matches "ata", "ehe", "tot",
361 etc.
362 \2 \2 Like "\1", but uses second sub-expression, */\2*
363 ... */\3*
364 \9 \9 Like "\1", but uses ninth sub-expression. */\9*
365 Note: The numbering of groups is done based on which
366 "\(" comes first (going left to right).
368 x x A single character, with no special meaning,
369 matches itself
370 \x \x A backslash followed by a single character, */\* */\\*
371 with no special meaning, is reserved for future
372 expansions
374 [] \[] A range. This is a sequence of characters */[]*
375 enclosed in "[]" or "\[]". It matches any */\[]*
376 single character from the sequence. E.g., "[xyz]"
377 matches any 'x', 'y' or 'z'.
378 - If the sequence begins with "^", it matches any
379 single character NOT in the sequence: "[^xyz]"
380 matches anything but 'x', 'y' and 'z'.
381 - If two characters in the sequence are separated by
382 '-', this is shorthand for the full list of ASCII
383 characters between them. E.g., "[0-9]" matches any
384 decimal digit.
385 - A character class expression is evaluated to the set
386 of characters belonging to that character class. The
387 following character classes are supported:
388 Name Contents ~
389 *[:alnum:]* [:alnum:] letters and digits
390 *[:alpha:]* [:alpha:] letters
391 *[:blank:]* [:blank:] space and tab characters
392 *[:cntrl:]* [:cntrl:] control characters
393 *[:digit:]* [:digit:] decimal digits
394 *[:graph:]* [:graph:] printable characters excluding space
395 *[:lower:]* [:lower:] lowercase letters
396 *[:print:]* [:print:] printable characters including space
397 *[:punct:]* [:punct:] punctuation characters
398 *[:space:]* [:space:] whitespace characters
399 *[:upper:]* [:upper:] uppercase letters
400 *[:xdigit:]* [:xdigit:] hexadecimal digits
401 *[:return:]* [:return:] the <CR> character
402 *[:tab:]* [:tab:] the <Tab> character
403 *[:escape:]* [:escape:] the <Esc> character
404 *[:backspace:]* [:backspace:] the <BS> character
405 The brackets in character class expressions are
406 additional to the brackets delimiting a range.
407 For example, the following is plausible for a UNIX
408 filename: [-./[:alnum:]_~]\+
409 That is, a list of at least one character, each of
410 which is either '-', '.', '/', alphabetic, numeric,
411 '_' or '~'. */\]*
412 - To include a literal ']', '^', '-' or '\' in the
413 sequence, put a backslash before it: "[xyz\]]",
414 "[\^xyz]", "[xy\-z]" and "[xyz\\]". (Note: POSIX
415 does not support the use of a backslash this way).
416 For ']' you can also make it the first character
417 (following a possible "^"): "[]xyz]" or "[^]xyz]"
418 {not in Vi}.
419 For '-' you can also make it the first or last
420 character: "[-xyz]", "[^-xyz]" or "[xyz-]".
421 For '\' you can also let it be followed by any
422 character that's not in "^]-\etrb". "[\xyz]"
423 matches '\', 'x', 'y' and 'z'. It's better to use
424 "\\" though, future expansions may use other
425 characters after '\'.
426 - The following translations are accepted when the 'l'
427 flag is not included in 'cpoptions' {not in Vi}:
428 \e <Esc>
429 \t <Tab>
430 \r <CR>
431 \b <BS>
432 NOTE: The other backslash codes mentioned above do
433 not work inside []!
434 - Matching ranges can be slow, use one of the other
435 items above when possible.
437 If the 'ignorecase' option is on, the case of letters is ignored. 'smartcase'
438 can be set to ignore case when the pattern contains uppercase letters only.
440 It is impossible to have a pattern that contains a line break (Sorry!).
442 Examples:
443 ^beep( Probably the start of the C function "beep".
445 [a-zA-Z]$ Any alphabetic character at the end of a line.
447 \<\I\i* or
448 \<\h\w*
449 \<[a-zA-Z_][a-zA-Z0-9_]*
450 An identifier (e.g., in a C program).
452 \(\.$\|\. \) A period followed by <EOL> or a space.
454 [.!?][])"']*\($\|[ ]\) A search pattern that finds the end of a sentence,
455 with almost the same definition as the ")" command.
457 Technical detail: *NL-used-for-Nul*
458 <Nul> characters in the file are stored as <NL> in memory. In the display
459 they are shown as "^@". The translation is done when reading and writing
460 files. To match a <Nul> with a search pattern you can just enter CTRL-@ or
461 "CTRL-V 000". This is probably just what you expect. Internally the
462 character is replaced with a <NL> in the search pattern. What is unusual is
463 that typing CTRL-V CTRL-J also inserts a <NL>, thus also searches for a <Nul>
464 in the file. {Vi cannot handle <Nul> characters in the file at all}
466 *CR-used-for-NL*
467 When 'fileformat' is "mac", <NL> characters in the file are stored as <CR>
468 characters internally. In the display they are shown as "^M". Otherwise this
469 works similar to the usage of <NL> for a <Nul>.
471 vim:tw=78:ts=8:sw=8: