@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/searching
@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
* POSIX Regexps:: Searching POSIX-style for the longest match.
* Match Data:: Finding out which part of the text matched,
after a string or regexp search.
-* Search and Replace:: Commands that loop, searching and replacing.
+* Search and Replace:: Commands that loop, searching and replacing.
* Standard Regexps:: Useful regexps for finding sentences, pages,...
@end menu
@end deffn
@deffn Command word-search-forward string &optional limit noerror repeat
-@c @cindex word search Redundant
This function searches forward from point for a ``word'' match for
@var{string}. If it finds a match, it sets point to the end of the
match found, and returns the new value of point.
-@c Emacs 19 feature
Word matching regards @var{string} as a sequence of words, disregarding
punctuation that separates them. It searches the buffer for the same
times. Point is positioned at the end of the last match.
@end deffn
+@deffn Command word-search-forward-lax string &optional limit noerror repeat
+This command is identical to @code{word-search-forward}, except that
+the end of @code{string} need not match a word boundary unless it ends
+in whitespace. For instance, searching for @samp{ball boy} matches
+@samp{ball boyee}, but does not match @samp{aball boy}.
+@end deffn
+
@deffn Command word-search-backward string &optional limit noerror repeat
This function searches backward from point for a word match to
@var{string}. This function is just like @code{word-search-forward}
beginning of the match.
@end deffn
+@deffn Command word-search-backward-lax string &optional limit noerror repeat
+This command is identical to @code{word-search-backward}, except that
+the end of @code{string} need not match a word boundary unless it ends
+in whitespace.
+@end deffn
+
@node Searching and Case
@section Searching and Case
@cindex searching and case
@code{case-fold-search} to @code{nil}. Then all letters must match
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.
+Buffer-Local}.) Alternatively, you may change the default value of
+@code{case-fold-search}.
Note that the user-level incremental search feature handles case
-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 used in Lisp code.
+distinctions differently. When the search string contains only lower
+case letters, the search ignores case, but when the search string
+contains one or more upper case letters, the search becomes
+case-sensitive. But this has nothing to do with the searching
+functions used in Lisp code.
+
+@defopt case-fold-search
+This buffer-local variable determines whether searches should ignore
+case. If the variable is @code{nil} they do not ignore case; otherwise
+they do ignore case.
+@end defopt
@defopt case-replace
This variable determines whether the higher level replacement
@code{replace-match}. @xref{Replacing Match}.
@end defopt
-@defopt case-fold-search
-This buffer-local variable determines whether searches should ignore
-case. If the variable is @code{nil} they do not ignore case; otherwise
-they do ignore case.
-@end defopt
-
-@defvar default-case-fold-search
-The value of this variable is the default value for
-@code{case-fold-search} in buffers that do not override it. This is the
-same as @code{(default-value 'case-fold-search)}.
-@end defvar
-
@node Regular Expressions
@section Regular Expressions
@cindex regular expression
@cindex regexp
- A @dfn{regular expression} (@dfn{regexp}, for short) is a pattern that
+ A @dfn{regular expression}, or @dfn{regexp} for short, is a pattern that
denotes a (possibly infinite) set of strings. Searching for matches for
a regexp is a very powerful operation. This section explains how to write
regexps; the following section says how to search for them.
@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
@item @samp{*?}, @samp{+?}, @samp{??}
+@cindex non-greedy repetition characters in regexp
These are ``non-greedy'' variants of the operators @samp{*}, @samp{+}
and @samp{?}. Where those operators match the largest possible
substring (consistent with matching the entire containing expression),
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}
+(including the empty string). 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
To include @samp{^} in a character alternative, put it anywhere but at
the beginning.
-The beginning and end of a range of multibyte characters must be in
-the same character set (@pxref{Character Sets}). Thus,
-@code{"[\x8e0-\x97c]"} is invalid because character 0x8e0 (@samp{a}
-with grave accent) is in the Emacs character set for Latin-1 but the
-character 0x97c (@samp{u} with diaeresis) is in the Emacs character
-set for Latin-2. (We use Lisp string syntax to write that example,
-and a few others in the next few paragraphs, in order to include hex
-escape sequences in them.)
-
If a range starts with a unibyte character @var{c} and ends with a
multibyte character @var{c2}, the range is divided into two parts: one
is @samp{@var{c}..?\377}, the other is @samp{@var{c1}..@var{c2}}, where
@var{c1} is the first character of the charset to which @var{c2}
belongs.
-You cannot always match all non-@acronym{ASCII} characters with the regular
-expression @code{"[\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-@acronym{ASCII} characters have codes
-above octal 0377. However, the regular expression @code{"[^\000-\177]"}
-does match all non-@acronym{ASCII} characters (see below regarding @samp{^}),
-in both multibyte and unibyte representations, because only the
-@acronym{ASCII} characters are excluded.
-
-A character alternative can also specify named
-character classes (@pxref{Char Classes}). This is a POSIX feature whose
-syntax is @samp{[:@var{class}:]}. Using a character class is equivalent
-to mentioning each of the characters in that class; but the latter is
-not feasible in practice, since some classes include thousands of
+A character alternative can also specify named character classes
+(@pxref{Char Classes}). This is a POSIX feature whose syntax is
+@samp{[:@var{class}:]}. Using a character class is equivalent to
+mentioning each of the characters in that class; but the latter is not
+feasible in practice, since some classes include thousands of
different characters.
@item @samp{[^ @dots{} ]}
mentioned as one of the characters not to match. This is in contrast to
the handling of regexps in programs such as @code{grep}.
+You can specify named character classes, just like in character
+alternatives. For instance, @samp{[^[:ascii:]]} matches any
+non-@acronym{ASCII} character. @xref{Char Classes}.
+
@item @samp{^}
@cindex beginning of line in regexp
When matching a buffer, @samp{^} matches the empty string, but only at the
This matches graphic characters---everything except @acronym{ASCII} control
characters, space, and the delete character.
@item [:lower:]
-This matches any lower-case letter, as determined by
-the current case table (@pxref{Case Tables}).
+This matches any lower-case letter, as determined by the current case
+table (@pxref{Case Tables}). If @code{case-fold-search} is
+non-@code{nil}, this also matches any upper-case letter.
@item [:multibyte:]
This matches any multibyte character (@pxref{Text Representations}).
@item [:nonascii:]
@item [:unibyte:]
This matches any unibyte character (@pxref{Text Representations}).
@item [:upper:]
-This matches any upper-case letter, as determined by
-the current case table (@pxref{Case Tables}).
+This matches any upper-case letter, as determined by the current case
+table (@pxref{Case Tables}). If @code{case-fold-search} is
+non-@code{nil}, this also matches any lower-case letter.
@item [:word:]
This matches any character that has word syntax (@pxref{Syntax Class
Table}).
For example, @samp{c[ad]\@{1,2\@}r} matches the strings @samp{car},
@samp{cdr}, @samp{caar}, @samp{cadr}, @samp{cdar}, and @samp{cddr}, and
nothing else.@*
-@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}. @*
-@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}. @*
+@samp{\@{0,1\@}} or @samp{\@{,1\@}} is equivalent to @samp{?}.@*
+@samp{\@{0,\@}} or @samp{\@{,\@}} is equivalent to @samp{*}.@*
@samp{\@{1,\@}} is equivalent to @samp{+}.
@item \( @dots{} \)
shy groups.
@item \(?: @dots{} \)
+@cindex shy groups
+@cindex non-capturing group
+@cindex unnumbered group
+@cindex @samp{(?:} in regexp
is the @dfn{shy group} construct. A shy group serves the first two
purposes of an ordinary group (controlling the nesting of other
operators), but it does not get a number, so you cannot refer back to
-its value with @samp{\@var{digit}}.
+its value with @samp{\@var{digit}}. Shy groups are particularly
+useful for mechanically-constructed regular expressions, because they
+can be added automatically without altering the numbering of ordinary,
+non-shy groups.
-Shy groups are particularly useful for mechanically-constructed regular
-expressions because they can be added automatically without altering the
-numbering of any ordinary, non-shy groups.
+Shy groups are also called @dfn{non-capturing} or @dfn{unnumbered
+groups}.
@item \(?@var{num}: @dots{} \)
is the @dfn{explicitly numbered group} construct. Normal groups get
matched---for instance, if it appears inside of an alternative that
wasn't used, or inside of a repetition that repeated zero times---then
the corresponding @samp{\@var{digit}} construct never matches
-anything. To use an artificial example,, @samp{\(foo\(b*\)\|lose\)\2}
+anything. To use an artificial example, @samp{\(foo\(b*\)\|lose\)\2}
cannot match @samp{lose}: the second alternative inside the larger
group matches it, but then @samp{\2} is undefined and can't match
anything. But it can match @samp{foobb}, because the first
@cindex @samp{\S} in regexp
matches any character whose syntax is not @var{code}.
+@cindex category, regexp search for
@item \c@var{c}
matches any character whose category is @var{c}. Here @var{c} is a
character that represents a category: thus, @samp{c} for Chinese
characters or @samp{g} for Greek characters in the standard category
-table.
+table. You can see the list of all the currently defined categories
+with @kbd{M-x describe-categories @key{RET}}. You can also define
+your own categories in addition to the standard ones using the
+@code{define-category} function (@pxref{Categories}).
@item \C@var{c}
matches any character whose category is not @var{c}.
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. If @var{paren} is @code{words}, then
-that construct is additionally surrounded by @samp{\<} and @samp{\>}.
+that construct is additionally surrounded by @samp{\<} and @samp{\>};
+alternatively, if @var{paren} is @code{symbols}, then that construct
+is additionally surrounded by @samp{\_<} and @samp{\_>}
+(@code{symbols} is often appropriate when matching
+programming-language keywords and the like).
This simplified definition of @code{regexp-opt} produces a
regular expression which is equivalent to the actual value
@defun regexp-opt-depth regexp
This function returns the total number of grouping constructs
-(parenthesized expressions) in @var{regexp}. (This does not include
-shy groups.)
+(parenthesized expressions) in @var{regexp}. This does not include
+shy groups (@pxref{Regexp Backslash}).
@end defun
@node Regexp Search
@end example
@end defun
+@defun string-match-p regexp string &optional start
+This predicate function does what @code{string-match} does, but it
+avoids modifying the match data.
+@end defun
+
@defun looking-at regexp
This function determines whether the text in the current buffer directly
following point matches the regular expression @var{regexp}. ``Directly
This function does not move point, but it updates the match data, which
you can access using @code{match-beginning} and @code{match-end}.
-@xref{Match Data}.
+@xref{Match Data}. If you need to test for a match without modifying
+the match data, use @code{looking-at-p}, described below.
In this example, point is located directly before the @samp{T}. If it
were anywhere else, the result would be @code{nil}.
@end example
@end defun
-@defun looking-back regexp &optional limit
+@defun looking-back regexp &optional limit greedy
This function returns @code{t} if @var{regexp} matches text before
point, ending at point, and @code{nil} otherwise.
not to search before @var{limit}. In this case, the match that is
found must begin at or after @var{limit}.
+If @var{greedy} is non-@code{nil}, this function extends the match
+backwards as far as possible, stopping when a single additional
+previous character cannot be part of a match for regexp. When the
+match is extended, its starting position is allowed to occur before
+@var{limit}.
+
@example
@group
---------- Buffer: foo ----------
@end example
@end defun
+@defun looking-at-p regexp
+This predicate function works like @code{looking-at}, but without
+updating the match data.
+@end defun
+
@defvar search-spaces-regexp
If this variable is non-@code{nil}, it should be a regular expression
that says how to search for whitespace. In that case, any group of
functions only when you really need the longest match.
The POSIX search and match functions do not properly support the
-non-greedy repetition operators. This is because POSIX backtracking
-conflicts with the semantics of non-greedy repetition.
+non-greedy repetition operators (@pxref{Regexp Special, non-greedy}).
+This is because POSIX backtracking conflicts with the semantics of
+non-greedy repetition.
-@defun posix-search-forward regexp &optional limit noerror repeat
+@deffn Command 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
+@end deffn
-@defun posix-search-backward regexp &optional limit noerror repeat
+@deffn Command 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
+@end deffn
@defun posix-looking-at regexp
This is like @code{looking-at} except that it performs the full
can't avoid another intervening search, you must save and restore the
match data around it, to prevent it from being overwritten.
+ Notice that all functions are allowed to overwrite the match data
+unless they're explicitly documented not to do so. A consequence is
+that functions that are run implictly in the background
+(@pxref{Timers}, and @ref{Idle Timers}) should likely save and restore
+the match data explicitly.
+
@menu
-* Replacing Match:: Replacing a substring that was matched.
+* Replacing Match:: Replacing a substring that was matched.
* Simple Match Data:: Accessing single items of match data,
- such as where a particular subexpression started.
+ such as where a particular subexpression started.
* Entire Match Data:: Accessing the entire match data at once, as a list.
* Saving Match Data:: Saving and restoring the match data.
@end menu
(re-search-forward "The \\(cat \\)")
(match-beginning 0)
(match-beginning 1))
- @result{} (9 9 13)
+ @result{} (17 9 13)
@end group
@group
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{replacements} is a cons cell, @code{(@var{function}
-. @var{data})}, this means to call @var{function} after each match to
+If @var{replacements} is a cons cell, @w{@code{(@var{function}
+. @var{data})}}, this means to call @var{function} after each match to
get the replacement text. This function is called with two arguments:
@var{data}, and the number of replacements already made.
user responses for queries. The argument @var{map}, if
non-@code{nil}, specifies a keymap to use instead of
@code{query-replace-map}.
+
+This function uses one of two functions to search for the next
+occurrence of @var{from-string}. These functions are specified by the
+values of two variables: @code{replace-re-search-function} and
+@code{replace-search-function}. The former is called when the
+argument @var{regexp-flag} is non-@code{nil}, the latter when it is
+@code{nil}.
@end defun
@defvar query-replace-map
Display some help, then ask again.
@end table
+@defvar multi-query-replace-map
+This variable holds a keymap that extends @code{query-replace-map} by
+providing additional keybindings that are useful in multi-buffer
+replacements.
+@end defvar
+
+@defvar replace-search-function
+This variable specifies a function that @code{perform-replace} calls
+to search for the next string to replace. Its default value is
+@code{search-forward}. Any other value should name a function of 3
+arguments: the first 3 arguments of @code{search-forward}
+(@pxref{String Search}).
+@end defvar
+
+@defvar replace-re-search-function
+This variable specifies a function that @code{perform-replace} calls
+to search for the next regexp to replace. Its default value is
+@code{re-search-forward}. Any other value should name a function of 3
+arguments: the first 3 arguments of @code{re-search-forward}
+(@pxref{Regexp Search}).
+@end defvar
+
@node Standard Regexps
@section Standard Regular Expressions Used in Editing
@cindex regexps used standardly in editing
This section describes some variables that hold regular expressions
used for certain purposes in editing:
-@defvar page-delimiter
+@defopt page-delimiter
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
+@end defopt
The following two regular expressions should @emph{not} assume the
match always starts at the beginning of a line; they should not use
@samp{^} would be incorrect. However, a @samp{^} is harmless in modes
where a left margin is never used.
-@defvar paragraph-separate
+@defopt 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 (after its left margin).
-@end defvar
+@end defopt
-@defvar paragraph-start
+@defopt 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{"\f\\|[ \t]*$"}}, which matches a line containing only
whitespace or starting with a form feed (after its left margin).
-@end defvar
+@end defopt
-@defvar sentence-end
+@defopt sentence-end
If non-@code{nil}, the value should be a regular expression describing
the end of a sentence, including the whitespace following the
sentence. (All paragraph boundaries also end sentences, regardless.)
@code{sentence-end} has to construct the regexp. That is why you
should always call the function @code{sentence-end} to obtain the
regexp to be used to recognize the end of a sentence.
-@end defvar
+@end defopt
@defun sentence-end
This function returns the value of the variable @code{sentence-end},
@code{sentence-end-without-period} and
@code{sentence-end-without-space}.
@end defun
-
-@ignore
- arch-tag: c2573ca2-18aa-4839-93b8-924043ef831f
-@end ignore