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
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
search-failed error is signaled. If noerror
nil and does nothing. If noerror is neither
search-forward moves point to the upper bound and
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
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-forwardexcept 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
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
it moves point to limit (or the end of the buffer) and
If repeat is non-
nil, then the search is
repeated that many times. Point is positioned at the end of the
word-search-forwardexcept 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:
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
(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
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
(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
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\\| \\)
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
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
search-failed error is signaled. If noerror
re-search-forward does nothing and
nil. If noerror is neither
re-search-forward moves point to limit (or
the end of the buffer) and returns
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
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
A true mirror-image of
require a special feature for matching regular expressions from end
to beginning. It's not worth the trouble of implementing that.
nilif there is no match. If start is non-
nil, the search starts at that index in string.
(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
This function does not move point, but it updates the match
data, which you can access using
match-end. See section The
In this example, point is located directly before the
`T'. If it were anywhere else, the result would be
---------- 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-forwardexcept that it performs the full backtracking specified by the POSIX standard for regular expression matching.
re-search-backwardexcept that it performs the full backtracking specified by the POSIX standard for regular expression matching.
looking-atexcept that it performs the full backtracking specified by the POSIX standard for regular expression matching.
string-matchexcept that it performs the full backtracking specified by the POSIX standard for regular expression matching.
query-replaceand 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-
from-string is considered a regular expression;
otherwise, it must match literally. If delimited-flag is
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,
nil, is a keymap to use instead of
query-replaceand related functions, as well as
map-y-or-n-p. It is unusual in two ways:
read-key-sequenceto 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
query-replace and friends.
y-or-n-pand related functions use this answer.
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
If you did the search in a string, pass the same string as
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.
nil, then case
conversion is not done, regardless of the value of
fixed-case. See section Searching and Case.
If literal is non-
replacement is inserted exactly as it is, the only
alterations being case changes as needed. If it is
(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
with 1 as subexp means to replace just the text that
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.
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
it; but you should make sure that the current buffer when you call
match-string is the one in which you did the searching
match-stringexcept 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-beginningexcept 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.)
set-match-data read or write the entire match data,
all at once.
(match-beginning n); and element corresponds to
All the elements are markers or
nil if matching was
done on a buffer, and all are integers or
matching was done on a string with
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>)
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
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
foodoes ; more searching. (match-end 0) => 61 ; Unexpected result---not 48!
You can save and restore the match data with
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
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
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-
nilvalue means to convert the case of the replacement text according to the text being replaced.
replace-match is where this variable
actually has its effect. See section Replacing the Text That Matched.
nilthey do not ignore case; otherwise they do ignore case.
case-fold-searchin buffers that do not override it. This is the same as
This section describes some variables that hold regular expressions used for certain purposes in editing:
"^\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-startalso.) 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.