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}:
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.
To read a password to pass to another program, you can use the
function @code{read-passwd}.
-@cindex password cache
- Passwords are sometimes needed several times throughout an Emacs
-session. Then it can be useful to avoid having to ask for a password
-more than once. Passwords are entered into the password cache using
-the function @code{password-cache-add}. To read a password, possibly
-retrieving the password from the cache without querying the user, you
-can use the function @code{password-read}. The two calls can be
-combined into the function @code{password-read-and-add} that read a
-password and store it in the cache.
-
- Typically users do not use the same password for all services. The
-password cache mechanism use a @samp{key} string to differentiate
-among the passwords. The @samp{key} string is typically a fixed
-string chosen to be related to what the password is used for. For
-example, a password used when connecting to a @acronym{IMAP} mail
-server called @samp{mail.example.org}, could use a @samp{key} string
-of @samp{imap:mail.example.org}. You can use any string, as long as
-it is reasonably unique.
-
-@cindex password expiry
-Passwords in the cache typically expire after a while (controlled by
-the variable @code{password-cache-expiry}), but you can force removal
-of a password using the function @code{password-cache-remove}. This
-is useful when there is a problem with the password, to avoid using
-the same incorrect password from the cache in the future.
-
@defun read-passwd prompt &optional confirm default
This function reads a password, prompting with @var{prompt}. It does
not echo the password as the user types it; instead, it echoes @samp{.}
then @code{read-passwd} returns the null string in that case.
@end defun
-@defun password-read prompt key
-Read a password from the user, using @code{read-passwd}, prompting
-with @var{prompt}. If a password has been stored in the password
-cache, using @code{password-cache-add} on the same @var{key}, it is
-returned directly, without querying the user.
-@end defun
-
-@defun password-cache-add key password
-Add a password to the password cache, indexed under the given
-@var{key}. The password is later retrieved using @code{password-read}
-called with the same @var{key}.
-@end defun
-
-@defun password-cache-remove key
-Remove a password from the cache, indexed under the given @var{key}.
-@end defun
-
-@defun password-read-and-add prompt &optional key
-Read a password, prompting with @var{prompt}, and possibly add it to
-the cache, indexed using the @var{key} string. This is one-call
-interface to @code{password-read} and @code{password-cache-add}.
-@end defun
-
-@defvar password-cache-expiry
-This variable specify for how many seconds passwords are retained in
-the password cache before they are expired. For high security, use a
-low value (below a minute). For more lax security, use a setting of
-@samp{14400} corresponding to half a work day (4 hours).
-@end defvar
-
-@defvar password-cache
-This variable toggle whether or not the password cache is used at all.
-The default is non-@code{nil}, i.e., to use the cache.
-@end defvar
-
@node Minibuffer Misc
@section Minibuffer Miscellany
@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