annotate man/search.texi @ 27881:f54471f7b913

replace-regexps-in-string, mouse-position-function, define-key-after change
author Dave Love <fx@gnu.org>
date Sat, 26 Feb 2000 14:00:51 +0000
parents 5c14849aee4c
children f1b33463506d
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
1 @c This is part of the Emacs manual.
27217
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
2 @c Copyright (C) 1985, 86, 87, 93-95, 97, 2000 Free Software Foundation, Inc.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
3 @c See file emacs.texi for copying conditions.
Dave Love <fx@gnu.org>
parents:
diff changeset
4 @node Search, Fixit, Display, Top
Dave Love <fx@gnu.org>
parents:
diff changeset
5 @chapter Searching and Replacement
Dave Love <fx@gnu.org>
parents:
diff changeset
6 @cindex searching
Dave Love <fx@gnu.org>
parents:
diff changeset
7 @cindex finding strings within text
Dave Love <fx@gnu.org>
parents:
diff changeset
8
Dave Love <fx@gnu.org>
parents:
diff changeset
9 Like other editors, Emacs has commands for searching for occurrences of
Dave Love <fx@gnu.org>
parents:
diff changeset
10 a string. The principal search command is unusual in that it is
Dave Love <fx@gnu.org>
parents:
diff changeset
11 @dfn{incremental}; it begins to search before you have finished typing the
Dave Love <fx@gnu.org>
parents:
diff changeset
12 search string. There are also nonincremental search commands more like
Dave Love <fx@gnu.org>
parents:
diff changeset
13 those of other editors.
Dave Love <fx@gnu.org>
parents:
diff changeset
14
Dave Love <fx@gnu.org>
parents:
diff changeset
15 Besides the usual @code{replace-string} command that finds all
Dave Love <fx@gnu.org>
parents:
diff changeset
16 occurrences of one string and replaces them with another, Emacs has a fancy
Dave Love <fx@gnu.org>
parents:
diff changeset
17 replacement command called @code{query-replace} which asks interactively
Dave Love <fx@gnu.org>
parents:
diff changeset
18 which occurrences to replace.
Dave Love <fx@gnu.org>
parents:
diff changeset
19
Dave Love <fx@gnu.org>
parents:
diff changeset
20 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
21 * Incremental Search:: Search happens as you type the string.
Dave Love <fx@gnu.org>
parents:
diff changeset
22 * Nonincremental Search:: Specify entire string and then search.
Dave Love <fx@gnu.org>
parents:
diff changeset
23 * Word Search:: Search for sequence of words.
Dave Love <fx@gnu.org>
parents:
diff changeset
24 * Regexp Search:: Search for match for a regexp.
Dave Love <fx@gnu.org>
parents:
diff changeset
25 * Regexps:: Syntax of regular expressions.
Dave Love <fx@gnu.org>
parents:
diff changeset
26 * Search Case:: To ignore case while searching, or not.
Dave Love <fx@gnu.org>
parents:
diff changeset
27 * Replace:: Search, and replace some or all matches.
Dave Love <fx@gnu.org>
parents:
diff changeset
28 * Other Repeating Search:: Operating on all matches for some regexp.
Dave Love <fx@gnu.org>
parents:
diff changeset
29 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
30
Dave Love <fx@gnu.org>
parents:
diff changeset
31 @node Incremental Search, Nonincremental Search, Search, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
32 @section Incremental Search
Dave Love <fx@gnu.org>
parents:
diff changeset
33
Dave Love <fx@gnu.org>
parents:
diff changeset
34 @cindex incremental search
Dave Love <fx@gnu.org>
parents:
diff changeset
35 An incremental search begins searching as soon as you type the first
Dave Love <fx@gnu.org>
parents:
diff changeset
36 character of the search string. As you type in the search string, Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
37 shows you where the string (as you have typed it so far) would be
Dave Love <fx@gnu.org>
parents:
diff changeset
38 found. When you have typed enough characters to identify the place you
Dave Love <fx@gnu.org>
parents:
diff changeset
39 want, you can stop. Depending on what you plan to do next, you may or
Dave Love <fx@gnu.org>
parents:
diff changeset
40 may not need to terminate the search explicitly with @key{RET}.
Dave Love <fx@gnu.org>
parents:
diff changeset
41
Dave Love <fx@gnu.org>
parents:
diff changeset
42 @c WideCommands
Dave Love <fx@gnu.org>
parents:
diff changeset
43 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
44 @item C-s
Dave Love <fx@gnu.org>
parents:
diff changeset
45 Incremental search forward (@code{isearch-forward}).
Dave Love <fx@gnu.org>
parents:
diff changeset
46 @item C-r
Dave Love <fx@gnu.org>
parents:
diff changeset
47 Incremental search backward (@code{isearch-backward}).
Dave Love <fx@gnu.org>
parents:
diff changeset
48 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
49
Dave Love <fx@gnu.org>
parents:
diff changeset
50 @kindex C-s
Dave Love <fx@gnu.org>
parents:
diff changeset
51 @findex isearch-forward
Dave Love <fx@gnu.org>
parents:
diff changeset
52 @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from
Dave Love <fx@gnu.org>
parents:
diff changeset
53 the keyboard and positions the cursor at the first occurrence of the
Dave Love <fx@gnu.org>
parents:
diff changeset
54 characters that you have typed. If you type @kbd{C-s} and then @kbd{F},
Dave Love <fx@gnu.org>
parents:
diff changeset
55 the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see
Dave Love <fx@gnu.org>
parents:
diff changeset
56 the cursor move to after the first @samp{FO}. After another @kbd{O}, the
Dave Love <fx@gnu.org>
parents:
diff changeset
57 cursor is after the first @samp{FOO} after the place where you started the
Dave Love <fx@gnu.org>
parents:
diff changeset
58 search. At each step, the buffer text that matches the search string is
Dave Love <fx@gnu.org>
parents:
diff changeset
59 highlighted, if the terminal can do that; at each step, the current search
Dave Love <fx@gnu.org>
parents:
diff changeset
60 string is updated in the echo area.
Dave Love <fx@gnu.org>
parents:
diff changeset
61
Dave Love <fx@gnu.org>
parents:
diff changeset
62 If you make a mistake in typing the search string, you can cancel
Dave Love <fx@gnu.org>
parents:
diff changeset
63 characters with @key{DEL}. Each @key{DEL} cancels the last character of
Dave Love <fx@gnu.org>
parents:
diff changeset
64 search string. This does not happen until Emacs is ready to read another
Dave Love <fx@gnu.org>
parents:
diff changeset
65 input character; first it must either find, or fail to find, the character
Dave Love <fx@gnu.org>
parents:
diff changeset
66 you want to erase. If you do not want to wait for this to happen, use
Dave Love <fx@gnu.org>
parents:
diff changeset
67 @kbd{C-g} as described below.
Dave Love <fx@gnu.org>
parents:
diff changeset
68
Dave Love <fx@gnu.org>
parents:
diff changeset
69 When you are satisfied with the place you have reached, you can type
Dave Love <fx@gnu.org>
parents:
diff changeset
70 @key{RET}, which stops searching, leaving the cursor where the search
Dave Love <fx@gnu.org>
parents:
diff changeset
71 brought it. Also, any command not specially meaningful in searches
Dave Love <fx@gnu.org>
parents:
diff changeset
72 stops the searching and is then executed. Thus, typing @kbd{C-a} would
Dave Love <fx@gnu.org>
parents:
diff changeset
73 exit the search and then move to the beginning of the line. @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
74 is necessary only if the next command you want to type is a printing
Dave Love <fx@gnu.org>
parents:
diff changeset
75 character, @key{DEL}, @key{RET}, or another control character that is
Dave Love <fx@gnu.org>
parents:
diff changeset
76 special within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s},
Dave Love <fx@gnu.org>
parents:
diff changeset
77 @kbd{C-y}, @kbd{M-y}, @kbd{M-r}, or @kbd{M-s}).
Dave Love <fx@gnu.org>
parents:
diff changeset
78
Dave Love <fx@gnu.org>
parents:
diff changeset
79 Sometimes you search for @samp{FOO} and find it, but not the one you
Dave Love <fx@gnu.org>
parents:
diff changeset
80 expected to find. There was a second @samp{FOO} that you forgot about,
Dave Love <fx@gnu.org>
parents:
diff changeset
81 before the one you were aiming for. In this event, type another @kbd{C-s}
Dave Love <fx@gnu.org>
parents:
diff changeset
82 to move to the next occurrence of the search string. This can be done any
Dave Love <fx@gnu.org>
parents:
diff changeset
83 number of times. If you overshoot, you can cancel some @kbd{C-s}
Dave Love <fx@gnu.org>
parents:
diff changeset
84 characters with @key{DEL}.
Dave Love <fx@gnu.org>
parents:
diff changeset
85
Dave Love <fx@gnu.org>
parents:
diff changeset
86 After you exit a search, you can search for the same string again by
Dave Love <fx@gnu.org>
parents:
diff changeset
87 typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes
Dave Love <fx@gnu.org>
parents:
diff changeset
88 incremental search, and the second @kbd{C-s} means ``search again.''
Dave Love <fx@gnu.org>
parents:
diff changeset
89
Dave Love <fx@gnu.org>
parents:
diff changeset
90 To reuse earlier search strings, use the @dfn{search ring}. The
Dave Love <fx@gnu.org>
parents:
diff changeset
91 commands @kbd{M-p} and @kbd{M-n} move through the ring to pick a search
Dave Love <fx@gnu.org>
parents:
diff changeset
92 string to reuse. These commands leave the selected search ring element
Dave Love <fx@gnu.org>
parents:
diff changeset
93 in the minibuffer, where you can edit it. Type @kbd{C-s} or @kbd{C-r}
Dave Love <fx@gnu.org>
parents:
diff changeset
94 to terminate editing the string and search for it.
Dave Love <fx@gnu.org>
parents:
diff changeset
95
Dave Love <fx@gnu.org>
parents:
diff changeset
96 If your string is not found at all, the echo area says @samp{Failing
Dave Love <fx@gnu.org>
parents:
diff changeset
97 I-Search}. The cursor is after the place where Emacs found as much of your
Dave Love <fx@gnu.org>
parents:
diff changeset
98 string as it could. Thus, if you search for @samp{FOOT}, and there is no
Dave Love <fx@gnu.org>
parents:
diff changeset
99 @samp{FOOT}, you might see the cursor after the @samp{FOO} in @samp{FOOL}.
Dave Love <fx@gnu.org>
parents:
diff changeset
100 At this point there are several things you can do. If your string was
Dave Love <fx@gnu.org>
parents:
diff changeset
101 mistyped, you can rub some of it out and correct it. If you like the place
Dave Love <fx@gnu.org>
parents:
diff changeset
102 you have found, you can type @key{RET} or some other Emacs command to
Dave Love <fx@gnu.org>
parents:
diff changeset
103 ``accept what the search offered.'' Or you can type @kbd{C-g}, which
Dave Love <fx@gnu.org>
parents:
diff changeset
104 removes from the search string the characters that could not be found (the
Dave Love <fx@gnu.org>
parents:
diff changeset
105 @samp{T} in @samp{FOOT}), leaving those that were found (the @samp{FOO} in
Dave Love <fx@gnu.org>
parents:
diff changeset
106 @samp{FOOT}). A second @kbd{C-g} at that point cancels the search
Dave Love <fx@gnu.org>
parents:
diff changeset
107 entirely, returning point to where it was when the search started.
Dave Love <fx@gnu.org>
parents:
diff changeset
108
Dave Love <fx@gnu.org>
parents:
diff changeset
109 An upper-case letter in the search string makes the search
Dave Love <fx@gnu.org>
parents:
diff changeset
110 case-sensitive. If you delete the upper-case character from the search
Dave Love <fx@gnu.org>
parents:
diff changeset
111 string, it ceases to have this effect. @xref{Search Case}.
Dave Love <fx@gnu.org>
parents:
diff changeset
112
Dave Love <fx@gnu.org>
parents:
diff changeset
113 If a search is failing and you ask to repeat it by typing another
Dave Love <fx@gnu.org>
parents:
diff changeset
114 @kbd{C-s}, it starts again from the beginning of the buffer. Repeating
Dave Love <fx@gnu.org>
parents:
diff changeset
115 a failing reverse search with @kbd{C-r} starts again from the end. This
Dave Love <fx@gnu.org>
parents:
diff changeset
116 is called @dfn{wrapping around}. @samp{Wrapped} appears in the search
Dave Love <fx@gnu.org>
parents:
diff changeset
117 prompt once this has happened. If you keep on going past the original
Dave Love <fx@gnu.org>
parents:
diff changeset
118 starting point of the search, it changes to @samp{Overwrapped}, which
Dave Love <fx@gnu.org>
parents:
diff changeset
119 means that you are revisiting matches that you have already seen.
Dave Love <fx@gnu.org>
parents:
diff changeset
120
Dave Love <fx@gnu.org>
parents:
diff changeset
121 @cindex quitting (in search)
Dave Love <fx@gnu.org>
parents:
diff changeset
122 The @kbd{C-g} ``quit'' character does special things during searches;
Dave Love <fx@gnu.org>
parents:
diff changeset
123 just what it does depends on the status of the search. If the search has
Dave Love <fx@gnu.org>
parents:
diff changeset
124 found what you specified and is waiting for input, @kbd{C-g} cancels the
Dave Love <fx@gnu.org>
parents:
diff changeset
125 entire search. The cursor moves back to where you started the search. If
Dave Love <fx@gnu.org>
parents:
diff changeset
126 @kbd{C-g} is typed when there are characters in the search string that have
Dave Love <fx@gnu.org>
parents:
diff changeset
127 not been found---because Emacs is still searching for them, or because it
Dave Love <fx@gnu.org>
parents:
diff changeset
128 has failed to find them---then the search string characters which have not
Dave Love <fx@gnu.org>
parents:
diff changeset
129 been found are discarded from the search string. With them gone, the
Dave Love <fx@gnu.org>
parents:
diff changeset
130 search is now successful and waiting for more input, so a second @kbd{C-g}
Dave Love <fx@gnu.org>
parents:
diff changeset
131 will cancel the entire search.
Dave Love <fx@gnu.org>
parents:
diff changeset
132
Dave Love <fx@gnu.org>
parents:
diff changeset
133 To search for a newline, type @kbd{C-j}. To search for another
Dave Love <fx@gnu.org>
parents:
diff changeset
134 control character, such as control-S or carriage return, you must quote
Dave Love <fx@gnu.org>
parents:
diff changeset
135 it by typing @kbd{C-q} first. This function of @kbd{C-q} is analogous
Dave Love <fx@gnu.org>
parents:
diff changeset
136 to its use for insertion (@pxref{Inserting Text}): it causes the
Dave Love <fx@gnu.org>
parents:
diff changeset
137 following character to be treated the way any ``ordinary'' character is
Dave Love <fx@gnu.org>
parents:
diff changeset
138 treated in the same context. You can also specify a character by its
Dave Love <fx@gnu.org>
parents:
diff changeset
139 octal code: enter @kbd{C-q} followed by a sequence of octal digits.
Dave Love <fx@gnu.org>
parents:
diff changeset
140
Dave Love <fx@gnu.org>
parents:
diff changeset
141 You can change to searching backwards with @kbd{C-r}. If a search fails
Dave Love <fx@gnu.org>
parents:
diff changeset
142 because the place you started was too late in the file, you should do this.
Dave Love <fx@gnu.org>
parents:
diff changeset
143 Repeated @kbd{C-r} keeps looking for more occurrences backwards. A
Dave Love <fx@gnu.org>
parents:
diff changeset
144 @kbd{C-s} starts going forwards again. @kbd{C-r} in a search can be canceled
Dave Love <fx@gnu.org>
parents:
diff changeset
145 with @key{DEL}.
Dave Love <fx@gnu.org>
parents:
diff changeset
146
Dave Love <fx@gnu.org>
parents:
diff changeset
147 @kindex C-r
Dave Love <fx@gnu.org>
parents:
diff changeset
148 @findex isearch-backward
Dave Love <fx@gnu.org>
parents:
diff changeset
149 If you know initially that you want to search backwards, you can use
Dave Love <fx@gnu.org>
parents:
diff changeset
150 @kbd{C-r} instead of @kbd{C-s} to start the search, because @kbd{C-r} as
Dave Love <fx@gnu.org>
parents:
diff changeset
151 a key runs a command (@code{isearch-backward}) to search backward. A
Dave Love <fx@gnu.org>
parents:
diff changeset
152 backward search finds matches that are entirely before the starting
Dave Love <fx@gnu.org>
parents:
diff changeset
153 point, just as a forward search finds matches that begin after it.
Dave Love <fx@gnu.org>
parents:
diff changeset
154
Dave Love <fx@gnu.org>
parents:
diff changeset
155 The characters @kbd{C-y} and @kbd{C-w} can be used in incremental
Dave Love <fx@gnu.org>
parents:
diff changeset
156 search to grab text from the buffer into the search string. This makes
Dave Love <fx@gnu.org>
parents:
diff changeset
157 it convenient to search for another occurrence of text at point.
Dave Love <fx@gnu.org>
parents:
diff changeset
158 @kbd{C-w} copies the word after point as part of the search string,
Dave Love <fx@gnu.org>
parents:
diff changeset
159 advancing point over that word. Another @kbd{C-s} to repeat the search
Dave Love <fx@gnu.org>
parents:
diff changeset
160 will then search for a string including that word. @kbd{C-y} is similar
Dave Love <fx@gnu.org>
parents:
diff changeset
161 to @kbd{C-w} but copies all the rest of the current line into the search
Dave Love <fx@gnu.org>
parents:
diff changeset
162 string. Both @kbd{C-y} and @kbd{C-w} convert the text they copy to
Dave Love <fx@gnu.org>
parents:
diff changeset
163 lower case if the search is currently not case-sensitive; this is so the
Dave Love <fx@gnu.org>
parents:
diff changeset
164 search remains case-insensitive.
Dave Love <fx@gnu.org>
parents:
diff changeset
165
Dave Love <fx@gnu.org>
parents:
diff changeset
166 The character @kbd{M-y} copies text from the kill ring into the search
Dave Love <fx@gnu.org>
parents:
diff changeset
167 string. It uses the same text that @kbd{C-y} as a command would yank.
27217
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
168 @kbd{mouse-2} in the echo area does the same.
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
169 @xref{Yanking}.
Dave Love <fx@gnu.org>
parents:
diff changeset
170
Dave Love <fx@gnu.org>
parents:
diff changeset
171 When you exit the incremental search, it sets the mark to where point
Dave Love <fx@gnu.org>
parents:
diff changeset
172 @emph{was}, before the search. That is convenient for moving back
Dave Love <fx@gnu.org>
parents:
diff changeset
173 there. In Transient Mark mode, incremental search sets the mark without
Dave Love <fx@gnu.org>
parents:
diff changeset
174 activating it, and does so only if the mark is not already active.
Dave Love <fx@gnu.org>
parents:
diff changeset
175
27217
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
176 @cindex lazy search highlighting
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
177 By default, Isearch uses @dfn{lazy highlighting}. All matches for
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
178 the current search string in the buffer after the point where searching
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
179 starts are highlighted. The extra highlighting makes it easier to
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
180 anticipate where the cursor will end up each time you press @kbd{C-s} or
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
181 @kbd{C-r} to repeat a pending search. Highlighting of these additional
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
182 matches happens in a deferred fashion so as not to rob Isearch of its
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
183 usual snappy response.
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
184 @vindex isearch-lazy-highlight-cleanup
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
185 By default the highlighting of matches is cleared when you end the
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
186 search. Customize the variable @code{isearch-lazy-highlight-cleanup} to
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
187 avoid cleaning up automatically. The command @kbd{M-x
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
188 isearch-lazy-highlight-cleanup} can be used to clean up manually.
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
189 @vindex isearch-lazy-highlight
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
190 Customize the variable @code{isearch-lazy-highlight} to turn off this
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
191 feature.
d21dbd5dc0b1 Lazy highlighting.
Dave Love <fx@gnu.org>
parents: 27139
diff changeset
192
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
193 @vindex isearch-mode-map
Dave Love <fx@gnu.org>
parents:
diff changeset
194 To customize the special characters that incremental search understands,
Dave Love <fx@gnu.org>
parents:
diff changeset
195 alter their bindings in the keymap @code{isearch-mode-map}. For a list
Dave Love <fx@gnu.org>
parents:
diff changeset
196 of bindings, look at the documentation of @code{isearch-mode} with
Dave Love <fx@gnu.org>
parents:
diff changeset
197 @kbd{C-h f isearch-mode @key{RET}}.
Dave Love <fx@gnu.org>
parents:
diff changeset
198
Dave Love <fx@gnu.org>
parents:
diff changeset
199 @subsection Slow Terminal Incremental Search
Dave Love <fx@gnu.org>
parents:
diff changeset
200
Dave Love <fx@gnu.org>
parents:
diff changeset
201 Incremental search on a slow terminal uses a modified style of display
Dave Love <fx@gnu.org>
parents:
diff changeset
202 that is designed to take less time. Instead of redisplaying the buffer at
Dave Love <fx@gnu.org>
parents:
diff changeset
203 each place the search gets to, it creates a new single-line window and uses
Dave Love <fx@gnu.org>
parents:
diff changeset
204 that to display the line that the search has found. The single-line window
Dave Love <fx@gnu.org>
parents:
diff changeset
205 comes into play as soon as point gets outside of the text that is already
Dave Love <fx@gnu.org>
parents:
diff changeset
206 on the screen.
Dave Love <fx@gnu.org>
parents:
diff changeset
207
Dave Love <fx@gnu.org>
parents:
diff changeset
208 When you terminate the search, the single-line window is removed.
Dave Love <fx@gnu.org>
parents:
diff changeset
209 Then Emacs redisplays the window in which the search was done, to show
Dave Love <fx@gnu.org>
parents:
diff changeset
210 its new position of point.
Dave Love <fx@gnu.org>
parents:
diff changeset
211
Dave Love <fx@gnu.org>
parents:
diff changeset
212 @ignore
Dave Love <fx@gnu.org>
parents:
diff changeset
213 The three dots at the end of the search string, normally used to indicate
Dave Love <fx@gnu.org>
parents:
diff changeset
214 that searching is going on, are not displayed in slow style display.
Dave Love <fx@gnu.org>
parents:
diff changeset
215 @end ignore
Dave Love <fx@gnu.org>
parents:
diff changeset
216
Dave Love <fx@gnu.org>
parents:
diff changeset
217 @vindex search-slow-speed
Dave Love <fx@gnu.org>
parents:
diff changeset
218 The slow terminal style of display is used when the terminal baud rate is
Dave Love <fx@gnu.org>
parents:
diff changeset
219 less than or equal to the value of the variable @code{search-slow-speed},
Dave Love <fx@gnu.org>
parents:
diff changeset
220 initially 1200.
Dave Love <fx@gnu.org>
parents:
diff changeset
221
Dave Love <fx@gnu.org>
parents:
diff changeset
222 @vindex search-slow-window-lines
Dave Love <fx@gnu.org>
parents:
diff changeset
223 The number of lines to use in slow terminal search display is controlled
Dave Love <fx@gnu.org>
parents:
diff changeset
224 by the variable @code{search-slow-window-lines}. Its normal value is 1.
Dave Love <fx@gnu.org>
parents:
diff changeset
225
Dave Love <fx@gnu.org>
parents:
diff changeset
226 @node Nonincremental Search, Word Search, Incremental Search, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
227 @section Nonincremental Search
Dave Love <fx@gnu.org>
parents:
diff changeset
228 @cindex nonincremental search
Dave Love <fx@gnu.org>
parents:
diff changeset
229
Dave Love <fx@gnu.org>
parents:
diff changeset
230 Emacs also has conventional nonincremental search commands, which require
Dave Love <fx@gnu.org>
parents:
diff changeset
231 you to type the entire search string before searching begins.
Dave Love <fx@gnu.org>
parents:
diff changeset
232
Dave Love <fx@gnu.org>
parents:
diff changeset
233 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
234 @item C-s @key{RET} @var{string} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
235 Search for @var{string}.
Dave Love <fx@gnu.org>
parents:
diff changeset
236 @item C-r @key{RET} @var{string} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
237 Search backward for @var{string}.
Dave Love <fx@gnu.org>
parents:
diff changeset
238 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
239
Dave Love <fx@gnu.org>
parents:
diff changeset
240 To do a nonincremental search, first type @kbd{C-s @key{RET}}. This
Dave Love <fx@gnu.org>
parents:
diff changeset
241 enters the minibuffer to read the search string; terminate the string
Dave Love <fx@gnu.org>
parents:
diff changeset
242 with @key{RET}, and then the search takes place. If the string is not
Dave Love <fx@gnu.org>
parents:
diff changeset
243 found, the search command gets an error.
Dave Love <fx@gnu.org>
parents:
diff changeset
244
Dave Love <fx@gnu.org>
parents:
diff changeset
245 The way @kbd{C-s @key{RET}} works is that the @kbd{C-s} invokes
Dave Love <fx@gnu.org>
parents:
diff changeset
246 incremental search, which is specially programmed to invoke nonincremental
Dave Love <fx@gnu.org>
parents:
diff changeset
247 search if the argument you give it is empty. (Such an empty argument would
Dave Love <fx@gnu.org>
parents:
diff changeset
248 otherwise be useless.) @kbd{C-r @key{RET}} also works this way.
Dave Love <fx@gnu.org>
parents:
diff changeset
249
Dave Love <fx@gnu.org>
parents:
diff changeset
250 However, nonincremental searches performed using @kbd{C-s @key{RET}} do
Dave Love <fx@gnu.org>
parents:
diff changeset
251 not call @code{search-forward} right away. The first thing done is to see
Dave Love <fx@gnu.org>
parents:
diff changeset
252 if the next character is @kbd{C-w}, which requests a word search.
Dave Love <fx@gnu.org>
parents:
diff changeset
253 @ifinfo
Dave Love <fx@gnu.org>
parents:
diff changeset
254 @xref{Word Search}.
Dave Love <fx@gnu.org>
parents:
diff changeset
255 @end ifinfo
Dave Love <fx@gnu.org>
parents:
diff changeset
256
Dave Love <fx@gnu.org>
parents:
diff changeset
257 @findex search-forward
Dave Love <fx@gnu.org>
parents:
diff changeset
258 @findex search-backward
Dave Love <fx@gnu.org>
parents:
diff changeset
259 Forward and backward nonincremental searches are implemented by the
Dave Love <fx@gnu.org>
parents:
diff changeset
260 commands @code{search-forward} and @code{search-backward}. These
Dave Love <fx@gnu.org>
parents:
diff changeset
261 commands may be bound to keys in the usual manner. The feature that you
Dave Love <fx@gnu.org>
parents:
diff changeset
262 can get to them via the incremental search commands exists for
Dave Love <fx@gnu.org>
parents:
diff changeset
263 historical reasons, and to avoid the need to find suitable key sequences
Dave Love <fx@gnu.org>
parents:
diff changeset
264 for them.
Dave Love <fx@gnu.org>
parents:
diff changeset
265
Dave Love <fx@gnu.org>
parents:
diff changeset
266 @node Word Search, Regexp Search, Nonincremental Search, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
267 @section Word Search
Dave Love <fx@gnu.org>
parents:
diff changeset
268 @cindex word search
Dave Love <fx@gnu.org>
parents:
diff changeset
269
Dave Love <fx@gnu.org>
parents:
diff changeset
270 Word search searches for a sequence of words without regard to how the
Dave Love <fx@gnu.org>
parents:
diff changeset
271 words are separated. More precisely, you type a string of many words,
Dave Love <fx@gnu.org>
parents:
diff changeset
272 using single spaces to separate them, and the string can be found even if
Dave Love <fx@gnu.org>
parents:
diff changeset
273 there are multiple spaces, newlines or other punctuation between the words.
Dave Love <fx@gnu.org>
parents:
diff changeset
274
Dave Love <fx@gnu.org>
parents:
diff changeset
275 Word search is useful for editing a printed document made with a text
Dave Love <fx@gnu.org>
parents:
diff changeset
276 formatter. If you edit while looking at the printed, formatted version,
Dave Love <fx@gnu.org>
parents:
diff changeset
277 you can't tell where the line breaks are in the source file. With word
Dave Love <fx@gnu.org>
parents:
diff changeset
278 search, you can search without having to know them.
Dave Love <fx@gnu.org>
parents:
diff changeset
279
Dave Love <fx@gnu.org>
parents:
diff changeset
280 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
281 @item C-s @key{RET} C-w @var{words} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
282 Search for @var{words}, ignoring details of punctuation.
Dave Love <fx@gnu.org>
parents:
diff changeset
283 @item C-r @key{RET} C-w @var{words} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
284 Search backward for @var{words}, ignoring details of punctuation.
Dave Love <fx@gnu.org>
parents:
diff changeset
285 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
286
Dave Love <fx@gnu.org>
parents:
diff changeset
287 Word search is a special case of nonincremental search and is invoked
Dave Love <fx@gnu.org>
parents:
diff changeset
288 with @kbd{C-s @key{RET} C-w}. This is followed by the search string,
Dave Love <fx@gnu.org>
parents:
diff changeset
289 which must always be terminated with @key{RET}. Being nonincremental,
Dave Love <fx@gnu.org>
parents:
diff changeset
290 this search does not start until the argument is terminated. It works
Dave Love <fx@gnu.org>
parents:
diff changeset
291 by constructing a regular expression and searching for that; see
Dave Love <fx@gnu.org>
parents:
diff changeset
292 @ref{Regexp Search}.
Dave Love <fx@gnu.org>
parents:
diff changeset
293
Dave Love <fx@gnu.org>
parents:
diff changeset
294 Use @kbd{C-r @key{RET} C-w} to do backward word search.
Dave Love <fx@gnu.org>
parents:
diff changeset
295
Dave Love <fx@gnu.org>
parents:
diff changeset
296 @findex word-search-forward
Dave Love <fx@gnu.org>
parents:
diff changeset
297 @findex word-search-backward
Dave Love <fx@gnu.org>
parents:
diff changeset
298 Forward and backward word searches are implemented by the commands
Dave Love <fx@gnu.org>
parents:
diff changeset
299 @code{word-search-forward} and @code{word-search-backward}. These
Dave Love <fx@gnu.org>
parents:
diff changeset
300 commands may be bound to keys in the usual manner. The feature that you
Dave Love <fx@gnu.org>
parents:
diff changeset
301 can get to them via the incremental search commands exists for historical
Dave Love <fx@gnu.org>
parents:
diff changeset
302 reasons, and to avoid the need to find suitable key sequences for them.
Dave Love <fx@gnu.org>
parents:
diff changeset
303
Dave Love <fx@gnu.org>
parents:
diff changeset
304 @node Regexp Search, Regexps, Word Search, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
305 @section Regular Expression Search
Dave Love <fx@gnu.org>
parents:
diff changeset
306 @cindex regular expression
Dave Love <fx@gnu.org>
parents:
diff changeset
307 @cindex regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
308
Dave Love <fx@gnu.org>
parents:
diff changeset
309 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
Dave Love <fx@gnu.org>
parents:
diff changeset
310 denotes a class of alternative strings to match, possibly infinitely
Dave Love <fx@gnu.org>
parents:
diff changeset
311 many. In GNU Emacs, you can search for the next match for a regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
312 either incrementally or not.
Dave Love <fx@gnu.org>
parents:
diff changeset
313
Dave Love <fx@gnu.org>
parents:
diff changeset
314 @kindex C-M-s
Dave Love <fx@gnu.org>
parents:
diff changeset
315 @findex isearch-forward-regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
316 @kindex C-M-r
Dave Love <fx@gnu.org>
parents:
diff changeset
317 @findex isearch-backward-regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
318 Incremental search for a regexp is done by typing @kbd{C-M-s}
Dave Love <fx@gnu.org>
parents:
diff changeset
319 (@code{isearch-forward-regexp}). This command reads a search string
Dave Love <fx@gnu.org>
parents:
diff changeset
320 incrementally just like @kbd{C-s}, but it treats the search string as a
Dave Love <fx@gnu.org>
parents:
diff changeset
321 regexp rather than looking for an exact match against the text in the
Dave Love <fx@gnu.org>
parents:
diff changeset
322 buffer. Each time you add text to the search string, you make the
Dave Love <fx@gnu.org>
parents:
diff changeset
323 regexp longer, and the new regexp is searched for. Invoking @kbd{C-s}
Dave Love <fx@gnu.org>
parents:
diff changeset
324 with a prefix argument (its value does not matter) is another way to do
Dave Love <fx@gnu.org>
parents:
diff changeset
325 a forward incremental regexp search. To search backward for a regexp,
Dave Love <fx@gnu.org>
parents:
diff changeset
326 use @kbd{C-M-r} (@code{isearch-backward-regexp}), or @kbd{C-r} with a
Dave Love <fx@gnu.org>
parents:
diff changeset
327 prefix argument.
Dave Love <fx@gnu.org>
parents:
diff changeset
328
Dave Love <fx@gnu.org>
parents:
diff changeset
329 All of the control characters that do special things within an
Dave Love <fx@gnu.org>
parents:
diff changeset
330 ordinary incremental search have the same function in incremental regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
331 search. Typing @kbd{C-s} or @kbd{C-r} immediately after starting the
Dave Love <fx@gnu.org>
parents:
diff changeset
332 search retrieves the last incremental search regexp used; that is to
Dave Love <fx@gnu.org>
parents:
diff changeset
333 say, incremental regexp and non-regexp searches have independent
Dave Love <fx@gnu.org>
parents:
diff changeset
334 defaults. They also have separate search rings that you can access with
Dave Love <fx@gnu.org>
parents:
diff changeset
335 @kbd{M-p} and @kbd{M-n}.
Dave Love <fx@gnu.org>
parents:
diff changeset
336
Dave Love <fx@gnu.org>
parents:
diff changeset
337 If you type @key{SPC} in incremental regexp search, it matches any
Dave Love <fx@gnu.org>
parents:
diff changeset
338 sequence of whitespace characters, including newlines. If you want
Dave Love <fx@gnu.org>
parents:
diff changeset
339 to match just a space, type @kbd{C-q @key{SPC}}.
Dave Love <fx@gnu.org>
parents:
diff changeset
340
Dave Love <fx@gnu.org>
parents:
diff changeset
341 Note that adding characters to the regexp in an incremental regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
342 search can make the cursor move back and start again. For example, if
Dave Love <fx@gnu.org>
parents:
diff changeset
343 you have searched for @samp{foo} and you add @samp{\|bar}, the cursor
Dave Love <fx@gnu.org>
parents:
diff changeset
344 backs up in case the first @samp{bar} precedes the first @samp{foo}.
Dave Love <fx@gnu.org>
parents:
diff changeset
345
Dave Love <fx@gnu.org>
parents:
diff changeset
346 @findex re-search-forward
Dave Love <fx@gnu.org>
parents:
diff changeset
347 @findex re-search-backward
Dave Love <fx@gnu.org>
parents:
diff changeset
348 Nonincremental search for a regexp is done by the functions
Dave Love <fx@gnu.org>
parents:
diff changeset
349 @code{re-search-forward} and @code{re-search-backward}. You can invoke
Dave Love <fx@gnu.org>
parents:
diff changeset
350 these with @kbd{M-x}, or bind them to keys, or invoke them by way of
Dave Love <fx@gnu.org>
parents:
diff changeset
351 incremental regexp search with @kbd{C-M-s @key{RET}} and @kbd{C-M-r
Dave Love <fx@gnu.org>
parents:
diff changeset
352 @key{RET}}.
Dave Love <fx@gnu.org>
parents:
diff changeset
353
Dave Love <fx@gnu.org>
parents:
diff changeset
354 If you use the incremental regexp search commands with a prefix
Dave Love <fx@gnu.org>
parents:
diff changeset
355 argument, they perform ordinary string search, like
Dave Love <fx@gnu.org>
parents:
diff changeset
356 @code{isearch-forward} and @code{isearch-backward}. @xref{Incremental
Dave Love <fx@gnu.org>
parents:
diff changeset
357 Search}.
Dave Love <fx@gnu.org>
parents:
diff changeset
358
Dave Love <fx@gnu.org>
parents:
diff changeset
359 @node Regexps, Search Case, Regexp Search, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
360 @section Syntax of Regular Expressions
Dave Love <fx@gnu.org>
parents:
diff changeset
361 @cindex regexp syntax
Dave Love <fx@gnu.org>
parents:
diff changeset
362
Dave Love <fx@gnu.org>
parents:
diff changeset
363 Regular expressions have a syntax in which a few characters are
Dave Love <fx@gnu.org>
parents:
diff changeset
364 special constructs and the rest are @dfn{ordinary}. An ordinary
Dave Love <fx@gnu.org>
parents:
diff changeset
365 character is a simple regular expression which matches that same
Dave Love <fx@gnu.org>
parents:
diff changeset
366 character and nothing else. The special characters are @samp{$},
Dave Love <fx@gnu.org>
parents:
diff changeset
367 @samp{^}, @samp{.}, @samp{*}, @samp{+}, @samp{?}, @samp{[}, @samp{]} and
Dave Love <fx@gnu.org>
parents:
diff changeset
368 @samp{\}. Any other character appearing in a regular expression is
Dave Love <fx@gnu.org>
parents:
diff changeset
369 ordinary, unless a @samp{\} precedes it.
Dave Love <fx@gnu.org>
parents:
diff changeset
370
Dave Love <fx@gnu.org>
parents:
diff changeset
371 For example, @samp{f} is not a special character, so it is ordinary, and
Dave Love <fx@gnu.org>
parents:
diff changeset
372 therefore @samp{f} is a regular expression that matches the string
Dave Love <fx@gnu.org>
parents:
diff changeset
373 @samp{f} and no other string. (It does @emph{not} match the string
Dave Love <fx@gnu.org>
parents:
diff changeset
374 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches
Dave Love <fx@gnu.org>
parents:
diff changeset
375 only @samp{o}. (When case distinctions are being ignored, these regexps
Dave Love <fx@gnu.org>
parents:
diff changeset
376 also match @samp{F} and @samp{O}, but we consider this a generalization
Dave Love <fx@gnu.org>
parents:
diff changeset
377 of ``the same string,'' rather than an exception.)
Dave Love <fx@gnu.org>
parents:
diff changeset
378
Dave Love <fx@gnu.org>
parents:
diff changeset
379 Any two regular expressions @var{a} and @var{b} can be concatenated. The
Dave Love <fx@gnu.org>
parents:
diff changeset
380 result is a regular expression which matches a string if @var{a} matches
Dave Love <fx@gnu.org>
parents:
diff changeset
381 some amount of the beginning of that string and @var{b} matches the rest of
Dave Love <fx@gnu.org>
parents:
diff changeset
382 the string.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
383
Dave Love <fx@gnu.org>
parents:
diff changeset
384 As a simple example, we can concatenate the regular expressions @samp{f}
Dave Love <fx@gnu.org>
parents:
diff changeset
385 and @samp{o} to get the regular expression @samp{fo}, which matches only
Dave Love <fx@gnu.org>
parents:
diff changeset
386 the string @samp{fo}. Still trivial. To do something nontrivial, you
Dave Love <fx@gnu.org>
parents:
diff changeset
387 need to use one of the special characters. Here is a list of them.
Dave Love <fx@gnu.org>
parents:
diff changeset
388
Dave Love <fx@gnu.org>
parents:
diff changeset
389 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
390 @item .@: @r{(Period)}
Dave Love <fx@gnu.org>
parents:
diff changeset
391 is a special character that matches any single character except a newline.
Dave Love <fx@gnu.org>
parents:
diff changeset
392 Using concatenation, we can make regular expressions like @samp{a.b}, which
Dave Love <fx@gnu.org>
parents:
diff changeset
393 matches any three-character string that begins with @samp{a} and ends with
Dave Love <fx@gnu.org>
parents:
diff changeset
394 @samp{b}.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
395
Dave Love <fx@gnu.org>
parents:
diff changeset
396 @item *
Dave Love <fx@gnu.org>
parents:
diff changeset
397 is not a construct by itself; it is a postfix operator that means to
Dave Love <fx@gnu.org>
parents:
diff changeset
398 match the preceding regular expression repetitively as many times as
Dave Love <fx@gnu.org>
parents:
diff changeset
399 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
Dave Love <fx@gnu.org>
parents:
diff changeset
400 @samp{o}s).
Dave Love <fx@gnu.org>
parents:
diff changeset
401
Dave Love <fx@gnu.org>
parents:
diff changeset
402 @samp{*} always applies to the @emph{smallest} possible preceding
Dave Love <fx@gnu.org>
parents:
diff changeset
403 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
Dave Love <fx@gnu.org>
parents:
diff changeset
404 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
Dave Love <fx@gnu.org>
parents:
diff changeset
405
Dave Love <fx@gnu.org>
parents:
diff changeset
406 The matcher processes a @samp{*} construct by matching, immediately,
Dave Love <fx@gnu.org>
parents:
diff changeset
407 as many repetitions as can be found. Then it continues with the rest
Dave Love <fx@gnu.org>
parents:
diff changeset
408 of the pattern. If that fails, backtracking occurs, discarding some
Dave Love <fx@gnu.org>
parents:
diff changeset
409 of the matches of the @samp{*}-modified construct in case that makes
Dave Love <fx@gnu.org>
parents:
diff changeset
410 it possible to match the rest of the pattern. For example, in matching
Dave Love <fx@gnu.org>
parents:
diff changeset
411 @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
Dave Love <fx@gnu.org>
parents:
diff changeset
412 tries to match all three @samp{a}s; but the rest of the pattern is
Dave Love <fx@gnu.org>
parents:
diff changeset
413 @samp{ar} and there is only @samp{r} left to match, so this try fails.
Dave Love <fx@gnu.org>
parents:
diff changeset
414 The next alternative is for @samp{a*} to match only two @samp{a}s.
Dave Love <fx@gnu.org>
parents:
diff changeset
415 With this choice, the rest of the regexp matches successfully.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
416
Dave Love <fx@gnu.org>
parents:
diff changeset
417 @item +
Dave Love <fx@gnu.org>
parents:
diff changeset
418 is a postfix operator, similar to @samp{*} except that it must match
Dave Love <fx@gnu.org>
parents:
diff changeset
419 the preceding expression at least once. So, for example, @samp{ca+r}
Dave Love <fx@gnu.org>
parents:
diff changeset
420 matches the strings @samp{car} and @samp{caaaar} but not the string
Dave Love <fx@gnu.org>
parents:
diff changeset
421 @samp{cr}, whereas @samp{ca*r} matches all three strings.
Dave Love <fx@gnu.org>
parents:
diff changeset
422
Dave Love <fx@gnu.org>
parents:
diff changeset
423 @item ?
Dave Love <fx@gnu.org>
parents:
diff changeset
424 is a postfix operator, similar to @samp{*} except that it can match the
Dave Love <fx@gnu.org>
parents:
diff changeset
425 preceding expression either once or not at all. For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
426 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
Dave Love <fx@gnu.org>
parents:
diff changeset
427
27094
6500fd0a7d8e *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 25829
diff changeset
428 @item *?, +?, ??
27139
a9508422287d Improve markup for the description of non-greedy operators.
Eli Zaretskii <eliz@gnu.org>
parents: 27094
diff changeset
429 @cindex non-greedy regexp matching
27094
6500fd0a7d8e *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 25829
diff changeset
430 are non-greedy variants of the operators above. The normal operators
27139
a9508422287d Improve markup for the description of non-greedy operators.
Eli Zaretskii <eliz@gnu.org>
parents: 27094
diff changeset
431 @samp{*}, @samp{+}, @samp{?} are @dfn{greedy} in that they match as much
a9508422287d Improve markup for the description of non-greedy operators.
Eli Zaretskii <eliz@gnu.org>
parents: 27094
diff changeset
432 as they can, while if you append a @samp{?} after them, it makes them
a9508422287d Improve markup for the description of non-greedy operators.
Eli Zaretskii <eliz@gnu.org>
parents: 27094
diff changeset
433 non-greedy: they will match as little as possible.
27094
6500fd0a7d8e *** empty log message ***
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 25829
diff changeset
434
27694
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
435 @item \@{n,m\@}
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
436 is another postfix operator that specifies an interval of iteration:
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
437 the preceding regular expression must match between @samp{n} and
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
438 @samp{m} times. If @samp{m} is omitted, then there is no upper bound
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
439 and if @samp{,m} is omitted, then the regular expression must match
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
440 exactly @samp{n} times. @*
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
441 @samp{\@{0,1\@}} is equivalent to @samp{?}. @*
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
442 @samp{\@{0,\@}} is equivalent to @samp{*}. @*
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
443 @samp{\@{1,\@}} is equivalent to @samp{+}. @*
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
444 @samp{\@{n\@}} is equivalent to @samp{\@{n,n\@}}.
5c14849aee4c documented \{n,m\} intervals
Stefan Monnier <monnier@iro.umontreal.ca>
parents: 27217
diff changeset
445
25829
Dave Love <fx@gnu.org>
parents:
diff changeset
446 @item [ @dots{} ]
Dave Love <fx@gnu.org>
parents:
diff changeset
447 is a @dfn{character set}, which begins with @samp{[} and is terminated
Dave Love <fx@gnu.org>
parents:
diff changeset
448 by @samp{]}. In the simplest case, the characters between the two
Dave Love <fx@gnu.org>
parents:
diff changeset
449 brackets are what this set can match.
Dave Love <fx@gnu.org>
parents:
diff changeset
450
Dave Love <fx@gnu.org>
parents:
diff changeset
451 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
Dave Love <fx@gnu.org>
parents:
diff changeset
452 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
Dave Love <fx@gnu.org>
parents:
diff changeset
453 (including the empty string), from which it follows that @samp{c[ad]*r}
Dave Love <fx@gnu.org>
parents:
diff changeset
454 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
Dave Love <fx@gnu.org>
parents:
diff changeset
455
Dave Love <fx@gnu.org>
parents:
diff changeset
456 You can also include character ranges in a character set, by writing the
Dave Love <fx@gnu.org>
parents:
diff changeset
457 starting and ending characters with a @samp{-} between them. Thus,
Dave Love <fx@gnu.org>
parents:
diff changeset
458 @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
Dave Love <fx@gnu.org>
parents:
diff changeset
459 intermixed freely with individual characters, as in @samp{[a-z$%.]},
Dave Love <fx@gnu.org>
parents:
diff changeset
460 which matches any lower-case ASCII letter or @samp{$}, @samp{%} or
Dave Love <fx@gnu.org>
parents:
diff changeset
461 period.
Dave Love <fx@gnu.org>
parents:
diff changeset
462
Dave Love <fx@gnu.org>
parents:
diff changeset
463 Note that the usual regexp special characters are not special inside a
Dave Love <fx@gnu.org>
parents:
diff changeset
464 character set. A completely different set of special characters exists
Dave Love <fx@gnu.org>
parents:
diff changeset
465 inside character sets: @samp{]}, @samp{-} and @samp{^}.
Dave Love <fx@gnu.org>
parents:
diff changeset
466
Dave Love <fx@gnu.org>
parents:
diff changeset
467 To include a @samp{]} in a character set, you must make it the first
Dave Love <fx@gnu.org>
parents:
diff changeset
468 character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
Dave Love <fx@gnu.org>
parents:
diff changeset
469 include a @samp{-}, write @samp{-} as the first or last character of the
Dave Love <fx@gnu.org>
parents:
diff changeset
470 set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]}
Dave Love <fx@gnu.org>
parents:
diff changeset
471 and @samp{-}.
Dave Love <fx@gnu.org>
parents:
diff changeset
472
Dave Love <fx@gnu.org>
parents:
diff changeset
473 To include @samp{^} in a set, put it anywhere but at the beginning of
Dave Love <fx@gnu.org>
parents:
diff changeset
474 the set.
Dave Love <fx@gnu.org>
parents:
diff changeset
475
Dave Love <fx@gnu.org>
parents:
diff changeset
476 When you use a range in case-insensitive search, you should write both
Dave Love <fx@gnu.org>
parents:
diff changeset
477 ends of the range in upper case, or both in lower case, or both should
Dave Love <fx@gnu.org>
parents:
diff changeset
478 be non-letters. The behavior of a mixed-case range such as @samp{A-z}
Dave Love <fx@gnu.org>
parents:
diff changeset
479 is somewhat ill-defined, and it may change in future Emacs versions.
Dave Love <fx@gnu.org>
parents:
diff changeset
480
Dave Love <fx@gnu.org>
parents:
diff changeset
481 @item [^ @dots{} ]
Dave Love <fx@gnu.org>
parents:
diff changeset
482 @samp{[^} begins a @dfn{complemented character set}, which matches any
Dave Love <fx@gnu.org>
parents:
diff changeset
483 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
Dave Love <fx@gnu.org>
parents:
diff changeset
484 all characters @emph{except} letters and digits.
Dave Love <fx@gnu.org>
parents:
diff changeset
485
Dave Love <fx@gnu.org>
parents:
diff changeset
486 @samp{^} is not special in a character set unless it is the first
Dave Love <fx@gnu.org>
parents:
diff changeset
487 character. The character following the @samp{^} is treated as if it
Dave Love <fx@gnu.org>
parents:
diff changeset
488 were first (in other words, @samp{-} and @samp{]} are not special there).
Dave Love <fx@gnu.org>
parents:
diff changeset
489
Dave Love <fx@gnu.org>
parents:
diff changeset
490 A complemented character set can match a newline, unless newline is
Dave Love <fx@gnu.org>
parents:
diff changeset
491 mentioned as one of the characters not to match. This is in contrast to
Dave Love <fx@gnu.org>
parents:
diff changeset
492 the handling of regexps in programs such as @code{grep}.
Dave Love <fx@gnu.org>
parents:
diff changeset
493
Dave Love <fx@gnu.org>
parents:
diff changeset
494 @item ^
Dave Love <fx@gnu.org>
parents:
diff changeset
495 is a special character that matches the empty string, but only at the
Dave Love <fx@gnu.org>
parents:
diff changeset
496 beginning of a line in the text being matched. Otherwise it fails to
Dave Love <fx@gnu.org>
parents:
diff changeset
497 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
Dave Love <fx@gnu.org>
parents:
diff changeset
498 the beginning of a line.
Dave Love <fx@gnu.org>
parents:
diff changeset
499
Dave Love <fx@gnu.org>
parents:
diff changeset
500 @item $
Dave Love <fx@gnu.org>
parents:
diff changeset
501 is similar to @samp{^} but matches only at the end of a line. Thus,
Dave Love <fx@gnu.org>
parents:
diff changeset
502 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
Dave Love <fx@gnu.org>
parents:
diff changeset
503
Dave Love <fx@gnu.org>
parents:
diff changeset
504 @item \
Dave Love <fx@gnu.org>
parents:
diff changeset
505 has two functions: it quotes the special characters (including
Dave Love <fx@gnu.org>
parents:
diff changeset
506 @samp{\}), and it introduces additional special constructs.
Dave Love <fx@gnu.org>
parents:
diff changeset
507
Dave Love <fx@gnu.org>
parents:
diff changeset
508 Because @samp{\} quotes special characters, @samp{\$} is a regular
Dave Love <fx@gnu.org>
parents:
diff changeset
509 expression that matches only @samp{$}, and @samp{\[} is a regular
Dave Love <fx@gnu.org>
parents:
diff changeset
510 expression that matches only @samp{[}, and so on.
Dave Love <fx@gnu.org>
parents:
diff changeset
511 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
512
Dave Love <fx@gnu.org>
parents:
diff changeset
513 Note: for historical compatibility, special characters are treated as
Dave Love <fx@gnu.org>
parents:
diff changeset
514 ordinary ones if they are in contexts where their special meanings make no
Dave Love <fx@gnu.org>
parents:
diff changeset
515 sense. For example, @samp{*foo} treats @samp{*} as ordinary since there is
Dave Love <fx@gnu.org>
parents:
diff changeset
516 no preceding expression on which the @samp{*} can act. It is poor practice
Dave Love <fx@gnu.org>
parents:
diff changeset
517 to depend on this behavior; it is better to quote the special character anyway,
Dave Love <fx@gnu.org>
parents:
diff changeset
518 regardless of where it appears.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
519
Dave Love <fx@gnu.org>
parents:
diff changeset
520 For the most part, @samp{\} followed by any character matches only that
Dave Love <fx@gnu.org>
parents:
diff changeset
521 character. However, there are several exceptions: two-character
Dave Love <fx@gnu.org>
parents:
diff changeset
522 sequences starting with @samp{\} that have special meanings. The second
Dave Love <fx@gnu.org>
parents:
diff changeset
523 character in the sequence is always an ordinary character when used on
Dave Love <fx@gnu.org>
parents:
diff changeset
524 its own. Here is a table of @samp{\} constructs.
Dave Love <fx@gnu.org>
parents:
diff changeset
525
Dave Love <fx@gnu.org>
parents:
diff changeset
526 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
527 @item \|
Dave Love <fx@gnu.org>
parents:
diff changeset
528 specifies an alternative. Two regular expressions @var{a} and @var{b}
Dave Love <fx@gnu.org>
parents:
diff changeset
529 with @samp{\|} in between form an expression that matches some text if
Dave Love <fx@gnu.org>
parents:
diff changeset
530 either @var{a} matches it or @var{b} matches it. It works by trying to
Dave Love <fx@gnu.org>
parents:
diff changeset
531 match @var{a}, and if that fails, by trying to match @var{b}.
Dave Love <fx@gnu.org>
parents:
diff changeset
532
Dave Love <fx@gnu.org>
parents:
diff changeset
533 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
Dave Love <fx@gnu.org>
parents:
diff changeset
534 but no other string.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
535
Dave Love <fx@gnu.org>
parents:
diff changeset
536 @samp{\|} applies to the largest possible surrounding expressions. Only a
Dave Love <fx@gnu.org>
parents:
diff changeset
537 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
Dave Love <fx@gnu.org>
parents:
diff changeset
538 @samp{\|}.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
539
Dave Love <fx@gnu.org>
parents:
diff changeset
540 Full backtracking capability exists to handle multiple uses of @samp{\|}.
Dave Love <fx@gnu.org>
parents:
diff changeset
541
Dave Love <fx@gnu.org>
parents:
diff changeset
542 @item \( @dots{} \)
Dave Love <fx@gnu.org>
parents:
diff changeset
543 is a grouping construct that serves three purposes:
Dave Love <fx@gnu.org>
parents:
diff changeset
544
Dave Love <fx@gnu.org>
parents:
diff changeset
545 @enumerate
Dave Love <fx@gnu.org>
parents:
diff changeset
546 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
547 To enclose a set of @samp{\|} alternatives for other operations.
Dave Love <fx@gnu.org>
parents:
diff changeset
548 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
Dave Love <fx@gnu.org>
parents:
diff changeset
549
Dave Love <fx@gnu.org>
parents:
diff changeset
550 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
551 To enclose a complicated expression for the postfix operators @samp{*},
Dave Love <fx@gnu.org>
parents:
diff changeset
552 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
Dave Love <fx@gnu.org>
parents:
diff changeset
553 @samp{bananana}, etc., with any (zero or more) number of @samp{na}
Dave Love <fx@gnu.org>
parents:
diff changeset
554 strings.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
555
Dave Love <fx@gnu.org>
parents:
diff changeset
556 @item
Dave Love <fx@gnu.org>
parents:
diff changeset
557 To record a matched substring for future reference.
Dave Love <fx@gnu.org>
parents:
diff changeset
558 @end enumerate
Dave Love <fx@gnu.org>
parents:
diff changeset
559
Dave Love <fx@gnu.org>
parents:
diff changeset
560 This last application is not a consequence of the idea of a
Dave Love <fx@gnu.org>
parents:
diff changeset
561 parenthetical grouping; it is a separate feature that is assigned as a
Dave Love <fx@gnu.org>
parents:
diff changeset
562 second meaning to the same @samp{\( @dots{} \)} construct. In practice
Dave Love <fx@gnu.org>
parents:
diff changeset
563 there is no conflict between the two meanings.
Dave Love <fx@gnu.org>
parents:
diff changeset
564
Dave Love <fx@gnu.org>
parents:
diff changeset
565 @item \@var{d}
Dave Love <fx@gnu.org>
parents:
diff changeset
566 matches the same text that matched the @var{d}th occurrence of a
Dave Love <fx@gnu.org>
parents:
diff changeset
567 @samp{\( @dots{} \)} construct.
Dave Love <fx@gnu.org>
parents:
diff changeset
568
Dave Love <fx@gnu.org>
parents:
diff changeset
569 After the end of a @samp{\( @dots{} \)} construct, the matcher remembers
Dave Love <fx@gnu.org>
parents:
diff changeset
570 the beginning and end of the text matched by that construct. Then,
Dave Love <fx@gnu.org>
parents:
diff changeset
571 later on in the regular expression, you can use @samp{\} followed by the
Dave Love <fx@gnu.org>
parents:
diff changeset
572 digit @var{d} to mean ``match the same text matched the @var{d}th time
Dave Love <fx@gnu.org>
parents:
diff changeset
573 by the @samp{\( @dots{} \)} construct.''
Dave Love <fx@gnu.org>
parents:
diff changeset
574
Dave Love <fx@gnu.org>
parents:
diff changeset
575 The strings matching the first nine @samp{\( @dots{} \)} constructs
Dave Love <fx@gnu.org>
parents:
diff changeset
576 appearing in a regular expression are assigned numbers 1 through 9 in
Dave Love <fx@gnu.org>
parents:
diff changeset
577 the order that the open-parentheses appear in the regular expression.
Dave Love <fx@gnu.org>
parents:
diff changeset
578 So you can use @samp{\1} through @samp{\9} to refer to the text matched
Dave Love <fx@gnu.org>
parents:
diff changeset
579 by the corresponding @samp{\( @dots{} \)} constructs.
Dave Love <fx@gnu.org>
parents:
diff changeset
580
Dave Love <fx@gnu.org>
parents:
diff changeset
581 For example, @samp{\(.*\)\1} matches any newline-free string that is
Dave Love <fx@gnu.org>
parents:
diff changeset
582 composed of two identical halves. The @samp{\(.*\)} matches the first
Dave Love <fx@gnu.org>
parents:
diff changeset
583 half, which may be anything, but the @samp{\1} that follows must match
Dave Love <fx@gnu.org>
parents:
diff changeset
584 the same exact text.
Dave Love <fx@gnu.org>
parents:
diff changeset
585
Dave Love <fx@gnu.org>
parents:
diff changeset
586 If a particular @samp{\( @dots{} \)} construct matches more than once
Dave Love <fx@gnu.org>
parents:
diff changeset
587 (which can easily happen if it is followed by @samp{*}), only the last
Dave Love <fx@gnu.org>
parents:
diff changeset
588 match is recorded.
Dave Love <fx@gnu.org>
parents:
diff changeset
589
Dave Love <fx@gnu.org>
parents:
diff changeset
590 @item \`
Dave Love <fx@gnu.org>
parents:
diff changeset
591 matches the empty string, but only at the beginning
Dave Love <fx@gnu.org>
parents:
diff changeset
592 of the buffer or string being matched against.
Dave Love <fx@gnu.org>
parents:
diff changeset
593
Dave Love <fx@gnu.org>
parents:
diff changeset
594 @item \'
Dave Love <fx@gnu.org>
parents:
diff changeset
595 matches the empty string, but only at the end of
Dave Love <fx@gnu.org>
parents:
diff changeset
596 the buffer or string being matched against.
Dave Love <fx@gnu.org>
parents:
diff changeset
597
Dave Love <fx@gnu.org>
parents:
diff changeset
598 @item \=
Dave Love <fx@gnu.org>
parents:
diff changeset
599 matches the empty string, but only at point.
Dave Love <fx@gnu.org>
parents:
diff changeset
600
Dave Love <fx@gnu.org>
parents:
diff changeset
601 @item \b
Dave Love <fx@gnu.org>
parents:
diff changeset
602 matches the empty string, but only at the beginning or
Dave Love <fx@gnu.org>
parents:
diff changeset
603 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
Dave Love <fx@gnu.org>
parents:
diff changeset
604 @samp{foo} as a separate word. @samp{\bballs?\b} matches
Dave Love <fx@gnu.org>
parents:
diff changeset
605 @samp{ball} or @samp{balls} as a separate word.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
606
Dave Love <fx@gnu.org>
parents:
diff changeset
607 @samp{\b} matches at the beginning or end of the buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
608 regardless of what text appears next to it.
Dave Love <fx@gnu.org>
parents:
diff changeset
609
Dave Love <fx@gnu.org>
parents:
diff changeset
610 @item \B
Dave Love <fx@gnu.org>
parents:
diff changeset
611 matches the empty string, but @emph{not} at the beginning or
Dave Love <fx@gnu.org>
parents:
diff changeset
612 end of a word.
Dave Love <fx@gnu.org>
parents:
diff changeset
613
Dave Love <fx@gnu.org>
parents:
diff changeset
614 @item \<
Dave Love <fx@gnu.org>
parents:
diff changeset
615 matches the empty string, but only at the beginning of a word.
Dave Love <fx@gnu.org>
parents:
diff changeset
616 @samp{\<} matches at the beginning of the buffer only if a
Dave Love <fx@gnu.org>
parents:
diff changeset
617 word-constituent character follows.
Dave Love <fx@gnu.org>
parents:
diff changeset
618
Dave Love <fx@gnu.org>
parents:
diff changeset
619 @item \>
Dave Love <fx@gnu.org>
parents:
diff changeset
620 matches the empty string, but only at the end of a word. @samp{\>}
Dave Love <fx@gnu.org>
parents:
diff changeset
621 matches at the end of the buffer only if the contents end with a
Dave Love <fx@gnu.org>
parents:
diff changeset
622 word-constituent character.
Dave Love <fx@gnu.org>
parents:
diff changeset
623
Dave Love <fx@gnu.org>
parents:
diff changeset
624 @item \w
Dave Love <fx@gnu.org>
parents:
diff changeset
625 matches any word-constituent character. The syntax table
Dave Love <fx@gnu.org>
parents:
diff changeset
626 determines which characters these are. @xref{Syntax}.
Dave Love <fx@gnu.org>
parents:
diff changeset
627
Dave Love <fx@gnu.org>
parents:
diff changeset
628 @item \W
Dave Love <fx@gnu.org>
parents:
diff changeset
629 matches any character that is not a word-constituent.
Dave Love <fx@gnu.org>
parents:
diff changeset
630
Dave Love <fx@gnu.org>
parents:
diff changeset
631 @item \s@var{c}
Dave Love <fx@gnu.org>
parents:
diff changeset
632 matches any character whose syntax is @var{c}. Here @var{c} is a
Dave Love <fx@gnu.org>
parents:
diff changeset
633 character that represents a syntax code: thus, @samp{w} for word
Dave Love <fx@gnu.org>
parents:
diff changeset
634 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
Dave Love <fx@gnu.org>
parents:
diff changeset
635 etc. Represent a character of whitespace (which can be a newline) by
Dave Love <fx@gnu.org>
parents:
diff changeset
636 either @samp{-} or a space character.
Dave Love <fx@gnu.org>
parents:
diff changeset
637
Dave Love <fx@gnu.org>
parents:
diff changeset
638 @item \S@var{c}
Dave Love <fx@gnu.org>
parents:
diff changeset
639 matches any character whose syntax is not @var{c}.
Dave Love <fx@gnu.org>
parents:
diff changeset
640 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
641
Dave Love <fx@gnu.org>
parents:
diff changeset
642 The constructs that pertain to words and syntax are controlled by the
Dave Love <fx@gnu.org>
parents:
diff changeset
643 setting of the syntax table (@pxref{Syntax}).
Dave Love <fx@gnu.org>
parents:
diff changeset
644
Dave Love <fx@gnu.org>
parents:
diff changeset
645 Here is a complicated regexp, used by Emacs to recognize the end of a
Dave Love <fx@gnu.org>
parents:
diff changeset
646 sentence together with any whitespace that follows. It is given in Lisp
Dave Love <fx@gnu.org>
parents:
diff changeset
647 syntax to enable you to distinguish the spaces from the tab characters. In
Dave Love <fx@gnu.org>
parents:
diff changeset
648 Lisp syntax, the string constant begins and ends with a double-quote.
Dave Love <fx@gnu.org>
parents:
diff changeset
649 @samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a
Dave Love <fx@gnu.org>
parents:
diff changeset
650 backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a
Dave Love <fx@gnu.org>
parents:
diff changeset
651 newline.
Dave Love <fx@gnu.org>
parents:
diff changeset
652
Dave Love <fx@gnu.org>
parents:
diff changeset
653 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
654 "[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
Dave Love <fx@gnu.org>
parents:
diff changeset
655 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
656
Dave Love <fx@gnu.org>
parents:
diff changeset
657 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
658 This contains four parts in succession: a character set matching period,
Dave Love <fx@gnu.org>
parents:
diff changeset
659 @samp{?}, or @samp{!}; a character set matching close-brackets, quotes,
Dave Love <fx@gnu.org>
parents:
diff changeset
660 or parentheses, repeated any number of times; an alternative in
Dave Love <fx@gnu.org>
parents:
diff changeset
661 backslash-parentheses that matches end-of-line, a tab, or two spaces;
Dave Love <fx@gnu.org>
parents:
diff changeset
662 and a character set matching whitespace characters, repeated any number
Dave Love <fx@gnu.org>
parents:
diff changeset
663 of times.
Dave Love <fx@gnu.org>
parents:
diff changeset
664
Dave Love <fx@gnu.org>
parents:
diff changeset
665 To enter the same regexp interactively, you would type @key{TAB} to
Dave Love <fx@gnu.org>
parents:
diff changeset
666 enter a tab, and @kbd{C-j} to enter a newline. You would also type
Dave Love <fx@gnu.org>
parents:
diff changeset
667 single backslashes as themselves, instead of doubling them for Lisp syntax.
Dave Love <fx@gnu.org>
parents:
diff changeset
668
Dave Love <fx@gnu.org>
parents:
diff changeset
669 @node Search Case, Replace, Regexps, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
670 @section Searching and Case
Dave Love <fx@gnu.org>
parents:
diff changeset
671
Dave Love <fx@gnu.org>
parents:
diff changeset
672 @vindex case-fold-search
Dave Love <fx@gnu.org>
parents:
diff changeset
673 Incremental searches in Emacs normally ignore the case of the text
Dave Love <fx@gnu.org>
parents:
diff changeset
674 they are searching through, if you specify the text in lower case.
Dave Love <fx@gnu.org>
parents:
diff changeset
675 Thus, if you specify searching for @samp{foo}, then @samp{Foo} and
Dave Love <fx@gnu.org>
parents:
diff changeset
676 @samp{foo} are also considered a match. Regexps, and in particular
Dave Love <fx@gnu.org>
parents:
diff changeset
677 character sets, are included: @samp{[ab]} would match @samp{a} or
Dave Love <fx@gnu.org>
parents:
diff changeset
678 @samp{A} or @samp{b} or @samp{B}.@refill
Dave Love <fx@gnu.org>
parents:
diff changeset
679
Dave Love <fx@gnu.org>
parents:
diff changeset
680 An upper-case letter anywhere in the incremental search string makes
Dave Love <fx@gnu.org>
parents:
diff changeset
681 the search case-sensitive. Thus, searching for @samp{Foo} does not find
Dave Love <fx@gnu.org>
parents:
diff changeset
682 @samp{foo} or @samp{FOO}. This applies to regular expression search as
Dave Love <fx@gnu.org>
parents:
diff changeset
683 well as to string search. The effect ceases if you delete the
Dave Love <fx@gnu.org>
parents:
diff changeset
684 upper-case letter from the search string.
Dave Love <fx@gnu.org>
parents:
diff changeset
685
Dave Love <fx@gnu.org>
parents:
diff changeset
686 If you set the variable @code{case-fold-search} to @code{nil}, then
Dave Love <fx@gnu.org>
parents:
diff changeset
687 all letters must match exactly, including case. This is a per-buffer
Dave Love <fx@gnu.org>
parents:
diff changeset
688 variable; altering the variable affects only the current buffer, but
Dave Love <fx@gnu.org>
parents:
diff changeset
689 there is a default value which you can change as well. @xref{Locals}.
Dave Love <fx@gnu.org>
parents:
diff changeset
690 This variable applies to nonincremental searches also, including those
Dave Love <fx@gnu.org>
parents:
diff changeset
691 performed by the replace commands (@pxref{Replace}) and the minibuffer
Dave Love <fx@gnu.org>
parents:
diff changeset
692 history matching commands (@pxref{Minibuffer History}).
Dave Love <fx@gnu.org>
parents:
diff changeset
693
Dave Love <fx@gnu.org>
parents:
diff changeset
694 @node Replace, Other Repeating Search, Search Case, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
695 @section Replacement Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
696 @cindex replacement
Dave Love <fx@gnu.org>
parents:
diff changeset
697 @cindex search-and-replace commands
Dave Love <fx@gnu.org>
parents:
diff changeset
698 @cindex string substitution
Dave Love <fx@gnu.org>
parents:
diff changeset
699 @cindex global substitution
Dave Love <fx@gnu.org>
parents:
diff changeset
700
Dave Love <fx@gnu.org>
parents:
diff changeset
701 Global search-and-replace operations are not needed as often in Emacs
Dave Love <fx@gnu.org>
parents:
diff changeset
702 as they are in other editors@footnote{In some editors,
Dave Love <fx@gnu.org>
parents:
diff changeset
703 search-and-replace operations are the only convenient way to make a
Dave Love <fx@gnu.org>
parents:
diff changeset
704 single change in the text.}, but they are available. In addition to the
Dave Love <fx@gnu.org>
parents:
diff changeset
705 simple @kbd{M-x replace-string} command which is like that found in most
Dave Love <fx@gnu.org>
parents:
diff changeset
706 editors, there is a @kbd{M-x query-replace} command which asks you, for
Dave Love <fx@gnu.org>
parents:
diff changeset
707 each occurrence of the pattern, whether to replace it.
Dave Love <fx@gnu.org>
parents:
diff changeset
708
Dave Love <fx@gnu.org>
parents:
diff changeset
709 The replace commands normally operate on the text from point to the
Dave Love <fx@gnu.org>
parents:
diff changeset
710 end of the buffer; however, in Transient Mark mode, when the mark is
Dave Love <fx@gnu.org>
parents:
diff changeset
711 active, they operate on the region. The replace commands all replace
Dave Love <fx@gnu.org>
parents:
diff changeset
712 one string (or regexp) with one replacement string. It is possible to
Dave Love <fx@gnu.org>
parents:
diff changeset
713 perform several replacements in parallel using the command
Dave Love <fx@gnu.org>
parents:
diff changeset
714 @code{expand-region-abbrevs} (@pxref{Expanding Abbrevs}).
Dave Love <fx@gnu.org>
parents:
diff changeset
715
Dave Love <fx@gnu.org>
parents:
diff changeset
716 @menu
Dave Love <fx@gnu.org>
parents:
diff changeset
717 * Unconditional Replace:: Replacing all matches for a string.
Dave Love <fx@gnu.org>
parents:
diff changeset
718 * Regexp Replace:: Replacing all matches for a regexp.
Dave Love <fx@gnu.org>
parents:
diff changeset
719 * Replacement and Case:: How replacements preserve case of letters.
Dave Love <fx@gnu.org>
parents:
diff changeset
720 * Query Replace:: How to use querying.
Dave Love <fx@gnu.org>
parents:
diff changeset
721 @end menu
Dave Love <fx@gnu.org>
parents:
diff changeset
722
Dave Love <fx@gnu.org>
parents:
diff changeset
723 @node Unconditional Replace, Regexp Replace, Replace, Replace
Dave Love <fx@gnu.org>
parents:
diff changeset
724 @subsection Unconditional Replacement
Dave Love <fx@gnu.org>
parents:
diff changeset
725 @findex replace-string
Dave Love <fx@gnu.org>
parents:
diff changeset
726 @findex replace-regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
727
Dave Love <fx@gnu.org>
parents:
diff changeset
728 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
729 @item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
730 Replace every occurrence of @var{string} with @var{newstring}.
Dave Love <fx@gnu.org>
parents:
diff changeset
731 @item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
732 Replace every match for @var{regexp} with @var{newstring}.
Dave Love <fx@gnu.org>
parents:
diff changeset
733 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
734
Dave Love <fx@gnu.org>
parents:
diff changeset
735 To replace every instance of @samp{foo} after point with @samp{bar},
Dave Love <fx@gnu.org>
parents:
diff changeset
736 use the command @kbd{M-x replace-string} with the two arguments
Dave Love <fx@gnu.org>
parents:
diff changeset
737 @samp{foo} and @samp{bar}. Replacement happens only in the text after
Dave Love <fx@gnu.org>
parents:
diff changeset
738 point, so if you want to cover the whole buffer you must go to the
Dave Love <fx@gnu.org>
parents:
diff changeset
739 beginning first. All occurrences up to the end of the buffer are
Dave Love <fx@gnu.org>
parents:
diff changeset
740 replaced; to limit replacement to part of the buffer, narrow to that
Dave Love <fx@gnu.org>
parents:
diff changeset
741 part of the buffer before doing the replacement (@pxref{Narrowing}).
Dave Love <fx@gnu.org>
parents:
diff changeset
742 In Transient Mark mode, when the region is active, replacement is
Dave Love <fx@gnu.org>
parents:
diff changeset
743 limited to the region (@pxref{Transient Mark}).
Dave Love <fx@gnu.org>
parents:
diff changeset
744
Dave Love <fx@gnu.org>
parents:
diff changeset
745 When @code{replace-string} exits, it leaves point at the last
Dave Love <fx@gnu.org>
parents:
diff changeset
746 occurrence replaced. It sets the mark to the prior position of point
Dave Love <fx@gnu.org>
parents:
diff changeset
747 (where the @code{replace-string} command was issued); use @kbd{C-u
Dave Love <fx@gnu.org>
parents:
diff changeset
748 C-@key{SPC}} to move back there.
Dave Love <fx@gnu.org>
parents:
diff changeset
749
Dave Love <fx@gnu.org>
parents:
diff changeset
750 A numeric argument restricts replacement to matches that are surrounded
Dave Love <fx@gnu.org>
parents:
diff changeset
751 by word boundaries. The argument's value doesn't matter.
Dave Love <fx@gnu.org>
parents:
diff changeset
752
Dave Love <fx@gnu.org>
parents:
diff changeset
753 @node Regexp Replace, Replacement and Case, Unconditional Replace, Replace
Dave Love <fx@gnu.org>
parents:
diff changeset
754 @subsection Regexp Replacement
Dave Love <fx@gnu.org>
parents:
diff changeset
755
Dave Love <fx@gnu.org>
parents:
diff changeset
756 The @kbd{M-x replace-string} command replaces exact matches for a
Dave Love <fx@gnu.org>
parents:
diff changeset
757 single string. The similar command @kbd{M-x replace-regexp} replaces
Dave Love <fx@gnu.org>
parents:
diff changeset
758 any match for a specified pattern.
Dave Love <fx@gnu.org>
parents:
diff changeset
759
Dave Love <fx@gnu.org>
parents:
diff changeset
760 In @code{replace-regexp}, the @var{newstring} need not be constant: it
Dave Love <fx@gnu.org>
parents:
diff changeset
761 can refer to all or part of what is matched by the @var{regexp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
762 @samp{\&} in @var{newstring} stands for the entire match being replaced.
Dave Love <fx@gnu.org>
parents:
diff changeset
763 @samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for
Dave Love <fx@gnu.org>
parents:
diff changeset
764 whatever matched the @var{d}th parenthesized grouping in @var{regexp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
765 To include a @samp{\} in the text to replace with, you must enter
Dave Love <fx@gnu.org>
parents:
diff changeset
766 @samp{\\}. For example,
Dave Love <fx@gnu.org>
parents:
diff changeset
767
Dave Love <fx@gnu.org>
parents:
diff changeset
768 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
769 M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
770 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
771
Dave Love <fx@gnu.org>
parents:
diff changeset
772 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
773 replaces (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr}
Dave Love <fx@gnu.org>
parents:
diff changeset
774 with @samp{cddr-safe}.
Dave Love <fx@gnu.org>
parents:
diff changeset
775
Dave Love <fx@gnu.org>
parents:
diff changeset
776 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
777 M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
778 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
779
Dave Love <fx@gnu.org>
parents:
diff changeset
780 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
781 performs the inverse transformation.
Dave Love <fx@gnu.org>
parents:
diff changeset
782
Dave Love <fx@gnu.org>
parents:
diff changeset
783 @node Replacement and Case, Query Replace, Regexp Replace, Replace
Dave Love <fx@gnu.org>
parents:
diff changeset
784 @subsection Replace Commands and Case
Dave Love <fx@gnu.org>
parents:
diff changeset
785
Dave Love <fx@gnu.org>
parents:
diff changeset
786 If the first argument of a replace command is all lower case, the
Dave Love <fx@gnu.org>
parents:
diff changeset
787 commands ignores case while searching for occurrences to
Dave Love <fx@gnu.org>
parents:
diff changeset
788 replace---provided @code{case-fold-search} is non-@code{nil}. If
Dave Love <fx@gnu.org>
parents:
diff changeset
789 @code{case-fold-search} is set to @code{nil}, case is always significant
Dave Love <fx@gnu.org>
parents:
diff changeset
790 in all searches.
Dave Love <fx@gnu.org>
parents:
diff changeset
791
Dave Love <fx@gnu.org>
parents:
diff changeset
792 @vindex case-replace
Dave Love <fx@gnu.org>
parents:
diff changeset
793 In addition, when the @var{newstring} argument is all or partly lower
Dave Love <fx@gnu.org>
parents:
diff changeset
794 case, replacement commands try to preserve the case pattern of each
Dave Love <fx@gnu.org>
parents:
diff changeset
795 occurrence. Thus, the command
Dave Love <fx@gnu.org>
parents:
diff changeset
796
Dave Love <fx@gnu.org>
parents:
diff changeset
797 @example
Dave Love <fx@gnu.org>
parents:
diff changeset
798 M-x replace-string @key{RET} foo @key{RET} bar @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
799 @end example
Dave Love <fx@gnu.org>
parents:
diff changeset
800
Dave Love <fx@gnu.org>
parents:
diff changeset
801 @noindent
Dave Love <fx@gnu.org>
parents:
diff changeset
802 replaces a lower case @samp{foo} with a lower case @samp{bar}, an
Dave Love <fx@gnu.org>
parents:
diff changeset
803 all-caps @samp{FOO} with @samp{BAR}, and a capitalized @samp{Foo} with
Dave Love <fx@gnu.org>
parents:
diff changeset
804 @samp{Bar}. (These three alternatives---lower case, all caps, and
Dave Love <fx@gnu.org>
parents:
diff changeset
805 capitalized, are the only ones that @code{replace-string} can
Dave Love <fx@gnu.org>
parents:
diff changeset
806 distinguish.)
Dave Love <fx@gnu.org>
parents:
diff changeset
807
Dave Love <fx@gnu.org>
parents:
diff changeset
808 If upper-case letters are used in the replacement string, they remain
Dave Love <fx@gnu.org>
parents:
diff changeset
809 upper case every time that text is inserted. If upper-case letters are
Dave Love <fx@gnu.org>
parents:
diff changeset
810 used in the first argument, the second argument is always substituted
Dave Love <fx@gnu.org>
parents:
diff changeset
811 exactly as given, with no case conversion. Likewise, if either
Dave Love <fx@gnu.org>
parents:
diff changeset
812 @code{case-replace} or @code{case-fold-search} is set to @code{nil},
Dave Love <fx@gnu.org>
parents:
diff changeset
813 replacement is done without case conversion.
Dave Love <fx@gnu.org>
parents:
diff changeset
814
Dave Love <fx@gnu.org>
parents:
diff changeset
815 @node Query Replace,, Replacement and Case, Replace
Dave Love <fx@gnu.org>
parents:
diff changeset
816 @subsection Query Replace
Dave Love <fx@gnu.org>
parents:
diff changeset
817 @cindex query replace
Dave Love <fx@gnu.org>
parents:
diff changeset
818
Dave Love <fx@gnu.org>
parents:
diff changeset
819 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
820 @item M-% @var{string} @key{RET} @var{newstring} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
821 @itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
822 Replace some occurrences of @var{string} with @var{newstring}.
Dave Love <fx@gnu.org>
parents:
diff changeset
823 @item C-M-% @var{regexp} @key{RET} @var{newstring} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
824 @itemx M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
825 Replace some matches for @var{regexp} with @var{newstring}.
Dave Love <fx@gnu.org>
parents:
diff changeset
826 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
827
Dave Love <fx@gnu.org>
parents:
diff changeset
828 @kindex M-%
Dave Love <fx@gnu.org>
parents:
diff changeset
829 @findex query-replace
Dave Love <fx@gnu.org>
parents:
diff changeset
830 If you want to change only some of the occurrences of @samp{foo} to
Dave Love <fx@gnu.org>
parents:
diff changeset
831 @samp{bar}, not all of them, then you cannot use an ordinary
Dave Love <fx@gnu.org>
parents:
diff changeset
832 @code{replace-string}. Instead, use @kbd{M-%} (@code{query-replace}).
Dave Love <fx@gnu.org>
parents:
diff changeset
833 This command finds occurrences of @samp{foo} one by one, displays each
Dave Love <fx@gnu.org>
parents:
diff changeset
834 occurrence and asks you whether to replace it. A numeric argument to
Dave Love <fx@gnu.org>
parents:
diff changeset
835 @code{query-replace} tells it to consider only occurrences that are
Dave Love <fx@gnu.org>
parents:
diff changeset
836 bounded by word-delimiter characters. This preserves case, just like
Dave Love <fx@gnu.org>
parents:
diff changeset
837 @code{replace-string}, provided @code{case-replace} is non-@code{nil},
Dave Love <fx@gnu.org>
parents:
diff changeset
838 as it normally is.
Dave Love <fx@gnu.org>
parents:
diff changeset
839
Dave Love <fx@gnu.org>
parents:
diff changeset
840 @kindex C-M-%
Dave Love <fx@gnu.org>
parents:
diff changeset
841 @findex query-replace-regexp
Dave Love <fx@gnu.org>
parents:
diff changeset
842 Aside from querying, @code{query-replace} works just like
Dave Love <fx@gnu.org>
parents:
diff changeset
843 @code{replace-string}, and @code{query-replace-regexp} works just like
Dave Love <fx@gnu.org>
parents:
diff changeset
844 @code{replace-regexp}. This command is run by @kbd{C-M-%}.
Dave Love <fx@gnu.org>
parents:
diff changeset
845
Dave Love <fx@gnu.org>
parents:
diff changeset
846 The things you can type when you are shown an occurrence of @var{string}
Dave Love <fx@gnu.org>
parents:
diff changeset
847 or a match for @var{regexp} are:
Dave Love <fx@gnu.org>
parents:
diff changeset
848
Dave Love <fx@gnu.org>
parents:
diff changeset
849 @ignore @c Not worth it.
Dave Love <fx@gnu.org>
parents:
diff changeset
850 @kindex SPC @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
851 @kindex DEL @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
852 @kindex , @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
853 @kindex RET @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
854 @kindex . @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
855 @kindex ! @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
856 @kindex ^ @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
857 @kindex C-r @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
858 @kindex C-w @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
859 @kindex C-l @r{(query-replace)}
Dave Love <fx@gnu.org>
parents:
diff changeset
860 @end ignore
Dave Love <fx@gnu.org>
parents:
diff changeset
861
Dave Love <fx@gnu.org>
parents:
diff changeset
862 @c WideCommands
Dave Love <fx@gnu.org>
parents:
diff changeset
863 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
864 @item @key{SPC}
Dave Love <fx@gnu.org>
parents:
diff changeset
865 to replace the occurrence with @var{newstring}.
Dave Love <fx@gnu.org>
parents:
diff changeset
866
Dave Love <fx@gnu.org>
parents:
diff changeset
867 @item @key{DEL}
Dave Love <fx@gnu.org>
parents:
diff changeset
868 to skip to the next occurrence without replacing this one.
Dave Love <fx@gnu.org>
parents:
diff changeset
869
Dave Love <fx@gnu.org>
parents:
diff changeset
870 @item , @r{(Comma)}
Dave Love <fx@gnu.org>
parents:
diff changeset
871 to replace this occurrence and display the result. You are then asked
Dave Love <fx@gnu.org>
parents:
diff changeset
872 for another input character to say what to do next. Since the
Dave Love <fx@gnu.org>
parents:
diff changeset
873 replacement has already been made, @key{DEL} and @key{SPC} are
Dave Love <fx@gnu.org>
parents:
diff changeset
874 equivalent in this situation; both move to the next occurrence.
Dave Love <fx@gnu.org>
parents:
diff changeset
875
Dave Love <fx@gnu.org>
parents:
diff changeset
876 You can type @kbd{C-r} at this point (see below) to alter the replaced
Dave Love <fx@gnu.org>
parents:
diff changeset
877 text. You can also type @kbd{C-x u} to undo the replacement; this exits
Dave Love <fx@gnu.org>
parents:
diff changeset
878 the @code{query-replace}, so if you want to do further replacement you
Dave Love <fx@gnu.org>
parents:
diff changeset
879 must use @kbd{C-x @key{ESC} @key{ESC} @key{RET}} to restart
Dave Love <fx@gnu.org>
parents:
diff changeset
880 (@pxref{Repetition}).
Dave Love <fx@gnu.org>
parents:
diff changeset
881
Dave Love <fx@gnu.org>
parents:
diff changeset
882 @item @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
883 to exit without doing any more replacements.
Dave Love <fx@gnu.org>
parents:
diff changeset
884
Dave Love <fx@gnu.org>
parents:
diff changeset
885 @item .@: @r{(Period)}
Dave Love <fx@gnu.org>
parents:
diff changeset
886 to replace this occurrence and then exit without searching for more
Dave Love <fx@gnu.org>
parents:
diff changeset
887 occurrences.
Dave Love <fx@gnu.org>
parents:
diff changeset
888
Dave Love <fx@gnu.org>
parents:
diff changeset
889 @item !
Dave Love <fx@gnu.org>
parents:
diff changeset
890 to replace all remaining occurrences without asking again.
Dave Love <fx@gnu.org>
parents:
diff changeset
891
Dave Love <fx@gnu.org>
parents:
diff changeset
892 @item ^
Dave Love <fx@gnu.org>
parents:
diff changeset
893 to go back to the position of the previous occurrence (or what used to
Dave Love <fx@gnu.org>
parents:
diff changeset
894 be an occurrence), in case you changed it by mistake. This works by
Dave Love <fx@gnu.org>
parents:
diff changeset
895 popping the mark ring. Only one @kbd{^} in a row is meaningful, because
Dave Love <fx@gnu.org>
parents:
diff changeset
896 only one previous replacement position is kept during @code{query-replace}.
Dave Love <fx@gnu.org>
parents:
diff changeset
897
Dave Love <fx@gnu.org>
parents:
diff changeset
898 @item C-r
Dave Love <fx@gnu.org>
parents:
diff changeset
899 to enter a recursive editing level, in case the occurrence needs to be
Dave Love <fx@gnu.org>
parents:
diff changeset
900 edited rather than just replaced with @var{newstring}. When you are
Dave Love <fx@gnu.org>
parents:
diff changeset
901 done, exit the recursive editing level with @kbd{C-M-c} to proceed to
Dave Love <fx@gnu.org>
parents:
diff changeset
902 the next occurrence. @xref{Recursive Edit}.
Dave Love <fx@gnu.org>
parents:
diff changeset
903
Dave Love <fx@gnu.org>
parents:
diff changeset
904 @item C-w
Dave Love <fx@gnu.org>
parents:
diff changeset
905 to delete the occurrence, and then enter a recursive editing level as in
Dave Love <fx@gnu.org>
parents:
diff changeset
906 @kbd{C-r}. Use the recursive edit to insert text to replace the deleted
Dave Love <fx@gnu.org>
parents:
diff changeset
907 occurrence of @var{string}. When done, exit the recursive editing level
Dave Love <fx@gnu.org>
parents:
diff changeset
908 with @kbd{C-M-c} to proceed to the next occurrence.
Dave Love <fx@gnu.org>
parents:
diff changeset
909
Dave Love <fx@gnu.org>
parents:
diff changeset
910 @item C-l
Dave Love <fx@gnu.org>
parents:
diff changeset
911 to redisplay the screen. Then you must type another character to
Dave Love <fx@gnu.org>
parents:
diff changeset
912 specify what to do with this occurrence.
Dave Love <fx@gnu.org>
parents:
diff changeset
913
Dave Love <fx@gnu.org>
parents:
diff changeset
914 @item C-h
Dave Love <fx@gnu.org>
parents:
diff changeset
915 to display a message summarizing these options. Then you must type
Dave Love <fx@gnu.org>
parents:
diff changeset
916 another character to specify what to do with this occurrence.
Dave Love <fx@gnu.org>
parents:
diff changeset
917 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
918
Dave Love <fx@gnu.org>
parents:
diff changeset
919 Some other characters are aliases for the ones listed above: @kbd{y},
Dave Love <fx@gnu.org>
parents:
diff changeset
920 @kbd{n} and @kbd{q} are equivalent to @key{SPC}, @key{DEL} and
Dave Love <fx@gnu.org>
parents:
diff changeset
921 @key{RET}.
Dave Love <fx@gnu.org>
parents:
diff changeset
922
Dave Love <fx@gnu.org>
parents:
diff changeset
923 Aside from this, any other character exits the @code{query-replace},
Dave Love <fx@gnu.org>
parents:
diff changeset
924 and is then reread as part of a key sequence. Thus, if you type
Dave Love <fx@gnu.org>
parents:
diff changeset
925 @kbd{C-k}, it exits the @code{query-replace} and then kills to end of
Dave Love <fx@gnu.org>
parents:
diff changeset
926 line.
Dave Love <fx@gnu.org>
parents:
diff changeset
927
Dave Love <fx@gnu.org>
parents:
diff changeset
928 To restart a @code{query-replace} once it is exited, use @kbd{C-x
Dave Love <fx@gnu.org>
parents:
diff changeset
929 @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it
Dave Love <fx@gnu.org>
parents:
diff changeset
930 used the minibuffer to read its arguments. @xref{Repetition, C-x ESC
Dave Love <fx@gnu.org>
parents:
diff changeset
931 ESC}.
Dave Love <fx@gnu.org>
parents:
diff changeset
932
Dave Love <fx@gnu.org>
parents:
diff changeset
933 See also @ref{Transforming File Names}, for Dired commands to rename,
Dave Love <fx@gnu.org>
parents:
diff changeset
934 copy, or link files by replacing regexp matches in file names.
Dave Love <fx@gnu.org>
parents:
diff changeset
935
Dave Love <fx@gnu.org>
parents:
diff changeset
936 @node Other Repeating Search,, Replace, Search
Dave Love <fx@gnu.org>
parents:
diff changeset
937 @section Other Search-and-Loop Commands
Dave Love <fx@gnu.org>
parents:
diff changeset
938
Dave Love <fx@gnu.org>
parents:
diff changeset
939 Here are some other commands that find matches for a regular
Dave Love <fx@gnu.org>
parents:
diff changeset
940 expression. They all operate from point to the end of the buffer, and
Dave Love <fx@gnu.org>
parents:
diff changeset
941 all ignore case in matching, if the pattern contains no upper-case
Dave Love <fx@gnu.org>
parents:
diff changeset
942 letters and @code{case-fold-search} is non-@code{nil}.
Dave Love <fx@gnu.org>
parents:
diff changeset
943
Dave Love <fx@gnu.org>
parents:
diff changeset
944 @findex list-matching-lines
Dave Love <fx@gnu.org>
parents:
diff changeset
945 @findex occur
Dave Love <fx@gnu.org>
parents:
diff changeset
946 @findex count-matches
Dave Love <fx@gnu.org>
parents:
diff changeset
947 @findex delete-non-matching-lines
Dave Love <fx@gnu.org>
parents:
diff changeset
948 @findex delete-matching-lines
Dave Love <fx@gnu.org>
parents:
diff changeset
949 @findex flush-lines
Dave Love <fx@gnu.org>
parents:
diff changeset
950 @findex keep-lines
Dave Love <fx@gnu.org>
parents:
diff changeset
951
Dave Love <fx@gnu.org>
parents:
diff changeset
952 @table @kbd
Dave Love <fx@gnu.org>
parents:
diff changeset
953 @item M-x occur @key{RET} @var{regexp} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
954 Display a list showing each line in the buffer that contains a match for
Dave Love <fx@gnu.org>
parents:
diff changeset
955 @var{regexp}. A numeric argument specifies the number of context lines
Dave Love <fx@gnu.org>
parents:
diff changeset
956 to print before and after each matching line; the default is none.
Dave Love <fx@gnu.org>
parents:
diff changeset
957 To limit the search to part of the buffer, narrow to that part
Dave Love <fx@gnu.org>
parents:
diff changeset
958 (@pxref{Narrowing}).
Dave Love <fx@gnu.org>
parents:
diff changeset
959
Dave Love <fx@gnu.org>
parents:
diff changeset
960 @kindex RET @r{(Occur mode)}
Dave Love <fx@gnu.org>
parents:
diff changeset
961 The buffer @samp{*Occur*} containing the output serves as a menu for
Dave Love <fx@gnu.org>
parents:
diff changeset
962 finding the occurrences in their original context. Click @kbd{Mouse-2}
Dave Love <fx@gnu.org>
parents:
diff changeset
963 on an occurrence listed in @samp{*Occur*}, or position point there and
Dave Love <fx@gnu.org>
parents:
diff changeset
964 type @key{RET}; this switches to the buffer that was searched and
Dave Love <fx@gnu.org>
parents:
diff changeset
965 moves point to the original of the chosen occurrence.
Dave Love <fx@gnu.org>
parents:
diff changeset
966
Dave Love <fx@gnu.org>
parents:
diff changeset
967 @item M-x list-matching-lines
Dave Love <fx@gnu.org>
parents:
diff changeset
968 Synonym for @kbd{M-x occur}.
Dave Love <fx@gnu.org>
parents:
diff changeset
969
Dave Love <fx@gnu.org>
parents:
diff changeset
970 @item M-x count-matches @key{RET} @var{regexp} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
971 Print the number of matches for @var{regexp} after point.
Dave Love <fx@gnu.org>
parents:
diff changeset
972
Dave Love <fx@gnu.org>
parents:
diff changeset
973 @item M-x flush-lines @key{RET} @var{regexp} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
974 Delete each line that follows point and contains a match for
Dave Love <fx@gnu.org>
parents:
diff changeset
975 @var{regexp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
976
Dave Love <fx@gnu.org>
parents:
diff changeset
977 @item M-x keep-lines @key{RET} @var{regexp} @key{RET}
Dave Love <fx@gnu.org>
parents:
diff changeset
978 Delete each line that follows point and @emph{does not} contain a match
Dave Love <fx@gnu.org>
parents:
diff changeset
979 for @var{regexp}.
Dave Love <fx@gnu.org>
parents:
diff changeset
980 @end table
Dave Love <fx@gnu.org>
parents:
diff changeset
981
Dave Love <fx@gnu.org>
parents:
diff changeset
982 In addition, you can use @code{grep} from Emacs to search a collection
Dave Love <fx@gnu.org>
parents:
diff changeset
983 of files for matches for a regular expression, then visit the matches
Dave Love <fx@gnu.org>
parents:
diff changeset
984 either sequentially or in arbitrary order. @xref{Grep Searching}.