*** empty log message ***
[emacs.git] / lispref / searching.texi
blobe23be33e440271afe39704aa88e2c77ef74ae4c0
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 of multibyte characters must be in the
315 same character set (@pxref{Character Sets}).  Thus, @samp{[\x8e0-\x97c]}
316 is invalid because character 0x8e0 (@samp{a} with grave accent) is in
317 the Emacs character set for Latin-1 but the character 0x97c (@samp{u}
318 with diaeresis) is in the Emacs character set for Latin-2.
320 If a range starts with a unibyte character @var{c} and ends with a
321 multibyte character @var{c2}, the range is divided into two parts: one
322 is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
323 @var{c1} is the first character of the charset to which @var{c2}
324 belongs.
326 You cannot always match all non-@sc{ascii} characters with the regular
327 expression @samp{[\200-\377]}.  This works when searching a unibyte
328 buffer or string (@pxref{Text Representations}), but not in a multibyte
329 buffer or string, because many non-@sc{ascii} characters have codes
330 above octal 0377.  However, the regular expression @samp{[^\000-\177]}
331 does match all non-@sc{ascii} characters (see below regarding @samp{^}),
332 in both multibyte and unibyte representations, because only the
333 @sc{ascii} characters are excluded.
335 Starting in Emacs 21, a character alternative can also specify named
336 character classes (@pxref{Char Classes}).  This is a POSIX feature whose
337 syntax is @samp{[:@var{class}:]}.  Using a character class is equivalent
338 to mentioning each of the characters in that class; but the latter is
339 not feasible in practice, since some classes include thousands of
340 different characters.
342 @item @samp{[^ @dots{} ]}
343 @cindex @samp{^} in regexp
344 @samp{[^} begins a @dfn{complemented character alternative}, which matches any
345 character except the ones specified.  Thus, @samp{[^a-z0-9A-Z]} matches
346 all characters @emph{except} letters and digits.
348 @samp{^} is not special in a character alternative unless it is the first
349 character.  The character following the @samp{^} is treated as if it
350 were first (in other words, @samp{-} and @samp{]} are not special there).
352 A complemented character alternative can match a newline, unless newline is
353 mentioned as one of the characters not to match.  This is in contrast to
354 the handling of regexps in programs such as @code{grep}.
356 @item @samp{^}
357 @cindex beginning of line in regexp
358 is a special character that matches the empty string, but only at the
359 beginning of a line in the text being matched.  Otherwise it fails to
360 match anything.  Thus, @samp{^foo} matches a @samp{foo} that occurs at
361 the beginning of a line.
363 When matching a string instead of a buffer, @samp{^} matches at the
364 beginning of the string or after a newline character @samp{\n}.
366 For historical compatibility reasons, @samp{^} can be used only at the
367 beginning of the regular expression, or after @samp{\(} or @samp{\|}.
369 @item @samp{$}
370 @cindex @samp{$} in regexp
371 @cindex end of line in regexp
372 is similar to @samp{^} but matches only at the end of a line.  Thus,
373 @samp{x+$} matches a string of one @samp{x} or more at the end of a line.
375 When matching a string instead of a buffer, @samp{$} matches at the end
376 of the string or before a newline character @samp{\n}.
378 For historical compatibility reasons, @samp{$} can be used only at the
379 end of the regular expression, or before @samp{\)} or @samp{\|}.
381 @item @samp{\}
382 @cindex @samp{\} in regexp
383 has two functions: it quotes the special characters (including
384 @samp{\}), and it introduces additional special constructs.
386 Because @samp{\} quotes special characters, @samp{\$} is a regular
387 expression that matches only @samp{$}, and @samp{\[} is a regular
388 expression that matches only @samp{[}, and so on.
390 Note that @samp{\} also has special meaning in the read syntax of Lisp
391 strings (@pxref{String Type}), and must be quoted with @samp{\}.  For
392 example, the regular expression that matches the @samp{\} character is
393 @samp{\\}.  To write a Lisp string that contains the characters
394 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another
395 @samp{\}.  Therefore, the read syntax for a regular expression matching
396 @samp{\} is @code{"\\\\"}.@refill
397 @end table
399 @strong{Please note:} For historical compatibility, special characters
400 are treated as ordinary ones if they are in contexts where their special
401 meanings make no sense.  For example, @samp{*foo} treats @samp{*} as
402 ordinary since there is no preceding expression on which the @samp{*}
403 can act.  It is poor practice to depend on this behavior; quote the
404 special character anyway, regardless of where it appears.@refill
406 @node Char Classes
407 @subsubsection Character Classes
408 @cindex character classes in regexp
410   Here is a table of the classes you can use in a character alternative,
411 in Emacs 21, and what they mean:
413 @table @samp
414 @item [:ascii:]
415 This matches any @sc{ascii} (unibyte) character.
416 @item [:alnum:]
417 This matches any letter or digit.  (At present, for multibyte
418 characters, it matches anything that has word syntax.)
419 @item [:alpha:]
420 This matches any letter.  (At present, for multibyte characters, it
421 matches anything that has word syntax.)
422 @item [:blank:]
423 This matches space and tab only.
424 @item [:cntrl:]
425 This matches any @sc{ascii} control character.
426 @item [:digit:]
427 This matches @samp{0} through @samp{9}.  Thus, @samp{[-+[:digit:]]}
428 matches any digit, as well as @samp{+} and @samp{-}.
429 @item [:graph:]
430 This matches graphic characters---everything except @sc{ascii} control
431 characters, space, and the delete character.
432 @item [:lower:]
433 This matches any lower-case letter, as determined by
434 the current case table (@pxref{Case Tables}).
435 @item [:nonascii:]
436 This matches any non-@sc{ascii} (multibyte) character.
437 @item [:print:]
438 This matches printing characters---everything except @sc{ascii} control
439 characters and the delete character.
440 @item [:punct:]
441 This matches any punctuation character.  (At present, for multibyte
442 characters, it matches anything that has non-word syntax.)
443 @item [:space:]
444 This matches any character that has whitespace syntax
445 (@pxref{Syntax Class Table}).
446 @item [:upper:]
447 This matches any upper-case letter, as determined by
448 the current case table (@pxref{Case Tables}).
449 @item [:word:]
450 This matches any character that has word syntax (@pxref{Syntax Class
451 Table}).
452 @item [:xdigit:]
453 This matches the hexadecimal digits: @samp{0} through @samp{9}, @samp{a}
454 through @samp{f} and @samp{A} through @samp{F}.
455 @end table
457 @node Regexp Backslash
458 @subsubsection Backslash Constructs in Regular Expressions
460   For the most part, @samp{\} followed by any character matches only
461 that character.  However, there are several exceptions: certain
462 two-character sequences starting with @samp{\} that have special
463 meanings.  (The character after the @samp{\} in such a sequence is
464 always ordinary when used on its own.)  Here is a table of the special
465 @samp{\} constructs.
467 @table @samp
468 @item \|
469 @cindex @samp{|} in regexp
470 @cindex regexp alternative
471 specifies an alternative.
472 Two regular expressions @var{a} and @var{b} with @samp{\|} in
473 between form an expression that matches anything that either @var{a} or
474 @var{b} matches.@refill
476 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}
477 but no other string.@refill
479 @samp{\|} applies to the largest possible surrounding expressions.  Only a
480 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of
481 @samp{\|}.@refill
483 Full backtracking capability exists to handle multiple uses of
484 @samp{\|}, if you use the POSIX regular expression functions
485 (@pxref{POSIX Regexps}).
487 @item \@{@var{m}\@}
488 is a postfix operator that repeats the previous pattern exactly @var{m}
489 times.  Thus, @samp{x\@{5\@}} matches the string @samp{xxxxx}
490 and nothing else.  @samp{c[ad]\@{3\@}r} matches string such as
491 @samp{caaar}, @samp{cdddr}, @samp{cadar}, and so on.
493 @item \@{@var{m},@var{n}\@}
494 is more general postfix operator that specifies repetition with a
495 minimum of @var{m} repeats and a maximum of @var{n} repeats.  If @var{m}
496 is omitted, the minimum is 0; if @var{n} is omitted, there is no
497 maximum.
499 For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
500 @samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
501 nothing else.@*
502 @samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.  @*
503 @samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.    @*
504 @samp{\@{1,\@}} is equivalent to @samp{+}.
506 @item \( @dots{} \)
507 @cindex @samp{(} in regexp
508 @cindex @samp{)} in regexp
509 @cindex regexp grouping
510 is a grouping construct that serves three purposes:
512 @enumerate
513 @item
514 To enclose a set of @samp{\|} alternatives for other operations.  Thus,
515 the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
516 or @samp{barx}.
518 @item
519 To enclose a complicated expression for the postfix operators @samp{*},
520 @samp{+} and @samp{?} to operate on.  Thus, @samp{ba\(na\)*} matches
521 @samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
522 number (zero or more) of @samp{na} strings.
524 @item
525 To record a matched substring for future reference with
526 @samp{\@var{digit}} (see below).
527 @end enumerate
529 This last application is not a consequence of the idea of a
530 parenthetical grouping; it is a separate feature that was assigned as a
531 second meaning to the same @samp{\( @dots{} \)} construct because, in
532 pratice, there was usually no conflict between the two meanings.  But
533 occasionally there is a conflict, and that led to the introduction of
534 shy groups.
536 @item \(?: @dots{} \)
537 is the @dfn{shy group} construct.  A shy group serves the first two
538 purposes of an ordinary group (controlling the nesting of other
539 operators), but it does not get a number, so you cannot refer back to
540 its value with @samp{\@var{digit}}.
542 Shy groups are particulary useful for mechanically-constructed regular
543 expressions because they can be added automatically without altering the
544 numbering of any ordinary, non-shy groups.
546 @item \@var{digit}
547 matches the same text that matched the @var{digit}th occurrence of a
548 @samp{\( @dots{} \)} construct.
550 In other words, after the end of a @samp{\( @dots{} \)} construct, the
551 matcher remembers the beginning and end of the text matched by that
552 construct.  Then, later on in the regular expression, you can use
553 @samp{\} followed by @var{digit} to match that same text, whatever it
554 may have been.
556 The strings matching the first nine @samp{\( @dots{} \)} constructs
557 appearing in a regular expression are assigned numbers 1 through 9 in
558 the order that the open parentheses appear in the regular expression.
559 So you can use @samp{\1} through @samp{\9} to refer to the text matched
560 by the corresponding @samp{\( @dots{} \)} constructs.
562 For example, @samp{\(.*\)\1} matches any newline-free string that is
563 composed of two identical halves.  The @samp{\(.*\)} matches the first
564 half, which may be anything, but the @samp{\1} that follows must match
565 the same exact text.
567 @item \w
568 @cindex @samp{\w} in regexp
569 matches any word-constituent character.  The editor syntax table
570 determines which characters these are.  @xref{Syntax Tables}.
572 @item \W
573 @cindex @samp{\W} in regexp
574 matches any character that is not a word constituent.
576 @item \s@var{code}
577 @cindex @samp{\s} in regexp
578 matches any character whose syntax is @var{code}.  Here @var{code} is a
579 character that represents a syntax code: thus, @samp{w} for word
580 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
581 etc.  To represent whitespace syntax, use either @samp{-} or a space
582 character.  @xref{Syntax Class Table}, for a list of syntax codes and
583 the characters that stand for them.
585 @item \S@var{code}
586 @cindex @samp{\S} in regexp
587 matches any character whose syntax is not @var{code}.
589 @item \c@var{c}
590 matches any character whose category is @var{c}.  Here @var{c} is a
591 character that represents a category: thus, @samp{c} for Chinese
592 characters or @samp{g} for Greek characters in the standard category
593 table.
595 @item \C@var{c}
596 matches any character whose category is not @var{c}.
597 @end table
599   The following regular expression constructs match the empty string---that is,
600 they don't use up any characters---but whether they match depends on the
601 context.
603 @table @samp
604 @item \`
605 @cindex @samp{\`} in regexp
606 matches the empty string, but only at the beginning
607 of the buffer or string being matched against.
609 @item \'
610 @cindex @samp{\'} in regexp
611 matches the empty string, but only at the end of
612 the buffer or string being matched against.
614 @item \=
615 @cindex @samp{\=} in regexp
616 matches the empty string, but only at point.
617 (This construct is not defined when matching against a string.)
619 @item \b
620 @cindex @samp{\b} in regexp
621 matches the empty string, but only at the beginning or
622 end of a word.  Thus, @samp{\bfoo\b} matches any occurrence of
623 @samp{foo} as a separate word.  @samp{\bballs?\b} matches
624 @samp{ball} or @samp{balls} as a separate word.@refill
626 @samp{\b} matches at the beginning or end of the buffer
627 regardless of what text appears next to it.
629 @item \B
630 @cindex @samp{\B} in regexp
631 matches the empty string, but @emph{not} at the beginning or
632 end of a word.
634 @item \<
635 @cindex @samp{\<} in regexp
636 matches the empty string, but only at the beginning of a word.
637 @samp{\<} matches at the beginning of the buffer only if a
638 word-constituent character follows.
640 @item \>
641 @cindex @samp{\>} in regexp
642 matches the empty string, but only at the end of a word.  @samp{\>}
643 matches at the end of the buffer only if the contents end with a
644 word-constituent character.
645 @end table
647 @kindex invalid-regexp
648   Not every string is a valid regular expression.  For example, a string
649 with unbalanced square brackets is invalid (with a few exceptions, such
650 as @samp{[]]}), and so is a string that ends with a single @samp{\}.  If
651 an invalid regular expression is passed to any of the search functions,
652 an @code{invalid-regexp} error is signaled.
654 @node Regexp Example
655 @comment  node-name,  next,  previous,  up
656 @subsection Complex Regexp Example
658   Here is a complicated regexp, used by Emacs to recognize the end of a
659 sentence together with any whitespace that follows.  It is the value of
660 the variable @code{sentence-end}.  
662   First, we show the regexp as a string in Lisp syntax to distinguish
663 spaces from tab characters.  The string constant begins and ends with a
664 double-quote.  @samp{\"} stands for a double-quote as part of the
665 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a
666 tab and @samp{\n} for a newline.
668 @example
669 "[.?!][]\"')@}]*\\($\\| $\\|\t\\|  \\)[ \t\n]*"
670 @end example
672 @noindent
673 In contrast, if you evaluate the variable @code{sentence-end}, you
674 will see the following:
676 @example
677 @group
678 sentence-end
679      @result{} "[.?!][]\"')@}]*\\($\\| $\\|  \\|  \\)[       
681 @end group
682 @end example
684 @noindent
685 In this output, tab and newline appear as themselves.
687   This regular expression contains four parts in succession and can be
688 deciphered as follows:
690 @table @code
691 @item [.?!]
692 The first part of the pattern is a character alternative that matches
693 any one of three characters: period, question mark, and exclamation
694 mark.  The match must begin with one of these three characters.
696 @item []\"')@}]*
697 The second part of the pattern matches any closing braces and quotation
698 marks, zero or more of them, that may follow the period, question mark
699 or exclamation mark.  The @code{\"} is Lisp syntax for a double-quote in
700 a string.  The @samp{*} at the end indicates that the immediately
701 preceding regular expression (a character alternative, in this case) may be
702 repeated zero or more times.
704 @item \\($\\|@ $\\|\t\\|@ @ \\)
705 The third part of the pattern matches the whitespace that follows the
706 end of a sentence: the end of a line (optionally with a space), or a
707 tab, or two spaces.  The double backslashes mark the parentheses and
708 vertical bars as regular expression syntax; the parentheses delimit a
709 group and the vertical bars separate alternatives.  The dollar sign is
710 used to match the end of a line.
712 @item [ \t\n]*
713 Finally, the last part of the pattern matches any additional whitespace
714 beyond the minimum needed to end a sentence.
715 @end table
717 @node Regexp Functions
718 @subsection Regular Expression Functions
720   These functions operate on regular expressions.
722 @defun regexp-quote string
723 This function returns a regular expression whose only exact match is
724 @var{string}.  Using this regular expression in @code{looking-at} will
725 succeed only if the next characters in the buffer are @var{string};
726 using it in a search function will succeed if the text being searched
727 contains @var{string}.
729 This allows you to request an exact string match or search when calling
730 a function that wants a regular expression.
732 @example
733 @group
734 (regexp-quote "^The cat$")
735      @result{} "\\^The cat\\$"
736 @end group
737 @end example
739 One use of @code{regexp-quote} is to combine an exact string match with
740 context described as a regular expression.  For example, this searches
741 for the string that is the value of @var{string}, surrounded by
742 whitespace:
744 @example
745 @group
746 (re-search-forward
747  (concat "\\s-" (regexp-quote string) "\\s-"))
748 @end group
749 @end example
750 @end defun
752 @defun regexp-opt strings &optional paren
753 This function returns an efficient regular expression that will match
754 any of the strings @var{strings}.  This is useful when you need to make
755 matching or searching as fast as possible---for example, for Font Lock
756 mode.
758 If the optional argument @var{paren} is non-@code{nil}, then the
759 returned regular expression is always enclosed by at least one
760 parentheses-grouping construct.
762 This simplified definition of @code{regexp-opt} produces a
763 regular expression which is equivalent to the actual value
764 (but not as efficient):
766 @example
767 (defun regexp-opt (strings paren)
768   (let ((open-paren (if paren "\\(" ""))
769         (close-paren (if paren "\\)" "")))
770     (concat open-paren
771             (mapconcat 'regexp-quote strings "\\|")
772             close-paren)))
773 @end example
774 @end defun
776 @defun regexp-opt-depth regexp
777 This function returns the total number of grouping constructs
778 (parenthesized expressions) in @var{regexp}.
779 @end defun
781 @node Regexp Search
782 @section Regular Expression Searching
783 @cindex regular expression searching
784 @cindex regexp searching
785 @cindex searching for regexp
787   In GNU Emacs, you can search for the next match for a regular
788 expression either incrementally or not.  For incremental search
789 commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
790 The GNU Emacs Manual}.  Here we describe only the search functions
791 useful in programs.  The principal one is @code{re-search-forward}.
793   These search functions convert the regular expression to multibyte if
794 the buffer is multibyte; they convert the regular expression to unibyte
795 if the buffer is unibyte.  @xref{Text Representations}.
797 @deffn Command re-search-forward regexp &optional limit noerror repeat
798 This function searches forward in the current buffer for a string of
799 text that is matched by the regular expression @var{regexp}.  The
800 function skips over any amount of text that is not matched by
801 @var{regexp}, and leaves point at the end of the first match found.
802 It returns the new value of point.
804 If @var{limit} is non-@code{nil} (it must be a position in the current
805 buffer), then it is the upper bound to the search.  No match extending
806 after that position is accepted.
808 If @var{repeat} is supplied (it must be a positive number), then the
809 search is repeated that many times (each time starting at the end of the
810 previous time's match).  If all these successive searches succeed, the
811 function succeeds, moving point and returning its new value.  Otherwise
812 the function fails.
814 What happens when the function fails depends on the value of
815 @var{noerror}.  If @var{noerror} is @code{nil}, a @code{search-failed}
816 error is signaled.  If @var{noerror} is @code{t},
817 @code{re-search-forward} does nothing and returns @code{nil}.  If
818 @var{noerror} is neither @code{nil} nor @code{t}, then
819 @code{re-search-forward} moves point to @var{limit} (or the end of the
820 buffer) and returns @code{nil}.
822 In the following example, point is initially before the @samp{T}.
823 Evaluating the search call moves point to the end of that line (between
824 the @samp{t} of @samp{hat} and the newline).
826 @example
827 @group
828 ---------- Buffer: foo ----------
829 I read "@point{}The cat in the hat
830 comes back" twice.
831 ---------- Buffer: foo ----------
832 @end group
834 @group
835 (re-search-forward "[a-z]+" nil t 5)
836      @result{} 27
838 ---------- Buffer: foo ----------
839 I read "The cat in the hat@point{}
840 comes back" twice.
841 ---------- Buffer: foo ----------
842 @end group
843 @end example
844 @end deffn
846 @deffn Command re-search-backward regexp &optional limit noerror repeat
847 This function searches backward in the current buffer for a string of
848 text that is matched by the regular expression @var{regexp}, leaving
849 point at the beginning of the first text found.
851 This function is analogous to @code{re-search-forward}, but they are not
852 simple mirror images.  @code{re-search-forward} finds the match whose
853 beginning is as close as possible to the starting point.  If
854 @code{re-search-backward} were a perfect mirror image, it would find the
855 match whose end is as close as possible.  However, in fact it finds the
856 match whose beginning is as close as possible.  The reason for this is that
857 matching a regular expression at a given spot always works from
858 beginning to end, and starts at a specified beginning position.
860 A true mirror-image of @code{re-search-forward} would require a special
861 feature for matching regular expressions from end to beginning.  It's
862 not worth the trouble of implementing that.
863 @end deffn
865 @defun string-match regexp string &optional start
866 This function returns the index of the start of the first match for
867 the regular expression @var{regexp} in @var{string}, or @code{nil} if
868 there is no match.  If @var{start} is non-@code{nil}, the search starts
869 at that index in @var{string}.
871 For example,
873 @example
874 @group
875 (string-match
876  "quick" "The quick brown fox jumped quickly.")
877      @result{} 4
878 @end group
879 @group
880 (string-match
881  "quick" "The quick brown fox jumped quickly." 8)
882      @result{} 27
883 @end group
884 @end example
886 @noindent
887 The index of the first character of the
888 string is 0, the index of the second character is 1, and so on.
890 After this function returns, the index of the first character beyond
891 the match is available as @code{(match-end 0)}.  @xref{Match Data}.
893 @example
894 @group
895 (string-match
896  "quick" "The quick brown fox jumped quickly." 8)
897      @result{} 27
898 @end group
900 @group
901 (match-end 0)
902      @result{} 32
903 @end group
904 @end example
905 @end defun
907 @defun looking-at regexp
908 This function determines whether the text in the current buffer directly
909 following point matches the regular expression @var{regexp}.  ``Directly
910 following'' means precisely that: the search is ``anchored'' and it can
911 succeed only starting with the first character following point.  The
912 result is @code{t} if so, @code{nil} otherwise.
914 This function does not move point, but it updates the match data, which
915 you can access using @code{match-beginning} and @code{match-end}.
916 @xref{Match Data}.
918 In this example, point is located directly before the @samp{T}.  If it
919 were anywhere else, the result would be @code{nil}.
921 @example
922 @group
923 ---------- Buffer: foo ----------
924 I read "@point{}The cat in the hat
925 comes back" twice.
926 ---------- Buffer: foo ----------
928 (looking-at "The cat in the hat$")
929      @result{} t
930 @end group
931 @end example
932 @end defun
934 @node POSIX Regexps
935 @section POSIX Regular Expression Searching
937   The usual regular expression functions do backtracking when necessary
938 to handle the @samp{\|} and repetition constructs, but they continue
939 this only until they find @emph{some} match.  Then they succeed and
940 report the first match found.
942   This section describes alternative search functions which perform the
943 full backtracking specified by the POSIX standard for regular expression
944 matching.  They continue backtracking until they have tried all
945 possibilities and found all matches, so they can report the longest
946 match, as required by POSIX.  This is much slower, so use these
947 functions only when you really need the longest match.
949 @defun posix-search-forward regexp &optional limit noerror repeat
950 This is like @code{re-search-forward} except that it performs the full
951 backtracking specified by the POSIX standard for regular expression
952 matching.
953 @end defun
955 @defun posix-search-backward regexp &optional limit noerror repeat
956 This is like @code{re-search-backward} except that it performs the full
957 backtracking specified by the POSIX standard for regular expression
958 matching.
959 @end defun
961 @defun posix-looking-at regexp
962 This is like @code{looking-at} except that it performs the full
963 backtracking specified by the POSIX standard for regular expression
964 matching.
965 @end defun
967 @defun posix-string-match regexp string &optional start
968 This is like @code{string-match} except that it performs the full
969 backtracking specified by the POSIX standard for regular expression
970 matching.
971 @end defun
973 @ignore
974 @deffn Command delete-matching-lines regexp
975 This function is identical to @code{delete-non-matching-lines}, save
976 that it deletes what @code{delete-non-matching-lines} keeps.
978 In the example below, point is located on the first line of text.
980 @example
981 @group
982 ---------- Buffer: foo ----------
983 We hold these truths
984 to be self-evident,
985 that all men are created
986 equal, and that they are
987 ---------- Buffer: foo ----------
988 @end group
990 @group
991 (delete-matching-lines "the")
992      @result{} nil
994 ---------- Buffer: foo ----------
995 to be self-evident,
996 that all men are created
997 ---------- Buffer: foo ----------
998 @end group
999 @end example
1000 @end deffn
1002 @deffn Command flush-lines regexp
1003 This function is the same as @code{delete-matching-lines}.
1004 @end deffn
1006 @defun delete-non-matching-lines regexp
1007 This function deletes all lines following point which don't
1008 contain a match for the regular expression @var{regexp}.
1009 @end defun
1011 @deffn Command keep-lines regexp
1012 This function is the same as @code{delete-non-matching-lines}.
1013 @end deffn
1015 @deffn Command how-many regexp
1016 This function counts the number of matches for @var{regexp} there are in
1017 the current buffer following point.  It prints this number in
1018 the echo area, returning the string printed.
1019 @end deffn
1021 @deffn Command count-matches regexp
1022 This function is a synonym of @code{how-many}.
1023 @end deffn
1025 @deffn Command list-matching-lines regexp &optional nlines
1026 This function is a synonym of @code{occur}.
1027 Show all lines following point containing a match for @var{regexp}.
1028 Display each line with @var{nlines} lines before and after,
1029 or @code{-}@var{nlines} before if @var{nlines} is negative.
1030 @var{nlines} defaults to @code{list-matching-lines-default-context-lines}.
1031 Interactively it is the prefix arg.
1033 The lines are shown in a buffer named @samp{*Occur*}.
1034 It serves as a menu to find any of the occurrences in this buffer.
1035 @kbd{C-h m} (@code{describe-mode}) in that buffer gives help.
1036 @end deffn
1038 @defopt list-matching-lines-default-context-lines
1039 Default value is 0.
1040 Default number of context lines to include around a @code{list-matching-lines}
1041 match.  A negative number means to include that many lines before the match.
1042 A positive number means to include that many lines both before and after.
1043 @end defopt
1044 @end ignore
1046 @node Search and Replace
1047 @section Search and Replace
1048 @cindex replacement
1050 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map
1051 This function is the guts of @code{query-replace} and related commands.
1052 It searches for occurrences of @var{from-string} and replaces some or
1053 all of them.  If @var{query-flag} is @code{nil}, it replaces all
1054 occurrences; otherwise, it asks the user what to do about each one.
1056 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is
1057 considered a regular expression; otherwise, it must match literally.  If
1058 @var{delimited-flag} is non-@code{nil}, then only replacements
1059 surrounded by word boundaries are considered.
1061 The argument @var{replacements} specifies what to replace occurrences
1062 with.  If it is a string, that string is used.  It can also be a list of
1063 strings, to be used in cyclic order.
1065 If @var{replacements} is a cons cell, @code{(@var{function}
1066 . @var{data})}, this means to call @var{function} after each match to
1067 get the replacement text.  This function is called with two arguments:
1068 @var{data}, and the number of replacements already made.
1070 If @var{repeat-count} is non-@code{nil}, it should be an integer.  Then
1071 it specifies how many times to use each of the strings in the
1072 @var{replacements} list before advancing cyclicly to the next one.
1074 If @var{from-string} contains upper-case letters, then
1075 @code{perform-replace} binds @code{case-fold-search} to @code{nil}, and
1076 it uses the @code{replacements} without altering the case of them.
1078 Normally, the keymap @code{query-replace-map} defines the possible user
1079 responses for queries.  The argument @var{map}, if non-@code{nil}, is a
1080 keymap to use instead of @code{query-replace-map}.
1081 @end defun
1083 @defvar query-replace-map
1084 This variable holds a special keymap that defines the valid user
1085 responses for @code{query-replace} and related functions, as well as
1086 @code{y-or-n-p} and @code{map-y-or-n-p}.  It is unusual in two ways:
1088 @itemize @bullet
1089 @item
1090 The ``key bindings'' are not commands, just symbols that are meaningful
1091 to the functions that use this map.
1093 @item
1094 Prefix keys are not supported; each key binding must be for a
1095 single-event key sequence.  This is because the functions don't use
1096 @code{read-key-sequence} to get the input; instead, they read a single
1097 event and look it up ``by hand.''
1098 @end itemize
1099 @end defvar
1101 Here are the meaningful ``bindings'' for @code{query-replace-map}.
1102 Several of them are meaningful only for @code{query-replace} and
1103 friends.
1105 @table @code
1106 @item act
1107 Do take the action being considered---in other words, ``yes.''
1109 @item skip
1110 Do not take action for this question---in other words, ``no.''
1112 @item exit
1113 Answer this question ``no,'' and give up on the entire series of
1114 questions, assuming that the answers will be ``no.''
1116 @item act-and-exit
1117 Answer this question ``yes,'' and give up on the entire series of
1118 questions, assuming that subsequent answers will be ``no.''
1120 @item act-and-show
1121 Answer this question ``yes,'' but show the results---don't advance yet
1122 to the next question.
1124 @item automatic
1125 Answer this question and all subsequent questions in the series with
1126 ``yes,'' without further user interaction.
1128 @item backup
1129 Move back to the previous place that a question was asked about.
1131 @item edit
1132 Enter a recursive edit to deal with this question---instead of any
1133 other action that would normally be taken.
1135 @item delete-and-edit
1136 Delete the text being considered, then enter a recursive edit to replace
1139 @item recenter
1140 Redisplay and center the window, then ask the same question again.
1142 @item quit
1143 Perform a quit right away.  Only @code{y-or-n-p} and related functions
1144 use this answer.
1146 @item help
1147 Display some help, then ask again.
1148 @end table
1150 @node Match Data
1151 @section The Match Data
1152 @cindex match data
1154   Emacs keeps track of the start and end positions of the segments of
1155 text found during a regular expression search.  This means, for example,
1156 that you can search for a complex pattern, such as a date in an Rmail
1157 message, and then extract parts of the match under control of the
1158 pattern.
1160   Because the match data normally describe the most recent search only,
1161 you must be careful not to do another search inadvertently between the
1162 search you wish to refer back to and the use of the match data.  If you
1163 can't avoid another intervening search, you must save and restore the
1164 match data around it, to prevent it from being overwritten.
1166 @menu
1167 * Replacing Match::       Replacing a substring that was matched.
1168 * Simple Match Data::     Accessing single items of match data,
1169                             such as where a particular subexpression started.
1170 * Entire Match Data::     Accessing the entire match data at once, as a list.
1171 * Saving Match Data::     Saving and restoring the match data.
1172 @end menu
1174 @node Replacing Match
1175 @subsection Replacing the Text that Matched
1177   This function replaces the text matched by the last search with
1178 @var{replacement}.
1180 @cindex case in replacements
1181 @defun replace-match replacement &optional fixedcase literal string subexp
1182 This function replaces the text in the buffer (or in @var{string}) that
1183 was matched by the last search.  It replaces that text with
1184 @var{replacement}.
1186 If you did the last search in a buffer, you should specify @code{nil}
1187 for @var{string}.  Then @code{replace-match} does the replacement by
1188 editing the buffer; it leaves point at the end of the replacement text,
1189 and returns @code{t}.
1191 If you did the search in a string, pass the same string as @var{string}.
1192 Then @code{replace-match} does the replacement by constructing and
1193 returning a new string.
1195 If @var{fixedcase} is non-@code{nil}, then the case of the replacement
1196 text is not changed; otherwise, the replacement text is converted to a
1197 different case depending upon the capitalization of the text to be
1198 replaced.  If the original text is all upper case, the replacement text
1199 is converted to upper case.  If the first word of the original text is
1200 capitalized, then the first word of the replacement text is capitalized.
1201 If the original text contains just one word, and that word is a capital
1202 letter, @code{replace-match} considers this a capitalized first word
1203 rather than all upper case.
1205 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
1206 exactly as it is, the only alterations being case changes as needed.
1207 If it is @code{nil} (the default), then the character @samp{\} is treated
1208 specially.  If a @samp{\} appears in @var{replacement}, then it must be
1209 part of one of the following sequences:
1211 @table @asis
1212 @item @samp{\&}
1213 @cindex @samp{&} in replacement
1214 @samp{\&} stands for the entire text being replaced.
1216 @item @samp{\@var{n}}
1217 @cindex @samp{\@var{n}} in replacement
1218 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that
1219 matched the @var{n}th subexpression in the original regexp.
1220 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
1222 @item @samp{\\}
1223 @cindex @samp{\} in replacement
1224 @samp{\\} stands for a single @samp{\} in the replacement text.
1225 @end table
1227 If @var{subexp} is non-@code{nil}, that says to replace just
1228 subexpression number @var{subexp} of the regexp that was matched, not
1229 the entire match.  For example, after matching @samp{foo \(ba*r\)},
1230 calling @code{replace-match} with 1 as @var{subexp} means to replace
1231 just the text that matched @samp{\(ba*r\)}.
1232 @end defun
1234 @node Simple Match Data
1235 @subsection Simple Match Data Access
1237   This section explains how to use the match data to find out what was
1238 matched by the last search or match operation.
1240   You can ask about the entire matching text, or about a particular
1241 parenthetical subexpression of a regular expression.  The @var{count}
1242 argument in the functions below specifies which.  If @var{count} is
1243 zero, you are asking about the entire match.  If @var{count} is
1244 positive, it specifies which subexpression you want.
1246   Recall that the subexpressions of a regular expression are those
1247 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}.  The
1248 @var{count}th subexpression is found by counting occurrences of
1249 @samp{\(} from the beginning of the whole regular expression.  The first
1250 subexpression is numbered 1, the second 2, and so on.  Only regular
1251 expressions can have subexpressions---after a simple string search, the
1252 only information available is about the entire match.
1254   A search which fails may or may not alter the match data.  In the
1255 past, a failing search did not do this, but we may change it in the
1256 future.
1258 @defun match-string count &optional in-string
1259 This function returns, as a string, the text matched in the last search
1260 or match operation.  It returns the entire text if @var{count} is zero,
1261 or just the portion corresponding to the @var{count}th parenthetical
1262 subexpression, if @var{count} is positive.  If @var{count} is out of
1263 range, or if that subexpression didn't match anything, the value is
1264 @code{nil}.
1266 If the last such operation was done against a string with
1267 @code{string-match}, then you should pass the same string as the
1268 argument @var{in-string}.  After a buffer search or match,
1269 you should omit @var{in-string} or pass @code{nil} for it; but you
1270 should make sure that the current buffer when you call
1271 @code{match-string} is the one in which you did the searching or
1272 matching.
1273 @end defun
1275 @defun match-string-no-properties count &optional in-string
1276 This function is like @code{match-string} except that the result
1277 has no text properties.
1278 @end defun
1280 @defun match-beginning count
1281 This function returns the position of the start of text matched by the
1282 last regular expression searched for, or a subexpression of it.
1284 If @var{count} is zero, then the value is the position of the start of
1285 the entire match.  Otherwise, @var{count} specifies a subexpression in
1286 the regular expression, and the value of the function is the starting
1287 position of the match for that subexpression.
1289 The value is @code{nil} for a subexpression inside a @samp{\|}
1290 alternative that wasn't used in the match.
1291 @end defun
1293 @defun match-end count
1294 This function is like @code{match-beginning} except that it returns the
1295 position of the end of the match, rather than the position of the
1296 beginning.
1297 @end defun
1299   Here is an example of using the match data, with a comment showing the
1300 positions within the text:
1302 @example
1303 @group
1304 (string-match "\\(qu\\)\\(ick\\)"
1305               "The quick fox jumped quickly.")
1306               ;0123456789      
1307      @result{} 4
1308 @end group
1310 @group
1311 (match-string 0 "The quick fox jumped quickly.")
1312      @result{} "quick"
1313 (match-string 1 "The quick fox jumped quickly.")
1314      @result{} "qu"
1315 (match-string 2 "The quick fox jumped quickly.")
1316      @result{} "ick"
1317 @end group
1319 @group
1320 (match-beginning 1)       ; @r{The beginning of the match}
1321      @result{} 4                 ;   @r{with @samp{qu} is at index 4.}
1322 @end group
1324 @group
1325 (match-beginning 2)       ; @r{The beginning of the match}
1326      @result{} 6                 ;   @r{with @samp{ick} is at index 6.}
1327 @end group
1329 @group
1330 (match-end 1)             ; @r{The end of the match}
1331      @result{} 6                 ;   @r{with @samp{qu} is at index 6.}
1333 (match-end 2)             ; @r{The end of the match}
1334      @result{} 9                 ;   @r{with @samp{ick} is at index 9.}
1335 @end group
1336 @end example
1338   Here is another example.  Point is initially located at the beginning
1339 of the line.  Searching moves point to between the space and the word
1340 @samp{in}.  The beginning of the entire match is at the 9th character of
1341 the buffer (@samp{T}), and the beginning of the match for the first
1342 subexpression is at the 13th character (@samp{c}).
1344 @example
1345 @group
1346 (list
1347   (re-search-forward "The \\(cat \\)")
1348   (match-beginning 0)
1349   (match-beginning 1))
1350     @result{} (9 9 13)
1351 @end group
1353 @group
1354 ---------- Buffer: foo ----------
1355 I read "The cat @point{}in the hat comes back" twice.
1356         ^   ^
1357         9  13
1358 ---------- Buffer: foo ----------
1359 @end group
1360 @end example
1362 @noindent
1363 (In this case, the index returned is a buffer position; the first
1364 character of the buffer counts as 1.)
1366 @node Entire Match Data
1367 @subsection Accessing the Entire Match Data
1369   The functions @code{match-data} and @code{set-match-data} read or
1370 write the entire match data, all at once.
1372 @defun match-data
1373 This function returns a newly constructed list containing all the
1374 information on what text the last search matched.  Element zero is the
1375 position of the beginning of the match for the whole expression; element
1376 one is the position of the end of the match for the expression.  The
1377 next two elements are the positions of the beginning and end of the
1378 match for the first subexpression, and so on.  In general, element
1379 @ifnottex
1380 number 2@var{n}
1381 @end ifnottex
1382 @tex
1383 number {\mathsurround=0pt $2n$}
1384 @end tex
1385 corresponds to @code{(match-beginning @var{n})}; and
1386 element
1387 @ifnottex
1388 number 2@var{n} + 1
1389 @end ifnottex
1390 @tex
1391 number {\mathsurround=0pt $2n+1$}
1392 @end tex
1393 corresponds to @code{(match-end @var{n})}.
1395 All the elements are markers or @code{nil} if matching was done on a
1396 buffer, and all are integers or @code{nil} if matching was done on a
1397 string with @code{string-match}.
1399 As always, there must be no possibility of intervening searches between
1400 the call to a search function and the call to @code{match-data} that is
1401 intended to access the match data for that search.
1403 @example
1404 @group
1405 (match-data)
1406      @result{}  (#<marker at 9 in foo>
1407           #<marker at 17 in foo>
1408           #<marker at 13 in foo>
1409           #<marker at 17 in foo>)
1410 @end group
1411 @end example
1412 @end defun
1414 @defun set-match-data match-list
1415 This function sets the match data from the elements of @var{match-list},
1416 which should be a list that was the value of a previous call to
1417 @code{match-data}.
1419 If @var{match-list} refers to a buffer that doesn't exist, you don't get
1420 an error; that sets the match data in a meaningless but harmless way.
1422 @findex store-match-data
1423 @code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
1424 @end defun
1426 @node Saving Match Data
1427 @subsection Saving and Restoring the Match Data
1429   When you call a function that may do a search, you may need to save
1430 and restore the match data around that call, if you want to preserve the
1431 match data from an earlier search for later use.  Here is an example
1432 that shows the problem that arises if you fail to save the match data:
1434 @example
1435 @group
1436 (re-search-forward "The \\(cat \\)")
1437      @result{} 48
1438 (foo)                   ; @r{Perhaps @code{foo} does}
1439                         ;   @r{more searching.}
1440 (match-end 0)
1441      @result{} 61              ; @r{Unexpected result---not 48!}
1442 @end group
1443 @end example
1445   You can save and restore the match data with @code{save-match-data}:
1447 @defmac save-match-data body@dots{}
1448 This macro executes @var{body}, saving and restoring the match
1449 data around it.
1450 @end defmac
1452   You could use @code{set-match-data} together with @code{match-data} to
1453 imitate the effect of the special form @code{save-match-data}.  Here is
1454 how:
1456 @example
1457 @group
1458 (let ((data (match-data)))
1459   (unwind-protect
1460       @dots{}   ; @r{Ok to change the original match data.}
1461     (set-match-data data)))
1462 @end group
1463 @end example
1465   Emacs automatically saves and restores the match data when it runs
1466 process filter functions (@pxref{Filter Functions}) and process
1467 sentinels (@pxref{Sentinels}).
1469 @ignore
1470   Here is a function which restores the match data provided the buffer
1471 associated with it still exists.
1473 @smallexample
1474 @group
1475 (defun restore-match-data (data)
1476 @c It is incorrect to split the first line of a doc string.
1477 @c If there's a problem here, it should be solved in some other way.
1478   "Restore the match data DATA unless the buffer is missing."
1479   (catch 'foo
1480     (let ((d data))
1481 @end group
1482       (while d
1483         (and (car d)
1484              (null (marker-buffer (car d)))
1485 @group
1486              ;; @file{match-data} @r{buffer is deleted.}
1487              (throw 'foo nil))
1488         (setq d (cdr d)))
1489       (set-match-data data))))
1490 @end group
1491 @end smallexample
1492 @end ignore
1494 @node Searching and Case
1495 @section Searching and Case
1496 @cindex searching and case
1498   By default, searches in Emacs ignore the case of the text they are
1499 searching through; if you specify searching for @samp{FOO}, then
1500 @samp{Foo} or @samp{foo} is also considered a match.  This applies to
1501 regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
1502 @samp{A} or @samp{b} or @samp{B}.
1504   If you do not want this feature, set the variable
1505 @code{case-fold-search} to @code{nil}.  Then all letters must match
1506 exactly, including case.  This is a buffer-local variable; altering the
1507 variable affects only the current buffer.  (@xref{Intro to
1508 Buffer-Local}.)  Alternatively, you may change the value of
1509 @code{default-case-fold-search}, which is the default value of
1510 @code{case-fold-search} for buffers that do not override it.
1512   Note that the user-level incremental search feature handles case
1513 distinctions differently.  When given a lower case letter, it looks for
1514 a match of either case, but when given an upper case letter, it looks
1515 for an upper case letter only.  But this has nothing to do with the
1516 searching functions used in Lisp code.
1518 @defopt case-replace
1519 This variable determines whether the replacement functions should
1520 preserve case.  If the variable is @code{nil}, that means to use the
1521 replacement text verbatim.  A non-@code{nil} value means to convert the
1522 case of the replacement text according to the text being replaced.
1524 This variable is used by passing it as an argument to the function
1525 @code{replace-match}.  @xref{Replacing Match}.
1526 @end defopt
1528 @defopt case-fold-search
1529 This buffer-local variable determines whether searches should ignore
1530 case.  If the variable is @code{nil} they do not ignore case; otherwise
1531 they do ignore case.
1532 @end defopt
1534 @defvar default-case-fold-search
1535 The value of this variable is the default value for
1536 @code{case-fold-search} in buffers that do not override it.  This is the
1537 same as @code{(default-value 'case-fold-search)}.
1538 @end defvar
1540 @node Standard Regexps
1541 @section Standard Regular Expressions Used in Editing
1542 @cindex regexps used standardly in editing
1543 @cindex standard regexps used in editing
1545   This section describes some variables that hold regular expressions
1546 used for certain purposes in editing:
1548 @defvar page-delimiter
1549 This is the regular expression describing line-beginnings that separate
1550 pages.  The default value is @code{"^\014"} (i.e., @code{"^^L"} or
1551 @code{"^\C-l"}); this matches a line that starts with a formfeed
1552 character.
1553 @end defvar
1555   The following two regular expressions should @emph{not} assume the
1556 match always starts at the beginning of a line; they should not use
1557 @samp{^} to anchor the match.  Most often, the paragraph commands do
1558 check for a match only at the beginning of a line, which means that
1559 @samp{^} would be superfluous.  When there is a nonzero left margin,
1560 they accept matches that start after the left margin.  In that case, a
1561 @samp{^} would be incorrect.  However, a @samp{^} is harmless in modes
1562 where a left margin is never used.
1564 @defvar paragraph-separate
1565 This is the regular expression for recognizing the beginning of a line
1566 that separates paragraphs.  (If you change this, you may have to
1567 change @code{paragraph-start} also.)  The default value is
1568 @w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
1569 spaces, tabs, and form feeds (after its left margin).
1570 @end defvar
1572 @defvar paragraph-start
1573 This is the regular expression for recognizing the beginning of a line
1574 that starts @emph{or} separates paragraphs.  The default value is
1575 @w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,
1576 newline, or form feed (after its left margin).
1577 @end defvar
1579 @defvar sentence-end
1580 This is the regular expression describing the end of a sentence.  (All
1581 paragraph boundaries also end sentences, regardless.)  The default value
1584 @example
1585 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
1586 @end example
1588 This means a period, question mark or exclamation mark, followed
1589 optionally by a closing parenthetical character, followed by tabs,
1590 spaces or new lines.
1592 For a detailed explanation of this regular expression, see @ref{Regexp
1593 Example}.
1594 @end defvar