Various small changes in addition to:
[emacs.git] / man / search.texi
blob5fa130a2e50e531e2efd00ef9bea7d7ba2a584c2
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001
3 @c   Free Software Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Search, Fixit, Display, Top
6 @chapter Searching and Replacement
7 @cindex searching
8 @cindex finding strings within text
10   Like other editors, Emacs has commands for searching for occurrences of
11 a string.  The principal search command is unusual in that it is
12 @dfn{incremental}; it begins to search before you have finished typing the
13 search string.  There are also nonincremental search commands more like
14 those of other editors.
16   Besides the usual @code{replace-string} command that finds all
17 occurrences of one string and replaces them with another, Emacs has a
18 more flexible replacement command called @code{query-replace}, which
19 asks interactively which occurrences to replace.
21 @menu
22 * Incremental Search::          Search happens as you type the string.
23 * Nonincremental Search::       Specify entire string and then search.
24 * Word Search::                 Search for sequence of words.
25 * Regexp Search::               Search for match for a regexp.
26 * Regexps::                     Syntax of regular expressions.
27 * Search Case::                 To ignore case while searching, or not.
28 * Configuring Scrolling::       Scrolling within incremental search.
29 * Replace::                     Search, and replace some or all matches.
30 * Other Repeating Search::      Operating on all matches for some regexp.
31 @end menu
33 @node Incremental Search, Nonincremental Search, Search, Search
34 @section Incremental Search
36 @cindex incremental search
37   An incremental search begins searching as soon as you type the first
38 character of the search string.  As you type in the search string, Emacs
39 shows you where the string (as you have typed it so far) would be
40 found.  When you have typed enough characters to identify the place you
41 want, you can stop.  Depending on what you plan to do next, you may or
42 may not need to terminate the search explicitly with @key{RET}.
44 @c WideCommands
45 @table @kbd
46 @item C-s
47 Incremental search forward (@code{isearch-forward}).
48 @item C-r
49 Incremental search backward (@code{isearch-backward}).
50 @end table
52 @kindex C-s
53 @findex isearch-forward
54   @kbd{C-s} starts a forward incremental search.  It reads characters
55 from the keyboard, and moves point past the next occurrence of those
56 characters.  If you type @kbd{C-s} and then @kbd{F}, that puts the
57 cursor after the first @samp{F} (the first following the starting point, since
58 this is a forward search).  Then if you type an @kbd{O}, you will see
59 the cursor move just after the first @samp{FO} (the @samp{F} in that
60 @samp{FO} may or may not be the first @samp{F}).  After another
61 @kbd{O}, the cursor moves after the first @samp{FOO} after the place
62 where you started the search.  At each step, the buffer text that
63 matches the search string is highlighted, if the terminal can do that;
64 the current search string is always displayed in the echo area.
66   If you make a mistake in typing the search string, you can cancel
67 characters with @key{DEL}.  Each @key{DEL} cancels the last character of
68 search string.  This does not happen until Emacs is ready to read another
69 input character; first it must either find, or fail to find, the character
70 you want to erase.  If you do not want to wait for this to happen, use
71 @kbd{C-g} as described below.
73   When you are satisfied with the place you have reached, you can type
74 @key{RET}, which stops searching, leaving the cursor where the search
75 brought it.  Also, any command not specially meaningful in searches
76 stops the searching and is then executed.  Thus, typing @kbd{C-a}
77 would exit the search and then move to the beginning of the line.
78 @key{RET} is necessary only if the next command you want to type is a
79 printing character, @key{DEL}, @key{RET}, or another character that is
80 special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
81 @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some other
82 meta-characters).
84   Sometimes you search for @samp{FOO} and find one, but not the one you
85 expected to find.  There was a second @samp{FOO} that you forgot
86 about, before the one you were aiming for.  In this event, type
87 another @kbd{C-s} to move to the next occurrence of the search string.
88 You can repeat this any number of times.  If you overshoot, you can
89 cancel some @kbd{C-s} characters with @key{DEL}.
91   After you exit a search, you can search for the same string again by
92 typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
93 incremental search, and the second @kbd{C-s} means ``search again.''
95   To reuse earlier search strings, use the @dfn{search ring}.  The
96 commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search
97 string to reuse.  These commands leave the selected search ring element
98 in the minibuffer, where you can edit it.  To edit the current search
99 string in the minibuffer without replacing it with items from the
100 search ring, type @kbd{M-e}.  Type @kbd{C-s} or @kbd{C-r}
101 to terminate editing the string and search for it.
103   If your string is not found at all, the echo area says @samp{Failing
104 I-Search}.  The cursor is after the place where Emacs found as much of your
105 string as it could.  Thus, if you search for @samp{FOOT}, and there is no
106 @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
107 At this point there are several things you can do.  If your string was
108 mistyped, you can rub some of it out and correct it.  If you like the place
109 you have found, you can type @key{RET} or some other Emacs command to
110 remain there.  Or you can type @kbd{C-g}, which
111 removes from the search string the characters that could not be found (the
112 @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
113 @samp{FOOT}).  A second @kbd{C-g} at that point cancels the search
114 entirely, returning point to where it was when the search started.
116   An upper-case letter in the search string makes the search
117 case-sensitive.  If you delete the upper-case character from the search
118 string, it ceases to have this effect.  @xref{Search Case}.
120   To search for a newline, type @kbd{C-j}.  To search for another
121 control character, such as control-S or carriage return, you must quote
122 it by typing @kbd{C-q} first.  This function of @kbd{C-q} is analogous
123 to its use for insertion (@pxref{Inserting Text}): it causes the
124 following character to be treated the way any ``ordinary'' character is
125 treated in the same context.  You can also specify a character by its
126 octal code: enter @kbd{C-q} followed by a sequence of octal digits.
128 @cindex searching for non-@acronym{ASCII} characters
129 @cindex input method, during incremental search
130   To search for non-@acronym{ASCII} characters, you must use an input method
131 (@pxref{Input Methods}).  If an input method is enabled in the
132 current buffer when you start the search, you can use it while you
133 type the search string also.  Emacs indicates that by including the
134 input method mnemonic in its prompt, like this:
136 @example
137 I-search [@var{im}]:
138 @end example
140 @noindent
141 @findex isearch-toggle-input-method
142 @findex isearch-toggle-specified-input-method
143 where @var{im} is the mnemonic of the active input method.  You can
144 toggle (enable or disable) the input method while you type the search
145 string with @kbd{C-\} (@code{isearch-toggle-input-method}).  You can
146 turn on a certain (non-default) input method with @kbd{C-^}
147 (@code{isearch-toggle-specified-input-method}), which prompts for the
148 name of the input method.  The input method you enable during
149 incremental search remains enabled in the current buffer afterwards.
151   If a search is failing and you ask to repeat it by typing another
152 @kbd{C-s}, it starts again from the beginning of the buffer.
153 Repeating a failing reverse search with @kbd{C-r} starts again from
154 the end.  This is called @dfn{wrapping around}, and @samp{Wrapped}
155 appears in the search prompt once this has happened.  If you keep on
156 going past the original starting point of the search, it changes to
157 @samp{Overwrapped}, which means that you are revisiting matches that
158 you have already seen.
160 @cindex quitting (in search)
161   The @kbd{C-g} ``quit'' character does special things during searches;
162 just what it does depends on the status of the search.  If the search has
163 found what you specified and is waiting for input, @kbd{C-g} cancels the
164 entire search.  The cursor moves back to where you started the search.  If
165 @kbd{C-g} is typed when there are characters in the search string that have
166 not been found---because Emacs is still searching for them, or because it
167 has failed to find them---then the search string characters which have not
168 been found are discarded from the search string.  With them gone, the
169 search is now successful and waiting for more input, so a second @kbd{C-g}
170 will cancel the entire search.
172   You can change to searching backwards with @kbd{C-r}.  If a search fails
173 because the place you started was too late in the file, you should do this.
174 Repeated @kbd{C-r} keeps looking for more occurrences backwards.  A
175 @kbd{C-s} starts going forwards again.  @kbd{C-r} in a search can be canceled
176 with @key{DEL}.
178 @kindex C-r
179 @findex isearch-backward
180   If you know initially that you want to search backwards, you can use
181 @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as
182 a key runs a command (@code{isearch-backward}) to search backward.  A
183 backward search finds matches that are entirely before the starting
184 point, just as a forward search finds matches that begin after it.
186   The characters @kbd{C-w} and @kbd{C-y} can be used in incremental
187 search to grab text from the buffer into the search string.  This
188 makes it convenient to search for another occurrence of text at point.
189 @kbd{C-w} copies the character or word after point as part of the
190 search string, advancing point over it.  (The decision, whether to
191 copy a character or a word, is heuristic.)  Another @kbd{C-s} to
192 repeat the search will then search for a string including that
193 character or word.
195   @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the
196 current line into the search string.  Both @kbd{C-y} and @kbd{C-w}
197 convert the text they copy to lower case if the search is currently
198 not case-sensitive; this is so the search remains case-insensitive.
200   @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one
201 character at a time: @kbd{C-M-w} deletes the last character from the
202 search string and @kbd{C-M-y} copies the character after point to the
203 end of the search string.  An alternative method to add the character
204 after point into the search string is to enter the minibuffer by
205 @kbd{M-e} and to type @kbd{C-f} at the end of the search string in the
206 minibuffer.
208   The character @kbd{M-y} copies text from the kill ring into the search
209 string.  It uses the same text that @kbd{C-y} as a command would yank.
210 @kbd{Mouse-2} in the echo area does the same.
211 @xref{Yanking}.
213   When you exit the incremental search, it sets the mark to where point
214 @emph{was}, before the search.  That is convenient for moving back
215 there.  In Transient Mark mode, incremental search sets the mark without
216 activating it, and does so only if the mark is not already active.
218   @kbd{M-%} or @kbd{C-M-%} exits the incremental search and starts an
219 interactive command @code{query-replace} or @code{query-replace-regexp}
220 with the last search string inserted in the minibuffer as initial input
221 for the string to replace.
223 @cindex lazy search highlighting
224 @vindex isearch-lazy-highlight
225   When you pause for a little while during incremental search, it
226 highlights all other possible matches for the search string.  This
227 makes it easier to anticipate where you can get to by typing @kbd{C-s}
228 or @kbd{C-r} to repeat the search.  The short delay before highlighting
229 other matches helps indicate which match is the current one.
230 If you don't like this feature, you can turn it off by setting
231 @code{isearch-lazy-highlight} to @code{nil}.
233 @vindex isearch-lazy-highlight-face
234 @cindex faces for highlighting search matches
235   You can control how this highlighting looks by customizing the faces
236 @code{isearch} (used for the current match) and
237 @code{isearch-lazy-highlight-face} (for all the other matches).
239 @vindex isearch-mode-map
240   To customize the special characters that incremental search understands,
241 alter their bindings in the keymap @code{isearch-mode-map}.  For a list
242 of bindings, look at the documentation of @code{isearch-mode} with
243 @kbd{C-h f isearch-mode @key{RET}}.
245 @subsection Scrolling During Incremental Search
247   Vertical scrolling during incremental search can be enabled by
248 setting the customizable variable @code{isearch-allow-scroll} to a
249 non-@code{nil} value.
251   You can then use the vertical scroll-bar or certain keyboard
252 commands such as @kbd{@key{PRIOR}} (@code{scroll-down}),
253 @kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter})
254 within the search, thus letting you see more of the text near the
255 current match.  You must run these commands via their key sequences to
256 stay in the search---typing M-x @var{comand-name} will always
257 terminate a search.
259   You can give prefix arguments to these commands in the usual way.
260 The current match cannot be scrolled out of the window---this is
261 intentional.
263   Several other commands, such as @kbd{C-x 2}
264 (@code{split-window-vertically}) and @kbd{C-x ^}
265 (@code{enlarge-window}) which don't scroll the window, are
266 nevertheless made available under this rubric, since they are likewise
267 handy during a search.
269   For a list of commands which are configured as scrolling commands by
270 default and instructions on how thus to configure other commands, see
271 @ref{Configuring Scrolling}.
273 @subsection Slow Terminal Incremental Search
275   Incremental search on a slow terminal uses a modified style of display
276 that is designed to take less time.  Instead of redisplaying the buffer at
277 each place the search gets to, it creates a new single-line window and uses
278 that to display the line that the search has found.  The single-line window
279 comes into play as soon as point moves outside of the text that is already
280 on the screen.
282   When you terminate the search, the single-line window is removed.
283 Emacs then redisplays the window in which the search was done, to show
284 its new position of point.
286 @vindex search-slow-speed
287   The slow terminal style of display is used when the terminal baud rate is
288 less than or equal to the value of the variable @code{search-slow-speed},
289 initially 1200.  See @code{baud-rate} in @ref{Display Custom}.
291 @vindex search-slow-window-lines
292   The number of lines to use in slow terminal search display is controlled
293 by the variable @code{search-slow-window-lines}.  Its normal value is 1.
295 @node Nonincremental Search, Word Search, Incremental Search, Search
296 @section Nonincremental Search
297 @cindex nonincremental search
299   Emacs also has conventional nonincremental search commands, which require
300 you to type the entire search string before searching begins.
302 @table @kbd
303 @item C-s @key{RET} @var{string} @key{RET}
304 Search for @var{string}.
305 @item C-r @key{RET} @var{string} @key{RET}
306 Search backward for @var{string}.
307 @end table
309   To do a nonincremental search, first type @kbd{C-s @key{RET}}.  This
310 enters the minibuffer to read the search string; terminate the string
311 with @key{RET}, and then the search takes place.  If the string is not
312 found, the search command signals an error.
314   When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
315 search as usual.  That command is specially programmed to invoke
316 nonincremental search, @code{search-forward}, if the string you
317 specify is empty.  (Such an empty argument would otherwise be
318 useless.)  But it does not call @code{search-forward} right away.  First
319 it checks the next input character to see if is @kbd{C-w},
320 which specifies a word search.
321 @ifinfo
322 @xref{Word Search}.
323 @end ifinfo
324 @kbd{C-r @key{RET}} does likewise, for a reverse incremental search.
326 @findex search-forward
327 @findex search-backward
328   Forward and backward nonincremental searches are implemented by the
329 commands @code{search-forward} and @code{search-backward}.  These
330 commands may be bound to keys in the usual manner.  The feature that you
331 can get to them via the incremental search commands exists for
332 historical reasons, and to avoid the need to find key sequences
333 for them.
335 @node Word Search, Regexp Search, Nonincremental Search, Search
336 @section Word Search
337 @cindex word search
339   Word search searches for a sequence of words without regard to how the
340 words are separated.  More precisely, you type a string of many words,
341 using single spaces to separate them, and the string can be found even
342 if there are multiple spaces, newlines, or other punctuation characters
343 between these words.
345   Word search is useful for editing a printed document made with a text
346 formatter.  If you edit while looking at the printed, formatted version,
347 you can't tell where the line breaks are in the source file.  With word
348 search, you can search without having to know them.
350 @table @kbd
351 @item C-s @key{RET} C-w @var{words} @key{RET}
352 Search for @var{words}, ignoring details of punctuation.
353 @item C-r @key{RET} C-w @var{words} @key{RET}
354 Search backward for @var{words}, ignoring details of punctuation.
355 @end table
357   Word search is a special case of nonincremental search and is invoked
358 with @kbd{C-s @key{RET} C-w}.  This is followed by the search string,
359 which must always be terminated with @key{RET}.  Being nonincremental,
360 this search does not start until the argument is terminated.  It works
361 by constructing a regular expression and searching for that; see
362 @ref{Regexp Search}.
364   Use @kbd{C-r @key{RET} C-w} to do backward word search.
366 @findex word-search-forward
367 @findex word-search-backward
368   Forward and backward word searches are implemented by the commands
369 @code{word-search-forward} and @code{word-search-backward}.  These
370 commands may be bound to keys in the usual manner.  They are available
371 via the incremental search commands both for historical reasons and
372 to avoid the need to find suitable key sequences for them.
374 @node Regexp Search, Regexps, Word Search, Search
375 @section Regular Expression Search
376 @cindex regular expression
377 @cindex regexp
379   A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern
380 that denotes a class of alternative strings to match, possibly
381 infinitely many.  GNU Emacs provides both incremental and
382 nonincremental ways to search for a match for a regexp.
384 @kindex C-M-s
385 @findex isearch-forward-regexp
386 @kindex C-M-r
387 @findex isearch-backward-regexp
388   Incremental search for a regexp is done by typing @kbd{C-M-s}
389 (@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a
390 prefix argument (whose value does not matter), or by typing @kbd{M-r}
391 within a forward incremental search.  This command reads a
392 search string incrementally just like @kbd{C-s}, but it treats the
393 search string as a regexp rather than looking for an exact match
394 against the text in the buffer.  Each time you add text to the search
395 string, you make the regexp longer, and the new regexp is searched
396 for.  To search backward for a regexp, use @kbd{C-M-r}
397 (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument,
398 or @kbd{M-r} within a backward incremental search.
400   All of the control characters that do special things within an
401 ordinary incremental search have the same function in incremental regexp
402 search.  Typing @kbd{C-s} or @kbd{C-r} immediately after starting the
403 search retrieves the last incremental search regexp used; that is to
404 say, incremental regexp and non-regexp searches have independent
405 defaults.  They also have separate search rings that you can access with
406 @kbd{M-p} and @kbd{M-n}.
408   If you type @key{SPC} in incremental regexp search, it matches any
409 sequence of whitespace characters, including newlines.  If you want
410 to match just a space, type @kbd{C-q @key{SPC}}.
412   Note that adding characters to the regexp in an incremental regexp
413 search can make the cursor move back and start again.  For example, if
414 you have searched for @samp{foo} and you add @samp{\|bar}, the cursor
415 backs up in case the first @samp{bar} precedes the first @samp{foo}.
417 @findex re-search-forward
418 @findex re-search-backward
419   Nonincremental search for a regexp is done by the functions
420 @code{re-search-forward} and @code{re-search-backward}.  You can invoke
421 these with @kbd{M-x}, or bind them to keys, or invoke them by way of
422 incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r
423 @key{RET}}.
425   If you use the incremental regexp search commands with a prefix
426 argument, they perform ordinary string search, like
427 @code{isearch-forward} and @code{isearch-backward}.  @xref{Incremental
428 Search}.
430 @node Regexps, Search Case, Regexp Search, Search
431 @section Syntax of Regular Expressions
432 @cindex syntax of regexps
434   This manual describes regular expression features that users
435 typically want to use.  There are additional features that are
436 mainly used in Lisp programs; see @ref{Regular Expressions,,,
437 elisp, the same manual}.
439   Regular expressions have a syntax in which a few characters are
440 special constructs and the rest are @dfn{ordinary}.  An ordinary
441 character is a simple regular expression which matches that same
442 character and nothing else.  The special characters are @samp{$},
443 @samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, @samp{]} and
444 @samp{\}.  Any other character appearing in a regular expression is
445 ordinary, unless a @samp{\} precedes it.  (When you use regular
446 expressions in a Lisp program, each @samp{\} must be doubled, see the
447 example near the end of this section.)
449   For example, @samp{f} is not a special character, so it is ordinary, and
450 therefore @samp{f} is a regular expression that matches the string
451 @samp{f} and no other string.  (It does @emph{not} match the string
452 @samp{ff}.)  Likewise, @samp{o} is a regular expression that matches
453 only @samp{o}.  (When case distinctions are being ignored, these regexps
454 also match @samp{F} and @samp{O}, but we consider this a generalization
455 of ``the same string,'' rather than an exception.)
457   Any two regular expressions @var{a} and @var{b} can be concatenated.  The
458 result is a regular expression which matches a string if @var{a} matches
459 some amount of the beginning of that string and @var{b} matches the rest of
460 the string.@refill
462   As a simple example, we can concatenate the regular expressions @samp{f}
463 and @samp{o} to get the regular expression @samp{fo}, which matches only
464 the string @samp{fo}.  Still trivial.  To do something nontrivial, you
465 need to use one of the special characters.  Here is a list of them.
467 @table @asis
468 @item @kbd{.}@: @r{(Period)}
469 is a special character that matches any single character except a newline.
470 Using concatenation, we can make regular expressions like @samp{a.b}, which
471 matches any three-character string that begins with @samp{a} and ends with
472 @samp{b}.@refill
474 @item @kbd{*}
475 is not a construct by itself; it is a postfix operator that means to
476 match the preceding regular expression repetitively as many times as
477 possible.  Thus, @samp{o*} matches any number of @samp{o}s (including no
478 @samp{o}s).
480 @samp{*} always applies to the @emph{smallest} possible preceding
481 expression.  Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
482 @samp{fo}.  It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
484 The matcher processes a @samp{*} construct by matching, immediately,
485 as many repetitions as can be found.  Then it continues with the rest
486 of the pattern.  If that fails, backtracking occurs, discarding some
487 of the matches of the @samp{*}-modified construct in case that makes
488 it possible to match the rest of the pattern.  For example, in matching
489 @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
490 tries to match all three @samp{a}s; but the rest of the pattern is
491 @samp{ar} and there is only @samp{r} left to match, so this try fails.
492 The next alternative is for @samp{a*} to match only two @samp{a}s.
493 With this choice, the rest of the regexp matches successfully.@refill
495 @item @kbd{+}
496 is a postfix operator, similar to @samp{*} except that it must match
497 the preceding expression at least once.  So, for example, @samp{ca+r}
498 matches the strings @samp{car} and @samp{caaaar} but not the string
499 @samp{cr}, whereas @samp{ca*r} matches all three strings.
501 @item @kbd{?}
502 is a postfix operator, similar to @samp{*} except that it can match the
503 preceding expression either once or not at all.  For example,
504 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
506 @item @kbd{*?}, @kbd{+?}, @kbd{??}
507 @cindex non-greedy regexp matching
508 are non-greedy variants of the operators above.  The normal operators
509 @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as
510 much as they can, as long as the overall regexp can still match.  With
511 a following @samp{?}, they are non-greedy: they will match as little
512 as possible.
514 Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
515 and the string @samp{abbbb}; but if you try to match them both against
516 the text @samp{abbb}, @samp{ab*} will match it all (the longest valid
517 match), while @samp{ab*?}  will match just @samp{a} (the shortest
518 valid match).
520 Non-greedy operators match the shortest possible string starting at a
521 given starting point; in a forward search, though, the earliest
522 possible starting point for match is always the one chosen.  Thus, if
523 you search for @samp{a.*?$} against the text @samp{abbab} followed by
524 a newline, it matches the whole string.  Since it @emph{can} match
525 starting at the first @samp{a}, it does.
527 @item @kbd{\@{@var{n}\@}}
528 is a postfix operator that specifies repetition @var{n} times---that
529 is, the preceding regular expression must match exactly @var{n} times
530 in a row.  For example, @samp{x\@{4\@}} matches the string @samp{xxxx}
531 and nothing else.
533 @item @kbd{\@{@var{n},@var{m}\@}}
534 is a postfix operator that specifies repetition between @var{n} and
535 @var{m} times---that is, the preceding regular expression must match
536 at least @var{n} times, but no more than @var{m} times.  If @var{m} is
537 omitted, then there is no upper limit, but the preceding regular
538 expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
539 equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
540 @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
542 @item @kbd{[ @dots{} ]}
543 is a @dfn{character set}, which begins with @samp{[} and is terminated
544 by @samp{]}.  In the simplest case, the characters between the two
545 brackets are what this set can match.
547 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
548 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
549 (including the empty string), from which it follows that @samp{c[ad]*r}
550 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
552 You can also include character ranges in a character set, by writing the
553 starting and ending characters with a @samp{-} between them.  Thus,
554 @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.  Ranges may be
555 intermixed freely with individual characters, as in @samp{[a-z$%.]},
556 which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
557 period.
559 Note that the usual regexp special characters are not special inside a
560 character set.  A completely different set of special characters exists
561 inside character sets: @samp{]}, @samp{-} and @samp{^}.
563 To include a @samp{]} in a character set, you must make it the first
564 character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.  To
565 include a @samp{-}, write @samp{-} as the first or last character of the
566 set, or put it after a range.  Thus, @samp{[]-]} matches both @samp{]}
567 and @samp{-}.
569 To include @samp{^} in a set, put it anywhere but at the beginning of
570 the set.  (At the beginning, it complements the set---see below.)
572 When you use a range in case-insensitive search, you should write both
573 ends of the range in upper case, or both in lower case, or both should
574 be non-letters.  The behavior of a mixed-case range such as @samp{A-z}
575 is somewhat ill-defined, and it may change in future Emacs versions.
577 @item @kbd{[^ @dots{} ]}
578 @samp{[^} begins a @dfn{complemented character set}, which matches any
579 character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
580 all characters @emph{except} @acronym{ASCII} letters and digits.
582 @samp{^} is not special in a character set unless it is the first
583 character.  The character following the @samp{^} is treated as if it
584 were first (in other words, @samp{-} and @samp{]} are not special there).
586 A complemented character set can match a newline, unless newline is
587 mentioned as one of the characters not to match.  This is in contrast to
588 the handling of regexps in programs such as @code{grep}.
590 @item @kbd{^}
591 is a special character that matches the empty string, but only at the
592 beginning of a line in the text being matched.  Otherwise it fails to
593 match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
594 the beginning of a line.
596 For historical compatibility reasons, @samp{^} can be used with this
597 meaning only at the beginning of the regular expression, or after
598 @samp{\(} or @samp{\|}.
600 @item @kbd{$}
601 is similar to @samp{^} but matches only at the end of a line.  Thus,
602 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
604 For historical compatibility reasons, @samp{$} can be used with this
605 meaning only at the end of the regular expression, or before @samp{\)}
606 or @samp{\|}.
608 @item @kbd{\}
609 has two functions: it quotes the special characters (including
610 @samp{\}), and it introduces additional special constructs.
612 Because @samp{\} quotes special characters, @samp{\$} is a regular
613 expression that matches only @samp{$}, and @samp{\[} is a regular
614 expression that matches only @samp{[}, and so on.
615 @end table
617 Note: for historical compatibility, special characters are treated as
618 ordinary ones if they are in contexts where their special meanings make no
619 sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
620 no preceding expression on which the @samp{*} can act.  It is poor practice
621 to depend on this behavior; it is better to quote the special character anyway,
622 regardless of where it appears.@refill
624 For the most part, @samp{\} followed by any character matches only that
625 character.  However, there are several exceptions: two-character
626 sequences starting with @samp{\} that have special meanings.  The second
627 character in the sequence is always an ordinary character when used on
628 its own.  Here is a table of @samp{\} constructs.
630 @table @kbd
631 @item \|
632 specifies an alternative.  Two regular expressions @var{a} and @var{b}
633 with @samp{\|} in between form an expression that matches some text if
634 either @var{a} matches it or @var{b} matches it.  It works by trying to
635 match @var{a}, and if that fails, by trying to match @var{b}.
637 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
638 but no other string.@refill
640 @samp{\|} applies to the largest possible surrounding expressions.  Only a
641 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
642 @samp{\|}.@refill
644 Full backtracking capability exists to handle multiple uses of @samp{\|}.
646 @item \( @dots{} \)
647 is a grouping construct that serves three purposes:
649 @enumerate
650 @item
651 To enclose a set of @samp{\|} alternatives for other operations.
652 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
654 @item
655 To enclose a complicated expression for the postfix operators @samp{*},
656 @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
657 @samp{bananana}, etc., with any (zero or more) number of @samp{na}
658 strings.@refill
660 @item
661 To record a matched substring for future reference.
662 @end enumerate
664 This last application is not a consequence of the idea of a
665 parenthetical grouping; it is a separate feature that is assigned as a
666 second meaning to the same @samp{\( @dots{} \)} construct.  In practice
667 there is usually no conflict between the two meanings; when there is
668 a conflict, you can use a ``shy'' group.
670 @item \(?: @dots{} \)
671 @cindex shy group, in regexp
672 specifies a ``shy'' group that does not record the matched substring;
673 you can't refer back to it with @samp{\@var{d}}.  This is useful
674 in mechanically combining regular expressions, so that you
675 can add groups for syntactic purposes without interfering with
676 the numbering of the groups that were written by the user.
678 @item \@var{d}
679 matches the same text that matched the @var{d}th occurrence of a
680 @samp{\( @dots{} \)} construct.
682 After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
683 the beginning and end of the text matched by that construct.  Then,
684 later on in the regular expression, you can use @samp{\} followed by the
685 digit @var{d} to mean ``match the same text matched the @var{d}th time
686 by the @samp{\( @dots{} \)} construct.''
688 The strings matching the first nine @samp{\( @dots{} \)} constructs
689 appearing in a regular expression are assigned numbers 1 through 9 in
690 the order that the open-parentheses appear in the regular expression.
691 So you can use @samp{\1} through @samp{\9} to refer to the text matched
692 by the corresponding @samp{\( @dots{} \)} constructs.
694 For example, @samp{\(.*\)\1} matches any newline-free string that is
695 composed of two identical halves.  The @samp{\(.*\)} matches the first
696 half, which may be anything, but the @samp{\1} that follows must match
697 the same exact text.
699 If a particular @samp{\( @dots{} \)} construct matches more than once
700 (which can easily happen if it is followed by @samp{*}), only the last
701 match is recorded.
703 @item \`
704 matches the empty string, but only at the beginning of the string or
705 buffer (or its accessible portion) being matched against.
707 @item \'
708 matches the empty string, but only at the end of the string or buffer
709 (or its accessible portion) being matched against.
711 @item \=
712 matches the empty string, but only at point.
714 @item \b
715 matches the empty string, but only at the beginning or
716 end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
717 @samp{foo} as a separate word.  @samp{\bballs?\b} matches
718 @samp{ball} or @samp{balls} as a separate word.@refill
720 @samp{\b} matches at the beginning or end of the buffer
721 regardless of what text appears next to it.
723 @item \B
724 matches the empty string, but @emph{not} at the beginning or
725 end of a word.
727 @item \<
728 matches the empty string, but only at the beginning of a word.
729 @samp{\<} matches at the beginning of the buffer only if a
730 word-constituent character follows.
732 @item \>
733 matches the empty string, but only at the end of a word.  @samp{\>}
734 matches at the end of the buffer only if the contents end with a
735 word-constituent character.
737 @item \w
738 matches any word-constituent character.  The syntax table
739 determines which characters these are.  @xref{Syntax}.
741 @item \W
742 matches any character that is not a word-constituent.
744 @item \_<
745 matches the empty string, but only at the beginning of a symbol.  A
746 symbol is a sequence of one or more word or symbol constituent
747 characters.  @samp{\_<} matches at the beginning of the buffer only if
748 a symbol-constituent character follows.
750 @item \_>
751 matches the empty string, but only at the end of a symbol.  @samp{\_>}
752 matches at the end of the buffer only if the contents end with a
753 symbol-constituent character.
755 @item \s@var{c}
756 matches any character whose syntax is @var{c}.  Here @var{c} is a
757 character that designates a particular syntax class: thus, @samp{w}
758 for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
759 for ordinary punctuation, etc.  @xref{Syntax}.
761 @item \S@var{c}
762 matches any character whose syntax is not @var{c}.
764 @cindex categories of characters
765 @cindex characters which belong to a specific language
766 @findex describe-categories
767 @item \c@var{c}
768 matches any character that belongs to the category @var{c}.  For
769 example, @samp{\cc} matches Chinese characters, @samp{\cg} matches
770 Greek characters, etc.  For the description of the known categories,
771 type @kbd{M-x describe-categories @key{RET}}.
773 @item \C@var{c}
774 matches any character that does @emph{not} belong to category
775 @var{c}.
776 @end table
778   The constructs that pertain to words and syntax are controlled by the
779 setting of the syntax table (@pxref{Syntax}).
781   Here is a complicated regexp, stored in @code{sentence-end} and used
782 by Emacs to recognize the end of a sentence together with any
783 whitespace that follows.  We show its Lisp syntax to distinguish the
784 spaces from the tab characters.  In Lisp syntax, the string constant
785 begins and ends with a double-quote.  @samp{\"} stands for a
786 double-quote as part of the regexp, @samp{\\} for a backslash as part
787 of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline.
789 @example
790 "[.?!][]\"')]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
791 @end example
793 @noindent
794 This contains four parts in succession: a character set matching
795 period, @samp{?}, or @samp{!}; a character set matching
796 close-brackets, quotes, or parentheses, repeated zero or more times; a
797 set of alternatives within backslash-parentheses that matches either
798 end-of-line, a space at the end of a line, a tab, or two spaces; and a
799 character set matching whitespace characters, repeated any number of
800 times.
802   To enter the same regexp in incremental search, you would type
803 @key{TAB} to enter a tab, and @kbd{C-j} to enter a newline.  You would
804 also type single backslashes as themselves, instead of doubling them
805 for Lisp syntax.  In commands that use ordinary minibuffer input to
806 read a regexp, you would quote the @kbd{C-j} by preceding it with a
807 @kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer.
809 @ignore
810 @c I commented this out because it is missing vital information
811 @c and therefore useless.  For instance, what do you do to *use* the
812 @c regular expression when it is finished?  What jobs is this good for?
813 @c  -- rms
815 @findex re-builder
816 @cindex authoring regular expressions
817   For convenient interactive development of regular expressions, you
818 can use the @kbd{M-x re-builder} command.  It provides a convenient
819 interface for creating regular expressions, by giving immediate visual
820 feedback.  The buffer from which @code{re-builder} was invoked becomes
821 the target for the regexp editor, which pops in a separate window.  At
822 all times, all the matches in the target buffer for the current
823 regular expression are highlighted.  Each parenthesized sub-expression
824 of the regexp is shown in a distinct face, which makes it easier to
825 verify even very complex regexps.  (On displays that don't support
826 colors, Emacs blinks the cursor around the matched text, as it does
827 for matching parens.)
828 @end ignore
830 @node Search Case, Configuring Scrolling, Regexps, Search
831 @section Searching and Case
833   Incremental searches in Emacs normally ignore the case of the text
834 they are searching through, if you specify the text in lower case.
835 Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
836 @samp{foo} are also considered a match.  Regexps, and in particular
837 character sets, are included: @samp{[ab]} would match @samp{a} or
838 @samp{A} or @samp{b} or @samp{B}.@refill
840   An upper-case letter anywhere in the incremental search string makes
841 the search case-sensitive.  Thus, searching for @samp{Foo} does not find
842 @samp{foo} or @samp{FOO}.  This applies to regular expression search as
843 well as to string search.  The effect ceases if you delete the
844 upper-case letter from the search string.
846   Typing @kbd{M-c} within an incremental search toggles the case
847 sensitivity of that search.  The effect does not extend beyond the
848 current incremental search to the next one, but it does override the
849 effect of including an upper-case letter in the current search.
851 @vindex case-fold-search
852   If you set the variable @code{case-fold-search} to @code{nil}, then
853 all letters must match exactly, including case.  This is a per-buffer
854 variable; altering the variable affects only the current buffer, but
855 there is a default value which you can change as well.  @xref{Locals}.
856 This variable applies to nonincremental searches also, including those
857 performed by the replace commands (@pxref{Replace}) and the minibuffer
858 history matching commands (@pxref{Minibuffer History}).
860 @node Configuring Scrolling, Replace, Search Case, Search
861 @section Configuring Scrolling
862 @cindex scrolling in incremental search
863 @vindex isearch-allow-scroll
865 Scrolling, etc., during incremental search is enabled by setting the
866 customizable variable @code{isearch-allow-scroll} to a non-@code{nil} value.
868 @c See Subject: Info file:  How do I get an itemized list without blank lines?
869 @c Date: Sat, 12 Apr 2003 09:45:31 +0000  in gnu.emacs.help
870 @subsection Standard scrolling commands
871 Here is the list of commands which are configured by default to be
872 ``scrolling'' commands in an incremental search, together with their
873 usual bindings:
874 @subsubsection Commands which scroll the window:
875 @table @asis
876 @item @code{scroll-bar-toolkit-scroll} (@kbd{@key{vertical-scroll-bar}@key{mouse-1}} in X-Windows)
877 @itemx @code{mac-handle-scroll-bar-event} (@kbd{@key{vertical-scroll-bar}@key{mouse-1}} on a Mac)
878 @itemx @code{w32-handle-scroll-bar-event} (@kbd{@key{vertical-scroll-bar}@key{mouse-1}} in MS-Windows)
879 @item @code{recenter} (@kbd{C-l}) @xref{Scrolling}.
880 @itemx @code{reposition-window} (@kbd{C-M-l}) @xref{Scrolling}.
881 @itemx @code{scroll-up} (@kbd{@key{NEXT}}) @xref{Scrolling}.
882 @itemx @code{scroll-down} (@kbd{@key{PRIOR}}) @xref{Scrolling}.
883 @end table
885 @subsubsection Commands which act on the other window:
886 @table @asis
887 @item @code{list-buffers} (@kbd{C-x C-b}) @xref{List Buffers}.
888 @itemx @code{scroll-other-window} (@kbd{C-M-v}) @xref{Other Window}.
889 @itemx @code{scroll-other-window-down} (@kbd{C-M-S-v}) @xref{Other Window}.
890 @itemx @code{beginning-of-buffer-other-window} (@kbd{M-@key{home}})
891 @itemx @code{end-of-buffer-other-window} (@kbd{M-@key{end}})
892 @end table
894 @subsubsection Commands which change the window layout:
895 @table @asis
896 @item @code{delete-other-windows} (@kbd{C-x 1}) @xref{Change Window}.
897 @itemx @code{balance-windows} (@kbd{C-x +}) @xref{Change Window}.
898 @itemx @code{split-window-vertically} (@kbd{C-x 2}) @xref{Split Window}.
899 @itemx @code{enlarge-window} (@kbd{C-x ^}) @xref{Change Window}.
900 @end table
902 @subsection Configuring other commands as scrolling commands
903 To do this, set a command's isearch-scroll property to the value t.
904 For example:
906 @example
907 @code{(put 'my-command 'isearch-scroll t)}
908 @end example
910 You should only thus configure commands which are ``safe'': i.e., they
911 won't leave emacs in an inconsistent state when executed within a
912 search---that is to say, the following things may be changed by a
913 command only temporarily, and must be restored before the command
914 finishes:
916 @enumerate
917 @item
918 Point.
919 @item
920 The buffer contents.
921 @item
922 The selected window and selected frame.
923 @item
924 The current match-data @xref{Match Data,,,elisp}.
925 @end enumerate
927 Additionally, the command must not delete the current window and must
928 not itself attempt an incremental search.  It may, however, change the
929 window's size, or create or delete other windows and frames.
931 Note that an attempt by a command to scroll the text
932 @emph{horizontally} won't work, although it will do no harm---any such
933 scrolling will be overriden and nullified by the display code.
935 @node Replace, Other Repeating Search, Configuring Scrolling, Search
936 @section Replacement Commands
937 @cindex replacement
938 @cindex search-and-replace commands
939 @cindex string substitution
940 @cindex global substitution
942   Global search-and-replace operations are not needed often in Emacs,
943 but they are available.  In addition to the simple @kbd{M-x
944 replace-string} command which replaces all occurrences,
945 there is a @kbd{M-x query-replace} command which finds each occurrence
946 of the pattern and asks you whether to replace it.
948   The replace commands normally operate on the text from point to the
949 end of the buffer; however, in Transient Mark mode (@pxref{Transient
950 Mark}), when the mark is active, they operate on the region.  The
951 replace commands all replace one string (or regexp) with one
952 replacement string.  It is possible to perform several replacements in
953 parallel using the command @code{expand-region-abbrevs}
954 (@pxref{Expanding Abbrevs}).
956 @menu
957 * Unconditional Replace::       Replacing all matches for a string.
958 * Regexp Replace::              Replacing all matches for a regexp.
959 * Replacement and Case::        How replacements preserve case of letters.
960 * Query Replace::               How to use querying.
961 @end menu
963 @node Unconditional Replace, Regexp Replace, Replace, Replace
964 @subsection Unconditional Replacement
965 @findex replace-string
966 @findex replace-regexp
968 @table @kbd
969 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
970 Replace every occurrence of @var{string} with @var{newstring}.
971 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
972 Replace every match for @var{regexp} with @var{newstring}.
973 @end table
975   To replace every instance of @samp{foo} after point with @samp{bar},
976 use the command @kbd{M-x replace-string} with the two arguments
977 @samp{foo} and @samp{bar}.  Replacement happens only in the text after
978 point, so if you want to cover the whole buffer you must go to the
979 beginning first.  All occurrences up to the end of the buffer are
980 replaced; to limit replacement to part of the buffer, narrow to that
981 part of the buffer before doing the replacement (@pxref{Narrowing}).
982 In Transient Mark mode, when the region is active, replacement is
983 limited to the region (@pxref{Transient Mark}).
985   When @code{replace-string} exits, it leaves point at the last
986 occurrence replaced.  It sets the mark to the prior position of point
987 (where the @code{replace-string} command was issued); use @kbd{C-u
988 C-@key{SPC}} to move back there.
990   A numeric argument restricts replacement to matches that are surrounded
991 by word boundaries.  The argument's value doesn't matter.
993   What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa?  You can do it this way:
995 @example
996 M-x replace-string @key{RET} x @key{RET} @@TEMP@@ @key{RET}
997 M-< M-x replace-string @key{RET} y @key{RET} x @key{RET}
998 M-< M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET}
999 @end example
1001 @noindent
1002 This works provided the string @samp{@@TEMP@@} does not appear
1003 in your text.
1005 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
1006 @subsection Regexp Replacement
1008   The @kbd{M-x replace-string} command replaces exact matches for a
1009 single string.  The similar command @kbd{M-x replace-regexp} replaces
1010 any match for a specified pattern.
1012   In @code{replace-regexp}, the @var{newstring} need not be constant:
1013 it can refer to all or part of what is matched by the @var{regexp}.
1014 @samp{\&} in @var{newstring} stands for the entire match being
1015 replaced.  @samp{\@var{d}} in @var{newstring}, where @var{d} is a
1016 digit, stands for whatever matched the @var{d}th parenthesized
1017 grouping in @var{regexp}.  @samp{\#} refers to the count of
1018 replacements already made in this command, as a decimal number.  In
1019 the first replacement, @samp{\#} stands for @samp{0}; in the second,
1020 for @samp{1}; and so on.  For example,
1022 @example
1023 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
1024 @end example
1026 @noindent
1027 replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
1028 with @samp{cddr-safe}.
1030 @example
1031 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
1032 @end example
1034 @noindent
1035 performs the inverse transformation.  To include a @samp{\} in the
1036 text to replace with, you must enter @samp{\\}.
1038   You can also use Lisp expressions to calculate parts of the
1039 replacement string.  To do this, write @samp{\,} followed by the
1040 expression in the replacement string.  Each replacement calculates the
1041 value of the expression, which ought to be a string, and uses it in
1042 the replacement string in place of the expression itself.  If the
1043 expression is a symbol, one space in the replacement string after the
1044 symbol name counts as part of the symbol name, so the value replaces
1045 them both.
1047   Inside such an expression, @samp{\&} and @samp{\@var{n}} used as
1048 subexpressions refer respectively to the entire match as a string, and
1049 to a submatch as a string.  @var{n} may exceed 9 here, and the value
1050 of @samp{\@var{n}} is @code{nil} if subexpression @var{n} did not
1051 match.  You can also use @samp{\#&} and @samp{\#@var{n}} refer to
1052 those matches converted to numbers (this is valid when the match or
1053 submatch has the form of a number).  @samp{\#} stands for the number
1054 of already-completed replacements.
1056   Repeating our example to exchange @samp{x} and @samp{y}, we can thus
1057 do it also this way:
1059 @example
1060 M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
1061 \,(if \1 "y" "x") @key{RET}
1062 @end example
1064   The @code{format} function (@pxref{Formatting Strings,,,elisp, GNU
1065 Emacs Lisp Reference Manual}) comes in handy for computing replacement
1066 strings for @samp{\,}.  For example, to add consecutively numbered
1067 strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
1068 already occupied), you can use
1070 @example
1071 M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
1072 \,(format "%-72sABC%05d" \& \#) @key{RET}
1073 @end example
1075   If you want to enter part of the replacement string by hand each
1076 time, use @samp{\?} in the replacement string.  Each replacement will
1077 enter a recursive edit, with point at the position where the @samp{\?}
1078 was.  For example,
1080 @example
1081 M-x replace-regexp @key{RET} \footnote@{ @key{RET}
1082 \&\\label@{fn:\#\?@} @key{RET}
1083 @end example
1085 @noindent
1086 will add labels starting with @samp{\label@{fn:0@}} to occurences of
1087 @samp{\footnote@{}, but letting you edit each replacement before
1088 performing it.  To number the labels starting at 1, use @samp{\,(1+
1089 \#)} instead of @samp{\#}.
1091 @node Replacement and Case, Query Replace, Regexp Replace, Replace
1092 @subsection Replace Commands and Case
1094   If the first argument of a replace command is all lower case, the
1095 command ignores case while searching for occurrences to
1096 replace---provided @code{case-fold-search} is non-@code{nil}.  If
1097 @code{case-fold-search} is set to @code{nil}, case is always significant
1098 in all searches.
1100 @vindex case-replace
1101   In addition, when the @var{newstring} argument is all or partly lower
1102 case, replacement commands try to preserve the case pattern of each
1103 occurrence.  Thus, the command
1105 @example
1106 M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
1107 @end example
1109 @noindent
1110 replaces a lower case @samp{foo} with a lower case @samp{bar}, an
1111 all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
1112 @samp{Bar}.  (These three alternatives---lower case, all caps, and
1113 capitalized, are the only ones that @code{replace-string} can
1114 distinguish.)
1116   If upper-case letters are used in the replacement string, they remain
1117 upper case every time that text is inserted.  If upper-case letters are
1118 used in the first argument, the second argument is always substituted
1119 exactly as given, with no case conversion.  Likewise, if either
1120 @code{case-replace} or @code{case-fold-search} is set to @code{nil},
1121 replacement is done without case conversion.
1123 @node Query Replace,, Replacement and Case, Replace
1124 @subsection Query Replace
1125 @cindex query replace
1127 @table @kbd
1128 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
1129 @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
1130 Replace some occurrences of @var{string} with @var{newstring}.
1131 @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
1132 @itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
1133 Replace some matches for @var{regexp} with @var{newstring}.
1134 @end table
1136 @kindex M-%
1137 @findex query-replace
1138   If you want to change only some of the occurrences of @samp{foo} to
1139 @samp{bar}, not all of them, then you cannot use an ordinary
1140 @code{replace-string}.  Instead, use @kbd{M-%} (@code{query-replace}).
1141 This command finds occurrences of @samp{foo} one by one, displays each
1142 occurrence and asks you whether to replace it.  Aside from querying,
1143 @code{query-replace} works just like @code{replace-string}.  It
1144 preserves case, like @code{replace-string}, provided
1145 @code{case-replace} is non-@code{nil}, as it normally is.  A numeric
1146 argument means consider only occurrences that are bounded by
1147 word-delimiter characters.
1149 @kindex C-M-%
1150 @findex query-replace-regexp
1151   @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}).
1153   The characters you can type when you are shown a match for the string
1154 or regexp are:
1156 @ignore @c Not worth it.
1157 @kindex SPC @r{(query-replace)}
1158 @kindex DEL @r{(query-replace)}
1159 @kindex , @r{(query-replace)}
1160 @kindex RET @r{(query-replace)}
1161 @kindex . @r{(query-replace)}
1162 @kindex ! @r{(query-replace)}
1163 @kindex ^ @r{(query-replace)}
1164 @kindex C-r @r{(query-replace)}
1165 @kindex C-w @r{(query-replace)}
1166 @kindex C-l @r{(query-replace)}
1167 @end ignore
1169 @c WideCommands
1170 @table @kbd
1171 @item @key{SPC}
1172 to replace the occurrence with @var{newstring}.
1174 @item @key{DEL}
1175 to skip to the next occurrence without replacing this one.
1177 @item , @r{(Comma)}
1178 to replace this occurrence and display the result.  You are then asked
1179 for another input character to say what to do next.  Since the
1180 replacement has already been made, @key{DEL} and @key{SPC} are
1181 equivalent in this situation; both move to the next occurrence.
1183 You can type @kbd{C-r} at this point (see below) to alter the replaced
1184 text.  You can also type @kbd{C-x u} to undo the replacement; this exits
1185 the @code{query-replace}, so if you want to do further replacement you
1186 must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
1187 (@pxref{Repetition}).
1189 @item @key{RET}
1190 to exit without doing any more replacements.
1192 @item .@: @r{(Period)}
1193 to replace this occurrence and then exit without searching for more
1194 occurrences.
1196 @item !
1197 to replace all remaining occurrences without asking again.
1199 @item ^
1200 to go back to the position of the previous occurrence (or what used to
1201 be an occurrence), in case you changed it by mistake or want to
1202 reexamine it.
1204 @item C-r
1205 to enter a recursive editing level, in case the occurrence needs to be
1206 edited rather than just replaced with @var{newstring}.  When you are
1207 done, exit the recursive editing level with @kbd{C-M-c} to proceed to
1208 the next occurrence.  @xref{Recursive Edit}.
1210 @item C-w
1211 to delete the occurrence, and then enter a recursive editing level as in
1212 @kbd{C-r}.  Use the recursive edit to insert text to replace the deleted
1213 occurrence of @var{string}.  When done, exit the recursive editing level
1214 with @kbd{C-M-c} to proceed to the next occurrence.
1216 @item e
1217 to edit the replacement string in the minibuffer.  When you exit the
1218 minibuffer by typing @key{RET}, the minibuffer contents replace the
1219 current occurrence of the pattern.  They also become the new
1220 replacement string for any further occurrences.
1222 @item C-l
1223 to redisplay the screen.  Then you must type another character to
1224 specify what to do with this occurrence.
1226 @item C-h
1227 to display a message summarizing these options.  Then you must type
1228 another character to specify what to do with this occurrence.
1229 @end table
1231   Some other characters are aliases for the ones listed above: @kbd{y},
1232 @kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
1233 @key{RET}.
1235   Aside from this, any other character exits the @code{query-replace},
1236 and is then reread as part of a key sequence.  Thus, if you type
1237 @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
1238 line.
1240   To restart a @code{query-replace} once it is exited, use @kbd{C-x
1241 @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
1242 used the minibuffer to read its arguments.  @xref{Repetition, C-x ESC
1243 ESC}.
1245   See also @ref{Transforming File Names}, for Dired commands to rename,
1246 copy, or link files by replacing regexp matches in file names.
1248 @node Other Repeating Search,, Replace, Search
1249 @section Other Search-and-Loop Commands
1251   Here are some other commands that find matches for a regular
1252 expression.  They all ignore case in matching, if the pattern contains
1253 no upper-case letters and @code{case-fold-search} is non-@code{nil}.
1254 Aside from @code{occur} and its variants, all operate on the text from
1255 point to the end of the buffer, or on the active region in Transient
1256 Mark mode.
1258 @findex list-matching-lines
1259 @findex occur
1260 @findex multi-occur
1261 @findex multi-occur-by-filename-regexp
1262 @findex how-many
1263 @findex delete-non-matching-lines
1264 @findex delete-matching-lines
1265 @findex flush-lines
1266 @findex keep-lines
1268 @table @kbd
1269 @item M-x occur @key{RET} @var{regexp} @key{RET}
1270 Display a list showing each line in the buffer that contains a match
1271 for @var{regexp}.  To limit the search to part of the buffer, narrow
1272 to that part (@pxref{Narrowing}).  A numeric argument @var{n}
1273 specifies that @var{n} lines of context are to be displayed before and
1274 after each matching line.
1276 @kindex RET @r{(Occur mode)}
1277 @kindex o @r{(Occur mode)}
1278 @kindex C-o @r{(Occur mode)}
1279 The buffer @samp{*Occur*} containing the output serves as a menu for
1280 finding the occurrences in their original context.  Click
1281 @kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position
1282 point there and type @key{RET}; this switches to the buffer that was
1283 searched and moves point to the original of the chosen occurrence.
1284 @kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o}
1285 does not select it.
1287 @item M-x list-matching-lines
1288 Synonym for @kbd{M-x occur}.
1290 @item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET}
1291 This function is just like @code{occur}, except it is able to search
1292 through multiple buffers.
1294 @item M-x multi-occur-by-filename-regexp @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET}
1295 This function is similar to @code{multi-occur}, except the buffers to
1296 search are specified by a regexp on their filename.
1298 @item M-x how-many @key{RET} @var{regexp} @key{RET}
1299 Print the number of matches for @var{regexp} that exist in the buffer
1300 after point.  In Transient Mark mode, if the region is active, the
1301 command operates on the region instead.
1303 @item M-x flush-lines @key{RET} @var{regexp} @key{RET}
1304 Delete each line that contains a match for @var{regexp}, operating on
1305 the text after point.  In Transient Mark mode, if the region is
1306 active, the command operates on the region instead.
1308 @item M-x keep-lines @key{RET} @var{regexp} @key{RET}
1309 Delete each line that @emph{does not} contain a match for
1310 @var{regexp}, operating on the text after point.  In Transient Mark
1311 mode, if the region is active, the command operates on the region
1312 instead.
1313 @end table
1315   You can also search multiple files under control of a tags table
1316 (@pxref{Tags Search}) or through Dired @kbd{A} command
1317 (@pxref{Operating on Files}), or ask the @code{grep} program to do it
1318 (@pxref{Grep Searching}).
1320 @ignore
1321    arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e
1322 @end ignore