doc/emacs small markup fixes
[emacs.git] / doc / emacs / search.texi
blobbdfb534e1863449f44b8ad214bcb3ccfa5cd6645
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
3 @c Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Search
6 @chapter Searching and Replacement
7 @cindex searching
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}).
20 @menu
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.
32 @end menu
34 @node Incremental Search
35 @section Incremental Search
36 @cindex incremental search
37 @cindex isearch
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}.
47 @table @kbd
48 @item C-s
49 Incremental search forward (@code{isearch-forward}).
50 @item C-r
51 Incremental search backward (@code{isearch-backward}).
52 @end table
54 @menu
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.
63 @end menu
65 @node Basic Isearch
66 @subsection Basics of Incremental Search
68 @table @kbd
69 @item C-s
70 Begin incremental search (@code{isearch-forward}).
71 @item C-r
72 Begin reverse incremental search (@code{isearch-backward}).
73 @end table
75 @kindex C-s
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
92 echo area.
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
106 described below).
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
115 already active.
117 @kindex C-r
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.
124 @node Repeat Isearch
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
152 @kbd{C-r}.
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.
168 @cindex search ring
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
190 @code{isearch-fail}.
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
213 search.
215 @node Special Isearch
216 @subsection Special Input for Incremental Search
218   Some of the characters you type during incremental search have
219 special effects.
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 @key{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
256 following methods:
258 @itemize @bullet
259 @item
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 @samp{control-S} character to the search string.
266 @item
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}).
271 @item
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
281 mnemonic, like this:
283 @example
284 I-search [@var{im}]:
285 @end example
287 @noindent
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.
293 @end itemize
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}).
316 @node Isearch Yank
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.
366 @table @asis
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}):
403 @example
404 (put 'view-lossage 'isearch-scroll t)
405 @end example
407 @noindent
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.
412 @end table
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.
445 @table @kbd
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}.
450 @end table
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}.
466 @node Word Search
467 @section Word Search
468 @cindex word search
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
477 newlines or spaces.
479 @table @kbd
480 @item M-s w
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.
488 @end table
490 @kindex M-s w
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
514 matches whole words.
516 @node Symbol Search
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.
529 @table @kbd
530 @item M-s _
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}).
534 @item M-s .
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.
541 @end table
543 @kindex M-s _
544 @kindex M-s .
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.
563 @node Regexp Search
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
572 the next section.
574 @table @kbd
575 @item C-M-s
576 Begin incremental regexp search (@code{isearch-forward-regexp}).
577 @item C-M-r
578 Begin reverse incremental regexp search (@code{isearch-backward-regexp}).
579 @end table
581 @kindex C-M-s
582 @findex isearch-forward-regexp
583 @kindex C-M-r
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   Unlike ordinary incremental search, incremental regexp search
606 do not use lax space matching by default.  To toggle this feature
607 use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}).
608 Then any @key{SPC} typed in incremental regexp search will match
609 any sequence of one or more whitespace characters.  The variable
610 @code{search-whitespace-regexp} specifies the regexp for the lax
611 space matching.  @xref{Special Isearch}.
613   In some cases, adding characters to the regexp in an incremental
614 regexp search can make the cursor move back and start again.  For
615 example, if you have searched for @samp{foo} and you add @samp{\|bar},
616 the cursor backs up in case the first @samp{bar} precedes the first
617 @samp{foo}.  @xref{Regexps}.
619   Forward and backward regexp search are not symmetrical, because
620 regexp matching in Emacs always operates forward, starting with the
621 beginning of the regexp.  Thus, forward regexp search scans forward,
622 trying a forward match at each possible starting position.  Backward
623 regexp search scans backward, trying a forward match at each possible
624 starting position.  These search methods are not mirror images.
626 @findex re-search-forward
627 @findex re-search-backward
628   Nonincremental search for a regexp is done with the commands
629 @code{re-search-forward} and @code{re-search-backward}.  You can
630 invoke these with @kbd{M-x}, or by way of incremental regexp search
631 with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}.
633   If you use the incremental regexp search commands with a prefix
634 argument, they perform ordinary string search, like
635 @code{isearch-forward} and @code{isearch-backward}.  @xref{Incremental
636 Search}.
638 @node Regexps
639 @section Syntax of Regular Expressions
640 @cindex syntax of regexps
641 @cindex regular expression
642 @cindex regexp
644   This manual describes regular expression features that users
645 typically use.  @xref{Regular Expressions,,, elisp, The Emacs Lisp
646 Reference Manual}, for additional features used mainly in Lisp
647 programs.
649   Regular expressions have a syntax in which a few characters are
650 special constructs and the rest are @dfn{ordinary}.  An ordinary
651 character matches that same character and nothing else.  The special
652 characters are @samp{$^.*+?[\}.  The character @samp{]} is special if
653 it ends a character alternative (see later).  The character @samp{-}
654 is special inside a character alternative.  Any other character
655 appearing in a regular expression is ordinary, unless a @samp{\}
656 precedes it.  (When you use regular expressions in a Lisp program,
657 each @samp{\} must be doubled, see the example near the end of this
658 section.)
660   For example, @samp{f} is not a special character, so it is ordinary, and
661 therefore @samp{f} is a regular expression that matches the string
662 @samp{f} and no other string.  (It does @emph{not} match the string
663 @samp{ff}.)  Likewise, @samp{o} is a regular expression that matches
664 only @samp{o}.  (When case distinctions are being ignored, these regexps
665 also match @samp{F} and @samp{O}, but we consider this a generalization
666 of ``the same string'', rather than an exception.)
668   Any two regular expressions @var{a} and @var{b} can be concatenated.
669 The result is a regular expression which matches a string if @var{a}
670 matches some amount of the beginning of that string and @var{b}
671 matches the rest of the string.  For example, concatenating the
672 regular expressions @samp{f} and @samp{o} gives the regular expression
673 @samp{fo}, which matches only the string @samp{fo}.  Still trivial.
674 To do something nontrivial, you need to use one of the special
675 characters.  Here is a list of them.
677 @table @asis
678 @item @kbd{.}@: @r{(Period)}
679 is a special character that matches any single character except a
680 newline.  For example, the regular expressions @samp{a.b} matches any
681 three-character string that begins with @samp{a} and ends with
682 @samp{b}.
684 @item @kbd{*}
685 is not a construct by itself; it is a postfix operator that means to
686 match the preceding regular expression repetitively any number of
687 times, as many times as possible.  Thus, @samp{o*} matches any number
688 of @samp{o}s, including no @samp{o}s.
690 @samp{*} always applies to the @emph{smallest} possible preceding
691 expression.  Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
692 @samp{fo}.  It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
694 The matcher processes a @samp{*} construct by matching, immediately,
695 as many repetitions as can be found.  Then it continues with the rest
696 of the pattern.  If that fails, backtracking occurs, discarding some
697 of the matches of the @samp{*}-modified construct in case that makes
698 it possible to match the rest of the pattern.  For example, in matching
699 @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
700 tries to match all three @samp{a}s; but the rest of the pattern is
701 @samp{ar} and there is only @samp{r} left to match, so this try fails.
702 The next alternative is for @samp{a*} to match only two @samp{a}s.
703 With this choice, the rest of the regexp matches successfully.
705 @item @kbd{+}
706 is a postfix operator, similar to @samp{*} except that it must match
707 the preceding expression at least once.  Thus, @samp{ca+r} matches the
708 strings @samp{car} and @samp{caaaar} but not the string @samp{cr},
709 whereas @samp{ca*r} matches all three strings.
711 @item @kbd{?}
712 is a postfix operator, similar to @samp{*} except that it can match
713 the preceding expression either once or not at all.  Thus, @samp{ca?r}
714 matches @samp{car} or @samp{cr}, and nothing else.
716 @item @kbd{*?}, @kbd{+?}, @kbd{??}
717 @cindex non-greedy regexp matching
718 are non-@dfn{greedy} variants of the operators above.  The normal
719 operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as
720 long as the overall regexp can still match.  With a following
721 @samp{?}, they will match as little as possible.
723 Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
724 and the string @samp{abbbb}; but if you try to match them both against
725 the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
726 match), while @samp{ab*?}  will match just @samp{a} (the shortest
727 valid match).
729 Non-greedy operators match the shortest possible string starting at a
730 given starting point; in a forward search, though, the earliest
731 possible starting point for match is always the one chosen.  Thus, if
732 you search for @samp{a.*?$} against the text @samp{abbab} followed by
733 a newline, it matches the whole string.  Since it @emph{can} match
734 starting at the first @samp{a}, it does.
736 @item @kbd{\@{@var{n}\@}}
737 is a postfix operator specifying @var{n} repetitions---that is, the
738 preceding regular expression must match exactly @var{n} times in a
739 row.  For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and
740 nothing else.
742 @item @kbd{\@{@var{n},@var{m}\@}}
743 is a postfix operator specifying between @var{n} and @var{m}
744 repetitions---that is, the preceding regular expression must match at
745 least @var{n} times, but no more than @var{m} times.  If @var{m} is
746 omitted, then there is no upper limit, but the preceding regular
747 expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
748 equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
749 @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
751 @item @kbd{[ @dots{} ]}
752 is a @dfn{character set}, beginning with @samp{[} and terminated by
753 @samp{]}.
755 In the simplest case, the characters between the two brackets are what
756 this set can match.  Thus, @samp{[ad]} matches either one @samp{a} or
757 one @samp{d}, and @samp{[ad]*} matches any string composed of just
758 @samp{a}s and @samp{d}s (including the empty string).  It follows that
759 @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
760 @samp{caddaar}, etc.
762 You can also include character ranges in a character set, by writing the
763 starting and ending characters with a @samp{-} between them.  Thus,
764 @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.  Ranges may be
765 intermixed freely with individual characters, as in @samp{[a-z$%.]},
766 which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
767 period.
769 You can also include certain special @dfn{character classes} in a
770 character set.  A @samp{[:} and balancing @samp{:]} enclose a
771 character class inside a character alternative.  For instance,
772 @samp{[[:alnum:]]} matches any letter or digit.  @xref{Char Classes,,,
773 elisp, The Emacs Lisp Reference Manual}, for a list of character
774 classes.
776 To include a @samp{]} in a character set, you must make it the first
777 character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To
778 include a @samp{-}, write @samp{-} as the first or last character of the
779 set, or put it after a range.  Thus, @samp{[]-]} matches both @samp{]}
780 and @samp{-}.
782 To include @samp{^} in a set, put it anywhere but at the beginning of
783 the set.  (At the beginning, it complements the set---see below.)
785 When you use a range in case-insensitive search, you should write both
786 ends of the range in upper case, or both in lower case, or both should
787 be non-letters.  The behavior of a mixed-case range such as @samp{A-z}
788 is somewhat ill-defined, and it may change in future Emacs versions.
790 @item @kbd{[^ @dots{} ]}
791 @samp{[^} begins a @dfn{complemented character set}, which matches any
792 character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
793 all characters @emph{except} @acronym{ASCII} letters and digits.
795 @samp{^} is not special in a character set unless it is the first
796 character.  The character following the @samp{^} is treated as if it
797 were first (in other words, @samp{-} and @samp{]} are not special there).
799 A complemented character set can match a newline, unless newline is
800 mentioned as one of the characters not to match.  This is in contrast to
801 the handling of regexps in programs such as @code{grep}.
803 @item @kbd{^}
804 is a special character that matches the empty string, but only at the
805 beginning of a line in the text being matched.  Otherwise it fails to
806 match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
807 the beginning of a line.
809 For historical compatibility reasons, @samp{^} can be used with this
810 meaning only at the beginning of the regular expression, or after
811 @samp{\(} or @samp{\|}.
813 @item @kbd{$}
814 is similar to @samp{^} but matches only at the end of a line.  Thus,
815 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
817 For historical compatibility reasons, @samp{$} can be used with this
818 meaning only at the end of the regular expression, or before @samp{\)}
819 or @samp{\|}.
821 @item @kbd{\}
822 has two functions: it quotes the special characters (including
823 @samp{\}), and it introduces additional special constructs.
825 Because @samp{\} quotes special characters, @samp{\$} is a regular
826 expression that matches only @samp{$}, and @samp{\[} is a regular
827 expression that matches only @samp{[}, and so on.
829 See the following section for the special constructs that begin
830 with @samp{\}.
831 @end table
833   Note: for historical compatibility, special characters are treated as
834 ordinary ones if they are in contexts where their special meanings make no
835 sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
836 no preceding expression on which the @samp{*} can act.  It is poor practice
837 to depend on this behavior; it is better to quote the special character anyway,
838 regardless of where it appears.
840 As a @samp{\} is not special inside a character alternative, it can
841 never remove the special meaning of @samp{-} or @samp{]}.  So you
842 should not quote these characters when they have no special meaning
843 either.  This would not clarify anything, since backslashes can
844 legitimately precede these characters where they @emph{have} special
845 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
846 which matches any single character except a backslash.
848 @node Regexp Backslash
849 @section Backslash in Regular Expressions
851   For the most part, @samp{\} followed by any character matches only
852 that character.  However, there are several exceptions: two-character
853 sequences starting with @samp{\} that have special meanings.  The
854 second character in the sequence is always an ordinary character when
855 used on its own.  Here is a table of @samp{\} constructs.
857 @table @kbd
858 @item \|
859 specifies an alternative.  Two regular expressions @var{a} and @var{b}
860 with @samp{\|} in between form an expression that matches some text if
861 either @var{a} matches it or @var{b} matches it.  It works by trying to
862 match @var{a}, and if that fails, by trying to match @var{b}.
864 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
865 but no other string.
867 @samp{\|} applies to the largest possible surrounding expressions.  Only a
868 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
869 @samp{\|}.
871 Full backtracking capability exists to handle multiple uses of @samp{\|}.
873 @item \( @dots{} \)
874 is a grouping construct that serves three purposes:
876 @enumerate
877 @item
878 To enclose a set of @samp{\|} alternatives for other operations.
879 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
881 @item
882 To enclose a complicated expression for the postfix operators @samp{*},
883 @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
884 @samp{bananana}, etc., with any (zero or more) number of @samp{na}
885 strings.
887 @item
888 To record a matched substring for future reference.
889 @end enumerate
891 This last application is not a consequence of the idea of a
892 parenthetical grouping; it is a separate feature that is assigned as a
893 second meaning to the same @samp{\( @dots{} \)} construct.  In practice
894 there is usually no conflict between the two meanings; when there is
895 a conflict, you can use a ``shy'' group.
897 @item \(?: @dots{} \)
898 @cindex shy group, in regexp
899 specifies a ``shy'' group that does not record the matched substring;
900 you can't refer back to it with @samp{\@var{d}}.  This is useful
901 in mechanically combining regular expressions, so that you
902 can add groups for syntactic purposes without interfering with
903 the numbering of the groups that are meant to be referred to.
905 @item \@var{d}
906 @cindex back reference, in regexp
907 matches the same text that matched the @var{d}th occurrence of a
908 @samp{\( @dots{} \)} construct.  This is called a @dfn{back
909 reference}.
911 After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
912 the beginning and end of the text matched by that construct.  Then,
913 later on in the regular expression, you can use @samp{\} followed by the
914 digit @var{d} to mean ``match the same text matched the @var{d}th time
915 by the @samp{\( @dots{} \)} construct''.
917 The strings matching the first nine @samp{\( @dots{} \)} constructs
918 appearing in a regular expression are assigned numbers 1 through 9 in
919 the order that the open-parentheses appear in the regular expression.
920 So you can use @samp{\1} through @samp{\9} to refer to the text matched
921 by the corresponding @samp{\( @dots{} \)} constructs.
923 For example, @samp{\(.*\)\1} matches any newline-free string that is
924 composed of two identical halves.  The @samp{\(.*\)} matches the first
925 half, which may be anything, but the @samp{\1} that follows must match
926 the same exact text.
928 If a particular @samp{\( @dots{} \)} construct matches more than once
929 (which can easily happen if it is followed by @samp{*}), only the last
930 match is recorded.
932 @item \`
933 matches the empty string, but only at the beginning of the string or
934 buffer (or its accessible portion) being matched against.
936 @item \'
937 matches the empty string, but only at the end of the string or buffer
938 (or its accessible portion) being matched against.
940 @item \=
941 matches the empty string, but only at point.
943 @item \b
944 matches the empty string, but only at the beginning or
945 end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
946 @samp{foo} as a separate word.  @samp{\bballs?\b} matches
947 @samp{ball} or @samp{balls} as a separate word.
949 @samp{\b} matches at the beginning or end of the buffer
950 regardless of what text appears next to it.
952 @item \B
953 matches the empty string, but @emph{not} at the beginning or
954 end of a word.
956 @item \<
957 matches the empty string, but only at the beginning of a word.
958 @samp{\<} matches at the beginning of the buffer only if a
959 word-constituent character follows.
961 @item \>
962 matches the empty string, but only at the end of a word.  @samp{\>}
963 matches at the end of the buffer only if the contents end with a
964 word-constituent character.
966 @item \w
967 matches any word-constituent character.  The syntax table determines
968 which characters these are.  @xref{Syntax Tables,, Syntax Tables,
969 elisp, The Emacs Lisp Reference Manual}.
971 @item \W
972 matches any character that is not a word-constituent.
974 @item \_<
975 matches the empty string, but only at the beginning of a symbol.
976 A symbol is a sequence of one or more symbol-constituent characters.
977 A symbol-constituent character is a character whose syntax is either
978 @samp{w} or @samp{_}.  @samp{\_<} matches at the beginning of the
979 buffer only if a symbol-constituent character follows.
981 @item \_>
982 matches the empty string, but only at the end of a symbol.  @samp{\_>}
983 matches at the end of the buffer only if the contents end with a
984 symbol-constituent character.
986 @item \s@var{c}
987 matches any character whose syntax is @var{c}.  Here @var{c} is a
988 character that designates a particular syntax class: thus, @samp{w}
989 for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
990 for ordinary punctuation, etc.  @xref{Syntax Tables,, Syntax Tables,
991 elisp, The Emacs Lisp Reference Manual}.
993 @item \S@var{c}
994 matches any character whose syntax is not @var{c}.
996 @cindex categories of characters
997 @cindex characters which belong to a specific language
998 @findex describe-categories
999 @item \c@var{c}
1000 matches any character that belongs to the category @var{c}.  For
1001 example, @samp{\cc} matches Chinese characters, @samp{\cg} matches
1002 Greek characters, etc.  For the description of the known categories,
1003 type @kbd{M-x describe-categories @key{RET}}.
1005 @item \C@var{c}
1006 matches any character that does @emph{not} belong to category
1007 @var{c}.
1008 @end table
1010   The constructs that pertain to words and syntax are controlled by
1011 the setting of the syntax table.  @xref{Syntax Tables,, Syntax Tables,
1012 elisp, The Emacs Lisp Reference Manual}.
1014 @node Regexp Example
1015 @section Regular Expression Example
1017   Here is an example of a regexp---similar to the regexp that Emacs
1018 uses, by default, to recognize the end of a sentence, not including
1019 the following space (i.e., the variable @code{sentence-end-base}):
1021 @example
1022 @verbatim
1023 [.?!][]\"')}]*
1024 @end verbatim
1025 @end example
1027 @noindent
1028 This contains two parts in succession: a character set matching
1029 period, @samp{?}, or @samp{!}, and a character set matching
1030 close-brackets, quotes, or parentheses, repeated zero or more times.
1032 @node Search Case
1033 @section Searching and Case
1035   Searches in Emacs normally ignore the case of the text they are
1036 searching through, if you specify the text in lower case.  Thus, if
1037 you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo}
1038 also match.  Regexps, and in particular character sets, behave
1039 likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or
1040 @samp{B}.
1042   An upper-case letter anywhere in the incremental search string makes
1043 the search case-sensitive.  Thus, searching for @samp{Foo} does not find
1044 @samp{foo} or @samp{FOO}.  This applies to regular expression search as
1045 well as to string search.  The effect ceases if you delete the
1046 upper-case letter from the search string.
1048 @vindex case-fold-search
1049   If you set the variable @code{case-fold-search} to @code{nil}, then
1050 all letters must match exactly, including case.  This is a per-buffer
1051 variable; altering the variable normally affects only the current buffer,
1052 unless you change its default value.  @xref{Locals}.
1053 This variable applies to nonincremental searches also, including those
1054 performed by the replace commands (@pxref{Replace}) and the minibuffer
1055 history matching commands (@pxref{Minibuffer History}).
1057 @c isearch-toggle-case-fold
1058   Typing @kbd{M-c} within an incremental search toggles the case
1059 sensitivity of that search.  The effect does not extend beyond the
1060 current incremental search to the next one, but it does override the
1061 effect of adding or removing an upper-case letter in the current
1062 search.
1064   Several related variables control case-sensitivity of searching and
1065 matching for specific commands or activities.  For instance,
1066 @code{tags-case-fold-search} controls case sensitivity for
1067 @code{find-tag}.  To find these variables, do @kbd{M-x
1068 apropos-variable @key{RET} case-fold-search @key{RET}}.
1070 @node Replace
1071 @section Replacement Commands
1072 @cindex replacement
1073 @cindex search-and-replace commands
1074 @cindex string substitution
1075 @cindex global substitution
1077   Emacs provides several commands for performing search-and-replace
1078 operations.  In addition to the simple @kbd{M-x replace-string}
1079 command, there is @kbd{M-%} (@code{query-replace}), which presents
1080 each occurrence of the pattern and asks you whether to replace it.
1082   The replace commands normally operate on the text from point to the
1083 end of the buffer.  When the region is active, they operate on it
1084 instead (@pxref{Mark}).  The basic replace commands replace one
1085 @dfn{search string} (or regexp) with one @dfn{replacement string}.  It
1086 is possible to perform several replacements in parallel, using the
1087 command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
1089 @vindex replace-lax-whitespace
1090   Unlike incremental search, the replacement commands do not use lax
1091 space matching (@pxref{Special Isearch}) by default.  To enable lax
1092 space matching for replacement, change the variable
1093 @code{replace-lax-whitespace} to @code{t}.  (This only affects how
1094 Emacs finds the text to replace, not the replacement text.)
1096 @menu
1097 * Unconditional Replace::   Replacing all matches for a string.
1098 * Regexp Replace::          Replacing all matches for a regexp.
1099 * Replacement and Case::    How replacements preserve case of letters.
1100 * Query Replace::           How to use querying.
1101 @end menu
1103 @node Unconditional Replace
1104 @subsection Unconditional Replacement
1105 @findex replace-string
1107 @table @kbd
1108 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
1109 Replace every occurrence of @var{string} with @var{newstring}.
1110 @end table
1112   To replace every instance of @samp{foo} after point with @samp{bar},
1113 use the command @kbd{M-x replace-string} with the two arguments
1114 @samp{foo} and @samp{bar}.  Replacement happens only in the text after
1115 point, so if you want to cover the whole buffer you must go to the
1116 beginning first.  All occurrences up to the end of the buffer are
1117 replaced; to limit replacement to part of the buffer, activate the
1118 region around that part.  When the region is active, replacement is
1119 limited to the region (@pxref{Mark}).
1121   When @code{replace-string} exits, it leaves point at the last
1122 occurrence replaced.  It adds the prior position of point (where the
1123 @code{replace-string} command was issued) to the mark ring, without
1124 activating the mark; use @kbd{C-u C-@key{SPC}} to move back there.
1125 @xref{Mark Ring}.
1127   A prefix argument restricts replacement to matches that are
1128 surrounded by word boundaries.
1130   @xref{Replacement and Case}, for details about case-sensitivity in
1131 replace commands.
1133 @node Regexp Replace
1134 @subsection Regexp Replacement
1135 @findex replace-regexp
1137   The @kbd{M-x replace-string} command replaces exact matches for a
1138 single string.  The similar command @kbd{M-x replace-regexp} replaces
1139 any match for a specified pattern.
1141 @table @kbd
1142 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
1143 Replace every match for @var{regexp} with @var{newstring}.
1144 @end table
1146 @cindex back reference, in regexp replacement
1147   In @code{replace-regexp}, the @var{newstring} need not be constant:
1148 it can refer to all or part of what is matched by the @var{regexp}.
1149 @samp{\&} in @var{newstring} stands for the entire match being
1150 replaced.  @samp{\@var{d}} in @var{newstring}, where @var{d} is a
1151 digit, stands for whatever matched the @var{d}th parenthesized
1152 grouping in @var{regexp}.  (This is called a ``back reference''.)
1153 @samp{\#} refers to the count of replacements already made in this
1154 command, as a decimal number.  In the first replacement, @samp{\#}
1155 stands for @samp{0}; in the second, for @samp{1}; and so on.  For
1156 example,
1158 @example
1159 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
1160 @end example
1162 @noindent
1163 replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
1164 with @samp{cddr-safe}.
1166 @example
1167 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
1168 @end example
1170 @noindent
1171 performs the inverse transformation.  To include a @samp{\} in the
1172 text to replace with, you must enter @samp{\\}.
1174   If you want to enter part of the replacement string by hand each
1175 time, use @samp{\?} in the replacement string.  Each replacement will
1176 ask you to edit the replacement string in the minibuffer, putting
1177 point where the @samp{\?} was.
1179   The remainder of this subsection is intended for specialized tasks
1180 and requires knowledge of Lisp.  Most readers can skip it.
1182   You can use Lisp expressions to calculate parts of the
1183 replacement string.  To do this, write @samp{\,} followed by the
1184 expression in the replacement string.  Each replacement calculates the
1185 value of the expression and converts it to text without quoting (if
1186 it's a string, this means using the string's contents), and uses it in
1187 the replacement string in place of the expression itself.  If the
1188 expression is a symbol, one space in the replacement string after the
1189 symbol name goes with the symbol name, so the value replaces them
1190 both.
1192   Inside such an expression, you can use some special sequences.
1193 @samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire
1194 match as a string, and to a submatch as a string.  @var{n} may be
1195 multiple digits, and the value of @samp{\@var{n}} is @code{nil} if
1196 subexpression @var{n} did not match.  You can also use @samp{\#&} and
1197 @samp{\#@var{n}} to refer to those matches as numbers (this is valid
1198 when the match or submatch has the form of a numeral).  @samp{\#} here
1199 too stands for the number of already-completed replacements.
1201   Repeating our example to exchange @samp{x} and @samp{y}, we can thus
1202 do it also this way:
1204 @example
1205 M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
1206 \,(if \1 "y" "x") @key{RET}
1207 @end example
1209   For computing replacement strings for @samp{\,}, the @code{format}
1210 function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs
1211 Lisp Reference Manual}).  For example, to add consecutively numbered
1212 strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
1213 already occupied), you can use
1215 @example
1216 M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
1217 \,(format "%-72sABC%05d" \& \#) @key{RET}
1218 @end example
1220 @node Replacement and Case
1221 @subsection Replace Commands and Case
1223   If the first argument of a replace command is all lower case, the
1224 command ignores case while searching for occurrences to
1225 replace---provided @code{case-fold-search} is non-@code{nil}.  If
1226 @code{case-fold-search} is set to @code{nil}, case is always significant
1227 in all searches.
1229 @vindex case-replace
1230   In addition, when the @var{newstring} argument is all or partly lower
1231 case, replacement commands try to preserve the case pattern of each
1232 occurrence.  Thus, the command
1234 @example
1235 M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
1236 @end example
1238 @noindent
1239 replaces a lower case @samp{foo} with a lower case @samp{bar}, an
1240 all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
1241 @samp{Bar}.  (These three alternatives---lower case, all caps, and
1242 capitalized, are the only ones that @code{replace-string} can
1243 distinguish.)
1245   If upper-case letters are used in the replacement string, they remain
1246 upper case every time that text is inserted.  If upper-case letters are
1247 used in the first argument, the second argument is always substituted
1248 exactly as given, with no case conversion.  Likewise, if either
1249 @code{case-replace} or @code{case-fold-search} is set to @code{nil},
1250 replacement is done without case conversion.
1252 @node Query Replace
1253 @subsection Query Replace
1254 @cindex query replace
1256 @table @kbd
1257 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
1258 Replace some occurrences of @var{string} with @var{newstring}.
1259 @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
1260 Replace some matches for @var{regexp} with @var{newstring}.
1261 @end table
1263 @kindex M-%
1264 @findex query-replace
1265   If you want to change only some of the occurrences of @samp{foo} to
1266 @samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}).
1267 This command finds occurrences of @samp{foo} one by one, displays each
1268 occurrence and asks you whether to replace it.  Aside from querying,
1269 @code{query-replace} works just like @code{replace-string}
1270 (@pxref{Unconditional Replace}).  In particular, it preserves case
1271 provided @code{case-replace} is non-@code{nil}, as it normally is
1272 (@pxref{Replacement and Case}).  A numeric argument means to consider
1273 only occurrences that are bounded by word-delimiter characters.  A
1274 negative prefix argument replaces backward.
1276 @kindex C-M-%
1277 @findex query-replace-regexp
1278   @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}).
1279 It works like @code{replace-regexp} except that it queries
1280 like @code{query-replace}.
1282 @cindex faces for highlighting query replace
1283   These commands highlight the current match using the face
1284 @code{query-replace}.  They highlight other matches using
1285 @code{lazy-highlight} just like incremental search (@pxref{Incremental
1286 Search}).  By default, @code{query-replace-regexp} will show the
1287 substituted replacement string for the current match in the
1288 minibuffer.  If you want to keep special sequences @samp{\&} and
1289 @samp{\@var{n}} unexpanded, customize
1290 @code{query-replace-show-replacement} variable.
1292   The characters you can type when you are shown a match for the string
1293 or regexp are:
1295 @ignore @c Not worth it.
1296 @kindex SPC @r{(query-replace)}
1297 @kindex DEL @r{(query-replace)}
1298 @kindex , @r{(query-replace)}
1299 @kindex RET @r{(query-replace)}
1300 @kindex . @r{(query-replace)}
1301 @kindex ! @r{(query-replace)}
1302 @kindex ^ @r{(query-replace)}
1303 @kindex C-r @r{(query-replace)}
1304 @kindex C-w @r{(query-replace)}
1305 @kindex C-l @r{(query-replace)}
1306 @end ignore
1308 @c WideCommands
1309 @table @kbd
1310 @item @key{SPC}
1311 to replace the occurrence with @var{newstring}.
1313 @item @key{DEL}
1314 to skip to the next occurrence without replacing this one.
1316 @item , @r{(Comma)}
1317 to replace this occurrence and display the result.  You are then asked
1318 for another input character to say what to do next.  Since the
1319 replacement has already been made, @key{DEL} and @key{SPC} are
1320 equivalent in this situation; both move to the next occurrence.
1322 You can type @kbd{C-r} at this point (see below) to alter the replaced
1323 text.  You can also type @kbd{C-x u} to undo the replacement; this exits
1324 the @code{query-replace}, so if you want to do further replacement you
1325 must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
1326 (@pxref{Repetition}).
1328 @item @key{RET}
1329 to exit without doing any more replacements.
1331 @item .@: @r{(Period)}
1332 to replace this occurrence and then exit without searching for more
1333 occurrences.
1335 @item !
1336 to replace all remaining occurrences without asking again.
1338 @item Y @r{(Upper-case)}
1339 to replace all remaining occurrences in all remaining buffers in
1340 multi-buffer replacements (like the Dired @key{Q} command that performs
1341 query replace on selected files).  It answers this question and all
1342 subsequent questions in the series with "yes", without further
1343 user interaction.
1345 @item N @r{(Upper-case)}
1346 to skip to the next buffer in multi-buffer replacements without
1347 replacing remaining occurrences in the current buffer.  It answers
1348 this question "no", gives up on the questions for the current buffer,
1349 and continues to the next buffer in the sequence.
1351 @item ^
1352 to go back to the position of the previous occurrence (or what used to
1353 be an occurrence), in case you changed it by mistake or want to
1354 reexamine it.
1356 @item C-r
1357 to enter a recursive editing level, in case the occurrence needs to be
1358 edited rather than just replaced with @var{newstring}.  When you are
1359 done, exit the recursive editing level with @kbd{C-M-c} to proceed to
1360 the next occurrence.  @xref{Recursive Edit}.
1362 @item C-w
1363 to delete the occurrence, and then enter a recursive editing level as in
1364 @kbd{C-r}.  Use the recursive edit to insert text to replace the deleted
1365 occurrence of @var{string}.  When done, exit the recursive editing level
1366 with @kbd{C-M-c} to proceed to the next occurrence.
1368 @item e
1369 to edit the replacement string in the minibuffer.  When you exit the
1370 minibuffer by typing @key{RET}, the minibuffer contents replace the
1371 current occurrence of the pattern.  They also become the new
1372 replacement string for any further occurrences.
1374 @item C-l
1375 to redisplay the screen.  Then you must type another character to
1376 specify what to do with this occurrence.
1378 @item C-h
1379 to display a message summarizing these options.  Then you must type
1380 another character to specify what to do with this occurrence.
1381 @end table
1383   Some other characters are aliases for the ones listed above: @kbd{y},
1384 @kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
1385 @key{RET}.
1387   Aside from this, any other character exits the @code{query-replace},
1388 and is then reread as part of a key sequence.  Thus, if you type
1389 @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
1390 line.
1392   To restart a @code{query-replace} once it is exited, use @kbd{C-x
1393 @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
1394 used the minibuffer to read its arguments.  @xref{Repetition, C-x ESC
1395 ESC}.
1397 @cindex invisible text, and query-replace
1398   The option @code{search-invisible} determines how @code{query-replace}
1399 treats invisible text.  @xref{Outline Search}.
1401   @xref{Operating on Files}, for the Dired @kbd{Q} command which
1402 performs query replace on selected files.  See also @ref{Transforming
1403 File Names}, for Dired commands to rename, copy, or link files by
1404 replacing regexp matches in file names.
1406 @node Other Repeating Search
1407 @section Other Search-and-Loop Commands
1409   Here are some other commands that find matches for a regular
1410 expression.  They all ignore case in matching, if the pattern contains
1411 no upper-case letters and @code{case-fold-search} is non-@code{nil}.
1412 Aside from @code{occur} and its variants, all operate on the text from
1413 point to the end of the buffer, or on the region if it is active.
1415 @findex list-matching-lines
1416 @findex occur
1417 @findex multi-occur
1418 @findex multi-occur-in-matching-buffers
1419 @findex how-many
1420 @findex flush-lines
1421 @findex keep-lines
1423 @table @kbd
1424 @item M-x multi-isearch-buffers
1425 Prompt for one or more buffer names, ending with @key{RET}; then,
1426 begin a multi-buffer incremental search in those buffers.  (If the
1427 search fails in one buffer, the next @kbd{C-s} tries searching the
1428 next specified buffer, and so forth.)  With a prefix argument, prompt
1429 for a regexp and begin a multi-buffer incremental search in buffers
1430 matching that regexp.
1432 @item M-x multi-isearch-buffers-regexp
1433 This command is just like @code{multi-isearch-buffers}, except it
1434 performs an incremental regexp search.
1436 @cindex Occur mode
1437 @cindex mode, Occur
1438 @item M-x occur
1439 Prompt for a regexp, and display a list showing each line in the
1440 buffer that contains a match for it.  To limit the search to part of
1441 the buffer, narrow to that part (@pxref{Narrowing}).  A numeric
1442 argument @var{n} specifies that @var{n} lines of context are to be
1443 displayed before and after each matching line.
1445 @kindex RET @r{(Occur mode)}
1446 @kindex o @r{(Occur mode)}
1447 @kindex C-o @r{(Occur mode)}
1448 In the @file{*Occur*} buffer, you can click on each entry, or move
1449 point there and type @key{RET}, to visit the corresponding position in
1450 the buffer that was searched.  @kbd{o} and @kbd{C-o} display the match
1451 in another window; @kbd{C-o} does not select it.  Alternatively, you
1452 can use the @kbd{C-x `} (@code{next-error}) command to visit the
1453 occurrences one by one (@pxref{Compilation Mode}).
1455 @cindex Occur Edit mode
1456 @cindex mode, Occur Edit
1457 Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit
1458 mode, in which edits made to the entries are also applied to the text
1459 in the originating buffer.  Type @kbd{C-c C-c} to return to Occur
1460 mode.
1462 The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x
1463 occur}.
1465 @kindex M-s o
1466 @item M-s o
1467 Run @code{occur} using the search string of the last incremental
1468 string search.  You can also run @kbd{M-s o} when an incremental
1469 search is active; this uses the current search string.
1471 @item M-x multi-occur
1472 This command is just like @code{occur}, except it is able to search
1473 through multiple buffers.  It asks you to specify the buffer names one
1474 by one.
1476 @item M-x multi-occur-in-matching-buffers
1477 This command is similar to @code{multi-occur}, except the buffers to
1478 search are specified by a regular expression that matches visited file
1479 names.  With a prefix argument, it uses the regular expression to
1480 match buffer names instead.
1482 @item M-x how-many
1483 Prompt for a regexp, and print the number of matches for it in the
1484 buffer after point.  If the region is active, this operates on the
1485 region instead.
1487 @item M-x flush-lines
1488 Prompt for a regexp, and delete each line that contains a match for
1489 it, operating on the text after point.  This command deletes the
1490 current line if it contains a match starting after point.  If the
1491 region is active, it operates on the region instead; if a line
1492 partially contained in the region contains a match entirely contained
1493 in the region, it is deleted.
1495 If a match is split across lines, @code{flush-lines} deletes all those
1496 lines.  It deletes the lines before starting to look for the next
1497 match; hence, it ignores a match starting on the same line at which
1498 another match ended.
1500 @item M-x keep-lines
1501 Prompt for a regexp, and delete each line that @emph{does not} contain
1502 a match for it, operating on the text after point.  If point is not at
1503 the beginning of a line, this command always keeps the current line.
1504 If the region is active, the command operates on the region instead;
1505 it never deletes lines that are only partially contained in the region
1506 (a newline that ends a line counts as part of that line).
1508 If a match is split across lines, this command keeps all those lines.
1509 @end table