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.
query-replace.
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.
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 programs
may depend on a value of nil.)
If repeat is non-nil, then the search is repeated that
many times. Point is positioned at the end of the last match.
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 which 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 which 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; better to 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: characters which, when preceded by `\', are special constructs. Such characters are always ordinary when encountered on their own. Here is a table of `\' constructs:
These 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 which is the value of string, surrounded by
whitespace:
(re-search-forward (concat "\\s " (regexp-quote string) "\\s "))
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 set, 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 regexp 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.
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.
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,
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.
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.
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. 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 is
done at a specified beginning position.
A true mirror-image of re-search-forward would require a special
feature for matching regexps 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
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, the
number of occurrences to consider. In this case, perform-replace
returns after considering that many occurrences.
Normally, the keymap query-replace-map defines the possible user
responses. 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:
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 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.
The argument count, a number, specifies a subexpression whose start position is the value. If count is zero, then the value is the position of the text matched by the whole regexp. If count is greater than zero, then the value is the position of the beginning of the text matched by the countth subexpression.
Subexpressions of a regular expression are those expressions grouped inside of 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.
The value is nil for a parenthetical grouping inside of a
`\|' alternative that wasn't used in the match.
match-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-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))
=> (t 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.)
This function replaces the text matched by the last search with replacement.
replace-match to replace a substring found with
string-match.
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 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:
replace-match leaves point at the end of the replacement text,
and returns t.
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. (In Emacs 18 and earlier versions,
markers were used even for matching on a string, except in the case
of the integer 0.)
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.
All asynchronous process functions (filters and sentinels) and
functions that use 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:
(re-search-forward "The \\(cat \\)")
=> 48
(foo) ; Perhaps foo does
; more searching.
(match-end 0)
=> 61 ; Unexpected result--not 48!
In Emacs versions 19 and later, you can save and restore the match
data with save-match-data:
You can use set-match-data together with match-data to
imitate the effect of the special form save-match-data. This is
useful for writing code that can run in Emacs 18. Here is how:
(let ((data (match-data)))
(unwind-protect
... ; May change the original match data.
(set-match-data data)))
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. Regexps, and in particular character sets, are included: 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 per-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 Lisp functions use.
query-replace should preserve
case in replacements. If the variable is nil, then
replace-match should not try to convert case.
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").
paragraph-start also.) The default value is "^[
\t\f]*$", which is a line that consists entirely of spaces, tabs, and
form feeds.
"^[ \t\n\f]", which matches a line starting with a space, tab,
newline, or form feed.
"[.?!][]\"')}]*\\($\\|\t\\| \\)[ \t\n]*"
This means a period, question mark or exclamation mark, followed by a closing brace, followed by tabs, spaces or new lines.
For a detailed explanation of this regular expression, see section Complex Regexp Example.