@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
-@c 2001, 2004
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002,
+@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
@code{enable-recursive-minibuffers} or by putting properties of that
name on command symbols (@pxref{Recursive Mini}).
- Like other buffers, a minibuffer may use any of several local keymaps
-(@pxref{Keymaps}); these contain various exit commands and in some cases
-completion commands (@pxref{Completion}).
-
-@itemize @bullet
-@item
-@code{minibuffer-local-map} is for ordinary input (no completion).
-
-@item
-@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
-just like @key{RET}.
-
-@item
-@code{minibuffer-local-completion-map} is for permissive completion.
-
-@item
-@code{minibuffer-local-must-match-map} is for strict completion and
-for cautious completion.
-@end itemize
+ Like other buffers, a minibuffer uses a local keymap
+(@pxref{Keymaps}) to specify special key bindings. The function that
+invokes the minibuffer also sets up its local map according to the job
+to be done. @xref{Text from Minibuffer}, for the non-completion
+minibuffer local maps. @xref{Completion Commands}, for the minibuffer
+local maps for completion.
When Emacs is running in batch mode, any request to read from the
minibuffer actually reads a line from the standard input descriptor that
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}.
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-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
bound to the value of @code{completion-ignore-case}.
@end defvar
-@defmac lazy-completion-table var fun &rest args
+@defmac lazy-completion-table var fun
This macro provides a way to initialize the variable @var{var} as a
collection for completion in a lazy way, not computing its actual
contents until they are first needed. You use this macro to produce a
value that you store in @var{var}. The actual computation of the
proper value is done the first time you do completion using @var{var}.
-It is done by calling @var{fun} with the arguments @var{args}. The
+It is done by calling @var{fun} with no arguments. The
value @var{fun} returns becomes the permanent value of @var{var}.
-Here are two examples of use:
+Here is an example of use:
@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)
+(defvar foo (lazy-completion-table foo make-my-alist))
@end smallexample
@end defmac
@samp{*Completions*}.
@end deffn
-@defun display-completion-list completions
+@defun display-completion-list completions &optional common-substring
This function displays @var{completions} to the stream in
@code{standard-output}, usually a buffer. (@xref{Read and Print}, for more
information about streams.) The argument @var{completions} is normally
the two strings is the actual completion, the second string serves as
annotation.
+The argument @var{common-substring} is the prefix that is common to
+all the completions. With normal Emacs completion, it is usually the
+same as the string that was completed. @code{display-completion-list}
+uses this to highlight text in the completion list for better visual
+feedback. This is not needed in the minibuffer; for minibuffer
+completion, you can pass @code{nil}.
+
This function is called by @code{minibuffer-completion-help}. The
most common way to use it is together with
@code{with-output-to-temp-buffer}, like this:
@example
(with-output-to-temp-buffer "*Completions*"
(display-completion-list
- (all-completions (buffer-string) my-alist)))
+ (all-completions (buffer-string) my-alist)
+ (buffer-string)))
@end example
@end defun
with other characters bound as in @code{minibuffer-local-map}.
@end defvar
+@defvar minibuffer-local-filename-completion-map
+This is like @code{minibuffer-local-completion-map}
+except that it does not bind @key{SPC}. This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
+@defvar minibuffer-local-must-match-filename-map
+This is like @code{minibuffer-local-must-match-map}
+except that it does not bind @key{SPC}. This keymap is used by the
+function @code{read-file-name}.
+@end defvar
+
@node High-Level Completion
@subsection High-Level Completion Functions
it should be a string or a buffer. It is mentioned in the prompt, but
is not inserted in the minibuffer as initial input.
+The argument @var{prompt} should be a string ending with a colon and a
+space. If @var{default} is non-@code{nil}, the function inserts it in
+@var{prompt} before the colon to follow the convention for reading from
+the minibuffer with a default value (@pxref{Programming Tips}).
+
If @var{existing} is non-@code{nil}, then the name specified must be
that of an existing buffer. The usual commands to exit the minibuffer
do not exit if the text is not valid, and @key{RET} does completion to
@samp{minibuffer.texi}, so that name is the value.
@example
-(read-buffer "Buffer name? " "foo" t)
+(read-buffer "Buffer name: " "foo" t)
@group
;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,}
@group
---------- Buffer: Minibuffer ----------
-Buffer name? (default foo) @point{}
+Buffer name (default foo): @point{}
---------- Buffer: Minibuffer ----------
@end group
@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{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
+non-@code{nil}. @xref{Completion Commands}.
+
The argument @var{directory} specifies the directory to use for
completion of relative file names. It should be an absolute directory
name. If @code{insert-default-directory} is non-@code{nil},
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,