*** empty log message ***
[emacs.git] / lispref / searching.texi
blob0b54fcd2fe85d72c0aa1ac3fa478aba7d1ecf268
1 @c -*-texinfo-*-
2 @c This is part of the GNU Emacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999
4 @c   Free Software Foundation, Inc. 
5 @c See the file elisp.texi for copying conditions.
6 @setfilename ../info/searching
7 @node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
8 @chapter Searching and Matching
9 @cindex searching
11   GNU Emacs provides two ways to search through a buffer for specified
12 text: exact string searches and regular expression searches.  After a
13 regular expression search, you can examine the @dfn{match data} to
14 determine which text matched the whole regular expression or various
15 portions of it.
17 @menu
18 * String Search::         Search for an exact match.
19 * Regular Expressions::   Describing classes of strings.
20 * Regexp Search::         Searching for a match for a regexp.
21 * POSIX Regexps::         Searching POSIX-style for the longest match.
22 * Search and Replace::    Internals of @code{query-replace}.
23 * Match Data::            Finding out which part of the text matched
24                             various parts of a regexp, after regexp search.
25 * Searching and Case::    Case-independent or case-significant searching.
26 * Standard Regexps::      Useful regexps for finding sentences, pages,...
27 @end menu
29   The @samp{skip-chars@dots{}} functions also perform a kind of searching.
30 @xref{Skipping Characters}.
32 @node String Search
33 @section Searching for Strings
34 @cindex string search
36   These are the primitive functions for searching through the text in a
37 buffer.  They are meant for use in programs, but you may call them
38 interactively.  If you do so, they prompt for the search string; the
39 arguments @var{limit} and @var{noerror} are @code{nil}, and @var{repeat}
40 is 1.
42   These search functions convert the search string to multibyte if the
43 buffer is multibyte; they convert the search string to unibyte if the
44 buffer is unibyte.  @xref{Text Representations}.
46 @deffn Command search-forward string &optional limit noerror repeat
47 This function searches forward from point for an exact match for
48 @var{string}.  If successful, it sets point to the end of the occurrence
49 found, and returns the new value of point.  If no match is found, the
50 value and side effects depend on @var{noerror} (see below).
51 @c Emacs 19 feature
53 In the following example, point is initially at the beginning of the
54 line.  Then @code{(search-forward "fox")} moves point after the last
55 letter of @samp{fox}:
57 @example
58 @group
59 ---------- Buffer: foo ----------
60 @point{}The quick brown fox jumped over the lazy dog.
61 ---------- Buffer: foo ----------
62 @end group
64 @group
65 (search-forward "fox")
66      @result{} 20
68 ---------- Buffer: foo ----------
69 The quick brown fox@point{} jumped over the lazy dog.
70 ---------- Buffer: foo ----------
71 @end group
72 @end example
74 The argument @var{limit} specifies the upper bound to the search.  (It
75 must be a position in the current buffer.)  No match extending after
76 that position is accepted.  If @var{limit} is omitted or @code{nil}, it
77 defaults to the end of the accessible portion of the buffer.
79 @kindex search-failed
80 What happens when the search fails depends on the value of
81 @var{noerror}.  If @var{noerror} is @code{nil}, a @code{search-failed}
82 error is signaled.  If @var{noerror} is @code{t}, @code{search-forward}
83 returns @code{nil} and does nothing.  If @var{noerror} is neither
84 @code{nil} nor @code{t}, then @code{search-forward} moves point to the
85 upper bound and returns @code{nil}.  (It would be more consistent now to
86 return the new position of point in that case, but some existing
87 programs may depend on a value of @code{nil}.)
89 If @var{repeat} is supplied (it must be a positive number), then the
90 search is repeated that many times (each time starting at the end of the
91 previous time's match).  If these successive searches succeed, the
92 function succeeds, moving point and returning its new value.  Otherwise
93 the search fails.
94 @end deffn
96 @deffn Command search-backward string &optional limit noerror repeat
97 This function searches backward from point for @var{string}.  It is
98 just like @code{search-forward} except that it searches backwards and
99 leaves point at the beginning of the match.
100 @end deffn
102 @deffn Command word-search-forward string &optional limit noerror repeat
103 @cindex word search
104 This function searches forward from point for a ``word'' match for
105 @var{string}.  If it finds a match, it sets point to the end of the
106 match found, and returns the new value of point.
107 @c Emacs 19 feature
109 Word matching regards @var{string} as a sequence of words, disregarding
110 punctuation that separates them.  It searches the buffer for the same
111 sequence of words.  Each word must be distinct in the buffer (searching
112 for the word @samp{ball} does not match the word @samp{balls}), but the
113 details of punctuation and spacing are ignored (searching for @samp{ball
114 boy} does match @samp{ball.  Boy!}).
116 In this example, point is initially at the beginning of the buffer; the
117 search leaves it between the @samp{y} and the @samp{!}.
119 @example
120 @group
121 ---------- Buffer: foo ----------
122 @point{}He said "Please!  Find
123 the ball boy!"
124 ---------- Buffer: foo ----------
125 @end group
127 @group
128 (word-search-forward "Please find the ball, boy.")
129      @result{} 35
131 ---------- Buffer: foo ----------
132 He said "Please!  Find
133 the ball boy@point{}!"
134 ---------- Buffer: foo ----------
135 @end group
136 @end example
138 If @var{limit} is non-@code{nil} (it must be a position in the current
139 buffer), then it is the upper bound to the search.  The match found must
140 not extend after that position.
142 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals
143 an error if the search fails.  If @var{noerror} is @code{t}, then it
144 returns @code{nil} instead of signaling an error.  If @var{noerror} is
145 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the
146 end of the buffer) and returns @code{nil}.
148 If @var{repeat} is non-@code{nil}, then the search is repeated that many
149 times.  Point is positioned at the end of the last match.
150 @end deffn
152 @deffn Command word-search-backward string &optional limit noerror repeat
153 This function searches backward from point for a word match to
154 @var{string}.  This function is just like @code{word-search-forward}
155 except that it searches backward and normally leaves point at the
156 beginning of the match.
157 @end deffn
159 @node Regular Expressions
160 @section Regular Expressions
161 @cindex regular expression
162 @cindex regexp
164   A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
165 denotes a (possibly infinite) set of strings.  Searching for matches for
166 a regexp is a very powerful operation.  This section explains how to write
167 regexps; the following section says how to search for them.
169 @menu
170 * Syntax of Regexps::       Rules for writing regular expressions.
171 * Regexp Functions::        Functions for operating on regular expressions.
172 * Regexp Example::          Illustrates regular expression syntax.
173 @end menu
175 @node Syntax of Regexps
176 @subsection Syntax of Regular Expressions
178   Regular expressions have a syntax in which a few characters are
179 special constructs and the rest are @dfn{ordinary}.  An ordinary
180 character is a simple regular expression that matches that character and
181 nothing else.  The special characters are @samp{.}, @samp{*}, @samp{+},
182 @samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
183 special characters will be defined in the future.  Any other character
184 appearing in a regular expression is ordinary, unless a @samp{\}
185 precedes it.
187   For example, @samp{f} is not a special character, so it is ordinary, and
188 therefore @samp{f} is a regular expression that matches the string
189 @samp{f} and no other string.  (It does @emph{not} match the string
190 @samp{fg}, but it does match a @emph{part} of that string.)  Likewise,
191 @samp{o} is a regular expression that matches only @samp{o}.@refill
193   Any two regular expressions @var{a} and @var{b} can be concatenated.  The
194 result is a regular expression that matches a string if @var{a} matches
195 some amount of the beginning of that string and @var{b} matches the rest of
196 the string.@refill
198   As a simple example, we can concatenate the regular expressions @samp{f}
199 and @samp{o} to get the regular expression @samp{fo}, which matches only
200 the string @samp{fo}.  Still trivial.  To do something more powerful, you
201 need to use one of the special regular expression constructs.
203 @menu
204 * Regexp Special::      Special characters in regular expressions.
205 * Char Classes::        Character classes used in regular expressions.
206 * Regexp Backslash::    Backslash-sequences in regular expressions.
207 @end menu
209 @node Regexp Special
210 @subsubsection Special Characters in Regular Expressions
212   Here is a list of the characters that are special in a regular
213 expression.
215 @need 800
216 @table @asis
217 @item @samp{.}@: @r{(Period)}
218 @cindex @samp{.} in regexp
219 is a special character that matches any single character except a newline.
220 Using concatenation, we can make regular expressions like @samp{a.b}, which
221 matches any three-character string that begins with @samp{a} and ends with
222 @samp{b}.@refill
224 @item @samp{*}
225 @cindex @samp{*} in regexp
226 is not a construct by itself; it is a postfix operator that means to
227 match the preceding regular expression repetitively as many times as
228 possible.  Thus, @samp{o*} matches any number of @samp{o}s (including no
229 @samp{o}s).
231 @samp{*} always applies to the @emph{smallest} possible preceding
232 expression.  Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
233 @samp{fo}.  It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
235 The matcher processes a @samp{*} construct by matching, immediately, as
236 many repetitions as can be found.  Then it continues with the rest of
237 the pattern.  If that fails, backtracking occurs, discarding some of the
238 matches of the @samp{*}-modified construct in the hope that that will
239 make it possible to match the rest of the pattern.  For example, in
240 matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
241 first tries to match all three @samp{a}s; but the rest of the pattern is
242 @samp{ar} and there is only @samp{r} left to match, so this try fails.
243 The next alternative is for @samp{a*} to match only two @samp{a}s.  With
244 this choice, the rest of the regexp matches successfully.@refill
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 try to match the sequence
249 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately fails.
250 The slowness is because Emacs must try each imaginable way of grouping
251 the 35 @samp{x}s before concluding that none of them can work.  To make
252 sure your regular expressions run fast, check nested repetitions
253 carefully.
255 @item @samp{+}
256 @cindex @samp{+} in regexp
257 is a postfix operator, similar to @samp{*} except that it must match
258 the preceding expression at least once.  So, for example, @samp{ca+r}
259 matches the strings @samp{car} and @samp{caaaar} but not the string
260 @samp{cr}, whereas @samp{ca*r} matches all three strings.
262 @item @samp{?}
263 @cindex @samp{?} in regexp
264 is a postfix operator, similar to @samp{*} except that it must match the
265 preceding expression either once or not at all.  For example,
266 @samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
268 @item @samp{*?}, @samp{+?}, @samp{??}
269 These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
270 and @samp{?}.  Where those operators match the largest possible
271 substring (consistent with matching the entire containing expression),
272 the non-greedy variants match the smallest possible substring
273 (consistent with matching the entire containing expression).
275 For example, the regular expression @samp{c[ad]*a} when applied to the
276 string @samp{cdaaada} matches the whole string; but the regular
277 expression @samp{c[ad]*?a}, applied to that same string, matches just
278 @samp{cda}.  (The smallest possible match here for @samp{[ad]*?} that
279 permits the whole expression to match is @samp{d}.)
281 @item @samp{[ @dots{} ]}
282 @cindex character alternative (in regexp)
283 @cindex @samp{[} in regexp
284 @cindex @samp{]} in regexp
285 is a @dfn{character alternative}, which begins with @samp{[} and is
286 terminated by @samp{]}.  In the simplest case, the characters between
287 the two brackets are what this character alternative can match.
289 Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
290 @samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
291 (including the empty string), from which it follows that @samp{c[ad]*r}
292 matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
294 You can also include character ranges in a character alternative, by
295 writing the starting and ending characters with a @samp{-} between them.
296 Thus, @samp{[a-z]} matches any lower-case @sc{ascii} letter.  Ranges may be
297 intermixed freely with individual characters, as in @samp{[a-z$%.]},
298 which matches any lower case @sc{ascii} letter or @samp{$}, @samp{%} or
299 period.
301 Note that the usual regexp special characters are not special inside a
302 character alternative.  A completely different set of characters is
303 special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
305 To include a @samp{]} in a character alternative, you must make it the
306 first character.  For example, @samp{[]a]} matches @samp{]} or @samp{a}.
307 To include a @samp{-}, write @samp{-} as the first or last character of
308 the character alternative, or put it after a range.  Thus, @samp{[]-]}
309 matches both @samp{]} and @samp{-}.
311 To include @samp{^} in a character alternative, put it anywhere but at
312 the beginning.
314 The beginning and end of a range must be in the same character set
315 (@pxref{Character Sets}).  Thus, @samp{[a-\x8e0]} is invalid because
316 @samp{a} is in the @sc{ascii} character set but the character 0x8e0
317 (@samp{a} with grave accent) is in the Emacs character set for Latin-1.
319 You cannot always match all non-@sc{ascii} characters with the regular
320 expression @samp{[\200-\377]}.  This works when searching a unibyte
321 buffer or string (@pxref{Text Representations}), but not in a multibyte
322 buffer or string, because many non-@sc{ascii} characters have codes
323 above octal 0377.  However, the regular expression @samp{[^\000-\177]}
324 does match all non-@sc{ascii} characters (see below regarding @samp{^}),
325 in both multibyte and unibyte representations, because only the
326 @sc{ascii} characters are excluded.
328 Starting in Emacs 21, a character alternative can also specify named
329 character classes (@pxref{Char Classes}).  This is a POSIX feature whose
330 syntax is @samp{[:@var{class}:]}.  Using a character class is equivalent
331 to mentioning each of the characters in that class; but the latter is
332 not feasible in practice, since some classes include thousands of
333 different characters.
335 @item @samp{[^ @dots{} ]}
336 @cindex @samp{^} in regexp
337 @samp{[^} begins a @dfn{complemented character alternative}, which matches any
338 character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
339 all characters @emph{except} letters and digits.
341 @samp{^} is not special in a character alternative unless it is the first
342 character.  The character following the @samp{^} is treated as if it
343 were first (in other words, @samp{-} and @samp{]} are not special there).
345 A complemented character alternative can match a newline, unless newline is
346 mentioned as one of the characters not to match.  This is in contrast to
347 the handling of regexps in programs such as @code{grep}.
349 @item @samp{^}
350 @cindex beginning of line in regexp
351 is a special character that matches the empty string, but only at the
352 beginning of a line in the text being matched.  Otherwise it fails to
353 match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
354 the beginning of a line.
356 When matching a string instead of a buffer, @samp{^} matches at the
357 beginning of the string or after a newline character @samp{\n}.
359 For historical compatibility reasons, @samp{^} can be used only at the
360 beginning of the regular expression, or after @samp{\(} or @samp{\|}.
362 @item @samp{$}
363 @cindex @samp{$} in regexp
364 @cindex end of line in regexp
365 is similar to @samp{^} but matches only at the end of a line.  Thus,
366 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
368 When matching a string instead of a buffer, @samp{$} matches at the end
369 of the string or before a newline character @samp{\n}.
371 For historical compatibility reasons, @samp{$} can be used only at the
372 end of the regular expression, or before @samp{\)} or @samp{\|}.
374 @item @samp{\}
375 @cindex @samp{\} in regexp
376 has two functions: it quotes the special characters (including
377 @samp{\}), and it introduces additional special constructs.
379 Because @samp{\} quotes special characters, @samp{\$} is a regular
380 expression that matches only @samp{$}, and @samp{\[} is a regular
381 expression that matches only @samp{[}, and so on.
383 Note that @samp{\} also has special meaning in the read syntax of Lisp
384 strings (@pxref{String Type}), and must be quoted with @samp{\}.  For
385 example, the regular expression that matches the @samp{\} character is
386 @samp{\\}.  To write a Lisp string that contains the characters
387 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
388 @samp{\}.  Therefore, the read syntax for a regular expression matching
389 @samp{\} is @code{"\\\\"}.@refill
390 @end table
392 @strong{Please note:} For historical compatibility, special characters
393 are treated as ordinary ones if they are in contexts where their special
394 meanings make no sense.  For example, @samp{*foo} treats @samp{*} as
395 ordinary since there is no preceding expression on which the @samp{*}
396 can act.  It is poor practice to depend on this behavior; quote the
397 special character anyway, regardless of where it appears.@refill
399 @node Char Classes
400 @subsubsection Character Classes
401 @cindex character classes in regexp
403   Here is a table of the classes you can use in a character alternative,
404 in Emacs 21, and what they mean:
406 @table @samp
407 @item [:ascii:]
408 This matches any @sc{ascii} (unibyte) character.
409 @item [:alnum:]
410 This matches any letter or digit.  (At present, for multibyte
411 characters, it matches anything that has word syntax.)
412 @item [:alpha:]
413 This matches any letter.  (At present, for multibyte characters, it
414 matches anything that has word syntax.)
415 @item [:blank:]
416 This matches space and tab only.
417 @item [:cntrl:]
418 This matches any @sc{ascii} control character.
419 @item [:digit:]
420 This matches @samp{0} through @samp{9}.  Thus, @samp{[-+[:digit:]]}
421 matches any digit, as well as @samp{+} and @samp{-}.
422 @item [:graph:]
423 This matches graphic characters---everything except @sc{ascii} control
424 characters, space, and the delete character.
425 @item [:lower:]
426 This matches any lower-case letter, as determined by
427 the current case table (@pxref{Case Tables}).
428 @item [:nonascii:]
429 This matches any non-@sc{ascii} (multibyte) character.
430 @item [:print:]
431 This matches printing characters---everything except @sc{ascii} control
432 characters and the delete character.
433 @item [:punct:]
434 This matches any punctuation character.  (At present, for multibyte
435 characters, it matches anything that has non-word syntax.)
436 @item [:space:]
437 This matches any character that has whitespace syntax
438 (@pxref{Syntax Class Table}).
439 @item [:upper:]
440 This matches any upper-case letter, as determined by
441 the current case table (@pxref{Case Tables}).
442 @item [:word:]
443 This matches any character that has word syntax (@pxref{Syntax Class
444 Table}).
445 @item [:xdigit:]
446 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
447 through @samp{f} and @samp{A} through @samp{F}.
448 @end table
450 @node Regexp Backslash
451 @subsubsection Backslash Constructs in Regular Expressions
453   For the most part, @samp{\} followed by any character matches only
454 that character.  However, there are several exceptions: certain
455 two-character sequences starting with @samp{\} that have special
456 meanings.  (The character after the @samp{\} in such a sequence is
457 always ordinary when used on its own.)  Here is a table of the special
458 @samp{\} constructs.
460 @table @samp
461 @item \|
462 @cindex @samp{|} in regexp
463 @cindex regexp alternative
464 specifies an alternative.
465 Two regular expressions @var{a} and @var{b} with @samp{\|} in
466 between form an expression that matches anything that either @var{a} or
467 @var{b} matches.@refill
469 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
470 but no other string.@refill
472 @samp{\|} applies to the largest possible surrounding expressions.  Only a
473 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
474 @samp{\|}.@refill
476 Full backtracking capability exists to handle multiple uses of
477 @samp{\|}, if you use the POSIX regular expression functions
478 (@pxref{POSIX Regexps}).
480 @item \@{@var{m}\@}
481 is a postfix operator that repeats the previous pattern exactly @var{m}
482 times.  Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
483 and nothing else.  @samp{c[ad]\@{3\@}r} matches string such as
484 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
486 @item \@{@var{m},@var{n}\@}
487 is more general postfix operator that specifies repetition with a
488 minimum of @var{m} repeats and a maximum of @var{n} repeats.  If @var{m}
489 is omitted, the minimum is 0; if @var{n} is omitted, there is no
490 maximum.
492 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
493 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
494 nothing else.@*
495 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.  @*
496 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.    @*
497 @samp{\@{1,\@}} is equivalent to @samp{+}.
499 @item \( @dots{} \)
500 @cindex @samp{(} in regexp
501 @cindex @samp{)} in regexp
502 @cindex regexp grouping
503 is a grouping construct that serves three purposes:
505 @enumerate
506 @item
507 To enclose a set of @samp{\|} alternatives for other operations.  Thus,
508 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
509 or @samp{barx}.
511 @item
512 To enclose a complicated expression for the postfix operators @samp{*},
513 @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
514 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
515 number (zero or more) of @samp{na} strings.
517 @item
518 To record a matched substring for future reference with
519 @samp{\@var{digit}} (see below).
520 @end enumerate
522 This last application is not a consequence of the idea of a
523 parenthetical grouping; it is a separate feature that was assigned as a
524 second meaning to the same @samp{\( @dots{} \)} construct because, in
525 pratice, there was usually no conflict between the two meanings.  But
526 occasionally there is a conflict, and that led to the introduction of
527 shy groups.
529 @item \(?: @dots{} \)
530 is the @dfn{shy group} construct.  A shy group serves the first two
531 purposes of an ordinary group (controlling the nesting of other
532 operators), but it does not get a number, so you cannot refer back to
533 its value with @samp{\@var{digit}}.
535 Shy groups are particulary useful for mechanically-constructed regular
536 expressions because they can be added automatically without altering the
537 numbering of any ordinary, non-shy groups.
539 @item \@var{digit}
540 matches the same text that matched the @var{digit}th occurrence of a
541 @samp{\( @dots{} \)} construct.
543 In other words, after the end of a @samp{\( @dots{} \)} construct, the
544 matcher remembers the beginning and end of the text matched by that
545 construct.  Then, later on in the regular expression, you can use
546 @samp{\} followed by @var{digit} to match that same text, whatever it
547 may have been.
549 The strings matching the first nine @samp{\( @dots{} \)} constructs
550 appearing in a regular expression are assigned numbers 1 through 9 in
551 the order that the open parentheses appear in the regular expression.
552 So you can use @samp{\1} through @samp{\9} to refer to the text matched
553 by the corresponding @samp{\( @dots{} \)} constructs.
555 For example, @samp{\(.*\)\1} matches any newline-free string that is
556 composed of two identical halves.  The @samp{\(.*\)} matches the first
557 half, which may be anything, but the @samp{\1} that follows must match
558 the same exact text.
560 @item \w
561 @cindex @samp{\w} in regexp
562 matches any word-constituent character.  The editor syntax table
563 determines which characters these are.  @xref{Syntax Tables}.
565 @item \W
566 @cindex @samp{\W} in regexp
567 matches any character that is not a word constituent.
569 @item \s@var{code}
570 @cindex @samp{\s} in regexp
571 matches any character whose syntax is @var{code}.  Here @var{code} is a
572 character that represents a syntax code: thus, @samp{w} for word
573 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
574 etc.  To represent whitespace syntax, use either @samp{-} or a space
575 character.  @xref{Syntax Class Table}, for a list of syntax codes and
576 the characters that stand for them.
578 @item \S@var{code}
579 @cindex @samp{\S} in regexp
580 matches any character whose syntax is not @var{code}.
581 @end table
583   The following regular expression constructs match the empty string---that is,
584 they don't use up any characters---but whether they match depends on the
585 context.
587 @table @samp
588 @item \`
589 @cindex @samp{\`} in regexp
590 matches the empty string, but only at the beginning
591 of the buffer or string being matched against.
593 @item \'
594 @cindex @samp{\'} in regexp
595 matches the empty string, but only at the end of
596 the buffer or string being matched against.
598 @item \=
599 @cindex @samp{\=} in regexp
600 matches the empty string, but only at point.
601 (This construct is not defined when matching against a string.)
603 @item \b
604 @cindex @samp{\b} in regexp
605 matches the empty string, but only at the beginning or
606 end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
607 @samp{foo} as a separate word.  @samp{\bballs?\b} matches
608 @samp{ball} or @samp{balls} as a separate word.@refill
610 @samp{\b} matches at the beginning or end of the buffer
611 regardless of what text appears next to it.
613 @item \B
614 @cindex @samp{\B} in regexp
615 matches the empty string, but @emph{not} at the beginning or
616 end of a word.
618 @item \<
619 @cindex @samp{\<} in regexp
620 matches the empty string, but only at the beginning of a word.
621 @samp{\<} matches at the beginning of the buffer only if a
622 word-constituent character follows.
624 @item \>
625 @cindex @samp{\>} in regexp
626 matches the empty string, but only at the end of a word.  @samp{\>}
627 matches at the end of the buffer only if the contents end with a
628 word-constituent character.
629 @end table
631 @kindex invalid-regexp
632   Not every string is a valid regular expression.  For example, a string
633 with unbalanced square brackets is invalid (with a few exceptions, such
634 as @samp{[]]}), and so is a string that ends with a single @samp{\}.  If
635 an invalid regular expression is passed to any of the search functions,
636 an @code{invalid-regexp} error is signaled.
638 @node Regexp Example
639 @comment  node-name,  next,  previous,  up
640 @subsection Complex Regexp Example
642   Here is a complicated regexp, used by Emacs to recognize the end of a
643 sentence together with any whitespace that follows.  It is the value of
644 the variable @code{sentence-end}.  
646   First, we show the regexp as a string in Lisp syntax to distinguish
647 spaces from tab characters.  The string constant begins and ends with a
648 double-quote.  @samp{\"} stands for a double-quote as part of the
649 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
650 tab and @samp{\n} for a newline.
652 @example
653 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
654 @end example
656 @noindent
657 In contrast, if you evaluate the variable @code{sentence-end}, you
658 will see the following:
660 @example
661 @group
662 sentence-end
663      @result{} "[.?!][]\"')@}]*\\($\\| $\\|  \\|  \\)[       
665 @end group
666 @end example
668 @noindent
669 In this output, tab and newline appear as themselves.
671   This regular expression contains four parts in succession and can be
672 deciphered as follows:
674 @table @code
675 @item [.?!]
676 The first part of the pattern is a character alternative that matches
677 any one of three characters: period, question mark, and exclamation
678 mark.  The match must begin with one of these three characters.
680 @item []\"')@}]*
681 The second part of the pattern matches any closing braces and quotation
682 marks, zero or more of them, that may follow the period, question mark
683 or exclamation mark.  The @code{\"} is Lisp syntax for a double-quote in
684 a string.  The @samp{*} at the end indicates that the immediately
685 preceding regular expression (a character alternative, in this case) may be
686 repeated zero or more times.
688 @item \\($\\|@ $\\|\t\\|@ @ \\)
689 The third part of the pattern matches the whitespace that follows the
690 end of a sentence: the end of a line (optionally with a space), or a
691 tab, or two spaces.  The double backslashes mark the parentheses and
692 vertical bars as regular expression syntax; the parentheses delimit a
693 group and the vertical bars separate alternatives.  The dollar sign is
694 used to match the end of a line.
696 @item [ \t\n]*
697 Finally, the last part of the pattern matches any additional whitespace
698 beyond the minimum needed to end a sentence.
699 @end table
701 @node Regexp Functions
702 @subsection Regular Expression Functions
704   These functions operate on regular expressions.
706 @defun regexp-quote string
707 This function returns a regular expression whose only exact match is
708 @var{string}.  Using this regular expression in @code{looking-at} will
709 succeed only if the next characters in the buffer are @var{string};
710 using it in a search function will succeed if the text being searched
711 contains @var{string}.
713 This allows you to request an exact string match or search when calling
714 a function that wants a regular expression.
716 @example
717 @group
718 (regexp-quote "^The cat$")
719      @result{} "\\^The cat\\$"
720 @end group
721 @end example
723 One use of @code{regexp-quote} is to combine an exact string match with
724 context described as a regular expression.  For example, this searches
725 for the string that is the value of @var{string}, surrounded by
726 whitespace:
728 @example
729 @group
730 (re-search-forward
731  (concat "\\s-" (regexp-quote string) "\\s-"))
732 @end group
733 @end example
734 @end defun
736 @defun regexp-opt strings &optional paren
737 This function returns an efficient regular expression that will match
738 any of the strings @var{strings}.  This is useful when you need to make
739 matching or searching as fast as possible---for example, for Font Lock
740 mode.
742 If the optional argument @var{paren} is non-@code{nil}, then the
743 returned regular expression is always enclosed by at least one
744 parentheses-grouping construct.
746 This simplified definition of @code{regexp-opt} produces a
747 regular expression which is equivalent to the actual value
748 (but not as efficient):
750 @example
751 (defun regexp-opt (strings paren)
752   (let ((open-paren (if paren "\\(" ""))
753         (close-paren (if paren "\\)" "")))
754     (concat open-paren
755             (mapconcat 'regexp-quote strings "\\|")
756             close-paren)))
757 @end example
758 @end defun
760 @defun regexp-opt-depth regexp
761 This function returns the total number of grouping constructs
762 (parenthesized expressions) in @var{regexp}.
763 @end defun
765 @node Regexp Search
766 @section Regular Expression Searching
767 @cindex regular expression searching
768 @cindex regexp searching
769 @cindex searching for regexp
771   In GNU Emacs, you can search for the next match for a regular
772 expression either incrementally or not.  For incremental search
773 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
774 The GNU Emacs Manual}.  Here we describe only the search functions
775 useful in programs.  The principal one is @code{re-search-forward}.
777   These search functions convert the regular expression to multibyte if
778 the buffer is multibyte; they convert the regular expression to unibyte
779 if the buffer is unibyte.  @xref{Text Representations}.
781 @deffn Command re-search-forward regexp &optional limit noerror repeat
782 This function searches forward in the current buffer for a string of
783 text that is matched by the regular expression @var{regexp}.  The
784 function skips over any amount of text that is not matched by
785 @var{regexp}, and leaves point at the end of the first match found.
786 It returns the new value of point.
788 If @var{limit} is non-@code{nil} (it must be a position in the current
789 buffer), then it is the upper bound to the search.  No match extending
790 after that position is accepted.
792 If @var{repeat} is supplied (it must be a positive number), then the
793 search is repeated that many times (each time starting at the end of the
794 previous time's match).  If all these successive searches succeed, the
795 function succeeds, moving point and returning its new value.  Otherwise
796 the function fails.
798 What happens when the function fails depends on the value of
799 @var{noerror}.  If @var{noerror} is @code{nil}, a @code{search-failed}
800 error is signaled.  If @var{noerror} is @code{t},
801 @code{re-search-forward} does nothing and returns @code{nil}.  If
802 @var{noerror} is neither @code{nil} nor @code{t}, then
803 @code{re-search-forward} moves point to @var{limit} (or the end of the
804 buffer) and returns @code{nil}.
806 In the following example, point is initially before the @samp{T}.
807 Evaluating the search call moves point to the end of that line (between
808 the @samp{t} of @samp{hat} and the newline).
810 @example
811 @group
812 ---------- Buffer: foo ----------
813 I read "@point{}The cat in the hat
814 comes back" twice.
815 ---------- Buffer: foo ----------
816 @end group
818 @group
819 (re-search-forward "[a-z]+" nil t 5)
820      @result{} 27
822 ---------- Buffer: foo ----------
823 I read "The cat in the hat@point{}
824 comes back" twice.
825 ---------- Buffer: foo ----------
826 @end group
827 @end example
828 @end deffn
830 @deffn Command re-search-backward regexp &optional limit noerror repeat
831 This function searches backward in the current buffer for a string of
832 text that is matched by the regular expression @var{regexp}, leaving
833 point at the beginning of the first text found.
835 This function is analogous to @code{re-search-forward}, but they are not
836 simple mirror images.  @code{re-search-forward} finds the match whose
837 beginning is as close as possible to the starting point.  If
838 @code{re-search-backward} were a perfect mirror image, it would find the
839 match whose end is as close as possible.  However, in fact it finds the
840 match whose beginning is as close as possible.  The reason for this is that
841 matching a regular expression at a given spot always works from
842 beginning to end, and starts at a specified beginning position.
844 A true mirror-image of @code{re-search-forward} would require a special
845 feature for matching regular expressions from end to beginning.  It's
846 not worth the trouble of implementing that.
847 @end deffn
849 @defun string-match regexp string &optional start
850 This function returns the index of the start of the first match for
851 the regular expression @var{regexp} in @var{string}, or @code{nil} if
852 there is no match.  If @var{start} is non-@code{nil}, the search starts
853 at that index in @var{string}.
855 For example,
857 @example
858 @group
859 (string-match
860  "quick" "The quick brown fox jumped quickly.")
861      @result{} 4
862 @end group
863 @group
864 (string-match
865  "quick" "The quick brown fox jumped quickly." 8)
866      @result{} 27
867 @end group
868 @end example
870 @noindent
871 The index of the first character of the
872 string is 0, the index of the second character is 1, and so on.
874 After this function returns, the index of the first character beyond
875 the match is available as @code{(match-end 0)}.  @xref{Match Data}.
877 @example
878 @group
879 (string-match
880  "quick" "The quick brown fox jumped quickly." 8)
881      @result{} 27
882 @end group
884 @group
885 (match-end 0)
886      @result{} 32
887 @end group
888 @end example
889 @end defun
891 @defun looking-at regexp
892 This function determines whether the text in the current buffer directly
893 following point matches the regular expression @var{regexp}.  ``Directly
894 following'' means precisely that: the search is ``anchored'' and it can
895 succeed only starting with the first character following point.  The
896 result is @code{t} if so, @code{nil} otherwise.
898 This function does not move point, but it updates the match data, which
899 you can access using @code{match-beginning} and @code{match-end}.
900 @xref{Match Data}.
902 In this example, point is located directly before the @samp{T}.  If it
903 were anywhere else, the result would be @code{nil}.
905 @example
906 @group
907 ---------- Buffer: foo ----------
908 I read "@point{}The cat in the hat
909 comes back" twice.
910 ---------- Buffer: foo ----------
912 (looking-at "The cat in the hat$")
913      @result{} t
914 @end group
915 @end example
916 @end defun
918 @node POSIX Regexps
919 @section POSIX Regular Expression Searching
921   The usual regular expression functions do backtracking when necessary
922 to handle the @samp{\|} and repetition constructs, but they continue
923 this only until they find @emph{some} match.  Then they succeed and
924 report the first match found.
926   This section describes alternative search functions which perform the
927 full backtracking specified by the POSIX standard for regular expression
928 matching.  They continue backtracking until they have tried all
929 possibilities and found all matches, so they can report the longest
930 match, as required by POSIX.  This is much slower, so use these
931 functions only when you really need the longest match.
933 @defun posix-search-forward regexp &optional limit noerror repeat
934 This is like @code{re-search-forward} except that it performs the full
935 backtracking specified by the POSIX standard for regular expression
936 matching.
937 @end defun
939 @defun posix-search-backward regexp &optional limit noerror repeat
940 This is like @code{re-search-backward} except that it performs the full
941 backtracking specified by the POSIX standard for regular expression
942 matching.
943 @end defun
945 @defun posix-looking-at regexp
946 This is like @code{looking-at} except that it performs the full
947 backtracking specified by the POSIX standard for regular expression
948 matching.
949 @end defun
951 @defun posix-string-match regexp string &optional start
952 This is like @code{string-match} except that it performs the full
953 backtracking specified by the POSIX standard for regular expression
954 matching.
955 @end defun
957 @ignore
958 @deffn Command delete-matching-lines regexp
959 This function is identical to @code{delete-non-matching-lines}, save
960 that it deletes what @code{delete-non-matching-lines} keeps.
962 In the example below, point is located on the first line of text.
964 @example
965 @group
966 ---------- Buffer: foo ----------
967 We hold these truths
968 to be self-evident,
969 that all men are created
970 equal, and that they are
971 ---------- Buffer: foo ----------
972 @end group
974 @group
975 (delete-matching-lines "the")
976      @result{} nil
978 ---------- Buffer: foo ----------
979 to be self-evident,
980 that all men are created
981 ---------- Buffer: foo ----------
982 @end group
983 @end example
984 @end deffn
986 @deffn Command flush-lines regexp
987 This function is the same as @code{delete-matching-lines}.
988 @end deffn
990 @defun delete-non-matching-lines regexp
991 This function deletes all lines following point which don't
992 contain a match for the regular expression @var{regexp}.
993 @end defun
995 @deffn Command keep-lines regexp
996 This function is the same as @code{delete-non-matching-lines}.
997 @end deffn
999 @deffn Command how-many regexp
1000 This function counts the number of matches for @var{regexp} there are in
1001 the current buffer following point.  It prints this number in
1002 the echo area, returning the string printed.
1003 @end deffn
1005 @deffn Command count-matches regexp
1006 This function is a synonym of @code{how-many}.
1007 @end deffn
1009 @deffn Command list-matching-lines regexp &optional nlines
1010 This function is a synonym of @code{occur}.
1011 Show all lines following point containing a match for @var{regexp}.
1012 Display each line with @var{nlines} lines before and after,
1013 or @code{-}@var{nlines} before if @var{nlines} is negative.
1014 @var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
1015 Interactively it is the prefix arg.
1017 The lines are shown in a buffer named @samp{*Occur*}.
1018 It serves as a menu to find any of the occurrences in this buffer.
1019 @kbd{C-h m} (@code{describe-mode}) in that buffer gives help.
1020 @end deffn
1022 @defopt list-matching-lines-default-context-lines
1023 Default value is 0.
1024 Default number of context lines to include around a @code{list-matching-lines}
1025 match.  A negative number means to include that many lines before the match.
1026 A positive number means to include that many lines both before and after.
1027 @end defopt
1028 @end ignore
1030 @node Search and Replace
1031 @section Search and Replace
1032 @cindex replacement
1034 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
1035 This function is the guts of @code{query-replace} and related commands.
1036 It searches for occurrences of @var{from-string} and replaces some or
1037 all of them.  If @var{query-flag} is @code{nil}, it replaces all
1038 occurrences; otherwise, it asks the user what to do about each one.
1040 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
1041 considered a regular expression; otherwise, it must match literally.  If
1042 @var{delimited-flag} is non-@code{nil}, then only replacements
1043 surrounded by word boundaries are considered.
1045 The argument @var{replacements} specifies what to replace occurrences
1046 with.  If it is a string, that string is used.  It can also be a list of
1047 strings, to be used in cyclic order.
1049 If @var{replacements} is a cons cell, @code{(@var{function}
1050 . @var{data})}, this means to call @var{function} after each match to
1051 get the replacement text.  This function is called with two arguments:
1052 @var{data}, and the number of replacements already made.
1054 If @var{repeat-count} is non-@code{nil}, it should be an integer.  Then
1055 it specifies how many times to use each of the strings in the
1056 @var{replacements} list before advancing cyclicly to the next one.
1058 If @var{from-string} contains upper-case letters, then
1059 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
1060 it uses the @code{replacements} without altering the case of them.
1062 Normally, the keymap @code{query-replace-map} defines the possible user
1063 responses for queries.  The argument @var{map}, if non-@code{nil}, is a
1064 keymap to use instead of @code{query-replace-map}.
1065 @end defun
1067 @defvar query-replace-map
1068 This variable holds a special keymap that defines the valid user
1069 responses for @code{query-replace} and related functions, as well as
1070 @code{y-or-n-p} and @code{map-y-or-n-p}.  It is unusual in two ways:
1072 @itemize @bullet
1073 @item
1074 The ``key bindings'' are not commands, just symbols that are meaningful
1075 to the functions that use this map.
1077 @item
1078 Prefix keys are not supported; each key binding must be for a
1079 single-event key sequence.  This is because the functions don't use
1080 @code{read-key-sequence} to get the input; instead, they read a single
1081 event and look it up ``by hand.''
1082 @end itemize
1083 @end defvar
1085 Here are the meaningful ``bindings'' for @code{query-replace-map}.
1086 Several of them are meaningful only for @code{query-replace} and
1087 friends.
1089 @table @code
1090 @item act
1091 Do take the action being considered---in other words, ``yes.''
1093 @item skip
1094 Do not take action for this question---in other words, ``no.''
1096 @item exit
1097 Answer this question ``no,'' and give up on the entire series of
1098 questions, assuming that the answers will be ``no.''
1100 @item act-and-exit
1101 Answer this question ``yes,'' and give up on the entire series of
1102 questions, assuming that subsequent answers will be ``no.''
1104 @item act-and-show
1105 Answer this question ``yes,'' but show the results---don't advance yet
1106 to the next question.
1108 @item automatic
1109 Answer this question and all subsequent questions in the series with
1110 ``yes,'' without further user interaction.
1112 @item backup
1113 Move back to the previous place that a question was asked about.
1115 @item edit
1116 Enter a recursive edit to deal with this question---instead of any
1117 other action that would normally be taken.
1119 @item delete-and-edit
1120 Delete the text being considered, then enter a recursive edit to replace
1123 @item recenter
1124 Redisplay and center the window, then ask the same question again.
1126 @item quit
1127 Perform a quit right away.  Only @code{y-or-n-p} and related functions
1128 use this answer.
1130 @item help
1131 Display some help, then ask again.
1132 @end table
1134 @node Match Data
1135 @section The Match Data
1136 @cindex match data
1138   Emacs keeps track of the start and end positions of the segments of
1139 text found during a regular expression search.  This means, for example,
1140 that you can search for a complex pattern, such as a date in an Rmail
1141 message, and then extract parts of the match under control of the
1142 pattern.
1144   Because the match data normally describe the most recent search only,
1145 you must be careful not to do another search inadvertently between the
1146 search you wish to refer back to and the use of the match data.  If you
1147 can't avoid another intervening search, you must save and restore the
1148 match data around it, to prevent it from being overwritten.
1150 @menu
1151 * Replacing Match::       Replacing a substring that was matched.
1152 * Simple Match Data::     Accessing single items of match data,
1153                             such as where a particular subexpression started.
1154 * Entire Match Data::     Accessing the entire match data at once, as a list.
1155 * Saving Match Data::     Saving and restoring the match data.
1156 @end menu
1158 @node Replacing Match
1159 @subsection Replacing the Text that Matched
1161   This function replaces the text matched by the last search with
1162 @var{replacement}.
1164 @cindex case in replacements
1165 @defun replace-match replacement &optional fixedcase literal string subexp
1166 This function replaces the text in the buffer (or in @var{string}) that
1167 was matched by the last search.  It replaces that text with
1168 @var{replacement}.
1170 If you did the last search in a buffer, you should specify @code{nil}
1171 for @var{string}.  Then @code{replace-match} does the replacement by
1172 editing the buffer; it leaves point at the end of the replacement text,
1173 and returns @code{t}.
1175 If you did the search in a string, pass the same string as @var{string}.
1176 Then @code{replace-match} does the replacement by constructing and
1177 returning a new string.
1179 If @var{fixedcase} is non-@code{nil}, then the case of the replacement
1180 text is not changed; otherwise, the replacement text is converted to a
1181 different case depending upon the capitalization of the text to be
1182 replaced.  If the original text is all upper case, the replacement text
1183 is converted to upper case.  If the first word of the original text is
1184 capitalized, then the first word of the replacement text is capitalized.
1185 If the original text contains just one word, and that word is a capital
1186 letter, @code{replace-match} considers this a capitalized first word
1187 rather than all upper case.
1189 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1190 exactly as it is, the only alterations being case changes as needed.
1191 If it is @code{nil} (the default), then the character @samp{\} is treated
1192 specially.  If a @samp{\} appears in @var{replacement}, then it must be
1193 part of one of the following sequences:
1195 @table @asis
1196 @item @samp{\&}
1197 @cindex @samp{&} in replacement
1198 @samp{\&} stands for the entire text being replaced.
1200 @item @samp{\@var{n}}
1201 @cindex @samp{\@var{n}} in replacement
1202 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1203 matched the @var{n}th subexpression in the original regexp.
1204 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1206 @item @samp{\\}
1207 @cindex @samp{\} in replacement
1208 @samp{\\} stands for a single @samp{\} in the replacement text.
1209 @end table
1211 If @var{subexp} is non-@code{nil}, that says to replace just
1212 subexpression number @var{subexp} of the regexp that was matched, not
1213 the entire match.  For example, after matching @samp{foo \(ba*r\)},
1214 calling @code{replace-match} with 1 as @var{subexp} means to replace
1215 just the text that matched @samp{\(ba*r\)}.
1216 @end defun
1218 @node Simple Match Data
1219 @subsection Simple Match Data Access
1221   This section explains how to use the match data to find out what was
1222 matched by the last search or match operation.
1224   You can ask about the entire matching text, or about a particular
1225 parenthetical subexpression of a regular expression.  The @var{count}
1226 argument in the functions below specifies which.  If @var{count} is
1227 zero, you are asking about the entire match.  If @var{count} is
1228 positive, it specifies which subexpression you want.
1230   Recall that the subexpressions of a regular expression are those
1231 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}.  The
1232 @var{count}th subexpression is found by counting occurrences of
1233 @samp{\(} from the beginning of the whole regular expression.  The first
1234 subexpression is numbered 1, the second 2, and so on.  Only regular
1235 expressions can have subexpressions---after a simple string search, the
1236 only information available is about the entire match.
1238   A search which fails may or may not alter the match data.  In the
1239 past, a failing search did not do this, but we may change it in the
1240 future.
1242 @defun match-string count &optional in-string
1243 This function returns, as a string, the text matched in the last search
1244 or match operation.  It returns the entire text if @var{count} is zero,
1245 or just the portion corresponding to the @var{count}th parenthetical
1246 subexpression, if @var{count} is positive.  If @var{count} is out of
1247 range, or if that subexpression didn't match anything, the value is
1248 @code{nil}.
1250 If the last such operation was done against a string with
1251 @code{string-match}, then you should pass the same string as the
1252 argument @var{in-string}.  After a buffer search or match,
1253 you should omit @var{in-string} or pass @code{nil} for it; but you
1254 should make sure that the current buffer when you call
1255 @code{match-string} is the one in which you did the searching or
1256 matching.
1257 @end defun
1259 @defun match-string-no-properties count &optional in-string
1260 This function is like @code{match-string} except that the result
1261 has no text properties.
1262 @end defun
1264 @defun match-beginning count
1265 This function returns the position of the start of text matched by the
1266 last regular expression searched for, or a subexpression of it.
1268 If @var{count} is zero, then the value is the position of the start of
1269 the entire match.  Otherwise, @var{count} specifies a subexpression in
1270 the regular expression, and the value of the function is the starting
1271 position of the match for that subexpression.
1273 The value is @code{nil} for a subexpression inside a @samp{\|}
1274 alternative that wasn't used in the match.
1275 @end defun
1277 @defun match-end count
1278 This function is like @code{match-beginning} except that it returns the
1279 position of the end of the match, rather than the position of the
1280 beginning.
1281 @end defun
1283   Here is an example of using the match data, with a comment showing the
1284 positions within the text:
1286 @example
1287 @group
1288 (string-match "\\(qu\\)\\(ick\\)"
1289               "The quick fox jumped quickly.")
1290               ;0123456789      
1291      @result{} 4
1292 @end group
1294 @group
1295 (match-string 0 "The quick fox jumped quickly.")
1296      @result{} "quick"
1297 (match-string 1 "The quick fox jumped quickly.")
1298      @result{} "qu"
1299 (match-string 2 "The quick fox jumped quickly.")
1300      @result{} "ick"
1301 @end group
1303 @group
1304 (match-beginning 1)       ; @r{The beginning of the match}
1305      @result{} 4                 ;   @r{with @samp{qu} is at index 4.}
1306 @end group
1308 @group
1309 (match-beginning 2)       ; @r{The beginning of the match}
1310      @result{} 6                 ;   @r{with @samp{ick} is at index 6.}
1311 @end group
1313 @group
1314 (match-end 1)             ; @r{The end of the match}
1315      @result{} 6                 ;   @r{with @samp{qu} is at index 6.}
1317 (match-end 2)             ; @r{The end of the match}
1318      @result{} 9                 ;   @r{with @samp{ick} is at index 9.}
1319 @end group
1320 @end example
1322   Here is another example.  Point is initially located at the beginning
1323 of the line.  Searching moves point to between the space and the word
1324 @samp{in}.  The beginning of the entire match is at the 9th character of
1325 the buffer (@samp{T}), and the beginning of the match for the first
1326 subexpression is at the 13th character (@samp{c}).
1328 @example
1329 @group
1330 (list
1331   (re-search-forward "The \\(cat \\)")
1332   (match-beginning 0)
1333   (match-beginning 1))
1334     @result{} (9 9 13)
1335 @end group
1337 @group
1338 ---------- Buffer: foo ----------
1339 I read "The cat @point{}in the hat comes back" twice.
1340         ^   ^
1341         9  13
1342 ---------- Buffer: foo ----------
1343 @end group
1344 @end example
1346 @noindent
1347 (In this case, the index returned is a buffer position; the first
1348 character of the buffer counts as 1.)
1350 @node Entire Match Data
1351 @subsection Accessing the Entire Match Data
1353   The functions @code{match-data} and @code{set-match-data} read or
1354 write the entire match data, all at once.
1356 @defun match-data
1357 This function returns a newly constructed list containing all the
1358 information on what text the last search matched.  Element zero is the
1359 position of the beginning of the match for the whole expression; element
1360 one is the position of the end of the match for the expression.  The
1361 next two elements are the positions of the beginning and end of the
1362 match for the first subexpression, and so on.  In general, element
1363 @ifnottex
1364 number 2@var{n}
1365 @end ifnottex
1366 @tex
1367 number {\mathsurround=0pt $2n$}
1368 @end tex
1369 corresponds to @code{(match-beginning @var{n})}; and
1370 element
1371 @ifnottex
1372 number 2@var{n} + 1
1373 @end ifnottex
1374 @tex
1375 number {\mathsurround=0pt $2n+1$}
1376 @end tex
1377 corresponds to @code{(match-end @var{n})}.
1379 All the elements are markers or @code{nil} if matching was done on a
1380 buffer, and all are integers or @code{nil} if matching was done on a
1381 string with @code{string-match}.
1383 As always, there must be no possibility of intervening searches between
1384 the call to a search function and the call to @code{match-data} that is
1385 intended to access the match data for that search.
1387 @example
1388 @group
1389 (match-data)
1390      @result{}  (#<marker at 9 in foo>
1391           #<marker at 17 in foo>
1392           #<marker at 13 in foo>
1393           #<marker at 17 in foo>)
1394 @end group
1395 @end example
1396 @end defun
1398 @defun set-match-data match-list
1399 This function sets the match data from the elements of @var{match-list},
1400 which should be a list that was the value of a previous call to
1401 @code{match-data}.
1403 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1404 an error; that sets the match data in a meaningless but harmless way.
1406 @findex store-match-data
1407 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1408 @end defun
1410 @node Saving Match Data
1411 @subsection Saving and Restoring the Match Data
1413   When you call a function that may do a search, you may need to save
1414 and restore the match data around that call, if you want to preserve the
1415 match data from an earlier search for later use.  Here is an example
1416 that shows the problem that arises if you fail to save the match data:
1418 @example
1419 @group
1420 (re-search-forward "The \\(cat \\)")
1421      @result{} 48
1422 (foo)                   ; @r{Perhaps @code{foo} does}
1423                         ;   @r{more searching.}
1424 (match-end 0)
1425      @result{} 61              ; @r{Unexpected result---not 48!}
1426 @end group
1427 @end example
1429   You can save and restore the match data with @code{save-match-data}:
1431 @defmac save-match-data body@dots{}
1432 This macro executes @var{body}, saving and restoring the match
1433 data around it.
1434 @end defmac
1436   You could use @code{set-match-data} together with @code{match-data} to
1437 imitate the effect of the special form @code{save-match-data}.  Here is
1438 how:
1440 @example
1441 @group
1442 (let ((data (match-data)))
1443   (unwind-protect
1444       @dots{}   ; @r{Ok to change the original match data.}
1445     (set-match-data data)))
1446 @end group
1447 @end example
1449   Emacs automatically saves and restores the match data when it runs
1450 process filter functions (@pxref{Filter Functions}) and process
1451 sentinels (@pxref{Sentinels}).
1453 @ignore
1454   Here is a function which restores the match data provided the buffer
1455 associated with it still exists.
1457 @smallexample
1458 @group
1459 (defun restore-match-data (data)
1460 @c It is incorrect to split the first line of a doc string.
1461 @c If there's a problem here, it should be solved in some other way.
1462   "Restore the match data DATA unless the buffer is missing."
1463   (catch 'foo
1464     (let ((d data))
1465 @end group
1466       (while d
1467         (and (car d)
1468              (null (marker-buffer (car d)))
1469 @group
1470              ;; @file{match-data} @r{buffer is deleted.}
1471              (throw 'foo nil))
1472         (setq d (cdr d)))
1473       (set-match-data data))))
1474 @end group
1475 @end smallexample
1476 @end ignore
1478 @node Searching and Case
1479 @section Searching and Case
1480 @cindex searching and case
1482   By default, searches in Emacs ignore the case of the text they are
1483 searching through; if you specify searching for @samp{FOO}, then
1484 @samp{Foo} or @samp{foo} is also considered a match.  This applies to
1485 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
1486 @samp{A} or @samp{b} or @samp{B}.
1488   If you do not want this feature, set the variable
1489 @code{case-fold-search} to @code{nil}.  Then all letters must match
1490 exactly, including case.  This is a buffer-local variable; altering the
1491 variable affects only the current buffer.  (@xref{Intro to
1492 Buffer-Local}.)  Alternatively, you may change the value of
1493 @code{default-case-fold-search}, which is the default value of
1494 @code{case-fold-search} for buffers that do not override it.
1496   Note that the user-level incremental search feature handles case
1497 distinctions differently.  When given a lower case letter, it looks for
1498 a match of either case, but when given an upper case letter, it looks
1499 for an upper case letter only.  But this has nothing to do with the
1500 searching functions used in Lisp code.
1502 @defopt case-replace
1503 This variable determines whether the replacement functions should
1504 preserve case.  If the variable is @code{nil}, that means to use the
1505 replacement text verbatim.  A non-@code{nil} value means to convert the
1506 case of the replacement text according to the text being replaced.
1508 This variable is used by passing it as an argument to the function
1509 @code{replace-match}.  @xref{Replacing Match}.
1510 @end defopt
1512 @defopt case-fold-search
1513 This buffer-local variable determines whether searches should ignore
1514 case.  If the variable is @code{nil} they do not ignore case; otherwise
1515 they do ignore case.
1516 @end defopt
1518 @defvar default-case-fold-search
1519 The value of this variable is the default value for
1520 @code{case-fold-search} in buffers that do not override it.  This is the
1521 same as @code{(default-value 'case-fold-search)}.
1522 @end defvar
1524 @node Standard Regexps
1525 @section Standard Regular Expressions Used in Editing
1526 @cindex regexps used standardly in editing
1527 @cindex standard regexps used in editing
1529   This section describes some variables that hold regular expressions
1530 used for certain purposes in editing:
1532 @defvar page-delimiter
1533 This is the regular expression describing line-beginnings that separate
1534 pages.  The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1535 @code{"^\C-l"}); this matches a line that starts with a formfeed
1536 character.
1537 @end defvar
1539   The following two regular expressions should @emph{not} assume the
1540 match always starts at the beginning of a line; they should not use
1541 @samp{^} to anchor the match.  Most often, the paragraph commands do
1542 check for a match only at the beginning of a line, which means that
1543 @samp{^} would be superfluous.  When there is a nonzero left margin,
1544 they accept matches that start after the left margin.  In that case, a
1545 @samp{^} would be incorrect.  However, a @samp{^} is harmless in modes
1546 where a left margin is never used.
1548 @defvar paragraph-separate
1549 This is the regular expression for recognizing the beginning of a line
1550 that separates paragraphs.  (If you change this, you may have to
1551 change @code{paragraph-start} also.)  The default value is
1552 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1553 spaces, tabs, and form feeds (after its left margin).
1554 @end defvar
1556 @defvar paragraph-start
1557 This is the regular expression for recognizing the beginning of a line
1558 that starts @emph{or} separates paragraphs.  The default value is
1559 @w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
1560 newline, or form feed (after its left margin).
1561 @end defvar
1563 @defvar sentence-end
1564 This is the regular expression describing the end of a sentence.  (All
1565 paragraph boundaries also end sentences, regardless.)  The default value
1568 @example
1569 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
1570 @end example
1572 This means a period, question mark or exclamation mark, followed
1573 optionally by a closing parenthetical character, followed by tabs,
1574 spaces or new lines.
1576 For a detailed explanation of this regular expression, see @ref{Regexp
1577 Example}.
1578 @end defvar