Mercurial > hg > xemacs-beta

comparison man/xemacs/search.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children 972bbb6d6ca2 abe6d1db359e
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1
2 @node Search, Fixit, Display, Top
3 @chapter Searching and Replacement
4 @cindex searching
5
6 Like other editors, Emacs has commands for searching for occurrences of
7 a string. The principal search command is unusual in that it is
8 @dfn{incremental}: it begins to search before you have finished typing the
9 search string. There are also non-incremental search commands more like
10 those of other editors.
11
12 Besides the usual @code{replace-string} command that finds all
13 occurrences of one string and replaces them with another, Emacs has a fancy
14 replacement command called @code{query-replace} which asks interactively
15 which occurrences to replace.
16
17 @menu
18 * Incremental Search:: Search happens as you type the string.
19 * Non-Incremental Search:: Specify entire string and then search.
20 * Word Search:: Search for sequence of words.
21 * Regexp Search:: Search for match for a regexp.
22 * Regexps:: Syntax of regular expressions.
23 * Search Case:: To ignore case while searching, or not.
24 * Replace:: Search, and replace some or all matches.
25 * Other Repeating Search:: Operating on all matches for some regexp.
26 @end menu
27
28 @node Incremental Search, Non-Incremental Search, Search, Search
29 @section Incremental Search
30
31 An incremental search begins searching as soon as you type the first
32 character of the search string. As you type in the search string, Emacs
33 shows you where the string (as you have typed it so far) is found.
34 When you have typed enough characters to identify the place you want, you
35 can stop. Depending on what you do next, you may or may not need to
36 terminate the search explicitly with a @key{RET}.
37
38 @c WideCommands
39 @table @kbd
40 @item C-s
41 Incremental search forward (@code{isearch-forward}).
42 @item C-r
43 Incremental search backward (@code{isearch-backward}).
44 @end table
45
46 @kindex C-s
47 @kindex C-r
48 @findex isearch-forward
49 @findex isearch-backward
50 @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from
51 the keyboard and positions the cursor at the first occurrence of the
52 characters that you have typed. If you type @kbd{C-s} and then @kbd{F},
53 the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see
54 the cursor move to after the first @samp{FO}. After another @kbd{O}, the
55 cursor is after the first @samp{FOO} after the place where you started the
56 search. Meanwhile, the search string @samp{FOO} has been echoed in the
57 echo area.@refill
58
59 The echo area display ends with three dots when actual searching is going
60 on. When search is waiting for more input, the three dots are removed.
61 (On slow terminals, the three dots are not displayed.)
62
63 If you make a mistake in typing the search string, you can erase
64 characters with @key{DEL}. Each @key{DEL} cancels the last character of the
65 search string. This does not happen until Emacs is ready to read another
66 input character; first it must either find, or fail to find, the character
67 you want to erase. If you do not want to wait for this to happen, use
68 @kbd{C-g} as described below.@refill
69
70 When you are satisfied with the place you have reached, you can type
71 @key{RET} (or @key{C-m}), which stops searching, leaving the cursor where
72 the search brought it. Any command not specially meaningful in searches also
73 stops the search and is then executed. Thus, typing @kbd{C-a} exits the
74 search and then moves to the beginning of the line. @key{RET} is necessary
75 only if the next command you want to type is a printing character,
76 @key{DEL}, @key{ESC}, or another control character that is special
77 within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, or @kbd{C-y}).
78
79 Sometimes you search for @samp{FOO} and find it, but were actually
80 looking for a different occurance of it. To move to the next occurrence
81 of the search string, type another @kbd{C-s}. Do this as often as
82 necessary. If you overshoot, you can cancel some @kbd{C-s}
83 characters with @key{DEL}.
84
85 After you exit a search, you can search for the same string again by
86 typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
87 incremental search, and the second @kbd{C-s} means ``search again''.
88
89 If the specified string is not found at all, the echo area displays
90 the text @samp{Failing I-Search}. The cursor is after the place where
91 Emacs found as much of your string as it could. Thus, if you search for
92 @samp{FOOT}, and there is no @samp{FOOT}, the cursor may be after the
93 @samp{FOO} in @samp{FOOL}. At this point there are several things you
94 can do. If you mistyped the search string, correct it. If you like the
95 place you have found, you can type @key{RET} or some other Emacs command
96 to ``accept what the search offered''. Or you can type @kbd{C-g}, which
97 removes from the search string the characters that could not be found
98 (the @samp{T} in @samp{FOOT}), leaving those that were found (the
99 @samp{FOO} in @samp{FOOT}). A second @kbd{C-g} at that point cancels
100 the search entirely, returning point to where it was when the search
101 started.
102
103 If a search is failing and you ask to repeat it by typing another
104 @kbd{C-s}, it starts again from the beginning of the buffer. Repeating
105 a failing backward search with @kbd{C-r} starts again from the end. This
106 is called @dfn{wrapping around}. @samp{Wrapped} appears in the search
107 prompt once this has happened.
108
109 @cindex quitting (in search)
110 The @kbd{C-g} ``quit'' character does special things during searches;
111 just what it does depends on the status of the search. If the search has
112 found what you specified and is waiting for input, @kbd{C-g} cancels the
113 entire search. The cursor moves back to where you started the search. If
114 @kbd{C-g} is typed when there are characters in the search string that have
115 not been found---because Emacs is still searching for them, or because it
116 has failed to find them---then the search string characters which have not
117 been found are discarded from the search string. The
118 search is now successful and waiting for more input, so a second @kbd{C-g}
119 cancels the entire search.
120
121 To search for a control character such as @kbd{C-s} or @key{DEL} or
122 @key{ESC}, you must quote it by typing @kbd{C-q} first. This function
123 of @kbd{C-q} is analogous to its meaning as an Emacs command: it causes
124 the following character to be treated the way a graphic character would
125 normally be treated in the same context.
126
127 To search backwards, you can use @kbd{C-r} instead of @kbd{C-s} to
128 start the search; @kbd{C-r} is the key that runs the command
129 (@code{isearch-backward}) to search backward. You can also use
130 @kbd{C-r} to change from searching forward to searching backwards. Do
131 this if a search fails because the place you started was too far down in the
132 file. Repeated @kbd{C-r} keeps looking for more occurrences backwards.
133 @kbd{C-s} starts going forward again. You can cancel @kbd{C-r} in a
134 search with @key{DEL}.
135
136 The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search
137 to grab text from the buffer into the search string. This makes it
138 convenient to search for another occurrence of text at point. @kbd{C-w}
139 copies the word after point as part of the search string, advancing
140 point over that word. Another @kbd{C-s} to repeat the search will then
141 search for a string including that word. @kbd{C-y} is similar to @kbd{C-w}
142 but copies the rest of the current line into the search string.
143
144 The characters @kbd{M-p} and @kbd{M-n} can be used in an incremental
145 search to recall things which you have searched for in the past. A
146 list of the last 16 things you have searched for is retained, and
147 @kbd{M-p} and @kbd{M-n} let you cycle through that ring.
148
149 The character @kbd{M-@key{TAB}} does completion on the elements in
150 the search history ring. For example, if you know that you have
151 recently searched for the string @code{POTATOE}, you could type
152 @kbd{C-s P O M-@key{TAB}}. If you had searched for other strings
153 beginning with @code{PO} then you would be shown a list of them, and
154 would need to type more to select one.
155
156 You can change any of the special characters in incremental search via
157 the normal keybinding mechanism: simply add a binding to the
158 @code{isearch-mode-map}. For example, to make the character
159 @kbd{C-b} mean ``search backwards'' while in isearch-mode, do this:
160
161 @example
162 (define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
163 @end example
164
165 These are the default bindings of isearch-mode:
166
167 @findex isearch-delete-char
168 @findex isearch-exit
169 @findex isearch-quote-char
170 @findex isearch-repeat-forward
171 @findex isearch-repeat-backward
172 @findex isearch-yank-line
173 @findex isearch-yank-word
174 @findex isearch-abort
175 @findex isearch-ring-retreat
176 @findex isearch-ring-advance
177 @findex isearch-complete
178
179 @kindex DEL (isearch-mode)
180 @kindex RET (isearch-mode)
181 @kindex C-q (isearch-mode)
182 @kindex C-s (isearch-mode)
183 @kindex C-r (isearch-mode)
184 @kindex C-y (isearch-mode)
185 @kindex C-w (isearch-mode)
186 @kindex C-g (isearch-mode)
187 @kindex M-p (isearch-mode)
188 @kindex M-n (isearch-mode)
189 @kindex M-TAB (isearch-mode)
190
191 @table @kbd
192 @item DEL
193 Delete a character from the incremental search string (@code{isearch-delete-char}).
194 @item RET
195 Exit incremental search (@code{isearch-exit}).
196 @item C-q
197 Quote special characters for incremental search (@code{isearch-quote-char}).
198 @item C-s
199 Repeat incremental search forward (@code{isearch-repeat-forward}).
200 @item C-r
201 Repeat incremental search backward (@code{isearch-repeat-backward}).
202 @item C-y
203 Pull rest of line from buffer into search string (@code{isearch-yank-line}).
204 @item C-w
205 Pull next word from buffer into search string (@code{isearch-yank-word}).
206 @item C-g
207 Cancels input back to what has been found successfully, or aborts the
208 isearch (@code{isearch-abort}).
209 @item M-p
210 Recall the previous element in the isearch history ring
211 (@code{isearch-ring-retreat}).
212 @item M-n
213 Recall the next element in the isearch history ring
214 (@code{isearch-ring-advance}).
215 @item M-@key{TAB}
216 Do completion on the elements in the isearch history ring
217 (@code{isearch-complete}).
218
219 @end table
220
221 Any other character which is normally inserted into a buffer when typed
222 is automatically added to the search string in isearch-mode.
223
224 @subsection Slow Terminal Incremental Search
225
226 Incremental search on a slow terminal uses a modified style of display
227 that is designed to take less time. Instead of redisplaying the buffer at
228 each place the search gets to, it creates a new single-line window and uses
229 that to display the line the search has found. The single-line window
230 appears as soon as point gets outside of the text that is already
231 on the screen.
232
233 When the search is terminated, the single-line window is removed. Only
234 at this time the window in which the search was done is redisplayed to show
235 its new value of point.
236
237 The three dots at the end of the search string, normally used to indicate
238 that searching is going on, are not displayed in slow style display.
239
240 @vindex search-slow-speed
241 The slow terminal style of display is used when the terminal baud rate is
242 less than or equal to the value of the variable @code{search-slow-speed},
243 initially 1200.
244
245 @vindex search-slow-window-lines
246 The number of lines to use in slow terminal search display is controlled
247 by the variable @code{search-slow-window-lines}. Its normal value is 1.
248
249 @node Non-Incremental Search, Word Search, Incremental Search, Search
250 @section Non-Incremental Search
251 @cindex non-incremental search
252
253 Emacs also has conventional non-incremental search commands, which require
254 you type the entire search string before searching begins.
255
256 @table @kbd
257 @item C-s @key{RET} @var{string} @key{RET}
258 Search for @var{string}.
259 @item C-r @key{RET} @var{string} @key{RET}
260 Search backward for @var{string}.
261 @end table
262
263 To do a non-incremental search, first type @kbd{C-s @key{RET}}
264 (or @kbd{C-s C-m}). This enters the minibuffer to read the search string.
265 Terminate the string with @key{RET} to start the search. If the string
266 is not found, the search command gets an error.
267
268 By default, @kbd{C-s} invokes incremental search, but if you give it an
269 empty argument, which would otherwise be useless, it invokes non-incremental
270 search. Therefore, @kbd{C-s @key{RET}} invokes non-incremental search.
271 @kbd{C-r @key{RET}} also works this way.
272
273 @findex search-forward
274 @findex search-backward
275 Forward and backward non-incremental searches are implemented by the
276 commands @code{search-forward} and @code{search-backward}. You can bind
277 these commands to keys. The reason that incremental
278 search is programmed to invoke them as well is that @kbd{C-s @key{RET}}
279 is the traditional sequence of characters used in Emacs to invoke
280 non-incremental search.
281
282 Non-incremental searches performed using @kbd{C-s @key{RET}} do
283 not call @code{search-forward} right away. They first check
284 if the next character is @kbd{C-w}, which requests a word search.
285 @ifinfo
286 @xref{Word Search}.
287 @end ifinfo
288
289 @node Word Search, Regexp Search, Non-Incremental Search, Search
290 @section Word Search
291 @cindex word search
292
293 Word search looks for a sequence of words without regard to how the
294 words are separated. More precisely, you type a string of many words,
295 using single spaces to separate them, and the string is found even if
296 there are multiple spaces, newlines or other punctuation between the words.
297
298 Word search is useful in editing documents formatted by text formatters.
299 If you edit while looking at the printed, formatted version, you can't tell
300 where the line breaks are in the source file. Word search, allows you
301 to search without having to know the line breaks.
302
303 @table @kbd
304 @item C-s @key{RET} C-w @var{words} @key{RET}
305 Search for @var{words}, ignoring differences in punctuation.
306 @item C-r @key{RET} C-w @var{words} @key{RET}
307 Search backward for @var{words}, ignoring differences in punctuation.
308 @end table
309
310 Word search is a special case of non-incremental search. It is invoked
311 with @kbd{C-s @key{RET} C-w} followed by the search string, which
312 must always be terminated with another @key{RET}. Being non-incremental, this
313 search does not start until the argument is terminated. It works by
314 constructing a regular expression and searching for that. @xref{Regexp
315 Search}.
316
317 You can do a backward word search with @kbd{C-r @key{RET} C-w}.
318
319 @findex word-search-forward
320 @findex word-search-backward
321 Forward and backward word searches are implemented by the commands
322 @code{word-search-forward} and @code{word-search-backward}. You can
323 bind these commands to keys. The reason that incremental
324 search is programmed to invoke them as well is that @kbd{C-s @key{RET} C-w}
325 is the traditional Emacs sequence of keys for word search.
326
327 @node Regexp Search, Regexps, Word Search, Search
328 @section Regular Expression Search
329 @cindex regular expression
330 @cindex regexp
331
332 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
333 denotes a set of strings, possibly an infinite set. Searching for matches
334 for a regexp is a powerful operation that editors on Unix systems have
335 traditionally offered. In XEmacs, you can search for the next match for
336 a regexp either incrementally or not.
337
338 @kindex M-C-s
339 @findex isearch-forward-regexp
340 @findex isearch-backward-regexp
341 Incremental search for a regexp is done by typing @kbd{M-C-s}
342 (@code{isearch-forward-regexp}). This command reads a search string
343 incrementally just like @kbd{C-s}, but it treats the search string as a
344 regexp rather than looking for an exact match against the text in the
345 buffer. Each time you add text to the search string, you make the regexp
346 longer, and the new regexp is searched for. A reverse regexp search command
347 @code{isearch-backward-regexp} also exists, but no key runs it.
348
349 All of the control characters that do special things within an ordinary
350 incremental search have the same functionality in incremental regexp search.
351 Typing @kbd{C-s} or @kbd{C-r} immediately after starting a search
352 retrieves the last incremental search regexp used:
353 incremental regexp and non-regexp searches have independent defaults.
354
355 @findex re-search-forward
356 @findex re-search-backward
357 Non-incremental search for a regexp is done by the functions
358 @code{re-search-forward} and @code{re-search-backward}. You can invoke
359 them with @kbd{M-x} or bind them to keys. You can also call
360 @code{re-search-forward} by way of incremental regexp search with
361 @kbd{M-C-s @key{RET}}.
362
363 @node Regexps, Search Case, Regexp Search, Search
364 @section Syntax of Regular Expressions
365
366 Regular expressions have a syntax in which a few characters are special
367 constructs and the rest are @dfn{ordinary}. An ordinary character is a
368 simple regular expression which matches that character and nothing else.
369 The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
370 @samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special
371 characters will be defined. Any other character appearing in a regular
372 expression is ordinary, unless a @samp{\} precedes it.@refill
373
374 For example, @samp{f} is not a special character, so it is ordinary, and
375 therefore @samp{f} is a regular expression that matches the string @samp{f}
376 and no other string. (It does @i{not} match the string @samp{ff}.) Likewise,
377 @samp{o} is a regular expression that matches only @samp{o}.@refill
378
379 Any two regular expressions @var{a} and @var{b} can be concatenated. The
380 result is a regular expression which matches a string if @var{a} matches
381 some amount of the beginning of that string and @var{b} matches the rest of
382 the string.@refill
383
384 As a simple example, you can concatenate the regular expressions @samp{f}
385 and @samp{o} to get the regular expression @samp{fo}, which matches only
386 the string @samp{fo}. To do something nontrivial, you
387 need to use one of the following special characters:
388
389 @table @kbd
390 @item .@: @r{(Period)}
391 is a special character that matches any single character except a newline.
392 Using concatenation, you can make regular expressions like @samp{a.b}, which
393 matches any three-character string which begins with @samp{a} and ends with
394 @samp{b}.@refill
395
396 @item *
397 is not a construct by itself; it is a suffix, which means the
398 preceding regular expression is to be repeated as many times as
399 possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
400 @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s.
401 The case of zero @samp{o}s is allowed: @samp{fo*} does match
402 @samp{f}.@refill
403
404 @samp{*} always applies to the @i{smallest} possible preceding
405 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
406 repeating @samp{fo}.@refill
407
408 The matcher processes a @samp{*} construct by immediately matching
409 as many repetitions as it can find. Then it continues with the rest
410 of the pattern. If that fails, backtracking occurs, discarding some
411 of the matches of the @samp{*}-modified construct in case that makes
412 it possible to match the rest of the pattern. For example, matching
413 @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
414 tries to match all three @samp{a}s; but the rest of the pattern is
415 @samp{ar} and there is only @samp{r} left to match, so this try fails.
416 The next alternative is for @samp{a*} to match only two @samp{a}s.
417 With this choice, the rest of the regexp matches successfully.@refill
418
419 @item +
420 is a suffix character similar to @samp{*} except that it requires that
421 the preceding expression be matched at least once. For example,
422 @samp{ca+r} will match the strings @samp{car} and @samp{caaaar}
423 but not the string @samp{cr}, whereas @samp{ca*r} would match all
424 three strings.@refill
425
426 @item ?
427 is a suffix character similar to @samp{*} except that it can match the
428 preceding expression either once or not at all. For example,
429 @samp{ca?r} will match @samp{car} or @samp{cr}; nothing else.
430
431 @item [ @dots{} ]
432 @samp{[} begins a @dfn{character set}, which is terminated by a
433 @samp{]}. In the simplest case, the characters between the two form
434 the set. Thus, @samp{[ad]} matches either one @samp{a} or one
435 @samp{d}, and @samp{[ad]*} matches any string composed of just
436 @samp{a}s and @samp{d}s (including the empty string), from which it
437 follows that @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
438 @samp{caddaar}, etc.@refill
439
440 You can include character ranges in a character set by writing two
441 characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any
442 lower-case letter. Ranges may be intermixed freely with individual
443 characters, as in @samp{[a-z$%.]}, which matches any lower-case letter
444 or @samp{$}, @samp{%}, or period.
445 @refill
446
447 Note that inside a character set the usual special characters are not
448 special any more. A completely different set of special characters
449 exists inside character sets: @samp{]}, @samp{-}, and @samp{^}.@refill
450
451 To include a @samp{]} in a character set, you must make it the first
452 character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
453 include a @samp{-}, write @samp{---}, which is a range containing only
454 @samp{-}. To include @samp{^}, make it other than the first character
455 in the set.@refill
456
457 @item [^ @dots{} ]
458 @samp{[^} begins a @dfn{complement character set}, which matches any
459 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
460 matches all characters @i{except} letters and digits.@refill
461
462 @samp{^} is not special in a character set unless it is the first
463 character. The character following the @samp{^} is treated as if it
464 were first (@samp{-} and @samp{]} are not special there).
465
466 Note that a complement character set can match a newline, unless
467 newline is mentioned as one of the characters not to match.
468
469 @item ^
470 is a special character that matches the empty string, but only if at
471 the beginning of a line in the text being matched. Otherwise, it fails
472 to match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs
473 at the beginning of a line.
474
475 @item $
476 is similar to @samp{^} but matches only at the end of a line. Thus,
477 @samp{xx*$} matches a string of one @samp{x} or more at the end of a line.
478
479 @item \
480 does two things: it quotes the special characters (including
481 @samp{\}), and it introduces additional special constructs.
482
483 Because @samp{\} quotes special characters, @samp{\$} is a regular
484 expression that matches only @samp{$}, and @samp{\[} is a regular
485 expression that matches only @samp{[}, and so on.@refill
486 @end table
487
488 Note: for historical compatibility, special characters are treated as
489 ordinary ones if they are in contexts where their special meanings make no
490 sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
491 no preceding expression on which the @samp{*} can act. It is poor practice
492 to depend on this behavior; better to quote the special character anyway,
493 regardless of where is appears.@refill
494
495 Usually, @samp{\} followed by any character matches only
496 that character. However, there are several exceptions: characters
497 which, when preceded by @samp{\}, are special constructs. Such
498 characters are always ordinary when encountered on their own. Here
499 is a table of @samp{\} constructs.
500
501 @table @kbd
502 @item \|
503 specifies an alternative.
504 Two regular expressions @var{a} and @var{b} with @samp{\|} in
505 between form an expression that matches anything @var{a} or
506 @var{b} matches.@refill
507
508 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
509 but no other string.@refill
510
511 @samp{\|} applies to the largest possible surrounding expressions. Only a
512 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
513 @samp{\|}.@refill
514
515 Full backtracking capability exists to handle multiple uses of @samp{\|}.
516
517 @item \( @dots{} \)
518 is a grouping construct that serves three purposes:
519
520 @enumerate
521 @item
522 To enclose a set of @samp{\|} alternatives for other operations.
523 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
524
525 @item
526 To enclose a complicated expression for the postfix @samp{*} to operate on.
527 Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any (zero or
528 more) number of @samp{na} strings.@refill
529
530 @item
531 To mark a matched substring for future reference.
532
533 @end enumerate
534
535 This last application is not a consequence of the idea of a
536 parenthetical grouping; it is a separate feature which happens to be
537 assigned as a second meaning to the same @samp{\( @dots{} \)} construct
538 because in practice there is no conflict between the two meanings.
539 Here is an explanation:
540
541 @item \@var{digit}
542 after the end of a @samp{\( @dots{} \)} construct, the matcher remembers the
543 beginning and end of the text matched by that construct. Then, later on
544 in the regular expression, you can use @samp{\} followed by @var{digit}
545 to mean ``match the same text matched the @var{digit}'th time by the
546 @samp{\( @dots{} \)} construct.''@refill
547
548 The strings matching the first nine @samp{\( @dots{} \)} constructs appearing
549 in a regular expression are assigned numbers 1 through 9 in order that the
550 open-parentheses appear in the regular expression. @samp{\1} through
551 @samp{\9} may be used to refer to the text matched by the corresponding
552 @samp{\( @dots{} \)} construct.
553
554 For example, @samp{\(.*\)\1} matches any newline-free string that is
555 composed of two identical halves. The @samp{\(.*\)} matches the first
556 half, which may be anything, but the @samp{\1} that follows must match
557 the same exact text.
558
559 @item \`
560 matches the empty string, provided it is at the beginning
561 of the buffer.
562
563 @item \'
564 matches the empty string, provided it is at the end of
565 the buffer.
566
567 @item \b
568 matches the empty string, provided it is at the beginning or
569 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
570 @samp{foo} as a separate word. @samp{\bballs?\b} matches
571 @samp{ball} or @samp{balls} as a separate word.@refill
572
573 @item \B
574 matches the empty string, provided it is @i{not} at the beginning or
575 end of a word.
576
577 @item \<
578 matches the empty string, provided it is at the beginning of a word.
579
580 @item \>
581 matches the empty string, provided it is at the end of a word.
582
583 @item \w
584 matches any word-constituent character. The editor syntax table
585 determines which characters these are.
586
587 @item \W
588 matches any character that is not a word-constituent.
589
590 @item \s@var{code}
591 matches any character whose syntax is @var{code}. @var{code} is a
592 character which represents a syntax code: thus, @samp{w} for word
593 constituent, @samp{-} for whitespace, @samp{(} for open-parenthesis,
594 etc. @xref{Syntax}.@refill
595
596 @item \S@var{code}
597 matches any character whose syntax is not @var{code}.
598 @end table
599
600 Here is a complicated regexp used by Emacs to recognize the end of a
601 sentence together with any whitespace that follows. It is given in Lisp
602 syntax to enable you to distinguish the spaces from the tab characters. In
603 Lisp syntax, the string constant begins and ends with a double-quote.
604 @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
605 backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
606 newline.
607
608 @example
609 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
610 @end example
611
612 @noindent
613 This regexp contains four parts: a character set matching
614 period, @samp{?} or @samp{!}; a character set matching close-brackets,
615 quotes or parentheses, repeated any number of times; an alternative in
616 backslash-parentheses that matches end-of-line, a tab or two spaces; and
617 a character set matching whitespace characters, repeated any number of
618 times.
619
620 @node Search Case, Replace, Regexps, Search
621 @section Searching and Case
622
623 @vindex case-fold-search
624 All searches in Emacs normally ignore the case of the text they
625 are searching through; if you specify searching for @samp{FOO},
626 @samp{Foo} and @samp{foo} are also considered a match. Regexps, and in
627 particular character sets, are included: @samp{[aB]} matches @samp{a}
628 or @samp{A} or @samp{b} or @samp{B}.@refill
629
630 If you want a case-sensitive search, set the variable
631 @code{case-fold-search} to @code{nil}. Then all letters must match
632 exactly, including case. @code{case-fold-search} is a per-buffer
633 variable; altering it affects only the current buffer, but
634 there is a default value which you can change as well. @xref{Locals}.
635 You can also use @b{Case Sensitive Search} from the @b{Options} menu
636 on your screen.
637
638 @node Replace, Other Repeating Search, Search Case, Search
639 @section Replacement Commands
640 @cindex replacement
641 @cindex string substitution
642 @cindex global substitution
643
644 Global search-and-replace operations are not needed as often in Emacs as
645 they are in other editors, but they are available. In addition to the
646 simple @code{replace-string} command which is like that found in most
647 editors, there is a @code{query-replace} command which asks you, for each
648 occurrence of a pattern, whether to replace it.
649
650 The replace commands all replace one string (or regexp) with one
651 replacement string. It is possible to perform several replacements in
652 parallel using the command @code{expand-region-abbrevs}. @xref{Expanding
653 Abbrevs}.
654
655 @menu
656 * Unconditional Replace:: Replacing all matches for a string.
657 * Regexp Replace:: Replacing all matches for a regexp.
658 * Replacement and Case:: How replacements preserve case of letters.
659 * Query Replace:: How to use querying.
660 @end menu
661
662 @node Unconditional Replace, Regexp Replace, Replace, Replace
663 @subsection Unconditional Replacement
664 @findex replace-string
665 @findex replace-regexp
666
667 @table @kbd
668 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
669 Replace every occurrence of @var{string} with @var{newstring}.
670 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
671 Replace every match for @var{regexp} with @var{newstring}.
672 @end table
673
674 To replace every instance of @samp{foo} after point with @samp{bar},
675 use the command @kbd{M-x replace-string} with the two arguments
676 @samp{foo} and @samp{bar}. Replacement occurs only after point: if you
677 want to cover the whole buffer you must go to the beginning first. By
678 default, all occurrences up to the end of the buffer are replaced. To
679 limit replacement to part of the buffer, narrow to that part of the
680 buffer before doing the replacement (@pxref{Narrowing}).
681
682 When @code{replace-string} exits, point is left at the last occurrence
683 replaced. The value of point when the @code{replace-string} command was
684 issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back
685 there.
686
687 A numeric argument restricts replacement to matches that are surrounded
688 by word boundaries.
689
690 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
691 @subsection Regexp Replacement
692
693 @code{replace-string} replaces exact matches for a single string. The
694 similar command @code{replace-regexp} replaces any match for a specified
695 pattern.
696
697 In @code{replace-regexp}, the @var{newstring} need not be constant. It
698 can refer to all or part of what is matched by the @var{regexp}. @samp{\&}
699 in @var{newstring} stands for the entire text being replaced.
700 @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
701 whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
702 For example,@refill
703
704 @example
705 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
706 @end example
707
708 @noindent
709 would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
710 with @samp{cddr-safe}.
711
712 @example
713 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
714 @end example
715
716 @noindent
717 would perform exactly the opposite replacements. To include a @samp{\}
718 in the text to replace with, you must give @samp{\\}.
719
720 @node Replacement and Case, Query Replace, Regexp Replace, Replace
721 @subsection Replace Commands and Case
722
723 @vindex case-replace
724 @vindex case-fold-search
725 If the arguments to a replace command are in lower case, the command
726 preserves case when it makes a replacement. Thus, the following command:
727
728 @example
729 M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
730 @end example
731
732 @noindent
733 replaces a lower-case @samp{foo} with a lower case @samp{bar}, @samp{FOO}
734 with @samp{BAR}, and @samp{Foo} with @samp{Bar}. If upper-case letters are
735 used in the second argument, they remain upper-case every time that
736 argument is inserted. If upper-case letters are used in the first
737 argument, the second argument is always substituted exactly as given, with
738 no case conversion. Likewise, if the variable @code{case-replace} is set
739 to @code{nil}, replacement is done without case conversion. If
740 @code{case-fold-search} is set to @code{nil}, case is significant in
741 matching occurrences of @samp{foo} to replace; also, case conversion of the
742 replacement string is not done.
743
744 @node Query Replace,, Replacement and Case, Replace
745 @subsection Query Replace
746 @cindex query replace
747
748 @table @kbd
749 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
750 @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
751 Replace some occurrences of @var{string} with @var{newstring}.
752 @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
753 Replace some matches for @var{regexp} with @var{newstring}.
754 @end table
755
756 @kindex M-%
757 @findex query-replace
758 If you want to change only some of the occurrences of @samp{foo} to
759 @samp{bar}, not all of them, you can use @code{query-replace} instead of
760 @kbd{M-%}. This command finds occurrences of @samp{foo} one by one,
761 displays each occurrence, and asks you whether to replace it. A numeric
762 argument to @code{query-replace} tells it to consider only occurrences
763 that are bounded by word-delimiter characters.@refill
764
765 @findex query-replace-regexp
766 Aside from querying, @code{query-replace} works just like
767 @code{replace-string}, and @code{query-replace-regexp} works
768 just like @code{replace-regexp}.@refill
769
770 The things you can type when you are shown an occurrence of @var{string}
771 or a match for @var{regexp} are:
772
773 @kindex SPC (query-replace)
774 @kindex DEL (query-replace)
775 @kindex , (query-replace)
776 @kindex ESC (query-replace)
777 @kindex . (query-replace)
778 @kindex ! (query-replace)
779 @kindex ^ (query-replace)
780 @kindex C-r (query-replace)
781 @kindex C-w (query-replace)
782 @kindex C-l (query-replace)
783
784 @c WideCommands
785 @table @kbd
786 @item @key{SPC}
787 to replace the occurrence with @var{newstring}. This preserves case, just
788 like @code{replace-string}, provided @code{case-replace} is non-@code{nil},
789 as it normally is.@refill
790
791 @item @key{DEL}
792 to skip to the next occurrence without replacing this one.
793
794 @item , @r{(Comma)}
795 to replace this occurrence and display the result. You are then
796 prompted for another input character. However, since the replacement has
797 already been made, @key{DEL} and @key{SPC} are equivalent. At this
798 point, you can type @kbd{C-r} (see below) to alter the replaced text. To
799 undo the replacement, you can type @kbd{C-x u}.
800 This exits the @code{query-replace}. If you want to do further
801 replacement you must use @kbd{C-x ESC} to restart (@pxref{Repetition}).
802
803 @item @key{ESC}
804 to exit without doing any more replacements.
805
806 @item .@: @r{(Period)}
807 to replace this occurrence and then exit.
808
809 @item !
810 to replace all remaining occurrences without asking again.
811
812 @item ^
813 to go back to the location of the previous occurrence (or what used to
814 be an occurrence), in case you changed it by mistake. This works by
815 popping the mark ring. Only one @kbd{^} in a row is allowed, because
816 only one previous replacement location is kept during @code{query-replace}.
817
818 @item C-r
819 to enter a recursive editing level, in case the occurrence needs to be
820 edited rather than just replaced with @var{newstring}. When you are
821 done, exit the recursive editing level with @kbd{C-M-c} and the next
822 occurrence will be displayed. @xref{Recursive Edit}.
823
824 @item C-w
825 to delete the occurrence, and then enter a recursive editing level as
826 in @kbd{C-r}. Use the recursive edit to insert text to replace the
827 deleted occurrence of @var{string}. When done, exit the recursive
828 editing level with @kbd{C-M-c} and the next occurrence will be
829 displayed.
830
831 @item C-l
832 to redisplay the screen and then give another answer.
833
834 @item C-h
835 to display a message summarizing these options, then give another
836 answer.
837 @end table
838
839 If you type any other character, Emacs exits the @code{query-replace}, and
840 executes the character as a command. To restart the @code{query-replace},
841 use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it
842 used the minibuffer to read its arguments. @xref{Repetition, C-x ESC}.
843
844 @node Other Repeating Search,, Replace, Search
845 @section Other Search-and-Loop Commands
846
847 Here are some other commands that find matches for a regular expression.
848 They all operate from point to the end of the buffer.
849
850 @findex list-matching-lines
851 @findex occur
852 @findex count-matches
853 @findex delete-non-matching-lines
854 @findex delete-matching-lines
855 @c grosscommands
856 @table @kbd
857 @item M-x occur
858 Print each line that follows point and contains a match for the
859 specified regexp. A numeric argument specifies the number of context
860 lines to print before and after each matching line; the default is
861 none.
862
863 @kindex C-c C-c (Occur mode)
864 The buffer @samp{*Occur*} containing the output serves as a menu for
865 finding occurrences in their original context. Find an occurrence
866 as listed in @samp{*Occur*}, position point there, and type @kbd{C-c
867 C-c}; this switches to the buffer that was searched and moves point to
868 the original of the same occurrence.
869
870 @item M-x list-matching-lines
871 Synonym for @kbd{M-x occur}.
872
873 @item M-x count-matches
874 Print the number of matches following point for the specified regexp.
875
876 @item M-x delete-non-matching-lines
877 Delete each line that follows point and does not contain a match for
878 the specified regexp.
879
880 @item M-x delete-matching-lines
881 Delete each line that follows point and contains a match for the
882 specified regexp.
883 @end table