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 |
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.
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]
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.
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.
[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.
[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.