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 ASCII letter. Ranges may be
270 intermixed freely with individual characters, as in @samp{[a-z$%.]},
271 which matches any lower case 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-\x8c0]} is invalid because
284 @samp{a} is in the @sc{ASCII} character set but the character 0x8c0
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 @samp{^} in regexp
316 @cindex beginning of line in regexp
317 is a special character that matches the empty string, but only at the
318 beginning of a line in the text being matched. Otherwise it fails to
319 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
320 the beginning of a line.
322 When matching a string instead of a buffer, @samp{^} matches at the
323 beginning of the string or after a newline character @samp{\n}.
326 @cindex @samp{$} in regexp
327 is similar to @samp{^} but matches only at the end of a line. Thus,
328 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
330 When matching a string instead of a buffer, @samp{$} matches at the end
331 of the string or before a newline character @samp{\n}.
334 @cindex @samp{\} in regexp
335 has two functions: it quotes the special characters (including
336 @samp{\}), and it introduces additional special constructs.
338 Because @samp{\} quotes special characters, @samp{\$} is a regular
339 expression that matches only @samp{$}, and @samp{\[} is a regular
340 expression that matches only @samp{[}, and so on.
342 Note that @samp{\} also has special meaning in the read syntax of Lisp
343 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
344 example, the regular expression that matches the @samp{\} character is
345 @samp{\\}. To write a Lisp string that contains the characters
346 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
347 @samp{\}. Therefore, the read syntax for a regular expression matching
348 @samp{\} is @code{"\\\\"}.@refill
351 @strong{Please note:} For historical compatibility, special characters
352 are treated as ordinary ones if they are in contexts where their special
353 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
354 ordinary since there is no preceding expression on which the @samp{*}
355 can act. It is poor practice to depend on this behavior; quote the
356 special character anyway, regardless of where it appears.@refill
358 For the most part, @samp{\} followed by any character matches only that
359 character. However, there are several exceptions: two-character
360 sequences starting with @samp{\} which have special meanings. (The
361 second character in such a sequence is always ordinary when used on its
362 own.) Here is a table of @samp{\} constructs.
366 @cindex @samp{|} in regexp
367 @cindex regexp alternative
368 specifies an alternative.
369 Two regular expressions @var{a} and @var{b} with @samp{\|} in
370 between form an expression that matches anything that either @var{a} or
371 @var{b} matches.@refill
373 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
374 but no other string.@refill
376 @samp{\|} applies to the largest possible surrounding expressions. Only a
377 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
380 Full backtracking capability exists to handle multiple uses of @samp{\|}.
383 @cindex @samp{(} in regexp
384 @cindex @samp{)} in regexp
385 @cindex regexp grouping
386 is a grouping construct that serves three purposes:
390 To enclose a set of @samp{\|} alternatives for other operations. Thus,
391 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
395 To enclose a complicated expression for the postfix operators @samp{*},
396 @samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
397 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
398 number (zero or more) of @samp{na} strings.
401 To record a matched substring for future reference.
404 This last application is not a consequence of the idea of a
405 parenthetical grouping; it is a separate feature that happens to be
406 assigned as a second meaning to the same @samp{\( @dots{} \)} construct
407 because there is no conflict in practice between the two meanings.
408 Here is an explanation of this feature:
411 matches the same text that matched the @var{digit}th occurrence of a
412 @samp{\( @dots{} \)} construct.
414 In other words, after the end of a @samp{\( @dots{} \)} construct, the
415 matcher remembers the beginning and end of the text matched by that
416 construct. Then, later on in the regular expression, you can use
417 @samp{\} followed by @var{digit} to match that same text, whatever it
420 The strings matching the first nine @samp{\( @dots{} \)} constructs
421 appearing in a regular expression are assigned numbers 1 through 9 in
422 the order that the open parentheses appear in the regular expression.
423 So you can use @samp{\1} through @samp{\9} to refer to the text matched
424 by the corresponding @samp{\( @dots{} \)} constructs.
426 For example, @samp{\(.*\)\1} matches any newline-free string that is
427 composed of two identical halves. The @samp{\(.*\)} matches the first
428 half, which may be anything, but the @samp{\1} that follows must match
432 @cindex @samp{\w} in regexp
433 matches any word-constituent character. The editor syntax table
434 determines which characters these are. @xref{Syntax Tables}.
437 @cindex @samp{\W} in regexp
438 matches any character that is not a word constituent.
441 @cindex @samp{\s} in regexp
442 matches any character whose syntax is @var{code}. Here @var{code} is a
443 character that represents a syntax code: thus, @samp{w} for word
444 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
445 etc. To represent whitespace syntax, use either @samp{-} or a space
446 character. @xref{Syntax Class Table}, for a list of syntax codes and
447 the characters that stand for them.
450 @cindex @samp{\S} in regexp
451 matches any character whose syntax is not @var{code}.
454 The following regular expression constructs match the empty string---that is,
455 they don't use up any characters---but whether they match depends on the
460 @cindex @samp{\`} in regexp
461 matches the empty string, but only at the beginning
462 of the buffer or string being matched against.
465 @cindex @samp{\'} in regexp
466 matches the empty string, but only at the end of
467 the buffer or string being matched against.
470 @cindex @samp{\=} in regexp
471 matches the empty string, but only at point.
472 (This construct is not defined when matching against a string.)
475 @cindex @samp{\b} in regexp
476 matches the empty string, but only at the beginning or
477 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
478 @samp{foo} as a separate word. @samp{\bballs?\b} matches
479 @samp{ball} or @samp{balls} as a separate word.@refill
481 @samp{\b} matches at the beginning or end of the buffer
482 regardless of what text appears next to it.
485 @cindex @samp{\B} in regexp
486 matches the empty string, but @emph{not} at the beginning or
490 @cindex @samp{\<} in regexp
491 matches the empty string, but only at the beginning of a word.
492 @samp{\<} matches at the beginning of the buffer only if a
493 word-constituent character follows.
496 @cindex @samp{\>} in regexp
497 matches the empty string, but only at the end of a word. @samp{\>}
498 matches at the end of the buffer only if the contents end with a
499 word-constituent character.
502 @kindex invalid-regexp
503 Not every string is a valid regular expression. For example, a string
504 with unbalanced square brackets is invalid (with a few exceptions, such
505 as @samp{[]]}), and so is a string that ends with a single @samp{\}. If
506 an invalid regular expression is passed to any of the search functions,
507 an @code{invalid-regexp} error is signaled.
509 @defun regexp-quote string
510 This function returns a regular expression string that matches exactly
511 @var{string} and nothing else. This allows you to request an exact
512 string match when calling a function that wants a regular expression.
516 (regexp-quote "^The cat$")
517 @result{} "\\^The cat\\$"
521 One use of @code{regexp-quote} is to combine an exact string match with
522 context described as a regular expression. For example, this searches
523 for the string that is the value of @var{string}, surrounded by
529 (concat "\\s-" (regexp-quote string) "\\s-"))
534 @defun regexp-opt strings &optional paren
536 This function returns an efficient regular expression that will match
537 any of the strings @var{strings}. This is useful when you need to make
538 matching or searching as fast as possible---for example, for Font Lock
541 If the optional argument @var{paren} is non-@code{nil}, then the
542 returned regular expression is always enclosed by at least one
543 parentheses-grouping construct.
545 This simplified definition of @code{regexp-opt} produces a
546 regular expression which is equivalent to the actual value
547 (but not as efficient):
550 (defun regexp-opt (strings paren)
551 (let ((open-paren (if paren "\\(" ""))
552 (close-paren (if paren "\\)" "")))
554 (mapconcat 'regexp-quote strings "\\|")
559 @defun regexp-opt-depth regexp
560 @tindex regexp-opt-depth
561 This function returns the total number of grouping constructs
562 (parenthesized expressions) in @var{regexp}.
566 @comment node-name, next, previous, up
567 @subsection Complex Regexp Example
569 Here is a complicated regexp, used by Emacs to recognize the end of a
570 sentence together with any whitespace that follows. It is the value of
571 the variable @code{sentence-end}.
573 First, we show the regexp as a string in Lisp syntax to distinguish
574 spaces from tab characters. The string constant begins and ends with a
575 double-quote. @samp{\"} stands for a double-quote as part of the
576 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
577 tab and @samp{\n} for a newline.
580 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
584 In contrast, if you evaluate the variable @code{sentence-end}, you
585 will see the following:
590 @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
596 In this output, tab and newline appear as themselves.
598 This regular expression contains four parts in succession and can be
599 deciphered as follows:
603 The first part of the pattern is a character alternative that matches
604 any one of three characters: period, question mark, and exclamation
605 mark. The match must begin with one of these three characters.
608 The second part of the pattern matches any closing braces and quotation
609 marks, zero or more of them, that may follow the period, question mark
610 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
611 a string. The @samp{*} at the end indicates that the immediately
612 preceding regular expression (a character alternative, in this case) may be
613 repeated zero or more times.
615 @item \\($\\|@ $\\|\t\\|@ @ \\)
616 The third part of the pattern matches the whitespace that follows the
617 end of a sentence: the end of a line (optionally with a space), or a
618 tab, or two spaces. The double backslashes mark the parentheses and
619 vertical bars as regular expression syntax; the parentheses delimit a
620 group and the vertical bars separate alternatives. The dollar sign is
621 used to match the end of a line.
624 Finally, the last part of the pattern matches any additional whitespace
625 beyond the minimum needed to end a sentence.
629 @section Regular Expression Searching
630 @cindex regular expression searching
631 @cindex regexp searching
632 @cindex searching for regexp
634 In GNU Emacs, you can search for the next match for a regular
635 expression either incrementally or not. For incremental search
636 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
637 The GNU Emacs Manual}. Here we describe only the search functions
638 useful in programs. The principal one is @code{re-search-forward}.
640 These search functions convert the regular expression to multibyte if
641 the buffer is multibyte; they convert the regular expression to unibyte
642 if the buffer is unibyte. @xref{Text Representations}.
644 @deffn Command re-search-forward regexp &optional limit noerror repeat
645 This function searches forward in the current buffer for a string of
646 text that is matched by the regular expression @var{regexp}. The
647 function skips over any amount of text that is not matched by
648 @var{regexp}, and leaves point at the end of the first match found.
649 It returns the new value of point.
651 If @var{limit} is non-@code{nil} (it must be a position in the current
652 buffer), then it is the upper bound to the search. No match extending
653 after that position is accepted.
655 If @var{repeat} is supplied (it must be a positive number), then the
656 search is repeated that many times (each time starting at the end of the
657 previous time's match). If all these successive searches succeed, the
658 function succeeds, moving point and returning its new value. Otherwise
661 What happens when the function fails depends on the value of
662 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
663 error is signaled. If @var{noerror} is @code{t},
664 @code{re-search-forward} does nothing and returns @code{nil}. If
665 @var{noerror} is neither @code{nil} nor @code{t}, then
666 @code{re-search-forward} moves point to @var{limit} (or the end of the
667 buffer) and returns @code{nil}.
669 In the following example, point is initially before the @samp{T}.
670 Evaluating the search call moves point to the end of that line (between
671 the @samp{t} of @samp{hat} and the newline).
675 ---------- Buffer: foo ----------
676 I read "@point{}The cat in the hat
678 ---------- Buffer: foo ----------
682 (re-search-forward "[a-z]+" nil t 5)
685 ---------- Buffer: foo ----------
686 I read "The cat in the hat@point{}
688 ---------- Buffer: foo ----------
693 @deffn Command re-search-backward regexp &optional limit noerror repeat
694 This function searches backward in the current buffer for a string of
695 text that is matched by the regular expression @var{regexp}, leaving
696 point at the beginning of the first text found.
698 This function is analogous to @code{re-search-forward}, but they are not
699 simple mirror images. @code{re-search-forward} finds the match whose
700 beginning is as close as possible to the starting point. If
701 @code{re-search-backward} were a perfect mirror image, it would find the
702 match whose end is as close as possible. However, in fact it finds the
703 match whose beginning is as close as possible. The reason is that
704 matching a regular expression at a given spot always works from
705 beginning to end, and starts at a specified beginning position.
707 A true mirror-image of @code{re-search-forward} would require a special
708 feature for matching regular expressions from end to beginning. It's
709 not worth the trouble of implementing that.
712 @defun string-match regexp string &optional start
713 This function returns the index of the start of the first match for
714 the regular expression @var{regexp} in @var{string}, or @code{nil} if
715 there is no match. If @var{start} is non-@code{nil}, the search starts
716 at that index in @var{string}.
723 "quick" "The quick brown fox jumped quickly.")
728 "quick" "The quick brown fox jumped quickly." 8)
734 The index of the first character of the
735 string is 0, the index of the second character is 1, and so on.
737 After this function returns, the index of the first character beyond
738 the match is available as @code{(match-end 0)}. @xref{Match Data}.
743 "quick" "The quick brown fox jumped quickly." 8)
754 @defun looking-at regexp
755 This function determines whether the text in the current buffer directly
756 following point matches the regular expression @var{regexp}. ``Directly
757 following'' means precisely that: the search is ``anchored'' and it can
758 succeed only starting with the first character following point. The
759 result is @code{t} if so, @code{nil} otherwise.
761 This function does not move point, but it updates the match data, which
762 you can access using @code{match-beginning} and @code{match-end}.
765 In this example, point is located directly before the @samp{T}. If it
766 were anywhere else, the result would be @code{nil}.
770 ---------- Buffer: foo ----------
771 I read "@point{}The cat in the hat
773 ---------- Buffer: foo ----------
775 (looking-at "The cat in the hat$")
782 @section POSIX Regular Expression Searching
784 The usual regular expression functions do backtracking when necessary
785 to handle the @samp{\|} and repetition constructs, but they continue
786 this only until they find @emph{some} match. Then they succeed and
787 report the first match found.
789 This section describes alternative search functions which perform the
790 full backtracking specified by the POSIX standard for regular expression
791 matching. They continue backtracking until they have tried all
792 possibilities and found all matches, so they can report the longest
793 match, as required by POSIX. This is much slower, so use these
794 functions only when you really need the longest match.
796 @defun posix-search-forward regexp &optional limit noerror repeat
797 This is like @code{re-search-forward} except that it performs the full
798 backtracking specified by the POSIX standard for regular expression
802 @defun posix-search-backward regexp &optional limit noerror repeat
803 This is like @code{re-search-backward} except that it performs the full
804 backtracking specified by the POSIX standard for regular expression
808 @defun posix-looking-at regexp
809 This is like @code{looking-at} except that it performs the full
810 backtracking specified by the POSIX standard for regular expression
814 @defun posix-string-match regexp string &optional start
815 This is like @code{string-match} except that it performs the full
816 backtracking specified by the POSIX standard for regular expression
821 @deffn Command delete-matching-lines regexp
822 This function is identical to @code{delete-non-matching-lines}, save
823 that it deletes what @code{delete-non-matching-lines} keeps.
825 In the example below, point is located on the first line of text.
829 ---------- Buffer: foo ----------
832 that all men are created
833 equal, and that they are
834 ---------- Buffer: foo ----------
838 (delete-matching-lines "the")
841 ---------- Buffer: foo ----------
843 that all men are created
844 ---------- Buffer: foo ----------
849 @deffn Command flush-lines regexp
850 This function is the same as @code{delete-matching-lines}.
853 @defun delete-non-matching-lines regexp
854 This function deletes all lines following point which don't
855 contain a match for the regular expression @var{regexp}.
858 @deffn Command keep-lines regexp
859 This function is the same as @code{delete-non-matching-lines}.
862 @deffn Command how-many regexp
863 This function counts the number of matches for @var{regexp} there are in
864 the current buffer following point. It prints this number in
865 the echo area, returning the string printed.
868 @deffn Command count-matches regexp
869 This function is a synonym of @code{how-many}.
872 @deffn Command list-matching-lines regexp nlines
873 This function is a synonym of @code{occur}.
874 Show all lines following point containing a match for @var{regexp}.
875 Display each line with @var{nlines} lines before and after,
876 or @code{-}@var{nlines} before if @var{nlines} is negative.
877 @var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
878 Interactively it is the prefix arg.
880 The lines are shown in a buffer named @samp{*Occur*}.
881 It serves as a menu to find any of the occurrences in this buffer.
882 @kbd{C-h m} (@code{describe-mode} in that buffer gives help.
885 @defopt list-matching-lines-default-context-lines
887 Default number of context lines to include around a @code{list-matching-lines}
888 match. A negative number means to include that many lines before the match.
889 A positive number means to include that many lines both before and after.
893 @node Search and Replace
894 @section Search and Replace
897 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
898 This function is the guts of @code{query-replace} and related commands.
899 It searches for occurrences of @var{from-string} and replaces some or
900 all of them. If @var{query-flag} is @code{nil}, it replaces all
901 occurrences; otherwise, it asks the user what to do about each one.
903 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
904 considered a regular expression; otherwise, it must match literally. If
905 @var{delimited-flag} is non-@code{nil}, then only replacements
906 surrounded by word boundaries are considered.
908 The argument @var{replacements} specifies what to replace occurrences
909 with. If it is a string, that string is used. It can also be a list of
910 strings, to be used in cyclic order.
912 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
913 it specifies how many times to use each of the strings in the
914 @var{replacements} list before advancing cyclicly to the next one.
916 Normally, the keymap @code{query-replace-map} defines the possible user
917 responses for queries. The argument @var{map}, if non-@code{nil}, is a
918 keymap to use instead of @code{query-replace-map}.
921 @defvar query-replace-map
922 This variable holds a special keymap that defines the valid user
923 responses for @code{query-replace} and related functions, as well as
924 @code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways:
928 The ``key bindings'' are not commands, just symbols that are meaningful
929 to the functions that use this map.
932 Prefix keys are not supported; each key binding must be for a
933 single-event key sequence. This is because the functions don't use
934 @code{read-key-sequence} to get the input; instead, they read a single
935 event and look it up ``by hand.''
939 Here are the meaningful ``bindings'' for @code{query-replace-map}.
940 Several of them are meaningful only for @code{query-replace} and
945 Do take the action being considered---in other words, ``yes.''
948 Do not take action for this question---in other words, ``no.''
951 Answer this question ``no,'' and give up on the entire series of
952 questions, assuming that the answers will be ``no.''
955 Answer this question ``yes,'' and give up on the entire series of
956 questions, assuming that subsequent answers will be ``no.''
959 Answer this question ``yes,'' but show the results---don't advance yet
960 to the next question.
963 Answer this question and all subsequent questions in the series with
964 ``yes,'' without further user interaction.
967 Move back to the previous place that a question was asked about.
970 Enter a recursive edit to deal with this question---instead of any
971 other action that would normally be taken.
973 @item delete-and-edit
974 Delete the text being considered, then enter a recursive edit to replace
978 Redisplay and center the window, then ask the same question again.
981 Perform a quit right away. Only @code{y-or-n-p} and related functions
985 Display some help, then ask again.
989 @section The Match Data
992 Emacs keeps track of the positions of the start and end of segments of
993 text found during a regular expression search. This means, for example,
994 that you can search for a complex pattern, such as a date in an Rmail
995 message, and then extract parts of the match under control of the
998 Because the match data normally describe the most recent search only,
999 you must be careful not to do another search inadvertently between the
1000 search you wish to refer back to and the use of the match data. If you
1001 can't avoid another intervening search, you must save and restore the
1002 match data around it, to prevent it from being overwritten.
1005 * Replacing Match:: Replacing a substring that was matched.
1006 * Simple Match Data:: Accessing single items of match data,
1007 such as where a particular subexpression started.
1008 * Entire Match Data:: Accessing the entire match data at once, as a list.
1009 * Saving Match Data:: Saving and restoring the match data.
1012 @node Replacing Match
1013 @subsection Replacing the Text That Matched
1015 This function replaces the text matched by the last search with
1018 @cindex case in replacements
1019 @defun replace-match replacement &optional fixedcase literal string subexp
1020 This function replaces the text in the buffer (or in @var{string}) that
1021 was matched by the last search. It replaces that text with
1024 If you did the last search in a buffer, you should specify @code{nil}
1025 for @var{string}. Then @code{replace-match} does the replacement by
1026 editing the buffer; it leaves point at the end of the replacement text,
1027 and returns @code{t}.
1029 If you did the search in a string, pass the same string as @var{string}.
1030 Then @code{replace-match} does the replacement by constructing and
1031 returning a new string.
1033 If @var{fixedcase} is non-@code{nil}, then the case of the replacement
1034 text is not changed; otherwise, the replacement text is converted to a
1035 different case depending upon the capitalization of the text to be
1036 replaced. If the original text is all upper case, the replacement text
1037 is converted to upper case. If the first word of the original text is
1038 capitalized, then the first word of the replacement text is capitalized.
1039 If the original text contains just one word, and that word is a capital
1040 letter, @code{replace-match} considers this a capitalized first word
1041 rather than all upper case.
1043 If @code{case-replace} is @code{nil}, then case conversion is not done,
1044 regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
1046 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1047 exactly as it is, the only alterations being case changes as needed.
1048 If it is @code{nil} (the default), then the character @samp{\} is treated
1049 specially. If a @samp{\} appears in @var{replacement}, then it must be
1050 part of one of the following sequences:
1054 @cindex @samp{&} in replacement
1055 @samp{\&} stands for the entire text being replaced.
1057 @item @samp{\@var{n}}
1058 @cindex @samp{\@var{n}} in replacement
1059 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1060 matched the @var{n}th subexpression in the original regexp.
1061 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1064 @cindex @samp{\} in replacement
1065 @samp{\\} stands for a single @samp{\} in the replacement text.
1068 If @var{subexp} is non-@code{nil}, that says to replace just
1069 subexpression number @var{subexp} of the regexp that was matched, not
1070 the entire match. For example, after matching @samp{foo \(ba*r\)},
1071 calling @code{replace-match} with 1 as @var{subexp} means to replace
1072 just the text that matched @samp{\(ba*r\)}.
1075 @node Simple Match Data
1076 @subsection Simple Match Data Access
1078 This section explains how to use the match data to find out what was
1079 matched by the last search or match operation.
1081 You can ask about the entire matching text, or about a particular
1082 parenthetical subexpression of a regular expression. The @var{count}
1083 argument in the functions below specifies which. If @var{count} is
1084 zero, you are asking about the entire match. If @var{count} is
1085 positive, it specifies which subexpression you want.
1087 Recall that the subexpressions of a regular expression are those
1088 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1089 @var{count}th subexpression is found by counting occurrences of
1090 @samp{\(} from the beginning of the whole regular expression. The first
1091 subexpression is numbered 1, the second 2, and so on. Only regular
1092 expressions can have subexpressions---after a simple string search, the
1093 only information available is about the entire match.
1095 A search which fails may or may not alter the match data. In the
1096 past, a failing search did not do this, but we may change it in the
1099 @defun match-string count &optional in-string
1100 This function returns, as a string, the text matched in the last search
1101 or match operation. It returns the entire text if @var{count} is zero,
1102 or just the portion corresponding to the @var{count}th parenthetical
1103 subexpression, if @var{count} is positive. If @var{count} is out of
1104 range, or if that subexpression didn't match anything, the value is
1107 If the last such operation was done against a string with
1108 @code{string-match}, then you should pass the same string as the
1109 argument @var{in-string}. After a buffer search or match,
1110 you should omit @var{in-string} or pass @code{nil} for it; but you
1111 should make sure that the current buffer when you call
1112 @code{match-string} is the one in which you did the searching or
1116 @defun match-string-no-properties count
1117 This function is like @code{match-string} except that the result
1118 has no text properties.
1121 @defun match-beginning count
1122 This function returns the position of the start of text matched by the
1123 last regular expression searched for, or a subexpression of it.
1125 If @var{count} is zero, then the value is the position of the start of
1126 the entire match. Otherwise, @var{count} specifies a subexpression in
1127 the regular expression, and the value of the function is the starting
1128 position of the match for that subexpression.
1130 The value is @code{nil} for a subexpression inside a @samp{\|}
1131 alternative that wasn't used in the match.
1134 @defun match-end count
1135 This function is like @code{match-beginning} except that it returns the
1136 position of the end of the match, rather than the position of the
1140 Here is an example of using the match data, with a comment showing the
1141 positions within the text:
1145 (string-match "\\(qu\\)\\(ick\\)"
1146 "The quick fox jumped quickly.")
1152 (match-string 0 "The quick fox jumped quickly.")
1154 (match-string 1 "The quick fox jumped quickly.")
1156 (match-string 2 "The quick fox jumped quickly.")
1161 (match-beginning 1) ; @r{The beginning of the match}
1162 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1166 (match-beginning 2) ; @r{The beginning of the match}
1167 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1171 (match-end 1) ; @r{The end of the match}
1172 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1174 (match-end 2) ; @r{The end of the match}
1175 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1179 Here is another example. Point is initially located at the beginning
1180 of the line. Searching moves point to between the space and the word
1181 @samp{in}. The beginning of the entire match is at the 9th character of
1182 the buffer (@samp{T}), and the beginning of the match for the first
1183 subexpression is at the 13th character (@samp{c}).
1188 (re-search-forward "The \\(cat \\)")
1190 (match-beginning 1))
1195 ---------- Buffer: foo ----------
1196 I read "The cat @point{}in the hat comes back" twice.
1199 ---------- Buffer: foo ----------
1204 (In this case, the index returned is a buffer position; the first
1205 character of the buffer counts as 1.)
1207 @node Entire Match Data
1208 @subsection Accessing the Entire Match Data
1210 The functions @code{match-data} and @code{set-match-data} read or
1211 write the entire match data, all at once.
1214 This function returns a newly constructed list containing all the
1215 information on what text the last search matched. Element zero is the
1216 position of the beginning of the match for the whole expression; element
1217 one is the position of the end of the match for the expression. The
1218 next two elements are the positions of the beginning and end of the
1219 match for the first subexpression, and so on. In general, element
1224 number {\mathsurround=0pt $2n$}
1226 corresponds to @code{(match-beginning @var{n})}; and
1232 number {\mathsurround=0pt $2n+1$}
1234 corresponds to @code{(match-end @var{n})}.
1236 All the elements are markers or @code{nil} if matching was done on a
1237 buffer, and all are integers or @code{nil} if matching was done on a
1238 string with @code{string-match}.
1240 As always, there must be no possibility of intervening searches between
1241 the call to a search function and the call to @code{match-data} that is
1242 intended to access the match data for that search.
1247 @result{} (#<marker at 9 in foo>
1248 #<marker at 17 in foo>
1249 #<marker at 13 in foo>
1250 #<marker at 17 in foo>)
1255 @defun set-match-data match-list
1256 This function sets the match data from the elements of @var{match-list},
1257 which should be a list that was the value of a previous call to
1260 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1261 an error; that sets the match data in a meaningless but harmless way.
1263 @findex store-match-data
1264 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1267 @node Saving Match Data
1268 @subsection Saving and Restoring the Match Data
1270 When you call a function that may do a search, you may need to save
1271 and restore the match data around that call, if you want to preserve the
1272 match data from an earlier search for later use. Here is an example
1273 that shows the problem that arises if you fail to save the match data:
1277 (re-search-forward "The \\(cat \\)")
1279 (foo) ; @r{Perhaps @code{foo} does}
1280 ; @r{more searching.}
1282 @result{} 61 ; @r{Unexpected result---not 48!}
1286 You can save and restore the match data with @code{save-match-data}:
1288 @defmac save-match-data body@dots{}
1289 This special form executes @var{body}, saving and restoring the match
1293 You could use @code{set-match-data} together with @code{match-data} to
1294 imitate the effect of the special form @code{save-match-data}. Here is
1299 (let ((data (match-data)))
1301 @dots{} ; @r{Ok to change the original match data.}
1302 (set-match-data data)))
1306 Emacs automatically saves and restores the match data when it runs
1307 process filter functions (@pxref{Filter Functions}) and process
1308 sentinels (@pxref{Sentinels}).
1311 Here is a function which restores the match data provided the buffer
1312 associated with it still exists.
1316 (defun restore-match-data (data)
1317 @c It is incorrect to split the first line of a doc string.
1318 @c If there's a problem here, it should be solved in some other way.
1319 "Restore the match data DATA unless the buffer is missing."
1325 (null (marker-buffer (car d)))
1327 ;; @file{match-data} @r{buffer is deleted.}
1330 (set-match-data data))))
1335 @node Searching and Case
1336 @section Searching and Case
1337 @cindex searching and case
1339 By default, searches in Emacs ignore the case of the text they are
1340 searching through; if you specify searching for @samp{FOO}, then
1341 @samp{Foo} or @samp{foo} is also considered a match. This applies to
1342 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
1343 @samp{A} or @samp{b} or @samp{B}.
1345 If you do not want this feature, set the variable
1346 @code{case-fold-search} to @code{nil}. Then all letters must match
1347 exactly, including case. This is a buffer-local variable; altering the
1348 variable affects only the current buffer. (@xref{Intro to
1349 Buffer-Local}.) Alternatively, you may change the value of
1350 @code{default-case-fold-search}, which is the default value of
1351 @code{case-fold-search} for buffers that do not override it.
1353 Note that the user-level incremental search feature handles case
1354 distinctions differently. When given a lower case letter, it looks for
1355 a match of either case, but when given an upper case letter, it looks
1356 for an upper case letter only. But this has nothing to do with the
1357 searching functions used in Lisp code.
1359 @defopt case-replace
1360 This variable determines whether the replacement functions should
1361 preserve case. If the variable is @code{nil}, that means to use the
1362 replacement text verbatim. A non-@code{nil} value means to convert the
1363 case of the replacement text according to the text being replaced.
1365 The function @code{replace-match} is where this variable actually has
1366 its effect. @xref{Replacing Match}.
1369 @defopt case-fold-search
1370 This buffer-local variable determines whether searches should ignore
1371 case. If the variable is @code{nil} they do not ignore case; otherwise
1372 they do ignore case.
1375 @defvar default-case-fold-search
1376 The value of this variable is the default value for
1377 @code{case-fold-search} in buffers that do not override it. This is the
1378 same as @code{(default-value 'case-fold-search)}.
1381 @node Standard Regexps
1382 @section Standard Regular Expressions Used in Editing
1383 @cindex regexps used standardly in editing
1384 @cindex standard regexps used in editing
1386 This section describes some variables that hold regular expressions
1387 used for certain purposes in editing:
1389 @defvar page-delimiter
1390 This is the regular expression describing line-beginnings that separate
1391 pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1392 @code{"^\C-l"}); this matches a line that starts with a formfeed
1396 The following two regular expressions should @emph{not} assume the
1397 match always starts at the beginning of a line; they should not use
1398 @samp{^} to anchor the match. Most often, the paragraph commands do
1399 check for a match only at the beginning of a line, which means that
1400 @samp{^} would be superfluous. When there is a nonzero left margin,
1401 they accept matches that start after the left margin. In that case, a
1402 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1403 where a left margin is never used.
1405 @defvar paragraph-separate
1406 This is the regular expression for recognizing the beginning of a line
1407 that separates paragraphs. (If you change this, you may have to
1408 change @code{paragraph-start} also.) The default value is
1409 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1410 spaces, tabs, and form feeds (after its left margin).
1413 @defvar paragraph-start
1414 This is the regular expression for recognizing the beginning of a line
1415 that starts @emph{or} separates paragraphs. The default value is
1416 @w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
1417 newline, or form feed (after its left margin).
1420 @defvar sentence-end
1421 This is the regular expression describing the end of a sentence. (All
1422 paragraph boundaries also end sentences, regardless.) The default value
1426 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
1429 This means a period, question mark or exclamation mark, followed
1430 optionally by a closing parenthetical character, followed by tabs,
1431 spaces or new lines.
1433 For a detailed explanation of this regular expression, see @ref{Regexp