1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
4 @c See file emacs.texi for copying conditions.
6 @chapter Searching and Replacement
8 @cindex finding strings within text
10 Like other editors, Emacs has commands to search for occurrences of
11 a string. Emacs also has commands to replace occurrences of a string
12 with a different string. There are also commands that do the same
13 thing, but search for patterns instead of fixed strings.
15 You can also search multiple files under the control of a tags table
16 (@pxref{Tags Search}) or through the Dired @kbd{A} command
17 (@pxref{Operating on Files}), or ask the @code{grep} program to do it
18 (@pxref{Grep Searching}).
21 * Incremental Search:: Search happens as you type the string.
22 * Nonincremental Search:: Specify entire string and then search.
23 * Word Search:: Search for sequence of words.
24 * Symbol Search:: Search for a source code symbol.
25 * Regexp Search:: Search for match for a regexp.
26 * Regexps:: Syntax of regular expressions.
27 * Regexp Backslash:: Regular expression constructs starting with `\'.
28 * Regexp Example:: A complex regular expression explained.
29 * Search Case:: To ignore case while searching, or not.
30 * Replace:: Search, and replace some or all matches.
31 * Other Repeating Search:: Operating on all matches for some regexp.
34 @node Incremental Search
35 @section Incremental Search
36 @cindex incremental search
39 The principal search command in Emacs is @dfn{incremental}: it
40 begins searching as soon as you type the first character of the search
41 string. As you type in the search string, Emacs shows you where the
42 string (as you have typed it so far) would be found. When you have
43 typed enough characters to identify the place you want, you can stop.
44 Depending on what you plan to do next, you may or may not need to
45 terminate the search explicitly with @key{RET}.
49 Incremental search forward (@code{isearch-forward}).
51 Incremental search backward (@code{isearch-backward}).
55 * Basic Isearch:: Basic incremental search commands.
56 * Repeat Isearch:: Searching for the same string again.
57 * Error in Isearch:: When your string is not found.
58 * Special Isearch:: Special input in incremental search.
59 * Isearch Yank:: Commands that grab text into the search string
60 or else edit the search string.
61 * Not Exiting Isearch:: Prefix argument and scrolling commands.
62 * Isearch Minibuffer:: Incremental search of the minibuffer history.
66 @subsection Basics of Incremental Search
70 Begin incremental search (@code{isearch-forward}).
72 Begin reverse incremental search (@code{isearch-backward}).
76 @findex isearch-forward
77 @kbd{C-s} (@code{isearch-forward}) starts a forward incremental
78 search. It reads characters from the keyboard, and moves point just
79 past the end of the next occurrence of those characters in the buffer.
81 For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the
82 cursor after the first @samp{F} that occurs in the buffer after the
83 starting point. Then if you then type @kbd{O}, the cursor moves to
84 just after the first @samp{FO}; the @samp{F} in that @samp{FO} might
85 not be the first @samp{F} previously found. After another @kbd{O},
86 the cursor moves to just after the first @samp{FOO}.
88 @cindex faces for highlighting search matches
89 At each step, Emacs highlights the @dfn{current match}---the buffer
90 text that matches the search string---using the @code{isearch} face
91 (@pxref{Faces}). The current search string is also displayed in the
94 If you make a mistake typing the search string, type @key{DEL}.
95 Each @key{DEL} cancels the last character of the search string.
97 When you are satisfied with the place you have reached, type
98 @key{RET}. This stops searching, leaving the cursor where the search
99 brought it. Also, any command not specially meaningful in searches
100 stops the searching and is then executed. Thus, typing @kbd{C-a}
101 exits the search and then moves to the beginning of the line.
102 @key{RET} is necessary only if the next command you want to type is a
103 printing character, @key{DEL}, @key{RET}, or another character that is
104 special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
105 @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others
108 As a special exception, entering @key{RET} when the search string is
109 empty launches nonincremental search (@pxref{Nonincremental Search}).
111 When you exit the incremental search, it adds the original value of
112 point to the mark ring, without activating the mark; you can thus use
113 @kbd{C-u C-@key{SPC}} to return to where you were before beginning the
114 search. @xref{Mark Ring}. It only does this if the mark was not
118 @findex isearch-backward
119 To search backwards, use @kbd{C-r} (@code{isearch-backward}) instead
120 of @kbd{C-s} to start the search. A backward search finds matches
121 that end before the starting point, just as a forward search finds
122 matches that begin after it.
125 @subsection Repeating Incremental Search
127 Suppose you search forward for @samp{FOO} and find a match, but not
128 the one you expected to find: the @samp{FOO} you were aiming for
129 occurs later in the buffer. In this event, type another @kbd{C-s} to
130 move to the next occurrence of the search string. You can repeat this
131 any number of times. If you overshoot, you can cancel some @kbd{C-s}
132 characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward
133 incremental search repeats the backward search.
135 @cindex lazy search highlighting
136 @vindex isearch-lazy-highlight
137 If you pause for a little while during incremental search, Emacs
138 highlights all the other possible matches for the search string that
139 are present on the screen. This helps you anticipate where you can
140 get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search. The
141 other matches are highlighted differently from the current match,
142 using the customizable face @code{lazy-highlight} (@pxref{Faces}). If
143 you don't like this feature, you can disable it by setting
144 @code{isearch-lazy-highlight} to @code{nil}.
146 After exiting a search, you can search for the same string again by
147 typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that
148 invokes incremental search, and the second @kbd{C-s} means ``search
149 again''. Similarly, @kbd{C-r C-r} searches backward for the last
150 search string. In determining the last search string, it doesn't
151 matter whether the string was searched for with @kbd{C-s} or
154 If you are searching forward but you realize you were looking for
155 something before the starting point, type @kbd{C-r} to switch to a
156 backward search, leaving the search string unchanged. Similarly,
157 @kbd{C-s} in a backward search switches to a forward search.
159 If a search is failing and you ask to repeat it by typing another
160 @kbd{C-s}, it starts again from the beginning of the buffer.
161 Repeating a failing reverse search with @kbd{C-r} starts again from
162 the end. This is called @dfn{wrapping around}, and @samp{Wrapped}
163 appears in the search prompt once this has happened. If you keep on
164 going past the original starting point of the search, it changes to
165 @samp{Overwrapped}, which means that you are revisiting matches that
166 you have already seen.
169 @kindex M-n @r{(Incremental search)}
170 @kindex M-p @r{(Incremental search)}
171 To reuse earlier search strings, use the @dfn{search ring}. The
172 commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a
173 search string to reuse. These commands leave the selected search ring
174 element in the minibuffer, where you can edit it.
176 @kindex M-e @r{(Incremental search)}
177 To edit the current search string in the minibuffer without
178 replacing it with items from the search ring, type @kbd{M-e}. Type @key{RET},
179 @kbd{C-s} or @kbd{C-r} to finish editing the string and search for it.
181 @node Error in Isearch
182 @subsection Errors in Incremental Search
184 If your string is not found at all, the echo area says @samp{Failing
185 I-Search}, and the cursor moves past the place where Emacs found as
186 much of your string as it could. Thus, if you search for @samp{FOOT},
187 and there is no @samp{FOOT}, you might see the cursor after the
188 @samp{FOO} in @samp{FOOL}. In the echo area, the part of the search
189 string that failed to match is highlighted using the face
192 At this point, there are several things you can do. If your string
193 was mistyped, you can use @key{DEL} to erase some of it and correct
194 it. If you like the place you have found, you can type @key{RET} to
195 remain there. Or you can type @kbd{C-g}, which removes from the
196 search string the characters that could not be found (the @samp{T} in
197 @samp{FOOT}), leaving those that were found (the @samp{FOO} in
198 @samp{FOOT}). A second @kbd{C-g} at that point cancels the search
199 entirely, returning point to where it was when the search started.
201 @cindex quitting (in search)
202 @kindex C-g @r{(Incremental search)}
203 The quit command, @kbd{C-g}, does special things during searches;
204 just what it does depends on the status of the search. If the search
205 has found what you specified and is waiting for input, @kbd{C-g}
206 cancels the entire search, moving the cursor back to where you started
207 the search. If @kbd{C-g} is typed when there are characters in the
208 search string that have not been found---because Emacs is still
209 searching for them, or because it has failed to find them---then the
210 search string characters which have not been found are discarded from
211 the search string. With them gone, the search is now successful and
212 waiting for more input, so a second @kbd{C-g} will cancel the entire
215 @node Special Isearch
216 @subsection Special Input for Incremental Search
218 Some of the characters you type during incremental search have
221 @cindex lax space matching
222 @kindex M-s SPC @r{(Incremental search)}
223 @kindex SPC @r{(Incremental search)}
224 @findex isearch-toggle-lax-whitespace
225 @vindex search-whitespace-regexp
226 By default, incremental search performs @dfn{lax space matching}:
227 each space, or sequence of spaces, matches any sequence of one or more
228 spaces in the text. Hence, @samp{foo bar} matches @samp{foo bar},
229 @samp{foo bar}, @samp{foo bar}, and so on (but not @samp{foobar}).
230 More precisely, Emacs matches each sequence of space characters in the
231 search string to a regular expression specified by the variable
232 @code{search-whitespace-regexp}. For example, to make spaces match
233 sequences of newlines as well as spaces, set it to
234 @samp{"[[:space:]\n]+"}.
236 To toggle lax space matching, type @kbd{M-s SPC}
237 (@code{isearch-toggle-lax-whitespace}). To disable this feature
238 entirely, change @code{search-whitespace-regexp} to @code{nil}; then
239 each space in the search string matches exactly one space.
241 If the search string you entered contains only lower-case letters,
242 the search is case-insensitive; as long as an upper-case letter exists
243 in the search string, the search becomes case-sensitive. If you
244 delete the upper-case character from the search string, it ceases to
245 have this effect. @xref{Search Case}.
247 @cindex invisible text, searching for
248 @kindex M-s i @r{(Incremental search)}
249 @findex isearch-toggle-invisible
250 To toggle whether or not invisible text is searched, type
251 @kbd{M-s i} (@code{isearch-toggle-invisible}). @xref{Outline Search}.
253 To search for a newline character, type @kbd{C-j}.
255 To search for non-@acronym{ASCII} characters, use one of the
260 Type @kbd{C-q}, followed by a non-graphic character or a sequence of
261 octal digits. This adds a character to the search string, similar to
262 inserting into a buffer using @kbd{C-q} (@pxref{Inserting Text}). For
263 example, @kbd{C-q C-s} during incremental search adds the
264 @key{control-S} character to the search string.
267 Type @kbd{C-x 8 @key{RET}}, followed by a Unicode name or code-point.
268 This adds the specified character into the search string, similar to
269 the usual @code{insert-char} command (@pxref{Inserting Text}).
272 Use an input method (@pxref{Input Methods}). If an input method is
273 enabled in the current buffer when you start the search, you can use
274 it in the search string also. While typing the search string, you can
275 toggle the input method with @kbd{C-\}
276 (@code{isearch-toggle-input-method}). You can also turn on a
277 non-default input method with @kbd{C-^}
278 (@code{isearch-toggle-specified-input-method}), which prompts for the
279 name of the input method. When an input method is active during
280 incremental search, the search prompt includes the input method
288 @findex isearch-toggle-input-method
289 @findex isearch-toggle-specified-input-method
290 where @var{im} is the mnemonic of the active input method. Any input
291 method you enable during incremental search remains enabled in the
292 current buffer afterwards.
295 @kindex M-% @r{(Incremental search)}
296 Typing @kbd{M-%} in incremental search invokes @code{query-replace}
297 or @code{query-replace-regexp} (depending on search mode) with the
298 current search string used as the string to replace. A negative
299 prefix argument means to replace backward. @xref{Query Replace}.
301 @kindex M-TAB @r{(Incremental search)}
302 Typing @kbd{M-@key{TAB}} in incremental search invokes
303 @code{isearch-complete}, which attempts to complete the search string
304 using the search ring as a list of completion alternatives.
305 @xref{Completion}. In many operating systems, the @kbd{M-@key{TAB}}
306 key sequence is captured by the window manager; you then need to
307 rebind @code{isearch-complete} to another key sequence if you want to
308 use it (@pxref{Rebinding}).
310 @vindex isearch-mode-map
311 When incremental search is active, you can type @kbd{C-h C-h} to
312 access interactive help options, including a list of special key
313 bindings. These key bindings are part of the keymap
314 @code{isearch-mode-map} (@pxref{Keymaps}).
317 @subsection Isearch Yanking
319 @kindex C-y @r{(Incremental search)}
320 @kindex M-y @r{(Incremental search)}
321 @findex isearch-yank-kill
322 @findex isearch-yank-pop
323 Within incremental search, @kbd{C-y} (@code{isearch-yank-kill})
324 appends the current kill to the search string. @kbd{M-y}
325 (@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that
326 appended text with an earlier kill, similar to the usual @kbd{M-y}
327 (@code{yank-pop}) command (@pxref{Yanking}). @kbd{Mouse-2} appends
328 the current X selection (@pxref{Primary Selection}).
330 @kindex C-w @r{(Incremental search)}
331 @findex isearch-yank-word-or-char
332 @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next
333 character or word at point to the search string. This is an easy way
334 to search for another occurrence of the text at point. (The decision
335 of whether to copy a character or a word is heuristic.)
337 @kindex M-s C-e @r{(Incremental search)}
338 @findex isearch-yank-line
339 Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest
340 of the current line to the search string. If point is already at the
341 end of a line, it appends the next line. With a prefix argument
342 @var{n}, it appends the next @var{n} lines.
344 If the search is currently case-insensitive, both @kbd{C-w} and
345 @kbd{M-s C-e} convert the text they copy to lower case, so that the
346 search remains case-insensitive.
348 @kindex C-M-w @r{(Incremental search)}
349 @kindex C-M-y @r{(Incremental search)}
350 @findex isearch-del-char
351 @findex isearch-yank-char
352 @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character
353 from the search string, and @kbd{C-M-y} (@code{isearch-yank-char})
354 appends the character after point to the search string. An
355 alternative method to add the character after point is to enter the
356 minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f}
357 at the end of the search string in the minibuffer.
359 @node Not Exiting Isearch
360 @subsection Not Exiting Incremental Search
362 This subsection describes two categories of commands which you can
363 type without exiting the current incremental search, even though they
364 are not themselves part of incremental search.
367 @item Prefix Arguments
368 @vindex isearch-allow-prefix
369 In incremental search, when you enter a prefix argument
370 (@pxref{Arguments}), by default it will apply either to the next
371 action in the search or to the command that exits the search.
373 In previous versions of Emacs, entering a prefix argument always
374 terminated the search. You can revert to this behavior by setting the
375 variable @code{isearch-allow-prefix} to @code{nil}.
377 When @code{isearch-allow-scroll} is non-@code{nil} (see below),
378 prefix arguments always have the default behavior described above.
380 @item Scrolling Commands
381 @vindex isearch-allow-scroll
382 Normally, scrolling commands exit incremental search. If you change
383 the variable @code{isearch-allow-scroll} to a non-@code{nil} value,
384 that enables the use of the scroll-bar, as well as keyboard scrolling
385 commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}).
386 This applies only to calling these commands via their bound key
387 sequences---typing @kbd{M-x} will still exit the search. You can give
388 prefix arguments to these commands in the usual way. This feature
389 won't let you scroll the current match out of visibility, however.
391 The @code{isearch-allow-scroll} feature also affects some other
392 commands, such as @kbd{C-x 2} (@code{split-window-below}) and @kbd{C-x
393 ^} (@code{enlarge-window}), which don't exactly scroll but do affect
394 where the text appears on the screen. It applies to any command whose
395 name has a non-@code{nil} @code{isearch-scroll} property. So you can
396 control which commands are affected by changing these properties.
398 For example, to make @kbd{C-h l} usable within an incremental search
399 in all future Emacs sessions, use @kbd{C-h c} to find what command it
400 runs (@pxref{Key Help}), which is @code{view-lossage}. Then you can
401 put the following line in your init file (@pxref{Init File}):
404 (put 'view-lossage 'isearch-scroll t)
408 This feature can be applied to any command that doesn't permanently
409 change point, the buffer contents, the match data, the current buffer,
410 or the selected window and frame. The command must not itself attempt
411 an incremental search.
414 @node Isearch Minibuffer
415 @subsection Searching the Minibuffer
416 @cindex minibuffer history, searching
418 If you start an incremental search while the minibuffer is active,
419 Emacs searches the contents of the minibuffer. Unlike searching an
420 ordinary buffer, the search string is not shown in the echo area,
421 because that is used to display the minibuffer.
423 If an incremental search fails in the minibuffer, it tries searching
424 the minibuffer history. @xref{Minibuffer History}. You can visualize
425 the minibuffer and its history as a series of ``pages'', with the
426 earliest history element on the first page and the current minibuffer
427 on the last page. A forward search, @kbd{C-s}, searches forward to
428 later pages; a reverse search, @kbd{C-r}, searches backwards to
429 earlier pages. Like in ordinary buffer search, a failing search can
430 wrap around, going from the last page to the first page or vice versa.
432 When the current match is on a history element, that history element
433 is pulled into the minibuffer. If you exit the incremental search
434 normally (e.g., by typing @key{RET}), it remains in the minibuffer
435 afterwards. Canceling the search, with @kbd{C-g}, restores the
436 contents of the minibuffer when you began the search.
438 @node Nonincremental Search
439 @section Nonincremental Search
440 @cindex nonincremental search
442 Emacs also has conventional nonincremental search commands, which require
443 you to type the entire search string before searching begins.
446 @item C-s @key{RET} @var{string} @key{RET}
447 Search for @var{string}.
448 @item C-r @key{RET} @var{string} @key{RET}
449 Search backward for @var{string}.
452 To start a nonincremental search, first type @kbd{C-s @key{RET}}.
453 This enters the minibuffer to read the search string; terminate the
454 string with @key{RET}, and then the search takes place. If the string
455 is not found, the search command signals an error.
457 @findex search-forward
458 @findex search-backward
459 When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
460 search as usual. That command is specially programmed to invoke the
461 command for nonincremental search, @code{search-forward}, if the
462 string you specify is empty. (Such an empty argument would otherwise
463 be useless.) @kbd{C-r @key{RET}} does likewise, invoking the command
464 @code{search-backward}.
470 A @dfn{word search} finds a sequence of words without regard to the
471 type of punctuation between them. For instance, if you enter a search
472 string that consists of two words separated by a single space, the
473 search matches any sequence of those two words separated by one or
474 more spaces, newlines, or other punctuation characters. This is
475 particularly useful for searching text documents, because you don't
476 have to worry whether the words you are looking for are separated by
481 If incremental search is active, toggle word search mode
482 (@code{isearch-toggle-word}); otherwise, begin an incremental forward
483 word search (@code{isearch-forward-word}).
484 @item M-s w @key{RET} @var{words} @key{RET}
485 Search for @var{words}, using a forward nonincremental word search.
486 @item M-s w C-r @key{RET} @var{words} @key{RET}
487 Search backward for @var{words}, using a nonincremental word search.
491 @findex isearch-forward-word
492 To begin a forward incremental word search, type @kbd{M-s w}. If
493 incremental search is not already active, this runs the command
494 @code{isearch-forward-word}. If incremental search is already active
495 (whether a forward or backward search), @kbd{M-s w} switches to a word
496 search while keeping the direction of the search and the current
497 search string unchanged. You can toggle word search back off by
498 typing @kbd{M-s w} again.
500 @findex word-search-forward
501 @findex word-search-backward
502 To begin a nonincremental word search, type @kbd{M-s w @key{RET}}
503 for a forward search, or @kbd{M-s w C-r @key{RET}} for a backward search.
504 These run the commands @code{word-search-forward} and
505 @code{word-search-backward} respectively.
507 Incremental and nonincremental word searches differ slightly in the
508 way they find a match. In a nonincremental word search, each word in
509 the search string must exactly match a whole word. In an incremental
510 word search, the matching is more lax: while you are typing the search
511 string, its first and last words need not match whole words. This is
512 so that the matching can proceed incrementally as you type. This
513 additional laxity does not apply to the lazy highlight, which always
517 @section Symbol Search
518 @cindex symbol search
520 A @dfn{symbol search} is much like an ordinary search, except that
521 the boundaries of the search must match the boundaries of a symbol.
522 The meaning of @dfn{symbol} in this context depends on the major mode,
523 and usually refers to a source code token, such as a Lisp symbol in
524 Emacs Lisp mode. For instance, if you perform an incremental symbol
525 search for the Lisp symbol @code{forward-word}, it would not match
526 @code{isearch-forward-word}. This feature is thus mainly useful for
527 searching source code.
531 If incremental search is active, toggle symbol search mode
532 (@code{isearch-toggle-symbol}); otherwise, begin an incremental
533 forward symbol search (@code{isearch-forward-symbol}).
535 Start a symbol incremental search forward with the symbol found near
536 point added to the search string initially.
537 @item M-s _ @key{RET} @var{symbol} @key{RET}
538 Search forward for @var{symbol}, nonincrementally.
539 @item M-s _ C-r @key{RET} @var{symbol} @key{RET}
540 Search backward for @var{symbol}, nonincrementally.
545 @findex isearch-forward-symbol
546 @findex isearch-forward-symbol-at-point
547 To begin a forward incremental symbol search, type @kbd{M-s _} (or
548 @kbd{M-s .} if the symbol to search is near point). If incremental
549 search is not already active, this runs the command
550 @code{isearch-forward-symbol}. If incremental search is already
551 active, @kbd{M-s _} switches to a symbol search, preserving the
552 direction of the search and the current search string; you can disable
553 symbol search by typing @kbd{M-s _} again. In incremental symbol
554 search, only the beginning of the search string is required to match
555 the beginning of a symbol.
557 To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}}
558 for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward
559 search. In nonincremental symbol searches, the beginning and end of
560 the search string are required to match the beginning and end of a
561 symbol, respectively.
564 @section Regular Expression Search
565 @cindex regexp search
566 @cindex search for a regular expression
568 A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern
569 that denotes a class of alternative strings to match. Emacs
570 provides both incremental and nonincremental ways to search for a
571 match for a regexp. The syntax of regular expressions is explained in
576 Begin incremental regexp search (@code{isearch-forward-regexp}).
578 Begin reverse incremental regexp search (@code{isearch-backward-regexp}).
582 @findex isearch-forward-regexp
584 @findex isearch-backward-regexp
585 Incremental search for a regexp is done by typing @kbd{C-M-s}
586 (@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a
587 prefix argument (whose value does not matter), or by typing @kbd{M-r}
588 within a forward incremental search. This command reads a
589 search string incrementally just like @kbd{C-s}, but it treats the
590 search string as a regexp rather than looking for an exact match
591 against the text in the buffer. Each time you add text to the search
592 string, you make the regexp longer, and the new regexp is searched
593 for. To search backward for a regexp, use @kbd{C-M-r}
594 (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument,
595 or @kbd{M-r} within a backward incremental search.
597 All of the special key sequences in an ordinary incremental search
598 do similar things in an incremental regexp search. For instance,
599 typing @kbd{C-s} immediately after starting the search retrieves the
600 last incremental search regexp used and searches forward for it.
601 Incremental regexp and non-regexp searches have independent defaults.
602 They also have separate search rings, which you can access with
603 @kbd{M-p} and @kbd{M-n}.
605 Just as in ordinary incremental search, any @key{SPC} typed in
606 incremental regexp search matches any sequence of one or more
607 whitespace characters. The variable @code{search-whitespace-regexp}
608 specifies the regexp for the lax space matching, and @kbd{M-s SPC}
609 (@code{isearch-toggle-lax-whitespace}) toggles the feature.
610 @xref{Special Isearch}.
612 In some cases, adding characters to the regexp in an incremental
613 regexp search can make the cursor move back and start again. For
614 example, if you have searched for @samp{foo} and you add @samp{\|bar},
615 the cursor backs up in case the first @samp{bar} precedes the first
616 @samp{foo}. @xref{Regexps}.
618 Forward and backward regexp search are not symmetrical, because
619 regexp matching in Emacs always operates forward, starting with the
620 beginning of the regexp. Thus, forward regexp search scans forward,
621 trying a forward match at each possible starting position. Backward
622 regexp search scans backward, trying a forward match at each possible
623 starting position. These search methods are not mirror images.
625 @findex re-search-forward
626 @findex re-search-backward
627 Nonincremental search for a regexp is done with the commands
628 @code{re-search-forward} and @code{re-search-backward}. You can
629 invoke these with @kbd{M-x}, or by way of incremental regexp search
630 with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}.
632 If you use the incremental regexp search commands with a prefix
633 argument, they perform ordinary string search, like
634 @code{isearch-forward} and @code{isearch-backward}. @xref{Incremental
638 @section Syntax of Regular Expressions
639 @cindex syntax of regexps
640 @cindex regular expression
643 This manual describes regular expression features that users
644 typically use. @xref{Regular Expressions,,, elisp, The Emacs Lisp
645 Reference Manual}, for additional features used mainly in Lisp
648 Regular expressions have a syntax in which a few characters are
649 special constructs and the rest are @dfn{ordinary}. An ordinary
650 character matches that same character and nothing else. The special
651 characters are @samp{$^.*+?[\}. The character @samp{]} is special if
652 it ends a character alternative (see later). The character @samp{-}
653 is special inside a character alternative. Any other character
654 appearing in a regular expression is ordinary, unless a @samp{\}
655 precedes it. (When you use regular expressions in a Lisp program,
656 each @samp{\} must be doubled, see the example near the end of this
659 For example, @samp{f} is not a special character, so it is ordinary, and
660 therefore @samp{f} is a regular expression that matches the string
661 @samp{f} and no other string. (It does @emph{not} match the string
662 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches
663 only @samp{o}. (When case distinctions are being ignored, these regexps
664 also match @samp{F} and @samp{O}, but we consider this a generalization
665 of ``the same string'', rather than an exception.)
667 Any two regular expressions @var{a} and @var{b} can be concatenated.
668 The result is a regular expression which matches a string if @var{a}
669 matches some amount of the beginning of that string and @var{b}
670 matches the rest of the string. For example, concatenating the
671 regular expressions @samp{f} and @samp{o} gives the regular expression
672 @samp{fo}, which matches only the string @samp{fo}. Still trivial.
673 To do something nontrivial, you need to use one of the special
674 characters. Here is a list of them.
677 @item @kbd{.}@: @r{(Period)}
678 is a special character that matches any single character except a
679 newline. For example, the regular expressions @samp{a.b} matches any
680 three-character string that begins with @samp{a} and ends with
684 is not a construct by itself; it is a postfix operator that means to
685 match the preceding regular expression repetitively any number of
686 times, as many times as possible. Thus, @samp{o*} matches any number
687 of @samp{o}s, including no @samp{o}s.
689 @samp{*} always applies to the @emph{smallest} possible preceding
690 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
691 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
693 The matcher processes a @samp{*} construct by matching, immediately,
694 as many repetitions as can be found. Then it continues with the rest
695 of the pattern. If that fails, backtracking occurs, discarding some
696 of the matches of the @samp{*}-modified construct in case that makes
697 it possible to match the rest of the pattern. For example, in matching
698 @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
699 tries to match all three @samp{a}s; but the rest of the pattern is
700 @samp{ar} and there is only @samp{r} left to match, so this try fails.
701 The next alternative is for @samp{a*} to match only two @samp{a}s.
702 With this choice, the rest of the regexp matches successfully.
705 is a postfix operator, similar to @samp{*} except that it must match
706 the preceding expression at least once. Thus, @samp{ca+r} matches the
707 strings @samp{car} and @samp{caaaar} but not the string @samp{cr},
708 whereas @samp{ca*r} matches all three strings.
711 is a postfix operator, similar to @samp{*} except that it can match
712 the preceding expression either once or not at all. Thus, @samp{ca?r}
713 matches @samp{car} or @samp{cr}, and nothing else.
715 @item @kbd{*?}, @kbd{+?}, @kbd{??}
716 @cindex non-greedy regexp matching
717 are non-@dfn{greedy} variants of the operators above. The normal
718 operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as
719 long as the overall regexp can still match. With a following
720 @samp{?}, they will match as little as possible.
722 Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
723 and the string @samp{abbbb}; but if you try to match them both against
724 the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
725 match), while @samp{ab*?} will match just @samp{a} (the shortest
728 Non-greedy operators match the shortest possible string starting at a
729 given starting point; in a forward search, though, the earliest
730 possible starting point for match is always the one chosen. Thus, if
731 you search for @samp{a.*?$} against the text @samp{abbab} followed by
732 a newline, it matches the whole string. Since it @emph{can} match
733 starting at the first @samp{a}, it does.
735 @item @kbd{\@{@var{n}\@}}
736 is a postfix operator specifying @var{n} repetitions---that is, the
737 preceding regular expression must match exactly @var{n} times in a
738 row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and
741 @item @kbd{\@{@var{n},@var{m}\@}}
742 is a postfix operator specifying between @var{n} and @var{m}
743 repetitions---that is, the preceding regular expression must match at
744 least @var{n} times, but no more than @var{m} times. If @var{m} is
745 omitted, then there is no upper limit, but the preceding regular
746 expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
747 equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
748 @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
750 @item @kbd{[ @dots{} ]}
751 is a @dfn{character set}, beginning with @samp{[} and terminated by
754 In the simplest case, the characters between the two brackets are what
755 this set can match. Thus, @samp{[ad]} matches either one @samp{a} or
756 one @samp{d}, and @samp{[ad]*} matches any string composed of just
757 @samp{a}s and @samp{d}s (including the empty string). It follows that
758 @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
761 You can also include character ranges in a character set, by writing the
762 starting and ending characters with a @samp{-} between them. Thus,
763 @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be
764 intermixed freely with individual characters, as in @samp{[a-z$%.]},
765 which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
768 You can also include certain special @dfn{character classes} in a
769 character set. A @samp{[:} and balancing @samp{:]} enclose a
770 character class inside a character alternative. For instance,
771 @samp{[[:alnum:]]} matches any letter or digit. @xref{Char Classes,,,
772 elisp, The Emacs Lisp Reference Manual}, for a list of character
775 To include a @samp{]} in a character set, you must make it the first
776 character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
777 include a @samp{-}, write @samp{-} as the first or last character of the
778 set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]}
781 To include @samp{^} in a set, put it anywhere but at the beginning of
782 the set. (At the beginning, it complements the set---see below.)
784 When you use a range in case-insensitive search, you should write both
785 ends of the range in upper case, or both in lower case, or both should
786 be non-letters. The behavior of a mixed-case range such as @samp{A-z}
787 is somewhat ill-defined, and it may change in future Emacs versions.
789 @item @kbd{[^ @dots{} ]}
790 @samp{[^} begins a @dfn{complemented character set}, which matches any
791 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
792 all characters @emph{except} @acronym{ASCII} letters and digits.
794 @samp{^} is not special in a character set unless it is the first
795 character. The character following the @samp{^} is treated as if it
796 were first (in other words, @samp{-} and @samp{]} are not special there).
798 A complemented character set can match a newline, unless newline is
799 mentioned as one of the characters not to match. This is in contrast to
800 the handling of regexps in programs such as @code{grep}.
803 is a special character that matches the empty string, but only at the
804 beginning of a line in the text being matched. Otherwise it fails to
805 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
806 the beginning of a line.
808 For historical compatibility reasons, @samp{^} can be used with this
809 meaning only at the beginning of the regular expression, or after
810 @samp{\(} or @samp{\|}.
813 is similar to @samp{^} but matches only at the end of a line. Thus,
814 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
816 For historical compatibility reasons, @samp{$} can be used with this
817 meaning only at the end of the regular expression, or before @samp{\)}
821 has two functions: it quotes the special characters (including
822 @samp{\}), and it introduces additional special constructs.
824 Because @samp{\} quotes special characters, @samp{\$} is a regular
825 expression that matches only @samp{$}, and @samp{\[} is a regular
826 expression that matches only @samp{[}, and so on.
828 See the following section for the special constructs that begin
832 Note: for historical compatibility, special characters are treated as
833 ordinary ones if they are in contexts where their special meanings make no
834 sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
835 no preceding expression on which the @samp{*} can act. It is poor practice
836 to depend on this behavior; it is better to quote the special character anyway,
837 regardless of where it appears.
839 As a @samp{\} is not special inside a character alternative, it can
840 never remove the special meaning of @samp{-} or @samp{]}. So you
841 should not quote these characters when they have no special meaning
842 either. This would not clarify anything, since backslashes can
843 legitimately precede these characters where they @emph{have} special
844 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
845 which matches any single character except a backslash.
847 @node Regexp Backslash
848 @section Backslash in Regular Expressions
850 For the most part, @samp{\} followed by any character matches only
851 that character. However, there are several exceptions: two-character
852 sequences starting with @samp{\} that have special meanings. The
853 second character in the sequence is always an ordinary character when
854 used on its own. Here is a table of @samp{\} constructs.
858 specifies an alternative. Two regular expressions @var{a} and @var{b}
859 with @samp{\|} in between form an expression that matches some text if
860 either @var{a} matches it or @var{b} matches it. It works by trying to
861 match @var{a}, and if that fails, by trying to match @var{b}.
863 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
866 @samp{\|} applies to the largest possible surrounding expressions. Only a
867 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
870 Full backtracking capability exists to handle multiple uses of @samp{\|}.
873 is a grouping construct that serves three purposes:
877 To enclose a set of @samp{\|} alternatives for other operations.
878 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
881 To enclose a complicated expression for the postfix operators @samp{*},
882 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
883 @samp{bananana}, etc., with any (zero or more) number of @samp{na}
887 To record a matched substring for future reference.
890 This last application is not a consequence of the idea of a
891 parenthetical grouping; it is a separate feature that is assigned as a
892 second meaning to the same @samp{\( @dots{} \)} construct. In practice
893 there is usually no conflict between the two meanings; when there is
894 a conflict, you can use a ``shy'' group.
896 @item \(?: @dots{} \)
897 @cindex shy group, in regexp
898 specifies a ``shy'' group that does not record the matched substring;
899 you can't refer back to it with @samp{\@var{d}}. This is useful
900 in mechanically combining regular expressions, so that you
901 can add groups for syntactic purposes without interfering with
902 the numbering of the groups that are meant to be referred to.
905 @cindex back reference, in regexp
906 matches the same text that matched the @var{d}th occurrence of a
907 @samp{\( @dots{} \)} construct. This is called a @dfn{back
910 After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
911 the beginning and end of the text matched by that construct. Then,
912 later on in the regular expression, you can use @samp{\} followed by the
913 digit @var{d} to mean ``match the same text matched the @var{d}th time
914 by the @samp{\( @dots{} \)} construct''.
916 The strings matching the first nine @samp{\( @dots{} \)} constructs
917 appearing in a regular expression are assigned numbers 1 through 9 in
918 the order that the open-parentheses appear in the regular expression.
919 So you can use @samp{\1} through @samp{\9} to refer to the text matched
920 by the corresponding @samp{\( @dots{} \)} constructs.
922 For example, @samp{\(.*\)\1} matches any newline-free string that is
923 composed of two identical halves. The @samp{\(.*\)} matches the first
924 half, which may be anything, but the @samp{\1} that follows must match
927 If a particular @samp{\( @dots{} \)} construct matches more than once
928 (which can easily happen if it is followed by @samp{*}), only the last
932 matches the empty string, but only at the beginning of the string or
933 buffer (or its accessible portion) being matched against.
936 matches the empty string, but only at the end of the string or buffer
937 (or its accessible portion) being matched against.
940 matches the empty string, but only at point.
943 matches the empty string, but only at the beginning or
944 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
945 @samp{foo} as a separate word. @samp{\bballs?\b} matches
946 @samp{ball} or @samp{balls} as a separate word.
948 @samp{\b} matches at the beginning or end of the buffer
949 regardless of what text appears next to it.
952 matches the empty string, but @emph{not} at the beginning or
956 matches the empty string, but only at the beginning of a word.
957 @samp{\<} matches at the beginning of the buffer only if a
958 word-constituent character follows.
961 matches the empty string, but only at the end of a word. @samp{\>}
962 matches at the end of the buffer only if the contents end with a
963 word-constituent character.
966 matches any word-constituent character. The syntax table determines
967 which characters these are. @xref{Syntax Tables,, Syntax Tables,
968 elisp, The Emacs Lisp Reference Manual}.
971 matches any character that is not a word-constituent.
974 matches the empty string, but only at the beginning of a symbol.
975 A symbol is a sequence of one or more symbol-constituent characters.
976 A symbol-constituent character is a character whose syntax is either
977 @samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the
978 buffer only if a symbol-constituent character follows.
981 matches the empty string, but only at the end of a symbol. @samp{\_>}
982 matches at the end of the buffer only if the contents end with a
983 symbol-constituent character.
986 matches any character whose syntax is @var{c}. Here @var{c} is a
987 character that designates a particular syntax class: thus, @samp{w}
988 for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
989 for ordinary punctuation, etc. @xref{Syntax Tables,, Syntax Tables,
990 elisp, The Emacs Lisp Reference Manual}.
993 matches any character whose syntax is not @var{c}.
995 @cindex categories of characters
996 @cindex characters which belong to a specific language
997 @findex describe-categories
999 matches any character that belongs to the category @var{c}. For
1000 example, @samp{\cc} matches Chinese characters, @samp{\cg} matches
1001 Greek characters, etc. For the description of the known categories,
1002 type @kbd{M-x describe-categories @key{RET}}.
1005 matches any character that does @emph{not} belong to category
1009 The constructs that pertain to words and syntax are controlled by
1010 the setting of the syntax table. @xref{Syntax Tables,, Syntax Tables,
1011 elisp, The Emacs Lisp Reference Manual}.
1013 @node Regexp Example
1014 @section Regular Expression Example
1016 Here is an example of a regexp---similar to the regexp that Emacs
1017 uses, by default, to recognize the end of a sentence, not including
1018 the following space (i.e., the variable @code{sentence-end-base}):
1027 This contains two parts in succession: a character set matching
1028 period, @samp{?}, or @samp{!}, and a character set matching
1029 close-brackets, quotes, or parentheses, repeated zero or more times.
1032 @section Searching and Case
1034 Searches in Emacs normally ignore the case of the text they are
1035 searching through, if you specify the text in lower case. Thus, if
1036 you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo}
1037 also match. Regexps, and in particular character sets, behave
1038 likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or
1041 An upper-case letter anywhere in the incremental search string makes
1042 the search case-sensitive. Thus, searching for @samp{Foo} does not find
1043 @samp{foo} or @samp{FOO}. This applies to regular expression search as
1044 well as to string search. The effect ceases if you delete the
1045 upper-case letter from the search string.
1047 @vindex case-fold-search
1048 If you set the variable @code{case-fold-search} to @code{nil}, then
1049 all letters must match exactly, including case. This is a per-buffer
1050 variable; altering the variable normally affects only the current buffer,
1051 unless you change its default value. @xref{Locals}.
1052 This variable applies to nonincremental searches also, including those
1053 performed by the replace commands (@pxref{Replace}) and the minibuffer
1054 history matching commands (@pxref{Minibuffer History}).
1056 @c isearch-toggle-case-fold
1057 Typing @kbd{M-c} within an incremental search toggles the case
1058 sensitivity of that search. The effect does not extend beyond the
1059 current incremental search to the next one, but it does override the
1060 effect of adding or removing an upper-case letter in the current
1063 Several related variables control case-sensitivity of searching and
1064 matching for specific commands or activities. For instance,
1065 @code{tags-case-fold-search} controls case sensitivity for
1066 @code{find-tag}. To find these variables, do @kbd{M-x
1067 apropos-variable @key{RET} case-fold-search @key{RET}}.
1070 @section Replacement Commands
1072 @cindex search-and-replace commands
1073 @cindex string substitution
1074 @cindex global substitution
1076 Emacs provides several commands for performing search-and-replace
1077 operations. In addition to the simple @kbd{M-x replace-string}
1078 command, there is @kbd{M-%} (@code{query-replace}), which presents
1079 each occurrence of the pattern and asks you whether to replace it.
1081 The replace commands normally operate on the text from point to the
1082 end of the buffer. When the region is active, they operate on it
1083 instead (@pxref{Mark}). The basic replace commands replace one
1084 @dfn{search string} (or regexp) with one @dfn{replacement string}. It
1085 is possible to perform several replacements in parallel, using the
1086 command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
1088 @vindex replace-lax-whitespace
1089 Unlike incremental search, the replacement commands do not use lax
1090 space matching (@pxref{Special Isearch}) by default. To enable lax
1091 space matching for replacement, change the variable
1092 @code{replace-lax-whitespace} to @code{t}. (This only affects how
1093 Emacs finds the text to replace, not the replacement text.)
1096 * Unconditional Replace:: Replacing all matches for a string.
1097 * Regexp Replace:: Replacing all matches for a regexp.
1098 * Replacement and Case:: How replacements preserve case of letters.
1099 * Query Replace:: How to use querying.
1102 @node Unconditional Replace
1103 @subsection Unconditional Replacement
1104 @findex replace-string
1107 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
1108 Replace every occurrence of @var{string} with @var{newstring}.
1111 To replace every instance of @samp{foo} after point with @samp{bar},
1112 use the command @kbd{M-x replace-string} with the two arguments
1113 @samp{foo} and @samp{bar}. Replacement happens only in the text after
1114 point, so if you want to cover the whole buffer you must go to the
1115 beginning first. All occurrences up to the end of the buffer are
1116 replaced; to limit replacement to part of the buffer, activate the
1117 region around that part. When the region is active, replacement is
1118 limited to the region (@pxref{Mark}).
1120 When @code{replace-string} exits, it leaves point at the last
1121 occurrence replaced. It adds the prior position of point (where the
1122 @code{replace-string} command was issued) to the mark ring, without
1123 activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
1126 A prefix argument restricts replacement to matches that are
1127 surrounded by word boundaries.
1129 @xref{Replacement and Case}, for details about case-sensitivity in
1132 @node Regexp Replace
1133 @subsection Regexp Replacement
1134 @findex replace-regexp
1136 The @kbd{M-x replace-string} command replaces exact matches for a
1137 single string. The similar command @kbd{M-x replace-regexp} replaces
1138 any match for a specified pattern.
1141 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
1142 Replace every match for @var{regexp} with @var{newstring}.
1145 @cindex back reference, in regexp replacement
1146 In @code{replace-regexp}, the @var{newstring} need not be constant:
1147 it can refer to all or part of what is matched by the @var{regexp}.
1148 @samp{\&} in @var{newstring} stands for the entire match being
1149 replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a
1150 digit, stands for whatever matched the @var{d}th parenthesized
1151 grouping in @var{regexp}. (This is called a ``back reference''.)
1152 @samp{\#} refers to the count of replacements already made in this
1153 command, as a decimal number. In the first replacement, @samp{\#}
1154 stands for @samp{0}; in the second, for @samp{1}; and so on. For
1158 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
1162 replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
1163 with @samp{cddr-safe}.
1166 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
1170 performs the inverse transformation. To include a @samp{\} in the
1171 text to replace with, you must enter @samp{\\}.
1173 If you want to enter part of the replacement string by hand each
1174 time, use @samp{\?} in the replacement string. Each replacement will
1175 ask you to edit the replacement string in the minibuffer, putting
1176 point where the @samp{\?} was.
1178 The remainder of this subsection is intended for specialized tasks
1179 and requires knowledge of Lisp. Most readers can skip it.
1181 You can use Lisp expressions to calculate parts of the
1182 replacement string. To do this, write @samp{\,} followed by the
1183 expression in the replacement string. Each replacement calculates the
1184 value of the expression and converts it to text without quoting (if
1185 it's a string, this means using the string's contents), and uses it in
1186 the replacement string in place of the expression itself. If the
1187 expression is a symbol, one space in the replacement string after the
1188 symbol name goes with the symbol name, so the value replaces them
1191 Inside such an expression, you can use some special sequences.
1192 @samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire
1193 match as a string, and to a submatch as a string. @var{n} may be
1194 multiple digits, and the value of @samp{\@var{n}} is @code{nil} if
1195 subexpression @var{n} did not match. You can also use @samp{\#&} and
1196 @samp{\#@var{n}} to refer to those matches as numbers (this is valid
1197 when the match or submatch has the form of a numeral). @samp{\#} here
1198 too stands for the number of already-completed replacements.
1200 Repeating our example to exchange @samp{x} and @samp{y}, we can thus
1201 do it also this way:
1204 M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
1205 \,(if \1 "y" "x") @key{RET}
1208 For computing replacement strings for @samp{\,}, the @code{format}
1209 function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs
1210 Lisp Reference Manual}). For example, to add consecutively numbered
1211 strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
1212 already occupied), you can use
1215 M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
1216 \,(format "%-72sABC%05d" \& \#) @key{RET}
1219 @node Replacement and Case
1220 @subsection Replace Commands and Case
1222 If the first argument of a replace command is all lower case, the
1223 command ignores case while searching for occurrences to
1224 replace---provided @code{case-fold-search} is non-@code{nil}. If
1225 @code{case-fold-search} is set to @code{nil}, case is always significant
1228 @vindex case-replace
1229 In addition, when the @var{newstring} argument is all or partly lower
1230 case, replacement commands try to preserve the case pattern of each
1231 occurrence. Thus, the command
1234 M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
1238 replaces a lower case @samp{foo} with a lower case @samp{bar}, an
1239 all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
1240 @samp{Bar}. (These three alternatives---lower case, all caps, and
1241 capitalized, are the only ones that @code{replace-string} can
1244 If upper-case letters are used in the replacement string, they remain
1245 upper case every time that text is inserted. If upper-case letters are
1246 used in the first argument, the second argument is always substituted
1247 exactly as given, with no case conversion. Likewise, if either
1248 @code{case-replace} or @code{case-fold-search} is set to @code{nil},
1249 replacement is done without case conversion.
1252 @subsection Query Replace
1253 @cindex query replace
1256 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
1257 Replace some occurrences of @var{string} with @var{newstring}.
1258 @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
1259 Replace some matches for @var{regexp} with @var{newstring}.
1263 @findex query-replace
1264 If you want to change only some of the occurrences of @samp{foo} to
1265 @samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}).
1266 This command finds occurrences of @samp{foo} one by one, displays each
1267 occurrence and asks you whether to replace it. Aside from querying,
1268 @code{query-replace} works just like @code{replace-string}
1269 (@pxref{Unconditional Replace}). In particular, it preserves case
1270 provided @code{case-replace} is non-@code{nil}, as it normally is
1271 (@pxref{Replacement and Case}). A numeric argument means to consider
1272 only occurrences that are bounded by word-delimiter characters. A
1273 negative prefix argument replaces backward.
1276 @findex query-replace-regexp
1277 @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}).
1278 It works like @code{replace-regexp} except that it queries
1279 like @code{query-replace}.
1281 @cindex faces for highlighting query replace
1282 These commands highlight the current match using the face
1283 @code{query-replace}. They highlight other matches using
1284 @code{lazy-highlight} just like incremental search (@pxref{Incremental
1285 Search}). By default, @code{query-replace-regexp} will show the
1286 substituted replacement string for the current match in the
1287 minibuffer. If you want to keep special sequences @samp{\&} and
1288 @samp{\@var{n}} unexpanded, customize
1289 @code{query-replace-show-replacement} variable.
1291 The characters you can type when you are shown a match for the string
1294 @ignore @c Not worth it.
1295 @kindex SPC @r{(query-replace)}
1296 @kindex DEL @r{(query-replace)}
1297 @kindex , @r{(query-replace)}
1298 @kindex RET @r{(query-replace)}
1299 @kindex . @r{(query-replace)}
1300 @kindex ! @r{(query-replace)}
1301 @kindex ^ @r{(query-replace)}
1302 @kindex C-r @r{(query-replace)}
1303 @kindex C-w @r{(query-replace)}
1304 @kindex C-l @r{(query-replace)}
1310 to replace the occurrence with @var{newstring}.
1313 to skip to the next occurrence without replacing this one.
1316 to replace this occurrence and display the result. You are then asked
1317 for another input character to say what to do next. Since the
1318 replacement has already been made, @key{DEL} and @key{SPC} are
1319 equivalent in this situation; both move to the next occurrence.
1321 You can type @kbd{C-r} at this point (see below) to alter the replaced
1322 text. You can also type @kbd{C-x u} to undo the replacement; this exits
1323 the @code{query-replace}, so if you want to do further replacement you
1324 must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
1325 (@pxref{Repetition}).
1328 to exit without doing any more replacements.
1330 @item .@: @r{(Period)}
1331 to replace this occurrence and then exit without searching for more
1335 to replace all remaining occurrences without asking again.
1337 @item Y @r{(Upper-case)}
1338 to replace all remaining occurrences in all remaining buffers in
1339 multi-buffer replacements (like the Dired `Q' command which performs
1340 query replace on selected files). It answers this question and all
1341 subsequent questions in the series with "yes", without further
1344 @item N @r{(Upper-case)}
1345 to skip to the next buffer in multi-buffer replacements without
1346 replacing remaining occurrences in the current buffer. It answers
1347 this question "no", gives up on the questions for the current buffer,
1348 and continues to the next buffer in the sequence.
1351 to go back to the position of the previous occurrence (or what used to
1352 be an occurrence), in case you changed it by mistake or want to
1356 to enter a recursive editing level, in case the occurrence needs to be
1357 edited rather than just replaced with @var{newstring}. When you are
1358 done, exit the recursive editing level with @kbd{C-M-c} to proceed to
1359 the next occurrence. @xref{Recursive Edit}.
1362 to delete the occurrence, and then enter a recursive editing level as in
1363 @kbd{C-r}. Use the recursive edit to insert text to replace the deleted
1364 occurrence of @var{string}. When done, exit the recursive editing level
1365 with @kbd{C-M-c} to proceed to the next occurrence.
1368 to edit the replacement string in the minibuffer. When you exit the
1369 minibuffer by typing @key{RET}, the minibuffer contents replace the
1370 current occurrence of the pattern. They also become the new
1371 replacement string for any further occurrences.
1374 to redisplay the screen. Then you must type another character to
1375 specify what to do with this occurrence.
1378 to display a message summarizing these options. Then you must type
1379 another character to specify what to do with this occurrence.
1382 Some other characters are aliases for the ones listed above: @kbd{y},
1383 @kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
1386 Aside from this, any other character exits the @code{query-replace},
1387 and is then reread as part of a key sequence. Thus, if you type
1388 @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
1391 To restart a @code{query-replace} once it is exited, use @kbd{C-x
1392 @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
1393 used the minibuffer to read its arguments. @xref{Repetition, C-x ESC
1396 @cindex invisible text, and query-replace
1397 The option @code{search-invisible} determines how @code{query-replace}
1398 treats invisible text. @xref{Outline Search}.
1400 @xref{Operating on Files}, for the Dired @kbd{Q} command which
1401 performs query replace on selected files. See also @ref{Transforming
1402 File Names}, for Dired commands to rename, copy, or link files by
1403 replacing regexp matches in file names.
1405 @node Other Repeating Search
1406 @section Other Search-and-Loop Commands
1408 Here are some other commands that find matches for a regular
1409 expression. They all ignore case in matching, if the pattern contains
1410 no upper-case letters and @code{case-fold-search} is non-@code{nil}.
1411 Aside from @code{occur} and its variants, all operate on the text from
1412 point to the end of the buffer, or on the region if it is active.
1414 @findex list-matching-lines
1417 @findex multi-occur-in-matching-buffers
1423 @item M-x multi-isearch-buffers
1424 Prompt for one or more buffer names, ending with @key{RET}; then,
1425 begin a multi-buffer incremental search in those buffers. (If the
1426 search fails in one buffer, the next @kbd{C-s} tries searching the
1427 next specified buffer, and so forth.) With a prefix argument, prompt
1428 for a regexp and begin a multi-buffer incremental search in buffers
1429 matching that regexp.
1431 @item M-x multi-isearch-buffers-regexp
1432 This command is just like @code{multi-isearch-buffers}, except it
1433 performs an incremental regexp search.
1438 Prompt for a regexp, and display a list showing each line in the
1439 buffer that contains a match for it. To limit the search to part of
1440 the buffer, narrow to that part (@pxref{Narrowing}). A numeric
1441 argument @var{n} specifies that @var{n} lines of context are to be
1442 displayed before and after each matching line.
1444 @kindex RET @r{(Occur mode)}
1445 @kindex o @r{(Occur mode)}
1446 @kindex C-o @r{(Occur mode)}
1447 In the @file{*Occur*} buffer, you can click on each entry, or move
1448 point there and type @key{RET}, to visit the corresponding position in
1449 the buffer that was searched. @kbd{o} and @kbd{C-o} display the match
1450 in another window; @kbd{C-o} does not select it. Alternatively, you
1451 can use the @kbd{C-x `} (@code{next-error}) command to visit the
1452 occurrences one by one (@pxref{Compilation Mode}).
1454 @cindex Occur Edit mode
1455 @cindex mode, Occur Edit
1456 Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit
1457 mode, in which edits made to the entries are also applied to the text
1458 in the originating buffer. Type @kbd{C-c C-c} to return to Occur
1461 The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x
1466 Run @code{occur} using the search string of the last incremental
1467 string search. You can also run @kbd{M-s o} when an incremental
1468 search is active; this uses the current search string.
1470 @item M-x multi-occur
1471 This command is just like @code{occur}, except it is able to search
1472 through multiple buffers. It asks you to specify the buffer names one
1475 @item M-x multi-occur-in-matching-buffers
1476 This command is similar to @code{multi-occur}, except the buffers to
1477 search are specified by a regular expression that matches visited file
1478 names. With a prefix argument, it uses the regular expression to
1479 match buffer names instead.
1482 Prompt for a regexp, and print the number of matches for it in the
1483 buffer after point. If the region is active, this operates on the
1486 @item M-x flush-lines
1487 Prompt for a regexp, and delete each line that contains a match for
1488 it, operating on the text after point. This command deletes the
1489 current line if it contains a match starting after point. If the
1490 region is active, it operates on the region instead; if a line
1491 partially contained in the region contains a match entirely contained
1492 in the region, it is deleted.
1494 If a match is split across lines, @code{flush-lines} deletes all those
1495 lines. It deletes the lines before starting to look for the next
1496 match; hence, it ignores a match starting on the same line at which
1497 another match ended.
1499 @item M-x keep-lines
1500 Prompt for a regexp, and delete each line that @emph{does not} contain
1501 a match for it, operating on the text after point. If point is not at
1502 the beginning of a line, this command always keeps the current line.
1503 If the region is active, the command operates on the region instead;
1504 it never deletes lines that are only partially contained in the region
1505 (a newline that ends a line counts as part of that line).
1507 If a match is split across lines, this command keeps all those lines.