2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003,
4 @c 2004, 2005, 2006 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}.
33 @section Searching for Strings
36 These are the primitive functions for searching through the text in a
37 buffer. They are meant for use in programs, but you may call them
38 interactively. If you do so, they prompt for the search string; the
39 arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
42 These search functions convert the search string to multibyte if the
43 buffer is multibyte; they convert the search string to unibyte if the
44 buffer is unibyte. @xref{Text Representations}.
46 @deffn Command search-forward string &optional limit noerror repeat
47 This function searches forward from point for an exact match for
48 @var{string}. If successful, it sets point to the end of the occurrence
49 found, and returns the new value of point. If no match is found, the
50 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 supplied (it must be a positive number), then the
94 search is repeated that many times (each time starting at the end of the
95 previous time's match). If these successive searches succeed, the
96 function succeeds, moving point and returning its new value. Otherwise
97 the search fails, with results depending on the value of
98 @var{noerror}, as described above.
101 @deffn Command search-backward string &optional limit noerror repeat
102 This function searches backward from point for @var{string}. It is
103 just like @code{search-forward} except that it searches backwards and
104 leaves point at the beginning of the match.
107 @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.
114 Word matching regards @var{string} as a sequence of words, disregarding
115 punctuation that separates them. It searches the buffer for the same
116 sequence of words. Each word must be distinct in the buffer (searching
117 for the word @samp{ball} does not match the word @samp{balls}), but the
118 details of punctuation and spacing are ignored (searching for @samp{ball
119 boy} does match @samp{ball. Boy!}).
121 In this example, point is initially at the beginning of the buffer; the
122 search leaves it between the @samp{y} and the @samp{!}.
126 ---------- Buffer: foo ----------
127 @point{}He said "Please! Find
129 ---------- Buffer: foo ----------
133 (word-search-forward "Please find the ball, boy.")
136 ---------- Buffer: foo ----------
137 He said "Please! Find
138 the ball boy@point{}!"
139 ---------- Buffer: foo ----------
143 If @var{limit} is non-@code{nil}, it must be a position in the current
144 buffer; it specifies the upper bound to the search. The match found
145 must not extend after that position.
147 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
148 an error if the search fails. If @var{noerror} is @code{t}, then it
149 returns @code{nil} instead of signaling an error. If @var{noerror} is
150 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
151 end of the accessible portion of the buffer) and returns @code{nil}.
153 If @var{repeat} is non-@code{nil}, then the search is repeated that many
154 times. Point is positioned at the end of the last match.
157 @deffn Command word-search-backward string &optional limit noerror repeat
158 This function searches backward from point for a word match to
159 @var{string}. This function is just like @code{word-search-forward}
160 except that it searches backward and normally leaves point at the
161 beginning of the match.
164 @node Searching and Case
165 @section Searching and Case
166 @cindex searching and case
168 By default, searches in Emacs ignore the case of the text they are
169 searching through; if you specify searching for @samp{FOO}, then
170 @samp{Foo} or @samp{foo} is also considered a match. This applies to
171 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
172 @samp{A} or @samp{b} or @samp{B}.
174 If you do not want this feature, set the variable
175 @code{case-fold-search} to @code{nil}. Then all letters must match
176 exactly, including case. This is a buffer-local variable; altering the
177 variable affects only the current buffer. (@xref{Intro to
178 Buffer-Local}.) Alternatively, you may change the value of
179 @code{default-case-fold-search}, which is the default value of
180 @code{case-fold-search} for buffers that do not override it.
182 Note that the user-level incremental search feature handles case
183 distinctions differently. When given a lower case letter, it looks for
184 a match of either case, but when given an upper case letter, it looks
185 for an upper case letter only. But this has nothing to do with the
186 searching functions used in Lisp code.
189 This variable determines whether the higher level replacement
190 functions should preserve case. If the variable is @code{nil}, that
191 means to use the replacement text verbatim. A non-@code{nil} value
192 means to convert the case of the replacement text according to the
195 This variable is used by passing it as an argument to the function
196 @code{replace-match}. @xref{Replacing Match}.
199 @defopt case-fold-search
200 This buffer-local variable determines whether searches should ignore
201 case. If the variable is @code{nil} they do not ignore case; otherwise
205 @defvar default-case-fold-search
206 The value of this variable is the default value for
207 @code{case-fold-search} in buffers that do not override it. This is the
208 same as @code{(default-value 'case-fold-search)}.
211 @node Regular Expressions
212 @section Regular Expressions
213 @cindex regular expression
216 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
217 denotes a (possibly infinite) set of strings. Searching for matches for
218 a regexp is a very powerful operation. This section explains how to write
219 regexps; the following section says how to search for them.
222 @cindex authoring regular expressions
223 For convenient interactive development of regular expressions, you
224 can use the @kbd{M-x re-builder} command. It provides a convenient
225 interface for creating regular expressions, by giving immediate visual
226 feedback in a separate buffer. As you edit the regexp, all its
227 matches in the target buffer are highlighted. Each parenthesized
228 sub-expression of the regexp is shown in a distinct face, which makes
229 it easier to verify even very complex regexps.
232 * Syntax of Regexps:: Rules for writing regular expressions.
233 * Regexp Example:: Illustrates regular expression syntax.
234 * Regexp Functions:: Functions for operating on regular expressions.
237 @node Syntax of Regexps
238 @subsection Syntax of Regular Expressions
240 Regular expressions have a syntax in which a few characters are
241 special constructs and the rest are @dfn{ordinary}. An ordinary
242 character is a simple regular expression that matches that character
243 and nothing else. The special characters are @samp{.}, @samp{*},
244 @samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
245 special characters will be defined in the future. The character
246 @samp{]} is special if it ends a character alternative (see later).
247 The character @samp{-} is special inside a character alternative. A
248 @samp{[:} and balancing @samp{:]} enclose a character class inside a
249 character alternative. Any other character appearing in a regular
250 expression is ordinary, unless a @samp{\} precedes it.
252 For example, @samp{f} is not a special character, so it is ordinary, and
253 therefore @samp{f} is a regular expression that matches the string
254 @samp{f} and no other string. (It does @emph{not} match the string
255 @samp{fg}, but it does match a @emph{part} of that string.) Likewise,
256 @samp{o} is a regular expression that matches only @samp{o}.@refill
258 Any two regular expressions @var{a} and @var{b} can be concatenated. The
259 result is a regular expression that matches a string if @var{a} matches
260 some amount of the beginning of that string and @var{b} matches the rest of
263 As a simple example, we can concatenate the regular expressions @samp{f}
264 and @samp{o} to get the regular expression @samp{fo}, which matches only
265 the string @samp{fo}. Still trivial. To do something more powerful, you
266 need to use one of the special regular expression constructs.
269 * Regexp Special:: Special characters in regular expressions.
270 * Char Classes:: Character classes used in regular expressions.
271 * Regexp Backslash:: Backslash-sequences in regular expressions.
275 @subsubsection Special Characters in Regular Expressions
277 Here is a list of the characters that are special in a regular
282 @item @samp{.}@: @r{(Period)}
283 @cindex @samp{.} in regexp
284 is a special character that matches any single character except a newline.
285 Using concatenation, we can make regular expressions like @samp{a.b}, which
286 matches any three-character string that begins with @samp{a} and ends with
290 @cindex @samp{*} in regexp
291 is not a construct by itself; it is a postfix operator that means to
292 match the preceding regular expression repetitively as many times as
293 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
296 @samp{*} always applies to the @emph{smallest} possible preceding
297 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
298 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
300 The matcher processes a @samp{*} construct by matching, immediately, as
301 many repetitions as can be found. Then it continues with the rest of
302 the pattern. If that fails, backtracking occurs, discarding some of the
303 matches of the @samp{*}-modified construct in the hope that that will
304 make it possible to match the rest of the pattern. For example, in
305 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
306 first tries to match all three @samp{a}s; but the rest of the pattern is
307 @samp{ar} and there is only @samp{r} left to match, so this try fails.
308 The next alternative is for @samp{a*} to match only two @samp{a}s. With
309 this choice, the rest of the regexp matches successfully.@refill
311 Nested repetition operators take a long time, or even forever, if they
312 lead to ambiguous matching. For example, trying to match the regular
313 expression @samp{\(x+y*\)*a} against the string
314 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could take hours before it
315 ultimately fails. Emacs must try each way of grouping the 35
316 @samp{x}s before concluding that none of them can work. Even worse,
317 @samp{\(x*\)*} can match the null string in infinitely many ways, so
318 it causes an infinite loop. To avoid these problems, check nested
319 repetitions carefully.
322 @cindex @samp{+} in regexp
323 is a postfix operator, similar to @samp{*} except that it must match
324 the preceding expression at least once. So, for example, @samp{ca+r}
325 matches the strings @samp{car} and @samp{caaaar} but not the string
326 @samp{cr}, whereas @samp{ca*r} matches all three strings.
329 @cindex @samp{?} in regexp
330 is a postfix operator, similar to @samp{*} except that it must match the
331 preceding expression either once or not at all. For example,
332 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
334 @item @samp{*?}, @samp{+?}, @samp{??}
335 These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
336 and @samp{?}. Where those operators match the largest possible
337 substring (consistent with matching the entire containing expression),
338 the non-greedy variants match the smallest possible substring
339 (consistent with matching the entire containing expression).
341 For example, the regular expression @samp{c[ad]*a} when applied to the
342 string @samp{cdaaada} matches the whole string; but the regular
343 expression @samp{c[ad]*?a}, applied to that same string, matches just
344 @samp{cda}. (The smallest possible match here for @samp{[ad]*?} that
345 permits the whole expression to match is @samp{d}.)
347 @item @samp{[ @dots{} ]}
348 @cindex character alternative (in regexp)
349 @cindex @samp{[} in regexp
350 @cindex @samp{]} in regexp
351 is a @dfn{character alternative}, which begins with @samp{[} and is
352 terminated by @samp{]}. In the simplest case, the characters between
353 the two brackets are what this character alternative can match.
355 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
356 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
357 (including the empty string), from which it follows that @samp{c[ad]*r}
358 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
360 You can also include character ranges in a character alternative, by
361 writing the starting and ending characters with a @samp{-} between them.
362 Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
363 Ranges may be intermixed freely with individual characters, as in
364 @samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
365 or @samp{$}, @samp{%} or period.
367 Note that the usual regexp special characters are not special inside a
368 character alternative. A completely different set of characters is
369 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
371 To include a @samp{]} in a character alternative, you must make it the
372 first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
373 To include a @samp{-}, write @samp{-} as the first or last character of
374 the character alternative, or put it after a range. Thus, @samp{[]-]}
375 matches both @samp{]} and @samp{-}.
377 To include @samp{^} in a character alternative, put it anywhere but at
380 The beginning and end of a range of multibyte characters must be in
381 the same character set (@pxref{Character Sets}). Thus,
382 @code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a}
383 with grave accent) is in the Emacs character set for Latin-1 but the
384 character 0x97c (@samp{u} with diaeresis) is in the Emacs character
385 set for Latin-2. (We use Lisp string syntax to write that example,
386 and a few others in the next few paragraphs, in order to include hex
387 escape sequences in them.)
389 If a range starts with a unibyte character @var{c} and ends with a
390 multibyte character @var{c2}, the range is divided into two parts: one
391 is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
392 @var{c1} is the first character of the charset to which @var{c2}
395 You cannot always match all non-@acronym{ASCII} characters with the regular
396 expression @code{"[\200-\377]"}. This works when searching a unibyte
397 buffer or string (@pxref{Text Representations}), but not in a multibyte
398 buffer or string, because many non-@acronym{ASCII} characters have codes
399 above octal 0377. However, the regular expression @code{"[^\000-\177]"}
400 does match all non-@acronym{ASCII} characters (see below regarding @samp{^}),
401 in both multibyte and unibyte representations, because only the
402 @acronym{ASCII} characters are excluded.
404 A character alternative can also specify named
405 character classes (@pxref{Char Classes}). This is a POSIX feature whose
406 syntax is @samp{[:@var{class}:]}. Using a character class is equivalent
407 to mentioning each of the characters in that class; but the latter is
408 not feasible in practice, since some classes include thousands of
409 different characters.
411 @item @samp{[^ @dots{} ]}
412 @cindex @samp{^} in regexp
413 @samp{[^} begins a @dfn{complemented character alternative}. This
414 matches any character except the ones specified. Thus,
415 @samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
418 @samp{^} is not special in a character alternative unless it is the first
419 character. The character following the @samp{^} is treated as if it
420 were first (in other words, @samp{-} and @samp{]} are not special there).
422 A complemented character alternative can match a newline, unless newline is
423 mentioned as one of the characters not to match. This is in contrast to
424 the handling of regexps in programs such as @code{grep}.
427 @cindex beginning of line in regexp
428 When matching a buffer, @samp{^} matches the empty string, but only at the
429 beginning of a line in the text being matched (or the beginning of the
430 accessible portion of the buffer). Otherwise it fails to match
431 anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the
434 When matching a string instead of a buffer, @samp{^} matches at the
435 beginning of the string or after a newline character.
437 For historical compatibility reasons, @samp{^} can be used only at the
438 beginning of the regular expression, or after @samp{\(} or @samp{\|}.
441 @cindex @samp{$} in regexp
442 @cindex end of line in regexp
443 is similar to @samp{^} but matches only at the end of a line (or the
444 end of the accessible portion of the buffer). Thus, @samp{x+$}
445 matches a string of one @samp{x} or more at the end of a line.
447 When matching a string instead of a buffer, @samp{$} matches at the end
448 of the string or before a newline character.
450 For historical compatibility reasons, @samp{$} can be used only at the
451 end of the regular expression, or before @samp{\)} or @samp{\|}.
454 @cindex @samp{\} in regexp
455 has two functions: it quotes the special characters (including
456 @samp{\}), and it introduces additional special constructs.
458 Because @samp{\} quotes special characters, @samp{\$} is a regular
459 expression that matches only @samp{$}, and @samp{\[} is a regular
460 expression that matches only @samp{[}, and so on.
462 Note that @samp{\} also has special meaning in the read syntax of Lisp
463 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
464 example, the regular expression that matches the @samp{\} character is
465 @samp{\\}. To write a Lisp string that contains the characters
466 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
467 @samp{\}. Therefore, the read syntax for a regular expression matching
468 @samp{\} is @code{"\\\\"}.@refill
471 @strong{Please note:} For historical compatibility, special characters
472 are treated as ordinary ones if they are in contexts where their special
473 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
474 ordinary since there is no preceding expression on which the @samp{*}
475 can act. It is poor practice to depend on this behavior; quote the
476 special character anyway, regardless of where it appears.@refill
478 As a @samp{\} is not special inside a character alternative, it can
479 never remove the special meaning of @samp{-} or @samp{]}. So you
480 should not quote these characters when they have no special meaning
481 either. This would not clarify anything, since backslashes can
482 legitimately precede these characters where they @emph{have} special
483 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
484 which matches any single character except a backslash.
486 In practice, most @samp{]} that occur in regular expressions close a
487 character alternative and hence are special. However, occasionally a
488 regular expression may try to match a complex pattern of literal
489 @samp{[} and @samp{]}. In such situations, it sometimes may be
490 necessary to carefully parse the regexp from the start to determine
491 which square brackets enclose a character alternative. For example,
492 @samp{[^][]]} consists of the complemented character alternative
493 @samp{[^][]} (which matches any single character that is not a square
494 bracket), followed by a literal @samp{]}.
496 The exact rules are that at the beginning of a regexp, @samp{[} is
497 special and @samp{]} not. This lasts until the first unquoted
498 @samp{[}, after which we are in a character alternative; @samp{[} is
499 no longer special (except when it starts a character class) but @samp{]}
500 is special, unless it immediately follows the special @samp{[} or that
501 @samp{[} followed by a @samp{^}. This lasts until the next special
502 @samp{]} that does not end a character class. This ends the character
503 alternative and restores the ordinary syntax of regular expressions;
504 an unquoted @samp{[} is special again and a @samp{]} not.
507 @subsubsection Character Classes
508 @cindex character classes in regexp
510 Here is a table of the classes you can use in a character alternative,
515 This matches any @acronym{ASCII} (unibyte) character.
517 This matches any letter or digit. (At present, for multibyte
518 characters, it matches anything that has word syntax.)
520 This matches any letter. (At present, for multibyte characters, it
521 matches anything that has word syntax.)
523 This matches space and tab only.
525 This matches any @acronym{ASCII} control character.
527 This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
528 matches any digit, as well as @samp{+} and @samp{-}.
530 This matches graphic characters---everything except @acronym{ASCII} control
531 characters, space, and the delete character.
533 This matches any lower-case letter, as determined by
534 the current case table (@pxref{Case Tables}).
536 This matches any non-@acronym{ASCII} (multibyte) 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 upper-case letter, as determined by
548 the current case table (@pxref{Case Tables}).
550 This matches any character that has word syntax (@pxref{Syntax Class
553 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
554 through @samp{f} and @samp{A} through @samp{F}.
557 @node Regexp Backslash
558 @subsubsection Backslash Constructs in Regular Expressions
560 For the most part, @samp{\} followed by any character matches only
561 that character. However, there are several exceptions: certain
562 two-character sequences starting with @samp{\} that have special
563 meanings. (The character after the @samp{\} in such a sequence is
564 always ordinary when used on its own.) Here is a table of the special
569 @cindex @samp{|} in regexp
570 @cindex regexp alternative
571 specifies an alternative.
572 Two regular expressions @var{a} and @var{b} with @samp{\|} in
573 between form an expression that matches anything that either @var{a} or
574 @var{b} matches.@refill
576 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
577 but no other string.@refill
579 @samp{\|} applies to the largest possible surrounding expressions. Only a
580 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
583 If you need full backtracking capability to handle multiple uses of
584 @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
588 is a postfix operator that repeats the previous pattern exactly @var{m}
589 times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
590 and nothing else. @samp{c[ad]\@{3\@}r} matches string such as
591 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
593 @item \@{@var{m},@var{n}\@}
594 is a more general postfix operator that specifies repetition with a
595 minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m}
596 is omitted, the minimum is 0; if @var{n} is omitted, there is no
599 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
600 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
602 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @*
603 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @*
604 @samp{\@{1,\@}} is equivalent to @samp{+}.
607 @cindex @samp{(} in regexp
608 @cindex @samp{)} in regexp
609 @cindex regexp grouping
610 is a grouping construct that serves three purposes:
614 To enclose a set of @samp{\|} alternatives for other operations. Thus,
615 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
619 To enclose a complicated expression for the postfix operators @samp{*},
620 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
621 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
622 number (zero or more) of @samp{na} strings.
625 To record a matched substring for future reference with
626 @samp{\@var{digit}} (see below).
629 This last application is not a consequence of the idea of a
630 parenthetical grouping; it is a separate feature that was assigned as a
631 second meaning to the same @samp{\( @dots{} \)} construct because, in
632 practice, there was usually no conflict between the two meanings. But
633 occasionally there is a conflict, and that led to the introduction of
636 @item \(?: @dots{} \)
637 is the @dfn{shy group} construct. A shy group serves the first two
638 purposes of an ordinary group (controlling the nesting of other
639 operators), but it does not get a number, so you cannot refer back to
640 its value with @samp{\@var{digit}}.
642 Shy groups are particularly useful for mechanically-constructed regular
643 expressions because they can be added automatically without altering the
644 numbering of any ordinary, non-shy groups.
647 matches the same text that matched the @var{digit}th occurrence of a
648 grouping (@samp{\( @dots{} \)}) construct.
650 In other words, after the end of a group, the matcher remembers the
651 beginning and end of the text matched by that group. Later on in the
652 regular expression you can use @samp{\} followed by @var{digit} to
653 match that same text, whatever it may have been.
655 The strings matching the first nine grouping constructs appearing in
656 the entire regular expression passed to a search or matching function
657 are assigned numbers 1 through 9 in the order that the open
658 parentheses appear in the regular expression. So you can use
659 @samp{\1} through @samp{\9} to refer to the text matched by the
660 corresponding grouping constructs.
662 For example, @samp{\(.*\)\1} matches any newline-free string that is
663 composed of two identical halves. The @samp{\(.*\)} matches the first
664 half, which may be anything, but the @samp{\1} that follows must match
667 If a @samp{\( @dots{} \)} construct matches more than once (which can
668 happen, for instance, if it is followed by @samp{*}), only the last
671 If a particular grouping construct in the regular expression was never
672 matched---for instance, if it appears inside of an alternative that
673 wasn't used, or inside of a repetition that repeated zero times---then
674 the corresponding @samp{\@var{digit}} construct never matches
675 anything. To use an artificial example,, @samp{\(foo\(b*\)\|lose\)\2}
676 cannot match @samp{lose}: the second alternative inside the larger
677 group matches it, but then @samp{\2} is undefined and can't match
678 anything. But it can match @samp{foobb}, because the first
679 alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
682 @cindex @samp{\w} in regexp
683 matches any word-constituent character. The editor syntax table
684 determines which characters these are. @xref{Syntax Tables}.
687 @cindex @samp{\W} in regexp
688 matches any character that is not a word constituent.
691 @cindex @samp{\s} in regexp
692 matches any character whose syntax is @var{code}. Here @var{code} is a
693 character that represents a syntax code: thus, @samp{w} for word
694 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
695 etc. To represent whitespace syntax, use either @samp{-} or a space
696 character. @xref{Syntax Class Table}, for a list of syntax codes and
697 the characters that stand for them.
700 @cindex @samp{\S} in regexp
701 matches any character whose syntax is not @var{code}.
704 matches any character whose category is @var{c}. Here @var{c} is a
705 character that represents a category: thus, @samp{c} for Chinese
706 characters or @samp{g} for Greek characters in the standard category
710 matches any character whose category is not @var{c}.
713 The following regular expression constructs match the empty string---that is,
714 they don't use up any characters---but whether they match depends on the
715 context. For all, the beginning and end of the accessible portion of
716 the buffer are treated as if they were the actual beginning and end of
721 @cindex @samp{\`} in regexp
722 matches the empty string, but only at the beginning
723 of the buffer or string being matched against.
726 @cindex @samp{\'} in regexp
727 matches the empty string, but only at the end of
728 the buffer or string being matched against.
731 @cindex @samp{\=} in regexp
732 matches the empty string, but only at point.
733 (This construct is not defined when matching against a string.)
736 @cindex @samp{\b} in regexp
737 matches the empty string, but only at the beginning or
738 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
739 @samp{foo} as a separate word. @samp{\bballs?\b} matches
740 @samp{ball} or @samp{balls} as a separate word.@refill
742 @samp{\b} matches at the beginning or end of the buffer (or string)
743 regardless of what text appears next to it.
746 @cindex @samp{\B} in regexp
747 matches the empty string, but @emph{not} at the beginning or
748 end of a word, nor at the beginning or end of the buffer (or string).
751 @cindex @samp{\<} in regexp
752 matches the empty string, but only at the beginning of a word.
753 @samp{\<} matches at the beginning of the buffer (or string) only if a
754 word-constituent character follows.
757 @cindex @samp{\>} in regexp
758 matches the empty string, but only at the end of a word. @samp{\>}
759 matches at the end of the buffer (or string) only if the contents end
760 with a word-constituent character.
763 @cindex @samp{\_<} in regexp
764 matches the empty string, but only at the beginning of a symbol. A
765 symbol is a sequence of one or more word or symbol constituent
766 characters. @samp{\_<} matches at the beginning of the buffer (or
767 string) only if a symbol-constituent character follows.
770 @cindex @samp{\_>} in regexp
771 matches the empty string, but only at the end of a symbol. @samp{\_>}
772 matches at the end of the buffer (or string) only if the contents end
773 with a symbol-constituent character.
776 @kindex invalid-regexp
777 Not every string is a valid regular expression. For example, a string
778 that ends inside a character alternative without terminating @samp{]}
779 is invalid, and so is a string that ends with a single @samp{\}. If
780 an invalid regular expression is passed to any of the search functions,
781 an @code{invalid-regexp} error is signaled.
784 @comment node-name, next, previous, up
785 @subsection Complex Regexp Example
787 Here is a complicated regexp which was formerly used by Emacs to
788 recognize the end of a sentence together with any whitespace that
789 follows. (Nowadays Emacs uses a similar but more complex default
790 regexp constructed by the function @code{sentence-end}.
791 @xref{Standard Regexps}.)
793 First, we show the regexp as a string in Lisp syntax to distinguish
794 spaces from tab characters. The string constant begins and ends with a
795 double-quote. @samp{\"} stands for a double-quote as part of the
796 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
797 tab and @samp{\n} for a newline.
800 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
804 In contrast, if you evaluate this string, you will see the following:
808 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
809 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
815 In this output, tab and newline appear as themselves.
817 This regular expression contains four parts in succession and can be
818 deciphered as follows:
822 The first part of the pattern is a character alternative that matches
823 any one of three characters: period, question mark, and exclamation
824 mark. The match must begin with one of these three characters. (This
825 is one point where the new default regexp used by Emacs differs from
826 the old. The new value also allows some non-@acronym{ASCII}
827 characters that end a sentence without any following whitespace.)
830 The second part of the pattern matches any closing braces and quotation
831 marks, zero or more of them, that may follow the period, question mark
832 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
833 a string. The @samp{*} at the end indicates that the immediately
834 preceding regular expression (a character alternative, in this case) may be
835 repeated zero or more times.
837 @item \\($\\|@ $\\|\t\\|@ @ \\)
838 The third part of the pattern matches the whitespace that follows the
839 end of a sentence: the end of a line (optionally with a space), or a
840 tab, or two spaces. The double backslashes mark the parentheses and
841 vertical bars as regular expression syntax; the parentheses delimit a
842 group and the vertical bars separate alternatives. The dollar sign is
843 used to match the end of a line.
846 Finally, the last part of the pattern matches any additional whitespace
847 beyond the minimum needed to end a sentence.
850 @node Regexp Functions
851 @subsection Regular Expression Functions
853 These functions operate on regular expressions.
855 @defun regexp-quote string
856 This function returns a regular expression whose only exact match is
857 @var{string}. Using this regular expression in @code{looking-at} will
858 succeed only if the next characters in the buffer are @var{string};
859 using it in a search function will succeed if the text being searched
860 contains @var{string}.
862 This allows you to request an exact string match or search when calling
863 a function that wants a regular expression.
867 (regexp-quote "^The cat$")
868 @result{} "\\^The cat\\$"
872 One use of @code{regexp-quote} is to combine an exact string match with
873 context described as a regular expression. For example, this searches
874 for the string that is the value of @var{string}, surrounded by
880 (concat "\\s-" (regexp-quote string) "\\s-"))
885 @defun regexp-opt strings &optional paren
886 This function returns an efficient regular expression that will match
887 any of the strings in the list @var{strings}. This is useful when you
888 need to make matching or searching as fast as possible---for example,
891 If the optional argument @var{paren} is non-@code{nil}, then the
892 returned regular expression is always enclosed by at least one
893 parentheses-grouping construct. If @var{paren} is @code{words}, then
894 that construct is additionally surrounded by @samp{\<} and @samp{\>}.
896 This simplified definition of @code{regexp-opt} produces a
897 regular expression which is equivalent to the actual value
898 (but not as efficient):
901 (defun regexp-opt (strings paren)
902 (let ((open-paren (if paren "\\(" ""))
903 (close-paren (if paren "\\)" "")))
905 (mapconcat 'regexp-quote strings "\\|")
910 @defun regexp-opt-depth regexp
911 This function returns the total number of grouping constructs
912 (parenthesized expressions) in @var{regexp}. (This does not include
917 @section Regular Expression Searching
918 @cindex regular expression searching
919 @cindex regexp searching
920 @cindex searching for regexp
922 In GNU Emacs, you can search for the next match for a regular
923 expression either incrementally or not. For incremental search
924 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
925 The GNU Emacs Manual}. Here we describe only the search functions
926 useful in programs. The principal one is @code{re-search-forward}.
928 These search functions convert the regular expression to multibyte if
929 the buffer is multibyte; they convert the regular expression to unibyte
930 if the buffer is unibyte. @xref{Text Representations}.
932 @deffn Command re-search-forward regexp &optional limit noerror repeat
933 This function searches forward in the current buffer for a string of
934 text that is matched by the regular expression @var{regexp}. The
935 function skips over any amount of text that is not matched by
936 @var{regexp}, and leaves point at the end of the first match found.
937 It returns the new value of point.
939 If @var{limit} is non-@code{nil}, it must be a position in the current
940 buffer. It specifies the upper bound to the search. No match
941 extending after that position is accepted.
943 If @var{repeat} is supplied, it must be a positive number; the search
944 is repeated that many times; each repetition starts at the end of the
945 previous match. If all these successive searches succeed, the search
946 succeeds, moving point and returning its new value. Otherwise the
947 search fails. What @code{re-search-forward} does when the search
948 fails depends on the value of @var{noerror}:
952 Signal a @code{search-failed} error.
954 Do nothing and return @code{nil}.
956 Move point to @var{limit} (or the end of the accessible portion of the
957 buffer) and return @code{nil}.
960 In the following example, point is initially before the @samp{T}.
961 Evaluating the search call moves point to the end of that line (between
962 the @samp{t} of @samp{hat} and the newline).
966 ---------- Buffer: foo ----------
967 I read "@point{}The cat in the hat
969 ---------- Buffer: foo ----------
973 (re-search-forward "[a-z]+" nil t 5)
976 ---------- Buffer: foo ----------
977 I read "The cat in the hat@point{}
979 ---------- Buffer: foo ----------
984 @deffn Command re-search-backward regexp &optional limit noerror repeat
985 This function searches backward in the current buffer for a string of
986 text that is matched by the regular expression @var{regexp}, leaving
987 point at the beginning of the first text found.
989 This function is analogous to @code{re-search-forward}, but they are not
990 simple mirror images. @code{re-search-forward} finds the match whose
991 beginning is as close as possible to the starting point. If
992 @code{re-search-backward} were a perfect mirror image, it would find the
993 match whose end is as close as possible. However, in fact it finds the
994 match whose beginning is as close as possible (and yet ends before the
995 starting point). The reason for this is that matching a regular
996 expression at a given spot always works from beginning to end, and
997 starts at a specified beginning position.
999 A true mirror-image of @code{re-search-forward} would require a special
1000 feature for matching regular expressions from end to beginning. It's
1001 not worth the trouble of implementing that.
1004 @defun string-match regexp string &optional start
1005 This function returns the index of the start of the first match for
1006 the regular expression @var{regexp} in @var{string}, or @code{nil} if
1007 there is no match. If @var{start} is non-@code{nil}, the search starts
1008 at that index in @var{string}.
1015 "quick" "The quick brown fox jumped quickly.")
1020 "quick" "The quick brown fox jumped quickly." 8)
1026 The index of the first character of the
1027 string is 0, the index of the second character is 1, and so on.
1029 After this function returns, the index of the first character beyond
1030 the match is available as @code{(match-end 0)}. @xref{Match Data}.
1035 "quick" "The quick brown fox jumped quickly." 8)
1046 @defun looking-at regexp
1047 This function determines whether the text in the current buffer directly
1048 following point matches the regular expression @var{regexp}. ``Directly
1049 following'' means precisely that: the search is ``anchored'' and it can
1050 succeed only starting with the first character following point. The
1051 result is @code{t} if so, @code{nil} otherwise.
1053 This function does not move point, but it updates the match data, which
1054 you can access using @code{match-beginning} and @code{match-end}.
1057 In this example, point is located directly before the @samp{T}. If it
1058 were anywhere else, the result would be @code{nil}.
1062 ---------- Buffer: foo ----------
1063 I read "@point{}The cat in the hat
1065 ---------- Buffer: foo ----------
1067 (looking-at "The cat in the hat$")
1073 @defun looking-back regexp &optional limit
1074 This function returns @code{t} if @var{regexp} matches text before
1075 point, ending at point, and @code{nil} otherwise.
1077 Because regular expression matching works only going forward, this is
1078 implemented by searching backwards from point for a match that ends at
1079 point. That can be quite slow if it has to search a long distance.
1080 You can bound the time required by specifying @var{limit}, which says
1081 not to search before @var{limit}. In this case, the match that is
1082 found must begin at or after @var{limit}.
1086 ---------- Buffer: foo ----------
1087 I read "@point{}The cat in the hat
1089 ---------- Buffer: foo ----------
1091 (looking-back "read \"" 3)
1093 (looking-back "read \"" 4)
1099 @defvar search-spaces-regexp
1100 If this variable is non-@code{nil}, it should be a regular expression
1101 that says how to search for whitespace. In that case, any group of
1102 spaces in a regular expression being searched for stands for use of
1103 this regular expression. However, spaces inside of constructs such as
1104 @samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
1105 @code{search-spaces-regexp}.
1107 Since this variable affects all regular expression search and match
1108 constructs, you should bind it temporarily for as small as possible
1113 @section POSIX Regular Expression Searching
1115 The usual regular expression functions do backtracking when necessary
1116 to handle the @samp{\|} and repetition constructs, but they continue
1117 this only until they find @emph{some} match. Then they succeed and
1118 report the first match found.
1120 This section describes alternative search functions which perform the
1121 full backtracking specified by the POSIX standard for regular expression
1122 matching. They continue backtracking until they have tried all
1123 possibilities and found all matches, so they can report the longest
1124 match, as required by POSIX. This is much slower, so use these
1125 functions only when you really need the longest match.
1127 The POSIX search and match functions do not properly support the
1128 non-greedy repetition operators. This is because POSIX backtracking
1129 conflicts with the semantics of non-greedy repetition.
1131 @defun posix-search-forward regexp &optional limit noerror repeat
1132 This is like @code{re-search-forward} except that it performs the full
1133 backtracking specified by the POSIX standard for regular expression
1137 @defun posix-search-backward regexp &optional limit noerror repeat
1138 This is like @code{re-search-backward} except that it performs the full
1139 backtracking specified by the POSIX standard for regular expression
1143 @defun posix-looking-at regexp
1144 This is like @code{looking-at} except that it performs the full
1145 backtracking specified by the POSIX standard for regular expression
1149 @defun posix-string-match regexp string &optional start
1150 This is like @code{string-match} except that it performs the full
1151 backtracking specified by the POSIX standard for regular expression
1156 @section The Match Data
1159 Emacs keeps track of the start and end positions of the segments of
1160 text found during a search; this is called the @dfn{match data}.
1161 Thanks to the match data, you can search for a complex pattern, such
1162 as a date in a mail message, and then extract parts of the match under
1163 control of the pattern.
1165 Because the match data normally describe the most recent search only,
1166 you must be careful not to do another search inadvertently between the
1167 search you wish to refer back to and the use of the match data. If you
1168 can't avoid another intervening search, you must save and restore the
1169 match data around it, to prevent it from being overwritten.
1172 * Replacing Match:: Replacing a substring that was matched.
1173 * Simple Match Data:: Accessing single items of match data,
1174 such as where a particular subexpression started.
1175 * Entire Match Data:: Accessing the entire match data at once, as a list.
1176 * Saving Match Data:: Saving and restoring the match data.
1179 @node Replacing Match
1180 @subsection Replacing the Text that Matched
1182 This function replaces all or part of the text matched by the last
1183 search. It works by means of the match data.
1185 @cindex case in replacements
1186 @defun replace-match replacement &optional fixedcase literal string subexp
1187 This function replaces the text in the buffer (or in @var{string}) that
1188 was matched by the last search. It replaces that text with
1191 If you did the last search in a buffer, you should specify @code{nil}
1192 for @var{string} and make sure that the current buffer when you call
1193 @code{replace-match} is the one in which you did the searching or
1194 matching. Then @code{replace-match} does the replacement by editing
1195 the buffer; it leaves point at the end of the replacement text, and
1198 If you did the search in a string, pass the same string as @var{string}.
1199 Then @code{replace-match} does the replacement by constructing and
1200 returning a new string.
1202 If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
1203 the replacement text without case conversion; otherwise, it converts
1204 the replacement text depending upon the capitalization of the text to
1205 be replaced. If the original text is all upper case, this converts
1206 the replacement text to upper case. If all words of the original text
1207 are capitalized, this capitalizes all the words of the replacement
1208 text. If all the words are one-letter and they are all upper case,
1209 they are treated as capitalized words rather than all-upper-case
1212 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1213 exactly as it is, the only alterations being case changes as needed.
1214 If it is @code{nil} (the default), then the character @samp{\} is treated
1215 specially. If a @samp{\} appears in @var{replacement}, then it must be
1216 part of one of the following sequences:
1220 @cindex @samp{&} in replacement
1221 @samp{\&} stands for the entire text being replaced.
1223 @item @samp{\@var{n}}
1224 @cindex @samp{\@var{n}} in replacement
1225 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1226 matched the @var{n}th subexpression in the original regexp.
1227 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1228 If the @var{n}th subexpression never matched, an empty string is substituted.
1231 @cindex @samp{\} in replacement
1232 @samp{\\} stands for a single @samp{\} in the replacement text.
1235 These substitutions occur after case conversion, if any,
1236 so the strings they substitute are never case-converted.
1238 If @var{subexp} is non-@code{nil}, that says to replace just
1239 subexpression number @var{subexp} of the regexp that was matched, not
1240 the entire match. For example, after matching @samp{foo \(ba*r\)},
1241 calling @code{replace-match} with 1 as @var{subexp} means to replace
1242 just the text that matched @samp{\(ba*r\)}.
1245 @node Simple Match Data
1246 @subsection Simple Match Data Access
1248 This section explains how to use the match data to find out what was
1249 matched by the last search or match operation, if it succeeded.
1251 You can ask about the entire matching text, or about a particular
1252 parenthetical subexpression of a regular expression. The @var{count}
1253 argument in the functions below specifies which. If @var{count} is
1254 zero, you are asking about the entire match. If @var{count} is
1255 positive, it specifies which subexpression you want.
1257 Recall that the subexpressions of a regular expression are those
1258 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1259 @var{count}th subexpression is found by counting occurrences of
1260 @samp{\(} from the beginning of the whole regular expression. The first
1261 subexpression is numbered 1, the second 2, and so on. Only regular
1262 expressions can have subexpressions---after a simple string search, the
1263 only information available is about the entire match.
1265 A search which fails may or may not alter the match data. In the
1266 past, a failing search did not do this, but we may change it in the
1267 future. So don't try to rely on the value of the match data after
1270 @defun match-string count &optional in-string
1271 This function returns, as a string, the text matched in the last search
1272 or match operation. It returns the entire text if @var{count} is zero,
1273 or just the portion corresponding to the @var{count}th parenthetical
1274 subexpression, if @var{count} is positive.
1276 If the last such operation was done against a string with
1277 @code{string-match}, then you should pass the same string as the
1278 argument @var{in-string}. After a buffer search or match,
1279 you should omit @var{in-string} or pass @code{nil} for it; but you
1280 should make sure that the current buffer when you call
1281 @code{match-string} is the one in which you did the searching or
1284 The value is @code{nil} if @var{count} is out of range, or for a
1285 subexpression inside a @samp{\|} alternative that wasn't used or a
1286 repetition that repeated zero times.
1289 @defun match-string-no-properties count &optional in-string
1290 This function is like @code{match-string} except that the result
1291 has no text properties.
1294 @defun match-beginning count
1295 This function returns the position of the start of text matched by the
1296 last regular expression searched for, or a subexpression of it.
1298 If @var{count} is zero, then the value is the position of the start of
1299 the entire match. Otherwise, @var{count} specifies a subexpression in
1300 the regular expression, and the value of the function is the starting
1301 position of the match for that subexpression.
1303 The value is @code{nil} for a subexpression inside a @samp{\|}
1304 alternative that wasn't used or a repetition that repeated zero times.
1307 @defun match-end count
1308 This function is like @code{match-beginning} except that it returns the
1309 position of the end of the match, rather than the position of the
1313 Here is an example of using the match data, with a comment showing the
1314 positions within the text:
1318 (string-match "\\(qu\\)\\(ick\\)"
1319 "The quick fox jumped quickly.")
1325 (match-string 0 "The quick fox jumped quickly.")
1327 (match-string 1 "The quick fox jumped quickly.")
1329 (match-string 2 "The quick fox jumped quickly.")
1334 (match-beginning 1) ; @r{The beginning of the match}
1335 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1339 (match-beginning 2) ; @r{The beginning of the match}
1340 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1344 (match-end 1) ; @r{The end of the match}
1345 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1347 (match-end 2) ; @r{The end of the match}
1348 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1352 Here is another example. Point is initially located at the beginning
1353 of the line. Searching moves point to between the space and the word
1354 @samp{in}. The beginning of the entire match is at the 9th character of
1355 the buffer (@samp{T}), and the beginning of the match for the first
1356 subexpression is at the 13th character (@samp{c}).
1361 (re-search-forward "The \\(cat \\)")
1363 (match-beginning 1))
1368 ---------- Buffer: foo ----------
1369 I read "The cat @point{}in the hat comes back" twice.
1372 ---------- Buffer: foo ----------
1377 (In this case, the index returned is a buffer position; the first
1378 character of the buffer counts as 1.)
1380 @node Entire Match Data
1381 @subsection Accessing the Entire Match Data
1383 The functions @code{match-data} and @code{set-match-data} read or
1384 write the entire match data, all at once.
1386 @defun match-data &optional integers reuse reseat
1387 This function returns a list of positions (markers or integers) that
1388 record all the information on what text the last search matched.
1389 Element zero is the position of the beginning of the match for the
1390 whole expression; element one is the position of the end of the match
1391 for the expression. The next two elements are the positions of the
1392 beginning and end of the match for the first subexpression, and so on.
1398 number {\mathsurround=0pt $2n$}
1400 corresponds to @code{(match-beginning @var{n})}; and
1406 number {\mathsurround=0pt $2n+1$}
1408 corresponds to @code{(match-end @var{n})}.
1410 Normally all the elements are markers or @code{nil}, but if
1411 @var{integers} is non-@code{nil}, that means to use integers instead
1412 of markers. (In that case, the buffer itself is appended as an
1413 additional element at the end of the list, to facilitate complete
1414 restoration of the match data.) If the last match was done on a
1415 string with @code{string-match}, then integers are always used,
1416 since markers can't point into a string.
1418 If @var{reuse} is non-@code{nil}, it should be a list. In that case,
1419 @code{match-data} stores the match data in @var{reuse}. That is,
1420 @var{reuse} is destructively modified. @var{reuse} does not need to
1421 have the right length. If it is not long enough to contain the match
1422 data, it is extended. If it is too long, the length of @var{reuse}
1423 stays the same, but the elements that were not used are set to
1424 @code{nil}. The purpose of this feature is to reduce the need for
1427 If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
1428 are reseated to point to nowhere.
1430 As always, there must be no possibility of intervening searches between
1431 the call to a search function and the call to @code{match-data} that is
1432 intended to access the match data for that search.
1437 @result{} (#<marker at 9 in foo>
1438 #<marker at 17 in foo>
1439 #<marker at 13 in foo>
1440 #<marker at 17 in foo>)
1445 @defun set-match-data match-list &optional reseat
1446 This function sets the match data from the elements of @var{match-list},
1447 which should be a list that was the value of a previous call to
1448 @code{match-data}. (More precisely, anything that has the same format
1451 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1452 an error; that sets the match data in a meaningless but harmless way.
1454 If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
1455 are reseated to point to nowhere.
1457 @findex store-match-data
1458 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1461 @node Saving Match Data
1462 @subsection Saving and Restoring the Match Data
1464 When you call a function that may do a search, you may need to save
1465 and restore the match data around that call, if you want to preserve the
1466 match data from an earlier search for later use. Here is an example
1467 that shows the problem that arises if you fail to save the match data:
1471 (re-search-forward "The \\(cat \\)")
1473 (foo) ; @r{Perhaps @code{foo} does}
1474 ; @r{more searching.}
1476 @result{} 61 ; @r{Unexpected result---not 48!}
1480 You can save and restore the match data with @code{save-match-data}:
1482 @defmac save-match-data body@dots{}
1483 This macro executes @var{body}, saving and restoring the match
1484 data around it. The return value is the value of the last form in
1488 You could use @code{set-match-data} together with @code{match-data} to
1489 imitate the effect of the special form @code{save-match-data}. Here is
1494 (let ((data (match-data)))
1496 @dots{} ; @r{Ok to change the original match data.}
1497 (set-match-data data)))
1501 Emacs automatically saves and restores the match data when it runs
1502 process filter functions (@pxref{Filter Functions}) and process
1503 sentinels (@pxref{Sentinels}).
1506 Here is a function which restores the match data provided the buffer
1507 associated with it still exists.
1511 (defun restore-match-data (data)
1512 @c It is incorrect to split the first line of a doc string.
1513 @c If there's a problem here, it should be solved in some other way.
1514 "Restore the match data DATA unless the buffer is missing."
1520 (null (marker-buffer (car d)))
1522 ;; @file{match-data} @r{buffer is deleted.}
1525 (set-match-data data))))
1530 @node Search and Replace
1531 @section Search and Replace
1534 If you want to find all matches for a regexp in part of the buffer,
1535 and replace them, the best way is to write an explicit loop using
1536 @code{re-search-forward} and @code{replace-match}, like this:
1539 (while (re-search-forward "foo[ \t]+bar" nil t)
1540 (replace-match "foobar"))
1544 @xref{Replacing Match,, Replacing the Text that Matched}, for a
1545 description of @code{replace-match}.
1547 However, replacing matches in a string is more complex, especially
1548 if you want to do it efficiently. So Emacs provides a function to do
1551 @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
1552 This function copies @var{string} and searches it for matches for
1553 @var{regexp}, and replaces them with @var{rep}. It returns the
1554 modified copy. If @var{start} is non-@code{nil}, the search for
1555 matches starts at that index in @var{string}, so matches starting
1556 before that index are not changed.
1558 This function uses @code{replace-match} to do the replacement, and it
1559 passes the optional arguments @var{fixedcase}, @var{literal} and
1560 @var{subexp} along to @code{replace-match}.
1562 Instead of a string, @var{rep} can be a function. In that case,
1563 @code{replace-regexp-in-string} calls @var{rep} for each match,
1564 passing the text of the match as its sole argument. It collects the
1565 value @var{rep} returns and passes that to @code{replace-match} as the
1566 replacement string. The match-data at this point are the result
1567 of matching @var{regexp} against a substring of @var{string}.
1570 If you want to write a command along the lines of @code{query-replace},
1571 you can use @code{perform-replace} to do the work.
1573 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
1574 This function is the guts of @code{query-replace} and related
1575 commands. It searches for occurrences of @var{from-string} in the
1576 text between positions @var{start} and @var{end} and replaces some or
1577 all of them. If @var{start} is @code{nil} (or omitted), point is used
1578 instead, and the end of the buffer's accessible portion is used for
1581 If @var{query-flag} is @code{nil}, it replaces all
1582 occurrences; otherwise, it asks the user what to do about each one.
1584 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
1585 considered a regular expression; otherwise, it must match literally. If
1586 @var{delimited-flag} is non-@code{nil}, then only replacements
1587 surrounded by word boundaries are considered.
1589 The argument @var{replacements} specifies what to replace occurrences
1590 with. If it is a string, that string is used. It can also be a list of
1591 strings, to be used in cyclic order.
1593 If @var{replacements} is a cons cell, @code{(@var{function}
1594 . @var{data})}, this means to call @var{function} after each match to
1595 get the replacement text. This function is called with two arguments:
1596 @var{data}, and the number of replacements already made.
1598 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
1599 it specifies how many times to use each of the strings in the
1600 @var{replacements} list before advancing cyclically to the next one.
1602 If @var{from-string} contains upper-case letters, then
1603 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
1604 it uses the @code{replacements} without altering the case of them.
1606 Normally, the keymap @code{query-replace-map} defines the possible
1607 user responses for queries. The argument @var{map}, if
1608 non-@code{nil}, specifies a keymap to use instead of
1609 @code{query-replace-map}.
1612 @defvar query-replace-map
1613 This variable holds a special keymap that defines the valid user
1614 responses for @code{perform-replace} and the commands that use it, as
1615 well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual
1620 The ``key bindings'' are not commands, just symbols that are meaningful
1621 to the functions that use this map.
1624 Prefix keys are not supported; each key binding must be for a
1625 single-event key sequence. This is because the functions don't use
1626 @code{read-key-sequence} to get the input; instead, they read a single
1627 event and look it up ``by hand.''
1631 Here are the meaningful ``bindings'' for @code{query-replace-map}.
1632 Several of them are meaningful only for @code{query-replace} and
1637 Do take the action being considered---in other words, ``yes.''
1640 Do not take action for this question---in other words, ``no.''
1643 Answer this question ``no,'' and give up on the entire series of
1644 questions, assuming that the answers will be ``no.''
1647 Answer this question ``yes,'' and give up on the entire series of
1648 questions, assuming that subsequent answers will be ``no.''
1651 Answer this question ``yes,'' but show the results---don't advance yet
1652 to the next question.
1655 Answer this question and all subsequent questions in the series with
1656 ``yes,'' without further user interaction.
1659 Move back to the previous place that a question was asked about.
1662 Enter a recursive edit to deal with this question---instead of any
1663 other action that would normally be taken.
1665 @item delete-and-edit
1666 Delete the text being considered, then enter a recursive edit to replace
1670 Redisplay and center the window, then ask the same question again.
1673 Perform a quit right away. Only @code{y-or-n-p} and related functions
1677 Display some help, then ask again.
1680 @node Standard Regexps
1681 @section Standard Regular Expressions Used in Editing
1682 @cindex regexps used standardly in editing
1683 @cindex standard regexps used in editing
1685 This section describes some variables that hold regular expressions
1686 used for certain purposes in editing:
1688 @defvar page-delimiter
1689 This is the regular expression describing line-beginnings that separate
1690 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1691 @code{"^\C-l"}); this matches a line that starts with a formfeed
1695 The following two regular expressions should @emph{not} assume the
1696 match always starts at the beginning of a line; they should not use
1697 @samp{^} to anchor the match. Most often, the paragraph commands do
1698 check for a match only at the beginning of a line, which means that
1699 @samp{^} would be superfluous. When there is a nonzero left margin,
1700 they accept matches that start after the left margin. In that case, a
1701 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1702 where a left margin is never used.
1704 @defvar paragraph-separate
1705 This is the regular expression for recognizing the beginning of a line
1706 that separates paragraphs. (If you change this, you may have to
1707 change @code{paragraph-start} also.) The default value is
1708 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1709 spaces, tabs, and form feeds (after its left margin).
1712 @defvar paragraph-start
1713 This is the regular expression for recognizing the beginning of a line
1714 that starts @emph{or} separates paragraphs. The default value is
1715 @w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
1716 whitespace or starting with a form feed (after its left margin).
1719 @defvar sentence-end
1720 If non-@code{nil}, the value should be a regular expression describing
1721 the end of a sentence, including the whitespace following the
1722 sentence. (All paragraph boundaries also end sentences, regardless.)
1724 If the value is @code{nil}, the default, then the function
1725 @code{sentence-end} has to construct the regexp. That is why you
1726 should always call the function @code{sentence-end} to obtain the
1727 regexp to be used to recognize the end of a sentence.
1731 This function returns the value of the variable @code{sentence-end},
1732 if non-@code{nil}. Otherwise it returns a default value based on the
1733 values of the variables @code{sentence-end-double-space}
1734 (@pxref{Definition of sentence-end-double-space}),
1735 @code{sentence-end-without-period} and
1736 @code{sentence-end-without-space}.
1740 arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f