@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2011
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2013 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
-@node Search, Fixit, Display, Top
+@node Search
@chapter Searching and Replacement
@cindex searching
@cindex finding strings within text
(@pxref{Operating on Files}), or ask the @code{grep} program to do it
(@pxref{Grep Searching}).
-
@menu
* Incremental Search:: Search happens as you type the string.
* Nonincremental Search:: Specify entire string and then search.
* Word Search:: Search for sequence of words.
+* Symbol Search:: Search for a source code symbol.
* Regexp Search:: Search for match for a regexp.
* Regexps:: Syntax of regular expressions.
* Regexp Backslash:: Regular expression constructs starting with `\'.
@end table
@menu
-* Basic Isearch:: Basic incremental search commands.
-* Repeat Isearch:: Searching for the same string again.
-* Error in Isearch:: When your string is not found.
-* Special Isearch:: Special input in incremental search.
-* Isearch Yank:: Commands that grab text into the search string
- or else edit the search string.
-* Isearch Scroll:: Scrolling during an incremental search.
-* Isearch Minibuffer:: Incremental search of the minibuffer history.
+* Basic Isearch:: Basic incremental search commands.
+* Repeat Isearch:: Searching for the same string again.
+* Error in Isearch:: When your string is not found.
+* Special Isearch:: Special input in incremental search.
+* Isearch Yank:: Commands that grab text into the search string
+ or else edit the search string.
+* Not Exiting Isearch:: Prefix argument and scrolling commands.
+* Isearch Minibuffer:: Incremental search of the minibuffer history.
@end menu
@node Basic Isearch
After exiting a search, you can search for the same string again by
typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that
invokes incremental search, and the second @kbd{C-s} means ``search
-again.'' Similarly, @kbd{C-r C-r} searches backward for the last
+again''. Similarly, @kbd{C-r C-r} searches backward for the last
search string. In determining the last search string, it doesn't
matter whether the string was searched for with @kbd{C-s} or
@kbd{C-r}.
@kindex M-e @r{(Incremental search)}
To edit the current search string in the minibuffer without
-replacing it with items from the search ring, type @kbd{M-e}. Type
+replacing it with items from the search ring, type @kbd{M-e}. Type @key{RET},
@kbd{C-s} or @kbd{C-r} to finish editing the string and search for it.
@node Error in Isearch
Some of the characters you type during incremental search have
special effects.
+@cindex lax space matching
+@kindex M-s SPC @r{(Incremental search)}
+@kindex SPC @r{(Incremental search)}
+@findex isearch-toggle-lax-whitespace
+@vindex search-whitespace-regexp
+ By default, incremental search performs @dfn{lax space matching}:
+each space, or sequence of spaces, matches any sequence of one or more
+spaces in the text. Hence, @samp{foo bar} matches @samp{foo bar},
+@samp{foo bar}, @samp{foo bar}, and so on (but not @samp{foobar}).
+More precisely, Emacs matches each sequence of space characters in the
+search string to a regular expression specified by the variable
+@code{search-whitespace-regexp}. For example, set it to
+@samp{"[[:space:]\n]+"} to make spaces match sequences of newlines as
+well as spaces. To toggle lax space matching, type @kbd{M-s SPC}
+(@code{isearch-toggle-lax-whitespace}). To disable this feature
+entirely, change @code{search-whitespace-regexp} to @code{nil}; then
+each space in the search string matches exactly one space
+
If the search string you entered contains only lower-case letters,
the search is case-insensitive; as long as an upper-case letter exists
in the search string, the search becomes case-sensitive. If you
@kindex M-% @r{(Incremental search)}
Typing @kbd{M-%} in incremental search invokes @code{query-replace}
or @code{query-replace-regexp} (depending on search mode) with the
-current search string used as the string to replace. @xref{Query
-Replace}.
+current search string used as the string to replace. A negative
+prefix argument means to replace backward. @xref{Query Replace}.
@kindex M-TAB @r{(Incremental search)}
Typing @kbd{M-@key{TAB}} in incremental search invokes
@findex isearch-yank-char
@kbd{C-M-w} (@code{isearch-del-char}) deletes the last character
from the search string, and @kbd{C-M-y} (@code{isearch-yank-char})
-appends the character after point to the the search string. An
+appends the character after point to the search string. An
alternative method to add the character after point is to enter the
minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f}
at the end of the search string in the minibuffer.
-@node Isearch Scroll
-@subsection Scrolling During Incremental Search
+@node Not Exiting Isearch
+@subsection Not Exiting Incremental Search
+
+This subsection describes two categories of commands which you can
+type without exiting the current incremental search, even though they
+are not themselves part of incremental search.
+
+@table @asis
+@item Prefix Arguments
+@vindex isearch-allow-prefix
+ In incremental search, when you enter a prefix argument
+(@pxref{Arguments}), by default it will apply either to the next
+action in the search or to the command that exits the search.
+
+ In previous versions of Emacs, entering a prefix argument always
+terminated the search. You can revert to this behavior by setting the
+variable @code{isearch-allow-prefix} to @code{nil}.
+
+ When @code{isearch-allow-scroll} is non-@code{nil} (see below),
+prefix arguments always have the default behavior described above.
+@item Scrolling Commands
@vindex isearch-allow-scroll
Normally, scrolling commands exit incremental search. If you change
the variable @code{isearch-allow-scroll} to a non-@code{nil} value,
won't let you scroll the current match out of visibility, however.
The @code{isearch-allow-scroll} feature also affects some other
-commands, such as @kbd{C-x 2} (@code{split-window-vertically}) and
-@kbd{C-x ^} (@code{enlarge-window}), which don't exactly scroll but do
-affect where the text appears on the screen. It applies to any
-command whose name has a non-@code{nil} @code{isearch-scroll}
-property. So you can control which commands are affected by changing
-these properties.
+commands, such as @kbd{C-x 2} (@code{split-window-below}) and @kbd{C-x
+^} (@code{enlarge-window}), which don't exactly scroll but do affect
+where the text appears on the screen. It applies to any command whose
+name has a non-@code{nil} @code{isearch-scroll} property. So you can
+control which commands are affected by changing these properties.
For example, to make @kbd{C-h l} usable within an incremental search
in all future Emacs sessions, use @kbd{C-h c} to find what command it
change point, the buffer contents, the match data, the current buffer,
or the selected window and frame. The command must not itself attempt
an incremental search.
+@end table
@node Isearch Minibuffer
@subsection Searching the Minibuffer
When the current match is on a history element, that history element
is pulled into the minibuffer. If you exit the incremental search
-normally (e.g. by typing @key{RET}), it remains in the minibuffer
+normally (e.g., by typing @key{RET}), it remains in the minibuffer
afterwards. Canceling the search, with @kbd{C-g}, restores the
contents of the minibuffer when you began the search.
proceeds incrementally as you type. This additional laxity does not
apply to the lazy highlight, which always matches whole words.
+@node Symbol Search
+@section Symbol Search
+@cindex symbol search
+
+ A @dfn{symbol search} is much like an ordinary search, except that
+the boundaries of the search must match the boundaries of a symbol.
+The meaning of @dfn{symbol} in this context depends on the major mode,
+and usually refers to a source code token, such as a Lisp symbol in
+Emacs Lisp mode. For instance, if you perform an incremental symbol
+search for the Lisp symbol @code{forward-word}, it would not match
+@code{isearch-forward-word}. This feature is thus mainly useful for
+searching source code.
+
+@table @kbd
+@item M-s _
+If incremental search is active, toggle symbol search mode
+(@code{isearch-toggle-symbol}); otherwise, begin an incremental
+forward symbol search (@code{isearch-forward-symbol}).
+@item M-s .
+Start a symbol incremental search forward with the symbol found near
+point added to the search string initially.
+@item M-s _ @key{RET} @var{symbol} @key{RET}
+Search forward for @var{symbol}, nonincrementally.
+@item M-s _ C-r @key{RET} @var{symbol} @key{RET}
+Search backward for @var{symbol}, nonincrementally.
+@end table
+
+@kindex M-s _
+@kindex M-s .
+@findex isearch-forward-symbol
+@findex isearch-forward-symbol-at-point
+ To begin a forward incremental symbol search, type @kbd{M-s _} (or
+@kbd{M-s .} if the symbol to search is near point). If incremental
+search is not already active, this runs the command
+@code{isearch-forward-symbol}. If incremental search is already
+active, @kbd{M-s _} switches to a symbol search, preserving the
+direction of the search and the current search string; you can disable
+symbol search by typing @kbd{M-s _} again. In incremental symbol
+search, only the beginning of the search string is required to match
+the beginning of a symbol.
+
+ To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}}
+for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward
+search. In nonincremental symbol searches, the beginning and end of
+the search string are required to match the beginning and end of a
+symbol, respectively.
+
@node Regexp Search
@section Regular Expression Search
@cindex regexp search
@cindex search for a regular expression
A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern
-that denotes a class of alternative strings to match. GNU Emacs
+that denotes a class of alternative strings to match. Emacs
provides both incremental and nonincremental ways to search for a
match for a regexp. The syntax of regular expressions is explained in
the next section.
They also have separate search rings, which you can access with
@kbd{M-p} and @kbd{M-n}.
-@vindex search-whitespace-regexp
- If you type @key{SPC} in incremental regexp search, it matches any
-sequence of whitespace characters, including newlines. If you want to
-match just a space, type @kbd{C-q @key{SPC}}. You can control what a
-bare space matches by setting the variable
-@code{search-whitespace-regexp} to the desired regexp.
+ Just as in ordinary incremental search, any @key{SPC} typed in
+incremental regexp search matches any sequence of one or more
+whitespace characters. The variable @code{search-whitespace-regexp}
+specifies the regexp for the lax space matching, and @kbd{M-s SPC}
+(@code{isearch-toggle-lax-whitespace}) toggles the feature.
+@xref{Special Isearch}.
In some cases, adding characters to the regexp in an incremental
regexp search can make the cursor move back and start again. For
@samp{ff}.) Likewise, @samp{o} is a regular expression that matches
only @samp{o}. (When case distinctions are being ignored, these regexps
also match @samp{F} and @samp{O}, but we consider this a generalization
-of ``the same string,'' rather than an exception.)
+of ``the same string'', rather than an exception.)
Any two regular expressions @var{a} and @var{b} can be concatenated.
The result is a regular expression which matches a string if @var{a}
tries to match all three @samp{a}s; but the rest of the pattern is
@samp{ar} and there is only @samp{r} left to match, so this try fails.
The next alternative is for @samp{a*} to match only two @samp{a}s.
-With this choice, the rest of the regexp matches successfully.@refill
+With this choice, the rest of the regexp matches successfully.
@item @kbd{+}
is a postfix operator, similar to @samp{*} except that it must match
match @var{a}, and if that fails, by trying to match @var{b}.
Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
-but no other string.@refill
+but no other string.
@samp{\|} applies to the largest possible surrounding expressions. Only a
surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
-@samp{\|}.@refill
+@samp{\|}.
Full backtracking capability exists to handle multiple uses of @samp{\|}.
To enclose a complicated expression for the postfix operators @samp{*},
@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
@samp{bananana}, etc., with any (zero or more) number of @samp{na}
-strings.@refill
+strings.
@item
To record a matched substring for future reference.
the beginning and end of the text matched by that construct. Then,
later on in the regular expression, you can use @samp{\} followed by the
digit @var{d} to mean ``match the same text matched the @var{d}th time
-by the @samp{\( @dots{} \)} construct.''
+by the @samp{\( @dots{} \)} construct''.
The strings matching the first nine @samp{\( @dots{} \)} constructs
appearing in a regular expression are assigned numbers 1 through 9 in
matches the empty string, but only at the beginning or
end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
@samp{foo} as a separate word. @samp{\bballs?\b} matches
-@samp{ball} or @samp{balls} as a separate word.@refill
+@samp{ball} or @samp{balls} as a separate word.
@samp{\b} matches at the beginning or end of the buffer
regardless of what text appears next to it.
you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo}
also match. Regexps, and in particular character sets, behave
likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or
-@samp{B}.@refill
+@samp{B}.
An upper-case letter anywhere in the incremental search string makes
the search case-sensitive. Thus, searching for @samp{Foo} does not find
is possible to perform several replacements in parallel, using the
command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
+@vindex replace-lax-whitespace
+ Unlike incremental search, the replacement commands do not use lax
+space matching (@pxref{Special Isearch}) by default. To enable lax
+space matching for replacement, change the variable
+@code{replace-lax-whitespace} to @code{t}. (This only affects how
+Emacs finds the text to replace, not the replacement text.)
+
@menu
* Unconditional Replace:: Replacing all matches for a string.
* Regexp Replace:: Replacing all matches for a regexp.
* Query Replace:: How to use querying.
@end menu
-@node Unconditional Replace, Regexp Replace, Replace, Replace
+@node Unconditional Replace
@subsection Unconditional Replacement
@findex replace-string
@xref{Replacement and Case}, for details about case-sensitivity in
replace commands.
-@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
+@node Regexp Replace
@subsection Regexp Replacement
@findex replace-regexp
@samp{\&} in @var{newstring} stands for the entire match being
replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a
digit, stands for whatever matched the @var{d}th parenthesized
-grouping in @var{regexp}. (This is called a ``back reference.'')
+grouping in @var{regexp}. (This is called a ``back reference''.)
@samp{\#} refers to the count of replacements already made in this
command, as a decimal number. In the first replacement, @samp{\#}
stands for @samp{0}; in the second, for @samp{1}; and so on. For
\,(format "%-72sABC%05d" \& \#) @key{RET}
@end example
-@node Replacement and Case, Query Replace, Regexp Replace, Replace
+@node Replacement and Case
@subsection Replace Commands and Case
If the first argument of a replace command is all lower case, the
@code{case-replace} or @code{case-fold-search} is set to @code{nil},
replacement is done without case conversion.
-@node Query Replace,, Replacement and Case, Replace
+@node Query Replace
@subsection Query Replace
@cindex query replace
(@pxref{Unconditional Replace}). In particular, it preserves case
provided @code{case-replace} is non-@code{nil}, as it normally is
(@pxref{Replacement and Case}). A numeric argument means to consider
-only occurrences that are bounded by word-delimiter characters.
+only occurrences that are bounded by word-delimiter characters. A
+negative prefix argument replaces backward.
@kindex C-M-%
@findex query-replace-regexp
@item !
to replace all remaining occurrences without asking again.
+@item Y @r{(Upper-case)}
+to replace all remaining occurrences in all remaining buffers in
+multi-buffer replacements (like the Dired `Q' command which performs
+query replace on selected files). It answers this question and all
+subsequent questions in the series with "yes", without further
+user interaction.
+
+@item N @r{(Upper-case)}
+to skip to the next buffer in multi-buffer replacements without
+replacing remaining occurrences in the current buffer. It answers
+this question "no", gives up on the questions for the current buffer,
+and continues to the next buffer in the sequence.
+
@item ^
to go back to the position of the previous occurrence (or what used to
be an occurrence), in case you changed it by mistake or want to
@kindex RET @r{(Occur mode)}
@kindex o @r{(Occur mode)}
@kindex C-o @r{(Occur mode)}
-In the @samp{*Occur*} buffer, you can click on each entry, or move
+In the @file{*Occur*} buffer, you can click on each entry, or move
point there and type @key{RET}, to visit the corresponding position in
the buffer that was searched. @kbd{o} and @kbd{C-o} display the match
in another window; @kbd{C-o} does not select it. Alternatively, you
@cindex Occur Edit mode
@cindex mode, Occur Edit
-Typing @kbd{e} in the @samp{*Occur*} buffer switches to Occur Edit
+Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit
mode, in which edits made to the entries are also applied to the text
in the originating buffer. Type @kbd{C-c C-c} to return to Occur
mode.