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 @setfilename ../../info/searching
7 @node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
8 @chapter Searching and Matching
11 GNU Emacs provides two ways to search through a buffer for specified
12 text: exact string searches and regular expression searches. After a
13 regular expression search, you can examine the @dfn{match data} to
14 determine which text matched the whole regular expression or various
18 * String Search:: Search for an exact match.
19 * Searching and Case:: Case-independent or case-significant searching.
20 * Regular Expressions:: Describing classes of strings.
21 * Regexp Search:: Searching for a match for a regexp.
22 * POSIX Regexps:: Searching POSIX-style for the longest match.
23 * Match Data:: Finding out which part of the text matched,
24 after a string or regexp search.
25 * Search and Replace:: Commands that loop, searching and replacing.
26 * Standard Regexps:: Useful regexps for finding sentences, pages,...
29 The @samp{skip-chars@dots{}} functions also perform a kind of searching.
30 @xref{Skipping Characters}. To search for changes in character
31 properties, see @ref{Property Search}.
34 @section Searching for Strings
37 These are the primitive functions for searching through the text in a
38 buffer. They are meant for use in programs, but you may call them
39 interactively. If you do so, they prompt for the search string; the
40 arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
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}.
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).
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
59 ---------- Buffer: foo ----------
60 @point{}The quick brown fox jumped over the lazy dog.
61 ---------- Buffer: foo ----------
65 (search-forward "fox")
68 ---------- Buffer: foo ----------
69 The quick brown fox@point{} jumped over the lazy dog.
70 ---------- Buffer: foo ----------
74 The argument @var{limit} specifies the upper bound to the search. (It
75 must 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.
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}. (It would be more consistent now to
86 return the new position of point in that case, but some existing
87 programs may depend on a value of @code{nil}.)
89 The argument @var{noerror} only affects valid searches which fail to
90 find a match. Invalid arguments cause errors regardless of
93 If @var{repeat} is a positive number @var{n}, it serves as a repeat
94 count: the search is repeated @var{n} times, each time starting at the
95 end of the previous time's match. If these successive searches
96 succeed, the function succeeds, moving point and returning its new
97 value. Otherwise the search fails, with results depending on the
98 value of @var{noerror}, as described above. If @var{repeat} is a
99 negative number -@var{n}, it serves as a repeat count of @var{n} for a
100 search in the opposite (backward) direction.
103 @deffn Command search-backward string &optional limit noerror repeat
104 This function searches backward from point for @var{string}. It is
105 like @code{search-forward}, except that it searches backwards rather
106 than forwards. Backward searches leave point at the beginning of the
110 @deffn Command word-search-forward string &optional limit noerror repeat
111 This function searches forward from point for a ``word'' match for
112 @var{string}. If it finds a match, it sets point to the end of the
113 match found, and returns the new value of point.
115 Word matching regards @var{string} as a sequence of words, disregarding
116 punctuation that separates them. It searches the buffer for the same
117 sequence of words. Each word must be distinct in the buffer (searching
118 for the word @samp{ball} does not match the word @samp{balls}), but the
119 details of punctuation and spacing are ignored (searching for @samp{ball
120 boy} does match @samp{ball. Boy!}).
122 In this example, point is initially at the beginning of the buffer; the
123 search leaves it between the @samp{y} and the @samp{!}.
127 ---------- Buffer: foo ----------
128 @point{}He said "Please! Find
130 ---------- Buffer: foo ----------
134 (word-search-forward "Please find the ball, boy.")
137 ---------- Buffer: foo ----------
138 He said "Please! Find
139 the ball boy@point{}!"
140 ---------- Buffer: foo ----------
144 If @var{limit} is non-@code{nil}, it must be a position in the current
145 buffer; it specifies the upper bound to the search. The match found
146 must not extend after that position.
148 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
149 an error if the search fails. If @var{noerror} is @code{t}, then it
150 returns @code{nil} instead of signaling an error. If @var{noerror} is
151 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
152 end of the accessible portion of the buffer) and returns @code{nil}.
154 If @var{repeat} is non-@code{nil}, then the search is repeated that many
155 times. Point is positioned at the end of the last match.
158 @deffn Command word-search-forward-lax string &optional limit noerror repeat
159 This command is identical to @code{word-search-forward}, except that
160 the end of @code{string} need not match a word boundary unless it ends
161 in whitespace. For instance, searching for @samp{ball boy} matches
162 @samp{ball boyee}, but does not match @samp{aball boy}.
165 @deffn Command word-search-backward string &optional limit noerror repeat
166 This function searches backward from point for a word match to
167 @var{string}. This function is just like @code{word-search-forward}
168 except that it searches backward and normally leaves point at the
169 beginning of the match.
172 @deffn Command word-search-backward-lax string &optional limit noerror repeat
173 This command is identical to @code{word-search-backward}, except that
174 the end of @code{string} need not match a word boundary unless it ends
178 @node Searching and Case
179 @section Searching and Case
180 @cindex searching and case
182 By default, searches in Emacs ignore the case of the text they are
183 searching through; if you specify searching for @samp{FOO}, then
184 @samp{Foo} or @samp{foo} is also considered a match. This applies to
185 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
186 @samp{A} or @samp{b} or @samp{B}.
188 If you do not want this feature, set the variable
189 @code{case-fold-search} to @code{nil}. Then all letters must match
190 exactly, including case. This is a buffer-local variable; altering the
191 variable affects only the current buffer. (@xref{Intro to
192 Buffer-Local}.) Alternatively, you may change the default value of
193 @code{case-fold-search}.
195 Note that the user-level incremental search feature handles case
196 distinctions differently. When the search string contains only lower
197 case letters, the search ignores case, but when the search string
198 contains one or more upper case letters, the search becomes
199 case-sensitive. But this has nothing to do with the searching
200 functions used in Lisp code.
202 @defopt case-fold-search
203 This buffer-local variable determines whether searches should ignore
204 case. If the variable is @code{nil} they do not ignore case; otherwise
209 This variable determines whether the higher level replacement
210 functions should preserve case. If the variable is @code{nil}, that
211 means to use the replacement text verbatim. A non-@code{nil} value
212 means to convert the case of the replacement text according to the
215 This variable is used by passing it as an argument to the function
216 @code{replace-match}. @xref{Replacing Match}.
219 @node Regular Expressions
220 @section Regular Expressions
221 @cindex regular expression
224 A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that
225 denotes a (possibly infinite) set of strings. Searching for matches for
226 a regexp is a very powerful operation. This section explains how to write
227 regexps; the following section says how to search for them.
230 @cindex regular expressions, developing
231 For convenient interactive development of regular expressions, you
232 can use the @kbd{M-x re-builder} command. It provides a convenient
233 interface for creating regular expressions, by giving immediate visual
234 feedback in a separate buffer. As you edit the regexp, all its
235 matches in the target buffer are highlighted. Each parenthesized
236 sub-expression of the regexp is shown in a distinct face, which makes
237 it easier to verify even very complex regexps.
240 * Syntax of Regexps:: Rules for writing regular expressions.
241 * Regexp Example:: Illustrates regular expression syntax.
242 * Regexp Functions:: Functions for operating on regular expressions.
245 @node Syntax of Regexps
246 @subsection Syntax of Regular Expressions
248 Regular expressions have a syntax in which a few characters are
249 special constructs and the rest are @dfn{ordinary}. An ordinary
250 character is a simple regular expression that matches that character
251 and nothing else. The special characters are @samp{.}, @samp{*},
252 @samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
253 special characters will be defined in the future. The character
254 @samp{]} is special if it ends a character alternative (see later).
255 The character @samp{-} is special inside a character alternative. A
256 @samp{[:} and balancing @samp{:]} enclose a character class inside a
257 character alternative. Any other character appearing in a regular
258 expression is ordinary, unless a @samp{\} precedes it.
260 For example, @samp{f} is not a special character, so it is ordinary, and
261 therefore @samp{f} is a regular expression that matches the string
262 @samp{f} and no other string. (It does @emph{not} match the string
263 @samp{fg}, but it does match a @emph{part} of that string.) Likewise,
264 @samp{o} is a regular expression that matches only @samp{o}.@refill
266 Any two regular expressions @var{a} and @var{b} can be concatenated. The
267 result is a regular expression that matches a string if @var{a} matches
268 some amount of the beginning of that string and @var{b} matches the rest of
271 As a simple example, we can concatenate the regular expressions @samp{f}
272 and @samp{o} to get the regular expression @samp{fo}, which matches only
273 the string @samp{fo}. Still trivial. To do something more powerful, you
274 need to use one of the special regular expression constructs.
277 * Regexp Special:: Special characters in regular expressions.
278 * Char Classes:: Character classes used in regular expressions.
279 * Regexp Backslash:: Backslash-sequences in regular expressions.
283 @subsubsection Special Characters in Regular Expressions
285 Here is a list of the characters that are special in a regular
290 @item @samp{.}@: @r{(Period)}
291 @cindex @samp{.} in regexp
292 is a special character that matches any single character except a newline.
293 Using concatenation, we can make regular expressions like @samp{a.b}, which
294 matches any three-character string that begins with @samp{a} and ends with
298 @cindex @samp{*} in regexp
299 is not a construct by itself; it is a postfix operator that means to
300 match the preceding regular expression repetitively as many times as
301 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
304 @samp{*} always applies to the @emph{smallest} possible preceding
305 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
306 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
308 The matcher processes a @samp{*} construct by matching, immediately, as
309 many repetitions as can be found. Then it continues with the rest of
310 the pattern. If that fails, backtracking occurs, discarding some of the
311 matches of the @samp{*}-modified construct in the hope that that will
312 make it possible to match the rest of the pattern. For example, in
313 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
314 first tries to match all three @samp{a}s; but the rest of the pattern is
315 @samp{ar} and there is only @samp{r} left to match, so this try fails.
316 The next alternative is for @samp{a*} to match only two @samp{a}s. With
317 this choice, the rest of the regexp matches successfully.
319 @strong{Warning:} Nested repetition operators can run for an
320 indefinitely long time, if they lead to ambiguous matching. For
321 example, trying to match the regular expression @samp{\(x+y*\)*a}
322 against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could
323 take hours before it ultimately fails. Emacs must try each way of
324 grouping the @samp{x}s before concluding that none of them can work.
325 Even worse, @samp{\(x*\)*} can match the null string in infinitely
326 many ways, so it causes an infinite loop. To avoid these problems,
327 check nested repetitions carefully, to make sure that they do not
328 cause combinatorial explosions in backtracking.
331 @cindex @samp{+} in regexp
332 is a postfix operator, similar to @samp{*} except that it must match
333 the preceding expression at least once. So, for example, @samp{ca+r}
334 matches the strings @samp{car} and @samp{caaaar} but not the string
335 @samp{cr}, whereas @samp{ca*r} matches all three strings.
338 @cindex @samp{?} in regexp
339 is a postfix operator, similar to @samp{*} except that it must match the
340 preceding expression either once or not at all. For example,
341 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
343 @item @samp{*?}, @samp{+?}, @samp{??}
344 @cindex non-greedy repetition characters in regexp
345 These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
346 and @samp{?}. Where those operators match the largest possible
347 substring (consistent with matching the entire containing expression),
348 the non-greedy variants match the smallest possible substring
349 (consistent with matching the entire containing expression).
351 For example, the regular expression @samp{c[ad]*a} when applied to the
352 string @samp{cdaaada} matches the whole string; but the regular
353 expression @samp{c[ad]*?a}, applied to that same string, matches just
354 @samp{cda}. (The smallest possible match here for @samp{[ad]*?} that
355 permits the whole expression to match is @samp{d}.)
357 @item @samp{[ @dots{} ]}
358 @cindex character alternative (in regexp)
359 @cindex @samp{[} in regexp
360 @cindex @samp{]} in regexp
361 is a @dfn{character alternative}, which begins with @samp{[} and is
362 terminated by @samp{]}. In the simplest case, the characters between
363 the two brackets are what this character alternative can match.
365 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
366 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
367 (including the empty string). It follows that @samp{c[ad]*r}
368 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
370 You can also include character ranges in a character alternative, by
371 writing the starting and ending characters with a @samp{-} between them.
372 Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
373 Ranges may be intermixed freely with individual characters, as in
374 @samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
375 or @samp{$}, @samp{%} or period.
377 Note that the usual regexp special characters are not special inside a
378 character alternative. A completely different set of characters is
379 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
381 To include a @samp{]} in a character alternative, you must make it the
382 first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
383 To include a @samp{-}, write @samp{-} as the first or last character of
384 the character alternative, or put it after a range. Thus, @samp{[]-]}
385 matches both @samp{]} and @samp{-}.
387 To include @samp{^} in a character alternative, put it anywhere but at
390 If a range starts with a unibyte character @var{c} and ends with a
391 multibyte character @var{c2}, the range is divided into two parts: one
392 is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
393 @var{c1} is the first character of the charset to which @var{c2}
396 A character alternative can also specify named character classes
397 (@pxref{Char Classes}). This is a POSIX feature whose syntax is
398 @samp{[:@var{class}:]}. Using a character class is equivalent to
399 mentioning each of the characters in that class; but the latter is not
400 feasible in practice, since some classes include thousands of
401 different characters.
403 @item @samp{[^ @dots{} ]}
404 @cindex @samp{^} in regexp
405 @samp{[^} begins a @dfn{complemented character alternative}. This
406 matches any character except the ones specified. Thus,
407 @samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
410 @samp{^} is not special in a character alternative unless it is the first
411 character. The character following the @samp{^} is treated as if it
412 were first (in other words, @samp{-} and @samp{]} are not special there).
414 A complemented character alternative can match a newline, unless newline is
415 mentioned as one of the characters not to match. This is in contrast to
416 the handling of regexps in programs such as @code{grep}.
418 You can specify named character classes, just like in character
419 alternatives. For instance, @samp{[^[:ascii:]]} matches any
420 non-@acronym{ASCII} character. @xref{Char Classes}.
423 @cindex beginning of line in regexp
424 When matching a buffer, @samp{^} matches the empty string, but only at the
425 beginning of a line in the text being matched (or the beginning of the
426 accessible portion of the buffer). Otherwise it fails to match
427 anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the
430 When matching a string instead of a buffer, @samp{^} matches at the
431 beginning of the string or after a newline character.
433 For historical compatibility reasons, @samp{^} can be used only at the
434 beginning of the regular expression, or after @samp{\(}, @samp{\(?:}
438 @cindex @samp{$} in regexp
439 @cindex end of line in regexp
440 is similar to @samp{^} but matches only at the end of a line (or the
441 end of the accessible portion of the buffer). Thus, @samp{x+$}
442 matches a string of one @samp{x} or more at the end of a line.
444 When matching a string instead of a buffer, @samp{$} matches at the end
445 of the string or before a newline character.
447 For historical compatibility reasons, @samp{$} can be used only at the
448 end of the regular expression, or before @samp{\)} or @samp{\|}.
451 @cindex @samp{\} in regexp
452 has two functions: it quotes the special characters (including
453 @samp{\}), and it introduces additional special constructs.
455 Because @samp{\} quotes special characters, @samp{\$} is a regular
456 expression that matches only @samp{$}, and @samp{\[} is a regular
457 expression that matches only @samp{[}, and so on.
459 Note that @samp{\} also has special meaning in the read syntax of Lisp
460 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
461 example, the regular expression that matches the @samp{\} character is
462 @samp{\\}. To write a Lisp string that contains the characters
463 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
464 @samp{\}. Therefore, the read syntax for a regular expression matching
465 @samp{\} is @code{"\\\\"}.@refill
468 @strong{Please note:} For historical compatibility, special characters
469 are treated as ordinary ones if they are in contexts where their special
470 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
471 ordinary since there is no preceding expression on which the @samp{*}
472 can act. It is poor practice to depend on this behavior; quote the
473 special character anyway, regardless of where it appears.@refill
475 As a @samp{\} is not special inside a character alternative, it can
476 never remove the special meaning of @samp{-} or @samp{]}. So you
477 should not quote these characters when they have no special meaning
478 either. This would not clarify anything, since backslashes can
479 legitimately precede these characters where they @emph{have} special
480 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
481 which matches any single character except a backslash.
483 In practice, most @samp{]} that occur in regular expressions close a
484 character alternative and hence are special. However, occasionally a
485 regular expression may try to match a complex pattern of literal
486 @samp{[} and @samp{]}. In such situations, it sometimes may be
487 necessary to carefully parse the regexp from the start to determine
488 which square brackets enclose a character alternative. For example,
489 @samp{[^][]]} consists of the complemented character alternative
490 @samp{[^][]} (which matches any single character that is not a square
491 bracket), followed by a literal @samp{]}.
493 The exact rules are that at the beginning of a regexp, @samp{[} is
494 special and @samp{]} not. This lasts until the first unquoted
495 @samp{[}, after which we are in a character alternative; @samp{[} is
496 no longer special (except when it starts a character class) but @samp{]}
497 is special, unless it immediately follows the special @samp{[} or that
498 @samp{[} followed by a @samp{^}. This lasts until the next special
499 @samp{]} that does not end a character class. This ends the character
500 alternative and restores the ordinary syntax of regular expressions;
501 an unquoted @samp{[} is special again and a @samp{]} not.
504 @subsubsection Character Classes
505 @cindex character classes in regexp
507 Here is a table of the classes you can use in a character alternative,
512 This matches any @acronym{ASCII} character (codes 0--127).
514 This matches any letter or digit. (At present, for multibyte
515 characters, it matches anything that has word syntax.)
517 This matches any letter. (At present, for multibyte characters, it
518 matches anything that has word syntax.)
520 This matches space and tab only.
522 This matches any @acronym{ASCII} control character.
524 This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
525 matches any digit, as well as @samp{+} and @samp{-}.
527 This matches graphic characters---everything except @acronym{ASCII} control
528 characters, space, and the delete character.
530 This matches any lower-case letter, as determined by the current case
531 table (@pxref{Case Tables}). If @code{case-fold-search} is
532 non-@code{nil}, this also matches any upper-case letter.
534 This matches any multibyte character (@pxref{Text Representations}).
536 This matches any non-@acronym{ASCII} character.
538 This matches printing characters---everything except @acronym{ASCII} control
539 characters and the delete character.
541 This matches any punctuation character. (At present, for multibyte
542 characters, it matches anything that has non-word syntax.)
544 This matches any character that has whitespace syntax
545 (@pxref{Syntax Class Table}).
547 This matches any unibyte character (@pxref{Text Representations}).
549 This matches any upper-case letter, as determined by the current case
550 table (@pxref{Case Tables}). If @code{case-fold-search} is
551 non-@code{nil}, this also matches any lower-case letter.
553 This matches any character that has word syntax (@pxref{Syntax Class
556 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
557 through @samp{f} and @samp{A} through @samp{F}.
560 @node Regexp Backslash
561 @subsubsection Backslash Constructs in Regular Expressions
563 For the most part, @samp{\} followed by any character matches only
564 that character. However, there are several exceptions: certain
565 two-character sequences starting with @samp{\} that have special
566 meanings. (The character after the @samp{\} in such a sequence is
567 always ordinary when used on its own.) Here is a table of the special
572 @cindex @samp{|} in regexp
573 @cindex regexp alternative
574 specifies an alternative.
575 Two regular expressions @var{a} and @var{b} with @samp{\|} in
576 between form an expression that matches anything that either @var{a} or
577 @var{b} matches.@refill
579 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
580 but no other string.@refill
582 @samp{\|} applies to the largest possible surrounding expressions. Only a
583 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
586 If you need full backtracking capability to handle multiple uses of
587 @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
591 is a postfix operator that repeats the previous pattern exactly @var{m}
592 times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
593 and nothing else. @samp{c[ad]\@{3\@}r} matches string such as
594 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
596 @item \@{@var{m},@var{n}\@}
597 is a more general postfix operator that specifies repetition with a
598 minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m}
599 is omitted, the minimum is 0; if @var{n} is omitted, there is no
602 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
603 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
605 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.@*
606 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.@*
607 @samp{\@{1,\@}} is equivalent to @samp{+}.
610 @cindex @samp{(} in regexp
611 @cindex @samp{)} in regexp
612 @cindex regexp grouping
613 is a grouping construct that serves three purposes:
617 To enclose a set of @samp{\|} alternatives for other operations. Thus,
618 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
622 To enclose a complicated expression for the postfix operators @samp{*},
623 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
624 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
625 number (zero or more) of @samp{na} strings.
628 To record a matched substring for future reference with
629 @samp{\@var{digit}} (see below).
632 This last application is not a consequence of the idea of a
633 parenthetical grouping; it is a separate feature that was assigned as a
634 second meaning to the same @samp{\( @dots{} \)} construct because, in
635 practice, there was usually no conflict between the two meanings. But
636 occasionally there is a conflict, and that led to the introduction of
639 @item \(?: @dots{} \)
641 @cindex non-capturing group
642 @cindex unnumbered group
643 @cindex @samp{(?:} in regexp
644 is the @dfn{shy group} construct. A shy group serves the first two
645 purposes of an ordinary group (controlling the nesting of other
646 operators), but it does not get a number, so you cannot refer back to
647 its value with @samp{\@var{digit}}. Shy groups are particularly
648 useful for mechanically-constructed regular expressions, because they
649 can be added automatically without altering the numbering of ordinary,
652 Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered
655 @item \(?@var{num}: @dots{} \)
656 is the @dfn{explicitly numbered group} construct. Normal groups get
657 their number implicitly, based on their position, which can be
658 inconvenient. This construct allows you to force a particular group
659 number. There is no particular restriction on the numbering,
660 e.g.@: you can have several groups with the same number in which case
661 the last one to match (i.e.@: the rightmost match) will win.
662 Implicitly numbered groups always get the smallest integer larger than
663 the one of any previous group.
666 matches the same text that matched the @var{digit}th occurrence of a
667 grouping (@samp{\( @dots{} \)}) construct.
669 In other words, after the end of a group, the matcher remembers the
670 beginning and end of the text matched by that group. Later on in the
671 regular expression you can use @samp{\} followed by @var{digit} to
672 match that same text, whatever it may have been.
674 The strings matching the first nine grouping constructs appearing in
675 the entire regular expression passed to a search or matching function
676 are assigned numbers 1 through 9 in the order that the open
677 parentheses appear in the regular expression. So you can use
678 @samp{\1} through @samp{\9} to refer to the text matched by the
679 corresponding grouping constructs.
681 For example, @samp{\(.*\)\1} matches any newline-free string that is
682 composed of two identical halves. The @samp{\(.*\)} matches the first
683 half, which may be anything, but the @samp{\1} that follows must match
686 If a @samp{\( @dots{} \)} construct matches more than once (which can
687 happen, for instance, if it is followed by @samp{*}), only the last
690 If a particular grouping construct in the regular expression was never
691 matched---for instance, if it appears inside of an alternative that
692 wasn't used, or inside of a repetition that repeated zero times---then
693 the corresponding @samp{\@var{digit}} construct never matches
694 anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2}
695 cannot match @samp{lose}: the second alternative inside the larger
696 group matches it, but then @samp{\2} is undefined and can't match
697 anything. But it can match @samp{foobb}, because the first
698 alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
701 @cindex @samp{\w} in regexp
702 matches any word-constituent character. The editor syntax table
703 determines which characters these are. @xref{Syntax Tables}.
706 @cindex @samp{\W} in regexp
707 matches any character that is not a word constituent.
710 @cindex @samp{\s} in regexp
711 matches any character whose syntax is @var{code}. Here @var{code} is a
712 character that represents a syntax code: thus, @samp{w} for word
713 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
714 etc. To represent whitespace syntax, use either @samp{-} or a space
715 character. @xref{Syntax Class Table}, for a list of syntax codes and
716 the characters that stand for them.
719 @cindex @samp{\S} in regexp
720 matches any character whose syntax is not @var{code}.
722 @cindex category, regexp search for
724 matches any character whose category is @var{c}. Here @var{c} is a
725 character that represents a category: thus, @samp{c} for Chinese
726 characters or @samp{g} for Greek characters in the standard category
727 table. You can see the list of all the currently defined categories
728 with @kbd{M-x describe-categories @key{RET}}. You can also define
729 your own categories in addition to the standard ones using the
730 @code{define-category} function (@pxref{Categories}).
733 matches any character whose category is not @var{c}.
736 The following regular expression constructs match the empty string---that is,
737 they don't use up any characters---but whether they match depends on the
738 context. For all, the beginning and end of the accessible portion of
739 the buffer are treated as if they were the actual beginning and end of
744 @cindex @samp{\`} in regexp
745 matches the empty string, but only at the beginning
746 of the buffer or string being matched against.
749 @cindex @samp{\'} in regexp
750 matches the empty string, but only at the end of
751 the buffer or string being matched against.
754 @cindex @samp{\=} in regexp
755 matches the empty string, but only at point.
756 (This construct is not defined when matching against a string.)
759 @cindex @samp{\b} in regexp
760 matches the empty string, but only at the beginning or
761 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
762 @samp{foo} as a separate word. @samp{\bballs?\b} matches
763 @samp{ball} or @samp{balls} as a separate word.@refill
765 @samp{\b} matches at the beginning or end of the buffer (or string)
766 regardless of what text appears next to it.
769 @cindex @samp{\B} in regexp
770 matches the empty string, but @emph{not} at the beginning or
771 end of a word, nor at the beginning or end of the buffer (or string).
774 @cindex @samp{\<} in regexp
775 matches the empty string, but only at the beginning of a word.
776 @samp{\<} matches at the beginning of the buffer (or string) only if a
777 word-constituent character follows.
780 @cindex @samp{\>} in regexp
781 matches the empty string, but only at the end of a word. @samp{\>}
782 matches at the end of the buffer (or string) only if the contents end
783 with a word-constituent character.
786 @cindex @samp{\_<} in regexp
787 matches the empty string, but only at the beginning of a symbol. A
788 symbol is a sequence of one or more word or symbol constituent
789 characters. @samp{\_<} matches at the beginning of the buffer (or
790 string) only if a symbol-constituent character follows.
793 @cindex @samp{\_>} in regexp
794 matches the empty string, but only at the end of a symbol. @samp{\_>}
795 matches at the end of the buffer (or string) only if the contents end
796 with a symbol-constituent character.
799 @kindex invalid-regexp
800 Not every string is a valid regular expression. For example, a string
801 that ends inside a character alternative without terminating @samp{]}
802 is invalid, and so is a string that ends with a single @samp{\}. If
803 an invalid regular expression is passed to any of the search functions,
804 an @code{invalid-regexp} error is signaled.
807 @comment node-name, next, previous, up
808 @subsection Complex Regexp Example
810 Here is a complicated regexp which was formerly used by Emacs to
811 recognize the end of a sentence together with any whitespace that
812 follows. (Nowadays Emacs uses a similar but more complex default
813 regexp constructed by the function @code{sentence-end}.
814 @xref{Standard Regexps}.)
816 First, we show the regexp as a string in Lisp syntax to distinguish
817 spaces from tab characters. The string constant begins and ends with a
818 double-quote. @samp{\"} stands for a double-quote as part of the
819 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
820 tab and @samp{\n} for a newline.
823 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
827 In contrast, if you evaluate this string, you will see the following:
831 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
832 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
838 In this output, tab and newline appear as themselves.
840 This regular expression contains four parts in succession and can be
841 deciphered as follows:
845 The first part of the pattern is a character alternative that matches
846 any one of three characters: period, question mark, and exclamation
847 mark. The match must begin with one of these three characters. (This
848 is one point where the new default regexp used by Emacs differs from
849 the old. The new value also allows some non-@acronym{ASCII}
850 characters that end a sentence without any following whitespace.)
853 The second part of the pattern matches any closing braces and quotation
854 marks, zero or more of them, that may follow the period, question mark
855 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
856 a string. The @samp{*} at the end indicates that the immediately
857 preceding regular expression (a character alternative, in this case) may be
858 repeated zero or more times.
860 @item \\($\\|@ $\\|\t\\|@ @ \\)
861 The third part of the pattern matches the whitespace that follows the
862 end of a sentence: the end of a line (optionally with a space), or a
863 tab, or two spaces. The double backslashes mark the parentheses and
864 vertical bars as regular expression syntax; the parentheses delimit a
865 group and the vertical bars separate alternatives. The dollar sign is
866 used to match the end of a line.
869 Finally, the last part of the pattern matches any additional whitespace
870 beyond the minimum needed to end a sentence.
873 @node Regexp Functions
874 @subsection Regular Expression Functions
876 These functions operate on regular expressions.
878 @defun regexp-quote string
879 This function returns a regular expression whose only exact match is
880 @var{string}. Using this regular expression in @code{looking-at} will
881 succeed only if the next characters in the buffer are @var{string};
882 using it in a search function will succeed if the text being searched
883 contains @var{string}.
885 This allows you to request an exact string match or search when calling
886 a function that wants a regular expression.
890 (regexp-quote "^The cat$")
891 @result{} "\\^The cat\\$"
895 One use of @code{regexp-quote} is to combine an exact string match with
896 context described as a regular expression. For example, this searches
897 for the string that is the value of @var{string}, surrounded by
903 (concat "\\s-" (regexp-quote string) "\\s-"))
908 @defun regexp-opt strings &optional paren
909 This function returns an efficient regular expression that will match
910 any of the strings in the list @var{strings}. This is useful when you
911 need to make matching or searching as fast as possible---for example,
914 If the optional argument @var{paren} is non-@code{nil}, then the
915 returned regular expression is always enclosed by at least one
916 parentheses-grouping construct. If @var{paren} is @code{words}, then
917 that construct is additionally surrounded by @samp{\<} and @samp{\>};
918 alternatively, if @var{paren} is @code{symbols}, then that construct
919 is additionally surrounded by @samp{\_<} and @samp{\_>}
920 (@code{symbols} is often appropriate when matching
921 programming-language keywords and the like).
923 This simplified definition of @code{regexp-opt} produces a
924 regular expression which is equivalent to the actual value
925 (but not as efficient):
928 (defun regexp-opt (strings paren)
929 (let ((open-paren (if paren "\\(" ""))
930 (close-paren (if paren "\\)" "")))
932 (mapconcat 'regexp-quote strings "\\|")
937 @defun regexp-opt-depth regexp
938 This function returns the total number of grouping constructs
939 (parenthesized expressions) in @var{regexp}. This does not include
940 shy groups (@pxref{Regexp Backslash}).
944 @section Regular Expression Searching
945 @cindex regular expression searching
946 @cindex regexp searching
947 @cindex searching for regexp
949 In GNU Emacs, you can search for the next match for a regular
950 expression either incrementally or not. For incremental search
951 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
952 The GNU Emacs Manual}. Here we describe only the search functions
953 useful in programs. The principal one is @code{re-search-forward}.
955 These search functions convert the regular expression to multibyte if
956 the buffer is multibyte; they convert the regular expression to unibyte
957 if the buffer is unibyte. @xref{Text Representations}.
959 @deffn Command re-search-forward regexp &optional limit noerror repeat
960 This function searches forward in the current buffer for a string of
961 text that is matched by the regular expression @var{regexp}. The
962 function skips over any amount of text that is not matched by
963 @var{regexp}, and leaves point at the end of the first match found.
964 It returns the new value of point.
966 If @var{limit} is non-@code{nil}, it must be a position in the current
967 buffer. It specifies the upper bound to the search. No match
968 extending after that position is accepted.
970 If @var{repeat} is supplied, it must be a positive number; the search
971 is repeated that many times; each repetition starts at the end of the
972 previous match. If all these successive searches succeed, the search
973 succeeds, moving point and returning its new value. Otherwise the
974 search fails. What @code{re-search-forward} does when the search
975 fails depends on the value of @var{noerror}:
979 Signal a @code{search-failed} error.
981 Do nothing and return @code{nil}.
983 Move point to @var{limit} (or the end of the accessible portion of the
984 buffer) and return @code{nil}.
987 In the following example, point is initially before the @samp{T}.
988 Evaluating the search call moves point to the end of that line (between
989 the @samp{t} of @samp{hat} and the newline).
993 ---------- Buffer: foo ----------
994 I read "@point{}The cat in the hat
996 ---------- Buffer: foo ----------
1000 (re-search-forward "[a-z]+" nil t 5)
1003 ---------- Buffer: foo ----------
1004 I read "The cat in the hat@point{}
1006 ---------- Buffer: foo ----------
1011 @deffn Command re-search-backward regexp &optional limit noerror repeat
1012 This function searches backward in the current buffer for a string of
1013 text that is matched by the regular expression @var{regexp}, leaving
1014 point at the beginning of the first text found.
1016 This function is analogous to @code{re-search-forward}, but they are not
1017 simple mirror images. @code{re-search-forward} finds the match whose
1018 beginning is as close as possible to the starting point. If
1019 @code{re-search-backward} were a perfect mirror image, it would find the
1020 match whose end is as close as possible. However, in fact it finds the
1021 match whose beginning is as close as possible (and yet ends before the
1022 starting point). The reason for this is that matching a regular
1023 expression at a given spot always works from beginning to end, and
1024 starts at a specified beginning position.
1026 A true mirror-image of @code{re-search-forward} would require a special
1027 feature for matching regular expressions from end to beginning. It's
1028 not worth the trouble of implementing that.
1031 @defun string-match regexp string &optional start
1032 This function returns the index of the start of the first match for
1033 the regular expression @var{regexp} in @var{string}, or @code{nil} if
1034 there is no match. If @var{start} is non-@code{nil}, the search starts
1035 at that index in @var{string}.
1042 "quick" "The quick brown fox jumped quickly.")
1047 "quick" "The quick brown fox jumped quickly." 8)
1053 The index of the first character of the
1054 string is 0, the index of the second character is 1, and so on.
1056 After this function returns, the index of the first character beyond
1057 the match is available as @code{(match-end 0)}. @xref{Match Data}.
1062 "quick" "The quick brown fox jumped quickly." 8)
1073 @defun string-match-p regexp string &optional start
1074 This predicate function does what @code{string-match} does, but it
1075 avoids modifying the match data.
1078 @defun looking-at regexp
1079 This function determines whether the text in the current buffer directly
1080 following point matches the regular expression @var{regexp}. ``Directly
1081 following'' means precisely that: the search is ``anchored'' and it can
1082 succeed only starting with the first character following point. The
1083 result is @code{t} if so, @code{nil} otherwise.
1085 This function does not move point, but it updates the match data, which
1086 you can access using @code{match-beginning} and @code{match-end}.
1087 @xref{Match Data}. If you need to test for a match without modifying
1088 the match data, use @code{looking-at-p}, described below.
1090 In this example, point is located directly before the @samp{T}. If it
1091 were anywhere else, the result would be @code{nil}.
1095 ---------- Buffer: foo ----------
1096 I read "@point{}The cat in the hat
1098 ---------- Buffer: foo ----------
1100 (looking-at "The cat in the hat$")
1106 @defun looking-back regexp &optional limit greedy
1107 This function returns @code{t} if @var{regexp} matches text before
1108 point, ending at point, and @code{nil} otherwise.
1110 Because regular expression matching works only going forward, this is
1111 implemented by searching backwards from point for a match that ends at
1112 point. That can be quite slow if it has to search a long distance.
1113 You can bound the time required by specifying @var{limit}, which says
1114 not to search before @var{limit}. In this case, the match that is
1115 found must begin at or after @var{limit}.
1117 If @var{greedy} is non-@code{nil}, this function extends the match
1118 backwards as far as possible, stopping when a single additional
1119 previous character cannot be part of a match for regexp. When the
1120 match is extended, its starting position is allowed to occur before
1125 ---------- Buffer: foo ----------
1126 I read "@point{}The cat in the hat
1128 ---------- Buffer: foo ----------
1130 (looking-back "read \"" 3)
1132 (looking-back "read \"" 4)
1138 @defun looking-at-p regexp
1139 This predicate function works like @code{looking-at}, but without
1140 updating the match data.
1143 @defvar search-spaces-regexp
1144 If this variable is non-@code{nil}, it should be a regular expression
1145 that says how to search for whitespace. In that case, any group of
1146 spaces in a regular expression being searched for stands for use of
1147 this regular expression. However, spaces inside of constructs such as
1148 @samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
1149 @code{search-spaces-regexp}.
1151 Since this variable affects all regular expression search and match
1152 constructs, you should bind it temporarily for as small as possible
1157 @section POSIX Regular Expression Searching
1159 The usual regular expression functions do backtracking when necessary
1160 to handle the @samp{\|} and repetition constructs, but they continue
1161 this only until they find @emph{some} match. Then they succeed and
1162 report the first match found.
1164 This section describes alternative search functions which perform the
1165 full backtracking specified by the POSIX standard for regular expression
1166 matching. They continue backtracking until they have tried all
1167 possibilities and found all matches, so they can report the longest
1168 match, as required by POSIX. This is much slower, so use these
1169 functions only when you really need the longest match.
1171 The POSIX search and match functions do not properly support the
1172 non-greedy repetition operators (@pxref{Regexp Special, non-greedy}).
1173 This is because POSIX backtracking conflicts with the semantics of
1174 non-greedy repetition.
1176 @deffn Command posix-search-forward regexp &optional limit noerror repeat
1177 This is like @code{re-search-forward} except that it performs the full
1178 backtracking specified by the POSIX standard for regular expression
1182 @deffn Command posix-search-backward regexp &optional limit noerror repeat
1183 This is like @code{re-search-backward} except that it performs the full
1184 backtracking specified by the POSIX standard for regular expression
1188 @defun posix-looking-at regexp
1189 This is like @code{looking-at} except that it performs the full
1190 backtracking specified by the POSIX standard for regular expression
1194 @defun posix-string-match regexp string &optional start
1195 This is like @code{string-match} except that it performs the full
1196 backtracking specified by the POSIX standard for regular expression
1201 @section The Match Data
1204 Emacs keeps track of the start and end positions of the segments of
1205 text found during a search; this is called the @dfn{match data}.
1206 Thanks to the match data, you can search for a complex pattern, such
1207 as a date in a mail message, and then extract parts of the match under
1208 control of the pattern.
1210 Because the match data normally describe the most recent search only,
1211 you must be careful not to do another search inadvertently between the
1212 search you wish to refer back to and the use of the match data. If you
1213 can't avoid another intervening search, you must save and restore the
1214 match data around it, to prevent it from being overwritten.
1216 Notice that all functions are allowed to overwrite the match data
1217 unless they're explicitly documented not to do so. A consequence is
1218 that functions that are run implicitly in the background
1219 (@pxref{Timers}, and @ref{Idle Timers}) should likely save and restore
1220 the match data explicitly.
1223 * Replacing Match:: Replacing a substring that was matched.
1224 * Simple Match Data:: Accessing single items of match data,
1225 such as where a particular subexpression started.
1226 * Entire Match Data:: Accessing the entire match data at once, as a list.
1227 * Saving Match Data:: Saving and restoring the match data.
1230 @node Replacing Match
1231 @subsection Replacing the Text that Matched
1232 @cindex replace matched text
1234 This function replaces all or part of the text matched by the last
1235 search. It works by means of the match data.
1237 @cindex case in replacements
1238 @defun replace-match replacement &optional fixedcase literal string subexp
1239 This function replaces the text in the buffer (or in @var{string}) that
1240 was matched by the last search. It replaces that text with
1243 If you did the last search in a buffer, you should specify @code{nil}
1244 for @var{string} and make sure that the current buffer when you call
1245 @code{replace-match} is the one in which you did the searching or
1246 matching. Then @code{replace-match} does the replacement by editing
1247 the buffer; it leaves point at the end of the replacement text, and
1250 If you did the search in a string, pass the same string as @var{string}.
1251 Then @code{replace-match} does the replacement by constructing and
1252 returning a new string.
1254 If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
1255 the replacement text without case conversion; otherwise, it converts
1256 the replacement text depending upon the capitalization of the text to
1257 be replaced. If the original text is all upper case, this converts
1258 the replacement text to upper case. If all words of the original text
1259 are capitalized, this capitalizes all the words of the replacement
1260 text. If all the words are one-letter and they are all upper case,
1261 they are treated as capitalized words rather than all-upper-case
1264 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1265 exactly as it is, the only alterations being case changes as needed.
1266 If it is @code{nil} (the default), then the character @samp{\} is treated
1267 specially. If a @samp{\} appears in @var{replacement}, then it must be
1268 part of one of the following sequences:
1272 @cindex @samp{&} in replacement
1273 @samp{\&} stands for the entire text being replaced.
1275 @item @samp{\@var{n}}
1276 @cindex @samp{\@var{n}} in replacement
1277 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1278 matched the @var{n}th subexpression in the original regexp.
1279 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1280 If the @var{n}th subexpression never matched, an empty string is substituted.
1283 @cindex @samp{\} in replacement
1284 @samp{\\} stands for a single @samp{\} in the replacement text.
1287 These substitutions occur after case conversion, if any,
1288 so the strings they substitute are never case-converted.
1290 If @var{subexp} is non-@code{nil}, that says to replace just
1291 subexpression number @var{subexp} of the regexp that was matched, not
1292 the entire match. For example, after matching @samp{foo \(ba*r\)},
1293 calling @code{replace-match} with 1 as @var{subexp} means to replace
1294 just the text that matched @samp{\(ba*r\)}.
1297 @defun match-substitute-replacement replacement &optional fixedcase literal string subexp
1298 This function returns the text that would be inserted into the buffer
1299 by @code{replace-match}, but without modifying the buffer. It is
1300 useful if you want to present the user with actual replacement result,
1301 with constructs like @samp{\@var{n}} or @samp{\&} substituted with
1302 matched groups. Arguments @var{replacement} and optional
1303 @var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the
1304 same meaning as for @code{replace-match}.
1307 @node Simple Match Data
1308 @subsection Simple Match Data Access
1310 This section explains how to use the match data to find out what was
1311 matched by the last search or match operation, if it succeeded.
1313 You can ask about the entire matching text, or about a particular
1314 parenthetical subexpression of a regular expression. The @var{count}
1315 argument in the functions below specifies which. If @var{count} is
1316 zero, you are asking about the entire match. If @var{count} is
1317 positive, it specifies which subexpression you want.
1319 Recall that the subexpressions of a regular expression are those
1320 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1321 @var{count}th subexpression is found by counting occurrences of
1322 @samp{\(} from the beginning of the whole regular expression. The first
1323 subexpression is numbered 1, the second 2, and so on. Only regular
1324 expressions can have subexpressions---after a simple string search, the
1325 only information available is about the entire match.
1327 Every successful search sets the match data. Therefore, you should
1328 query the match data immediately after searching, before calling any
1329 other function that might perform another search. Alternatively, you
1330 may save and restore the match data (@pxref{Saving Match Data}) around
1331 the call to functions that could perform another search.
1333 A search which fails may or may not alter the match data. In the
1334 past, a failing search did not do this, but we may change it in the
1335 future. So don't try to rely on the value of the match data after
1338 @defun match-string count &optional in-string
1339 This function returns, as a string, the text matched in the last search
1340 or match operation. It returns the entire text if @var{count} is zero,
1341 or just the portion corresponding to the @var{count}th parenthetical
1342 subexpression, if @var{count} is positive.
1344 If the last such operation was done against a string with
1345 @code{string-match}, then you should pass the same string as the
1346 argument @var{in-string}. After a buffer search or match,
1347 you should omit @var{in-string} or pass @code{nil} for it; but you
1348 should make sure that the current buffer when you call
1349 @code{match-string} is the one in which you did the searching or
1352 The value is @code{nil} if @var{count} is out of range, or for a
1353 subexpression inside a @samp{\|} alternative that wasn't used or a
1354 repetition that repeated zero times.
1357 @defun match-string-no-properties count &optional in-string
1358 This function is like @code{match-string} except that the result
1359 has no text properties.
1362 @defun match-beginning count
1363 This function returns the position of the start of text matched by the
1364 last regular expression searched for, or a subexpression of it.
1366 If @var{count} is zero, then the value is the position of the start of
1367 the entire match. Otherwise, @var{count} specifies a subexpression in
1368 the regular expression, and the value of the function is the starting
1369 position of the match for that subexpression.
1371 The value is @code{nil} for a subexpression inside a @samp{\|}
1372 alternative that wasn't used or a repetition that repeated zero times.
1375 @defun match-end count
1376 This function is like @code{match-beginning} except that it returns the
1377 position of the end of the match, rather than the position of the
1381 Here is an example of using the match data, with a comment showing the
1382 positions within the text:
1386 (string-match "\\(qu\\)\\(ick\\)"
1387 "The quick fox jumped quickly.")
1393 (match-string 0 "The quick fox jumped quickly.")
1395 (match-string 1 "The quick fox jumped quickly.")
1397 (match-string 2 "The quick fox jumped quickly.")
1402 (match-beginning 1) ; @r{The beginning of the match}
1403 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1407 (match-beginning 2) ; @r{The beginning of the match}
1408 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1412 (match-end 1) ; @r{The end of the match}
1413 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1415 (match-end 2) ; @r{The end of the match}
1416 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1420 Here is another example. Point is initially located at the beginning
1421 of the line. Searching moves point to between the space and the word
1422 @samp{in}. The beginning of the entire match is at the 9th character of
1423 the buffer (@samp{T}), and the beginning of the match for the first
1424 subexpression is at the 13th character (@samp{c}).
1429 (re-search-forward "The \\(cat \\)")
1431 (match-beginning 1))
1436 ---------- Buffer: foo ----------
1437 I read "The cat @point{}in the hat comes back" twice.
1440 ---------- Buffer: foo ----------
1445 (In this case, the index returned is a buffer position; the first
1446 character of the buffer counts as 1.)
1448 @node Entire Match Data
1449 @subsection Accessing the Entire Match Data
1451 The functions @code{match-data} and @code{set-match-data} read or
1452 write the entire match data, all at once.
1454 @defun match-data &optional integers reuse reseat
1455 This function returns a list of positions (markers or integers) that
1456 record all the information on what text the last search matched.
1457 Element zero is the position of the beginning of the match for the
1458 whole expression; element one is the position of the end of the match
1459 for the expression. The next two elements are the positions of the
1460 beginning and end of the match for the first subexpression, and so on.
1466 number {\mathsurround=0pt $2n$}
1468 corresponds to @code{(match-beginning @var{n})}; and
1474 number {\mathsurround=0pt $2n+1$}
1476 corresponds to @code{(match-end @var{n})}.
1478 Normally all the elements are markers or @code{nil}, but if
1479 @var{integers} is non-@code{nil}, that means to use integers instead
1480 of markers. (In that case, the buffer itself is appended as an
1481 additional element at the end of the list, to facilitate complete
1482 restoration of the match data.) If the last match was done on a
1483 string with @code{string-match}, then integers are always used,
1484 since markers can't point into a string.
1486 If @var{reuse} is non-@code{nil}, it should be a list. In that case,
1487 @code{match-data} stores the match data in @var{reuse}. That is,
1488 @var{reuse} is destructively modified. @var{reuse} does not need to
1489 have the right length. If it is not long enough to contain the match
1490 data, it is extended. If it is too long, the length of @var{reuse}
1491 stays the same, but the elements that were not used are set to
1492 @code{nil}. The purpose of this feature is to reduce the need for
1495 If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
1496 are reseated to point to nowhere.
1498 As always, there must be no possibility of intervening searches between
1499 the call to a search function and the call to @code{match-data} that is
1500 intended to access the match data for that search.
1505 @result{} (#<marker at 9 in foo>
1506 #<marker at 17 in foo>
1507 #<marker at 13 in foo>
1508 #<marker at 17 in foo>)
1513 @defun set-match-data match-list &optional reseat
1514 This function sets the match data from the elements of @var{match-list},
1515 which should be a list that was the value of a previous call to
1516 @code{match-data}. (More precisely, anything that has the same format
1519 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1520 an error; that sets the match data in a meaningless but harmless way.
1522 If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
1523 are reseated to point to nowhere.
1525 @findex store-match-data
1526 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1529 @node Saving Match Data
1530 @subsection Saving and Restoring the Match Data
1532 When you call a function that may do a search, you may need to save
1533 and restore the match data around that call, if you want to preserve the
1534 match data from an earlier search for later use. Here is an example
1535 that shows the problem that arises if you fail to save the match data:
1539 (re-search-forward "The \\(cat \\)")
1541 (foo) ; @r{Perhaps @code{foo} does}
1542 ; @r{more searching.}
1544 @result{} 61 ; @r{Unexpected result---not 48!}
1548 You can save and restore the match data with @code{save-match-data}:
1550 @defmac save-match-data body@dots{}
1551 This macro executes @var{body}, saving and restoring the match
1552 data around it. The return value is the value of the last form in
1556 You could use @code{set-match-data} together with @code{match-data} to
1557 imitate the effect of the special form @code{save-match-data}. Here is
1562 (let ((data (match-data)))
1564 @dots{} ; @r{Ok to change the original match data.}
1565 (set-match-data data)))
1569 Emacs automatically saves and restores the match data when it runs
1570 process filter functions (@pxref{Filter Functions}) and process
1571 sentinels (@pxref{Sentinels}).
1574 Here is a function which restores the match data provided the buffer
1575 associated with it still exists.
1579 (defun restore-match-data (data)
1580 @c It is incorrect to split the first line of a doc string.
1581 @c If there's a problem here, it should be solved in some other way.
1582 "Restore the match data DATA unless the buffer is missing."
1588 (null (marker-buffer (car d)))
1590 ;; @file{match-data} @r{buffer is deleted.}
1593 (set-match-data data))))
1598 @node Search and Replace
1599 @section Search and Replace
1600 @cindex replacement after search
1601 @cindex searching and replacing
1603 If you want to find all matches for a regexp in part of the buffer,
1604 and replace them, the best way is to write an explicit loop using
1605 @code{re-search-forward} and @code{replace-match}, like this:
1608 (while (re-search-forward "foo[ \t]+bar" nil t)
1609 (replace-match "foobar"))
1613 @xref{Replacing Match,, Replacing the Text that Matched}, for a
1614 description of @code{replace-match}.
1616 However, replacing matches in a string is more complex, especially
1617 if you want to do it efficiently. So Emacs provides a function to do
1620 @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
1621 This function copies @var{string} and searches it for matches for
1622 @var{regexp}, and replaces them with @var{rep}. It returns the
1623 modified copy. If @var{start} is non-@code{nil}, the search for
1624 matches starts at that index in @var{string}, so matches starting
1625 before that index are not changed.
1627 This function uses @code{replace-match} to do the replacement, and it
1628 passes the optional arguments @var{fixedcase}, @var{literal} and
1629 @var{subexp} along to @code{replace-match}.
1631 Instead of a string, @var{rep} can be a function. In that case,
1632 @code{replace-regexp-in-string} calls @var{rep} for each match,
1633 passing the text of the match as its sole argument. It collects the
1634 value @var{rep} returns and passes that to @code{replace-match} as the
1635 replacement string. The match-data at this point are the result
1636 of matching @var{regexp} against a substring of @var{string}.
1639 If you want to write a command along the lines of @code{query-replace},
1640 you can use @code{perform-replace} to do the work.
1642 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
1643 This function is the guts of @code{query-replace} and related
1644 commands. It searches for occurrences of @var{from-string} in the
1645 text between positions @var{start} and @var{end} and replaces some or
1646 all of them. If @var{start} is @code{nil} (or omitted), point is used
1647 instead, and the end of the buffer's accessible portion is used for
1650 If @var{query-flag} is @code{nil}, it replaces all
1651 occurrences; otherwise, it asks the user what to do about each one.
1653 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
1654 considered a regular expression; otherwise, it must match literally. If
1655 @var{delimited-flag} is non-@code{nil}, then only replacements
1656 surrounded by word boundaries are considered.
1658 The argument @var{replacements} specifies what to replace occurrences
1659 with. If it is a string, that string is used. It can also be a list of
1660 strings, to be used in cyclic order.
1662 If @var{replacements} is a cons cell, @w{@code{(@var{function}
1663 . @var{data})}}, this means to call @var{function} after each match to
1664 get the replacement text. This function is called with two arguments:
1665 @var{data}, and the number of replacements already made.
1667 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
1668 it specifies how many times to use each of the strings in the
1669 @var{replacements} list before advancing cyclically to the next one.
1671 If @var{from-string} contains upper-case letters, then
1672 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
1673 it uses the @code{replacements} without altering the case of them.
1675 Normally, the keymap @code{query-replace-map} defines the possible
1676 user responses for queries. The argument @var{map}, if
1677 non-@code{nil}, specifies a keymap to use instead of
1678 @code{query-replace-map}.
1680 This function uses one of two functions to search for the next
1681 occurrence of @var{from-string}. These functions are specified by the
1682 values of two variables: @code{replace-re-search-function} and
1683 @code{replace-search-function}. The former is called when the
1684 argument @var{regexp-flag} is non-@code{nil}, the latter when it is
1688 @defvar query-replace-map
1689 This variable holds a special keymap that defines the valid user
1690 responses for @code{perform-replace} and the commands that use it, as
1691 well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual
1696 The ``key bindings'' are not commands, just symbols that are meaningful
1697 to the functions that use this map.
1700 Prefix keys are not supported; each key binding must be for a
1701 single-event key sequence. This is because the functions don't use
1702 @code{read-key-sequence} to get the input; instead, they read a single
1703 event and look it up ``by hand.''
1707 Here are the meaningful ``bindings'' for @code{query-replace-map}.
1708 Several of them are meaningful only for @code{query-replace} and
1713 Do take the action being considered---in other words, ``yes.''
1716 Do not take action for this question---in other words, ``no.''
1719 Answer this question ``no,'' and give up on the entire series of
1720 questions, assuming that the answers will be ``no.''
1723 Answer this question ``yes,'' and give up on the entire series of
1724 questions, assuming that subsequent answers will be ``no.''
1727 Answer this question ``yes,'' but show the results---don't advance yet
1728 to the next question.
1731 Answer this question and all subsequent questions in the series with
1732 ``yes,'' without further user interaction.
1735 Move back to the previous place that a question was asked about.
1738 Enter a recursive edit to deal with this question---instead of any
1739 other action that would normally be taken.
1741 @item delete-and-edit
1742 Delete the text being considered, then enter a recursive edit to replace
1746 Redisplay and center the window, then ask the same question again.
1749 Perform a quit right away. Only @code{y-or-n-p} and related functions
1753 Display some help, then ask again.
1756 @defvar multi-query-replace-map
1757 This variable holds a keymap that extends @code{query-replace-map} by
1758 providing additional keybindings that are useful in multi-buffer
1762 @defvar replace-search-function
1763 This variable specifies a function that @code{perform-replace} calls
1764 to search for the next string to replace. Its default value is
1765 @code{search-forward}. Any other value should name a function of 3
1766 arguments: the first 3 arguments of @code{search-forward}
1767 (@pxref{String Search}).
1770 @defvar replace-re-search-function
1771 This variable specifies a function that @code{perform-replace} calls
1772 to search for the next regexp to replace. Its default value is
1773 @code{re-search-forward}. Any other value should name a function of 3
1774 arguments: the first 3 arguments of @code{re-search-forward}
1775 (@pxref{Regexp Search}).
1778 @node Standard Regexps
1779 @section Standard Regular Expressions Used in Editing
1780 @cindex regexps used standardly in editing
1781 @cindex standard regexps used in editing
1783 This section describes some variables that hold regular expressions
1784 used for certain purposes in editing:
1786 @defopt page-delimiter
1787 This is the regular expression describing line-beginnings that separate
1788 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1789 @code{"^\C-l"}); this matches a line that starts with a formfeed
1793 The following two regular expressions should @emph{not} assume the
1794 match always starts at the beginning of a line; they should not use
1795 @samp{^} to anchor the match. Most often, the paragraph commands do
1796 check for a match only at the beginning of a line, which means that
1797 @samp{^} would be superfluous. When there is a nonzero left margin,
1798 they accept matches that start after the left margin. In that case, a
1799 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1800 where a left margin is never used.
1802 @defopt paragraph-separate
1803 This is the regular expression for recognizing the beginning of a line
1804 that separates paragraphs. (If you change this, you may have to
1805 change @code{paragraph-start} also.) The default value is
1806 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1807 spaces, tabs, and form feeds (after its left margin).
1810 @defopt paragraph-start
1811 This is the regular expression for recognizing the beginning of a line
1812 that starts @emph{or} separates paragraphs. The default value is
1813 @w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
1814 whitespace or starting with a form feed (after its left margin).
1817 @defopt sentence-end
1818 If non-@code{nil}, the value should be a regular expression describing
1819 the end of a sentence, including the whitespace following the
1820 sentence. (All paragraph boundaries also end sentences, regardless.)
1822 If the value is @code{nil}, the default, then the function
1823 @code{sentence-end} has to construct the regexp. That is why you
1824 should always call the function @code{sentence-end} to obtain the
1825 regexp to be used to recognize the end of a sentence.
1829 This function returns the value of the variable @code{sentence-end},
1830 if non-@code{nil}. Otherwise it returns a default value based on the
1831 values of the variables @code{sentence-end-double-space}
1832 (@pxref{Definition of sentence-end-double-space}),
1833 @code{sentence-end-without-period} and
1834 @code{sentence-end-without-space}.