@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 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/searching
-@node Searching and Matching, Syntax Tables, Text, Top
+@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
@chapter Searching and Matching
@cindex searching
* 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.
@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat}
is set to 1.
+ These search functions convert the search string to multibyte if the
+buffer is multibyte; they convert the search string to unibyte if the
+buffer is unibyte. @xref{Text Representations}.
+
@deffn Command search-forward string &optional limit noerror repeat
- This function searches forward from point for an exact match for
+This function searches forward from point for an exact match for
@var{string}. If successful, it sets point to the end of the occurrence
found, and returns the new value of point. If no match is found, the
value and side effects depend on @var{noerror} (see below).
@c Emacs 19 feature
- In the following example, point is initially at the beginning of the
+In the following example, point is initially at the beginning of the
line. Then @code{(search-forward "fox")} moves point after the last
letter of @samp{fox}:
@end group
@end example
- The argument @var{limit} specifies the upper bound to the search. (It
+The argument @var{limit} specifies the upper bound to the search. (It
must be a position in the current buffer.) No match extending after
that position is accepted. If @var{limit} is omitted or @code{nil}, it
defaults to the end of the accessible portion of the buffer.
@kindex search-failed
- What happens when the search fails depends on the value of
+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 the
-upper bound and returns @code{nil}. (It would be more consistent now
-to return the new position of point in that case, but some programs
-may depend on a value of @code{nil}.)
+upper bound and returns @code{nil}. (It would be more consistent now to
+return the new position of point in that case, but some existing
+programs may depend on a value of @code{nil}.)
If @var{repeat} is supplied (it must be a positive number), then the
search is repeated that many times (each time starting at the end of the
need to use one of the special characters. Here is a list of them:
@need 1200
-@table @kbd
-@item .@: @r{(Period)}
+@table @asis
+@item @samp{.}@: @r{(Period)}
@cindex @samp{.} in regexp
is a special character that matches any single character except a newline.
Using concatenation, we can make regular expressions like @samp{a.b}, which
matches any three-character string that begins with @samp{a} and ends with
@samp{b}.@refill
-@item *
+@item @samp{*}
@cindex @samp{*} in regexp
-is not a construct by itself; it is a suffix operator that means to
-repeat the preceding regular expression as many times as possible. In
-@samp{fo*}, the @samp{*} applies to the @samp{o}, so @samp{fo*} matches
-one @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
+is not a construct by itself; it is a postfix operator that means to
+match the preceding regular expression repetitively as many times as
+possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
+@samp{o}s).
@samp{*} always applies to the @emph{smallest} possible preceding
-expression. Thus, @samp{fo*} has a repeating @samp{o}, not a
-repeating @samp{fo}.@refill
-
-The matcher processes a @samp{*} construct by matching, immediately,
-as many repetitions as can be found. Then it continues with the rest
-of the pattern. If that fails, backtracking occurs, discarding some
-of the matches of the @samp{*}-modified construct in case that makes
-it possible to match the rest of the pattern. For example, in matching
-@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
-tries to match all three @samp{a}s; but the rest of the pattern is
+expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
+@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
+
+The matcher processes a @samp{*} construct by matching, immediately, as
+many repetitions as can be found. Then it continues with the rest of
+the pattern. If that fails, backtracking occurs, discarding some of the
+matches of the @samp{*}-modified construct in the hope that that will
+make it possible to match the rest of the pattern. For example, in
+matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
+first tries 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.@refill
-
-@item +
+The next alternative is for @samp{a*} to match only two @samp{a}s. With
+this choice, the rest of the regexp matches successfully.@refill
+
+Nested repetition operators can be extremely slow if they specify
+backtracking loops. For example, it could take hours for the regular
+expression @samp{\(x+y*\)*a} to try to match the sequence
+@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately fails.
+The slowness is because Emacs must try each imaginable way of grouping
+the 35 @samp{x}'s before concluding that none of them can work. To make
+sure your regular expressions run fast, check nested repetitions
+carefully.
+
+@item @samp{+}
@cindex @samp{+} in regexp
-is a suffix operator similar to @samp{*} except that the preceding
-expression must match at least once. So, for example, @samp{ca+r}
+is a postfix operator, similar to @samp{*} except that it must match
+the preceding expression 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 ?
+@item @samp{?}
@cindex @samp{?} in regexp
-is a suffix operator similar to @samp{*} except that the preceding
-expression can match either once or not at all. For example,
-@samp{ca?r} matches @samp{car} or @samp{cr}, but does not match anyhing
-else.
+is a postfix operator, similar to @samp{*} except that it must match the
+preceding expression either once or not at all. For example,
+@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
-@item [ @dots{} ]
-@cindex character set (in regexp)
+@item @samp{[ @dots{} ]}
+@cindex character alternative (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 brackets
-form 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}s
-and @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.@refill
-
-The usual regular expression special characters are not special inside a
-character set. A completely different set of special characters exists
-inside character sets: @samp{]}, @samp{-} and @samp{^}.@refill
-
-@samp{-} is used for ranges of characters. To write a range, write two
-characters with a @samp{-} between them. Thus, @samp{[a-z]} matches any
-lower case letter. Ranges may be intermixed freely with individual
-characters, as in @samp{[a-z$%.]}, which matches any lower case letter
-or @samp{$}, @samp{%}, or a period.@refill
-
-To 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 it
-immediately 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 of
-the set.
-
-@item [^ @dots{} ]
+is a @dfn{character alternative}, which begins with @samp{[} and is
+terminated by @samp{]}. In the simplest case, the characters between
+the two brackets are what this character alternative can match.
+
+Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
+@samp{[ad]*} matches any string composed of just @samp{a}s and @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.
+
+You can also include character ranges in a character alternative, by
+writing the starting and ending characters with a @samp{-} between them.
+Thus, @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
+intermixed freely with individual characters, as in @samp{[a-z$%.]},
+which matches any lower case ASCII letter or @samp{$}, @samp{%} or
+period.
+
+You cannot always match all non-@sc{ASCII} characters with the regular
+expression @samp{[\200-\377]}. This works when searching a unibyte
+buffer or string (@pxref{Text Representations}), but not in a multibyte
+buffer or string, because many non-@sc{ASCII} characters have codes
+above octal 0377. However, the regular expression @samp{[^\000-\177]}
+does match all non-@sc{ASCII} characters, in both multibyte and unibyte
+representations, because only the @sc{ASCII} characters are excluded.
+
+The beginning and end of a range must be in the same character set
+(@pxref{Character Sets}). Thus, @samp{[a-\x8c0]} is invalid because
+@samp{a} is in the @sc{ASCII} character set but the character 0x8c0
+(@samp{A} with grave accent) is in the Emacs character set for Latin-1.
+
+Note that the usual regexp special characters are not special inside a
+character alternative. A completely different set of characters are
+special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
+
+To include a @samp{]} in a character alternative, you must make it the
+first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
+To include a @samp{-}, write @samp{-} as the first or last character of
+the character alternative, or put it after a range. Thus, @samp{[]-]}
+matches both @samp{]} and @samp{-}.
+
+To include @samp{^} in a character alternative, put it anywhere but at
+the beginning.
+
+@item @samp{[^ @dots{} ]}
@cindex @samp{^} in regexp
-@samp{[^} begins a @dfn{complement character set}, which matches any
-character except the ones specified. Thus, @samp{[^a-z0-9A-Z]}
-matches all characters @emph{except} letters and digits.@refill
+@samp{[^} begins a @dfn{complemented character alternative}, which matches any
+character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
+all characters @emph{except} letters and digits.
-@samp{^} is not special in a character set unless it is the first
+@samp{^} is not special in a character alternative unless it is the first
character. The character following the @samp{^} is treated as if it
-were first (thus, @samp{-} and @samp{]} are not special there).
+were first (in other words, @samp{-} and @samp{]} are not special there).
-Note that a complement character set can match a newline, unless
-newline is mentioned as one of the characters not to match.
+A complemented character alternative can match a newline, unless newline is
+mentioned as one of the characters not to match. This is in contrast to
+the handling of regexps in programs such as @code{grep}.
-@item ^
+@item @samp{^}
@cindex @samp{^} in regexp
@cindex beginning of line in regexp
is a special character that matches the empty string, but only at the
When matching a string instead of a buffer, @samp{^} matches at the
beginning of the string or after a newline character @samp{\n}.
-@item $
+@item @samp{$}
@cindex @samp{$} in regexp
is 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 end
of the string or before a newline character @samp{\n}.
-@item \
+@item @samp{\}
@cindex @samp{\} in regexp
has two functions: it quotes the special characters (including
@samp{\}), and it introduces additional special constructs.
can act. It is poor practice to depend on this behavior; quote the
special character anyway, regardless of where it appears.@refill
-For the most part, @samp{\} followed by any character matches only
-that character. However, there are several exceptions: characters
-that, when preceded by @samp{\}, are special constructs. Such
-characters are always ordinary when encountered on their own. Here
-is a table of @samp{\} constructs:
+For the most part, @samp{\} followed by any character matches only that
+character. However, there are several exceptions: two-character
+sequences starting with @samp{\} which have special meanings. (The
+second character in such a sequence is always ordinary when used on its
+own.) Here is a table of @samp{\} constructs.
-@table @kbd
+@table @samp
@item \|
@cindex @samp{|} in regexp
@cindex regexp alternative
@enumerate
@item
-To enclose a set of @samp{\|} alternatives for other operations.
-Thus, @samp{\(foo\|bar\)x} matches either @samp{foox} or @samp{barx}.
+To enclose a set of @samp{\|} alternatives for other operations. Thus,
+the regular expression @samp{\(foo\|bar\)x} matches either @samp{foox}
+or @samp{barx}.
@item
-To enclose an expression for a suffix operator such as @samp{*} to act
-on. Thus, @samp{ba\(na\)*} matches @samp{bananana}, etc., with any
-(zero or more) number of @samp{na} strings.@refill
+To enclose a complicated expression for the postfix operators @samp{*},
+@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
+@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
+number (zero or more) of @samp{na} strings.
@item
To record a matched substring for future reference.
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. the
+In other words, after the end of a @samp{\( @dots{} \)} construct, the
matcher remembers the beginning and end of the text matched by that
construct. Then, later on in the regular expression, you can use
@samp{\} followed by @var{digit} to match that same text, whatever it
matches any character whose syntax is @var{code}. Here @var{code} is a
character that represents a syntax code: thus, @samp{w} for word
constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
-etc. @xref{Syntax Tables}, for a list of syntax codes and the
-characters that stand for them.
+etc. To represent whitespace syntax, use either @samp{-} or a space
+character. @xref{Syntax Class Table}, for a list of syntax codes and
+the characters that stand for them.
@item \S@var{code}
@cindex @samp{\S} in regexp
they don't use up any characters---but whether they match depends on the
context.
-@table @kbd
+@table @samp
@item \`
@cindex @samp{\`} in regexp
matches the empty string, but only at the beginning
@samp{foo} as a separate word. @samp{\bballs?\b} matches
@samp{ball} or @samp{balls} as a separate word.@refill
+@samp{\b} matches at the beginning or end of the buffer
+regardless of what text appears next to it.
+
@item \B
@cindex @samp{\B} in regexp
matches the empty string, but @emph{not} at the beginning or
@item \<
@cindex @samp{\<} in regexp
matches the empty string, but only at the beginning of a word.
+@samp{\<} matches at the beginning of the buffer only if a
+word-constituent character follows.
@item \>
@cindex @samp{\>} in regexp
-matches the empty string, but only at the end of a word.
+matches the empty string, but only at the end of a word. @samp{\>}
+matches at the end of the buffer only if the contents end with a
+word-constituent character.
@end table
@kindex invalid-regexp
One use of @code{regexp-quote} is to combine an exact string match with
context described as a regular expression. For example, this searches
-for the string that is the value of @code{string}, surrounded by
+for the string that is the value of @var{string}, surrounded by
whitespace:
@example
@end example
@end defun
+@defun regexp-opt strings &optional paren
+@tindex regexp-opt
+This function returns an efficient regular expression that will match
+any of the strings @var{strings}. This is useful when you need to make
+matching or searching as fast as possible---for example, for Font Lock
+mode.
+
+If the optional argument @var{paren} is non-@code{nil}, then the
+returned regular expression is always enclosed by at least one
+parentheses-grouping construct.
+
+This simplified definition of @code{regexp-opt} produces a
+regular expression which is equivalent to the actual value
+(but not as efficient):
+
+@example
+(defun regexp-opt (strings paren)
+ (let ((open-paren (if paren "\\(" ""))
+ (close-paren (if paren "\\)" "")))
+ (concat open-paren
+ (mapconcat 'regexp-quote strings "\\|")
+ close-paren)))
+@end example
+@end defun
+
+@defun regexp-opt-depth regexp
+@tindex regexp-opt-depth
+This function returns the total number of grouping constructs
+(parenthesized expressions) in @var{regexp}.
+@end defun
+
@node Regexp Example
@comment node-name, next, previous, up
@subsection Complex Regexp Example
"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
@end example
- In contrast, if you evaluate the variable @code{sentence-end}, you
+@noindent
+In contrast, if you evaluate the variable @code{sentence-end}, you
will see the following:
@example
@group
sentence-end
-@result{}
-"[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
+ @result{} "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
]*"
@end group
@end example
@table @code
@item [.?!]
-The first part of the pattern is a character set that matches any one of
-three characters: period, question mark, and exclamation mark. The
-match must begin with one of these three characters.
+The first part of the pattern is a character alternative that matches
+any one of three characters: period, question mark, and exclamation
+mark. The match must begin with one of these three characters.
@item []\"')@}]*
The second part of the pattern matches any closing braces and quotation
marks, zero or more of them, that may follow the period, question mark
or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
a string. The @samp{*} at the end indicates that the immediately
-preceding regular expression (a character set, in this case) may be
+preceding regular expression (a character alternative, in this case) may be
repeated zero or more times.
@item \\($\\|@ $\\|\t\\|@ @ \\)
The third part of the pattern matches the whitespace that follows the
-end of a sentence: the end of a line, or a tab, or two spaces. The
-double backslashes mark the parentheses and vertical bars as regular
-expression syntax; the parentheses delimit a group and the vertical bars
-separate alternatives. The dollar sign is used to match the end of a
-line.
+end of a sentence: the end of a line (optionally with a space), or a
+tab, or two spaces. The double backslashes mark the parentheses and
+vertical bars as regular expression syntax; the parentheses delimit a
+group and the vertical bars separate alternatives. The dollar sign is
+used to match the end of a line.
@item [ \t\n]*
Finally, the last part of the pattern matches any additional whitespace
@cindex regexp searching
@cindex searching for regexp
- In GNU Emacs, you can search for the next match for a regexp either
-incrementally or not. For incremental search commands, see @ref{Regexp
-Search, , Regular Expression Search, emacs, The GNU Emacs Manual}. Here
-we describe only the search functions useful in programs. The principal
-one is @code{re-search-forward}.
+ In GNU Emacs, you can search for the next match for a regular
+expression either incrementally or not. For incremental search
+commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
+The GNU Emacs Manual}. Here we describe only the search functions
+useful in programs. The principal one is @code{re-search-forward}.
+
+ These search functions convert the regular expression to multibyte if
+the buffer is multibyte; they convert the regular expression to unibyte
+if the buffer is unibyte. @xref{Text Representations}.
@deffn Command re-search-forward regexp &optional limit noerror repeat
This function searches forward in the current buffer for a string of
buffer), then it is the upper bound to the search. No match extending
after that position is accepted.
-What happens when the search fails depends on the value of
+If @var{repeat} is supplied (it must be a positive number), then the
+search is repeated that many times (each time starting at the end of the
+previous time's match). If all these successive searches succeed, the
+function succeeds, moving point and returning its new value. Otherwise
+the function fails.
+
+What happens when the function 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
@code{re-search-forward} moves point to @var{limit} (or the end of the
buffer) and returns @code{nil}.
-If @var{repeat} is supplied (it must be a positive number), then the
-search is repeated that many times (each time starting at the end of the
-previous time's match). If these successive searches succeed, the
-function succeeds, moving point and returning its new value. Otherwise
-the 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 (between
the @samp{t} of @samp{hat} and the newline).
beginning to end, and starts at a specified beginning position.
A true mirror-image of @code{re-search-forward} would require a special
-feature for matching regexps from end to beginning. It's not worth the
-trouble of implementing that.
+feature for matching regular expressions from end to beginning. It's
+not worth the trouble of implementing that.
@end deffn
@defun string-match regexp string &optional start
@end example
@end defun
+@node POSIX Regexps
+@section POSIX Regular Expression Searching
+
+ The usual regular expression functions do backtracking when necessary
+to handle the @samp{\|} and repetition constructs, but they continue
+this only until they find @emph{some} match. Then they succeed and
+report the first match found.
+
+ This section describes alternative search functions which perform the
+full backtracking specified by the POSIX standard for regular expression
+matching. They continue backtracking until they have tried all
+possibilities and found all matches, so they can report the longest
+match, as required by POSIX. This is much slower, so use these
+functions only when you really need the longest match.
+
+@defun posix-search-forward regexp &optional limit noerror repeat
+This is like @code{re-search-forward} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
+@defun posix-search-backward regexp &optional limit noerror repeat
+This is like @code{re-search-backward} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
+@defun posix-looking-at regexp
+This is like @code{looking-at} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
+@defun posix-string-match regexp string &optional start
+This is like @code{string-match} except that it performs the full
+backtracking specified by the POSIX standard for regular expression
+matching.
+@end defun
+
@ignore
@deffn Command delete-matching-lines regexp
This function is identical to @code{delete-non-matching-lines}, save
with. If it is a string, that string is used. It can also be a list of
strings, to be used in cyclic order.
-If @var{repeat-count} is non-@code{nil}, it should be an integer, the
-number of occurrences to consider. In this case, @code{perform-replace}
-returns after considering that many occurrences.
+If @var{repeat-count} is non-@code{nil}, it should be an integer. Then
+it 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 user
responses for queries. The argument @var{map}, if non-@code{nil}, is a
to the functions that use this map.
@item
-Prefix keys are not supported; each key binding must be for a single event
-key sequence. This is because the functions don't use read key sequence to
-get the input; instead, they read a single event and look it up ``by hand.''
+Prefix keys are not supported; each key binding must be for a
+single-event key sequence. This is because the functions don't use
+@code{read-key-sequence} to get the input; instead, they read a single
+event and look it up ``by hand.''
@end itemize
@end defvar
match data around it, to prevent it from being overwritten.
@menu
+* Replacing Match:: Replacing a substring that was matched.
* 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 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 subexp
+This function replaces the text in the buffer (or in @var{string}) that
+was 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 by
+editing 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 and
+returning a new string.
+
+If @var{fixedcase} is non-@code{nil}, then the case of the replacement
+text is not changed; otherwise, the replacement text is converted to a
+different case depending upon the capitalization of the text to be
+replaced. If the original text is all upper case, the replacement text
+is converted to upper case. If the first word of the original text is
+capitalized, then the first word of the replacement text is capitalized.
+If the original text contains just one word, and that word is a capital
+letter, @code{replace-match} considers this a capitalized first word
+rather 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 inserted
+exactly as it is, the only alterations being case changes as needed.
+If it is @code{nil} (the default), then the character @samp{\} is treated
+specially. If a @samp{\} appears in @var{replacement}, then it must be
+part 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 that
+matched 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 table
+
+If @var{subexp} is non-@code{nil}, that says to replace just
+subexpression number @var{subexp} of the regexp that was matched, not
+the entire match. For example, after matching @samp{foo \(ba*r\)},
+calling @code{replace-match} with 1 as @var{subexp} means to replace
+just the text that matched @samp{\(ba*r\)}.
+@end defun
+
@node Simple Match Data
@subsection Simple Match Data Access
- This section explains how to use the match data to find the starting
-point or ending point of the text that was matched by a particular
-search, or by a particular parenthetical subexpression of a regular
-expression.
+ This section explains how to use the match data to find out what was
+matched by the last search or match operation.
+
+ You can ask about the entire matching text, or about a particular
+parenthetical subexpression of a regular expression. The @var{count}
+argument in the functions below specifies which. If @var{count} is
+zero, you are asking about the entire match. If @var{count} is
+positive, it specifies which subexpression you want.
+
+ Recall that the subexpressions of a regular expression are those
+expressions 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 first
+subexpression is numbered 1, the second 2, and so on. Only regular
+expressions can have subexpressions---after a simple string search, the
+only information available is about the entire match.
+
+ A search which fails may or may not alter the match data. In the
+past, a failing search did not do this, but we may change it in the
+future.
+
+@defun match-string count &optional in-string
+This function returns, as a string, the text matched in the last search
+or match operation. It returns the entire text if @var{count} is zero,
+or just the portion corresponding to the @var{count}th parenthetical
+subexpression, if @var{count} is positive. If @var{count} is out of
+range, 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 the
+argument @var{in-string}. After a buffer search or match,
+you should omit @var{in-string} or pass @code{nil} for it; but you
+should make sure that the current buffer when you call
+@code{match-string} is the one in which you did the searching or
+matching.
+@end defun
+
+@defun match-string-no-properties count
+This function is like @code{match-string} except that the result
+has no text properties.
+@end defun
@defun match-beginning count
This function returns the position of the start of text matched by the
last regular expression searched for, or a subexpression of it.
If @var{count} is zero, then the value is the position of the start of
-the text matched by the whole regexp. Otherwise, @var{count}, specifies
-a subexpression in the regular expresion. The value of the function is
-the starting position of the match for that subexpression.
-
-Subexpressions of a regular expression are those expressions 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 first subexpression is
-numbered 1, the second 2, and so on.
-
-The value is @code{nil} for a subexpression inside a
-@samp{\|} alternative that wasn't used in the match.
+the entire match. Otherwise, @var{count} specifies a subexpression in
+the regular expression, and the value of the function is the starting
+position 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 count
-This function returns the position of the end of the text that matched
-the last regular expression searched for, or a subexpression of it.
-This function is otherwise similar to @code{match-beginning}.
+This function is like @code{match-beginning} except that it returns the
+position of the end of the match, rather than the position of the
+beginning.
@end defun
Here is an example of using the match data, with a comment showing the
@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.}
(In this case, the index returned is a buffer position; the first
character 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
-This function replaces the buffer text matched by the last search, with
-@var{replacement}. It applies only to buffers; you can't use
-@code{replace-match} to replace a substring found with
-@code{string-match}.
-
-If @var{fixedcase} is non-@code{nil}, then the case of the replacement
-text is not changed; otherwise, the replacement text is converted to a
-different case depending upon the capitalization of the text to be
-replaced. If the original text is all upper case, the replacement text
-is converted to upper case. If the first word of the original text is
-capitalized, then the first word of the replacement text is capitalized.
-If the original text contains just one word, and that word is a capital
-letter, @code{replace-match} considers this a capitalized first word
-rather 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 inserted
-exactly as it is, the only alterations being case changes as needed.
-If it is @code{nil} (the default), then the character @samp{\} is treated
-specially. If a @samp{\} appears in @var{replacement}, then it must be
-part 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 that
-matched 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 table
-
-@code{replace-match} leaves point at the end of the replacement text,
-and returns @code{t}.
-@end defun
-
@node Entire Match Data
@subsection Accessing the Entire Match Data
All the elements are markers or @code{nil} if matching was done on a
buffer, and all are integers or @code{nil} if matching was done on a
-string with @code{string-match}. (In Emacs 18 and earlier versions,
-markers were used even for matching on a string, except in the case
-of the integer 0.)
+string with @code{string-match}.
As always, there must be no possibility of intervening searches between
the call to a search function and the call to @code{match-data} that is
an 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}.
+@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
@end defun
@node Saving Match Data
You can save and restore the match data with @code{save-match-data}:
-@defspec save-match-data body@dots{}
+@defmac save-match-data body@dots{}
This special form executes @var{body}, saving and restoring the match
data around it.
-@end defspec
+@end defmac
- You can use @code{set-match-data} together with @code{match-data} to
-imitate the effect of the special form @code{save-match-data}. This is
-useful for writing code that can run in Emacs 18. Here is how:
+ You could use @code{set-match-data} together with @code{match-data} to
+imitate the effect of the special form @code{save-match-data}. Here is
+how:
@example
@group
(let ((data (match-data)))
(unwind-protect
- @dots{} ; @r{May change the original match data.}
+ @dots{} ; @r{Ok to change the original match data.}
(set-match-data data)))
@end group
@end example
By default, searches in Emacs ignore the case of the text they are
searching through; if you specify searching for @samp{FOO}, then
-@samp{Foo} or @samp{foo} is also considered a match. Regexps, and in
-particular character sets, are included: thus, @samp{[aB]} would match
-@samp{a} or @samp{A} or @samp{b} or @samp{B}.
+@samp{Foo} or @samp{foo} is also considered a match. This applies to
+regular expressions, too; 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 match
distinctions differently. When given a lower case letter, it looks for
a match of either case, but when given an upper case letter, it looks
for an upper case letter only. But this has nothing to do with the
-searching functions Lisp functions use.
+searching functions used in Lisp code.
@defopt case-replace
This variable determines whether the replacement functions should
used for certain purposes in editing:
@defvar page-delimiter
-This is the regexp describing line-beginnings that separate pages. The
-default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
-this matches a line that starts with a formfeed character.
+This is the regular expression describing line-beginnings that separate
+pages. The default 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 the
+match always starts at the beginning of a line; they should not use
+@samp{^} to anchor the match. Most often, the paragraph commands do
+check 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 modes
+where a left margin is never used.
+
@defvar paragraph-separate
This is the regular expression for recognizing the beginning of a line
that separates paragraphs. (If you change this, you may have to
change @code{paragraph-start} also.) The default value is
-@w{@code{"^[@ \t\f]*$"}}, which matches a line that consists entirely of
-spaces, tabs, and form feeds.
+@w{@code{"[@ \t\f]*$"}}, which matches a line that consists entirely of
+spaces, tabs, and form feeds (after its left margin).
@end defvar
@defvar paragraph-start
This is the regular expression for recognizing the beginning of a line
that 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.
+@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-end
HCoop / bpt / emacs.git / blobdiff