@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, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
+@c Free Software 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.
-* Regexp Search:: Search for match for a regexp.
-* Regexps:: Syntax of regular expressions.
-* Regexp Backslash:: Regular expression constructs starting with `\'.
-* Regexp Example:: A complex regular expression explained.
-* Search Case:: To ignore case while searching, or not.
-* Replace:: Search, and replace some or all matches.
-* Other Repeating Search:: Operating on all matches for some regexp.
+* 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 `\'.
+* Regexp Example:: A complex regular expression explained.
+* Search Case:: To ignore case while searching, or not.
+* Replace:: Search, and replace some or all matches.
+* Other Repeating Search:: Operating on all matches for some regexp.
@end menu
@node Incremental Search
or else edit the search string.
* Isearch Scroll:: Scrolling during an incremental search.
* Isearch Minibuffer:: Incremental search of the minibuffer history.
-* Slow Isearch:: Incremental search features for slow terminals.
@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}.
you have already seen.
@cindex search ring
+@kindex M-n @r{(Incremental search)}
+@kindex M-p @r{(Incremental search)}
To reuse earlier search strings, use the @dfn{search ring}. The
commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a
search string to reuse. These commands leave the selected search ring
-element in the minibuffer, where you can edit it. To edit the current
-search string in the minibuffer without replacing it with items from
-the search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r} to
-terminate editing the string and search for it.
+element in the minibuffer, where you can edit it.
+
+@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
+@kbd{C-s} or @kbd{C-r} to finish editing the string and search for it.
@node Error in Isearch
@subsection Errors in Incremental Search
If your string is not found at all, the echo area says @samp{Failing
-I-Search}. The cursor is after the place where Emacs found as much of
-your string as it could. Thus, if you search for @samp{FOOT}, and
-there is no @samp{FOOT}, you might see the cursor after the @samp{FOO}
-in @samp{FOOL}. In the echo area, the part of the search string that
-failed to match is highlighted using the customizable face
+I-Search}, and the cursor moves past the place where Emacs found as
+much of your string as it could. Thus, if you search for @samp{FOOT},
+and there is no @samp{FOOT}, you might see the cursor after the
+@samp{FOO} in @samp{FOOL}. In the echo area, the part of the search
+string that failed to match is highlighted using the face
@code{isearch-fail}.
At this point, there are several things you can do. If your string
entirely, returning point to where it was when the search started.
@cindex quitting (in search)
+@kindex C-g @r{(Incremental search)}
The quit command, @kbd{C-g}, does special things during searches;
just what it does depends on the status of the search. If the search
has found what you specified and is waiting for input, @kbd{C-g}
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
@vindex isearch-mode-map
When incremental search is active, you can type @kbd{C-h C-h} to
-access interactive help options, including a list of special
-keybindings. These keybindings are part of the keymap
+access interactive help options, including a list of special key
+bindings. These key bindings are part of the keymap
@code{isearch-mode-map} (@pxref{Keymaps}).
@node Isearch Yank
@subsection Isearch Yanking
- Within incremental search, you can use @kbd{C-w} and @kbd{C-y} to grab
-text from the buffer into the search string. This makes it convenient
-to search for another occurrence of text at point.
-
- @kbd{C-w} copies the character or word after point and adds it to
-the search string, advancing point over it. (The decision, whether to
-copy a character or a word, is heuristic.)
-
- @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the
-current line into the search string. If point is already at the end
-of a line, it grabs the entire next line. If the search is currently
-case-insensitive, both @kbd{C-y} and @kbd{C-w} convert the text they
-copy to lower case, so that the search remains case-insensitive.
-
- @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one
-character at a time: @kbd{C-M-w} deletes the last character from the
-search string and @kbd{C-M-y} copies the character after point to the
-end of the search string. An alternative method to add the character
-after point into the search string is to enter the minibuffer by
-@kbd{M-e} and to type @kbd{C-f} at the end of the search string in the
-minibuffer.
-
- The character @kbd{M-y} copies text from the kill ring into the
-search string. It uses the same text that @kbd{C-y} would yank.
-@kbd{Mouse-2} in the echo area does the same. @xref{Yanking}.
+@kindex C-y @r{(Incremental search)}
+@kindex M-y @r{(Incremental search)}
+@findex isearch-yank-kill
+@findex isearch-yank-pop
+ Within incremental search, @kbd{C-y} (@code{isearch-yank-kill})
+appends the current kill to the search string. @kbd{M-y}
+(@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that
+appended text with an earlier kill, similar to the usual @kbd{M-y}
+(@code{yank-pop}) command (@pxref{Yanking}). @kbd{Mouse-2} appends
+the current X selection (@pxref{Primary Selection}).
+
+@kindex C-w @r{(Incremental search)}
+@findex isearch-yank-word-or-char
+ @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next
+character or word at point to the search string. This is an easy way
+to search for another occurrence of the text at point. (The decision
+of whether to copy a character or a word is heuristic.)
+
+@kindex M-s C-e @r{(Incremental search)}
+@findex isearch-yank-line
+ Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest
+of the current line to the search string. If point is already at the
+end of a line, it appends the next line.
+
+ If the search is currently case-insensitive, both @kbd{C-w} and
+@kbd{M-s C-e} convert the text they copy to lower case, so that the
+search remains case-insensitive.
+
+@kindex C-M-w @r{(Incremental search)}
+@kindex C-M-y @r{(Incremental search)}
+@findex isearch-del-char
+@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 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
@vindex isearch-allow-scroll
- 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 @key{prior} (@code{scroll-down}), @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.
-
- This feature won't let you scroll the current match out of visibility,
-however.
-
- 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 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.
+ Normally, scrolling commands exit incremental search. If you change
+the variable @code{isearch-allow-scroll} to a non-@code{nil} value,
+that enables the use of the scroll-bar, as well as keyboard scrolling
+commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}).
+This applies only to calling these commands via their bound key
+sequences---typing @kbd{M-x} will still exit the search. You can give
+prefix arguments to these commands in the usual way. This feature
+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-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
-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 (@pxref{Key Help}), which is @code{view-lossage}. Then you can
+put the following line in your init file (@pxref{Init File}):
@example
(put 'view-lossage 'isearch-scroll t)
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
-afterwards. Cancelling the search, with @kbd{C-g}, restores the
+afterwards. Canceling the search, with @kbd{C-g}, restores the
contents of the minibuffer when you began the search.
-@node Slow Isearch
-@subsection Slow Terminal Incremental Search
-
- Incremental search on a slow terminal uses a modified style of display
-that is designed to take less time. Instead of redisplaying the buffer at
-each place the search gets to, it creates a new single-line window and uses
-that to display the line that the search has found. The single-line window
-comes into play as soon as point moves outside of the text that is already
-on the screen.
-
- When you terminate the search, the single-line window is removed.
-Emacs then redisplays the window in which the search was done, to show
-its new position of point.
-
-@vindex search-slow-speed
- The slow terminal style of display is used when the terminal baud rate is
-less than or equal to the value of the variable @code{search-slow-speed},
-initially 1200. See also the discussion of the variable @code{baud-rate}
-(@pxref{baud-rate,, Customization of Display}).
-
-@vindex search-slow-window-lines
- The number of lines to use in slow terminal search display is controlled
-by the variable @code{search-slow-window-lines}. Its normal value is 1.
-
@node Nonincremental Search
@section Nonincremental Search
@cindex nonincremental search
string with @key{RET}, and then the search takes place. If the string
is not found, the search command signals an error.
- When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
-search as usual. That command is specially programmed to invoke
-nonincremental search, @code{search-forward}, if the string you
-specify is empty. (Such an empty argument would otherwise be
-useless.) @kbd{C-r @key{RET}} does likewise, for a reverse
-incremental search.
-
@findex search-forward
@findex search-backward
- Forward and backward nonincremental searches are implemented by the
-commands @code{search-forward} and @code{search-backward}. These
-commands may be bound to other keys in the usual manner.
+ When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental
+search as usual. That command is specially programmed to invoke the
+command for nonincremental search, @code{search-forward}, if the
+string you specify is empty. (Such an empty argument would otherwise
+be useless.) @kbd{C-r @key{RET}} does likewise, invoking the command
+@code{search-backward}.
@node Word Search
@section Word Search
These run the commands @code{word-search-forward} and
@code{word-search-backward} respectively.
- A nonincremental word search differs slightly from the incremental
-version in the way it finds a match: the last word in the search
-string must be an exact match for a whole word. In an incremental
-word search, the last word in the search string can match part of a
-word; this allows the matching to proceed incrementally as you type.
+ Incremental and nonincremental word searches differ slightly in the
+way they find a match. In a nonincremental word search, the last word
+in the search string must exactly match a whole word. In an
+incremental word search, the matching is more lax: the last word in
+the search string can match part of a word, so that the matching
+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 _ @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 _
+@findex isearch-forward-symbol
+ To begin a forward incremental symbol search, type @kbd{M-s _}. 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 regular expression
-@cindex regexp
+@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 following section.
+the next section.
@table @kbd
@item C-M-s
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
@findex re-search-forward
@findex re-search-backward
- Nonincremental search for a regexp is done by the functions
+ Nonincremental search for a regexp is done with the commands
@code{re-search-forward} and @code{re-search-backward}. You can
invoke these with @kbd{M-x}, or by way of incremental regexp search
with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}.
@node Regexps
@section Syntax of Regular Expressions
@cindex syntax of regexps
+@cindex regular expression
+@cindex regexp
This manual describes regular expression features that users
-typically want to use. There are additional features that are
-mainly used in Lisp programs; see @ref{Regular Expressions,,,
-elisp, The Emacs Lisp Reference Manual}.
+typically use. @xref{Regular Expressions,,, elisp, The Emacs Lisp
+Reference Manual}, for additional features used mainly in Lisp
+programs.
Regular expressions have a syntax in which a few characters are
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{[}, 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.)
+character matches that same character and nothing else. The special
+characters are @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
@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} matches
-some amount of the beginning of that string and @var{b} matches the rest of
-the string.@refill
-
- As a simple example, we can concatenate the regular expressions @samp{f}
-and @samp{o} to get the regular expression @samp{fo}, which matches only
-the string @samp{fo}. Still trivial. To do something nontrivial, you
-need to use one of the special characters. Here is a list of them.
+ 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}
+matches some amount of the beginning of that string and @var{b}
+matches the rest of the string. For example, concatenating the
+regular expressions @samp{f} and @samp{o} gives the regular expression
+@samp{fo}, which matches only the string @samp{fo}. Still trivial.
+To do something nontrivial, you need to use one of the special
+characters. Here is a list of them.
@table @asis
@item @kbd{.}@: @r{(Period)}
-is a special character that matches any single character except a newline.
-Using concatenation, we can make regular expressions like @samp{a.b}, which
-matches any three-character string that begins with @samp{a} and ends with
-@samp{b}.@refill
+is a special character that matches any single character except a
+newline. For example, the regular expressions @samp{a.b} matches any
+three-character string that begins with @samp{a} and ends with
+@samp{b}.
@item @kbd{*}
is not a construct by itself; it is a postfix operator that means to
-match the preceding regular expression repetitively as many times as
-possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
-@samp{o}s).
+match the preceding regular expression repetitively any number of
+times, as many times as possible. Thus, @samp{o*} matches any number
+of @samp{o}s, including no @samp{o}s.
@samp{*} always applies to the @emph{smallest} possible preceding
expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
@item @kbd{+}
is a postfix operator, similar to @samp{*} except that it must match
-the preceding expression at least once. So, for example, @samp{ca+r}
-matches the strings @samp{car} and @samp{caaaar} but not the string
-@samp{cr}, whereas @samp{ca*r} matches all three strings.
+the preceding expression at least once. Thus, @samp{ca+r} matches the
+strings @samp{car} and @samp{caaaar} but not the string @samp{cr},
+whereas @samp{ca*r} matches all three strings.
@item @kbd{?}
-is a postfix operator, similar to @samp{*} except that it can match the
-preceding expression either once or not at all. For example,
-@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
+is a postfix operator, similar to @samp{*} except that it can match
+the preceding expression either once or not at all. Thus, @samp{ca?r}
+matches @samp{car} or @samp{cr}, and nothing else.
@item @kbd{*?}, @kbd{+?}, @kbd{??}
@cindex non-greedy regexp matching
-are non-greedy variants of the operators above. The normal operators
-@samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as
-much as they can, as long as the overall regexp can still match. With
-a following @samp{?}, they are non-greedy: they will match as little
-as possible.
+are non-@dfn{greedy} variants of the operators above. The normal
+operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as
+long as the overall regexp can still match. With a following
+@samp{?}, they will match as little as possible.
Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a}
and the string @samp{abbbb}; but if you try to match them both against
starting at the first @samp{a}, it does.
@item @kbd{\@{@var{n}\@}}
-is a postfix operator that specifies repetition @var{n} times---that
-is, the preceding regular expression must match exactly @var{n} times
-in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx}
-and nothing else.
+is a postfix operator specifying @var{n} repetitions---that is, the
+preceding regular expression must match exactly @var{n} times in a
+row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and
+nothing else.
@item @kbd{\@{@var{n},@var{m}\@}}
-is a postfix operator that specifies repetition between @var{n} and
-@var{m} times---that is, the preceding regular expression must match
-at least @var{n} times, but no more than @var{m} times. If @var{m} is
+is a postfix operator specifying between @var{n} and @var{m}
+repetitions---that is, the preceding regular expression must match at
+least @var{n} times, but no more than @var{m} times. If @var{m} is
omitted, then there is no upper limit, but the preceding regular
expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is
equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to
@samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}.
@item @kbd{[ @dots{} ]}
-is a @dfn{character set}, which begins with @samp{[} and is terminated
-by @samp{]}. In the simplest case, the characters between the two
-brackets are what this set can match.
+is a @dfn{character set}, beginning with @samp{[} and terminated by
+@samp{]}.
-Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
-@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
-(including the empty string), from which it follows that @samp{c[ad]*r}
-matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
+In the simplest case, the characters between the two brackets are what
+this set can match. Thus, @samp{[ad]} matches either one @samp{a} or
+one @samp{d}, and @samp{[ad]*} matches any string composed of just
+@samp{a}s and @samp{d}s (including the empty string). It follows that
+@samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
+@samp{caddaar}, etc.
You can also include character ranges in a character set, by writing the
starting and ending characters with a @samp{-} between them. Thus,
which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or
period.
-Note that the usual regexp special characters are not special inside a
-character set. A completely different set of special characters exists
-inside character sets: @samp{]}, @samp{-} and @samp{^}.
+You can also include certain special @dfn{character classes} in a
+character set. A @samp{[:} and balancing @samp{:]} enclose a
+character class inside a character alternative. For instance,
+@samp{[[:alnum:]]} matches any letter or digit. @xref{Char Classes,,,
+elisp, The Emacs Lisp Reference Manual}, for a list of character
+classes.
To include a @samp{]} in a character set, you must make it the first
character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
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
word-constituent character.
@item \w
-matches any word-constituent character. The syntax table
-determines which characters these are. @xref{Syntax}.
+matches any word-constituent character. The syntax table determines
+which characters these are. @xref{Syntax Tables,, Syntax Tables,
+elisp, The Emacs Lisp Reference Manual}.
@item \W
matches any character that is not a word-constituent.
matches any character whose syntax is @var{c}. Here @var{c} is a
character that designates a particular syntax class: thus, @samp{w}
for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.}
-for ordinary punctuation, etc. @xref{Syntax}.
+for ordinary punctuation, etc. @xref{Syntax Tables,, Syntax Tables,
+elisp, The Emacs Lisp Reference Manual}.
@item \S@var{c}
matches any character whose syntax is not @var{c}.
@var{c}.
@end table
- The constructs that pertain to words and syntax are controlled by the
-setting of the syntax table (@pxref{Syntax}).
+ The constructs that pertain to words and syntax are controlled by
+the setting of the syntax table. @xref{Syntax Tables,, Syntax Tables,
+elisp, The Emacs Lisp Reference Manual}.
@node Regexp Example
@section Regular Expression Example
- Here is an example of a regexp---the regexp that Emacs uses, by
-default, to recognize the end of a sentence, not including the
-following space (i.e., the variable @code{sentence-end-base}):
+ Here is an example of a regexp---similar to the regexp that Emacs
+uses, by default, to recognize the end of a sentence, not including
+the following space (i.e., the variable @code{sentence-end-base}):
@example
@verbatim
-[.?!][]\"'””)}]*
+[.?!][]\"')}]*
@end verbatim
@end example
Searches in Emacs normally ignore the case of the text they are
searching through, if you specify the text in lower case. Thus, if
you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo}
-are also considered a match. Regexps, and in particular character
-sets, are included: @samp{[ab]} would match @samp{a} or @samp{A} or
-@samp{b} or @samp{B}.@refill
+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
An upper-case letter anywhere in the incremental search string makes
the search case-sensitive. Thus, searching for @samp{Foo} does not find
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. When the mark is active, they operate on the
-region instead (@pxref{Mark}). The basic replace commands replace one
+end of the buffer. When the region is active, they operate on it
+instead (@pxref{Mark}). The basic replace commands replace one
@dfn{search string} (or regexp) with one @dfn{replacement string}. It
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.
-* Replacement and Case:: How replacements preserve case of letters.
-* Query Replace:: How to use querying.
+* Unconditional Replace:: Replacing all matches for a string.
+* Regexp Replace:: Replacing all matches for a regexp.
+* Replacement and Case:: How replacements preserve case of letters.
+* 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{Mark Ring}.
A prefix argument restricts replacement to matches that are
-surrounded by word boundaries. The argument's value doesn't matter.
+surrounded by word boundaries.
@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
@table @kbd
@item M-% @var{string} @key{RET} @var{newstring} @key{RET}
-@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
Replace some occurrences of @var{string} with @var{newstring}.
@item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
-@itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
Replace some matches for @var{regexp} with @var{newstring}.
@end table
@code{query-replace} works just like @code{replace-string}
(@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 consider
+(@pxref{Replacement and Case}). A numeric argument means to consider
only occurrences that are bounded by word-delimiter characters.
@kindex C-M-%
These commands highlight the current match using the face
@code{query-replace}. They highlight other matches using
@code{lazy-highlight} just like incremental search (@pxref{Incremental
-Search}). By default, @code{query-replace-regexp} will show
+Search}). By default, @code{query-replace-regexp} will show the
substituted replacement string for the current match in the
minibuffer. If you want to keep special sequences @samp{\&} and
@samp{\@var{n}} unexpanded, customize
@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
This command is just like @code{multi-isearch-buffers}, except it
performs an incremental regexp search.
+@cindex Occur mode
+@cindex mode, Occur
@item M-x occur
Prompt for a regexp, and display a list showing each line in the
buffer that contains a match for it. To limit the search to part of
@kindex RET @r{(Occur mode)}
@kindex o @r{(Occur mode)}
@kindex C-o @r{(Occur mode)}
-The buffer @samp{*Occur*} containing the output serves as a menu for
-finding the occurrences in their original context. Click
-@kbd{Mouse-2} on an occurrence listed in @samp{*Occur*}, or position
-point there and type @key{RET}; this switches to the buffer that was
-searched and moves point to the original of the chosen occurrence.
-@kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o}
-does not select it.
-
-After using @kbd{M-x occur}, you can use @code{next-error} to visit
-the occurrences found, one by one. @ref{Compilation Mode}.
+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
+can use the @kbd{C-x `} (@code{next-error}) command to visit the
+occurrences one by one (@pxref{Compilation Mode}).
+
+@cindex Occur Edit mode
+@cindex mode, 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.
+
+The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x
+occur}.
@kindex M-s o
@item M-s o
string search. You can also run @kbd{M-s o} when an incremental
search is active; this uses the current search string.
-@item M-x list-matching-lines
-Synonym for @kbd{M-x occur}.
-
@item M-x multi-occur
This command is just like @code{occur}, except it is able to search
through multiple buffers. It asks you to specify the buffer names one
If a match is split across lines, this command keeps all those lines.
@end table
-
-@ignore
- arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e
-@end ignore