Most often, the minibuffer is used to read text as a string. It can
also be used to read a Lisp object in textual form. The most basic
primitive for minibuffer input is @code{read-from-minibuffer}; it can do
-either one.
+either one. There are also specialized commands for reading
+commands, variables, file names, etc. (@pxref{Completion}).
In most cases, you should not call minibuffer input functions in the
middle of a Lisp function. Instead, do all minibuffer input as part of
reading the arguments for a command, in the @code{interactive}
specification. @xref{Defining Commands}.
-@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method keep-all
This function is the most general way to get input through the
minibuffer. By default, it accepts arbitrary text and returns it as a
string; however, if @var{read} is non-@code{nil}, then it uses
Representations}) from whichever buffer was current before entering the
minibuffer.
+If @var{keep-all} is non-@code{nil}, even empty and duplicate inputs
+are added to the history list.
+
Use of @var{initial-contents} is mostly deprecated; we recommend using
a non-@code{nil} value only in conjunction with specifying a cons cell
for @var{hist}. @xref{Initial Input}.
@code{abort-recursive-edit}
@item @kbd{M-n}
+@itemx @key{DOWN}
@code{next-history-element}
@item @kbd{M-p}
+@itemx @key{UP}
@code{previous-history-element}
@item @kbd{M-s}
inputs. It's the Lisp programmer's job to specify the right history
list for each use of the minibuffer.
- The basic minibuffer input functions @code{read-from-minibuffer} and
-@code{completing-read} both accept an optional argument named @var{hist}
-which is how you specify the history list. Here are the possible
-values:
+ You specify the history list with the optional @var{hist} argument
+to either @code{read-from-minibuffer} or @code{completing-read}. Here
+are the possible values for it:
@table @asis
@item @var{variable}
@node Basic Completion
@subsection Basic Completion Functions
- The functions @code{try-completion}, @code{all-completions} and
-@code{test-completion} have nothing in themselves to do with
-minibuffers. We describe them in this chapter so as to keep them near
-the higher-level completion features that do use the minibuffer.
+ The completion functions @code{try-completion},
+@code{all-completions} and @code{test-completion} have nothing in
+themselves to do with minibuffers. We describe them in this chapter
+so as to keep them near the higher-level completion features that do
+use the minibuffer.
@defun try-completion string collection &optional predicate
This function returns the longest common substring of all possible
completions of @var{string} in @var{collection}. The value of
-@var{collection} must be a list of strings, an alist, an obarray, a
-hash table, or a function that implements a virtual set of strings
-(see below).
+@var{collection} must be a list of strings or symbols, an alist, an
+obarray, a hash table, or a function that implements a virtual set of
+strings (see below).
Completion compares @var{string} against each of the permissible
completions specified by @var{collection}; if the beginning of the
If @var{collection} is an alist (@pxref{Association Lists}), the
permissible completions are the elements of the alist that are either
-strings or conses whose @sc{car} is a string. Other elements of the
-alist are ignored. (Remember that in Emacs Lisp, the elements of
-alists do not @emph{have} to be conses.) As all elements of the alist
-can be strings, this case actually includes lists of strings, even
-though we usually do not think of such lists as alists.
+strings, symbols, or conses whose @sc{car} is a string or symbol.
+Symbols are converted to strings using @code{symbol-name}.
+Other elements of the alist are ignored. (Remember that in Emacs Lisp,
+the elements of alists do not @emph{have} to be conses.) As all
+elements of the alist can be strings, this case actually includes
+lists of strings or symbols, even though we usually do not think of
+such lists as alists.
@cindex obarray in completion
If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
Here are two examples of use:
-@example
+@smallexample
(defvar foo (lazy-completion-table foo make-my-alist 'global))
(make-local-variable 'bar)
(setq bar (lazy-completion-table foo make-my-alist 'local)
-@end example
+@end smallexample
@end defmac
@node Minibuffer Completion
If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
@code{completing-read} returns @code{barfoo}.
-The @code{completing-read} function binds three variables to pass
-information to the commands that actually do completion. These
-variables are @code{minibuffer-completion-table},
-@code{minibuffer-completion-predicate} and
-@code{minibuffer-completion-confirm}. For more information about them,
-see @ref{Completion Commands}.
+The @code{completing-read} function binds variables to pass
+information to the commands that actually do completion.
+They are described in the following section.
@end defun
@node Completion Commands
emacs, The GNU Emacs Manual}, for a short description of Partial
Completion mode.
-@defvar minibuffer-local-completion-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is not required. By default, this
-keymap makes the following bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}
-(@pxref{Definition of minibuffer-local-map}).
-@end defvar
-
-@defvar minibuffer-local-must-match-map
-@code{completing-read} uses this value as the local keymap when an
-exact match of one of the completions is required. Therefore, no keys
-are bound to @code{exit-minibuffer}, the command that exits the
-minibuffer unconditionally. By default, this keymap makes the following
-bindings:
-
-@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-
-@item @kbd{C-j}
-@code{minibuffer-complete-and-exit}
-
-@item @key{RET}
-@code{minibuffer-complete-and-exit}
-@end table
-
-@noindent
-with other characters bound as in @code{minibuffer-local-map}.
-@end defvar
-
@defvar minibuffer-completion-table
The value of this variable is the collection used for completion in
the minibuffer. This is the global variable that contains what
minibuffer completion functions.
@end defvar
+@defvar minibuffer-completion-confirm
+When the value of this variable is non-@code{nil}, Emacs asks for
+confirmation of a completion before exiting the minibuffer.
+@code{completing-read} binds this variable, and the function
+@code{minibuffer-complete-and-exit} checks the value before exiting.
+@end defvar
+
@deffn Command minibuffer-complete-word
This function completes the minibuffer contents by at most a single
word. Even if the minibuffer contents have only one completion,
when run twice in succession.
@end deffn
-@defvar minibuffer-completion-confirm
-When the value of this variable is non-@code{nil}, Emacs asks for
-confirmation of a completion before exiting the minibuffer. The
-function @code{minibuffer-complete-and-exit} checks the value of this
-variable before it exits.
-@end defvar
-
@deffn Command minibuffer-completion-help
This function creates a list of the possible completions of the
current minibuffer contents. It works by calling @code{all-completions}
can be completed because the next character is not uniquely determined.
@end defopt
+@defvar minibuffer-local-completion-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is not required. By default, this
+keymap makes the following bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}
+(@pxref{Definition of minibuffer-local-map}).
+@end defvar
+
+@defvar minibuffer-local-must-match-map
+@code{completing-read} uses this value as the local keymap when an
+exact match of one of the completions is required. Therefore, no keys
+are bound to @code{exit-minibuffer}, the command that exits the
+minibuffer unconditionally. By default, this keymap makes the following
+bindings:
+
+@table @asis
+@item @kbd{?}
+@code{minibuffer-completion-help}
+
+@item @key{SPC}
+@code{minibuffer-complete-word}
+
+@item @key{TAB}
+@code{minibuffer-complete}
+
+@item @kbd{C-j}
+@code{minibuffer-complete-and-exit}
+
+@item @key{RET}
+@code{minibuffer-complete-and-exit}
+@end table
+
+@noindent
+with other characters bound as in @code{minibuffer-local-map}.
+@end defvar
+
@node High-Level Completion
@subsection High-Level Completion Functions
as the string @code{"/gp/gnu/elisp/manual.texi"}.
@end defun
+@defvar read-file-name-function
+If non-@code{nil}, this should be a function that accepts the same
+arguments as @code{read-file-name}. When @code{read-file-name} is
+called, it calls this function with the supplied arguments instead of
+doing its usual work.
+@end defvar
+
+@defvar read-file-name-completion-ignore-case
+If this variable is non-@code{nil}, @code{read-file-name} ignores case
+when performing completion.
+@end defvar
+
@defun read-directory-name prompt &optional directory default existing initial
This function is like @code{read-file-name} but allows only directory
names as completion possibilities.
@code{read-directory-name} constructs a substitute default by
combining @var{directory} (or the current buffer's default directory
if @var{directory} is @code{nil}) and @var{initial}. If both
-@var{default} and @var{initial} are @code{nil}, this function uses the
-current buffer's default directory as substitute default, ignoring
-@var{directory}.
+@var{default} and @var{initial} are @code{nil}, this function uses
+@var{directory} as substitute default, or the current buffer's default
+directory if @var{directory} is @code{nil}.
@end defun
@defopt insert-default-directory
@defun minibuffer-prompt-end
@tindex minibuffer-prompt-end
-This function, available starting in Emacs 21, returns the current
+This function returns the current
position of the end of the minibuffer prompt, if a minibuffer is
current. Otherwise, it returns the minimum valid buffer position.
@end defun
@defun minibuffer-contents
@tindex minibuffer-contents
-This function, available starting in Emacs 21, returns the editable
+This function returns the editable
contents of the minibuffer (that is, everything except the prompt) as
a string, if a minibuffer is current. Otherwise, it returns the
entire contents of the current buffer.
@defun delete-minibuffer-contents
@tindex delete-minibuffer-contents
-This function, available starting in Emacs 21, erases the editable
+This function erases the editable
contents of the minibuffer (that is, everything except the prompt), if
a minibuffer is current. Otherwise, it erases the entire buffer.
@end defun