1 2@node Search, Fixit, Display, Top 3@chapter Searching and Replacement 4@cindex searching 5 6 Like other editors, Emacs has commands for searching for occurrences of 7a string. The principal search command is unusual in that it is 8@dfn{incremental}: it begins to search before you have finished typing the 9search string. There are also non-incremental search commands more like 10those of other editors. 11 12 Besides the usual @code{replace-string} command that finds all 13occurrences of one string and replaces them with another, Emacs has a fancy 14replacement command called @code{query-replace} which asks interactively 15which occurrences to replace. 16 17@menu 18* Incremental Search:: Search happens as you type the string. 19* Non-Incremental Search:: Specify entire string and then search. 20* Word Search:: Search for sequence of words. 21* Regexp Search:: Search for match for a regexp. 22* Regexps:: Syntax of regular expressions. 23* Search Case:: To ignore case while searching, or not. 24* Replace:: Search, and replace some or all matches. 25* Other Repeating Search:: Operating on all matches for some regexp. 26@end menu 27 28@node Incremental Search, Non-Incremental Search, Search, Search 29@section Incremental Search 30 31 An incremental search begins searching as soon as you type the first 32character of the search string. As you type in the search string, Emacs 33shows you where the string (as you have typed it so far) is found. 34When you have typed enough characters to identify the place you want, you 35can stop. Depending on what you do next, you may or may not need to 36terminate the search explicitly with a @key{RET}. 37 38@c WideCommands 39@table @kbd 40@item C-s 41Incremental search forward (@code{isearch-forward}). 42@item C-r 43Incremental search backward (@code{isearch-backward}). 44@end table 45 46@kindex C-s 47@kindex C-r 48@findex isearch-forward 49@findex isearch-backward 50 @kbd{C-s} starts an incremental search. @kbd{C-s} reads characters from 51the keyboard and positions the cursor at the first occurrence of the 52characters that you have typed. If you type @kbd{C-s} and then @kbd{F}, 53the cursor moves right after the first @samp{F}. Type an @kbd{O}, and see 54the cursor move to after the first @samp{FO}. After another @kbd{O}, the 55cursor is after the first @samp{FOO} after the place where you started the 56search. Meanwhile, the search string @samp{FOO} has been echoed in the 57echo area.@refill 58 59 The echo area display ends with three dots when actual searching is going 60on. When search is waiting for more input, the three dots are removed. 61(On slow terminals, the three dots are not displayed.) 62 63 If you make a mistake in typing the search string, you can erase 64characters with @key{DEL}. Each @key{DEL} cancels the last character of the 65search string. This does not happen until Emacs is ready to read another 66input character; first it must either find, or fail to find, the character 67you want to erase. If you do not want to wait for this to happen, use 68@kbd{C-g} as described below.@refill 69 70 When you are satisfied with the place you have reached, you can type 71@key{RET} (or @key{C-m}), which stops searching, leaving the cursor where 72the search brought it. Any command not specially meaningful in searches also 73stops the search and is then executed. Thus, typing @kbd{C-a} exits the 74search and then moves to the beginning of the line. @key{RET} is necessary 75only if the next command you want to type is a printing character, 76@key{DEL}, @key{ESC}, or another control character that is special 77within searches (@kbd{C-q}, @kbd{C-w}, @kbd{C-r}, @kbd{C-s}, or @kbd{C-y}). 78 79 Sometimes you search for @samp{FOO} and find it, but were actually 80looking for a different occurrence of it. To move to the next occurrence 81of the search string, type another @kbd{C-s}. Do this as often as 82necessary. If you overshoot, you can cancel some @kbd{C-s} 83characters with @key{DEL}. 84 85 After you exit a search, you can search for the same string again by 86typing just @kbd{C-s C-s}: the first @kbd{C-s} is the key that invokes 87incremental search, and the second @kbd{C-s} means ``search again''. 88 89 If the specified string is not found at all, the echo area displays 90the text @samp{Failing I-Search}. The cursor is after the place where 91Emacs found as much of your string as it could. Thus, if you search for 92@samp{FOOT}, and there is no @samp{FOOT}, the cursor may be after the 93@samp{FOO} in @samp{FOOL}. At this point there are several things you 94can do. If you mistyped the search string, correct it. If you like the 95place you have found, you can type @key{RET} or some other Emacs command 96to ``accept what the search offered''. Or you can type @kbd{C-g}, which 97removes from the search string the characters that could not be found 98(the @samp{T} in @samp{FOOT}), leaving those that were found (the 99@samp{FOO} in @samp{FOOT}). A second @kbd{C-g} at that point cancels 100the search entirely, returning point to where it was when the search 101started. 102 103 If a search is failing and you ask to repeat it by typing another 104@kbd{C-s}, it starts again from the beginning of the buffer. Repeating 105a failing backward search with @kbd{C-r} starts again from the end. This 106is called @dfn{wrapping around}. @samp{Wrapped} appears in the search 107prompt once this has happened. 108 109@cindex quitting (in search) 110 The @kbd{C-g} ``quit'' character does special things during searches; 111just what it does depends on the status of the search. If the search has 112found what you specified and is waiting for input, @kbd{C-g} cancels the 113entire search. The cursor moves back to where you started the search. If 114@kbd{C-g} is typed when there are characters in the search string that have 115not been found---because Emacs is still searching for them, or because it 116has failed to find them---then the search string characters which have not 117been found are discarded from the search string. The 118search is now successful and waiting for more input, so a second @kbd{C-g} 119cancels the entire search. 120 121 To search for a control character such as @kbd{C-s} or @key{DEL} or 122@key{ESC}, you must quote it by typing @kbd{C-q} first. This function 123of @kbd{C-q} is analogous to its meaning as an Emacs command: it causes 124the following character to be treated the way a graphic character would 125normally be treated in the same context. 126 127 To search backwards, you can use @kbd{C-r} instead of @kbd{C-s} to 128start the search; @kbd{C-r} is the key that runs the command 129(@code{isearch-backward}) to search backward. You can also use 130@kbd{C-r} to change from searching forward to searching backwards. Do 131this if a search fails because the place you started was too far down in the 132file. Repeated @kbd{C-r} keeps looking for more occurrences backwards. 133@kbd{C-s} starts going forward again. You can cancel @kbd{C-r} in a 134search with @key{DEL}. 135 136 The characters @kbd{C-y} and @kbd{C-w} can be used in incremental search 137to grab text from the buffer into the search string. This makes it 138convenient to search for another occurrence of text at point. @kbd{C-w} 139copies the word after point as part of the search string, advancing 140point over that word. Another @kbd{C-s} to repeat the search will then 141search for a string including that word. @kbd{C-y} is similar to @kbd{C-w} 142but copies the rest of the current line into the search string. 143 144 The characters @kbd{M-p} and @kbd{M-n} can be used in an incremental 145search to recall things which you have searched for in the past. A 146list of the last 16 things you have searched for is retained, and 147@kbd{M-p} and @kbd{M-n} let you cycle through that ring. 148 149The character @kbd{M-@key{TAB}} does completion on the elements in 150the search history ring. For example, if you know that you have 151recently searched for the string @code{POTATOE}, you could type 152@kbd{C-s P O M-@key{TAB}}. If you had searched for other strings 153beginning with @code{PO} then you would be shown a list of them, and 154would need to type more to select one. 155 156 You can change any of the special characters in incremental search via 157the normal keybinding mechanism: simply add a binding to the 158@code{isearch-mode-map}. For example, to make the character 159@kbd{C-b} mean ``search backwards'' while in isearch-mode, do this: 160 161@example 162(define-key isearch-mode-map "\C-b" 'isearch-repeat-backward) 163@end example 164 165These are the default bindings of isearch-mode: 166 167@findex isearch-delete-char 168@findex isearch-exit 169@findex isearch-quote-char 170@findex isearch-repeat-forward 171@findex isearch-repeat-backward 172@findex isearch-yank-line 173@findex isearch-yank-word 174@findex isearch-abort 175@findex isearch-ring-retreat 176@findex isearch-ring-advance 177@findex isearch-complete 178 179@kindex DEL (isearch-mode) 180@kindex RET (isearch-mode) 181@kindex C-q (isearch-mode) 182@kindex C-s (isearch-mode) 183@kindex C-r (isearch-mode) 184@kindex C-y (isearch-mode) 185@kindex C-w (isearch-mode) 186@kindex C-g (isearch-mode) 187@kindex M-p (isearch-mode) 188@kindex M-n (isearch-mode) 189@kindex M-TAB (isearch-mode) 190 191@table @kbd 192@item DEL 193Delete a character from the incremental search string (@code{isearch-delete-char}). 194@item RET 195Exit incremental search (@code{isearch-exit}). 196@item C-q 197Quote special characters for incremental search (@code{isearch-quote-char}). 198@item C-s 199Repeat incremental search forward (@code{isearch-repeat-forward}). 200@item C-r 201Repeat incremental search backward (@code{isearch-repeat-backward}). 202@item C-y 203Pull rest of line from buffer into search string (@code{isearch-yank-line}). 204@item C-w 205Pull next word from buffer into search string (@code{isearch-yank-word}). 206@item C-g 207Cancels input back to what has been found successfully, or aborts the 208isearch (@code{isearch-abort}). 209@item M-p 210Recall the previous element in the isearch history ring 211(@code{isearch-ring-retreat}). 212@item M-n 213Recall the next element in the isearch history ring 214(@code{isearch-ring-advance}). 215@item M-@key{TAB} 216Do completion on the elements in the isearch history ring 217(@code{isearch-complete}). 218 219@end table 220 221Any other character which is normally inserted into a buffer when typed 222is automatically added to the search string in isearch-mode. 223 224@subsection Slow Terminal Incremental Search 225 226 Incremental search on a slow terminal uses a modified style of display 227that is designed to take less time. Instead of redisplaying the buffer at 228each place the search gets to, it creates a new single-line window and uses 229that to display the line the search has found. The single-line window 230appears as soon as point gets outside of the text that is already 231on the screen. 232 233 When the search is terminated, the single-line window is removed. Only 234at this time the window in which the search was done is redisplayed to show 235its new value of point. 236 237 The three dots at the end of the search string, normally used to indicate 238that searching is going on, are not displayed in slow style display. 239 240@vindex search-slow-speed 241 The slow terminal style of display is used when the terminal baud rate is 242less than or equal to the value of the variable @code{search-slow-speed}, 243initially 1200. 244 245@vindex search-slow-window-lines 246 The number of lines to use in slow terminal search display is controlled 247by the variable @code{search-slow-window-lines}. Its normal value is 1. 248 249@node Non-Incremental Search, Word Search, Incremental Search, Search 250@section Non-Incremental Search 251@cindex non-incremental search 252 253 Emacs also has conventional non-incremental search commands, which require 254you type the entire search string before searching begins. 255 256@table @kbd 257@item C-s @key{RET} @var{string} @key{RET} 258Search for @var{string}. 259@item C-r @key{RET} @var{string} @key{RET} 260Search backward for @var{string}. 261@end table 262 263 To do a non-incremental search, first type @kbd{C-s @key{RET}} 264(or @kbd{C-s C-m}). This enters the minibuffer to read the search string. 265Terminate the string with @key{RET} to start the search. If the string 266is not found, the search command gets an error. 267 268 By default, @kbd{C-s} invokes incremental search, but if you give it an 269empty argument, which would otherwise be useless, it invokes non-incremental 270search. Therefore, @kbd{C-s @key{RET}} invokes non-incremental search. 271@kbd{C-r @key{RET}} also works this way. 272 273@findex search-forward 274@findex search-backward 275 Forward and backward non-incremental searches are implemented by the 276commands @code{search-forward} and @code{search-backward}. You can bind 277these commands to keys. The reason that incremental 278search is programmed to invoke them as well is that @kbd{C-s @key{RET}} 279is the traditional sequence of characters used in Emacs to invoke 280non-incremental search. 281 282 Non-incremental searches performed using @kbd{C-s @key{RET}} do 283not call @code{search-forward} right away. They first check 284if the next character is @kbd{C-w}, which requests a word search. 285@ifinfo 286@xref{Word Search}. 287@end ifinfo 288 289@node Word Search, Regexp Search, Non-Incremental Search, Search 290@section Word Search 291@cindex word search 292 293 Word search looks for a sequence of words without regard to how the 294words are separated. More precisely, you type a string of many words, 295using single spaces to separate them, and the string is found even if 296there are multiple spaces, newlines or other punctuation between the words. 297 298 Word search is useful in editing documents formatted by text formatters. 299If you edit while looking at the printed, formatted version, you can't tell 300where the line breaks are in the source file. Word search, allows you 301to search without having to know the line breaks. 302 303@table @kbd 304@item C-s @key{RET} C-w @var{words} @key{RET} 305Search for @var{words}, ignoring differences in punctuation. 306@item C-r @key{RET} C-w @var{words} @key{RET} 307Search backward for @var{words}, ignoring differences in punctuation. 308@end table 309 310 Word search is a special case of non-incremental search. It is invoked 311with @kbd{C-s @key{RET} C-w} followed by the search string, which 312must always be terminated with another @key{RET}. Being non-incremental, this 313search does not start until the argument is terminated. It works by 314constructing a regular expression and searching for that. @xref{Regexp 315Search}. 316 317 You can do a backward word search with @kbd{C-r @key{RET} C-w}. 318 319@findex word-search-forward 320@findex word-search-backward 321 Forward and backward word searches are implemented by the commands 322@code{word-search-forward} and @code{word-search-backward}. You can 323bind these commands to keys. The reason that incremental 324search is programmed to invoke them as well is that @kbd{C-s @key{RET} C-w} 325is the traditional Emacs sequence of keys for word search. 326 327@node Regexp Search, Regexps, Word Search, Search 328@section Regular Expression Search 329@cindex regular expression 330@cindex regexp 331 332 A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that 333denotes a (possibly infinite) set of strings. Searching for matches 334for a regexp is a powerful operation that editors on Unix systems have 335traditionally offered. 336 337 To gain a thorough understanding of regular expressions and how to use 338them to best advantage, we recommend that you study @cite{Mastering 339Regular Expressions, by Jeffrey E.F. Friedl, O'Reilly and Associates, 3401997}. (It's known as the "Hip Owls" book, because of the picture on its 341cover.) You might also read the manuals to @ref{(gawk)Top}, 342@ref{(ed)Top}, @cite{sed}, @cite{grep}, @ref{(perl)Top}, 343@ref{(regex)Top}, @ref{(rx)Top}, @cite{pcre}, and @ref{(flex)Top}, which 344also make good use of regular expressions. 345 346 The XEmacs regular expression syntax most closely resembles that of 347@cite{ed}, or @cite{grep}, the GNU versions of which all utilize the GNU 348@cite{regex} library. XEmacs' version of @cite{regex} has recently been 349extended with some Perl--like capabilities, described in the next 350section. 351 352 In XEmacs, you can search for the next match for a regexp either 353incrementally or not. 354 355@kindex M-C-s 356@kindex M-C-r 357@findex isearch-forward-regexp 358@findex isearch-backward-regexp 359 Incremental search for a regexp is done by typing @kbd{M-C-s} 360(@code{isearch-forward-regexp}). This command reads a search string 361incrementally just like @kbd{C-s}, but it treats the search string as a 362regexp rather than looking for an exact match against the text in the 363buffer. Each time you add text to the search string, you make the regexp 364longer, and the new regexp is searched for. A reverse regexp search command 365@code{isearch-backward-regexp} also exists, bound to @kbd{M-C-r}. 366 367 All of the control characters that do special things within an ordinary 368incremental search have the same functionality in incremental regexp search. 369Typing @kbd{C-s} or @kbd{C-r} immediately after starting a search 370retrieves the last incremental search regexp used: 371incremental regexp and non-regexp searches have independent defaults. 372 373@findex re-search-forward 374@findex re-search-backward 375 Non-incremental search for a regexp is done by the functions 376@code{re-search-forward} and @code{re-search-backward}. You can invoke 377them with @kbd{M-x} or bind them to keys. You can also call 378@code{re-search-forward} by way of incremental regexp search with 379@kbd{M-C-s @key{RET}}; similarly for @code{re-search-backward} with 380@kbd{M-C-r @key{RET}}. 381 382@node Regexps, Search Case, Regexp Search, Search 383@section Syntax of Regular Expressions 384 385 Regular expressions have a syntax in which a few characters are 386special constructs and the rest are @dfn{ordinary}. An ordinary 387character is a simple regular expression that matches that character and 388nothing else. The special characters are @samp{.}, @samp{*}, @samp{+}, 389@samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new 390special characters will be defined in the future. Any other character 391appearing in a regular expression is ordinary, unless a @samp{\} 392precedes it. 393 394For example, @samp{f} is not a special character, so it is ordinary, and 395therefore @samp{f} is a regular expression that matches the string 396@samp{f} and no other string. (It does @emph{not} match the string 397@samp{ff}.) Likewise, @samp{o} is a regular expression that matches 398only @samp{o}.@refill 399 400Any two regular expressions @var{a} and @var{b} can be concatenated. The 401result is a regular expression that matches a string if @var{a} matches 402some amount of the beginning of that string and @var{b} matches the rest of 403the string.@refill 404 405As a simple example, we can concatenate the regular expressions @samp{f} 406and @samp{o} to get the regular expression @samp{fo}, which matches only 407the string @samp{fo}. Still trivial. To do something more powerful, you 408need to use one of the special characters. Here is a list of them: 409 410@need 1200 411@table @kbd 412@item .@: @r{(Period)} 413@cindex @samp{.} in regexp 414is a special character that matches any single character except a newline. 415Using concatenation, we can make regular expressions like @samp{a.b}, which 416matches any three-character string that begins with @samp{a} and ends with 417@samp{b}.@refill 418 419@item * 420@cindex @samp{*} in regexp 421is not a construct by itself; it is a quantifying suffix operator that 422means to repeat the preceding regular expression as many times as 423possible. In @samp{fo*}, the @samp{*} applies to the @samp{o}, so 424@samp{fo*} matches one @samp{f} followed by any number of @samp{o}s. 425The case of zero @samp{o}s is allowed: @samp{fo*} does match 426@samp{f}.@refill 427 428@samp{*} always applies to the @emph{smallest} possible preceding 429expression. Thus, @samp{fo*} has a repeating @samp{o}, not a 430repeating @samp{fo}.@refill 431 432The matcher processes a @samp{*} construct by matching, immediately, as 433many repetitions as can be found; it is "greedy". Then it continues 434with the rest of the pattern. If that fails, backtracking occurs, 435discarding some of the matches of the @samp{*}-modified construct in 436case that makes it possible to match the rest of the pattern. For 437example, in matching @samp{ca*ar} against the string @samp{caaar}, the 438@samp{a*} first tries to match all three @samp{a}s; but the rest of the 439pattern is @samp{ar} and there is only @samp{r} left to match, so this 440try fails. The next alternative is for @samp{a*} to match only two 441@samp{a}s. With this choice, the rest of the regexp matches 442successfully.@refill 443 444Nested repetition operators can be extremely slow if they specify 445backtracking loops. For example, it could take hours for the regular 446expression @samp{\(x+y*\)*a} to match the sequence 447@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because 448Emacs must try each imaginable way of grouping the 35 @samp{x}'s before 449concluding that none of them can work. To make sure your regular 450expressions run fast, check nested repetitions carefully. 451 452@item + 453@cindex @samp{+} in regexp 454is a quantifying suffix operator similar to @samp{*} except that the 455preceding expression must match at least once. It is also "greedy". 456So, for example, @samp{ca+r} matches the strings @samp{car} and 457@samp{caaaar} but not the string @samp{cr}, whereas @samp{ca*r} matches 458all three strings. 459 460@item ? 461@cindex @samp{?} in regexp 462is a quantifying suffix operator similar to @samp{*}, except that the 463preceding expression can match either once or not at all. For example, 464@samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anything 465else. 466 467@item *? 468@cindex @samp{*?} in regexp 469works just like @samp{*}, except that rather than matching the longest 470match, it matches the shortest match. @samp{*?} is known as a 471@dfn{non-greedy} quantifier, a regexp construct borrowed from Perl. 472@c Did perl get this from somewhere? What's the real history of *? ? 473 474This construct is very useful for when you want to match the text inside 475a pair of delimiters. For instance, @samp{/\*.*?\*/} will match C 476comments in a string. This could not easily be achieved without the use 477of a non-greedy quantifier. 478 479This construct has not been available prior to XEmacs 20.4. It is not 480available in FSF Emacs. 481 482@item +? 483@cindex @samp{+?} in regexp 484is the non-greedy version of @samp{+}. 485 486@item ?? 487@cindex @samp{??} in regexp 488is the non-greedy version of @samp{?}. 489 490@item \@{n,m\@} 491@c Note the spacing after the close brace is deliberate. 492@cindex @samp{\@{n,m\@} }in regexp 493serves as an interval quantifier, analogous to @samp{*} or @samp{+}, but 494specifies that the expression must match at least @var{n} times, but no 495more than @var{m} times. This syntax is supported by most Unix regexp 496utilities, and has been introduced to XEmacs for the version 20.3. 497 498Unfortunately, the non-greedy version of this quantifier does not exist 499currently, although it does in Perl. 500 501@item [ @dots{} ] 502@cindex character set (in regexp) 503@cindex @samp{[} in regexp 504@cindex @samp{]} in regexp 505@samp{[} begins a @dfn{character set}, which is terminated by a 506@samp{]}. In the simplest case, the characters between the two brackets 507form the set. Thus, @samp{[ad]} matches either one @samp{a} or one 508@samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}s 509and @samp{d}s (including the empty string), from which it follows that 510@samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr}, 511@samp{caddaar}, etc.@refill 512 513The usual regular expression special characters are not special inside a 514character set. A completely different set of special characters exists 515inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill 516 517@samp{-} is used for ranges of characters. To write a range, write two 518characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any 519lower case letter. Ranges may be intermixed freely with individual 520characters, as in @samp{[a-z$%.]}, which matches any lower case letter 521or @samp{$}, @samp{%}, or a period.@refill 522 523To include a @samp{]} in a character set, make it the first character. 524For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a 525@samp{-}, write @samp{-} as the first character in the set, or put it 526immediately after a range. (You can replace one individual character 527@var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the 528@samp{-}.) There is no way to write a set containing just @samp{-} and 529@samp{]}. 530 531To include @samp{^} in a set, put it anywhere but at the beginning of 532the set. 533 534@item [^ @dots{} ] 535@cindex @samp{^} in regexp 536@samp{[^} begins a @dfn{complement character set}, which matches any 537character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} 538matches all characters @emph{except} letters and digits.@refill 539 540@samp{^} is not special in a character set unless it is the first 541character. The character following the @samp{^} is treated as if it 542were first (thus, @samp{-} and @samp{]} are not special there). 543 544Note that a complement character set can match a newline, unless 545newline is mentioned as one of the characters not to match. 546 547@item ^ 548@cindex @samp{^} in regexp 549@cindex beginning of line in regexp 550is a special character that matches the empty string, but only at the 551beginning of a line in the text being matched. Otherwise it fails to 552match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at 553the beginning of a line. 554 555When matching a string instead of a buffer, @samp{^} matches at the 556beginning of the string or after a newline character @samp{\n}. 557 558@item $ 559@cindex @samp{$} in regexp 560is similar to @samp{^} but matches only at the end of a line. Thus, 561@samp{x+$} matches a string of one @samp{x} or more at the end of a line. 562 563When matching a string instead of a buffer, @samp{$} matches at the end 564of the string or before a newline character @samp{\n}. 565 566@item \ 567@cindex @samp{\} in regexp 568has two functions: it quotes the special characters (including 569@samp{\}), and it introduces additional special constructs. 570 571Because @samp{\} quotes special characters, @samp{\$} is a regular 572expression that matches only @samp{$}, and @samp{\[} is a regular 573expression that matches only @samp{[}, and so on. 574 575@c Removed a paragraph here in lispref about doubling backslashes inside 576@c of Lisp strings. 577 578@end table 579 580@strong{Please note:} For historical compatibility, special characters 581are treated as ordinary ones if they are in contexts where their special 582meanings make no sense. For example, @samp{*foo} treats @samp{*} as 583ordinary since there is no preceding expression on which the @samp{*} 584can act. It is poor practice to depend on this behavior; quote the 585special character anyway, regardless of where it appears.@refill 586 587For the most part, @samp{\} followed by any character matches only 588that character. However, there are several exceptions: characters 589that, when preceded by @samp{\}, are special constructs. Such 590characters are always ordinary when encountered on their own. Here 591is a table of @samp{\} constructs: 592 593@table @kbd 594@item \| 595@cindex @samp{|} in regexp 596@cindex regexp alternative 597specifies an alternative. 598Two regular expressions @var{a} and @var{b} with @samp{\|} in 599between form an expression that matches anything that either @var{a} or 600@var{b} matches.@refill 601 602Thus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar} 603but no other string.@refill 604 605@samp{\|} applies to the largest possible surrounding expressions. Only a 606surrounding @samp{\( @dots{} \)} grouping can limit the grouping power of 607@samp{\|}.@refill 608 609Full backtracking capability exists to handle multiple uses of @samp{\|}. 610 611@item \( @dots{} \) 612@cindex @samp{(} in regexp 613@cindex @samp{)} in regexp 614@cindex regexp grouping 615is a grouping construct that serves three purposes: 616 617@enumerate 618@item 619To enclose a set of @samp{\|} alternatives for other operations. 620Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}. 621 622@item 623To enclose an expression for a suffix operator such as @samp{*} to act 624on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any 625(zero or more) number of @samp{na} strings.@refill 626 627@item 628To record a matched substring for future reference. 629@end enumerate 630 631This last application is not a consequence of the idea of a 632parenthetical grouping; it is a separate feature that happens to be 633assigned as a second meaning to the same @samp{\( @dots{} \)} construct 634because there is no conflict in practice between the two meanings. 635Here is an explanation of this feature: 636 637@item \@var{digit} 638matches the same text that matched the @var{digit}th occurrence of a 639@samp{\( @dots{} \)} construct. 640 641In other words, after the end of a @samp{\( @dots{} \)} construct. the 642matcher remembers the beginning and end of the text matched by that 643construct. Then, later on in the regular expression, you can use 644@samp{\} followed by @var{digit} to match that same text, whatever it 645may have been. 646 647The strings matching the first nine @samp{\( @dots{} \)} constructs 648appearing in a regular expression are assigned numbers 1 through 9 in 649the order that the open parentheses appear in the regular expression. 650So you can use @samp{\1} through @samp{\9} to refer to the text matched 651by the corresponding @samp{\( @dots{} \)} constructs. 652 653For example, @samp{\(.*\)\1} matches any newline-free string that is 654composed of two identical halves. The @samp{\(.*\)} matches the first 655half, which may be anything, but the @samp{\1} that follows must match 656the same exact text. 657 658@item \(?: @dots{} \) 659@cindex @samp{\(?:} in regexp 660@cindex regexp grouping 661is called a @dfn{shy} grouping operator, and it is used just like 662@samp{\( @dots{} \)}, except that it does not cause the matched 663substring to be recorded for future reference. 664 665This is useful when you need a lot of grouping @samp{\( @dots{} \)} 666constructs, but only want to remember one or two -- or if you have 667more than nine groupings and need to use backreferences to refer to 668the groupings at the end. 669 670Using @samp{\(?: @dots{} \)} rather than @samp{\( @dots{} \)} when you 671don't need the captured substrings ought to speed up your programs some, 672since it shortens the code path followed by the regular expression 673engine, as well as the amount of memory allocation and string copying it 674must do. The actual performance gain to be observed has not been 675measured or quantified as of this writing. 676@c This is used to good advantage by the font-locking code, and by 677@c `regexp-opt.el'. 678 679The shy grouping operator has been borrowed from Perl, and has not been 680available prior to XEmacs 20.3, nor is it available in FSF Emacs. 681 682@item \w 683@cindex @samp{\w} in regexp 684matches any word-constituent character. The editor syntax table 685determines which characters these are. @xref{Syntax}. 686 687@item \W 688@cindex @samp{\W} in regexp 689matches any character that is not a word constituent. 690 691@item \s@var{code} 692@cindex @samp{\s} in regexp 693matches any character whose syntax is @var{code}. Here @var{code} is a 694character that represents a syntax code: thus, @samp{w} for word 695constituent, @samp{-} for whitespace, @samp{(} for open parenthesis, 696etc. @xref{Syntax}, for a list of syntax codes and the characters that 697stand for them. 698 699@item \S@var{code} 700@cindex @samp{\S} in regexp 701matches any character whose syntax is not @var{code}. 702@end table 703 704 The following regular expression constructs match the empty string---that is, 705they don't use up any characters---but whether they match depends on the 706context. 707 708@table @kbd 709@item \` 710@cindex @samp{\`} in regexp 711matches the empty string, but only at the beginning 712of the buffer or string being matched against. 713 714@item \' 715@cindex @samp{\'} in regexp 716matches the empty string, but only at the end of 717the buffer or string being matched against. 718 719@item \= 720@cindex @samp{\=} in regexp 721matches the empty string, but only at point. 722(This construct is not defined when matching against a string.) 723 724@item \b 725@cindex @samp{\b} in regexp 726matches the empty string, but only at the beginning or 727end of a word. Thus, @samp{\bfoo\b} matches any occurrence of 728@samp{foo} as a separate word. @samp{\bballs?\b} matches 729@samp{ball} or @samp{balls} as a separate word.@refill 730 731@item \B 732@cindex @samp{\B} in regexp 733matches the empty string, but @emph{not} at the beginning or 734end of a word. 735 736@item \< 737@cindex @samp{\<} in regexp 738matches the empty string, but only at the beginning of a word. 739 740@item \> 741@cindex @samp{\>} in regexp 742matches the empty string, but only at the end of a word. 743@end table 744 745 Here is a complicated regexp used by Emacs to recognize the end of a 746sentence together with any whitespace that follows. It is given in Lisp 747syntax to enable you to distinguish the spaces from the tab characters. In 748Lisp syntax, the string constant begins and ends with a double-quote. 749@samp{\"} stands for a double-quote as part of the regexp, @samp{\\} for a 750backslash as part of the regexp, @samp{\t} for a tab and @samp{\n} for a 751newline. 752 753@example 754"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*" 755@end example 756 757@noindent 758This regexp contains four parts: a character set matching 759period, @samp{?} or @samp{!}; a character set matching close-brackets, 760quotes or parentheses, repeated any number of times; an alternative in 761backslash-parentheses that matches end-of-line, a tab or two spaces; and 762a character set matching whitespace characters, repeated any number of 763times. 764 765@node Search Case, Replace, Regexps, Search 766@section Searching and Case 767 768@vindex case-fold-search 769 All searches in Emacs normally ignore the case of the text they 770are searching through; if you specify searching for @samp{FOO}, 771@samp{Foo} and @samp{foo} are also considered a match. Regexps, and in 772particular character sets, are included: @samp{[aB]} matches @samp{a} 773or @samp{A} or @samp{b} or @samp{B}.@refill 774 775 If you want a case-sensitive search, set the variable 776@code{case-fold-search} to @code{nil}. Then all letters must match 777exactly, including case. @code{case-fold-search} is a per-buffer 778variable; altering it affects only the current buffer, but 779there is a default value which you can change as well. @xref{Locals}. 780You can also use @b{Case Sensitive Search} from the @b{Options} menu 781on your screen. 782 783@node Replace, Other Repeating Search, Search Case, Search 784@section Replacement Commands 785@cindex replacement 786@cindex string substitution 787@cindex global substitution 788 789 Global search-and-replace operations are not needed as often in Emacs as 790they are in other editors, but they are available. In addition to the 791simple @code{replace-string} command which is like that found in most 792editors, there is a @code{query-replace} command which asks you, for each 793occurrence of a pattern, whether to replace it. 794 795 The replace commands all replace one string (or regexp) with one 796replacement string. It is possible to perform several replacements in 797parallel using the command @code{expand-region-abbrevs}. @xref{Expanding 798Abbrevs}. 799 800@menu 801* Unconditional Replace:: Replacing all matches for a string. 802* Regexp Replace:: Replacing all matches for a regexp. 803* Replacement and Case:: How replacements preserve case of letters. 804* Query Replace:: How to use querying. 805@end menu 806 807@node Unconditional Replace, Regexp Replace, Replace, Replace 808@subsection Unconditional Replacement 809@findex replace-string 810@findex replace-regexp 811 812@table @kbd 813@item M-x replace-string @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} 814Replace every occurrence of @var{string} with @var{newstring}. 815@item M-x replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} 816Replace every match for @var{regexp} with @var{newstring}. 817@end table 818 819 To replace every instance of @samp{foo} after point with @samp{bar}, 820use the command @kbd{M-x replace-string} with the two arguments 821@samp{foo} and @samp{bar}. Replacement occurs only after point: if you 822want to cover the whole buffer you must go to the beginning first. By 823default, all occurrences up to the end of the buffer are replaced. To 824limit replacement to part of the buffer, narrow to that part of the 825buffer before doing the replacement (@pxref{Narrowing}). 826 827 When @code{replace-string} exits, point is left at the last occurrence 828replaced. The value of point when the @code{replace-string} command was 829issued is remembered on the mark ring; @kbd{C-u C-@key{SPC}} moves back 830there. 831 832 A numeric argument restricts replacement to matches that are surrounded 833by word boundaries. 834 835@node Regexp Replace, Replacement and Case, Unconditional Replace, Replace 836@subsection Regexp Replacement 837 838 @code{replace-string} replaces exact matches for a single string. The 839similar command @code{replace-regexp} replaces any match for a specified 840pattern. 841 842 In @code{replace-regexp}, the @var{newstring} need not be constant. It 843can refer to all or part of what is matched by the @var{regexp}. @samp{\&} 844in @var{newstring} stands for the entire text being replaced. 845@samp{\@var{d}} in @var{newstring}, where @var{d} is a digit, stands for 846whatever matched the @var{d}'th parenthesized grouping in @var{regexp}. 847For example,@refill 848 849@example 850M-x replace-regexp @key{RET} c[ad]+r @key{RET} \&-safe @key{RET} 851@end example 852 853@noindent 854would replace (for example) @samp{cadr} with @samp{cadr-safe} and @samp{cddr} 855with @samp{cddr-safe}. 856 857@example 858M-x replace-regexp @key{RET} \(c[ad]+r\)-safe @key{RET} \1 @key{RET} 859@end example 860 861@noindent 862would perform exactly the opposite replacements. To include a @samp{\} 863in the text to replace with, you must give @samp{\\}. 864 865@node Replacement and Case, Query Replace, Regexp Replace, Replace 866@subsection Replace Commands and Case 867 868@vindex case-replace 869@vindex case-fold-search 870 If the arguments to a replace command are in lower case, the command 871preserves case when it makes a replacement. Thus, the following command: 872 873@example 874M-x replace-string @key{RET} foo @key{RET} bar @key{RET} 875@end example 876 877@noindent 878replaces a lower-case @samp{foo} with a lower case @samp{bar}, @samp{FOO} 879with @samp{BAR}, and @samp{Foo} with @samp{Bar}. If upper-case letters are 880used in the second argument, they remain upper-case every time that 881argument is inserted. If upper-case letters are used in the first 882argument, the second argument is always substituted exactly as given, with 883no case conversion. Likewise, if the variable @code{case-replace} is set 884to @code{nil}, replacement is done without case conversion. If 885@code{case-fold-search} is set to @code{nil}, case is significant in 886matching occurrences of @samp{foo} to replace; also, case conversion of the 887replacement string is not done. 888 889@node Query Replace,, Replacement and Case, Replace 890@subsection Query Replace 891@cindex query replace 892 893@table @kbd 894@item M-% @var{string} @key{RET} @var{newstring} @key{RET} 895@itemx M-x query-replace @key{RET} @var{string} @key{RET} @var{newstring} @key{RET} 896Replace some occurrences of @var{string} with @var{newstring}. 897@item M-x query-replace-regexp @key{RET} @var{regexp} @key{RET} @var{newstring} @key{RET} 898Replace some matches for @var{regexp} with @var{newstring}. 899@end table 900 901@kindex M-% 902@findex query-replace 903 If you want to change only some of the occurrences of @samp{foo} to 904@samp{bar}, not all of them, you can use @code{query-replace} instead of 905@kbd{M-%}. This command finds occurrences of @samp{foo} one by one, 906displays each occurrence, and asks you whether to replace it. A numeric 907argument to @code{query-replace} tells it to consider only occurrences 908that are bounded by word-delimiter characters.@refill 909 910@findex query-replace-regexp 911 Aside from querying, @code{query-replace} works just like 912@code{replace-string}, and @code{query-replace-regexp} works 913just like @code{replace-regexp}.@refill 914 915 The things you can type when you are shown an occurrence of @var{string} 916or a match for @var{regexp} are: 917 918@kindex SPC (query-replace) 919@kindex DEL (query-replace) 920@kindex , (query-replace) 921@kindex ESC (query-replace) 922@kindex . (query-replace) 923@kindex ! (query-replace) 924@kindex ^ (query-replace) 925@kindex C-r (query-replace) 926@kindex C-w (query-replace) 927@kindex C-l (query-replace) 928 929@c WideCommands 930@table @kbd 931@item @key{SPC} 932to replace the occurrence with @var{newstring}. This preserves case, just 933like @code{replace-string}, provided @code{case-replace} is non-@code{nil}, 934as it normally is.@refill 935 936@item @key{DEL} 937to skip to the next occurrence without replacing this one. 938 939@item , @r{(Comma)} 940to replace this occurrence and display the result. You are then 941prompted for another input character. However, since the replacement has 942already been made, @key{DEL} and @key{SPC} are equivalent. At this 943point, you can type @kbd{C-r} (see below) to alter the replaced text. To 944undo the replacement, you can type @kbd{C-x u}. 945This exits the @code{query-replace}. If you want to do further 946replacement you must use @kbd{C-x @key{ESC} @key{ESC}} to restart (@pxref{Repetition}). 947 948@item @key{ESC} 949to exit without doing any more replacements. 950 951@item .@: @r{(Period)} 952to replace this occurrence and then exit. 953 954@item ! 955to replace all remaining occurrences without asking again. 956 957@item ^ 958to go back to the location of the previous occurrence (or what used to 959be an occurrence), in case you changed it by mistake. This works by 960popping the mark ring. Only one @kbd{^} in a row is allowed, because 961only one previous replacement location is kept during @code{query-replace}. 962 963@item C-r 964to enter a recursive editing level, in case the occurrence needs to be 965edited rather than just replaced with @var{newstring}. When you are 966done, exit the recursive editing level with @kbd{C-M-c} and the next 967occurrence will be displayed. @xref{Recursive Edit}. 968 969@item C-w 970to delete the occurrence, and then enter a recursive editing level as 971in @kbd{C-r}. Use the recursive edit to insert text to replace the 972deleted occurrence of @var{string}. When done, exit the recursive 973editing level with @kbd{C-M-c} and the next occurrence will be 974displayed. 975 976@item C-l 977to redisplay the screen and then give another answer. 978 979@item C-h 980to display a message summarizing these options, then give another 981answer. 982@end table 983 984 If you type any other character, Emacs exits the @code{query-replace}, and 985executes the character as a command. To restart the @code{query-replace}, 986use @kbd{C-x @key{ESC} @key{ESC}}, which repeats the @code{query-replace} because it 987used the minibuffer to read its arguments. @xref{Repetition, C-x ESC ESC}. 988 989@node Other Repeating Search,, Replace, Search 990@section Other Search-and-Loop Commands 991 992 Here are some other commands that find matches for a regular expression. 993They all operate from point to the end of the buffer. 994 995@findex list-matching-lines 996@findex occur 997@findex count-matches 998@findex delete-non-matching-lines 999@findex delete-matching-lines 1000@c grosscommands 1001@table @kbd 1002@item M-x occur 1003Print each line that follows point and contains a match for the 1004specified regexp. A numeric argument specifies the number of context 1005lines to print before and after each matching line; the default is 1006none. 1007 1008@kindex C-c C-c (Occur mode) 1009The buffer @samp{*Occur*} containing the output serves as a menu for 1010finding occurrences in their original context. Find an occurrence 1011as listed in @samp{*Occur*}, position point there, and type @kbd{C-c 1012C-c}; this switches to the buffer that was searched and moves point to 1013the original of the same occurrence. 1014 1015@item M-x list-matching-lines 1016Synonym for @kbd{M-x occur}. 1017 1018@item M-x count-matches 1019Print the number of matches following point for the specified regexp. 1020 1021@item M-x delete-non-matching-lines 1022Delete each line that follows point and does not contain a match for 1023the specified regexp. 1024 1025@item M-x delete-matching-lines 1026Delete each line that follows point and contains a match for the 1027specified regexp. 1028@end table 1029