|
0
|
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
|
|
442
|
80 looking for a different occurrence of it. To move to the next occurrence
|
|
0
|
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
|
|
442
|
333 denotes a (possibly infinite) set of strings. Searching for matches
|
|
0
|
334 for a regexp is a powerful operation that editors on Unix systems have
|
|
442
|
335 traditionally offered.
|
|
|
336
|
|
|
337 To gain a thorough understanding of regular expressions and how to use
|
|
|
338 them to best advantage, we recommend that you study @cite{Mastering
|
|
|
339 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
|
|
|
340 1997}. (It's known as the "Hip Owls" book, because of the picture on its
|
|
|
341 cover.) You might also read the manuals to @ref{(gawk)Top},
|
|
|
342 @ref{(ed)Top}, @cite{sed}, @cite{grep}, @ref{(perl)Top},
|
|
|
343 @ref{(regex)Top}, @ref{(rx)Top}, @cite{pcre}, and @ref{(flex)Top}, which
|
|
|
344 also make good use of regular expressions.
|
|
|
345
|
|
|
346 The XEmacs regular expression syntax most closely resembles that of
|
|
|
347 @cite{ed}, or @cite{grep}, the GNU versions of which all utilize the GNU
|
|
|
348 @cite{regex} library. XEmacs' version of @cite{regex} has recently been
|
|
|
349 extended with some Perl--like capabilities, described in the next
|
|
|
350 section.
|
|
|
351
|
|
|
352 In XEmacs, you can search for the next match for a regexp either
|
|
|
353 incrementally or not.
|
|
0
|
354
|
|
|
355 @kindex M-C-s
|
|
442
|
356 @kindex M-C-r
|
|
0
|
357 @findex isearch-forward-regexp
|
|
|
358 @findex isearch-backward-regexp
|
|
|
359 Incremental search for a regexp is done by typing @kbd{M-C-s}
|
|
|
360 (@code{isearch-forward-regexp}). This command reads a search string
|
|
|
361 incrementally just like @kbd{C-s}, but it treats the search string as a
|
|
|
362 regexp rather than looking for an exact match against the text in the
|
|
|
363 buffer. Each time you add text to the search string, you make the regexp
|
|
|
364 longer, and the new regexp is searched for. A reverse regexp search command
|
|
442
|
365 @code{isearch-backward-regexp} also exists, bound to @kbd{M-C-r}.
|
|
0
|
366
|
|
|
367 All of the control characters that do special things within an ordinary
|
|
|
368 incremental search have the same functionality in incremental regexp search.
|
|
|
369 Typing @kbd{C-s} or @kbd{C-r} immediately after starting a search
|
|
|
370 retrieves the last incremental search regexp used:
|
|
|
371 incremental regexp and non-regexp searches have independent defaults.
|
|
|
372
|
|
|
373 @findex re-search-forward
|
|
|
374 @findex re-search-backward
|
|
|
375 Non-incremental search for a regexp is done by the functions
|
|
|
376 @code{re-search-forward} and @code{re-search-backward}. You can invoke
|
|
|
377 them with @kbd{M-x} or bind them to keys. You can also call
|
|
|
378 @code{re-search-forward} by way of incremental regexp search with
|
|
442
|
379 @kbd{M-C-s @key{RET}}; similarly for @code{re-search-backward} with
|
|
|
380 @kbd{M-C-r @key{RET}}.
|
|
0
|
381
|
|
|
382 @node Regexps, Search Case, Regexp Search, Search
|
|
|
383 @section Syntax of Regular Expressions
|
|
|
384
|
|
442
|
385 Regular expressions have a syntax in which a few characters are
|
|
|
386 special constructs and the rest are @dfn{ordinary}. An ordinary
|
|
|
387 character is a simple regular expression that matches that character and
|
|
|
388 nothing else. The special characters are @samp{.}, @samp{*}, @samp{+},
|
|
|
389 @samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
|
|
|
390 special characters will be defined in the future. Any other character
|
|
|
391 appearing in a regular expression is ordinary, unless a @samp{\}
|
|
|
392 precedes it.
|
|
0
|
393
|
|
|
394 For example, @samp{f} is not a special character, so it is ordinary, and
|
|
442
|
395 therefore @samp{f} is a regular expression that matches the string
|
|
|
396 @samp{f} and no other string. (It does @emph{not} match the string
|
|
|
397 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches
|
|
|
398 only @samp{o}.@refill
|
|
0
|
399
|
|
|
400 Any two regular expressions @var{a} and @var{b} can be concatenated. The
|
|
442
|
401 result is a regular expression that matches a string if @var{a} matches
|
|
0
|
402 some amount of the beginning of that string and @var{b} matches the rest of
|
|
|
403 the string.@refill
|
|
|
404
|
|
442
|
405 As a simple example, we can concatenate the regular expressions @samp{f}
|
|
0
|
406 and @samp{o} to get the regular expression @samp{fo}, which matches only
|
|
442
|
407 the string @samp{fo}. Still trivial. To do something more powerful, you
|
|
|
408 need to use one of the special characters. Here is a list of them:
|
|
0
|
409
|
|
442
|
410 @need 1200
|
|
0
|
411 @table @kbd
|
|
|
412 @item .@: @r{(Period)}
|
|
442
|
413 @cindex @samp{.} in regexp
|
|
0
|
414 is a special character that matches any single character except a newline.
|
|
442
|
415 Using concatenation, we can make regular expressions like @samp{a.b}, which
|
|
|
416 matches any three-character string that begins with @samp{a} and ends with
|
|
0
|
417 @samp{b}.@refill
|
|
|
418
|
|
|
419 @item *
|
|
442
|
420 @cindex @samp{*} in regexp
|
|
|
421 is not a construct by itself; it is a quantifying suffix operator that
|
|
|
422 means to repeat the preceding regular expression as many times as
|
|
0
|
423 possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
|
|
|
424 @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s.
|
|
|
425 The case of zero @samp{o}s is allowed: @samp{fo*} does match
|
|
|
426 @samp{f}.@refill
|
|
|
427
|
|
442
|
428 @samp{*} always applies to the @emph{smallest} possible preceding
|
|
0
|
429 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
|
|
|
430 repeating @samp{fo}.@refill
|
|
|
431
|
|
442
|
432 The matcher processes a @samp{*} construct by matching, immediately, as
|
|
|
433 many repetitions as can be found; it is "greedy". Then it continues
|
|
|
434 with the rest of the pattern. If that fails, backtracking occurs,
|
|
|
435 discarding some of the matches of the @samp{*}-modified construct in
|
|
|
436 case that makes it possible to match the rest of the pattern. For
|
|
|
437 example, in matching @samp{ca*ar} against the string @samp{caaar}, the
|
|
|
438 @samp{a*} first tries to match all three @samp{a}s; but the rest of the
|
|
|
439 pattern is @samp{ar} and there is only @samp{r} left to match, so this
|
|
|
440 try fails. The next alternative is for @samp{a*} to match only two
|
|
|
441 @samp{a}s. With this choice, the rest of the regexp matches
|
|
|
442 successfully.@refill
|
|
|
443
|
|
|
444 Nested repetition operators can be extremely slow if they specify
|
|
|
445 backtracking loops. For example, it could take hours for the regular
|
|
|
446 expression @samp{\(x+y*\)*a} to match the sequence
|
|
|
447 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because
|
|
|
448 Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
|
|
|
449 concluding that none of them can work. To make sure your regular
|
|
|
450 expressions run fast, check nested repetitions carefully.
|
|
0
|
451
|
|
|
452 @item +
|
|
442
|
453 @cindex @samp{+} in regexp
|
|
|
454 is a quantifying suffix operator similar to @samp{*} except that the
|
|
|
455 preceding expression must match at least once. It is also "greedy".
|
|
|
456 So, for example, @samp{ca+r} matches the strings @samp{car} and
|
|
|
457 @samp{caaaar} but not the string @samp{cr}, whereas @samp{ca*r} matches
|
|
|
458 all three strings.
|
|
0
|
459
|
|
|
460 @item ?
|
|
442
|
461 @cindex @samp{?} in regexp
|
|
|
462 is a quantifying suffix operator similar to @samp{*}, except that the
|
|
|
463 preceding expression can match either once or not at all. For example,
|
|
|
464 @samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anything
|
|
|
465 else.
|
|
|
466
|
|
|
467 @item *?
|
|
|
468 @cindex @samp{*?} in regexp
|
|
|
469 works just like @samp{*}, except that rather than matching the longest
|
|
|
470 match, it matches the shortest match. @samp{*?} is known as a
|
|
|
471 @dfn{non-greedy} quantifier, a regexp construct borrowed from Perl.
|
|
|
472 @c Did perl get this from somewhere? What's the real history of *? ?
|
|
|
473
|
|
|
474 This construct is very useful for when you want to match the text inside
|
|
|
475 a pair of delimiters. For instance, @samp{/\*.*?\*/} will match C
|
|
|
476 comments in a string. This could not easily be achieved without the use
|
|
|
477 of a non-greedy quantifier.
|
|
|
478
|
|
|
479 This construct has not been available prior to XEmacs 20.4. It is not
|
|
|
480 available in FSF Emacs.
|
|
|
481
|
|
|
482 @item +?
|
|
|
483 @cindex @samp{+?} in regexp
|
|
|
484 is the non-greedy version of @samp{+}.
|
|
|
485
|
|
|
486 @item ??
|
|
|
487 @cindex @samp{??} in regexp
|
|
|
488 is the non-greedy version of @samp{?}.
|
|
|
489
|
|
|
490 @item \@{n,m\@}
|
|
|
491 @c Note the spacing after the close brace is deliberate.
|
|
|
492 @cindex @samp{\@{n,m\@} }in regexp
|
|
|
493 serves as an interval quantifier, analogous to @samp{*} or @samp{+}, but
|
|
|
494 specifies that the expression must match at least @var{n} times, but no
|
|
|
495 more than @var{m} times. This syntax is supported by most Unix regexp
|
|
|
496 utilities, and has been introduced to XEmacs for the version 20.3.
|
|
|
497
|
|
|
498 Unfortunately, the non-greedy version of this quantifier does not exist
|
|
|
499 currently, although it does in Perl.
|
|
0
|
500
|
|
|
501 @item [ @dots{} ]
|
|
442
|
502 @cindex character set (in regexp)
|
|
|
503 @cindex @samp{[} in regexp
|
|
|
504 @cindex @samp{]} in regexp
|
|
0
|
505 @samp{[} begins a @dfn{character set}, which is terminated by a
|
|
442
|
506 @samp{]}. In the simplest case, the characters between the two brackets
|
|
|
507 form the set. Thus, @samp{[ad]} matches either one @samp{a} or one
|
|
|
508 @samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}s
|
|
|
509 and @samp{d}s (including the empty string), from which it follows that
|
|
|
510 @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
|
|
0
|
511 @samp{caddaar}, etc.@refill
|
|
|
512
|
|
442
|
513 The usual regular expression special characters are not special inside a
|
|
|
514 character set. A completely different set of special characters exists
|
|
|
515 inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
|
|
|
516
|
|
|
517 @samp{-} is used for ranges of characters. To write a range, write two
|
|
0
|
518 characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any
|
|
442
|
519 lower case letter. Ranges may be intermixed freely with individual
|
|
|
520 characters, as in @samp{[a-z$%.]}, which matches any lower case letter
|
|
|
521 or @samp{$}, @samp{%}, or a period.@refill
|
|
0
|
522
|
|
442
|
523 To include a @samp{]} in a character set, make it the first character.
|
|
|
524 For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a
|
|
|
525 @samp{-}, write @samp{-} as the first character in the set, or put it
|
|
|
526 immediately after a range. (You can replace one individual character
|
|
|
527 @var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the
|
|
|
528 @samp{-}.) There is no way to write a set containing just @samp{-} and
|
|
|
529 @samp{]}.
|
|
0
|
530
|
|
442
|
531 To include @samp{^} in a set, put it anywhere but at the beginning of
|
|
|
532 the set.
|
|
0
|
533
|
|
|
534 @item [^ @dots{} ]
|
|
442
|
535 @cindex @samp{^} in regexp
|
|
0
|
536 @samp{[^} begins a @dfn{complement character set}, which matches any
|
|
|
537 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
|
|
442
|
538 matches all characters @emph{except} letters and digits.@refill
|
|
0
|
539
|
|
|
540 @samp{^} is not special in a character set unless it is the first
|
|
|
541 character. The character following the @samp{^} is treated as if it
|
|
442
|
542 were first (thus, @samp{-} and @samp{]} are not special there).
|
|
0
|
543
|
|
|
544 Note that a complement character set can match a newline, unless
|
|
|
545 newline is mentioned as one of the characters not to match.
|
|
|
546
|
|
|
547 @item ^
|
|
442
|
548 @cindex @samp{^} in regexp
|
|
|
549 @cindex beginning of line in regexp
|
|
|
550 is a special character that matches the empty string, but only at the
|
|
|
551 beginning of a line in the text being matched. Otherwise it fails to
|
|
|
552 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
|
|
|
553 the beginning of a line.
|
|
|
554
|
|
|
555 When matching a string instead of a buffer, @samp{^} matches at the
|
|
|
556 beginning of the string or after a newline character @samp{\n}.
|
|
0
|
557
|
|
|
558 @item $
|
|
442
|
559 @cindex @samp{$} in regexp
|
|
0
|
560 is similar to @samp{^} but matches only at the end of a line. Thus,
|
|
442
|
561 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
|
|
|
562
|
|
|
563 When matching a string instead of a buffer, @samp{$} matches at the end
|
|
|
564 of the string or before a newline character @samp{\n}.
|
|
0
|
565
|
|
|
566 @item \
|
|
442
|
567 @cindex @samp{\} in regexp
|
|
|
568 has two functions: it quotes the special characters (including
|
|
0
|
569 @samp{\}), and it introduces additional special constructs.
|
|
|
570
|
|
|
571 Because @samp{\} quotes special characters, @samp{\$} is a regular
|
|
|
572 expression that matches only @samp{$}, and @samp{\[} is a regular
|
|
442
|
573 expression that matches only @samp{[}, and so on.
|
|
|
574
|
|
|
575 @c Removed a paragraph here in lispref about doubling backslashes inside
|
|
|
576 @c of Lisp strings.
|
|
|
577
|
|
0
|
578 @end table
|
|
|
579
|
|
442
|
580 @strong{Please note:} For historical compatibility, special characters
|
|
|
581 are treated as ordinary ones if they are in contexts where their special
|
|
|
582 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
|
|
|
583 ordinary since there is no preceding expression on which the @samp{*}
|
|
|
584 can act. It is poor practice to depend on this behavior; quote the
|
|
|
585 special character anyway, regardless of where it appears.@refill
|
|
0
|
586
|
|
442
|
587 For the most part, @samp{\} followed by any character matches only
|
|
0
|
588 that character. However, there are several exceptions: characters
|
|
442
|
589 that, when preceded by @samp{\}, are special constructs. Such
|
|
0
|
590 characters are always ordinary when encountered on their own. Here
|
|
442
|
591 is a table of @samp{\} constructs:
|
|
0
|
592
|
|
|
593 @table @kbd
|
|
|
594 @item \|
|
|
442
|
595 @cindex @samp{|} in regexp
|
|
|
596 @cindex regexp alternative
|
|
0
|
597 specifies an alternative.
|
|
|
598 Two regular expressions @var{a} and @var{b} with @samp{\|} in
|
|
442
|
599 between form an expression that matches anything that either @var{a} or
|
|
0
|
600 @var{b} matches.@refill
|
|
|
601
|
|
|
602 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
|
|
|
603 but no other string.@refill
|
|
|
604
|
|
|
605 @samp{\|} applies to the largest possible surrounding expressions. Only a
|
|
|
606 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
|
|
|
607 @samp{\|}.@refill
|
|
|
608
|
|
|
609 Full backtracking capability exists to handle multiple uses of @samp{\|}.
|
|
|
610
|
|
|
611 @item \( @dots{} \)
|
|
442
|
612 @cindex @samp{(} in regexp
|
|
|
613 @cindex @samp{)} in regexp
|
|
|
614 @cindex regexp grouping
|
|
0
|
615 is a grouping construct that serves three purposes:
|
|
|
616
|
|
|
617 @enumerate
|
|
|
618 @item
|
|
|
619 To enclose a set of @samp{\|} alternatives for other operations.
|
|
|
620 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
|
|
|
621
|
|
|
622 @item
|
|
442
|
623 To enclose an expression for a suffix operator such as @samp{*} to act
|
|
|
624 on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any
|
|
|
625 (zero or more) number of @samp{na} strings.@refill
|
|
0
|
626
|
|
|
627 @item
|
|
442
|
628 To record a matched substring for future reference.
|
|
0
|
629 @end enumerate
|
|
|
630
|
|
|
631 This last application is not a consequence of the idea of a
|
|
442
|
632 parenthetical grouping; it is a separate feature that happens to be
|
|
0
|
633 assigned as a second meaning to the same @samp{\( @dots{} \)} construct
|
|
442
|
634 because there is no conflict in practice between the two meanings.
|
|
|
635 Here is an explanation of this feature:
|
|
0
|
636
|
|
|
637 @item \@var{digit}
|
|
442
|
638 matches the same text that matched the @var{digit}th occurrence of a
|
|
|
639 @samp{\( @dots{} \)} construct.
|
|
0
|
640
|
|
442
|
641 In other words, after the end of a @samp{\( @dots{} \)} construct. the
|
|
|
642 matcher remembers the beginning and end of the text matched by that
|
|
|
643 construct. Then, later on in the regular expression, you can use
|
|
|
644 @samp{\} followed by @var{digit} to match that same text, whatever it
|
|
|
645 may have been.
|
|
|
646
|
|
|
647 The strings matching the first nine @samp{\( @dots{} \)} constructs
|
|
|
648 appearing in a regular expression are assigned numbers 1 through 9 in
|
|
|
649 the order that the open parentheses appear in the regular expression.
|
|
|
650 So you can use @samp{\1} through @samp{\9} to refer to the text matched
|
|
|
651 by the corresponding @samp{\( @dots{} \)} constructs.
|
|
0
|
652
|
|
|
653 For example, @samp{\(.*\)\1} matches any newline-free string that is
|
|
|
654 composed of two identical halves. The @samp{\(.*\)} matches the first
|
|
|
655 half, which may be anything, but the @samp{\1} that follows must match
|
|
|
656 the same exact text.
|
|
|
657
|
|
442
|
658 @item \(?: @dots{} \)
|
|
|
659 @cindex @samp{\(?:} in regexp
|
|
|
660 @cindex regexp grouping
|
|
|
661 is called a @dfn{shy} grouping operator, and it is used just like
|
|
|
662 @samp{\( @dots{} \)}, except that it does not cause the matched
|
|
|
663 substring to be recorded for future reference.
|
|
|
664
|
|
|
665 This is useful when you need a lot of grouping @samp{\( @dots{} \)}
|
|
|
666 constructs, but only want to remember one or two -- or if you have
|
|
|
667 more than nine groupings and need to use backreferences to refer to
|
|
|
668 the groupings at the end.
|
|
|
669
|
|
|
670 Using @samp{\(?: @dots{} \)} rather than @samp{\( @dots{} \)} when you
|
|
|
671 don't need the captured substrings ought to speed up your programs some,
|
|
|
672 since it shortens the code path followed by the regular expression
|
|
|
673 engine, as well as the amount of memory allocation and string copying it
|
|
|
674 must do. The actual performance gain to be observed has not been
|
|
|
675 measured or quantified as of this writing.
|
|
|
676 @c This is used to good advantage by the font-locking code, and by
|
|
|
677 @c `regexp-opt.el'.
|
|
|
678
|
|
|
679 The shy grouping operator has been borrowed from Perl, and has not been
|
|
|
680 available prior to XEmacs 20.3, nor is it available in FSF Emacs.
|
|
|
681
|
|
|
682 @item \w
|
|
|
683 @cindex @samp{\w} in regexp
|
|
|
684 matches any word-constituent character. The editor syntax table
|
|
|
685 determines which characters these are. @xref{Syntax}.
|
|
|
686
|
|
|
687 @item \W
|
|
|
688 @cindex @samp{\W} in regexp
|
|
|
689 matches any character that is not a word constituent.
|
|
|
690
|
|
|
691 @item \s@var{code}
|
|
|
692 @cindex @samp{\s} in regexp
|
|
|
693 matches any character whose syntax is @var{code}. Here @var{code} is a
|
|
|
694 character that represents a syntax code: thus, @samp{w} for word
|
|
|
695 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
|
|
|
696 etc. @xref{Syntax}, for a list of syntax codes and the characters that
|
|
|
697 stand for them.
|
|
|
698
|
|
|
699 @item \S@var{code}
|
|
|
700 @cindex @samp{\S} in regexp
|
|
|
701 matches any character whose syntax is not @var{code}.
|
|
|
702 @end table
|
|
|
703
|
|
|
704 The following regular expression constructs match the empty string---that is,
|
|
|
705 they don't use up any characters---but whether they match depends on the
|
|
|
706 context.
|
|
|
707
|
|
|
708 @table @kbd
|
|
0
|
709 @item \`
|
|
442
|
710 @cindex @samp{\`} in regexp
|
|
|
711 matches the empty string, but only at the beginning
|
|
|
712 of the buffer or string being matched against.
|
|
0
|
713
|
|
|
714 @item \'
|
|
442
|
715 @cindex @samp{\'} in regexp
|
|
|
716 matches the empty string, but only at the end of
|
|
|
717 the buffer or string being matched against.
|
|
|
718
|
|
|
719 @item \=
|
|
|
720 @cindex @samp{\=} in regexp
|
|
|
721 matches the empty string, but only at point.
|
|
|
722 (This construct is not defined when matching against a string.)
|
|
0
|
723
|
|
|
724 @item \b
|
|
442
|
725 @cindex @samp{\b} in regexp
|
|
|
726 matches the empty string, but only at the beginning or
|
|
0
|
727 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
|
|
|
728 @samp{foo} as a separate word. @samp{\bballs?\b} matches
|
|
|
729 @samp{ball} or @samp{balls} as a separate word.@refill
|
|
|
730
|
|
|
731 @item \B
|
|
442
|
732 @cindex @samp{\B} in regexp
|
|
|
733 matches the empty string, but @emph{not} at the beginning or
|
|
0
|
734 end of a word.
|
|
|
735
|
|
|
736 @item \<
|
|
442
|
737 @cindex @samp{\<} in regexp
|
|
|
738 matches the empty string, but only at the beginning of a word.
|
|
0
|
739
|
|
|
740 @item \>
|
|
442
|
741 @cindex @samp{\>} in regexp
|
|
|
742 matches the empty string, but only at the end of a word.
|
|
0
|
743 @end table
|
|
|
744
|
|
|
745 Here is a complicated regexp used by Emacs to recognize the end of a
|
|
|
746 sentence together with any whitespace that follows. It is given in Lisp
|
|
|
747 syntax to enable you to distinguish the spaces from the tab characters. In
|
|
|
748 Lisp syntax, the string constant begins and ends with a double-quote.
|
|
|
749 @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
|
|
|
750 backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
|
|
|
751 newline.
|
|
|
752
|
|
|
753 @example
|
|
|
754 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
|
|
|
755 @end example
|
|
|
756
|
|
|
757 @noindent
|
|
|
758 This regexp contains four parts: a character set matching
|
|
|
759 period, @samp{?} or @samp{!}; a character set matching close-brackets,
|
|
|
760 quotes or parentheses, repeated any number of times; an alternative in
|
|
|
761 backslash-parentheses that matches end-of-line, a tab or two spaces; and
|
|
|
762 a character set matching whitespace characters, repeated any number of
|
|
|
763 times.
|
|
|
764
|
|
|
765 @node Search Case, Replace, Regexps, Search
|
|
|
766 @section Searching and Case
|
|
|
767
|
|
|
768 @vindex case-fold-search
|
|
|
769 All searches in Emacs normally ignore the case of the text they
|
|
|
770 are searching through; if you specify searching for @samp{FOO},
|
|
|
771 @samp{Foo} and @samp{foo} are also considered a match. Regexps, and in
|
|
|
772 particular character sets, are included: @samp{[aB]} matches @samp{a}
|
|
|
773 or @samp{A} or @samp{b} or @samp{B}.@refill
|
|
|
774
|
|
|
775 If you want a case-sensitive search, set the variable
|
|
|
776 @code{case-fold-search} to @code{nil}. Then all letters must match
|
|
|
777 exactly, including case. @code{case-fold-search} is a per-buffer
|
|
|
778 variable; altering it affects only the current buffer, but
|
|
|
779 there is a default value which you can change as well. @xref{Locals}.
|
|
|
780 You can also use @b{Case Sensitive Search} from the @b{Options} menu
|
|
|
781 on your screen.
|
|
|
782
|
|
|
783 @node Replace, Other Repeating Search, Search Case, Search
|
|
|
784 @section Replacement Commands
|
|
|
785 @cindex replacement
|
|
|
786 @cindex string substitution
|
|
|
787 @cindex global substitution
|
|
|
788
|
|
|
789 Global search-and-replace operations are not needed as often in Emacs as
|
|
|
790 they are in other editors, but they are available. In addition to the
|
|
|
791 simple @code{replace-string} command which is like that found in most
|
|
|
792 editors, there is a @code{query-replace} command which asks you, for each
|
|
|
793 occurrence of a pattern, whether to replace it.
|
|
|
794
|
|
|
795 The replace commands all replace one string (or regexp) with one
|
|
|
796 replacement string. It is possible to perform several replacements in
|
|
|
797 parallel using the command @code{expand-region-abbrevs}. @xref{Expanding
|
|
|
798 Abbrevs}.
|
|
|
799
|
|
|
800 @menu
|
|
|
801 * Unconditional Replace:: Replacing all matches for a string.
|
|
|
802 * Regexp Replace:: Replacing all matches for a regexp.
|
|
|
803 * Replacement and Case:: How replacements preserve case of letters.
|
|
|
804 * Query Replace:: How to use querying.
|
|
|
805 @end menu
|
|
|
806
|
|
|
807 @node Unconditional Replace, Regexp Replace, Replace, Replace
|
|
|
808 @subsection Unconditional Replacement
|
|
|
809 @findex replace-string
|
|
|
810 @findex replace-regexp
|
|
|
811
|
|
|
812 @table @kbd
|
|
|
813 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
|
|
|
814 Replace every occurrence of @var{string} with @var{newstring}.
|
|
|
815 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
|
|
|
816 Replace every match for @var{regexp} with @var{newstring}.
|
|
|
817 @end table
|
|
|
818
|
|
|
819 To replace every instance of @samp{foo} after point with @samp{bar},
|
|
|
820 use the command @kbd{M-x replace-string} with the two arguments
|
|
|
821 @samp{foo} and @samp{bar}. Replacement occurs only after point: if you
|
|
|
822 want to cover the whole buffer you must go to the beginning first. By
|
|
|
823 default, all occurrences up to the end of the buffer are replaced. To
|
|
|
824 limit replacement to part of the buffer, narrow to that part of the
|
|
|
825 buffer before doing the replacement (@pxref{Narrowing}).
|
|
|
826
|
|
|
827 When @code{replace-string} exits, point is left at the last occurrence
|
|
|
828 replaced. The value of point when the @code{replace-string} command was
|
|
|
829 issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back
|
|
|
830 there.
|
|
|
831
|
|
|
832 A numeric argument restricts replacement to matches that are surrounded
|
|
|
833 by word boundaries.
|
|
|
834
|
|
|
835 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
|
|
|
836 @subsection Regexp Replacement
|
|
|
837
|
|
|
838 @code{replace-string} replaces exact matches for a single string. The
|
|
|
839 similar command @code{replace-regexp} replaces any match for a specified
|
|
|
840 pattern.
|
|
|
841
|
|
|
842 In @code{replace-regexp}, the @var{newstring} need not be constant. It
|
|
|
843 can refer to all or part of what is matched by the @var{regexp}. @samp{\&}
|
|
|
844 in @var{newstring} stands for the entire text being replaced.
|
|
|
845 @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
|
|
|
846 whatever matched the @var{d}'th parenthesized grouping in @var{regexp}.
|
|
|
847 For example,@refill
|
|
|
848
|
|
|
849 @example
|
|
|
850 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
|
|
|
851 @end example
|
|
|
852
|
|
|
853 @noindent
|
|
|
854 would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
|
|
|
855 with @samp{cddr-safe}.
|
|
|
856
|
|
|
857 @example
|
|
|
858 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
|
|
|
859 @end example
|
|
|
860
|
|
|
861 @noindent
|
|
|
862 would perform exactly the opposite replacements. To include a @samp{\}
|
|
|
863 in the text to replace with, you must give @samp{\\}.
|
|
|
864
|
|
|
865 @node Replacement and Case, Query Replace, Regexp Replace, Replace
|
|
|
866 @subsection Replace Commands and Case
|
|
|
867
|
|
|
868 @vindex case-replace
|
|
|
869 @vindex case-fold-search
|
|
|
870 If the arguments to a replace command are in lower case, the command
|
|
|
871 preserves case when it makes a replacement. Thus, the following command:
|
|
|
872
|
|
|
873 @example
|
|
|
874 M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
|
|
|
875 @end example
|
|
|
876
|
|
|
877 @noindent
|
|
|
878 replaces a lower-case @samp{foo} with a lower case @samp{bar}, @samp{FOO}
|
|
|
879 with @samp{BAR}, and @samp{Foo} with @samp{Bar}. If upper-case letters are
|
|
|
880 used in the second argument, they remain upper-case every time that
|
|
|
881 argument is inserted. If upper-case letters are used in the first
|
|
|
882 argument, the second argument is always substituted exactly as given, with
|
|
|
883 no case conversion. Likewise, if the variable @code{case-replace} is set
|
|
|
884 to @code{nil}, replacement is done without case conversion. If
|
|
|
885 @code{case-fold-search} is set to @code{nil}, case is significant in
|
|
|
886 matching occurrences of @samp{foo} to replace; also, case conversion of the
|
|
|
887 replacement string is not done.
|
|
|
888
|
|
|
889 @node Query Replace,, Replacement and Case, Replace
|
|
|
890 @subsection Query Replace
|
|
|
891 @cindex query replace
|
|
|
892
|
|
|
893 @table @kbd
|
|
|
894 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
|
|
|
895 @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
|
|
|
896 Replace some occurrences of @var{string} with @var{newstring}.
|
|
|
897 @item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
|
|
|
898 Replace some matches for @var{regexp} with @var{newstring}.
|
|
|
899 @end table
|
|
|
900
|
|
|
901 @kindex M-%
|
|
|
902 @findex query-replace
|
|
|
903 If you want to change only some of the occurrences of @samp{foo} to
|
|
|
904 @samp{bar}, not all of them, you can use @code{query-replace} instead of
|
|
|
905 @kbd{M-%}. This command finds occurrences of @samp{foo} one by one,
|
|
|
906 displays each occurrence, and asks you whether to replace it. A numeric
|
|
|
907 argument to @code{query-replace} tells it to consider only occurrences
|
|
|
908 that are bounded by word-delimiter characters.@refill
|
|
|
909
|
|
|
910 @findex query-replace-regexp
|
|
|
911 Aside from querying, @code{query-replace} works just like
|
|
|
912 @code{replace-string}, and @code{query-replace-regexp} works
|
|
|
913 just like @code{replace-regexp}.@refill
|
|
|
914
|
|
|
915 The things you can type when you are shown an occurrence of @var{string}
|
|
|
916 or a match for @var{regexp} are:
|
|
|
917
|
|
|
918 @kindex SPC (query-replace)
|
|
|
919 @kindex DEL (query-replace)
|
|
|
920 @kindex , (query-replace)
|
|
|
921 @kindex ESC (query-replace)
|
|
|
922 @kindex . (query-replace)
|
|
|
923 @kindex ! (query-replace)
|
|
|
924 @kindex ^ (query-replace)
|
|
|
925 @kindex C-r (query-replace)
|
|
|
926 @kindex C-w (query-replace)
|
|
|
927 @kindex C-l (query-replace)
|
|
|
928
|
|
|
929 @c WideCommands
|
|
|
930 @table @kbd
|
|
|
931 @item @key{SPC}
|
|
|
932 to replace the occurrence with @var{newstring}. This preserves case, just
|
|
|
933 like @code{replace-string}, provided @code{case-replace} is non-@code{nil},
|
|
|
934 as it normally is.@refill
|
|
|
935
|
|
|
936 @item @key{DEL}
|
|
|
937 to skip to the next occurrence without replacing this one.
|
|
|
938
|
|
|
939 @item , @r{(Comma)}
|
|
|
940 to replace this occurrence and display the result. You are then
|
|
|
941 prompted for another input character. However, since the replacement has
|
|
|
942 already been made, @key{DEL} and @key{SPC} are equivalent. At this
|
|
|
943 point, you can type @kbd{C-r} (see below) to alter the replaced text. To
|
|
|
944 undo the replacement, you can type @kbd{C-x u}.
|
|
|
945 This exits the @code{query-replace}. If you want to do further
|
|
|
946 replacement you must use @kbd{C-x ESC} to restart (@pxref{Repetition}).
|
|
|
947
|
|
|
948 @item @key{ESC}
|
|
|
949 to exit without doing any more replacements.
|
|
|
950
|
|
|
951 @item .@: @r{(Period)}
|
|
|
952 to replace this occurrence and then exit.
|
|
|
953
|
|
|
954 @item !
|
|
|
955 to replace all remaining occurrences without asking again.
|
|
|
956
|
|
|
957 @item ^
|
|
|
958 to go back to the location of the previous occurrence (or what used to
|
|
|
959 be an occurrence), in case you changed it by mistake. This works by
|
|
|
960 popping the mark ring. Only one @kbd{^} in a row is allowed, because
|
|
|
961 only one previous replacement location is kept during @code{query-replace}.
|
|
|
962
|
|
|
963 @item C-r
|
|
|
964 to enter a recursive editing level, in case the occurrence needs to be
|
|
|
965 edited rather than just replaced with @var{newstring}. When you are
|
|
|
966 done, exit the recursive editing level with @kbd{C-M-c} and the next
|
|
|
967 occurrence will be displayed. @xref{Recursive Edit}.
|
|
|
968
|
|
|
969 @item C-w
|
|
|
970 to delete the occurrence, and then enter a recursive editing level as
|
|
|
971 in @kbd{C-r}. Use the recursive edit to insert text to replace the
|
|
|
972 deleted occurrence of @var{string}. When done, exit the recursive
|
|
|
973 editing level with @kbd{C-M-c} and the next occurrence will be
|
|
|
974 displayed.
|
|
|
975
|
|
|
976 @item C-l
|
|
|
977 to redisplay the screen and then give another answer.
|
|
|
978
|
|
|
979 @item C-h
|
|
|
980 to display a message summarizing these options, then give another
|
|
|
981 answer.
|
|
|
982 @end table
|
|
|
983
|
|
|
984 If you type any other character, Emacs exits the @code{query-replace}, and
|
|
|
985 executes the character as a command. To restart the @code{query-replace},
|
|
|
986 use @kbd{C-x @key{ESC}}, which repeats the @code{query-replace} because it
|
|
|
987 used the minibuffer to read its arguments. @xref{Repetition, C-x ESC}.
|
|
|
988
|
|
|
989 @node Other Repeating Search,, Replace, Search
|
|
|
990 @section Other Search-and-Loop Commands
|
|
|
991
|
|
|
992 Here are some other commands that find matches for a regular expression.
|
|
|
993 They all operate from point to the end of the buffer.
|
|
|
994
|
|
|
995 @findex list-matching-lines
|
|
|
996 @findex occur
|
|
|
997 @findex count-matches
|
|
|
998 @findex delete-non-matching-lines
|
|
|
999 @findex delete-matching-lines
|
|
|
1000 @c grosscommands
|
|
|
1001 @table @kbd
|
|
|
1002 @item M-x occur
|
|
|
1003 Print each line that follows point and contains a match for the
|
|
|
1004 specified regexp. A numeric argument specifies the number of context
|
|
|
1005 lines to print before and after each matching line; the default is
|
|
|
1006 none.
|
|
|
1007
|
|
|
1008 @kindex C-c C-c (Occur mode)
|
|
|
1009 The buffer @samp{*Occur*} containing the output serves as a menu for
|
|
|
1010 finding occurrences in their original context. Find an occurrence
|
|
|
1011 as listed in @samp{*Occur*}, position point there, and type @kbd{C-c
|
|
|
1012 C-c}; this switches to the buffer that was searched and moves point to
|
|
|
1013 the original of the same occurrence.
|
|
|
1014
|
|
|
1015 @item M-x list-matching-lines
|
|
|
1016 Synonym for @kbd{M-x occur}.
|
|
|
1017
|
|
|
1018 @item M-x count-matches
|
|
|
1019 Print the number of matches following point for the specified regexp.
|
|
|
1020
|
|
|
1021 @item M-x delete-non-matching-lines
|
|
|
1022 Delete each line that follows point and does not contain a match for
|
|
|
1023 the specified regexp.
|
|
|
1024
|
|
|
1025 @item M-x delete-matching-lines
|
|
|
1026 Delete each line that follows point and contains a match for the
|
|
|
1027 specified regexp.
|
|
|
1028 @end table
|
