Mercurial > emacs
changeset 84195:0560c07ceabf
Move to ../doc/emacs/, misc/
| author | Glenn Morris <rgm@gnu.org> |
|---|---|
| date | Thu, 06 Sep 2007 04:40:11 +0000 |
| parents | 90c522bcea44 |
| children | 40b5b59581cc |
| files | man/search.texi |
| diffstat | 1 files changed, 0 insertions(+), 1361 deletions(-) [+] |
line wrap: on
line diff
--- a/man/search.texi Thu Sep 06 04:40:05 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,1361 +0,0 @@ -@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 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 - - Like other editors, Emacs has commands for searching for occurrences of -a string. The principal search command is unusual in that it is -@dfn{incremental}; it begins to search before you have finished typing the -search string. There are also nonincremental search commands more like -those of other editors. - - Besides the usual @code{replace-string} command that finds all -occurrences of one string and replaces them with another, Emacs has a -more flexible replacement command called @code{query-replace}, which -asks interactively which occurrences to replace. There are also -commands to find and operate on all matches for a pattern. - - You can also search multiple files under control of a tags -table (@pxref{Tags Search}) or through the Dired @kbd{A} command -(@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. -@end menu - -@node Incremental Search -@section Incremental Search -@cindex incremental search -@cindex isearch - - An incremental search begins searching as soon as you type the first -character of the search string. As you type in the search string, Emacs -shows you where the string (as you have typed it so far) would be -found. When you have typed enough characters to identify the place you -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}. - -@table @kbd -@item C-s -Incremental search forward (@code{isearch-forward}). -@item C-r -Incremental search backward (@code{isearch-backward}). -@end table - -@menu -* Basic Isearch:: Basic incremental search commands. -* Repeat Isearch:: Searching for the same string again. -* Error in Isearch:: When your string is not found. -* Special Isearch:: Special input in incremental search. -* Non-ASCII Isearch:: How to search for non-ASCII characters. -* Isearch Yank:: Commands that grab text into the search string - or else edit the search string. -* Highlight Isearch:: Isearch highlights the other possible matches. -* Isearch Scroll:: Scrolling during an incremental search. -* Slow Isearch:: Incremental search features for slow terminals. -@end menu - -@node Basic Isearch -@subsection Basics of Incremental Search - -@kindex C-s -@findex isearch-forward - @kbd{C-s} starts a forward incremental search. It reads characters -from the keyboard, and moves point past the next occurrence of those -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 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 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. - - If you make a mistake in typing the search string, you can cancel -characters with @key{DEL}. Each @key{DEL} cancels the last character of -search string. This does not happen until Emacs is ready to read another -input character; first it must either find, or fail to find, the character -you want to erase. If you do not want to wait for this to happen, use -@kbd{C-g} as described below. - - When you are satisfied with the place you have reached, you can type -@key{RET}, which stops searching, leaving the cursor where the search -brought it. Also, any command not specially meaningful in searches -stops the searching and is then executed. Thus, typing @kbd{C-a} -would exit the search and then move to the beginning of the line. -@key{RET} is necessary only if the next command you want to type is a -printing character, @key{DEL}, @key{RET}, or another character that is -special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, -@kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some other -meta-characters). - - When you exit the incremental search, it sets the mark 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. - -@node Repeat Isearch -@subsection Repeating Incremental Search - - Sometimes you search for @samp{FOO} and find one, but not the one you -expected to find. There was a second @samp{FOO} that you forgot -about, before the one you were aiming for. In this event, type -another @kbd{C-s} to move to the next occurrence of the search string. -You can repeat this any number of times. If you overshoot, you can -cancel some @kbd{C-s} characters with @key{DEL}. - - After you exit 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.'' - - If a search is failing and you ask to repeat it by typing another -@kbd{C-s}, it starts again from the beginning of the buffer. -Repeating a failing reverse search with @kbd{C-r} starts again from -the end. This is called @dfn{wrapping around}, and @samp{Wrapped} -appears in the search prompt once this has happened. If you keep on -going past the original starting point of the search, it changes to -@samp{Overwrapped}, which means that you are revisiting matches that -you have already seen. - - 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. - - 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 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 - - 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}. -At this point there are several things you can do. If your string was -mistyped, you can rub some of it out and correct it. If you like the place -you have found, you can type @key{RET} or some other Emacs command to -remain there. Or you can type @kbd{C-g}, which -removes from the search string the characters that could not be found (the -@samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in -@samp{FOOT}). A second @kbd{C-g} at that point cancels the search -entirely, returning point to where it was when the search started. - -@cindex quitting (in search) - The @kbd{C-g} ``quit'' character 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} cancels the -entire search. The cursor moves back to where you started the search. If -@kbd{C-g} is typed when there are characters in the search string that have -not been found---because Emacs is still searching for them, or because it -has failed to find them---then the search string characters which have not -been found are discarded from the search string. With them gone, the -search is now successful and waiting for more input, so a second @kbd{C-g} -will cancel the entire search. - -@node Special Isearch -@subsection Special Input for Incremental Search - - An upper-case letter in the search string makes the search -case-sensitive. If you delete the upper-case character from the search -string, it ceases to have this effect. @xref{Search Case}. - - To search for a newline, type @kbd{C-j}. To search for another -control character, such as control-S or carriage return, you must quote -it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous -to its use for insertion (@pxref{Inserting Text}): it causes the -following character to be treated the way any ``ordinary'' character is -treated in the same context. You can also specify a character by its -octal code: enter @kbd{C-q} followed by a sequence of octal digits. - - @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. @xref{Query -Replace}. - - Entering @key{RET} when the search string is empty launches -nonincremental search (@pxref{Nonincremental Search}). - -@vindex isearch-mode-map - To customize the special characters that incremental search understands, -alter their bindings in the keymap @code{isearch-mode-map}. For a list -of bindings, look at the documentation of @code{isearch-mode} with -@kbd{C-h f isearch-mode @key{RET}}. - -@node Non-ASCII Isearch -@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 can use @kbd{C-q} (see the previous section), but it is easier to -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 in the search string also. Emacs indicates that by including the -input method mnemonic in its prompt, like this: - -@example -I-search [@var{im}]: -@end example - -@noindent -@findex isearch-toggle-input-method -@findex isearch-toggle-specified-input-method -where @var{im} is the mnemonic of the active input method. - - You can toggle (enable or disable) the input method while you type -the search string with @kbd{C-\} (@code{isearch-toggle-input-method}). -You can turn on a certain (non-default) input method with @kbd{C-^} -(@code{isearch-toggle-specified-input-method}), which prompts for the -name of the input method. The input method you enable during -incremental search remains enabled in the current buffer afterwards. - -@node Isearch Yank -@subsection Isearch Yanking - - The characters @kbd{C-w} and @kbd{C-y} can be used in incremental -search 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 as part of the -search string, advancing point over it. (The decision, whether to -copy a character or a word, is heuristic.) Another @kbd{C-s} to -repeat the search will then search for a string including that -character or word. - - @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. Both @kbd{C-y} and -@kbd{C-w} convert the text they copy to lower case if the search is -currently not case-sensitive; this is so 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} as a command would yank. -@kbd{Mouse-2} in the echo area does the same. -@xref{Yanking}. - -@node Highlight Isearch -@subsection Lazy Search Highlighting -@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 -makes it easier to anticipate where you can get to by typing @kbd{C-s} -or @kbd{C-r} to repeat the search. The short delay before highlighting -other matches helps indicate which match is the current one. -If you don't like this feature, you can turn it off by setting -@code{isearch-lazy-highlight} to @code{nil}. - -@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). - -@node Isearch Scroll -@subsection Scrolling During Incremental Search - - 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}). -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. - - 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}): - -@example -(put 'view-lossage 'isearch-scroll t) -@end example - -@noindent -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 - - 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 - - Emacs also has conventional nonincremental search commands, which require -you to type the entire search string before searching begins. - -@table @kbd -@item C-s @key{RET} @var{string} @key{RET} -Search for @var{string}. -@item C-r @key{RET} @var{string} @key{RET} -Search backward for @var{string}. -@end table - - To do a nonincremental search, first type @kbd{C-s @key{RET}}. This -enters the minibuffer to read the search string; terminate the 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.) 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. -@ifnottex -@xref{Word Search}. -@end ifnottex -@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 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 separate key sequences -for them. - -@node Word Search -@section Word Search -@cindex word search - - Word search searches for a sequence of words without regard to how the -words are separated. More precisely, you type a string of many words, -using single spaces to separate them, and the string can be found even -if there are multiple spaces, newlines, or other punctuation characters -between these words. - - Word search is useful for editing a printed document made with a text -formatter. If you edit while looking at the printed, formatted version, -you can't tell where the line breaks are in the source file. With word -search, you can search without having to know them. - -@table @kbd -@item C-s @key{RET} C-w @var{words} @key{RET} -Search for @var{words}, ignoring details of punctuation. -@item C-r @key{RET} C-w @var{words} @key{RET} -Search backward for @var{words}, ignoring details of punctuation. -@end table - - Word search as a special case of nonincremental search is invoked -with @kbd{C-s @key{RET} C-w}. This is followed by the search string, -which must always be terminated with @key{RET}. Being nonincremental, -this search does not start until the argument is terminated. It works -by constructing a regular expression and searching for that; see -@ref{Regexp Search}. - - Use @kbd{C-r @key{RET} C-w} to do backward word search. - - You can also invoke word search with @kbd{C-s M-e C-w} or @kbd{C-r -M-e C-w} followed by the search string and terminated with @key{RET}, -@kbd{C-s} or @kbd{C-r}. This puts word search into incremental mode -where you can use all keys available for incremental search. However, -when you type more words in incremental word search, it will fail -until you type complete words. - -@findex word-search-forward -@findex word-search-backward - Forward and backward word searches are implemented by the commands -@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 separate key sequences for them. - -@node Regexp Search -@section Regular Expression Search -@cindex regular expression -@cindex regexp - - A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern -that denotes a class of alternative strings to match, possibly -infinitely many. GNU 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. - -@kindex C-M-s -@findex isearch-forward-regexp -@kindex C-M-r -@findex isearch-backward-regexp - Incremental search for a regexp is done by typing @kbd{C-M-s} -(@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a -prefix argument (whose value does not matter), or by typing @kbd{M-r} -within a forward incremental search. This command reads a -search string incrementally just like @kbd{C-s}, but it treats the -search string as a regexp rather than looking for an exact match -against the text in the buffer. Each time you add text to the search -string, you make the regexp longer, and the new regexp is searched -for. To search backward for a regexp, use @kbd{C-M-r} -(@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, -or @kbd{M-r} within a backward incremental search. - - All of the control characters that do special things within an -ordinary incremental search have the same function in incremental regexp -search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the -search retrieves the last incremental search regexp used; that is to -say, incremental regexp and non-regexp searches have independent -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}}. You can control what a -bare space matches by setting the variable -@code{search-whitespace-regexp} to the desired 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}. - - Forward and backward regexp search are not symmetrical, because -regexp matching in Emacs always operates forward, starting with the -beginning of the regexp. Thus, forward regexp search scans forward, -trying a forward match at each possible starting position. Backward -regexp search scans backward, trying a forward match at each possible -starting position. These search methods are not mirror images. - -@findex re-search-forward -@findex re-search-backward - Nonincremental search for a regexp is done by the functions -@code{re-search-forward} and @code{re-search-backward}. You can invoke -these with @kbd{M-x}, or bind them to keys, or invoke them by way of -incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r -@key{RET}}. - - If you use the incremental regexp search commands with a prefix -argument, they perform ordinary string search, like -@code{isearch-forward} and @code{isearch-backward}. @xref{Incremental -Search}. - -@node Regexps -@section Syntax of Regular Expressions -@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{$}, -@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 -@samp{f} and no other string. (It does @emph{not} match 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.) - - 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. - -@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 - -@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). - -@samp{*} always applies to the @emph{smallest} possible preceding -expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating -@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. - -The matcher processes a @samp{*} construct by matching, immediately, -as many repetitions as can be found. Then it continues with the rest -of the pattern. If that fails, backtracking occurs, discarding some -of the matches of the @samp{*}-modified construct in case that makes -it possible to match the rest of the pattern. For example, in matching -@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first -tries to match all three @samp{a}s; but the rest of the pattern is -@samp{ar} and there is only @samp{r} left to match, so this try fails. -The next alternative is for @samp{a*} to match only two @samp{a}s. -With this choice, the rest of the regexp matches successfully.@refill - -@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. - -@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. - -@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. - -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 -the text @samp{abbb}, @samp{ab*} will match it all (the longest valid -match), while @samp{ab*?} will match just @samp{a} (the shortest -valid match). - -Non-greedy operators match the shortest possible string starting at a -given starting point; in a forward search, though, the earliest -possible starting point for match is always the one chosen. Thus, if -you search for @samp{a.*?$} against the text @samp{abbab} followed by -a newline, it matches the whole string. Since it @emph{can} match -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. - -@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 -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. - -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. - -You can also include character ranges in a character set, by writing the -starting and ending characters with a @samp{-} between them. Thus, -@samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be -intermixed freely with individual characters, as in @samp{[a-z$%.]}, -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{^}. - -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 -include a @samp{-}, write @samp{-} as the first or last character of the -set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} -and @samp{-}. - -To include @samp{^} in a set, put it anywhere but at the beginning of -the set. (At the beginning, it complements the set---see below.) - -When you use a range in case-insensitive search, you should write both -ends of the range in upper case, or both in lower case, or both should -be non-letters. The behavior of a mixed-case range such as @samp{A-z} -is somewhat ill-defined, and it may change in future Emacs versions. - -@item @kbd{[^ @dots{} ]} -@samp{[^} begins a @dfn{complemented character set}, which matches any -character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches -all characters @emph{except} @acronym{ASCII} letters and digits. - -@samp{^} is not special in a character set unless it is the first -character. The character following the @samp{^} is treated as if it -were first (in other words, @samp{-} and @samp{]} are not special there). - -A complemented character set can match a newline, unless newline is -mentioned as one of the characters not to match. This is in contrast to -the handling of regexps in programs such as @code{grep}. - -@item @kbd{^} -is a special character that matches the empty string, but only at the -beginning of a line in the text being matched. Otherwise it fails to -match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at -the beginning of a line. - -For historical compatibility reasons, @samp{^} can be used with this -meaning only at the beginning of the regular expression, or after -@samp{\(} or @samp{\|}. - -@item @kbd{$} -is similar to @samp{^} but matches only at the end of a line. Thus, -@samp{x+$} matches a string of one @samp{x} or more at the end of a line. - -For historical compatibility reasons, @samp{$} can be used with this -meaning only at the end of the regular expression, or before @samp{\)} -or @samp{\|}. - -@item @kbd{\} -has two functions: it quotes the special characters (including -@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. - -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 - - 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 -either @var{a} matches it or @var{b} matches it. It works by trying to -match @var{a}, and if that fails, by trying to match @var{b}. - -Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} -but no other string.@refill - -@samp{\|} applies to the largest possible surrounding expressions. Only a -surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of -@samp{\|}.@refill - -Full backtracking capability exists to handle multiple uses of @samp{\|}. - -@item \( @dots{} \) -is a grouping construct that serves three purposes: - -@enumerate -@item -To enclose a set of @samp{\|} alternatives for other operations. -Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. - -@item -To enclose a complicated expression for the postfix operators @samp{*}, -@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches -@samp{bananana}, etc., with any (zero or more) number of @samp{na} -strings.@refill - -@item -To record a matched substring for future reference. -@end enumerate - -This last application is not a consequence of the idea of a -parenthetical grouping; it is a separate feature that is assigned as a -second meaning to the same @samp{\( @dots{} \)} construct. In practice -there is usually no conflict between the two meanings; when there is -a conflict, you can use a ``shy'' group. - -@item \(?: @dots{} \) -@cindex shy group, in regexp -specifies a ``shy'' group that does not record the matched substring; -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 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. 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, -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.'' - -The strings matching the first nine @samp{\( @dots{} \)} constructs -appearing in a regular expression are assigned numbers 1 through 9 in -the order that the open-parentheses appear in the regular expression. -So you can use @samp{\1} through @samp{\9} to refer to the text matched -by the corresponding @samp{\( @dots{} \)} constructs. - -For example, @samp{\(.*\)\1} matches any newline-free string that is -composed of two identical halves. The @samp{\(.*\)} matches the first -half, which may be anything, but the @samp{\1} that follows must match -the same exact text. - -If a particular @samp{\( @dots{} \)} construct matches more than once -(which can easily happen if it is followed by @samp{*}), only the last -match is recorded. - -@item \` -matches the empty string, but only at the beginning of the string or -buffer (or its accessible portion) being matched against. - -@item \' -matches the empty string, but only at the end of the string or buffer -(or its accessible portion) being matched against. - -@item \= -matches the empty string, but only at point. - -@item \b -matches the empty string, but only at the beginning or -end of a word. Thus, @samp{\bfoo\b} matches any occurrence of -@samp{foo} as a separate word. @samp{\bballs?\b} matches -@samp{ball} or @samp{balls} as a separate word.@refill - -@samp{\b} matches at the beginning or end of the buffer -regardless of what text appears next to it. - -@item \B -matches the empty string, but @emph{not} at the beginning or -end of a word. - -@item \< -matches the empty string, but only at the beginning of a word. -@samp{\<} matches at the beginning of the buffer only if a -word-constituent character follows. - -@item \> -matches the empty string, but only at the end of a word. @samp{\>} -matches at the end of the buffer only if the contents end with a -word-constituent character. - -@item \w -matches any word-constituent character. The syntax table -determines which characters these are. @xref{Syntax}. - -@item \W -matches any character that is not a word-constituent. - -@item \_< -matches the empty string, but only at the beginning of a symbol. -A symbol is a sequence of one or more symbol-constituent characters. -A symbol-constituent character is a character whose syntax is either -@samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the -buffer only if a symbol-constituent character follows. - -@item \_> -matches the empty string, but only at the end of a symbol. @samp{\_>} -matches at the end of the buffer only if the contents end with a -symbol-constituent character. - -@item \s@var{c} -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}. - -@item \S@var{c} -matches any character whose syntax is not @var{c}. - -@cindex categories of characters -@cindex characters which belong to a specific language -@findex describe-categories -@item \c@var{c} -matches any character that belongs to the category @var{c}. For -example, @samp{\cc} matches Chinese characters, @samp{\cg} matches -Greek characters, etc. For the description of the known categories, -type @kbd{M-x describe-categories @key{RET}}. - -@item \C@var{c} -matches any character that does @emph{not} belong to category -@var{c}. -@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. - -@example -"[.?!][]\"')]*\\($\\| $\\|\t\\| \\)[ \t\n]*" -@end example - -@noindent -This contains four parts in succession: a character set matching -period, @samp{?}, or @samp{!}; a character set matching -close-brackets, quotes, or parentheses, repeated zero or more times; a -set of alternatives within backslash-parentheses that matches either -end-of-line, a space at the end of a line, a tab, or two spaces; and a -character set matching whitespace characters, repeated any number of -times. - - To enter the same regexp in incremental search, you would type -@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 -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 - - An upper-case letter anywhere in the incremental 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. - - Typing @kbd{M-c} 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 including an upper-case letter in the current search. - -@vindex case-fold-search -@vindex default-case-fold-search - If you set the variable @code{case-fold-search} to @code{nil}, then -all letters must match exactly, including case. This is a per-buffer -variable; altering the variable affects only the current buffer, but -there is a default value in @code{default-case-fold-search} that you -can also set. @xref{Locals}. This variable applies to nonincremental -searches also, including those performed by the replace commands -(@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 -@cindex search-and-replace commands -@cindex string substitution -@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 -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}). - -@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. -@end menu - -@node Unconditional Replace, Regexp Replace, Replace, Replace -@subsection Unconditional Replacement -@findex replace-string - -@table @kbd -@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} -Replace every occurrence of @var{string} with @var{newstring}. -@end table - - To replace every instance of @samp{foo} after point with @samp{bar}, -use the command @kbd{M-x replace-string} with the two arguments -@samp{foo} and @samp{bar}. Replacement happens only in the text after -point, so if you want to cover the whole buffer you must go to the -beginning first. All occurrences up to the end of the buffer are -replaced; to limit replacement to part of the buffer, narrow to that -part of the buffer before doing the replacement (@pxref{Narrowing}). -In Transient Mark mode, when the region is active, replacement is -limited to the region (@pxref{Transient Mark}). - - When @code{replace-string} exits, it leaves point at the last -occurrence replaced. It sets the mark to the prior position of point -(where the @code{replace-string} command was issued); use @kbd{C-u -C-@key{SPC}} to move back there. - - A numeric argument restricts replacement to matches that are surrounded -by word boundaries. The argument's value doesn't matter. - - @xref{Replacement and Case}, for details about case-sensitivity in -replace commands. - - What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa? You can do it this way: - -@example -M-x replace-string @key{RET} x @key{RET} @@TEMP@@ @key{RET} -M-< M-x replace-string @key{RET} y @key{RET} x @key{RET} -M-< M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET} -@end example - -@noindent -This works provided the string @samp{@@TEMP@@} does not appear -in your text. - -@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace -@subsection Regexp Replacement -@findex replace-regexp - - The @kbd{M-x replace-string} command replaces exact matches for a -single string. The similar command @kbd{M-x replace-regexp} replaces -any match for a specified pattern. - -@table @kbd -@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} -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}. (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} -@end example - -@noindent -replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} -with @samp{cddr-safe}. - -@example -M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} -@end example - -@noindent -performs the inverse transformation. To include a @samp{\} in the -text to replace with, you must enter @samp{\\}. - - 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. - - The remainder of this subsection is intended for specialized tasks -and requires knowledge of Lisp. Most readers can skip it. - - You can 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 - -@node Replacement and Case, Query Replace, Regexp Replace, Replace -@subsection Replace Commands and Case - - If the first argument of a replace command is all lower case, the -command ignores case while searching for occurrences to -replace---provided @code{case-fold-search} is non-@code{nil}. If -@code{case-fold-search} is set to @code{nil}, case is always significant -in all searches. - -@vindex case-replace - In addition, when the @var{newstring} argument is all or partly lower -case, replacement commands try to preserve the case pattern of each -occurrence. Thus, the command - -@example -M-x replace-string @key{RET} foo @key{RET} bar @key{RET} -@end example - -@noindent -replaces a lower case @samp{foo} with a lower case @samp{bar}, an -all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with -@samp{Bar}. (These three alternatives---lower case, all caps, and -capitalized, are the only ones that @code{replace-string} can -distinguish.) - - If upper-case letters are used in the replacement string, they remain -upper case every time that text is inserted. If upper-case letters are -used in the first argument, the second argument is always substituted -exactly as given, with no case conversion. Likewise, if either -@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 -@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 - -@kindex M-% -@findex query-replace - If you want to change only some of the occurrences of @samp{foo} to -@samp{bar}, not all of them, then you cannot use an ordinary -@code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}). -This command finds occurrences of @samp{foo} one by one, displays each -occurrence and asks you whether to replace it. Aside from querying, -@code{query-replace} works just like @code{replace-string}. It -preserves case, like @code{replace-string}, provided -@code{case-replace} is non-@code{nil}, as it normally is -(@pxref{Replacement and Case}). A numeric argument means consider -only occurrences that are bounded by word-delimiter characters. - -@kindex C-M-% -@findex query-replace-regexp - @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). -It works like @code{replace-regexp} except that it queries -like @code{query-replace}. - -@cindex faces for highlighting query replace - 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}). - - The characters you can type when you are shown a match for the string -or regexp are: - -@ignore @c Not worth it. -@kindex SPC @r{(query-replace)} -@kindex DEL @r{(query-replace)} -@kindex , @r{(query-replace)} -@kindex RET @r{(query-replace)} -@kindex . @r{(query-replace)} -@kindex ! @r{(query-replace)} -@kindex ^ @r{(query-replace)} -@kindex C-r @r{(query-replace)} -@kindex C-w @r{(query-replace)} -@kindex C-l @r{(query-replace)} -@end ignore - -@c WideCommands -@table @kbd -@item @key{SPC} -to replace the occurrence with @var{newstring}. - -@item @key{DEL} -to skip to the next occurrence without replacing this one. - -@item , @r{(Comma)} -to replace this occurrence and display the result. You are then asked -for another input character to say what to do next. Since the -replacement has already been made, @key{DEL} and @key{SPC} are -equivalent in this situation; both move to the next occurrence. - -You can type @kbd{C-r} at this point (see below) to alter the replaced -text. You can also type @kbd{C-x u} to undo the replacement; this exits -the @code{query-replace}, so if you want to do further replacement you -must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart -(@pxref{Repetition}). - -@item @key{RET} -to exit without doing any more replacements. - -@item .@: @r{(Period)} -to replace this occurrence and then exit without searching for more -occurrences. - -@item ! -to replace all remaining occurrences without asking again. - -@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 -reexamine it. - -@item C-r -to enter a recursive editing level, in case the occurrence needs to be -edited rather than just replaced with @var{newstring}. When you are -done, exit the recursive editing level with @kbd{C-M-c} to proceed to -the next occurrence. @xref{Recursive Edit}. - -@item C-w -to delete the occurrence, and then enter a recursive editing level as in -@kbd{C-r}. Use the recursive edit to insert text to replace the deleted -occurrence of @var{string}. When done, exit the recursive editing level -with @kbd{C-M-c} to proceed to the next occurrence. - -@item e -to edit the replacement string in the minibuffer. When you exit the -minibuffer by typing @key{RET}, the minibuffer contents replace the -current occurrence of the pattern. They also become the new -replacement string for any further occurrences. - -@item C-l -to redisplay the screen. Then you must type another character to -specify what to do with this occurrence. - -@item C-h -to display a message summarizing these options. Then you must type -another character to specify what to do with this occurrence. -@end table - - Some other characters are aliases for the ones listed above: @kbd{y}, -@kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and -@key{RET}. - - Aside from this, any other character exits the @code{query-replace}, -and is then reread as part of a key sequence. Thus, if you type -@kbd{C-k}, it exits the @code{query-replace} and then kills to end of -line. - - To restart a @code{query-replace} once it is exited, use @kbd{C-x -@key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it -used the minibuffer to read its arguments. @xref{Repetition, C-x ESC -ESC}. - - @xref{Operating on Files}, for the Dired @kbd{Q} command which -performs query replace on selected files. See also @ref{Transforming -File Names}, for Dired commands to rename, copy, or link files by -replacing regexp matches in file names. - -@node Other Repeating Search -@section Other Search-and-Loop Commands - - Here are some other commands that find matches for a regular -expression. They all ignore case in matching, if the pattern contains -no upper-case letters and @code{case-fold-search} is non-@code{nil}. -Aside from @code{occur} and its variants, all operate on the text from -point to the end of the buffer, or on the active region in Transient -Mark mode. - -@findex list-matching-lines -@findex occur -@findex multi-occur -@findex multi-occur-in-matching-buffers -@findex how-many -@findex delete-non-matching-lines -@findex delete-matching-lines -@findex flush-lines -@findex keep-lines - -@table @kbd -@item M-x occur @key{RET} @var{regexp} @key{RET} -Display a list showing each line in the buffer that contains a match -for @var{regexp}. To limit the search to part of the buffer, narrow -to that part (@pxref{Narrowing}). A numeric argument @var{n} -specifies that @var{n} lines of context are to be displayed before and -after each matching line. Currently, @code{occur} can not correctly -handle multiline matches. - -@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}. - -@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. It asks you to specify the buffer names one by one. - -@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 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 -after point. In Transient Mark mode, if the region is active, the -command operates on the region instead. - -@item M-x flush-lines @key{RET} @var{regexp} @key{RET} -This command deletes each line that contains a match for @var{regexp}, -operating on the text after point; it deletes the current line -if it contains a match starting after point. In Transient Mark mode, -if the region is active, the command operates on the region instead; -it deletes a line partially contained in the region if it contains a -match entirely contained in the region. - -If a match is split across lines, @code{flush-lines} deletes all those -lines. It deletes the lines before starting to look for the next -match; hence, it ignores a match starting on the same line at which -another match ended. - -@item M-x keep-lines @key{RET} @var{regexp} @key{RET} -This command deletes each line that @emph{does not} contain a match for -@var{regexp}, operating on the text after point; if point is not at the -beginning of a line, it always keeps the current line. In Transient -Mark mode, if the region is active, the command operates on the region -instead; it never deletes lines that are only partially contained in -the region (a newline that ends a line counts as part of that line). - -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