annotate man/search.texi @ 68846:c51312efd7b3

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