@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+@c 2001, 2004
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/minibuf
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}.
properties unconditionally, regardless of the value of this variable.
@end defvar
-@anchor{Definition of minibuffer-local-map}
@defvar minibuffer-local-map
+@anchor{Definition of minibuffer-local-map}
This is the default local keymap for reading from the minibuffer. By
default, it makes the following bindings:
@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}
@code{history-length} specifies the maximum length for most history
lists. To specify a different maximum length for a particular history
list, put the length in the @code{history-length} property of the
-history list symbol.
+history list symbol. The variable @code{history-delete-duplicates}
+specifies whether to delete duplicates in history.
@defvar history-length
The value of this variable specifies the maximum length for all
history lists that don't specify their own maximum lengths. If the
value is @code{t}, that means there no maximum (don't delete old
elements).
+@end defvar
+
+@defvar history-delete-duplicates
+If the value of this variable is @code{t}, that means when adding a
+new history element, all previous identical elements are deleted.
@end defvar
Here are some of the standard minibuffer history list variables:
Use of a cons cell as the value for @var{initial} arguments is
deprecated in user code.
-
+
@node Completion
@section Completion
@cindex completion
@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
@end smallexample
@end defun
-@anchor{Definition of test-completion}
@defun test-completion string collection &optional predicate
+@anchor{Definition of test-completion}
This function returns non-@code{nil} if @var{string} is a valid
completion possibility specified by @var{collection} and
@var{predicate}. The arguments are the same as in
(@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}:
@end defun
@defun read-variable prompt &optional default
+@anchor{Definition of read-variable}
This function reads the name of a user variable and returns it as a
symbol.
@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
@end defvar
@defvar minibuffer-help-form
+@anchor{Definition of minibuffer-help-form}
The current value of this variable is used to rebind @code{help-form}
locally inside the minibuffer (@pxref{Help Functions}).
@end defvar
@end defun
@defun minibuffer-window &optional frame
+@anchor{Definition of minibuffer-window}
This function returns the minibuffer window used for frame @var{frame}.
If @var{frame} is @code{nil}, that stands for the current frame. Note
that the minibuffer window used by a frame need not be part of that
@end defun
@defvar minibuffer-scroll-window
+@anchor{Definition of minibuffer-scroll-window}
If the value of this variable is non-@code{nil}, it should be a window
object. When the function @code{scroll-other-window} is called in the
minibuffer, it scrolls this window.
HCoop / bpt / emacs.git / blobdiff