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}
@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
(@pxref{Text Representations}) from whichever buffer was current before
entering the minibuffer.
-Completion ignores case when comparing the input against the possible
-matches, if the built-in variable @code{completion-ignore-case} is
-non-@code{nil}. @xref{Basic Completion}.
+If the built-in variable @code{completion-ignore-case} is
+non-@code{nil}, completion ignores case when comparing the input
+against the possible matches. @xref{Basic Completion}. In this mode
+of operation, @var{predicate} must also ignore case, or you will get
+surprising results.
Here's an example of using @code{completing-read}:
@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
HCoop / bpt / emacs.git / blobdiff