1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000
3 @c Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Search, Fixit, Display, Top
6 @chapter Searching and Replacement
8 @cindex finding strings within text
10 Like other editors, Emacs has commands for searching for occurrences of
11 a string. The principal search command is unusual in that it is
12 @dfn{incremental}; it begins to search before you have finished typing the
13 search string. There are also nonincremental search commands more like
14 those of other editors.
16 Besides the usual @code{replace-string} command that finds all
17 occurrences of one string and replaces them with another, Emacs has a fancy
18 replacement command called @code{query-replace} which asks interactively
19 which occurrences to replace.
22 * Incremental Search:: Search happens as you type the string.
23 * Nonincremental Search:: Specify entire string and then search.
24 * Word Search:: Search for sequence of words.
25 * Regexp Search:: Search for match for a regexp.
26 * Regexps:: Syntax of regular expressions.
27 * Search Case:: To ignore case while searching, or not.
28 * Replace:: Search, and replace some or all matches.
29 * Other Repeating Search:: Operating on all matches for some regexp.
32 @node Incremental Search, Nonincremental Search, Search, Search
33 @section Incremental Search
35 @cindex incremental search
36 An incremental search begins searching as soon as you type the first
37 character of the search string. As you type in the search string, Emacs
38 shows you where the string (as you have typed it so far) would be
39 found. When you have typed enough characters to identify the place you
40 want, you can stop. Depending on what you plan to do next, you may or
41 may not need to terminate the search explicitly with @key{RET}.
46 Incremental search forward (@code{isearch-forward}).
48 Incremental search backward (@code{isearch-backward}).
52 @findex isearch-forward
53 @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from
54 the keyboard and positions the cursor at the first occurrence of the
55 characters that you have typed. If you type @kbd{C-s} and then @kbd{F},
56 the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see
57 the cursor move to after the first @samp{FO}. After another @kbd{O}, the
58 cursor is after the first @samp{FOO} after the place where you started the
59 search. At each step, the buffer text that matches the search string is
60 highlighted, if the terminal can do that; at each step, the current search
61 string is updated in the echo area. Multilingual text can be input by
62 toggling input methods with @kbd{C-\} or @kbd{C-^}.
64 If you make a mistake in typing the search string, you can cancel
65 characters with @key{DEL}. Each @key{DEL} cancels the last character of
66 search string. This does not happen until Emacs is ready to read another
67 input character; first it must either find, or fail to find, the character
68 you want to erase. If you do not want to wait for this to happen, use
69 @kbd{C-g} as described below.
71 When you are satisfied with the place you have reached, you can type
72 @key{RET}, which stops searching, leaving the cursor where the search
73 brought it. Also, any command not specially meaningful in searches
74 stops the searching and is then executed. Thus, typing @kbd{C-a} would
75 exit the search and then move to the beginning of the line. @key{RET}
76 is necessary only if the next command you want to type is a printing
77 character, @key{DEL}, @key{RET}, or another control character that is
78 special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
79 @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, or @kbd{M-s}).
81 Sometimes you search for @samp{FOO} and find it, but not the one you
82 expected to find. There was a second @samp{FOO} that you forgot about,
83 before the one you were aiming for. In this event, type another @kbd{C-s}
84 to move to the next occurrence of the search string. This can be done any
85 number of times. If you overshoot, you can cancel some @kbd{C-s}
86 characters with @key{DEL}.
88 After you exit a search, you can search for the same string again by
89 typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
90 incremental search, and the second @kbd{C-s} means ``search again.''
92 To reuse earlier search strings, use the @dfn{search ring}. The
93 commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search
94 string to reuse. These commands leave the selected search ring element
95 in the minibuffer, where you can edit it. Type @kbd{C-s} or @kbd{C-r}
96 to terminate editing the string and search for it.
98 If your string is not found at all, the echo area says @samp{Failing
99 I-Search}. The cursor is after the place where Emacs found as much of your
100 string as it could. Thus, if you search for @samp{FOOT}, and there is no
101 @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
102 At this point there are several things you can do. If your string was
103 mistyped, you can rub some of it out and correct it. If you like the place
104 you have found, you can type @key{RET} or some other Emacs command to
105 ``accept what the search offered.'' Or you can type @kbd{C-g}, which
106 removes from the search string the characters that could not be found (the
107 @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
108 @samp{FOOT}). A second @kbd{C-g} at that point cancels the search
109 entirely, returning point to where it was when the search started.
111 An upper-case letter in the search string makes the search
112 case-sensitive. If you delete the upper-case character from the search
113 string, it ceases to have this effect. @xref{Search Case}.
115 If a search is failing and you ask to repeat it by typing another
116 @kbd{C-s}, it starts again from the beginning of the buffer. Repeating
117 a failing reverse search with @kbd{C-r} starts again from the end. This
118 is called @dfn{wrapping around}. @samp{Wrapped} appears in the search
119 prompt once this has happened. If you keep on going past the original
120 starting point of the search, it changes to @samp{Overwrapped}, which
121 means that you are revisiting matches that you have already seen.
123 @cindex quitting (in search)
124 The @kbd{C-g} ``quit'' character does special things during searches;
125 just what it does depends on the status of the search. If the search has
126 found what you specified and is waiting for input, @kbd{C-g} cancels the
127 entire search. The cursor moves back to where you started the search. If
128 @kbd{C-g} is typed when there are characters in the search string that have
129 not been found---because Emacs is still searching for them, or because it
130 has failed to find them---then the search string characters which have not
131 been found are discarded from the search string. With them gone, the
132 search is now successful and waiting for more input, so a second @kbd{C-g}
133 will cancel the entire search.
135 To search for a newline, type @kbd{C-j}. To search for another
136 control character, such as control-S or carriage return, you must quote
137 it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous
138 to its use for insertion (@pxref{Inserting Text}): it causes the
139 following character to be treated the way any ``ordinary'' character is
140 treated in the same context. You can also specify a character by its
141 octal code: enter @kbd{C-q} followed by a sequence of octal digits.
143 You can change to searching backwards with @kbd{C-r}. If a search fails
144 because the place you started was too late in the file, you should do this.
145 Repeated @kbd{C-r} keeps looking for more occurrences backwards. A
146 @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be canceled
150 @findex isearch-backward
151 If you know initially that you want to search backwards, you can use
152 @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as
153 a key runs a command (@code{isearch-backward}) to search backward. A
154 backward search finds matches that are entirely before the starting
155 point, just as a forward search finds matches that begin after it.
157 The characters @kbd{C-y} and @kbd{C-w} can be used in incremental
158 search to grab text from the buffer into the search string. This makes
159 it convenient to search for another occurrence of text at point.
160 @kbd{C-w} copies the word after point as part of the search string,
161 advancing point over that word. Another @kbd{C-s} to repeat the search
162 will then search for a string including that word. @kbd{C-y} is similar
163 to @kbd{C-w} but copies all the rest of the current line into the search
164 string. Both @kbd{C-y} and @kbd{C-w} convert the text they copy to
165 lower case if the search is currently not case-sensitive; this is so the
166 search remains case-insensitive.
168 The character @kbd{M-y} copies text from the kill ring into the search
169 string. It uses the same text that @kbd{C-y} as a command would yank.
170 @kbd{mouse-2} in the echo area does the same.
173 When you exit the incremental search, it sets the mark to where point
174 @emph{was}, before the search. That is convenient for moving back
175 there. In Transient Mark mode, incremental search sets the mark without
176 activating it, and does so only if the mark is not already active.
178 @cindex lazy search highlighting
179 By default, Isearch uses @dfn{lazy highlighting}. All matches for
180 the current search string in the buffer after the point where searching
181 starts are highlighted. The extra highlighting makes it easier to
182 anticipate where the cursor will end up each time you press @kbd{C-s} or
183 @kbd{C-r} to repeat a pending search. Highlighting of these additional
184 matches happens in a deferred fashion so as not to rob Isearch of its
185 usual snappy response.
186 @vindex isearch-lazy-highlight-cleanup
187 @findex isearch-lazy-highlight-cleanup
188 By default the highlighting of matches is cleared when you end the
189 search. Customize the variable @code{isearch-lazy-highlight-cleanup} to
190 avoid cleaning up automatically. The command @kbd{M-x
191 isearch-lazy-highlight-cleanup} can be used to clean up manually.
192 @vindex isearch-lazy-highlight
193 Customize the variable @code{isearch-lazy-highlight} to turn off this
196 @vindex isearch-lazy-highlight-face
197 @cindex faces for highlighting search matches
198 You can control how does the highlighting of matches look like by
199 customizing the faces @code{isearch} (highlights the current match) and
200 @code{isearch-lazy-highlight-face} (highlights the other matches). The
201 former defaults to the @code{region} face, the latter to the
202 @code{secodnary-selection} face.
204 @vindex isearch-mode-map
205 To customize the special characters that incremental search understands,
206 alter their bindings in the keymap @code{isearch-mode-map}. For a list
207 of bindings, look at the documentation of @code{isearch-mode} with
208 @kbd{C-h f isearch-mode @key{RET}}.
210 @subsection Slow Terminal Incremental Search
212 Incremental search on a slow terminal uses a modified style of display
213 that is designed to take less time. Instead of redisplaying the buffer at
214 each place the search gets to, it creates a new single-line window and uses
215 that to display the line that the search has found. The single-line window
216 comes into play as soon as point gets outside of the text that is already
219 When you terminate the search, the single-line window is removed.
220 Then Emacs redisplays the window in which the search was done, to show
221 its new position of point.
224 The three dots at the end of the search string, normally used to indicate
225 that searching is going on, are not displayed in slow style display.
228 @vindex search-slow-speed
229 The slow terminal style of display is used when the terminal baud rate is
230 less than or equal to the value of the variable @code{search-slow-speed},
233 @vindex search-slow-window-lines
234 The number of lines to use in slow terminal search display is controlled
235 by the variable @code{search-slow-window-lines}. Its normal value is 1.
237 @node Nonincremental Search, Word Search, Incremental Search, Search
238 @section Nonincremental Search
239 @cindex nonincremental search
241 Emacs also has conventional nonincremental search commands, which require
242 you to type the entire search string before searching begins.
245 @item C-s @key{RET} @var{string} @key{RET}
246 Search for @var{string}.
247 @item C-r @key{RET} @var{string} @key{RET}
248 Search backward for @var{string}.
251 To do a nonincremental search, first type @kbd{C-s @key{RET}}. This
252 enters the minibuffer to read the search string; terminate the string
253 with @key{RET}, and then the search takes place. If the string is not
254 found, the search command gets an error.
256 The way @kbd{C-s @key{RET}} works is that the @kbd{C-s} invokes
257 incremental search, which is specially programmed to invoke nonincremental
258 search if the argument you give it is empty. (Such an empty argument would
259 otherwise be useless.) @kbd{C-r @key{RET}} also works this way.
261 However, nonincremental searches performed using @kbd{C-s @key{RET}} do
262 not call @code{search-forward} right away. The first thing done is to see
263 if the next character is @kbd{C-w}, which requests a word search.
268 @findex search-forward
269 @findex search-backward
270 Forward and backward nonincremental searches are implemented by the
271 commands @code{search-forward} and @code{search-backward}. These
272 commands may be bound to keys in the usual manner. The feature that you
273 can get to them via the incremental search commands exists for
274 historical reasons, and to avoid the need to find suitable key sequences
277 @node Word Search, Regexp Search, Nonincremental Search, Search
281 Word search searches for a sequence of words without regard to how the
282 words are separated. More precisely, you type a string of many words,
283 using single spaces to separate them, and the string can be found even if
284 there are multiple spaces, newlines or other punctuation between the words.
286 Word search is useful for editing a printed document made with a text
287 formatter. If you edit while looking at the printed, formatted version,
288 you can't tell where the line breaks are in the source file. With word
289 search, you can search without having to know them.
292 @item C-s @key{RET} C-w @var{words} @key{RET}
293 Search for @var{words}, ignoring details of punctuation.
294 @item C-r @key{RET} C-w @var{words} @key{RET}
295 Search backward for @var{words}, ignoring details of punctuation.
298 Word search is a special case of nonincremental search and is invoked
299 with @kbd{C-s @key{RET} C-w}. This is followed by the search string,
300 which must always be terminated with @key{RET}. Being nonincremental,
301 this search does not start until the argument is terminated. It works
302 by constructing a regular expression and searching for that; see
305 Use @kbd{C-r @key{RET} C-w} to do backward word search.
307 @findex word-search-forward
308 @findex word-search-backward
309 Forward and backward word searches are implemented by the commands
310 @code{word-search-forward} and @code{word-search-backward}. These
311 commands may be bound to keys in the usual manner. The feature that you
312 can get to them via the incremental search commands exists for historical
313 reasons, and to avoid the need to find suitable key sequences for them.
315 @node Regexp Search, Regexps, Word Search, Search
316 @section Regular Expression Search
317 @cindex regular expression
320 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
321 denotes a class of alternative strings to match, possibly infinitely
322 many. In GNU Emacs, you can search for the next match for a regexp
323 either incrementally or not.
326 @findex isearch-forward-regexp
328 @findex isearch-backward-regexp
329 Incremental search for a regexp is done by typing @kbd{C-M-s}
330 (@code{isearch-forward-regexp}). This command reads a search string
331 incrementally just like @kbd{C-s}, but it treats the search string as a
332 regexp rather than looking for an exact match against the text in the
333 buffer. Each time you add text to the search string, you make the
334 regexp longer, and the new regexp is searched for. Invoking @kbd{C-s}
335 with a prefix argument (its value does not matter) is another way to do
336 a forward incremental regexp search. To search backward for a regexp,
337 use @kbd{C-M-r} (@code{isearch-backward-regexp}), or @kbd{C-r} with a
340 All of the control characters that do special things within an
341 ordinary incremental search have the same function in incremental regexp
342 search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the
343 search retrieves the last incremental search regexp used; that is to
344 say, incremental regexp and non-regexp searches have independent
345 defaults. They also have separate search rings that you can access with
346 @kbd{M-p} and @kbd{M-n}.
348 If you type @key{SPC} in incremental regexp search, it matches any
349 sequence of whitespace characters, including newlines. If you want
350 to match just a space, type @kbd{C-q @key{SPC}}.
352 Note that adding characters to the regexp in an incremental regexp
353 search can make the cursor move back and start again. For example, if
354 you have searched for @samp{foo} and you add @samp{\|bar}, the cursor
355 backs up in case the first @samp{bar} precedes the first @samp{foo}.
357 @findex re-search-forward
358 @findex re-search-backward
359 Nonincremental search for a regexp is done by the functions
360 @code{re-search-forward} and @code{re-search-backward}. You can invoke
361 these with @kbd{M-x}, or bind them to keys, or invoke them by way of
362 incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r
365 If you use the incremental regexp search commands with a prefix
366 argument, they perform ordinary string search, like
367 @code{isearch-forward} and @code{isearch-backward}. @xref{Incremental
370 @node Regexps, Search Case, Regexp Search, Search
371 @section Syntax of Regular Expressions
372 @cindex regexp syntax
374 Regular expressions have a syntax in which a few characters are
375 special constructs and the rest are @dfn{ordinary}. An ordinary
376 character is a simple regular expression which matches that same
377 character and nothing else. The special characters are @samp{$},
378 @samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, @samp{]} and
379 @samp{\}. Any other character appearing in a regular expression is
380 ordinary, unless a @samp{\} precedes it.
382 For example, @samp{f} is not a special character, so it is ordinary, and
383 therefore @samp{f} is a regular expression that matches the string
384 @samp{f} and no other string. (It does @emph{not} match the string
385 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches
386 only @samp{o}. (When case distinctions are being ignored, these regexps
387 also match @samp{F} and @samp{O}, but we consider this a generalization
388 of ``the same string,'' rather than an exception.)
390 Any two regular expressions @var{a} and @var{b} can be concatenated. The
391 result is a regular expression which matches a string if @var{a} matches
392 some amount of the beginning of that string and @var{b} matches the rest of
395 As a simple example, we can concatenate the regular expressions @samp{f}
396 and @samp{o} to get the regular expression @samp{fo}, which matches only
397 the string @samp{fo}. Still trivial. To do something nontrivial, you
398 need to use one of the special characters. Here is a list of them.
401 @item .@: @r{(Period)}
402 is a special character that matches any single character except a newline.
403 Using concatenation, we can make regular expressions like @samp{a.b}, which
404 matches any three-character string that begins with @samp{a} and ends with
408 is not a construct by itself; it is a postfix operator that means to
409 match the preceding regular expression repetitively as many times as
410 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
413 @samp{*} always applies to the @emph{smallest} possible preceding
414 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
415 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
417 The matcher processes a @samp{*} construct by matching, immediately,
418 as many repetitions as can be found. Then it continues with the rest
419 of the pattern. If that fails, backtracking occurs, discarding some
420 of the matches of the @samp{*}-modified construct in case that makes
421 it possible to match the rest of the pattern. For example, in matching
422 @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
423 tries to match all three @samp{a}s; but the rest of the pattern is
424 @samp{ar} and there is only @samp{r} left to match, so this try fails.
425 The next alternative is for @samp{a*} to match only two @samp{a}s.
426 With this choice, the rest of the regexp matches successfully.@refill
429 is a postfix operator, similar to @samp{*} except that it must match
430 the preceding expression at least once. So, for example, @samp{ca+r}
431 matches the strings @samp{car} and @samp{caaaar} but not the string
432 @samp{cr}, whereas @samp{ca*r} matches all three strings.
435 is a postfix operator, similar to @samp{*} except that it can match the
436 preceding expression either once or not at all. For example,
437 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
440 @cindex non-greedy regexp matching
441 are non-greedy variants of the operators above. The normal operators
442 @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as much
443 as they can, while if you append a @samp{?} after them, it makes them
444 non-greedy: they will match as little as possible.
446 @item \@{@var{n},@var{m}\@}
447 is another postfix operator that specifies an interval of iteration:
448 the preceding regular expression must match between @var{n} and
449 @var{m} times. If @var{m} is omitted, then there is no upper bound
450 and if @samp{,@var{m}} is omitted, then the regular expression must match
451 exactly @var{n} times. @*
452 @samp{\@{0,1\@}} is equivalent to @samp{?}. @*
453 @samp{\@{0,\@}} is equivalent to @samp{*}. @*
454 @samp{\@{1,\@}} is equivalent to @samp{+}. @*
455 @samp{\@{@var{n}\@}} is equivalent to @samp{\@{@var{n},@var{n}\@}}.
458 is a @dfn{character set}, which begins with @samp{[} and is terminated
459 by @samp{]}. In the simplest case, the characters between the two
460 brackets are what this set can match.
462 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
463 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
464 (including the empty string), from which it follows that @samp{c[ad]*r}
465 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
467 You can also include character ranges in a character set, by writing the
468 starting and ending characters with a @samp{-} between them. Thus,
469 @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
470 intermixed freely with individual characters, as in @samp{[a-z$%.]},
471 which matches any lower-case ASCII letter or @samp{$}, @samp{%} or
474 Note that the usual regexp special characters are not special inside a
475 character set. A completely different set of special characters exists
476 inside character sets: @samp{]}, @samp{-} and @samp{^}.
478 To include a @samp{]} in a character set, you must make it the first
479 character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
480 include a @samp{-}, write @samp{-} as the first or last character of the
481 set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]}
484 To include @samp{^} in a set, put it anywhere but at the beginning of
487 When you use a range in case-insensitive search, you should write both
488 ends of the range in upper case, or both in lower case, or both should
489 be non-letters. The behavior of a mixed-case range such as @samp{A-z}
490 is somewhat ill-defined, and it may change in future Emacs versions.
493 @samp{[^} begins a @dfn{complemented character set}, which matches any
494 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
495 all characters @emph{except} letters and digits.
497 @samp{^} is not special in a character set unless it is the first
498 character. The character following the @samp{^} is treated as if it
499 were first (in other words, @samp{-} and @samp{]} are not special there).
501 A complemented character set can match a newline, unless newline is
502 mentioned as one of the characters not to match. This is in contrast to
503 the handling of regexps in programs such as @code{grep}.
506 is a special character that matches the empty string, but only at the
507 beginning of a line in the text being matched. Otherwise it fails to
508 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
509 the beginning of a line.
512 is similar to @samp{^} but matches only at the end of a line. Thus,
513 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
516 has two functions: it quotes the special characters (including
517 @samp{\}), and it introduces additional special constructs.
519 Because @samp{\} quotes special characters, @samp{\$} is a regular
520 expression that matches only @samp{$}, and @samp{\[} is a regular
521 expression that matches only @samp{[}, and so on.
524 Note: for historical compatibility, special characters are treated as
525 ordinary ones if they are in contexts where their special meanings make no
526 sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
527 no preceding expression on which the @samp{*} can act. It is poor practice
528 to depend on this behavior; it is better to quote the special character anyway,
529 regardless of where it appears.@refill
531 For the most part, @samp{\} followed by any character matches only that
532 character. However, there are several exceptions: two-character
533 sequences starting with @samp{\} that have special meanings. The second
534 character in the sequence is always an ordinary character when used on
535 its own. Here is a table of @samp{\} constructs.
539 specifies an alternative. Two regular expressions @var{a} and @var{b}
540 with @samp{\|} in between form an expression that matches some text if
541 either @var{a} matches it or @var{b} matches it. It works by trying to
542 match @var{a}, and if that fails, by trying to match @var{b}.
544 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
545 but no other string.@refill
547 @samp{\|} applies to the largest possible surrounding expressions. Only a
548 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
551 Full backtracking capability exists to handle multiple uses of @samp{\|}.
554 is a grouping construct that serves three purposes:
558 To enclose a set of @samp{\|} alternatives for other operations.
559 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
562 To enclose a complicated expression for the postfix operators @samp{*},
563 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
564 @samp{bananana}, etc., with any (zero or more) number of @samp{na}
568 To record a matched substring for future reference.
571 This last application is not a consequence of the idea of a
572 parenthetical grouping; it is a separate feature that is assigned as a
573 second meaning to the same @samp{\( @dots{} \)} construct. In practice
574 there is almost no conflict between the two meanings.
576 @item \(?: @dots{} \)
577 is another grouping construct (often called ``shy'') that serves the same
578 first two purposes, but not the third:
579 it cannot be referred to later on by number. This is only useful
580 for mechanically constructed regular expressions where grouping
581 constructs need to be introduced implicitly and hence risk changing the
582 numbering of subsequent groups.
585 matches the same text that matched the @var{d}th occurrence of a
586 @samp{\( @dots{} \)} construct.
588 After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
589 the beginning and end of the text matched by that construct. Then,
590 later on in the regular expression, you can use @samp{\} followed by the
591 digit @var{d} to mean ``match the same text matched the @var{d}th time
592 by the @samp{\( @dots{} \)} construct.''
594 The strings matching the first nine @samp{\( @dots{} \)} constructs
595 appearing in a regular expression are assigned numbers 1 through 9 in
596 the order that the open-parentheses appear in the regular expression.
597 So you can use @samp{\1} through @samp{\9} to refer to the text matched
598 by the corresponding @samp{\( @dots{} \)} constructs.
600 For example, @samp{\(.*\)\1} matches any newline-free string that is
601 composed of two identical halves. The @samp{\(.*\)} matches the first
602 half, which may be anything, but the @samp{\1} that follows must match
605 If a particular @samp{\( @dots{} \)} construct matches more than once
606 (which can easily happen if it is followed by @samp{*}), only the last
610 matches the empty string, but only at the beginning
611 of the buffer or string being matched against.
614 matches the empty string, but only at the end of
615 the buffer or string being matched against.
618 matches the empty string, but only at point.
621 matches the empty string, but only at the beginning or
622 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
623 @samp{foo} as a separate word. @samp{\bballs?\b} matches
624 @samp{ball} or @samp{balls} as a separate word.@refill
626 @samp{\b} matches at the beginning or end of the buffer
627 regardless of what text appears next to it.
630 matches the empty string, but @emph{not} at the beginning or
634 matches the empty string, but only at the beginning of a word.
635 @samp{\<} matches at the beginning of the buffer only if a
636 word-constituent character follows.
639 matches the empty string, but only at the end of a word. @samp{\>}
640 matches at the end of the buffer only if the contents end with a
641 word-constituent character.
644 matches any word-constituent character. The syntax table
645 determines which characters these are. @xref{Syntax}.
648 matches any character that is not a word-constituent.
651 matches any character whose syntax is @var{c}. Here @var{c} is a
652 character that represents a syntax code: thus, @samp{w} for word
653 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
654 etc. Represent a character of whitespace (which can be a newline) by
655 either @samp{-} or a space character.
658 matches any character whose syntax is not @var{c}.
661 The constructs that pertain to words and syntax are controlled by the
662 setting of the syntax table (@pxref{Syntax}).
664 Here is a complicated regexp, used by Emacs to recognize the end of a
665 sentence together with any whitespace that follows. It is given in Lisp
666 syntax to enable you to distinguish the spaces from the tab characters. In
667 Lisp syntax, the string constant begins and ends with a double-quote.
668 @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
669 backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
673 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
677 This contains four parts in succession: a character set matching period,
678 @samp{?}, or @samp{!}; a character set matching close-brackets, quotes,
679 or parentheses, repeated any number of times; an alternative in
680 backslash-parentheses that matches end-of-line, a tab, or two spaces;
681 and a character set matching whitespace characters, repeated any number
684 To enter the same regexp interactively, you would type @key{TAB} to
685 enter a tab, and @kbd{C-j} to enter a newline. You would also type
686 single backslashes as themselves, instead of doubling them for Lisp syntax.
689 @cindex authoring regular expressions
690 For easier authoring of regular expressions, you can use the @kbd{M-x
691 re-builder} command. It provides a convenient interface for creating
692 regular expressions, by giving immediate visual feedback. The buffer
693 from which @code{re-builder} was invoked becomes the target for the
694 regexp editor, which pops in a separate window. Text that matches the
695 regular expression you typed so far is color marked in the target
696 buffer. Each parenthesized sub-expression of the regexp is shown in a
697 distinct face, which makes it easier to verify even very complex
698 regexps. (On displays that don't support colors, Emacs blinks the
699 cursor around the matched text, like it does for matching parens.)
701 @node Search Case, Replace, Regexps, Search
702 @section Searching and Case
704 @vindex case-fold-search
705 Incremental searches in Emacs normally ignore the case of the text
706 they are searching through, if you specify the text in lower case.
707 Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
708 @samp{foo} are also considered a match. Regexps, and in particular
709 character sets, are included: @samp{[ab]} would match @samp{a} or
710 @samp{A} or @samp{b} or @samp{B}.@refill
712 An upper-case letter anywhere in the incremental search string makes
713 the search case-sensitive. Thus, searching for @samp{Foo} does not find
714 @samp{foo} or @samp{FOO}. This applies to regular expression search as
715 well as to string search. The effect ceases if you delete the
716 upper-case letter from the search string.
718 If you set the variable @code{case-fold-search} to @code{nil}, then
719 all letters must match exactly, including case. This is a per-buffer
720 variable; altering the variable affects only the current buffer, but
721 there is a default value which you can change as well. @xref{Locals}.
722 This variable applies to nonincremental searches also, including those
723 performed by the replace commands (@pxref{Replace}) and the minibuffer
724 history matching commands (@pxref{Minibuffer History}).
726 @node Replace, Other Repeating Search, Search Case, Search
727 @section Replacement Commands
729 @cindex search-and-replace commands
730 @cindex string substitution
731 @cindex global substitution
733 Global search-and-replace operations are not needed as often in Emacs
734 as they are in other editors@footnote{In some editors,
735 search-and-replace operations are the only convenient way to make a
736 single change in the text.}, but they are available. In addition to the
737 simple @kbd{M-x replace-string} command which is like that found in most
738 editors, there is a @kbd{M-x query-replace} command which asks you, for
739 each occurrence of the pattern, whether to replace it.
741 The replace commands normally operate on the text from point to the
742 end of the buffer; however, in Transient Mark mode, when the mark is
743 active, they operate on the region. The replace commands all replace
744 one string (or regexp) with one replacement string. It is possible to
745 perform several replacements in parallel using the command
746 @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
749 * Unconditional Replace:: Replacing all matches for a string.
750 * Regexp Replace:: Replacing all matches for a regexp.
751 * Replacement and Case:: How replacements preserve case of letters.
752 * Query Replace:: How to use querying.
755 @node Unconditional Replace, Regexp Replace, Replace, Replace
756 @subsection Unconditional Replacement
757 @findex replace-string
758 @findex replace-regexp
761 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
762 Replace every occurrence of @var{string} with @var{newstring}.
763 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
764 Replace every match for @var{regexp} with @var{newstring}.
767 To replace every instance of @samp{foo} after point with @samp{bar},
768 use the command @kbd{M-x replace-string} with the two arguments
769 @samp{foo} and @samp{bar}. Replacement happens only in the text after
770 point, so if you want to cover the whole buffer you must go to the
771 beginning first. All occurrences up to the end of the buffer are
772 replaced; to limit replacement to part of the buffer, narrow to that
773 part of the buffer before doing the replacement (@pxref{Narrowing}).
774 In Transient Mark mode, when the region is active, replacement is
775 limited to the region (@pxref{Transient Mark}).
777 When @code{replace-string} exits, it leaves point at the last
778 occurrence replaced. It sets the mark to the prior position of point
779 (where the @code{replace-string} command was issued); use @kbd{C-u
780 C-@key{SPC}} to move back there.
782 A numeric argument restricts replacement to matches that are surrounded
783 by word boundaries. The argument's value doesn't matter.
785 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
786 @subsection Regexp Replacement
788 The @kbd{M-x replace-string} command replaces exact matches for a
789 single string. The similar command @kbd{M-x replace-regexp} replaces
790 any match for a specified pattern.
792 In @code{replace-regexp}, the @var{newstring} need not be constant: it
793 can refer to all or part of what is matched by the @var{regexp}.
794 @samp{\&} in @var{newstring} stands for the entire match being replaced.
795 @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
796 whatever matched the @var{d}th parenthesized grouping in @var{regexp}.
797 To include a @samp{\} in the text to replace with, you must enter
798 @samp{\\}. For example,
801 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
805 replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
806 with @samp{cddr-safe}.
809 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
813 performs the inverse transformation.
815 @node Replacement and Case, Query Replace, Regexp Replace, Replace
816 @subsection Replace Commands and Case
818 If the first argument of a replace command is all lower case, the
819 commands ignores case while searching for occurrences to
820 replace---provided @code{case-fold-search} is non-@code{nil}. If
821 @code{case-fold-search} is set to @code{nil}, case is always significant
825 In addition, when the @var{newstring} argument is all or partly lower
826 case, replacement commands try to preserve the case pattern of each
827 occurrence. Thus, the command
830 M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
834 replaces a lower case @samp{foo} with a lower case @samp{bar}, an
835 all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
836 @samp{Bar}. (These three alternatives---lower case, all caps, and
837 capitalized, are the only ones that @code{replace-string} can
840 If upper-case letters are used in the replacement string, they remain
841 upper case every time that text is inserted. If upper-case letters are
842 used in the first argument, the second argument is always substituted
843 exactly as given, with no case conversion. Likewise, if either
844 @code{case-replace} or @code{case-fold-search} is set to @code{nil},
845 replacement is done without case conversion.
847 @node Query Replace,, Replacement and Case, Replace
848 @subsection Query Replace
849 @cindex query replace
852 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
853 @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
854 Replace some occurrences of @var{string} with @var{newstring}.
855 @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
856 @itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
857 Replace some matches for @var{regexp} with @var{newstring}.
861 @findex query-replace
862 If you want to change only some of the occurrences of @samp{foo} to
863 @samp{bar}, not all of them, then you cannot use an ordinary
864 @code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}).
865 This command finds occurrences of @samp{foo} one by one, displays each
866 occurrence and asks you whether to replace it. A numeric argument to
867 @code{query-replace} tells it to consider only occurrences that are
868 bounded by word-delimiter characters. This preserves case, just like
869 @code{replace-string}, provided @code{case-replace} is non-@code{nil},
873 @findex query-replace-regexp
874 Aside from querying, @code{query-replace} works just like
875 @code{replace-string}, and @code{query-replace-regexp} works just like
876 @code{replace-regexp}. This command is run by @kbd{C-M-%}.
878 The things you can type when you are shown an occurrence of @var{string}
879 or a match for @var{regexp} are:
881 @ignore @c Not worth it.
882 @kindex SPC @r{(query-replace)}
883 @kindex DEL @r{(query-replace)}
884 @kindex , @r{(query-replace)}
885 @kindex RET @r{(query-replace)}
886 @kindex . @r{(query-replace)}
887 @kindex ! @r{(query-replace)}
888 @kindex ^ @r{(query-replace)}
889 @kindex C-r @r{(query-replace)}
890 @kindex C-w @r{(query-replace)}
891 @kindex C-l @r{(query-replace)}
897 to replace the occurrence with @var{newstring}.
900 to skip to the next occurrence without replacing this one.
903 to replace this occurrence and display the result. You are then asked
904 for another input character to say what to do next. Since the
905 replacement has already been made, @key{DEL} and @key{SPC} are
906 equivalent in this situation; both move to the next occurrence.
908 You can type @kbd{C-r} at this point (see below) to alter the replaced
909 text. You can also type @kbd{C-x u} to undo the replacement; this exits
910 the @code{query-replace}, so if you want to do further replacement you
911 must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
912 (@pxref{Repetition}).
915 to exit without doing any more replacements.
917 @item .@: @r{(Period)}
918 to replace this occurrence and then exit without searching for more
922 to replace all remaining occurrences without asking again.
925 to go back to the position of the previous occurrence (or what used to
926 be an occurrence), in case you changed it by mistake. This works by
927 popping the mark ring. Only one @kbd{^} in a row is meaningful, because
928 only one previous replacement position is kept during @code{query-replace}.
931 to enter a recursive editing level, in case the occurrence needs to be
932 edited rather than just replaced with @var{newstring}. When you are
933 done, exit the recursive editing level with @kbd{C-M-c} to proceed to
934 the next occurrence. @xref{Recursive Edit}.
937 to delete the occurrence, and then enter a recursive editing level as in
938 @kbd{C-r}. Use the recursive edit to insert text to replace the deleted
939 occurrence of @var{string}. When done, exit the recursive editing level
940 with @kbd{C-M-c} to proceed to the next occurrence.
943 to redisplay the screen. Then you must type another character to
944 specify what to do with this occurrence.
947 to let you edit the replacement string.
950 to display a message summarizing these options. Then you must type
951 another character to specify what to do with this occurrence.
954 Some other characters are aliases for the ones listed above: @kbd{y},
955 @kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
958 Aside from this, any other character exits the @code{query-replace},
959 and is then reread as part of a key sequence. Thus, if you type
960 @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
963 To restart a @code{query-replace} once it is exited, use @kbd{C-x
964 @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
965 used the minibuffer to read its arguments. @xref{Repetition, C-x ESC
968 See also @ref{Transforming File Names}, for Dired commands to rename,
969 copy, or link files by replacing regexp matches in file names.
971 @node Other Repeating Search,, Replace, Search
972 @section Other Search-and-Loop Commands
974 Here are some other commands that find matches for a regular
975 expression. They all operate from point to the end of the buffer, and
976 all ignore case in matching, if the pattern contains no upper-case
977 letters and @code{case-fold-search} is non-@code{nil}.
979 @findex list-matching-lines
982 @findex delete-non-matching-lines
983 @findex delete-matching-lines
988 @item M-x occur @key{RET} @var{regexp} @key{RET}
989 Display a list showing each line in the buffer that contains a match for
990 @var{regexp}. A numeric argument specifies the number of context lines
991 to print before and after each matching line; the default is none.
992 To limit the search to part of the buffer, narrow to that part
995 @kindex RET @r{(Occur mode)}
996 The buffer @samp{*Occur*} containing the output serves as a menu for
997 finding the occurrences in their original context. Click @kbd{Mouse-2}
998 on an occurrence listed in @samp{*Occur*}, or position point there and
999 type @key{RET}; this switches to the buffer that was searched and
1000 moves point to the original of the chosen occurrence.
1002 @item M-x list-matching-lines
1003 Synonym for @kbd{M-x occur}.
1005 @item M-x how-many @key{RET} @var{regexp} @key{RET}
1006 Print the number of matches for @var{regexp} after point, or in the
1007 active region in Transient Mark mode.
1009 @item M-x flush-lines @key{RET} @var{regexp} @key{RET}
1010 Delete each line after point, or in the active region in Transient Mark
1011 mode, that contains a match for @var{regexp}.
1013 @item M-x keep-lines @key{RET} @var{regexp} @key{RET}
1014 Delete each line that follows point, or is in the active region in
1015 Transient Mark mode, and @emph{does not} contain a match for
1019 Searching and replacing can be performed under the control of tags
1020 files (@pxref{Tags Search}) and Dired (@pxref{Operating on Files}).
1022 In addition, you can use @code{grep} from Emacs to search a collection
1023 of files for matches for a regular expression, then visit the matches
1024 either sequentially or in arbitrary order. @xref{Grep Searching}.