@c -*-texinfo-*-@c This is part of the GNU Emacs Lisp Reference Manual.@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions.@setfilename ../info/searching@node Searching and Matching, Syntax Tables, Text, Top@chapter Searching and Matching@cindex searching GNU Emacs provides two ways to search through a buffer for specifiedtext: exact string searches and regular expression searches. After aregular expression search, you can examine the @dfn{match data} todetermine which text matched the whole regular expression or variousportions of it.@menu* String Search:: Search for an exact match.* Regular Expressions:: Describing classes of strings.* Regexp Search:: Searching for a match for a regexp.* POSIX Regexps:: Searching POSIX-style for the longest match.* Search and Replace:: Internals of @code{query-replace}.* Match Data:: Finding out which part of the text matched various parts of a regexp, after regexp search.* Searching and Case:: Case-independent or case-significant searching.* Standard Regexps:: Useful regexps for finding sentences, pages,...@end menu The @samp{skip-chars@dots{}} functions also perform a kind of searching.@xref{Skipping Characters}.@node String Search@section Searching for Strings@cindex string search These are the primitive functions for searching through the text in abuffer. They are meant for use in programs, but you may call theminteractively. If you do so, they prompt for the search string;@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat}is set to 1.@deffn Command search-forward string &optional limit noerror repeat This function searches forward from point for an exact match for@var{string}. If successful, it sets point to the end of the occurrencefound, and returns the new value of point. If no match is found, thevalue and side effects depend on @var{noerror} (see below).@c Emacs 19 feature In the following example, point is initially at the beginning of theline. Then @code{(search-forward "fox")} moves point after the lastletter of @samp{fox}:@example@group---------- Buffer: foo ----------@point{}The quick brown fox jumped over the lazy dog.---------- Buffer: foo ----------@end group@group(search-forward "fox") @result{} 20---------- Buffer: foo ----------The quick brown fox@point{} jumped over the lazy dog.---------- Buffer: foo ----------@end group@end example The argument @var{limit} specifies the upper bound to the search. (Itmust be a position in the current buffer.) No match extending afterthat position is accepted. If @var{limit} is omitted or @code{nil}, itdefaults to the end of the accessible portion of the buffer.@kindex search-failed What happens when the search fails depends on the value of@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}error is signaled. If @var{noerror} is @code{t}, @code{search-forward}returns @code{nil} and does nothing. If @var{noerror} is neither@code{nil} nor @code{t}, then @code{search-forward} moves point to theupper bound and returns @code{nil}. (It would be more consistent nowto return the new position of point in that case, but some programsmay depend on a value of @code{nil}.)If @var{repeat} is supplied (it must be a positive number), then thesearch is repeated that many times (each time starting at the end of theprevious time's match). If these successive searches succeed, thefunction succeeds, moving point and returning its new value. Otherwisethe search fails.@end deffn@deffn Command search-backward string &optional limit noerror repeatThis function searches backward from point for @var{string}. It isjust like @code{search-forward} except that it searches backwards andleaves point at the beginning of the match.@end deffn@deffn Command word-search-forward string &optional limit noerror repeat@cindex word searchThis function searches forward from point for a ``word'' match for@var{string}. If it finds a match, it sets point to the end of thematch found, and returns the new value of point.@c Emacs 19 featureWord matching regards @var{string} as a sequence of words, disregardingpunctuation that separates them. It searches the buffer for the samesequence of words. Each word must be distinct in the buffer (searchingfor the word @samp{ball} does not match the word @samp{balls}), but thedetails of punctuation and spacing are ignored (searching for @samp{ballboy} does match @samp{ball. Boy!}).In this example, point is initially at the beginning of the buffer; thesearch leaves it between the @samp{y} and the @samp{!}.@example@group---------- Buffer: foo ----------@point{}He said "Please! Findthe ball boy!"---------- Buffer: foo ----------@end group@group(word-search-forward "Please find the ball, boy.") @result{} 35---------- Buffer: foo ----------He said "Please! Findthe ball boy@point{}!"---------- Buffer: foo ----------@end group@end exampleIf @var{limit} is non-@code{nil} (it must be a position in the currentbuffer), then it is the upper bound to the search. The match found mustnot extend after that position.If @var{noerror} is @code{nil}, then @code{word-search-forward} signalsan error if the search fails. If @var{noerror} is @code{t}, then itreturns @code{nil} instead of signaling an error. If @var{noerror} isneither @code{nil} nor @code{t}, it moves point to @var{limit} (or theend of the buffer) and returns @code{nil}.If @var{repeat} is non-@code{nil}, then the search is repeated that manytimes. Point is positioned at the end of the last match.@end deffn@deffn Command word-search-backward string &optional limit noerror repeatThis function searches backward from point for a word match to@var{string}. This function is just like @code{word-search-forward}except that it searches backward and normally leaves point at thebeginning of the match.@end deffn@node Regular Expressions@section Regular Expressions@cindex regular expression@cindex regexp A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern thatdenotes a (possibly infinite) set of strings. Searching for matches fora regexp is a very powerful operation. This section explains how to writeregexps; the following section says how to search for them.@menu* Syntax of Regexps:: Rules for writing regular expressions.* Regexp Example:: Illustrates regular expression syntax.@end menu@node Syntax of Regexps@subsection Syntax of Regular Expressions Regular expressions have a syntax in which a few characters arespecial constructs and the rest are @dfn{ordinary}. An ordinarycharacter is a simple regular expression that matches that character andnothing else. The special characters are @samp{.}, @samp{*}, @samp{+},@samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no newspecial characters will be defined in the future. Any other characterappearing in a regular expression is ordinary, unless a @samp{\}precedes it.For example, @samp{f} is not a special character, so it is ordinary, andtherefore @samp{f} is a regular expression that matches the string@samp{f} and no other string. (It does @emph{not} match the string@samp{ff}.) Likewise, @samp{o} is a regular expression that matchesonly @samp{o}.@refillAny two regular expressions @var{a} and @var{b} can be concatenated. Theresult is a regular expression that matches a string if @var{a} matchessome amount of the beginning of that string and @var{b} matches the rest ofthe string.@refillAs a simple example, we can concatenate the regular expressions @samp{f}and @samp{o} to get the regular expression @samp{fo}, which matches onlythe string @samp{fo}. Still trivial. To do something more powerful, youneed to use one of the special characters. Here is a list of them:@need 1200@table @kbd@item .@: @r{(Period)}@cindex @samp{.} in regexpis a special character that matches any single character except a newline.Using concatenation, we can make regular expressions like @samp{a.b}, whichmatches any three-character string that begins with @samp{a} and ends with@samp{b}.@refill@item *@cindex @samp{*} in regexpis not a construct by itself; it is a suffix operator that means torepeat the preceding regular expression as many times as possible. In@samp{fo*}, the @samp{*} applies to the @samp{o}, so @samp{fo*} matchesone @samp{f} followed by any number of @samp{o}s. The case of zero@samp{o}s is allowed: @samp{fo*} does match @samp{f}.@refill@samp{*} always applies to the @emph{smallest} possible precedingexpression. Thus, @samp{fo*} has a repeating @samp{o}, not arepeating @samp{fo}.@refillThe matcher processes a @samp{*} construct by matching, immediately,as many repetitions as can be found. Then it continues with the restof the pattern. If that fails, backtracking occurs, discarding someof the matches of the @samp{*}-modified construct in case that makesit possible to match the rest of the pattern. For example, in matching@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} firsttries to match all three @samp{a}s; but the rest of the pattern is@samp{ar} and there is only @samp{r} left to match, so this try fails.The next alternative is for @samp{a*} to match only two @samp{a}s.With this choice, the rest of the regexp matches successfully.@refillNested repetition operators can be extremely slow if they specifybacktracking loops. For example, it could take hours for the regularexpression @samp{\(x+y*\)*a} to match the sequence@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is becauseEmacs must try each imaginable way of grouping the 35 @samp{x}'s beforeconcluding that none of them can work. To make sure your regularexpressions run fast, check nested repetitions carefully.@item +@cindex @samp{+} in regexpis a suffix operator similar to @samp{*} except that the precedingexpression must match at least once. So, for example, @samp{ca+r}matches the strings @samp{car} and @samp{caaaar} but not the string@samp{cr}, whereas @samp{ca*r} matches all three strings.@item ?@cindex @samp{?} in regexpis a suffix operator similar to @samp{*} except that the precedingexpression can match either once or not at all. For example,@samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anyhingelse.@item [ @dots{} ]@cindex character set (in regexp)@cindex @samp{[} in regexp@cindex @samp{]} in regexp@samp{[} begins a @dfn{character set}, which is terminated by a@samp{]}. In the simplest case, the characters between the two bracketsform the set. Thus, @samp{[ad]} matches either one @samp{a} or one@samp{d}, and @samp{[ad]*} matches any string composed of just @samp{a}sand @samp{d}s (including the empty string), from which it follows that@samp{c[ad]*r} matches @samp{cr}, @samp{car}, @samp{cdr},@samp{caddaar}, etc.@refillThe usual regular expression special characters are not special inside acharacter set. A completely different set of special characters existsinside character sets: @samp{]}, @samp{-} and @samp{^}.@refill@samp{-} is used for ranges of characters. To write a range, write twocharacters with a @samp{-} between them. Thus, @samp{[a-z]} matches anylower case letter. Ranges may be intermixed freely with individualcharacters, as in @samp{[a-z$%.]}, which matches any lower case letteror @samp{$}, @samp{%}, or a period.@refillTo include a @samp{]} in a character set, make it the first character.For example, @samp{[]a]} matches @samp{]} or @samp{a}. To include a@samp{-}, write @samp{-} as the first character in the set, or put itimmediately after a range. (You can replace one individual character@var{c} with the range @samp{@var{c}-@var{c}} to make a place to put the@samp{-}.) There is no way to write a set containing just @samp{-} and@samp{]}.To include @samp{^} in a set, put it anywhere but at the beginning ofthe set.@item [^ @dots{} ]@cindex @samp{^} in regexp@samp{[^} begins a @dfn{complement character set}, which matches anycharacter except the ones specified. Thus, @samp{[^a-z0-9A-Z]}matches all characters @emph{except} letters and digits.@refill@samp{^} is not special in a character set unless it is the firstcharacter. The character following the @samp{^} is treated as if itwere first (thus, @samp{-} and @samp{]} are not special there).Note that a complement character set can match a newline, unlessnewline is mentioned as one of the characters not to match.@item ^@cindex @samp{^} in regexp@cindex beginning of line in regexpis a special character that matches the empty string, but only at thebeginning of a line in the text being matched. Otherwise it fails tomatch anything. Thus, @samp{^foo} matches a @samp{foo} that occurs atthe beginning of a line.When matching a string instead of a buffer, @samp{^} matches at thebeginning of the string or after a newline character @samp{\n}.@item $@cindex @samp{$} in regexpis similar to @samp{^} but matches only at the end of a line. Thus,@samp{x+$} matches a string of one @samp{x} or more at the end of a line.When matching a string instead of a buffer, @samp{$} matches at the endof the string or before a newline character @samp{\n}.@item \@cindex @samp{\} in regexphas two functions: it quotes the special characters (including@samp{\}), and it introduces additional special constructs.Because @samp{\} quotes special characters, @samp{\$} is a regularexpression that matches only @samp{$}, and @samp{\[} is a regularexpression that matches only @samp{[}, and so on.Note that @samp{\} also has special meaning in the read syntax of Lispstrings (@pxref{String Type}), and must be quoted with @samp{\}. Forexample, the regular expression that matches the @samp{\} character is@samp{\\}. To write a Lisp string that contains the characters@samp{\\}, Lisp syntax requires you to quote each @samp{\} with another@samp{\}. Therefore, the read syntax for a regular expression matching@samp{\} is @code{"\\\\"}.@refill@end table@strong{Please note:} For historical compatibility, special charactersare treated as ordinary ones if they are in contexts where their specialmeanings make no sense. For example, @samp{*foo} treats @samp{*} asordinary since there is no preceding expression on which the @samp{*}can act. It is poor practice to depend on this behavior; quote thespecial character anyway, regardless of where it appears.@refillFor the most part, @samp{\} followed by any character matches onlythat character. However, there are several exceptions: charactersthat, when preceded by @samp{\}, are special constructs. Suchcharacters are always ordinary when encountered on their own. Hereis a table of @samp{\} constructs:@table @kbd@item \|@cindex @samp{|} in regexp@cindex regexp alternativespecifies an alternative.Two regular expressions @var{a} and @var{b} with @samp{\|} inbetween form an expression that matches anything that either @var{a} or@var{b} matches.@refillThus, @samp{foo\|bar} matches either @samp{foo} or @samp{bar}but no other string.@refill@samp{\|} applies to the largest possible surrounding expressions. Only asurrounding @samp{\( @dots{} \)} grouping can limit the grouping power of@samp{\|}.@refillFull backtracking capability exists to handle multiple uses of @samp{\|}.@item \( @dots{} \)@cindex @samp{(} in regexp@cindex @samp{)} in regexp@cindex regexp groupingis a grouping construct that serves three purposes:@enumerate@itemTo enclose a set of @samp{\|} alternatives for other operations.Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.@itemTo enclose an expression for a suffix operator such as @samp{*} to acton. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any(zero or more) number of @samp{na} strings.@refill@itemTo record a matched substring for future reference.@end enumerateThis last application is not a consequence of the idea of aparenthetical grouping; it is a separate feature that happens to beassigned as a second meaning to the same @samp{\( @dots{} \)} constructbecause there is no conflict in practice between the two meanings.Here is an explanation of this feature:@item \@var{digit}matches the same text that matched the @var{digit}th occurrence of a@samp{\( @dots{} \)} construct.In other words, after the end of a @samp{\( @dots{} \)} construct. thematcher remembers the beginning and end of the text matched by thatconstruct. Then, later on in the regular expression, you can use@samp{\} followed by @var{digit} to match that same text, whatever itmay have been.The strings matching the first nine @samp{\( @dots{} \)} constructsappearing in a regular expression are assigned numbers 1 through 9 inthe order that the open parentheses appear in the regular expression.So you can use @samp{\1} through @samp{\9} to refer to the text matchedby the corresponding @samp{\( @dots{} \)} constructs.For example, @samp{\(.*\)\1} matches any newline-free string that iscomposed of two identical halves. The @samp{\(.*\)} matches the firsthalf, which may be anything, but the @samp{\1} that follows must matchthe same exact text.@item \w@cindex @samp{\w} in regexpmatches any word-constituent character. The editor syntax tabledetermines which characters these are. @xref{Syntax Tables}.@item \W@cindex @samp{\W} in regexpmatches any character that is not a word constituent.@item \s@var{code}@cindex @samp{\s} in regexpmatches any character whose syntax is @var{code}. Here @var{code} is acharacter that represents a syntax code: thus, @samp{w} for wordconstituent, @samp{-} for whitespace, @samp{(} for open parenthesis,etc. @xref{Syntax Tables}, for a list of syntax codes and thecharacters that stand for them.@item \S@var{code}@cindex @samp{\S} in regexpmatches any character whose syntax is not @var{code}.@end table The following regular expression constructs match the empty string---that is,they don't use up any characters---but whether they match depends on thecontext.@table @kbd@item \`@cindex @samp{\`} in regexpmatches the empty string, but only at the beginningof the buffer or string being matched against.@item \'@cindex @samp{\'} in regexpmatches the empty string, but only at the end ofthe buffer or string being matched against.@item \=@cindex @samp{\=} in regexpmatches the empty string, but only at point.(This construct is not defined when matching against a string.)@item \b@cindex @samp{\b} in regexpmatches the empty string, but only at the beginning orend of a word. Thus, @samp{\bfoo\b} matches any occurrence of@samp{foo} as a separate word. @samp{\bballs?\b} matches@samp{ball} or @samp{balls} as a separate word.@refill@item \B@cindex @samp{\B} in regexpmatches the empty string, but @emph{not} at the beginning orend of a word.@item \<@cindex @samp{\<} in regexpmatches the empty string, but only at the beginning of a word.@item \>@cindex @samp{\>} in regexpmatches the empty string, but only at the end of a word.@end table@kindex invalid-regexp Not every string is a valid regular expression. For example, a stringwith unbalanced square brackets is invalid (with a few exceptions, suchas @samp{[]]}), and so is a string that ends with a single @samp{\}. Ifan invalid regular expression is passed to any of the search functions,an @code{invalid-regexp} error is signaled.@defun regexp-quote stringThis function returns a regular expression string that matches exactly@var{string} and nothing else. This allows you to request an exactstring match when calling a function that wants a regular expression.@example@group(regexp-quote "^The cat$") @result{} "\\^The cat\\$"@end group@end exampleOne use of @code{regexp-quote} is to combine an exact string match withcontext described as a regular expression. For example, this searchesfor the string that is the value of @code{string}, surrounded bywhitespace:@example@group(re-search-forward (concat "\\s-" (regexp-quote string) "\\s-"))@end group@end example@end defun@node Regexp Example@comment node-name, next, previous, up@subsection Complex Regexp Example Here is a complicated regexp, used by Emacs to recognize the end of asentence together with any whitespace that follows. It is the value ofthe variable @code{sentence-end}. First, we show the regexp as a string in Lisp syntax to distinguishspaces from tab characters. The string constant begins and ends with adouble-quote. @samp{\"} stands for a double-quote as part of thestring, @samp{\\} for a backslash as part of the string, @samp{\t} for atab and @samp{\n} for a newline.@example"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"@end example In contrast, if you evaluate the variable @code{sentence-end}, youwill see the following:@example@groupsentence-end@result{}"[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[ ]*"@end group@end example@noindentIn this output, tab and newline appear as themselves. This regular expression contains four parts in succession and can bedeciphered as follows:@table @code@item [.?!]The first part of the pattern is a character set that matches any one ofthree characters: period, question mark, and exclamation mark. Thematch must begin with one of these three characters.@item []\"')@}]*The second part of the pattern matches any closing braces and quotationmarks, zero or more of them, that may follow the period, question markor exclamation mark. The @code{\"} is Lisp syntax for a double-quote ina string. The @samp{*} at the end indicates that the immediatelypreceding regular expression (a character set, in this case) may berepeated zero or more times.@item \\($\\|@ $\\|\t\\|@ @ \\)The third part of the pattern matches the whitespace that follows theend of a sentence: the end of a line, or a tab, or two spaces. Thedouble backslashes mark the parentheses and vertical bars as regularexpression syntax; the parentheses delimit a group and the vertical barsseparate alternatives. The dollar sign is used to match the end of aline.@item [ \t\n]*Finally, the last part of the pattern matches any additional whitespacebeyond the minimum needed to end a sentence.@end table@node Regexp Search@section Regular Expression Searching@cindex regular expression searching@cindex regexp searching@cindex searching for regexp In GNU Emacs, you can search for the next match for a regexp eitherincrementally or not. For incremental search commands, see @ref{RegexpSearch, , Regular Expression Search, emacs, The GNU Emacs Manual}. Herewe describe only the search functions useful in programs. The principalone is @code{re-search-forward}.@deffn Command re-search-forward regexp &optional limit noerror repeatThis function searches forward in the current buffer for a string oftext that is matched by the regular expression @var{regexp}. Thefunction skips over any amount of text that is not matched by@var{regexp}, and leaves point at the end of the first match found.It returns the new value of point.If @var{limit} is non-@code{nil} (it must be a position in the currentbuffer), then it is the upper bound to the search. No match extendingafter that position is accepted.What happens when the search fails depends on the value of@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}error is signaled. If @var{noerror} is @code{t},@code{re-search-forward} does nothing and returns @code{nil}. If@var{noerror} is neither @code{nil} nor @code{t}, then@code{re-search-forward} moves point to @var{limit} (or the end of thebuffer) and returns @code{nil}.If @var{repeat} is supplied (it must be a positive number), then thesearch is repeated that many times (each time starting at the end of theprevious time's match). If these successive searches succeed, thefunction succeeds, moving point and returning its new value. Otherwisethe search fails.In the following example, point is initially before the @samp{T}.Evaluating the search call moves point to the end of that line (betweenthe @samp{t} of @samp{hat} and the newline).@example@group---------- Buffer: foo ----------I read "@point{}The cat in the hatcomes back" twice.---------- Buffer: foo ----------@end group@group(re-search-forward "[a-z]+" nil t 5) @result{} 27---------- Buffer: foo ----------I read "The cat in the hat@point{}comes back" twice.---------- Buffer: foo ----------@end group@end example@end deffn@deffn Command re-search-backward regexp &optional limit noerror repeatThis function searches backward in the current buffer for a string oftext that is matched by the regular expression @var{regexp}, leavingpoint at the beginning of the first text found.This function is analogous to @code{re-search-forward}, but they are notsimple mirror images. @code{re-search-forward} finds the match whosebeginning is as close as possible to the starting point. If@code{re-search-backward} were a perfect mirror image, it would find thematch whose end is as close as possible. However, in fact it finds thematch whose beginning is as close as possible. The reason is thatmatching a regular expression at a given spot always works frombeginning to end, and starts at a specified beginning position.A true mirror-image of @code{re-search-forward} would require a specialfeature for matching regexps from end to beginning. It's not worth thetrouble of implementing that.@end deffn@defun string-match regexp string &optional startThis function returns the index of the start of the first match forthe regular expression @var{regexp} in @var{string}, or @code{nil} ifthere is no match. If @var{start} is non-@code{nil}, the search startsat that index in @var{string}.For example,@example@group(string-match "quick" "The quick brown fox jumped quickly.") @result{} 4@end group@group(string-match "quick" "The quick brown fox jumped quickly." 8) @result{} 27@end group@end example@noindentThe index of the first character of thestring is 0, the index of the second character is 1, and so on.After this function returns, the index of the first character beyondthe match is available as @code{(match-end 0)}. @xref{Match Data}.@example@group(string-match "quick" "The quick brown fox jumped quickly." 8) @result{} 27@end group@group(match-end 0) @result{} 32@end group@end example@end defun@defun looking-at regexpThis function determines whether the text in the current buffer directlyfollowing point matches the regular expression @var{regexp}. ``Directlyfollowing'' means precisely that: the search is ``anchored'' and it cansucceed only starting with the first character following point. Theresult is @code{t} if so, @code{nil} otherwise.This function does not move point, but it updates the match data, whichyou can access using @code{match-beginning} and @code{match-end}.@xref{Match Data}.In this example, point is located directly before the @samp{T}. If itwere anywhere else, the result would be @code{nil}.@example@group---------- Buffer: foo ----------I read "@point{}The cat in the hatcomes back" twice.---------- Buffer: foo ----------(looking-at "The cat in the hat$") @result{} t@end group@end example@end defun@node POSIX Regexps@section POSIX Regular Expression Searching The usual regular expression functions do backtracking when necessaryto handle the @samp{\|} and repetition constructs, but they continuethis only until they find @emph{some} match. Then they succeed andreport the first match found. This section describes alternative search functions which perform thefull backtracking specified by the POSIX standard for regular expressionmatching. They continue backtracking until they have tried allpossibilities and found all matches, so they can report the longestmatch, as required by POSIX. This is much slower, so use thesefunctions only when you really need the longest match. In Emacs versions prior to 19.29, these functions did not exist, andthe functions described above implemented full POSIX backtracking.@defun posix-search-forward regexp &optional limit noerror repeatThis is like @code{re-search-forward} except that it performs the fullbacktracking specified by the POSIX standard for regular expressionmatching.@end defun@defun posix-search-backward regexp &optional limit noerror repeatThis is like @code{re-search-backward} except that it performs the fullbacktracking specified by the POSIX standard for regular expressionmatching.@end defun@defun posix-looking-at regexpThis is like @code{looking-at} except that it performs the fullbacktracking specified by the POSIX standard for regular expressionmatching.@end defun@defun posix-string-match regexp string &optional startThis is like @code{string-match} except that it performs the fullbacktracking specified by the POSIX standard for regular expressionmatching.@end defun@ignore@deffn Command delete-matching-lines regexpThis function is identical to @code{delete-non-matching-lines}, savethat it deletes what @code{delete-non-matching-lines} keeps.In the example below, point is located on the first line of text.@example@group---------- Buffer: foo ----------We hold these truthsto be self-evident,that all men are createdequal, and that they are---------- Buffer: foo ----------@end group@group(delete-matching-lines "the") @result{} nil---------- Buffer: foo ----------to be self-evident,that all men are created---------- Buffer: foo ----------@end group@end example@end deffn@deffn Command flush-lines regexpThis function is the same as @code{delete-matching-lines}.@end deffn@defun delete-non-matching-lines regexpThis function deletes all lines following point which don'tcontain a match for the regular expression @var{regexp}.@end defun@deffn Command keep-lines regexpThis function is the same as @code{delete-non-matching-lines}.@end deffn@deffn Command how-many regexpThis function counts the number of matches for @var{regexp} there are inthe current buffer following point. It prints this number inthe echo area, returning the string printed.@end deffn@deffn Command count-matches regexpThis function is a synonym of @code{how-many}.@end deffn@deffn Command list-matching-lines regexp nlinesThis function is a synonym of @code{occur}.Show all lines following point containing a match for @var{regexp}.Display each line with @var{nlines} lines before and after,or @code{-}@var{nlines} before if @var{nlines} is negative.@var{nlines} defaults to @code{list-matching-lines-default-context-lines}.Interactively it is the prefix arg.The lines are shown in a buffer named @samp{*Occur*}.It serves as a menu to find any of the occurrences in this buffer.@kbd{C-h m} (@code{describe-mode} in that buffer gives help.@end deffn@defopt list-matching-lines-default-context-linesDefault value is 0.Default number of context lines to include around a @code{list-matching-lines}match. A negative number means to include that many lines before the match.A positive number means to include that many lines both before and after.@end defopt@end ignore@node Search and Replace@section Search and Replace@cindex replacement@defun perform-replace from-string replacements query-flag regexp-flag delimited-flag &optional repeat-count mapThis function is the guts of @code{query-replace} and related commands.It searches for occurrences of @var{from-string} and replaces some orall of them. If @var{query-flag} is @code{nil}, it replaces alloccurrences; otherwise, it asks the user what to do about each one.If @var{regexp-flag} is non-@code{nil}, then @var{from-string} isconsidered a regular expression; otherwise, it must match literally. If@var{delimited-flag} is non-@code{nil}, then only replacementssurrounded by word boundaries are considered.The argument @var{replacements} specifies what to replace occurrenceswith. If it is a string, that string is used. It can also be a list ofstrings, to be used in cyclic order.If @var{repeat-count} is non-@code{nil}, it should be an integer. Thenit specifies how many times to use each of the strings in the@var{replacements} list before advancing cyclicly to the next one.Normally, the keymap @code{query-replace-map} defines the possible userresponses for queries. The argument @var{map}, if non-@code{nil}, is akeymap to use instead of @code{query-replace-map}.@end defun@defvar query-replace-mapThis variable holds a special keymap that defines the valid userresponses for @code{query-replace} and related functions, as well as@code{y-or-n-p} and @code{map-y-or-n-p}. It is unusual in two ways:@itemize @bullet@itemThe ``key bindings'' are not commands, just symbols that are meaningfulto the functions that use this map.@itemPrefix keys are not supported; each key binding must be for a single eventkey sequence. This is because the functions don't use read key sequence toget the input; instead, they read a single event and look it up ``by hand.''@end itemize@end defvarHere are the meaningful ``bindings'' for @code{query-replace-map}.Several of them are meaningful only for @code{query-replace} andfriends.@table @code@item actDo take the action being considered---in other words, ``yes.''@item skipDo not take action for this question---in other words, ``no.''@item exitAnswer this question ``no,'' and give up on the entire series ofquestions, assuming that the answers will be ``no.''@item act-and-exitAnswer this question ``yes,'' and give up on the entire series ofquestions, assuming that subsequent answers will be ``no.''@item act-and-showAnswer this question ``yes,'' but show the results---don't advance yetto the next question.@item automaticAnswer this question and all subsequent questions in the series with``yes,'' without further user interaction.@item backupMove back to the previous place that a question was asked about.@item editEnter a recursive edit to deal with this question---instead of anyother action that would normally be taken.@item delete-and-editDelete the text being considered, then enter a recursive edit to replaceit.@item recenterRedisplay and center the window, then ask the same question again.@item quitPerform a quit right away. Only @code{y-or-n-p} and related functionsuse this answer.@item helpDisplay some help, then ask again.@end table@node Match Data@section The Match Data@cindex match data Emacs keeps track of the positions of the start and end of segments oftext found during a regular expression search. This means, for example,that you can search for a complex pattern, such as a date in an Rmailmessage, and then extract parts of the match under control of thepattern. Because the match data normally describe the most recent search only,you must be careful not to do another search inadvertently between thesearch you wish to refer back to and the use of the match data. If youcan't avoid another intervening search, you must save and restore thematch data around it, to prevent it from being overwritten.@menu* Simple Match Data:: Accessing single items of match data, such as where a particular subexpression started.* Replacing Match:: Replacing a substring that was matched.* Entire Match Data:: Accessing the entire match data at once, as a list.* Saving Match Data:: Saving and restoring the match data.@end menu@node Simple Match Data@subsection Simple Match Data Access This section explains how to use the match data to find out what wasmatched by the last search or match operation. You can ask about the entire matching text, or about a particularparenthetical subexpression of a regular expression. The @var{count}argument in the functions below specifies which. If @var{count} iszero, you are asking about the entire match. If @var{count} ispositive, it specifies which subexpression you want. Recall that the subexpressions of a regular expression are thoseexpressions grouped with escaped parentheses, @samp{\(@dots{}\)}. The@var{count}th subexpression is found by counting occurrences of@samp{\(} from the beginning of the whole regular expression. The firstsubexpression is numbered 1, the second 2, and so on. Only regularexpressions can have subexpressions---after a simple string search, theonly information available is about the entire match.@defun match-string count &optional in-stringThis function returns, as a string, the text matched in the last searchor match operation. It returns the entire text if @var{count} is zero,or just the portion corresponding to the @var{count}th parentheticalsubexpression, if @var{count} is positive. If @var{count} is out ofrange, or if that subexpression didn't match anything, the value is@code{nil}.If the last such operation was done against a string with@code{string-match}, then you should pass the same string as theargument @var{in-string}. Otherwise, after a buffer search or match,you should omit @var{in-string} or pass @code{nil} for it; but youshould make sure that the current buffer when you call@code{match-string} is the one in which you did the searching ormatching.@end defun@defun match-beginning countThis function returns the position of the start of text matched by thelast regular expression searched for, or a subexpression of it.If @var{count} is zero, then the value is the position of the start ofthe entire match. Otherwise, @var{count} specifies a subexpression inthe regular expresion, and the value of the function is the startingposition of the match for that subexpression.The value is @code{nil} for a subexpression inside a @samp{\|}alternative that wasn't used in the match.@end defun@defun match-end countThis function is like @code{match-beginning} except that it returns theposition of the end of the match, rather than the position of thebeginning.@end defun Here is an example of using the match data, with a comment showing thepositions within the text:@example@group(string-match "\\(qu\\)\\(ick\\)" "The quick fox jumped quickly.") ;0123456789 @result{} 4@end group@group(match-string 0 "The quick fox jumped quickly.") @result{} "quick"(match-string 1 "The quick fox jumped quickly.") @result{} "qu"(match-string 2 "The quick fox jumped quickly.") @result{} "ick"@end group@group(match-beginning 1) ; @r{The beginning of the match} @result{} 4 ; @r{with @samp{qu} is at index 4.}@end group@group(match-beginning 2) ; @r{The beginning of the match} @result{} 6 ; @r{with @samp{ick} is at index 6.}@end group@group(match-end 1) ; @r{The end of the match} @result{} 6 ; @r{with @samp{qu} is at index 6.}(match-end 2) ; @r{The end of the match} @result{} 9 ; @r{with @samp{ick} is at index 9.}@end group@end example Here is another example. Point is initially located at the beginningof the line. Searching moves point to between the space and the word@samp{in}. The beginning of the entire match is at the 9th character ofthe buffer (@samp{T}), and the beginning of the match for the firstsubexpression is at the 13th character (@samp{c}).@example@group(list (re-search-forward "The \\(cat \\)") (match-beginning 0) (match-beginning 1)) @result{} (9 9 13)@end group@group---------- Buffer: foo ----------I read "The cat @point{}in the hat comes back" twice. ^ ^ 9 13---------- Buffer: foo ----------@end group@end example@noindent(In this case, the index returned is a buffer position; the firstcharacter of the buffer counts as 1.)@node Replacing Match@subsection Replacing the Text That Matched This function replaces the text matched by the last search with@var{replacement}.@cindex case in replacements@defun replace-match replacement &optional fixedcase literal string subexpThis function replaces the text in the buffer (or in @var{string}) thatwas matched by the last search. It replaces that text with@var{replacement}.If you did the last search in a buffer, you should specify @code{nil}for @var{string}. Then @code{replace-match} does the replacement byediting the buffer; it leaves point at the end of the replacement text,and returns @code{t}.If you did the search in a string, pass the same string as @var{string}.Then @code{replace-match} does the replacement by constructing andreturning a new string.If @var{fixedcase} is non-@code{nil}, then the case of the replacementtext is not changed; otherwise, the replacement text is converted to adifferent case depending upon the capitalization of the text to bereplaced. If the original text is all upper case, the replacement textis converted to upper case. If the first word of the original text iscapitalized, then the first word of the replacement text is capitalized.If the original text contains just one word, and that word is a capitalletter, @code{replace-match} considers this a capitalized first wordrather than all upper case.If @code{case-replace} is @code{nil}, then case conversion is not done,regardless of the value of @var{fixed-case}. @xref{Searching and Case}.If @var{literal} is non-@code{nil}, then @var{replacement} is insertedexactly as it is, the only alterations being case changes as needed.If it is @code{nil} (the default), then the character @samp{\} is treatedspecially. If a @samp{\} appears in @var{replacement}, then it must bepart of one of the following sequences:@table @asis@item @samp{\&}@cindex @samp{&} in replacement@samp{\&} stands for the entire text being replaced.@item @samp{\@var{n}}@cindex @samp{\@var{n}} in replacement@samp{\@var{n}}, where @var{n} is a digit, stands for the text thatmatched the @var{n}th subexpression in the original regexp.Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.@item @samp{\\}@cindex @samp{\} in replacement@samp{\\} stands for a single @samp{\} in the replacement text.@end tableIf @var{subexp} is non-@code{nil}, that says to replace justsubexpression number @var{subexp} of the regexp that was matched, notthe entire match. For example, after matching @samp{foo \(ba*r\)},calling @code{replace-match} with 1 as @var{subexp} means to replacejust the text that matched @samp{\(ba*r\)}.@end defun@node Entire Match Data@subsection Accessing the Entire Match Data The functions @code{match-data} and @code{set-match-data} read orwrite the entire match data, all at once.@defun match-dataThis function returns a newly constructed list containing all theinformation on what text the last search matched. Element zero is theposition of the beginning of the match for the whole expression; elementone is the position of the end of the match for the expression. Thenext two elements are the positions of the beginning and end of thematch for the first subexpression, and so on. In general, element@ifinfonumber 2@var{n}@end ifinfo@texnumber {\mathsurround=0pt $2n$}@end texcorresponds to @code{(match-beginning @var{n})}; andelement@ifinfonumber 2@var{n} + 1@end ifinfo@texnumber {\mathsurround=0pt $2n+1$}@end texcorresponds to @code{(match-end @var{n})}.All the elements are markers or @code{nil} if matching was done on abuffer, and all are integers or @code{nil} if matching was done on astring with @code{string-match}. (In Emacs 18 and earlier versions,markers were used even for matching on a string, except in the caseof the integer 0.)As always, there must be no possibility of intervening searches betweenthe call to a search function and the call to @code{match-data} that isintended to access the match data for that search.@example@group(match-data) @result{} (#<marker at 9 in foo> #<marker at 17 in foo> #<marker at 13 in foo> #<marker at 17 in foo>)@end group@end example@end defun@defun set-match-data match-listThis function sets the match data from the elements of @var{match-list},which should be a list that was the value of a previous call to@code{match-data}.If @var{match-list} refers to a buffer that doesn't exist, you don't getan error; that sets the match data in a meaningless but harmless way.@findex store-match-data@code{store-match-data} is an alias for @code{set-match-data}.@end defun@node Saving Match Data@subsection Saving and Restoring the Match Data When you call a function that may do a search, you may need to saveand restore the match data around that call, if you want to preserve thematch data from an earlier search for later use. Here is an examplethat shows the problem that arises if you fail to save the match data:@example@group(re-search-forward "The \\(cat \\)") @result{} 48(foo) ; @r{Perhaps @code{foo} does} ; @r{more searching.}(match-end 0) @result{} 61 ; @r{Unexpected result---not 48!}@end group@end example You can save and restore the match data with @code{save-match-data}:@defmac save-match-data body@dots{}This special form executes @var{body}, saving and restoring the matchdata around it.@end defmac You can use @code{set-match-data} together with @code{match-data} toimitate the effect of the special form @code{save-match-data}. This isuseful for writing code that can run in Emacs 18. Here is how:@example@group(let ((data (match-data))) (unwind-protect @dots{} ; @r{May change the original match data.} (set-match-data data)))@end group@end example Emacs automatically saves and restores the match data when it runsprocess filter functions (@pxref{Filter Functions}) and processsentinels (@pxref{Sentinels}).@ignore Here is a function which restores the match data provided the bufferassociated with it still exists.@smallexample@group(defun restore-match-data (data)@c It is incorrect to split the first line of a doc string.@c If there's a problem here, it should be solved in some other way. "Restore the match data DATA unless the buffer is missing." (catch 'foo (let ((d data))@end group (while d (and (car d) (null (marker-buffer (car d)))@group ;; @file{match-data} @r{buffer is deleted.} (throw 'foo nil)) (setq d (cdr d))) (set-match-data data))))@end group@end smallexample@end ignore@node Searching and Case@section Searching and Case@cindex searching and case By default, searches in Emacs ignore the case of the text they aresearching through; if you specify searching for @samp{FOO}, then@samp{Foo} or @samp{foo} is also considered a match. Regexps, and inparticular character sets, are included: thus, @samp{[aB]} would match@samp{a} or @samp{A} or @samp{b} or @samp{B}. If you do not want this feature, set the variable@code{case-fold-search} to @code{nil}. Then all letters must matchexactly, including case. This is a buffer-local variable; altering thevariable affects only the current buffer. (@xref{Intro toBuffer-Local}.) Alternatively, you may change the value of@code{default-case-fold-search}, which is the default value of@code{case-fold-search} for buffers that do not override it. Note that the user-level incremental search feature handles casedistinctions differently. When given a lower case letter, it looks fora match of either case, but when given an upper case letter, it looksfor an upper case letter only. But this has nothing to do with thesearching functions Lisp functions use.@defopt case-replaceThis variable determines whether the replacement functions shouldpreserve case. If the variable is @code{nil}, that means to use thereplacement text verbatim. A non-@code{nil} value means to convert thecase of the replacement text according to the text being replaced.The function @code{replace-match} is where this variable actually hasits effect. @xref{Replacing Match}.@end defopt@defopt case-fold-searchThis buffer-local variable determines whether searches should ignorecase. If the variable is @code{nil} they do not ignore case; otherwisethey do ignore case.@end defopt@defvar default-case-fold-searchThe value of this variable is the default value for@code{case-fold-search} in buffers that do not override it. This is thesame as @code{(default-value 'case-fold-search)}.@end defvar@node Standard Regexps@section Standard Regular Expressions Used in Editing@cindex regexps used standardly in editing@cindex standard regexps used in editing This section describes some variables that hold regular expressionsused for certain purposes in editing:@defvar page-delimiterThis is the regexp describing line-beginnings that separate pages. Thedefault value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});this matches a line that starts with a formfeed character.@end defvar The following two regular expressions should @emph{not} assume thematch always starts at the beginning of a line; they should not use@samp{^} to anchor the match. Most often, the paragraph commands docheck for a match only at the beginning of a line, which means that@samp{^} would be superfluous. When there is a nonzero left margin,they accept matches that start after the left margin. In that case, a@samp{^} would be incorrect. However, a @samp{^} is harmless in modeswhere a left margin is never used.@defvar paragraph-separateThis is the regular expression for recognizing the beginning of a linethat separates paragraphs. (If you change this, you may have tochange @code{paragraph-start} also.) The default value is@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely ofspaces, tabs, and form feeds (after its left margin).@end defvar@defvar paragraph-startThis is the regular expression for recognizing the beginning of a linethat starts @emph{or} separates paragraphs. The default value is@w{@code{"[@ \t\n\f]"}}, which matches a line starting with a space, tab,newline, or form feed (after its left margin).@end defvar@defvar sentence-endThis is the regular expression describing the end of a sentence. (Allparagraph boundaries also end sentences, regardless.) The default valueis:@example"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"@end exampleThis means a period, question mark or exclamation mark, followedoptionally by a closing parenthetical character, followed by tabs,spaces or new lines.For a detailed explanation of this regular expression, see @ref{RegexpExample}.@end defvar