GNU Emacs provides two ways to search through a buffer for specified text: exact string searches and regular expression searches. After a regular expression search, you can examine the match data to determine which text matched the whole regular expression or various portions of it.
The `skip-chars...' functions also perform a kind of searching. See section Skipping Characters.
These are the primitive functions for searching through the text
in a buffer. They are meant for use in programs, but you may call
them interactively. If you do so, they prompt for the search
string; limit and noerror are set to
nil
, and 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. See section Text Representations.
In the following example, point is initially at the beginning of
the line. Then (search-forward "fox")
moves point
after the last letter of `fox':
---------- Buffer: foo ---------- -!-The quick brown fox jumped over the lazy dog. ---------- Buffer: foo ---------- (search-forward "fox") => 20 ---------- Buffer: foo ---------- The quick brown fox-!- jumped over the lazy dog. ---------- Buffer: foo ----------
The argument 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 limit is
omitted or nil
, it defaults to the end of the
accessible portion of the buffer.
What happens when the search
fails depends on the value of noerror. If
noerror is nil
, a
search-failed
error is signaled. If noerror
is t
, search-forward
returns
nil
and does nothing. If noerror is neither
nil
nor t
, then
search-forward
moves point to the upper bound and
returns 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 nil
.)
If 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.
search-forward
except that it searches backwards and
leaves point at the beginning of the match.
Word matching regards string as a sequence of words, disregarding punctuation that separates them. It searches the buffer for the same sequence of words. Each word must be distinct in the buffer (searching for the word `ball' does not match the word `balls'), but the details of punctuation and spacing are ignored (searching for `ball boy' does match `ball. Boy!').
In this example, point is initially at the beginning of the buffer; the search leaves it between the `y' and the `!'.
---------- Buffer: foo ---------- -!-He said "Please! Find the ball boy!" ---------- Buffer: foo ---------- (word-search-forward "Please find the ball, boy.") => 35 ---------- Buffer: foo ---------- He said "Please! Find the ball boy-!-!" ---------- Buffer: foo ----------
If limit is non-nil
(it must be a
position in the current buffer), then it is the upper bound to the
search. The match found must not extend after that position.
If noerror is nil
, then
word-search-forward
signals an error if the search
fails. If noerror is t
, then it returns
nil
instead of signaling an error. If
noerror is neither nil
nor t
,
it moves point to limit (or the end of the buffer) and
returns nil
.
If repeat is non-nil
, then the search is
repeated that many times. Point is positioned at the end of the
last match.
word-search-forward
except that
it searches backward and normally leaves point at the beginning of
the match.
A regular expression (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.
Regular expressions have a syntax in which a few characters are special constructs and the rest are ordinary. An ordinary character is a simple regular expression that matches that character and nothing else. The special characters are `.', `*', `+', `?', `[', `]', `^', `$', and `\'; no new special characters will be defined in the future. Any other character appearing in a regular expression is ordinary, unless a `\' precedes it.
For example, `f' is not a special character, so it is ordinary, and therefore `f' is a regular expression that matches the string `f' and no other string. (It does not match the string `ff'.) Likewise, `o' is a regular expression that matches only `o'.
Any two regular expressions a and b can be concatenated. The result is a regular expression that matches a string if a matches some amount of the beginning of that string and b matches the rest of the string.
As a simple example, we can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. Still trivial. To do something more powerful, you need to use one of the special characters. Here is a list of them:
grep
.
"\\\\"
.
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, `*foo' treats `*' as ordinary since there is no preceding expression on which the `*' can act. It is poor practice to depend on this behavior; quote the special character anyway, regardless of where it appears.
For the most part, `\' followed by any character matches only that character. However, there are several exceptions: two-character sequences starting with `\' which have special meanings. (The second character in such a sequence is always ordinary when used on its own.) Here is a table of `\' constructs.
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.
Not every string is a valid
regular expression. For example, a string with unbalanced square
brackets is invalid (with a few exceptions, such as
`[]]'), and so is a string that ends with a single
`\'. If an invalid regular expression is passed to any
of the search functions, an invalid-regexp
error is
signaled.
(regexp-quote "^The cat$") => "\\^The cat\\$"
One use of 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
string, surrounded by whitespace:
(re-search-forward (concat "\\s-" (regexp-quote string) "\\s-"))
If the optional argument paren is
non-nil
, then the returned regular expression is
always enclosed by at least one parentheses-grouping construct.
This simplified definition of regexp-opt
produces a
regular expression which is equivalent to the actual value (but not
as efficient):
(defun regexp-opt (strings paren) (let ((open-paren (if paren "\\(" "")) (close-paren (if paren "\\)" ""))) (concat open-paren (mapconcat 'regexp-quote strings "\\|") close-paren)))
Here is a complicated regexp, used by Emacs to recognize the end
of a sentence together with any whitespace that follows. It is the
value of the variable sentence-end
.
First, we show the regexp as a string in Lisp syntax to distinguish spaces from tab characters. The string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the string, `\\' for a backslash as part of the string, `\t' for a tab and `\n' for a newline.
"[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
In contrast, if you evaluate the variable
sentence-end
, you will see the following:
sentence-end => "[.?!][]\"')}]*\\($\\| $\\| \\| \\)[ ]*"
In this output, tab and newline appear as themselves.
This regular expression contains four parts in succession and can be deciphered as follows:
[.?!]
[]\"')}]*
\"
is Lisp
syntax for a double-quote in a string. The `*' at the
end indicates that the immediately preceding regular expression (a
character alternative, in this case) may be repeated zero or more
times.
\\($\\| $\\|\t\\| \\)
[ \t\n]*
In GNU Emacs, you can search for the next match for a regular
expression either incrementally or not. For incremental search
commands, see section `Regular Expression Search' in The GNU
Emacs Manual. Here we describe only the search functions
useful in programs. The principal one is
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. See section Text Representations.
If limit is non-nil
(it must be a
position in the current buffer), then it is the upper bound to the
search. No match extending after that position is accepted.
If 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
noerror. If noerror is nil
, a
search-failed
error is signaled. If noerror
is t
, re-search-forward
does nothing and
returns nil
. If noerror is neither
nil
nor t
, then
re-search-forward
moves point to limit (or
the end of the buffer) and returns nil
.
In the following example, point is initially before the `T'. Evaluating the search call moves point to the end of that line (between the `t' of `hat' and the newline).
---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (re-search-forward "[a-z]+" nil t 5) => 27 ---------- Buffer: foo ---------- I read "The cat in the hat-!- comes back" twice. ---------- Buffer: foo ----------
This function is analogous to re-search-forward
,
but they are not simple mirror images.
re-search-forward
finds the match whose beginning is
as close as possible to the starting point. If
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 re-search-forward
would
require a special feature for matching regular expressions from end
to beginning. It's not worth the trouble of implementing that.
nil
if
there is no match. If start is non-nil
, the
search starts at that index in string. For example,
(string-match "quick" "The quick brown fox jumped quickly.") => 4 (string-match "quick" "The quick brown fox jumped quickly." 8) => 27
The index of the first character of the string is 0, the index of the second character is 1, and so on.
After this function returns, the index of the first character
beyond the match is available as (match-end 0)
. See
section The Match Data.
(string-match "quick" "The quick brown fox jumped quickly." 8) => 27 (match-end 0) => 32
t
if so, nil
otherwise.
This function does not move point, but it updates the match
data, which you can access using match-beginning
and
match-end
. See section The
Match Data.
In this example, point is located directly before the
`T'. If it were anywhere else, the result would be
nil
.
---------- Buffer: foo ---------- I read "-!-The cat in the hat comes back" twice. ---------- Buffer: foo ---------- (looking-at "The cat in the hat$") => t
The usual regular expression functions do backtracking when necessary to handle the `\|' and repetition constructs, but they continue this only until they find 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.
re-search-forward
except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
re-search-backward
except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
looking-at
except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
string-match
except that it performs the full
backtracking specified by the POSIX standard for regular expression
matching.
query-replace
and related commands. It searches for
occurrences of from-string and replaces some or all of
them. If query-flag is nil
, it replaces all
occurrences; otherwise, it asks the user what to do about each one.
If regexp-flag is non-nil
, then
from-string is considered a regular expression;
otherwise, it must match literally. If delimited-flag is
non-nil
, then only replacements surrounded by word
boundaries are considered.
The argument replacements specifies what to replace occurrences 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 repeat-count is non-nil
, it should be
an integer. Then it specifies how many times to use each of the
strings in the replacements list before advancing
cyclicly to the next one.
Normally, the keymap query-replace-map
defines the
possible user responses for queries. The argument map,
if non-nil
, is a keymap to use instead of
query-replace-map
.
query-replace
and related functions, as well as
y-or-n-p
and map-y-or-n-p
. It is unusual
in two ways: read-key-sequence
to get the input; instead, they read
a single event and look it up "by hand."
Here are the meaningful "bindings" for
query-replace-map
. Several of them are meaningful only
for query-replace
and friends.
act
skip
exit
act-and-exit
act-and-show
automatic
backup
edit
delete-and-edit
recenter
quit
y-or-n-p
and
related functions use this answer.
help
Emacs keeps track of the positions of the start and end of segments of text found during a regular expression search. This means, for example, that you can search for a complex pattern, such as a date in an Rmail message, and then extract parts of the match under control of the pattern.
Because the match data normally describe the most recent search only, you must be careful not to do another search inadvertently between the search you wish to refer back to and the use of the match data. If you can't avoid another intervening search, you must save and restore the match data around it, to prevent it from being overwritten.
This function replaces the text matched by the last search with replacement.
If you did the last search in a buffer, you should specify
nil
for string. Then
replace-match
does the replacement by editing the
buffer; it leaves point at the end of the replacement text, and
returns t
.
If you did the search in a string, pass the same string as
string. Then replace-match
does the
replacement by constructing and returning a new string.
If fixedcase is non-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,
replace-match
considers this a capitalized first word
rather than all upper case.
If case-replace
is nil
, then case
conversion is not done, regardless of the value of
fixed-case. See section Searching and Case.
If literal is non-nil
, then
replacement is inserted exactly as it is, the only
alterations being case changes as needed. If it is nil
(the default), then the character `\' is treated
specially. If a `\' appears in replacement,
then it must be part of one of the following sequences:
If subexp is non-nil
, that says to
replace just subexpression number subexp of the regexp
that was matched, not the entire match. For example, after matching
`foo \(ba*r\)', calling replace-match
with 1 as subexp means to replace just the text that
matched `\(ba*r\)'.
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 count argument in the functions below specifies which. If count is zero, you are asking about the entire match. If count is positive, it specifies which subexpression you want.
Recall that the subexpressions of a regular expression are those expressions grouped with escaped parentheses, `\(...\)'. The countth subexpression is found by counting occurrences of `\(' 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.
nil
. If the last such operation was done against a string with
string-match
, then you should pass the same string as
the argument in-string. After a buffer search or match,
you should omit in-string or pass nil
for
it; but you should make sure that the current buffer when you call
match-string
is the one in which you did the searching
or matching.
match-string
except that the result has no text
properties.
If count is zero, then the value is the position of the start of the entire match. Otherwise, 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 nil
for a subexpression inside a
`\|' alternative that wasn't used in the match.
match-beginning
except that it returns the position of
the end of the match, rather than the position of the
beginning.
Here is an example of using the match data, with a comment showing the positions within the text:
(string-match "\\(qu\\)\\(ick\\)" "The quick fox jumped quickly.") ;0123456789 => 4 (match-string 0 "The quick fox jumped quickly.") => "quick" (match-string 1 "The quick fox jumped quickly.") => "qu" (match-string 2 "The quick fox jumped quickly.") => "ick" (match-beginning 1) ; The beginning of the match => 4 ; with `qu' is at index 4. (match-beginning 2) ; The beginning of the match => 6 ; with `ick' is at index 6. (match-end 1) ; The end of the match => 6 ; with `qu' is at index 6. (match-end 2) ; The end of the match => 9 ; with `ick' is at index 9.
Here is another example. Point is initially located at the beginning of the line. Searching moves point to between the space and the word `in'. The beginning of the entire match is at the 9th character of the buffer (`T'), and the beginning of the match for the first subexpression is at the 13th character (`c').
(list (re-search-forward "The \\(cat \\)") (match-beginning 0) (match-beginning 1)) => (9 9 13) ---------- Buffer: foo ---------- I read "The cat -!-in the hat comes back" twice. ^ ^ 9 13 ---------- Buffer: foo ----------
(In this case, the index returned is a buffer position; the first character of the buffer counts as 1.)
The functions match-data
and
set-match-data
read or write the entire match data,
all at once.
(match-beginning n)
; and
element corresponds to (match-end n)
.
All the elements are markers or nil
if matching was
done on a buffer, and all are integers or nil
if
matching was done on a string with string-match
.
As always, there must be no possibility of intervening searches
between the call to a search function and the call to
match-data
that is intended to access the match data
for that search.
(match-data) => (#<marker at 9 in foo> #<marker at 17 in foo> #<marker at 13 in foo> #<marker at 17 in foo>)
match-data
. If match-list refers to a buffer that doesn't exist, you don't get an error; that sets the match data in a meaningless but harmless way.
store-match-data
is a semi-obsolete alias for
set-match-data
.
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:
(re-search-forward "The \\(cat \\)")
=> 48
(foo) ; Perhaps foo
does
; more searching.
(match-end 0)
=> 61 ; Unexpected result---not 48!
You can save and restore the match data with
save-match-data
:
You could use set-match-data
together with
match-data
to imitate the effect of the special form
save-match-data
. Here is how:
(let ((data (match-data))) (unwind-protect ... ; Ok to change the original match data. (set-match-data data)))
Emacs automatically saves and restores the match data when it runs process filter functions (see section Process Filter Functions) and process sentinels (see section Sentinels: Detecting Process Status Changes).
By default, searches in Emacs ignore the case of the text they are searching through; if you specify searching for `FOO', then `Foo' or `foo' is also considered a match. This applies to regular expressions, too; thus, `[aB]' would match `a' or `A' or `b' or `B'.
If you do not want this feature, set the variable
case-fold-search
to nil
. Then all letters
must match exactly, including case. This is a buffer-local
variable; altering the variable affects only the current buffer.
(See section Introduction to
Buffer-Local Variables.) Alternatively, you may change the
value of default-case-fold-search
, which is the
default value of case-fold-search
for buffers that do
not override it.
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.
nil
, that means to use the replacement
text verbatim. A non-nil
value means to convert the
case of the replacement text according to the text being replaced.
The function replace-match
is where this variable
actually has its effect. See section Replacing the Text That Matched.
nil
they do not ignore case; otherwise they do ignore
case.
case-fold-search
in buffers
that do not override it. This is the same as (default-value
'case-fold-search)
.
This section describes some variables that hold regular expressions used for certain purposes in editing:
"^\014"
(i.e., "^^L"
or
"^\C-l"
); this matches a line that starts with a
formfeed character.
The following two regular expressions should not assume the match always starts at the beginning of a line; they should not use `^' to anchor the match. Most often, the paragraph commands do check for a match only at the beginning of a line, which means that `^' would be superfluous. When there is a nonzero left margin, they accept matches that start after the left margin. In that case, a `^' would be incorrect. However, a `^' is harmless in modes where a left margin is never used.
paragraph-start
also.) The default value is "[
\t\f]*$"
, which matches a line that consists entirely of
spaces, tabs, and form feeds (after its left margin).
"[
\t\n\f]"
, which matches a line starting with a space, tab,
newline, or form feed (after its left margin).
"[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
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 section Complex Regexp Example.