comparison man/search.texi @ 82981:335d5c2fc901

Revision: [e-mail]--gnu-2004/emacs--gnus--5.10--patch-2 Merge from [e-mail]--2004/emacs--multi-tty--0, emacs--cvs-trunk--0 Patches applied: * [e-mail]--2004/emacs--multi-tty--0--patch-224 Added sorted-doc to backup regex in lib-src. * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-465 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-482 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-483 Build-in-place tweak * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-484 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-486 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-487 Tweak permissions * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-488 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-489 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-490 Update from CVS: man/fixit.texi (Spelling): Fix typo. * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-491 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-494 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-495 Update from CVS: Add missing lisp/mh-e files * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-496 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-499 Update from CVS * [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-500 - [e-mail]--gnu-2004/emacs--cvs-trunk--0--patch-522 Update from CVS

82980:08aac74a5b90

  When you exit the incremental search, it sets the mark to where point
@emph{was}, before the search.  That is convenient for moving back
there.  In Transient Mark mode, incremental search sets the mark without
activating it, and does so only if the mark is not already active.

  @kbd{M-%} or @kbd{C-M-%} exits the incremental search and starts an
interactive command @code{query-replace} or @code{query-replace-regexp}
with the last search string inserted in the minibuffer as initial input
for the string to replace.

@cindex lazy search highlighting
@vindex isearch-lazy-highlight
  When you pause for a little while during incremental search, it
highlights all other possible matches for the search string.  This

@cindex syntax of regexps

  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 same manual}.

  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{$},

@item
The buffer contents.
@item
The selected window and selected frame.
@item
The current match-data @xref{Match Data,,,elisp}.
@end enumerate

Additionally, the command must not delete the current window and must
not itself attempt an incremental search.  It may, however, change the
window's size, or create or delete other windows and frames.

Note that an attempt by a command to scroll the text
@emph{horizontally} won't work, although it will do no harm---any such
scrolling will be overriden and nullified by the display code.

@node Replace, Other Repeating Search, Configuring Scrolling, Search
@section Replacement Commands
@cindex replacement
@cindex search-and-replace commands

text to replace with, you must enter @samp{\\}.

  You can also use Lisp expressions to calculate parts of the
replacement string.  To do this, write @samp{\,} followed by the
expression in the replacement string.  Each replacement calculates the
value of the expression, which ought to be a string, and uses it in
the replacement string in place of the expression itself.  If the
expression is a symbol, one space in the replacement string after the
symbol name counts as part of the symbol name, so the value replaces
them both.

  Inside such an expression, @samp{\&} and @samp{\@var{n}} used as
subexpressions refer respectively to the entire match as a string, and
to a submatch as a string.  @var{n} may exceed 9 here, and the value
of @samp{\@var{n}} is @code{nil} if subexpression @var{n} did not
match.  You can also use @samp{\#&} and @samp{\#@var{n}} refer to
those matches converted to numbers (this is valid when the match or
submatch has the form of a number).  @samp{\#} stands for the number
of already-completed replacements.

  Repeating our example to exchange @samp{x} and @samp{y}, we can thus
do it also this way:

@example
M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
\,(if \1 "y" "x") @key{RET}
@end example

  The @code{format} function (@pxref{Formatting Strings,,,elisp, GNU
Emacs Lisp Reference Manual}) comes in handy for computing replacement
strings for @samp{\,}.  For example, to add consecutively numbered
strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
already occupied), you can use

@example
M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
\,(format "%-72sABC%05d" \& \#) @key{RET}
@end example

  If you want to enter part of the replacement string by hand each
time, use @samp{\?} in the replacement string.  Each replacement will
enter a recursive edit, with point at the position where the @samp{\?}
was.  For example,

@example
M-x replace-regexp @key{RET} \footnote@{ @key{RET}
\&\\label@{fn:\#\?@} @key{RET}
@end example

@noindent
will add labels starting with @samp{\label@{fn:0@}} to occurences of
@samp{\footnote@{}, but letting you edit each replacement before
performing it.  To number the labels starting at 1, use @samp{\,(1+
\#)} instead of @samp{\#}.

@node Replacement and Case, Query Replace, Regexp Replace, Replace

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.

@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

82981:335d5c2fc901

  When you exit the incremental search, it sets the mark to where point
@emph{was}, before the search.  That is convenient for moving back
there.  In Transient Mark mode, incremental search sets the mark without
activating it, and does so only if the mark is not already active.

  @kbd{M-%} typed 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.

@cindex lazy search highlighting
@vindex isearch-lazy-highlight
  When you pause for a little while during incremental search, it
highlights all other possible matches for the search string.  This

@cindex syntax of regexps

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

  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{$},

@item
The buffer contents.
@item
The selected window and selected frame.
@item
The current match-data.  @xref{Match Data,,, elisp, The Emacs Lisp
Reference Manual}.
@end enumerate

Additionally, the command must not delete the current window and must
not itself attempt an incremental search.  It may, however, change the
window's size, or create or delete other windows and frames.

Note that an attempt by a command to scroll the text
@emph{horizontally} won't work, although it will do no harm---any such
scrolling will be overridden and nullified by the display code.

@node Replace, Other Repeating Search, Configuring Scrolling, Search
@section Replacement Commands
@cindex replacement
@cindex search-and-replace commands

text to replace with, you must enter @samp{\\}.

  You can also use Lisp expressions to calculate parts of the
replacement string.  To do this, write @samp{\,} followed by the
expression in the replacement string.  Each replacement calculates the
value of the expression and converts it to text without quoting (if
it's a string, this means using the string's contents), and uses it in
the replacement string in place of the expression itself.  If the
expression is a symbol, one space in the replacement string after the
symbol name goes with the symbol name, so the value replaces them
both.

  Inside such an expression, you can use some special sequences.
@samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire
match as a string, and to a submatch as a string.  @var{n} may be
multiple digits, and the value of @samp{\@var{n}} is @code{nil} if
subexpression @var{n} did not match.  You can also use @samp{\#&} and
@samp{\#@var{n}} to refer to those matches as numbers (this is valid
when the match or submatch has the form of a numeral).  @samp{\#} here
too stands for the number of already-completed replacements.

  Repeating our example to exchange @samp{x} and @samp{y}, we can thus
do it also this way:

@example
M-x replace-regexp @key{RET} \(x\)\|y @key{RET}
\,(if \1 "y" "x") @key{RET}
@end example

  For computing replacement strings for @samp{\,}, the @code{format}
function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs
Lisp Reference Manual}).  For example, to add consecutively numbered
strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are
already occupied), you can use

@example
M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET}
\,(format "%-72sABC%05d" \& \#) @key{RET}
@end example

  If you want to enter part of the replacement string by hand each
time, use @samp{\?} in the replacement string.  Each replacement will
ask you to edit the replacement string in the minibuffer, putting
point where the @samp{\?} was.  For example,

@example
M-x replace-regexp @key{RET} \\footnote@{ @key{RET}
\&\\label@{fn:\#\?@} @key{RET}
@end example

@noindent
will add labels starting with @samp{\label@{fn:0@}} to occurrences of
@samp{\footnote@{}, but letting you edit each replacement before
performing it.  To number the labels starting at 1, use @samp{\,(1+
\#)} instead of @samp{\#}.

@node Replacement and Case, Query Replace, Regexp Replace, Replace

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.

Occur mode supports the @code{next-error} functionality described in
in @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