@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, 2002,
-@c 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
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 keep-all
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
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}.
@end defvar
@defvar minibuffer-local-map
+This
@anchor{Definition of minibuffer-local-map}
-This is the default local keymap for reading from the minibuffer. By
+@c avoid page break at anchor; work around Texinfo deficiency
+is the default local keymap for reading from the minibuffer. By
default, it makes the following bindings:
@table @asis
history list symbol. The variable @code{history-delete-duplicates}
specifies whether to delete duplicates in history.
+@defun add-to-history history-var newelt &optional maxelt keep-all
+This function adds a new element @var{newelt}, if it isn't the empty
+string, to the history list stored in the variable @var{history-var},
+and returns the updated history list. It limits the list length to
+the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
+(described below). The possible values of @var{maxelt} have the same
+meaning as the values of @code{history-length}.
+
+Normally, @code{add-to-history} removes duplicate members from the
+history list if @code{history-delete-duplicates} is non-@code{nil}.
+However, if @var{keep-all} is non-@code{nil}, that says not to remove
+duplicates, and to add @var{newelt} to the list even if it is empty.
+@end defun
+
+@defvar history-add-new-input
+If the value of this variable is @code{nil}, standard functions that
+read from the minibuffer don't add new elements to the history list.
+This lets Lisp programs explicitly manage input history by using
+@code{add-to-history}. By default, @code{history-add-new-input} is
+set to a non-@code{nil} value.
+@end defvar
+
@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).
+elements). The value of @code{history-length} property of the history
+list variable's symbol, if set, overrides this variable for that
+particular history list.
@end defvar
@defvar history-delete-duplicates
Several of the functions for minibuffer input have an argument called
@var{initial} or @var{initial-contents}. This is a mostly-deprecated
-feature for specifiying that the minibuffer should start out with
+feature for specifying that the minibuffer should start out with
certain text, instead of empty as usual.
If @var{initial} is a string, the minibuffer starts out containing the
so as to keep them near the higher-level completion features that do
use the minibuffer.
+ If you store a completion alist in a variable, you should mark the
+variable as ``risky'' with a non-@code{nil}
+@code{risky-local-variable} property.
+
@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
If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
returns @code{fill-prefix}.
-This function is similar to @code{read-command}, but uses the
-predicate @code{user-variable-p} instead of @code{commandp}:
+In general, @code{read-variable} is similar to @code{read-command},
+but uses the predicate @code{user-variable-p} instead of
+@code{commandp}:
@cindex @code{user-variable-p} example
@example
@end defun
See also the functions @code{read-coding-system} and
-@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems}.
+@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
+and @code{read-input-method-name}, in @ref{Input Methods}.
@node Reading File Names
@subsection Reading File Names
@var{existing} is @code{nil}, then the name of a nonexistent file is
acceptable.
-The function @code{read-file-name} uses
+@code{read-file-name} uses
@code{minibuffer-local-filename-completion-map} as the keymap if
@var{existing} is @code{nil}, and uses
@code{minibuffer-local-must-match-filename-map} if @var{existing} is
This function asks the user a question, expecting input in the echo
area. It returns @code{t} if the user types @kbd{y}, @code{nil} if the
user types @kbd{n}. This function also accepts @key{SPC} to mean yes
-and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit'', like
+and @key{DEL} to mean no. It accepts @kbd{C-]} to mean ``quit,'' like
@kbd{C-g}, because the question might look like a minibuffer and for
that reason the user might try to use @kbd{C-]} to get out. The answer
is a single character, with no @key{RET} needed to terminate it. Upper
When the user responds with @var{char}, @code{map-y-or-n-p} calls
@var{function}. If it returns non-@code{nil}, the object is considered
-``acted upon'', and @code{map-y-or-n-p} advances to the next object in
+``acted upon,'' and @code{map-y-or-n-p} advances to the next object in
@var{list}. If it returns @code{nil}, the prompt is repeated for the
same object.
@end defun
@defun minibuffer-prompt-end
-@tindex minibuffer-prompt-end
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 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
@end defun
@defun minibuffer-contents-no-properties
-@tindex minibuffer-contents-no-properties
This is like @code{minibuffer-contents}, except that it does not copy text
properties, just the characters themselves. @xref{Text Properties}.
@end defun
@defun minibuffer-completion-contents
-@tindex minibuffer-completion-contents
This is like @code{minibuffer-contents}, except that it returns only
the contents before point. That is the part that completion commands
operate on. @xref{Minibuffer Completion}.
@end defun
@defun delete-minibuffer-contents
-@tindex delete-minibuffer-contents
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 current buffer.