2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
4 @c See the file elisp.texi for copying conditions.
5 @setfilename ../info/searching
6 @node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
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 * Regular Expressions:: Describing classes of strings.
19 * Regexp Search:: Searching for a match for a regexp.
20 * POSIX Regexps:: Searching POSIX-style for the longest match.
21 * Search and Replace:: Internals of @code{query-replace}.
22 * Match Data:: Finding out which part of the text matched
23 various parts of a regexp, after regexp search.
24 * Searching and Case:: Case-independent or case-significant searching.
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}.
32 @section Searching for Strings
35 These are the primitive functions for searching through the text in a
36 buffer. They are meant for use in programs, but you may call them
37 interactively. If you do so, they prompt for the search string;
38 @var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat}
41 These search functions convert the search string to multibyte if the
42 buffer is multibyte; they convert the search string to unibyte if the
43 buffer is unibyte. @xref{Text Representations}.
45 @deffn Command search-forward string &optional limit noerror repeat
46 This function searches forward from point for an exact match for
47 @var{string}. If successful, it sets point to the end of the occurrence
48 found, and returns the new value of point. If no match is found, the
49 value and side effects depend on @var{noerror} (see below).
52 In the following example, point is initially at the beginning of the
53 line. Then @code{(search-forward "fox")} moves point after the last
58 ---------- Buffer: foo ----------
59 @point{}The quick brown fox jumped over the lazy dog.
60 ---------- Buffer: foo ----------
64 (search-forward "fox")
67 ---------- Buffer: foo ----------
68 The quick brown fox@point{} jumped over the lazy dog.
69 ---------- Buffer: foo ----------
73 The argument @var{limit} specifies the upper bound to the search. (It
74 must be a position in the current buffer.) No match extending after
75 that position is accepted. If @var{limit} is omitted or @code{nil}, it
76 defaults to the end of the accessible portion of the buffer.
79 What happens when the search fails depends on the value of
80 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
81 error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
82 returns @code{nil} and does nothing. If @var{noerror} is neither
83 @code{nil} nor @code{t}, then @code{search-forward} moves point to the
84 upper bound and returns @code{nil}. (It would be more consistent now to
85 return the new position of point in that case, but some existing
86 programs may depend on a value of @code{nil}.)
88 If @var{repeat} is supplied (it must be a positive number), then the
89 search is repeated that many times (each time starting at the end of the
90 previous time's match). If these successive searches succeed, the
91 function succeeds, moving point and returning its new value. Otherwise
95 @deffn Command search-backward string &optional limit noerror repeat
96 This function searches backward from point for @var{string}. It is
97 just like @code{search-forward} except that it searches backwards and
98 leaves point at the beginning of the match.
101 @deffn Command word-search-forward string &optional limit noerror repeat
103 This function searches forward from point for a ``word'' match for
104 @var{string}. If it finds a match, it sets point to the end of the
105 match found, and returns the new value of point.
108 Word matching regards @var{string} as a sequence of words, disregarding
109 punctuation that separates them. It searches the buffer for the same
110 sequence of words. Each word must be distinct in the buffer (searching
111 for the word @samp{ball} does not match the word @samp{balls}), but the
112 details of punctuation and spacing are ignored (searching for @samp{ball
113 boy} does match @samp{ball. Boy!}).
115 In this example, point is initially at the beginning of the buffer; the
116 search leaves it between the @samp{y} and the @samp{!}.
120 ---------- Buffer: foo ----------
121 @point{}He said "Please! Find
123 ---------- Buffer: foo ----------
127 (word-search-forward "Please find the ball, boy.")
130 ---------- Buffer: foo ----------
131 He said "Please! Find
132 the ball boy@point{}!"
133 ---------- Buffer: foo ----------
137 If @var{limit} is non-@code{nil} (it must be a position in the current
138 buffer), then it is the upper bound to the search. The match found must
139 not extend after that position.
141 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
142 an error if the search fails. If @var{noerror} is @code{t}, then it
143 returns @code{nil} instead of signaling an error. If @var{noerror} is
144 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
145 end of the buffer) and returns @code{nil}.
147 If @var{repeat} is non-@code{nil}, then the search is repeated that many
148 times. Point is positioned at the end of the last match.
151 @deffn Command word-search-backward string &optional limit noerror repeat
152 This function searches backward from point for a word match to
153 @var{string}. This function is just like @code{word-search-forward}
154 except that it searches backward and normally leaves point at the
155 beginning of the match.
158 @node Regular Expressions
159 @section Regular Expressions
160 @cindex regular expression
163 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
164 denotes a (possibly infinite) set of strings. Searching for matches for
165 a regexp is a very powerful operation. This section explains how to write
166 regexps; the following section says how to search for them.
169 * Syntax of Regexps:: Rules for writing regular expressions.
170 * Regexp Example:: Illustrates regular expression syntax.
173 @node Syntax of Regexps
174 @subsection Syntax of Regular Expressions
176 Regular expressions have a syntax in which a few characters are
177 special constructs and the rest are @dfn{ordinary}. An ordinary
178 character is a simple regular expression that matches that character and
179 nothing else. The special characters are @samp{.}, @samp{*}, @samp{+},
180 @samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
181 special characters will be defined in the future. Any other character
182 appearing in a regular expression is ordinary, unless a @samp{\}
185 For example, @samp{f} is not a special character, so it is ordinary, and
186 therefore @samp{f} is a regular expression that matches the string
187 @samp{f} and no other string. (It does @emph{not} match the string
188 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches
189 only @samp{o}.@refill
191 Any two regular expressions @var{a} and @var{b} can be concatenated. The
192 result is a regular expression that matches a string if @var{a} matches
193 some amount of the beginning of that string and @var{b} matches the rest of
196 As a simple example, we can concatenate the regular expressions @samp{f}
197 and @samp{o} to get the regular expression @samp{fo}, which matches only
198 the string @samp{fo}. Still trivial. To do something more powerful, you
199 need to use one of the special characters. Here is a list of them:
203 @item @samp{.}@: @r{(Period)}
204 @cindex @samp{.} in regexp
205 is a special character that matches any single character except a newline.
206 Using concatenation, we can make regular expressions like @samp{a.b}, which
207 matches any three-character string that begins with @samp{a} and ends with
211 @cindex @samp{*} in regexp
212 is not a construct by itself; it is a postfix operator that means to
213 match the preceding regular expression repetitively as many times as
214 possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
217 @samp{*} always applies to the @emph{smallest} possible preceding
218 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
219 @samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
221 The matcher processes a @samp{*} construct by matching, immediately, as
222 many repetitions as can be found. Then it continues with the rest of
223 the pattern. If that fails, backtracking occurs, discarding some of the
224 matches of the @samp{*}-modified construct in the hope that that will
225 make it possible to match the rest of the pattern. For example, in
226 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
227 first tries to match all three @samp{a}s; but the rest of the pattern is
228 @samp{ar} and there is only @samp{r} left to match, so this try fails.
229 The next alternative is for @samp{a*} to match only two @samp{a}s. With
230 this choice, the rest of the regexp matches successfully.@refill
232 Nested repetition operators can be extremely slow if they specify
233 backtracking loops. For example, it could take hours for the regular
234 expression @samp{\(x+y*\)*a} to try to match the sequence
235 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately fails.
236 The slowness is because Emacs must try each imaginable way of grouping
237 the 35 @samp{x}s before concluding that none of them can work. To make
238 sure your regular expressions run fast, check nested repetitions
242 @cindex @samp{+} in regexp
243 is a postfix operator, similar to @samp{*} except that it must match
244 the preceding expression at least once. So, for example, @samp{ca+r}
245 matches the strings @samp{car} and @samp{caaaar} but not the string
246 @samp{cr}, whereas @samp{ca*r} matches all three strings.
249 @cindex @samp{?} in regexp
250 is a postfix operator, similar to @samp{*} except that it must match the
251 preceding expression either once or not at all. For example,
252 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
254 @item @samp{[ @dots{} ]}
255 @cindex character alternative (in regexp)
256 @cindex @samp{[} in regexp
257 @cindex @samp{]} in regexp
258 is a @dfn{character alternative}, which begins with @samp{[} and is
259 terminated by @samp{]}. In the simplest case, the characters between
260 the two brackets are what this character alternative can match.
262 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
263 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
264 (including the empty string), from which it follows that @samp{c[ad]*r}
265 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
267 You can also include character ranges in a character alternative, by
268 writing the starting and ending characters with a @samp{-} between them.
269 Thus, @samp{[a-z]} matches any lower-case @sc{ASCII} letter. Ranges may be
270 intermixed freely with individual characters, as in @samp{[a-z$%.]},
271 which matches any lower case @sc{ASCII} letter or @samp{$}, @samp{%} or
274 You cannot always match all non-@sc{ASCII} characters with the regular
275 expression @samp{[\200-\377]}. This works when searching a unibyte
276 buffer or string (@pxref{Text Representations}), but not in a multibyte
277 buffer or string, because many non-@sc{ASCII} characters have codes
278 above octal 0377. However, the regular expression @samp{[^\000-\177]}
279 does match all non-@sc{ASCII} characters, in both multibyte and unibyte
280 representations, because only the @sc{ASCII} characters are excluded.
282 The beginning and end of a range must be in the same character set
283 (@pxref{Character Sets}). Thus, @samp{[a-\x8e0]} is invalid because
284 @samp{a} is in the @sc{ASCII} character set but the character 0x8e0
285 (@samp{a} with grave accent) is in the Emacs character set for Latin-1.
287 Note that the usual regexp special characters are not special inside a
288 character alternative. A completely different set of characters are
289 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
291 To include a @samp{]} in a character alternative, you must make it the
292 first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
293 To include a @samp{-}, write @samp{-} as the first or last character of
294 the character alternative, or put it after a range. Thus, @samp{[]-]}
295 matches both @samp{]} and @samp{-}.
297 To include @samp{^} in a character alternative, put it anywhere but at
300 @item @samp{[^ @dots{} ]}
301 @cindex @samp{^} in regexp
302 @samp{[^} begins a @dfn{complemented character alternative}, which matches any
303 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
304 all characters @emph{except} letters and digits.
306 @samp{^} is not special in a character alternative unless it is the first
307 character. The character following the @samp{^} is treated as if it
308 were first (in other words, @samp{-} and @samp{]} are not special there).
310 A complemented character alternative can match a newline, unless newline is
311 mentioned as one of the characters not to match. This is in contrast to
312 the handling of regexps in programs such as @code{grep}.
315 @cindex beginning of line in regexp
316 is a special character that matches the empty string, but only at the
317 beginning of a line in the text being matched. Otherwise it fails to
318 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
319 the beginning of a line.
321 When matching a string instead of a buffer, @samp{^} matches at the
322 beginning of the string or after a newline character @samp{\n}.
325 @cindex @samp{$} in regexp
326 is similar to @samp{^} but matches only at the end of a line. Thus,
327 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
329 When matching a string instead of a buffer, @samp{$} matches at the end
330 of the string or before a newline character @samp{\n}.
333 @cindex @samp{\} in regexp
334 has two functions: it quotes the special characters (including
335 @samp{\}), and it introduces additional special constructs.
337 Because @samp{\} quotes special characters, @samp{\$} is a regular
338 expression that matches only @samp{$}, and @samp{\[} is a regular
339 expression that matches only @samp{[}, and so on.
341 Note that @samp{\} also has special meaning in the read syntax of Lisp
342 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
343 example, the regular expression that matches the @samp{\} character is
344 @samp{\\}. To write a Lisp string that contains the characters
345 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
346 @samp{\}. Therefore, the read syntax for a regular expression matching
347 @samp{\} is @code{"\\\\"}.@refill
350 @strong{Please note:} For historical compatibility, special characters
351 are treated as ordinary ones if they are in contexts where their special
352 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
353 ordinary since there is no preceding expression on which the @samp{*}
354 can act. It is poor practice to depend on this behavior; quote the
355 special character anyway, regardless of where it appears.@refill
357 For the most part, @samp{\} followed by any character matches only that
358 character. However, there are several exceptions: two-character
359 sequences starting with @samp{\} which have special meanings. (The
360 second character in such a sequence is always ordinary when used on its
361 own.) Here is a table of @samp{\} constructs.
365 @cindex @samp{|} in regexp
366 @cindex regexp alternative
367 specifies an alternative.
368 Two regular expressions @var{a} and @var{b} with @samp{\|} in
369 between form an expression that matches anything that either @var{a} or
370 @var{b} matches.@refill
372 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
373 but no other string.@refill
375 @samp{\|} applies to the largest possible surrounding expressions. Only a
376 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
379 Full backtracking capability exists to handle multiple uses of @samp{\|}.
382 @cindex @samp{(} in regexp
383 @cindex @samp{)} in regexp
384 @cindex regexp grouping
385 is a grouping construct that serves three purposes:
389 To enclose a set of @samp{\|} alternatives for other operations. Thus,
390 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
394 To enclose a complicated expression for the postfix operators @samp{*},
395 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
396 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
397 number (zero or more) of @samp{na} strings.
400 To record a matched substring for future reference.
403 This last application is not a consequence of the idea of a
404 parenthetical grouping; it is a separate feature that happens to be
405 assigned as a second meaning to the same @samp{\( @dots{} \)} construct
406 because there is no conflict in practice between the two meanings.
407 Here is an explanation of this feature:
410 matches the same text that matched the @var{digit}th occurrence of a
411 @samp{\( @dots{} \)} construct.
413 In other words, after the end of a @samp{\( @dots{} \)} construct, the
414 matcher remembers the beginning and end of the text matched by that
415 construct. Then, later on in the regular expression, you can use
416 @samp{\} followed by @var{digit} to match that same text, whatever it
419 The strings matching the first nine @samp{\( @dots{} \)} constructs
420 appearing in a regular expression are assigned numbers 1 through 9 in
421 the order that the open parentheses appear in the regular expression.
422 So you can use @samp{\1} through @samp{\9} to refer to the text matched
423 by the corresponding @samp{\( @dots{} \)} constructs.
425 For example, @samp{\(.*\)\1} matches any newline-free string that is
426 composed of two identical halves. The @samp{\(.*\)} matches the first
427 half, which may be anything, but the @samp{\1} that follows must match
431 @cindex @samp{\w} in regexp
432 matches any word-constituent character. The editor syntax table
433 determines which characters these are. @xref{Syntax Tables}.
436 @cindex @samp{\W} in regexp
437 matches any character that is not a word constituent.
440 @cindex @samp{\s} in regexp
441 matches any character whose syntax is @var{code}. Here @var{code} is a
442 character that represents a syntax code: thus, @samp{w} for word
443 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
444 etc. To represent whitespace syntax, use either @samp{-} or a space
445 character. @xref{Syntax Class Table}, for a list of syntax codes and
446 the characters that stand for them.
449 @cindex @samp{\S} in regexp
450 matches any character whose syntax is not @var{code}.
453 The following regular expression constructs match the empty string---that is,
454 they don't use up any characters---but whether they match depends on the
459 @cindex @samp{\`} in regexp
460 matches the empty string, but only at the beginning
461 of the buffer or string being matched against.
464 @cindex @samp{\'} in regexp
465 matches the empty string, but only at the end of
466 the buffer or string being matched against.
469 @cindex @samp{\=} in regexp
470 matches the empty string, but only at point.
471 (This construct is not defined when matching against a string.)
474 @cindex @samp{\b} in regexp
475 matches the empty string, but only at the beginning or
476 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
477 @samp{foo} as a separate word. @samp{\bballs?\b} matches
478 @samp{ball} or @samp{balls} as a separate word.@refill
480 @samp{\b} matches at the beginning or end of the buffer
481 regardless of what text appears next to it.
484 @cindex @samp{\B} in regexp
485 matches the empty string, but @emph{not} at the beginning or
489 @cindex @samp{\<} in regexp
490 matches the empty string, but only at the beginning of a word.
491 @samp{\<} matches at the beginning of the buffer only if a
492 word-constituent character follows.
495 @cindex @samp{\>} in regexp
496 matches the empty string, but only at the end of a word. @samp{\>}
497 matches at the end of the buffer only if the contents end with a
498 word-constituent character.
501 @kindex invalid-regexp
502 Not every string is a valid regular expression. For example, a string
503 with unbalanced square brackets is invalid (with a few exceptions, such
504 as @samp{[]]}), and so is a string that ends with a single @samp{\}. If
505 an invalid regular expression is passed to any of the search functions,
506 an @code{invalid-regexp} error is signaled.
508 @defun regexp-quote string
509 This function returns a regular expression string that matches exactly
510 @var{string} and nothing else. This allows you to request an exact
511 string match when calling a function that wants a regular expression.
515 (regexp-quote "^The cat$")
516 @result{} "\\^The cat\\$"
520 One use of @code{regexp-quote} is to combine an exact string match with
521 context described as a regular expression. For example, this searches
522 for the string that is the value of @var{string}, surrounded by
528 (concat "\\s-" (regexp-quote string) "\\s-"))
533 @defun regexp-opt strings &optional paren
535 This function returns an efficient regular expression that will match
536 any of the strings @var{strings}. This is useful when you need to make
537 matching or searching as fast as possible---for example, for Font Lock
540 If the optional argument @var{paren} is non-@code{nil}, then the
541 returned regular expression is always enclosed by at least one
542 parentheses-grouping construct.
544 This simplified definition of @code{regexp-opt} produces a
545 regular expression which is equivalent to the actual value
546 (but not as efficient):
549 (defun regexp-opt (strings paren)
550 (let ((open-paren (if paren "\\(" ""))
551 (close-paren (if paren "\\)" "")))
553 (mapconcat 'regexp-quote strings "\\|")
558 @defun regexp-opt-depth regexp
559 @tindex regexp-opt-depth
560 This function returns the total number of grouping constructs
561 (parenthesized expressions) in @var{regexp}.
565 @comment node-name, next, previous, up
566 @subsection Complex Regexp Example
568 Here is a complicated regexp, used by Emacs to recognize the end of a
569 sentence together with any whitespace that follows. It is the value of
570 the variable @code{sentence-end}.
572 First, we show the regexp as a string in Lisp syntax to distinguish
573 spaces from tab characters. The string constant begins and ends with a
574 double-quote. @samp{\"} stands for a double-quote as part of the
575 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
576 tab and @samp{\n} for a newline.
579 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
583 In contrast, if you evaluate the variable @code{sentence-end}, you
584 will see the following:
589 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
595 In this output, tab and newline appear as themselves.
597 This regular expression contains four parts in succession and can be
598 deciphered as follows:
602 The first part of the pattern is a character alternative that matches
603 any one of three characters: period, question mark, and exclamation
604 mark. The match must begin with one of these three characters.
607 The second part of the pattern matches any closing braces and quotation
608 marks, zero or more of them, that may follow the period, question mark
609 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
610 a string. The @samp{*} at the end indicates that the immediately
611 preceding regular expression (a character alternative, in this case) may be
612 repeated zero or more times.
614 @item \\($\\|@ $\\|\t\\|@ @ \\)
615 The third part of the pattern matches the whitespace that follows the
616 end of a sentence: the end of a line (optionally with a space), or a
617 tab, or two spaces. The double backslashes mark the parentheses and
618 vertical bars as regular expression syntax; the parentheses delimit a
619 group and the vertical bars separate alternatives. The dollar sign is
620 used to match the end of a line.
623 Finally, the last part of the pattern matches any additional whitespace
624 beyond the minimum needed to end a sentence.
628 @section Regular Expression Searching
629 @cindex regular expression searching
630 @cindex regexp searching
631 @cindex searching for regexp
633 In GNU Emacs, you can search for the next match for a regular
634 expression either incrementally or not. For incremental search
635 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
636 The GNU Emacs Manual}. Here we describe only the search functions
637 useful in programs. The principal one is @code{re-search-forward}.
639 These search functions convert the regular expression to multibyte if
640 the buffer is multibyte; they convert the regular expression to unibyte
641 if the buffer is unibyte. @xref{Text Representations}.
643 @deffn Command re-search-forward regexp &optional limit noerror repeat
644 This function searches forward in the current buffer for a string of
645 text that is matched by the regular expression @var{regexp}. The
646 function skips over any amount of text that is not matched by
647 @var{regexp}, and leaves point at the end of the first match found.
648 It returns the new value of point.
650 If @var{limit} is non-@code{nil} (it must be a position in the current
651 buffer), then it is the upper bound to the search. No match extending
652 after that position is accepted.
654 If @var{repeat} is supplied (it must be a positive number), then the
655 search is repeated that many times (each time starting at the end of the
656 previous time's match). If all these successive searches succeed, the
657 function succeeds, moving point and returning its new value. Otherwise
660 What happens when the function fails depends on the value of
661 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
662 error is signaled. If @var{noerror} is @code{t},
663 @code{re-search-forward} does nothing and returns @code{nil}. If
664 @var{noerror} is neither @code{nil} nor @code{t}, then
665 @code{re-search-forward} moves point to @var{limit} (or the end of the
666 buffer) and returns @code{nil}.
668 In the following example, point is initially before the @samp{T}.
669 Evaluating the search call moves point to the end of that line (between
670 the @samp{t} of @samp{hat} and the newline).
674 ---------- Buffer: foo ----------
675 I read "@point{}The cat in the hat
677 ---------- Buffer: foo ----------
681 (re-search-forward "[a-z]+" nil t 5)
684 ---------- Buffer: foo ----------
685 I read "The cat in the hat@point{}
687 ---------- Buffer: foo ----------
692 @deffn Command re-search-backward regexp &optional limit noerror repeat
693 This function searches backward in the current buffer for a string of
694 text that is matched by the regular expression @var{regexp}, leaving
695 point at the beginning of the first text found.
697 This function is analogous to @code{re-search-forward}, but they are not
698 simple mirror images. @code{re-search-forward} finds the match whose
699 beginning is as close as possible to the starting point. If
700 @code{re-search-backward} were a perfect mirror image, it would find the
701 match whose end is as close as possible. However, in fact it finds the
702 match whose beginning is as close as possible. The reason is that
703 matching a regular expression at a given spot always works from
704 beginning to end, and starts at a specified beginning position.
706 A true mirror-image of @code{re-search-forward} would require a special
707 feature for matching regular expressions from end to beginning. It's
708 not worth the trouble of implementing that.
711 @defun string-match regexp string &optional start
712 This function returns the index of the start of the first match for
713 the regular expression @var{regexp} in @var{string}, or @code{nil} if
714 there is no match. If @var{start} is non-@code{nil}, the search starts
715 at that index in @var{string}.
722 "quick" "The quick brown fox jumped quickly.")
727 "quick" "The quick brown fox jumped quickly." 8)
733 The index of the first character of the
734 string is 0, the index of the second character is 1, and so on.
736 After this function returns, the index of the first character beyond
737 the match is available as @code{(match-end 0)}. @xref{Match Data}.
742 "quick" "The quick brown fox jumped quickly." 8)
753 @defun looking-at regexp
754 This function determines whether the text in the current buffer directly
755 following point matches the regular expression @var{regexp}. ``Directly
756 following'' means precisely that: the search is ``anchored'' and it can
757 succeed only starting with the first character following point. The
758 result is @code{t} if so, @code{nil} otherwise.
760 This function does not move point, but it updates the match data, which
761 you can access using @code{match-beginning} and @code{match-end}.
764 In this example, point is located directly before the @samp{T}. If it
765 were anywhere else, the result would be @code{nil}.
769 ---------- Buffer: foo ----------
770 I read "@point{}The cat in the hat
772 ---------- Buffer: foo ----------
774 (looking-at "The cat in the hat$")
781 @section POSIX Regular Expression Searching
783 The usual regular expression functions do backtracking when necessary
784 to handle the @samp{\|} and repetition constructs, but they continue
785 this only until they find @emph{some} match. Then they succeed and
786 report the first match found.
788 This section describes alternative search functions which perform the
789 full backtracking specified by the POSIX standard for regular expression
790 matching. They continue backtracking until they have tried all
791 possibilities and found all matches, so they can report the longest
792 match, as required by POSIX. This is much slower, so use these
793 functions only when you really need the longest match.
795 @defun posix-search-forward regexp &optional limit noerror repeat
796 This is like @code{re-search-forward} except that it performs the full
797 backtracking specified by the POSIX standard for regular expression
801 @defun posix-search-backward regexp &optional limit noerror repeat
802 This is like @code{re-search-backward} except that it performs the full
803 backtracking specified by the POSIX standard for regular expression
807 @defun posix-looking-at regexp
808 This is like @code{looking-at} except that it performs the full
809 backtracking specified by the POSIX standard for regular expression
813 @defun posix-string-match regexp string &optional start
814 This is like @code{string-match} except that it performs the full
815 backtracking specified by the POSIX standard for regular expression
820 @deffn Command delete-matching-lines regexp
821 This function is identical to @code{delete-non-matching-lines}, save
822 that it deletes what @code{delete-non-matching-lines} keeps.
824 In the example below, point is located on the first line of text.
828 ---------- Buffer: foo ----------
831 that all men are created
832 equal, and that they are
833 ---------- Buffer: foo ----------
837 (delete-matching-lines "the")
840 ---------- Buffer: foo ----------
842 that all men are created
843 ---------- Buffer: foo ----------
848 @deffn Command flush-lines regexp
849 This function is the same as @code{delete-matching-lines}.
852 @defun delete-non-matching-lines regexp
853 This function deletes all lines following point which don't
854 contain a match for the regular expression @var{regexp}.
857 @deffn Command keep-lines regexp
858 This function is the same as @code{delete-non-matching-lines}.
861 @deffn Command how-many regexp
862 This function counts the number of matches for @var{regexp} there are in
863 the current buffer following point. It prints this number in
864 the echo area, returning the string printed.
867 @deffn Command count-matches regexp
868 This function is a synonym of @code{how-many}.
871 @deffn Command list-matching-lines regexp nlines
872 This function is a synonym of @code{occur}.
873 Show all lines following point containing a match for @var{regexp}.
874 Display each line with @var{nlines} lines before and after,
875 or @code{-}@var{nlines} before if @var{nlines} is negative.
876 @var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
877 Interactively it is the prefix arg.
879 The lines are shown in a buffer named @samp{*Occur*}.
880 It serves as a menu to find any of the occurrences in this buffer.
881 @kbd{C-h m} (@code{describe-mode} in that buffer gives help.
884 @defopt list-matching-lines-default-context-lines
886 Default number of context lines to include around a @code{list-matching-lines}
887 match. A negative number means to include that many lines before the match.
888 A positive number means to include that many lines both before and after.
892 @node Search and Replace
893 @section Search and Replace
896 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
897 This function is the guts of @code{query-replace} and related commands.
898 It searches for occurrences of @var{from-string} and replaces some or
899 all of them. If @var{query-flag} is @code{nil}, it replaces all
900 occurrences; otherwise, it asks the user what to do about each one.
902 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
903 considered a regular expression; otherwise, it must match literally. If
904 @var{delimited-flag} is non-@code{nil}, then only replacements
905 surrounded by word boundaries are considered.
907 The argument @var{replacements} specifies what to replace occurrences
908 with. If it is a string, that string is used. It can also be a list of
909 strings, to be used in cyclic order.
911 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
912 it specifies how many times to use each of the strings in the
913 @var{replacements} list before advancing cyclicly to the next one.
915 Normally, the keymap @code{query-replace-map} defines the possible user
916 responses for queries. The argument @var{map}, if non-@code{nil}, is a
917 keymap to use instead of @code{query-replace-map}.
920 @defvar query-replace-map
921 This variable holds a special keymap that defines the valid user
922 responses for @code{query-replace} and related functions, as well as
923 @code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways:
927 The ``key bindings'' are not commands, just symbols that are meaningful
928 to the functions that use this map.
931 Prefix keys are not supported; each key binding must be for a
932 single-event key sequence. This is because the functions don't use
933 @code{read-key-sequence} to get the input; instead, they read a single
934 event and look it up ``by hand.''
938 Here are the meaningful ``bindings'' for @code{query-replace-map}.
939 Several of them are meaningful only for @code{query-replace} and
944 Do take the action being considered---in other words, ``yes.''
947 Do not take action for this question---in other words, ``no.''
950 Answer this question ``no,'' and give up on the entire series of
951 questions, assuming that the answers will be ``no.''
954 Answer this question ``yes,'' and give up on the entire series of
955 questions, assuming that subsequent answers will be ``no.''
958 Answer this question ``yes,'' but show the results---don't advance yet
959 to the next question.
962 Answer this question and all subsequent questions in the series with
963 ``yes,'' without further user interaction.
966 Move back to the previous place that a question was asked about.
969 Enter a recursive edit to deal with this question---instead of any
970 other action that would normally be taken.
972 @item delete-and-edit
973 Delete the text being considered, then enter a recursive edit to replace
977 Redisplay and center the window, then ask the same question again.
980 Perform a quit right away. Only @code{y-or-n-p} and related functions
984 Display some help, then ask again.
988 @section The Match Data
991 Emacs keeps track of the positions of the start and end of segments of
992 text found during a regular expression search. This means, for example,
993 that you can search for a complex pattern, such as a date in an Rmail
994 message, and then extract parts of the match under control of the
997 Because the match data normally describe the most recent search only,
998 you must be careful not to do another search inadvertently between the
999 search you wish to refer back to and the use of the match data. If you
1000 can't avoid another intervening search, you must save and restore the
1001 match data around it, to prevent it from being overwritten.
1004 * Replacing Match:: Replacing a substring that was matched.
1005 * Simple Match Data:: Accessing single items of match data,
1006 such as where a particular subexpression started.
1007 * Entire Match Data:: Accessing the entire match data at once, as a list.
1008 * Saving Match Data:: Saving and restoring the match data.
1011 @node Replacing Match
1012 @subsection Replacing the Text That Matched
1014 This function replaces the text matched by the last search with
1017 @cindex case in replacements
1018 @defun replace-match replacement &optional fixedcase literal string subexp
1019 This function replaces the text in the buffer (or in @var{string}) that
1020 was matched by the last search. It replaces that text with
1023 If you did the last search in a buffer, you should specify @code{nil}
1024 for @var{string}. Then @code{replace-match} does the replacement by
1025 editing the buffer; it leaves point at the end of the replacement text,
1026 and returns @code{t}.
1028 If you did the search in a string, pass the same string as @var{string}.
1029 Then @code{replace-match} does the replacement by constructing and
1030 returning a new string.
1032 If @var{fixedcase} is non-@code{nil}, then the case of the replacement
1033 text is not changed; otherwise, the replacement text is converted to a
1034 different case depending upon the capitalization of the text to be
1035 replaced. If the original text is all upper case, the replacement text
1036 is converted to upper case. If the first word of the original text is
1037 capitalized, then the first word of the replacement text is capitalized.
1038 If the original text contains just one word, and that word is a capital
1039 letter, @code{replace-match} considers this a capitalized first word
1040 rather than all upper case.
1042 If @code{case-replace} is @code{nil}, then case conversion is not done,
1043 regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
1045 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1046 exactly as it is, the only alterations being case changes as needed.
1047 If it is @code{nil} (the default), then the character @samp{\} is treated
1048 specially. If a @samp{\} appears in @var{replacement}, then it must be
1049 part of one of the following sequences:
1053 @cindex @samp{&} in replacement
1054 @samp{\&} stands for the entire text being replaced.
1056 @item @samp{\@var{n}}
1057 @cindex @samp{\@var{n}} in replacement
1058 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1059 matched the @var{n}th subexpression in the original regexp.
1060 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1063 @cindex @samp{\} in replacement
1064 @samp{\\} stands for a single @samp{\} in the replacement text.
1067 If @var{subexp} is non-@code{nil}, that says to replace just
1068 subexpression number @var{subexp} of the regexp that was matched, not
1069 the entire match. For example, after matching @samp{foo \(ba*r\)},
1070 calling @code{replace-match} with 1 as @var{subexp} means to replace
1071 just the text that matched @samp{\(ba*r\)}.
1074 @node Simple Match Data
1075 @subsection Simple Match Data Access
1077 This section explains how to use the match data to find out what was
1078 matched by the last search or match operation.
1080 You can ask about the entire matching text, or about a particular
1081 parenthetical subexpression of a regular expression. The @var{count}
1082 argument in the functions below specifies which. If @var{count} is
1083 zero, you are asking about the entire match. If @var{count} is
1084 positive, it specifies which subexpression you want.
1086 Recall that the subexpressions of a regular expression are those
1087 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1088 @var{count}th subexpression is found by counting occurrences of
1089 @samp{\(} from the beginning of the whole regular expression. The first
1090 subexpression is numbered 1, the second 2, and so on. Only regular
1091 expressions can have subexpressions---after a simple string search, the
1092 only information available is about the entire match.
1094 A search which fails may or may not alter the match data. In the
1095 past, a failing search did not do this, but we may change it in the
1098 @defun match-string count &optional in-string
1099 This function returns, as a string, the text matched in the last search
1100 or match operation. It returns the entire text if @var{count} is zero,
1101 or just the portion corresponding to the @var{count}th parenthetical
1102 subexpression, if @var{count} is positive. If @var{count} is out of
1103 range, or if that subexpression didn't match anything, the value is
1106 If the last such operation was done against a string with
1107 @code{string-match}, then you should pass the same string as the
1108 argument @var{in-string}. After a buffer search or match,
1109 you should omit @var{in-string} or pass @code{nil} for it; but you
1110 should make sure that the current buffer when you call
1111 @code{match-string} is the one in which you did the searching or
1115 @defun match-string-no-properties count
1116 This function is like @code{match-string} except that the result
1117 has no text properties.
1120 @defun match-beginning count
1121 This function returns the position of the start of text matched by the
1122 last regular expression searched for, or a subexpression of it.
1124 If @var{count} is zero, then the value is the position of the start of
1125 the entire match. Otherwise, @var{count} specifies a subexpression in
1126 the regular expression, and the value of the function is the starting
1127 position of the match for that subexpression.
1129 The value is @code{nil} for a subexpression inside a @samp{\|}
1130 alternative that wasn't used in the match.
1133 @defun match-end count
1134 This function is like @code{match-beginning} except that it returns the
1135 position of the end of the match, rather than the position of the
1139 Here is an example of using the match data, with a comment showing the
1140 positions within the text:
1144 (string-match "\\(qu\\)\\(ick\\)"
1145 "The quick fox jumped quickly.")
1151 (match-string 0 "The quick fox jumped quickly.")
1153 (match-string 1 "The quick fox jumped quickly.")
1155 (match-string 2 "The quick fox jumped quickly.")
1160 (match-beginning 1) ; @r{The beginning of the match}
1161 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1165 (match-beginning 2) ; @r{The beginning of the match}
1166 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1170 (match-end 1) ; @r{The end of the match}
1171 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1173 (match-end 2) ; @r{The end of the match}
1174 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1178 Here is another example. Point is initially located at the beginning
1179 of the line. Searching moves point to between the space and the word
1180 @samp{in}. The beginning of the entire match is at the 9th character of
1181 the buffer (@samp{T}), and the beginning of the match for the first
1182 subexpression is at the 13th character (@samp{c}).
1187 (re-search-forward "The \\(cat \\)")
1189 (match-beginning 1))
1194 ---------- Buffer: foo ----------
1195 I read "The cat @point{}in the hat comes back" twice.
1198 ---------- Buffer: foo ----------
1203 (In this case, the index returned is a buffer position; the first
1204 character of the buffer counts as 1.)
1206 @node Entire Match Data
1207 @subsection Accessing the Entire Match Data
1209 The functions @code{match-data} and @code{set-match-data} read or
1210 write the entire match data, all at once.
1213 This function returns a newly constructed list containing all the
1214 information on what text the last search matched. Element zero is the
1215 position of the beginning of the match for the whole expression; element
1216 one is the position of the end of the match for the expression. The
1217 next two elements are the positions of the beginning and end of the
1218 match for the first subexpression, and so on. In general, element
1223 number {\mathsurround=0pt $2n$}
1225 corresponds to @code{(match-beginning @var{n})}; and
1231 number {\mathsurround=0pt $2n+1$}
1233 corresponds to @code{(match-end @var{n})}.
1235 All the elements are markers or @code{nil} if matching was done on a
1236 buffer, and all are integers or @code{nil} if matching was done on a
1237 string with @code{string-match}.
1239 As always, there must be no possibility of intervening searches between
1240 the call to a search function and the call to @code{match-data} that is
1241 intended to access the match data for that search.
1246 @result{} (#<marker at 9 in foo>
1247 #<marker at 17 in foo>
1248 #<marker at 13 in foo>
1249 #<marker at 17 in foo>)
1254 @defun set-match-data match-list
1255 This function sets the match data from the elements of @var{match-list},
1256 which should be a list that was the value of a previous call to
1259 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1260 an error; that sets the match data in a meaningless but harmless way.
1262 @findex store-match-data
1263 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1266 @node Saving Match Data
1267 @subsection Saving and Restoring the Match Data
1269 When you call a function that may do a search, you may need to save
1270 and restore the match data around that call, if you want to preserve the
1271 match data from an earlier search for later use. Here is an example
1272 that shows the problem that arises if you fail to save the match data:
1276 (re-search-forward "The \\(cat \\)")
1278 (foo) ; @r{Perhaps @code{foo} does}
1279 ; @r{more searching.}
1281 @result{} 61 ; @r{Unexpected result---not 48!}
1285 You can save and restore the match data with @code{save-match-data}:
1287 @defmac save-match-data body@dots{}
1288 This macro executes @var{body}, saving and restoring the match
1292 You could use @code{set-match-data} together with @code{match-data} to
1293 imitate the effect of the special form @code{save-match-data}. Here is
1298 (let ((data (match-data)))
1300 @dots{} ; @r{Ok to change the original match data.}
1301 (set-match-data data)))
1305 Emacs automatically saves and restores the match data when it runs
1306 process filter functions (@pxref{Filter Functions}) and process
1307 sentinels (@pxref{Sentinels}).
1310 Here is a function which restores the match data provided the buffer
1311 associated with it still exists.
1315 (defun restore-match-data (data)
1316 @c It is incorrect to split the first line of a doc string.
1317 @c If there's a problem here, it should be solved in some other way.
1318 "Restore the match data DATA unless the buffer is missing."
1324 (null (marker-buffer (car d)))
1326 ;; @file{match-data} @r{buffer is deleted.}
1329 (set-match-data data))))
1334 @node Searching and Case
1335 @section Searching and Case
1336 @cindex searching and case
1338 By default, searches in Emacs ignore the case of the text they are
1339 searching through; if you specify searching for @samp{FOO}, then
1340 @samp{Foo} or @samp{foo} is also considered a match. This applies to
1341 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
1342 @samp{A} or @samp{b} or @samp{B}.
1344 If you do not want this feature, set the variable
1345 @code{case-fold-search} to @code{nil}. Then all letters must match
1346 exactly, including case. This is a buffer-local variable; altering the
1347 variable affects only the current buffer. (@xref{Intro to
1348 Buffer-Local}.) Alternatively, you may change the value of
1349 @code{default-case-fold-search}, which is the default value of
1350 @code{case-fold-search} for buffers that do not override it.
1352 Note that the user-level incremental search feature handles case
1353 distinctions differently. When given a lower case letter, it looks for
1354 a match of either case, but when given an upper case letter, it looks
1355 for an upper case letter only. But this has nothing to do with the
1356 searching functions used in Lisp code.
1358 @defopt case-replace
1359 This variable determines whether the replacement functions should
1360 preserve case. If the variable is @code{nil}, that means to use the
1361 replacement text verbatim. A non-@code{nil} value means to convert the
1362 case of the replacement text according to the text being replaced.
1364 The function @code{replace-match} is where this variable actually has
1365 its effect. @xref{Replacing Match}.
1368 @defopt case-fold-search
1369 This buffer-local variable determines whether searches should ignore
1370 case. If the variable is @code{nil} they do not ignore case; otherwise
1371 they do ignore case.
1374 @defvar default-case-fold-search
1375 The value of this variable is the default value for
1376 @code{case-fold-search} in buffers that do not override it. This is the
1377 same as @code{(default-value 'case-fold-search)}.
1380 @node Standard Regexps
1381 @section Standard Regular Expressions Used in Editing
1382 @cindex regexps used standardly in editing
1383 @cindex standard regexps used in editing
1385 This section describes some variables that hold regular expressions
1386 used for certain purposes in editing:
1388 @defvar page-delimiter
1389 This is the regular expression describing line-beginnings that separate
1390 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1391 @code{"^\C-l"}); this matches a line that starts with a formfeed
1395 The following two regular expressions should @emph{not} assume the
1396 match always starts at the beginning of a line; they should not use
1397 @samp{^} to anchor the match. Most often, the paragraph commands do
1398 check for a match only at the beginning of a line, which means that
1399 @samp{^} would be superfluous. When there is a nonzero left margin,
1400 they accept matches that start after the left margin. In that case, a
1401 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1402 where a left margin is never used.
1404 @defvar paragraph-separate
1405 This is the regular expression for recognizing the beginning of a line
1406 that separates paragraphs. (If you change this, you may have to
1407 change @code{paragraph-start} also.) The default value is
1408 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1409 spaces, tabs, and form feeds (after its left margin).
1412 @defvar paragraph-start
1413 This is the regular expression for recognizing the beginning of a line
1414 that starts @emph{or} separates paragraphs. The default value is
1415 @w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
1416 newline, or form feed (after its left margin).
1419 @defvar sentence-end
1420 This is the regular expression describing the end of a sentence. (All
1421 paragraph boundaries also end sentences, regardless.) The default value
1425 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
1428 This means a period, question mark or exclamation mark, followed
1429 optionally by a closing parenthetical character, followed by tabs,
1430 spaces or new lines.
1432 For a detailed explanation of this regular expression, see @ref{Regexp