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