2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 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, Text, 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 @deffn Command search-forward string &optional limit noerror repeat
42 This function searches forward from point for an exact match for
43 @var{string}. If successful, it sets point to the end of the occurrence
44 found, and returns the new value of point. If no match is found, the
45 value and side effects depend on @var{noerror} (see below).
48 In the following example, point is initially at the beginning of the
49 line. Then @code{(search-forward "fox")} moves point after the last
54 ---------- Buffer: foo ----------
55 @point{}The quick brown fox jumped over the lazy dog.
56 ---------- Buffer: foo ----------
60 (search-forward "fox")
63 ---------- Buffer: foo ----------
64 The quick brown fox@point{} jumped over the lazy dog.
65 ---------- Buffer: foo ----------
69 The argument @var{limit} specifies the upper bound to the search. (It
70 must be a position in the current buffer.) No match extending after
71 that position is accepted. If @var{limit} is omitted or @code{nil}, it
72 defaults to the end of the accessible portion of the buffer.
75 What happens when the search fails depends on the value of
76 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
77 error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
78 returns @code{nil} and does nothing. If @var{noerror} is neither
79 @code{nil} nor @code{t}, then @code{search-forward} moves point to the
80 upper bound and returns @code{nil}. (It would be more consistent now
81 to return the new position of point in that case, but some programs
82 may depend on a value of @code{nil}.)
84 If @var{repeat} is supplied (it must be a positive number), then the
85 search is repeated that many times (each time starting at the end of the
86 previous time's match). If these successive searches succeed, the
87 function succeeds, moving point and returning its new value. Otherwise
91 @deffn Command search-backward string &optional limit noerror repeat
92 This function searches backward from point for @var{string}. It is
93 just like @code{search-forward} except that it searches backwards and
94 leaves point at the beginning of the match.
97 @deffn Command word-search-forward string &optional limit noerror repeat
99 This function searches forward from point for a ``word'' match for
100 @var{string}. If it finds a match, it sets point to the end of the
101 match found, and returns the new value of point.
104 Word matching regards @var{string} as a sequence of words, disregarding
105 punctuation that separates them. It searches the buffer for the same
106 sequence of words. Each word must be distinct in the buffer (searching
107 for the word @samp{ball} does not match the word @samp{balls}), but the
108 details of punctuation and spacing are ignored (searching for @samp{ball
109 boy} does match @samp{ball. Boy!}).
111 In this example, point is initially at the beginning of the buffer; the
112 search leaves it between the @samp{y} and the @samp{!}.
116 ---------- Buffer: foo ----------
117 @point{}He said "Please! Find
119 ---------- Buffer: foo ----------
123 (word-search-forward "Please find the ball, boy.")
126 ---------- Buffer: foo ----------
127 He said "Please! Find
128 the ball boy@point{}!"
129 ---------- Buffer: foo ----------
133 If @var{limit} is non-@code{nil} (it must be a position in the current
134 buffer), then it is the upper bound to the search. The match found must
135 not extend after that position.
137 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
138 an error if the search fails. If @var{noerror} is @code{t}, then it
139 returns @code{nil} instead of signaling an error. If @var{noerror} is
140 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
141 end of the buffer) and returns @code{nil}.
143 If @var{repeat} is non-@code{nil}, then the search is repeated that many
144 times. Point is positioned at the end of the last match.
147 @deffn Command word-search-backward string &optional limit noerror repeat
148 This function searches backward from point for a word match to
149 @var{string}. This function is just like @code{word-search-forward}
150 except that it searches backward and normally leaves point at the
151 beginning of the match.
154 @node Regular Expressions
155 @section Regular Expressions
156 @cindex regular expression
159 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
160 denotes a (possibly infinite) set of strings. Searching for matches for
161 a regexp is a very powerful operation. This section explains how to write
162 regexps; the following section says how to search for them.
165 * Syntax of Regexps:: Rules for writing regular expressions.
166 * Regexp Example:: Illustrates regular expression syntax.
169 @node Syntax of Regexps
170 @subsection Syntax of Regular Expressions
172 Regular expressions have a syntax in which a few characters are
173 special constructs and the rest are @dfn{ordinary}. An ordinary
174 character is a simple regular expression that matches that character and
175 nothing else. The special characters are @samp{.}, @samp{*}, @samp{+},
176 @samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
177 special characters will be defined in the future. Any other character
178 appearing in a regular expression is ordinary, unless a @samp{\}
181 For example, @samp{f} is not a special character, so it is ordinary, and
182 therefore @samp{f} is a regular expression that matches the string
183 @samp{f} and no other string. (It does @emph{not} match the string
184 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches
185 only @samp{o}.@refill
187 Any two regular expressions @var{a} and @var{b} can be concatenated. The
188 result is a regular expression that matches a string if @var{a} matches
189 some amount of the beginning of that string and @var{b} matches the rest of
192 As a simple example, we can concatenate the regular expressions @samp{f}
193 and @samp{o} to get the regular expression @samp{fo}, which matches only
194 the string @samp{fo}. Still trivial. To do something more powerful, you
195 need to use one of the special characters. Here is a list of them:
199 @item .@: @r{(Period)}
200 @cindex @samp{.} in regexp
201 is a special character that matches any single character except a newline.
202 Using concatenation, we can make regular expressions like @samp{a.b}, which
203 matches any three-character string that begins with @samp{a} and ends with
207 @cindex @samp{*} in regexp
208 is not a construct by itself; it is a suffix operator that means to
209 repeat the preceding regular expression as many times as possible. In
210 @samp{fo*}, the @samp{*} applies to the @samp{o}, so @samp{fo*} matches
211 one @samp{f} followed by any number of @samp{o}s. The case of zero
212 @samp{o}s is allowed: @samp{fo*} does match @samp{f}.@refill
214 @samp{*} always applies to the @emph{smallest} possible preceding
215 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
216 repeating @samp{fo}.@refill
218 The matcher processes a @samp{*} construct by matching, immediately,
219 as many repetitions as can be found. Then it continues with the rest
220 of the pattern. If that fails, backtracking occurs, discarding some
221 of the matches of the @samp{*}-modified construct in case that makes
222 it possible to match the rest of the pattern. For example, in matching
223 @samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
224 tries to match all three @samp{a}s; but the rest of the pattern is
225 @samp{ar} and there is only @samp{r} left to match, so this try fails.
226 The next alternative is for @samp{a*} to match only two @samp{a}s.
227 With this choice, the rest of the regexp matches successfully.@refill
229 Nested repetition operators can be extremely slow if they specify
230 backtracking loops. For example, it could take hours for the regular
231 expression @samp{\(x+y*\)*a} to match the sequence
232 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because
233 Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
234 concluding that none of them can work. To make sure your regular
235 expressions run fast, check nested repetitions carefully.
238 @cindex @samp{+} in regexp
239 is a suffix operator similar to @samp{*} except that the preceding
240 expression must match at least once. So, for example, @samp{ca+r}
241 matches the strings @samp{car} and @samp{caaaar} but not the string
242 @samp{cr}, whereas @samp{ca*r} matches all three strings.
245 @cindex @samp{?} in regexp
246 is a suffix operator similar to @samp{*} except that the preceding
247 expression can match either once or not at all. For example,
248 @samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anyhing
252 @cindex character set (in regexp)
253 @cindex @samp{[} in regexp
254 @cindex @samp{]} in regexp
255 @samp{[} begins a @dfn{character set}, which is terminated by a
256 @samp{]}. In the simplest case, the characters between the two brackets
257 form the set. Thus, @samp{[ad]} matches either one @samp{a} or one
258 @samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}s
259 and @samp{d}s (including the empty string), from which it follows that
260 @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
261 @samp{caddaar}, etc.@refill
263 The usual regular expression special characters are not special inside a
264 character set. A completely different set of special characters exists
265 inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
267 @samp{-} is used for ranges of characters. To write a range, write two
268 characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any
269 lower case letter. Ranges may be intermixed freely with individual
270 characters, as in @samp{[a-z$%.]}, which matches any lower case letter
271 or @samp{$}, @samp{%}, or a period.@refill
273 To include a @samp{]} in a character set, make it the first character.
274 For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a
275 @samp{-}, write @samp{-} as the first character in the set, or put it
276 immediately after a range. (You can replace one individual character
277 @var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the
278 @samp{-}.) There is no way to write a set containing just @samp{-} and
281 To include @samp{^} in a set, put it anywhere but at the beginning of
285 @cindex @samp{^} in regexp
286 @samp{[^} begins a @dfn{complement character set}, which matches any
287 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
288 matches all characters @emph{except} letters and digits.@refill
290 @samp{^} is not special in a character set unless it is the first
291 character. The character following the @samp{^} is treated as if it
292 were first (thus, @samp{-} and @samp{]} are not special there).
294 Note that a complement character set can match a newline, unless
295 newline is mentioned as one of the characters not to match.
298 @cindex @samp{^} in regexp
299 @cindex beginning of line in regexp
300 is a special character that matches the empty string, but only at the
301 beginning of a line in the text being matched. Otherwise it fails to
302 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
303 the beginning of a line.
305 When matching a string instead of a buffer, @samp{^} matches at the
306 beginning of the string or after a newline character @samp{\n}.
309 @cindex @samp{$} in regexp
310 is similar to @samp{^} but matches only at the end of a line. Thus,
311 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
313 When matching a string instead of a buffer, @samp{$} matches at the end
314 of the string or before a newline character @samp{\n}.
317 @cindex @samp{\} in regexp
318 has two functions: it quotes the special characters (including
319 @samp{\}), and it introduces additional special constructs.
321 Because @samp{\} quotes special characters, @samp{\$} is a regular
322 expression that matches only @samp{$}, and @samp{\[} is a regular
323 expression that matches only @samp{[}, and so on.
325 Note that @samp{\} also has special meaning in the read syntax of Lisp
326 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
327 example, the regular expression that matches the @samp{\} character is
328 @samp{\\}. To write a Lisp string that contains the characters
329 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
330 @samp{\}. Therefore, the read syntax for a regular expression matching
331 @samp{\} is @code{"\\\\"}.@refill
334 @strong{Please note:} For historical compatibility, special characters
335 are treated as ordinary ones if they are in contexts where their special
336 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
337 ordinary since there is no preceding expression on which the @samp{*}
338 can act. It is poor practice to depend on this behavior; quote the
339 special character anyway, regardless of where it appears.@refill
341 For the most part, @samp{\} followed by any character matches only
342 that character. However, there are several exceptions: characters
343 that, when preceded by @samp{\}, are special constructs. Such
344 characters are always ordinary when encountered on their own. Here
345 is a table of @samp{\} constructs:
349 @cindex @samp{|} in regexp
350 @cindex regexp alternative
351 specifies an alternative.
352 Two regular expressions @var{a} and @var{b} with @samp{\|} in
353 between form an expression that matches anything that either @var{a} or
354 @var{b} matches.@refill
356 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
357 but no other string.@refill
359 @samp{\|} applies to the largest possible surrounding expressions. Only a
360 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
363 Full backtracking capability exists to handle multiple uses of @samp{\|}.
366 @cindex @samp{(} in regexp
367 @cindex @samp{)} in regexp
368 @cindex regexp grouping
369 is a grouping construct that serves three purposes:
373 To enclose a set of @samp{\|} alternatives for other operations. Thus,
374 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
378 To enclose an expression for a suffix operator such as @samp{*} to act
379 on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any
380 (zero or more) number of @samp{na} strings.@refill
383 To record a matched substring for future reference.
386 This last application is not a consequence of the idea of a
387 parenthetical grouping; it is a separate feature that happens to be
388 assigned as a second meaning to the same @samp{\( @dots{} \)} construct
389 because there is no conflict in practice between the two meanings.
390 Here is an explanation of this feature:
393 matches the same text that matched the @var{digit}th occurrence of a
394 @samp{\( @dots{} \)} construct.
396 In other words, after the end of a @samp{\( @dots{} \)} construct. the
397 matcher remembers the beginning and end of the text matched by that
398 construct. Then, later on in the regular expression, you can use
399 @samp{\} followed by @var{digit} to match that same text, whatever it
402 The strings matching the first nine @samp{\( @dots{} \)} constructs
403 appearing in a regular expression are assigned numbers 1 through 9 in
404 the order that the open parentheses appear in the regular expression.
405 So you can use @samp{\1} through @samp{\9} to refer to the text matched
406 by the corresponding @samp{\( @dots{} \)} constructs.
408 For example, @samp{\(.*\)\1} matches any newline-free string that is
409 composed of two identical halves. The @samp{\(.*\)} matches the first
410 half, which may be anything, but the @samp{\1} that follows must match
414 @cindex @samp{\w} in regexp
415 matches any word-constituent character. The editor syntax table
416 determines which characters these are. @xref{Syntax Tables}.
419 @cindex @samp{\W} in regexp
420 matches any character that is not a word constituent.
423 @cindex @samp{\s} in regexp
424 matches any character whose syntax is @var{code}. Here @var{code} is a
425 character that represents a syntax code: thus, @samp{w} for word
426 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
427 etc. @xref{Syntax Tables}, for a list of syntax codes and the
428 characters that stand for them.
431 @cindex @samp{\S} in regexp
432 matches any character whose syntax is not @var{code}.
435 The following regular expression constructs match the empty string---that is,
436 they don't use up any characters---but whether they match depends on the
441 @cindex @samp{\`} in regexp
442 matches the empty string, but only at the beginning
443 of the buffer or string being matched against.
446 @cindex @samp{\'} in regexp
447 matches the empty string, but only at the end of
448 the buffer or string being matched against.
451 @cindex @samp{\=} in regexp
452 matches the empty string, but only at point.
453 (This construct is not defined when matching against a string.)
456 @cindex @samp{\b} in regexp
457 matches the empty string, but only at the beginning or
458 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
459 @samp{foo} as a separate word. @samp{\bballs?\b} matches
460 @samp{ball} or @samp{balls} as a separate word.@refill
463 @cindex @samp{\B} in regexp
464 matches the empty string, but @emph{not} at the beginning or
468 @cindex @samp{\<} in regexp
469 matches the empty string, but only at the beginning of a word.
472 @cindex @samp{\>} in regexp
473 matches the empty string, but only at the end of a word.
476 @kindex invalid-regexp
477 Not every string is a valid regular expression. For example, a string
478 with unbalanced square brackets is invalid (with a few exceptions, such
479 as @samp{[]]}), and so is a string that ends with a single @samp{\}. If
480 an invalid regular expression is passed to any of the search functions,
481 an @code{invalid-regexp} error is signaled.
483 @defun regexp-quote string
484 This function returns a regular expression string that matches exactly
485 @var{string} and nothing else. This allows you to request an exact
486 string match when calling a function that wants a regular expression.
490 (regexp-quote "^The cat$")
491 @result{} "\\^The cat\\$"
495 One use of @code{regexp-quote} is to combine an exact string match with
496 context described as a regular expression. For example, this searches
497 for the string that is the value of @code{string}, surrounded by
503 (concat "\\s-" (regexp-quote string) "\\s-"))
509 @comment node-name, next, previous, up
510 @subsection Complex Regexp Example
512 Here is a complicated regexp, used by Emacs to recognize the end of a
513 sentence together with any whitespace that follows. It is the value of
514 the variable @code{sentence-end}.
516 First, we show the regexp as a string in Lisp syntax to distinguish
517 spaces from tab characters. The string constant begins and ends with a
518 double-quote. @samp{\"} stands for a double-quote as part of the
519 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
520 tab and @samp{\n} for a newline.
523 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
526 In contrast, if you evaluate the variable @code{sentence-end}, you
527 will see the following:
533 "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
539 In this output, tab and newline appear as themselves.
541 This regular expression contains four parts in succession and can be
542 deciphered as follows:
546 The first part of the pattern is a character set that matches any one of
547 three characters: period, question mark, and exclamation mark. The
548 match must begin with one of these three characters.
551 The second part of the pattern matches any closing braces and quotation
552 marks, zero or more of them, that may follow the period, question mark
553 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
554 a string. The @samp{*} at the end indicates that the immediately
555 preceding regular expression (a character set, in this case) may be
556 repeated zero or more times.
558 @item \\($\\|@ $\\|\t\\|@ @ \\)
559 The third part of the pattern matches the whitespace that follows the
560 end of a sentence: the end of a line, or a tab, or two spaces. The
561 double backslashes mark the parentheses and vertical bars as regular
562 expression syntax; the parentheses delimit a group and the vertical bars
563 separate alternatives. The dollar sign is used to match the end of a
567 Finally, the last part of the pattern matches any additional whitespace
568 beyond the minimum needed to end a sentence.
572 @section Regular Expression Searching
573 @cindex regular expression searching
574 @cindex regexp searching
575 @cindex searching for regexp
577 In GNU Emacs, you can search for the next match for a regexp either
578 incrementally or not. For incremental search commands, see @ref{Regexp
579 Search, , Regular Expression Search, emacs, The GNU Emacs Manual}. Here
580 we describe only the search functions useful in programs. The principal
581 one is @code{re-search-forward}.
583 @deffn Command re-search-forward regexp &optional limit noerror repeat
584 This function searches forward in the current buffer for a string of
585 text that is matched by the regular expression @var{regexp}. The
586 function skips over any amount of text that is not matched by
587 @var{regexp}, and leaves point at the end of the first match found.
588 It returns the new value of point.
590 If @var{limit} is non-@code{nil} (it must be a position in the current
591 buffer), then it is the upper bound to the search. No match extending
592 after that position is accepted.
594 What happens when the search fails depends on the value of
595 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
596 error is signaled. If @var{noerror} is @code{t},
597 @code{re-search-forward} does nothing and returns @code{nil}. If
598 @var{noerror} is neither @code{nil} nor @code{t}, then
599 @code{re-search-forward} moves point to @var{limit} (or the end of the
600 buffer) and returns @code{nil}.
602 If @var{repeat} is supplied (it must be a positive number), then the
603 search is repeated that many times (each time starting at the end of the
604 previous time's match). If these successive searches succeed, the
605 function succeeds, moving point and returning its new value. Otherwise
608 In the following example, point is initially before the @samp{T}.
609 Evaluating the search call moves point to the end of that line (between
610 the @samp{t} of @samp{hat} and the newline).
614 ---------- Buffer: foo ----------
615 I read "@point{}The cat in the hat
617 ---------- Buffer: foo ----------
621 (re-search-forward "[a-z]+" nil t 5)
624 ---------- Buffer: foo ----------
625 I read "The cat in the hat@point{}
627 ---------- Buffer: foo ----------
632 @deffn Command re-search-backward regexp &optional limit noerror repeat
633 This function searches backward in the current buffer for a string of
634 text that is matched by the regular expression @var{regexp}, leaving
635 point at the beginning of the first text found.
637 This function is analogous to @code{re-search-forward}, but they are not
638 simple mirror images. @code{re-search-forward} finds the match whose
639 beginning is as close as possible to the starting point. If
640 @code{re-search-backward} were a perfect mirror image, it would find the
641 match whose end is as close as possible. However, in fact it finds the
642 match whose beginning is as close as possible. The reason is that
643 matching a regular expression at a given spot always works from
644 beginning to end, and starts at a specified beginning position.
646 A true mirror-image of @code{re-search-forward} would require a special
647 feature for matching regexps from end to beginning. It's not worth the
648 trouble of implementing that.
651 @defun string-match regexp string &optional start
652 This function returns the index of the start of the first match for
653 the regular expression @var{regexp} in @var{string}, or @code{nil} if
654 there is no match. If @var{start} is non-@code{nil}, the search starts
655 at that index in @var{string}.
662 "quick" "The quick brown fox jumped quickly.")
667 "quick" "The quick brown fox jumped quickly." 8)
673 The index of the first character of the
674 string is 0, the index of the second character is 1, and so on.
676 After this function returns, the index of the first character beyond
677 the match is available as @code{(match-end 0)}. @xref{Match Data}.
682 "quick" "The quick brown fox jumped quickly." 8)
693 @defun looking-at regexp
694 This function determines whether the text in the current buffer directly
695 following point matches the regular expression @var{regexp}. ``Directly
696 following'' means precisely that: the search is ``anchored'' and it can
697 succeed only starting with the first character following point. The
698 result is @code{t} if so, @code{nil} otherwise.
700 This function does not move point, but it updates the match data, which
701 you can access using @code{match-beginning} and @code{match-end}.
704 In this example, point is located directly before the @samp{T}. If it
705 were anywhere else, the result would be @code{nil}.
709 ---------- Buffer: foo ----------
710 I read "@point{}The cat in the hat
712 ---------- Buffer: foo ----------
714 (looking-at "The cat in the hat$")
721 @section POSIX Regular Expression Searching
723 The usual regular expression functions do backtracking when necessary
724 to handle the @samp{\|} and repetition constructs, but they continue
725 this only until they find @emph{some} match. Then they succeed and
726 report the first match found.
728 This section describes alternative search functions which perform the
729 full backtracking specified by the POSIX standard for regular expression
730 matching. They continue backtracking until they have tried all
731 possibilities and found all matches, so they can report the longest
732 match, as required by POSIX. This is much slower, so use these
733 functions only when you really need the longest match.
735 In Emacs versions prior to 19.29, these functions did not exist, and
736 the functions described above implemented full POSIX backtracking.
738 @defun posix-search-forward regexp &optional limit noerror repeat
739 This is like @code{re-search-forward} except that it performs the full
740 backtracking specified by the POSIX standard for regular expression
744 @defun posix-search-backward regexp &optional limit noerror repeat
745 This is like @code{re-search-backward} except that it performs the full
746 backtracking specified by the POSIX standard for regular expression
750 @defun posix-looking-at regexp
751 This is like @code{looking-at} except that it performs the full
752 backtracking specified by the POSIX standard for regular expression
756 @defun posix-string-match regexp string &optional start
757 This is like @code{string-match} except that it performs the full
758 backtracking specified by the POSIX standard for regular expression
763 @deffn Command delete-matching-lines regexp
764 This function is identical to @code{delete-non-matching-lines}, save
765 that it deletes what @code{delete-non-matching-lines} keeps.
767 In the example below, point is located on the first line of text.
771 ---------- Buffer: foo ----------
774 that all men are created
775 equal, and that they are
776 ---------- Buffer: foo ----------
780 (delete-matching-lines "the")
783 ---------- Buffer: foo ----------
785 that all men are created
786 ---------- Buffer: foo ----------
791 @deffn Command flush-lines regexp
792 This function is the same as @code{delete-matching-lines}.
795 @defun delete-non-matching-lines regexp
796 This function deletes all lines following point which don't
797 contain a match for the regular expression @var{regexp}.
800 @deffn Command keep-lines regexp
801 This function is the same as @code{delete-non-matching-lines}.
804 @deffn Command how-many regexp
805 This function counts the number of matches for @var{regexp} there are in
806 the current buffer following point. It prints this number in
807 the echo area, returning the string printed.
810 @deffn Command count-matches regexp
811 This function is a synonym of @code{how-many}.
814 @deffn Command list-matching-lines regexp nlines
815 This function is a synonym of @code{occur}.
816 Show all lines following point containing a match for @var{regexp}.
817 Display each line with @var{nlines} lines before and after,
818 or @code{-}@var{nlines} before if @var{nlines} is negative.
819 @var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
820 Interactively it is the prefix arg.
822 The lines are shown in a buffer named @samp{*Occur*}.
823 It serves as a menu to find any of the occurrences in this buffer.
824 @kbd{C-h m} (@code{describe-mode} in that buffer gives help.
827 @defopt list-matching-lines-default-context-lines
829 Default number of context lines to include around a @code{list-matching-lines}
830 match. A negative number means to include that many lines before the match.
831 A positive number means to include that many lines both before and after.
835 @node Search and Replace
836 @section Search and Replace
839 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
840 This function is the guts of @code{query-replace} and related commands.
841 It searches for occurrences of @var{from-string} and replaces some or
842 all of them. If @var{query-flag} is @code{nil}, it replaces all
843 occurrences; otherwise, it asks the user what to do about each one.
845 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
846 considered a regular expression; otherwise, it must match literally. If
847 @var{delimited-flag} is non-@code{nil}, then only replacements
848 surrounded by word boundaries are considered.
850 The argument @var{replacements} specifies what to replace occurrences
851 with. If it is a string, that string is used. It can also be a list of
852 strings, to be used in cyclic order.
854 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
855 it specifies how many times to use each of the strings in the
856 @var{replacements} list before advancing cyclicly to the next one.
858 Normally, the keymap @code{query-replace-map} defines the possible user
859 responses for queries. The argument @var{map}, if non-@code{nil}, is a
860 keymap to use instead of @code{query-replace-map}.
863 @defvar query-replace-map
864 This variable holds a special keymap that defines the valid user
865 responses for @code{query-replace} and related functions, as well as
866 @code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways:
870 The ``key bindings'' are not commands, just symbols that are meaningful
871 to the functions that use this map.
874 Prefix keys are not supported; each key binding must be for a single event
875 key sequence. This is because the functions don't use read key sequence to
876 get the input; instead, they read a single event and look it up ``by hand.''
880 Here are the meaningful ``bindings'' for @code{query-replace-map}.
881 Several of them are meaningful only for @code{query-replace} and
886 Do take the action being considered---in other words, ``yes.''
889 Do not take action for this question---in other words, ``no.''
892 Answer this question ``no,'' and give up on the entire series of
893 questions, assuming that the answers will be ``no.''
896 Answer this question ``yes,'' and give up on the entire series of
897 questions, assuming that subsequent answers will be ``no.''
900 Answer this question ``yes,'' but show the results---don't advance yet
901 to the next question.
904 Answer this question and all subsequent questions in the series with
905 ``yes,'' without further user interaction.
908 Move back to the previous place that a question was asked about.
911 Enter a recursive edit to deal with this question---instead of any
912 other action that would normally be taken.
914 @item delete-and-edit
915 Delete the text being considered, then enter a recursive edit to replace
919 Redisplay and center the window, then ask the same question again.
922 Perform a quit right away. Only @code{y-or-n-p} and related functions
926 Display some help, then ask again.
930 @section The Match Data
933 Emacs keeps track of the positions of the start and end of segments of
934 text found during a regular expression search. This means, for example,
935 that you can search for a complex pattern, such as a date in an Rmail
936 message, and then extract parts of the match under control of the
939 Because the match data normally describe the most recent search only,
940 you must be careful not to do another search inadvertently between the
941 search you wish to refer back to and the use of the match data. If you
942 can't avoid another intervening search, you must save and restore the
943 match data around it, to prevent it from being overwritten.
946 * Simple Match Data:: Accessing single items of match data,
947 such as where a particular subexpression started.
948 * Replacing Match:: Replacing a substring that was matched.
949 * Entire Match Data:: Accessing the entire match data at once, as a list.
950 * Saving Match Data:: Saving and restoring the match data.
953 @node Simple Match Data
954 @subsection Simple Match Data Access
956 This section explains how to use the match data to find out what was
957 matched by the last search or match operation.
959 You can ask about the entire matching text, or about a particular
960 parenthetical subexpression of a regular expression. The @var{count}
961 argument in the functions below specifies which. If @var{count} is
962 zero, you are asking about the entire match. If @var{count} is
963 positive, it specifies which subexpression you want.
965 Recall that the subexpressions of a regular expression are those
966 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
967 @var{count}th subexpression is found by counting occurrences of
968 @samp{\(} from the beginning of the whole regular expression. The first
969 subexpression is numbered 1, the second 2, and so on. Only regular
970 expressions can have subexpressions---after a simple string search, the
971 only information available is about the entire match.
973 @defun match-string count &optional in-string
974 This function returns, as a string, the text matched in the last search
975 or match operation. It returns the entire text if @var{count} is zero,
976 or just the portion corresponding to the @var{count}th parenthetical
977 subexpression, if @var{count} is positive. If @var{count} is out of
978 range, or if that subexpression didn't match anything, the value is
981 If the last such operation was done against a string with
982 @code{string-match}, then you should pass the same string as the
983 argument @var{in-string}. Otherwise, after a buffer search or match,
984 you should omit @var{in-string} or pass @code{nil} for it; but you
985 should make sure that the current buffer when you call
986 @code{match-string} is the one in which you did the searching or
990 @defun match-beginning count
991 This function returns the position of the start of text matched by the
992 last regular expression searched for, or a subexpression of it.
994 If @var{count} is zero, then the value is the position of the start of
995 the entire match. Otherwise, @var{count} specifies a subexpression in
996 the regular expresion, and the value of the function is the starting
997 position of the match for that subexpression.
999 The value is @code{nil} for a subexpression inside a @samp{\|}
1000 alternative that wasn't used in the match.
1003 @defun match-end count
1004 This function is like @code{match-beginning} except that it returns the
1005 position of the end of the match, rather than the position of the
1009 Here is an example of using the match data, with a comment showing the
1010 positions within the text:
1014 (string-match "\\(qu\\)\\(ick\\)"
1015 "The quick fox jumped quickly.")
1021 (match-string 0 "The quick fox jumped quickly.")
1023 (match-string 1 "The quick fox jumped quickly.")
1025 (match-string 2 "The quick fox jumped quickly.")
1030 (match-beginning 1) ; @r{The beginning of the match}
1031 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1035 (match-beginning 2) ; @r{The beginning of the match}
1036 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1040 (match-end 1) ; @r{The end of the match}
1041 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1043 (match-end 2) ; @r{The end of the match}
1044 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1048 Here is another example. Point is initially located at the beginning
1049 of the line. Searching moves point to between the space and the word
1050 @samp{in}. The beginning of the entire match is at the 9th character of
1051 the buffer (@samp{T}), and the beginning of the match for the first
1052 subexpression is at the 13th character (@samp{c}).
1057 (re-search-forward "The \\(cat \\)")
1059 (match-beginning 1))
1064 ---------- Buffer: foo ----------
1065 I read "The cat @point{}in the hat comes back" twice.
1068 ---------- Buffer: foo ----------
1073 (In this case, the index returned is a buffer position; the first
1074 character of the buffer counts as 1.)
1076 @node Replacing Match
1077 @subsection Replacing the Text That Matched
1079 This function replaces the text matched by the last search with
1082 @cindex case in replacements
1083 @defun replace-match replacement &optional fixedcase literal string subexp
1084 This function replaces the text in the buffer (or in @var{string}) that
1085 was matched by the last search. It replaces that text with
1088 If you did the last search in a buffer, you should specify @code{nil}
1089 for @var{string}. Then @code{replace-match} does the replacement by
1090 editing the buffer; it leaves point at the end of the replacement text,
1091 and returns @code{t}.
1093 If you did the search in a string, pass the same string as @var{string}.
1094 Then @code{replace-match} does the replacement by constructing and
1095 returning a new string.
1097 If @var{fixedcase} is non-@code{nil}, then the case of the replacement
1098 text is not changed; otherwise, the replacement text is converted to a
1099 different case depending upon the capitalization of the text to be
1100 replaced. If the original text is all upper case, the replacement text
1101 is converted to upper case. If the first word of the original text is
1102 capitalized, then the first word of the replacement text is capitalized.
1103 If the original text contains just one word, and that word is a capital
1104 letter, @code{replace-match} considers this a capitalized first word
1105 rather than all upper case.
1107 If @code{case-replace} is @code{nil}, then case conversion is not done,
1108 regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
1110 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1111 exactly as it is, the only alterations being case changes as needed.
1112 If it is @code{nil} (the default), then the character @samp{\} is treated
1113 specially. If a @samp{\} appears in @var{replacement}, then it must be
1114 part of one of the following sequences:
1118 @cindex @samp{&} in replacement
1119 @samp{\&} stands for the entire text being replaced.
1121 @item @samp{\@var{n}}
1122 @cindex @samp{\@var{n}} in replacement
1123 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1124 matched the @var{n}th subexpression in the original regexp.
1125 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1128 @cindex @samp{\} in replacement
1129 @samp{\\} stands for a single @samp{\} in the replacement text.
1132 If @var{subexp} is non-@code{nil}, that says to replace just
1133 subexpression number @var{subexp} of the regexp that was matched, not
1134 the entire match. For example, after matching @samp{foo \(ba*r\)},
1135 calling @code{replace-match} with 1 as @var{subexp} means to replace
1136 just the text that matched @samp{\(ba*r\)}.
1139 @node Entire Match Data
1140 @subsection Accessing the Entire Match Data
1142 The functions @code{match-data} and @code{set-match-data} read or
1143 write the entire match data, all at once.
1146 This function returns a newly constructed list containing all the
1147 information on what text the last search matched. Element zero is the
1148 position of the beginning of the match for the whole expression; element
1149 one is the position of the end of the match for the expression. The
1150 next two elements are the positions of the beginning and end of the
1151 match for the first subexpression, and so on. In general, element
1156 number {\mathsurround=0pt $2n$}
1158 corresponds to @code{(match-beginning @var{n})}; and
1164 number {\mathsurround=0pt $2n+1$}
1166 corresponds to @code{(match-end @var{n})}.
1168 All the elements are markers or @code{nil} if matching was done on a
1169 buffer, and all are integers or @code{nil} if matching was done on a
1170 string with @code{string-match}. (In Emacs 18 and earlier versions,
1171 markers were used even for matching on a string, except in the case
1174 As always, there must be no possibility of intervening searches between
1175 the call to a search function and the call to @code{match-data} that is
1176 intended to access the match data for that search.
1181 @result{} (#<marker at 9 in foo>
1182 #<marker at 17 in foo>
1183 #<marker at 13 in foo>
1184 #<marker at 17 in foo>)
1189 @defun set-match-data match-list
1190 This function sets the match data from the elements of @var{match-list},
1191 which should be a list that was the value of a previous call to
1194 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1195 an error; that sets the match data in a meaningless but harmless way.
1197 @findex store-match-data
1198 @code{store-match-data} is an alias for @code{set-match-data}.
1201 @node Saving Match Data
1202 @subsection Saving and Restoring the Match Data
1204 When you call a function that may do a search, you may need to save
1205 and restore the match data around that call, if you want to preserve the
1206 match data from an earlier search for later use. Here is an example
1207 that shows the problem that arises if you fail to save the match data:
1211 (re-search-forward "The \\(cat \\)")
1213 (foo) ; @r{Perhaps @code{foo} does}
1214 ; @r{more searching.}
1216 @result{} 61 ; @r{Unexpected result---not 48!}
1220 You can save and restore the match data with @code{save-match-data}:
1222 @defmac save-match-data body@dots{}
1223 This special form executes @var{body}, saving and restoring the match
1227 You can use @code{set-match-data} together with @code{match-data} to
1228 imitate the effect of the special form @code{save-match-data}. This is
1229 useful for writing code that can run in Emacs 18. Here is how:
1233 (let ((data (match-data)))
1235 @dots{} ; @r{May change the original match data.}
1236 (set-match-data data)))
1240 Emacs automatically saves and restores the match data when it runs
1241 process filter functions (@pxref{Filter Functions}) and process
1242 sentinels (@pxref{Sentinels}).
1245 Here is a function which restores the match data provided the buffer
1246 associated with it still exists.
1250 (defun restore-match-data (data)
1251 @c It is incorrect to split the first line of a doc string.
1252 @c If there's a problem here, it should be solved in some other way.
1253 "Restore the match data DATA unless the buffer is missing."
1259 (null (marker-buffer (car d)))
1261 ;; @file{match-data} @r{buffer is deleted.}
1264 (set-match-data data))))
1269 @node Searching and Case
1270 @section Searching and Case
1271 @cindex searching and case
1273 By default, searches in Emacs ignore the case of the text they are
1274 searching through; if you specify searching for @samp{FOO}, then
1275 @samp{Foo} or @samp{foo} is also considered a match. Regexps, and in
1276 particular character sets, are included: thus, @samp{[aB]} would match
1277 @samp{a} or @samp{A} or @samp{b} or @samp{B}.
1279 If you do not want this feature, set the variable
1280 @code{case-fold-search} to @code{nil}. Then all letters must match
1281 exactly, including case. This is a buffer-local variable; altering the
1282 variable affects only the current buffer. (@xref{Intro to
1283 Buffer-Local}.) Alternatively, you may change the value of
1284 @code{default-case-fold-search}, which is the default value of
1285 @code{case-fold-search} for buffers that do not override it.
1287 Note that the user-level incremental search feature handles case
1288 distinctions differently. When given a lower case letter, it looks for
1289 a match of either case, but when given an upper case letter, it looks
1290 for an upper case letter only. But this has nothing to do with the
1291 searching functions Lisp functions use.
1293 @defopt case-replace
1294 This variable determines whether the replacement functions should
1295 preserve case. If the variable is @code{nil}, that means to use the
1296 replacement text verbatim. A non-@code{nil} value means to convert the
1297 case of the replacement text according to the text being replaced.
1299 The function @code{replace-match} is where this variable actually has
1300 its effect. @xref{Replacing Match}.
1303 @defopt case-fold-search
1304 This buffer-local variable determines whether searches should ignore
1305 case. If the variable is @code{nil} they do not ignore case; otherwise
1306 they do ignore case.
1309 @defvar default-case-fold-search
1310 The value of this variable is the default value for
1311 @code{case-fold-search} in buffers that do not override it. This is the
1312 same as @code{(default-value 'case-fold-search)}.
1315 @node Standard Regexps
1316 @section Standard Regular Expressions Used in Editing
1317 @cindex regexps used standardly in editing
1318 @cindex standard regexps used in editing
1320 This section describes some variables that hold regular expressions
1321 used for certain purposes in editing:
1323 @defvar page-delimiter
1324 This is the regexp describing line-beginnings that separate pages. The
1325 default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
1326 this matches a line that starts with a formfeed character.
1329 The following two regular expressions should @emph{not} assume the
1330 match always starts at the beginning of a line; they should not use
1331 @samp{^} to anchor the match. Most often, the paragraph commands do
1332 check for a match only at the beginning of a line, which means that
1333 @samp{^} would be superfluous. When there is a nonzero left margin,
1334 they accept matches that start after the left margin. In that case, a
1335 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1336 where a left margin is never used.
1338 @defvar paragraph-separate
1339 This is the regular expression for recognizing the beginning of a line
1340 that separates paragraphs. (If you change this, you may have to
1341 change @code{paragraph-start} also.) The default value is
1342 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1343 spaces, tabs, and form feeds (after its left margin).
1346 @defvar paragraph-start
1347 This is the regular expression for recognizing the beginning of a line
1348 that starts @emph{or} separates paragraphs. The default value is
1349 @w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
1350 newline, or form feed (after its left margin).
1353 @defvar sentence-end
1354 This is the regular expression describing the end of a sentence. (All
1355 paragraph boundaries also end sentences, regardless.) The default value
1359 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
1362 This means a period, question mark or exclamation mark, followed
1363 optionally by a closing parenthetical character, followed by tabs,
1364 spaces or new lines.
1366 For a detailed explanation of this regular expression, see @ref{Regexp