2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990-1995, 1998-1999, 2001-2015 Free Software
5 @c See the file elisp.texi for copying conditions.
6 @node Searching and Matching
7 @chapter Searching and Matching
10 GNU Emacs provides two ways to search through a buffer for specified
11 text: exact string searches and regular expression searches. After a
12 regular expression search, you can examine the @dfn{match data} to
13 determine which text matched the whole regular expression or various
17 * String Search:: Search for an exact match.
18 * Searching and Case:: Case-independent or case-significant searching.
19 * Regular Expressions:: Describing classes of strings.
20 * Regexp Search:: Searching for a match for a regexp.
21 * POSIX Regexps:: Searching POSIX-style for the longest match.
22 * Match Data:: Finding out which part of the text matched,
23 after a string or regexp search.
24 * Search and Replace:: Commands that loop, searching and replacing.
25 * Standard Regexps:: Useful regexps for finding sentences, pages,...
28 The @samp{skip-chars@dots{}} functions also perform a kind of searching.
29 @xref{Skipping Characters}. To search for changes in character
30 properties, see @ref{Property Search}.
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}
40 is 1. For more details on interactive searching, @pxref{Search,,
41 Searching and Replacement, emacs, The GNU Emacs Manual}.
43 These search functions convert the search string to multibyte if the
44 buffer is multibyte; they convert the search string to unibyte if the
45 buffer is unibyte. @xref{Text Representations}.
47 @deffn Command search-forward string &optional limit noerror repeat
48 This function searches forward from point for an exact match for
49 @var{string}. If successful, it sets point to the end of the occurrence
50 found, and returns the new value of point. If no match is found, the
51 value and side effects depend on @var{noerror} (see below).
53 In the following example, point is initially at the beginning of the
54 line. Then @code{(search-forward "fox")} moves point after the last
59 ---------- Buffer: foo ----------
60 @point{}The quick brown fox jumped over the lazy dog.
61 ---------- Buffer: foo ----------
65 (search-forward "fox")
68 ---------- Buffer: foo ----------
69 The quick brown fox@point{} jumped over the lazy dog.
70 ---------- Buffer: foo ----------
74 The argument @var{limit} specifies the bound to the search, and should
75 be a position in the current buffer. No match extending after
76 that position is accepted. If @var{limit} is omitted or @code{nil}, it
77 defaults to the end of the accessible portion of the buffer.
80 What happens when the search fails depends on the value of
81 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
82 error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
83 returns @code{nil} and does nothing. If @var{noerror} is neither
84 @code{nil} nor @code{t}, then @code{search-forward} moves point to the
85 upper bound and returns @code{nil}.
86 @c I see no prospect of this ever changing, and frankly the current
87 @c behavior seems better, so there seems no need to mention this.
89 (It would be more consistent now to return the new position of point
90 in that case, but some existing programs may depend on a value of
94 The argument @var{noerror} only affects valid searches which fail to
95 find a match. Invalid arguments cause errors regardless of
98 If @var{repeat} is a positive number @var{n}, it serves as a repeat
99 count: the search is repeated @var{n} times, each time starting at the
100 end of the previous time's match. If these successive searches
101 succeed, the function succeeds, moving point and returning its new
102 value. Otherwise the search fails, with results depending on the
103 value of @var{noerror}, as described above. If @var{repeat} is a
104 negative number -@var{n}, it serves as a repeat count of @var{n} for a
105 search in the opposite (backward) direction.
108 @deffn Command search-backward string &optional limit noerror repeat
109 This function searches backward from point for @var{string}. It is
110 like @code{search-forward}, except that it searches backwards rather
111 than forwards. Backward searches leave point at the beginning of the
115 @deffn Command word-search-forward string &optional limit noerror repeat
116 This function searches forward from point for a ``word'' match for
117 @var{string}. If it finds a match, it sets point to the end of the
118 match found, and returns the new value of point.
120 Word matching regards @var{string} as a sequence of words, disregarding
121 punctuation that separates them. It searches the buffer for the same
122 sequence of words. Each word must be distinct in the buffer (searching
123 for the word @samp{ball} does not match the word @samp{balls}), but the
124 details of punctuation and spacing are ignored (searching for @samp{ball
125 boy} does match @samp{ball. Boy!}).
127 In this example, point is initially at the beginning of the buffer; the
128 search leaves it between the @samp{y} and the @samp{!}.
132 ---------- Buffer: foo ----------
133 @point{}He said "Please! Find
135 ---------- Buffer: foo ----------
139 (word-search-forward "Please find the ball, boy.")
142 ---------- Buffer: foo ----------
143 He said "Please! Find
144 the ball boy@point{}!"
145 ---------- Buffer: foo ----------
149 If @var{limit} is non-@code{nil}, it must be a position in the current
150 buffer; it specifies the upper bound to the search. The match found
151 must not extend after that position.
153 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
154 an error if the search fails. If @var{noerror} is @code{t}, then it
155 returns @code{nil} instead of signaling an error. If @var{noerror} is
156 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
157 end of the accessible portion of the buffer) and returns @code{nil}.
159 If @var{repeat} is non-@code{nil}, then the search is repeated that many
160 times. Point is positioned at the end of the last match.
162 @findex word-search-regexp
163 Internally, @code{word-search-forward} and related functions use the
164 function @code{word-search-regexp} to convert @var{string} to a
165 regular expression that ignores punctuation.
168 @deffn Command word-search-forward-lax string &optional limit noerror repeat
169 This command is identical to @code{word-search-forward}, except that
170 the beginning or the end of @var{string} need not match a word
171 boundary, unless @var{string} begins or ends in whitespace.
172 For instance, searching for @samp{ball boy} matches @samp{ball boyee},
173 but does not match @samp{balls boy}.
176 @deffn Command word-search-backward string &optional limit noerror repeat
177 This function searches backward from point for a word match to
178 @var{string}. This function is just like @code{word-search-forward}
179 except that it searches backward and normally leaves point at the
180 beginning of the match.
183 @deffn Command word-search-backward-lax string &optional limit noerror repeat
184 This command is identical to @code{word-search-backward}, except that
185 the beginning or the end of @var{string} need not match a word
186 boundary, unless @var{string} begins or ends in whitespace.
189 @node Searching and Case
190 @section Searching and Case
191 @cindex searching and case
193 By default, searches in Emacs ignore the case of the text they are
194 searching through; if you specify searching for @samp{FOO}, then
195 @samp{Foo} or @samp{foo} is also considered a match. This applies to
196 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
197 @samp{A} or @samp{b} or @samp{B}.
199 If you do not want this feature, set the variable
200 @code{case-fold-search} to @code{nil}. Then all letters must match
201 exactly, including case. This is a buffer-local variable; altering the
202 variable affects only the current buffer. (@xref{Intro to
203 Buffer-Local}.) Alternatively, you may change the default value.
204 In Lisp code, you will more typically use @code{let} to bind
205 @code{case-fold-search} to the desired value.
207 Note that the user-level incremental search feature handles case
208 distinctions differently. When the search string contains only lower
209 case letters, the search ignores case, but when the search string
210 contains one or more upper case letters, the search becomes
211 case-sensitive. But this has nothing to do with the searching
212 functions used in Lisp code. @xref{Incremental Search,,, emacs,
213 The GNU Emacs Manual}.
215 @defopt case-fold-search
216 This buffer-local variable determines whether searches should ignore
217 case. If the variable is @code{nil} they do not ignore case; otherwise
218 (and by default) they do ignore case.
222 This variable determines whether the higher-level replacement
223 functions should preserve case. If the variable is @code{nil}, that
224 means to use the replacement text verbatim. A non-@code{nil} value
225 means to convert the case of the replacement text according to the
228 This variable is used by passing it as an argument to the function
229 @code{replace-match}. @xref{Replacing Match}.
232 @node Regular Expressions
233 @section Regular Expressions
234 @cindex regular expression
237 A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that
238 denotes a (possibly infinite) set of strings. Searching for matches for
239 a regexp is a very powerful operation. This section explains how to write
240 regexps; the following section says how to search for them.
243 @cindex regular expressions, developing
244 For interactive development of regular expressions, you
245 can use the @kbd{M-x re-builder} command. It provides a convenient
246 interface for creating regular expressions, by giving immediate visual
247 feedback in a separate buffer. As you edit the regexp, all its
248 matches in the target buffer are highlighted. Each parenthesized
249 sub-expression of the regexp is shown in a distinct face, which makes
250 it easier to verify even very complex regexps.
253 * Syntax of Regexps:: Rules for writing regular expressions.
254 * Regexp Example:: Illustrates regular expression syntax.
255 * Regexp Functions:: Functions for operating on regular expressions.
258 @node Syntax of Regexps
259 @subsection Syntax of Regular Expressions
260 @cindex regexp syntax
261 @cindex syntax of regular expressions
263 Regular expressions have a syntax in which a few characters are
264 special constructs and the rest are @dfn{ordinary}. An ordinary
265 character is a simple regular expression that matches that character
266 and nothing else. The special characters are @samp{.}, @samp{*},
267 @samp{+}, @samp{?}, @samp{[}, @samp{^}, @samp{$}, and @samp{\}; no new
268 special characters will be defined in the future. The character
269 @samp{]} is special if it ends a character alternative (see later).
270 The character @samp{-} is special inside a character alternative. A
271 @samp{[:} and balancing @samp{:]} enclose a character class inside a
272 character alternative. Any other character appearing in a regular
273 expression is ordinary, unless a @samp{\} precedes it.
275 For example, @samp{f} is not a special character, so it is ordinary, and
276 therefore @samp{f} is a regular expression that matches the string
277 @samp{f} and no other string. (It does @emph{not} match the string
278 @samp{fg}, but it does match a @emph{part} of that string.) Likewise,
279 @samp{o} is a regular expression that matches only @samp{o}.
281 Any two regular expressions @var{a} and @var{b} can be concatenated. The
282 result is a regular expression that matches a string if @var{a} matches
283 some amount of the beginning of that string and @var{b} matches the rest of
286 As a simple example, we can concatenate the regular expressions @samp{f}
287 and @samp{o} to get the regular expression @samp{fo}, which matches only
288 the string @samp{fo}. Still trivial. To do something more powerful, you
289 need to use one of the special regular expression constructs.
292 * Regexp Special:: Special characters in regular expressions.
293 * Char Classes:: Character classes used in regular expressions.
294 * Regexp Backslash:: Backslash-sequences in regular expressions.
298 @subsubsection Special Characters in Regular Expressions
299 @cindex regexp, special characters in
301 Here is a list of the characters that are special in a regular
306 @item @samp{.}@: @r{(Period)}
307 @cindex @samp{.} in regexp
308 is a special character that matches any single character except a newline.
309 Using concatenation, we can make regular expressions like @samp{a.b}, which
310 matches any three-character string that begins with @samp{a} and ends with
314 @cindex @samp{*} in regexp
315 is not a construct by itself; it is a postfix operator that means to
316 match the preceding regular expression repetitively as many times as
317 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
320 @samp{*} always applies to the @emph{smallest} possible preceding
321 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
322 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
324 @cindex backtracking and regular expressions
325 The matcher processes a @samp{*} construct by matching, immediately, as
326 many repetitions as can be found. Then it continues with the rest of
327 the pattern. If that fails, backtracking occurs, discarding some of the
328 matches of the @samp{*}-modified construct in the hope that that will
329 make it possible to match the rest of the pattern. For example, in
330 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
331 first tries to match all three @samp{a}s; but the rest of the pattern is
332 @samp{ar} and there is only @samp{r} left to match, so this try fails.
333 The next alternative is for @samp{a*} to match only two @samp{a}s. With
334 this choice, the rest of the regexp matches successfully.
336 @strong{Warning:} Nested repetition operators can run for an
337 indefinitely long time, if they lead to ambiguous matching. For
338 example, trying to match the regular expression @samp{\(x+y*\)*a}
339 against the string @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz} could
340 take hours before it ultimately fails. Emacs must try each way of
341 grouping the @samp{x}s before concluding that none of them can work.
342 Even worse, @samp{\(x*\)*} can match the null string in infinitely
343 many ways, so it causes an infinite loop. To avoid these problems,
344 check nested repetitions carefully, to make sure that they do not
345 cause combinatorial explosions in backtracking.
348 @cindex @samp{+} in regexp
349 is a postfix operator, similar to @samp{*} except that it must match
350 the preceding expression at least once. So, for example, @samp{ca+r}
351 matches the strings @samp{car} and @samp{caaaar} but not the string
352 @samp{cr}, whereas @samp{ca*r} matches all three strings.
355 @cindex @samp{?} in regexp
356 is a postfix operator, similar to @samp{*} except that it must match the
357 preceding expression either once or not at all. For example,
358 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
360 @item @samp{*?}, @samp{+?}, @samp{??}
361 @cindex non-greedy repetition characters in regexp
362 These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
363 and @samp{?}. Where those operators match the largest possible
364 substring (consistent with matching the entire containing expression),
365 the non-greedy variants match the smallest possible substring
366 (consistent with matching the entire containing expression).
368 For example, the regular expression @samp{c[ad]*a} when applied to the
369 string @samp{cdaaada} matches the whole string; but the regular
370 expression @samp{c[ad]*?a}, applied to that same string, matches just
371 @samp{cda}. (The smallest possible match here for @samp{[ad]*?} that
372 permits the whole expression to match is @samp{d}.)
374 @item @samp{[ @dots{} ]}
375 @cindex character alternative (in regexp)
376 @cindex @samp{[} in regexp
377 @cindex @samp{]} in regexp
378 is a @dfn{character alternative}, which begins with @samp{[} and is
379 terminated by @samp{]}. In the simplest case, the characters between
380 the two brackets are what this character alternative can match.
382 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
383 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
384 (including the empty string). It follows that @samp{c[ad]*r}
385 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
387 You can also include character ranges in a character alternative, by
388 writing the starting and ending characters with a @samp{-} between them.
389 Thus, @samp{[a-z]} matches any lower-case @acronym{ASCII} letter.
390 Ranges may be intermixed freely with individual characters, as in
391 @samp{[a-z$%.]}, which matches any lower case @acronym{ASCII} letter
392 or @samp{$}, @samp{%} or period.
394 If @code{case-fold-search} is non-@code{nil}, @samp{[a-z]} also
395 matches upper-case letters. Note that a range like @samp{[a-z]} is
396 not affected by the locale's collation sequence, it always represents
397 a sequence in @acronym{ASCII} order.
398 @c This wasn't obvious to me, since, e.g., the grep manual "Character
399 @c Classes and Bracket Expressions" specifically notes the opposite
400 @c behavior. But by experiment Emacs seems unaffected by LC_COLLATE
403 Note also that the usual regexp special characters are not special inside a
404 character alternative. A completely different set of characters is
405 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
407 To include a @samp{]} in a character alternative, you must make it the
408 first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
409 To include a @samp{-}, write @samp{-} as the first or last character of
410 the character alternative, or put it after a range. Thus, @samp{[]-]}
411 matches both @samp{]} and @samp{-}. (As explained below, you cannot
412 use @samp{\]} to include a @samp{]} inside a character alternative,
413 since @samp{\} is not special there.)
415 To include @samp{^} in a character alternative, put it anywhere but at
418 @c What if it starts with a multibyte and ends with a unibyte?
419 @c That doesn't seem to match anything...?
420 If a range starts with a unibyte character @var{c} and ends with a
421 multibyte character @var{c2}, the range is divided into two parts: one
422 spans the unibyte characters @samp{@var{c}..?\377}, the other the
423 multibyte characters @samp{@var{c1}..@var{c2}}, where @var{c1} is the
424 first character of the charset to which @var{c2} belongs.
426 A character alternative can also specify named character classes
427 (@pxref{Char Classes}). This is a POSIX feature. For example,
428 @samp{[[:ascii:]]} matches any @acronym{ASCII} character.
429 Using a character class is equivalent to mentioning each of the
430 characters in that class; but the latter is not feasible in practice,
431 since some classes include thousands of different characters.
433 @item @samp{[^ @dots{} ]}
434 @cindex @samp{^} in regexp
435 @samp{[^} begins a @dfn{complemented character alternative}. This
436 matches any character except the ones specified. Thus,
437 @samp{[^a-z0-9A-Z]} matches all characters @emph{except} letters and
440 @samp{^} is not special in a character alternative unless it is the first
441 character. The character following the @samp{^} is treated as if it
442 were first (in other words, @samp{-} and @samp{]} are not special there).
444 A complemented character alternative can match a newline, unless newline is
445 mentioned as one of the characters not to match. This is in contrast to
446 the handling of regexps in programs such as @code{grep}.
448 You can specify named character classes, just like in character
449 alternatives. For instance, @samp{[^[:ascii:]]} matches any
450 non-@acronym{ASCII} character. @xref{Char Classes}.
453 @cindex beginning of line in regexp
454 When matching a buffer, @samp{^} matches the empty string, but only at the
455 beginning of a line in the text being matched (or the beginning of the
456 accessible portion of the buffer). Otherwise it fails to match
457 anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at the
460 When matching a string instead of a buffer, @samp{^} matches at the
461 beginning of the string or after a newline character.
463 For historical compatibility reasons, @samp{^} can be used only at the
464 beginning of the regular expression, or after @samp{\(}, @samp{\(?:}
468 @cindex @samp{$} in regexp
469 @cindex end of line in regexp
470 is similar to @samp{^} but matches only at the end of a line (or the
471 end of the accessible portion of the buffer). Thus, @samp{x+$}
472 matches a string of one @samp{x} or more at the end of a line.
474 When matching a string instead of a buffer, @samp{$} matches at the end
475 of the string or before a newline character.
477 For historical compatibility reasons, @samp{$} can be used only at the
478 end of the regular expression, or before @samp{\)} or @samp{\|}.
481 @cindex @samp{\} in regexp
482 has two functions: it quotes the special characters (including
483 @samp{\}), and it introduces additional special constructs.
485 Because @samp{\} quotes special characters, @samp{\$} is a regular
486 expression that matches only @samp{$}, and @samp{\[} is a regular
487 expression that matches only @samp{[}, and so on.
489 Note that @samp{\} also has special meaning in the read syntax of Lisp
490 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
491 example, the regular expression that matches the @samp{\} character is
492 @samp{\\}. To write a Lisp string that contains the characters
493 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
494 @samp{\}. Therefore, the read syntax for a regular expression matching
495 @samp{\} is @code{"\\\\"}.
498 @strong{Please note:} For historical compatibility, special characters
499 are treated as ordinary ones if they are in contexts where their special
500 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
501 ordinary since there is no preceding expression on which the @samp{*}
502 can act. It is poor practice to depend on this behavior; quote the
503 special character anyway, regardless of where it appears.
505 As a @samp{\} is not special inside a character alternative, it can
506 never remove the special meaning of @samp{-} or @samp{]}. So you
507 should not quote these characters when they have no special meaning
508 either. This would not clarify anything, since backslashes can
509 legitimately precede these characters where they @emph{have} special
510 meaning, as in @samp{[^\]} (@code{"[^\\]"} for Lisp string syntax),
511 which matches any single character except a backslash.
513 In practice, most @samp{]} that occur in regular expressions close a
514 character alternative and hence are special. However, occasionally a
515 regular expression may try to match a complex pattern of literal
516 @samp{[} and @samp{]}. In such situations, it sometimes may be
517 necessary to carefully parse the regexp from the start to determine
518 which square brackets enclose a character alternative. For example,
519 @samp{[^][]]} consists of the complemented character alternative
520 @samp{[^][]} (which matches any single character that is not a square
521 bracket), followed by a literal @samp{]}.
523 The exact rules are that at the beginning of a regexp, @samp{[} is
524 special and @samp{]} not. This lasts until the first unquoted
525 @samp{[}, after which we are in a character alternative; @samp{[} is
526 no longer special (except when it starts a character class) but @samp{]}
527 is special, unless it immediately follows the special @samp{[} or that
528 @samp{[} followed by a @samp{^}. This lasts until the next special
529 @samp{]} that does not end a character class. This ends the character
530 alternative and restores the ordinary syntax of regular expressions;
531 an unquoted @samp{[} is special again and a @samp{]} not.
534 @subsubsection Character Classes
535 @cindex character classes in regexp
537 Here is a table of the classes you can use in a character alternative,
542 This matches any @acronym{ASCII} character (codes 0--127).
544 This matches any letter or digit. For multibyte characters, it
545 matches characters whose Unicode @samp{general-category} property
546 (@pxref{Character Properties}) indicates they are alphabetic or
547 decimal number characters.
549 This matches any letter. For multibyte characters, it matches
550 characters whose Unicode @samp{general-category} property
551 (@pxref{Character Properties}) indicates they are alphabetic
554 This matches space and tab only.
556 This matches any @acronym{ASCII} control character.
558 This matches @samp{0} through @samp{9}. Thus, @samp{[-+[:digit:]]}
559 matches any digit, as well as @samp{+} and @samp{-}.
561 This matches graphic characters---everything except @acronym{ASCII} control
562 characters, space, and the delete character.
564 This matches any lower-case letter, as determined by the current case
565 table (@pxref{Case Tables}). If @code{case-fold-search} is
566 non-@code{nil}, this also matches any upper-case letter.
568 This matches any multibyte character (@pxref{Text Representations}).
570 This matches any non-@acronym{ASCII} character.
572 This matches printing characters---everything except @acronym{ASCII} control
573 characters and the delete character.
575 This matches any punctuation character. (At present, for multibyte
576 characters, it matches anything that has non-word syntax.)
578 This matches any character that has whitespace syntax
579 (@pxref{Syntax Class Table}).
581 This matches any unibyte character (@pxref{Text Representations}).
583 This matches any upper-case letter, as determined by the current case
584 table (@pxref{Case Tables}). If @code{case-fold-search} is
585 non-@code{nil}, this also matches any lower-case letter.
587 This matches any character that has word syntax (@pxref{Syntax Class
590 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
591 through @samp{f} and @samp{A} through @samp{F}.
594 @node Regexp Backslash
595 @subsubsection Backslash Constructs in Regular Expressions
596 @cindex backslash in regular expressions
598 For the most part, @samp{\} followed by any character matches only
599 that character. However, there are several exceptions: certain
600 sequences starting with @samp{\} that have special meanings. Here is
601 a table of the special @samp{\} constructs.
605 @cindex @samp{|} in regexp
606 @cindex regexp alternative
607 specifies an alternative.
608 Two regular expressions @var{a} and @var{b} with @samp{\|} in
609 between form an expression that matches anything that either @var{a} or
612 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
615 @samp{\|} applies to the largest possible surrounding expressions. Only a
616 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
619 If you need full backtracking capability to handle multiple uses of
620 @samp{\|}, use the POSIX regular expression functions (@pxref{POSIX
624 is a postfix operator that repeats the previous pattern exactly @var{m}
625 times. Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
626 and nothing else. @samp{c[ad]\@{3\@}r} matches string such as
627 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
629 @item \@{@var{m},@var{n}\@}
630 is a more general postfix operator that specifies repetition with a
631 minimum of @var{m} repeats and a maximum of @var{n} repeats. If @var{m}
632 is omitted, the minimum is 0; if @var{n} is omitted, there is no
635 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
636 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
638 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.@*
639 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.@*
640 @samp{\@{1,\@}} is equivalent to @samp{+}.
643 @cindex @samp{(} in regexp
644 @cindex @samp{)} in regexp
645 @cindex regexp grouping
646 is a grouping construct that serves three purposes:
650 To enclose a set of @samp{\|} alternatives for other operations. Thus,
651 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
655 To enclose a complicated expression for the postfix operators @samp{*},
656 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
657 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
658 number (zero or more) of @samp{na} strings.
661 To record a matched substring for future reference with
662 @samp{\@var{digit}} (see below).
665 This last application is not a consequence of the idea of a
666 parenthetical grouping; it is a separate feature that was assigned as a
667 second meaning to the same @samp{\( @dots{} \)} construct because, in
668 practice, there was usually no conflict between the two meanings. But
669 occasionally there is a conflict, and that led to the introduction of
672 @item \(?: @dots{} \)
674 @cindex non-capturing group
675 @cindex unnumbered group
676 @cindex @samp{(?:} in regexp
677 is the @dfn{shy group} construct. A shy group serves the first two
678 purposes of an ordinary group (controlling the nesting of other
679 operators), but it does not get a number, so you cannot refer back to
680 its value with @samp{\@var{digit}}. Shy groups are particularly
681 useful for mechanically-constructed regular expressions, because they
682 can be added automatically without altering the numbering of ordinary,
685 Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered
688 @item \(?@var{num}: @dots{} \)
689 is the @dfn{explicitly numbered group} construct. Normal groups get
690 their number implicitly, based on their position, which can be
691 inconvenient. This construct allows you to force a particular group
692 number. There is no particular restriction on the numbering,
693 e.g., you can have several groups with the same number in which case
694 the last one to match (i.e., the rightmost match) will win.
695 Implicitly numbered groups always get the smallest integer larger than
696 the one of any previous group.
699 matches the same text that matched the @var{digit}th occurrence of a
700 grouping (@samp{\( @dots{} \)}) construct.
702 In other words, after the end of a group, the matcher remembers the
703 beginning and end of the text matched by that group. Later on in the
704 regular expression you can use @samp{\} followed by @var{digit} to
705 match that same text, whatever it may have been.
707 The strings matching the first nine grouping constructs appearing in
708 the entire regular expression passed to a search or matching function
709 are assigned numbers 1 through 9 in the order that the open
710 parentheses appear in the regular expression. So you can use
711 @samp{\1} through @samp{\9} to refer to the text matched by the
712 corresponding grouping constructs.
714 For example, @samp{\(.*\)\1} matches any newline-free string that is
715 composed of two identical halves. The @samp{\(.*\)} matches the first
716 half, which may be anything, but the @samp{\1} that follows must match
719 If a @samp{\( @dots{} \)} construct matches more than once (which can
720 happen, for instance, if it is followed by @samp{*}), only the last
723 If a particular grouping construct in the regular expression was never
724 matched---for instance, if it appears inside of an alternative that
725 wasn't used, or inside of a repetition that repeated zero times---then
726 the corresponding @samp{\@var{digit}} construct never matches
727 anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2}
728 cannot match @samp{lose}: the second alternative inside the larger
729 group matches it, but then @samp{\2} is undefined and can't match
730 anything. But it can match @samp{foobb}, because the first
731 alternative matches @samp{foob} and @samp{\2} matches @samp{b}.
734 @cindex @samp{\w} in regexp
735 matches any word-constituent character. The editor syntax table
736 determines which characters these are. @xref{Syntax Tables}.
739 @cindex @samp{\W} in regexp
740 matches any character that is not a word constituent.
743 @cindex @samp{\s} in regexp
744 matches any character whose syntax is @var{code}. Here @var{code} is a
745 character that represents a syntax code: thus, @samp{w} for word
746 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
747 etc. To represent whitespace syntax, use either @samp{-} or a space
748 character. @xref{Syntax Class Table}, for a list of syntax codes and
749 the characters that stand for them.
752 @cindex @samp{\S} in regexp
753 matches any character whose syntax is not @var{code}.
755 @cindex category, regexp search for
757 matches any character whose category is @var{c}. Here @var{c} is a
758 character that represents a category: thus, @samp{c} for Chinese
759 characters or @samp{g} for Greek characters in the standard category
760 table. You can see the list of all the currently defined categories
761 with @kbd{M-x describe-categories @key{RET}}. You can also define
762 your own categories in addition to the standard ones using the
763 @code{define-category} function (@pxref{Categories}).
766 matches any character whose category is not @var{c}.
769 The following regular expression constructs match the empty string---that is,
770 they don't use up any characters---but whether they match depends on the
771 context. For all, the beginning and end of the accessible portion of
772 the buffer are treated as if they were the actual beginning and end of
777 @cindex @samp{\`} in regexp
778 matches the empty string, but only at the beginning
779 of the buffer or string being matched against.
782 @cindex @samp{\'} in regexp
783 matches the empty string, but only at the end of
784 the buffer or string being matched against.
787 @cindex @samp{\=} in regexp
788 matches the empty string, but only at point.
789 (This construct is not defined when matching against a string.)
792 @cindex @samp{\b} in regexp
793 matches the empty string, but only at the beginning or
794 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
795 @samp{foo} as a separate word. @samp{\bballs?\b} matches
796 @samp{ball} or @samp{balls} as a separate word.
798 @samp{\b} matches at the beginning or end of the buffer (or string)
799 regardless of what text appears next to it.
802 @cindex @samp{\B} in regexp
803 matches the empty string, but @emph{not} at the beginning or
804 end of a word, nor at the beginning or end of the buffer (or string).
807 @cindex @samp{\<} in regexp
808 matches the empty string, but only at the beginning of a word.
809 @samp{\<} matches at the beginning of the buffer (or string) only if a
810 word-constituent character follows.
813 @cindex @samp{\>} in regexp
814 matches the empty string, but only at the end of a word. @samp{\>}
815 matches at the end of the buffer (or string) only if the contents end
816 with a word-constituent character.
819 @cindex @samp{\_<} in regexp
820 matches the empty string, but only at the beginning of a symbol. A
821 symbol is a sequence of one or more word or symbol constituent
822 characters. @samp{\_<} matches at the beginning of the buffer (or
823 string) only if a symbol-constituent character follows.
826 @cindex @samp{\_>} in regexp
827 matches the empty string, but only at the end of a symbol. @samp{\_>}
828 matches at the end of the buffer (or string) only if the contents end
829 with a symbol-constituent character.
832 @kindex invalid-regexp
833 Not every string is a valid regular expression. For example, a string
834 that ends inside a character alternative without a terminating @samp{]}
835 is invalid, and so is a string that ends with a single @samp{\}. If
836 an invalid regular expression is passed to any of the search functions,
837 an @code{invalid-regexp} error is signaled.
840 @subsection Complex Regexp Example
842 Here is a complicated regexp which was formerly used by Emacs to
843 recognize the end of a sentence together with any whitespace that
844 follows. (Nowadays Emacs uses a similar but more complex default
845 regexp constructed by the function @code{sentence-end}.
846 @xref{Standard Regexps}.)
848 Below, we show first the regexp as a string in Lisp syntax (to
849 distinguish spaces from tab characters), and then the result of
850 evaluating it. The string constant begins and ends with a
851 double-quote. @samp{\"} stands for a double-quote as part of the
852 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
853 tab and @samp{\n} for a newline.
857 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|@ @ \\)[ \t\n]*"
858 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\|@ @ \\)[
864 In the output, tab and newline appear as themselves.
866 This regular expression contains four parts in succession and can be
867 deciphered as follows:
871 The first part of the pattern is a character alternative that matches
872 any one of three characters: period, question mark, and exclamation
873 mark. The match must begin with one of these three characters. (This
874 is one point where the new default regexp used by Emacs differs from
875 the old. The new value also allows some non-@acronym{ASCII}
876 characters that end a sentence without any following whitespace.)
879 The second part of the pattern matches any closing braces and quotation
880 marks, zero or more of them, that may follow the period, question mark
881 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
882 a string. The @samp{*} at the end indicates that the immediately
883 preceding regular expression (a character alternative, in this case) may be
884 repeated zero or more times.
886 @item \\($\\|@ $\\|\t\\|@ @ \\)
887 The third part of the pattern matches the whitespace that follows the
888 end of a sentence: the end of a line (optionally with a space), or a
889 tab, or two spaces. The double backslashes mark the parentheses and
890 vertical bars as regular expression syntax; the parentheses delimit a
891 group and the vertical bars separate alternatives. The dollar sign is
892 used to match the end of a line.
895 Finally, the last part of the pattern matches any additional whitespace
896 beyond the minimum needed to end a sentence.
899 @node Regexp Functions
900 @subsection Regular Expression Functions
902 These functions operate on regular expressions.
904 @cindex quote special characters in regexp
905 @defun regexp-quote string
906 This function returns a regular expression whose only exact match is
907 @var{string}. Using this regular expression in @code{looking-at} will
908 succeed only if the next characters in the buffer are @var{string};
909 using it in a search function will succeed if the text being searched
910 contains @var{string}. @xref{Regexp Search}.
912 This allows you to request an exact string match or search when calling
913 a function that wants a regular expression.
917 (regexp-quote "^The cat$")
918 @result{} "\\^The cat\\$"
922 One use of @code{regexp-quote} is to combine an exact string match with
923 context described as a regular expression. For example, this searches
924 for the string that is the value of @var{string}, surrounded by
930 (concat "\\s-" (regexp-quote string) "\\s-"))
935 @cindex optimize regexp
936 @defun regexp-opt strings &optional paren
937 This function returns an efficient regular expression that will match
938 any of the strings in the list @var{strings}. This is useful when you
939 need to make matching or searching as fast as possible---for example,
940 for Font Lock mode@footnote{Note that @code{regexp-opt} does not
941 guarantee that its result is absolutely the most efficient form
942 possible. A hand-tuned regular expression can sometimes be slightly
943 more efficient, but is almost never worth the effort.}.
944 @c E.g., see http://debbugs.gnu.org/2816
946 If the optional argument @var{paren} is non-@code{nil}, then the
947 returned regular expression is always enclosed by at least one
948 parentheses-grouping construct. If @var{paren} is @code{words}, then
949 that construct is additionally surrounded by @samp{\<} and @samp{\>};
950 alternatively, if @var{paren} is @code{symbols}, then that construct
951 is additionally surrounded by @samp{\_<} and @samp{\_>}
952 (@code{symbols} is often appropriate when matching
953 programming-language keywords and the like).
955 This simplified definition of @code{regexp-opt} produces a
956 regular expression which is equivalent to the actual value
957 (but not as efficient):
960 (defun regexp-opt (strings &optional paren)
961 (let ((open-paren (if paren "\\(" ""))
962 (close-paren (if paren "\\)" "")))
964 (mapconcat 'regexp-quote strings "\\|")
969 @defun regexp-opt-depth regexp
970 This function returns the total number of grouping constructs
971 (parenthesized expressions) in @var{regexp}. This does not include
972 shy groups (@pxref{Regexp Backslash}).
975 @c Supposedly an internal regexp-opt function, but table.el uses it at least.
976 @defun regexp-opt-charset chars
977 This function returns a regular expression matching a character in the
978 list of characters @var{chars}.
981 (regexp-opt-charset '(?a ?b ?c ?d ?e))
986 @c Internal functions: regexp-opt-group
989 @section Regular Expression Searching
990 @cindex regular expression searching
991 @cindex regexp searching
992 @cindex searching for regexp
994 In GNU Emacs, you can search for the next match for a regular
995 expression (@pxref{Syntax of Regexps}) either incrementally or not.
996 For incremental search commands, see @ref{Regexp Search, , Regular
997 Expression Search, emacs, The GNU Emacs Manual}. Here we describe
998 only the search functions useful in programs. The principal one is
999 @code{re-search-forward}.
1001 These search functions convert the regular expression to multibyte if
1002 the buffer is multibyte; they convert the regular expression to unibyte
1003 if the buffer is unibyte. @xref{Text Representations}.
1005 @deffn Command re-search-forward regexp &optional limit noerror repeat
1006 This function searches forward in the current buffer for a string of
1007 text that is matched by the regular expression @var{regexp}. The
1008 function skips over any amount of text that is not matched by
1009 @var{regexp}, and leaves point at the end of the first match found.
1010 It returns the new value of point.
1012 If @var{limit} is non-@code{nil}, it must be a position in the current
1013 buffer. It specifies the upper bound to the search. No match
1014 extending after that position is accepted.
1016 If @var{repeat} is supplied, it must be a positive number; the search
1017 is repeated that many times; each repetition starts at the end of the
1018 previous match. If all these successive searches succeed, the search
1019 succeeds, moving point and returning its new value. Otherwise the
1020 search fails. What @code{re-search-forward} does when the search
1021 fails depends on the value of @var{noerror}:
1025 Signal a @code{search-failed} error.
1027 Do nothing and return @code{nil}.
1029 Move point to @var{limit} (or the end of the accessible portion of the
1030 buffer) and return @code{nil}.
1033 In the following example, point is initially before the @samp{T}.
1034 Evaluating the search call moves point to the end of that line (between
1035 the @samp{t} of @samp{hat} and the newline).
1039 ---------- Buffer: foo ----------
1040 I read "@point{}The cat in the hat
1042 ---------- Buffer: foo ----------
1046 (re-search-forward "[a-z]+" nil t 5)
1049 ---------- Buffer: foo ----------
1050 I read "The cat in the hat@point{}
1052 ---------- Buffer: foo ----------
1057 @deffn Command re-search-backward regexp &optional limit noerror repeat
1058 This function searches backward in the current buffer for a string of
1059 text that is matched by the regular expression @var{regexp}, leaving
1060 point at the beginning of the first text found.
1062 This function is analogous to @code{re-search-forward}, but they are not
1063 simple mirror images. @code{re-search-forward} finds the match whose
1064 beginning is as close as possible to the starting point. If
1065 @code{re-search-backward} were a perfect mirror image, it would find the
1066 match whose end is as close as possible. However, in fact it finds the
1067 match whose beginning is as close as possible (and yet ends before the
1068 starting point). The reason for this is that matching a regular
1069 expression at a given spot always works from beginning to end, and
1070 starts at a specified beginning position.
1072 A true mirror-image of @code{re-search-forward} would require a special
1073 feature for matching regular expressions from end to beginning. It's
1074 not worth the trouble of implementing that.
1077 @defun string-match regexp string &optional start
1078 This function returns the index of the start of the first match for
1079 the regular expression @var{regexp} in @var{string}, or @code{nil} if
1080 there is no match. If @var{start} is non-@code{nil}, the search starts
1081 at that index in @var{string}.
1088 "quick" "The quick brown fox jumped quickly.")
1093 "quick" "The quick brown fox jumped quickly." 8)
1099 The index of the first character of the
1100 string is 0, the index of the second character is 1, and so on.
1102 After this function returns, the index of the first character beyond
1103 the match is available as @code{(match-end 0)}. @xref{Match Data}.
1108 "quick" "The quick brown fox jumped quickly." 8)
1119 @defun string-match-p regexp string &optional start
1120 This predicate function does what @code{string-match} does, but it
1121 avoids modifying the match data.
1124 @defun looking-at regexp
1125 This function determines whether the text in the current buffer directly
1126 following point matches the regular expression @var{regexp}. ``Directly
1127 following'' means precisely that: the search is ``anchored'' and it can
1128 succeed only starting with the first character following point. The
1129 result is @code{t} if so, @code{nil} otherwise.
1131 This function does not move point, but it does update the match data.
1132 @xref{Match Data}. If you need to test for a match without modifying
1133 the match data, use @code{looking-at-p}, described below.
1135 In this example, point is located directly before the @samp{T}. If it
1136 were anywhere else, the result would be @code{nil}.
1140 ---------- Buffer: foo ----------
1141 I read "@point{}The cat in the hat
1143 ---------- Buffer: foo ----------
1145 (looking-at "The cat in the hat$")
1151 @defun looking-back regexp &optional limit greedy
1152 This function returns @code{t} if @var{regexp} matches the text
1153 immediately before point (i.e., ending at point), and @code{nil} otherwise.
1155 Because regular expression matching works only going forward, this is
1156 implemented by searching backwards from point for a match that ends at
1157 point. That can be quite slow if it has to search a long distance.
1158 You can bound the time required by specifying @var{limit}, which says
1159 not to search before @var{limit}. In this case, the match that is
1160 found must begin at or after @var{limit}. Here's an example:
1164 ---------- Buffer: foo ----------
1165 I read "@point{}The cat in the hat
1167 ---------- Buffer: foo ----------
1169 (looking-back "read \"" 3)
1171 (looking-back "read \"" 4)
1176 If @var{greedy} is non-@code{nil}, this function extends the match
1177 backwards as far as possible, stopping when a single additional
1178 previous character cannot be part of a match for regexp. When the
1179 match is extended, its starting position is allowed to occur before
1182 @c http://debbugs.gnu.org/5689
1183 As a general recommendation, try to avoid using @code{looking-back}
1184 wherever possible, since it is slow. For this reason, there are no
1185 plans to add a @code{looking-back-p} function.
1188 @defun looking-at-p regexp
1189 This predicate function works like @code{looking-at}, but without
1190 updating the match data.
1193 @defvar search-spaces-regexp
1194 If this variable is non-@code{nil}, it should be a regular expression
1195 that says how to search for whitespace. In that case, any group of
1196 spaces in a regular expression being searched for stands for use of
1197 this regular expression. However, spaces inside of constructs such as
1198 @samp{[@dots{}]} and @samp{*}, @samp{+}, @samp{?} are not affected by
1199 @code{search-spaces-regexp}.
1201 Since this variable affects all regular expression search and match
1202 constructs, you should bind it temporarily for as small as possible
1207 @section POSIX Regular Expression Searching
1209 @cindex backtracking and POSIX regular expressions
1210 The usual regular expression functions do backtracking when necessary
1211 to handle the @samp{\|} and repetition constructs, but they continue
1212 this only until they find @emph{some} match. Then they succeed and
1213 report the first match found.
1215 This section describes alternative search functions which perform the
1216 full backtracking specified by the POSIX standard for regular expression
1217 matching. They continue backtracking until they have tried all
1218 possibilities and found all matches, so they can report the longest
1219 match, as required by POSIX@. This is much slower, so use these
1220 functions only when you really need the longest match.
1222 The POSIX search and match functions do not properly support the
1223 non-greedy repetition operators (@pxref{Regexp Special, non-greedy}).
1224 This is because POSIX backtracking conflicts with the semantics of
1225 non-greedy repetition.
1227 @deffn Command posix-search-forward regexp &optional limit noerror repeat
1228 This is like @code{re-search-forward} except that it performs the full
1229 backtracking specified by the POSIX standard for regular expression
1233 @deffn Command posix-search-backward regexp &optional limit noerror repeat
1234 This is like @code{re-search-backward} except that it performs the full
1235 backtracking specified by the POSIX standard for regular expression
1239 @defun posix-looking-at regexp
1240 This is like @code{looking-at} except that it performs the full
1241 backtracking specified by the POSIX standard for regular expression
1245 @defun posix-string-match regexp string &optional start
1246 This is like @code{string-match} except that it performs the full
1247 backtracking specified by the POSIX standard for regular expression
1252 @section The Match Data
1255 Emacs keeps track of the start and end positions of the segments of
1256 text found during a search; this is called the @dfn{match data}.
1257 Thanks to the match data, you can search for a complex pattern, such
1258 as a date in a mail message, and then extract parts of the match under
1259 control of the pattern.
1261 Because the match data normally describe the most recent search only,
1262 you must be careful not to do another search inadvertently between the
1263 search you wish to refer back to and the use of the match data. If you
1264 can't avoid another intervening search, you must save and restore the
1265 match data around it, to prevent it from being overwritten.
1267 Notice that all functions are allowed to overwrite the match data
1268 unless they're explicitly documented not to do so. A consequence is
1269 that functions that are run implicitly in the background
1270 (@pxref{Timers}, and @ref{Idle Timers}) should likely save and restore
1271 the match data explicitly.
1274 * Replacing Match:: Replacing a substring that was matched.
1275 * Simple Match Data:: Accessing single items of match data,
1276 such as where a particular subexpression started.
1277 * Entire Match Data:: Accessing the entire match data at once, as a list.
1278 * Saving Match Data:: Saving and restoring the match data.
1281 @node Replacing Match
1282 @subsection Replacing the Text that Matched
1283 @cindex replace matched text
1285 This function replaces all or part of the text matched by the last
1286 search. It works by means of the match data.
1288 @cindex case in replacements
1289 @defun replace-match replacement &optional fixedcase literal string subexp
1290 This function performs a replacement operation on a buffer or string.
1292 If you did the last search in a buffer, you should omit the
1293 @var{string} argument or specify @code{nil} for it, and make sure that
1294 the current buffer is the one in which you performed the last search.
1295 Then this function edits the buffer, replacing the matched text with
1296 @var{replacement}. It leaves point at the end of the replacement
1299 If you performed the last search on a string, pass the same string as
1300 @var{string}. Then this function returns a new string, in which the
1301 matched text is replaced by @var{replacement}.
1303 If @var{fixedcase} is non-@code{nil}, then @code{replace-match} uses
1304 the replacement text without case conversion; otherwise, it converts
1305 the replacement text depending upon the capitalization of the text to
1306 be replaced. If the original text is all upper case, this converts
1307 the replacement text to upper case. If all words of the original text
1308 are capitalized, this capitalizes all the words of the replacement
1309 text. If all the words are one-letter and they are all upper case,
1310 they are treated as capitalized words rather than all-upper-case
1313 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1314 exactly as it is, the only alterations being case changes as needed.
1315 If it is @code{nil} (the default), then the character @samp{\} is treated
1316 specially. If a @samp{\} appears in @var{replacement}, then it must be
1317 part of one of the following sequences:
1321 @cindex @samp{&} in replacement
1322 This stands for the entire text being replaced.
1324 @item @samp{\@var{n}}, where @var{n} is a digit
1325 @cindex @samp{\@var{n}} in replacement
1326 This stands for the text that matched the @var{n}th subexpression in
1327 the original regexp. Subexpressions are those expressions grouped
1328 inside @samp{\(@dots{}\)}. If the @var{n}th subexpression never
1329 matched, an empty string is substituted.
1332 @cindex @samp{\} in replacement
1333 This stands for a single @samp{\} in the replacement text.
1336 This stands for itself (for compatibility with @code{replace-regexp}
1337 and related commands; @pxref{Regexp Replace,,, emacs, The GNU
1342 Any other character following @samp{\} signals an error.
1344 The substitutions performed by @samp{\&} and @samp{\@var{n}} occur
1345 after case conversion, if any. Therefore, the strings they substitute
1346 are never case-converted.
1348 If @var{subexp} is non-@code{nil}, that says to replace just
1349 subexpression number @var{subexp} of the regexp that was matched, not
1350 the entire match. For example, after matching @samp{foo \(ba*r\)},
1351 calling @code{replace-match} with 1 as @var{subexp} means to replace
1352 just the text that matched @samp{\(ba*r\)}.
1355 @defun match-substitute-replacement replacement &optional fixedcase literal string subexp
1356 This function returns the text that would be inserted into the buffer
1357 by @code{replace-match}, but without modifying the buffer. It is
1358 useful if you want to present the user with actual replacement result,
1359 with constructs like @samp{\@var{n}} or @samp{\&} substituted with
1360 matched groups. Arguments @var{replacement} and optional
1361 @var{fixedcase}, @var{literal}, @var{string} and @var{subexp} have the
1362 same meaning as for @code{replace-match}.
1365 @node Simple Match Data
1366 @subsection Simple Match Data Access
1368 This section explains how to use the match data to find out what was
1369 matched by the last search or match operation, if it succeeded.
1371 You can ask about the entire matching text, or about a particular
1372 parenthetical subexpression of a regular expression. The @var{count}
1373 argument in the functions below specifies which. If @var{count} is
1374 zero, you are asking about the entire match. If @var{count} is
1375 positive, it specifies which subexpression you want.
1377 Recall that the subexpressions of a regular expression are those
1378 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1379 @var{count}th subexpression is found by counting occurrences of
1380 @samp{\(} from the beginning of the whole regular expression. The first
1381 subexpression is numbered 1, the second 2, and so on. Only regular
1382 expressions can have subexpressions---after a simple string search, the
1383 only information available is about the entire match.
1385 Every successful search sets the match data. Therefore, you should
1386 query the match data immediately after searching, before calling any
1387 other function that might perform another search. Alternatively, you
1388 may save and restore the match data (@pxref{Saving Match Data}) around
1389 the call to functions that could perform another search. Or use the
1390 functions that explicitly do not modify the match data;
1391 e.g., @code{string-match-p}.
1393 @c This is an old comment and presumably there is no prospect of this
1394 @c changing now. But still the advice stands.
1395 A search which fails may or may not alter the match data. In the
1396 current implementation, it does not, but we may change it in the
1397 future. Don't try to rely on the value of the match data after a
1400 @defun match-string count &optional in-string
1401 This function returns, as a string, the text matched in the last search
1402 or match operation. It returns the entire text if @var{count} is zero,
1403 or just the portion corresponding to the @var{count}th parenthetical
1404 subexpression, if @var{count} is positive.
1406 If the last such operation was done against a string with
1407 @code{string-match}, then you should pass the same string as the
1408 argument @var{in-string}. After a buffer search or match,
1409 you should omit @var{in-string} or pass @code{nil} for it; but you
1410 should make sure that the current buffer when you call
1411 @code{match-string} is the one in which you did the searching or
1412 matching. Failure to follow this advice will lead to incorrect results.
1414 The value is @code{nil} if @var{count} is out of range, or for a
1415 subexpression inside a @samp{\|} alternative that wasn't used or a
1416 repetition that repeated zero times.
1419 @defun match-string-no-properties count &optional in-string
1420 This function is like @code{match-string} except that the result
1421 has no text properties.
1424 @defun match-beginning count
1425 This function returns the position of the start of the text matched by the
1426 last regular expression searched for, or a subexpression of it.
1428 If @var{count} is zero, then the value is the position of the start of
1429 the entire match. Otherwise, @var{count} specifies a subexpression in
1430 the regular expression, and the value of the function is the starting
1431 position of the match for that subexpression.
1433 The value is @code{nil} for a subexpression inside a @samp{\|}
1434 alternative that wasn't used or a repetition that repeated zero times.
1437 @defun match-end count
1438 This function is like @code{match-beginning} except that it returns the
1439 position of the end of the match, rather than the position of the
1443 Here is an example of using the match data, with a comment showing the
1444 positions within the text:
1448 (string-match "\\(qu\\)\\(ick\\)"
1449 "The quick fox jumped quickly.")
1455 (match-string 0 "The quick fox jumped quickly.")
1457 (match-string 1 "The quick fox jumped quickly.")
1459 (match-string 2 "The quick fox jumped quickly.")
1464 (match-beginning 1) ; @r{The beginning of the match}
1465 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1469 (match-beginning 2) ; @r{The beginning of the match}
1470 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1474 (match-end 1) ; @r{The end of the match}
1475 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1477 (match-end 2) ; @r{The end of the match}
1478 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1482 Here is another example. Point is initially located at the beginning
1483 of the line. Searching moves point to between the space and the word
1484 @samp{in}. The beginning of the entire match is at the 9th character of
1485 the buffer (@samp{T}), and the beginning of the match for the first
1486 subexpression is at the 13th character (@samp{c}).
1491 (re-search-forward "The \\(cat \\)")
1493 (match-beginning 1))
1498 ---------- Buffer: foo ----------
1499 I read "The cat @point{}in the hat comes back" twice.
1502 ---------- Buffer: foo ----------
1507 (In this case, the index returned is a buffer position; the first
1508 character of the buffer counts as 1.)
1510 @node Entire Match Data
1511 @subsection Accessing the Entire Match Data
1513 The functions @code{match-data} and @code{set-match-data} read or
1514 write the entire match data, all at once.
1516 @defun match-data &optional integers reuse reseat
1517 This function returns a list of positions (markers or integers) that
1518 record all the information on the text that the last search matched.
1519 Element zero is the position of the beginning of the match for the
1520 whole expression; element one is the position of the end of the match
1521 for the expression. The next two elements are the positions of the
1522 beginning and end of the match for the first subexpression, and so on.
1528 number {\mathsurround=0pt $2n$}
1530 corresponds to @code{(match-beginning @var{n})}; and
1536 number {\mathsurround=0pt $2n+1$}
1538 corresponds to @code{(match-end @var{n})}.
1540 Normally all the elements are markers or @code{nil}, but if
1541 @var{integers} is non-@code{nil}, that means to use integers instead
1542 of markers. (In that case, the buffer itself is appended as an
1543 additional element at the end of the list, to facilitate complete
1544 restoration of the match data.) If the last match was done on a
1545 string with @code{string-match}, then integers are always used,
1546 since markers can't point into a string.
1548 If @var{reuse} is non-@code{nil}, it should be a list. In that case,
1549 @code{match-data} stores the match data in @var{reuse}. That is,
1550 @var{reuse} is destructively modified. @var{reuse} does not need to
1551 have the right length. If it is not long enough to contain the match
1552 data, it is extended. If it is too long, the length of @var{reuse}
1553 stays the same, but the elements that were not used are set to
1554 @code{nil}. The purpose of this feature is to reduce the need for
1557 If @var{reseat} is non-@code{nil}, all markers on the @var{reuse} list
1558 are reseated to point to nowhere.
1560 As always, there must be no possibility of intervening searches between
1561 the call to a search function and the call to @code{match-data} that is
1562 intended to access the match data for that search.
1567 @result{} (#<marker at 9 in foo>
1568 #<marker at 17 in foo>
1569 #<marker at 13 in foo>
1570 #<marker at 17 in foo>)
1575 @defun set-match-data match-list &optional reseat
1576 This function sets the match data from the elements of @var{match-list},
1577 which should be a list that was the value of a previous call to
1578 @code{match-data}. (More precisely, anything that has the same format
1581 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1582 an error; that sets the match data in a meaningless but harmless way.
1584 If @var{reseat} is non-@code{nil}, all markers on the @var{match-list} list
1585 are reseated to point to nowhere.
1587 @c TODO Make it properly obsolete.
1588 @findex store-match-data
1589 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1592 @node Saving Match Data
1593 @subsection Saving and Restoring the Match Data
1595 When you call a function that may search, you may need to save
1596 and restore the match data around that call, if you want to preserve the
1597 match data from an earlier search for later use. Here is an example
1598 that shows the problem that arises if you fail to save the match data:
1602 (re-search-forward "The \\(cat \\)")
1604 (foo) ; @r{@code{foo} does more searching.}
1606 @result{} 61 ; @r{Unexpected result---not 48!}
1610 You can save and restore the match data with @code{save-match-data}:
1612 @defmac save-match-data body@dots{}
1613 This macro executes @var{body}, saving and restoring the match
1614 data around it. The return value is the value of the last form in
1618 You could use @code{set-match-data} together with @code{match-data} to
1619 imitate the effect of the special form @code{save-match-data}. Here is
1624 (let ((data (match-data)))
1626 @dots{} ; @r{Ok to change the original match data.}
1627 (set-match-data data)))
1631 Emacs automatically saves and restores the match data when it runs
1632 process filter functions (@pxref{Filter Functions}) and process
1633 sentinels (@pxref{Sentinels}).
1636 Here is a function which restores the match data provided the buffer
1637 associated with it still exists.
1641 (defun restore-match-data (data)
1642 @c It is incorrect to split the first line of a doc string.
1643 @c If there's a problem here, it should be solved in some other way.
1644 "Restore the match data DATA unless the buffer is missing."
1650 (null (marker-buffer (car d)))
1652 ;; @file{match-data} @r{buffer is deleted.}
1655 (set-match-data data))))
1660 @node Search and Replace
1661 @section Search and Replace
1662 @cindex replacement after search
1663 @cindex searching and replacing
1665 If you want to find all matches for a regexp in part of the buffer,
1666 and replace them, the best way is to write an explicit loop using
1667 @code{re-search-forward} and @code{replace-match}, like this:
1670 (while (re-search-forward "foo[ \t]+bar" nil t)
1671 (replace-match "foobar"))
1675 @xref{Replacing Match,, Replacing the Text that Matched}, for a
1676 description of @code{replace-match}.
1678 However, replacing matches in a string is more complex, especially
1679 if you want to do it efficiently. So Emacs provides a function to do
1682 @defun replace-regexp-in-string regexp rep string &optional fixedcase literal subexp start
1683 This function copies @var{string} and searches it for matches for
1684 @var{regexp}, and replaces them with @var{rep}. It returns the
1685 modified copy. If @var{start} is non-@code{nil}, the search for
1686 matches starts at that index in @var{string}, so matches starting
1687 before that index are not changed.
1689 This function uses @code{replace-match} to do the replacement, and it
1690 passes the optional arguments @var{fixedcase}, @var{literal} and
1691 @var{subexp} along to @code{replace-match}.
1693 Instead of a string, @var{rep} can be a function. In that case,
1694 @code{replace-regexp-in-string} calls @var{rep} for each match,
1695 passing the text of the match as its sole argument. It collects the
1696 value @var{rep} returns and passes that to @code{replace-match} as the
1697 replacement string. The match data at this point are the result
1698 of matching @var{regexp} against a substring of @var{string}.
1701 If you want to write a command along the lines of @code{query-replace},
1702 you can use @code{perform-replace} to do the work.
1704 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map start end
1705 This function is the guts of @code{query-replace} and related
1706 commands. It searches for occurrences of @var{from-string} in the
1707 text between positions @var{start} and @var{end} and replaces some or
1708 all of them. If @var{start} is @code{nil} (or omitted), point is used
1709 instead, and the end of the buffer's accessible portion is used for
1712 If @var{query-flag} is @code{nil}, it replaces all
1713 occurrences; otherwise, it asks the user what to do about each one.
1715 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
1716 considered a regular expression; otherwise, it must match literally. If
1717 @var{delimited-flag} is non-@code{nil}, then only replacements
1718 surrounded by word boundaries are considered.
1720 The argument @var{replacements} specifies what to replace occurrences
1721 with. If it is a string, that string is used. It can also be a list of
1722 strings, to be used in cyclic order.
1724 If @var{replacements} is a cons cell, @w{@code{(@var{function}
1725 . @var{data})}}, this means to call @var{function} after each match to
1726 get the replacement text. This function is called with two arguments:
1727 @var{data}, and the number of replacements already made.
1729 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
1730 it specifies how many times to use each of the strings in the
1731 @var{replacements} list before advancing cyclically to the next one.
1733 If @var{from-string} contains upper-case letters, then
1734 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
1735 it uses the @var{replacements} without altering their case.
1737 Normally, the keymap @code{query-replace-map} defines the possible
1738 user responses for queries. The argument @var{map}, if
1739 non-@code{nil}, specifies a keymap to use instead of
1740 @code{query-replace-map}.
1742 This function uses one of two functions to search for the next
1743 occurrence of @var{from-string}. These functions are specified by the
1744 values of two variables: @code{replace-re-search-function} and
1745 @code{replace-search-function}. The former is called when the
1746 argument @var{regexp-flag} is non-@code{nil}, the latter when it is
1750 @defvar query-replace-map
1751 This variable holds a special keymap that defines the valid user
1752 responses for @code{perform-replace} and the commands that use it, as
1753 well as @code{y-or-n-p} and @code{map-y-or-n-p}. This map is unusual
1758 The ``key bindings'' are not commands, just symbols that are meaningful
1759 to the functions that use this map.
1762 Prefix keys are not supported; each key binding must be for a
1763 single-event key sequence. This is because the functions don't use
1764 @code{read-key-sequence} to get the input; instead, they read a single
1765 event and look it up ``by hand''.
1769 Here are the meaningful ``bindings'' for @code{query-replace-map}.
1770 Several of them are meaningful only for @code{query-replace} and
1775 Do take the action being considered---in other words, ``yes''.
1778 Do not take action for this question---in other words, ``no''.
1781 Answer this question ``no'', and give up on the entire series of
1782 questions, assuming that the answers will be ``no''.
1785 Like @code{exit}, but add the key that was pressed to
1786 @code{unread-command-events} (@pxref{Event Input Misc}).
1789 Answer this question ``yes'', and give up on the entire series of
1790 questions, assuming that subsequent answers will be ``no''.
1793 Answer this question ``yes'', but show the results---don't advance yet
1794 to the next question.
1797 Answer this question and all subsequent questions in the series with
1798 ``yes'', without further user interaction.
1801 Move back to the previous place that a question was asked about.
1804 Enter a recursive edit to deal with this question---instead of any
1805 other action that would normally be taken.
1807 @item edit-replacement
1808 Edit the replacement for this question in the minibuffer.
1810 @item delete-and-edit
1811 Delete the text being considered, then enter a recursive edit to replace
1817 @itemx scroll-other-window
1818 @itemx scroll-other-window-down
1819 Perform the specified window scroll operation, then ask the same
1820 question again. Only @code{y-or-n-p} and related functions use this
1824 Perform a quit right away. Only @code{y-or-n-p} and related functions
1828 Display some help, then ask again.
1831 @defvar multi-query-replace-map
1832 This variable holds a keymap that extends @code{query-replace-map} by
1833 providing additional keybindings that are useful in multi-buffer
1834 replacements. The additional ``bindings'' are:
1838 Answer this question and all subsequent questions in the series with
1839 ``yes'', without further user interaction, for all remaining buffers.
1842 Answer this question ``no'', and give up on the entire series of
1843 questions for the current buffer. Continue to the next buffer in the
1848 @defvar replace-search-function
1849 This variable specifies a function that @code{perform-replace} calls
1850 to search for the next string to replace. Its default value is
1851 @code{search-forward}. Any other value should name a function of 3
1852 arguments: the first 3 arguments of @code{search-forward}
1853 (@pxref{String Search}).
1856 @defvar replace-re-search-function
1857 This variable specifies a function that @code{perform-replace} calls
1858 to search for the next regexp to replace. Its default value is
1859 @code{re-search-forward}. Any other value should name a function of 3
1860 arguments: the first 3 arguments of @code{re-search-forward}
1861 (@pxref{Regexp Search}).
1864 @node Standard Regexps
1865 @section Standard Regular Expressions Used in Editing
1866 @cindex regexps used standardly in editing
1867 @cindex standard regexps used in editing
1869 This section describes some variables that hold regular expressions
1870 used for certain purposes in editing:
1872 @defopt page-delimiter
1873 This is the regular expression describing line-beginnings that separate
1874 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1875 @code{"^\C-l"}); this matches a line that starts with a formfeed
1879 The following two regular expressions should @emph{not} assume the
1880 match always starts at the beginning of a line; they should not use
1881 @samp{^} to anchor the match. Most often, the paragraph commands do
1882 check for a match only at the beginning of a line, which means that
1883 @samp{^} would be superfluous. When there is a nonzero left margin,
1884 they accept matches that start after the left margin. In that case, a
1885 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1886 where a left margin is never used.
1888 @defopt paragraph-separate
1889 This is the regular expression for recognizing the beginning of a line
1890 that separates paragraphs. (If you change this, you may have to
1891 change @code{paragraph-start} also.) The default value is
1892 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1893 spaces, tabs, and form feeds (after its left margin).
1896 @defopt paragraph-start
1897 This is the regular expression for recognizing the beginning of a line
1898 that starts @emph{or} separates paragraphs. The default value is
1899 @w{@code{"\f\\|[ \t]*$"}}, which matches a line containing only
1900 whitespace or starting with a form feed (after its left margin).
1903 @defopt sentence-end
1904 If non-@code{nil}, the value should be a regular expression describing
1905 the end of a sentence, including the whitespace following the
1906 sentence. (All paragraph boundaries also end sentences, regardless.)
1908 If the value is @code{nil}, as it is by default, then the function
1909 @code{sentence-end} constructs the regexp. That is why you
1910 should always call the function @code{sentence-end} to obtain the
1911 regexp to be used to recognize the end of a sentence.
1915 This function returns the value of the variable @code{sentence-end},
1916 if non-@code{nil}. Otherwise it returns a default value based on the
1917 values of the variables @code{sentence-end-double-space}
1918 (@pxref{Definition of sentence-end-double-space}),
1919 @code{sentence-end-without-period}, and
1920 @code{sentence-end-without-space}.