to return the new position of point in that case, but some programs
may depend on a value of @code{nil}.)
- If @var{repeat} is non-@code{nil}, then the search is repeated that
-many times. Point is positioned at the end of the last match.
+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.
@end deffn
@deffn Command search-backward string &optional limit noerror repeat
@node Syntax of Regexps
@subsection Syntax of Regular Expressions
- Regular expressions have a syntax in which a few characters are special
-constructs and the rest are @dfn{ordinary}. An ordinary character is a
-simple regular expression which matches that character and nothing else.
-The special characters are @samp{$}, @samp{^}, @samp{.}, @samp{*},
-@samp{+}, @samp{?}, @samp{[}, @samp{]} and @samp{\}; no new special
-characters will be defined in the future. Any other character appearing
-in a regular expression is ordinary, unless a @samp{\} precedes it.
+ Regular expressions have a syntax in which a few characters are
+special constructs and the rest are @dfn{ordinary}. An ordinary
+character is a simple regular expression that matches that character and
+nothing else. The special characters are @samp{.}, @samp{*}, @samp{+},
+@samp{?}, @samp{[}, @samp{]}, @samp{^}, @samp{$}, and @samp{\}; no new
+special characters will be defined in the future. Any other character
+appearing in a regular expression is ordinary, unless a @samp{\}
+precedes it.
For example, @samp{f} is not a special character, so it is ordinary, and
therefore @samp{f} is a regular expression that matches the string
only @samp{o}.@refill
Any two regular expressions @var{a} and @var{b} can be concatenated. The
-result is a regular expression which matches a string if @var{a} matches
+result is a regular expression that matches a string if @var{a} matches
some amount of the beginning of that string and @var{b} matches the rest of
the string.@refill
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
+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
+@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{-}.) 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
@item ^
@cindex @samp{^} in regexp
@cindex beginning of line in regexp
-is a special character that matches the empty string, but only at
-the beginning of a line in the text being matched. Otherwise it fails
-to match anything. Thus, @samp{^foo} matches a @samp{foo} which occurs
-at the beginning of a line.
+is a special character that matches the empty string, but only at the
+beginning of a line in the text being matched. Otherwise it fails to
+match anything. Thus, @samp{^foo} matches a @samp{foo} that occurs at
+the beginning of a line.
-When matching a string, @samp{^} matches at the beginning of the string
-or after a newline character @samp{\n}.
+When matching a string instead of a buffer, @samp{^} matches at the
+beginning of the string or after a newline character @samp{\n}.
@item $
@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, @samp{$} matches at the end of the string
-or before a newline character @samp{\n}.
+When matching a string instead of a buffer, @samp{$} matches at the end
+of the string or before a newline character @samp{\n}.
@item \
@cindex @samp{\} in regexp
@samp{\}), and it introduces additional special constructs.
Because @samp{\} quotes special characters, @samp{\$} is a regular
-expression which matches only @samp{$}, and @samp{\[} is a regular
-expression which matches only @samp{[}, and so on.
+expression that matches only @samp{$}, and @samp{\[} is a regular
+expression that matches only @samp{[}, and so on.
Note that @samp{\} also has special meaning in the read syntax of Lisp
strings (@pxref{String Type}), and must be quoted with @samp{\}. For
@samp{\} is @code{"\\\\"}.@refill
@end table
-@strong{Please note:} for historical compatibility, special characters
+@strong{Please note:} For historical compatibility, special characters
are treated as ordinary ones if they are in contexts where their special
meanings make no sense. For example, @samp{*foo} treats @samp{*} as
ordinary since there is no preceding expression on which the @samp{*}
-can act. It is poor practice to depend on this behavior; better to
-quote the special character anyway, regardless of where it
-appears.@refill
+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
-which, when preceded by @samp{\}, are special constructs. Such
+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:
@end enumerate
This last application is not a consequence of the idea of a
-parenthetical grouping; it is a separate feature which happens to be
+parenthetical grouping; it is a separate feature that happens to be
assigned as a second meaning to the same @samp{\( @dots{} \)} construct
because there is no conflict in practice between the two meanings.
Here is an explanation of this feature:
@item \@var{digit}
-matches the same text which matched the @var{digit}th occurrence of a
+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
@item \W
@cindex @samp{\W} in regexp
-matches any character that is not a word-constituent.
+matches any character that is not a word constituent.
@item \s@var{code}
@cindex @samp{\s} in regexp
matches any character whose syntax is @var{code}. Here @var{code} is a
-character which represents a syntax code: thus, @samp{w} for word
+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.
matches any character whose syntax is not @var{code}.
@end table
- These regular expression constructs match the empty string---that is,
+ The following regular expression constructs match the empty string---that is,
they don't use up any characters---but whether they match depends on the
context.
@kindex invalid-regexp
Not every string is a valid regular expression. For example, a string
with unbalanced square brackets is invalid (with a few exceptions, such
-as @samp{[]]}, and so is a string that ends with a single @samp{\}. If
+as @samp{[]]}), and so is a string that ends with a single @samp{\}. If
an invalid regular expression is passed to any of the search functions,
an @code{invalid-regexp} error is signaled.
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 which is the value of @code{string}, surrounded by
+for the string that is the value of @code{string}, surrounded by
whitespace:
@example
@group
(re-search-forward
- (concat "\\s " (regexp-quote string) "\\s "))
+ (concat "\\s-" (regexp-quote string) "\\s-"))
@end group
@end example
@end defun
@table @code
@item [.?!]
-The first part of the pattern consists of three characters, a period, a
-question mark and an exclamation mark, within square brackets. The
+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.
@item []\"')@}]*
preceding regular expression (a character set, in this case) may be
repeated zero or more times.
-@item \\($\\|@ \\|\t\\|@ @ \\)
+@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 mark the group and the vertical bars
+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.
text that is matched by the regular expression @var{regexp}, leaving
point at the beginning of the first text found.
-This function is analogous to @code{re-search-forward}, but they are
-not simple mirror images. @code{re-search-forward} finds the match
-whose beginning is as close as possible. If @code{re-search-backward}
-were a perfect mirror image, it would find the match whose end is as
-close as possible. However, in fact it finds the match whose beginning
-is as close as possible. The reason is that matching a regular
-expression at a given spot always works from beginning to end, and is
-done at a specified beginning position.
+This function is analogous to @code{re-search-forward}, but they are not
+simple mirror images. @code{re-search-forward} finds the match whose
+beginning is as close as possible to the starting point. If
+@code{re-search-backward} were a perfect mirror image, it would find the
+match whose end is as close as possible. However, in fact it finds the
+match whose beginning is as close as possible. The reason is that
+matching a regular expression at a given spot always works from
+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
returns after considering that many occurrences.
Normally, the keymap @code{query-replace-map} defines the possible user
-responses. The argument @var{map}, if non-@code{nil}, is a keymap to
-use instead of @code{query-replace-map}.
+responses for queries. The argument @var{map}, if non-@code{nil}, is a
+keymap to use instead of @code{query-replace-map}.
@end defun
@defvar query-replace-map
Do not take action for this question---in other words, ``no.''
@item exit
-Answer this question ``no,'' and don't ask any more.
+Answer this question ``no,'' and give up on the entire series of
+questions, assuming that the answers will be ``no.''
@item act-and-exit
-Answer this question ``yes,'' and don't ask any more.
+Answer this question ``yes,'' and give up on the entire series of
+questions, assuming that subsequent answers will be ``no.''
@item act-and-show
Answer this question ``yes,'' but show the results---don't advance yet
This function returns the position of the start of text matched by the
last regular expression searched for, or a subexpression of it.
-The argument @var{count}, a number, specifies a subexpression whose
-start position is the value. If @var{count} is zero, then the value is
-the position of the text matched by the whole regexp. If @var{count} is
-greater than zero, then the value is the position of the beginning of
-the text matched by the @var{count}th subexpression.
+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
-inside of parentheses, @samp{\(@dots{}\)}. The @var{count}th
+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 parenthetical grouping inside of a
+The value is @code{nil} for a subexpression inside a
@samp{\|} alternative that wasn't used in the match.
@end defun
(re-search-forward "The \\(cat \\)")
(match-beginning 0)
(match-beginning 1))
- @result{} (t 9 13)
+ @result{} (9 9 13)
@end group
@group
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
@item @samp{\@var{n}}
@cindex @samp{\@var{n}} in replacement
-@samp{\@var{n}} stands for the text that matched the @var{n}th
-subexpression in the original regexp. Subexpressions are those
-expressions grouped inside of @samp{\(@dots{}\)}. @var{n} is a digit.
+@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
@node Saving Match Data
@subsection Saving and Restoring the Match Data
- All asynchronous process functions (filters and sentinels) and
-functions that use @code{recursive-edit} should save and restore the
-match data if they do a search or if they let the user type arbitrary
-commands. Saving the match data is useful in other cases as
-well---whenever you want to access the match data resulting from an
-earlier search, notwithstanding another intervening search.
-
- This example shows the problem that can arise if you fail to
-attend to this requirement:
+ When you call a function that may do a search, you may need to save
+and restore the match data around that call, if you want to preserve the
+match data from an earlier search for later use. Here is an example
+that shows the problem that arises if you fail to save the match data:
@example
@group
@end group
@end example
- In Emacs versions 19 and later, you can save and restore the match
-data with @code{save-match-data}:
+ You can save and restore the match data with @code{save-match-data}:
@defspec save-match-data body@dots{}
This special form executes @var{body}, saving and restoring the match
-data around it. This is useful if you wish to do a search without
-altering the match data that resulted from an earlier search.
+data around it.
@end defspec
You can use @code{set-match-data} together with @code{match-data} to
@end group
@end example
+ Emacs automatically saves and restores the match data when it runs
+process filter functions (@pxref{Filter Functions}) and process
+sentinels (@pxref{Sentinels}).
+
@ignore
Here is a function which restores the match data provided the buffer
associated with it still exists.
If you do not want this feature, set the variable
@code{case-fold-search} to @code{nil}. Then all letters must match
-exactly, including case. This is a per-buffer-local variable; altering
-the variable affects only the current buffer. (@xref{Intro to
+exactly, including case. This is a buffer-local variable; altering the
+variable affects only the current buffer. (@xref{Intro to
Buffer-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.
searching functions Lisp functions use.
@defopt case-replace
-This variable determines whether @code{query-replace} should preserve
-case in replacements. If the variable is @code{nil}, then
-@code{replace-match} should not try to convert case.
+This variable determines whether the replacement functions should
+preserve case. If the variable is @code{nil}, that means to use the
+replacement text verbatim. A non-@code{nil} value means to convert the
+case of the replacement text according to the text being replaced.
+
+The function @code{replace-match} is where this variable actually has
+its effect. @xref{Replacing Match}.
@end defopt
@defopt case-fold-search
@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"}).
+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
@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 @code{"^[
-\t\f]*$"}, which is a line that consists entirely of spaces, tabs, and
-form feeds.
+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.
@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
-@code{"^[ \t\n\f]"}, which matches a line starting with a space, tab,
+@w{@code{"^[@ \t\n\f]"}}, which matches a line starting with a space, tab,
newline, or form feed.
@end defvar
is:
@example
-"[.?!][]\"')@}]*\\($\\|\t\\| \\)[ \t\n]*"
+"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
@end example
-This means a period, question mark or exclamation mark, followed by a
-closing brace, followed by tabs, spaces or new lines.
+This means a period, question mark or exclamation mark, followed
+optionally by a closing parenthetical character, followed by tabs,
+spaces or new lines.
For a detailed explanation of this regular expression, see @ref{Regexp
Example}.
HCoop / bpt / emacs.git / blobdiff