14.5. Completion

We saw an example of Emacs's completion facility in Chapter 1. Completion is more than just a feature: it is a general principle in the design of Emacs. It can be articulated as follows:

If you have to type in the name of something, and that name is one of a finite number of possibilities, Emacs should figure out what you mean after the smallest possible number of keystrokes.

In other words, you can type in the shortest unambiguous prefix and tell Emacs to figure out the rest of the name. By "shortest unambiguous prefix," we mean "enough of the name, starting from the beginning, to distinguish it from the other possibilities." Several important things in Emacs have names that are chosen from a finite number of possibilities, including the following:

• Commands

• Files in a given directory

• Buffers

• Emacs variables

Most of the time, completion is available when you are prompted for a name of something in the minibuffer. While you are typing in the name, you can use three keys to tell Emacs to help complete it for you: Tab, Space, and question mark (?). Their functions are shown in Table 14-5.

Table 14-5. Completion keys

Keystroke	Action
Tab	Completes the name as far as possible.
Space	Completes the name out to the next punctuation character.
?	Lists the choices at this point in a *Completions* window.

You will probably find Tab to be the most useful.

As a running example, assume you have typed C-x C-f to visit a file, and the file you want to visit is a C program called program.c. Let's say you type pro and press Tab; Emacs responds by completing the name to the full program.c. If you press Space, Emacs completes only as far as program. After Emacs completes the name, you can press Enter to visit the file.

How much of the name do you need to type in before you can use completion? That depends on the other possible choices in the given situation. If program.c were the only file in your directory, you could just type p and press Tab.^[2] If there were other files in your directory and none of them has a name beginning with p, you could do the same thing. But if you had a file called problem.c, you would have to type prog before you pressed Tab; in this case, prog is the shortest unambiguous prefix. If you just type in pro and press Tab, Emacs responds with a *Completions* window containing a list of the completion choices, in this case program.c and problem.c, and returns your cursor to the minibuffer so that you can finish typing the filename. The same thing happens if you typed a question mark instead of Tab. At this point, you can type g and press Tab again; Emacs completes the name to program.c.

^[2] You can't just press Tab without typing the p because the current and parent directories, named . and .., respectively, are also file choices. Normally, Emacs runs dired when you visit a file that's a directory.

As another example, let's say you have documentation for your C program in the file program.txt, and you want to visit it. You press C-x C-f and type prog at the prompt, followed by Tab. Emacs completes out to program.. At this point, you can type t and press Tab again; Emacs completes the entire program.txt. In other words, you can use completion repeatedly when specifying a name.

Finally, let's say you also have a file in your directory called simply program, which is the result of compiling your C file, but you still want to visit the documentation file. You type prog and press Tab; Emacs completes out to program. (including the period). At this point, Tab and Space do different things. If you press Tab again, Emacs responds with the message [Complete, but not unique] in the minibuffer, but if you press Space, Emacs assumes you aren't interested in the file program and attempts to complete further. Because you have the files program.c and program.txt, Emacs only completes out to program., and you have to type t and press Tab again.

Completion works the same way with buffer names, for example, when you type C-x b to switch to another buffer in the current window. It also works with command names when you type M-x but with one added feature. Notice that when you specify a file or buffer name, it is possible that the file or buffer you want doesn't yet exist (for example, when you want to create a new file). In this case, of course, you must type in the entire file or buffer name and press Enter. But when you type M-x for a command, there is no possibility of the command not existing. Therefore, Emacs automatically attempts to do completion on command names when you press Enter.

For example, if you want to put a buffer for a text file in auto-fill mode (see Chapter 2), you can type M-x auto-f and press Enter instead of typing the entire M-x auto-fill-mode. If you type in a nonunique (ambiguous) prefix of a command name for example, if you type M-x aut and press Enter, then Enter acts just like Tab; in this case, it completes out to auto. If you press Enter again, Emacs responds with a *Completions* window listing the choices. To get auto-fill-mode, you have to type f and press Enter again.

Completion on command names with Enter is very convenient. After you have used Emacs for a while, you will become familiar with the shortest unambiguous prefixes for commands you use often, and you can save a considerable amount of typing by using these prefixes instead of the full names.^[3]

^[3] For example, if you make changes to your .emacs file regularly, you will appreciate that M-x eval-c is an acceptable prefix for M-x eval-current-buffer.

Emacs can also do completion on the names of Emacs variables. In Chapter 2, and elsewhere, we saw how you can use M-x set-variable to change the values of Emacs variables. The Enter feature just described works on variables as well as commands; therefore, you can use completion, including Enter, when doing M-x set-variable. Actually, commands and variables are both special kinds of Emacs Lisp symbols, and Emacs can do completion with Enter on all kinds of Lisp symbols. Completion on Lisp symbols comes in handy when you are using some of the help commands described earlier in this chapter.

14.5.1 Customizing Completion

If you have read Chapter 10 and are comfortable with setting Emacs variables, you should know that a few variables can customize the way Emacs does completion. The variable completion-auto-help determines whether a *Completions* window automatically appears when you try to use Space or Tab on an ambiguous prefix. Its default is t, meaning that such windows automatically appear. If you set it to nil, instead of a *Completions* window appearing, Emacs just displays the message [Next char not unique] for a couple of seconds in the minibuffer.

If you are a programmer or if you use text formatters like LATEX , you will create files that are not meant for humans to read, such as object files created by compilers and print files created by text formatters. Ideally, you wouldn't want Emacs to bother with these files when you are doing completion; for example, if you have the files program.c and program.o (object-code output from the compiler), you want Emacs to recognize only the former. Emacs does have a feature that deals with this; indeed, you may already have noticed that in this kind of situation, if you type program and press Tab, Emacs ignores program.o and completes out to program.c. The variable completion-ignored-extensions controls this; it is a list of filename suffixes that Emacs ignores during filename completion. By default, the list includes tilde (~) for Emacs backup files, .o for programmers, various suffixes for users, .elc (byte-compiled Emacs Lisp) for Emacs customizers, and others. (Of course, if you really want to look at these files, you can type their names manually.)

You can add your own "ignored" suffix to the list by putting a line of this form in your .emacs file:

(setq completion-ignored-extensions       (cons "suffix" completion-ignored-extensions))

For example, let's say you are doing text processing with a printer that prints PostScript, and your text processor produces print files with the suffix .ps. If you don't want to look at these files, put the following line in your .emacs file:

(setq completion-ignored-extensions       (cons ".ps" completion-ignored-extensions))

Finally, you can tell Emacs to ignore case distinctions when doing completion by setting the variable completion-ignore-case to t (or any value other than nil). Its default value is nil, meaning that Emacs respects case distinctions.