7. The Minibuffer

The minibuffer is the facility used by af commands to read arguments more complicated than a single number. Minibuffer arguments can be file names, buffer names, af command names, address lists, and many other things, depending on the command reading the argument. You can use many editing commands in the minibuffer to edit the argument.

When the minibuffer is in use, it appears in the echo area, and the terminal's cursor moves there. The beginning of the minibuffer line displays a prompt which says what kind of input you should supply and how it will be used. Often this prompt is derived from the name of the command that the argument is for. The prompt normally ends with a colon.

Sometimes a default argument appears in parentheses after the colon; it too is part of the prompt. The default will be used as the argument value if you enter an empty argument (e.g., just type RET). For example, commands that read buffer names always show a default, which is the name of the buffer that will be used if you type just RET.

The simplest way to enter a minibuffer argument is to type the text you want, terminated by RET which exits the minibuffer. You can cancel the command that wants the argument, and get out of the minibuffer, by typing C-g.

Sometimes, a default response will already be in the minibuffer when you enter it. If it is completely wrong, then you can type C-a C-k to remove it. These default responses appear for convenience when you are prompted for a long value that you are likely to want to edit, rather then retype from scratch.

Most commands which use typeout allow you to redirect the output into a file, instead of viewing it. The major exception to this is RET (open-message), since there are several ways to save a message to a file. To redirect typeout to a file simply give the command a prefix argument of any value; you will be prompted for the file name using the minibuffer.

7.1 Echo Area Conflicts		How af handles echoing in the minibuffer.
7.2 Inserting Text		How to enter text into the minibuffer.
7.3 Deleting Text		How to delete text in the minibuffer.
7.4 Editing the Text		Basic minibuffer editing commands.
7.5 Dealing with Words		Commands which act on words in the text.
7.6 Completion		An abbreviation facility for minibuffer input.
7.7 Minibuffer History		Reusing recent minibuffer arguments.

7.1 Echo Area Conflicts

• If a command gets an error while you are in the minibuffer, this does not cancel the minibuffer. However, the echo area is needed for the error message and therefore the minibuffer itself is hidden for a while. It comes back after a few seconds, or as soon as you type anything.

• If in the minibuffer you use a command whose purpose is to print a message in the echo area, such as C-x =, the message is printed normally, and the minibuffer is hidden for a while. It comes back after a few seconds, or as soon as you type anything.

• Echoing of keystrokes does not take place while the minibuffer is in use.

7.2 Inserting Text

To insert printing characters into the minibuffer, just type them. This inserts the characters you type into the buffer at the cursor (that is, at point; which has a different appearance in the minibuffer, but the same meaning). The cursor moves forward, and any text after the cursor moves forward too. If the text in the buffer is `foobar', with the cursor before the `b', then if you type xx, you get `fooxxbar', with the cursor still before the `b'. This all works because in the minibuffer all the printing characters run the command self-insert-command.

Direct insertion works for printing characters and SPC, but other characters act as editing commands and do not insert themselves. If you need to insert a control character or a character whose code is above 200 octal, you must quote it by typing the character C-q (quoted-insert) first. There are two ways to use C-q:

• C-q followed by any non-graphic character (even C-g) inserts that character.
• C-q followed by three octal digits inserts the character with the specified character code.

A numeric argument to C-q specifies how many copies of the quoted character should be inserted (see section 5.8 Numeric Arguments).

When you have finished entering the text, simply type RET (newline) to accept the argument and exit the minibuffer.

7.3 Deleting Text

To delete a character you have inserted, use DEL (delete-backward-char). DEL deletes the character before the cursor (not the one that the cursor is on top of or under; that is the character after the cursor). The cursor and all characters after it move backwards. Therefore, if you type a printing character and then type DEL, they cancel out.

To delete the character that the cursor is under, use C-d (delete-char). This deletes the character, moving all the characters after the cursor backwards. The cursor is left in place. Therefore C-d is equivalent to C-f DEL.

To delete the text from the cursor to the end of the line, use C-k (kill-line). This kills the characters from the one the cursor is under to the end of the line, leaving the cursor at the end of the line (see section 14.5 Killing and Yanking in the Minibuffer).

7.4 Editing the Text

C-a

Move to the beginning of the line (beginning-of-line).

C-e

Move to the end of the line (end-of-line).

C-f

Move forward one character (forward-char).

C-b

Move backward one character (backward-char).

C-t

Transpose the two characters on either side of point, moving point forward one character (transpose-chars).

7.5 Dealing with Words

The minibuffer includes several commands for dealing with words rather than characters. Often these take the usual command for moving point, but use a Meta key rather then a control key:

M-f

Move forward one word (forward-word).

M-b

Move backward one word (backward-word).

M-DEL

Delete the next word (backward-kill-word).

M-d

Delete the previous word (kill-word).

M-l

Convert the next word to lower case (downcase-word).

M-u

Convert the next word to upper case (upcase-word).

M-c

Capitalise the next word (capitalize-word).

7.6 Completion

For certain kinds of arguments, you can use completion to enter the argument value. Completion means that you type part of the argument, then af visibly fills in the rest, or as much as can be determined from the part you have typed.

When completion is available, certain keys---TAB, RET, and SPC---are rebound to complete the text present in the minibuffer into a longer string that it stands for, by matching it against a set of completion alternatives provided by the command reading the argument. ? is defined to display a list of possible completions of what you have inserted.

For example, when M-x uses the minibuffer to read the name of a command, it provides a list of all available af command names to complete against. The completion keys match the text in the minibuffer against all the command names, find any additional name characters implied by the ones already present in the minibuffer, and add those characters to the ones you have given. This is what makes it possible to type M-x del SPC m RET instead of M-x delete-message RET (for example).

Case is often significant in completion, because it is significant in many of the names that you can complete (buffer names and file names). Thus, `fo' often does not complete to `Foo'. Completion does ignore case distinctions for certain arguments in which case does not matter (such as af command or configuration variable names).

7.6.1 Completion Example		An example of minibuffer completion.
7.6.2 Completion Commands		Commands that completion uses.
7.6.3 Strict Completion		Types of minibuffer completion.

7.6.1 Completion Example

A concrete example may help here. If you type M-x co TAB, the TAB looks for alternatives (in this case, command names) that start with `co'. There are only two: copy-region-as-kill and copy-tagset-as-kill. These are the same as far as copy-, so the `co' in the minibuffer changes to `copy-'.

If you type TAB again immediately, there are multiple possibilities for the very next character--it could be `r' or `t'---so no more characters are added; instead, TAB just produces a beep. If you now type ?, af will produce a list of all possible completions to typeout; when you exit typeout, the minibuffer is still waiting for the next character.

If you go on to type r TAB, this TAB sees `copy-r'. The only command name starting this way is copy-region-as-kill, so completion fills in the rest of that. You now have `copy-region-as-kill' in the minibuffer after typing just co TAB r TAB. Note that TAB has this effect because in the minibuffer it is bound to the command minibuffer-complete when completion is available.

7.6.2 Completion Commands

TAB

Complete the text in the minibuffer as much as possible (minibuffer-complete).

SPC

Complete the minibuffer text, but don't go beyond one word (minibuffer-complete-word).

RET

Submit the text in the minibuffer as the argument, possibly completing first as described below (minibuffer-complete-and-exit).

?

Print a list of all possible completions of the text in the minibuffer (minibuffer-list-completions).

SPC completes much like TAB, but never goes beyond the next hyphen or space. If you have `copy-r' in the minibuffer and type SPC, it finds that the completion is `copy-region-as-kill', but it stops completing after `region-'. This gives `copy-region-'. Another SPC at this point completes to `copy-region-as-'.

7.6.3 Strict Completion

There are three different ways that RET can work in completing the minibuffer, depending on how the argument will be used.

• Strict completion is used when it is meaningless to give any argument except one of the known alternatives. For example, when M-x reads the name of a command to run, it is meaningless to give anything but the name of an existing command or macro. In strict completion, RET refuses to exit if the text in the minibuffer does not complete to an exact match.

• Cautious completion is similar to strict completion, except that RET exits only if the text was an exact match already, not needing completion. If the text is not an exact match, RET does not exit, but it does complete the text. If it completes to an exact match, a second RET will exit.

  Cautious completion is used for reading file names for files that must already exist.

• Permissive completion is used when any string whatever is meaningful, and the list of completion alternatives is just a guide. For example, when C-x C-f reads the name of a folder to visit, any folder name is allowed, in case you want to create a folder. In permissive completion, RET takes the text in the minibuffer exactly as given, without completing it.

7.7 Minibuffer History

Every argument that you enter with the minibuffer is saved on a minibuffer history list so that you can use it again later in another argument. You can think of the minibuffer history as a buffer which you can move through displaying a line at a time.

C-p

Move to the next earlier argument string saved in the minibuffer history (previous-line).

C-n

Move to the next later argument string saved in the minibuffer history (next-line).

M-<

Move to the first argument string saved in the minibuffer history (beginning-of-buffer).

M->

Move to the last argument string saved in the minibuffer history (end-of-buffer). This will always move you to the text you were editing before using the minibuffer history.

C-r

Move to an earlier saved argument in the minibuffer history that matches the current text (search-backward).

C-s

Move to a later saved argument in the minibuffer history that matches the current text (search-forward)..

The simplest way to reuse the saved arguments in the history list is to move through the history list one element at a time. While in the minibuffer, type C-p to "move to" the previous minibuffer input, and use C-n to "move to" the next input. Similarly, you can use C-< and C-> to "move to" the first and last elements in the history list.

When you move to a new history line, any text you had typed is stored for you as the last history element, so you can return to it by typing M->. To use a history element as the argument, exit the minibuffer as usual with RET. You can also edit the text before you reuse it; this does not change the history element that you "moved" to, but your new argument does go at the end of the history list in its own right.

There are also commands to search forward or backward through the history. At the moment they search for a history element that starts with the text you have typed in the minibuffer, up to the position of the cursor; so typing `list- C-r' will search for a history element that begins with `list-'. If a matching history element is found then the cursor will stay in the same column, so that typing C-r again will search for another history element beginning with list-.