Commit | Line | Data |
---|---|---|
8cf51b2c | 1 | @c This is part of the Emacs manual. |
ba318903 | 2 | @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software |
ab422c4d | 3 | @c Foundation, Inc. |
8cf51b2c | 4 | @c See file emacs.texi for copying conditions. |
abb9615e | 5 | @node Search |
8cf51b2c GM |
6 | @chapter Searching and Replacement |
7 | @cindex searching | |
8 | @cindex finding strings within text | |
9 | ||
b5fb9df5 CY |
10 | Like other editors, Emacs has commands to search for occurrences of |
11 | a string. Emacs also has commands to replace occurrences of a string | |
12 | with a different string. There are also commands that do the same | |
13 | thing, but search for patterns instead of fixed strings. | |
14 | ||
15 | You can also search multiple files under the control of a tags table | |
16 | (@pxref{Tags Search}) or through the Dired @kbd{A} command | |
8cf51b2c GM |
17 | (@pxref{Operating on Files}), or ask the @code{grep} program to do it |
18 | (@pxref{Grep Searching}). | |
19 | ||
8cf51b2c | 20 | @menu |
8838673e GM |
21 | * Incremental Search:: Search happens as you type the string. |
22 | * Nonincremental Search:: Specify entire string and then search. | |
23 | * Word Search:: Search for sequence of words. | |
05b621a6 | 24 | * Symbol Search:: Search for a source code symbol. |
8838673e GM |
25 | * Regexp Search:: Search for match for a regexp. |
26 | * Regexps:: Syntax of regular expressions. | |
27 | * Regexp Backslash:: Regular expression constructs starting with `\'. | |
28 | * Regexp Example:: A complex regular expression explained. | |
29 | * Search Case:: To ignore case while searching, or not. | |
30 | * Replace:: Search, and replace some or all matches. | |
31 | * Other Repeating Search:: Operating on all matches for some regexp. | |
8cf51b2c GM |
32 | @end menu |
33 | ||
34 | @node Incremental Search | |
35 | @section Incremental Search | |
36 | @cindex incremental search | |
37 | @cindex isearch | |
38 | ||
b5fb9df5 CY |
39 | The principal search command in Emacs is @dfn{incremental}: it |
40 | begins searching as soon as you type the first character of the search | |
41 | string. As you type in the search string, Emacs shows you where the | |
42 | string (as you have typed it so far) would be found. When you have | |
43 | typed enough characters to identify the place you want, you can stop. | |
44 | Depending on what you plan to do next, you may or may not need to | |
45 | terminate the search explicitly with @key{RET}. | |
8cf51b2c GM |
46 | |
47 | @table @kbd | |
48 | @item C-s | |
49 | Incremental search forward (@code{isearch-forward}). | |
50 | @item C-r | |
51 | Incremental search backward (@code{isearch-backward}). | |
52 | @end table | |
53 | ||
54 | @menu | |
80fa505f AM |
55 | * Basic Isearch:: Basic incremental search commands. |
56 | * Repeat Isearch:: Searching for the same string again. | |
57 | * Error in Isearch:: When your string is not found. | |
58 | * Special Isearch:: Special input in incremental search. | |
59 | * Isearch Yank:: Commands that grab text into the search string | |
60 | or else edit the search string. | |
61 | * Not Exiting Isearch:: Prefix argument and scrolling commands. | |
62 | * Isearch Minibuffer:: Incremental search of the minibuffer history. | |
8cf51b2c GM |
63 | @end menu |
64 | ||
65 | @node Basic Isearch | |
66 | @subsection Basics of Incremental Search | |
67 | ||
b5fb9df5 | 68 | @table @kbd |
97b3a00b | 69 | @item C-s |
b5fb9df5 CY |
70 | Begin incremental search (@code{isearch-forward}). |
71 | @item C-r | |
72 | Begin reverse incremental search (@code{isearch-backward}). | |
73 | @end table | |
74 | ||
8cf51b2c GM |
75 | @kindex C-s |
76 | @findex isearch-forward | |
b5fb9df5 CY |
77 | @kbd{C-s} (@code{isearch-forward}) starts a forward incremental |
78 | search. It reads characters from the keyboard, and moves point just | |
79 | past the end of the next occurrence of those characters in the buffer. | |
80 | ||
81 | For instance, if you type @kbd{C-s} and then @kbd{F}, that puts the | |
82 | cursor after the first @samp{F} that occurs in the buffer after the | |
83 | starting point. Then if you then type @kbd{O}, the cursor moves to | |
84 | just after the first @samp{FO}; the @samp{F} in that @samp{FO} might | |
85 | not be the first @samp{F} previously found. After another @kbd{O}, | |
86 | the cursor moves to just after the first @samp{FOO}. | |
87 | ||
88 | @cindex faces for highlighting search matches | |
89 | At each step, Emacs highlights the @dfn{current match}---the buffer | |
90 | text that matches the search string---using the @code{isearch} face | |
91 | (@pxref{Faces}). The current search string is also displayed in the | |
92 | echo area. | |
93 | ||
94 | If you make a mistake typing the search string, type @key{DEL}. | |
95 | Each @key{DEL} cancels the last character of the search string. | |
96 | ||
97 | When you are satisfied with the place you have reached, type | |
98 | @key{RET}. This stops searching, leaving the cursor where the search | |
8cf51b2c GM |
99 | brought it. Also, any command not specially meaningful in searches |
100 | stops the searching and is then executed. Thus, typing @kbd{C-a} | |
b5fb9df5 | 101 | exits the search and then moves to the beginning of the line. |
8cf51b2c GM |
102 | @key{RET} is necessary only if the next command you want to type is a |
103 | printing character, @key{DEL}, @key{RET}, or another character that is | |
104 | special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, | |
b5fb9df5 CY |
105 | @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some others |
106 | described below). | |
107 | ||
108 | As a special exception, entering @key{RET} when the search string is | |
109 | empty launches nonincremental search (@pxref{Nonincremental Search}). | |
8cf51b2c | 110 | |
6184c708 | 111 | When you exit the incremental search, it adds the original value of |
b5fb9df5 CY |
112 | point to the mark ring, without activating the mark; you can thus use |
113 | @kbd{C-u C-@key{SPC}} to return to where you were before beginning the | |
6184c708 CY |
114 | search. @xref{Mark Ring}. It only does this if the mark was not |
115 | already active. | |
8cf51b2c | 116 | |
b5fb9df5 CY |
117 | @kindex C-r |
118 | @findex isearch-backward | |
119 | To search backwards, use @kbd{C-r} (@code{isearch-backward}) instead | |
120 | of @kbd{C-s} to start the search. A backward search finds matches | |
121 | that end before the starting point, just as a forward search finds | |
122 | matches that begin after it. | |
123 | ||
8cf51b2c GM |
124 | @node Repeat Isearch |
125 | @subsection Repeating Incremental Search | |
126 | ||
b5fb9df5 CY |
127 | Suppose you search forward for @samp{FOO} and find a match, but not |
128 | the one you expected to find: the @samp{FOO} you were aiming for | |
129 | occurs later in the buffer. In this event, type another @kbd{C-s} to | |
130 | move to the next occurrence of the search string. You can repeat this | |
131 | any number of times. If you overshoot, you can cancel some @kbd{C-s} | |
132 | characters with @key{DEL}. Similarly, each @kbd{C-r} in a backward | |
133 | incremental search repeats the backward search. | |
134 | ||
135 | @cindex lazy search highlighting | |
136 | @vindex isearch-lazy-highlight | |
137 | If you pause for a little while during incremental search, Emacs | |
138 | highlights all the other possible matches for the search string that | |
139 | are present on the screen. This helps you anticipate where you can | |
140 | get to by typing @kbd{C-s} or @kbd{C-r} to repeat the search. The | |
141 | other matches are highlighted differently from the current match, | |
142 | using the customizable face @code{lazy-highlight} (@pxref{Faces}). If | |
143 | you don't like this feature, you can disable it by setting | |
144 | @code{isearch-lazy-highlight} to @code{nil}. | |
145 | ||
146 | After exiting a search, you can search for the same string again by | |
147 | typing just @kbd{C-s C-s}. The first @kbd{C-s} is the key that | |
148 | invokes incremental search, and the second @kbd{C-s} means ``search | |
16152b76 | 149 | again''. Similarly, @kbd{C-r C-r} searches backward for the last |
b5fb9df5 CY |
150 | search string. In determining the last search string, it doesn't |
151 | matter whether the string was searched for with @kbd{C-s} or | |
152 | @kbd{C-r}. | |
8cf51b2c | 153 | |
b5fb9df5 CY |
154 | If you are searching forward but you realize you were looking for |
155 | something before the starting point, type @kbd{C-r} to switch to a | |
156 | backward search, leaving the search string unchanged. Similarly, | |
157 | @kbd{C-s} in a backward search switches to a forward search. | |
8cf51b2c GM |
158 | |
159 | If a search is failing and you ask to repeat it by typing another | |
160 | @kbd{C-s}, it starts again from the beginning of the buffer. | |
161 | Repeating a failing reverse search with @kbd{C-r} starts again from | |
162 | the end. This is called @dfn{wrapping around}, and @samp{Wrapped} | |
163 | appears in the search prompt once this has happened. If you keep on | |
164 | going past the original starting point of the search, it changes to | |
165 | @samp{Overwrapped}, which means that you are revisiting matches that | |
166 | you have already seen. | |
167 | ||
b5fb9df5 | 168 | @cindex search ring |
5abc31ef CY |
169 | @kindex M-n @r{(Incremental search)} |
170 | @kindex M-p @r{(Incremental search)} | |
8cf51b2c | 171 | To reuse earlier search strings, use the @dfn{search ring}. The |
b5fb9df5 CY |
172 | commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a |
173 | search string to reuse. These commands leave the selected search ring | |
5abc31ef CY |
174 | element in the minibuffer, where you can edit it. |
175 | ||
176 | @kindex M-e @r{(Incremental search)} | |
177 | To edit the current search string in the minibuffer without | |
6d65486d | 178 | replacing it with items from the search ring, type @kbd{M-e}. Type @key{RET}, |
5abc31ef | 179 | @kbd{C-s} or @kbd{C-r} to finish editing the string and search for it. |
8cf51b2c GM |
180 | |
181 | @node Error in Isearch | |
182 | @subsection Errors in Incremental Search | |
183 | ||
184 | If your string is not found at all, the echo area says @samp{Failing | |
5abc31ef CY |
185 | I-Search}, and the cursor moves past the place where Emacs found as |
186 | much of your string as it could. Thus, if you search for @samp{FOOT}, | |
187 | and there is no @samp{FOOT}, you might see the cursor after the | |
188 | @samp{FOO} in @samp{FOOL}. In the echo area, the part of the search | |
189 | string that failed to match is highlighted using the face | |
b5fb9df5 CY |
190 | @code{isearch-fail}. |
191 | ||
192 | At this point, there are several things you can do. If your string | |
193 | was mistyped, you can use @key{DEL} to erase some of it and correct | |
194 | it. If you like the place you have found, you can type @key{RET} to | |
195 | remain there. Or you can type @kbd{C-g}, which removes from the | |
196 | search string the characters that could not be found (the @samp{T} in | |
197 | @samp{FOOT}), leaving those that were found (the @samp{FOO} in | |
8cf51b2c GM |
198 | @samp{FOOT}). A second @kbd{C-g} at that point cancels the search |
199 | entirely, returning point to where it was when the search started. | |
200 | ||
201 | @cindex quitting (in search) | |
5abc31ef | 202 | @kindex C-g @r{(Incremental search)} |
b5fb9df5 CY |
203 | The quit command, @kbd{C-g}, does special things during searches; |
204 | just what it does depends on the status of the search. If the search | |
205 | has found what you specified and is waiting for input, @kbd{C-g} | |
206 | cancels the entire search, moving the cursor back to where you started | |
207 | the search. If @kbd{C-g} is typed when there are characters in the | |
208 | search string that have not been found---because Emacs is still | |
209 | searching for them, or because it has failed to find them---then the | |
210 | search string characters which have not been found are discarded from | |
211 | the search string. With them gone, the search is now successful and | |
212 | waiting for more input, so a second @kbd{C-g} will cancel the entire | |
213 | search. | |
8cf51b2c GM |
214 | |
215 | @node Special Isearch | |
216 | @subsection Special Input for Incremental Search | |
217 | ||
b5fb9df5 CY |
218 | Some of the characters you type during incremental search have |
219 | special effects. | |
220 | ||
48de8b12 CY |
221 | @cindex lax space matching |
222 | @kindex M-s SPC @r{(Incremental search)} | |
223 | @kindex SPC @r{(Incremental search)} | |
224 | @findex isearch-toggle-lax-whitespace | |
225 | @vindex search-whitespace-regexp | |
226 | By default, incremental search performs @dfn{lax space matching}: | |
227 | each space, or sequence of spaces, matches any sequence of one or more | |
228 | spaces in the text. Hence, @samp{foo bar} matches @samp{foo bar}, | |
229 | @samp{foo bar}, @samp{foo bar}, and so on (but not @samp{foobar}). | |
230 | More precisely, Emacs matches each sequence of space characters in the | |
231 | search string to a regular expression specified by the variable | |
de7ce2d1 CY |
232 | @code{search-whitespace-regexp}. For example, to make spaces match |
233 | sequences of newlines as well as spaces, set it to | |
234 | @samp{"[[:space:]\n]+"}. | |
235 | ||
d7e9a7f8 | 236 | To toggle lax space matching, type @kbd{M-s @key{SPC}} |
48de8b12 CY |
237 | (@code{isearch-toggle-lax-whitespace}). To disable this feature |
238 | entirely, change @code{search-whitespace-regexp} to @code{nil}; then | |
de7ce2d1 | 239 | each space in the search string matches exactly one space. |
48de8b12 | 240 | |
b5fb9df5 CY |
241 | If the search string you entered contains only lower-case letters, |
242 | the search is case-insensitive; as long as an upper-case letter exists | |
243 | in the search string, the search becomes case-sensitive. If you | |
244 | delete the upper-case character from the search string, it ceases to | |
245 | have this effect. @xref{Search Case}. | |
246 | ||
4d49cc65 GM |
247 | @cindex invisible text, searching for |
248 | @kindex M-s i @r{(Incremental search)} | |
249 | @findex isearch-toggle-invisible | |
3242f74a GM |
250 | To toggle whether or not invisible text is searched, type |
251 | @kbd{M-s i} (@code{isearch-toggle-invisible}). @xref{Outline Search}. | |
4d49cc65 | 252 | |
b5fb9df5 CY |
253 | To search for a newline character, type @kbd{C-j}. |
254 | ||
de7ce2d1 CY |
255 | To search for non-@acronym{ASCII} characters, use one of the |
256 | following methods: | |
257 | ||
258 | @itemize @bullet | |
259 | @item | |
260 | Type @kbd{C-q}, followed by a non-graphic character or a sequence of | |
261 | octal digits. This adds a character to the search string, similar to | |
262 | inserting into a buffer using @kbd{C-q} (@pxref{Inserting Text}). For | |
263 | example, @kbd{C-q C-s} during incremental search adds the | |
d7e9a7f8 | 264 | @samp{control-S} character to the search string. |
de7ce2d1 CY |
265 | |
266 | @item | |
267 | Type @kbd{C-x 8 @key{RET}}, followed by a Unicode name or code-point. | |
268 | This adds the specified character into the search string, similar to | |
269 | the usual @code{insert-char} command (@pxref{Inserting Text}). | |
270 | ||
271 | @item | |
272 | Use an input method (@pxref{Input Methods}). If an input method is | |
273 | enabled in the current buffer when you start the search, you can use | |
274 | it in the search string also. While typing the search string, you can | |
275 | toggle the input method with @kbd{C-\} | |
276 | (@code{isearch-toggle-input-method}). You can also turn on a | |
277 | non-default input method with @kbd{C-^} | |
b5fb9df5 CY |
278 | (@code{isearch-toggle-specified-input-method}), which prompts for the |
279 | name of the input method. When an input method is active during | |
280 | incremental search, the search prompt includes the input method | |
281 | mnemonic, like this: | |
8cf51b2c GM |
282 | |
283 | @example | |
284 | I-search [@var{im}]: | |
285 | @end example | |
286 | ||
287 | @noindent | |
288 | @findex isearch-toggle-input-method | |
289 | @findex isearch-toggle-specified-input-method | |
b5fb9df5 CY |
290 | where @var{im} is the mnemonic of the active input method. Any input |
291 | method you enable during incremental search remains enabled in the | |
292 | current buffer afterwards. | |
de7ce2d1 | 293 | @end itemize |
8cf51b2c | 294 | |
9cfa31ea CY |
295 | @kindex M-% @r{(Incremental search)} |
296 | Typing @kbd{M-%} in incremental search invokes @code{query-replace} | |
b5fb9df5 | 297 | or @code{query-replace-regexp} (depending on search mode) with the |
57b837ab XF |
298 | current search string used as the string to replace. A negative |
299 | prefix argument means to replace backward. @xref{Query Replace}. | |
b5fb9df5 | 300 | |
9cfa31ea CY |
301 | @kindex M-TAB @r{(Incremental search)} |
302 | Typing @kbd{M-@key{TAB}} in incremental search invokes | |
303 | @code{isearch-complete}, which attempts to complete the search string | |
304 | using the search ring as a list of completion alternatives. | |
305 | @xref{Completion}. In many operating systems, the @kbd{M-@key{TAB}} | |
306 | key sequence is captured by the window manager; you then need to | |
307 | rebind @code{isearch-complete} to another key sequence if you want to | |
308 | use it (@pxref{Rebinding}). | |
309 | ||
b5fb9df5 CY |
310 | @vindex isearch-mode-map |
311 | When incremental search is active, you can type @kbd{C-h C-h} to | |
e7a3ff06 CY |
312 | access interactive help options, including a list of special key |
313 | bindings. These key bindings are part of the keymap | |
b5fb9df5 | 314 | @code{isearch-mode-map} (@pxref{Keymaps}). |
8cf51b2c GM |
315 | |
316 | @node Isearch Yank | |
317 | @subsection Isearch Yanking | |
318 | ||
5abc31ef CY |
319 | @kindex C-y @r{(Incremental search)} |
320 | @kindex M-y @r{(Incremental search)} | |
321 | @findex isearch-yank-kill | |
322 | @findex isearch-yank-pop | |
892777ba | 323 | Within incremental search, @kbd{C-y} (@code{isearch-yank-kill}) |
5abc31ef CY |
324 | appends the current kill to the search string. @kbd{M-y} |
325 | (@code{isearch-yank-pop}), if called after @kbd{C-y}, replaces that | |
326 | appended text with an earlier kill, similar to the usual @kbd{M-y} | |
327 | (@code{yank-pop}) command (@pxref{Yanking}). @kbd{Mouse-2} appends | |
328 | the current X selection (@pxref{Primary Selection}). | |
329 | ||
330 | @kindex C-w @r{(Incremental search)} | |
331 | @findex isearch-yank-word-or-char | |
332 | @kbd{C-w} (@code{isearch-yank-word-or-char}) appends the next | |
333 | character or word at point to the search string. This is an easy way | |
334 | to search for another occurrence of the text at point. (The decision | |
335 | of whether to copy a character or a word is heuristic.) | |
336 | ||
337 | @kindex M-s C-e @r{(Incremental search)} | |
338 | @findex isearch-yank-line | |
339 | Similarly, @kbd{M-s C-e} (@code{isearch-yank-line}) appends the rest | |
340 | of the current line to the search string. If point is already at the | |
de7ce2d1 CY |
341 | end of a line, it appends the next line. With a prefix argument |
342 | @var{n}, it appends the next @var{n} lines. | |
892777ba CY |
343 | |
344 | If the search is currently case-insensitive, both @kbd{C-w} and | |
345 | @kbd{M-s C-e} convert the text they copy to lower case, so that the | |
346 | search remains case-insensitive. | |
8cf51b2c | 347 | |
5abc31ef CY |
348 | @kindex C-M-w @r{(Incremental search)} |
349 | @kindex C-M-y @r{(Incremental search)} | |
350 | @findex isearch-del-char | |
351 | @findex isearch-yank-char | |
352 | @kbd{C-M-w} (@code{isearch-del-char}) deletes the last character | |
353 | from the search string, and @kbd{C-M-y} (@code{isearch-yank-char}) | |
58179cce | 354 | appends the character after point to the search string. An |
5abc31ef CY |
355 | alternative method to add the character after point is to enter the |
356 | minibuffer with @kbd{M-e} (@pxref{Repeat Isearch}) and type @kbd{C-f} | |
357 | at the end of the search string in the minibuffer. | |
8cf51b2c | 358 | |
80fa505f AM |
359 | @node Not Exiting Isearch |
360 | @subsection Not Exiting Incremental Search | |
8cf51b2c | 361 | |
80fa505f AM |
362 | This subsection describes two categories of commands which you can |
363 | type without exiting the current incremental search, even though they | |
364 | are not themselves part of incremental search. | |
365 | ||
366 | @table @asis | |
367 | @item Prefix Arguments | |
368 | @vindex isearch-allow-prefix | |
369 | In incremental search, when you enter a prefix argument | |
370 | (@pxref{Arguments}), by default it will apply either to the next | |
371 | action in the search or to the command that exits the search. | |
372 | ||
373 | In previous versions of Emacs, entering a prefix argument always | |
374 | terminated the search. You can revert to this behavior by setting the | |
375 | variable @code{isearch-allow-prefix} to @code{nil}. | |
376 | ||
377 | When @code{isearch-allow-scroll} is non-@code{nil} (see below), | |
378 | prefix arguments always have the default behavior described above. | |
379 | ||
380 | @item Scrolling Commands | |
40e67246 | 381 | @vindex isearch-allow-scroll |
5abc31ef CY |
382 | Normally, scrolling commands exit incremental search. If you change |
383 | the variable @code{isearch-allow-scroll} to a non-@code{nil} value, | |
384 | that enables the use of the scroll-bar, as well as keyboard scrolling | |
385 | commands like @kbd{C-v}, @kbd{M-v}, and @kbd{C-l} (@pxref{Scrolling}). | |
386 | This applies only to calling these commands via their bound key | |
387 | sequences---typing @kbd{M-x} will still exit the search. You can give | |
388 | prefix arguments to these commands in the usual way. This feature | |
389 | won't let you scroll the current match out of visibility, however. | |
390 | ||
391 | The @code{isearch-allow-scroll} feature also affects some other | |
291d142b CY |
392 | commands, such as @kbd{C-x 2} (@code{split-window-below}) and @kbd{C-x |
393 | ^} (@code{enlarge-window}), which don't exactly scroll but do affect | |
394 | where the text appears on the screen. It applies to any command whose | |
395 | name has a non-@code{nil} @code{isearch-scroll} property. So you can | |
396 | control which commands are affected by changing these properties. | |
8cf51b2c GM |
397 | |
398 | For example, to make @kbd{C-h l} usable within an incremental search | |
399 | in all future Emacs sessions, use @kbd{C-h c} to find what command it | |
5abc31ef CY |
400 | runs (@pxref{Key Help}), which is @code{view-lossage}. Then you can |
401 | put the following line in your init file (@pxref{Init File}): | |
8cf51b2c GM |
402 | |
403 | @example | |
404 | (put 'view-lossage 'isearch-scroll t) | |
405 | @end example | |
406 | ||
407 | @noindent | |
408 | This feature can be applied to any command that doesn't permanently | |
409 | change point, the buffer contents, the match data, the current buffer, | |
410 | or the selected window and frame. The command must not itself attempt | |
411 | an incremental search. | |
80fa505f | 412 | @end table |
8cf51b2c | 413 | |
b5fb9df5 CY |
414 | @node Isearch Minibuffer |
415 | @subsection Searching the Minibuffer | |
416 | @cindex minibuffer history, searching | |
417 | ||
418 | If you start an incremental search while the minibuffer is active, | |
419 | Emacs searches the contents of the minibuffer. Unlike searching an | |
420 | ordinary buffer, the search string is not shown in the echo area, | |
421 | because that is used to display the minibuffer. | |
422 | ||
423 | If an incremental search fails in the minibuffer, it tries searching | |
424 | the minibuffer history. @xref{Minibuffer History}. You can visualize | |
425 | the minibuffer and its history as a series of ``pages'', with the | |
426 | earliest history element on the first page and the current minibuffer | |
427 | on the last page. A forward search, @kbd{C-s}, searches forward to | |
428 | later pages; a reverse search, @kbd{C-r}, searches backwards to | |
429 | earlier pages. Like in ordinary buffer search, a failing search can | |
430 | wrap around, going from the last page to the first page or vice versa. | |
431 | ||
432 | When the current match is on a history element, that history element | |
433 | is pulled into the minibuffer. If you exit the incremental search | |
1df7defd | 434 | normally (e.g., by typing @key{RET}), it remains in the minibuffer |
bfd779dd | 435 | afterwards. Canceling the search, with @kbd{C-g}, restores the |
b5fb9df5 CY |
436 | contents of the minibuffer when you began the search. |
437 | ||
8cf51b2c GM |
438 | @node Nonincremental Search |
439 | @section Nonincremental Search | |
440 | @cindex nonincremental search | |
441 | ||
442 | Emacs also has conventional nonincremental search commands, which require | |
443 | you to type the entire search string before searching begins. | |
444 | ||
445 | @table @kbd | |
446 | @item C-s @key{RET} @var{string} @key{RET} | |
447 | Search for @var{string}. | |
448 | @item C-r @key{RET} @var{string} @key{RET} | |
449 | Search backward for @var{string}. | |
450 | @end table | |
451 | ||
b5fb9df5 CY |
452 | To start a nonincremental search, first type @kbd{C-s @key{RET}}. |
453 | This enters the minibuffer to read the search string; terminate the | |
454 | string with @key{RET}, and then the search takes place. If the string | |
455 | is not found, the search command signals an error. | |
8cf51b2c | 456 | |
8cf51b2c GM |
457 | @findex search-forward |
458 | @findex search-backward | |
5abc31ef CY |
459 | When you type @kbd{C-s @key{RET}}, the @kbd{C-s} invokes incremental |
460 | search as usual. That command is specially programmed to invoke the | |
461 | command for nonincremental search, @code{search-forward}, if the | |
462 | string you specify is empty. (Such an empty argument would otherwise | |
463 | be useless.) @kbd{C-r @key{RET}} does likewise, invoking the command | |
464 | @code{search-backward}. | |
8cf51b2c GM |
465 | |
466 | @node Word Search | |
467 | @section Word Search | |
468 | @cindex word search | |
469 | ||
b5fb9df5 CY |
470 | A @dfn{word search} finds a sequence of words without regard to the |
471 | type of punctuation between them. For instance, if you enter a search | |
472 | string that consists of two words separated by a single space, the | |
473 | search matches any sequence of those two words separated by one or | |
474 | more spaces, newlines, or other punctuation characters. This is | |
475 | particularly useful for searching text documents, because you don't | |
476 | have to worry whether the words you are looking for are separated by | |
477 | newlines or spaces. | |
8cf51b2c GM |
478 | |
479 | @table @kbd | |
b5fb9df5 CY |
480 | @item M-s w |
481 | If incremental search is active, toggle word search mode | |
482 | (@code{isearch-toggle-word}); otherwise, begin an incremental forward | |
483 | word search (@code{isearch-forward-word}). | |
97b3a00b JL |
484 | @item M-s w @key{RET} @var{words} @key{RET} |
485 | Search for @var{words}, using a forward nonincremental word search. | |
486 | @item M-s w C-r @key{RET} @var{words} @key{RET} | |
487 | Search backward for @var{words}, using a nonincremental word search. | |
8cf51b2c GM |
488 | @end table |
489 | ||
97b3a00b JL |
490 | @kindex M-s w |
491 | @findex isearch-forward-word | |
b5fb9df5 CY |
492 | To begin a forward incremental word search, type @kbd{M-s w}. If |
493 | incremental search is not already active, this runs the command | |
494 | @code{isearch-forward-word}. If incremental search is already active | |
495 | (whether a forward or backward search), @kbd{M-s w} switches to a word | |
496 | search while keeping the direction of the search and the current | |
497 | search string unchanged. You can toggle word search back off by | |
498 | typing @kbd{M-s w} again. | |
8cf51b2c GM |
499 | |
500 | @findex word-search-forward | |
501 | @findex word-search-backward | |
97b3a00b JL |
502 | To begin a nonincremental word search, type @kbd{M-s w @key{RET}} |
503 | for a forward search, or @kbd{M-s w C-r @key{RET}} for a backward search. | |
b5fb9df5 CY |
504 | These run the commands @code{word-search-forward} and |
505 | @code{word-search-backward} respectively. | |
506 | ||
2931c841 | 507 | Incremental and nonincremental word searches differ slightly in the |
de7ce2d1 CY |
508 | way they find a match. In a nonincremental word search, each word in |
509 | the search string must exactly match a whole word. In an incremental | |
510 | word search, the matching is more lax: while you are typing the search | |
511 | string, its first and last words need not match whole words. This is | |
512 | so that the matching can proceed incrementally as you type. This | |
513 | additional laxity does not apply to the lazy highlight, which always | |
514 | matches whole words. | |
8cf51b2c | 515 | |
05b621a6 CY |
516 | @node Symbol Search |
517 | @section Symbol Search | |
518 | @cindex symbol search | |
519 | ||
520 | A @dfn{symbol search} is much like an ordinary search, except that | |
521 | the boundaries of the search must match the boundaries of a symbol. | |
522 | The meaning of @dfn{symbol} in this context depends on the major mode, | |
523 | and usually refers to a source code token, such as a Lisp symbol in | |
524 | Emacs Lisp mode. For instance, if you perform an incremental symbol | |
525 | search for the Lisp symbol @code{forward-word}, it would not match | |
526 | @code{isearch-forward-word}. This feature is thus mainly useful for | |
527 | searching source code. | |
528 | ||
529 | @table @kbd | |
530 | @item M-s _ | |
531 | If incremental search is active, toggle symbol search mode | |
532 | (@code{isearch-toggle-symbol}); otherwise, begin an incremental | |
533 | forward symbol search (@code{isearch-forward-symbol}). | |
07e9eaa2 XF |
534 | @item M-s . |
535 | Start a symbol incremental search forward with the symbol found near | |
536 | point added to the search string initially. | |
05b621a6 CY |
537 | @item M-s _ @key{RET} @var{symbol} @key{RET} |
538 | Search forward for @var{symbol}, nonincrementally. | |
539 | @item M-s _ C-r @key{RET} @var{symbol} @key{RET} | |
540 | Search backward for @var{symbol}, nonincrementally. | |
541 | @end table | |
542 | ||
543 | @kindex M-s _ | |
07e9eaa2 | 544 | @kindex M-s . |
05b621a6 | 545 | @findex isearch-forward-symbol |
07e9eaa2 XF |
546 | @findex isearch-forward-symbol-at-point |
547 | To begin a forward incremental symbol search, type @kbd{M-s _} (or | |
548 | @kbd{M-s .} if the symbol to search is near point). If incremental | |
549 | search is not already active, this runs the command | |
05b621a6 CY |
550 | @code{isearch-forward-symbol}. If incremental search is already |
551 | active, @kbd{M-s _} switches to a symbol search, preserving the | |
552 | direction of the search and the current search string; you can disable | |
553 | symbol search by typing @kbd{M-s _} again. In incremental symbol | |
554 | search, only the beginning of the search string is required to match | |
555 | the beginning of a symbol. | |
556 | ||
557 | To begin a nonincremental symbol search, type @kbd{M-s _ @key{RET}} | |
558 | for a forward search, or @kbd{M-s _ C-r @key{RET}} or a backward | |
559 | search. In nonincremental symbol searches, the beginning and end of | |
560 | the search string are required to match the beginning and end of a | |
561 | symbol, respectively. | |
562 | ||
8cf51b2c GM |
563 | @node Regexp Search |
564 | @section Regular Expression Search | |
116b6d38 EZ |
565 | @cindex regexp search |
566 | @cindex search for a regular expression | |
8cf51b2c | 567 | |
b5fb9df5 | 568 | A @dfn{regular expression} (or @dfn{regexp} for short) is a pattern |
e2058813 | 569 | that denotes a class of alternative strings to match. Emacs |
b5fb9df5 CY |
570 | provides both incremental and nonincremental ways to search for a |
571 | match for a regexp. The syntax of regular expressions is explained in | |
5abc31ef | 572 | the next section. |
8cf51b2c | 573 | |
97b3a00b JL |
574 | @table @kbd |
575 | @item C-M-s | |
576 | Begin incremental regexp search (@code{isearch-forward-regexp}). | |
577 | @item C-M-r | |
578 | Begin reverse incremental regexp search (@code{isearch-backward-regexp}). | |
579 | @end table | |
580 | ||
8cf51b2c GM |
581 | @kindex C-M-s |
582 | @findex isearch-forward-regexp | |
583 | @kindex C-M-r | |
584 | @findex isearch-backward-regexp | |
585 | Incremental search for a regexp is done by typing @kbd{C-M-s} | |
586 | (@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a | |
587 | prefix argument (whose value does not matter), or by typing @kbd{M-r} | |
588 | within a forward incremental search. This command reads a | |
589 | search string incrementally just like @kbd{C-s}, but it treats the | |
590 | search string as a regexp rather than looking for an exact match | |
591 | against the text in the buffer. Each time you add text to the search | |
592 | string, you make the regexp longer, and the new regexp is searched | |
593 | for. To search backward for a regexp, use @kbd{C-M-r} | |
594 | (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, | |
595 | or @kbd{M-r} within a backward incremental search. | |
596 | ||
b5fb9df5 CY |
597 | All of the special key sequences in an ordinary incremental search |
598 | do similar things in an incremental regexp search. For instance, | |
599 | typing @kbd{C-s} immediately after starting the search retrieves the | |
600 | last incremental search regexp used and searches forward for it. | |
601 | Incremental regexp and non-regexp searches have independent defaults. | |
602 | They also have separate search rings, which you can access with | |
8cf51b2c GM |
603 | @kbd{M-p} and @kbd{M-n}. |
604 | ||
48de8b12 CY |
605 | Just as in ordinary incremental search, any @key{SPC} typed in |
606 | incremental regexp search matches any sequence of one or more | |
607 | whitespace characters. The variable @code{search-whitespace-regexp} | |
d7e9a7f8 | 608 | specifies the regexp for the lax space matching, and @kbd{M-s @key{SPC}} |
48de8b12 CY |
609 | (@code{isearch-toggle-lax-whitespace}) toggles the feature. |
610 | @xref{Special Isearch}. | |
8cf51b2c | 611 | |
b5fb9df5 CY |
612 | In some cases, adding characters to the regexp in an incremental |
613 | regexp search can make the cursor move back and start again. For | |
614 | example, if you have searched for @samp{foo} and you add @samp{\|bar}, | |
615 | the cursor backs up in case the first @samp{bar} precedes the first | |
616 | @samp{foo}. @xref{Regexps}. | |
8cf51b2c GM |
617 | |
618 | Forward and backward regexp search are not symmetrical, because | |
619 | regexp matching in Emacs always operates forward, starting with the | |
620 | beginning of the regexp. Thus, forward regexp search scans forward, | |
621 | trying a forward match at each possible starting position. Backward | |
622 | regexp search scans backward, trying a forward match at each possible | |
623 | starting position. These search methods are not mirror images. | |
624 | ||
625 | @findex re-search-forward | |
626 | @findex re-search-backward | |
5abc31ef | 627 | Nonincremental search for a regexp is done with the commands |
b5fb9df5 CY |
628 | @code{re-search-forward} and @code{re-search-backward}. You can |
629 | invoke these with @kbd{M-x}, or by way of incremental regexp search | |
630 | with @kbd{C-M-s @key{RET}} and @kbd{C-M-r @key{RET}}. | |
8cf51b2c GM |
631 | |
632 | If you use the incremental regexp search commands with a prefix | |
633 | argument, they perform ordinary string search, like | |
634 | @code{isearch-forward} and @code{isearch-backward}. @xref{Incremental | |
635 | Search}. | |
636 | ||
637 | @node Regexps | |
638 | @section Syntax of Regular Expressions | |
639 | @cindex syntax of regexps | |
116b6d38 EZ |
640 | @cindex regular expression |
641 | @cindex regexp | |
8cf51b2c GM |
642 | |
643 | This manual describes regular expression features that users | |
65401ee3 CY |
644 | typically use. @xref{Regular Expressions,,, elisp, The Emacs Lisp |
645 | Reference Manual}, for additional features used mainly in Lisp | |
646 | programs. | |
8cf51b2c GM |
647 | |
648 | Regular expressions have a syntax in which a few characters are | |
649 | special constructs and the rest are @dfn{ordinary}. An ordinary | |
65401ee3 CY |
650 | character matches that same character and nothing else. The special |
651 | characters are @samp{$^.*+?[\}. The character @samp{]} is special if | |
652 | it ends a character alternative (see later). The character @samp{-} | |
653 | is special inside a character alternative. Any other character | |
654 | appearing in a regular expression is ordinary, unless a @samp{\} | |
655 | precedes it. (When you use regular expressions in a Lisp program, | |
656 | each @samp{\} must be doubled, see the example near the end of this | |
657 | section.) | |
8cf51b2c GM |
658 | |
659 | For example, @samp{f} is not a special character, so it is ordinary, and | |
660 | therefore @samp{f} is a regular expression that matches the string | |
661 | @samp{f} and no other string. (It does @emph{not} match the string | |
662 | @samp{ff}.) Likewise, @samp{o} is a regular expression that matches | |
663 | only @samp{o}. (When case distinctions are being ignored, these regexps | |
664 | also match @samp{F} and @samp{O}, but we consider this a generalization | |
16152b76 | 665 | of ``the same string'', rather than an exception.) |
8cf51b2c | 666 | |
65401ee3 CY |
667 | Any two regular expressions @var{a} and @var{b} can be concatenated. |
668 | The result is a regular expression which matches a string if @var{a} | |
669 | matches some amount of the beginning of that string and @var{b} | |
670 | matches the rest of the string. For example, concatenating the | |
671 | regular expressions @samp{f} and @samp{o} gives the regular expression | |
672 | @samp{fo}, which matches only the string @samp{fo}. Still trivial. | |
673 | To do something nontrivial, you need to use one of the special | |
674 | characters. Here is a list of them. | |
8cf51b2c GM |
675 | |
676 | @table @asis | |
677 | @item @kbd{.}@: @r{(Period)} | |
65401ee3 CY |
678 | is a special character that matches any single character except a |
679 | newline. For example, the regular expressions @samp{a.b} matches any | |
680 | three-character string that begins with @samp{a} and ends with | |
681 | @samp{b}. | |
8cf51b2c GM |
682 | |
683 | @item @kbd{*} | |
684 | is not a construct by itself; it is a postfix operator that means to | |
65401ee3 CY |
685 | match the preceding regular expression repetitively any number of |
686 | times, as many times as possible. Thus, @samp{o*} matches any number | |
687 | of @samp{o}s, including no @samp{o}s. | |
8cf51b2c GM |
688 | |
689 | @samp{*} always applies to the @emph{smallest} possible preceding | |
690 | expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating | |
691 | @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on. | |
692 | ||
693 | The matcher processes a @samp{*} construct by matching, immediately, | |
694 | as many repetitions as can be found. Then it continues with the rest | |
695 | of the pattern. If that fails, backtracking occurs, discarding some | |
696 | of the matches of the @samp{*}-modified construct in case that makes | |
697 | it possible to match the rest of the pattern. For example, in matching | |
698 | @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first | |
699 | tries to match all three @samp{a}s; but the rest of the pattern is | |
700 | @samp{ar} and there is only @samp{r} left to match, so this try fails. | |
701 | The next alternative is for @samp{a*} to match only two @samp{a}s. | |
76f1a3c3 | 702 | With this choice, the rest of the regexp matches successfully. |
8cf51b2c GM |
703 | |
704 | @item @kbd{+} | |
705 | is a postfix operator, similar to @samp{*} except that it must match | |
65401ee3 CY |
706 | the preceding expression at least once. Thus, @samp{ca+r} matches the |
707 | strings @samp{car} and @samp{caaaar} but not the string @samp{cr}, | |
708 | whereas @samp{ca*r} matches all three strings. | |
8cf51b2c GM |
709 | |
710 | @item @kbd{?} | |
65401ee3 CY |
711 | is a postfix operator, similar to @samp{*} except that it can match |
712 | the preceding expression either once or not at all. Thus, @samp{ca?r} | |
713 | matches @samp{car} or @samp{cr}, and nothing else. | |
8cf51b2c GM |
714 | |
715 | @item @kbd{*?}, @kbd{+?}, @kbd{??} | |
716 | @cindex non-greedy regexp matching | |
65401ee3 CY |
717 | are non-@dfn{greedy} variants of the operators above. The normal |
718 | operators @samp{*}, @samp{+}, @samp{?} match as much as they can, as | |
719 | long as the overall regexp can still match. With a following | |
720 | @samp{?}, they will match as little as possible. | |
8cf51b2c GM |
721 | |
722 | Thus, both @samp{ab*} and @samp{ab*?} can match the string @samp{a} | |
723 | and the string @samp{abbbb}; but if you try to match them both against | |
724 | the text @samp{abbb}, @samp{ab*} will match it all (the longest valid | |
725 | match), while @samp{ab*?} will match just @samp{a} (the shortest | |
726 | valid match). | |
727 | ||
728 | Non-greedy operators match the shortest possible string starting at a | |
729 | given starting point; in a forward search, though, the earliest | |
730 | possible starting point for match is always the one chosen. Thus, if | |
731 | you search for @samp{a.*?$} against the text @samp{abbab} followed by | |
732 | a newline, it matches the whole string. Since it @emph{can} match | |
733 | starting at the first @samp{a}, it does. | |
734 | ||
735 | @item @kbd{\@{@var{n}\@}} | |
65401ee3 CY |
736 | is a postfix operator specifying @var{n} repetitions---that is, the |
737 | preceding regular expression must match exactly @var{n} times in a | |
738 | row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} and | |
739 | nothing else. | |
8cf51b2c GM |
740 | |
741 | @item @kbd{\@{@var{n},@var{m}\@}} | |
65401ee3 CY |
742 | is a postfix operator specifying between @var{n} and @var{m} |
743 | repetitions---that is, the preceding regular expression must match at | |
744 | least @var{n} times, but no more than @var{m} times. If @var{m} is | |
8cf51b2c GM |
745 | omitted, then there is no upper limit, but the preceding regular |
746 | expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is | |
747 | equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to | |
748 | @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. | |
749 | ||
750 | @item @kbd{[ @dots{} ]} | |
65401ee3 CY |
751 | is a @dfn{character set}, beginning with @samp{[} and terminated by |
752 | @samp{]}. | |
8cf51b2c | 753 | |
65401ee3 CY |
754 | In the simplest case, the characters between the two brackets are what |
755 | this set can match. Thus, @samp{[ad]} matches either one @samp{a} or | |
756 | one @samp{d}, and @samp{[ad]*} matches any string composed of just | |
757 | @samp{a}s and @samp{d}s (including the empty string). It follows that | |
758 | @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr}, | |
759 | @samp{caddaar}, etc. | |
8cf51b2c GM |
760 | |
761 | You can also include character ranges in a character set, by writing the | |
762 | starting and ending characters with a @samp{-} between them. Thus, | |
763 | @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be | |
764 | intermixed freely with individual characters, as in @samp{[a-z$%.]}, | |
765 | which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or | |
766 | period. | |
767 | ||
65401ee3 CY |
768 | You can also include certain special @dfn{character classes} in a |
769 | character set. A @samp{[:} and balancing @samp{:]} enclose a | |
770 | character class inside a character alternative. For instance, | |
771 | @samp{[[:alnum:]]} matches any letter or digit. @xref{Char Classes,,, | |
772 | elisp, The Emacs Lisp Reference Manual}, for a list of character | |
773 | classes. | |
8cf51b2c GM |
774 | |
775 | To include a @samp{]} in a character set, you must make it the first | |
776 | character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To | |
777 | include a @samp{-}, write @samp{-} as the first or last character of the | |
778 | set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]} | |
779 | and @samp{-}. | |
780 | ||
781 | To include @samp{^} in a set, put it anywhere but at the beginning of | |
782 | the set. (At the beginning, it complements the set---see below.) | |
783 | ||
784 | When you use a range in case-insensitive search, you should write both | |
785 | ends of the range in upper case, or both in lower case, or both should | |
786 | be non-letters. The behavior of a mixed-case range such as @samp{A-z} | |
787 | is somewhat ill-defined, and it may change in future Emacs versions. | |
788 | ||
789 | @item @kbd{[^ @dots{} ]} | |
790 | @samp{[^} begins a @dfn{complemented character set}, which matches any | |
791 | character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches | |
792 | all characters @emph{except} @acronym{ASCII} letters and digits. | |
793 | ||
794 | @samp{^} is not special in a character set unless it is the first | |
795 | character. The character following the @samp{^} is treated as if it | |
796 | were first (in other words, @samp{-} and @samp{]} are not special there). | |
797 | ||
798 | A complemented character set can match a newline, unless newline is | |
799 | mentioned as one of the characters not to match. This is in contrast to | |
800 | the handling of regexps in programs such as @code{grep}. | |
801 | ||
802 | @item @kbd{^} | |
803 | is a special character that matches the empty string, but only at the | |
804 | beginning of a line in the text being matched. Otherwise it fails to | |
805 | match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at | |
806 | the beginning of a line. | |
807 | ||
808 | For historical compatibility reasons, @samp{^} can be used with this | |
809 | meaning only at the beginning of the regular expression, or after | |
810 | @samp{\(} or @samp{\|}. | |
811 | ||
812 | @item @kbd{$} | |
813 | is similar to @samp{^} but matches only at the end of a line. Thus, | |
814 | @samp{x+$} matches a string of one @samp{x} or more at the end of a line. | |
815 | ||
816 | For historical compatibility reasons, @samp{$} can be used with this | |
817 | meaning only at the end of the regular expression, or before @samp{\)} | |
818 | or @samp{\|}. | |
819 | ||
820 | @item @kbd{\} | |
821 | has two functions: it quotes the special characters (including | |
822 | @samp{\}), and it introduces additional special constructs. | |
823 | ||
824 | Because @samp{\} quotes special characters, @samp{\$} is a regular | |
825 | expression that matches only @samp{$}, and @samp{\[} is a regular | |
826 | expression that matches only @samp{[}, and so on. | |
827 | ||
828 | See the following section for the special constructs that begin | |
829 | with @samp{\}. | |
830 | @end table | |
831 | ||
832 | Note: for historical compatibility, special characters are treated as | |
833 | ordinary ones if they are in contexts where their special meanings make no | |
834 | sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is | |
835 | no preceding expression on which the @samp{*} can act. It is poor practice | |
836 | to depend on this behavior; it is better to quote the special character anyway, | |
837 | regardless of where it appears. | |
838 | ||
839 | As a @samp{\} is not special inside a character alternative, it can | |
840 | never remove the special meaning of @samp{-} or @samp{]}. So you | |
841 | should not quote these characters when they have no special meaning | |
842 | either. This would not clarify anything, since backslashes can | |
843 | legitimately precede these characters where they @emph{have} special | |
844 | meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax), | |
845 | which matches any single character except a backslash. | |
846 | ||
847 | @node Regexp Backslash | |
848 | @section Backslash in Regular Expressions | |
849 | ||
850 | For the most part, @samp{\} followed by any character matches only | |
851 | that character. However, there are several exceptions: two-character | |
852 | sequences starting with @samp{\} that have special meanings. The | |
853 | second character in the sequence is always an ordinary character when | |
854 | used on its own. Here is a table of @samp{\} constructs. | |
855 | ||
856 | @table @kbd | |
857 | @item \| | |
858 | specifies an alternative. Two regular expressions @var{a} and @var{b} | |
859 | with @samp{\|} in between form an expression that matches some text if | |
860 | either @var{a} matches it or @var{b} matches it. It works by trying to | |
861 | match @var{a}, and if that fails, by trying to match @var{b}. | |
862 | ||
863 | Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} | |
76f1a3c3 | 864 | but no other string. |
8cf51b2c GM |
865 | |
866 | @samp{\|} applies to the largest possible surrounding expressions. Only a | |
867 | surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of | |
76f1a3c3 | 868 | @samp{\|}. |
8cf51b2c GM |
869 | |
870 | Full backtracking capability exists to handle multiple uses of @samp{\|}. | |
871 | ||
872 | @item \( @dots{} \) | |
873 | is a grouping construct that serves three purposes: | |
874 | ||
875 | @enumerate | |
876 | @item | |
877 | To enclose a set of @samp{\|} alternatives for other operations. | |
878 | Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. | |
879 | ||
880 | @item | |
881 | To enclose a complicated expression for the postfix operators @samp{*}, | |
882 | @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches | |
883 | @samp{bananana}, etc., with any (zero or more) number of @samp{na} | |
76f1a3c3 | 884 | strings. |
8cf51b2c GM |
885 | |
886 | @item | |
887 | To record a matched substring for future reference. | |
888 | @end enumerate | |
889 | ||
890 | This last application is not a consequence of the idea of a | |
891 | parenthetical grouping; it is a separate feature that is assigned as a | |
892 | second meaning to the same @samp{\( @dots{} \)} construct. In practice | |
893 | there is usually no conflict between the two meanings; when there is | |
894 | a conflict, you can use a ``shy'' group. | |
895 | ||
896 | @item \(?: @dots{} \) | |
897 | @cindex shy group, in regexp | |
898 | specifies a ``shy'' group that does not record the matched substring; | |
899 | you can't refer back to it with @samp{\@var{d}}. This is useful | |
900 | in mechanically combining regular expressions, so that you | |
901 | can add groups for syntactic purposes without interfering with | |
902 | the numbering of the groups that are meant to be referred to. | |
903 | ||
904 | @item \@var{d} | |
905 | @cindex back reference, in regexp | |
906 | matches the same text that matched the @var{d}th occurrence of a | |
907 | @samp{\( @dots{} \)} construct. This is called a @dfn{back | |
908 | reference}. | |
909 | ||
910 | After the end of a @samp{\( @dots{} \)} construct, the matcher remembers | |
911 | the beginning and end of the text matched by that construct. Then, | |
912 | later on in the regular expression, you can use @samp{\} followed by the | |
913 | digit @var{d} to mean ``match the same text matched the @var{d}th time | |
16152b76 | 914 | by the @samp{\( @dots{} \)} construct''. |
8cf51b2c GM |
915 | |
916 | The strings matching the first nine @samp{\( @dots{} \)} constructs | |
917 | appearing in a regular expression are assigned numbers 1 through 9 in | |
918 | the order that the open-parentheses appear in the regular expression. | |
919 | So you can use @samp{\1} through @samp{\9} to refer to the text matched | |
920 | by the corresponding @samp{\( @dots{} \)} constructs. | |
921 | ||
922 | For example, @samp{\(.*\)\1} matches any newline-free string that is | |
923 | composed of two identical halves. The @samp{\(.*\)} matches the first | |
924 | half, which may be anything, but the @samp{\1} that follows must match | |
925 | the same exact text. | |
926 | ||
927 | If a particular @samp{\( @dots{} \)} construct matches more than once | |
928 | (which can easily happen if it is followed by @samp{*}), only the last | |
929 | match is recorded. | |
930 | ||
931 | @item \` | |
932 | matches the empty string, but only at the beginning of the string or | |
933 | buffer (or its accessible portion) being matched against. | |
934 | ||
935 | @item \' | |
936 | matches the empty string, but only at the end of the string or buffer | |
937 | (or its accessible portion) being matched against. | |
938 | ||
939 | @item \= | |
940 | matches the empty string, but only at point. | |
941 | ||
942 | @item \b | |
943 | matches the empty string, but only at the beginning or | |
944 | end of a word. Thus, @samp{\bfoo\b} matches any occurrence of | |
945 | @samp{foo} as a separate word. @samp{\bballs?\b} matches | |
76f1a3c3 | 946 | @samp{ball} or @samp{balls} as a separate word. |
8cf51b2c GM |
947 | |
948 | @samp{\b} matches at the beginning or end of the buffer | |
949 | regardless of what text appears next to it. | |
950 | ||
951 | @item \B | |
952 | matches the empty string, but @emph{not} at the beginning or | |
953 | end of a word. | |
954 | ||
955 | @item \< | |
956 | matches the empty string, but only at the beginning of a word. | |
957 | @samp{\<} matches at the beginning of the buffer only if a | |
958 | word-constituent character follows. | |
959 | ||
960 | @item \> | |
961 | matches the empty string, but only at the end of a word. @samp{\>} | |
962 | matches at the end of the buffer only if the contents end with a | |
963 | word-constituent character. | |
964 | ||
965 | @item \w | |
6cfd0fa2 CY |
966 | matches any word-constituent character. The syntax table determines |
967 | which characters these are. @xref{Syntax Tables,, Syntax Tables, | |
968 | elisp, The Emacs Lisp Reference Manual}. | |
8cf51b2c GM |
969 | |
970 | @item \W | |
971 | matches any character that is not a word-constituent. | |
972 | ||
973 | @item \_< | |
974 | matches the empty string, but only at the beginning of a symbol. | |
975 | A symbol is a sequence of one or more symbol-constituent characters. | |
976 | A symbol-constituent character is a character whose syntax is either | |
977 | @samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the | |
978 | buffer only if a symbol-constituent character follows. | |
979 | ||
980 | @item \_> | |
981 | matches the empty string, but only at the end of a symbol. @samp{\_>} | |
982 | matches at the end of the buffer only if the contents end with a | |
983 | symbol-constituent character. | |
984 | ||
985 | @item \s@var{c} | |
986 | matches any character whose syntax is @var{c}. Here @var{c} is a | |
987 | character that designates a particular syntax class: thus, @samp{w} | |
988 | for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} | |
6cfd0fa2 CY |
989 | for ordinary punctuation, etc. @xref{Syntax Tables,, Syntax Tables, |
990 | elisp, The Emacs Lisp Reference Manual}. | |
8cf51b2c GM |
991 | |
992 | @item \S@var{c} | |
993 | matches any character whose syntax is not @var{c}. | |
994 | ||
995 | @cindex categories of characters | |
996 | @cindex characters which belong to a specific language | |
997 | @findex describe-categories | |
998 | @item \c@var{c} | |
999 | matches any character that belongs to the category @var{c}. For | |
1000 | example, @samp{\cc} matches Chinese characters, @samp{\cg} matches | |
1001 | Greek characters, etc. For the description of the known categories, | |
1002 | type @kbd{M-x describe-categories @key{RET}}. | |
1003 | ||
1004 | @item \C@var{c} | |
1005 | matches any character that does @emph{not} belong to category | |
1006 | @var{c}. | |
1007 | @end table | |
1008 | ||
6cfd0fa2 CY |
1009 | The constructs that pertain to words and syntax are controlled by |
1010 | the setting of the syntax table. @xref{Syntax Tables,, Syntax Tables, | |
1011 | elisp, The Emacs Lisp Reference Manual}. | |
8cf51b2c GM |
1012 | |
1013 | @node Regexp Example | |
1014 | @section Regular Expression Example | |
1015 | ||
62d94509 EZ |
1016 | Here is an example of a regexp---similar to the regexp that Emacs |
1017 | uses, by default, to recognize the end of a sentence, not including | |
1018 | the following space (i.e., the variable @code{sentence-end-base}): | |
8cf51b2c GM |
1019 | |
1020 | @example | |
b5fb9df5 | 1021 | @verbatim |
62d94509 | 1022 | [.?!][]\"')}]* |
b5fb9df5 | 1023 | @end verbatim |
8cf51b2c GM |
1024 | @end example |
1025 | ||
1026 | @noindent | |
b5fb9df5 CY |
1027 | This contains two parts in succession: a character set matching |
1028 | period, @samp{?}, or @samp{!}, and a character set matching | |
1029 | close-brackets, quotes, or parentheses, repeated zero or more times. | |
8cf51b2c GM |
1030 | |
1031 | @node Search Case | |
1032 | @section Searching and Case | |
1033 | ||
b5fb9df5 CY |
1034 | Searches in Emacs normally ignore the case of the text they are |
1035 | searching through, if you specify the text in lower case. Thus, if | |
1036 | you specify searching for @samp{foo}, then @samp{Foo} and @samp{foo} | |
5abc31ef CY |
1037 | also match. Regexps, and in particular character sets, behave |
1038 | likewise: @samp{[ab]} matches @samp{a} or @samp{A} or @samp{b} or | |
76f1a3c3 | 1039 | @samp{B}. |
8cf51b2c GM |
1040 | |
1041 | An upper-case letter anywhere in the incremental search string makes | |
1042 | the search case-sensitive. Thus, searching for @samp{Foo} does not find | |
1043 | @samp{foo} or @samp{FOO}. This applies to regular expression search as | |
1044 | well as to string search. The effect ceases if you delete the | |
1045 | upper-case letter from the search string. | |
1046 | ||
8cf51b2c | 1047 | @vindex case-fold-search |
8cf51b2c GM |
1048 | If you set the variable @code{case-fold-search} to @code{nil}, then |
1049 | all letters must match exactly, including case. This is a per-buffer | |
4e3b4528 SM |
1050 | variable; altering the variable normally affects only the current buffer, |
1051 | unless you change its default value. @xref{Locals}. | |
1052 | This variable applies to nonincremental searches also, including those | |
1053 | performed by the replace commands (@pxref{Replace}) and the minibuffer | |
1054 | history matching commands (@pxref{Minibuffer History}). | |
8cf51b2c | 1055 | |
4d49cc65 | 1056 | @c isearch-toggle-case-fold |
74750d55 LI |
1057 | Typing @kbd{M-c} within an incremental search toggles the case |
1058 | sensitivity of that search. The effect does not extend beyond the | |
1059 | current incremental search to the next one, but it does override the | |
1060 | effect of adding or removing an upper-case letter in the current | |
1061 | search. | |
1062 | ||
8cf51b2c GM |
1063 | Several related variables control case-sensitivity of searching and |
1064 | matching for specific commands or activities. For instance, | |
1065 | @code{tags-case-fold-search} controls case sensitivity for | |
1066 | @code{find-tag}. To find these variables, do @kbd{M-x | |
1067 | apropos-variable @key{RET} case-fold-search @key{RET}}. | |
1068 | ||
1069 | @node Replace | |
1070 | @section Replacement Commands | |
1071 | @cindex replacement | |
1072 | @cindex search-and-replace commands | |
1073 | @cindex string substitution | |
1074 | @cindex global substitution | |
1075 | ||
b5fb9df5 CY |
1076 | Emacs provides several commands for performing search-and-replace |
1077 | operations. In addition to the simple @kbd{M-x replace-string} | |
1078 | command, there is @kbd{M-%} (@code{query-replace}), which presents | |
1079 | each occurrence of the pattern and asks you whether to replace it. | |
8cf51b2c GM |
1080 | |
1081 | The replace commands normally operate on the text from point to the | |
5abc31ef CY |
1082 | end of the buffer. When the region is active, they operate on it |
1083 | instead (@pxref{Mark}). The basic replace commands replace one | |
b5fb9df5 CY |
1084 | @dfn{search string} (or regexp) with one @dfn{replacement string}. It |
1085 | is possible to perform several replacements in parallel, using the | |
1086 | command @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}). | |
8cf51b2c | 1087 | |
48de8b12 CY |
1088 | @vindex replace-lax-whitespace |
1089 | Unlike incremental search, the replacement commands do not use lax | |
1090 | space matching (@pxref{Special Isearch}) by default. To enable lax | |
1091 | space matching for replacement, change the variable | |
1092 | @code{replace-lax-whitespace} to @code{t}. (This only affects how | |
1093 | Emacs finds the text to replace, not the replacement text.) | |
1094 | ||
8cf51b2c | 1095 | @menu |
8838673e GM |
1096 | * Unconditional Replace:: Replacing all matches for a string. |
1097 | * Regexp Replace:: Replacing all matches for a regexp. | |
1098 | * Replacement and Case:: How replacements preserve case of letters. | |
1099 | * Query Replace:: How to use querying. | |
8cf51b2c GM |
1100 | @end menu |
1101 | ||
abb9615e | 1102 | @node Unconditional Replace |
8cf51b2c GM |
1103 | @subsection Unconditional Replacement |
1104 | @findex replace-string | |
1105 | ||
1106 | @table @kbd | |
1107 | @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} | |
1108 | Replace every occurrence of @var{string} with @var{newstring}. | |
1109 | @end table | |
1110 | ||
1111 | To replace every instance of @samp{foo} after point with @samp{bar}, | |
1112 | use the command @kbd{M-x replace-string} with the two arguments | |
1113 | @samp{foo} and @samp{bar}. Replacement happens only in the text after | |
1114 | point, so if you want to cover the whole buffer you must go to the | |
1115 | beginning first. All occurrences up to the end of the buffer are | |
b5fb9df5 CY |
1116 | replaced; to limit replacement to part of the buffer, activate the |
1117 | region around that part. When the region is active, replacement is | |
1118 | limited to the region (@pxref{Mark}). | |
8cf51b2c GM |
1119 | |
1120 | When @code{replace-string} exits, it leaves point at the last | |
6184c708 CY |
1121 | occurrence replaced. It adds the prior position of point (where the |
1122 | @code{replace-string} command was issued) to the mark ring, without | |
1123 | activating the mark; use @kbd{C-u C-@key{SPC}} to move back there. | |
1124 | @xref{Mark Ring}. | |
8cf51b2c | 1125 | |
b5fb9df5 | 1126 | A prefix argument restricts replacement to matches that are |
5abc31ef | 1127 | surrounded by word boundaries. |
8cf51b2c GM |
1128 | |
1129 | @xref{Replacement and Case}, for details about case-sensitivity in | |
1130 | replace commands. | |
1131 | ||
abb9615e | 1132 | @node Regexp Replace |
8cf51b2c GM |
1133 | @subsection Regexp Replacement |
1134 | @findex replace-regexp | |
1135 | ||
1136 | The @kbd{M-x replace-string} command replaces exact matches for a | |
1137 | single string. The similar command @kbd{M-x replace-regexp} replaces | |
1138 | any match for a specified pattern. | |
1139 | ||
1140 | @table @kbd | |
1141 | @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} | |
1142 | Replace every match for @var{regexp} with @var{newstring}. | |
1143 | @end table | |
1144 | ||
1145 | @cindex back reference, in regexp replacement | |
1146 | In @code{replace-regexp}, the @var{newstring} need not be constant: | |
1147 | it can refer to all or part of what is matched by the @var{regexp}. | |
1148 | @samp{\&} in @var{newstring} stands for the entire match being | |
1149 | replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a | |
1150 | digit, stands for whatever matched the @var{d}th parenthesized | |
16152b76 | 1151 | grouping in @var{regexp}. (This is called a ``back reference''.) |
8cf51b2c GM |
1152 | @samp{\#} refers to the count of replacements already made in this |
1153 | command, as a decimal number. In the first replacement, @samp{\#} | |
1154 | stands for @samp{0}; in the second, for @samp{1}; and so on. For | |
1155 | example, | |
1156 | ||
1157 | @example | |
1158 | M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} | |
1159 | @end example | |
1160 | ||
1161 | @noindent | |
1162 | replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} | |
1163 | with @samp{cddr-safe}. | |
1164 | ||
1165 | @example | |
1166 | M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} | |
1167 | @end example | |
1168 | ||
1169 | @noindent | |
1170 | performs the inverse transformation. To include a @samp{\} in the | |
1171 | text to replace with, you must enter @samp{\\}. | |
1172 | ||
1173 | If you want to enter part of the replacement string by hand each | |
1174 | time, use @samp{\?} in the replacement string. Each replacement will | |
1175 | ask you to edit the replacement string in the minibuffer, putting | |
1176 | point where the @samp{\?} was. | |
1177 | ||
1178 | The remainder of this subsection is intended for specialized tasks | |
1179 | and requires knowledge of Lisp. Most readers can skip it. | |
1180 | ||
1181 | You can use Lisp expressions to calculate parts of the | |
1182 | replacement string. To do this, write @samp{\,} followed by the | |
1183 | expression in the replacement string. Each replacement calculates the | |
1184 | value of the expression and converts it to text without quoting (if | |
1185 | it's a string, this means using the string's contents), and uses it in | |
1186 | the replacement string in place of the expression itself. If the | |
1187 | expression is a symbol, one space in the replacement string after the | |
1188 | symbol name goes with the symbol name, so the value replaces them | |
1189 | both. | |
1190 | ||
1191 | Inside such an expression, you can use some special sequences. | |
1192 | @samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire | |
1193 | match as a string, and to a submatch as a string. @var{n} may be | |
1194 | multiple digits, and the value of @samp{\@var{n}} is @code{nil} if | |
1195 | subexpression @var{n} did not match. You can also use @samp{\#&} and | |
1196 | @samp{\#@var{n}} to refer to those matches as numbers (this is valid | |
1197 | when the match or submatch has the form of a numeral). @samp{\#} here | |
1198 | too stands for the number of already-completed replacements. | |
1199 | ||
1200 | Repeating our example to exchange @samp{x} and @samp{y}, we can thus | |
1201 | do it also this way: | |
1202 | ||
1203 | @example | |
1204 | M-x replace-regexp @key{RET} \(x\)\|y @key{RET} | |
1205 | \,(if \1 "y" "x") @key{RET} | |
1206 | @end example | |
1207 | ||
1208 | For computing replacement strings for @samp{\,}, the @code{format} | |
1209 | function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs | |
1210 | Lisp Reference Manual}). For example, to add consecutively numbered | |
1211 | strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are | |
1212 | already occupied), you can use | |
1213 | ||
1214 | @example | |
1215 | M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} | |
1216 | \,(format "%-72sABC%05d" \& \#) @key{RET} | |
1217 | @end example | |
1218 | ||
abb9615e | 1219 | @node Replacement and Case |
8cf51b2c GM |
1220 | @subsection Replace Commands and Case |
1221 | ||
1222 | If the first argument of a replace command is all lower case, the | |
1223 | command ignores case while searching for occurrences to | |
1224 | replace---provided @code{case-fold-search} is non-@code{nil}. If | |
1225 | @code{case-fold-search} is set to @code{nil}, case is always significant | |
1226 | in all searches. | |
1227 | ||
1228 | @vindex case-replace | |
1229 | In addition, when the @var{newstring} argument is all or partly lower | |
1230 | case, replacement commands try to preserve the case pattern of each | |
1231 | occurrence. Thus, the command | |
1232 | ||
1233 | @example | |
1234 | M-x replace-string @key{RET} foo @key{RET} bar @key{RET} | |
1235 | @end example | |
1236 | ||
1237 | @noindent | |
1238 | replaces a lower case @samp{foo} with a lower case @samp{bar}, an | |
1239 | all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with | |
1240 | @samp{Bar}. (These three alternatives---lower case, all caps, and | |
1241 | capitalized, are the only ones that @code{replace-string} can | |
1242 | distinguish.) | |
1243 | ||
1244 | If upper-case letters are used in the replacement string, they remain | |
1245 | upper case every time that text is inserted. If upper-case letters are | |
1246 | used in the first argument, the second argument is always substituted | |
1247 | exactly as given, with no case conversion. Likewise, if either | |
1248 | @code{case-replace} or @code{case-fold-search} is set to @code{nil}, | |
1249 | replacement is done without case conversion. | |
1250 | ||
abb9615e | 1251 | @node Query Replace |
8cf51b2c GM |
1252 | @subsection Query Replace |
1253 | @cindex query replace | |
1254 | ||
1255 | @table @kbd | |
1256 | @item M-% @var{string} @key{RET} @var{newstring} @key{RET} | |
8cf51b2c GM |
1257 | Replace some occurrences of @var{string} with @var{newstring}. |
1258 | @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET} | |
8cf51b2c GM |
1259 | Replace some matches for @var{regexp} with @var{newstring}. |
1260 | @end table | |
1261 | ||
1262 | @kindex M-% | |
1263 | @findex query-replace | |
1264 | If you want to change only some of the occurrences of @samp{foo} to | |
abfd0191 | 1265 | @samp{bar}, not all of them, use @kbd{M-%} (@code{query-replace}). |
8cf51b2c GM |
1266 | This command finds occurrences of @samp{foo} one by one, displays each |
1267 | occurrence and asks you whether to replace it. Aside from querying, | |
abfd0191 RS |
1268 | @code{query-replace} works just like @code{replace-string} |
1269 | (@pxref{Unconditional Replace}). In particular, it preserves case | |
1270 | provided @code{case-replace} is non-@code{nil}, as it normally is | |
5abc31ef | 1271 | (@pxref{Replacement and Case}). A numeric argument means to consider |
57b837ab XF |
1272 | only occurrences that are bounded by word-delimiter characters. A |
1273 | negative prefix argument replaces backward. | |
8cf51b2c GM |
1274 | |
1275 | @kindex C-M-% | |
1276 | @findex query-replace-regexp | |
1277 | @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). | |
1278 | It works like @code{replace-regexp} except that it queries | |
1279 | like @code{query-replace}. | |
1280 | ||
1281 | @cindex faces for highlighting query replace | |
1282 | These commands highlight the current match using the face | |
1283 | @code{query-replace}. They highlight other matches using | |
1284 | @code{lazy-highlight} just like incremental search (@pxref{Incremental | |
5abc31ef | 1285 | Search}). By default, @code{query-replace-regexp} will show the |
21d50ba1 JL |
1286 | substituted replacement string for the current match in the |
1287 | minibuffer. If you want to keep special sequences @samp{\&} and | |
1288 | @samp{\@var{n}} unexpanded, customize | |
1289 | @code{query-replace-show-replacement} variable. | |
8cf51b2c GM |
1290 | |
1291 | The characters you can type when you are shown a match for the string | |
1292 | or regexp are: | |
1293 | ||
1294 | @ignore @c Not worth it. | |
1295 | @kindex SPC @r{(query-replace)} | |
1296 | @kindex DEL @r{(query-replace)} | |
1297 | @kindex , @r{(query-replace)} | |
1298 | @kindex RET @r{(query-replace)} | |
1299 | @kindex . @r{(query-replace)} | |
1300 | @kindex ! @r{(query-replace)} | |
1301 | @kindex ^ @r{(query-replace)} | |
1302 | @kindex C-r @r{(query-replace)} | |
1303 | @kindex C-w @r{(query-replace)} | |
1304 | @kindex C-l @r{(query-replace)} | |
1305 | @end ignore | |
1306 | ||
1307 | @c WideCommands | |
1308 | @table @kbd | |
1309 | @item @key{SPC} | |
1310 | to replace the occurrence with @var{newstring}. | |
1311 | ||
1312 | @item @key{DEL} | |
1313 | to skip to the next occurrence without replacing this one. | |
1314 | ||
1315 | @item , @r{(Comma)} | |
1316 | to replace this occurrence and display the result. You are then asked | |
1317 | for another input character to say what to do next. Since the | |
1318 | replacement has already been made, @key{DEL} and @key{SPC} are | |
1319 | equivalent in this situation; both move to the next occurrence. | |
1320 | ||
1321 | You can type @kbd{C-r} at this point (see below) to alter the replaced | |
1322 | text. You can also type @kbd{C-x u} to undo the replacement; this exits | |
1323 | the @code{query-replace}, so if you want to do further replacement you | |
1324 | must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart | |
1325 | (@pxref{Repetition}). | |
1326 | ||
1327 | @item @key{RET} | |
1328 | to exit without doing any more replacements. | |
1329 | ||
1330 | @item .@: @r{(Period)} | |
1331 | to replace this occurrence and then exit without searching for more | |
1332 | occurrences. | |
1333 | ||
1334 | @item ! | |
1335 | to replace all remaining occurrences without asking again. | |
1336 | ||
e5a94ec4 JL |
1337 | @item Y @r{(Upper-case)} |
1338 | to replace all remaining occurrences in all remaining buffers in | |
1339 | multi-buffer replacements (like the Dired `Q' command which performs | |
1340 | query replace on selected files). It answers this question and all | |
1341 | subsequent questions in the series with "yes", without further | |
1342 | user interaction. | |
1343 | ||
1344 | @item N @r{(Upper-case)} | |
1345 | to skip to the next buffer in multi-buffer replacements without | |
1346 | replacing remaining occurrences in the current buffer. It answers | |
1347 | this question "no", gives up on the questions for the current buffer, | |
1348 | and continues to the next buffer in the sequence. | |
1349 | ||
8cf51b2c GM |
1350 | @item ^ |
1351 | to go back to the position of the previous occurrence (or what used to | |
1352 | be an occurrence), in case you changed it by mistake or want to | |
1353 | reexamine it. | |
1354 | ||
1355 | @item C-r | |
1356 | to enter a recursive editing level, in case the occurrence needs to be | |
1357 | edited rather than just replaced with @var{newstring}. When you are | |
1358 | done, exit the recursive editing level with @kbd{C-M-c} to proceed to | |
1359 | the next occurrence. @xref{Recursive Edit}. | |
1360 | ||
1361 | @item C-w | |
1362 | to delete the occurrence, and then enter a recursive editing level as in | |
1363 | @kbd{C-r}. Use the recursive edit to insert text to replace the deleted | |
1364 | occurrence of @var{string}. When done, exit the recursive editing level | |
1365 | with @kbd{C-M-c} to proceed to the next occurrence. | |
1366 | ||
1367 | @item e | |
1368 | to edit the replacement string in the minibuffer. When you exit the | |
1369 | minibuffer by typing @key{RET}, the minibuffer contents replace the | |
1370 | current occurrence of the pattern. They also become the new | |
1371 | replacement string for any further occurrences. | |
1372 | ||
1373 | @item C-l | |
1374 | to redisplay the screen. Then you must type another character to | |
1375 | specify what to do with this occurrence. | |
1376 | ||
1377 | @item C-h | |
1378 | to display a message summarizing these options. Then you must type | |
1379 | another character to specify what to do with this occurrence. | |
1380 | @end table | |
1381 | ||
1382 | Some other characters are aliases for the ones listed above: @kbd{y}, | |
1383 | @kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and | |
1384 | @key{RET}. | |
1385 | ||
1386 | Aside from this, any other character exits the @code{query-replace}, | |
1387 | and is then reread as part of a key sequence. Thus, if you type | |
1388 | @kbd{C-k}, it exits the @code{query-replace} and then kills to end of | |
1389 | line. | |
1390 | ||
1391 | To restart a @code{query-replace} once it is exited, use @kbd{C-x | |
1392 | @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it | |
1393 | used the minibuffer to read its arguments. @xref{Repetition, C-x ESC | |
1394 | ESC}. | |
1395 | ||
2501c912 GM |
1396 | @cindex invisible text, and query-replace |
1397 | The option @code{search-invisible} determines how @code{query-replace} | |
1398 | treats invisible text. @xref{Outline Search}. | |
1399 | ||
8cf51b2c GM |
1400 | @xref{Operating on Files}, for the Dired @kbd{Q} command which |
1401 | performs query replace on selected files. See also @ref{Transforming | |
1402 | File Names}, for Dired commands to rename, copy, or link files by | |
1403 | replacing regexp matches in file names. | |
1404 | ||
1405 | @node Other Repeating Search | |
1406 | @section Other Search-and-Loop Commands | |
1407 | ||
1408 | Here are some other commands that find matches for a regular | |
1409 | expression. They all ignore case in matching, if the pattern contains | |
1410 | no upper-case letters and @code{case-fold-search} is non-@code{nil}. | |
1411 | Aside from @code{occur} and its variants, all operate on the text from | |
6184c708 | 1412 | point to the end of the buffer, or on the region if it is active. |
8cf51b2c GM |
1413 | |
1414 | @findex list-matching-lines | |
1415 | @findex occur | |
1416 | @findex multi-occur | |
1417 | @findex multi-occur-in-matching-buffers | |
1418 | @findex how-many | |
8cf51b2c GM |
1419 | @findex flush-lines |
1420 | @findex keep-lines | |
1421 | ||
1422 | @table @kbd | |
15cf2f52 CY |
1423 | @item M-x multi-isearch-buffers |
1424 | Prompt for one or more buffer names, ending with @key{RET}; then, | |
1425 | begin a multi-buffer incremental search in those buffers. (If the | |
1426 | search fails in one buffer, the next @kbd{C-s} tries searching the | |
1427 | next specified buffer, and so forth.) With a prefix argument, prompt | |
1428 | for a regexp and begin a multi-buffer incremental search in buffers | |
1429 | matching that regexp. | |
1430 | ||
1431 | @item M-x multi-isearch-buffers-regexp | |
1432 | This command is just like @code{multi-isearch-buffers}, except it | |
1433 | performs an incremental regexp search. | |
1434 | ||
5abc31ef CY |
1435 | @cindex Occur mode |
1436 | @cindex mode, Occur | |
15cf2f52 CY |
1437 | @item M-x occur |
1438 | Prompt for a regexp, and display a list showing each line in the | |
1439 | buffer that contains a match for it. To limit the search to part of | |
1440 | the buffer, narrow to that part (@pxref{Narrowing}). A numeric | |
1441 | argument @var{n} specifies that @var{n} lines of context are to be | |
dc2d2590 | 1442 | displayed before and after each matching line. |
8cf51b2c GM |
1443 | |
1444 | @kindex RET @r{(Occur mode)} | |
1445 | @kindex o @r{(Occur mode)} | |
1446 | @kindex C-o @r{(Occur mode)} | |
1c64e6ed | 1447 | In the @file{*Occur*} buffer, you can click on each entry, or move |
5abc31ef CY |
1448 | point there and type @key{RET}, to visit the corresponding position in |
1449 | the buffer that was searched. @kbd{o} and @kbd{C-o} display the match | |
1450 | in another window; @kbd{C-o} does not select it. Alternatively, you | |
1451 | can use the @kbd{C-x `} (@code{next-error}) command to visit the | |
1452 | occurrences one by one (@pxref{Compilation Mode}). | |
1453 | ||
1454 | @cindex Occur Edit mode | |
1455 | @cindex mode, Occur Edit | |
1c64e6ed | 1456 | Typing @kbd{e} in the @file{*Occur*} buffer switches to Occur Edit |
5abc31ef CY |
1457 | mode, in which edits made to the entries are also applied to the text |
1458 | in the originating buffer. Type @kbd{C-c C-c} to return to Occur | |
1459 | mode. | |
1460 | ||
1461 | The command @kbd{M-x list-matching-lines} is a synonym for @kbd{M-x | |
1462 | occur}. | |
8cf51b2c | 1463 | |
b5fb9df5 CY |
1464 | @kindex M-s o |
1465 | @item M-s o | |
1466 | Run @code{occur} using the search string of the last incremental | |
97b3a00b | 1467 | string search. You can also run @kbd{M-s o} when an incremental |
b5fb9df5 CY |
1468 | search is active; this uses the current search string. |
1469 | ||
15cf2f52 CY |
1470 | @item M-x multi-occur |
1471 | This command is just like @code{occur}, except it is able to search | |
1472 | through multiple buffers. It asks you to specify the buffer names one | |
1473 | by one. | |
1474 | ||
1475 | @item M-x multi-occur-in-matching-buffers | |
1476 | This command is similar to @code{multi-occur}, except the buffers to | |
1477 | search are specified by a regular expression that matches visited file | |
1478 | names. With a prefix argument, it uses the regular expression to | |
1479 | match buffer names instead. | |
1480 | ||
1481 | @item M-x how-many | |
1482 | Prompt for a regexp, and print the number of matches for it in the | |
1483 | buffer after point. If the region is active, this operates on the | |
1484 | region instead. | |
1485 | ||
1486 | @item M-x flush-lines | |
1487 | Prompt for a regexp, and delete each line that contains a match for | |
1488 | it, operating on the text after point. This command deletes the | |
1489 | current line if it contains a match starting after point. If the | |
1490 | region is active, it operates on the region instead; if a line | |
1491 | partially contained in the region contains a match entirely contained | |
1492 | in the region, it is deleted. | |
8cf51b2c GM |
1493 | |
1494 | If a match is split across lines, @code{flush-lines} deletes all those | |
1495 | lines. It deletes the lines before starting to look for the next | |
1496 | match; hence, it ignores a match starting on the same line at which | |
1497 | another match ended. | |
1498 | ||
15cf2f52 CY |
1499 | @item M-x keep-lines |
1500 | Prompt for a regexp, and delete each line that @emph{does not} contain | |
1501 | a match for it, operating on the text after point. If point is not at | |
1502 | the beginning of a line, this command always keeps the current line. | |
1503 | If the region is active, the command operates on the region instead; | |
1504 | it never deletes lines that are only partially contained in the region | |
1505 | (a newline that ends a line counts as part of that line). | |
8cf51b2c GM |
1506 | |
1507 | If a match is split across lines, this command keeps all those lines. | |
1508 | @end table |