@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2015 Free Software
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software
@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Search
with a different string. There are also commands that do the same
thing, but search for patterns instead of fixed strings.
- You can also search multiple files under the control of a tags table
-(@pxref{Tags Search}) or through the Dired @kbd{A} command
+ You can also search multiple files under the control of @code{xref}
+(@pxref{Identifier Search}) or through the Dired @kbd{A} command
(@pxref{Operating on Files}), or ask the @code{grep} program to do it
(@pxref{Grep Searching}).
* Regexps:: Syntax of regular expressions.
* Regexp Backslash:: Regular expression constructs starting with `\'.
* Regexp Example:: A complex regular expression explained.
-* Lax Search:: Search ignores some distinctions between
+* Lax Search:: Search ignores some distinctions among
similar characters, like letter-case.
* Replace:: Search, and replace some or all matches.
* Other Repeating Search:: Operating on all matches for some regexp.
@cindex incremental search, edit search string
@cindex interactively edit search string
@kindex M-e @r{(Incremental search)}
-@kindex Mouse-1 @r{in the minibuffer (Incremental Search)}
+@kindex mouse-1 @r{in the minibuffer (Incremental Search)}
To edit the current search string in the minibuffer without
replacing it with items from the search ring, type @kbd{M-e} or click
-@kbd{Mouse-1} in the minibuffer. Type @key{RET}, @kbd{C-s} or
+@kbd{mouse-1} in the minibuffer. Type @key{RET}, @kbd{C-s} or
@kbd{C-r} to finish editing the string and search for it. Type
@kbd{C-f} or @kbd{@key{RIGHT}} to add to the search string characters
following point from the buffer from which you started the search.
@kindex C-y @r{(Incremental search)}
@kindex M-y @r{(Incremental search)}
-@kindex Mouse-2 @r{in the minibuffer (Incremental search)}
+@kindex mouse-2 @r{in the minibuffer (Incremental search)}
@findex isearch-yank-kill
@findex isearch-yank-pop
@findex isearch-yank-x-selection
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}). Clicking @kbd{Mouse-2}
+(@code{yank-pop}) command (@pxref{Yanking}). Clicking @kbd{mouse-2}
in the echo area appends the current X selection (@pxref{Primary
Selection}) to the search string (@code{isearch-yank-x-selection}).
Normally, typing a command that is not bound by the incremental
search exits the search before executing the command. Thus, the
command operates on the buffer from which you invoked the search.
-However, if you customize the variable @code{search-exit-option} to a
-@code{nil} value, the characters which you type that are not
-interpreted by the incremental search are simply appended to the
-search string. This is so you could include in the search string
-control characters, such as @kbd{C-a}, that would normally exit the
-search and invoke the command bound to them on the buffer.
+However, if you customize the variable @code{search-exit-option} to
+@code{nil}, the characters which you type that are not interpreted by
+the incremental search are simply appended to the search string. This
+is so you could include in the search string control characters, such
+as @kbd{C-a}, that would normally exit the search and invoke the
+command bound to them on the buffer.
@table @asis
@item Prefix Arguments
string with @key{RET}, and then the search takes place. If the string
is not found, the search command signals an error.
-@findex search-forward
-@findex search-backward
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}.
+command for nonincremental search, if the string you specify is empty.
+(Such an empty argument would otherwise be useless.) @kbd{C-r
+@key{RET}} does likewise, invoking the nonincremental
+backward-searching command.
+
+ Nonincremental search can also be invoked form the menu bar's
+@samp{Edit->Search} menu.
+
+@findex search-forward
+@findex search-backward
+ You can also use two simpler commands, @kbd{M-x search-forward} and
+@kbd{M-x search-backward}. These commands look for the literal
+strings you specify, and don't support any of the lax-search features
+(@pxref{Lax Search}) except case folding.
@node Word Search
@section Word Search
additional laxity does not apply to the lazy highlight
(@pxref{Incremental Search}), which always matches whole words.
+ The word search commands don't perform character folding, and
+toggling lax whitespace matching (@pxref{Lax Search, lax space
+matching}) has no effect on them.
+
@kindex M-s M-w
@findex eww-search-word
@vindex eww-search-prefix
the search string are required to match the beginning and end of a
symbol, respectively.
+ The symbol search commands don't perform character folding, and
+toggling lax whitespace matching (@pxref{Lax Search, lax space
+matching}) has no effect on them.
+
@node Regexp Search
@section Regular Expression Search
@cindex regexp search
@code{regexp-search-ring-max}, 16 by default.
Unlike ordinary incremental search, incremental regexp search
-do not use lax space matching by default. To toggle this feature
+does not use lax space matching by default. To toggle this feature
use @kbd{M-s @key{SPC}} (@code{isearch-toggle-lax-whitespace}).
Then any @key{SPC} typed in incremental regexp search will match
any sequence of one or more whitespace characters. The variable
@code{search-whitespace-regexp} specifies the regexp for the lax
space matching. @xref{Special Isearch}.
+ Also unlike ordinary incremental search, incremental regexp search
+cannot use character folding (@pxref{Lax Search}). (If you toggle
+character folding during incremental regexp search with @kbd{M-s '},
+the search becomes a non-regexp search and the search pattern you
+typed is interpreted as a literal string.)
+
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},
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}}.
+with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. When you invoke
+these commands with @kbd{M-x}, they search for the exact regexp you
+specify, and thus don't support any lax-search features (@pxref{Lax
+Search}) except case folding.
If you use the incremental regexp search commands with a prefix
argument, they perform ordinary string search, like
@cindex lax search
@cindex character equivalence in search
Normally, you'd want search commands to disregard certain minor
-differences between the search string you types and the text being
+differences between the search string you type and the text being
searched. For example, sequences of whitespace characters of
-different length are normally perceived as equivalent; letter-case
+different length are usually perceived as equivalent; letter-case
differences usually don't matter; etc. This is known as
@dfn{character equivalence}.
each space, or sequence of spaces, matches any sequence of one or more
whitespace characters in the text. (Incremental regexp search has a
separate default; see @ref{Regexp Search}.) Hence, @samp{foo bar}
-matches @samp{foo bar}, @samp{foo@w{ }bar}, @samp{foo@w{ }bar}, and so
-on (but not @samp{foobar}). More precisely, Emacs matches each
+matches @samp{foo bar}, @samp{foo@w{ }bar}, @samp{foo@w{ }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, to make spaces match sequences of newlines as well as
spaces, tabs, and formfeed characters as whitespace.
If you want whitespace characters to match exactly, you can turn lax
-space matching by typing @kbd{M-s @key{SPC}}
+space matching off by typing @kbd{M-s @key{SPC}}
(@code{isearch-toggle-lax-whitespace}) within an incremental search.
Another @kbd{M-s @key{SPC}} turns lax space matching back on. To
-disable this feature entirely, change @code{search-whitespace-regexp}
-to @code{nil}; then each space in the search string matches exactly
-one space.
+disable lax whitespace matching for all searches, change
+@code{search-whitespace-regexp} to @code{nil}; then each space in the
+search string matches exactly one space.
@cindex case folding in search
@cindex case-sensitivity and search
- Searches in Emacs normally ignore the case of the text they are
+ Searches in Emacs by default ignore the case of the text they are
searching through, if you specify the search string in lower case.
Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
@samp{foo} also match. Regexps, and in particular character sets,
An upper-case letter anywhere in the search string makes the search
case-sensitive. Thus, searching for @samp{Foo} does not find
@samp{foo} or @samp{FOO}. This applies to regular expression search
-as well as to string search. The effect ceases if you delete the
-upper-case letter from the search string. The variable
+as well as to literal string search. The effect ceases if you delete
+the upper-case letter from the search string. The variable
@code{search-upper-case} controls this: if it is non-@code{nil} (the
default), an upper-case character in the search string make the search
case-sensitive; setting it to @code{nil} disables this effect of
Typing @kbd{M-c} or @kbd{M-s c} (@code{isearch-toggle-case-fold})
within an incremental search toggles the case sensitivity of that
search. The effect does not extend beyond the current incremental
-search to the next one, but it does override the effect of adding or
-removing an upper-case letter in the current search.
+search, but it does override the effect of adding or removing an
+upper-case letter in the current search.
Several related variables control case-sensitivity of searching and
matching for specific commands or activities. For instance,
@cindex character folding in search
@cindex equivalent character sequences
- Case folding disregards case distinctions between characters, making
+ Case folding disregards case distinctions among characters, making
upper-case characters match lower-case variants, and vice versa. A
generalization of case folding is @dfn{character folding}, which
-disregards wider classes of distinctions between similar characters.
-For instance, under character folding the letter @code{a} will match
-all of its accented cousins like @code{@"a} and @code{@'a}, i.e., the
-match disregards the diacriticals that distinguish between these
-variants. In addition, @code{a} will match other characters that
+disregards wider classes of distinctions among similar characters.
+For instance, under character folding the letter @code{a} matches all
+of its accented cousins like @code{@"a} and @code{@'a}, i.e., the
+match disregards the diacritics that distinguish these
+variants. In addition, @code{a} matches other characters that
resemble it, or have it as part of their graphical representation,
such as @sc{u+249c parenthesized latin small letter a} and @sc{u+2100
account of} (which looks like a small @code{a} over @code{c}).
-Similarly, the @acronym{ASCII} double-quote character @code{"} will
-match all the other variants of double quotes defined by the Unicode
-standard.
-@ignore @c FIXME: This doesn't work. Should it?
-Finally, character folding can make a sequence of one or
+Similarly, the @acronym{ASCII} double-quote character @code{"} matches
+all the other variants of double quotes defined by the Unicode
+standard. Finally, character folding can make a sequence of one or
more characters match another sequence of a different length: for
-example, the sequence of two characters @code{ae} matches the ligature
-@code{@ae{}}.
-@end ignore
-Character sequences that match under character folding are called
-@dfn{equivalent}.
+example, the sequence of two characters @code{ff} matches @sc{u+fb00
+latin small ligature ff}. Character sequences that are not identical,
+but match under character folding are known as @dfn{equivalent
+character sequences}.
@kindex M-s ' @r{(Incremental Search)}
-@findex isearch-toggle-character-fold
- Searches in Emacs normally perform character folding, thus matching
-equivalent character sequences. You can disable this behavior by
-customizing the variable @code{search-default-regexp-mode} to the
-@code{nil} value. @xref{Search Customizations}. Within an
-incremental search, typing @kbd{M-s '}
-(@code{isearch-toggle-character-fold}) toggles character folding, but
-only for that search.
+@findex isearch-toggle-char-fold
+ Generally, search commands in Emacs do not by default perform
+character folding in order to match equivalent character sequences.
+You can enable this behavior by customizing the variable
+@code{search-default-mode} to @code{char-fold-to-regexp}.
+@xref{Search Customizations}. Within an incremental search, typing
+@kbd{M-s '} (@code{isearch-toggle-char-fold}) toggles character
+folding, but only for that search. (Replace commands have a different
+default, controlled by a separate option; see @ref{Replacement and Lax
+Matches}.)
Like with case folding, typing an explicit variant of a character,
such as @code{@"a}, as part of the search string disables character
@cindex character folding in replace commands
The replacement commands by default do not use character folding
(@pxref{Lax Search, character folding}) when looking for the text to
-replace. To enable character folding for matching, set the variable
-@code{replace-character-fold} to a non-@code{nil} value. (This
+replace. To enable character folding for matching in
+@code{query-replace} and @code{replace-string}, set the variable
+@code{replace-char-fold} to a non-@code{nil} value. (This
setting does not affect the replacement text, only how Emacs finds the
-text to replace.)
+text to replace. It also doesn't affect @code{replace-regexp}.)
@node Query Replace
@subsection Query Replace
@cindex default search mode
@cindex search mode, default
The default search mode for the incremental search is specified by
-the variable @code{search-default-regexp-mode}. It can be @code{nil},
+the variable @code{search-default-mode}. It can be @code{nil},
@code{t}, or a function. If it is @code{nil}, the default mode is to
do literal searches without character folding, but with case folding
and lax-whitespace matches as determined by @code{case-fold-search}
and @code{search-whitespace-regexp}, respectively (@pxref{Lax
Search}). If the value is @code{t}, incremental search defaults to
-regexp searches. The default value specifies a function that causes
-the default search mode to perform character folding in addition to
-case folding and lax-whitespace matching.
+regexp searches. The default value specifies a function that only
+performs case folding and lax-whitespace matching.
@vindex search-highlight
The current match of an on-going incremental search is highlighted
using the @code{isearch} face. This highlighting can be disabled by
-setting the variable @code{search-highlight} to a @code{nil} value.
+setting the variable @code{search-highlight} to @code{nil}.
@cindex lazy highlighting customizations
@vindex isearch-lazy-highlight
@cindex lazy-highlight face
The other matches for the search string that are visible on display
are highlighted using the @code{lazy-highlight} face. Setting the
-variable @code{isearch-lazy-highlight} to a @code{nil} value disables
-this highlighting. Here are some other variables that customize the
-lazy highlighting:
+variable @code{isearch-lazy-highlight} to @code{nil} disables this
+highlighting. Here are some other variables that customize the lazy
+highlighting:
@table @code
@item lazy-highlight-initial-delay
search string is empty launches a nonincremental search. (Actually,
it lets you edit the search string, and the next @key{RET} does the
search.) However, if you customize the variable
-@code{search-nonincremental-instead} to a @code{nil} value, typing
-@key{RET} will always exit the incremental search, even if the search
-string is empty.
+@code{search-nonincremental-instead} to @code{nil}, typing @key{RET}
+will always exit the incremental search, even if the search string is
+empty.
@vindex isearch-hide-immediately
By default, incremental search and query-replace commands match
invisible text, but hide any such matches as soon as the current match
moves off the invisible text. If you customize the variable
-@code{isearch-hide-immediately} to a @code{nil} value, any invisible
-text where matches were found stays on display until the search or the
+@code{isearch-hide-immediately} to @code{nil}, any invisible text
+where matches were found stays on display until the search or the
replace command exits.
@cindex search display on slow terminals