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