annotate lispref/searching.texi @ 73923:9ebe2e5d0079

*** empty log message ***
author Juanma Barranquero <lekktu@gmail.com>
date Sat, 11 Nov 2006 16:13:41 +0000
parents 869dcf71ace3
children e7dacee7b66e 8dd8c8286063
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1 @c -*-texinfo-*-
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
2 @c This is part of the GNU Emacs Lisp Reference Manual.
64889
e836425ee789 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 64115
diff changeset
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
68648
067115a6e738 Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents: 65182
diff changeset
4 @c 2004, 2005, 2006 Free Software Foundation, Inc.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
5 @c See the file elisp.texi for copying conditions.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
6 @setfilename ../info/searching
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
7 @node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
8 @chapter Searching and Matching
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
9 @cindex searching
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
10
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
11 GNU Emacs provides two ways to search through a buffer for specified
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
12 text: exact string searches and regular expression searches. After a
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
13 regular expression search, you can examine the @dfn{match data} to
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
14 determine which text matched the whole regular expression or various
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
15 portions of it.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
16
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
17 @menu
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
18 * String Search:: Search for an exact match.
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
19 * Searching and Case:: Case-independent or case-significant searching.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
20 * Regular Expressions:: Describing classes of strings.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
21 * Regexp Search:: Searching for a match for a regexp.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
22 * POSIX Regexps:: Searching POSIX-style for the longest match.
54041
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53568
diff changeset
23 * Match Data:: Finding out which part of the text matched,
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53568
diff changeset
24 after a string or regexp search.
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
25 * Search and Replace:: Commands that loop, searching and replacing.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
26 * Standard Regexps:: Useful regexps for finding sentences, pages,...
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
27 @end menu
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
28
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
29 The @samp{skip-chars@dots{}} functions also perform a kind of searching.
73098
28a1d231aeec (Searching and Matching): Mention property search.
Richard M. Stallman <rms@gnu.org>
parents: 70741
diff changeset
30 @xref{Skipping Characters}. To search for changes in character
28a1d231aeec (Searching and Matching): Mention property search.
Richard M. Stallman <rms@gnu.org>
parents: 70741
diff changeset
31 properties, see @ref{Property Search}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
32
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
33 @node String Search
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
34 @section Searching for Strings
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
35 @cindex string search
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
36
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
37 These are the primitive functions for searching through the text in a
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
38 buffer. They are meant for use in programs, but you may call them
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
39 interactively. If you do so, they prompt for the search string; the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
40 arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
41 is 1.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
42
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
43 These search functions convert the search string to multibyte if the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
44 buffer is multibyte; they convert the search string to unibyte if the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
45 buffer is unibyte. @xref{Text Representations}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
46
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
47 @deffn Command search-forward string &optional limit noerror repeat
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
48 This function searches forward from point for an exact match for
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
49 @var{string}. If successful, it sets point to the end of the occurrence
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
50 found, and returns the new value of point. If no match is found, the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
51 value and side effects depend on @var{noerror} (see below).
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
52 @c Emacs 19 feature
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
53
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
54 In the following example, point is initially at the beginning of the
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
55 line. Then @code{(search-forward "fox")} moves point after the last
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
56 letter of @samp{fox}:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
57
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
58 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
59 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
60 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
61 @point{}The quick brown fox jumped over the lazy dog.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
62 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
63 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
64
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
65 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
66 (search-forward "fox")
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
67 @result{} 20
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
68
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
69 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
70 The quick brown fox@point{} jumped over the lazy dog.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
71 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
72 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
73 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
74
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
75 The argument @var{limit} specifies the upper bound to the search. (It
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
76 must be a position in the current buffer.) No match extending after
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
77 that position is accepted. If @var{limit} is omitted or @code{nil}, it
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
78 defaults to the end of the accessible portion of the buffer.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
79
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
80 @kindex search-failed
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
81 What happens when the search fails depends on the value of
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
82 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
83 error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
84 returns @code{nil} and does nothing. If @var{noerror} is neither
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
85 @code{nil} nor @code{t}, then @code{search-forward} moves point to the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
86 upper bound and returns @code{nil}. (It would be more consistent now to
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
87 return the new position of point in that case, but some existing
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
88 programs may depend on a value of @code{nil}.)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
89
70089
3e2a72a06085 (String Search): Clarify effect of NOERROR.
Richard M. Stallman <rms@gnu.org>
parents: 69413
diff changeset
90 The argument @var{noerror} only affects valid searches which fail to
3e2a72a06085 (String Search): Clarify effect of NOERROR.
Richard M. Stallman <rms@gnu.org>
parents: 69413
diff changeset
91 find a match. Invalid arguments cause errors regardless of
3e2a72a06085 (String Search): Clarify effect of NOERROR.
Richard M. Stallman <rms@gnu.org>
parents: 69413
diff changeset
92 @var{noerror}.
3e2a72a06085 (String Search): Clarify effect of NOERROR.
Richard M. Stallman <rms@gnu.org>
parents: 69413
diff changeset
93
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
94 If @var{repeat} is supplied (it must be a positive number), then the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
95 search is repeated that many times (each time starting at the end of the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
96 previous time's match). If these successive searches succeed, the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
97 function succeeds, moving point and returning its new value. Otherwise
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
98 the search fails, with results depending on the value of
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
99 @var{noerror}, as described above.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
100 @end deffn
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
101
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
102 @deffn Command search-backward string &optional limit noerror repeat
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
103 This function searches backward from point for @var{string}. It is
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
104 just like @code{search-forward} except that it searches backwards and
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
105 leaves point at the beginning of the match.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
106 @end deffn
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
107
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
108 @deffn Command word-search-forward string &optional limit noerror repeat
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
109 @cindex word search
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
110 This function searches forward from point for a ``word'' match for
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
111 @var{string}. If it finds a match, it sets point to the end of the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
112 match found, and returns the new value of point.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
113 @c Emacs 19 feature
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
114
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
115 Word matching regards @var{string} as a sequence of words, disregarding
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
116 punctuation that separates them. It searches the buffer for the same
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
117 sequence of words. Each word must be distinct in the buffer (searching
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
118 for the word @samp{ball} does not match the word @samp{balls}), but the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
119 details of punctuation and spacing are ignored (searching for @samp{ball
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
120 boy} does match @samp{ball. Boy!}).
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
121
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
122 In this example, point is initially at the beginning of the buffer; the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
123 search leaves it between the @samp{y} and the @samp{!}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
124
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
125 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
126 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
127 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
128 @point{}He said "Please! Find
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
129 the ball boy!"
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
130 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
131 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
132
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
133 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
134 (word-search-forward "Please find the ball, boy.")
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
135 @result{} 35
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
136
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
137 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
138 He said "Please! Find
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
139 the ball boy@point{}!"
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
140 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
141 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
142 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
143
60678
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
144 If @var{limit} is non-@code{nil}, it must be a position in the current
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
145 buffer; it specifies the upper bound to the search. The match found
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
146 must not extend after that position.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
147
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
148 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
149 an error if the search fails. If @var{noerror} is @code{t}, then it
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
150 returns @code{nil} instead of signaling an error. If @var{noerror} is
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
151 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
152 end of the accessible portion of the buffer) and returns @code{nil}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
153
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
154 If @var{repeat} is non-@code{nil}, then the search is repeated that many
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
155 times. Point is positioned at the end of the last match.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
156 @end deffn
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
157
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
158 @deffn Command word-search-backward string &optional limit noerror repeat
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
159 This function searches backward from point for a word match to
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
160 @var{string}. This function is just like @code{word-search-forward}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
161 except that it searches backward and normally leaves point at the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
162 beginning of the match.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
163 @end deffn
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
164
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
165 @node Searching and Case
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
166 @section Searching and Case
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
167 @cindex searching and case
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
168
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
169 By default, searches in Emacs ignore the case of the text they are
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
170 searching through; if you specify searching for @samp{FOO}, then
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
171 @samp{Foo} or @samp{foo} is also considered a match. This applies to
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
172 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
173 @samp{A} or @samp{b} or @samp{B}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
174
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
175 If you do not want this feature, set the variable
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
176 @code{case-fold-search} to @code{nil}. Then all letters must match
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
177 exactly, including case. This is a buffer-local variable; altering the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
178 variable affects only the current buffer. (@xref{Intro to
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
179 Buffer-Local}.) Alternatively, you may change the value of
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
180 @code{default-case-fold-search}, which is the default value of
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
181 @code{case-fold-search} for buffers that do not override it.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
183 Note that the user-level incremental search feature handles case
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
184 distinctions differently. When given a lower case letter, it looks for
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
185 a match of either case, but when given an upper case letter, it looks
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
186 for an upper case letter only. But this has nothing to do with the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
187 searching functions used in Lisp code.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
188
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
189 @defopt case-replace
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
190 This variable determines whether the higher level replacement
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
191 functions should preserve case. If the variable is @code{nil}, that
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
192 means to use the replacement text verbatim. A non-@code{nil} value
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
193 means to convert the case of the replacement text according to the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
194 text being replaced.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
195
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
196 This variable is used by passing it as an argument to the function
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
197 @code{replace-match}. @xref{Replacing Match}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
198 @end defopt
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
199
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
200 @defopt case-fold-search
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
201 This buffer-local variable determines whether searches should ignore
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
202 case. If the variable is @code{nil} they do not ignore case; otherwise
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
203 they do ignore case.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
204 @end defopt
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
205
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
206 @defvar default-case-fold-search
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
207 The value of this variable is the default value for
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
208 @code{case-fold-search} in buffers that do not override it. This is the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
209 same as @code{(default-value 'case-fold-search)}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
210 @end defvar
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
211
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
212 @node Regular Expressions
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
213 @section Regular Expressions
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
214 @cindex regular expression
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
215 @cindex regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
216
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
217 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
218 denotes a (possibly infinite) set of strings. Searching for matches for
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
219 a regexp is a very powerful operation. This section explains how to write
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
220 regexps; the following section says how to search for them.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
221
64915
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
222 @findex re-builder
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
223 @cindex authoring regular expressions
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
224 For convenient interactive development of regular expressions, you
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
225 can use the @kbd{M-x re-builder} command. It provides a convenient
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
226 interface for creating regular expressions, by giving immediate visual
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
227 feedback in a separate buffer. As you edit the regexp, all its
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
228 matches in the target buffer are highlighted. Each parenthesized
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
229 sub-expression of the regexp is shown in a distinct face, which makes
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
230 it easier to verify even very complex regexps.
3e6c73954fda (Regular Expressions): Document re-builder.
Richard M. Stallman <rms@gnu.org>
parents: 64889
diff changeset
231
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
232 @menu
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
233 * Syntax of Regexps:: Rules for writing regular expressions.
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
234 * Regexp Example:: Illustrates regular expression syntax.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
235 * Regexp Functions:: Functions for operating on regular expressions.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
236 @end menu
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
237
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
238 @node Syntax of Regexps
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
239 @subsection Syntax of Regular Expressions
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
240
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
241 Regular expressions have a syntax in which a few characters are
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
242 special constructs and the rest are @dfn{ordinary}. An ordinary
69330
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
243 character is a simple regular expression that matches that character
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
244 and nothing else. The special characters are @samp{.}, @samp{*},
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
245 @samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
246 special characters will be defined in the future. The character
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
247 @samp{]} is special if it ends a character alternative (see later).
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
248 The character @samp{-} is special inside a character alternative. A
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
249 @samp{[:} and balancing @samp{:]} enclose a character class inside a
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
250 character alternative. Any other character appearing in a regular
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
251 expression is ordinary, unless a @samp{\} precedes it.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
252
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
253 For example, @samp{f} is not a special character, so it is ordinary, and
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
254 therefore @samp{f} is a regular expression that matches the string
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
255 @samp{f} and no other string. (It does @emph{not} match the string
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
256 @samp{fg}, but it does match a @emph{part} of that string.) Likewise,
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
257 @samp{o} is a regular expression that matches only @samp{o}.@refill
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
258
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
259 Any two regular expressions @var{a} and @var{b} can be concatenated. The
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
260 result is a regular expression that matches a string if @var{a} matches
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
261 some amount of the beginning of that string and @var{b} matches the rest of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
262 the string.@refill
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
263
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
264 As a simple example, we can concatenate the regular expressions @samp{f}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
265 and @samp{o} to get the regular expression @samp{fo}, which matches only
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
266 the string @samp{fo}. Still trivial. To do something more powerful, you
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
267 need to use one of the special regular expression constructs.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
268
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
269 @menu
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
270 * Regexp Special:: Special characters in regular expressions.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
271 * Char Classes:: Character classes used in regular expressions.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
272 * Regexp Backslash:: Backslash-sequences in regular expressions.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
273 @end menu
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
274
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
275 @node Regexp Special
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
276 @subsubsection Special Characters in Regular Expressions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
277
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
278 Here is a list of the characters that are special in a regular
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
279 expression.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
280
22274
f0cd03a7dac9 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22252
diff changeset
281 @need 800
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
282 @table @asis
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
283 @item @samp{.}@: @r{(Period)}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
284 @cindex @samp{.} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
285 is a special character that matches any single character except a newline.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
286 Using concatenation, we can make regular expressions like @samp{a.b}, which
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
287 matches any three-character string that begins with @samp{a} and ends with
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
288 @samp{b}.@refill
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
289
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
290 @item @samp{*}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
291 @cindex @samp{*} in regexp
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
292 is not a construct by itself; it is a postfix operator that means to
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
293 match the preceding regular expression repetitively as many times as
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
294 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
295 @samp{o}s).
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
296
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
297 @samp{*} always applies to the @emph{smallest} possible preceding
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
298 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
299 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
300
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
301 The matcher processes a @samp{*} construct by matching, immediately, as
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
302 many repetitions as can be found. Then it continues with the rest of
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
303 the pattern. If that fails, backtracking occurs, discarding some of the
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
304 matches of the @samp{*}-modified construct in the hope that that will
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
305 make it possible to match the rest of the pattern. For example, in
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
306 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
307 first tries to match all three @samp{a}s; but the rest of the pattern is
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
308 @samp{ar} and there is only @samp{r} left to match, so this try fails.
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
309 The next alternative is for @samp{a*} to match only two @samp{a}s. With
70692
f03812b51969 (Regexp Special): Clarify nested regexp warning.
Richard M. Stallman <rms@gnu.org>
parents: 70089
diff changeset
310 this choice, the rest of the regexp matches successfully.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
311
70692
f03812b51969 (Regexp Special): Clarify nested regexp warning.
Richard M. Stallman <rms@gnu.org>
parents: 70089
diff changeset
312 @strong{Warning:} Nested repetition operators take a long time,
f03812b51969 (Regexp Special): Clarify nested regexp warning.
Richard M. Stallman <rms@gnu.org>
parents: 70089
diff changeset
313 or even forever, if they
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
314 lead to ambiguous matching. For example, trying to match the regular
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
315 expression @samp{\(x+y*\)*a} against the string
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
316 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could take hours before it
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
317 ultimately fails. Emacs must try each way of grouping the 35
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
318 @samp{x}s before concluding that none of them can work. Even worse,
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
319 @samp{\(x*\)*} can match the null string in infinitely many ways, so
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
320 it causes an infinite loop. To avoid these problems, check nested
70692
f03812b51969 (Regexp Special): Clarify nested regexp warning.
Richard M. Stallman <rms@gnu.org>
parents: 70089
diff changeset
321 repetitions carefully, to make sure that they do not cause combinatorial
f03812b51969 (Regexp Special): Clarify nested regexp warning.
Richard M. Stallman <rms@gnu.org>
parents: 70089
diff changeset
322 explosions in backtracking.
11651
f43818d3bbd8 Warn about nested repetition.
Richard M. Stallman <rms@gnu.org>
parents: 10038
diff changeset
323
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
324 @item @samp{+}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
325 @cindex @samp{+} in regexp
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
326 is a postfix operator, similar to @samp{*} except that it must match
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
327 the preceding expression at least once. So, for example, @samp{ca+r}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
328 matches the strings @samp{car} and @samp{caaaar} but not the string
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
329 @samp{cr}, whereas @samp{ca*r} matches all three strings.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
330
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
331 @item @samp{?}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
332 @cindex @samp{?} in regexp
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
333 is a postfix operator, similar to @samp{*} except that it must match the
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
334 preceding expression either once or not at all. For example,
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
335 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
336
27095
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
337 @item @samp{*?}, @samp{+?}, @samp{??}
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
338 These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
339 and @samp{?}. Where those operators match the largest possible
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
340 substring (consistent with matching the entire containing expression),
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
341 the non-greedy variants match the smallest possible substring
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
342 (consistent with matching the entire containing expression).
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
343
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
344 For example, the regular expression @samp{c[ad]*a} when applied to the
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
345 string @samp{cdaaada} matches the whole string; but the regular
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
346 expression @samp{c[ad]*?a}, applied to that same string, matches just
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
347 @samp{cda}. (The smallest possible match here for @samp{[ad]*?} that
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
348 permits the whole expression to match is @samp{d}.)
7cc86d68ccf8 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 26783
diff changeset
349
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
350 @item @samp{[ @dots{} ]}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
351 @cindex character alternative (in regexp)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
352 @cindex @samp{[} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
353 @cindex @samp{]} in regexp
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
354 is a @dfn{character alternative}, which begins with @samp{[} and is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
355 terminated by @samp{]}. In the simplest case, the characters between
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
356 the two brackets are what this character alternative can match.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
357
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
358 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
359 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
360 (including the empty string), from which it follows that @samp{c[ad]*r}
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
361 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
362
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
363 You can also include character ranges in a character alternative, by
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
364 writing the starting and ending characters with a @samp{-} between them.
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
365 Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
366 Ranges may be intermixed freely with individual characters, as in
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
367 @samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
368 or @samp{$}, @samp{%} or period.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
369
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
370 Note that the usual regexp special characters are not special inside a
24934
f5e3b4ecd255 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 22274
diff changeset
371 character alternative. A completely different set of characters is
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
372 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
373
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
374 To include a @samp{]} in a character alternative, you must make it the
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
375 first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
376 To include a @samp{-}, write @samp{-} as the first or last character of
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
377 the character alternative, or put it after a range. Thus, @samp{[]-]}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
378 matches both @samp{]} and @samp{-}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
379
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
380 To include @samp{^} in a character alternative, put it anywhere but at
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
381 the beginning.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
382
37842
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
383 The beginning and end of a range of multibyte characters must be in
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
384 the same character set (@pxref{Character Sets}). Thus,
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
385 @code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a}
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
386 with grave accent) is in the Emacs character set for Latin-1 but the
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
387 character 0x97c (@samp{u} with diaeresis) is in the Emacs character
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
388 set for Latin-2. (We use Lisp string syntax to write that example,
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
389 and a few others in the next few paragraphs, in order to include hex
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
390 escape sequences in them.)
32464
c3aecbe98b99 Non-ASCII in regexp ranges.
Dave Love <fx@gnu.org>
parents: 27780
diff changeset
391
c3aecbe98b99 Non-ASCII in regexp ranges.
Dave Love <fx@gnu.org>
parents: 27780
diff changeset
392 If a range starts with a unibyte character @var{c} and ends with a
c3aecbe98b99 Non-ASCII in regexp ranges.
Dave Love <fx@gnu.org>
parents: 27780
diff changeset
393 multibyte character @var{c2}, the range is divided into two parts: one
c3aecbe98b99 Non-ASCII in regexp ranges.
Dave Love <fx@gnu.org>
parents: 27780
diff changeset
394 is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
c3aecbe98b99 Non-ASCII in regexp ranges.
Dave Love <fx@gnu.org>
parents: 27780
diff changeset
395 @var{c1} is the first character of the charset to which @var{c2}
c3aecbe98b99 Non-ASCII in regexp ranges.
Dave Love <fx@gnu.org>
parents: 27780
diff changeset
396 belongs.
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48701
diff changeset
397
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
398 You cannot always match all non-@acronym{ASCII} characters with the regular
37842
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
399 expression @code{"[\200-\377]"}. This works when searching a unibyte
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
400 buffer or string (@pxref{Text Representations}), but not in a multibyte
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
401 buffer or string, because many non-@acronym{ASCII} characters have codes
37842
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
402 above octal 0377. However, the regular expression @code{"[^\000-\177]"}
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
403 does match all non-@acronym{ASCII} characters (see below regarding @samp{^}),
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
404 in both multibyte and unibyte representations, because only the
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
405 @acronym{ASCII} characters are excluded.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
406
60453
0b5288fc6e21 (Regexp Special, Char Classes): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 58349
diff changeset
407 A character alternative can also specify named
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
408 character classes (@pxref{Char Classes}). This is a POSIX feature whose
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
409 syntax is @samp{[:@var{class}:]}. Using a character class is equivalent
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
410 to mentioning each of the characters in that class; but the latter is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
411 not feasible in practice, since some classes include thousands of
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
412 different characters.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
413
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
414 @item @samp{[^ @dots{} ]}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
415 @cindex @samp{^} in regexp
63583
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
416 @samp{[^} begins a @dfn{complemented character alternative}. This
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
417 matches any character except the ones specified. Thus,
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
418 @samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
99e9892a51d9 Fix formatting ugliness.
Richard M. Stallman <rms@gnu.org>
parents: 63469
diff changeset
419 digits.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
420
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
421 @samp{^} is not special in a character alternative unless it is the first
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
422 character. The character following the @samp{^} is treated as if it
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
423 were first (in other words, @samp{-} and @samp{]} are not special there).
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
424
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
425 A complemented character alternative can match a newline, unless newline is
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
426 mentioned as one of the characters not to match. This is in contrast to
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
427 the handling of regexps in programs such as @code{grep}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
428
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
429 @item @samp{^}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
430 @cindex beginning of line in regexp
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
431 When matching a buffer, @samp{^} matches the empty string, but only at the
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
432 beginning of a line in the text being matched (or the beginning of the
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
433 accessible portion of the buffer). Otherwise it fails to match
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
434 anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
435 beginning of a line.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
436
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
437 When matching a string instead of a buffer, @samp{^} matches at the
37842
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
438 beginning of the string or after a newline character.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
439
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
440 For historical compatibility reasons, @samp{^} can be used only at the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
441 beginning of the regular expression, or after @samp{\(} or @samp{\|}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
442
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
443 @item @samp{$}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
444 @cindex @samp{$} in regexp
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
445 @cindex end of line in regexp
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
446 is similar to @samp{^} but matches only at the end of a line (or the
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
447 end of the accessible portion of the buffer). Thus, @samp{x+$}
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
448 matches a string of one @samp{x} or more at the end of a line.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
449
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
450 When matching a string instead of a buffer, @samp{$} matches at the end
37842
2b1f94f72990 Use Lisp escape sequences only inside string syntax.
Richard M. Stallman <rms@gnu.org>
parents: 35796
diff changeset
451 of the string or before a newline character.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
452
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
453 For historical compatibility reasons, @samp{$} can be used only at the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
454 end of the regular expression, or before @samp{\)} or @samp{\|}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
455
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
456 @item @samp{\}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
457 @cindex @samp{\} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
458 has two functions: it quotes the special characters (including
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
459 @samp{\}), and it introduces additional special constructs.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
460
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
461 Because @samp{\} quotes special characters, @samp{\$} is a regular
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
462 expression that matches only @samp{$}, and @samp{\[} is a regular
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
463 expression that matches only @samp{[}, and so on.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
464
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
465 Note that @samp{\} also has special meaning in the read syntax of Lisp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
466 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
467 example, the regular expression that matches the @samp{\} character is
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
468 @samp{\\}. To write a Lisp string that contains the characters
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
469 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
470 @samp{\}. Therefore, the read syntax for a regular expression matching
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
471 @samp{\} is @code{"\\\\"}.@refill
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
472 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
473
7735
7db892210924 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7086
diff changeset
474 @strong{Please note:} For historical compatibility, special characters
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
475 are treated as ordinary ones if they are in contexts where their special
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
476 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
477 ordinary since there is no preceding expression on which the @samp{*}
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
478 can act. It is poor practice to depend on this behavior; quote the
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
479 special character anyway, regardless of where it appears.@refill
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
480
69330
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
481 As a @samp{\} is not special inside a character alternative, it can
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
482 never remove the special meaning of @samp{-} or @samp{]}. So you
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
483 should not quote these characters when they have no special meaning
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
484 either. This would not clarify anything, since backslashes can
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
485 legitimately precede these characters where they @emph{have} special
69413
774f0386ba3c (Regexp Special): Use @samp for regular expressions that are not in
Luc Teirlinck <teirllm@auburn.edu>
parents: 69338
diff changeset
486 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
69330
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
487 which matches any single character except a backslash.
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
488
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
489 In practice, most @samp{]} that occur in regular expressions close a
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
490 character alternative and hence are special. However, occasionally a
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
491 regular expression may try to match a complex pattern of literal
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
492 @samp{[} and @samp{]}. In such situations, it sometimes may be
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
493 necessary to carefully parse the regexp from the start to determine
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
494 which square brackets enclose a character alternative. For example,
69413
774f0386ba3c (Regexp Special): Use @samp for regular expressions that are not in
Luc Teirlinck <teirllm@auburn.edu>
parents: 69338
diff changeset
495 @samp{[^][]]} consists of the complemented character alternative
774f0386ba3c (Regexp Special): Use @samp for regular expressions that are not in
Luc Teirlinck <teirllm@auburn.edu>
parents: 69338
diff changeset
496 @samp{[^][]} (which matches any single character that is not a square
69338
3b476a22dc6a (Regexp Special): Put remark between parentheses to avoid misreading.
Luc Teirlinck <teirllm@auburn.edu>
parents: 69330
diff changeset
497 bracket), followed by a literal @samp{]}.
69330
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
498
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
499 The exact rules are that at the beginning of a regexp, @samp{[} is
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
500 special and @samp{]} not. This lasts until the first unquoted
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
501 @samp{[}, after which we are in a character alternative; @samp{[} is
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
502 no longer special (except when it starts a character class) but @samp{]}
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
503 is special, unless it immediately follows the special @samp{[} or that
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
504 @samp{[} followed by a @samp{^}. This lasts until the next special
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
505 @samp{]} that does not end a character class. This ends the character
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
506 alternative and restores the ordinary syntax of regular expressions;
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
507 an unquoted @samp{[} is special again and a @samp{]} not.
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
508
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
509 @node Char Classes
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
510 @subsubsection Character Classes
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
511 @cindex character classes in regexp
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
512
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
513 Here is a table of the classes you can use in a character alternative,
60453
0b5288fc6e21 (Regexp Special, Char Classes): Get rid of "Emacs 21".
Richard M. Stallman <rms@gnu.org>
parents: 58349
diff changeset
514 and what they mean:
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
515
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
516 @table @samp
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
517 @item [:ascii:]
73235
869dcf71ace3 (Char Classes): Document :multibyte: and :unibyte:.
Richard M. Stallman <rms@gnu.org>
parents: 73098
diff changeset
518 This matches any @acronym{ASCII} character (codes 0--127).
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
519 @item [:alnum:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
520 This matches any letter or digit. (At present, for multibyte
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
521 characters, it matches anything that has word syntax.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
522 @item [:alpha:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
523 This matches any letter. (At present, for multibyte characters, it
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
524 matches anything that has word syntax.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
525 @item [:blank:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
526 This matches space and tab only.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
527 @item [:cntrl:]
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
528 This matches any @acronym{ASCII} control character.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
529 @item [:digit:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
530 This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
531 matches any digit, as well as @samp{+} and @samp{-}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
532 @item [:graph:]
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
533 This matches graphic characters---everything except @acronym{ASCII} control
27374
0f5edee5242b *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27373
diff changeset
534 characters, space, and the delete character.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
535 @item [:lower:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
536 This matches any lower-case letter, as determined by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
537 the current case table (@pxref{Case Tables}).
73235
869dcf71ace3 (Char Classes): Document :multibyte: and :unibyte:.
Richard M. Stallman <rms@gnu.org>
parents: 73098
diff changeset
538 @item [:multibyte:]
869dcf71ace3 (Char Classes): Document :multibyte: and :unibyte:.
Richard M. Stallman <rms@gnu.org>
parents: 73098
diff changeset
539 This matches any multibyte character (@pxref{Text Representations}).
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
540 @item [:nonascii:]
73235
869dcf71ace3 (Char Classes): Document :multibyte: and :unibyte:.
Richard M. Stallman <rms@gnu.org>
parents: 73098
diff changeset
541 This matches any non-@acronym{ASCII} character.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
542 @item [:print:]
52978
1a5c50faf357 Replace @sc{foo} with @acronym{FOO}.
Eli Zaretskii <eliz@gnu.org>
parents: 52401
diff changeset
543 This matches printing characters---everything except @acronym{ASCII} control
27373
a6d5729aef1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27193
diff changeset
544 characters and the delete character.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
545 @item [:punct:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
546 This matches any punctuation character. (At present, for multibyte
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
547 characters, it matches anything that has non-word syntax.)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
548 @item [:space:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
549 This matches any character that has whitespace syntax
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
550 (@pxref{Syntax Class Table}).
73235
869dcf71ace3 (Char Classes): Document :multibyte: and :unibyte:.
Richard M. Stallman <rms@gnu.org>
parents: 73098
diff changeset
551 @item [:unibyte:]
869dcf71ace3 (Char Classes): Document :multibyte: and :unibyte:.
Richard M. Stallman <rms@gnu.org>
parents: 73098
diff changeset
552 This matches any unibyte character (@pxref{Text Representations}).
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
553 @item [:upper:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
554 This matches any upper-case letter, as determined by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
555 the current case table (@pxref{Case Tables}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
556 @item [:word:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
557 This matches any character that has word syntax (@pxref{Syntax Class
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
558 Table}).
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
559 @item [:xdigit:]
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
560 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
561 through @samp{f} and @samp{A} through @samp{F}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
562 @end table
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
563
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
564 @node Regexp Backslash
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
565 @subsubsection Backslash Constructs in Regular Expressions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
566
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
567 For the most part, @samp{\} followed by any character matches only
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
568 that character. However, there are several exceptions: certain
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
569 two-character sequences starting with @samp{\} that have special
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
570 meanings. (The character after the @samp{\} in such a sequence is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
571 always ordinary when used on its own.) Here is a table of the special
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
572 @samp{\} constructs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
573
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
574 @table @samp
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
575 @item \|
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
576 @cindex @samp{|} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
577 @cindex regexp alternative
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
578 specifies an alternative.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
579 Two regular expressions @var{a} and @var{b} with @samp{\|} in
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
580 between form an expression that matches anything that either @var{a} or
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
581 @var{b} matches.@refill
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
582
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
583 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
584 but no other string.@refill
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
585
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
586 @samp{\|} applies to the largest possible surrounding expressions. Only a
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
587 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
588 @samp{\|}.@refill
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
589
49959
264cc4bc5c57 Clarify about POSIX functions and non-greedy repetition operators.
Richard M. Stallman <rms@gnu.org>
parents: 49809
diff changeset
590 If you need full backtracking capability to handle multiple uses of
264cc4bc5c57 Clarify about POSIX functions and non-greedy repetition operators.
Richard M. Stallman <rms@gnu.org>
parents: 49809
diff changeset
591 @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
264cc4bc5c57 Clarify about POSIX functions and non-greedy repetition operators.
Richard M. Stallman <rms@gnu.org>
parents: 49809
diff changeset
592 Regexps}).
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
593
27780
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
594 @item \@{@var{m}\@}
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
595 is a postfix operator that repeats the previous pattern exactly @var{m}
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
596 times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
597 and nothing else. @samp{c[ad]\@{3\@}r} matches string such as
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
598 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
599
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
600 @item \@{@var{m},@var{n}\@}
54041
bb6e41200945 Minor fixes.
Richard M. Stallman <rms@gnu.org>
parents: 53568
diff changeset
601 is a more general postfix operator that specifies repetition with a
27780
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
602 minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m}
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
603 is omitted, the minimum is 0; if @var{n} is omitted, there is no
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
604 maximum.
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
605
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
606 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
607 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
608 nothing else.@*
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
609 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @*
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
610 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @*
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
611 @samp{\@{1,\@}} is equivalent to @samp{+}.
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
612
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
613 @item \( @dots{} \)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
614 @cindex @samp{(} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
615 @cindex @samp{)} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
616 @cindex regexp grouping
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
617 is a grouping construct that serves three purposes:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
618
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
619 @enumerate
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
620 @item
16736
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12805
diff changeset
621 To enclose a set of @samp{\|} alternatives for other operations. Thus,
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12805
diff changeset
622 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
981e116b4ac6 Minor cleanups for overfull hboxes.
Richard M. Stallman <rms@gnu.org>
parents: 12805
diff changeset
623 or @samp{barx}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
624
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
625 @item
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
626 To enclose a complicated expression for the postfix operators @samp{*},
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
627 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
628 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
629 number (zero or more) of @samp{na} strings.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
630
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
631 @item
27780
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
632 To record a matched substring for future reference with
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
633 @samp{\@var{digit}} (see below).
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
634 @end enumerate
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
635
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
636 This last application is not a consequence of the idea of a
27780
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
637 parenthetical grouping; it is a separate feature that was assigned as a
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
638 second meaning to the same @samp{\( @dots{} \)} construct because, in
48701
bfdd0deae843 Fix typo.
Pavel Janík <Pavel@Janik.cz>
parents: 47435
diff changeset
639 practice, there was usually no conflict between the two meanings. But
27780
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
640 occasionally there is a conflict, and that led to the introduction of
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
641 shy groups.
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
642
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
643 @item \(?: @dots{} \)
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
644 is the @dfn{shy group} construct. A shy group serves the first two
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
645 purposes of an ordinary group (controlling the nesting of other
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
646 operators), but it does not get a number, so you cannot refer back to
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
647 its value with @samp{\@var{digit}}.
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
648
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
649 Shy groups are particularly useful for mechanically-constructed regular
27780
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
650 expressions because they can be added automatically without altering the
72cae205b4f4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 27374
diff changeset
651 numbering of any ordinary, non-shy groups.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
652
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
653 @item \@var{digit}
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
654 matches the same text that matched the @var{digit}th occurrence of a
39166
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
655 grouping (@samp{\( @dots{} \)}) construct.
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
656
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
657 In other words, after the end of a group, the matcher remembers the
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
658 beginning and end of the text matched by that group. Later on in the
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
659 regular expression you can use @samp{\} followed by @var{digit} to
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
660 match that same text, whatever it may have been.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
661
39166
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
662 The strings matching the first nine grouping constructs appearing in
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
663 the entire regular expression passed to a search or matching function
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
664 are assigned numbers 1 through 9 in the order that the open
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
665 parentheses appear in the regular expression. So you can use
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
666 @samp{\1} through @samp{\9} to refer to the text matched by the
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
667 corresponding grouping constructs.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
668
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
669 For example, @samp{\(.*\)\1} matches any newline-free string that is
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
670 composed of two identical halves. The @samp{\(.*\)} matches the first
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
671 half, which may be anything, but the @samp{\1} that follows must match
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
672 the same exact text.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
673
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
674 If a @samp{\( @dots{} \)} construct matches more than once (which can
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
675 happen, for instance, if it is followed by @samp{*}), only the last
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
676 match is recorded.
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
677
39166
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
678 If a particular grouping construct in the regular expression was never
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
679 matched---for instance, if it appears inside of an alternative that
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
680 wasn't used, or inside of a repetition that repeated zero times---then
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
681 the corresponding @samp{\@var{digit}} construct never matches
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
682 anything. To use an artificial example,, @samp{\(foo\(b*\)\|lose\)\2}
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
683 cannot match @samp{lose}: the second alternative inside the larger
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
684 group matches it, but then @samp{\2} is undefined and can't match
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
685 anything. But it can match @samp{foobb}, because the first
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
686 alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
687
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
688 @item \w
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
689 @cindex @samp{\w} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
690 matches any word-constituent character. The editor syntax table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
691 determines which characters these are. @xref{Syntax Tables}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
692
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
693 @item \W
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
694 @cindex @samp{\W} in regexp
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
695 matches any character that is not a word constituent.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
696
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
697 @item \s@var{code}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
698 @cindex @samp{\s} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
699 matches any character whose syntax is @var{code}. Here @var{code} is a
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
700 character that represents a syntax code: thus, @samp{w} for word
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
701 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
702 etc. To represent whitespace syntax, use either @samp{-} or a space
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
703 character. @xref{Syntax Class Table}, for a list of syntax codes and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
704 the characters that stand for them.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
705
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
706 @item \S@var{code}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
707 @cindex @samp{\S} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
708 matches any character whose syntax is not @var{code}.
35796
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
709
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
710 @item \c@var{c}
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
711 matches any character whose category is @var{c}. Here @var{c} is a
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
712 character that represents a category: thus, @samp{c} for Chinese
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
713 characters or @samp{g} for Greek characters in the standard category
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
714 table.
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
715
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
716 @item \C@var{c}
d3872b19023d (Regexp Backslash): categories.
Dave Love <fx@gnu.org>
parents: 32464
diff changeset
717 matches any character whose category is not @var{c}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
718 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
719
8427
bc548090f760 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 7735
diff changeset
720 The following regular expression constructs match the empty string---that is,
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
721 they don't use up any characters---but whether they match depends on the
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
722 context. For all, the beginning and end of the accessible portion of
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
723 the buffer are treated as if they were the actual beginning and end of
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
724 the buffer.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
725
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
726 @table @samp
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
727 @item \`
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
728 @cindex @samp{\`} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
729 matches the empty string, but only at the beginning
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
730 of the buffer or string being matched against.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
731
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
732 @item \'
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
733 @cindex @samp{\'} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
734 matches the empty string, but only at the end of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
735 the buffer or string being matched against.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
736
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
737 @item \=
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
738 @cindex @samp{\=} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
739 matches the empty string, but only at point.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
740 (This construct is not defined when matching against a string.)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
741
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
742 @item \b
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
743 @cindex @samp{\b} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
744 matches the empty string, but only at the beginning or
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
745 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
746 @samp{foo} as a separate word. @samp{\bballs?\b} matches
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
747 @samp{ball} or @samp{balls} as a separate word.@refill
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
748
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
749 @samp{\b} matches at the beginning or end of the buffer (or string)
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
750 regardless of what text appears next to it.
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
751
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
752 @item \B
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
753 @cindex @samp{\B} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
754 matches the empty string, but @emph{not} at the beginning or
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
755 end of a word, nor at the beginning or end of the buffer (or string).
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
756
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
757 @item \<
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
758 @cindex @samp{\<} in regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
759 matches the empty string, but only at the beginning of a word.
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
760 @samp{\<} matches at the beginning of the buffer (or string) only if a
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
761 word-constituent character follows.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
762
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
763 @item \>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
764 @cindex @samp{\>} in regexp
17884
aa0b21b54684 Update regexp syntax from Emacs manual.
Richard M. Stallman <rms@gnu.org>
parents: 16736
diff changeset
765 matches the empty string, but only at the end of a word. @samp{\>}
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
766 matches at the end of the buffer (or string) only if the contents end
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
767 with a word-constituent character.
56439
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
768
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
769 @item \_<
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
770 @cindex @samp{\_<} in regexp
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
771 matches the empty string, but only at the beginning of a symbol. A
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
772 symbol is a sequence of one or more word or symbol constituent
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
773 characters. @samp{\_<} matches at the beginning of the buffer (or
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
774 string) only if a symbol-constituent character follows.
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
775
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
776 @item \_>
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
777 @cindex @samp{\_>} in regexp
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
778 matches the empty string, but only at the end of a symbol. @samp{\_>}
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
779 matches at the end of the buffer (or string) only if the contents end
7cc505680b75 (Regexp Backslash): Document new \_< and \_> operators.
Luc Teirlinck <teirllm@auburn.edu>
parents: 56313
diff changeset
780 with a symbol-constituent character.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
781 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
782
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
783 @kindex invalid-regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
784 Not every string is a valid regular expression. For example, a string
69330
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
785 that ends inside a character alternative without terminating @samp{]}
b000598ecc11 (Syntax of Regexps): More accurately describe
Luc Teirlinck <teirllm@auburn.edu>
parents: 68648
diff changeset
786 is invalid, and so is a string that ends with a single @samp{\}. If
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
787 an invalid regular expression is passed to any of the search functions,
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
788 an @code{invalid-regexp} error is signaled.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
789
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
790 @node Regexp Example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
791 @comment node-name, next, previous, up
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
792 @subsection Complex Regexp Example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
793
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
794 Here is a complicated regexp which was formerly used by Emacs to
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
795 recognize the end of a sentence together with any whitespace that
57403
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
796 follows. (Nowadays Emacs uses a similar but more complex default
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
797 regexp constructed by the function @code{sentence-end}.
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
798 @xref{Standard Regexps}.)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
799
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
800 First, we show the regexp as a string in Lisp syntax to distinguish
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
801 spaces from tab characters. The string constant begins and ends with a
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
802 double-quote. @samp{\"} stands for a double-quote as part of the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
803 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
804 tab and @samp{\n} for a newline.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
805
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
806 @example
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
807 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
808 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
809
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
810 @noindent
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
811 In contrast, if you evaluate this string, you will see the following:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
812
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
813 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
814 @group
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
815 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
816 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
817 ]*"
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
818 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
819 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
820
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
821 @noindent
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
822 In this output, tab and newline appear as themselves.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
823
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
824 This regular expression contains four parts in succession and can be
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
825 deciphered as follows:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
826
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
827 @table @code
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
828 @item [.?!]
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
829 The first part of the pattern is a character alternative that matches
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
830 any one of three characters: period, question mark, and exclamation
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
831 mark. The match must begin with one of these three characters. (This
57403
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
832 is one point where the new default regexp used by Emacs differs from
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
833 the old. The new value also allows some non-@acronym{ASCII}
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
834 characters that end a sentence without any following whitespace.)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
835
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
836 @item []\"')@}]*
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
837 The second part of the pattern matches any closing braces and quotation
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
838 marks, zero or more of them, that may follow the period, question mark
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
839 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
840 a string. The @samp{*} at the end indicates that the immediately
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
841 preceding regular expression (a character alternative, in this case) may be
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
842 repeated zero or more times.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
843
8469
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
844 @item \\($\\|@ $\\|\t\\|@ @ \\)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
845 The third part of the pattern matches the whitespace that follows the
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
846 end of a sentence: the end of a line (optionally with a space), or a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
847 tab, or two spaces. The double backslashes mark the parentheses and
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
848 vertical bars as regular expression syntax; the parentheses delimit a
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
849 group and the vertical bars separate alternatives. The dollar sign is
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
850 used to match the end of a line.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
851
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
852 @item [ \t\n]*
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
853 Finally, the last part of the pattern matches any additional whitespace
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
854 beyond the minimum needed to end a sentence.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
855 @end table
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
856
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
857 @node Regexp Functions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
858 @subsection Regular Expression Functions
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
859
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
860 These functions operate on regular expressions.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
861
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
862 @defun regexp-quote string
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
863 This function returns a regular expression whose only exact match is
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
864 @var{string}. Using this regular expression in @code{looking-at} will
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
865 succeed only if the next characters in the buffer are @var{string};
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
866 using it in a search function will succeed if the text being searched
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
867 contains @var{string}.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
868
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
869 This allows you to request an exact string match or search when calling
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
870 a function that wants a regular expression.
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
871
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
872 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
873 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
874 (regexp-quote "^The cat$")
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
875 @result{} "\\^The cat\\$"
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
876 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
877 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
878
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
879 One use of @code{regexp-quote} is to combine an exact string match with
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
880 context described as a regular expression. For example, this searches
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
881 for the string that is the value of @var{string}, surrounded by
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
882 whitespace:
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
883
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
884 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
885 @group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
886 (re-search-forward
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
887 (concat "\\s-" (regexp-quote string) "\\s-"))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
888 @end group
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
889 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
890 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
891
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
892 @defun regexp-opt strings &optional paren
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
893 This function returns an efficient regular expression that will match
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
894 any of the strings in the list @var{strings}. This is useful when you
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
895 need to make matching or searching as fast as possible---for example,
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
896 for Font Lock mode.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
897
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
898 If the optional argument @var{paren} is non-@code{nil}, then the
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
899 returned regular expression is always enclosed by at least one
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
900 parentheses-grouping construct. If @var{paren} is @code{words}, then
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
901 that construct is additionally surrounded by @samp{\<} and @samp{\>}.
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
902
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
903 This simplified definition of @code{regexp-opt} produces a
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
904 regular expression which is equivalent to the actual value
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
905 (but not as efficient):
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
906
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
907 @example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
908 (defun regexp-opt (strings paren)
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
909 (let ((open-paren (if paren "\\(" ""))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
910 (close-paren (if paren "\\)" "")))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
911 (concat open-paren
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
912 (mapconcat 'regexp-quote strings "\\|")
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
913 close-paren)))
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
914 @end example
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
915 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
916
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
917 @defun regexp-opt-depth regexp
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
918 This function returns the total number of grouping constructs
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
919 (parenthesized expressions) in @var{regexp}. (This does not include
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
920 shy groups.)
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
921 @end defun
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
922
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
923 @node Regexp Search
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
924 @section Regular Expression Searching
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
925 @cindex regular expression searching
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
926 @cindex regexp searching
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
927 @cindex searching for regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
928
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
929 In GNU Emacs, you can search for the next match for a regular
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
930 expression either incrementally or not. For incremental search
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
931 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
932 The GNU Emacs Manual}. Here we describe only the search functions
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
933 useful in programs. The principal one is @code{re-search-forward}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
934
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
935 These search functions convert the regular expression to multibyte if
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
936 the buffer is multibyte; they convert the regular expression to unibyte
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
937 if the buffer is unibyte. @xref{Text Representations}.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
938
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
939 @deffn Command re-search-forward regexp &optional limit noerror repeat
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
940 This function searches forward in the current buffer for a string of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
941 text that is matched by the regular expression @var{regexp}. The
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
942 function skips over any amount of text that is not matched by
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
943 @var{regexp}, and leaves point at the end of the first match found.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
944 It returns the new value of point.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
945
60678
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
946 If @var{limit} is non-@code{nil}, it must be a position in the current
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
947 buffer. It specifies the upper bound to the search. No match
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
948 extending after that position is accepted.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
949
60678
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
950 If @var{repeat} is supplied, it must be a positive number; the search
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
951 is repeated that many times; each repetition starts at the end of the
64115
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
952 previous match. If all these successive searches succeed, the search
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
953 succeeds, moving point and returning its new value. Otherwise the
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
954 search fails. What @code{re-search-forward} does when the search
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
955 fails depends on the value of @var{noerror}:
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
956
64115
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
957 @table @asis
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
958 @item @code{nil}
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
959 Signal a @code{search-failed} error.
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
960 @item @code{t}
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
961 Do nothing and return @code{nil}.
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
962 @item anything else
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
963 Move point to @var{limit} (or the end of the accessible portion of the
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
964 buffer) and return @code{nil}.
23d3e1c615ee (Regexp Search): Clarify what re-search-forward does when the search fails.
Richard M. Stallman <rms@gnu.org>
parents: 63663
diff changeset
965 @end table
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
966
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
967 In the following example, point is initially before the @samp{T}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
968 Evaluating the search call moves point to the end of that line (between
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
969 the @samp{t} of @samp{hat} and the newline).
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
970
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
971 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
972 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
973 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
974 I read "@point{}The cat in the hat
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
975 comes back" twice.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
976 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
977 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
978
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
979 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
980 (re-search-forward "[a-z]+" nil t 5)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
981 @result{} 27
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
982
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
983 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
984 I read "The cat in the hat@point{}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
985 comes back" twice.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
986 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
987 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
988 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
989 @end deffn
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
990
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
991 @deffn Command re-search-backward regexp &optional limit noerror repeat
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
992 This function searches backward in the current buffer for a string of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
993 text that is matched by the regular expression @var{regexp}, leaving
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
994 point at the beginning of the first text found.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
995
8469
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
996 This function is analogous to @code{re-search-forward}, but they are not
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
997 simple mirror images. @code{re-search-forward} finds the match whose
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
998 beginning is as close as possible to the starting point. If
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
999 @code{re-search-backward} were a perfect mirror image, it would find the
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1000 match whose end is as close as possible. However, in fact it finds the
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1001 match whose beginning is as close as possible (and yet ends before the
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1002 starting point). The reason for this is that matching a regular
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1003 expression at a given spot always works from beginning to end, and
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1004 starts at a specified beginning position.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1005
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1006 A true mirror-image of @code{re-search-forward} would require a special
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1007 feature for matching regular expressions from end to beginning. It's
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1008 not worth the trouble of implementing that.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1009 @end deffn
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1010
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1011 @defun string-match regexp string &optional start
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1012 This function returns the index of the start of the first match for
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1013 the regular expression @var{regexp} in @var{string}, or @code{nil} if
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1014 there is no match. If @var{start} is non-@code{nil}, the search starts
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1015 at that index in @var{string}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1016
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1017 For example,
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1018
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1019 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1020 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1021 (string-match
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1022 "quick" "The quick brown fox jumped quickly.")
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1023 @result{} 4
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1024 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1025 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1026 (string-match
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1027 "quick" "The quick brown fox jumped quickly." 8)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1028 @result{} 27
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1029 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1030 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1031
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1032 @noindent
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1033 The index of the first character of the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1034 string is 0, the index of the second character is 1, and so on.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1035
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1036 After this function returns, the index of the first character beyond
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1037 the match is available as @code{(match-end 0)}. @xref{Match Data}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1038
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1039 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1040 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1041 (string-match
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1042 "quick" "The quick brown fox jumped quickly." 8)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1043 @result{} 27
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1044 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1045
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1046 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1047 (match-end 0)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1048 @result{} 32
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1049 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1050 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1051 @end defun
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1052
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1053 @defun looking-at regexp
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1054 This function determines whether the text in the current buffer directly
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1055 following point matches the regular expression @var{regexp}. ``Directly
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1056 following'' means precisely that: the search is ``anchored'' and it can
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1057 succeed only starting with the first character following point. The
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1058 result is @code{t} if so, @code{nil} otherwise.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1059
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1060 This function does not move point, but it updates the match data, which
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1061 you can access using @code{match-beginning} and @code{match-end}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1062 @xref{Match Data}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1063
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1064 In this example, point is located directly before the @samp{T}. If it
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1065 were anywhere else, the result would be @code{nil}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1066
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1067 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1068 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1069 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1070 I read "@point{}The cat in the hat
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1071 comes back" twice.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1072 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1073
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1074 (looking-at "The cat in the hat$")
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1075 @result{} t
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1076 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1077 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1078 @end defun
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1079
57252
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1080 @defun looking-back regexp &optional limit
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1081 This function returns @code{t} if @var{regexp} matches text before
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1082 point, ending at point, and @code{nil} otherwise.
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1083
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1084 Because regular expression matching works only going forward, this is
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1085 implemented by searching backwards from point for a match that ends at
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1086 point. That can be quite slow if it has to search a long distance.
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1087 You can bound the time required by specifying @var{limit}, which says
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1088 not to search before @var{limit}. In this case, the match that is
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1089 found must begin at or after @var{limit}.
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1090
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1091 @example
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1092 @group
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1093 ---------- Buffer: foo ----------
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1094 I read "@point{}The cat in the hat
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1095 comes back" twice.
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1096 ---------- Buffer: foo ----------
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1097
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1098 (looking-back "read \"" 3)
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1099 @result{} t
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1100 (looking-back "read \"" 4)
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1101 @result{} nil
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1102 @end group
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1103 @end example
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1104 @end defun
a325c378e9bb (Regexp Search): Add looking-back.
Richard M. Stallman <rms@gnu.org>
parents: 56439
diff changeset
1105
58349
e497e4d0b665 (Regexp Search): Rename that to search-spaces-regexp.
Richard M. Stallman <rms@gnu.org>
parents: 58329
diff changeset
1106 @defvar search-spaces-regexp
58329
30f22485a11e (Regexp Search): Add search-whitespace-regexp.
Richard M. Stallman <rms@gnu.org>
parents: 57403
diff changeset
1107 If this variable is non-@code{nil}, it should be a regular expression
30f22485a11e (Regexp Search): Add search-whitespace-regexp.
Richard M. Stallman <rms@gnu.org>
parents: 57403
diff changeset
1108 that says how to search for whitespace. In that case, any group of
60678
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1109 spaces in a regular expression being searched for stands for use of
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1110 this regular expression. However, spaces inside of constructs such as
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1111 @samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1112 @code{search-spaces-regexp}.
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1113
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1114 Since this variable affects all regular expression search and match
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1115 constructs, you should bind it temporarily for as small as possible
b41b3abcbecf (String Search, Regexp Search, Regexp Search): Cleanups.
Richard M. Stallman <rms@gnu.org>
parents: 60453
diff changeset
1116 a part of the code.
58329
30f22485a11e (Regexp Search): Add search-whitespace-regexp.
Richard M. Stallman <rms@gnu.org>
parents: 57403
diff changeset
1117 @end defvar
30f22485a11e (Regexp Search): Add search-whitespace-regexp.
Richard M. Stallman <rms@gnu.org>
parents: 57403
diff changeset
1118
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1119 @node POSIX Regexps
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1120 @section POSIX Regular Expression Searching
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1121
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1122 The usual regular expression functions do backtracking when necessary
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1123 to handle the @samp{\|} and repetition constructs, but they continue
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1124 this only until they find @emph{some} match. Then they succeed and
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1125 report the first match found.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1126
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1127 This section describes alternative search functions which perform the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1128 full backtracking specified by the POSIX standard for regular expression
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1129 matching. They continue backtracking until they have tried all
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1130 possibilities and found all matches, so they can report the longest
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1131 match, as required by POSIX. This is much slower, so use these
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1132 functions only when you really need the longest match.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1133
49959
264cc4bc5c57 Clarify about POSIX functions and non-greedy repetition operators.
Richard M. Stallman <rms@gnu.org>
parents: 49809
diff changeset
1134 The POSIX search and match functions do not properly support the
264cc4bc5c57 Clarify about POSIX functions and non-greedy repetition operators.
Richard M. Stallman <rms@gnu.org>
parents: 49809
diff changeset
1135 non-greedy repetition operators. This is because POSIX backtracking
264cc4bc5c57 Clarify about POSIX functions and non-greedy repetition operators.
Richard M. Stallman <rms@gnu.org>
parents: 49809
diff changeset
1136 conflicts with the semantics of non-greedy repetition.
264cc4bc5c57 Clarify about POSIX functions and non-greedy repetition operators.
Richard M. Stallman <rms@gnu.org>
parents: 49809
diff changeset
1137
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1138 @defun posix-search-forward regexp &optional limit noerror repeat
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1139 This is like @code{re-search-forward} except that it performs the full
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1140 backtracking specified by the POSIX standard for regular expression
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1141 matching.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1142 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1143
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1144 @defun posix-search-backward regexp &optional limit noerror repeat
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1145 This is like @code{re-search-backward} except that it performs the full
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1146 backtracking specified by the POSIX standard for regular expression
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1147 matching.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1148 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1149
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1150 @defun posix-looking-at regexp
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1151 This is like @code{looking-at} except that it performs the full
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1152 backtracking specified by the POSIX standard for regular expression
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1153 matching.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1154 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1155
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1156 @defun posix-string-match regexp string &optional start
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1157 This is like @code{string-match} except that it performs the full
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1158 backtracking specified by the POSIX standard for regular expression
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1159 matching.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1160 @end defun
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1161
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1162 @node Match Data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1163 @section The Match Data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1164 @cindex match data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1165
25089
309fe4eb6522 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 24934
diff changeset
1166 Emacs keeps track of the start and end positions of the segments of
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1167 text found during a search; this is called the @dfn{match data}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1168 Thanks to the match data, you can search for a complex pattern, such
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1169 as a date in a mail message, and then extract parts of the match under
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1170 control of the pattern.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1171
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1172 Because the match data normally describe the most recent search only,
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1173 you must be careful not to do another search inadvertently between the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1174 search you wish to refer back to and the use of the match data. If you
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1175 can't avoid another intervening search, you must save and restore the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1176 match data around it, to prevent it from being overwritten.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1177
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1178 @menu
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1179 * Replacing Match:: Replacing a substring that was matched.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1180 * Simple Match Data:: Accessing single items of match data,
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1181 such as where a particular subexpression started.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1182 * Entire Match Data:: Accessing the entire match data at once, as a list.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1183 * Saving Match Data:: Saving and restoring the match data.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1184 @end menu
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1185
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1186 @node Replacing Match
25751
467b88fab665 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 25089
diff changeset
1187 @subsection Replacing the Text that Matched
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1188
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1189 This function replaces all or part of the text matched by the last
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1190 search. It works by means of the match data.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1191
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1192 @cindex case in replacements
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1193 @defun replace-match replacement &optional fixedcase literal string subexp
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1194 This function replaces the text in the buffer (or in @var{string}) that
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1195 was matched by the last search. It replaces that text with
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1196 @var{replacement}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1197
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1198 If you did the last search in a buffer, you should specify @code{nil}
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1199 for @var{string} and make sure that the current buffer when you call
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1200 @code{replace-match} is the one in which you did the searching or
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1201 matching. Then @code{replace-match} does the replacement by editing
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1202 the buffer; it leaves point at the end of the replacement text, and
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1203 returns @code{t}.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1204
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1205 If you did the search in a string, pass the same string as @var{string}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1206 Then @code{replace-match} does the replacement by constructing and
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1207 returning a new string.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1208
45104
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1209 If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1210 the replacement text without case conversion; otherwise, it converts
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1211 the replacement text depending upon the capitalization of the text to
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1212 be replaced. If the original text is all upper case, this converts
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1213 the replacement text to upper case. If all words of the original text
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1214 are capitalized, this capitalizes all the words of the replacement
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1215 text. If all the words are one-letter and they are all upper case,
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1216 they are treated as capitalized words rather than all-upper-case
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1217 words.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1218
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1219 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1220 exactly as it is, the only alterations being case changes as needed.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1221 If it is @code{nil} (the default), then the character @samp{\} is treated
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1222 specially. If a @samp{\} appears in @var{replacement}, then it must be
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1223 part of one of the following sequences:
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1224
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1225 @table @asis
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1226 @item @samp{\&}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1227 @cindex @samp{&} in replacement
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1228 @samp{\&} stands for the entire text being replaced.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1229
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1230 @item @samp{\@var{n}}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1231 @cindex @samp{\@var{n}} in replacement
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1232 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1233 matched the @var{n}th subexpression in the original regexp.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1234 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1235 If the @var{n}th subexpression never matched, an empty string is substituted.
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1236
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1237 @item @samp{\\}
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1238 @cindex @samp{\} in replacement
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1239 @samp{\\} stands for a single @samp{\} in the replacement text.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1240 @end table
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1241
45104
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1242 These substitutions occur after case conversion, if any,
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1243 so the strings they substitute are never case-converted.
441493d3bba0 Clarify how replace-match does case conversion.
Richard M. Stallman <rms@gnu.org>
parents: 41939
diff changeset
1244
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1245 If @var{subexp} is non-@code{nil}, that says to replace just
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1246 subexpression number @var{subexp} of the regexp that was matched, not
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1247 the entire match. For example, after matching @samp{foo \(ba*r\)},
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1248 calling @code{replace-match} with 1 as @var{subexp} means to replace
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1249 just the text that matched @samp{\(ba*r\)}.
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1250 @end defun
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1251
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1252 @node Simple Match Data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1253 @subsection Simple Match Data Access
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1254
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1255 This section explains how to use the match data to find out what was
49809
4556482b5d22 Clarify that match data is unpredictable after failing searches.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
1256 matched by the last search or match operation, if it succeeded.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1257
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1258 You can ask about the entire matching text, or about a particular
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1259 parenthetical subexpression of a regular expression. The @var{count}
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1260 argument in the functions below specifies which. If @var{count} is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1261 zero, you are asking about the entire match. If @var{count} is
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1262 positive, it specifies which subexpression you want.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1263
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1264 Recall that the subexpressions of a regular expression are those
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1265 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1266 @var{count}th subexpression is found by counting occurrences of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1267 @samp{\(} from the beginning of the whole regular expression. The first
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1268 subexpression is numbered 1, the second 2, and so on. Only regular
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1269 expressions can have subexpressions---after a simple string search, the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1270 only information available is about the entire match.
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1271
70741
0e29340d15dc (Simple Match Data): Warn about match data being set anew by every search.
Eli Zaretskii <eliz@gnu.org>
parents: 70692
diff changeset
1272 Every successful search sets the match data. Therefore, you should
0e29340d15dc (Simple Match Data): Warn about match data being set anew by every search.
Eli Zaretskii <eliz@gnu.org>
parents: 70692
diff changeset
1273 query the match data immediately after searching, before calling any
0e29340d15dc (Simple Match Data): Warn about match data being set anew by every search.
Eli Zaretskii <eliz@gnu.org>
parents: 70692
diff changeset
1274 other function that might perform another search. Alternatively, you
0e29340d15dc (Simple Match Data): Warn about match data being set anew by every search.
Eli Zaretskii <eliz@gnu.org>
parents: 70692
diff changeset
1275 may save and restore the match data (@pxref{Saving Match Data}) around
0e29340d15dc (Simple Match Data): Warn about match data being set anew by every search.
Eli Zaretskii <eliz@gnu.org>
parents: 70692
diff changeset
1276 the call to functions that could perform another search.
0e29340d15dc (Simple Match Data): Warn about match data being set anew by every search.
Eli Zaretskii <eliz@gnu.org>
parents: 70692
diff changeset
1277
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1278 A search which fails may or may not alter the match data. In the
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1279 past, a failing search did not do this, but we may change it in the
49809
4556482b5d22 Clarify that match data is unpredictable after failing searches.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
1280 future. So don't try to rely on the value of the match data after
4556482b5d22 Clarify that match data is unpredictable after failing searches.
Richard M. Stallman <rms@gnu.org>
parents: 49600
diff changeset
1281 a failing search.
22138
d4ac295a98b3 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21682
diff changeset
1282
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1283 @defun match-string count &optional in-string
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1284 This function returns, as a string, the text matched in the last search
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1285 or match operation. It returns the entire text if @var{count} is zero,
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1286 or just the portion corresponding to the @var{count}th parenthetical
39166
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
1287 subexpression, if @var{count} is positive.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1288
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1289 If the last such operation was done against a string with
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1290 @code{string-match}, then you should pass the same string as the
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1291 argument @var{in-string}. After a buffer search or match,
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1292 you should omit @var{in-string} or pass @code{nil} for it; but you
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1293 should make sure that the current buffer when you call
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1294 @code{match-string} is the one in which you did the searching or
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1295 matching.
39166
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
1296
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
1297 The value is @code{nil} if @var{count} is out of range, or for a
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
1298 subexpression inside a @samp{\|} alternative that wasn't used or a
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
1299 repetition that repeated zero times.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1300 @end defun
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1301
26288
6119687f6888 Patch from rms.
Gerd Moellmann <gerd@gnu.org>
parents: 25751
diff changeset
1302 @defun match-string-no-properties count &optional in-string
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
1303 This function is like @code{match-string} except that the result
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
1304 has no text properties.
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
1305 @end defun
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
1306
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1307 @defun match-beginning count
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1308 This function returns the position of the start of text matched by the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1309 last regular expression searched for, or a subexpression of it.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1310
8469
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1311 If @var{count} is zero, then the value is the position of the start of
12125
995be67f3fd1 updates for version 19.29.
Melissa Weisshaus <melissa@gnu.org>
parents: 12098
diff changeset
1312 the entire match. Otherwise, @var{count} specifies a subexpression in
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1313 the regular expression, and the value of the function is the starting
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1314 position of the match for that subexpression.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1315
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1316 The value is @code{nil} for a subexpression inside a @samp{\|}
39166
f0bfa8a7d472 Explain clearly what \digit does when that grouping
Richard M. Stallman <rms@gnu.org>
parents: 38927
diff changeset
1317 alternative that wasn't used or a repetition that repeated zero times.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1318 @end defun
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1319
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1320 @defun match-end count
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1321 This function is like @code{match-beginning} except that it returns the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1322 position of the end of the match, rather than the position of the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1323 beginning.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1324 @end defun
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1325
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1326 Here is an example of using the match data, with a comment showing the
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1327 positions within the text:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1328
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1329 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1330 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1331 (string-match "\\(qu\\)\\(ick\\)"
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1332 "The quick fox jumped quickly.")
49600
23a1cea22d13 Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents: 48701
diff changeset
1333 ;0123456789
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1334 @result{} 4
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1335 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1336
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1337 @group
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1338 (match-string 0 "The quick fox jumped quickly.")
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1339 @result{} "quick"
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1340 (match-string 1 "The quick fox jumped quickly.")
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1341 @result{} "qu"
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1342 (match-string 2 "The quick fox jumped quickly.")
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1343 @result{} "ick"
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1344 @end group
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1345
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1346 @group
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1347 (match-beginning 1) ; @r{The beginning of the match}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1348 @result{} 4 ; @r{with @samp{qu} is at index 4.}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1349 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1350
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1351 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1352 (match-beginning 2) ; @r{The beginning of the match}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1353 @result{} 6 ; @r{with @samp{ick} is at index 6.}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1354 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1355
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1356 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1357 (match-end 1) ; @r{The end of the match}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1358 @result{} 6 ; @r{with @samp{qu} is at index 6.}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1359
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1360 (match-end 2) ; @r{The end of the match}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1361 @result{} 9 ; @r{with @samp{ick} is at index 9.}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1362 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1363 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1364
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1365 Here is another example. Point is initially located at the beginning
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1366 of the line. Searching moves point to between the space and the word
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1367 @samp{in}. The beginning of the entire match is at the 9th character of
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1368 the buffer (@samp{T}), and the beginning of the match for the first
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1369 subexpression is at the 13th character (@samp{c}).
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1370
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1371 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1372 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1373 (list
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1374 (re-search-forward "The \\(cat \\)")
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1375 (match-beginning 0)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1376 (match-beginning 1))
8469
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1377 @result{} (9 9 13)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1378 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1379
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1380 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1381 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1382 I read "The cat @point{}in the hat comes back" twice.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1383 ^ ^
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1384 9 13
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1385 ---------- Buffer: foo ----------
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1386 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1387 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1388
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1389 @noindent
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1390 (In this case, the index returned is a buffer position; the first
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1391 character of the buffer counts as 1.)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1392
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1393 @node Entire Match Data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1394 @subsection Accessing the Entire Match Data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1395
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1396 The functions @code{match-data} and @code{set-match-data} read or
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1397 write the entire match data, all at once.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1398
63153
286783f742e6 (Entire Match Data): Explain new `reseat' argument to
Kim F. Storm <storm@cua.dk>
parents: 63135
diff changeset
1399 @defun match-data &optional integers reuse reseat
63135
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1400 This function returns a list of positions (markers or integers) that
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1401 record all the information on what text the last search matched.
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1402 Element zero is the position of the beginning of the match for the
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1403 whole expression; element one is the position of the end of the match
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1404 for the expression. The next two elements are the positions of the
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1405 beginning and end of the match for the first subexpression, and so on.
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1406 In general, element
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1407 @ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1408 number 2@var{n}
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1409 @end ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1410 @tex
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1411 number {\mathsurround=0pt $2n$}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1412 @end tex
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1413 corresponds to @code{(match-beginning @var{n})}; and
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1414 element
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1415 @ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1416 number 2@var{n} + 1
27193
89afca54a135 @ifinto -> @ifnottex.
Gerd Moellmann <gerd@gnu.org>
parents: 27189
diff changeset
1417 @end ifnottex
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1418 @tex
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1419 number {\mathsurround=0pt $2n+1$}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1420 @end tex
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1421 corresponds to @code{(match-end @var{n})}.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1422
63135
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1423 Normally all the elements are markers or @code{nil}, but if
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1424 @var{integers} is non-@code{nil}, that means to use integers instead
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1425 of markers. (In that case, the buffer itself is appended as an
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1426 additional element at the end of the list, to facilitate complete
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1427 restoration of the match data.) If the last match was done on a
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1428 string with @code{string-match}, then integers are always used,
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1429 since markers can't point into a string.
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1430
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1431 If @var{reuse} is non-@code{nil}, it should be a list. In that case,
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1432 @code{match-data} stores the match data in @var{reuse}. That is,
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1433 @var{reuse} is destructively modified. @var{reuse} does not need to
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1434 have the right length. If it is not long enough to contain the match
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1435 data, it is extended. If it is too long, the length of @var{reuse}
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1436 stays the same, but the elements that were not used are set to
63135
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1437 @code{nil}. The purpose of this feature is to reduce the need for
ade1be8b63fd (Entire Match Data): Clarify when match-data
Richard M. Stallman <rms@gnu.org>
parents: 60678
diff changeset
1438 garbage collection.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1439
63153
286783f742e6 (Entire Match Data): Explain new `reseat' argument to
Kim F. Storm <storm@cua.dk>
parents: 63135
diff changeset
1440 If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
63663
c4d74e911908 (Entire Match Data): Remove evaporate option for
Kim F. Storm <storm@cua.dk>
parents: 63583
diff changeset
1441 are reseated to point to nowhere.
63153
286783f742e6 (Entire Match Data): Explain new `reseat' argument to
Kim F. Storm <storm@cua.dk>
parents: 63135
diff changeset
1442
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1443 As always, there must be no possibility of intervening searches between
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1444 the call to a search function and the call to @code{match-data} that is
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1445 intended to access the match data for that search.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1446
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1447 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1448 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1449 (match-data)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1450 @result{} (#<marker at 9 in foo>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1451 #<marker at 17 in foo>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1452 #<marker at 13 in foo>
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1453 #<marker at 17 in foo>)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1454 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1455 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1456 @end defun
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1457
63153
286783f742e6 (Entire Match Data): Explain new `reseat' argument to
Kim F. Storm <storm@cua.dk>
parents: 63135
diff changeset
1458 @defun set-match-data match-list &optional reseat
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1459 This function sets the match data from the elements of @var{match-list},
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1460 which should be a list that was the value of a previous call to
41939
e9a4c1f03019 Minor clarifications for search-forward and set-match-data.
Richard M. Stallman <rms@gnu.org>
parents: 39166
diff changeset
1461 @code{match-data}. (More precisely, anything that has the same format
e9a4c1f03019 Minor clarifications for search-forward and set-match-data.
Richard M. Stallman <rms@gnu.org>
parents: 39166
diff changeset
1462 will work.)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1463
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1464 If @var{match-list} refers to a buffer that doesn't exist, you don't get
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1465 an error; that sets the match data in a meaningless but harmless way.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1466
63153
286783f742e6 (Entire Match Data): Explain new `reseat' argument to
Kim F. Storm <storm@cua.dk>
parents: 63135
diff changeset
1467 If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
63663
c4d74e911908 (Entire Match Data): Remove evaporate option for
Kim F. Storm <storm@cua.dk>
parents: 63583
diff changeset
1468 are reseated to point to nowhere.
63153
286783f742e6 (Entire Match Data): Explain new `reseat' argument to
Kim F. Storm <storm@cua.dk>
parents: 63135
diff changeset
1469
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1470 @findex store-match-data
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1471 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1472 @end defun
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1473
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1474 @node Saving Match Data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1475 @subsection Saving and Restoring the Match Data
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1476
10038
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1477 When you call a function that may do a search, you may need to save
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1478 and restore the match data around that call, if you want to preserve the
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1479 match data from an earlier search for later use. Here is an example
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1480 that shows the problem that arises if you fail to save the match data:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1481
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1482 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1483 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1484 (re-search-forward "The \\(cat \\)")
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1485 @result{} 48
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1486 (foo) ; @r{Perhaps @code{foo} does}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1487 ; @r{more searching.}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1488 (match-end 0)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1489 @result{} 61 ; @r{Unexpected result---not 48!}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1490 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1491 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1492
10038
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1493 You can save and restore the match data with @code{save-match-data}:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1494
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1495 @defmac save-match-data body@dots{}
22252
40089afa2b1d *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 22138
diff changeset
1496 This macro executes @var{body}, saving and restoring the match
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1497 data around it. The return value is the value of the last form in
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1498 @var{body}.
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1499 @end defmac
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1500
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1501 You could use @code{set-match-data} together with @code{match-data} to
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1502 imitate the effect of the special form @code{save-match-data}. Here is
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1503 how:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1504
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1505 @example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1506 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1507 (let ((data (match-data)))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1508 (unwind-protect
21007
66d807bdc5b4 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 17886
diff changeset
1509 @dots{} ; @r{Ok to change the original match data.}
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1510 (set-match-data data)))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1511 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1512 @end example
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1513
10038
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1514 Emacs automatically saves and restores the match data when it runs
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1515 process filter functions (@pxref{Filter Functions}) and process
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1516 sentinels (@pxref{Sentinels}).
6b8e51b286c6 Filters and sentinels now save match data themselves.
Richard M. Stallman <rms@gnu.org>
parents: 8469
diff changeset
1517
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1518 @ignore
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1519 Here is a function which restores the match data provided the buffer
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1520 associated with it still exists.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1521
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1522 @smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1523 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1524 (defun restore-match-data (data)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1525 @c It is incorrect to split the first line of a doc string.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1526 @c If there's a problem here, it should be solved in some other way.
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1527 "Restore the match data DATA unless the buffer is missing."
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1528 (catch 'foo
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1529 (let ((d data))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1530 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1531 (while d
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1532 (and (car d)
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1533 (null (marker-buffer (car d)))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1534 @group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1535 ;; @file{match-data} @r{buffer is deleted.}
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1536 (throw 'foo nil))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1537 (setq d (cdr d)))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1538 (set-match-data data))))
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1539 @end group
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1540 @end smallexample
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1541 @end ignore
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1542
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1543 @node Search and Replace
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1544 @section Search and Replace
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1545 @cindex replacement
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1546
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1547 If you want to find all matches for a regexp in part of the buffer,
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1548 and replace them, the best way is to write an explicit loop using
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1549 @code{re-search-forward} and @code{replace-match}, like this:
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1550
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1551 @example
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1552 (while (re-search-forward "foo[ \t]+bar" nil t)
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1553 (replace-match "foobar"))
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1554 @end example
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1555
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1556 @noindent
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1557 @xref{Replacing Match,, Replacing the Text that Matched}, for a
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1558 description of @code{replace-match}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1559
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1560 However, replacing matches in a string is more complex, especially
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1561 if you want to do it efficiently. So Emacs provides a function to do
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1562 this.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1563
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1564 @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1565 This function copies @var{string} and searches it for matches for
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1566 @var{regexp}, and replaces them with @var{rep}. It returns the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1567 modified copy. If @var{start} is non-@code{nil}, the search for
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1568 matches starts at that index in @var{string}, so matches starting
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1569 before that index are not changed.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1570
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1571 This function uses @code{replace-match} to do the replacement, and it
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1572 passes the optional arguments @var{fixedcase}, @var{literal} and
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1573 @var{subexp} along to @code{replace-match}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1574
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1575 Instead of a string, @var{rep} can be a function. In that case,
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1576 @code{replace-regexp-in-string} calls @var{rep} for each match,
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1577 passing the text of the match as its sole argument. It collects the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1578 value @var{rep} returns and passes that to @code{replace-match} as the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1579 replacement string. The match-data at this point are the result
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1580 of matching @var{regexp} against a substring of @var{string}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1581 @end defun
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1582
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1583 If you want to write a command along the lines of @code{query-replace},
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1584 you can use @code{perform-replace} to do the work.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1585
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1586 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1587 This function is the guts of @code{query-replace} and related
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1588 commands. It searches for occurrences of @var{from-string} in the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1589 text between positions @var{start} and @var{end} and replaces some or
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1590 all of them. If @var{start} is @code{nil} (or omitted), point is used
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1591 instead, and the end of the buffer's accessible portion is used for
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1592 @var{end}.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1593
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1594 If @var{query-flag} is @code{nil}, it replaces all
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1595 occurrences; otherwise, it asks the user what to do about each one.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1596
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1597 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1598 considered a regular expression; otherwise, it must match literally. If
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1599 @var{delimited-flag} is non-@code{nil}, then only replacements
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1600 surrounded by word boundaries are considered.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1601
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1602 The argument @var{replacements} specifies what to replace occurrences
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1603 with. If it is a string, that string is used. It can also be a list of
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1604 strings, to be used in cyclic order.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1605
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1606 If @var{replacements} is a cons cell, @code{(@var{function}
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1607 . @var{data})}, this means to call @var{function} after each match to
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1608 get the replacement text. This function is called with two arguments:
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1609 @var{data}, and the number of replacements already made.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1610
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1611 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1612 it specifies how many times to use each of the strings in the
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1613 @var{replacements} list before advancing cyclically to the next one.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1614
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1615 If @var{from-string} contains upper-case letters, then
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1616 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1617 it uses the @code{replacements} without altering the case of them.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1618
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1619 Normally, the keymap @code{query-replace-map} defines the possible
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1620 user responses for queries. The argument @var{map}, if
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1621 non-@code{nil}, specifies a keymap to use instead of
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1622 @code{query-replace-map}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1623 @end defun
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1624
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1625 @defvar query-replace-map
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1626 This variable holds a special keymap that defines the valid user
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1627 responses for @code{perform-replace} and the commands that use it, as
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1628 well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1629 in two ways:
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1630
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1631 @itemize @bullet
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1632 @item
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1633 The ``key bindings'' are not commands, just symbols that are meaningful
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1634 to the functions that use this map.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1635
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1636 @item
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1637 Prefix keys are not supported; each key binding must be for a
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1638 single-event key sequence. This is because the functions don't use
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1639 @code{read-key-sequence} to get the input; instead, they read a single
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1640 event and look it up ``by hand.''
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1641 @end itemize
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1642 @end defvar
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1643
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1644 Here are the meaningful ``bindings'' for @code{query-replace-map}.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1645 Several of them are meaningful only for @code{query-replace} and
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1646 friends.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1647
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1648 @table @code
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1649 @item act
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1650 Do take the action being considered---in other words, ``yes.''
8469
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1651
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1652 @item skip
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1653 Do not take action for this question---in other words, ``no.''
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1654
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1655 @item exit
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1656 Answer this question ``no,'' and give up on the entire series of
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1657 questions, assuming that the answers will be ``no.''
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1658
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1659 @item act-and-exit
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1660 Answer this question ``yes,'' and give up on the entire series of
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1661 questions, assuming that subsequent answers will be ``no.''
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1662
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1663 @item act-and-show
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1664 Answer this question ``yes,'' but show the results---don't advance yet
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1665 to the next question.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1666
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1667 @item automatic
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1668 Answer this question and all subsequent questions in the series with
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1669 ``yes,'' without further user interaction.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1670
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1671 @item backup
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1672 Move back to the previous place that a question was asked about.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1673
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1674 @item edit
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1675 Enter a recursive edit to deal with this question---instead of any
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1676 other action that would normally be taken.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1677
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1678 @item delete-and-edit
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1679 Delete the text being considered, then enter a recursive edit to replace
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1680 it.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1681
65182
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1682 @item recenter
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1683 Redisplay and center the window, then ask the same question again.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1684
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1685 @item quit
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1686 Perform a quit right away. Only @code{y-or-n-p} and related functions
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1687 use this answer.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1688
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1689 @item help
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1690 Display some help, then ask again.
54da3e88d8f6 (Searching and Matching): Move node.
Richard M. Stallman <rms@gnu.org>
parents: 65122
diff changeset
1691 @end table
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1692
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1693 @node Standard Regexps
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1694 @section Standard Regular Expressions Used in Editing
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1695 @cindex regexps used standardly in editing
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1696 @cindex standard regexps used in editing
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1697
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1698 This section describes some variables that hold regular expressions
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1699 used for certain purposes in editing:
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1700
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1701 @defvar page-delimiter
21682
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1702 This is the regular expression describing line-beginnings that separate
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1703 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1704 @code{"^\C-l"}); this matches a line that starts with a formfeed
90da2489c498 *** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents: 21007
diff changeset
1705 character.
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1706 @end defvar
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1707
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1708 The following two regular expressions should @emph{not} assume the
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1709 match always starts at the beginning of a line; they should not use
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1710 @samp{^} to anchor the match. Most often, the paragraph commands do
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1711 check for a match only at the beginning of a line, which means that
12098
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1712 @samp{^} would be superfluous. When there is a nonzero left margin,
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1713 they accept matches that start after the left margin. In that case, a
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1714 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
a6eb5f12b0f3 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 12067
diff changeset
1715 where a left margin is never used.
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1716
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1717 @defvar paragraph-separate
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1718 This is the regular expression for recognizing the beginning of a line
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1719 that separates paragraphs. (If you change this, you may have to
8469
9e44c96dd99d entered into RCS
Richard M. Stallman <rms@gnu.org>
parents: 8427
diff changeset
1720 change @code{paragraph-start} also.) The default value is
12067
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1721 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
73dc8205d259 *** empty log message ***
Karl Heuer <kwzh@gnu.org>
parents: 11651
diff changeset
1722 spaces, tabs, and form feeds (after its left margin).
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1723 @end defvar
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1724
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1725 @defvar paragraph-start
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1726 This is the regular expression for recognizing the beginning of a line
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1727 that starts @emph{or} separates paragraphs. The default value is
53568
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1728 @w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
a93ed629b104 Various small changes in addition to the following.
Luc Teirlinck <teirllm@auburn.edu>
parents: 52978
diff changeset
1729 whitespace or starting with a form feed (after its left margin).
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1730 @end defvar
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1731
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1732 @defvar sentence-end
57403
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1733 If non-@code{nil}, the value should be a regular expression describing
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1734 the end of a sentence, including the whitespace following the
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1735 sentence. (All paragraph boundaries also end sentences, regardless.)
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1736
57403
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1737 If the value is @code{nil}, the default, then the function
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1738 @code{sentence-end} has to construct the regexp. That is why you
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1739 should always call the function @code{sentence-end} to obtain the
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1740 regexp to be used to recognize the end of a sentence.
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1741 @end defvar
6552
3b84ed22f747 Initial revision
Richard M. Stallman <rms@gnu.org>
parents:
diff changeset
1742
57403
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1743 @defun sentence-end
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1744 This function returns the value of the variable @code{sentence-end},
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1745 if non-@code{nil}. Otherwise it returns a default value based on the
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1746 values of the variables @code{sentence-end-double-space}
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1747 (@pxref{Definition of sentence-end-double-space}),
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1748 @code{sentence-end-without-period} and
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1749 @code{sentence-end-without-space}.
5353c1a56ee3 (Regexp Example): Update description of how Emacs currently recognizes
Luc Teirlinck <teirllm@auburn.edu>
parents: 57252
diff changeset
1750 @end defun
52401
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49959
diff changeset
1751
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49959
diff changeset
1752 @ignore
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49959
diff changeset
1753 arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f
695cf19ef79e Add arch taglines
Miles Bader <miles@gnu.org>
parents: 49959
diff changeset
1754 @end ignore