@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002,
-@c 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Search, Fixit, Display, Top
@chapter Searching and Replacement
want, you can stop. Depending on what you plan to do next, you may or
may not need to terminate the search explicitly with @key{RET}.
-@c WideCommands
@table @kbd
@item C-s
Incremental search forward (@code{isearch-forward}).
characters. If you type @kbd{C-s} and then @kbd{F}, that puts the
cursor after the first @samp{F} (the first following the starting point, since
this is a forward search). Then if you type an @kbd{O}, you will see
-the cursor move just after the first @samp{FO} (the @samp{F} in that
+the cursor move to just after the first @samp{FO} (the @samp{F} in that
@samp{FO} may or may not be the first @samp{F}). After another
-@kbd{O}, the cursor moves after the first @samp{FOO} after the place
+@kbd{O}, the cursor moves to just after the first @samp{FOO} after the place
where you started the search. At each step, the buffer text that
matches the search string is highlighted, if the terminal can do that;
the current search string is always displayed in the echo area.
search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r}
to terminate editing the string and search for it.
- You can change to searching backwards with @kbd{C-r}. If a search fails
-because the place you started was too late in the file, you should do this.
-Repeated @kbd{C-r} keeps looking for more occurrences backwards. A
-@kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be canceled
+ You can change to searching backwards with @kbd{C-r}. For instance,
+if you are searching forward but you realize you were looking for
+something above the starting point, you can do this. Repeated
+@kbd{C-r} keeps looking for more occurrences backwards. A @kbd{C-s}
+starts going forwards again. @kbd{C-r} in a search can be canceled
with @key{DEL}.
@kindex C-r
@findex isearch-backward
If you know initially that you want to search backwards, you can use
-@kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as
-a key runs a command (@code{isearch-backward}) to search backward. A
-backward search finds matches that are entirely before the starting
-point, just as a forward search finds matches that begin after it.
+@kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r}
+as a key runs a command (@code{isearch-backward}) to search backward.
+A backward search finds matches that end before the starting point,
+just as a forward search finds matches that begin after it.
@node Error in Isearch
@subsection Errors in Incremental Search
@cindex searching for non-@acronym{ASCII} characters
@cindex input method, during incremental search
- To enter non-@acronym{ASCII} characters in an incrementral search,
+ To enter non-@acronym{ASCII} characters in an incremental search,
you must use an input method (@pxref{Input Methods}). If an input
method is enabled in the current buffer when you start the search, you
can use it while you type the search string also. Emacs indicates
@cindex faces for highlighting search matches
You can control how this highlighting looks by customizing the faces
@code{isearch} (used for the current match) and @code{lazy-highlight}
-(for all the other matches). The latter is also used for other matches
-inside @code{query-replace}.
+(for all the other matches).
@node Isearch Scroll
@subsection Scrolling During Incremental Search
- Vertical scrolling during incremental search can be enabled by
-setting the customizable variable @code{isearch-allow-scroll} to a
-non-@code{nil} value.
-
- You can then use the vertical scroll-bar or certain keyboard
+ You can enable the use of vertical scrolling during incremental
+search (without exiting the search) by setting the customizable
+variable @code{isearch-allow-scroll} to a non-@code{nil} value. This
+applies to using the vertical scroll-bar and to certain keyboard
commands such as @kbd{@key{PRIOR}} (@code{scroll-down}),
-@kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter})
-within the search, thus letting you see more of the text near the
-current match. You must run these commands via their key sequences to
-stay in the search---typing M-x @var{command-name} will always
-terminate a search.
+@kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter}).
+You must run these commands via their key sequences to stay in the
+search---typing @kbd{M-x} will terminate the search. You can give
+prefix arguments to these commands in the usual way.
- You can give prefix arguments to these commands in the usual way.
-The current match cannot be scrolled out of the window---this is
-intentional.
+ This feature won't let you scroll the current match out of visibility,
+however.
- Several other commands, such as @kbd{C-x 2}
+ The 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 scroll the window, are
-nevertheless made available under this rubric, since they are likewise
-handy during a search.
+(@code{enlarge-window}) which don't exactly scroll but do affect where
+the text appears on the screen. In general, 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.
- You can make other commands usable within an incremental search by
-giving the command a non-@code{nil} @code{isearch-scroll} property.
-For example, to make @kbd{C-h l} usable within an incremental search
+ 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
-runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.) Then
-you can put the following line in your @file{.emacs} file (@pxref{Init File}):
+runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.)
+Then you can put the following line in your @file{.emacs} file
+(@pxref{Init File}):
@example
(put 'view-lossage 'isearch-scroll t)
@end example
@noindent
-This works for commands that don't permanently change point, the
-buffer contents, the match data, the current buffer, or the selected
-window and frame. The command must not delete the current window and
-must not itself attempt an incremental search.
+This feature can be applied to any command that doesn't permanently
+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.
@node Slow Isearch
@subsection Slow Terminal Incremental Search
useless.) But it does not call @code{search-forward} right away. First
it checks the next input character to see if is @kbd{C-w},
which specifies a word search.
-@ifinfo
+@ifnottex
@xref{Word Search}.
-@end ifinfo
+@end ifnottex
@kbd{C-r @key{RET}} does likewise, for a reverse incremental search.
@findex search-forward
commands @code{search-forward} and @code{search-backward}. These
commands may be bound to keys in the usual manner. The feature that you
can get to them via the incremental search commands exists for
-historical reasons, and to avoid the need to find key sequences
+historical reasons, and to avoid the need to find separate key sequences
for them.
@node Word Search
@code{word-search-forward} and @code{word-search-backward}. These
commands may be bound to keys in the usual manner. They are available
via the incremental search commands both for historical reasons and
-to avoid the need to find suitable key sequences for them.
+to avoid the need to find separate key sequences for them.
@node Regexp Search
@section Regular Expression Search
defaults. They also have separate search rings that 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}}.
+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.
- Note that adding characters to the regexp in an incremental regexp
+ In some cases, adding characters to the regexp in an incremental regexp
search can make the cursor move back and start again. For example, if
you have searched for @samp{foo} and you add @samp{\|bar}, the cursor
backs up in case the first @samp{bar} precedes the first @samp{foo}.
special constructs and the rest are @dfn{ordinary}. An ordinary
character is a simple regular expression which matches that same
character and nothing else. The special characters are @samp{$},
-@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, @samp{]} and
-@samp{\}. Any other character appearing in a regular expression is
-ordinary, unless a @samp{\} precedes it. (When you use regular
-expressions in a Lisp program, each @samp{\} must be doubled, see the
-example near the end of this section.)
+@samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, and
+@samp{\}. The character @samp{]} is special if it ends a character
+alternative (see later). The character @samp{-} is special inside a
+character alternative. Any other character appearing in a regular
+expression is ordinary, unless a @samp{\} precedes it. (When you use
+regular expressions in a Lisp program, each @samp{\} must be doubled,
+see the example near the end of this section.)
For example, @samp{f} is not a special character, so it is ordinary, and
therefore @samp{f} is a regular expression that matches the string
to depend on this behavior; it is better to quote the special character anyway,
regardless of where it appears.
+As a @samp{\} is not special inside a character alternative, it can
+never remove the special meaning of @samp{-} or @samp{]}. So you
+should not quote these characters when they have no special meaning
+either. This would not clarify anything, since backslashes can
+legitimately precede these characters where they @emph{have} special
+meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
+which matches any single character except a backslash.
+
@node Regexp Backslash
@section Backslash in Regular Expressions
you can't refer back to it with @samp{\@var{d}}. This is useful
in mechanically combining regular expressions, so that you
can add groups for syntactic purposes without interfering with
-the numbering of the groups that were written by the user.
+the numbering of the groups that are meant to be referred to.
@item \@var{d}
+@cindex back reference, in regexp
matches the same text that matched the @var{d}th occurrence of a
-@samp{\( @dots{} \)} construct.
+@samp{\( @dots{} \)} construct. This is called a @dfn{back
+reference}.
After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
the beginning and end of the text matched by that construct. Then,
(@pxref{Replace}) and the minibuffer history matching commands
(@pxref{Minibuffer History}).
+ Several related variables control case-sensitivity of searching and
+matching for specific commands or activities. For instance,
+@code{tags-case-fold-search} controls case sensitivity for
+@code{find-tag}. To find these variables, do @kbd{M-x
+apropos-variable @key{RET} case-fold-search @key{RET}}.
+
@node Replace
@section Replacement Commands
@cindex replacement
Global search-and-replace operations are not needed often in Emacs,
but they are available. In addition to the simple @kbd{M-x
replace-string} command which replaces all occurrences,
-there is a @kbd{M-x query-replace} command which finds each occurrence
+there is @kbd{M-%} (@code{query-replace}), which presents each occurrence
of the pattern and asks you whether to replace it.
The replace commands normally operate on the text from point to the
end of the buffer; however, in Transient Mark mode (@pxref{Transient
Mark}), when the mark is active, they operate on the region. The
-replace commands all replace one string (or regexp) with one
+basic replace commands replace one string (or regexp) with one
replacement string. It is possible to perform several replacements in
parallel using the command @code{expand-region-abbrevs}
(@pxref{Expanding Abbrevs}).
Replace every match for @var{regexp} with @var{newstring}.
@end table
+@cindex back reference, in regexp replacement
In @code{replace-regexp}, the @var{newstring} need not be constant:
it can refer to all or part of what is matched by the @var{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}. @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 example,
+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
+example,
@example
M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
@findex list-matching-lines
@findex occur
@findex multi-occur
-@findex multi-occur-by-filename-regexp
+@findex multi-occur-in-matching-buffers
@findex how-many
@findex delete-non-matching-lines
@findex delete-matching-lines
@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o}
does not select it.
-Occur mode supports the @code{next-error} functionality described in
-@ref{Compilation Mode}.
+After using @kbd{M-x occur}, you can use @code{next-error} to visit
+the occurrences found, one by one. @ref{Compilation Mode}.
@item M-x list-matching-lines
Synonym for @kbd{M-x occur}.
@item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET}
This function is just like @code{occur}, except it is able to search
-through multiple buffers.
+through multiple buffers. It asks you to specify the buffer names one by one.
-@item M-x multi-occur-by-filename-regexp @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET}
+@item M-x multi-occur-in-matching-buffers @key{RET} @var{bufregexp} @key{RET} @var{regexp} @key{RET}
This function is similar to @code{multi-occur}, except the buffers to
-search are specified by a regexp on their filename.
+search are specified by a regular expression that matches visited
+file names. With a prefix argument, it uses the regular expression to match
+buffer names instead.
@item M-x how-many @key{RET} @var{regexp} @key{RET}
Print the number of matches for @var{regexp} that exist in the buffer