2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/searching.info
6 @node Searching and Matching, Syntax Tables, Text, Top
7 @chapter Searching and Matching
10 XEmacs 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.
164 To gain a thorough understanding of regular expressions and how to use
165 them to best advantage, we recommend that you study @cite{Mastering
166 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates,
167 1997}. (It's known as the "Hip Owls" book, because of the picture on its
168 cover.) You might also read the manuals to @ref{(gawk)Top},
169 @ref{(ed)Top}, @cite{sed}, @cite{grep}, @ref{(perl)Top},
170 @ref{(regex)Top}, @ref{(rx)Top}, @cite{pcre}, and @ref{(flex)Top}, which
171 also make good use of regular expressions.
173 The XEmacs regular expression syntax most closely resembles that of
174 @cite{ed}, or @cite{grep}, the GNU versions of which all utilize the GNU
175 @cite{regex} library. XEmacs' version of @cite{regex} has recently been
176 extended with some Perl--like capabilities, described in the next
180 * Syntax of Regexps:: Rules for writing regular expressions.
181 * Regexp Example:: Illustrates regular expression syntax.
184 @node Syntax of Regexps
185 @subsection Syntax of Regular Expressions
187 Regular expressions have a syntax in which a few characters are
188 special constructs and the rest are @dfn{ordinary}. An ordinary
189 character is a simple regular expression that matches that character and
190 nothing else. The special characters are @samp{.}, @samp{*}, @samp{+},
191 @samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
192 special characters will be defined in the future. Any other character
193 appearing in a regular expression is ordinary, unless a @samp{\}
196 For example, @samp{f} is not a special character, so it is ordinary, and
197 therefore @samp{f} is a regular expression that matches the string
198 @samp{f} and no other string. (It does @emph{not} match the string
199 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches
200 only @samp{o}.@refill
202 Any two regular expressions @var{a} and @var{b} can be concatenated. The
203 result is a regular expression that matches a string if @var{a} matches
204 some amount of the beginning of that string and @var{b} matches the rest of
207 As a simple example, we can concatenate the regular expressions @samp{f}
208 and @samp{o} to get the regular expression @samp{fo}, which matches only
209 the string @samp{fo}. Still trivial. To do something more powerful, you
210 need to use one of the special characters. Here is a list of them:
214 @item .@: @r{(Period)}
215 @cindex @samp{.} in regexp
216 is a special character that matches any single character except a newline.
217 Using concatenation, we can make regular expressions like @samp{a.b}, which
218 matches any three-character string that begins with @samp{a} and ends with
222 @cindex @samp{*} in regexp
223 is not a construct by itself; it is a quantifying suffix operator that
224 means to repeat the preceding regular expression as many times as
225 possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so
226 @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s.
227 The case of zero @samp{o}s is allowed: @samp{fo*} does match
230 @samp{*} always applies to the @emph{smallest} possible preceding
231 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
232 repeating @samp{fo}.@refill
234 The matcher processes a @samp{*} construct by matching, immediately, as
235 many repetitions as can be found; it is "greedy". Then it continues
236 with the rest of the pattern. If that fails, backtracking occurs,
237 discarding some of the matches of the @samp{*}-modified construct in
238 case that makes it possible to match the rest of the pattern. For
239 example, in matching @samp{ca*ar} against the string @samp{caaar}, the
240 @samp{a*} first tries to match all three @samp{a}s; but the rest of the
241 pattern is @samp{ar} and there is only @samp{r} left to match, so this
242 try fails. The next alternative is for @samp{a*} to match only two
243 @samp{a}s. With this choice, the rest of the regexp matches
246 Nested repetition operators can be extremely slow if they specify
247 backtracking loops. For example, it could take hours for the regular
248 expression @samp{\(x+y*\)*a} to match the sequence
249 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because
250 Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
251 concluding that none of them can work. To make sure your regular
252 expressions run fast, check nested repetitions carefully.
255 @cindex @samp{+} in regexp
256 is a quantifying suffix operator similar to @samp{*} except that the
257 preceding expression must match at least once. It is also "greedy".
258 So, for example, @samp{ca+r} matches the strings @samp{car} and
259 @samp{caaaar} but not the string @samp{cr}, whereas @samp{ca*r} matches
263 @cindex @samp{?} in regexp
264 is a quantifying suffix operator similar to @samp{*}, except that the
265 preceding expression can match either once or not at all. For example,
266 @samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anything
270 @cindex @samp{*?} in regexp
271 works just like @samp{*}, except that rather than matching the longest
272 match, it matches the shortest match. @samp{*?} is known as a
273 @dfn{non-greedy} quantifier, a regexp construct borrowed from Perl.
274 @c Did perl get this from somewhere? What's the real history of *? ?
276 This construct very useful for when you want to match the text inside a
277 pair of delimiters. For instance, @samp{/\*.*?\*/} will match C
278 comments in a string. This could not be achieved without the use of
281 This construct has not been available prior to XEmacs 20.4. It is not
282 available in FSF Emacs.
285 @cindex @samp{+?} in regexp
286 is the @samp{+} analog to @samp{*?}.
289 @c Note the spacing after the close brace is deliberate.
290 @cindex @samp{\@{n,m\@} }in regexp
291 serves as an interval quantifier, analogous to @samp{*} or @samp{+}, but
292 specifies that the expression must match at least @var{n} times, but no
293 more than @var{m} times. This syntax is supported by most Unix regexp
294 utilities, and has been introduced to XEmacs for the version 20.3.
297 @cindex character set (in regexp)
298 @cindex @samp{[} in regexp
299 @cindex @samp{]} in regexp
300 @samp{[} begins a @dfn{character set}, which is terminated by a
301 @samp{]}. In the simplest case, the characters between the two brackets
302 form the set. Thus, @samp{[ad]} matches either one @samp{a} or one
303 @samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}s
304 and @samp{d}s (including the empty string), from which it follows that
305 @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},
306 @samp{caddaar}, etc.@refill
308 The usual regular expression special characters are not special inside a
309 character set. A completely different set of special characters exists
310 inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
312 @samp{-} is used for ranges of characters. To write a range, write two
313 characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any
314 lower case letter. Ranges may be intermixed freely with individual
315 characters, as in @samp{[a-z$%.]}, which matches any lower case letter
316 or @samp{$}, @samp{%}, or a period.@refill
318 To include a @samp{]} in a character set, make it the first character.
319 For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a
320 @samp{-}, write @samp{-} as the first character in the set, or put it
321 immediately after a range. (You can replace one individual character
322 @var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the
323 @samp{-}.) There is no way to write a set containing just @samp{-} and
326 To include @samp{^} in a set, put it anywhere but at the beginning of
330 @cindex @samp{^} in regexp
331 @samp{[^} begins a @dfn{complement character set}, which matches any
332 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
333 matches all characters @emph{except} letters and digits.@refill
335 @samp{^} is not special in a character set unless it is the first
336 character. The character following the @samp{^} is treated as if it
337 were first (thus, @samp{-} and @samp{]} are not special there).
339 Note that a complement character set can match a newline, unless
340 newline is mentioned as one of the characters not to match.
343 @cindex @samp{^} in regexp
344 @cindex beginning of line in regexp
345 is a special character that matches the empty string, but only at the
346 beginning of a line in the text being matched. Otherwise it fails to
347 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
348 the beginning of a line.
350 When matching a string instead of a buffer, @samp{^} matches at the
351 beginning of the string or after a newline character @samp{\n}.
354 @cindex @samp{$} in regexp
355 is similar to @samp{^} but matches only at the end of a line. Thus,
356 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
358 When matching a string instead of a buffer, @samp{$} matches at the end
359 of the string or before a newline character @samp{\n}.
362 @cindex @samp{\} in regexp
363 has two functions: it quotes the special characters (including
364 @samp{\}), and it introduces additional special constructs.
366 Because @samp{\} quotes special characters, @samp{\$} is a regular
367 expression that matches only @samp{$}, and @samp{\[} is a regular
368 expression that matches only @samp{[}, and so on.
370 Note that @samp{\} also has special meaning in the read syntax of Lisp
371 strings (@pxref{String Type}), and must be quoted with @samp{\}. For
372 example, the regular expression that matches the @samp{\} character is
373 @samp{\\}. To write a Lisp string that contains the characters
374 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
375 @samp{\}. Therefore, the read syntax for a regular expression matching
376 @samp{\} is @code{"\\\\"}.@refill
379 @strong{Please note:} For historical compatibility, special characters
380 are treated as ordinary ones if they are in contexts where their special
381 meanings make no sense. For example, @samp{*foo} treats @samp{*} as
382 ordinary since there is no preceding expression on which the @samp{*}
383 can act. It is poor practice to depend on this behavior; quote the
384 special character anyway, regardless of where it appears.@refill
386 For the most part, @samp{\} followed by any character matches only
387 that character. However, there are several exceptions: characters
388 that, when preceded by @samp{\}, are special constructs. Such
389 characters are always ordinary when encountered on their own. Here
390 is a table of @samp{\} constructs:
394 @cindex @samp{|} in regexp
395 @cindex regexp alternative
396 specifies an alternative.
397 Two regular expressions @var{a} and @var{b} with @samp{\|} in
398 between form an expression that matches anything that either @var{a} or
399 @var{b} matches.@refill
401 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
402 but no other string.@refill
404 @samp{\|} applies to the largest possible surrounding expressions. Only a
405 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
408 Full backtracking capability exists to handle multiple uses of @samp{\|}.
411 @cindex @samp{(} in regexp
412 @cindex @samp{)} in regexp
413 @cindex regexp grouping
414 is a grouping construct that serves three purposes:
418 To enclose a set of @samp{\|} alternatives for other operations.
419 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
422 To enclose an expression for a suffix operator such as @samp{*} to act
423 on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any
424 (zero or more) number of @samp{na} strings.@refill
427 To record a matched substring for future reference.
430 This last application is not a consequence of the idea of a
431 parenthetical grouping; it is a separate feature that happens to be
432 assigned as a second meaning to the same @samp{\( @dots{} \)} construct
433 because there is no conflict in practice between the two meanings.
434 Here is an explanation of this feature:
437 matches the same text that matched the @var{digit}th occurrence of a
438 @samp{\( @dots{} \)} construct.
440 In other words, after the end of a @samp{\( @dots{} \)} construct. the
441 matcher remembers the beginning and end of the text matched by that
442 construct. Then, later on in the regular expression, you can use
443 @samp{\} followed by @var{digit} to match that same text, whatever it
446 The strings matching the first nine @samp{\( @dots{} \)} constructs
447 appearing in a regular expression are assigned numbers 1 through 9 in
448 the order that the open parentheses appear in the regular expression.
449 So you can use @samp{\1} through @samp{\9} to refer to the text matched
450 by the corresponding @samp{\( @dots{} \)} constructs.
452 For example, @samp{\(.*\)\1} matches any newline-free string that is
453 composed of two identical halves. The @samp{\(.*\)} matches the first
454 half, which may be anything, but the @samp{\1} that follows must match
457 @item \(?: @dots{} \)
458 @cindex @samp{\(?:} in regexp
459 @cindex regexp grouping
460 is called a @dfn{shy} grouping operator, and it is used just like
461 @samp{\( @dots{} \)}, except that it does not cause the matched
462 substring to be recorded for future reference.
464 This is useful when you need a lot of grouping @samp{\( @dots{} \)}
465 constructs, but only want to remember one or two. Then you can use
466 not want to remember them for later use with @code{match-string}.
468 Using @samp{\(?: @dots{} \)} rather than @samp{\( @dots{} \)} when you
469 don't need the captured substrings ought to speed up your programs some,
470 since it shortens the code path followed by the regular expression
471 engine, as well as the amount of memory allocation and string copying it
472 must do. The actual performance gain to be observed has not been
473 measured or quantified as of this writing.
474 @c This is used to good advantage by the font-locking code, and by
475 @c `regexp-opt.el'. ... It will be. It's not yet, but will be.
477 The shy grouping operator has been borrowed from Perl, and has not been
478 available prior to XEmacs 20.3, nor is it available in FSF Emacs.
481 @cindex @samp{\w} in regexp
482 matches any word-constituent character. The editor syntax table
483 determines which characters these are. @xref{Syntax Tables}.
486 @cindex @samp{\W} in regexp
487 matches any character that is not a word constituent.
490 @cindex @samp{\s} in regexp
491 matches any character whose syntax is @var{code}. Here @var{code} is a
492 character that represents a syntax code: thus, @samp{w} for word
493 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
494 etc. @xref{Syntax Tables}, for a list of syntax codes and the
495 characters that stand for them.
498 @cindex @samp{\S} in regexp
499 matches any character whose syntax is not @var{code}.
502 The following regular expression constructs match the empty string---that is,
503 they don't use up any characters---but whether they match depends on the
508 @cindex @samp{\`} in regexp
509 matches the empty string, but only at the beginning
510 of the buffer or string being matched against.
513 @cindex @samp{\'} in regexp
514 matches the empty string, but only at the end of
515 the buffer or string being matched against.
518 @cindex @samp{\=} in regexp
519 matches the empty string, but only at point.
520 (This construct is not defined when matching against a string.)
523 @cindex @samp{\b} in regexp
524 matches the empty string, but only at the beginning or
525 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of
526 @samp{foo} as a separate word. @samp{\bballs?\b} matches
527 @samp{ball} or @samp{balls} as a separate word.@refill
530 @cindex @samp{\B} in regexp
531 matches the empty string, but @emph{not} at the beginning or
535 @cindex @samp{\<} in regexp
536 matches the empty string, but only at the beginning of a word.
539 @cindex @samp{\>} in regexp
540 matches the empty string, but only at the end of a word.
543 @kindex invalid-regexp
544 Not every string is a valid regular expression. For example, a string
545 with unbalanced square brackets is invalid (with a few exceptions, such
546 as @samp{[]]}), and so is a string that ends with a single @samp{\}. If
547 an invalid regular expression is passed to any of the search functions,
548 an @code{invalid-regexp} error is signaled.
550 @defun regexp-quote string
551 This function returns a regular expression string that matches exactly
552 @var{string} and nothing else. This allows you to request an exact
553 string match when calling a function that wants a regular expression.
557 (regexp-quote "^The cat$")
558 @result{} "\\^The cat\\$"
562 One use of @code{regexp-quote} is to combine an exact string match with
563 context described as a regular expression. For example, this searches
564 for the string that is the value of @code{string}, surrounded by
570 (concat "\\s-" (regexp-quote string) "\\s-"))
576 @subsection Complex Regexp Example
578 Here is a complicated regexp, used by XEmacs to recognize the end of a
579 sentence together with any whitespace that follows. It is the value of
580 the variable @code{sentence-end}.
582 First, we show the regexp as a string in Lisp syntax to distinguish
583 spaces from tab characters. The string constant begins and ends with a
584 double-quote. @samp{\"} stands for a double-quote as part of the
585 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
586 tab and @samp{\n} for a newline.
589 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
592 In contrast, if you evaluate the variable @code{sentence-end}, you
593 will see the following:
599 "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
605 In this output, tab and newline appear as themselves.
607 This regular expression contains four parts in succession and can be
608 deciphered as follows:
612 The first part of the pattern is a character set that matches any one of
613 three characters: period, question mark, and exclamation mark. The
614 match must begin with one of these three characters.
617 The second part of the pattern matches any closing braces and quotation
618 marks, zero or more of them, that may follow the period, question mark
619 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
620 a string. The @samp{*} at the end indicates that the immediately
621 preceding regular expression (a character set, in this case) may be
622 repeated zero or more times.
624 @item \\($\\|@ $\\|\t\\|@ @ \\)
625 The third part of the pattern matches the whitespace that follows the
626 end of a sentence: the end of a line, or a tab, or two spaces. The
627 double backslashes mark the parentheses and vertical bars as regular
628 expression syntax; the parentheses delimit a group and the vertical bars
629 separate alternatives. The dollar sign is used to match the end of a
633 Finally, the last part of the pattern matches any additional whitespace
634 beyond the minimum needed to end a sentence.
638 @section Regular Expression Searching
639 @cindex regular expression searching
640 @cindex regexp searching
641 @cindex searching for regexp
643 In XEmacs, you can search for the next match for a regexp either
644 incrementally or not. Incremental search commands are described in the
645 @cite{The XEmacs Reference Manual}. @xref{Regexp Search, , Regular Expression
646 Search, emacs, The XEmacs Reference Manual}. Here we describe only the search
647 functions useful in programs. The principal one is
648 @code{re-search-forward}.
650 @deffn Command re-search-forward regexp &optional limit noerror repeat
651 This function searches forward in the current buffer for a string of
652 text that is matched by the regular expression @var{regexp}. The
653 function skips over any amount of text that is not matched by
654 @var{regexp}, and leaves point at the end of the first match found.
655 It returns the new value of point.
657 If @var{limit} is non-@code{nil} (it must be a position in the current
658 buffer), then it is the upper bound to the search. No match extending
659 after that position is accepted.
661 What happens when the search 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 If @var{repeat} is supplied (it must be a positive number), then the
670 search is repeated that many times (each time starting at the end of the
671 previous time's match). If these successive searches succeed, the
672 function succeeds, moving point and returning its new value. Otherwise
675 In the following example, point is initially before the @samp{T}.
676 Evaluating the search call moves point to the end of that line (between
677 the @samp{t} of @samp{hat} and the newline).
681 ---------- Buffer: foo ----------
682 I read "@point{}The cat in the hat
684 ---------- Buffer: foo ----------
688 (re-search-forward "[a-z]+" nil t 5)
691 ---------- Buffer: foo ----------
692 I read "The cat in the hat@point{}
694 ---------- Buffer: foo ----------
699 @deffn Command re-search-backward regexp &optional limit noerror repeat
700 This function searches backward in the current buffer for a string of
701 text that is matched by the regular expression @var{regexp}, leaving
702 point at the beginning of the first text found.
704 This function is analogous to @code{re-search-forward}, but they are not
705 simple mirror images. @code{re-search-forward} finds the match whose
706 beginning is as close as possible to the starting point. If
707 @code{re-search-backward} were a perfect mirror image, it would find the
708 match whose end is as close as possible. However, in fact it finds the
709 match whose beginning is as close as possible. The reason is that
710 matching a regular expression at a given spot always works from
711 beginning to end, and starts at a specified beginning position.
713 A true mirror-image of @code{re-search-forward} would require a special
714 feature for matching regexps from end to beginning. It's not worth the
715 trouble of implementing that.
718 @defun string-match regexp string &optional start
719 This function returns the index of the start of the first match for
720 the regular expression @var{regexp} in @var{string}, or @code{nil} if
721 there is no match. If @var{start} is non-@code{nil}, the search starts
722 at that index in @var{string}.
729 "quick" "The quick brown fox jumped quickly.")
734 "quick" "The quick brown fox jumped quickly." 8)
740 The index of the first character of the
741 string is 0, the index of the second character is 1, and so on.
743 After this function returns, the index of the first character beyond
744 the match is available as @code{(match-end 0)}. @xref{Match Data}.
749 "quick" "The quick brown fox jumped quickly." 8)
760 @defun split-string string &optional pattern
761 This function splits @var{string} to substrings delimited by
762 @var{pattern}, and returns a list of substrings. If @var{pattern} is
763 omitted, it defaults to @samp{[ \f\t\n\r\v]+}, which means that it
764 splits @var{string} by white--space.
768 (split-string "foo bar")
769 @result{} ("foo" "bar")
773 (split-string "something")
774 @result{} ("something")
778 (split-string "a:b:c" ":")
779 @result{} ("a" "b" "c")
783 (split-string ":a::b:c" ":")
784 @result{} ("" "a" "" "b" "c")
789 @defun split-path path
790 This function splits a search path into a list of strings. The path
791 components are separated with the characters specified with
792 @code{path-separator}. Under Unix, @code{path-separator} will normally
793 be @samp{:}, while under Windows, it will be @samp{;}.
796 @defun looking-at regexp
797 This function determines whether the text in the current buffer directly
798 following point matches the regular expression @var{regexp}. ``Directly
799 following'' means precisely that: the search is ``anchored'' and it can
800 succeed only starting with the first character following point. The
801 result is @code{t} if so, @code{nil} otherwise.
803 This function does not move point, but it updates the match data, which
804 you can access using @code{match-beginning} and @code{match-end}.
807 In this example, point is located directly before the @samp{T}. If it
808 were anywhere else, the result would be @code{nil}.
812 ---------- Buffer: foo ----------
813 I read "@point{}The cat in the hat
815 ---------- Buffer: foo ----------
817 (looking-at "The cat in the hat$")
824 @section POSIX Regular Expression Searching
826 The usual regular expression functions do backtracking when necessary
827 to handle the @samp{\|} and repetition constructs, but they continue
828 this only until they find @emph{some} match. Then they succeed and
829 report the first match found.
831 This section describes alternative search functions which perform the
832 full backtracking specified by the POSIX standard for regular expression
833 matching. They continue backtracking until they have tried all
834 possibilities and found all matches, so they can report the longest
835 match, as required by POSIX. This is much slower, so use these
836 functions only when you really need the longest match.
838 In Emacs versions prior to 19.29, these functions did not exist, and
839 the functions described above implemented full POSIX backtracking.
841 @defun posix-search-forward regexp &optional limit noerror repeat
842 This is like @code{re-search-forward} except that it performs the full
843 backtracking specified by the POSIX standard for regular expression
847 @defun posix-search-backward regexp &optional limit noerror repeat
848 This is like @code{re-search-backward} except that it performs the full
849 backtracking specified by the POSIX standard for regular expression
853 @defun posix-looking-at regexp
854 This is like @code{looking-at} except that it performs the full
855 backtracking specified by the POSIX standard for regular expression
859 @defun posix-string-match regexp string &optional start
860 This is like @code{string-match} except that it performs the full
861 backtracking specified by the POSIX standard for regular expression
866 @deffn Command delete-matching-lines regexp
867 This function is identical to @code{delete-non-matching-lines}, save
868 that it deletes what @code{delete-non-matching-lines} keeps.
870 In the example below, point is located on the first line of text.
874 ---------- Buffer: foo ----------
877 that all men are created
878 equal, and that they are
879 ---------- Buffer: foo ----------
883 (delete-matching-lines "the")
886 ---------- Buffer: foo ----------
888 that all men are created
889 ---------- Buffer: foo ----------
894 @deffn Command flush-lines regexp
895 This function is the same as @code{delete-matching-lines}.
898 @defun delete-non-matching-lines regexp
899 This function deletes all lines following point which don't
900 contain a match for the regular expression @var{regexp}.
903 @deffn Command keep-lines regexp
904 This function is the same as @code{delete-non-matching-lines}.
907 @deffn Command how-many regexp
908 This function counts the number of matches for @var{regexp} there are in
909 the current buffer following point. It prints this number in
910 the echo area, returning the string printed.
913 @deffn Command count-matches regexp
914 This function is a synonym of @code{how-many}.
917 @deffn Command list-matching-lines regexp nlines
918 This function is a synonym of @code{occur}.
919 Show all lines following point containing a match for @var{regexp}.
920 Display each line with @var{nlines} lines before and after,
921 or @code{-}@var{nlines} before if @var{nlines} is negative.
922 @var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
923 Interactively it is the prefix arg.
925 The lines are shown in a buffer named @samp{*Occur*}.
926 It serves as a menu to find any of the occurrences in this buffer.
927 @kbd{C-h m} (@code{describe-mode} in that buffer gives help.
930 @defopt list-matching-lines-default-context-lines
932 Default number of context lines to include around a @code{list-matching-lines}
933 match. A negative number means to include that many lines before the match.
934 A positive number means to include that many lines both before and after.
938 @node Search and Replace
939 @section Search and Replace
942 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
943 This function is the guts of @code{query-replace} and related commands.
944 It searches for occurrences of @var{from-string} and replaces some or
945 all of them. If @var{query-flag} is @code{nil}, it replaces all
946 occurrences; otherwise, it asks the user what to do about each one.
948 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
949 considered a regular expression; otherwise, it must match literally. If
950 @var{delimited-flag} is non-@code{nil}, then only replacements
951 surrounded by word boundaries are considered.
953 The argument @var{replacements} specifies what to replace occurrences
954 with. If it is a string, that string is used. It can also be a list of
955 strings, to be used in cyclic order.
957 If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
958 it specifies how many times to use each of the strings in the
959 @var{replacements} list before advancing cyclicly to the next one.
961 Normally, the keymap @code{query-replace-map} defines the possible user
962 responses for queries. The argument @var{map}, if non-@code{nil}, is a
963 keymap to use instead of @code{query-replace-map}.
966 @defvar query-replace-map
967 This variable holds a special keymap that defines the valid user
968 responses for @code{query-replace} and related functions, as well as
969 @code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways:
973 The ``key bindings'' are not commands, just symbols that are meaningful
974 to the functions that use this map.
977 Prefix keys are not supported; each key binding must be for a single event
978 key sequence. This is because the functions don't use read key sequence to
979 get the input; instead, they read a single event and look it up ``by hand.''
983 Here are the meaningful ``bindings'' for @code{query-replace-map}.
984 Several of them are meaningful only for @code{query-replace} and
989 Do take the action being considered---in other words, ``yes.''
992 Do not take action for this question---in other words, ``no.''
995 Answer this question ``no,'' and give up on the entire series of
996 questions, assuming that the answers will be ``no.''
999 Answer this question ``yes,'' and give up on the entire series of
1000 questions, assuming that subsequent answers will be ``no.''
1003 Answer this question ``yes,'' but show the results---don't advance yet
1004 to the next question.
1007 Answer this question and all subsequent questions in the series with
1008 ``yes,'' without further user interaction.
1011 Move back to the previous place that a question was asked about.
1014 Enter a recursive edit to deal with this question---instead of any
1015 other action that would normally be taken.
1017 @item delete-and-edit
1018 Delete the text being considered, then enter a recursive edit to replace
1022 Redisplay and center the window, then ask the same question again.
1025 Perform a quit right away. Only @code{y-or-n-p} and related functions
1029 Display some help, then ask again.
1033 @section The Match Data
1036 XEmacs keeps track of the positions of the start and end of segments of
1037 text found during a regular expression search. This means, for example,
1038 that you can search for a complex pattern, such as a date in an Rmail
1039 message, and then extract parts of the match under control of the
1042 Because the match data normally describe the most recent search only,
1043 you must be careful not to do another search inadvertently between the
1044 search you wish to refer back to and the use of the match data. If you
1045 can't avoid another intervening search, you must save and restore the
1046 match data around it, to prevent it from being overwritten.
1049 * Simple Match Data:: Accessing single items of match data,
1050 such as where a particular subexpression started.
1051 * Replacing Match:: Replacing a substring that was matched.
1052 * Entire Match Data:: Accessing the entire match data at once, as a list.
1053 * Saving Match Data:: Saving and restoring the match data.
1056 @node Simple Match Data
1057 @subsection Simple Match Data Access
1059 This section explains how to use the match data to find out what was
1060 matched by the last search or match operation.
1062 You can ask about the entire matching text, or about a particular
1063 parenthetical subexpression of a regular expression. The @var{count}
1064 argument in the functions below specifies which. If @var{count} is
1065 zero, you are asking about the entire match. If @var{count} is
1066 positive, it specifies which subexpression you want.
1068 Recall that the subexpressions of a regular expression are those
1069 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The
1070 @var{count}th subexpression is found by counting occurrences of
1071 @samp{\(} from the beginning of the whole regular expression. The first
1072 subexpression is numbered 1, the second 2, and so on. Only regular
1073 expressions can have subexpressions---after a simple string search, the
1074 only information available is about the entire match.
1076 @defun match-string count &optional in-string
1077 This function returns, as a string, the text matched in the last search
1078 or match operation. It returns the entire text if @var{count} is zero,
1079 or just the portion corresponding to the @var{count}th parenthetical
1080 subexpression, if @var{count} is positive. If @var{count} is out of
1081 range, or if that subexpression didn't match anything, the value is
1084 If the last such operation was done against a string with
1085 @code{string-match}, then you should pass the same string as the
1086 argument @var{in-string}. Otherwise, after a buffer search or match,
1087 you should omit @var{in-string} or pass @code{nil} for it; but you
1088 should make sure that the current buffer when you call
1089 @code{match-string} is the one in which you did the searching or
1093 @defun match-beginning count
1094 This function returns the position of the start of text matched by the
1095 last regular expression searched for, or a subexpression of it.
1097 If @var{count} is zero, then the value is the position of the start of
1098 the entire match. Otherwise, @var{count} specifies a subexpression in
1099 the regular expression, and the value of the function is the starting
1100 position of the match for that subexpression.
1102 The value is @code{nil} for a subexpression inside a @samp{\|}
1103 alternative that wasn't used in the match.
1106 @defun match-end count
1107 This function is like @code{match-beginning} except that it returns the
1108 position of the end of the match, rather than the position of the
1112 Here is an example of using the match data, with a comment showing the
1113 positions within the text:
1117 (string-match "\\(qu\\)\\(ick\\)"
1118 "The quick fox jumped quickly.")
1124 (match-string 0 "The quick fox jumped quickly.")
1126 (match-string 1 "The quick fox jumped quickly.")
1128 (match-string 2 "The quick fox jumped quickly.")
1133 (match-beginning 1) ; @r{The beginning of the match}
1134 @result{} 4 ; @r{with @samp{qu} is at index 4.}
1138 (match-beginning 2) ; @r{The beginning of the match}
1139 @result{} 6 ; @r{with @samp{ick} is at index 6.}
1143 (match-end 1) ; @r{The end of the match}
1144 @result{} 6 ; @r{with @samp{qu} is at index 6.}
1146 (match-end 2) ; @r{The end of the match}
1147 @result{} 9 ; @r{with @samp{ick} is at index 9.}
1151 Here is another example. Point is initially located at the beginning
1152 of the line. Searching moves point to between the space and the word
1153 @samp{in}. The beginning of the entire match is at the 9th character of
1154 the buffer (@samp{T}), and the beginning of the match for the first
1155 subexpression is at the 13th character (@samp{c}).
1160 (re-search-forward "The \\(cat \\)")
1162 (match-beginning 1))
1167 ---------- Buffer: foo ----------
1168 I read "The cat @point{}in the hat comes back" twice.
1171 ---------- Buffer: foo ----------
1176 (In this case, the index returned is a buffer position; the first
1177 character of the buffer counts as 1.)
1179 @node Replacing Match
1180 @subsection Replacing the Text That Matched
1182 This function replaces the text matched by the last search with
1185 @cindex case in replacements
1186 @defun replace-match replacement &optional fixedcase literal string
1187 This function replaces the text in the buffer (or in @var{string}) that
1188 was matched by the last search. It replaces that text with
1191 If you did the last search in a buffer, you should specify @code{nil}
1192 for @var{string}. Then @code{replace-match} does the replacement by
1193 editing the buffer; it leaves point at the end of the replacement text,
1194 and returns @code{t}.
1196 If you did the search in a string, pass the same string as @var{string}.
1197 Then @code{replace-match} does the replacement by constructing and
1198 returning a new string.
1200 If @var{fixedcase} is non-@code{nil}, then the case of the replacement
1201 text is not changed; otherwise, the replacement text is converted to a
1202 different case depending upon the capitalization of the text to be
1203 replaced. If the original text is all upper case, the replacement text
1204 is converted to upper case. If the first word of the original text is
1205 capitalized, then the first word of the replacement text is capitalized.
1206 If the original text contains just one word, and that word is a capital
1207 letter, @code{replace-match} considers this a capitalized first word
1208 rather than all upper case.
1210 If @code{case-replace} is @code{nil}, then case conversion is not done,
1211 regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
1213 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1214 exactly as it is, the only alterations being case changes as needed.
1215 If it is @code{nil} (the default), then the character @samp{\} is treated
1216 specially. If a @samp{\} appears in @var{replacement}, then it must be
1217 part of one of the following sequences:
1221 @cindex @samp{&} in replacement
1222 @samp{\&} stands for the entire text being replaced.
1224 @item @samp{\@var{n}}
1225 @cindex @samp{\@var{n}} in replacement
1226 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1227 matched the @var{n}th subexpression in the original regexp.
1228 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1231 @cindex @samp{\} in replacement
1232 @samp{\\} stands for a single @samp{\} in the replacement text.
1236 @node Entire Match Data
1237 @subsection Accessing the Entire Match Data
1239 The functions @code{match-data} and @code{set-match-data} read or
1240 write the entire match data, all at once.
1243 This function returns a newly constructed list containing all the
1244 information on what text the last search matched. Element zero is the
1245 position of the beginning of the match for the whole expression; element
1246 one is the position of the end of the match for the expression. The
1247 next two elements are the positions of the beginning and end of the
1248 match for the first subexpression, and so on. In general, element
1253 number {\mathsurround=0pt $2n$}
1255 corresponds to @code{(match-beginning @var{n})}; and
1261 number {\mathsurround=0pt $2n+1$}
1263 corresponds to @code{(match-end @var{n})}.
1265 All the elements are markers or @code{nil} if matching was done on a
1266 buffer, and all are integers or @code{nil} if matching was done on a
1267 string with @code{string-match}. (In Emacs 18 and earlier versions,
1268 markers were used even for matching on a string, except in the case
1271 As always, there must be no possibility of intervening searches between
1272 the call to a search function and the call to @code{match-data} that is
1273 intended to access the match data for that search.
1278 @result{} (#<marker at 9 in foo>
1279 #<marker at 17 in foo>
1280 #<marker at 13 in foo>
1281 #<marker at 17 in foo>)
1286 @defun set-match-data match-list
1287 This function sets the match data from the elements of @var{match-list},
1288 which should be a list that was the value of a previous call to
1291 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1292 an error; that sets the match data in a meaningless but harmless way.
1294 @findex store-match-data
1295 @code{store-match-data} is an alias for @code{set-match-data}.
1298 @node Saving Match Data
1299 @subsection Saving and Restoring the Match Data
1301 When you call a function that may do a search, you may need to save
1302 and restore the match data around that call, if you want to preserve the
1303 match data from an earlier search for later use. Here is an example
1304 that shows the problem that arises if you fail to save the match data:
1308 (re-search-forward "The \\(cat \\)")
1310 (foo) ; @r{Perhaps @code{foo} does}
1311 ; @r{more searching.}
1313 @result{} 61 ; @r{Unexpected result---not 48!}
1317 You can save and restore the match data with @code{save-match-data}:
1319 @defmac save-match-data body@dots{}
1320 This special form executes @var{body}, saving and restoring the match
1324 You can use @code{set-match-data} together with @code{match-data} to
1325 imitate the effect of the special form @code{save-match-data}. This is
1326 useful for writing code that can run in Emacs 18. Here is how:
1330 (let ((data (match-data)))
1332 @dots{} ; @r{May change the original match data.}
1333 (set-match-data data)))
1337 Emacs automatically saves and restores the match data when it runs
1338 process filter functions (@pxref{Filter Functions}) and process
1339 sentinels (@pxref{Sentinels}).
1342 Here is a function which restores the match data provided the buffer
1343 associated with it still exists.
1347 (defun restore-match-data (data)
1348 @c It is incorrect to split the first line of a doc string.
1349 @c If there's a problem here, it should be solved in some other way.
1350 "Restore the match data DATA unless the buffer is missing."
1356 (null (marker-buffer (car d)))
1358 ;; @file{match-data} @r{buffer is deleted.}
1361 (set-match-data data))))
1366 @node Searching and Case
1367 @section Searching and Case
1368 @cindex searching and case
1370 By default, searches in Emacs ignore the case of the text they are
1371 searching through; if you specify searching for @samp{FOO}, then
1372 @samp{Foo} or @samp{foo} is also considered a match. Regexps, and in
1373 particular character sets, are included: thus, @samp{[aB]} would match
1374 @samp{a} or @samp{A} or @samp{b} or @samp{B}.
1376 If you do not want this feature, set the variable
1377 @code{case-fold-search} to @code{nil}. Then all letters must match
1378 exactly, including case. This is a buffer-local variable; altering the
1379 variable affects only the current buffer. (@xref{Intro to
1380 Buffer-Local}.) Alternatively, you may change the value of
1381 @code{default-case-fold-search}, which is the default value of
1382 @code{case-fold-search} for buffers that do not override it.
1384 Note that the user-level incremental search feature handles case
1385 distinctions differently. When given a lower case letter, it looks for
1386 a match of either case, but when given an upper case letter, it looks
1387 for an upper case letter only. But this has nothing to do with the
1388 searching functions Lisp functions use.
1390 @defopt case-replace
1391 This variable determines whether the replacement functions should
1392 preserve case. If the variable is @code{nil}, that means to use the
1393 replacement text verbatim. A non-@code{nil} value means to convert the
1394 case of the replacement text according to the text being replaced.
1396 The function @code{replace-match} is where this variable actually has
1397 its effect. @xref{Replacing Match}.
1400 @defopt case-fold-search
1401 This buffer-local variable determines whether searches should ignore
1402 case. If the variable is @code{nil} they do not ignore case; otherwise
1403 they do ignore case.
1406 @defvar default-case-fold-search
1407 The value of this variable is the default value for
1408 @code{case-fold-search} in buffers that do not override it. This is the
1409 same as @code{(default-value 'case-fold-search)}.
1412 @node Standard Regexps
1413 @section Standard Regular Expressions Used in Editing
1414 @cindex regexps used standardly in editing
1415 @cindex standard regexps used in editing
1417 This section describes some variables that hold regular expressions
1418 used for certain purposes in editing:
1420 @defvar page-delimiter
1421 This is the regexp describing line-beginnings that separate pages. The
1422 default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
1423 this matches a line that starts with a formfeed character.
1426 The following two regular expressions should @emph{not} assume the
1427 match always starts at the beginning of a line; they should not use
1428 @samp{^} to anchor the match. Most often, the paragraph commands do
1429 check for a match only at the beginning of a line, which means that
1430 @samp{^} would be superfluous. When there is a nonzero left margin,
1431 they accept matches that start after the left margin. In that case, a
1432 @samp{^} would be incorrect. However, a @samp{^} is harmless in modes
1433 where a left margin is never used.
1435 @defvar paragraph-separate
1436 This is the regular expression for recognizing the beginning of a line
1437 that separates paragraphs. (If you change this, you may have to
1438 change @code{paragraph-start} also.) The default value is
1439 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1440 spaces, tabs, and form feeds (after its left margin).
1443 @defvar paragraph-start
1444 This is the regular expression for recognizing the beginning of a line
1445 that starts @emph{or} separates paragraphs. The default value is
1446 @w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
1447 newline, or form feed (after its left margin).
1450 @defvar sentence-end
1451 This is the regular expression describing the end of a sentence. (All
1452 paragraph boundaries also end sentences, regardless.) The default value
1456 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
1459 This means a period, question mark or exclamation mark, followed
1460 optionally by a closing parenthetical character, followed by tabs,
1461 spaces or new lines.
1463 For a detailed explanation of this regular expression, see @ref{Regexp