Mercurial > emacs
comparison man/search.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | 2eca4c95c2bf |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 @c This is part of the Emacs manual. | 1 @c This is part of the Emacs manual. |
2 @c Copyright (C) 1985, 86, 87, 93, 94, 95, 97, 2000, 2001 | 2 @c Copyright (C) 1985, 1986, 1987, 1993, 1994, 1995, 1997, 2000, 2001, 2002, |
3 @c Free Software Foundation, Inc. | 3 @c 2003, 2004, 2005 Free Software Foundation, Inc. |
4 @c See file emacs.texi for copying conditions. | 4 @c See file emacs.texi for copying conditions. |
5 @node Search, Fixit, Display, Top | 5 @node Search, Fixit, Display, Top |
6 @chapter Searching and Replacement | 6 @chapter Searching and Replacement |
7 @cindex searching | 7 @cindex searching |
8 @cindex finding strings within text | 8 @cindex finding strings within text |
17 occurrences of one string and replaces them with another, Emacs has a | 17 occurrences of one string and replaces them with another, Emacs has a |
18 more flexible replacement command called @code{query-replace}, which | 18 more flexible replacement command called @code{query-replace}, which |
19 asks interactively which occurrences to replace. | 19 asks interactively which occurrences to replace. |
20 | 20 |
21 @menu | 21 @menu |
22 * Incremental Search:: Search happens as you type the string. | 22 * Incremental Search:: Search happens as you type the string. |
23 * Nonincremental Search:: Specify entire string and then search. | 23 * Nonincremental Search:: Specify entire string and then search. |
24 * Word Search:: Search for sequence of words. | 24 * Word Search:: Search for sequence of words. |
25 * Regexp Search:: Search for match for a regexp. | 25 * Regexp Search:: Search for match for a regexp. |
26 * Regexps:: Syntax of regular expressions. | 26 * Regexps:: Syntax of regular expressions. |
27 * Search Case:: To ignore case while searching, or not. | 27 * Regexp Backslash:: Regular expression constructs starting with `\'. |
28 * Replace:: Search, and replace some or all matches. | 28 * Regexp Example:: A complex regular expression explained. |
29 * Other Repeating Search:: Operating on all matches for some regexp. | 29 * Search Case:: To ignore case while searching, or not. |
30 * Replace:: Search, and replace some or all matches. | |
31 * Other Repeating Search:: Operating on all matches for some regexp. | |
30 @end menu | 32 @end menu |
31 | 33 |
32 @node Incremental Search, Nonincremental Search, Search, Search | 34 @node Incremental Search |
33 @section Incremental Search | 35 @section Incremental Search |
34 | 36 |
35 @cindex incremental search | |
36 An incremental search begins searching as soon as you type the first | 37 An incremental search begins searching as soon as you type the first |
37 character of the search string. As you type in the search string, Emacs | 38 character of the search string. As you type in the search string, Emacs |
38 shows you where the string (as you have typed it so far) would be | 39 shows you where the string (as you have typed it so far) would be |
39 found. When you have typed enough characters to identify the place you | 40 found. When you have typed enough characters to identify the place you |
40 want, you can stop. Depending on what you plan to do next, you may or | 41 want, you can stop. Depending on what you plan to do next, you may or |
45 @item C-s | 46 @item C-s |
46 Incremental search forward (@code{isearch-forward}). | 47 Incremental search forward (@code{isearch-forward}). |
47 @item C-r | 48 @item C-r |
48 Incremental search backward (@code{isearch-backward}). | 49 Incremental search backward (@code{isearch-backward}). |
49 @end table | 50 @end table |
51 | |
52 @menu | |
53 * Basic Isearch:: Basic incremental search commands. | |
54 * Repeat Isearch:: Searching for the same string again. | |
55 * Error in Isearch:: When your string is not found. | |
56 * Special Isearch:: Special input in incremental search. | |
57 * Non-ASCII Isearch:: How to search for non-ASCII characters. | |
58 * Isearch Yank:: Commands that grab text into the search string | |
59 or else edit the search string. | |
60 * Highlight Isearch:: Isearch highlights the other possible matches. | |
61 * Isearch Scroll:: Scrolling during an incremental search. | |
62 * Slow Isearch:: Incremental search features for slow terminals. | |
63 @end menu | |
64 | |
65 @node Basic Isearch | |
66 @subsection Basics of Incremental Search | |
67 @cindex incremental search | |
50 | 68 |
51 @kindex C-s | 69 @kindex C-s |
52 @findex isearch-forward | 70 @findex isearch-forward |
53 @kbd{C-s} starts a forward incremental search. It reads characters | 71 @kbd{C-s} starts a forward incremental search. It reads characters |
54 from the keyboard, and moves point past the next occurrence of those | 72 from the keyboard, and moves point past the next occurrence of those |
75 stops the searching and is then executed. Thus, typing @kbd{C-a} | 93 stops the searching and is then executed. Thus, typing @kbd{C-a} |
76 would exit the search and then move to the beginning of the line. | 94 would exit the search and then move to the beginning of the line. |
77 @key{RET} is necessary only if the next command you want to type is a | 95 @key{RET} is necessary only if the next command you want to type is a |
78 printing character, @key{DEL}, @key{RET}, or another character that is | 96 printing character, @key{DEL}, @key{RET}, or another character that is |
79 special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, | 97 special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, |
80 @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-s}, and some other | 98 @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, @kbd{M-c}, @kbd{M-e}, and some other |
81 meta-characters). | 99 meta-characters). |
100 | |
101 When you exit the incremental search, it sets the mark where point | |
102 @emph{was} before the search. That is convenient for moving back | |
103 there. In Transient Mark mode, incremental search sets the mark | |
104 without activating it, and does so only if the mark is not already | |
105 active. | |
106 | |
107 @node Repeat Isearch | |
108 @subsection Repeating Incremental Search | |
82 | 109 |
83 Sometimes you search for @samp{FOO} and find one, but not the one you | 110 Sometimes you search for @samp{FOO} and find one, but not the one you |
84 expected to find. There was a second @samp{FOO} that you forgot | 111 expected to find. There was a second @samp{FOO} that you forgot |
85 about, before the one you were aiming for. In this event, type | 112 about, before the one you were aiming for. In this event, type |
86 another @kbd{C-s} to move to the next occurrence of the search string. | 113 another @kbd{C-s} to move to the next occurrence of the search string. |
89 | 116 |
90 After you exit a search, you can search for the same string again by | 117 After you exit a search, you can search for the same string again by |
91 typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes | 118 typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes |
92 incremental search, and the second @kbd{C-s} means ``search again.'' | 119 incremental search, and the second @kbd{C-s} means ``search again.'' |
93 | 120 |
121 If a search is failing and you ask to repeat it by typing another | |
122 @kbd{C-s}, it starts again from the beginning of the buffer. | |
123 Repeating a failing reverse search with @kbd{C-r} starts again from | |
124 the end. This is called @dfn{wrapping around}, and @samp{Wrapped} | |
125 appears in the search prompt once this has happened. If you keep on | |
126 going past the original starting point of the search, it changes to | |
127 @samp{Overwrapped}, which means that you are revisiting matches that | |
128 you have already seen. | |
129 | |
94 To reuse earlier search strings, use the @dfn{search ring}. The | 130 To reuse earlier search strings, use the @dfn{search ring}. The |
95 commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search | 131 commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search |
96 string to reuse. These commands leave the selected search ring element | 132 string to reuse. These commands leave the selected search ring element |
97 in the minibuffer, where you can edit it. Type @kbd{C-s} or @kbd{C-r} | 133 in the minibuffer, where you can edit it. To edit the current search |
134 string in the minibuffer without replacing it with items from the | |
135 search ring, type @kbd{M-e}. Type @kbd{C-s} or @kbd{C-r} | |
98 to terminate editing the string and search for it. | 136 to terminate editing the string and search for it. |
137 | |
138 You can change to searching backwards with @kbd{C-r}. If a search fails | |
139 because the place you started was too late in the file, you should do this. | |
140 Repeated @kbd{C-r} keeps looking for more occurrences backwards. A | |
141 @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be canceled | |
142 with @key{DEL}. | |
143 | |
144 @kindex C-r | |
145 @findex isearch-backward | |
146 If you know initially that you want to search backwards, you can use | |
147 @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as | |
148 a key runs a command (@code{isearch-backward}) to search backward. A | |
149 backward search finds matches that are entirely before the starting | |
150 point, just as a forward search finds matches that begin after it. | |
151 | |
152 @node Error in Isearch | |
153 @subsection Errors in Incremental Search | |
99 | 154 |
100 If your string is not found at all, the echo area says @samp{Failing | 155 If your string is not found at all, the echo area says @samp{Failing |
101 I-Search}. The cursor is after the place where Emacs found as much of your | 156 I-Search}. The cursor is after the place where Emacs found as much of your |
102 string as it could. Thus, if you search for @samp{FOOT}, and there is no | 157 string as it could. Thus, if you search for @samp{FOOT}, and there is no |
103 @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}. | 158 @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}. |
108 removes from the search string the characters that could not be found (the | 163 removes from the search string the characters that could not be found (the |
109 @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in | 164 @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in |
110 @samp{FOOT}). A second @kbd{C-g} at that point cancels the search | 165 @samp{FOOT}). A second @kbd{C-g} at that point cancels the search |
111 entirely, returning point to where it was when the search started. | 166 entirely, returning point to where it was when the search started. |
112 | 167 |
113 An upper-case letter in the search string makes the search | |
114 case-sensitive. If you delete the upper-case character from the search | |
115 string, it ceases to have this effect. @xref{Search Case}. | |
116 | |
117 To search for a newline, type @kbd{C-j}. To search for another | |
118 control character, such as control-S or carriage return, you must quote | |
119 it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous | |
120 to its use for insertion (@pxref{Inserting Text}): it causes the | |
121 following character to be treated the way any ``ordinary'' character is | |
122 treated in the same context. You can also specify a character by its | |
123 octal code: enter @kbd{C-q} followed by a sequence of octal digits. | |
124 | |
125 @cindex searching for non-ASCII characters | |
126 @cindex input method, during incremental search | |
127 To search for non-ASCII characters, you must use an input method | |
128 (@pxref{Input Methods}). If an input method is enabled in the | |
129 current buffer when you start the search, you can use it while you | |
130 type the search string also. Emacs indicates that by including the | |
131 input method mnemonic in its prompt, like this: | |
132 | |
133 @example | |
134 I-search [@var{im}]: | |
135 @end example | |
136 | |
137 @noindent | |
138 @findex isearch-toggle-input-method | |
139 @findex isearch-toggle-specified-input-method | |
140 where @var{im} is the mnemonic of the active input method. You can | |
141 toggle (enable or disable) the input method while you type the search | |
142 string with @kbd{C-\} (@code{isearch-toggle-input-method}). You can | |
143 turn on a certain (non-default) input method with @kbd{C-^} | |
144 (@code{isearch-toggle-specified-input-method}), which prompts for the | |
145 name of the input method. The input method you enable during | |
146 incremental search remains enabled in the current buffer afterwards. | |
147 | |
148 If a search is failing and you ask to repeat it by typing another | |
149 @kbd{C-s}, it starts again from the beginning of the buffer. | |
150 Repeating a failing reverse search with @kbd{C-r} starts again from | |
151 the end. This is called @dfn{wrapping around}, and @samp{Wrapped} | |
152 appears in the search prompt once this has happened. If you keep on | |
153 going past the original starting point of the search, it changes to | |
154 @samp{Overwrapped}, which means that you are revisiting matches that | |
155 you have already seen. | |
156 | |
157 @cindex quitting (in search) | 168 @cindex quitting (in search) |
158 The @kbd{C-g} ``quit'' character does special things during searches; | 169 The @kbd{C-g} ``quit'' character does special things during searches; |
159 just what it does depends on the status of the search. If the search has | 170 just what it does depends on the status of the search. If the search has |
160 found what you specified and is waiting for input, @kbd{C-g} cancels the | 171 found what you specified and is waiting for input, @kbd{C-g} cancels the |
161 entire search. The cursor moves back to where you started the search. If | 172 entire search. The cursor moves back to where you started the search. If |
164 has failed to find them---then the search string characters which have not | 175 has failed to find them---then the search string characters which have not |
165 been found are discarded from the search string. With them gone, the | 176 been found are discarded from the search string. With them gone, the |
166 search is now successful and waiting for more input, so a second @kbd{C-g} | 177 search is now successful and waiting for more input, so a second @kbd{C-g} |
167 will cancel the entire search. | 178 will cancel the entire search. |
168 | 179 |
169 You can change to searching backwards with @kbd{C-r}. If a search fails | 180 @node Special Isearch |
170 because the place you started was too late in the file, you should do this. | 181 @subsection Special Input for Incremental Search |
171 Repeated @kbd{C-r} keeps looking for more occurrences backwards. A | 182 |
172 @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be canceled | 183 An upper-case letter in the search string makes the search |
173 with @key{DEL}. | 184 case-sensitive. If you delete the upper-case character from the search |
174 | 185 string, it ceases to have this effect. @xref{Search Case}. |
175 @kindex C-r | 186 |
176 @findex isearch-backward | 187 To search for a newline, type @kbd{C-j}. To search for another |
177 If you know initially that you want to search backwards, you can use | 188 control character, such as control-S or carriage return, you must quote |
178 @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as | 189 it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous |
179 a key runs a command (@code{isearch-backward}) to search backward. A | 190 to its use for insertion (@pxref{Inserting Text}): it causes the |
180 backward search finds matches that are entirely before the starting | 191 following character to be treated the way any ``ordinary'' character is |
181 point, just as a forward search finds matches that begin after it. | 192 treated in the same context. You can also specify a character by its |
182 | 193 octal code: enter @kbd{C-q} followed by a sequence of octal digits. |
183 The characters @kbd{C-y} and @kbd{C-w} can be used in incremental | 194 |
195 @kbd{M-%} typed in incremental search invokes @code{query-replace} | |
196 or @code{query-replace-regexp} (depending on search mode) with the | |
197 current search string used as the string to replace. @xref{Query | |
198 Replace}. | |
199 | |
200 Entering @key{RET} when the search string is empty launches | |
201 nonincremental search (@pxref{Nonincremental Search}). | |
202 | |
203 @vindex isearch-mode-map | |
204 To customize the special characters that incremental search understands, | |
205 alter their bindings in the keymap @code{isearch-mode-map}. For a list | |
206 of bindings, look at the documentation of @code{isearch-mode} with | |
207 @kbd{C-h f isearch-mode @key{RET}}. | |
208 | |
209 @node Non-ASCII Isearch | |
210 @subsection Isearch for Non-@acronym{ASCII} Characters | |
211 | |
212 @cindex searching for non-@acronym{ASCII} characters | |
213 @cindex input method, during incremental search | |
214 | |
215 To enter non-@acronym{ASCII} characters in an incremental search, | |
216 you must use an input method (@pxref{Input Methods}). If an input | |
217 method is enabled in the current buffer when you start the search, you | |
218 can use it while you type the search string also. Emacs indicates | |
219 that by including the input method mnemonic in its prompt, like this: | |
220 | |
221 @example | |
222 I-search [@var{im}]: | |
223 @end example | |
224 | |
225 @noindent | |
226 @findex isearch-toggle-input-method | |
227 @findex isearch-toggle-specified-input-method | |
228 where @var{im} is the mnemonic of the active input method. You can | |
229 toggle (enable or disable) the input method while you type the search | |
230 string with @kbd{C-\} (@code{isearch-toggle-input-method}). You can | |
231 turn on a certain (non-default) input method with @kbd{C-^} | |
232 (@code{isearch-toggle-specified-input-method}), which prompts for the | |
233 name of the input method. The input method you enable during | |
234 incremental search remains enabled in the current buffer afterwards. | |
235 | |
236 @node Isearch Yank | |
237 @subsection Isearch Yanking | |
238 | |
239 The characters @kbd{C-w} and @kbd{C-y} can be used in incremental | |
184 search to grab text from the buffer into the search string. This | 240 search to grab text from the buffer into the search string. This |
185 makes it convenient to search for another occurrence of text at point. | 241 makes it convenient to search for another occurrence of text at point. |
186 @kbd{C-w} copies the character or word after point as part of the | 242 @kbd{C-w} copies the character or word after point as part of the |
187 search string, advancing point over it. (The decision, whether to | 243 search string, advancing point over it. (The decision, whether to |
188 copy a character or a word, is heuristic.) Another @kbd{C-s} to | 244 copy a character or a word, is heuristic.) Another @kbd{C-s} to |
189 repeat the search will then search for a string including that | 245 repeat the search will then search for a string including that |
190 character or word. | 246 character or word. |
191 | 247 |
192 @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the | 248 @kbd{C-y} is similar to @kbd{C-w} but copies all the rest of the |
193 current line into the search string. Both @kbd{C-y} and @kbd{C-w} | 249 current line into the search string. If point is already at the end |
194 convert the text they copy to lower case if the search is currently | 250 of a line, it grabs the entire next line. Both @kbd{C-y} and |
195 not case-sensitive; this is so the search remains case-insensitive. | 251 @kbd{C-w} convert the text they copy to lower case if the search is |
252 currently not case-sensitive; this is so the search remains | |
253 case-insensitive. | |
254 | |
255 @kbd{C-M-w} and @kbd{C-M-y} modify the search string by only one | |
256 character at a time: @kbd{C-M-w} deletes the last character from the | |
257 search string and @kbd{C-M-y} copies the character after point to the | |
258 end of the search string. An alternative method to add the character | |
259 after point into the search string is to enter the minibuffer by | |
260 @kbd{M-e} and to type @kbd{C-f} at the end of the search string in the | |
261 minibuffer. | |
196 | 262 |
197 The character @kbd{M-y} copies text from the kill ring into the search | 263 The character @kbd{M-y} copies text from the kill ring into the search |
198 string. It uses the same text that @kbd{C-y} as a command would yank. | 264 string. It uses the same text that @kbd{C-y} as a command would yank. |
199 @kbd{Mouse-2} in the echo area does the same. | 265 @kbd{Mouse-2} in the echo area does the same. |
200 @xref{Yanking}. | 266 @xref{Yanking}. |
201 | 267 |
202 When you exit the incremental search, it sets the mark to where point | 268 @node Highlight Isearch |
203 @emph{was}, before the search. That is convenient for moving back | 269 @subsection Lazy Search Highlighting |
204 there. In Transient Mark mode, incremental search sets the mark without | |
205 activating it, and does so only if the mark is not already active. | |
206 | |
207 @cindex lazy search highlighting | 270 @cindex lazy search highlighting |
208 @vindex isearch-lazy-highlight | 271 @vindex isearch-lazy-highlight |
272 | |
209 When you pause for a little while during incremental search, it | 273 When you pause for a little while during incremental search, it |
210 highlights all other possible matches for the search string. This | 274 highlights all other possible matches for the search string. This |
211 makes it easier to anticipate where you can get to by typing @kbd{C-s} | 275 makes it easier to anticipate where you can get to by typing @kbd{C-s} |
212 or @kbd{C-r} to repeat the search. The short delay before highlighting | 276 or @kbd{C-r} to repeat the search. The short delay before highlighting |
213 other matches helps indicate which match is the current one. | 277 other matches helps indicate which match is the current one. |
214 If you don't like this feature, you can turn it off by setting | 278 If you don't like this feature, you can turn it off by setting |
215 @code{isearch-lazy-highlight} to @code{nil}. | 279 @code{isearch-lazy-highlight} to @code{nil}. |
216 | 280 |
217 @vindex isearch-lazy-highlight-face | |
218 @cindex faces for highlighting search matches | 281 @cindex faces for highlighting search matches |
219 You can control how this highlighting looks by customizing the faces | 282 You can control how this highlighting looks by customizing the faces |
220 @code{isearch} (used for the current match) and | 283 @code{isearch} (used for the current match) and @code{lazy-highlight} |
221 @code{isearch-lazy-highlight-face} (for all the other matches). | 284 (for all the other matches). The latter is also used for other matches |
222 | 285 inside @code{query-replace}. |
223 @vindex isearch-mode-map | 286 |
224 To customize the special characters that incremental search understands, | 287 @node Isearch Scroll |
225 alter their bindings in the keymap @code{isearch-mode-map}. For a list | 288 @subsection Scrolling During Incremental Search |
226 of bindings, look at the documentation of @code{isearch-mode} with | 289 |
227 @kbd{C-h f isearch-mode @key{RET}}. | 290 Vertical scrolling during incremental search can be enabled by |
228 | 291 setting the customizable variable @code{isearch-allow-scroll} to a |
292 non-@code{nil} value. | |
293 | |
294 You can then use the vertical scroll-bar or certain keyboard | |
295 commands such as @kbd{@key{PRIOR}} (@code{scroll-down}), | |
296 @kbd{@key{NEXT}} (@code{scroll-up}) and @kbd{C-l} (@code{recenter}) | |
297 within the search, thus letting you see more of the text near the | |
298 current match. You must run these commands via their key sequences to | |
299 stay in the search---typing M-x @var{command-name} will always | |
300 terminate a search. | |
301 | |
302 You can give prefix arguments to these commands in the usual way. | |
303 The current match cannot be scrolled out of the window---this is | |
304 intentional. | |
305 | |
306 Several other commands, such as @kbd{C-x 2} | |
307 (@code{split-window-vertically}) and @kbd{C-x ^} | |
308 (@code{enlarge-window}) which don't scroll the window, are | |
309 nevertheless made available under this rubric, since they are likewise | |
310 handy during a search. | |
311 | |
312 You can make other commands usable within an incremental search by | |
313 giving the command a non-@code{nil} @code{isearch-scroll} property. | |
314 For example, to make @kbd{C-h l} usable within an incremental search | |
315 in all future Emacs sessions, use @kbd{C-h c} to find what command it | |
316 runs. (You type @kbd{C-h c C-h l}; it says @code{view-lossage}.) Then | |
317 you can put the following line in your @file{.emacs} file (@pxref{Init File}): | |
318 | |
319 @example | |
320 (put 'view-lossage 'isearch-scroll t) | |
321 @end example | |
322 | |
323 @noindent | |
324 This works for commands that don't permanently change point, the | |
325 buffer contents, the match data, the current buffer, or the selected | |
326 window and frame. The command must not delete the current window and | |
327 must not itself attempt an incremental search. | |
328 | |
329 @node Slow Isearch | |
229 @subsection Slow Terminal Incremental Search | 330 @subsection Slow Terminal Incremental Search |
230 | 331 |
231 Incremental search on a slow terminal uses a modified style of display | 332 Incremental search on a slow terminal uses a modified style of display |
232 that is designed to take less time. Instead of redisplaying the buffer at | 333 that is designed to take less time. Instead of redisplaying the buffer at |
233 each place the search gets to, it creates a new single-line window and uses | 334 each place the search gets to, it creates a new single-line window and uses |
240 its new position of point. | 341 its new position of point. |
241 | 342 |
242 @vindex search-slow-speed | 343 @vindex search-slow-speed |
243 The slow terminal style of display is used when the terminal baud rate is | 344 The slow terminal style of display is used when the terminal baud rate is |
244 less than or equal to the value of the variable @code{search-slow-speed}, | 345 less than or equal to the value of the variable @code{search-slow-speed}, |
245 initially 1200. See @code{baud-rate} in @ref{Display Custom}. | 346 initially 1200. See also the discussion of the variable @code{baud-rate} |
347 (@pxref{baud-rate,, Customization of Display}). | |
246 | 348 |
247 @vindex search-slow-window-lines | 349 @vindex search-slow-window-lines |
248 The number of lines to use in slow terminal search display is controlled | 350 The number of lines to use in slow terminal search display is controlled |
249 by the variable @code{search-slow-window-lines}. Its normal value is 1. | 351 by the variable @code{search-slow-window-lines}. Its normal value is 1. |
250 | 352 |
251 @node Nonincremental Search, Word Search, Incremental Search, Search | 353 @node Nonincremental Search |
252 @section Nonincremental Search | 354 @section Nonincremental Search |
253 @cindex nonincremental search | 355 @cindex nonincremental search |
254 | 356 |
255 Emacs also has conventional nonincremental search commands, which require | 357 Emacs also has conventional nonincremental search commands, which require |
256 you to type the entire search string before searching begins. | 358 you to type the entire search string before searching begins. |
286 commands may be bound to keys in the usual manner. The feature that you | 388 commands may be bound to keys in the usual manner. The feature that you |
287 can get to them via the incremental search commands exists for | 389 can get to them via the incremental search commands exists for |
288 historical reasons, and to avoid the need to find key sequences | 390 historical reasons, and to avoid the need to find key sequences |
289 for them. | 391 for them. |
290 | 392 |
291 @node Word Search, Regexp Search, Nonincremental Search, Search | 393 @node Word Search |
292 @section Word Search | 394 @section Word Search |
293 @cindex word search | 395 @cindex word search |
294 | 396 |
295 Word search searches for a sequence of words without regard to how the | 397 Word search searches for a sequence of words without regard to how the |
296 words are separated. More precisely, you type a string of many words, | 398 words are separated. More precisely, you type a string of many words, |
325 @code{word-search-forward} and @code{word-search-backward}. These | 427 @code{word-search-forward} and @code{word-search-backward}. These |
326 commands may be bound to keys in the usual manner. They are available | 428 commands may be bound to keys in the usual manner. They are available |
327 via the incremental search commands both for historical reasons and | 429 via the incremental search commands both for historical reasons and |
328 to avoid the need to find suitable key sequences for them. | 430 to avoid the need to find suitable key sequences for them. |
329 | 431 |
330 @node Regexp Search, Regexps, Word Search, Search | 432 @node Regexp Search |
331 @section Regular Expression Search | 433 @section Regular Expression Search |
332 @cindex regular expression | 434 @cindex regular expression |
333 @cindex regexp | 435 @cindex regexp |
334 | 436 |
335 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern | 437 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern |
336 that denotes a class of alternative strings to match, possibly | 438 that denotes a class of alternative strings to match, possibly |
337 infinitely many. GNU Emacs provides both incremental and | 439 infinitely many. GNU Emacs provides both incremental and |
338 nonincremental ways to search for a match for a regexp. | 440 nonincremental ways to search for a match for a regexp. The syntax of |
441 regular expressions is explained in the following section. | |
339 | 442 |
340 @kindex C-M-s | 443 @kindex C-M-s |
341 @findex isearch-forward-regexp | 444 @findex isearch-forward-regexp |
342 @kindex C-M-r | 445 @kindex C-M-r |
343 @findex isearch-backward-regexp | 446 @findex isearch-backward-regexp |
344 Incremental search for a regexp is done by typing @kbd{C-M-s} | 447 Incremental search for a regexp is done by typing @kbd{C-M-s} |
345 (@code{isearch-forward-regexp}), or by invoking @kbd{C-s} with a | 448 (@code{isearch-forward-regexp}), by invoking @kbd{C-s} with a |
346 prefix argument (whose value does not matter). This command reads a | 449 prefix argument (whose value does not matter), or by typing @kbd{M-r} |
450 within a forward incremental search. This command reads a | |
347 search string incrementally just like @kbd{C-s}, but it treats the | 451 search string incrementally just like @kbd{C-s}, but it treats the |
348 search string as a regexp rather than looking for an exact match | 452 search string as a regexp rather than looking for an exact match |
349 against the text in the buffer. Each time you add text to the search | 453 against the text in the buffer. Each time you add text to the search |
350 string, you make the regexp longer, and the new regexp is searched | 454 string, you make the regexp longer, and the new regexp is searched |
351 for. To search backward for a regexp, use @kbd{C-M-r} | 455 for. To search backward for a regexp, use @kbd{C-M-r} |
352 (@code{isearch-backward-regexp}), or @kbd{C-r} with a prefix argument. | 456 (@code{isearch-backward-regexp}), @kbd{C-r} with a prefix argument, |
457 or @kbd{M-r} within a backward incremental search. | |
353 | 458 |
354 All of the control characters that do special things within an | 459 All of the control characters that do special things within an |
355 ordinary incremental search have the same function in incremental regexp | 460 ordinary incremental search have the same function in incremental regexp |
356 search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the | 461 search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the |
357 search retrieves the last incremental search regexp used; that is to | 462 search retrieves the last incremental search regexp used; that is to |
358 say, incremental regexp and non-regexp searches have independent | 463 say, incremental regexp and non-regexp searches have independent |
359 defaults. They also have separate search rings that you can access with | 464 defaults. They also have separate search rings that you can access with |
360 @kbd{M-p} and @kbd{M-n}. | 465 @kbd{M-p} and @kbd{M-n}. |
361 | 466 |
467 @vindex search-whitespace-regexp | |
362 If you type @key{SPC} in incremental regexp search, it matches any | 468 If you type @key{SPC} in incremental regexp search, it matches any |
363 sequence of whitespace characters, including newlines. If you want | 469 sequence of whitespace characters, including newlines. If you want to |
364 to match just a space, type @kbd{C-q @key{SPC}}. | 470 match just a space, type @kbd{C-q @key{SPC}}. You can control what a |
471 bare spece matches by setting the variable | |
472 @code{search-whitespace-regexp} to the desired regexp. | |
365 | 473 |
366 Note that adding characters to the regexp in an incremental regexp | 474 Note that adding characters to the regexp in an incremental regexp |
367 search can make the cursor move back and start again. For example, if | 475 search can make the cursor move back and start again. For example, if |
368 you have searched for @samp{foo} and you add @samp{\|bar}, the cursor | 476 you have searched for @samp{foo} and you add @samp{\|bar}, the cursor |
369 backs up in case the first @samp{bar} precedes the first @samp{foo}. | 477 backs up in case the first @samp{bar} precedes the first @samp{foo}. |
379 If you use the incremental regexp search commands with a prefix | 487 If you use the incremental regexp search commands with a prefix |
380 argument, they perform ordinary string search, like | 488 argument, they perform ordinary string search, like |
381 @code{isearch-forward} and @code{isearch-backward}. @xref{Incremental | 489 @code{isearch-forward} and @code{isearch-backward}. @xref{Incremental |
382 Search}. | 490 Search}. |
383 | 491 |
384 @node Regexps, Search Case, Regexp Search, Search | 492 @node Regexps |
385 @section Syntax of Regular Expressions | 493 @section Syntax of Regular Expressions |
386 @cindex syntax of regexps | 494 @cindex syntax of regexps |
495 | |
496 This manual describes regular expression features that users | |
497 typically want to use. There are additional features that are | |
498 mainly used in Lisp programs; see @ref{Regular Expressions,,, | |
499 elisp, The Emacs Lisp Reference Manual}. | |
387 | 500 |
388 Regular expressions have a syntax in which a few characters are | 501 Regular expressions have a syntax in which a few characters are |
389 special constructs and the rest are @dfn{ordinary}. An ordinary | 502 special constructs and the rest are @dfn{ordinary}. An ordinary |
390 character is a simple regular expression which matches that same | 503 character is a simple regular expression which matches that same |
391 character and nothing else. The special characters are @samp{$}, | 504 character and nothing else. The special characters are @samp{$}, |
411 As a simple example, we can concatenate the regular expressions @samp{f} | 524 As a simple example, we can concatenate the regular expressions @samp{f} |
412 and @samp{o} to get the regular expression @samp{fo}, which matches only | 525 and @samp{o} to get the regular expression @samp{fo}, which matches only |
413 the string @samp{fo}. Still trivial. To do something nontrivial, you | 526 the string @samp{fo}. Still trivial. To do something nontrivial, you |
414 need to use one of the special characters. Here is a list of them. | 527 need to use one of the special characters. Here is a list of them. |
415 | 528 |
416 @table @kbd | 529 @table @asis |
417 @item .@: @r{(Period)} | 530 @item @kbd{.}@: @r{(Period)} |
418 is a special character that matches any single character except a newline. | 531 is a special character that matches any single character except a newline. |
419 Using concatenation, we can make regular expressions like @samp{a.b}, which | 532 Using concatenation, we can make regular expressions like @samp{a.b}, which |
420 matches any three-character string that begins with @samp{a} and ends with | 533 matches any three-character string that begins with @samp{a} and ends with |
421 @samp{b}.@refill | 534 @samp{b}.@refill |
422 | 535 |
423 @item * | 536 @item @kbd{*} |
424 is not a construct by itself; it is a postfix operator that means to | 537 is not a construct by itself; it is a postfix operator that means to |
425 match the preceding regular expression repetitively as many times as | 538 match the preceding regular expression repetitively as many times as |
426 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no | 539 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no |
427 @samp{o}s). | 540 @samp{o}s). |
428 | 541 |
439 tries to match all three @samp{a}s; but the rest of the pattern is | 552 tries to match all three @samp{a}s; but the rest of the pattern is |
440 @samp{ar} and there is only @samp{r} left to match, so this try fails. | 553 @samp{ar} and there is only @samp{r} left to match, so this try fails. |
441 The next alternative is for @samp{a*} to match only two @samp{a}s. | 554 The next alternative is for @samp{a*} to match only two @samp{a}s. |
442 With this choice, the rest of the regexp matches successfully.@refill | 555 With this choice, the rest of the regexp matches successfully.@refill |
443 | 556 |
444 @item + | 557 @item @kbd{+} |
445 is a postfix operator, similar to @samp{*} except that it must match | 558 is a postfix operator, similar to @samp{*} except that it must match |
446 the preceding expression at least once. So, for example, @samp{ca+r} | 559 the preceding expression at least once. So, for example, @samp{ca+r} |
447 matches the strings @samp{car} and @samp{caaaar} but not the string | 560 matches the strings @samp{car} and @samp{caaaar} but not the string |
448 @samp{cr}, whereas @samp{ca*r} matches all three strings. | 561 @samp{cr}, whereas @samp{ca*r} matches all three strings. |
449 | 562 |
450 @item ? | 563 @item @kbd{?} |
451 is a postfix operator, similar to @samp{*} except that it can match the | 564 is a postfix operator, similar to @samp{*} except that it can match the |
452 preceding expression either once or not at all. For example, | 565 preceding expression either once or not at all. For example, |
453 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. | 566 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else. |
454 | 567 |
455 @item *?, +?, ?? | 568 @item @kbd{*?}, @kbd{+?}, @kbd{??} |
456 @cindex non-greedy regexp matching | 569 @cindex non-greedy regexp matching |
457 are non-greedy variants of the operators above. The normal operators | 570 are non-greedy variants of the operators above. The normal operators |
458 @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as | 571 @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as |
459 much as they can, as long as the overall regexp can still match. With | 572 much as they can, as long as the overall regexp can still match. With |
460 a following @samp{?}, they are non-greedy: they will match as little | 573 a following @samp{?}, they are non-greedy: they will match as little |
471 possible starting point for match is always the one chosen. Thus, if | 584 possible starting point for match is always the one chosen. Thus, if |
472 you search for @samp{a.*?$} against the text @samp{abbab} followed by | 585 you search for @samp{a.*?$} against the text @samp{abbab} followed by |
473 a newline, it matches the whole string. Since it @emph{can} match | 586 a newline, it matches the whole string. Since it @emph{can} match |
474 starting at the first @samp{a}, it does. | 587 starting at the first @samp{a}, it does. |
475 | 588 |
476 @item \@{@var{n}\@} | 589 @item @kbd{\@{@var{n}\@}} |
477 is a postfix operator that specifies repetition @var{n} times---that | 590 is a postfix operator that specifies repetition @var{n} times---that |
478 is, the preceding regular expression must match exactly @var{n} times | 591 is, the preceding regular expression must match exactly @var{n} times |
479 in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} | 592 in a row. For example, @samp{x\@{4\@}} matches the string @samp{xxxx} |
480 and nothing else. | 593 and nothing else. |
481 | 594 |
482 @item \@{@var{n},@var{m}\@} | 595 @item @kbd{\@{@var{n},@var{m}\@}} |
483 is a postfix operator that specifies repetition between @var{n} and | 596 is a postfix operator that specifies repetition between @var{n} and |
484 @var{m} times---that is, the preceding regular expression must match | 597 @var{m} times---that is, the preceding regular expression must match |
485 at least @var{n} times, but no more than @var{m} times. If @var{m} is | 598 at least @var{n} times, but no more than @var{m} times. If @var{m} is |
486 omitted, then there is no upper limit, but the preceding regular | 599 omitted, then there is no upper limit, but the preceding regular |
487 expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is | 600 expression must match at least @var{n} times.@* @samp{\@{0,1\@}} is |
488 equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to | 601 equivalent to @samp{?}. @* @samp{\@{0,\@}} is equivalent to |
489 @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. | 602 @samp{*}. @* @samp{\@{1,\@}} is equivalent to @samp{+}. |
490 | 603 |
491 @item [ @dots{} ] | 604 @item @kbd{[ @dots{} ]} |
492 is a @dfn{character set}, which begins with @samp{[} and is terminated | 605 is a @dfn{character set}, which begins with @samp{[} and is terminated |
493 by @samp{]}. In the simplest case, the characters between the two | 606 by @samp{]}. In the simplest case, the characters between the two |
494 brackets are what this set can match. | 607 brackets are what this set can match. |
495 | 608 |
496 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and | 609 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and |
498 (including the empty string), from which it follows that @samp{c[ad]*r} | 611 (including the empty string), from which it follows that @samp{c[ad]*r} |
499 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. | 612 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc. |
500 | 613 |
501 You can also include character ranges in a character set, by writing the | 614 You can also include character ranges in a character set, by writing the |
502 starting and ending characters with a @samp{-} between them. Thus, | 615 starting and ending characters with a @samp{-} between them. Thus, |
503 @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be | 616 @samp{[a-z]} matches any lower-case @acronym{ASCII} letter. Ranges may be |
504 intermixed freely with individual characters, as in @samp{[a-z$%.]}, | 617 intermixed freely with individual characters, as in @samp{[a-z$%.]}, |
505 which matches any lower-case ASCII letter or @samp{$}, @samp{%} or | 618 which matches any lower-case @acronym{ASCII} letter or @samp{$}, @samp{%} or |
506 period. | 619 period. |
507 | 620 |
508 Note that the usual regexp special characters are not special inside a | 621 Note that the usual regexp special characters are not special inside a |
509 character set. A completely different set of special characters exists | 622 character set. A completely different set of special characters exists |
510 inside character sets: @samp{]}, @samp{-} and @samp{^}. | 623 inside character sets: @samp{]}, @samp{-} and @samp{^}. |
521 When you use a range in case-insensitive search, you should write both | 634 When you use a range in case-insensitive search, you should write both |
522 ends of the range in upper case, or both in lower case, or both should | 635 ends of the range in upper case, or both in lower case, or both should |
523 be non-letters. The behavior of a mixed-case range such as @samp{A-z} | 636 be non-letters. The behavior of a mixed-case range such as @samp{A-z} |
524 is somewhat ill-defined, and it may change in future Emacs versions. | 637 is somewhat ill-defined, and it may change in future Emacs versions. |
525 | 638 |
526 @item [^ @dots{} ] | 639 @item @kbd{[^ @dots{} ]} |
527 @samp{[^} begins a @dfn{complemented character set}, which matches any | 640 @samp{[^} begins a @dfn{complemented character set}, which matches any |
528 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches | 641 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches |
529 all characters @emph{except} ASCII letters and digits. | 642 all characters @emph{except} @acronym{ASCII} letters and digits. |
530 | 643 |
531 @samp{^} is not special in a character set unless it is the first | 644 @samp{^} is not special in a character set unless it is the first |
532 character. The character following the @samp{^} is treated as if it | 645 character. The character following the @samp{^} is treated as if it |
533 were first (in other words, @samp{-} and @samp{]} are not special there). | 646 were first (in other words, @samp{-} and @samp{]} are not special there). |
534 | 647 |
535 A complemented character set can match a newline, unless newline is | 648 A complemented character set can match a newline, unless newline is |
536 mentioned as one of the characters not to match. This is in contrast to | 649 mentioned as one of the characters not to match. This is in contrast to |
537 the handling of regexps in programs such as @code{grep}. | 650 the handling of regexps in programs such as @code{grep}. |
538 | 651 |
539 @item ^ | 652 @item @kbd{^} |
540 is a special character that matches the empty string, but only at the | 653 is a special character that matches the empty string, but only at the |
541 beginning of a line in the text being matched. Otherwise it fails to | 654 beginning of a line in the text being matched. Otherwise it fails to |
542 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at | 655 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at |
543 the beginning of a line. | 656 the beginning of a line. |
544 | 657 |
545 @item $ | 658 For historical compatibility reasons, @samp{^} can be used with this |
659 meaning only at the beginning of the regular expression, or after | |
660 @samp{\(} or @samp{\|}. | |
661 | |
662 @item @kbd{$} | |
546 is similar to @samp{^} but matches only at the end of a line. Thus, | 663 is similar to @samp{^} but matches only at the end of a line. Thus, |
547 @samp{x+$} matches a string of one @samp{x} or more at the end of a line. | 664 @samp{x+$} matches a string of one @samp{x} or more at the end of a line. |
548 | 665 |
549 @item \ | 666 For historical compatibility reasons, @samp{$} can be used with this |
667 meaning only at the end of the regular expression, or before @samp{\)} | |
668 or @samp{\|}. | |
669 | |
670 @item @kbd{\} | |
550 has two functions: it quotes the special characters (including | 671 has two functions: it quotes the special characters (including |
551 @samp{\}), and it introduces additional special constructs. | 672 @samp{\}), and it introduces additional special constructs. |
552 | 673 |
553 Because @samp{\} quotes special characters, @samp{\$} is a regular | 674 Because @samp{\} quotes special characters, @samp{\$} is a regular |
554 expression that matches only @samp{$}, and @samp{\[} is a regular | 675 expression that matches only @samp{$}, and @samp{\[} is a regular |
555 expression that matches only @samp{[}, and so on. | 676 expression that matches only @samp{[}, and so on. |
677 | |
678 See the following section for the special constructs that begin | |
679 with @samp{\}. | |
556 @end table | 680 @end table |
557 | 681 |
558 Note: for historical compatibility, special characters are treated as | 682 Note: for historical compatibility, special characters are treated as |
559 ordinary ones if they are in contexts where their special meanings make no | 683 ordinary ones if they are in contexts where their special meanings make no |
560 sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is | 684 sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is |
561 no preceding expression on which the @samp{*} can act. It is poor practice | 685 no preceding expression on which the @samp{*} can act. It is poor practice |
562 to depend on this behavior; it is better to quote the special character anyway, | 686 to depend on this behavior; it is better to quote the special character anyway, |
563 regardless of where it appears.@refill | 687 regardless of where it appears. |
564 | 688 |
565 For the most part, @samp{\} followed by any character matches only that | 689 @node Regexp Backslash |
566 character. However, there are several exceptions: two-character | 690 @section Backslash in Regular Expressions |
567 sequences starting with @samp{\} that have special meanings. The second | 691 |
568 character in the sequence is always an ordinary character when used on | 692 For the most part, @samp{\} followed by any character matches only |
569 its own. Here is a table of @samp{\} constructs. | 693 that character. However, there are several exceptions: two-character |
694 sequences starting with @samp{\} that have special meanings. The | |
695 second character in the sequence is always an ordinary character when | |
696 used on its own. Here is a table of @samp{\} constructs. | |
570 | 697 |
571 @table @kbd | 698 @table @kbd |
572 @item \| | 699 @item \| |
573 specifies an alternative. Two regular expressions @var{a} and @var{b} | 700 specifies an alternative. Two regular expressions @var{a} and @var{b} |
574 with @samp{\|} in between form an expression that matches some text if | 701 with @samp{\|} in between form an expression that matches some text if |
679 matches any word-constituent character. The syntax table | 806 matches any word-constituent character. The syntax table |
680 determines which characters these are. @xref{Syntax}. | 807 determines which characters these are. @xref{Syntax}. |
681 | 808 |
682 @item \W | 809 @item \W |
683 matches any character that is not a word-constituent. | 810 matches any character that is not a word-constituent. |
811 | |
812 @item \_< | |
813 matches the empty string, but only at the beginning of a symbol. | |
814 A symbol is a sequence of one or more symbol-constituent characters. | |
815 A symbol-constituent character is a character whose syntax is either | |
816 @samp{w} or @samp{_}. @samp{\_<} matches at the beginning of the | |
817 buffer only if a symbol-constituent character follows. | |
818 | |
819 @item \_> | |
820 matches the empty string, but only at the end of a symbol. @samp{\_>} | |
821 matches at the end of the buffer only if the contents end with a | |
822 symbol-constituent character. | |
684 | 823 |
685 @item \s@var{c} | 824 @item \s@var{c} |
686 matches any character whose syntax is @var{c}. Here @var{c} is a | 825 matches any character whose syntax is @var{c}. Here @var{c} is a |
687 character that designates a particular syntax class: thus, @samp{w} | 826 character that designates a particular syntax class: thus, @samp{w} |
688 for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} | 827 for word constituent, @samp{-} or @samp{ } for whitespace, @samp{.} |
706 @end table | 845 @end table |
707 | 846 |
708 The constructs that pertain to words and syntax are controlled by the | 847 The constructs that pertain to words and syntax are controlled by the |
709 setting of the syntax table (@pxref{Syntax}). | 848 setting of the syntax table (@pxref{Syntax}). |
710 | 849 |
711 Here is a complicated regexp, stored in @code{sentence-end} and used | 850 @node Regexp Example |
712 by Emacs to recognize the end of a sentence together with any | 851 @section Regular Expression Example |
713 whitespace that follows. We show its Lisp syntax to distinguish the | 852 |
714 spaces from the tab characters. In Lisp syntax, the string constant | 853 Here is a complicated regexp---a simplified version of the regexp |
715 begins and ends with a double-quote. @samp{\"} stands for a | 854 that Emacs uses, by default, to recognize the end of a sentence |
716 double-quote as part of the regexp, @samp{\\} for a backslash as part | 855 together with any whitespace that follows. We show its Lisp syntax to |
717 of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline. | 856 distinguish the spaces from the tab characters. In Lisp syntax, the |
857 string constant begins and ends with a double-quote. @samp{\"} stands | |
858 for a double-quote as part of the regexp, @samp{\\} for a backslash as | |
859 part of the regexp, @samp{\t} for a tab, and @samp{\n} for a newline. | |
718 | 860 |
719 @example | 861 @example |
720 "[.?!][]\"')]*\\($\\| $\\|\t\\| \\)[ \t\n]*" | 862 "[.?!][]\"')]*\\($\\| $\\|\t\\| \\)[ \t\n]*" |
721 @end example | 863 @end example |
722 | 864 |
734 also type single backslashes as themselves, instead of doubling them | 876 also type single backslashes as themselves, instead of doubling them |
735 for Lisp syntax. In commands that use ordinary minibuffer input to | 877 for Lisp syntax. In commands that use ordinary minibuffer input to |
736 read a regexp, you would quote the @kbd{C-j} by preceding it with a | 878 read a regexp, you would quote the @kbd{C-j} by preceding it with a |
737 @kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer. | 879 @kbd{C-q} to prevent @kbd{C-j} from exiting the minibuffer. |
738 | 880 |
739 @ignore | 881 @node Search Case |
740 @c I commented this out because it is missing vital information | |
741 @c and therefore useless. For instance, what do you do to *use* the | |
742 @c regular expression when it is finished? What jobs is this good for? | |
743 @c -- rms | |
744 | |
745 @findex re-builder | |
746 @cindex authoring regular expressions | |
747 For convenient interactive development of regular expressions, you | |
748 can use the @kbd{M-x re-builder} command. It provides a convenient | |
749 interface for creating regular expressions, by giving immediate visual | |
750 feedback. The buffer from which @code{re-builder} was invoked becomes | |
751 the target for the regexp editor, which pops in a separate window. At | |
752 all times, all the matches in the target buffer for the current | |
753 regular expression are highlighted. Each parenthesized sub-expression | |
754 of the regexp is shown in a distinct face, which makes it easier to | |
755 verify even very complex regexps. (On displays that don't support | |
756 colors, Emacs blinks the cursor around the matched text, as it does | |
757 for matching parens.) | |
758 @end ignore | |
759 | |
760 @node Search Case, Replace, Regexps, Search | |
761 @section Searching and Case | 882 @section Searching and Case |
762 | 883 |
763 Incremental searches in Emacs normally ignore the case of the text | 884 Incremental searches in Emacs normally ignore the case of the text |
764 they are searching through, if you specify the text in lower case. | 885 they are searching through, if you specify the text in lower case. |
765 Thus, if you specify searching for @samp{foo}, then @samp{Foo} and | 886 Thus, if you specify searching for @samp{foo}, then @samp{Foo} and |
777 sensitivity of that search. The effect does not extend beyond the | 898 sensitivity of that search. The effect does not extend beyond the |
778 current incremental search to the next one, but it does override the | 899 current incremental search to the next one, but it does override the |
779 effect of including an upper-case letter in the current search. | 900 effect of including an upper-case letter in the current search. |
780 | 901 |
781 @vindex case-fold-search | 902 @vindex case-fold-search |
903 @vindex default-case-fold-search | |
782 If you set the variable @code{case-fold-search} to @code{nil}, then | 904 If you set the variable @code{case-fold-search} to @code{nil}, then |
783 all letters must match exactly, including case. This is a per-buffer | 905 all letters must match exactly, including case. This is a per-buffer |
784 variable; altering the variable affects only the current buffer, but | 906 variable; altering the variable affects only the current buffer, but |
785 there is a default value which you can change as well. @xref{Locals}. | 907 there is a default value in @code{default-case-fold-search} that you |
786 This variable applies to nonincremental searches also, including those | 908 can also set. @xref{Locals}. This variable applies to nonincremental |
787 performed by the replace commands (@pxref{Replace}) and the minibuffer | 909 searches also, including those performed by the replace commands |
788 history matching commands (@pxref{Minibuffer History}). | 910 (@pxref{Replace}) and the minibuffer history matching commands |
789 | 911 (@pxref{Minibuffer History}). |
790 @node Replace, Other Repeating Search, Search Case, Search | 912 |
913 Several related variables control case-sensitivity of searching and | |
914 matching for specific commands or activities. For instance, | |
915 @code{tags-case-fold-search} controls case sensitivity for | |
916 @code{find-tag}. To find these variables, do @kbd{M-x | |
917 apropos-variable @key{RET} case-fold-search @key{RET}}. | |
918 | |
919 @node Replace | |
791 @section Replacement Commands | 920 @section Replacement Commands |
792 @cindex replacement | 921 @cindex replacement |
793 @cindex search-and-replace commands | 922 @cindex search-and-replace commands |
794 @cindex string substitution | 923 @cindex string substitution |
795 @cindex global substitution | 924 @cindex global substitution |
796 | 925 |
797 Global search-and-replace operations are not needed often in Emacs, | 926 Global search-and-replace operations are not needed often in Emacs, |
798 but they are available. In addition to the simple @kbd{M-x | 927 but they are available. In addition to the simple @kbd{M-x |
799 replace-string} command which is like that found in most editors, | 928 replace-string} command which replaces all occurrences, |
800 there is a @kbd{M-x query-replace} command which finds each occurrence | 929 there is @kbd{M-%} (@code{query-replace}), which presents each occurrence |
801 of the pattern and asks you whether to replace it. | 930 of the pattern and asks you whether to replace it. |
802 | 931 |
803 The replace commands normally operate on the text from point to the | 932 The replace commands normally operate on the text from point to the |
804 end of the buffer; however, in Transient Mark mode (@pxref{Transient | 933 end of the buffer; however, in Transient Mark mode (@pxref{Transient |
805 Mark}), when the mark is active, they operate on the region. The | 934 Mark}), when the mark is active, they operate on the region. The |
807 replacement string. It is possible to perform several replacements in | 936 replacement string. It is possible to perform several replacements in |
808 parallel using the command @code{expand-region-abbrevs} | 937 parallel using the command @code{expand-region-abbrevs} |
809 (@pxref{Expanding Abbrevs}). | 938 (@pxref{Expanding Abbrevs}). |
810 | 939 |
811 @menu | 940 @menu |
812 * Unconditional Replace:: Replacing all matches for a string. | 941 * Unconditional Replace:: Replacing all matches for a string. |
813 * Regexp Replace:: Replacing all matches for a regexp. | 942 * Regexp Replace:: Replacing all matches for a regexp. |
814 * Replacement and Case:: How replacements preserve case of letters. | 943 * Replacement and Case:: How replacements preserve case of letters. |
815 * Query Replace:: How to use querying. | 944 * Query Replace:: How to use querying. |
816 @end menu | 945 @end menu |
817 | 946 |
818 @node Unconditional Replace, Regexp Replace, Replace, Replace | 947 @node Unconditional Replace, Regexp Replace, Replace, Replace |
819 @subsection Unconditional Replacement | 948 @subsection Unconditional Replacement |
820 @findex replace-string | 949 @findex replace-string |
821 @findex replace-regexp | |
822 | 950 |
823 @table @kbd | 951 @table @kbd |
824 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} | 952 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} |
825 Replace every occurrence of @var{string} with @var{newstring}. | 953 Replace every occurrence of @var{string} with @var{newstring}. |
826 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} | |
827 Replace every match for @var{regexp} with @var{newstring}. | |
828 @end table | 954 @end table |
829 | 955 |
830 To replace every instance of @samp{foo} after point with @samp{bar}, | 956 To replace every instance of @samp{foo} after point with @samp{bar}, |
831 use the command @kbd{M-x replace-string} with the two arguments | 957 use the command @kbd{M-x replace-string} with the two arguments |
832 @samp{foo} and @samp{bar}. Replacement happens only in the text after | 958 @samp{foo} and @samp{bar}. Replacement happens only in the text after |
846 by word boundaries. The argument's value doesn't matter. | 972 by word boundaries. The argument's value doesn't matter. |
847 | 973 |
848 What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa? You can do it this way: | 974 What if you want to exchange @samp{x} and @samp{y}: replace every @samp{x} with a @samp{y} and vice versa? You can do it this way: |
849 | 975 |
850 @example | 976 @example |
851 M-x query-replace @key{RET} x @key{RET} @@TEMP@@ @key{RET} | 977 M-x replace-string @key{RET} x @key{RET} @@TEMP@@ @key{RET} |
852 M-x query-replace @key{RET} y @key{RET} x @key{RET} | 978 M-< M-x replace-string @key{RET} y @key{RET} x @key{RET} |
853 M-x query-replace @key{RET} @@TEMP@@ @key{RET} y @key{RET} | 979 M-< M-x replace-string @key{RET} @@TEMP@@ @key{RET} y @key{RET} |
854 @end example | 980 @end example |
855 | 981 |
856 @noindent | 982 @noindent |
857 This works provided the string @samp{@@TEMP@@} does not appear | 983 This works provided the string @samp{@@TEMP@@} does not appear |
858 in your text. | 984 in your text. |
859 | 985 |
860 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace | 986 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace |
861 @subsection Regexp Replacement | 987 @subsection Regexp Replacement |
988 @findex replace-regexp | |
862 | 989 |
863 The @kbd{M-x replace-string} command replaces exact matches for a | 990 The @kbd{M-x replace-string} command replaces exact matches for a |
864 single string. The similar command @kbd{M-x replace-regexp} replaces | 991 single string. The similar command @kbd{M-x replace-regexp} replaces |
865 any match for a specified pattern. | 992 any match for a specified pattern. |
866 | 993 |
867 In @code{replace-regexp}, the @var{newstring} need not be constant: it | 994 @table @kbd |
868 can refer to all or part of what is matched by the @var{regexp}. | 995 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} |
869 @samp{\&} in @var{newstring} stands for the entire match being replaced. | 996 Replace every match for @var{regexp} with @var{newstring}. |
870 @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for | 997 @end table |
871 whatever matched the @var{d}th parenthesized grouping in @var{regexp}. | 998 |
872 To include a @samp{\} in the text to replace with, you must enter | 999 In @code{replace-regexp}, the @var{newstring} need not be constant: |
873 @samp{\\}. For example, | 1000 it can refer to all or part of what is matched by the @var{regexp}. |
1001 @samp{\&} in @var{newstring} stands for the entire match being | |
1002 replaced. @samp{\@var{d}} in @var{newstring}, where @var{d} is a | |
1003 digit, stands for whatever matched the @var{d}th parenthesized | |
1004 grouping in @var{regexp}. @samp{\#} refers to the count of | |
1005 replacements already made in this command, as a decimal number. In | |
1006 the first replacement, @samp{\#} stands for @samp{0}; in the second, | |
1007 for @samp{1}; and so on. For example, | |
874 | 1008 |
875 @example | 1009 @example |
876 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} | 1010 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} |
877 @end example | 1011 @end example |
878 | 1012 |
883 @example | 1017 @example |
884 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} | 1018 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} |
885 @end example | 1019 @end example |
886 | 1020 |
887 @noindent | 1021 @noindent |
888 performs the inverse transformation. | 1022 performs the inverse transformation. To include a @samp{\} in the |
1023 text to replace with, you must enter @samp{\\}. | |
1024 | |
1025 If you want to enter part of the replacement string by hand each | |
1026 time, use @samp{\?} in the replacement string. Each replacement will | |
1027 ask you to edit the replacement string in the minibuffer, putting | |
1028 point where the @samp{\?} was. | |
1029 | |
1030 The remainder of this subsection is intended for specialized tasks | |
1031 and requires knowledge of Lisp. Most readers can skip it. | |
1032 | |
1033 You can use Lisp expressions to calculate parts of the | |
1034 replacement string. To do this, write @samp{\,} followed by the | |
1035 expression in the replacement string. Each replacement calculates the | |
1036 value of the expression and converts it to text without quoting (if | |
1037 it's a string, this means using the string's contents), and uses it in | |
1038 the replacement string in place of the expression itself. If the | |
1039 expression is a symbol, one space in the replacement string after the | |
1040 symbol name goes with the symbol name, so the value replaces them | |
1041 both. | |
1042 | |
1043 Inside such an expression, you can use some special sequences. | |
1044 @samp{\&} and @samp{\@var{n}} refer here, as usual, to the entire | |
1045 match as a string, and to a submatch as a string. @var{n} may be | |
1046 multiple digits, and the value of @samp{\@var{n}} is @code{nil} if | |
1047 subexpression @var{n} did not match. You can also use @samp{\#&} and | |
1048 @samp{\#@var{n}} to refer to those matches as numbers (this is valid | |
1049 when the match or submatch has the form of a numeral). @samp{\#} here | |
1050 too stands for the number of already-completed replacements. | |
1051 | |
1052 Repeating our example to exchange @samp{x} and @samp{y}, we can thus | |
1053 do it also this way: | |
1054 | |
1055 @example | |
1056 M-x replace-regexp @key{RET} \(x\)\|y @key{RET} | |
1057 \,(if \1 "y" "x") @key{RET} | |
1058 @end example | |
1059 | |
1060 For computing replacement strings for @samp{\,}, the @code{format} | |
1061 function is often useful (@pxref{Formatting Strings,,, elisp, The Emacs | |
1062 Lisp Reference Manual}). For example, to add consecutively numbered | |
1063 strings like @samp{ABC00042} to columns 73 @w{to 80} (unless they are | |
1064 already occupied), you can use | |
1065 | |
1066 @example | |
1067 M-x replace-regexp @key{RET} ^.\@{0,72\@}$ @key{RET} | |
1068 \,(format "%-72sABC%05d" \& \#) @key{RET} | |
1069 @end example | |
889 | 1070 |
890 @node Replacement and Case, Query Replace, Regexp Replace, Replace | 1071 @node Replacement and Case, Query Replace, Regexp Replace, Replace |
891 @subsection Replace Commands and Case | 1072 @subsection Replace Commands and Case |
892 | 1073 |
893 If the first argument of a replace command is all lower case, the | 1074 If the first argument of a replace command is all lower case, the |
946 word-delimiter characters. | 1127 word-delimiter characters. |
947 | 1128 |
948 @kindex C-M-% | 1129 @kindex C-M-% |
949 @findex query-replace-regexp | 1130 @findex query-replace-regexp |
950 @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). | 1131 @kbd{C-M-%} performs regexp search and replace (@code{query-replace-regexp}). |
1132 It works like @code{replace-regexp} except that it queries | |
1133 like @code{query-replace}. | |
1134 | |
1135 @cindex faces for highlighting query replace | |
1136 These commands highlight the current match using the face | |
1137 @code{query-replace}. They highlight other matches using | |
1138 @code{lazy-highlight} just like incremental search (@pxref{Incremental | |
1139 Search}). | |
951 | 1140 |
952 The characters you can type when you are shown a match for the string | 1141 The characters you can type when you are shown a match for the string |
953 or regexp are: | 1142 or regexp are: |
954 | 1143 |
955 @ignore @c Not worth it. | 1144 @ignore @c Not worth it. |
995 @item ! | 1184 @item ! |
996 to replace all remaining occurrences without asking again. | 1185 to replace all remaining occurrences without asking again. |
997 | 1186 |
998 @item ^ | 1187 @item ^ |
999 to go back to the position of the previous occurrence (or what used to | 1188 to go back to the position of the previous occurrence (or what used to |
1000 be an occurrence), in case you changed it by mistake. This works by | 1189 be an occurrence), in case you changed it by mistake or want to |
1001 popping the mark ring. Only one @kbd{^} in a row is meaningful, because | 1190 reexamine it. |
1002 only one previous replacement position is kept during @code{query-replace}. | |
1003 | 1191 |
1004 @item C-r | 1192 @item C-r |
1005 to enter a recursive editing level, in case the occurrence needs to be | 1193 to enter a recursive editing level, in case the occurrence needs to be |
1006 edited rather than just replaced with @var{newstring}. When you are | 1194 edited rather than just replaced with @var{newstring}. When you are |
1007 done, exit the recursive editing level with @kbd{C-M-c} to proceed to | 1195 done, exit the recursive editing level with @kbd{C-M-c} to proceed to |
1043 ESC}. | 1231 ESC}. |
1044 | 1232 |
1045 See also @ref{Transforming File Names}, for Dired commands to rename, | 1233 See also @ref{Transforming File Names}, for Dired commands to rename, |
1046 copy, or link files by replacing regexp matches in file names. | 1234 copy, or link files by replacing regexp matches in file names. |
1047 | 1235 |
1048 @node Other Repeating Search,, Replace, Search | 1236 @node Other Repeating Search |
1049 @section Other Search-and-Loop Commands | 1237 @section Other Search-and-Loop Commands |
1050 | 1238 |
1051 Here are some other commands that find matches for a regular | 1239 Here are some other commands that find matches for a regular |
1052 expression. They all ignore case in matching, if the pattern contains | 1240 expression. They all ignore case in matching, if the pattern contains |
1053 no upper-case letters and @code{case-fold-search} is non-@code{nil}. | 1241 no upper-case letters and @code{case-fold-search} is non-@code{nil}. |
1069 @item M-x occur @key{RET} @var{regexp} @key{RET} | 1257 @item M-x occur @key{RET} @var{regexp} @key{RET} |
1070 Display a list showing each line in the buffer that contains a match | 1258 Display a list showing each line in the buffer that contains a match |
1071 for @var{regexp}. To limit the search to part of the buffer, narrow | 1259 for @var{regexp}. To limit the search to part of the buffer, narrow |
1072 to that part (@pxref{Narrowing}). A numeric argument @var{n} | 1260 to that part (@pxref{Narrowing}). A numeric argument @var{n} |
1073 specifies that @var{n} lines of context are to be displayed before and | 1261 specifies that @var{n} lines of context are to be displayed before and |
1074 after each matching line. | 1262 after each matching line. Currently, @code{occur} can not correctly |
1263 handle multiline matches. | |
1075 | 1264 |
1076 @kindex RET @r{(Occur mode)} | 1265 @kindex RET @r{(Occur mode)} |
1077 @kindex o @r{(Occur mode)} | 1266 @kindex o @r{(Occur mode)} |
1078 @kindex C-o @r{(Occur mode)} | 1267 @kindex C-o @r{(Occur mode)} |
1079 The buffer @samp{*Occur*} containing the output serves as a menu for | 1268 The buffer @samp{*Occur*} containing the output serves as a menu for |
1082 point there and type @key{RET}; this switches to the buffer that was | 1271 point there and type @key{RET}; this switches to the buffer that was |
1083 searched and moves point to the original of the chosen occurrence. | 1272 searched and moves point to the original of the chosen occurrence. |
1084 @kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} | 1273 @kbd{o} and @kbd{C-o} display the match in another window; @kbd{C-o} |
1085 does not select it. | 1274 does not select it. |
1086 | 1275 |
1276 Occur mode supports the @code{next-error} functionality described in | |
1277 @ref{Compilation Mode}. | |
1278 | |
1087 @item M-x list-matching-lines | 1279 @item M-x list-matching-lines |
1088 Synonym for @kbd{M-x occur}. | 1280 Synonym for @kbd{M-x occur}. |
1089 | 1281 |
1090 @item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET} | 1282 @item M-x multi-occur @key{RET} @var{buffers} @key{RET} @var{regexp} @key{RET} |
1091 This function is just like @code{occur}, except it is able to search | 1283 This function is just like @code{occur}, except it is able to search |
1099 Print the number of matches for @var{regexp} that exist in the buffer | 1291 Print the number of matches for @var{regexp} that exist in the buffer |
1100 after point. In Transient Mark mode, if the region is active, the | 1292 after point. In Transient Mark mode, if the region is active, the |
1101 command operates on the region instead. | 1293 command operates on the region instead. |
1102 | 1294 |
1103 @item M-x flush-lines @key{RET} @var{regexp} @key{RET} | 1295 @item M-x flush-lines @key{RET} @var{regexp} @key{RET} |
1104 Delete each line that contains a match for @var{regexp}, operating on | 1296 This command deletes each line that contains a match for @var{regexp}, |
1105 the text after point. In Transient Mark mode, if the region is | 1297 operating on the text after point; it deletes the current line |
1106 active, the command operates on the region instead. | 1298 if it contains a match starting after point. In Transient Mark mode, |
1299 if the region is active, the command operates on the region instead; | |
1300 it deletes a line partially contained in the region if it contains a | |
1301 match entirely contained in the region. | |
1302 | |
1303 If a match is split across lines, @code{flush-lines} deletes all those | |
1304 lines. It deletes the lines before starting to look for the next | |
1305 match; hence, it ignores a match starting on the same line at which | |
1306 another match ended. | |
1107 | 1307 |
1108 @item M-x keep-lines @key{RET} @var{regexp} @key{RET} | 1308 @item M-x keep-lines @key{RET} @var{regexp} @key{RET} |
1109 Delete each line that @emph{does not} contain a match for | 1309 This command deletes each line that @emph{does not} contain a match for |
1110 @var{regexp}, operating on the text after point. In Transient Mark | 1310 @var{regexp}, operating on the text after point; if point is not at the |
1111 mode, if the region is active, the command operates on the region | 1311 beginning of a line, it always keeps the current line. In Transient |
1112 instead. | 1312 Mark mode, if the region is active, the command operates on the region |
1313 instead; it never deletes lines that are only partially contained in | |
1314 the region (a newline that ends a line counts as part of that line). | |
1315 | |
1316 If a match is split across lines, this command keeps all those lines. | |
1113 @end table | 1317 @end table |
1114 | 1318 |
1115 You can also search multiple files under control of a tags table | 1319 You can also search multiple files under control of a tags table |
1116 (@pxref{Tags Search}) or through Dired @kbd{A} command | 1320 (@pxref{Tags Search}) or through the Dired @kbd{A} command |
1117 (@pxref{Operating on Files}), or ask the @code{grep} program to do it | 1321 (@pxref{Operating on Files}), or ask the @code{grep} program to do it |
1118 (@pxref{Grep Searching}). | 1322 (@pxref{Grep Searching}). |
1323 | |
1324 @ignore | |
1325 arch-tag: fd9d8e77-66af-491c-b212-d80999613e3e | |
1326 @end ignore |