2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
4 @c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
5 @c Free Software Foundation, Inc.
6 @c See the file elisp.texi for copying conditions.
7 @setfilename ../../info/searching
8 @node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
9 @chapter Searching and Matching
12 GNU Emacs provides two ways to search through a buffer for specified
13 text: exact string searches and regular expression searches. After a
14 regular expression search, you can examine the @dfn{match data} to
15 determine which text matched the whole regular expression or various
19 * String Search:: Search for an exact match.
20 * Searching and Case:: Case-independent or case-significant searching.
21 * Regular Expressions:: Describing classes of strings.
22 * Regexp Search:: Searching for a match for a regexp.
23 * POSIX Regexps:: Searching POSIX-style for the longest match.
24 * Match Data:: Finding out which part of the text matched,
25 after a string or regexp search.
26 * Search and Replace:: Commands that loop, searching and replacing.
27 * Standard Regexps:: Useful regexps for finding sentences, pages,...
30 The @samp{skip-chars@dots{}} functions also perform a kind of searching.
31 @xref{Skipping Characters}. To search for changes in character
32 properties, see @ref{Property Search}.
35 @section Searching for Strings
38 These are the primitive functions for searching through the text in a
39 buffer. They are meant for use in programs, but you may call them
40 interactively. If you do so, they prompt for the search string; the
41 arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
44 These search functions convert the search string to multibyte if the
45 buffer is multibyte; they convert the search string to unibyte if the
46 buffer is unibyte. @xref{Text Representations}.
48 @deffn Command search-forward string &optional limit noerror repeat
49 This function searches forward from point for an exact match for
50 @var{string}. If successful, it sets point to the end of the occurrence
51 found, and returns the new value of point. If no match is found, the
52 value and side effects depend on @var{noerror} (see below).
55 In the following example, point is initially at the beginning of the
56 line. Then @code{(search-forward "fox")} moves point after the last
61 ---------- Buffer: foo ----------
62 @point{}The quick brown fox jumped over the lazy dog.
63 ---------- Buffer: foo ----------
67 (search-forward "fox")
70 ---------- Buffer: foo ----------
71 The quick brown fox@point{} jumped over the lazy dog.
72 ---------- Buffer: foo ----------
76 The argument @var{limit} specifies the upper bound to the search. (It
77 must be a position in the current buffer.) No match extending after
78 that position is accepted. If @var{limit} is omitted or @code{nil}, it
79 defaults to the end of the accessible portion of the buffer.
82 What happens when the search fails depends on the value of
83 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
84 error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
85 returns @code{nil} and does nothing. If @var{noerror} is neither
86 @code{nil} nor @code{t}, then @code{search-forward} moves point to the
87 upper bound and returns @code{nil}. (It would be more consistent now to
88 return the new position of point in that case, but some existing
89 programs may depend on a value of @code{nil}.)
91 The argument @var{noerror} only affects valid searches which fail to
92 find a match. Invalid arguments cause errors regardless of
95 If @var{repeat} is supplied (it must be a positive number), then the
96 search is repeated that many times (each time starting at the end of the
97 previous time's match). If these successive searches succeed, the
98 function succeeds, moving point and returning its new value. Otherwise
99 the search fails, with results depending on the value of
100 @var{noerror}, as described above.
103 @deffn Command search-backward string &optional limit noerror repeat
104 This function searches backward from point for @var{string}. It is
105 just like @code{search-forward} except that it searches backwards and
106 leaves point at the beginning of the match.
109 @deffn Command word-search-forward string &optional limit noerror repeat
110 This function searches forward from point for a ``word'' match for
111 @var{string}. If it finds a match, it sets point to the end of the
112 match found, and returns the new value of point.
114 Word matching regards @var{string} as a sequence of words, disregarding
115 punctuation that separates them. It searches the buffer for the same
116 sequence of words. Each word must be distinct in the buffer (searching
117 for the word @samp{ball} does not match the word @samp{balls}), but the
118 details of punctuation and spacing are ignored (searching for @samp{ball
119 boy} does match @samp{ball. Boy!}).
121 In this example, point is initially at the beginning of the buffer; the
122 search leaves it between the @samp{y} and the @samp{!}.
126 ---------- Buffer: foo ----------
127 @point{}He said "Please! Find
129 ---------- Buffer: foo ----------
133 (word-search-forward "Please find the ball, boy.")
136 ---------- Buffer: foo ----------
137 He said "Please! Find
138 the ball boy@point{}!"
139 ---------- Buffer: foo ----------
143 If @var{limit} is non-@code{nil}, it must be a position in the current
144 buffer; it specifies the upper bound to the search. The match found
145 must not extend after that position.
147 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
148 an error if the search fails. If @var{noerror} is @code{t}, then it
149 returns @code{nil} instead of signaling an error. If @var{noerror} is
150 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
151 end of the accessible portion of the buffer) and returns @code{nil}.
153 If @var{repeat} is non-@code{nil}, then the search is repeated that many
154 times. Point is positioned at the end of the last match.
157 @deffn Command word-search-forward-lax string &optional limit noerror repeat
158 This command is identical to @code{word-search-forward}, except that
159 the end of @code{string} need not match a word boundary unless it ends
160 in whitespace. For instance, searching for @samp{ball boy} matches
161 @samp{ball boyee}, but does not match @samp{aball boy}.
164 @deffn Command word-search-backward string &optional limit noerror repeat
165 This function searches backward from point for a word match to
166 @var{string}. This function is just like @code{word-search-forward}
167 except that it searches backward and normally leaves point at the
168 beginning of the match.
171 @deffn Command word-search-backward-lax string &optional limit noerror repeat
172 This command is identical to @code{word-search-backward}, except that
173 the end of @code{string} need not match a word boundary unless it ends
177 @node Searching and Case
178 @section Searching and Case
179 @cindex searching and case
181 By default, searches in Emacs ignore the case of the text they are
182 searching through; if you specify searching for @samp{FOO}, then
183 @samp{Foo} or @samp{foo} is also considered a match. This applies to
184 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
185 @samp{A} or @samp{b} or @samp{B}.
187 If you do not want this feature, set the variable
188 @code{case-fold-search} to @code{nil}. Then all letters must match
189 exactly, including case. This is a buffer-local variable; altering the
190 variable affects only the current buffer. (@xref{Intro to
191 Buffer-Local}.) Alternatively, you may change the default value of
192 @code{case-fold-search}.
194 Note that the user-level incremental search feature handles case
195 distinctions differently. When the search string contains only lower
196 case letters, the search ignores case, but when the search string
197 contains one or more upper case letters, the search becomes
198 case-sensitive. But this has nothing to do with the searching
199 functions used in Lisp code.
201 @defopt case-fold-search
202 This buffer-local variable determines whether searches should ignore
203 case. If the variable is @code{nil} they do not ignore case; otherwise
208 This variable determines whether the higher level replacement
209 functions should preserve case. If the variable is @code{nil}, that
210 means to use the replacement text verbatim. A non-@code{nil} value
211 means to convert the case of the replacement text according to the
214 This variable is used by passing it as an argument to the function
215 @code{replace-match}. @xref{Replacing Match}.
218 @node Regular Expressions
219 @section Regular Expressions
220 @cindex regular expression
223 A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that
224 denotes a (possibly infinite) set of strings. Searching for matches for
225 a regexp is a very powerful operation. This section explains how to write
226 regexps; the following section says how to search for them.
229 @cindex regular expressions, developing
230 For convenient interactive development of regular expressions, you
231 can use the @kbd{M-x re-builder} command. It provides a convenient
232 interface for creating regular expressions, by giving immediate visual
233 feedback in a separate buffer. As you edit the regexp, all its
234 matches in the target buffer are highlighted. Each parenthesized
235 sub-expression of the regexp is shown in a distinct face, which makes
236 it easier to verify even very complex regexps.
239 * Syntax of Regexps:: Rules for writing regular expressions.
240 * Regexp Example:: Illustrates regular expression syntax.
241 * Regexp Functions:: Functions for operating on regular expressions.
244 @node Syntax of Regexps
245 @subsection Syntax of Regular Expressions
247 Regular expressions have a syntax in which a few characters are
248 special constructs and the rest are @dfn{ordinary}. An ordinary
249 character is a simple regular expression that matches that character
250 and nothing else. The special characters are @samp{.}, @samp{*},
251 @samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
252 special characters will be defined in the future. The character
253 @samp{]} is special if it ends a character alternative (see later).
254 The character @samp{-} is special inside a character alternative. A
255 @samp{[:} and balancing @samp{:]} enclose a character class inside a
256 character alternative. Any other character appearing in a regular
257 expression is ordinary, unless a @samp{\} precedes it.
259 For example, @samp{f} is not a special character, so it is ordinary, and
260 therefore @samp{f} is a regular expression that matches the string
261 @samp{f} and no other string. (It does @emph{not} match the string
262 @samp{fg}, but it does match a @emph{part} of that string.) Likewise,
263 @samp{o} is a regular expression that matches only @samp{o}.@refill
265 Any two regular expressions @var{a} and @var{b} can be concatenated. The
266 result is a regular expression that matches a string if @var{a} matches
267 some amount of the beginning of that string and @var{b} matches the rest of
270 As a simple example, we can concatenate the regular expressions @samp{f}
271 and @samp{o} to get the regular expression @samp{fo}, which matches only
272 the string @samp{fo}. Still trivial. To do something more powerful, you
273 need to use one of the special regular expression constructs.
276 * Regexp Special:: Special characters in regular expressions.
277 * Char Classes:: Character classes used in regular expressions.
278 * Regexp Backslash:: Backslash-sequences in regular expressions.
282 @subsubsection Special Characters in Regular Expressions
284 Here is a list of the characters that are special in a regular
289 @item @samp{.}@: @r{(Period)}
290 @cindex @samp{.} in regexp
291 is a special character that matches any single character except a newline.
292 Using concatenation, we can make regular expressions like @samp{a.b}, which
293 matches any three-character string that begins with @samp{a} and ends with
297 @cindex @samp{*} in regexp
298 is not a construct by itself; it is a postfix operator that means to
299 match the preceding regular expression repetitively as many times as
300 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
303 @samp{*} always applies to the @emph{smallest} possible preceding
304 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
305 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
307 The matcher processes a @samp{*} construct by matching, immediately, as
308 many repetitions as can be found. Then it continues with the rest of
309 the pattern. If that fails, backtracking occurs, discarding some of the
310 matches of the @samp{*}-modified construct in the hope that that will
311 make it possible to match the rest of the pattern. For example, in
312 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
313 first tries to match all three @samp{a}s; but the rest of the pattern is
314 @samp{ar} and there is only @samp{r} left to match, so this try fails.
315 The next alternative is for @samp{a*} to match only two @samp{a}s. With
316 this choice, the rest of the regexp matches successfully.
318 @strong{Warning:} Nested repetition operators can run for an
319 indefinitely long time, if they lead to ambiguous matching. For
320 example, trying to match the regular expression @samp{\(x+y*\)*a}
321 against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could
322 take hours before it ultimately fails. Emacs must try each way of
323 grouping the @samp{x}s before concluding that none of them can work.
324 Even worse, @samp{\(x*\)*} can match the null string in infinitely
325 many ways, so it causes an infinite loop. To avoid these problems,
326 check nested repetitions carefully, to make sure that they do not
327 cause combinatorial explosions in backtracking.
330 @cindex @samp{+} in regexp
331 is a postfix operator, similar to @samp{*} except that it must match
332 the preceding expression at least once. So, for example, @samp{ca+r}
333 matches the strings @samp{car} and @samp{caaaar} but not the string
334 @samp{cr}, whereas @samp{ca*r} matches all three strings.
337 @cindex @samp{?} in regexp
338 is a postfix operator, similar to @samp{*} except that it must match the
339 preceding expression either once or not at all. For example,
340 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
342 @item @samp{*?}, @samp{+?}, @samp{??}
343 @cindex non-greedy repetition characters in regexp
344 These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
345 and @samp{?}. Where those operators match the largest possible
346 substring (consistent with matching the entire containing expression),
347 the non-greedy variants match the smallest possible substring
348 (consistent with matching the entire containing expression).
350 For example, the regular expression @samp{c[ad]*a} when applied to the
351 string @samp{cdaaada} matches the whole string; but the regular
352 expression @samp{c[ad]*?a}, applied to that same string, matches just
353 @samp{cda}. (The smallest possible match here for @samp{[ad]*?} that
354 permits the whole expression to match is @samp{d}.)
356 @item @samp{[ @dots{} ]}
357 @cindex character alternative (in regexp)
358 @cindex @samp{[} in regexp
359 @cindex @samp{]} in regexp
360 is a @dfn{character alternative}, which begins with @samp{[} and is
361 terminated by @samp{]}. In the simplest case, the characters between
362 the two brackets are what this character alternative can match.
364 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
365 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
366 (including the empty string). It follows that @samp{c[ad]*r}
367 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
369 You can also include character ranges in a character alternative, by
370 writing the starting and ending characters with a @samp{-} between them.
371 Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
372 Ranges may be intermixed freely with individual characters, as in
373 @samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
374 or @samp{$}, @samp{%} or period.
376 Note that the usual regexp special characters are not special inside a
377 character alternative. A completely different set of characters is
378 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
380 To include a @samp{]} in a character alternative, you must make it the
381 first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
382 To include a @samp{-}, write @samp{-} as the first or last character of
383 the character alternative, or put it after a range. Thus, @samp{[]-]}
384 matches both @samp{]} and @samp{-}.
386 To include @samp{^} in a character alternative, put it anywhere but at
389 If a range starts with a unibyte character @var{c} and ends with a
390 multibyte character @var{c2}, the range is divided into two parts: one
391 is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
392 @var{c1} is the first character of the charset to which @var{c2}
395 A character alternative can also specify named character classes
396 (@pxref{Char Classes}). This is a POSIX feature whose syntax is
397 @samp{[:@var{class}:]}. Using a character class is equivalent to
398 mentioning each of the characters in that class; but the latter is not
399 feasible in practice, since some classes include thousands of
400 different characters.
402 @item @samp{[^ @dots{} ]}
403 @cindex @samp{^} in regexp
404 @samp{[^} begins a @dfn{complemented character alternative}. This
405 matches any character except the ones specified. Thus,
406 @samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
409 @samp{^} is not special in a character alternative unless it is the first
410 character. The character following the @samp{^} is treated as if it
411 were first (in other words, @samp{-} and @samp{]} are not special there).
413 A complemented character alternative can match a newline, unless newline is
414 mentioned as one of the characters not to match. This is in contrast to
415 the handling of regexps in programs such as @code{grep}.
417 You can specify named character classes, just like in character
418 alternatives. For instance, @samp{[^[:ascii:]]} matches any
419 non-@acronym{ASCII} character. @xref{Char Classes}.
422 @cindex beginning of line in regexp
423 When matching a buffer, @samp{^} matches the empty string, but only at the
424 beginning of a line in the text being matched (or the beginning of the
425 accessible portion of the buffer). Otherwise it fails to match
426 anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the
429 When matching a string instead of a buffer, @samp{^} matches at the
430 beginning of the string or after a newline character.
432 For historical compatibility reasons, @samp{^} can be used only at the
433 beginning of the regular expression, or after @samp{\(}, @samp{\(?:}
437 @cindex @samp{$} in regexp
438 @cindex end of line in regexp
439 is similar to @samp{^} but matches only at the end of a line (or the
440 end of the accessible portion of the buffer). Thus, @samp{x+$}
441 matches a string of one @samp{x} or more at the end of a line.
443 When matching a string instead of a buffer, @samp{$} matches at the end
444 of the string or before a newline character.
446 For historical compatibility reasons, @samp{$} can be used only at the
447 end of the regular expression, or before @samp{\)} or @samp{\|}.
450 @cindex @samp{\} in regexp
451 has two functions: it quotes the special characters (including
452 @samp{\}), and it introduces additional special constructs.
454 Because @samp{\} quotes special characters, @samp{\$} is a regular
455 expression that matches only @samp{$}, and @samp{\[} is a regular
456 expression that matches only @samp{[}, and so on.
458 Note that @samp{\} also has special meaning in the read syntax of Lisp
459 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
460 example, the regular expression that matches the @samp{\} character is
461 @samp{\\}. To write a Lisp string that contains the characters
462 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
463 @samp{\}. Therefore, the read syntax for a regular expression matching
464 @samp{\} is @code{"\\\\"}.@refill
467 @strong{Please note:} For historical compatibility, special characters
468 are treated as ordinary ones if they are in contexts where their special
469 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
470 ordinary since there is no preceding expression on which the @samp{*}
471 can act. It is poor practice to depend on this behavior; quote the
472 special character anyway, regardless of where it appears.@refill
474 As a @samp{\} is not special inside a character alternative, it can
475 never remove the special meaning of @samp{-} or @samp{]}. So you
476 should not quote these characters when they have no special meaning
477 either. This would not clarify anything, since backslashes can
478 legitimately precede these characters where they @emph{have} special
479 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
480 which matches any single character except a backslash.
482 In practice, most @samp{]} that occur in regular expressions close a
483 character alternative and hence are special. However, occasionally a
484 regular expression may try to match a complex pattern of literal
485 @samp{[} and @samp{]}. In such situations, it sometimes may be
486 necessary to carefully parse the regexp from the start to determine
487 which square brackets enclose a character alternative. For example,
488 @samp{[^][]]} consists of the complemented character alternative
489 @samp{[^][]} (which matches any single character that is not a square
490 bracket), followed by a literal @samp{]}.
492 The exact rules are that at the beginning of a regexp, @samp{[} is
493 special and @samp{]} not. This lasts until the first unquoted
494 @samp{[}, after which we are in a character alternative; @samp{[} is
495 no longer special (except when it starts a character class) but @samp{]}
496 is special, unless it immediately follows the special @samp{[} or that
497 @samp{[} followed by a @samp{^}. This lasts until the next special
498 @samp{]} that does not end a character class. This ends the character
499 alternative and restores the ordinary syntax of regular expressions;
500 an unquoted @samp{[} is special again and a @samp{]} not.
503 @subsubsection Character Classes
504 @cindex character classes in regexp
506 Here is a table of the classes you can use in a character alternative,
511 This matches any @acronym{ASCII} character (codes 0--127).
513 This matches any letter or digit. (At present, for multibyte
514 characters, it matches anything that has word syntax.)
516 This matches any letter. (At present, for multibyte characters, it
517 matches anything that has word syntax.)
519 This matches space and tab only.
521 This matches any @acronym{ASCII} control character.
523 This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
524 matches any digit, as well as @samp{+} and @samp{-}.
526 This matches graphic characters---everything except @acronym{ASCII} control
527 characters, space, and the delete character.
529 This matches any lower-case letter, as determined by the current case
530 table (@pxref{Case Tables}). If @code{case-fold-search} is
531 non-@code{nil}, this also matches any upper-case letter.
533 This matches any multibyte character (@pxref{Text Representations}).
535 This matches any non-@acronym{ASCII} character.
537 This matches printing characters---everything except @acronym{ASCII} control
538 characters and the delete character.
540 This matches any punctuation character. (At present, for multibyte
541 characters, it matches anything that has non-word syntax.)
543 This matches any character that has whitespace syntax
544 (@pxref{Syntax Class Table}).
546 This matches any unibyte character (@pxref{Text Representations}).
548 This matches any upper-case letter, as determined by the current case
549 table (@pxref{Case Tables}). If @code{case-fold-search} is
550 non-@code{nil}, this also matches any lower-case letter.
552 This matches any character that has word syntax (@pxref{Syntax Class
555 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
556 through @samp{f} and @samp{A} through @samp{F}.
559 @node Regexp Backslash
560 @subsubsection Backslash Constructs in Regular Expressions
562 For the most part, @samp{\} followed by any character matches only
563 that character. However, there are several exceptions: certain
564 two-character sequences starting with @samp{\} that have special
565 meanings. (The character after the @samp{\} in such a sequence is
566 always ordinary when used on its own.) Here is a table of the special
571 @cindex @samp{|} in regexp
572 @cindex regexp alternative
573 specifies an alternative.
574 Two regular expressions @var{a} and @var{b} with @samp{\|} in
575 between form an expression that matches anything that either @var{a} or
576 @var{b} matches.@refill
578 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
579 but no other string.@refill
581 @samp{\|} applies to the largest possible surrounding expressions. Only a
582 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
585 If you need full backtracking capability to handle multiple uses of
586 @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
590 is a postfix operator that repeats the previous pattern exactly @var{m}
591 times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
592 and nothing else. @samp{c[ad]\@{3\@}r} matches string such as
593 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
595 @item \@{@var{m},@var{n}\@}
596 is a more general postfix operator that specifies repetition with a
597 minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m}
598 is omitted, the minimum is 0; if @var{n} is omitted, there is no
601 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
602 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
604 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.@*
605 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.@*
606 @samp{\@{1,\@}} is equivalent to @samp{+}.
609 @cindex @samp{(} in regexp
610 @cindex @samp{)} in regexp
611 @cindex regexp grouping
612 is a grouping construct that serves three purposes:
616 To enclose a set of @samp{\|} alternatives for other operations. Thus,
617 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
621 To enclose a complicated expression for the postfix operators @samp{*},
622 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
623 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
624 number (zero or more) of @samp{na} strings.
627 To record a matched substring for future reference with
628 @samp{\@var{digit}} (see below).
631 This last application is not a consequence of the idea of a
632 parenthetical grouping; it is a separate feature that was assigned as a
633 second meaning to the same @samp{\( @dots{} \)} construct because, in
634 practice, there was usually no conflict between the two meanings. But
635 occasionally there is a conflict, and that led to the introduction of
638 @item \(?: @dots{} \)
640 @cindex non-capturing group
641 @cindex unnumbered group
642 @cindex @samp{(?:} in regexp
643 is the @dfn{shy group} construct. A shy group serves the first two
644 purposes of an ordinary group (controlling the nesting of other
645 operators), but it does not get a number, so you cannot refer back to
646 its value with @samp{\@var{digit}}. Shy groups are particularly
647 useful for mechanically-constructed regular expressions, because they
648 can be added automatically without altering the numbering of ordinary,
651 Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered
654 @item \(?@var{num}: @dots{} \)
655 is the @dfn{explicitly numbered group} construct. Normal groups get
656 their number implicitly, based on their position, which can be
657 inconvenient. This construct allows you to force a particular group
658 number. There is no particular restriction on the numbering,
659 e.g.@: you can have several groups with the same number in which case
660 the last one to match (i.e.@: the rightmost match) will win.
661 Implicitly numbered groups always get the smallest integer larger than
662 the one of any previous group.
665 matches the same text that matched the @var{digit}th occurrence of a
666 grouping (@samp{\( @dots{} \)}) construct.
668 In other words, after the end of a group, the matcher remembers the
669 beginning and end of the text matched by that group. Later on in the
670 regular expression you can use @samp{\} followed by @var{digit} to
671 match that same text, whatever it may have been.
673 The strings matching the first nine grouping constructs appearing in
674 the entire regular expression passed to a search or matching function
675 are assigned numbers 1 through 9 in the order that the open
676 parentheses appear in the regular expression. So you can use
677 @samp{\1} through @samp{\9} to refer to the text matched by the
678 corresponding grouping constructs.
680 For example, @samp{\(.*\)\1} matches any newline-free string that is
681 composed of two identical halves. The @samp{\(.*\)} matches the first
682 half, which may be anything, but the @samp{\1} that follows must match
685 If a @samp{\( @dots{} \)} construct matches more than once (which can
686 happen, for instance, if it is followed by @samp{*}), only the last
689 If a particular grouping construct in the regular expression was never
690 matched---for instance, if it appears inside of an alternative that
691 wasn't used, or inside of a repetition that repeated zero times---then
692 the corresponding @samp{\@var{digit}} construct never matches
693 anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2}
694 cannot match @samp{lose}: the second alternative inside the larger
695 group matches it, but then @samp{\2} is undefined and can't match
696 anything. But it can match @samp{foobb}, because the first
697 alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
700 @cindex @samp{\w} in regexp
701 matches any word-constituent character. The editor syntax table
702 determines which characters these are. @xref{Syntax Tables}.
705 @cindex @samp{\W} in regexp
706 matches any character that is not a word constituent.
709 @cindex @samp{\s} in regexp
710 matches any character whose syntax is @var{code}. Here @var{code} is a
711 character that represents a syntax code: thus, @samp{w} for word
712 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
713 etc. To represent whitespace syntax, use either @samp{-} or a space
714 character. @xref{Syntax Class Table}, for a list of syntax codes and
715 the characters that stand for them.
718 @cindex @samp{\S} in regexp
719 matches any character whose syntax is not @var{code}.
722 matches any character whose category is @var{c}. Here @var{c} is a
723 character that represents a category: thus, @samp{c} for Chinese
724 characters or @samp{g} for Greek characters in the standard category
728 matches any character whose category is not @var{c}.
731 The following regular expression constructs match the empty string---that is,
732 they don't use up any characters---but whether they match depends on the
733 context. For all, the beginning and end of the accessible portion of
734 the buffer are treated as if they were the actual beginning and end of
739 @cindex @samp{\`} in regexp
740 matches the empty string, but only at the beginning
741 of the buffer or string being matched against.
744 @cindex @samp{\'} in regexp
745 matches the empty string, but only at the end of
746 the buffer or string being matched against.
749 @cindex @samp{\=} in regexp
750 matches the empty string, but only at point.
751 (This construct is not defined when matching against a string.)
754 @cindex @samp{\b} in regexp
755 matches the empty string, but only at the beginning or
756 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
757 @samp{foo} as a separate word. @samp{\bballs?\b} matches
758 @samp{ball} or @samp{balls} as a separate word.@refill
760 @samp{\b} matches at the beginning or end of the buffer (or string)
761 regardless of what text appears next to it.
764 @cindex @samp{\B} in regexp
765 matches the empty string, but @emph{not} at the beginning or
766 end of a word, nor at the beginning or end of the buffer (or string).
769 @cindex @samp{\<} in regexp
770 matches the empty string, but only at the beginning of a word.
771 @samp{\<} matches at the beginning of the buffer (or string) only if a
772 word-constituent character follows.
775 @cindex @samp{\>} in regexp
776 matches the empty string, but only at the end of a word. @samp{\>}
777 matches at the end of the buffer (or string) only if the contents end
778 with a word-constituent character.
781 @cindex @samp{\_<} in regexp
782 matches the empty string, but only at the beginning of a symbol. A
783 symbol is a sequence of one or more word or symbol constituent
784 characters. @samp{\_<} matches at the beginning of the buffer (or
785 string) only if a symbol-constituent character follows.
788 @cindex @samp{\_>} in regexp
789 matches the empty string, but only at the end of a symbol. @samp{\_>}
790 matches at the end of the buffer (or string) only if the contents end
791 with a symbol-constituent character.
794 @kindex invalid-regexp
795 Not every string is a valid regular expression. For example, a string
796 that ends inside a character alternative without terminating @samp{]}
797 is invalid, and so is a string that ends with a single @samp{\}. If
798 an invalid regular expression is passed to any of the search functions,
799 an @code{invalid-regexp} error is signaled.
802 @comment node-name, next, previous, up
803 @subsection Complex Regexp Example
805 Here is a complicated regexp which was formerly used by Emacs to
806 recognize the end of a sentence together with any whitespace that
807 follows. (Nowadays Emacs uses a similar but more complex default
808 regexp constructed by the function @code{sentence-end}.
809 @xref{Standard Regexps}.)
811 First, we show the regexp as a string in Lisp syntax to distinguish
812 spaces from tab characters. The string constant begins and ends with a
813 double-quote. @samp{\"} stands for a double-quote as part of the
814 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
815 tab and @samp{\n} for a newline.
818 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
822 In contrast, if you evaluate this string, you will see the following:
826 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
827 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
833 In this output, tab and newline appear as themselves.
835 This regular expression contains four parts in succession and can be
836 deciphered as follows:
840 The first part of the pattern is a character alternative that matches
841 any one of three characters: period, question mark, and exclamation
842 mark. The match must begin with one of these three characters. (This
843 is one point where the new default regexp used by Emacs differs from
844 the old. The new value also allows some non-@acronym{ASCII}
845 characters that end a sentence without any following whitespace.)
848 The second part of the pattern matches any closing braces and quotation
849 marks, zero or more of them, that may follow the period, question mark
850 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
851 a string. The @samp{*} at the end indicates that the immediately
852 preceding regular expression (a character alternative, in this case) may be
853 repeated zero or more times.
855 @item \\($\\|@ $\\|\t\\|@ @ \\)
856 The third part of the pattern matches the whitespace that follows the
857 end of a sentence: the end of a line (optionally with a space), or a
858 tab, or two spaces. The double backslashes mark the parentheses and
859 vertical bars as regular expression syntax; the parentheses delimit a
860 group and the vertical bars separate alternatives. The dollar sign is
861 used to match the end of a line.
864 Finally, the last part of the pattern matches any additional whitespace
865 beyond the minimum needed to end a sentence.
868 @node Regexp Functions
869 @subsection Regular Expression Functions
871 These functions operate on regular expressions.
873 @defun regexp-quote string
874 This function returns a regular expression whose only exact match is
875 @var{string}. Using this regular expression in @code{looking-at} will
876 succeed only if the next characters in the buffer are @var{string};
877 using it in a search function will succeed if the text being searched
878 contains @var{string}.
880 This allows you to request an exact string match or search when calling
881 a function that wants a regular expression.
885 (regexp-quote "^The cat$")
886 @result{} "\\^The cat\\$"
890 One use of @code{regexp-quote} is to combine an exact string match with
891 context described as a regular expression. For example, this searches
892 for the string that is the value of @var{string}, surrounded by
898 (concat "\\s-" (regexp-quote string) "\\s-"))
903 @defun regexp-opt strings &optional paren
904 This function returns an efficient regular expression that will match
905 any of the strings in the list @var{strings}. This is useful when you
906 need to make matching or searching as fast as possible---for example,
909 If the optional argument @var{paren} is non-@code{nil}, then the
910 returned regular expression is always enclosed by at least one
911 parentheses-grouping construct. If @var{paren} is @code{words}, then
912 that construct is additionally surrounded by @samp{\<} and @samp{\>};
913 alternatively, if @var{paren} is @code{symbols}, then that construct
914 is additionally surrounded by @samp{\_<} and @samp{\_>}
915 (@code{symbols} is often appropriate when matching
916 programming-language keywords and the like).
918 This simplified definition of @code{regexp-opt} produces a
919 regular expression which is equivalent to the actual value
920 (but not as efficient):
923 (defun regexp-opt (strings paren)
924 (let ((open-paren (if paren "\\(" ""))
925 (close-paren (if paren "\\)" "")))
927 (mapconcat 'regexp-quote strings "\\|")
932 @defun regexp-opt-depth regexp
933 This function returns the total number of grouping constructs
934 (parenthesized expressions) in @var{regexp}. This does not include
935 shy groups (@pxref{Regexp Backslash}).
939 @section Regular Expression Searching
940 @cindex regular expression searching
941 @cindex regexp searching
942 @cindex searching for regexp
944 In GNU Emacs, you can search for the next match for a regular
945 expression either incrementally or not. For incremental search
946 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
947 The GNU Emacs Manual}. Here we describe only the search functions
948 useful in programs. The principal one is @code{re-search-forward}.
950 These search functions convert the regular expression to multibyte if
951 the buffer is multibyte; they convert the regular expression to unibyte
952 if the buffer is unibyte. @xref{Text Representations}.
954 @deffn Command re-search-forward regexp &optional limit noerror repeat
955 This function searches forward in the current buffer for a string of
956 text that is matched by the regular expression @var{regexp}. The
957 function skips over any amount of text that is not matched by
958 @var{regexp}, and leaves point at the end of the first match found.
959 It returns the new value of point.
961 If @var{limit} is non-@code{nil}, it must be a position in the current
962 buffer. It specifies the upper bound to the search. No match
963 extending after that position is accepted.
965 If @var{repeat} is supplied, it must be a positive number; the search
966 is repeated that many times; each repetition starts at the end of the
967 previous match. If all these successive searches succeed, the search
968 succeeds, moving point and returning its new value. Otherwise the
969 search fails. What @code{re-search-forward} does when the search
970 fails depends on the value of @var{noerror}:
974 Signal a @code{search-failed} error.
976 Do nothing and return @code{nil}.
978 Move point to @var{limit} (or the end of the accessible portion of the
979 buffer) and return @code{nil}.
982 In the following example, point is initially before the @samp{T}.
983 Evaluating the search call moves point to the end of that line (between
984 the @samp{t} of @samp{hat} and the newline).
988 ---------- Buffer: foo ----------
989 I read "@point{}The cat in the hat
991 ---------- Buffer: foo ----------
995 (re-search-forward "[a-z]+" nil t 5)
998 ---------- Buffer: foo ----------
999 I read "The cat in the hat@point{}
1001 ---------- Buffer: foo ----------
1006 @deffn Command re-search-backward regexp &optional limit noerror repeat
1007 This function searches backward in the current buffer for a string of
1008 text that is matched by the regular expression @var{regexp}, leaving
1009 point at the beginning of the first text found.
1011 This function is analogous to @code{re-search-forward}, but they are not
1012 simple mirror images. @code{re-search-forward} finds the match whose
1013 beginning is as close as possible to the starting point. If
1014 @code{re-search-backward} were a perfect mirror image, it would find the
1015 match whose end is as close as possible. However, in fact it finds the
1016 match whose beginning is as close as possible (and yet ends before the
1017 starting point). The reason for this is that matching a regular
1018 expression at a given spot always works from beginning to end, and
1019 starts at a specified beginning position.
1021 A true mirror-image of @code{re-search-forward} would require a special
1022 feature for matching regular expressions from end to beginning. It's
1023 not worth the trouble of implementing that.
1026 @defun string-match regexp string &optional start
1027 This function returns the index of the start of the first match for
1028 the regular expression @var{regexp} in @var{string}, or @code{nil} if
1029 there is no match. If @var{start} is non-@code{nil}, the search starts
1030 at that index in @var{string}.
1037 "quick" "The quick brown fox jumped quickly.")
1042 "quick" "The quick brown fox jumped quickly." 8)
1048 The index of the first character of the
1049 string is 0, the index of the second character is 1, and so on.
1051 After this function returns, the index of the first character beyond
1052 the match is available as @code{(match-end 0)}. @xref{Match Data}.
1057 "quick" "The quick brown fox jumped quickly." 8)
1068 @defun string-match-p regexp string &optional start
1069 This predicate function does what @code{string-match} does, but it
1070 avoids modifying the match data.
1073 @defun looking-at regexp
1074 This function determines whether the text in the current buffer directly
1075 following point matches the regular expression @var{regexp}. ``Directly
1076 following'' means precisely that: the search is ``anchored'' and it can
1077 succeed only starting with the first character following point. The
1078 result is @code{t} if so, @code{nil} otherwise.
1080 This function does not move point, but it updates the match data, which
1081 you can access using @code{match-beginning} and @code{match-end}.
1082 @xref{Match Data}. If you need to test for a match without modifying
1083 the match data, use @code{looking-at-p}, described below.
1085 In this example, point is located directly before the @samp{T}. If it
1086 were anywhere else, the result would be @code{nil}.
1090 ---------- Buffer: foo ----------
1091 I read "@point{}The cat in the hat
1093 ---------- Buffer: foo ----------
1095 (looking-at "The cat in the hat$")
1101 @defun looking-back regexp &optional limit greedy
1102 This function returns @code{t} if @var{regexp} matches text before
1103 point, ending at point, and @code{nil} otherwise.
1105 Because regular expression matching works only going forward, this is
1106 implemented by searching backwards from point for a match that ends at
1107 point. That can be quite slow if it has to search a long distance.
1108 You can bound the time required by specifying @var{limit}, which says
1109 not to search before @var{limit}. In this case, the match that is
1110 found must begin at or after @var{limit}.
1112 If @var{greedy} is non-@code{nil}, this function extends the match
1113 backwards as far as possible, stopping when a single additional
1114 previous character cannot be part of a match for regexp. When the
1115 match is extended, its starting position is allowed to occur before
1120 ---------- Buffer: foo ----------
1121 I read "@point{}The cat in the hat
1123 ---------- Buffer: foo ----------
1125 (looking-back "read \"" 3)
1127 (looking-back "read \"" 4)
1133 @defun looking-at-p regexp
1134 This predicate function works like @code{looking-at}, but without
1135 updating the match data.
1138 @defvar search-spaces-regexp
1139 If this variable is non-@code{nil}, it should be a regular expression
1140 that says how to search for whitespace. In that case, any group of
1141 spaces in a regular expression being searched for stands for use of
1142 this regular expression. However, spaces inside of constructs such as
1143 @samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
1144 @code{search-spaces-regexp}.
1146 Since this variable affects all regular expression search and match
1147 constructs, you should bind it temporarily for as small as possible
1152 @section POSIX Regular Expression Searching
1154 The usual regular expression functions do backtracking when necessary
1155 to handle the @samp{\|} and repetition constructs, but they continue
1156 this only until they find @emph{some} match. Then they succeed and
1157 report the first match found.
1159 This section describes alternative search functions which perform the
1160 full backtracking specified by the POSIX standard for regular expression
1161 matching. They continue backtracking until they have tried all
1162 possibilities and found all matches, so they can report the longest
1163 match, as required by POSIX. This is much slower, so use these
1164 functions only when you really need the longest match.
1166 The POSIX search and match functions do not properly support the
1167 non-greedy repetition operators (@pxref{Regexp Special, non-greedy}).
1168 This is because POSIX backtracking conflicts with the semantics of
1169 non-greedy repetition.
1171 @deffn Command posix-search-forward regexp &optional limit noerror repeat
1172 This is like @code{re-search-forward} except that it performs the full
1173 backtracking specified by the POSIX standard for regular expression
1177 @deffn Command posix-search-backward regexp &optional limit noerror repeat
1178 This is like @code{re-search-backward} except that it performs the full
1179 backtracking specified by the POSIX standard for regular expression
1183 @defun posix-looking-at regexp
1184 This is like @code{looking-at} except that it performs the full
1185 backtracking specified by the POSIX standard for regular expression
1189 @defun posix-string-match regexp string &optional start
1190 This is like @code{string-match} except that it performs the full
1191 backtracking specified by the POSIX standard for regular expression
1196 @section The Match Data
1199 Emacs keeps track of the start and end positions of the segments of
1200 text found during a search; this is called the @dfn{match data}.
1201 Thanks to the match data, you can search for a complex pattern, such
1202 as a date in a mail message, and then extract parts of the match under
1203 control of the pattern.
1205 Because the match data normally describe the most recent search only,
1206 you must be careful not to do another search inadvertently between the
1207 search you wish to refer back to and the use of the match data. If you
1208 can't avoid another intervening search, you must save and restore the
1209 match data around it, to prevent it from being overwritten.
1212 * Replacing Match:: Replacing a substring that was matched.
1213 * Simple Match Data:: Accessing single items of match data,
1214 such as where a particular subexpression started.
1215 * Entire Match Data:: Accessing the entire match data at once, as a list.
1216 * Saving Match Data:: Saving and restoring the match data.
1219 @node Replacing Match
1220 @subsection Replacing the Text that Matched
1221 @cindex replace matched text
1223 This function replaces all or part of the text matched by the last
1224 search. It works by means of the match data.
1226 @cindex case in replacements
1227 @defun replace-match replacement &optional fixedcase literal string subexp
1228 This function replaces the text in the buffer (or in @var{string}) that
1229 was matched by the last search. It replaces that text with
1232 If you did the last search in a buffer, you should specify @code{nil}
1233 for @var{string} and make sure that the current buffer when you call
1234 @code{replace-match} is the one in which you did the searching or
1235 matching. Then @code{replace-match} does the replacement by editing
1236 the buffer; it leaves point at the end of the replacement text, and
1239 If you did the search in a string, pass the same string as @var{string}.
1240 Then @code{replace-match} does the replacement by constructing and
1241 returning a new string.
1243 If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
1244 the replacement text without case conversion; otherwise, it converts
1245 the replacement text depending upon the capitalization of the text to
1246 be replaced. If the original text is all upper case, this converts
1247 the replacement text to upper case. If all words of the original text
1248 are capitalized, this capitalizes all the words of the replacement
1249 text. If all the words are one-letter and they are all upper case,
1250 they are treated as capitalized words rather than all-upper-case
1253 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1254 exactly as it is, the only alterations being case changes as needed.
1255 If it is @code{nil} (the default), then the character @samp{\} is treated
1256 specially. If a @samp{\} appears in @var{replacement}, then it must be
1257 part of one of the following sequences:
1261 @cindex @samp{&} in replacement
1262 @samp{\&} stands for the entire text being replaced.
1264 @item @samp{\@var{n}}
1265 @cindex @samp{\@var{n}} in replacement
1266 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1267 matched the @var{n}th subexpression in the original regexp.
1268 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1269 If the @var{n}th subexpression never matched, an empty string is substituted.
1272 @cindex @samp{\} in replacement
1273 @samp{\\} stands for a single @samp{\} in the replacement text.
1276 These substitutions occur after case conversion, if any,
1277 so the strings they substitute are never case-converted.
1279 If @var{subexp} is non-@code{nil}, that says to replace just
1280 subexpression number @var{subexp} of the regexp that was matched, not
1281 the entire match. For example, after matching @samp{foo \(ba*r\)},
1282 calling @code{replace-match} with 1 as @var{subexp} means to replace
1283 just the text that matched @samp{\(ba*r\)}.
1286 @defun match-substitute-replacement replacement &optional fixedcase literal string subexp
1287 This function returns the text that would be inserted into the buffer
1288 by @code{replace-match}, but without modifying the buffer. It is
1289 useful if you want to present the user with actual replacement result,
1290 with constructs like @samp{\@var{n}} or @samp{\&} substituted with
1291 matched groups. Arguments @var{replacement} and optional
1292 @var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the
1293 same meaning as for @code{replace-match}.
1296 @node Simple Match Data
1297 @subsection Simple Match Data Access
1299 This section explains how to use the match data to find out what was
1300 matched by the last search or match operation, if it succeeded.
1302 You can ask about the entire matching text, or about a particular
1303 parenthetical subexpression of a regular expression. The @var{count}
1304 argument in the functions below specifies which. If @var{count} is
1305 zero, you are asking about the entire match. If @var{count} is
1306 positive, it specifies which subexpression you want.
1308 Recall that the subexpressions of a regular expression are those
1309 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1310 @var{count}th subexpression is found by counting occurrences of
1311 @samp{\(} from the beginning of the whole regular expression. The first
1312 subexpression is numbered 1, the second 2, and so on. Only regular
1313 expressions can have subexpressions---after a simple string search, the
1314 only information available is about the entire match.
1316 Every successful search sets the match data. Therefore, you should
1317 query the match data immediately after searching, before calling any
1318 other function that might perform another search. Alternatively, you
1319 may save and restore the match data (@pxref{Saving Match Data}) around
1320 the call to functions that could perform another search.
1322 A search which fails may or may not alter the match data. In the
1323 past, a failing search did not do this, but we may change it in the
1324 future. So don't try to rely on the value of the match data after
1327 @defun match-string count &optional in-string
1328 This function returns, as a string, the text matched in the last search
1329 or match operation. It returns the entire text if @var{count} is zero,
1330 or just the portion corresponding to the @var{count}th parenthetical
1331 subexpression, if @var{count} is positive.
1333 If the last such operation was done against a string with
1334 @code{string-match}, then you should pass the same string as the
1335 argument @var{in-string}. After a buffer search or match,
1336 you should omit @var{in-string} or pass @code{nil} for it; but you
1337 should make sure that the current buffer when you call
1338 @code{match-string} is the one in which you did the searching or
1341 The value is @code{nil} if @var{count} is out of range, or for a
1342 subexpression inside a @samp{\|} alternative that wasn't used or a
1343 repetition that repeated zero times.
1346 @defun match-string-no-properties count &optional in-string
1347 This function is like @code{match-string} except that the result
1348 has no text properties.
1351 @defun match-beginning count
1352 This function returns the position of the start of text matched by the
1353 last regular expression searched for, or a subexpression of it.
1355 If @var{count} is zero, then the value is the position of the start of
1356 the entire match. Otherwise, @var{count} specifies a subexpression in
1357 the regular expression, and the value of the function is the starting
1358 position of the match for that subexpression.
1360 The value is @code{nil} for a subexpression inside a @samp{\|}
1361 alternative that wasn't used or a repetition that repeated zero times.
1364 @defun match-end count
1365 This function is like @code{match-beginning} except that it returns the
1366 position of the end of the match, rather than the position of the
1370 Here is an example of using the match data, with a comment showing the
1371 positions within the text:
1375 (string-match "\\(qu\\)\\(ick\\)"
1376 "The quick fox jumped quickly.")
1382 (match-string 0 "The quick fox jumped quickly.")
1384 (match-string 1 "The quick fox jumped quickly.")
1386 (match-string 2 "The quick fox jumped quickly.")
1391 (match-beginning 1) ; @r{The beginning of the match}
1392 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1396 (match-beginning 2) ; @r{The beginning of the match}
1397 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1401 (match-end 1) ; @r{The end of the match}
1402 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1404 (match-end 2) ; @r{The end of the match}
1405 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1409 Here is another example. Point is initially located at the beginning
1410 of the line. Searching moves point to between the space and the word
1411 @samp{in}. The beginning of the entire match is at the 9th character of
1412 the buffer (@samp{T}), and the beginning of the match for the first
1413 subexpression is at the 13th character (@samp{c}).
1418 (re-search-forward "The \\(cat \\)")
1420 (match-beginning 1))
1425 ---------- Buffer: foo ----------
1426 I read "The cat @point{}in the hat comes back" twice.
1429 ---------- Buffer: foo ----------
1434 (In this case, the index returned is a buffer position; the first
1435 character of the buffer counts as 1.)
1437 @node Entire Match Data
1438 @subsection Accessing the Entire Match Data
1440 The functions @code{match-data} and @code{set-match-data} read or
1441 write the entire match data, all at once.
1443 @defun match-data &optional integers reuse reseat
1444 This function returns a list of positions (markers or integers) that
1445 record all the information on what text the last search matched.
1446 Element zero is the position of the beginning of the match for the
1447 whole expression; element one is the position of the end of the match
1448 for the expression. The next two elements are the positions of the
1449 beginning and end of the match for the first subexpression, and so on.
1455 number {\mathsurround=0pt $2n$}
1457 corresponds to @code{(match-beginning @var{n})}; and
1463 number {\mathsurround=0pt $2n+1$}
1465 corresponds to @code{(match-end @var{n})}.
1467 Normally all the elements are markers or @code{nil}, but if
1468 @var{integers} is non-@code{nil}, that means to use integers instead
1469 of markers. (In that case, the buffer itself is appended as an
1470 additional element at the end of the list, to facilitate complete
1471 restoration of the match data.) If the last match was done on a
1472 string with @code{string-match}, then integers are always used,
1473 since markers can't point into a string.
1475 If @var{reuse} is non-@code{nil}, it should be a list. In that case,
1476 @code{match-data} stores the match data in @var{reuse}. That is,
1477 @var{reuse} is destructively modified. @var{reuse} does not need to
1478 have the right length. If it is not long enough to contain the match
1479 data, it is extended. If it is too long, the length of @var{reuse}
1480 stays the same, but the elements that were not used are set to
1481 @code{nil}. The purpose of this feature is to reduce the need for
1484 If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
1485 are reseated to point to nowhere.
1487 As always, there must be no possibility of intervening searches between
1488 the call to a search function and the call to @code{match-data} that is
1489 intended to access the match data for that search.
1494 @result{} (#<marker at 9 in foo>
1495 #<marker at 17 in foo>
1496 #<marker at 13 in foo>
1497 #<marker at 17 in foo>)
1502 @defun set-match-data match-list &optional reseat
1503 This function sets the match data from the elements of @var{match-list},
1504 which should be a list that was the value of a previous call to
1505 @code{match-data}. (More precisely, anything that has the same format
1508 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1509 an error; that sets the match data in a meaningless but harmless way.
1511 If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
1512 are reseated to point to nowhere.
1514 @findex store-match-data
1515 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1518 @node Saving Match Data
1519 @subsection Saving and Restoring the Match Data
1521 When you call a function that may do a search, you may need to save
1522 and restore the match data around that call, if you want to preserve the
1523 match data from an earlier search for later use. Here is an example
1524 that shows the problem that arises if you fail to save the match data:
1528 (re-search-forward "The \\(cat \\)")
1530 (foo) ; @r{Perhaps @code{foo} does}
1531 ; @r{more searching.}
1533 @result{} 61 ; @r{Unexpected result---not 48!}
1537 You can save and restore the match data with @code{save-match-data}:
1539 @defmac save-match-data body@dots{}
1540 This macro executes @var{body}, saving and restoring the match
1541 data around it. The return value is the value of the last form in
1545 You could use @code{set-match-data} together with @code{match-data} to
1546 imitate the effect of the special form @code{save-match-data}. Here is
1551 (let ((data (match-data)))
1553 @dots{} ; @r{Ok to change the original match data.}
1554 (set-match-data data)))
1558 Emacs automatically saves and restores the match data when it runs
1559 process filter functions (@pxref{Filter Functions}) and process
1560 sentinels (@pxref{Sentinels}).
1563 Here is a function which restores the match data provided the buffer
1564 associated with it still exists.
1568 (defun restore-match-data (data)
1569 @c It is incorrect to split the first line of a doc string.
1570 @c If there's a problem here, it should be solved in some other way.
1571 "Restore the match data DATA unless the buffer is missing."
1577 (null (marker-buffer (car d)))
1579 ;; @file{match-data} @r{buffer is deleted.}
1582 (set-match-data data))))
1587 @node Search and Replace
1588 @section Search and Replace
1589 @cindex replacement after search
1590 @cindex searching and replacing
1592 If you want to find all matches for a regexp in part of the buffer,
1593 and replace them, the best way is to write an explicit loop using
1594 @code{re-search-forward} and @code{replace-match}, like this:
1597 (while (re-search-forward "foo[ \t]+bar" nil t)
1598 (replace-match "foobar"))
1602 @xref{Replacing Match,, Replacing the Text that Matched}, for a
1603 description of @code{replace-match}.
1605 However, replacing matches in a string is more complex, especially
1606 if you want to do it efficiently. So Emacs provides a function to do
1609 @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
1610 This function copies @var{string} and searches it for matches for
1611 @var{regexp}, and replaces them with @var{rep}. It returns the
1612 modified copy. If @var{start} is non-@code{nil}, the search for
1613 matches starts at that index in @var{string}, so matches starting
1614 before that index are not changed.
1616 This function uses @code{replace-match} to do the replacement, and it
1617 passes the optional arguments @var{fixedcase}, @var{literal} and
1618 @var{subexp} along to @code{replace-match}.
1620 Instead of a string, @var{rep} can be a function. In that case,
1621 @code{replace-regexp-in-string} calls @var{rep} for each match,
1622 passing the text of the match as its sole argument. It collects the
1623 value @var{rep} returns and passes that to @code{replace-match} as the
1624 replacement string. The match-data at this point are the result
1625 of matching @var{regexp} against a substring of @var{string}.
1628 If you want to write a command along the lines of @code{query-replace},
1629 you can use @code{perform-replace} to do the work.
1631 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
1632 This function is the guts of @code{query-replace} and related
1633 commands. It searches for occurrences of @var{from-string} in the
1634 text between positions @var{start} and @var{end} and replaces some or
1635 all of them. If @var{start} is @code{nil} (or omitted), point is used
1636 instead, and the end of the buffer's accessible portion is used for
1639 If @var{query-flag} is @code{nil}, it replaces all
1640 occurrences; otherwise, it asks the user what to do about each one.
1642 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
1643 considered a regular expression; otherwise, it must match literally. If
1644 @var{delimited-flag} is non-@code{nil}, then only replacements
1645 surrounded by word boundaries are considered.
1647 The argument @var{replacements} specifies what to replace occurrences
1648 with. If it is a string, that string is used. It can also be a list of
1649 strings, to be used in cyclic order.
1651 If @var{replacements} is a cons cell, @w{@code{(@var{function}
1652 . @var{data})}}, this means to call @var{function} after each match to
1653 get the replacement text. This function is called with two arguments:
1654 @var{data}, and the number of replacements already made.
1656 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
1657 it specifies how many times to use each of the strings in the
1658 @var{replacements} list before advancing cyclically to the next one.
1660 If @var{from-string} contains upper-case letters, then
1661 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
1662 it uses the @code{replacements} without altering the case of them.
1664 Normally, the keymap @code{query-replace-map} defines the possible
1665 user responses for queries. The argument @var{map}, if
1666 non-@code{nil}, specifies a keymap to use instead of
1667 @code{query-replace-map}.
1669 This function uses one of two functions to search for the next
1670 occurrence of @var{from-string}. These functions are specified by the
1671 values of two variables: @code{replace-re-search-function} and
1672 @code{replace-search-function}. The former is called when the
1673 argument @var{regexp-flag} is non-@code{nil}, the latter when it is
1677 @defvar query-replace-map
1678 This variable holds a special keymap that defines the valid user
1679 responses for @code{perform-replace} and the commands that use it, as
1680 well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual
1685 The ``key bindings'' are not commands, just symbols that are meaningful
1686 to the functions that use this map.
1689 Prefix keys are not supported; each key binding must be for a
1690 single-event key sequence. This is because the functions don't use
1691 @code{read-key-sequence} to get the input; instead, they read a single
1692 event and look it up ``by hand.''
1696 Here are the meaningful ``bindings'' for @code{query-replace-map}.
1697 Several of them are meaningful only for @code{query-replace} and
1702 Do take the action being considered---in other words, ``yes.''
1705 Do not take action for this question---in other words, ``no.''
1708 Answer this question ``no,'' and give up on the entire series of
1709 questions, assuming that the answers will be ``no.''
1712 Answer this question ``yes,'' and give up on the entire series of
1713 questions, assuming that subsequent answers will be ``no.''
1716 Answer this question ``yes,'' but show the results---don't advance yet
1717 to the next question.
1720 Answer this question and all subsequent questions in the series with
1721 ``yes,'' without further user interaction.
1724 Move back to the previous place that a question was asked about.
1727 Enter a recursive edit to deal with this question---instead of any
1728 other action that would normally be taken.
1730 @item delete-and-edit
1731 Delete the text being considered, then enter a recursive edit to replace
1735 Redisplay and center the window, then ask the same question again.
1738 Perform a quit right away. Only @code{y-or-n-p} and related functions
1742 Display some help, then ask again.
1745 @defvar multi-query-replace-map
1746 This variable holds a keymap that extends @code{query-replace-map} by
1747 providing additional keybindings that are useful in multi-buffer
1751 @defvar replace-search-function
1752 This variable specifies a function that @code{perform-replace} calls
1753 to search for the next string to replace. Its default value is
1754 @code{search-forward}. Any other value should name a function of 3
1755 arguments: the first 3 arguments of @code{search-forward}
1756 (@pxref{String Search}).
1759 @defvar replace-re-search-function
1760 This variable specifies a function that @code{perform-replace} calls
1761 to search for the next regexp to replace. Its default value is
1762 @code{re-search-forward}. Any other value should name a function of 3
1763 arguments: the first 3 arguments of @code{re-search-forward}
1764 (@pxref{Regexp Search}).
1767 @node Standard Regexps
1768 @section Standard Regular Expressions Used in Editing
1769 @cindex regexps used standardly in editing
1770 @cindex standard regexps used in editing
1772 This section describes some variables that hold regular expressions
1773 used for certain purposes in editing:
1775 @defopt page-delimiter
1776 This is the regular expression describing line-beginnings that separate
1777 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1778 @code{"^\C-l"}); this matches a line that starts with a formfeed
1782 The following two regular expressions should @emph{not} assume the
1783 match always starts at the beginning of a line; they should not use
1784 @samp{^} to anchor the match. Most often, the paragraph commands do
1785 check for a match only at the beginning of a line, which means that
1786 @samp{^} would be superfluous. When there is a nonzero left margin,
1787 they accept matches that start after the left margin. In that case, a
1788 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1789 where a left margin is never used.
1791 @defopt paragraph-separate
1792 This is the regular expression for recognizing the beginning of a line
1793 that separates paragraphs. (If you change this, you may have to
1794 change @code{paragraph-start} also.) The default value is
1795 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1796 spaces, tabs, and form feeds (after its left margin).
1799 @defopt paragraph-start
1800 This is the regular expression for recognizing the beginning of a line
1801 that starts @emph{or} separates paragraphs. The default value is
1802 @w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
1803 whitespace or starting with a form feed (after its left margin).
1806 @defopt sentence-end
1807 If non-@code{nil}, the value should be a regular expression describing
1808 the end of a sentence, including the whitespace following the
1809 sentence. (All paragraph boundaries also end sentences, regardless.)
1811 If the value is @code{nil}, the default, then the function
1812 @code{sentence-end} has to construct the regexp. That is why you
1813 should always call the function @code{sentence-end} to obtain the
1814 regexp to be used to recognize the end of a sentence.
1818 This function returns the value of the variable @code{sentence-end},
1819 if non-@code{nil}. Otherwise it returns a default value based on the
1820 values of the variables @code{sentence-end-double-space}
1821 (@pxref{Definition of sentence-end-double-space}),
1822 @code{sentence-end-without-period} and
1823 @code{sentence-end-without-space}.