Like other editors, Emacs has commands for searching for occurrences of a string. The principal search command is unusual in that it is incremental: it begins to search before you have finished typing the search string. There are also non-incremental search commands more like those of other editors.
Besides the usual replace-string command that finds all
occurrences of one string and replaces them with another, Emacs has a fancy
replacement command called query-replace which asks interactively
which occurrences to replace.
An incremental search begins searching as soon as you type the first character of the search string. As you type in the search string, Emacs shows you where the string (as you have typed it so far) is found. When you have typed enough characters to identify the place you want, you can stop. Depending on what you do next, you may or may not need to terminate the search explicitly with a RET.
isearch-forward).
isearch-backward).
C-s starts an incremental search. C-s reads characters from the keyboard and positions the cursor at the first occurrence of the characters that you have typed. If you type C-s and then F, the cursor moves right after the first `F'. Type an O, and see the cursor move to after the first `FO'. After another O, the cursor is after the first `FOO' after the place where you started the search. Meanwhile, the search string `FOO' has been echoed in the echo area.
The echo area display ends with three dots when actual searching is going on. When search is waiting for more input, the three dots are removed. (On slow terminals, the three dots are not displayed.)
If you make a mistake in typing the search string, you can erase characters with DEL. Each DEL cancels the last character of the search string. This does not happen until Emacs is ready to read another input character; first it must either find, or fail to find, the character you want to erase. If you do not want to wait for this to happen, use C-g as described below.
When you are satisfied with the place you have reached, you can type RET (or C-m), which stops searching, leaving the cursor where the search brought it. Any command not specially meaningful in searches also stops the search and is then executed. Thus, typing C-a exits the search and then moves to the beginning of the line. RET is necessary only if the next command you want to type is a printing character, DEL, ESC, or another control character that is special within searches (C-q, C-w, C-r, C-s, or C-y).
Sometimes you search for `FOO' and find it, but were actually looking for a different occurance of it. To move to the next occurrence of the search string, type another C-s. Do this as often as necessary. If you overshoot, you can cancel some C-s characters with DEL.
After you exit a search, you can search for the same string again by typing just C-s C-s: the first C-s is the key that invokes incremental search, and the second C-s means "search again".
If the specified string is not found at all, the echo area displays the text `Failing I-Search'. The cursor is after the place where Emacs found as much of your string as it could. Thus, if you search for `FOOT', and there is no `FOOT', the cursor may be after the `FOO' in `FOOL'. At this point there are several things you can do. If you mistyped the search string, correct it. If you like the place you have found, you can type RET or some other Emacs command to "accept what the search offered". Or you can type C-g, which removes from the search string the characters that could not be found (the `T' in `FOOT'), leaving those that were found (the `FOO' in `FOOT'). A second C-g at that point cancels the search entirely, returning point to where it was when the search started.
If a search is failing and you ask to repeat it by typing another C-s, it starts again from the beginning of the buffer. Repeating a failing backward search with C-r starts again from the end. This is called wrapping around. `Wrapped' appears in the search prompt once this has happened.
The C-g "quit" character does special things during searches; just what it does depends on the status of the search. If the search has found what you specified and is waiting for input, C-g cancels the entire search. The cursor moves back to where you started the search. If C-g is typed when there are characters in the search string that have not been found--because Emacs is still searching for them, or because it has failed to find them--then the search string characters which have not been found are discarded from the search string. The search is now successful and waiting for more input, so a second C-g cancels the entire search.
To search for a control character such as C-s or DEL or ESC, you must quote it by typing C-q first. This function of C-q is analogous to its meaning as an Emacs command: it causes the following character to be treated the way a graphic character would normally be treated in the same context.
To search backwards, you can use C-r instead of C-s to
start the search; C-r is the key that runs the command
(isearch-backward) to search backward. You can also use
C-r to change from searching forward to searching backwards. Do
this if a search fails because the place you started was too far down in the
file. Repeated C-r keeps looking for more occurrences backwards.
C-s starts going forward again. You can cancel C-r in a
search with DEL.
The characters C-y and C-w can be used in incremental search to grab text from the buffer into the search string. This makes it convenient to search for another occurrence of text at point. C-w copies the word after point as part of the search string, advancing point over that word. Another C-s to repeat the search will then search for a string including that word. C-y is similar to C-w but copies the rest of the current line into the search string.
The characters M-p and M-n can be used in an incremental search to recall things which you have searched for in the past. A list of the last 16 things you have searched for is retained, and M-p and M-n let you cycle through that ring.
The character M-TAB does completion on the elements in
the search history ring. For example, if you know that you have
recently searched for the string POTATOE, you could type
C-s P O M-TAB. If you had searched for other strings
beginning with PO then you would be shown a list of them, and
would need to type more to select one.
You can change any of the special characters in incremental search via
the normal keybinding mechanism: simply add a binding to the
isearch-mode-map. For example, to make the character
C-b mean "search backwards" while in isearch-mode, do this:
(define-key isearch-mode-map "\C-b" 'isearch-repeat-backward)
These are the default bindings of isearch-mode:
isearch-delete-char).
isearch-exit).
isearch-quote-char).
isearch-repeat-forward).
isearch-repeat-backward).
isearch-yank-line).
isearch-yank-word).
isearch-abort).
isearch-ring-retreat).
isearch-ring-advance).
isearch-complete).
Any other character which is normally inserted into a buffer when typed is automatically added to the search string in isearch-mode.
Incremental search on a slow terminal uses a modified style of display that is designed to take less time. Instead of redisplaying the buffer at each place the search gets to, it creates a new single-line window and uses that to display the line the search has found. The single-line window appears as soon as point gets outside of the text that is already on the screen.
When the search is terminated, the single-line window is removed. Only at this time the window in which the search was done is redisplayed to show its new value of point.
The three dots at the end of the search string, normally used to indicate that searching is going on, are not displayed in slow style display.
The slow terminal style of display is used when the terminal baud rate is
less than or equal to the value of the variable search-slow-speed,
initially 1200.
The number of lines to use in slow terminal search display is controlled
by the variable search-slow-window-lines. Its normal value is 1.
Emacs also has conventional non-incremental search commands, which require you type the entire search string before searching begins.
To do a non-incremental search, first type C-s RET (or C-s C-m). This enters the minibuffer to read the search string. Terminate the string with RET to start the search. If the string is not found, the search command gets an error.
By default, C-s invokes incremental search, but if you give it an empty argument, which would otherwise be useless, it invokes non-incremental search. Therefore, C-s RET invokes non-incremental search. C-r RET also works this way.
Forward and backward non-incremental searches are implemented by the
commands search-forward and search-backward. You can bind
these commands to keys. The reason that incremental
search is programmed to invoke them as well is that C-s RET
is the traditional sequence of characters used in Emacs to invoke
non-incremental search.
Non-incremental searches performed using C-s RET do
not call search-forward right away. They first check
if the next character is C-w, which requests a word search.
Word search looks for a sequence of words without regard to how the words are separated. More precisely, you type a string of many words, using single spaces to separate them, and the string is found even if there are multiple spaces, newlines or other punctuation between the words.
Word search is useful in editing documents formatted by text formatters. If you edit while looking at the printed, formatted version, you can't tell where the line breaks are in the source file. Word search, allows you to search without having to know the line breaks.
Word search is a special case of non-incremental search. It is invoked with C-s RET C-w followed by the search string, which must always be terminated with another RET. Being non-incremental, this search does not start until the argument is terminated. It works by constructing a regular expression and searching for that. See section Regular Expression Search.
You can do a backward word search with C-r RET C-w.
Forward and backward word searches are implemented by the commands
word-search-forward and word-search-backward. You can
bind these commands to keys. The reason that incremental
search is programmed to invoke them as well is that C-s RET C-w
is the traditional Emacs sequence of keys for word search.
A regular expression (regexp, for short) is a pattern that denotes a set of strings, possibly an infinite set. Searching for matches for a regexp is a powerful operation that editors on Unix systems have traditionally offered. In XEmacs, you can search for the next match for a regexp either incrementally or not.
Incremental search for a regexp is done by typing M-C-s
(isearch-forward-regexp). This command reads a search string
incrementally just like C-s, but it treats the search string as a
regexp rather than looking for an exact match against the text in the
buffer. Each time you add text to the search string, you make the regexp
longer, and the new regexp is searched for. A reverse regexp search command
isearch-backward-regexp also exists, but no key runs it.
All of the control characters that do special things within an ordinary incremental search have the same functionality in incremental regexp search. Typing C-s or C-r immediately after starting a search retrieves the last incremental search regexp used: incremental regexp and non-regexp searches have independent defaults.
Non-incremental search for a regexp is done by the functions
re-search-forward and re-search-backward. You can invoke
them with M-x or bind them to keys. You can also call
re-search-forward by way of incremental regexp search with
M-C-s RET.
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. 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, you can concatenate the regular expressions `f' and `o' to get the regular expression `fo', which matches only the string `fo'. To do something nontrivial, you need to use one of the following special characters:
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 is appears.
Usually, `\' 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.
Here is a complicated regexp used by Emacs to recognize the end of a sentence together with any whitespace that follows. It is given in Lisp syntax to enable you to distinguish the spaces from the tab characters. In Lisp syntax, the string constant begins and ends with a double-quote. `\"' stands for a double-quote as part of the regexp, `\\' for a backslash as part of the regexp, `\t' for a tab and `\n' for a newline.
"[.?!][]\"')]*\\($\\|\t\\| \\)[ \t\n]*"
This regexp contains four parts: a character set matching period, `?' or `!'; a character set matching close-brackets, quotes or parentheses, repeated any number of times; an alternative in backslash-parentheses that matches end-of-line, a tab or two spaces; and a character set matching whitespace characters, repeated any number of times.
All searches in Emacs normally ignore the case of the text they are searching through; if you specify searching for `FOO', `Foo' and `foo' are also considered a match. Regexps, and in particular character sets, are included: `[aB]' matches `a' or `A' or `b' or `B'.
If you want a case-sensitive search, set the variable
case-fold-search to nil. Then all letters must match
exactly, including case. case-fold-search is a per-buffer
variable; altering it affects only the current buffer, but
there is a default value which you can change as well. See section Local Variables.
You can also use Case Sensitive Search from the Options menu
on your screen.
Global search-and-replace operations are not needed as often in Emacs as
they are in other editors, but they are available. In addition to the
simple replace-string command which is like that found in most
editors, there is a query-replace command which asks you, for each
occurrence of a pattern, whether to replace it.
The replace commands all replace one string (or regexp) with one
replacement string. It is possible to perform several replacements in
parallel using the command expand-region-abbrevs. See section Controlling Abbrev Expansion.
To replace every instance of `foo' after point with `bar', use the command M-x replace-string with the two arguments `foo' and `bar'. Replacement occurs only after point: if you want to cover the whole buffer you must go to the beginning first. By default, all occurrences up to the end of the buffer are replaced. To limit replacement to part of the buffer, narrow to that part of the buffer before doing the replacement (see section Narrowing).
When replace-string exits, point is left at the last occurrence
replaced. The value of point when the replace-string command was
issued is remembered on the mark ring; C-u C-SPC moves back
there.
A numeric argument restricts replacement to matches that are surrounded by word boundaries.
replace-string replaces exact matches for a single string. The
similar command replace-regexp replaces any match for a specified
pattern.
In replace-regexp, the newstring need not be constant. It
can refer to all or part of what is matched by the regexp. `\&'
in newstring stands for the entire text being replaced.
`\d' in newstring, where d is a digit, stands for
whatever matched the d'th parenthesized grouping in regexp.
For example,
M-x replace-regexp RET c[ad]+r RET \&-safe RET
would replace (for example) `cadr' with `cadr-safe' and `cddr' with `cddr-safe'.
M-x replace-regexp RET \(c[ad]+r\)-safe RET \1 RET
would perform exactly the opposite replacements. To include a `\' in the text to replace with, you must give `\\'.
If the arguments to a replace command are in lower case, the command preserves case when it makes a replacement. Thus, the following command:
M-x replace-string RET foo RET bar RET
replaces a lower-case `foo' with a lower case `bar', `FOO'
with `BAR', and `Foo' with `Bar'. If upper-case letters are
used in the second argument, they remain upper-case every time that
argument is inserted. If upper-case letters are used in the first
argument, the second argument is always substituted exactly as given, with
no case conversion. Likewise, if the variable case-replace is set
to nil, replacement is done without case conversion. If
case-fold-search is set to nil, case is significant in
matching occurrences of `foo' to replace; also, case conversion of the
replacement string is not done.
If you want to change only some of the occurrences of `foo' to
`bar', not all of them, you can use query-replace instead of
M-%. This command finds occurrences of `foo' one by one,
displays each occurrence, and asks you whether to replace it. A numeric
argument to query-replace tells it to consider only occurrences
that are bounded by word-delimiter characters.
Aside from querying, query-replace works just like
replace-string, and query-replace-regexp works
just like replace-regexp.
The things you can type when you are shown an occurrence of string or a match for regexp are:
replace-string, provided case-replace is non-nil,
as it normally is.
query-replace. If you want to do further
replacement you must use C-x ESC to restart (see section Repeating Minibuffer Commands).
query-replace.
If you type any other character, Emacs exits the query-replace, and
executes the character as a command. To restart the query-replace,
use C-x ESC, which repeats the query-replace because it
used the minibuffer to read its arguments. See section Repeating Minibuffer Commands.
Here are some other commands that find matches for a regular expression. They all operate from point to the end of the buffer.