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