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