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