+@c -*- coding: utf-8 -*-
@c This is part of the Emacs manual.
-@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2016 Free Software
+@c Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Minibuffer
@chapter The Minibuffer
use the usual Emacs editing commands in the minibuffer to edit the
argument text.
+@menu
+* Basic Minibuffer:: Basic usage of the minibuffer.
+* Minibuffer File:: Entering file names with the minibuffer.
+* Minibuffer Edit:: How to edit in the minibuffer.
+* Completion:: An abbreviation facility for minibuffer input.
+* Minibuffer History:: Reusing recent minibuffer arguments.
+* Repetition:: Re-executing commands that used the minibuffer.
+* Passwords:: Entering passwords in the echo area.
+* Yes or No Prompts:: Replying yes or no in the echo area.
+@end menu
+
+@node Basic Minibuffer
+@section Using the Minibuffer
+
@cindex prompt
When the minibuffer is in use, it appears in the echo area, with a
-cursor. The minibuffer starts with a @dfn{prompt} in a distinct
-color, usually ending with a colon. The prompt states what kind of
-input is expected, and how it will be used.
+cursor. The minibuffer starts with a @dfn{prompt}, usually ending
+with a colon. The prompt states what kind of input is expected, and
+how it will be used. The prompt is highlighted using the
+@code{minibuffer-prompt} face (@pxref{Faces}).
The simplest way to enter a minibuffer argument is to type the text,
-then @key{RET} to submit the argument and exit the minibuffer. You
-can cancel the minibuffer, and the command that wants the argument, by
-typing @kbd{C-g}.
+then @key{RET} to submit the argument and exit the minibuffer.
+Alternatively, you can type @kbd{C-g} to exit the minibuffer by
+canceling the command asking for the argument (@pxref{Quitting}).
@cindex default argument
- Sometimes, a @dfn{default argument} appears in the prompt, inside
+ Sometimes, the prompt shows a @dfn{default argument}, inside
parentheses before the colon. This default will be used as the
argument if you just type @key{RET}. For example, commands that read
buffer names usually show a buffer name as the default; you can type
@key{RET} to operate on that default buffer.
+@cindex Minibuffer Electric Default mode
+@cindex mode, Minibuffer Electric Default
+@findex minibuffer-electric-default-mode
+@vindex minibuffer-eldef-shorten-default
+ If you enable Minibuffer Electric Default mode, a global minor mode,
+Emacs hides the default argument as soon as you modify the contents of
+the minibuffer (since typing @key{RET} would no longer submit that
+default). If you ever bring back the original minibuffer text, the
+prompt again shows the default. Furthermore, if you change the
+variable @code{minibuffer-eldef-shorten-default} to a non-@code{nil}
+value, the default argument is displayed as @samp{[@var{default}]}
+instead of @samp{(default @var{default})}, saving some screen space.
+To enable this minor mode, type @kbd{M-x
+minibuffer-electric-default-mode}.
+
Since the minibuffer appears in the echo area, it can conflict with
other uses of the echo area. If an error message or an informative
message is emitted while the minibuffer is active, the message hides
the minibuffer comes back. While the minibuffer is in use, keystrokes
do not echo.
-@menu
-* Minibuffer File:: Entering file names with the minibuffer.
-* Minibuffer Edit:: How to edit in the minibuffer.
-* Completion:: An abbreviation facility for minibuffer input.
-* Minibuffer History:: Reusing recent minibuffer arguments.
-* Repetition:: Re-executing commands that used the minibuffer.
-* Passwords:: Entering passwords in the echo area.
-* Yes or No Prompts:: Replying yes or no in the echo area.
-@end menu
-
@node Minibuffer File
@section Minibuffers for File Names
@cindex double slash in file name
@cindex slashes repeated in file name
@findex file-name-shadow-mode
-Emacs interprets a double slash as ``ignore everything before the
-second slash in the pair''. In the example above,
+A double slash causes Emacs to ignore everything before the
+second slash in the pair. In the example above,
@file{/u2/emacs/src/} is ignored, so the argument you supplied is
@file{/etc/termcap}. The ignored part of the file name is dimmed if
the terminal allows it. (To disable this dimming, turn off File Name
@findex minibuffer-inactive-mode
When not active, the minibuffer is in @code{minibuffer-inactive-mode},
-and clicking @kbd{Mouse-1} there shows the @file{*Messages*} buffer.
+and clicking @kbd{mouse-1} there shows the @file{*Messages*} buffer.
If you use a dedicated frame for minibuffers, Emacs also recognizes
certain keys there, for example @kbd{n} to make a new frame.
@table @kbd
@findex mouse-choose-completion
-@item Mouse-1
-@itemx Mouse-2
+@item mouse-1
+@itemx mouse-2
Clicking mouse button 1 or 2 on a completion alternative chooses it
(@code{mouse-choose-completion}).
point (@code{choose-completion}).
@findex next-completion
-@item @key{Right}
+@item @key{RIGHT}
While in the completion list buffer, this moves point to the following
completion alternative (@code{next-completion}).
@findex previous-completion
-@item @key{Left}
+@item @key{LEFT}
While in the completion list buffer, this moves point to the previous
completion alternative (@code{previous-completion}).
@end table
@cindex completion style
Completion commands work by narrowing a large list of possible
-completion alternatives to a smaller subset that ``matches'' what you
+completion alternatives to a smaller subset that matches what you
have typed in the minibuffer. In @ref{Completion Example}, we gave a
simple example of such matching. The procedure of determining what
-constitutes a ``match'' is quite intricate. Emacs attempts to offer
+constitutes a match is quite intricate. Emacs attempts to offer
plausible completions under most circumstances.
Emacs performs completion using one or more @dfn{completion
@code{".o"}, @code{".elc"}, and @code{"~"}. For example, if a
directory contains @samp{foo.c} and @samp{foo.elc}, @samp{foo}
completes to @samp{foo.c}. However, if @emph{all} possible
-completions end in ``ignored'' strings, they are not ignored: in the
+completions end in otherwise-ignored strings, they are not ignored: in the
previous example, @samp{foo.e} completes to @samp{foo.elc}. Emacs
disregards @code{completion-ignored-extensions} when showing
completion alternatives in the completion list.
+ Shell completion is an extended version of filename completion,
+@pxref{Shell Options}.
+
@vindex completion-auto-help
If @code{completion-auto-help} is set to @code{nil}, the completion
commands never display the completion list buffer; you must type
@vindex completion-cycle-threshold
If @code{completion-cycle-threshold} is non-@code{nil}, completion
-commands can ``cycle'' through completion alternatives. Normally, if
+commands can cycle through completion alternatives. Normally, if
there is more than one completion alternative for the text in the
minibuffer, a completion command completes up to the longest common
substring. If you change @code{completion-cycle-threshold} to
numeric value @var{n}, completion commands switch to this cycling
behavior only when there are @var{n} or fewer alternatives.
-@cindex Icomplete mode
-@findex icomplete-mode
- Icomplete mode presents a constantly-updated display that tells you
-what completions are available for the text you've entered so far. The
-command to enable or disable this minor mode is @kbd{M-x
-icomplete-mode}.
-
@node Minibuffer History
@section Minibuffer History
@cindex minibuffer history
@table @kbd
@item M-p
-@itemx @key{Up}
Move to the previous item in the minibuffer history, an earlier
argument (@code{previous-history-element}).
@item M-n
-@itemx @key{Down}
Move to the next item in the minibuffer history
(@code{next-history-element}).
+@item @key{UP}
+@itemx @key{DOWN}
+Like @kbd{M-p} and @kbd{M-n}, but move to the previous or next line of
+a multi-line item before going to the previous history item
+(@code{previous-line-or-history-element} and
+@code{next-line-or-history-element}) .
@item M-r @var{regexp} @key{RET}
Move to an earlier item in the minibuffer history that
matches @var{regexp} (@code{previous-matching-history-element}).
@kindex DOWN @r{(minibuffer history)}
@findex next-history-element
@findex previous-history-element
- While in the minibuffer, @kbd{M-p} or @key{Up}
-(@code{previous-history-element}) moves through the minibuffer history
-list, one item at a time. Each @kbd{M-p} fetches an earlier item from
-the history list into the minibuffer, replacing its existing contents.
-Typing @kbd{M-n} or @key{Down} (@code{next-history-element}) moves
-through the minibuffer history list in the opposite direction,
-fetching later entries into the minibuffer.
+ While in the minibuffer, @kbd{M-p} (@code{previous-history-element})
+moves through the minibuffer history list, one item at a time. Each
+@kbd{M-p} fetches an earlier item from the history list into the
+minibuffer, replacing its existing contents. Typing @kbd{M-n}
+(@code{next-history-element}) moves through the minibuffer history
+list in the opposite direction, fetching later entries into the
+minibuffer.
If you type @kbd{M-n} in the minibuffer when there are no later
entries in the minibuffer history (e.g., if you haven't previously
typed @kbd{M-p}), Emacs tries fetching from a list of default
arguments: values that you are likely to enter. You can think of this
-as moving through the ``future history'' list.
+as moving through the ``future history''.
+
+@findex previous-line-or-history-element
+@findex next-line-or-history-element
+ The arrow keys @kbd{@key{UP}} and @kbd{@key{DOWN}} work like
+@kbd{M-p} and @kbd{M-n}, but if the current history item is longer
+than a single line, they allow you to move to the previous or next
+line of the current history item before going to the previous or next
+history item.
- If you edit the text inserted by the @kbd{M-p} or @key{M-n}
+ If you edit the text inserted by the @kbd{M-p} or @kbd{M-n}
minibuffer history commands, this does not change its entry in the
history list. However, the edited argument does go at the end of the
history list when you submit it.
@var{n}th matching entry. These commands are unusual, in that they
use the minibuffer to read the regular expression argument, even
though they are invoked from the minibuffer. An upper-case letter in
-the regular expression makes the search case-sensitive (@pxref{Search
-Case}).
+the regular expression makes the search case-sensitive (@pxref{Lax
+Search}).
You can also search through the history using an incremental search.
@xref{Isearch Minibuffer}.
@node Yes or No Prompts
@section Yes or No Prompts
- An Emacs command may require you to answer a ``yes or no'' question
+ An Emacs command may require you to answer a yes-or-no question
during the course of its execution. Such queries come in two main
varieties.
@cindex y or n prompt
- For the first type of ``yes or no'' query, the prompt ends with
+ For the first type of yes-or-no query, the prompt ends with
@samp{(y or n)}. Such a query does not actually use the minibuffer;
the prompt appears in the echo area, and you answer by typing either
@samp{y} or @samp{n}, which immediately delivers the response. For
like this:
@smallexample
-File `foo.el' exists; overwrite? (y or n)
+File ‘foo.el’ exists; overwrite? (y or n)
@end smallexample
@noindent
(@pxref{Quitting}).
@cindex yes or no prompt
- The second type of ``yes or no'' query is typically employed if
+ The second type of yes-or-no query is typically employed if
giving the wrong answer would have serious consequences; it uses the
minibuffer, and features a prompt ending with @samp{(yes or no)}. For
example, if you invoke @kbd{C-x k} (@code{kill-buffer}) on a