comparison man/search.texi @ 90224:2d92f5c9d6ae

Revision: [e-mail]--gnu-2005/emacs--unicode--0--patch-78 Merge from emacs--cvs-trunk--0 Patches applied: * emacs--cvs-trunk--0 (patch 514-518) - Update from CVS - Merge from gnus--rel--5.10 * gnus--rel--5.10 (patch 104-105) - Update from CVS

90223:edf295560b5a

@c This is part of the Emacs manual.
@c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2004, 2005
@c   Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Search, Fixit, Display, Top
@chapter Searching and Replacement
@cindex searching
@cindex finding strings within text

* 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.
* 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

@subsection Isearch for Non-@acronym{ASCII} Characters

@cindex searching for non-@acronym{ASCII} characters
@cindex input method, during incremental search

  To enter non-@acronym{ASCII} characters in an incrementral 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
that by including the input method mnemonic in its prompt, like this:

@samp{\}), and it introduces additional special constructs.

Because @samp{\} quotes special characters, @samp{\$} is a regular
expression that matches only @samp{$}, and @samp{\[} is a regular
expression that matches only @samp{[}, and so on.
@end table

Note: for historical compatibility, special characters are treated as
ordinary ones if they are in contexts where their special meanings make no
sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
no preceding expression on which the @samp{*} can act.  It is poor practice
to depend on this behavior; it is better to quote the special character anyway,
regardless of where it appears.@refill

For the most part, @samp{\} followed by any character matches only that
character.  However, there are several exceptions: two-character
sequences starting with @samp{\} that have special meanings.  The second
character in the sequence is always an ordinary character when used on
its own.  Here is a table of @samp{\} constructs.

@table @kbd
@item \|
specifies an alternative.  Two regular expressions @var{a} and @var{b}
with @samp{\|} in between form an expression that matches some text if

@end table

  The constructs that pertain to words and syntax are controlled by the
setting of the syntax table (@pxref{Syntax}).

  Here is a complicated regexp.  It is a simplified version of the
regexp that Emacs uses, by default, to recognize the end of a sentence
together with any whitespace that follows.  We show its Lisp syntax to
distinguish the spaces from the tab characters.  In Lisp syntax, the
string constant begins and ends with a double-quote.  @samp{\"} stands
for a double-quote as part of the regexp, @samp{\\} for a backslash as
part of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline.

@key{TAB} to enter a tab, and @kbd{C-j} to enter a newline.  You would
also type single backslashes as themselves, instead of doubling them
for Lisp syntax.  In commands that use ordinary minibuffer input to
read a regexp, you would quote the @kbd{C-j} by preceding it with a
@kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer.

@ignore
@c I commented this out because it is missing vital information
@c and therefore useless.  For instance, what do you do to *use* the
@c regular expression when it is finished?  What jobs is this good for?
@c  -- rms

@findex re-builder
@cindex authoring regular expressions
  For convenient interactive development of regular expressions, you
can use the @kbd{M-x re-builder} command.  It provides a convenient
interface for creating regular expressions, by giving immediate visual
feedback.  The buffer from which @code{re-builder} was invoked becomes
the target for the regexp editor, which pops in a separate window.  At
all times, all the matches in the target buffer for the current
regular expression are highlighted.  Each parenthesized sub-expression
of the regexp is shown in a distinct face, which makes it easier to
verify even very complex regexps.  (On displays that don't support
colors, Emacs blinks the cursor around the matched text, as it does
for matching parens.)
@end ignore

@node Search Case
@section Searching and Case

  Incremental searches in Emacs normally ignore the case of the text

@cindex global substitution

  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
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

90224:2d92f5c9d6ae

@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 See file emacs.texi for copying conditions.
@node Search, Fixit, Display, Top
@chapter Searching and Replacement
@cindex searching
@cindex finding strings within text

* 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.
@end menu

@subsection Isearch for Non-@acronym{ASCII} Characters

@cindex searching for non-@acronym{ASCII} characters
@cindex input method, during incremental 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
that by including the input method mnemonic in its prompt, like this:

@samp{\}), and it introduces additional special constructs.

Because @samp{\} quotes special characters, @samp{\$} is a regular
expression that matches only @samp{$}, and @samp{\[} is a regular
expression that matches only @samp{[}, and so on.

See the following section for the special constructs that begin
with @samp{\}.
@end table

  Note: for historical compatibility, special characters are treated as
ordinary ones if they are in contexts where their special meanings make no
sense.  For example, @samp{*foo} treats @samp{*} as ordinary since there is
no preceding expression on which the @samp{*} can act.  It is poor practice
to depend on this behavior; it is better to quote the special character anyway,
regardless of where it appears.

@node Regexp Backslash
@section Backslash in Regular Expressions

  For the most part, @samp{\} followed by any character matches only
that character.  However, there are several exceptions: two-character
sequences starting with @samp{\} that have special meanings.  The
second character in the sequence is always an ordinary character when
used on its own.  Here is a table of @samp{\} constructs.

@table @kbd
@item \|
specifies an alternative.  Two regular expressions @var{a} and @var{b}
with @samp{\|} in between form an expression that matches some text if

@end table

  The constructs that pertain to words and syntax are controlled by the
setting of the syntax table (@pxref{Syntax}).

@node Regexp Example
@section Regular Expression Example

  Here is a complicated regexp---a simplified version of the regexp
that Emacs uses, by default, to recognize the end of a sentence
together with any whitespace that follows.  We show its Lisp syntax to
distinguish the spaces from the tab characters.  In Lisp syntax, the
string constant begins and ends with a double-quote.  @samp{\"} stands
for a double-quote as part of the regexp, @samp{\\} for a backslash as
part of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline.

@key{TAB} to enter a tab, and @kbd{C-j} to enter a newline.  You would
also type single backslashes as themselves, instead of doubling them
for Lisp syntax.  In commands that use ordinary minibuffer input to
read a regexp, you would quote the @kbd{C-j} by preceding it with a
@kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer.

@node Search Case
@section Searching and Case

  Incremental searches in Emacs normally ignore the case of the text

@cindex global substitution

  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 @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