[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Emacs commands use the minibuffer to read arguments more complicated than a single number. Minibuffer arguments can be file names, buffer names, Lisp function names, Emacs command names, Lisp expressions, and many other things, depending on the command reading the argument. To edit the argument in the minibuffer, you can use Emacs editing commands.
When the minibuffer is in use, it appears in the echo area, and the cursor moves there. The beginning of the minibuffer line displays a prompt indicating what kind of input you should supply and how it will be used. The prompt is often derived from the name of the command 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 is used as the argument value if you enter an empty argument (e.g., by just typing <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 give a minibuffer argument is to type the text you want, terminated by <RET> to exit the minibuffer. To get out of the minibuffer and cancel the command that it was for, type C-g.
Since the minibuffer uses the screen space of the echo area, it can conflict with other ways Emacs customarily uses the echo area. Here is how Emacs handles such conflicts:
1.1 Minibuffers for File Names | Entering file names with the minibuffer. | |
1.2 Editing in the Minibuffer | How to edit in the minibuffer. | |
1.3 Completion | An abbreviation facility for minibuffer input. | |
1.4 Repeating Minibuffer Commands | Re-executing commands that used the minibuffer. |
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Sometimes the minibuffer starts out with text in it. For example, when you are supposed to give a file name, the minibuffer starts out containing the default directory, which ends with a slash. This informs you in which directory the file will be looked for if you do not specify a different one. For example, the minibuffer might start out with:
Find File: /u2/emacs/src/
where ‘Find File: ’ is the prompt. Typing buffer.c specifies
the file
‘/u2/emacs/src/buffer.c’. To find files in nearby
directories, use ‘..’; thus, if you type ../lisp/simple.el, the
file that you visit will be the one named
‘/u2/emacs/lisp/simple.el’.
Alternatively, you can use M-<DEL> to kill directory names you
don’t want (@pxref{Words}).
You can also type an absolute file name, one starting with a slash or a tilde, ignoring the default directory. For example, to find the file ‘/etc/termcap’, just type the name, giving:
Find File: /u2/emacs/src//etc/termcap
Two slashes in a row are not normally meaningful in Unix file names, but they are allowed in XEmacs. They mean, “ignore everything before the second slash in the pair.” Thus, ‘/u2/emacs/src/’ is ignored, and you get the file ‘/etc/termcap’.
If you set insert-default-directory
to nil
, the default
directory is not inserted in the minibuffer. This way, the minibuffer
starts out empty. But the name you type, if relative, is still
interpreted with respect to the same default directory.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The minibuffer is an Emacs buffer (albeit a peculiar one), and the usual Emacs commands are available for editing the text of an argument you are entering.
Since <RET> in the minibuffer is defined to exit the minibuffer, you must use C-o or C-q <LFD> to insert a newline into the minibuffer. (Recall that a newline is really the <LFD> character.)
The minibuffer has its own window, which always has space on the screen but acts as if it were not there when the minibuffer is not in use. The minibuffer window is just like the others; you can switch to another window with C-x o, edit text in other windows, and perhaps even visit more files before returning to the minibuffer to submit the argument. You can kill text in another window, return to the minibuffer window, and then yank the text to use it in the argument. @xref{Windows}.
There are, however, some restrictions on the use of the minibuffer window. You cannot switch buffers in it—the minibuffer and its window are permanently attached. You also cannot split or kill the minibuffer window, but you can make it taller with C-x ^.
If you are in the minibuffer and issue a command that displays help text in another window, that window will be scrolled if you type M-C-v while in the minibuffer until you exit the minibuffer. This feature is helpful if a completing minibuffer gives you a long list of possible completions.
If the variable minibuffer-confirm-incomplete
is t
, you
are asked for confirmation if there is no known completion for the text
you typed. For example, if you attempted to visit a non-existent file,
the minibuffer might read:
Find File:chocolate_bar.c [no completions, confirm]
If you press Return again, that confirms the filename. Otherwise, you can continue editing it.
Emacs supports recursive use of the minibuffer. However, it is easy to do this by accident (because of autorepeating keyboards, for example) and get confused. Therefore, most Emacs commands that use the minibuffer refuse to operate if the minibuffer window is selected. If the minibuffer is active but you have switched to a different window, recursive use of the minibuffer is allowed—if you know enough to try to do this, you probably will not get confused.
If you set the variable enable-recursive-minibuffers
to be
non-nil
, recursive use of the minibuffer is always allowed.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When appropriate, the minibuffer provides a completion facility. You type the beginning of an argument and one of the completion keys, and Emacs visibly fills in the rest, depending on what you have already typed.
When completion is available, certain keys—<TAB>, <RET>, and <SPC>—are redefined to complete an abbreviation 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 the minibuffer is being used by Meta-x to read the name of a command, it is given a list of all available Emacs command names to complete against. The completion keys match the text in the minibuffer against all the command names, find any additional characters of the name that are implied by the ones already present in the minibuffer, and add those characters to the ones you have given.
Case is normally significant in completion because it is significant in most of the names that you can complete (buffer names, file names, and command names). Thus, ‘fo’ will not complete to ‘Foo’. When you are completing a name in which case does not matter, case may be ignored for completion’s sake if specified by program.
When a completion list is displayed, the completions will highlight as you move the mouse over them. Clicking the middle mouse button on any highlighted completion will “select” it just as if you had typed it in and hit <RET>.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Consider the following example. If you type Meta-x au <TAB>,
<TAB> looks for alternatives (in this case, command names) that
start with ‘au’. There are only two commands: auto-fill-mode
and
auto-save-mode
. They are the same as far as auto-
, so the
‘au’ in the minibuffer changes to ‘auto-’.
If you type <TAB> again immediately, there are multiple possibilities for the very next character—it could be ‘s’ or ‘f’—so no more characters are added; but a list of all possible completions is displayed in another window.
If you go on to type f <TAB>, this <TAB> sees
‘auto-f’. The only command name starting this way is
auto-fill-mode
, so completion inserts the rest of that command. You
now have ‘auto-fill-mode’ in the minibuffer after typing just au
<TAB> f <TAB>. Note that <TAB> has this effect because in the
minibuffer it is bound to the function minibuffer-complete
when
completion is supposed to be done.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Here is a list of all the completion commands defined in the minibuffer when completion is available.
Complete the text in the minibuffer as much as possible
(minibuffer-complete
).
Complete the text in the minibuffer but don’t add or fill out more
than one word (minibuffer-complete-word
).
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
).
Select the highlighted text under the mouse as a minibuffer response.
When the minibuffer is being used to prompt the user for a completion,
any valid completions which are visible on the screen will be highlighted
when the mouse moves over them. Clicking <button2> will select the
highlighted completion and exit the minibuffer.
(minibuf-select-highlighted-completion
).
<SPC> completes in a way that is similar to <TAB>, but it never
goes beyond the next hyphen or space. If you have ‘auto-f’ in the
minibuffer and type <SPC>, it finds that the completion is
‘auto-fill-mode’, but it stops completing after ‘fill-’.
The result is ‘auto-fill-’. Another <SPC> at this point
completes all the way to ‘auto-fill-mode’. <SPC> in the
minibuffer runs the function minibuffer-complete-word
when
completion is available.
There are three different ways that <RET> can work in completing minibuffers, depending on how the argument will be used.
Cautious completion is used for reading file names for files that must already exist.
The completion commands display a list of all possible completions in a window whenever there is more than one possibility for the very next character. Typing ? explicitly requests such a list. The list of completions counts as help text, so C-M-v typed in the minibuffer scrolls the list.
When completion is done on file names, certain file names are usually
ignored. The variable completion-ignored-extensions
contains a list
of strings; a file whose name ends in any of those strings is ignored as a
possible completion. The standard value of this variable has several
elements including ".o"
, ".elc"
, ".dvi"
and "~"
.
The effect is that, for example, ‘foo’ completes to ‘foo.c’
even though ‘foo.o’ exists as well. If the only possible completions
are files that end in “ignored” strings, they are not ignored.
If a completion command finds the next character is undetermined, it
automatically displays a list of all possible completions. If the variable
completion-auto-help
is set to nil
, this does not happen,
and you must type ? to display the possible completions.
If the variable minibuffer-confirm-incomplete
is set to t
,
then in contexts where completing-read
allows answers that are
not valid completions, an extra <RET> must be typed to confirm the
response. This is helpful for catching typos.
[ << ] | [ < ] | [ Up ] | [ > ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Every command that uses the minibuffer at least once is recorded on a special history list, together with the values of the minibuffer arguments, so that you can repeat the command easily. In particular, every use of Meta-x is recorded, since M-x uses the minibuffer to read the command name.
Re-execute a recent minibuffer command
(repeat-complex-command
).
Within C-x <ESC>, move to previous recorded command
(previous-history-element
).
Within C-x <ESC>, move to the next (more recent) recorded
command (next-history-element
).
Display the entire command history, showing all the commands C-x <ESC> can repeat, most recent first.
C-x <ESC> is used to re-execute a recent command that used the minibuffer. With no argument, it repeats the last command. A numeric argument specifies which command to repeat; 1 means the last one, and larger numbers specify earlier commands.
C-x <ESC> works by turning the previous command into a Lisp expression and then entering a minibuffer initialized with the text for that expression. If you type just <RET>, the command is repeated as before. You can also change the command by editing the Lisp expression. The expression you finally submit will be executed. The repeated command is added to the front of the command history unless it is identical to the most recently executed command already there.
Even if you don’t understand Lisp syntax, it will probably be obvious which command is displayed for repetition. If you do not change the text, you can be sure the command will repeat exactly as before.
If you are in the minibuffer for C-x <ESC> and the command shown to you is not the one you want to repeat, you can move around the list of previous commands using M-n and M-p. M-p replaces the contents of the minibuffer with the next earlier recorded command, and M-n replaces it with the next later command. After finding the desired previous command, you can edit its expression and then resubmit it by typing <RET>. Any editing you have done on the command to be repeated is lost if you use M-n or M-p.
M-n and M-p are specially defined within C-x <ESC>
to run the commands previous-history-element
and
next-history-element
.
The list of previous commands using the minibuffer is stored as a Lisp
list in the variable command-history
. Each element of the list
is a Lisp expression which describes one command and its arguments.
Lisp programs can reexecute a command by feeding the corresponding
command-history
element to eval
.
[Top] | [Contents] | [Index] | [ ? ] |
This document was generated on December 6, 2024 using texi2html 5.0.
The buttons in the navigation panels have the following meaning:
Button | Name | Go to | From 1.2.3 go to |
---|---|---|---|
[ << ] | FastBack | Beginning of this chapter or previous chapter | 1 |
[ < ] | Back | Previous section in reading order | 1.2.2 |
[ Up ] | Up | Up section | 1.2 |
[ > ] | Forward | Next section in reading order | 1.2.4 |
[ >> ] | FastForward | Next chapter | 2 |
[Top] | Top | Cover (top) of document | |
[Contents] | Contents | Table of contents | |
[Index] | Index | Index | |
[ ? ] | About | About (help) |
where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:
This document was generated on December 6, 2024 using texi2html 5.0.