Hour 7: Searching for Text in a Buffer: Incremental Search

Sams Teach Yourself Emacs in 24 Hours

Hour 7: Searching for Text in a Buffer

Sections in this Hour:
Incremental Search		Summary
Searching for Words		Q&A
Search and Replace		Exercises
Listing Lines that Match a Pattern

Hour 7
Searching for Text in a Buffer

After you learn the basics of editing in Emacs, you will be ready to continue to the next topic of editing files. That is, locating the text that you want to change. Although this might seem like an issue that you can cover in three minutes, it isn't! This issue includes many different search situations, such as the following:

Searching for text in the current buffer

Listing lines that match a particular pattern

Searching for text in several files

Replacing some text with other text

Keeping a list of locations in different files

This subject is split over three hours. This hour describes various ways to do search-related tasks in one buffer. Hour 8, "Searching for Text in Multiple Files," describes how to do search-related tasks in several files. Finally Hour 9, "Regular Expressions," describes searches that include regular expressions instead of ordinary text.

Incremental Search

Two of the searching functions in Emacs are bound to C-s (isearch-forward) and C-r (isearch-backward). These functions search forward and backward in the text, respectively. Before I discuss them, you should try them out. Yes, now--go on and try them and come back later; I'll discuss them afterward. When searching with C-s and C-r, Emacs starts searching for the text as soon as you start typing. This helps you speed up your work, because you seldom need to type the whole word or phrase that you are searching for.

Searching for Words in Text

This task will show you an example of an incremental search, in which the word alarmingly is searched for. The steps are shown together with an Emacs window that shows the search progress. The important thing to notice is the location of the point. To begin, follow these steps:

: 1. Press C-s (isearch-forward) to start searching. This prompts you with the text I-search: in the minibuffer (see Figure 7.1). Had you chosen to search backward, the prompt would be I-search backward:.

Figure 7.1
Press C-s or C-r to start your search.

: 2. Press the letter a. Emacs will immediately position the point at the first location in the buffer, where the substring a is (see Figure 7.2).

Figure 7.2
Pressing a makes Emacs proceed to the first location with an a.

: 3. Press the letter l (that is, the lowercase letter L). Because the letter after a at its current position isn't the letter l, Emacs continues its search, and this time it moves the point to the letter l in Aladdin (see Figure 7.3).

Figure 7.3
Typing the letter l makes Emacs search forward in the text for this, because the next letter at the previous location wasn't an l.

: 4. Press the letter a again. This time Emacs doesn't need to start searching again, because its current match can be extended with the letter a (see Figure 7.4).

Figure 7.4
The current location also matches ala, so Emacs doesn't need to continue searching through the document.

: 5. Press the letter r, and Emacs will continue searching until it finds the substring alar. Now you have found the first occurrence of the word alarmingly (see Figure 7.5).

Figure 7.5
The word alarmingly has now been found.

: 6. Press C-s to continue searching for the text alar. This will bring you to the next occurrence of alarmingly (see Figure 7.6).

Figure 7.6
Pressing C-s will make Emacs proceed to the next match of the string alar.

: 7. You might press C-s a few times until you get to the third occurrence of alarmingly; but an alternative is to press C-w, which will append the rest of the word to the search string, and then press C-s with this modified search string. Try pressing C-w (see Figure 7.7).

Figure 7.7
Typing C-w will make Emacs append the rest of the current word to the search string.

: 8. Finally, press C-s, which brings you to the third occurrence of the word alarmingly (see Figure 7.8).

Figure 7.8
Pressing C-s will now continue the search, this time for the word alarmingly.

: 9. Now that you have found the location at which you want to edit, press the Enter key to exit the incremental search.

Although these steps might seem difficult and cumbersome, they aren't. Quickly review what you did: You started to type the word you were searching for. When you came to a location where you could see that you needed to type many letters before the search would continue to a new word, you pressed C-s. When you got to the word you searched for, you pressed C-w and continued the search with C-s. After you have these keybindings in your fingers, you'll be amazed how quickly you can find the right location.

Note - Incremental searches are not limited to word boundaries. Your search string might match in the middle of a word. For example, if you search for the, Emacs will also match aesthetic, because it contains the letters the in it.

Exiting a Search

It might seem obvious, but the purpose of searching for something is to find it; when you have found it, you want the point to be at that location so you can continue editing from there. To do so, press the Enter key when you have found the correct location. An alternative is to press one of the keys that do not have special meaning within the search (you'll learn about this shortly). Thus you can press M-b (backward-word) to exit search and go to the beginning of the word in which you found a match.

Caution - The previous paragraph is only accurate only if you (or your system administrator) haven't set the variable search-exit-option to nil. If you find that Emacs says that M-b isn't valid when you press it while searching, search-exit-option is set to nil.

To disable it, insert the following into your .emacs file:

(setq search-exit-option t)

Hitting Enter will then be your only way to exit the search.

If, on the other hand, you do not find what you are searching for, you might want to get back to the location where you started your search. To do that you must press C-g either once or twice. If you type characters that aren't found, you need to press C-g twice; otherwise, it is enough to press it once. In a situation where you press extra characters that aren't found, the first C-g will remove these characters from the search string, and the second C-g will exit your searching.

Using an Old Search String

If you search for a string once, you're likely to search for it again. For that reason, Emacs has the capability to recall old search strings. The most valuable of these features is the capability to do the previous search once again.

If you press C-s or C-r as the first letter of your search string, Emacs will search again for the string that you searched for the previous time you searched. (C-s will search forward and C-r will search backward.) If you searched for the string beer in your previous search, and you press C-s C-s, you will search for the word beer once again, forward from your current location in the buffer.

You can also search backward in the history of search commands (just like you can search backward for previously opened files when you press C-x C-f [find-file]). To do this, press either C-s or C-r to search through your search history, and then press M-p to search backward in the history of search strings. If you get too far back, you can press M-n to search forward once again. When you find the string that you want to use, you can modify it if it is not the exact string you want to search for. When you are happy about the string, you can start the search by pressing the Enter key.

If you have marked some text and you want to append this to your search string, you can press M-y. This also means that if you have some marked text that you want to search for, you simply press C-s M-y.

Caution - Please note that the keybinding for pasting the text onto the search string is M-y and not C-y. C-y does normally mean paste, but not when searching. When searching, C-y means append to the search string all the text from the point to the end of the line.

When the Search Fails

When you search forward in the buffer and Emacs gets to the end of the buffer without finding a match for your search string, it beeps and displays Failing I-search. At this point, you can press C-s to make Emacs continue searching from the beginning of the buffer. In case you should forget it, Emacs indicates that this has happened by changing its prompt from I-search to Wrapped I-search. If you continue searching, Emacs will at some point pass your original starting point. To indicate this, its prompt changes to Overwrapped I-search.

The same applies when you search backward in the buffer--with the natural difference that the point where searching becomes wrapped is at the beginning of the buffer instead of the end.

Cases in Search Operations

When searching for some text in Emacs, case matters only if you have included case in your search string. Thus if you search for the text foo (all lowercase), Emacs will find every text string that matches foo regardless of its case. Emacs will find FOO, Foo, and fOo. If, on the other hand, your search string includes letters in uppercase, only words that match the case will be found.

Tip - As everything else in Emacs, its behavior can be changed. If you want Emacs to always match using case (such as, Foo should not be matched by foo), insert the following line into your .emacs file:

(setq-default case-fold-search nil)

Searching for a String from the Window Manager's Clipboard

An ordinary nonincremental nonword search mechanism is available by pressing C-s and the Enter key. You will very seldom use this way of searching, because you will find incremental search a very convenient way of searching. There is one situation, however, where this is useful. Namely if you have marked some text in another application that you want to search for in Emacs. Because this text is not available in your kill-ring, it cannot be appended to the search string by pressing M-y when searching. In these situations you should press C-s to start your searching, press the Enter key to enter ordinary text search, paste the text into the search string using the mouse, and press Enter again to start the search.

Windows Notes - GNU Emacs on Windows will bring the contents of the Clipboard into the minibuffer with C-y. The Clipboard is the top of the kill-ring.

Highlighting the Matches

It is very useful if your match is highlighted when searching, instead of the point being located next to the match. An example of such highlighting is shown in Figure 7.9.

Figure 7.9
Highlighting the matches when searching.

To enable highlighting when searching, insert the following line in your .emacs file:


(setq search-highlight t)

To highlight matches when using search-and-replace (search-and-replace is described in the next section), insert the following line in your .emacs file:


(setq query-replace-highlight t)

Marking and Searching in XEmacs

If point is located at the beginning of a text piece that you want to mark for cut-and-paste, you can set the mark at the location as usual by pressing C-SPC (set- mark-command). After that you can search forward to find the end of the region, and use the desired cut-and-paste function.

If you use XEmacs, there is one point to be aware of. Namely that XEmacs deactivates the mark when starting to search. This means that the region is not active after searching, and thus cannot be used for cut-and-paste. The mark, however, still exists, so you can reactivate the region by pressing C-x C-x (exchange-point-and-mark) and afterward do the cut-and-paste operation.