Mercurial > hg > xemacs-beta
annotate man/lispref/searching.texi @ 5610:d69ea1ff4ce3
Add the zero, *then* flush, when reading integers for the #N=... syntax.
src/ChangeLog addition:
2011-12-10 Aidan Kehoe <kehoea@parhasard.net>
* lread.c (read1): Add the zero, *then* flush, when reading an
integer into Vread_buffer_stream.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Sat, 10 Dec 2011 16:17:49 +0000 |
| parents | a46c5c8d6564 |
| children | 3df910176b6a |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/searching.info | |
| 6 @node Searching and Matching, Syntax Tables, Text, Top | |
| 7 @chapter Searching and Matching | |
| 8 @cindex searching | |
| 9 | |
| 10 XEmacs provides two ways to search through a buffer for specified | |
| 11 text: exact string searches and regular expression searches. After a | |
| 12 regular expression search, you can examine the @dfn{match data} to | |
| 13 determine which text matched the whole regular expression or various | |
| 14 portions of it. | |
| 15 | |
| 16 @menu | |
| 17 * String Search:: Search for an exact match. | |
| 18 * Regular Expressions:: Describing classes of strings. | |
| 19 * Regexp Search:: Searching for a match for a regexp. | |
| 20 * POSIX Regexps:: Searching POSIX-style for the longest match. | |
| 21 * Search and Replace:: Internals of @code{query-replace}. | |
| 22 * Match Data:: Finding out which part of the text matched | |
| 23 various parts of a regexp, after regexp search. | |
| 24 * Searching and Case:: Case-independent or case-significant searching. | |
| 25 * Standard Regexps:: Useful regexps for finding sentences, pages,... | |
| 26 @end menu | |
| 27 | |
| 28 The @samp{skip-chars@dots{}} functions also perform a kind of searching. | |
| 29 @xref{Skipping Characters}. | |
| 30 | |
| 31 @node String Search | |
| 32 @section Searching for Strings | |
| 33 @cindex string search | |
| 34 | |
| 35 These are the primitive functions for searching through the text in a | |
| 36 buffer. They are meant for use in programs, but you may call them | |
| 37 interactively. If you do so, they prompt for the search string; | |
| 444 | 38 @var{limit} and @var{noerror} are set to @code{nil}, and @var{count} |
| 428 | 39 is set to 1. |
| 40 | |
| 444 | 41 @deffn Command search-forward string &optional limit noerror count buffer |
| 428 | 42 This function searches forward from point for an exact match for |
| 43 @var{string}. If successful, it sets point to the end of the occurrence | |
| 44 found, and returns the new value of point. If no match is found, the | |
| 45 value and side effects depend on @var{noerror} (see below). | |
| 46 | |
| 47 In the following example, point is initially at the beginning of the | |
| 48 line. Then @code{(search-forward "fox")} moves point after the last | |
| 49 letter of @samp{fox}: | |
| 50 | |
| 51 @example | |
| 52 @group | |
| 53 ---------- Buffer: foo ---------- | |
| 54 @point{}The quick brown fox jumped over the lazy dog. | |
| 55 ---------- Buffer: foo ---------- | |
| 56 @end group | |
| 57 | |
| 58 @group | |
| 59 (search-forward "fox") | |
| 60 @result{} 20 | |
| 61 | |
| 62 ---------- Buffer: foo ---------- | |
| 63 The quick brown fox@point{} jumped over the lazy dog. | |
| 64 ---------- Buffer: foo ---------- | |
| 65 @end group | |
| 66 @end example | |
| 67 | |
| 68 The argument @var{limit} specifies the upper bound to the search. (It | |
| 69 must be a position in the current buffer.) No match extending after | |
| 70 that position is accepted. If @var{limit} is omitted or @code{nil}, it | |
| 71 defaults to the end of the accessible portion of the buffer. | |
| 72 | |
| 73 @kindex search-failed | |
| 74 What happens when the search fails depends on the value of | |
| 75 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} | |
| 76 error is signaled. If @var{noerror} is @code{t}, @code{search-forward} | |
| 77 returns @code{nil} and does nothing. If @var{noerror} is neither | |
| 78 @code{nil} nor @code{t}, then @code{search-forward} moves point to the | |
| 79 upper bound and returns @code{nil}. (It would be more consistent now | |
| 80 to return the new position of point in that case, but some programs | |
| 81 may depend on a value of @code{nil}.) | |
| 82 | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4199
diff
changeset
|
83 If @var{count} is supplied (it must be a fixnum), then the search is |
| 444 | 84 repeated that many times (each time starting at the end of the previous |
| 85 time's match). If @var{count} is negative, the search direction is | |
| 86 backward. If the successive searches succeed, the function succeeds, | |
| 87 moving point and returning its new value. Otherwise the search fails. | |
| 88 | |
| 89 @var{buffer} is the buffer to search in, and defaults to the current buffer. | |
| 428 | 90 @end deffn |
| 91 | |
| 444 | 92 @deffn Command search-backward string &optional limit noerror count buffer |
| 428 | 93 This function searches backward from point for @var{string}. It is |
| 94 just like @code{search-forward} except that it searches backwards and | |
| 95 leaves point at the beginning of the match. | |
| 96 @end deffn | |
| 97 | |
| 444 | 98 @deffn Command word-search-forward string &optional limit noerror count buffer |
| 428 | 99 @cindex word search |
| 100 This function searches forward from point for a ``word'' match for | |
| 101 @var{string}. If it finds a match, it sets point to the end of the | |
| 102 match found, and returns the new value of point. | |
| 103 | |
| 104 Word matching regards @var{string} as a sequence of words, disregarding | |
| 105 punctuation that separates them. It searches the buffer for the same | |
| 106 sequence of words. Each word must be distinct in the buffer (searching | |
| 107 for the word @samp{ball} does not match the word @samp{balls}), but the | |
| 108 details of punctuation and spacing are ignored (searching for @samp{ball | |
| 109 boy} does match @samp{ball. Boy!}). | |
| 110 | |
| 111 In this example, point is initially at the beginning of the buffer; the | |
| 112 search leaves it between the @samp{y} and the @samp{!}. | |
| 113 | |
| 114 @example | |
| 115 @group | |
| 116 ---------- Buffer: foo ---------- | |
| 117 @point{}He said "Please! Find | |
| 118 the ball boy!" | |
| 119 ---------- Buffer: foo ---------- | |
| 120 @end group | |
| 121 | |
| 122 @group | |
| 123 (word-search-forward "Please find the ball, boy.") | |
| 124 @result{} 35 | |
| 125 | |
| 126 ---------- Buffer: foo ---------- | |
| 127 He said "Please! Find | |
| 128 the ball boy@point{}!" | |
| 129 ---------- Buffer: foo ---------- | |
| 130 @end group | |
| 131 @end example | |
| 132 | |
| 133 If @var{limit} is non-@code{nil} (it must be a position in the current | |
| 134 buffer), then it is the upper bound to the search. The match found must | |
| 135 not extend after that position. | |
| 136 | |
| 137 If @var{noerror} is @code{nil}, then @code{word-search-forward} signals | |
| 138 an error if the search fails. If @var{noerror} is @code{t}, then it | |
| 139 returns @code{nil} instead of signaling an error. If @var{noerror} is | |
| 140 neither @code{nil} nor @code{t}, it moves point to @var{limit} (or the | |
| 141 end of the buffer) and returns @code{nil}. | |
| 142 | |
| 444 | 143 If @var{count} is non-@code{nil}, then the search is repeated that many |
| 428 | 144 times. Point is positioned at the end of the last match. |
| 444 | 145 |
| 146 @var{buffer} is the buffer to search in, and defaults to the current buffer. | |
| 428 | 147 @end deffn |
| 148 | |
| 444 | 149 @deffn Command word-search-backward string &optional limit noerror count buffer |
| 428 | 150 This function searches backward from point for a word match to |
| 151 @var{string}. This function is just like @code{word-search-forward} | |
| 152 except that it searches backward and normally leaves point at the | |
| 153 beginning of the match. | |
| 154 @end deffn | |
| 155 | |
| 156 @node Regular Expressions | |
| 157 @section Regular Expressions | |
| 158 @cindex regular expression | |
| 159 @cindex regexp | |
| 160 | |
| 161 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that | |
| 162 denotes a (possibly infinite) set of strings. Searching for matches for | |
| 163 a regexp is a very powerful operation. This section explains how to write | |
| 164 regexps; the following section says how to search for them. | |
| 165 | |
| 166 To gain a thorough understanding of regular expressions and how to use | |
| 167 them to best advantage, we recommend that you study @cite{Mastering | |
| 168 Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates, | |
| 169 1997}. (It's known as the "Hip Owls" book, because of the picture on its | |
| 170 cover.) You might also read the manuals to @ref{(gawk)Top}, | |
| 171 @ref{(ed)Top}, @cite{sed}, @cite{grep}, @ref{(perl)Top}, | |
| 172 @ref{(regex)Top}, @ref{(rx)Top}, @cite{pcre}, and @ref{(flex)Top}, which | |
| 173 also make good use of regular expressions. | |
| 174 | |
| 175 The XEmacs regular expression syntax most closely resembles that of | |
| 176 @cite{ed}, or @cite{grep}, the GNU versions of which all utilize the GNU | |
| 177 @cite{regex} library. XEmacs' version of @cite{regex} has recently been | |
| 178 extended with some Perl--like capabilities, described in the next | |
| 179 section. | |
| 180 | |
| 181 @menu | |
| 182 * Syntax of Regexps:: Rules for writing regular expressions. | |
| 183 * Regexp Example:: Illustrates regular expression syntax. | |
| 184 @end menu | |
| 185 | |
| 186 @node Syntax of Regexps | |
| 187 @subsection Syntax of Regular Expressions | |
| 188 | |
| 189 Regular expressions have a syntax in which a few characters are | |
| 190 special constructs and the rest are @dfn{ordinary}. An ordinary | |
| 191 character is a simple regular expression that matches that character and | |
| 192 nothing else. The special characters are @samp{.}, @samp{*}, @samp{+}, | |
| 193 @samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new | |
| 194 special characters will be defined in the future. Any other character | |
| 195 appearing in a regular expression is ordinary, unless a @samp{\} | |
| 196 precedes it. | |
| 197 | |
| 198 For example, @samp{f} is not a special character, so it is ordinary, and | |
| 199 therefore @samp{f} is a regular expression that matches the string | |
| 200 @samp{f} and no other string. (It does @emph{not} match the string | |
| 201 @samp{ff}.) Likewise, @samp{o} is a regular expression that matches | |
| 202 only @samp{o}.@refill | |
| 203 | |
| 204 Any two regular expressions @var{a} and @var{b} can be concatenated. The | |
| 205 result is a regular expression that matches a string if @var{a} matches | |
| 206 some amount of the beginning of that string and @var{b} matches the rest of | |
| 207 the string.@refill | |
| 208 | |
| 209 As a simple example, we can concatenate the regular expressions @samp{f} | |
| 210 and @samp{o} to get the regular expression @samp{fo}, which matches only | |
| 211 the string @samp{fo}. Still trivial. To do something more powerful, you | |
| 212 need to use one of the special characters. Here is a list of them: | |
| 213 | |
| 214 @need 1200 | |
| 215 @table @kbd | |
| 216 @item .@: @r{(Period)} | |
| 217 @cindex @samp{.} in regexp | |
| 218 is a special character that matches any single character except a newline. | |
| 219 Using concatenation, we can make regular expressions like @samp{a.b}, which | |
| 220 matches any three-character string that begins with @samp{a} and ends with | |
| 221 @samp{b}.@refill | |
| 222 | |
| 223 @item * | |
| 224 @cindex @samp{*} in regexp | |
| 225 is not a construct by itself; it is a quantifying suffix operator that | |
| 226 means to repeat the preceding regular expression as many times as | |
| 227 possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so | |
| 228 @samp{fo*} matches one @samp{f} followed by any number of @samp{o}s. | |
| 229 The case of zero @samp{o}s is allowed: @samp{fo*} does match | |
| 230 @samp{f}.@refill | |
| 231 | |
| 232 @samp{*} always applies to the @emph{smallest} possible preceding | |
| 233 expression. Thus, @samp{fo*} has a repeating @samp{o}, not a | |
| 234 repeating @samp{fo}.@refill | |
| 235 | |
| 236 The matcher processes a @samp{*} construct by matching, immediately, as | |
| 237 many repetitions as can be found; it is "greedy". Then it continues | |
| 238 with the rest of the pattern. If that fails, backtracking occurs, | |
| 239 discarding some of the matches of the @samp{*}-modified construct in | |
| 240 case that makes it possible to match the rest of the pattern. For | |
| 241 example, in matching @samp{ca*ar} against the string @samp{caaar}, the | |
| 242 @samp{a*} first tries to match all three @samp{a}s; but the rest of the | |
| 243 pattern is @samp{ar} and there is only @samp{r} left to match, so this | |
| 244 try fails. The next alternative is for @samp{a*} to match only two | |
| 245 @samp{a}s. With this choice, the rest of the regexp matches | |
| 246 successfully.@refill | |
| 247 | |
| 248 Nested repetition operators can be extremely slow if they specify | |
| 249 backtracking loops. For example, it could take hours for the regular | |
| 250 expression @samp{\(x+y*\)*a} to match the sequence | |
| 251 @samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because | |
| 252 Emacs must try each imaginable way of grouping the 35 @samp{x}'s before | |
| 253 concluding that none of them can work. To make sure your regular | |
| 254 expressions run fast, check nested repetitions carefully. | |
| 255 | |
| 256 @item + | |
| 257 @cindex @samp{+} in regexp | |
| 258 is a quantifying suffix operator similar to @samp{*} except that the | |
| 259 preceding expression must match at least once. It is also "greedy". | |
| 260 So, for example, @samp{ca+r} matches the strings @samp{car} and | |
| 261 @samp{caaaar} but not the string @samp{cr}, whereas @samp{ca*r} matches | |
| 262 all three strings. | |
| 263 | |
| 264 @item ? | |
| 265 @cindex @samp{?} in regexp | |
| 266 is a quantifying suffix operator similar to @samp{*}, except that the | |
| 267 preceding expression can match either once or not at all. For example, | |
| 268 @samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anything | |
| 269 else. | |
| 270 | |
| 271 @item *? | |
| 272 @cindex @samp{*?} in regexp | |
| 273 works just like @samp{*}, except that rather than matching the longest | |
| 274 match, it matches the shortest match. @samp{*?} is known as a | |
| 275 @dfn{non-greedy} quantifier, a regexp construct borrowed from Perl. | |
| 276 @c Did perl get this from somewhere? What's the real history of *? ? | |
| 277 | |
| 442 | 278 This construct is very useful for when you want to match the text inside |
| 279 a pair of delimiters. For instance, @samp{/\*.*?\*/} will match C | |
| 280 comments in a string. This could not easily be achieved without the use | |
| 281 of a non-greedy quantifier. | |
| 428 | 282 |
| 283 This construct has not been available prior to XEmacs 20.4. It is not | |
| 284 available in FSF Emacs. | |
| 285 | |
| 286 @item +? | |
| 287 @cindex @samp{+?} in regexp | |
| 442 | 288 is the non-greedy version of @samp{+}. |
| 289 | |
| 290 @item ?? | |
| 291 @cindex @samp{??} in regexp | |
| 292 is the non-greedy version of @samp{?}. | |
| 428 | 293 |
| 294 @item \@{n,m\@} | |
| 295 @c Note the spacing after the close brace is deliberate. | |
| 296 @cindex @samp{\@{n,m\@} }in regexp | |
| 297 serves as an interval quantifier, analogous to @samp{*} or @samp{+}, but | |
| 298 specifies that the expression must match at least @var{n} times, but no | |
| 299 more than @var{m} times. This syntax is supported by most Unix regexp | |
| 300 utilities, and has been introduced to XEmacs for the version 20.3. | |
| 301 | |
| 442 | 302 Unfortunately, the non-greedy version of this quantifier does not exist |
| 303 currently, although it does in Perl. | |
| 304 | |
| 428 | 305 @item [ @dots{} ] |
| 306 @cindex character set (in regexp) | |
| 307 @cindex @samp{[} in regexp | |
| 308 @cindex @samp{]} in regexp | |
| 309 @samp{[} begins a @dfn{character set}, which is terminated by a | |
| 310 @samp{]}. In the simplest case, the characters between the two brackets | |
| 311 form the set. Thus, @samp{[ad]} matches either one @samp{a} or one | |
| 312 @samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}s | |
| 313 and @samp{d}s (including the empty string), from which it follows that | |
| 314 @samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr}, | |
| 315 @samp{caddaar}, etc.@refill | |
| 316 | |
| 317 The usual regular expression special characters are not special inside a | |
| 318 character set. A completely different set of special characters exists | |
| 319 inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill | |
| 320 | |
| 321 @samp{-} is used for ranges of characters. To write a range, write two | |
| 322 characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any | |
| 323 lower case letter. Ranges may be intermixed freely with individual | |
| 324 characters, as in @samp{[a-z$%.]}, which matches any lower case letter | |
| 325 or @samp{$}, @samp{%}, or a period.@refill | |
| 326 | |
| 327 To include a @samp{]} in a character set, make it the first character. | |
| 328 For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a | |
| 329 @samp{-}, write @samp{-} as the first character in the set, or put it | |
| 330 immediately after a range. (You can replace one individual character | |
| 331 @var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the | |
| 332 @samp{-}.) There is no way to write a set containing just @samp{-} and | |
| 333 @samp{]}. | |
| 334 | |
| 335 To include @samp{^} in a set, put it anywhere but at the beginning of | |
| 336 the set. | |
| 337 | |
| 338 @item [^ @dots{} ] | |
| 339 @cindex @samp{^} in regexp | |
| 340 @samp{[^} begins a @dfn{complement character set}, which matches any | |
| 341 character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} | |
| 342 matches all characters @emph{except} letters and digits.@refill | |
| 343 | |
| 344 @samp{^} is not special in a character set unless it is the first | |
| 345 character. The character following the @samp{^} is treated as if it | |
| 346 were first (thus, @samp{-} and @samp{]} are not special there). | |
| 347 | |
| 348 Note that a complement character set can match a newline, unless | |
| 349 newline is mentioned as one of the characters not to match. | |
| 350 | |
| 351 @item ^ | |
| 352 @cindex @samp{^} in regexp | |
| 353 @cindex beginning of line in regexp | |
| 354 is a special character that matches the empty string, but only at the | |
| 355 beginning of a line in the text being matched. Otherwise it fails to | |
| 356 match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at | |
| 357 the beginning of a line. | |
| 358 | |
| 359 When matching a string instead of a buffer, @samp{^} matches at the | |
| 360 beginning of the string or after a newline character @samp{\n}. | |
| 361 | |
| 362 @item $ | |
| 363 @cindex @samp{$} in regexp | |
| 364 is similar to @samp{^} but matches only at the end of a line. Thus, | |
| 365 @samp{x+$} matches a string of one @samp{x} or more at the end of a line. | |
| 366 | |
| 367 When matching a string instead of a buffer, @samp{$} matches at the end | |
| 368 of the string or before a newline character @samp{\n}. | |
| 369 | |
| 370 @item \ | |
| 371 @cindex @samp{\} in regexp | |
| 372 has two functions: it quotes the special characters (including | |
| 373 @samp{\}), and it introduces additional special constructs. | |
| 374 | |
| 375 Because @samp{\} quotes special characters, @samp{\$} is a regular | |
| 376 expression that matches only @samp{$}, and @samp{\[} is a regular | |
| 377 expression that matches only @samp{[}, and so on. | |
| 378 | |
| 379 Note that @samp{\} also has special meaning in the read syntax of Lisp | |
| 380 strings (@pxref{String Type}), and must be quoted with @samp{\}. For | |
| 381 example, the regular expression that matches the @samp{\} character is | |
| 382 @samp{\\}. To write a Lisp string that contains the characters | |
| 383 @samp{\\}, Lisp syntax requires you to quote each @samp{\} with another | |
| 384 @samp{\}. Therefore, the read syntax for a regular expression matching | |
| 385 @samp{\} is @code{"\\\\"}.@refill | |
| 386 @end table | |
| 387 | |
| 388 @strong{Please note:} For historical compatibility, special characters | |
| 389 are treated as ordinary ones if they are in contexts where their special | |
| 390 meanings make no sense. For example, @samp{*foo} treats @samp{*} as | |
| 391 ordinary since there is no preceding expression on which the @samp{*} | |
| 392 can act. It is poor practice to depend on this behavior; quote the | |
| 393 special character anyway, regardless of where it appears.@refill | |
| 394 | |
| 395 For the most part, @samp{\} followed by any character matches only | |
| 396 that character. However, there are several exceptions: characters | |
| 397 that, when preceded by @samp{\}, are special constructs. Such | |
| 398 characters are always ordinary when encountered on their own. Here | |
| 399 is a table of @samp{\} constructs: | |
| 400 | |
| 401 @table @kbd | |
| 402 @item \| | |
| 403 @cindex @samp{|} in regexp | |
| 404 @cindex regexp alternative | |
| 405 specifies an alternative. | |
| 406 Two regular expressions @var{a} and @var{b} with @samp{\|} in | |
| 407 between form an expression that matches anything that either @var{a} or | |
| 408 @var{b} matches.@refill | |
| 409 | |
| 410 Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} | |
| 411 but no other string.@refill | |
| 412 | |
| 413 @samp{\|} applies to the largest possible surrounding expressions. Only a | |
| 414 surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of | |
| 415 @samp{\|}.@refill | |
| 416 | |
| 417 Full backtracking capability exists to handle multiple uses of @samp{\|}. | |
| 418 | |
| 419 @item \( @dots{} \) | |
| 420 @cindex @samp{(} in regexp | |
| 421 @cindex @samp{)} in regexp | |
| 422 @cindex regexp grouping | |
| 423 is a grouping construct that serves three purposes: | |
| 424 | |
| 425 @enumerate | |
| 426 @item | |
| 427 To enclose a set of @samp{\|} alternatives for other operations. | |
| 428 Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. | |
| 429 | |
| 430 @item | |
| 431 To enclose an expression for a suffix operator such as @samp{*} to act | |
| 432 on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any | |
| 433 (zero or more) number of @samp{na} strings.@refill | |
| 434 | |
| 435 @item | |
| 436 To record a matched substring for future reference. | |
| 437 @end enumerate | |
| 438 | |
| 439 This last application is not a consequence of the idea of a | |
| 440 parenthetical grouping; it is a separate feature that happens to be | |
| 441 assigned as a second meaning to the same @samp{\( @dots{} \)} construct | |
| 442 because there is no conflict in practice between the two meanings. | |
| 443 Here is an explanation of this feature: | |
| 444 | |
| 445 @item \@var{digit} | |
| 446 matches the same text that matched the @var{digit}th occurrence of a | |
| 447 @samp{\( @dots{} \)} construct. | |
| 448 | |
| 2255 | 449 In other words, after the end of a @samp{\( @dots{} \)} construct, the |
| 428 | 450 matcher remembers the beginning and end of the text matched by that |
| 451 construct. Then, later on in the regular expression, you can use | |
| 452 @samp{\} followed by @var{digit} to match that same text, whatever it | |
| 453 may have been. | |
| 454 | |
| 455 The strings matching the first nine @samp{\( @dots{} \)} constructs | |
| 456 appearing in a regular expression are assigned numbers 1 through 9 in | |
| 457 the order that the open parentheses appear in the regular expression. | |
| 458 So you can use @samp{\1} through @samp{\9} to refer to the text matched | |
| 459 by the corresponding @samp{\( @dots{} \)} constructs. | |
| 460 | |
| 461 For example, @samp{\(.*\)\1} matches any newline-free string that is | |
| 462 composed of two identical halves. The @samp{\(.*\)} matches the first | |
| 463 half, which may be anything, but the @samp{\1} that follows must match | |
| 464 the same exact text. | |
| 465 | |
| 466 @item \(?: @dots{} \) | |
| 467 @cindex @samp{\(?:} in regexp | |
| 468 @cindex regexp grouping | |
| 469 is called a @dfn{shy} grouping operator, and it is used just like | |
| 470 @samp{\( @dots{} \)}, except that it does not cause the matched | |
| 471 substring to be recorded for future reference. | |
| 472 | |
| 473 This is useful when you need a lot of grouping @samp{\( @dots{} \)} | |
| 442 | 474 constructs, but only want to remember one or two -- or if you have |
| 475 more than nine groupings and need to use backreferences to refer to | |
| 2255 | 476 the groupings at the end. It also allows construction of regular |
| 477 expressions from variable subexpressions that contain varying numbers of | |
| 478 non-capturing subexpressions, without disturbing the group counts for | |
| 479 the main expression. For example | |
| 480 | |
| 481 @example | |
| 482 (let ((sre (if foo "\\(?:bar\\|baz\\)" "quux"))) | |
| 483 (re-search-forward (format "a\\(b+ %s c+\\) d" sre) nil t) | |
| 484 (match-string 1)) | |
| 485 @end example | |
| 428 | 486 |
| 2255 | 487 It is very tedious to write this kind of code without shy groups, even |
| 488 if you know what all the alternative subexpressions will look like. | |
| 428 | 489 |
| 2255 | 490 Using @samp{\(?: @dots{} \)} rather than @samp{\( @dots{} \)} should |
| 491 give little performance gain, as the start of each group must be | |
| 492 recorded for the purpose of back-tracking in any case, and no string | |
| 493 copying is done until @code{match-string} is called. | |
| 494 | |
| 495 The shy grouping operator has been borrowed from Perl, and was not | |
| 496 available prior to XEmacs 20.3, and has only been available in GNU Emacs | |
| 497 since version 21. | |
| 428 | 498 |
| 499 @item \w | |
| 500 @cindex @samp{\w} in regexp | |
| 501 matches any word-constituent character. The editor syntax table | |
| 502 determines which characters these are. @xref{Syntax Tables}. | |
| 503 | |
| 504 @item \W | |
| 505 @cindex @samp{\W} in regexp | |
| 506 matches any character that is not a word constituent. | |
| 507 | |
| 508 @item \s@var{code} | |
| 509 @cindex @samp{\s} in regexp | |
| 510 matches any character whose syntax is @var{code}. Here @var{code} is a | |
| 511 character that represents a syntax code: thus, @samp{w} for word | |
| 512 constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, | |
| 513 etc. @xref{Syntax Tables}, for a list of syntax codes and the | |
| 514 characters that stand for them. | |
| 515 | |
| 516 @item \S@var{code} | |
| 517 @cindex @samp{\S} in regexp | |
| 518 matches any character whose syntax is not @var{code}. | |
| 2608 | 519 |
| 520 @item \c@var{category} | |
| 521 @cindex @samp{\c} in regexp | |
| 522 matches any character in @var{category}. Only available under Mule, | |
| 523 categories, and category tables, are further described in @ref{Category | |
| 524 Tables}. They are a mechanism for constructing classes of characters | |
| 525 that can be local to a buffer, and that do not require complicated [] | |
| 526 expressions every time they are referenced. | |
| 527 | |
| 528 @item \C@var{category} | |
| 529 @cindex @samp{\C} in regexp | |
| 530 matches any character outside @var{category}. @xref{Category Tables}, | |
| 531 again, and note that this is only available under Mule. | |
| 428 | 532 @end table |
| 533 | |
| 534 The following regular expression constructs match the empty string---that is, | |
| 535 they don't use up any characters---but whether they match depends on the | |
| 536 context. | |
| 537 | |
| 538 @table @kbd | |
| 539 @item \` | |
| 540 @cindex @samp{\`} in regexp | |
| 541 matches the empty string, but only at the beginning | |
| 542 of the buffer or string being matched against. | |
| 543 | |
| 544 @item \' | |
| 545 @cindex @samp{\'} in regexp | |
| 546 matches the empty string, but only at the end of | |
| 547 the buffer or string being matched against. | |
| 548 | |
| 549 @item \= | |
| 550 @cindex @samp{\=} in regexp | |
| 551 matches the empty string, but only at point. | |
| 552 (This construct is not defined when matching against a string.) | |
| 553 | |
| 554 @item \b | |
| 555 @cindex @samp{\b} in regexp | |
| 556 matches the empty string, but only at the beginning or | |
| 557 end of a word. Thus, @samp{\bfoo\b} matches any occurrence of | |
| 558 @samp{foo} as a separate word. @samp{\bballs?\b} matches | |
| 559 @samp{ball} or @samp{balls} as a separate word.@refill | |
| 560 | |
| 561 @item \B | |
| 562 @cindex @samp{\B} in regexp | |
| 563 matches the empty string, but @emph{not} at the beginning or | |
| 564 end of a word. | |
| 565 | |
| 566 @item \< | |
| 567 @cindex @samp{\<} in regexp | |
| 568 matches the empty string, but only at the beginning of a word. | |
| 569 | |
| 570 @item \> | |
| 571 @cindex @samp{\>} in regexp | |
| 572 matches the empty string, but only at the end of a word. | |
| 573 @end table | |
| 574 | |
| 575 @kindex invalid-regexp | |
| 576 Not every string is a valid regular expression. For example, a string | |
| 577 with unbalanced square brackets is invalid (with a few exceptions, such | |
| 578 as @samp{[]]}), and so is a string that ends with a single @samp{\}. If | |
| 579 an invalid regular expression is passed to any of the search functions, | |
| 580 an @code{invalid-regexp} error is signaled. | |
| 581 | |
| 582 @defun regexp-quote string | |
| 583 This function returns a regular expression string that matches exactly | |
| 584 @var{string} and nothing else. This allows you to request an exact | |
| 585 string match when calling a function that wants a regular expression. | |
| 586 | |
| 587 @example | |
| 588 @group | |
| 589 (regexp-quote "^The cat$") | |
| 590 @result{} "\\^The cat\\$" | |
| 591 @end group | |
| 592 @end example | |
| 593 | |
| 594 One use of @code{regexp-quote} is to combine an exact string match with | |
| 595 context described as a regular expression. For example, this searches | |
| 596 for the string that is the value of @code{string}, surrounded by | |
| 597 whitespace: | |
| 598 | |
| 599 @example | |
| 600 @group | |
| 601 (re-search-forward | |
| 602 (concat "\\s-" (regexp-quote string) "\\s-")) | |
| 603 @end group | |
| 604 @end example | |
| 605 @end defun | |
| 606 | |
| 607 @node Regexp Example | |
| 608 @subsection Complex Regexp Example | |
| 609 | |
| 610 Here is a complicated regexp, used by XEmacs to recognize the end of a | |
| 611 sentence together with any whitespace that follows. It is the value of | |
| 444 | 612 the variable @code{sentence-end}. |
| 428 | 613 |
| 614 First, we show the regexp as a string in Lisp syntax to distinguish | |
| 615 spaces from tab characters. The string constant begins and ends with a | |
| 616 double-quote. @samp{\"} stands for a double-quote as part of the | |
| 617 string, @samp{\\} for a backslash as part of the string, @samp{\t} for a | |
| 618 tab and @samp{\n} for a newline. | |
| 619 | |
| 620 @example | |
| 621 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" | |
| 622 @end example | |
| 623 | |
| 624 In contrast, if you evaluate the variable @code{sentence-end}, you | |
| 625 will see the following: | |
| 626 | |
| 627 @example | |
| 628 @group | |
| 629 sentence-end | |
| 630 @result{} | |
| 444 | 631 "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[ |
| 428 | 632 ]*" |
| 633 @end group | |
| 634 @end example | |
| 635 | |
| 636 @noindent | |
| 637 In this output, tab and newline appear as themselves. | |
| 638 | |
| 639 This regular expression contains four parts in succession and can be | |
| 640 deciphered as follows: | |
| 641 | |
| 642 @table @code | |
| 643 @item [.?!] | |
| 644 The first part of the pattern is a character set that matches any one of | |
| 645 three characters: period, question mark, and exclamation mark. The | |
| 646 match must begin with one of these three characters. | |
| 647 | |
| 648 @item []\"')@}]* | |
| 649 The second part of the pattern matches any closing braces and quotation | |
| 650 marks, zero or more of them, that may follow the period, question mark | |
| 651 or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in | |
| 652 a string. The @samp{*} at the end indicates that the immediately | |
| 653 preceding regular expression (a character set, in this case) may be | |
| 654 repeated zero or more times. | |
| 655 | |
| 656 @item \\($\\|@ $\\|\t\\|@ @ \\) | |
| 657 The third part of the pattern matches the whitespace that follows the | |
| 658 end of a sentence: the end of a line, or a tab, or two spaces. The | |
| 659 double backslashes mark the parentheses and vertical bars as regular | |
| 660 expression syntax; the parentheses delimit a group and the vertical bars | |
| 661 separate alternatives. The dollar sign is used to match the end of a | |
| 662 line. | |
| 663 | |
| 664 @item [ \t\n]* | |
| 665 Finally, the last part of the pattern matches any additional whitespace | |
| 666 beyond the minimum needed to end a sentence. | |
| 667 @end table | |
| 668 | |
| 669 @node Regexp Search | |
| 670 @section Regular Expression Searching | |
| 671 @cindex regular expression searching | |
| 672 @cindex regexp searching | |
| 673 @cindex searching for regexp | |
| 674 | |
| 675 In XEmacs, you can search for the next match for a regexp either | |
| 676 incrementally or not. Incremental search commands are described in the | |
| 446 | 677 @cite{The XEmacs Lisp Reference Manual}. @xref{Regexp Search, , Regular Expression |
| 678 Search, xemacs, The XEmacs Lisp Reference Manual}. Here we describe only the search | |
| 428 | 679 functions useful in programs. The principal one is |
| 680 @code{re-search-forward}. | |
| 681 | |
| 444 | 682 @deffn Command re-search-forward regexp &optional limit noerror count buffer |
| 428 | 683 This function searches forward in the current buffer for a string of |
| 684 text that is matched by the regular expression @var{regexp}. The | |
| 685 function skips over any amount of text that is not matched by | |
| 686 @var{regexp}, and leaves point at the end of the first match found. | |
| 687 It returns the new value of point. | |
| 688 | |
| 689 If @var{limit} is non-@code{nil} (it must be a position in the current | |
| 690 buffer), then it is the upper bound to the search. No match extending | |
| 691 after that position is accepted. | |
| 692 | |
| 693 What happens when the search fails depends on the value of | |
| 694 @var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed} | |
| 695 error is signaled. If @var{noerror} is @code{t}, | |
| 696 @code{re-search-forward} does nothing and returns @code{nil}. If | |
| 697 @var{noerror} is neither @code{nil} nor @code{t}, then | |
| 698 @code{re-search-forward} moves point to @var{limit} (or the end of the | |
| 699 buffer) and returns @code{nil}. | |
| 700 | |
| 444 | 701 If @var{count} is supplied (it must be a positive number), then the |
| 428 | 702 search is repeated that many times (each time starting at the end of the |
| 703 previous time's match). If these successive searches succeed, the | |
| 704 function succeeds, moving point and returning its new value. Otherwise | |
| 705 the search fails. | |
| 706 | |
| 707 In the following example, point is initially before the @samp{T}. | |
| 708 Evaluating the search call moves point to the end of that line (between | |
| 709 the @samp{t} of @samp{hat} and the newline). | |
| 710 | |
| 711 @example | |
| 712 @group | |
| 713 ---------- Buffer: foo ---------- | |
| 714 I read "@point{}The cat in the hat | |
| 715 comes back" twice. | |
| 716 ---------- Buffer: foo ---------- | |
| 717 @end group | |
| 718 | |
| 719 @group | |
| 720 (re-search-forward "[a-z]+" nil t 5) | |
| 721 @result{} 27 | |
| 722 | |
| 723 ---------- Buffer: foo ---------- | |
| 724 I read "The cat in the hat@point{} | |
| 725 comes back" twice. | |
| 726 ---------- Buffer: foo ---------- | |
| 727 @end group | |
| 728 @end example | |
| 729 @end deffn | |
| 730 | |
| 444 | 731 @deffn Command re-search-backward regexp &optional limit noerror count buffer |
| 428 | 732 This function searches backward in the current buffer for a string of |
| 733 text that is matched by the regular expression @var{regexp}, leaving | |
| 734 point at the beginning of the first text found. | |
| 735 | |
| 736 This function is analogous to @code{re-search-forward}, but they are not | |
| 737 simple mirror images. @code{re-search-forward} finds the match whose | |
| 738 beginning is as close as possible to the starting point. If | |
| 739 @code{re-search-backward} were a perfect mirror image, it would find the | |
| 740 match whose end is as close as possible. However, in fact it finds the | |
| 741 match whose beginning is as close as possible. The reason is that | |
| 742 matching a regular expression at a given spot always works from | |
| 743 beginning to end, and starts at a specified beginning position. | |
| 744 | |
| 745 A true mirror-image of @code{re-search-forward} would require a special | |
| 746 feature for matching regexps from end to beginning. It's not worth the | |
| 747 trouble of implementing that. | |
| 748 @end deffn | |
| 749 | |
| 444 | 750 @defun string-match regexp string &optional start buffer |
| 428 | 751 This function returns the index of the start of the first match for |
| 752 the regular expression @var{regexp} in @var{string}, or @code{nil} if | |
| 753 there is no match. If @var{start} is non-@code{nil}, the search starts | |
| 754 at that index in @var{string}. | |
| 755 | |
| 444 | 756 |
| 757 Optional arg @var{buffer} controls how case folding is done (according | |
| 758 to the value of @code{case-fold-search} in @var{buffer} and | |
| 759 @var{buffer}'s case tables) and defaults to the current buffer. | |
| 760 | |
| 428 | 761 For example, |
| 762 | |
| 763 @example | |
| 764 @group | |
| 765 (string-match | |
| 766 "quick" "The quick brown fox jumped quickly.") | |
| 767 @result{} 4 | |
| 768 @end group | |
| 769 @group | |
| 770 (string-match | |
| 771 "quick" "The quick brown fox jumped quickly." 8) | |
| 772 @result{} 27 | |
| 773 @end group | |
| 774 @end example | |
| 775 | |
| 776 @noindent | |
| 777 The index of the first character of the | |
| 778 string is 0, the index of the second character is 1, and so on. | |
| 779 | |
| 780 After this function returns, the index of the first character beyond | |
| 781 the match is available as @code{(match-end 0)}. @xref{Match Data}. | |
| 782 | |
| 783 @example | |
| 784 @group | |
| 785 (string-match | |
| 786 "quick" "The quick brown fox jumped quickly." 8) | |
| 787 @result{} 27 | |
| 788 @end group | |
| 789 | |
| 790 @group | |
| 791 (match-end 0) | |
| 792 @result{} 32 | |
| 793 @end group | |
| 794 @end example | |
| 795 @end defun | |
| 796 | |
| 1495 | 797 The function @code{split-string} can be used to parse a string into |
| 798 components delimited by text matching a regular expression. | |
| 799 | |
| 800 @defvar split-string-default-separators | |
| 801 The default value of @var{separators} for @code{split-string}, initially | |
| 802 @samp{"[ \f\t\n\r\v]+"}. | |
| 803 @end defvar | |
| 804 | |
| 805 @defun split-string string &optional separators omit-nulls | |
| 806 This function splits @var{string} into substrings delimited by matches | |
| 807 for the regular expression @var{separators}. Each match for | |
| 808 @var{separators} defines a splitting point; the substrings between the | |
| 809 splitting points are made into a list, which is the value returned by | |
| 810 @code{split-string}. If @var{omit-nulls} is @code{t}, null strings will | |
| 811 be removed from the result list. Otherwise, null strings are left in | |
| 812 the result. If @var{separators} is @code{nil} (or omitted), the default | |
| 813 is the value of @code{split-string-default-separators}. | |
| 814 | |
| 815 As a special case, when @var{separators} is @code{nil} (or omitted), | |
| 816 null strings are always omitted from the result. Thus: | |
| 817 | |
| 818 @example | |
| 819 (split-string " two words ") | |
| 820 @result{} ("two" "words") | |
| 821 @end example | |
| 822 | |
| 823 The result is not @samp{("" "two" "words" "")}, which would rarely be | |
| 824 useful. If you need such a result, use an explict value for | |
| 825 @var{separators}: | |
| 826 | |
| 827 @example | |
| 828 (split-string " two words " split-string-default-separators) | |
| 829 @result{} ("" "two" "words" "") | |
| 830 @end example | |
| 831 | |
| 832 A few examples (there are more in the regression tests): | |
| 428 | 833 |
| 834 @example | |
| 835 @group | |
| 1495 | 836 (split-string "foo" "") |
| 837 @result{} ("" "f" "o" "o" "") | |
| 838 @end group | |
| 839 @group | |
| 840 (split-string "foo" "^") | |
| 841 @result{} ("" "foo") | |
| 842 @end group | |
| 843 @group | |
| 844 (split-string "foo" "$") | |
| 845 @result{} ("foo" "")) | |
| 846 @end group | |
| 847 @group | |
| 848 (split-string "foo,bar" ",") | |
| 428 | 849 @result{} ("foo" "bar") |
| 850 @end group | |
| 851 @group | |
| 1495 | 852 (split-string ",foo,bar," ",") |
| 853 @result{} ("" "foo" "bar" "") | |
| 428 | 854 @end group |
| 855 @group | |
| 1495 | 856 (split-string ",foo,bar," "^,") |
| 857 @result{} ("" "foo,bar,") | |
| 428 | 858 @end group |
| 859 @group | |
| 1495 | 860 (split-string "foo,bar" "," t) |
| 861 @result{} ("foo" "bar") | |
| 862 @end group | |
| 863 @group | |
| 864 (split-string ",foo,bar," "," t) | |
| 865 @result{} ("foo" "bar") | |
| 428 | 866 @end group |
| 867 @end example | |
| 868 @end defun | |
| 869 | |
| 870 @defun split-path path | |
| 871 This function splits a search path into a list of strings. The path | |
| 872 components are separated with the characters specified with | |
| 873 @code{path-separator}. Under Unix, @code{path-separator} will normally | |
| 874 be @samp{:}, while under Windows, it will be @samp{;}. | |
| 875 @end defun | |
| 876 | |
| 444 | 877 @defun looking-at regexp &optional buffer |
| 428 | 878 This function determines whether the text in the current buffer directly |
| 879 following point matches the regular expression @var{regexp}. ``Directly | |
| 880 following'' means precisely that: the search is ``anchored'' and it can | |
| 881 succeed only starting with the first character following point. The | |
| 882 result is @code{t} if so, @code{nil} otherwise. | |
| 883 | |
| 884 This function does not move point, but it updates the match data, which | |
| 885 you can access using @code{match-beginning} and @code{match-end}. | |
| 886 @xref{Match Data}. | |
| 887 | |
| 888 In this example, point is located directly before the @samp{T}. If it | |
| 889 were anywhere else, the result would be @code{nil}. | |
| 890 | |
| 891 @example | |
| 892 @group | |
| 893 ---------- Buffer: foo ---------- | |
| 894 I read "@point{}The cat in the hat | |
| 895 comes back" twice. | |
| 896 ---------- Buffer: foo ---------- | |
| 897 | |
| 898 (looking-at "The cat in the hat$") | |
| 899 @result{} t | |
| 900 @end group | |
| 901 @end example | |
| 902 @end defun | |
| 903 | |
| 904 @node POSIX Regexps | |
| 905 @section POSIX Regular Expression Searching | |
| 906 | |
| 907 The usual regular expression functions do backtracking when necessary | |
| 908 to handle the @samp{\|} and repetition constructs, but they continue | |
| 909 this only until they find @emph{some} match. Then they succeed and | |
| 910 report the first match found. | |
| 911 | |
| 912 This section describes alternative search functions which perform the | |
| 913 full backtracking specified by the POSIX standard for regular expression | |
| 914 matching. They continue backtracking until they have tried all | |
| 915 possibilities and found all matches, so they can report the longest | |
| 916 match, as required by POSIX. This is much slower, so use these | |
| 917 functions only when you really need the longest match. | |
| 918 | |
| 919 In Emacs versions prior to 19.29, these functions did not exist, and | |
| 920 the functions described above implemented full POSIX backtracking. | |
| 921 | |
| 444 | 922 @deffn Command posix-search-forward regexp &optional limit noerror count buffer |
| 428 | 923 This is like @code{re-search-forward} except that it performs the full |
| 924 backtracking specified by the POSIX standard for regular expression | |
| 925 matching. | |
| 444 | 926 @end deffn |
| 428 | 927 |
| 444 | 928 @deffn Command posix-search-backward regexp &optional limit noerror count buffer |
| 428 | 929 This is like @code{re-search-backward} except that it performs the full |
| 930 backtracking specified by the POSIX standard for regular expression | |
| 931 matching. | |
| 444 | 932 @end deffn |
| 428 | 933 |
| 444 | 934 @defun posix-looking-at regexp &optional buffer |
| 428 | 935 This is like @code{looking-at} except that it performs the full |
| 936 backtracking specified by the POSIX standard for regular expression | |
| 937 matching. | |
| 938 @end defun | |
| 939 | |
| 444 | 940 @defun posix-string-match regexp string &optional start buffer |
| 428 | 941 This is like @code{string-match} except that it performs the full |
| 942 backtracking specified by the POSIX standard for regular expression | |
| 943 matching. | |
| 444 | 944 |
| 945 Optional arg @var{buffer} controls how case folding is done (according | |
| 946 to the value of @code{case-fold-search} in @var{buffer} and | |
| 947 @var{buffer}'s case tables) and defaults to the current buffer. | |
| 428 | 948 @end defun |
| 949 | |
| 950 @ignore | |
| 951 @deffn Command delete-matching-lines regexp | |
| 952 This function is identical to @code{delete-non-matching-lines}, save | |
| 953 that it deletes what @code{delete-non-matching-lines} keeps. | |
| 954 | |
| 955 In the example below, point is located on the first line of text. | |
| 956 | |
| 957 @example | |
| 958 @group | |
| 959 ---------- Buffer: foo ---------- | |
| 960 We hold these truths | |
| 961 to be self-evident, | |
| 962 that all men are created | |
| 963 equal, and that they are | |
| 964 ---------- Buffer: foo ---------- | |
| 965 @end group | |
| 966 | |
| 967 @group | |
| 968 (delete-matching-lines "the") | |
| 969 @result{} nil | |
| 970 | |
| 971 ---------- Buffer: foo ---------- | |
| 972 to be self-evident, | |
| 973 that all men are created | |
| 974 ---------- Buffer: foo ---------- | |
| 975 @end group | |
| 976 @end example | |
| 977 @end deffn | |
| 978 | |
| 979 @deffn Command flush-lines regexp | |
| 444 | 980 This function is an alias of @code{delete-matching-lines}. |
| 428 | 981 @end deffn |
| 982 | |
| 444 | 983 @deffn Command delete-non-matching-lines regexp |
| 428 | 984 This function deletes all lines following point which don't |
| 985 contain a match for the regular expression @var{regexp}. | |
| 444 | 986 @end deffn |
| 428 | 987 |
| 988 @deffn Command keep-lines regexp | |
| 989 This function is the same as @code{delete-non-matching-lines}. | |
| 990 @end deffn | |
| 991 | |
| 444 | 992 @deffn Command count-matches regexp |
| 428 | 993 This function counts the number of matches for @var{regexp} there are in |
| 994 the current buffer following point. It prints this number in | |
| 995 the echo area, returning the string printed. | |
| 996 @end deffn | |
| 997 | |
| 444 | 998 @deffn Command how-many regexp |
| 999 This function is an alias of @code{count-matches}. | |
| 428 | 1000 @end deffn |
| 1001 | |
| 444 | 1002 @deffn Command list-matching-lines regexp &optional nlines |
| 428 | 1003 This function is a synonym of @code{occur}. |
| 1004 Show all lines following point containing a match for @var{regexp}. | |
| 1005 Display each line with @var{nlines} lines before and after, | |
| 1006 or @code{-}@var{nlines} before if @var{nlines} is negative. | |
| 1007 @var{nlines} defaults to @code{list-matching-lines-default-context-lines}. | |
| 1008 Interactively it is the prefix arg. | |
| 1009 | |
| 1010 The lines are shown in a buffer named @samp{*Occur*}. | |
| 1011 It serves as a menu to find any of the occurrences in this buffer. | |
| 1012 @kbd{C-h m} (@code{describe-mode} in that buffer gives help. | |
| 1013 @end deffn | |
| 1014 | |
| 1015 @defopt list-matching-lines-default-context-lines | |
| 1016 Default value is 0. | |
| 1017 Default number of context lines to include around a @code{list-matching-lines} | |
| 1018 match. A negative number means to include that many lines before the match. | |
| 1019 A positive number means to include that many lines both before and after. | |
| 1020 @end defopt | |
| 1021 @end ignore | |
| 1022 | |
| 1023 @node Search and Replace | |
| 1024 @section Search and Replace | |
| 1025 @cindex replacement | |
| 1026 | |
| 1027 @defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count map | |
| 1028 This function is the guts of @code{query-replace} and related commands. | |
| 1029 It searches for occurrences of @var{from-string} and replaces some or | |
| 1030 all of them. If @var{query-flag} is @code{nil}, it replaces all | |
| 1031 occurrences; otherwise, it asks the user what to do about each one. | |
| 1032 | |
| 1033 If @var{regexp-flag} is non-@code{nil}, then @var{from-string} is | |
| 1034 considered a regular expression; otherwise, it must match literally. If | |
| 1035 @var{delimited-flag} is non-@code{nil}, then only replacements | |
| 1036 surrounded by word boundaries are considered. | |
| 1037 | |
| 1038 The argument @var{replacements} specifies what to replace occurrences | |
| 1039 with. If it is a string, that string is used. It can also be a list of | |
| 1040 strings, to be used in cyclic order. | |
| 1041 | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
4199
diff
changeset
|
1042 If @var{repeat-count} is non-@code{nil}, it should be a fixnum. Then |
| 428 | 1043 it specifies how many times to use each of the strings in the |
| 1044 @var{replacements} list before advancing cyclicly to the next one. | |
| 1045 | |
| 1046 Normally, the keymap @code{query-replace-map} defines the possible user | |
| 1047 responses for queries. The argument @var{map}, if non-@code{nil}, is a | |
| 1048 keymap to use instead of @code{query-replace-map}. | |
| 1049 @end defun | |
| 1050 | |
| 1051 @defvar query-replace-map | |
| 1052 This variable holds a special keymap that defines the valid user | |
| 1053 responses for @code{query-replace} and related functions, as well as | |
| 1054 @code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways: | |
| 1055 | |
| 1056 @itemize @bullet | |
| 1057 @item | |
| 1058 The ``key bindings'' are not commands, just symbols that are meaningful | |
| 1059 to the functions that use this map. | |
| 1060 | |
| 1061 @item | |
| 1062 Prefix keys are not supported; each key binding must be for a single event | |
| 1063 key sequence. This is because the functions don't use read key sequence to | |
| 1064 get the input; instead, they read a single event and look it up ``by hand.'' | |
| 1065 @end itemize | |
| 1066 @end defvar | |
| 1067 | |
| 1068 Here are the meaningful ``bindings'' for @code{query-replace-map}. | |
| 1069 Several of them are meaningful only for @code{query-replace} and | |
| 1070 friends. | |
| 1071 | |
| 1072 @table @code | |
| 1073 @item act | |
| 1074 Do take the action being considered---in other words, ``yes.'' | |
| 1075 | |
| 1076 @item skip | |
| 1077 Do not take action for this question---in other words, ``no.'' | |
| 1078 | |
| 1079 @item exit | |
| 1080 Answer this question ``no,'' and give up on the entire series of | |
| 1081 questions, assuming that the answers will be ``no.'' | |
| 1082 | |
| 1083 @item act-and-exit | |
| 1084 Answer this question ``yes,'' and give up on the entire series of | |
| 1085 questions, assuming that subsequent answers will be ``no.'' | |
| 1086 | |
| 1087 @item act-and-show | |
| 1088 Answer this question ``yes,'' but show the results---don't advance yet | |
| 1089 to the next question. | |
| 1090 | |
| 1091 @item automatic | |
| 1092 Answer this question and all subsequent questions in the series with | |
| 1093 ``yes,'' without further user interaction. | |
| 1094 | |
| 1095 @item backup | |
| 1096 Move back to the previous place that a question was asked about. | |
| 1097 | |
| 1098 @item edit | |
| 1099 Enter a recursive edit to deal with this question---instead of any | |
| 1100 other action that would normally be taken. | |
| 1101 | |
| 1102 @item delete-and-edit | |
| 1103 Delete the text being considered, then enter a recursive edit to replace | |
| 1104 it. | |
| 1105 | |
| 1106 @item recenter | |
| 1107 Redisplay and center the window, then ask the same question again. | |
| 1108 | |
| 1109 @item quit | |
| 1110 Perform a quit right away. Only @code{y-or-n-p} and related functions | |
| 1111 use this answer. | |
| 1112 | |
| 1113 @item help | |
| 1114 Display some help, then ask again. | |
| 1115 @end table | |
| 1116 | |
| 1117 @node Match Data | |
| 1118 @section The Match Data | |
| 1119 @cindex match data | |
| 1120 | |
| 1121 XEmacs keeps track of the positions of the start and end of segments of | |
| 1122 text found during a regular expression search. This means, for example, | |
| 1123 that you can search for a complex pattern, such as a date in an Rmail | |
| 1124 message, and then extract parts of the match under control of the | |
| 1125 pattern. | |
| 1126 | |
| 1468 | 1127 Because the match data normally describe the most recent successful |
| 1128 search only, you must be careful not to do another search inadvertently | |
| 1129 between the search you wish to refer back to and the use of the match | |
| 1130 data. If you can't avoid another intervening search, you must save and | |
| 1131 restore the match data around it, to prevent it from being overwritten. | |
| 1132 | |
| 1133 To make it possible to write iterative or recursive code that repeatedly | |
| 1134 searches, and uses the data from the last successful search when no more | |
| 1135 matches can be found, a search or match which fails will preserve the | |
| 1136 match data from the last successful search. (You must not depend on | |
| 1137 match data being preserved in case the search or match signals an | |
| 1138 error.) If for some reason you need to clear the match data, you may | |
| 1139 use @code{(store-match-data nil)}. | |
| 428 | 1140 |
| 1141 @menu | |
| 1142 * Simple Match Data:: Accessing single items of match data, | |
| 1143 such as where a particular subexpression started. | |
| 1144 * Replacing Match:: Replacing a substring that was matched. | |
| 1145 * Entire Match Data:: Accessing the entire match data at once, as a list. | |
| 1146 * Saving Match Data:: Saving and restoring the match data. | |
| 1147 @end menu | |
| 1148 | |
| 1149 @node Simple Match Data | |
| 1150 @subsection Simple Match Data Access | |
| 1151 | |
| 1152 This section explains how to use the match data to find out what was | |
| 1153 matched by the last search or match operation. | |
| 1154 | |
| 1155 You can ask about the entire matching text, or about a particular | |
| 1156 parenthetical subexpression of a regular expression. The @var{count} | |
| 1157 argument in the functions below specifies which. If @var{count} is | |
| 1158 zero, you are asking about the entire match. If @var{count} is | |
| 1159 positive, it specifies which subexpression you want. | |
| 1160 | |
| 1161 Recall that the subexpressions of a regular expression are those | |
| 1162 expressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The | |
| 1163 @var{count}th subexpression is found by counting occurrences of | |
| 1164 @samp{\(} from the beginning of the whole regular expression. The first | |
| 1165 subexpression is numbered 1, the second 2, and so on. Only regular | |
| 1166 expressions can have subexpressions---after a simple string search, the | |
| 1167 only information available is about the entire match. | |
| 1168 | |
| 1169 @defun match-string count &optional in-string | |
| 1170 This function returns, as a string, the text matched in the last search | |
| 1171 or match operation. It returns the entire text if @var{count} is zero, | |
| 1172 or just the portion corresponding to the @var{count}th parenthetical | |
| 1173 subexpression, if @var{count} is positive. If @var{count} is out of | |
| 1174 range, or if that subexpression didn't match anything, the value is | |
| 1175 @code{nil}. | |
| 1176 | |
| 1177 If the last such operation was done against a string with | |
| 1178 @code{string-match}, then you should pass the same string as the | |
| 1179 argument @var{in-string}. Otherwise, after a buffer search or match, | |
| 1180 you should omit @var{in-string} or pass @code{nil} for it; but you | |
| 1181 should make sure that the current buffer when you call | |
| 1182 @code{match-string} is the one in which you did the searching or | |
| 1183 matching. | |
| 1184 @end defun | |
| 1185 | |
| 1186 @defun match-beginning count | |
| 1187 This function returns the position of the start of text matched by the | |
| 1188 last regular expression searched for, or a subexpression of it. | |
| 1189 | |
| 1190 If @var{count} is zero, then the value is the position of the start of | |
| 1191 the entire match. Otherwise, @var{count} specifies a subexpression in | |
| 1192 the regular expression, and the value of the function is the starting | |
| 1193 position of the match for that subexpression. | |
| 1194 | |
| 1195 The value is @code{nil} for a subexpression inside a @samp{\|} | |
| 1196 alternative that wasn't used in the match. | |
| 1197 @end defun | |
| 1198 | |
| 1199 @defun match-end count | |
| 1200 This function is like @code{match-beginning} except that it returns the | |
| 1201 position of the end of the match, rather than the position of the | |
| 1202 beginning. | |
| 1203 @end defun | |
| 1204 | |
| 1205 Here is an example of using the match data, with a comment showing the | |
| 1206 positions within the text: | |
| 1207 | |
| 1208 @example | |
| 1209 @group | |
| 1210 (string-match "\\(qu\\)\\(ick\\)" | |
| 1211 "The quick fox jumped quickly.") | |
| 444 | 1212 ;0123456789 |
| 428 | 1213 @result{} 4 |
| 1214 @end group | |
| 1215 | |
| 1216 @group | |
| 1217 (match-string 0 "The quick fox jumped quickly.") | |
| 1218 @result{} "quick" | |
| 1219 (match-string 1 "The quick fox jumped quickly.") | |
| 1220 @result{} "qu" | |
| 1221 (match-string 2 "The quick fox jumped quickly.") | |
| 1222 @result{} "ick" | |
| 1223 @end group | |
| 1224 | |
| 1225 @group | |
| 1226 (match-beginning 1) ; @r{The beginning of the match} | |
| 1227 @result{} 4 ; @r{with @samp{qu} is at index 4.} | |
| 1228 @end group | |
| 1229 | |
| 1230 @group | |
| 1231 (match-beginning 2) ; @r{The beginning of the match} | |
| 1232 @result{} 6 ; @r{with @samp{ick} is at index 6.} | |
| 1233 @end group | |
| 1234 | |
| 1235 @group | |
| 1236 (match-end 1) ; @r{The end of the match} | |
| 1237 @result{} 6 ; @r{with @samp{qu} is at index 6.} | |
| 1238 | |
| 1239 (match-end 2) ; @r{The end of the match} | |
| 1240 @result{} 9 ; @r{with @samp{ick} is at index 9.} | |
| 1241 @end group | |
| 1242 @end example | |
| 1243 | |
| 1244 Here is another example. Point is initially located at the beginning | |
| 1245 of the line. Searching moves point to between the space and the word | |
| 1246 @samp{in}. The beginning of the entire match is at the 9th character of | |
| 1247 the buffer (@samp{T}), and the beginning of the match for the first | |
| 1248 subexpression is at the 13th character (@samp{c}). | |
| 1249 | |
| 1250 @example | |
| 1251 @group | |
| 1252 (list | |
| 1253 (re-search-forward "The \\(cat \\)") | |
| 1254 (match-beginning 0) | |
| 1255 (match-beginning 1)) | |
| 1256 @result{} (9 9 13) | |
| 1257 @end group | |
| 1258 | |
| 1259 @group | |
| 1260 ---------- Buffer: foo ---------- | |
| 1261 I read "The cat @point{}in the hat comes back" twice. | |
| 1262 ^ ^ | |
| 1263 9 13 | |
| 1264 ---------- Buffer: foo ---------- | |
| 1265 @end group | |
| 1266 @end example | |
| 1267 | |
| 1268 @noindent | |
| 1269 (In this case, the index returned is a buffer position; the first | |
| 1270 character of the buffer counts as 1.) | |
| 1271 | |
| 1272 @node Replacing Match | |
| 1273 @subsection Replacing the Text That Matched | |
| 1274 | |
| 1275 This function replaces the text matched by the last search with | |
| 1276 @var{replacement}. | |
| 1277 | |
| 1278 @cindex case in replacements | |
| 444 | 1279 @defun replace-match replacement &optional fixedcase literal string strbuffer |
| 428 | 1280 This function replaces the text in the buffer (or in @var{string}) that |
| 1281 was matched by the last search. It replaces that text with | |
| 1282 @var{replacement}. | |
| 1283 | |
| 1284 If you did the last search in a buffer, you should specify @code{nil} | |
| 4199 | 1285 for @var{string}. (An error will be signaled if you don't.) Then |
| 1286 @code{replace-match} does the replacement by editing the buffer; it | |
| 1287 leaves point at the end of the replacement text, and returns @code{t}. | |
| 428 | 1288 |
| 1289 If you did the search in a string, pass the same string as @var{string}. | |
| 4199 | 1290 (An error will be signaled if you specify nil.) Then |
| 1291 @code{replace-match} does the replacement by constructing and returning | |
| 1292 a new string. | |
| 444 | 1293 |
| 428 | 1294 If @var{fixedcase} is non-@code{nil}, then the case of the replacement |
| 1295 text is not changed; otherwise, the replacement text is converted to a | |
| 1296 different case depending upon the capitalization of the text to be | |
| 1297 replaced. If the original text is all upper case, the replacement text | |
| 1298 is converted to upper case. If the first word of the original text is | |
| 1299 capitalized, then the first word of the replacement text is capitalized. | |
| 1300 If the original text contains just one word, and that word is a capital | |
| 1301 letter, @code{replace-match} considers this a capitalized first word | |
| 1302 rather than all upper case. | |
| 1303 | |
| 1304 If @code{case-replace} is @code{nil}, then case conversion is not done, | |
| 444 | 1305 regardless of the value of @var{fixedcase}. @xref{Searching and Case}. |
| 428 | 1306 |
| 1307 If @var{literal} is non-@code{nil}, then @var{replacement} is inserted | |
| 1308 exactly as it is, the only alterations being case changes as needed. | |
| 1309 If it is @code{nil} (the default), then the character @samp{\} is treated | |
| 1310 specially. If a @samp{\} appears in @var{replacement}, then it must be | |
| 1311 part of one of the following sequences: | |
| 1312 | |
| 1313 @table @asis | |
| 1314 @item @samp{\&} | |
| 4199 | 1315 @cindex @samp{\&} in replacement |
| 428 | 1316 @samp{\&} stands for the entire text being replaced. |
| 1317 | |
| 1318 @item @samp{\@var{n}} | |
| 1319 @cindex @samp{\@var{n}} in replacement | |
| 4199 | 1320 @cindex @samp{\@var{digit}} in replacement |
| 428 | 1321 @samp{\@var{n}}, where @var{n} is a digit, stands for the text that |
| 1322 matched the @var{n}th subexpression in the original regexp. | |
| 1323 Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}. | |
| 1324 | |
| 1325 @item @samp{\\} | |
| 4199 | 1326 @cindex @samp{\\} in replacement |
| 428 | 1327 @samp{\\} stands for a single @samp{\} in the replacement text. |
| 4199 | 1328 |
| 1329 @item @samp{\u} | |
| 1330 @cindex @samp{\u} in replacement | |
| 1331 @samp{\u} means upcase the next character. | |
| 1332 | |
| 1333 @item @samp{\l} | |
| 1334 @cindex @samp{\l} in replacement | |
| 1335 @samp{\l} means downcase the next character. | |
| 1336 | |
| 1337 @item @samp{\U} | |
| 1338 @cindex @samp{\U} in replacement | |
| 1339 @samp{\U} means begin upcasing all following characters. | |
| 1340 | |
| 1341 @item @samp{\L} | |
| 1342 @cindex @samp{\L} in replacement | |
| 1343 @samp{\L} means begin downcasing all following characters. | |
| 1344 | |
| 1345 @item @samp{\E} | |
| 1346 @cindex @samp{\E} in replacement | |
| 1347 @samp{\E} means terminate the effect of any @samp{\U} or @samp{\L}. | |
| 428 | 1348 @end table |
| 4199 | 1349 |
| 1350 Case changes made with @samp{\u}, @samp{\l}, @samp{\U}, and @samp{\L} | |
| 1351 override all other case changes that may be made in the replaced text. | |
| 1352 | |
| 1353 The fifth argument @var{strbuffer} may be a buffer to be used for | |
| 1354 syntax-table and case-table lookup. If @var{strbuffer} is not a buffer, | |
| 1355 the current buffer is used. When @var{string} is not a string, the | |
| 1356 buffer that the match occurred in has automatically been remembered and | |
| 1357 you do not need to specify it. @var{string} may also be an integer, | |
| 1358 specifying the index of the subexpression to match. When @var{string} | |
| 1359 is not an integer, the ``subexpression'' is 0, @emph{i.e.}, the whole | |
| 1360 match. An @code{invalid-argument} error will be signaled if you specify | |
| 1361 a buffer when @var{string} is nil, or specify a subexpression which was | |
| 1362 not matched. | |
| 1363 | |
| 1364 It is not possible to specify both a buffer and a subexpression, but the | |
| 1365 idiom | |
| 1366 @example | |
| 1367 (with-current-buffer @var{buffer} (replace-match ... @var{integer})) | |
| 1368 @end example | |
| 1369 may be used. | |
| 1370 | |
| 428 | 1371 @end defun |
| 1372 | |
| 4199 | 1373 |
| 428 | 1374 @node Entire Match Data |
| 1375 @subsection Accessing the Entire Match Data | |
| 1376 | |
| 1377 The functions @code{match-data} and @code{set-match-data} read or | |
| 1378 write the entire match data, all at once. | |
| 1379 | |
| 444 | 1380 @defun match-data &optional integers reuse |
| 428 | 1381 This function returns a newly constructed list containing all the |
| 1382 information on what text the last search matched. Element zero is the | |
| 1383 position of the beginning of the match for the whole expression; element | |
| 1384 one is the position of the end of the match for the expression. The | |
| 1385 next two elements are the positions of the beginning and end of the | |
| 1386 match for the first subexpression, and so on. In general, element | |
| 1387 @ifinfo | |
| 1388 number 2@var{n} | |
| 1389 @end ifinfo | |
| 1390 @tex | |
| 1391 number {\mathsurround=0pt $2n$} | |
| 1392 @end tex | |
| 1393 corresponds to @code{(match-beginning @var{n})}; and | |
| 1394 element | |
| 1395 @ifinfo | |
| 1396 number 2@var{n} + 1 | |
| 1397 @end ifinfo | |
| 1398 @tex | |
| 1399 number {\mathsurround=0pt $2n+1$} | |
| 1400 @end tex | |
| 1401 corresponds to @code{(match-end @var{n})}. | |
| 1402 | |
| 1403 All the elements are markers or @code{nil} if matching was done on a | |
| 1404 buffer, and all are integers or @code{nil} if matching was done on a | |
| 444 | 1405 string with @code{string-match}. However, if the optional first |
| 1406 argument @var{integers} is non-@code{nil}, always use integers (rather | |
| 1407 than markers) to represent buffer positions. | |
| 1408 | |
| 1409 If the optional second argument @var{reuse} is a list, reuse it as part | |
| 1410 of the value. If @var{reuse} is long enough to hold all the values, and if | |
| 1411 @var{integers} is non-@code{nil}, no new lisp objects are created. | |
| 428 | 1412 |
| 1413 As always, there must be no possibility of intervening searches between | |
| 1414 the call to a search function and the call to @code{match-data} that is | |
| 1415 intended to access the match data for that search. | |
| 1416 | |
| 1417 @example | |
| 1418 @group | |
| 1419 (match-data) | |
| 1420 @result{} (#<marker at 9 in foo> | |
| 1421 #<marker at 17 in foo> | |
| 1422 #<marker at 13 in foo> | |
| 1423 #<marker at 17 in foo>) | |
| 1424 @end group | |
| 1425 @end example | |
| 1426 @end defun | |
| 1427 | |
| 1428 @defun set-match-data match-list | |
| 1429 This function sets the match data from the elements of @var{match-list}, | |
| 1430 which should be a list that was the value of a previous call to | |
| 1431 @code{match-data}. | |
| 1432 | |
| 1433 If @var{match-list} refers to a buffer that doesn't exist, you don't get | |
| 1434 an error; that sets the match data in a meaningless but harmless way. | |
| 1435 | |
| 1436 @findex store-match-data | |
| 1437 @code{store-match-data} is an alias for @code{set-match-data}. | |
| 1438 @end defun | |
| 1439 | |
| 1440 @node Saving Match Data | |
| 1441 @subsection Saving and Restoring the Match Data | |
| 1442 | |
| 1443 When you call a function that may do a search, you may need to save | |
| 1444 and restore the match data around that call, if you want to preserve the | |
| 1445 match data from an earlier search for later use. Here is an example | |
| 1446 that shows the problem that arises if you fail to save the match data: | |
| 1447 | |
| 1448 @example | |
| 1449 @group | |
| 1450 (re-search-forward "The \\(cat \\)") | |
| 1451 @result{} 48 | |
| 1452 (foo) ; @r{Perhaps @code{foo} does} | |
| 1453 ; @r{more searching.} | |
| 1454 (match-end 0) | |
| 1455 @result{} 61 ; @r{Unexpected result---not 48!} | |
| 1456 @end group | |
| 1457 @end example | |
| 1458 | |
| 1459 You can save and restore the match data with @code{save-match-data}: | |
| 1460 | |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
1461 @defmac save-match-data body@dots{} |
|
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
1462 This macro executes @var{body}, saving and restoring the match |
| 428 | 1463 data around it. |
|
5547
a46c5c8d6564
Avoid calling various macros "special operators" in the manuals.
Aidan Kehoe <kehoea@parhasard.net>
parents:
5361
diff
changeset
|
1464 @end defmac |
| 428 | 1465 |
| 1466 Emacs automatically saves and restores the match data when it runs | |
| 1467 process filter functions (@pxref{Filter Functions}) and process | |
| 1468 sentinels (@pxref{Sentinels}). | |
| 1469 | |
| 1470 @ignore | |
| 1471 Here is a function which restores the match data provided the buffer | |
| 1472 associated with it still exists. | |
| 1473 | |
| 1474 @smallexample | |
| 1475 @group | |
| 1476 (defun restore-match-data (data) | |
| 1477 @c It is incorrect to split the first line of a doc string. | |
| 1478 @c If there's a problem here, it should be solved in some other way. | |
| 1479 "Restore the match data DATA unless the buffer is missing." | |
| 1480 (catch 'foo | |
| 1481 (let ((d data)) | |
| 1482 @end group | |
| 1483 (while d | |
| 1484 (and (car d) | |
| 1485 (null (marker-buffer (car d))) | |
| 1486 @group | |
| 1487 ;; @file{match-data} @r{buffer is deleted.} | |
| 1488 (throw 'foo nil)) | |
| 1489 (setq d (cdr d))) | |
| 1490 (set-match-data data)))) | |
| 1491 @end group | |
| 1492 @end smallexample | |
| 1493 @end ignore | |
| 1494 | |
| 1495 @node Searching and Case | |
| 1496 @section Searching and Case | |
| 1497 @cindex searching and case | |
| 1498 | |
| 1499 By default, searches in Emacs ignore the case of the text they are | |
| 1500 searching through; if you specify searching for @samp{FOO}, then | |
| 1501 @samp{Foo} or @samp{foo} is also considered a match. Regexps, and in | |
| 1502 particular character sets, are included: thus, @samp{[aB]} would match | |
| 1503 @samp{a} or @samp{A} or @samp{b} or @samp{B}. | |
| 1504 | |
| 1505 If you do not want this feature, set the variable | |
| 1506 @code{case-fold-search} to @code{nil}. Then all letters must match | |
| 1507 exactly, including case. This is a buffer-local variable; altering the | |
| 1508 variable affects only the current buffer. (@xref{Intro to | |
| 1509 Buffer-Local}.) Alternatively, you may change the value of | |
| 1510 @code{default-case-fold-search}, which is the default value of | |
| 1511 @code{case-fold-search} for buffers that do not override it. | |
| 1512 | |
| 1513 Note that the user-level incremental search feature handles case | |
| 1514 distinctions differently. When given a lower case letter, it looks for | |
| 1515 a match of either case, but when given an upper case letter, it looks | |
| 1516 for an upper case letter only. But this has nothing to do with the | |
| 1517 searching functions Lisp functions use. | |
| 1518 | |
| 1519 @defopt case-replace | |
| 1520 This variable determines whether the replacement functions should | |
| 1521 preserve case. If the variable is @code{nil}, that means to use the | |
| 1522 replacement text verbatim. A non-@code{nil} value means to convert the | |
| 1523 case of the replacement text according to the text being replaced. | |
| 1524 | |
| 1525 The function @code{replace-match} is where this variable actually has | |
| 1526 its effect. @xref{Replacing Match}. | |
| 1527 @end defopt | |
| 1528 | |
| 1529 @defopt case-fold-search | |
| 1530 This buffer-local variable determines whether searches should ignore | |
| 1531 case. If the variable is @code{nil} they do not ignore case; otherwise | |
| 1532 they do ignore case. | |
| 1533 @end defopt | |
| 1534 | |
| 1535 @defvar default-case-fold-search | |
| 1536 The value of this variable is the default value for | |
| 1537 @code{case-fold-search} in buffers that do not override it. This is the | |
| 1538 same as @code{(default-value 'case-fold-search)}. | |
| 1539 @end defvar | |
| 1540 | |
| 1541 @node Standard Regexps | |
| 1542 @section Standard Regular Expressions Used in Editing | |
| 1543 @cindex regexps used standardly in editing | |
| 1544 @cindex standard regexps used in editing | |
| 1545 | |
| 1546 This section describes some variables that hold regular expressions | |
| 1547 used for certain purposes in editing: | |
| 1548 | |
| 1549 @defvar page-delimiter | |
| 1550 This is the regexp describing line-beginnings that separate pages. The | |
| 1551 default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"}); | |
| 1552 this matches a line that starts with a formfeed character. | |
| 1553 @end defvar | |
| 1554 | |
| 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. | |
| 1563 | |
| 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 | |
| 1571 | |
| 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 | |
| 1578 | |
| 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 | |
| 1582 is: | |
| 1583 | |
| 1584 @example | |
| 1585 "[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*" | |
| 1586 @end example | |
| 1587 | |
| 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. | |
| 1591 | |
| 1592 For a detailed explanation of this regular expression, see @ref{Regexp | |
| 1593 Example}. | |
| 1594 @end defvar |