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 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).
54 In the following example, point is initially at the beginning of the
55 line. Then @code{(search-forward "fox")} moves point after the last
60 ---------- Buffer: foo ----------
61 @point{}The quick brown fox jumped over the lazy dog.
62 ---------- Buffer: foo ----------
66 (search-forward "fox")
69 ---------- Buffer: foo ----------
70 The quick brown fox@point{} jumped over the lazy dog.
71 ---------- Buffer: foo ----------
75 The argument @var{limit} specifies the upper bound to the search. (It
76 must be a position in the current buffer.) No match extending after
77 that position is accepted. If @var{limit} is omitted or @code{nil}, it
78 defaults to the end of the accessible portion of the buffer.
81 What happens when the search fails depends on the value of
82 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
83 error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
84 returns @code{nil} and does nothing. If @var{noerror} is neither
85 @code{nil} nor @code{t}, then @code{search-forward} moves point to the
86 upper bound and returns @code{nil}. (It would be more consistent now to
87 return the new position of point in that case, but some existing
88 programs may depend on a value of @code{nil}.)
90 The argument @var{noerror} only affects valid searches which fail to
91 find a match. Invalid arguments cause errors regardless of
94 If @var{repeat} is supplied (it must be a positive number), then the
95 search is repeated that many times (each time starting at the end of the
96 previous time's match). If these successive searches succeed, the
97 function succeeds, moving point and returning its new value. Otherwise
98 the search fails, with results depending on the value of
99 @var{noerror}, as described above.
102 @deffn Command search-backward string &optional limit noerror repeat
103 This function searches backward from point for @var{string}. It is
104 just like @code{search-forward} except that it searches backwards and
105 leaves point at the beginning of the match.
108 @deffn Command word-search-forward string &optional limit noerror repeat
109 This function searches forward from point for a ``word'' match for
110 @var{string}. If it finds a match, it sets point to the end of the
111 match found, and returns the new value of point.
113 Word matching regards @var{string} as a sequence of words, disregarding
114 punctuation that separates them. It searches the buffer for the same
115 sequence of words. Each word must be distinct in the buffer (searching
116 for the word @samp{ball} does not match the word @samp{balls}), but the
117 details of punctuation and spacing are ignored (searching for @samp{ball
118 boy} does match @samp{ball. Boy!}).
120 In this example, point is initially at the beginning of the buffer; the
121 search leaves it between the @samp{y} and the @samp{!}.
125 ---------- Buffer: foo ----------
126 @point{}He said "Please! Find
128 ---------- Buffer: foo ----------
132 (word-search-forward "Please find the ball, boy.")
135 ---------- Buffer: foo ----------
136 He said "Please! Find
137 the ball boy@point{}!"
138 ---------- Buffer: foo ----------
142 If @var{limit} is non-@code{nil}, it must be a position in the current
143 buffer; it specifies the upper bound to the search. The match found
144 must not extend after that position.
146 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
147 an error if the search fails. If @var{noerror} is @code{t}, then it
148 returns @code{nil} instead of signaling an error. If @var{noerror} is
149 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
150 end of the accessible portion of the buffer) and returns @code{nil}.
152 If @var{repeat} is non-@code{nil}, then the search is repeated that many
153 times. Point is positioned at the end of the last match.
156 @deffn Command word-search-forward-lax string &optional limit noerror repeat
157 This command is identical to @code{word-search-forward}, except that
158 the end of @code{string} need not match a word boundary unless it ends
159 in whitespace. For instance, searching for @samp{ball boy} matches
160 @samp{ball boyee}, but does not match @samp{aball boy}.
163 @deffn Command word-search-backward string &optional limit noerror repeat
164 This function searches backward from point for a word match to
165 @var{string}. This function is just like @code{word-search-forward}
166 except that it searches backward and normally leaves point at the
167 beginning of the match.
170 @deffn Command word-search-backward-lax string &optional limit noerror repeat
171 This command is identical to @code{word-search-backward}, except that
172 the end of @code{string} need not match a word boundary unless it ends
176 @node Searching and Case
177 @section Searching and Case
178 @cindex searching and case
180 By default, searches in Emacs ignore the case of the text they are
181 searching through; if you specify searching for @samp{FOO}, then
182 @samp{Foo} or @samp{foo} is also considered a match. This applies to
183 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
184 @samp{A} or @samp{b} or @samp{B}.
186 If you do not want this feature, set the variable
187 @code{case-fold-search} to @code{nil}. Then all letters must match
188 exactly, including case. This is a buffer-local variable; altering the
189 variable affects only the current buffer. (@xref{Intro to
190 Buffer-Local}.) Alternatively, you may change the default value of
191 @code{case-fold-search}.
193 Note that the user-level incremental search feature handles case
194 distinctions differently. When the search string contains only lower
195 case letters, the search ignores case, but when the search string
196 contains one or more upper case letters, the search becomes
197 case-sensitive. But this has nothing to do with the searching
198 functions used in Lisp code.
200 @defopt case-fold-search
201 This buffer-local variable determines whether searches should ignore
202 case. If the variable is @code{nil} they do not ignore case; otherwise
207 This variable determines whether the higher level replacement
208 functions should preserve case. If the variable is @code{nil}, that
209 means to use the replacement text verbatim. A non-@code{nil} value
210 means to convert the case of the replacement text according to the
213 This variable is used by passing it as an argument to the function
214 @code{replace-match}. @xref{Replacing Match}.
217 @node Regular Expressions
218 @section Regular Expressions
219 @cindex regular expression
222 A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that
223 denotes a (possibly infinite) set of strings. Searching for matches for
224 a regexp is a very powerful operation. This section explains how to write
225 regexps; the following section says how to search for them.
228 @cindex regular expressions, developing
229 For convenient interactive development of regular expressions, you
230 can use the @kbd{M-x re-builder} command. It provides a convenient
231 interface for creating regular expressions, by giving immediate visual
232 feedback in a separate buffer. As you edit the regexp, all its
233 matches in the target buffer are highlighted. Each parenthesized
234 sub-expression of the regexp is shown in a distinct face, which makes
235 it easier to verify even very complex regexps.
238 * Syntax of Regexps:: Rules for writing regular expressions.
239 * Regexp Example:: Illustrates regular expression syntax.
240 * Regexp Functions:: Functions for operating on regular expressions.
243 @node Syntax of Regexps
244 @subsection Syntax of Regular Expressions
246 Regular expressions have a syntax in which a few characters are
247 special constructs and the rest are @dfn{ordinary}. An ordinary
248 character is a simple regular expression that matches that character
249 and nothing else. The special characters are @samp{.}, @samp{*},
250 @samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
251 special characters will be defined in the future. The character
252 @samp{]} is special if it ends a character alternative (see later).
253 The character @samp{-} is special inside a character alternative. A
254 @samp{[:} and balancing @samp{:]} enclose a character class inside a
255 character alternative. Any other character appearing in a regular
256 expression is ordinary, unless a @samp{\} precedes it.
258 For example, @samp{f} is not a special character, so it is ordinary, and
259 therefore @samp{f} is a regular expression that matches the string
260 @samp{f} and no other string. (It does @emph{not} match the string
261 @samp{fg}, but it does match a @emph{part} of that string.) Likewise,
262 @samp{o} is a regular expression that matches only @samp{o}.@refill
264 Any two regular expressions @var{a} and @var{b} can be concatenated. The
265 result is a regular expression that matches a string if @var{a} matches
266 some amount of the beginning of that string and @var{b} matches the rest of
269 As a simple example, we can concatenate the regular expressions @samp{f}
270 and @samp{o} to get the regular expression @samp{fo}, which matches only
271 the string @samp{fo}. Still trivial. To do something more powerful, you
272 need to use one of the special regular expression constructs.
275 * Regexp Special:: Special characters in regular expressions.
276 * Char Classes:: Character classes used in regular expressions.
277 * Regexp Backslash:: Backslash-sequences in regular expressions.
281 @subsubsection Special Characters in Regular Expressions
283 Here is a list of the characters that are special in a regular
288 @item @samp{.}@: @r{(Period)}
289 @cindex @samp{.} in regexp
290 is a special character that matches any single character except a newline.
291 Using concatenation, we can make regular expressions like @samp{a.b}, which
292 matches any three-character string that begins with @samp{a} and ends with
296 @cindex @samp{*} in regexp
297 is not a construct by itself; it is a postfix operator that means to
298 match the preceding regular expression repetitively as many times as
299 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
302 @samp{*} always applies to the @emph{smallest} possible preceding
303 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
304 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
306 The matcher processes a @samp{*} construct by matching, immediately, as
307 many repetitions as can be found. Then it continues with the rest of
308 the pattern. If that fails, backtracking occurs, discarding some of the
309 matches of the @samp{*}-modified construct in the hope that that will
310 make it possible to match the rest of the pattern. For example, in
311 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
312 first tries to match all three @samp{a}s; but the rest of the pattern is
313 @samp{ar} and there is only @samp{r} left to match, so this try fails.
314 The next alternative is for @samp{a*} to match only two @samp{a}s. With
315 this choice, the rest of the regexp matches successfully.
317 @strong{Warning:} Nested repetition operators can run for an
318 indefinitely long time, if they lead to ambiguous matching. For
319 example, trying to match the regular expression @samp{\(x+y*\)*a}
320 against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could
321 take hours before it ultimately fails. Emacs must try each way of
322 grouping the @samp{x}s before concluding that none of them can work.
323 Even worse, @samp{\(x*\)*} can match the null string in infinitely
324 many ways, so it causes an infinite loop. To avoid these problems,
325 check nested repetitions carefully, to make sure that they do not
326 cause combinatorial explosions in backtracking.
329 @cindex @samp{+} in regexp
330 is a postfix operator, similar to @samp{*} except that it must match
331 the preceding expression at least once. So, for example, @samp{ca+r}
332 matches the strings @samp{car} and @samp{caaaar} but not the string
333 @samp{cr}, whereas @samp{ca*r} matches all three strings.
336 @cindex @samp{?} in regexp
337 is a postfix operator, similar to @samp{*} except that it must match the
338 preceding expression either once or not at all. For example,
339 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
341 @item @samp{*?}, @samp{+?}, @samp{??}
342 @cindex non-greedy repetition characters in regexp
343 These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
344 and @samp{?}. Where those operators match the largest possible
345 substring (consistent with matching the entire containing expression),
346 the non-greedy variants match the smallest possible substring
347 (consistent with matching the entire containing expression).
349 For example, the regular expression @samp{c[ad]*a} when applied to the
350 string @samp{cdaaada} matches the whole string; but the regular
351 expression @samp{c[ad]*?a}, applied to that same string, matches just
352 @samp{cda}. (The smallest possible match here for @samp{[ad]*?} that
353 permits the whole expression to match is @samp{d}.)
355 @item @samp{[ @dots{} ]}
356 @cindex character alternative (in regexp)
357 @cindex @samp{[} in regexp
358 @cindex @samp{]} in regexp
359 is a @dfn{character alternative}, which begins with @samp{[} and is
360 terminated by @samp{]}. In the simplest case, the characters between
361 the two brackets are what this character alternative can match.
363 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
364 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
365 (including the empty string), from which it follows that @samp{c[ad]*r}
366 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
368 You can also include character ranges in a character alternative, by
369 writing the starting and ending characters with a @samp{-} between them.
370 Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
371 Ranges may be intermixed freely with individual characters, as in
372 @samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
373 or @samp{$}, @samp{%} or period.
375 Note that the usual regexp special characters are not special inside a
376 character alternative. A completely different set of characters is
377 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
379 To include a @samp{]} in a character alternative, you must make it the
380 first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
381 To include a @samp{-}, write @samp{-} as the first or last character of
382 the character alternative, or put it after a range. Thus, @samp{[]-]}
383 matches both @samp{]} and @samp{-}.
385 To include @samp{^} in a character alternative, put it anywhere but at
388 The beginning and end of a range of multibyte characters must be in
389 the same character set (@pxref{Character Sets}). Thus,
390 @code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a}
391 with grave accent) is in the Emacs character set for Latin-1 but the
392 character 0x97c (@samp{u} with diaeresis) is in the Emacs character
393 set for Latin-2. (We use Lisp string syntax to write that example,
394 and a few others in the next few paragraphs, in order to include hex
395 escape sequences in them.)
397 If a range starts with a unibyte character @var{c} and ends with a
398 multibyte character @var{c2}, the range is divided into two parts: one
399 is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
400 @var{c1} is the first character of the charset to which @var{c2}
403 You cannot always match all non-@acronym{ASCII} characters with the
404 regular expression @code{"[\200-\377]"}. This works when searching a
405 unibyte buffer or string (@pxref{Text Representations}), but not in a
406 multibyte buffer or string, because many non-@acronym{ASCII}
407 characters have codes above @code{#o377}. However, the regular
408 expression @code{"[^\000-\177]"} does match all non-@acronym{ASCII}
409 characters (see below regarding @samp{^}), in both multibyte and
410 unibyte representations, because only the @acronym{ASCII} characters
413 A character alternative can also specify named
414 character classes (@pxref{Char Classes}). This is a POSIX feature whose
415 syntax is @samp{[:@var{class}:]}. Using a character class is equivalent
416 to mentioning each of the characters in that class; but the latter is
417 not feasible in practice, since some classes include thousands of
418 different characters.
420 @item @samp{[^ @dots{} ]}
421 @cindex @samp{^} in regexp
422 @samp{[^} begins a @dfn{complemented character alternative}. This
423 matches any character except the ones specified. Thus,
424 @samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
427 @samp{^} is not special in a character alternative unless it is the first
428 character. The character following the @samp{^} is treated as if it
429 were first (in other words, @samp{-} and @samp{]} are not special there).
431 A complemented character alternative can match a newline, unless newline is
432 mentioned as one of the characters not to match. This is in contrast to
433 the handling of regexps in programs such as @code{grep}.
436 @cindex beginning of line in regexp
437 When matching a buffer, @samp{^} matches the empty string, but only at the
438 beginning of a line in the text being matched (or the beginning of the
439 accessible portion of the buffer). Otherwise it fails to match
440 anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the
443 When matching a string instead of a buffer, @samp{^} matches at the
444 beginning of the string or after a newline character.
446 For historical compatibility reasons, @samp{^} can be used only at the
447 beginning of the regular expression, or after @samp{\(}, @samp{\(?:}
451 @cindex @samp{$} in regexp
452 @cindex end of line in regexp
453 is similar to @samp{^} but matches only at the end of a line (or the
454 end of the accessible portion of the buffer). Thus, @samp{x+$}
455 matches a string of one @samp{x} or more at the end of a line.
457 When matching a string instead of a buffer, @samp{$} matches at the end
458 of the string or before a newline character.
460 For historical compatibility reasons, @samp{$} can be used only at the
461 end of the regular expression, or before @samp{\)} or @samp{\|}.
464 @cindex @samp{\} in regexp
465 has two functions: it quotes the special characters (including
466 @samp{\}), and it introduces additional special constructs.
468 Because @samp{\} quotes special characters, @samp{\$} is a regular
469 expression that matches only @samp{$}, and @samp{\[} is a regular
470 expression that matches only @samp{[}, and so on.
472 Note that @samp{\} also has special meaning in the read syntax of Lisp
473 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
474 example, the regular expression that matches the @samp{\} character is
475 @samp{\\}. To write a Lisp string that contains the characters
476 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
477 @samp{\}. Therefore, the read syntax for a regular expression matching
478 @samp{\} is @code{"\\\\"}.@refill
481 @strong{Please note:} For historical compatibility, special characters
482 are treated as ordinary ones if they are in contexts where their special
483 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
484 ordinary since there is no preceding expression on which the @samp{*}
485 can act. It is poor practice to depend on this behavior; quote the
486 special character anyway, regardless of where it appears.@refill
488 As a @samp{\} is not special inside a character alternative, it can
489 never remove the special meaning of @samp{-} or @samp{]}. So you
490 should not quote these characters when they have no special meaning
491 either. This would not clarify anything, since backslashes can
492 legitimately precede these characters where they @emph{have} special
493 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
494 which matches any single character except a backslash.
496 In practice, most @samp{]} that occur in regular expressions close a
497 character alternative and hence are special. However, occasionally a
498 regular expression may try to match a complex pattern of literal
499 @samp{[} and @samp{]}. In such situations, it sometimes may be
500 necessary to carefully parse the regexp from the start to determine
501 which square brackets enclose a character alternative. For example,
502 @samp{[^][]]} consists of the complemented character alternative
503 @samp{[^][]} (which matches any single character that is not a square
504 bracket), followed by a literal @samp{]}.
506 The exact rules are that at the beginning of a regexp, @samp{[} is
507 special and @samp{]} not. This lasts until the first unquoted
508 @samp{[}, after which we are in a character alternative; @samp{[} is
509 no longer special (except when it starts a character class) but @samp{]}
510 is special, unless it immediately follows the special @samp{[} or that
511 @samp{[} followed by a @samp{^}. This lasts until the next special
512 @samp{]} that does not end a character class. This ends the character
513 alternative and restores the ordinary syntax of regular expressions;
514 an unquoted @samp{[} is special again and a @samp{]} not.
517 @subsubsection Character Classes
518 @cindex character classes in regexp
520 Here is a table of the classes you can use in a character alternative,
525 This matches any @acronym{ASCII} character (codes 0--127).
527 This matches any letter or digit. (At present, for multibyte
528 characters, it matches anything that has word syntax.)
530 This matches any letter. (At present, for multibyte characters, it
531 matches anything that has word syntax.)
533 This matches space and tab only.
535 This matches any @acronym{ASCII} control character.
537 This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
538 matches any digit, as well as @samp{+} and @samp{-}.
540 This matches graphic characters---everything except @acronym{ASCII} control
541 characters, space, and the delete character.
543 This matches any lower-case letter, as determined by the current case
544 table (@pxref{Case Tables}). If @code{case-fold-search} is
545 non-@code{nil}, this also matches any upper-case letter.
547 This matches any multibyte character (@pxref{Text Representations}).
549 This matches any non-@acronym{ASCII} character.
551 This matches printing characters---everything except @acronym{ASCII} control
552 characters and the delete character.
554 This matches any punctuation character. (At present, for multibyte
555 characters, it matches anything that has non-word syntax.)
557 This matches any character that has whitespace syntax
558 (@pxref{Syntax Class Table}).
560 This matches any unibyte character (@pxref{Text Representations}).
562 This matches any upper-case letter, as determined by the current case
563 table (@pxref{Case Tables}). If @code{case-fold-search} is
564 non-@code{nil}, this also matches any lower-case letter.
566 This matches any character that has word syntax (@pxref{Syntax Class
569 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
570 through @samp{f} and @samp{A} through @samp{F}.
573 @node Regexp Backslash
574 @subsubsection Backslash Constructs in Regular Expressions
576 For the most part, @samp{\} followed by any character matches only
577 that character. However, there are several exceptions: certain
578 two-character sequences starting with @samp{\} that have special
579 meanings. (The character after the @samp{\} in such a sequence is
580 always ordinary when used on its own.) Here is a table of the special
585 @cindex @samp{|} in regexp
586 @cindex regexp alternative
587 specifies an alternative.
588 Two regular expressions @var{a} and @var{b} with @samp{\|} in
589 between form an expression that matches anything that either @var{a} or
590 @var{b} matches.@refill
592 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
593 but no other string.@refill
595 @samp{\|} applies to the largest possible surrounding expressions. Only a
596 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
599 If you need full backtracking capability to handle multiple uses of
600 @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
604 is a postfix operator that repeats the previous pattern exactly @var{m}
605 times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
606 and nothing else. @samp{c[ad]\@{3\@}r} matches string such as
607 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
609 @item \@{@var{m},@var{n}\@}
610 is a more general postfix operator that specifies repetition with a
611 minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m}
612 is omitted, the minimum is 0; if @var{n} is omitted, there is no
615 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
616 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
618 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @*
619 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @*
620 @samp{\@{1,\@}} is equivalent to @samp{+}.
623 @cindex @samp{(} in regexp
624 @cindex @samp{)} in regexp
625 @cindex regexp grouping
626 is a grouping construct that serves three purposes:
630 To enclose a set of @samp{\|} alternatives for other operations. Thus,
631 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
635 To enclose a complicated expression for the postfix operators @samp{*},
636 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
637 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
638 number (zero or more) of @samp{na} strings.
641 To record a matched substring for future reference with
642 @samp{\@var{digit}} (see below).
645 This last application is not a consequence of the idea of a
646 parenthetical grouping; it is a separate feature that was assigned as a
647 second meaning to the same @samp{\( @dots{} \)} construct because, in
648 practice, there was usually no conflict between the two meanings. But
649 occasionally there is a conflict, and that led to the introduction of
652 @item \(?: @dots{} \)
654 @cindex non-capturing group
655 @cindex unnumbered group
656 @cindex @samp{(?:} in regexp
657 is the @dfn{shy group} construct. A shy group serves the first two
658 purposes of an ordinary group (controlling the nesting of other
659 operators), but it does not get a number, so you cannot refer back to
660 its value with @samp{\@var{digit}}. Shy groups are particularly
661 useful for mechanically-constructed regular expressions, because they
662 can be added automatically without altering the numbering of ordinary,
665 Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered
668 @item \(?@var{num}: @dots{} \)
669 is the @dfn{explicitly numbered group} construct. Normal groups get
670 their number implicitly, based on their position, which can be
671 inconvenient. This construct allows you to force a particular group
672 number. There is no particular restriction on the numbering,
673 e.g.@: you can have several groups with the same number in which case
674 the last one to match (i.e.@: the rightmost match) will win.
675 Implicitly numbered groups always get the smallest integer larger than
676 the one of any previous group.
679 matches the same text that matched the @var{digit}th occurrence of a
680 grouping (@samp{\( @dots{} \)}) construct.
682 In other words, after the end of a group, the matcher remembers the
683 beginning and end of the text matched by that group. Later on in the
684 regular expression you can use @samp{\} followed by @var{digit} to
685 match that same text, whatever it may have been.
687 The strings matching the first nine grouping constructs appearing in
688 the entire regular expression passed to a search or matching function
689 are assigned numbers 1 through 9 in the order that the open
690 parentheses appear in the regular expression. So you can use
691 @samp{\1} through @samp{\9} to refer to the text matched by the
692 corresponding grouping constructs.
694 For example, @samp{\(.*\)\1} matches any newline-free string that is
695 composed of two identical halves. The @samp{\(.*\)} matches the first
696 half, which may be anything, but the @samp{\1} that follows must match
699 If a @samp{\( @dots{} \)} construct matches more than once (which can
700 happen, for instance, if it is followed by @samp{*}), only the last
703 If a particular grouping construct in the regular expression was never
704 matched---for instance, if it appears inside of an alternative that
705 wasn't used, or inside of a repetition that repeated zero times---then
706 the corresponding @samp{\@var{digit}} construct never matches
707 anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2}
708 cannot match @samp{lose}: the second alternative inside the larger
709 group matches it, but then @samp{\2} is undefined and can't match
710 anything. But it can match @samp{foobb}, because the first
711 alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
714 @cindex @samp{\w} in regexp
715 matches any word-constituent character. The editor syntax table
716 determines which characters these are. @xref{Syntax Tables}.
719 @cindex @samp{\W} in regexp
720 matches any character that is not a word constituent.
723 @cindex @samp{\s} in regexp
724 matches any character whose syntax is @var{code}. Here @var{code} is a
725 character that represents a syntax code: thus, @samp{w} for word
726 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
727 etc. To represent whitespace syntax, use either @samp{-} or a space
728 character. @xref{Syntax Class Table}, for a list of syntax codes and
729 the characters that stand for them.
732 @cindex @samp{\S} in regexp
733 matches any character whose syntax is not @var{code}.
736 matches any character whose category is @var{c}. Here @var{c} is a
737 character that represents a category: thus, @samp{c} for Chinese
738 characters or @samp{g} for Greek characters in the standard category
742 matches any character whose category is not @var{c}.
745 The following regular expression constructs match the empty string---that is,
746 they don't use up any characters---but whether they match depends on the
747 context. For all, the beginning and end of the accessible portion of
748 the buffer are treated as if they were the actual beginning and end of
753 @cindex @samp{\`} in regexp
754 matches the empty string, but only at the beginning
755 of the buffer or string being matched against.
758 @cindex @samp{\'} in regexp
759 matches the empty string, but only at the end of
760 the buffer or string being matched against.
763 @cindex @samp{\=} in regexp
764 matches the empty string, but only at point.
765 (This construct is not defined when matching against a string.)
768 @cindex @samp{\b} in regexp
769 matches the empty string, but only at the beginning or
770 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
771 @samp{foo} as a separate word. @samp{\bballs?\b} matches
772 @samp{ball} or @samp{balls} as a separate word.@refill
774 @samp{\b} matches at the beginning or end of the buffer (or string)
775 regardless of what text appears next to it.
778 @cindex @samp{\B} in regexp
779 matches the empty string, but @emph{not} at the beginning or
780 end of a word, nor at the beginning or end of the buffer (or string).
783 @cindex @samp{\<} in regexp
784 matches the empty string, but only at the beginning of a word.
785 @samp{\<} matches at the beginning of the buffer (or string) only if a
786 word-constituent character follows.
789 @cindex @samp{\>} in regexp
790 matches the empty string, but only at the end of a word. @samp{\>}
791 matches at the end of the buffer (or string) only if the contents end
792 with a word-constituent character.
795 @cindex @samp{\_<} in regexp
796 matches the empty string, but only at the beginning of a symbol. A
797 symbol is a sequence of one or more word or symbol constituent
798 characters. @samp{\_<} matches at the beginning of the buffer (or
799 string) only if a symbol-constituent character follows.
802 @cindex @samp{\_>} in regexp
803 matches the empty string, but only at the end of a symbol. @samp{\_>}
804 matches at the end of the buffer (or string) only if the contents end
805 with a symbol-constituent character.
808 @kindex invalid-regexp
809 Not every string is a valid regular expression. For example, a string
810 that ends inside a character alternative without terminating @samp{]}
811 is invalid, and so is a string that ends with a single @samp{\}. If
812 an invalid regular expression is passed to any of the search functions,
813 an @code{invalid-regexp} error is signaled.
816 @comment node-name, next, previous, up
817 @subsection Complex Regexp Example
819 Here is a complicated regexp which was formerly used by Emacs to
820 recognize the end of a sentence together with any whitespace that
821 follows. (Nowadays Emacs uses a similar but more complex default
822 regexp constructed by the function @code{sentence-end}.
823 @xref{Standard Regexps}.)
825 First, we show the regexp as a string in Lisp syntax to distinguish
826 spaces from tab characters. The string constant begins and ends with a
827 double-quote. @samp{\"} stands for a double-quote as part of the
828 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
829 tab and @samp{\n} for a newline.
832 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
836 In contrast, if you evaluate this string, you will see the following:
840 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
841 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
847 In this output, tab and newline appear as themselves.
849 This regular expression contains four parts in succession and can be
850 deciphered as follows:
854 The first part of the pattern is a character alternative that matches
855 any one of three characters: period, question mark, and exclamation
856 mark. The match must begin with one of these three characters. (This
857 is one point where the new default regexp used by Emacs differs from
858 the old. The new value also allows some non-@acronym{ASCII}
859 characters that end a sentence without any following whitespace.)
862 The second part of the pattern matches any closing braces and quotation
863 marks, zero or more of them, that may follow the period, question mark
864 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
865 a string. The @samp{*} at the end indicates that the immediately
866 preceding regular expression (a character alternative, in this case) may be
867 repeated zero or more times.
869 @item \\($\\|@ $\\|\t\\|@ @ \\)
870 The third part of the pattern matches the whitespace that follows the
871 end of a sentence: the end of a line (optionally with a space), or a
872 tab, or two spaces. The double backslashes mark the parentheses and
873 vertical bars as regular expression syntax; the parentheses delimit a
874 group and the vertical bars separate alternatives. The dollar sign is
875 used to match the end of a line.
878 Finally, the last part of the pattern matches any additional whitespace
879 beyond the minimum needed to end a sentence.
882 @node Regexp Functions
883 @subsection Regular Expression Functions
885 These functions operate on regular expressions.
887 @defun regexp-quote string
888 This function returns a regular expression whose only exact match is
889 @var{string}. Using this regular expression in @code{looking-at} will
890 succeed only if the next characters in the buffer are @var{string};
891 using it in a search function will succeed if the text being searched
892 contains @var{string}.
894 This allows you to request an exact string match or search when calling
895 a function that wants a regular expression.
899 (regexp-quote "^The cat$")
900 @result{} "\\^The cat\\$"
904 One use of @code{regexp-quote} is to combine an exact string match with
905 context described as a regular expression. For example, this searches
906 for the string that is the value of @var{string}, surrounded by
912 (concat "\\s-" (regexp-quote string) "\\s-"))
917 @defun regexp-opt strings &optional paren
918 This function returns an efficient regular expression that will match
919 any of the strings in the list @var{strings}. This is useful when you
920 need to make matching or searching as fast as possible---for example,
923 If the optional argument @var{paren} is non-@code{nil}, then the
924 returned regular expression is always enclosed by at least one
925 parentheses-grouping construct. If @var{paren} is @code{words}, then
926 that construct is additionally surrounded by @samp{\<} and @samp{\>}.
928 This simplified definition of @code{regexp-opt} produces a
929 regular expression which is equivalent to the actual value
930 (but not as efficient):
933 (defun regexp-opt (strings paren)
934 (let ((open-paren (if paren "\\(" ""))
935 (close-paren (if paren "\\)" "")))
937 (mapconcat 'regexp-quote strings "\\|")
942 @defun regexp-opt-depth regexp
943 This function returns the total number of grouping constructs
944 (parenthesized expressions) in @var{regexp}. This does not include
945 shy groups (@pxref{Regexp Backslash}).
949 @section Regular Expression Searching
950 @cindex regular expression searching
951 @cindex regexp searching
952 @cindex searching for regexp
954 In GNU Emacs, you can search for the next match for a regular
955 expression either incrementally or not. For incremental search
956 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
957 The GNU Emacs Manual}. Here we describe only the search functions
958 useful in programs. The principal one is @code{re-search-forward}.
960 These search functions convert the regular expression to multibyte if
961 the buffer is multibyte; they convert the regular expression to unibyte
962 if the buffer is unibyte. @xref{Text Representations}.
964 @deffn Command re-search-forward regexp &optional limit noerror repeat
965 This function searches forward in the current buffer for a string of
966 text that is matched by the regular expression @var{regexp}. The
967 function skips over any amount of text that is not matched by
968 @var{regexp}, and leaves point at the end of the first match found.
969 It returns the new value of point.
971 If @var{limit} is non-@code{nil}, it must be a position in the current
972 buffer. It specifies the upper bound to the search. No match
973 extending after that position is accepted.
975 If @var{repeat} is supplied, it must be a positive number; the search
976 is repeated that many times; each repetition starts at the end of the
977 previous match. If all these successive searches succeed, the search
978 succeeds, moving point and returning its new value. Otherwise the
979 search fails. What @code{re-search-forward} does when the search
980 fails depends on the value of @var{noerror}:
984 Signal a @code{search-failed} error.
986 Do nothing and return @code{nil}.
988 Move point to @var{limit} (or the end of the accessible portion of the
989 buffer) and return @code{nil}.
992 In the following example, point is initially before the @samp{T}.
993 Evaluating the search call moves point to the end of that line (between
994 the @samp{t} of @samp{hat} and the newline).
998 ---------- Buffer: foo ----------
999 I read "@point{}The cat in the hat
1001 ---------- Buffer: foo ----------
1005 (re-search-forward "[a-z]+" nil t 5)
1008 ---------- Buffer: foo ----------
1009 I read "The cat in the hat@point{}
1011 ---------- Buffer: foo ----------
1016 @deffn Command re-search-backward regexp &optional limit noerror repeat
1017 This function searches backward in the current buffer for a string of
1018 text that is matched by the regular expression @var{regexp}, leaving
1019 point at the beginning of the first text found.
1021 This function is analogous to @code{re-search-forward}, but they are not
1022 simple mirror images. @code{re-search-forward} finds the match whose
1023 beginning is as close as possible to the starting point. If
1024 @code{re-search-backward} were a perfect mirror image, it would find the
1025 match whose end is as close as possible. However, in fact it finds the
1026 match whose beginning is as close as possible (and yet ends before the
1027 starting point). The reason for this is that matching a regular
1028 expression at a given spot always works from beginning to end, and
1029 starts at a specified beginning position.
1031 A true mirror-image of @code{re-search-forward} would require a special
1032 feature for matching regular expressions from end to beginning. It's
1033 not worth the trouble of implementing that.
1036 @defun string-match regexp string &optional start
1037 This function returns the index of the start of the first match for
1038 the regular expression @var{regexp} in @var{string}, or @code{nil} if
1039 there is no match. If @var{start} is non-@code{nil}, the search starts
1040 at that index in @var{string}.
1047 "quick" "The quick brown fox jumped quickly.")
1052 "quick" "The quick brown fox jumped quickly." 8)
1058 The index of the first character of the
1059 string is 0, the index of the second character is 1, and so on.
1061 After this function returns, the index of the first character beyond
1062 the match is available as @code{(match-end 0)}. @xref{Match Data}.
1067 "quick" "The quick brown fox jumped quickly." 8)
1078 @defun string-match-p regexp string &optional start
1079 This predicate function does what @code{string-match} does, but it
1080 avoids modifying the match data.
1083 @defun looking-at regexp
1084 This function determines whether the text in the current buffer directly
1085 following point matches the regular expression @var{regexp}. ``Directly
1086 following'' means precisely that: the search is ``anchored'' and it can
1087 succeed only starting with the first character following point. The
1088 result is @code{t} if so, @code{nil} otherwise.
1090 This function does not move point, but it updates the match data, which
1091 you can access using @code{match-beginning} and @code{match-end}.
1092 @xref{Match Data}. If you need to test for a match without modifying
1093 the match data, use @code{looking-at-p}, described below.
1095 In this example, point is located directly before the @samp{T}. If it
1096 were anywhere else, the result would be @code{nil}.
1100 ---------- Buffer: foo ----------
1101 I read "@point{}The cat in the hat
1103 ---------- Buffer: foo ----------
1105 (looking-at "The cat in the hat$")
1111 @defun looking-back regexp &optional limit greedy
1112 This function returns @code{t} if @var{regexp} matches text before
1113 point, ending at point, and @code{nil} otherwise.
1115 Because regular expression matching works only going forward, this is
1116 implemented by searching backwards from point for a match that ends at
1117 point. That can be quite slow if it has to search a long distance.
1118 You can bound the time required by specifying @var{limit}, which says
1119 not to search before @var{limit}. In this case, the match that is
1120 found must begin at or after @var{limit}.
1122 If @var{greedy} is non-@code{nil}, this function extends the match
1123 backwards as far as possible, stopping when a single additional
1124 previous character cannot be part of a match for regexp. When the
1125 match is extended, its starting position is allowed to occur before
1130 ---------- Buffer: foo ----------
1131 I read "@point{}The cat in the hat
1133 ---------- Buffer: foo ----------
1135 (looking-back "read \"" 3)
1137 (looking-back "read \"" 4)
1143 @defun looking-at-p regexp
1144 This predicate function works like @code{looking-at}, but without
1145 updating the match data.
1148 @defvar search-spaces-regexp
1149 If this variable is non-@code{nil}, it should be a regular expression
1150 that says how to search for whitespace. In that case, any group of
1151 spaces in a regular expression being searched for stands for use of
1152 this regular expression. However, spaces inside of constructs such as
1153 @samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
1154 @code{search-spaces-regexp}.
1156 Since this variable affects all regular expression search and match
1157 constructs, you should bind it temporarily for as small as possible
1162 @section POSIX Regular Expression Searching
1164 The usual regular expression functions do backtracking when necessary
1165 to handle the @samp{\|} and repetition constructs, but they continue
1166 this only until they find @emph{some} match. Then they succeed and
1167 report the first match found.
1169 This section describes alternative search functions which perform the
1170 full backtracking specified by the POSIX standard for regular expression
1171 matching. They continue backtracking until they have tried all
1172 possibilities and found all matches, so they can report the longest
1173 match, as required by POSIX. This is much slower, so use these
1174 functions only when you really need the longest match.
1176 The POSIX search and match functions do not properly support the
1177 non-greedy repetition operators (@pxref{Regexp Special, non-greedy}).
1178 This is because POSIX backtracking conflicts with the semantics of
1179 non-greedy repetition.
1181 @deffn Command posix-search-forward regexp &optional limit noerror repeat
1182 This is like @code{re-search-forward} except that it performs the full
1183 backtracking specified by the POSIX standard for regular expression
1187 @deffn Command posix-search-backward regexp &optional limit noerror repeat
1188 This is like @code{re-search-backward} except that it performs the full
1189 backtracking specified by the POSIX standard for regular expression
1193 @defun posix-looking-at regexp
1194 This is like @code{looking-at} except that it performs the full
1195 backtracking specified by the POSIX standard for regular expression
1199 @defun posix-string-match regexp string &optional start
1200 This is like @code{string-match} except that it performs the full
1201 backtracking specified by the POSIX standard for regular expression
1206 @section The Match Data
1209 Emacs keeps track of the start and end positions of the segments of
1210 text found during a search; this is called the @dfn{match data}.
1211 Thanks to the match data, you can search for a complex pattern, such
1212 as a date in a mail message, and then extract parts of the match under
1213 control of the pattern.
1215 Because the match data normally describe the most recent search only,
1216 you must be careful not to do another search inadvertently between the
1217 search you wish to refer back to and the use of the match data. If you
1218 can't avoid another intervening search, you must save and restore the
1219 match data around it, to prevent it from being overwritten.
1222 * Replacing Match:: Replacing a substring that was matched.
1223 * Simple Match Data:: Accessing single items of match data,
1224 such as where a particular subexpression started.
1225 * Entire Match Data:: Accessing the entire match data at once, as a list.
1226 * Saving Match Data:: Saving and restoring the match data.
1229 @node Replacing Match
1230 @subsection Replacing the Text that Matched
1231 @cindex replace matched text
1233 This function replaces all or part of the text matched by the last
1234 search. It works by means of the match data.
1236 @cindex case in replacements
1237 @defun replace-match replacement &optional fixedcase literal string subexp
1238 This function replaces the text in the buffer (or in @var{string}) that
1239 was matched by the last search. It replaces that text with
1242 If you did the last search in a buffer, you should specify @code{nil}
1243 for @var{string} and make sure that the current buffer when you call
1244 @code{replace-match} is the one in which you did the searching or
1245 matching. Then @code{replace-match} does the replacement by editing
1246 the buffer; it leaves point at the end of the replacement text, and
1249 If you did the search in a string, pass the same string as @var{string}.
1250 Then @code{replace-match} does the replacement by constructing and
1251 returning a new string.
1253 If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
1254 the replacement text without case conversion; otherwise, it converts
1255 the replacement text depending upon the capitalization of the text to
1256 be replaced. If the original text is all upper case, this converts
1257 the replacement text to upper case. If all words of the original text
1258 are capitalized, this capitalizes all the words of the replacement
1259 text. If all the words are one-letter and they are all upper case,
1260 they are treated as capitalized words rather than all-upper-case
1263 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1264 exactly as it is, the only alterations being case changes as needed.
1265 If it is @code{nil} (the default), then the character @samp{\} is treated
1266 specially. If a @samp{\} appears in @var{replacement}, then it must be
1267 part of one of the following sequences:
1271 @cindex @samp{&} in replacement
1272 @samp{\&} stands for the entire text being replaced.
1274 @item @samp{\@var{n}}
1275 @cindex @samp{\@var{n}} in replacement
1276 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1277 matched the @var{n}th subexpression in the original regexp.
1278 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1279 If the @var{n}th subexpression never matched, an empty string is substituted.
1282 @cindex @samp{\} in replacement
1283 @samp{\\} stands for a single @samp{\} in the replacement text.
1286 These substitutions occur after case conversion, if any,
1287 so the strings they substitute are never case-converted.
1289 If @var{subexp} is non-@code{nil}, that says to replace just
1290 subexpression number @var{subexp} of the regexp that was matched, not
1291 the entire match. For example, after matching @samp{foo \(ba*r\)},
1292 calling @code{replace-match} with 1 as @var{subexp} means to replace
1293 just the text that matched @samp{\(ba*r\)}.
1296 @defun match-substitute-replacement replacement &optional fixedcase literal string subexp
1297 This function returns the text that would be inserted into the buffer
1298 by @code{replace-match}, but without modifying the buffer. It is
1299 useful if you want to present the user with actual replacement result,
1300 with constructs like @samp{\@var{n}} or @samp{\&} substituted with
1301 matched groups. Arguments @var{replacement} and optional
1302 @var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the
1303 same meaning as for @code{replace-match}.
1306 @node Simple Match Data
1307 @subsection Simple Match Data Access
1309 This section explains how to use the match data to find out what was
1310 matched by the last search or match operation, if it succeeded.
1312 You can ask about the entire matching text, or about a particular
1313 parenthetical subexpression of a regular expression. The @var{count}
1314 argument in the functions below specifies which. If @var{count} is
1315 zero, you are asking about the entire match. If @var{count} is
1316 positive, it specifies which subexpression you want.
1318 Recall that the subexpressions of a regular expression are those
1319 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1320 @var{count}th subexpression is found by counting occurrences of
1321 @samp{\(} from the beginning of the whole regular expression. The first
1322 subexpression is numbered 1, the second 2, and so on. Only regular
1323 expressions can have subexpressions---after a simple string search, the
1324 only information available is about the entire match.
1326 Every successful search sets the match data. Therefore, you should
1327 query the match data immediately after searching, before calling any
1328 other function that might perform another search. Alternatively, you
1329 may save and restore the match data (@pxref{Saving Match Data}) around
1330 the call to functions that could perform another search.
1332 A search which fails may or may not alter the match data. In the
1333 past, a failing search did not do this, but we may change it in the
1334 future. So don't try to rely on the value of the match data after
1337 @defun match-string count &optional in-string
1338 This function returns, as a string, the text matched in the last search
1339 or match operation. It returns the entire text if @var{count} is zero,
1340 or just the portion corresponding to the @var{count}th parenthetical
1341 subexpression, if @var{count} is positive.
1343 If the last such operation was done against a string with
1344 @code{string-match}, then you should pass the same string as the
1345 argument @var{in-string}. After a buffer search or match,
1346 you should omit @var{in-string} or pass @code{nil} for it; but you
1347 should make sure that the current buffer when you call
1348 @code{match-string} is the one in which you did the searching or
1351 The value is @code{nil} if @var{count} is out of range, or for a
1352 subexpression inside a @samp{\|} alternative that wasn't used or a
1353 repetition that repeated zero times.
1356 @defun match-string-no-properties count &optional in-string
1357 This function is like @code{match-string} except that the result
1358 has no text properties.
1361 @defun match-beginning count
1362 This function returns the position of the start of text matched by the
1363 last regular expression searched for, or a subexpression of it.
1365 If @var{count} is zero, then the value is the position of the start of
1366 the entire match. Otherwise, @var{count} specifies a subexpression in
1367 the regular expression, and the value of the function is the starting
1368 position of the match for that subexpression.
1370 The value is @code{nil} for a subexpression inside a @samp{\|}
1371 alternative that wasn't used or a repetition that repeated zero times.
1374 @defun match-end count
1375 This function is like @code{match-beginning} except that it returns the
1376 position of the end of the match, rather than the position of the
1380 Here is an example of using the match data, with a comment showing the
1381 positions within the text:
1385 (string-match "\\(qu\\)\\(ick\\)"
1386 "The quick fox jumped quickly.")
1392 (match-string 0 "The quick fox jumped quickly.")
1394 (match-string 1 "The quick fox jumped quickly.")
1396 (match-string 2 "The quick fox jumped quickly.")
1401 (match-beginning 1) ; @r{The beginning of the match}
1402 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1406 (match-beginning 2) ; @r{The beginning of the match}
1407 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1411 (match-end 1) ; @r{The end of the match}
1412 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1414 (match-end 2) ; @r{The end of the match}
1415 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1419 Here is another example. Point is initially located at the beginning
1420 of the line. Searching moves point to between the space and the word
1421 @samp{in}. The beginning of the entire match is at the 9th character of
1422 the buffer (@samp{T}), and the beginning of the match for the first
1423 subexpression is at the 13th character (@samp{c}).
1428 (re-search-forward "The \\(cat \\)")
1430 (match-beginning 1))
1435 ---------- Buffer: foo ----------
1436 I read "The cat @point{}in the hat comes back" twice.
1439 ---------- Buffer: foo ----------
1444 (In this case, the index returned is a buffer position; the first
1445 character of the buffer counts as 1.)
1447 @node Entire Match Data
1448 @subsection Accessing the Entire Match Data
1450 The functions @code{match-data} and @code{set-match-data} read or
1451 write the entire match data, all at once.
1453 @defun match-data &optional integers reuse reseat
1454 This function returns a list of positions (markers or integers) that
1455 record all the information on what text the last search matched.
1456 Element zero is the position of the beginning of the match for the
1457 whole expression; element one is the position of the end of the match
1458 for the expression. The next two elements are the positions of the
1459 beginning and end of the match for the first subexpression, and so on.
1465 number {\mathsurround=0pt $2n$}
1467 corresponds to @code{(match-beginning @var{n})}; and
1473 number {\mathsurround=0pt $2n+1$}
1475 corresponds to @code{(match-end @var{n})}.
1477 Normally all the elements are markers or @code{nil}, but if
1478 @var{integers} is non-@code{nil}, that means to use integers instead
1479 of markers. (In that case, the buffer itself is appended as an
1480 additional element at the end of the list, to facilitate complete
1481 restoration of the match data.) If the last match was done on a
1482 string with @code{string-match}, then integers are always used,
1483 since markers can't point into a string.
1485 If @var{reuse} is non-@code{nil}, it should be a list. In that case,
1486 @code{match-data} stores the match data in @var{reuse}. That is,
1487 @var{reuse} is destructively modified. @var{reuse} does not need to
1488 have the right length. If it is not long enough to contain the match
1489 data, it is extended. If it is too long, the length of @var{reuse}
1490 stays the same, but the elements that were not used are set to
1491 @code{nil}. The purpose of this feature is to reduce the need for
1494 If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
1495 are reseated to point to nowhere.
1497 As always, there must be no possibility of intervening searches between
1498 the call to a search function and the call to @code{match-data} that is
1499 intended to access the match data for that search.
1504 @result{} (#<marker at 9 in foo>
1505 #<marker at 17 in foo>
1506 #<marker at 13 in foo>
1507 #<marker at 17 in foo>)
1512 @defun set-match-data match-list &optional reseat
1513 This function sets the match data from the elements of @var{match-list},
1514 which should be a list that was the value of a previous call to
1515 @code{match-data}. (More precisely, anything that has the same format
1518 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1519 an error; that sets the match data in a meaningless but harmless way.
1521 If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
1522 are reseated to point to nowhere.
1524 @findex store-match-data
1525 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1528 @node Saving Match Data
1529 @subsection Saving and Restoring the Match Data
1531 When you call a function that may do a search, you may need to save
1532 and restore the match data around that call, if you want to preserve the
1533 match data from an earlier search for later use. Here is an example
1534 that shows the problem that arises if you fail to save the match data:
1538 (re-search-forward "The \\(cat \\)")
1540 (foo) ; @r{Perhaps @code{foo} does}
1541 ; @r{more searching.}
1543 @result{} 61 ; @r{Unexpected result---not 48!}
1547 You can save and restore the match data with @code{save-match-data}:
1549 @defmac save-match-data body@dots{}
1550 This macro executes @var{body}, saving and restoring the match
1551 data around it. The return value is the value of the last form in
1555 You could use @code{set-match-data} together with @code{match-data} to
1556 imitate the effect of the special form @code{save-match-data}. Here is
1561 (let ((data (match-data)))
1563 @dots{} ; @r{Ok to change the original match data.}
1564 (set-match-data data)))
1568 Emacs automatically saves and restores the match data when it runs
1569 process filter functions (@pxref{Filter Functions}) and process
1570 sentinels (@pxref{Sentinels}).
1573 Here is a function which restores the match data provided the buffer
1574 associated with it still exists.
1578 (defun restore-match-data (data)
1579 @c It is incorrect to split the first line of a doc string.
1580 @c If there's a problem here, it should be solved in some other way.
1581 "Restore the match data DATA unless the buffer is missing."
1587 (null (marker-buffer (car d)))
1589 ;; @file{match-data} @r{buffer is deleted.}
1592 (set-match-data data))))
1597 @node Search and Replace
1598 @section Search and Replace
1599 @cindex replacement after search
1600 @cindex searching and replacing
1602 If you want to find all matches for a regexp in part of the buffer,
1603 and replace them, the best way is to write an explicit loop using
1604 @code{re-search-forward} and @code{replace-match}, like this:
1607 (while (re-search-forward "foo[ \t]+bar" nil t)
1608 (replace-match "foobar"))
1612 @xref{Replacing Match,, Replacing the Text that Matched}, for a
1613 description of @code{replace-match}.
1615 However, replacing matches in a string is more complex, especially
1616 if you want to do it efficiently. So Emacs provides a function to do
1619 @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
1620 This function copies @var{string} and searches it for matches for
1621 @var{regexp}, and replaces them with @var{rep}. It returns the
1622 modified copy. If @var{start} is non-@code{nil}, the search for
1623 matches starts at that index in @var{string}, so matches starting
1624 before that index are not changed.
1626 This function uses @code{replace-match} to do the replacement, and it
1627 passes the optional arguments @var{fixedcase}, @var{literal} and
1628 @var{subexp} along to @code{replace-match}.
1630 Instead of a string, @var{rep} can be a function. In that case,
1631 @code{replace-regexp-in-string} calls @var{rep} for each match,
1632 passing the text of the match as its sole argument. It collects the
1633 value @var{rep} returns and passes that to @code{replace-match} as the
1634 replacement string. The match-data at this point are the result
1635 of matching @var{regexp} against a substring of @var{string}.
1638 If you want to write a command along the lines of @code{query-replace},
1639 you can use @code{perform-replace} to do the work.
1641 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
1642 This function is the guts of @code{query-replace} and related
1643 commands. It searches for occurrences of @var{from-string} in the
1644 text between positions @var{start} and @var{end} and replaces some or
1645 all of them. If @var{start} is @code{nil} (or omitted), point is used
1646 instead, and the end of the buffer's accessible portion is used for
1649 If @var{query-flag} is @code{nil}, it replaces all
1650 occurrences; otherwise, it asks the user what to do about each one.
1652 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
1653 considered a regular expression; otherwise, it must match literally. If
1654 @var{delimited-flag} is non-@code{nil}, then only replacements
1655 surrounded by word boundaries are considered.
1657 The argument @var{replacements} specifies what to replace occurrences
1658 with. If it is a string, that string is used. It can also be a list of
1659 strings, to be used in cyclic order.
1661 If @var{replacements} is a cons cell, @w{@code{(@var{function}
1662 . @var{data})}}, this means to call @var{function} after each match to
1663 get the replacement text. This function is called with two arguments:
1664 @var{data}, and the number of replacements already made.
1666 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
1667 it specifies how many times to use each of the strings in the
1668 @var{replacements} list before advancing cyclically to the next one.
1670 If @var{from-string} contains upper-case letters, then
1671 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
1672 it uses the @code{replacements} without altering the case of them.
1674 Normally, the keymap @code{query-replace-map} defines the possible
1675 user responses for queries. The argument @var{map}, if
1676 non-@code{nil}, specifies a keymap to use instead of
1677 @code{query-replace-map}.
1679 This function uses one of two functions to search for the next
1680 occurrence of @var{from-string}. These functions are specified by the
1681 values of two variables: @code{replace-re-search-function} and
1682 @code{replace-search-function}. The former is called when the
1683 argument @var{regexp-flag} is non-@code{nil}, the latter when it is
1687 @defvar query-replace-map
1688 This variable holds a special keymap that defines the valid user
1689 responses for @code{perform-replace} and the commands that use it, as
1690 well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual
1695 The ``key bindings'' are not commands, just symbols that are meaningful
1696 to the functions that use this map.
1699 Prefix keys are not supported; each key binding must be for a
1700 single-event key sequence. This is because the functions don't use
1701 @code{read-key-sequence} to get the input; instead, they read a single
1702 event and look it up ``by hand.''
1706 Here are the meaningful ``bindings'' for @code{query-replace-map}.
1707 Several of them are meaningful only for @code{query-replace} and
1712 Do take the action being considered---in other words, ``yes.''
1715 Do not take action for this question---in other words, ``no.''
1718 Answer this question ``no,'' and give up on the entire series of
1719 questions, assuming that the answers will be ``no.''
1722 Answer this question ``yes,'' and give up on the entire series of
1723 questions, assuming that subsequent answers will be ``no.''
1726 Answer this question ``yes,'' but show the results---don't advance yet
1727 to the next question.
1730 Answer this question and all subsequent questions in the series with
1731 ``yes,'' without further user interaction.
1734 Move back to the previous place that a question was asked about.
1737 Enter a recursive edit to deal with this question---instead of any
1738 other action that would normally be taken.
1740 @item delete-and-edit
1741 Delete the text being considered, then enter a recursive edit to replace
1745 Redisplay and center the window, then ask the same question again.
1748 Perform a quit right away. Only @code{y-or-n-p} and related functions
1752 Display some help, then ask again.
1755 @defvar multi-query-replace-map
1756 This variable holds a keymap that extends @code{query-replace-map} by
1757 providing additional keybindings that are useful in multi-buffer
1761 @defvar replace-search-function
1762 This variable specifies a function that @code{perform-replace} calls
1763 to search for the next string to replace. Its default value is
1764 @code{search-forward}. Any other value should name a function of 3
1765 arguments: the first 3 arguments of @code{search-forward}
1766 (@pxref{String Search}).
1769 @defvar replace-re-search-function
1770 This variable specifies a function that @code{perform-replace} calls
1771 to search for the next regexp to replace. Its default value is
1772 @code{re-search-forward}. Any other value should name a function of 3
1773 arguments: the first 3 arguments of @code{re-search-forward}
1774 (@pxref{Regexp Search}).
1777 @node Standard Regexps
1778 @section Standard Regular Expressions Used in Editing
1779 @cindex regexps used standardly in editing
1780 @cindex standard regexps used in editing
1782 This section describes some variables that hold regular expressions
1783 used for certain purposes in editing:
1785 @defopt page-delimiter
1786 This is the regular expression describing line-beginnings that separate
1787 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1788 @code{"^\C-l"}); this matches a line that starts with a formfeed
1792 The following two regular expressions should @emph{not} assume the
1793 match always starts at the beginning of a line; they should not use
1794 @samp{^} to anchor the match. Most often, the paragraph commands do
1795 check for a match only at the beginning of a line, which means that
1796 @samp{^} would be superfluous. When there is a nonzero left margin,
1797 they accept matches that start after the left margin. In that case, a
1798 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1799 where a left margin is never used.
1801 @defopt paragraph-separate
1802 This is the regular expression for recognizing the beginning of a line
1803 that separates paragraphs. (If you change this, you may have to
1804 change @code{paragraph-start} also.) The default value is
1805 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1806 spaces, tabs, and form feeds (after its left margin).
1809 @defopt paragraph-start
1810 This is the regular expression for recognizing the beginning of a line
1811 that starts @emph{or} separates paragraphs. The default value is
1812 @w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
1813 whitespace or starting with a form feed (after its left margin).
1816 @defopt sentence-end
1817 If non-@code{nil}, the value should be a regular expression describing
1818 the end of a sentence, including the whitespace following the
1819 sentence. (All paragraph boundaries also end sentences, regardless.)
1821 If the value is @code{nil}, the default, then the function
1822 @code{sentence-end} has to construct the regexp. That is why you
1823 should always call the function @code{sentence-end} to obtain the
1824 regexp to be used to recognize the end of a sentence.
1828 This function returns the value of the variable @code{sentence-end},
1829 if non-@code{nil}. Otherwise it returns a default value based on the
1830 values of the variables @code{sentence-end-double-space}
1831 (@pxref{Definition of sentence-end-double-space}),
1832 @code{sentence-end-without-period} and
1833 @code{sentence-end-without-space}.
1837 arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f