@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 Free Software Foundation, Inc.
+@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
@emph{within} a buffer, such as editing commands, work normally in a
minibuffer. However, many operations for managing buffers do not apply
to minibuffers. The name of a minibuffer always has the form @w{@samp{
-*Minibuf-@var{number}}}, and it cannot be changed. Minibuffers are
+*Minibuf-@var{number}*}}, and it cannot be changed. Minibuffers are
displayed only in special windows used only for minibuffers; these
windows always appear at the bottom of a frame. (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
just a minibuffer, you can change the minibuffer's size by changing the
frame's size.
+ Use of the minibuffer reads input events, and that alters the values
+of variables such as @code{this-command} and @code{last-command}
+(@pxref{Command Loop Info}). Your program should bind them around the
+code that uses the minibuffer, if you do not want that to change them.
+
If a command uses a minibuffer while there is an active minibuffer,
this is called a @dfn{recursive minibuffer}. The first minibuffer is
named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
@item
@code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
-just like @key{RET}. This is used mainly for Mocklisp compatibility.
+just like @key{RET}.
@item
@code{minibuffer-local-completion-map} is for permissive completion.
@code{read-from-minibuffer}. The keymap used is
@code{minibuffer-local-map}.
-The optional argument @var{history}, if non-nil, specifies a history
-list and optionally the initial position in the list. The optional
-argument @var{default} specifies a default value to return if the user
-enters null input; it should be a string. The optional argument
-@var{inherit-input-method} specifies whether to inherit the current
-buffer's input method.
+The optional argument @var{history}, if non-@code{nil}, specifies a
+history list and optionally the initial position in the list. The
+optional argument @var{default} specifies a default value to return if
+the user enters null input; it should be a string. The optional
+argument @var{inherit-input-method} specifies whether to inherit the
+current buffer's input method.
This function is a simplified interface to the
@code{read-from-minibuffer} function:
@group
(edit-and-eval-command "Please edit: " '(forward-word 1))
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
@end group
name to the input functions when you wish. But it is safe to modify the
list by hand when the minibuffer input functions are not using it.
+ Emacs functions that add a new element to a history list can also
+delete old elements if the list gets too long. The variable
+@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.
+
+@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
+
Here are some of the standard minibuffer history list variables:
@defvar minibuffer-history
* High-Level Completion:: Convenient special cases of completion
(reading buffer name, file name, etc.)
* Reading File Names:: Using completion to read file names.
-* Programmed Completion:: Finding the completions for a given file name.
+* Programmed Completion:: Writing your own completion-function.
@end menu
@node Basic Completion
@subsection Basic Completion Functions
- The two functions @code{try-completion} and @code{all-completions}
-have nothing in themselves to do with minibuffers. We describe them in
-this chapter so as to keep them near the higher-level completion
-features that do use the minibuffer.
+ The functions @code{try-completion}, @code{all-completions} and
+@code{test-completion} have nothing in themselves to do with
+minibuffers. We describe them in this chapter so as to keep them near
+the higher-level completion features that do use the minibuffer.
@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 an alist, an obarray, or a function that
-implements a virtual set of strings (see below).
+@var{collection} must be a list of strings, an alist, an obarray, 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
empty and then add symbols to it one by one using @code{intern}.
Also, you cannot intern a given symbol in more than one obarray.
-If the argument @var{predicate} is non-@code{nil}, then it must be a
-function of one argument. It is used to test each possible match, and
-the match is accepted only if @var{predicate} returns non-@code{nil}.
-The argument given to @var{predicate} is either a cons cell from the alist
-(the @sc{car} of which is a string) or else it is a symbol (@emph{not} a
-symbol name) from the obarray.
-
You can also use a symbol that is a function as @var{collection}. Then
the function is solely responsible for performing completion;
@code{try-completion} returns whatever this function returns. The
function can be used in @code{all-completions} and do the appropriate
thing in either case.) @xref{Programmed Completion}.
+If the argument @var{predicate} is non-@code{nil}, then it must be a
+function of one argument. It is used to test each possible match, and
+the match is accepted only if @var{predicate} returns non-@code{nil}.
+The argument given to @var{predicate} is either a string from the
+list, a cons cell from the alist (the @sc{car} of which is a string)
+or a symbol (@emph{not} a symbol name) from the obarray.
+
In the first of the following examples, the string @samp{foo} is
matched by three of the alist @sc{car}s. All of the matches begin with
the characters @samp{fooba}, so that is the result. In the second
@smallexample
@group
-(try-completion
+(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
@result{} "fooba"
@smallexample
@group
-(defun test (s)
+(defun test (s)
(> (length (car s)) 6))
@result{} test
@end group
@group
-(try-completion
+(try-completion
"foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
@result{} "foobar"
@end group
@smallexample
@group
-(defun test (s)
+(defun test (s)
(> (length (car s)) 6))
@result{} test
@end group
@group
-(all-completions
+(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
@end smallexample
@end defun
+@defun test-completion string collection &optional predicate
+This function returns non-@code{nil} if @var{string} is a valid
+completion possibility specified by @var{collection} and
+@var{predicate}. The other arguments are the same as in
+@code{try-completion}. For instance, if @var{collection} is a list,
+this is true if @var{string} appears in the list and @var{predicate}
+is satisfied.
+
+If @var{collection} is a function, it is called with three arguments,
+the values @var{string}, @var{predicate} and @code{lambda}; whatever
+it returns, @code{test-completion} returns in turn.
+@end defun
+
@defvar completion-ignore-case
-If the value of this variable is
-non-@code{nil}, Emacs does not consider case significant in completion.
+If the value of this variable is non-@code{nil}, Emacs does not
+consider case significant in completion.
@end defvar
+@defmac lazy-completion-table var fun &rest args
+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
+value @var{fun} returns becomes the permanent value of @var{var}.
+
+Here are two examples of use:
+
+@example
+(defvar foo (lazy-completion-table foo make-my-alist 'global))
+
+(make-local-variable 'bar)
+(setq bar (lazy-completion-table foo make-my-alist 'local)
+@end example
+@end defmac
+
@node Minibuffer Completion
@subsection Completion and the Minibuffer
@end group
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
---------- Buffer: Minibuffer ----------
@example
(read-buffer "Buffer name? " "foo" t)
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
(read-command "Command name? ")
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears with an empty minibuffer:}
@end group
@group
----------- Buffer: Minibuffer ----------
-Command name?
+---------- Buffer: Minibuffer ----------
+Command name?
---------- Buffer: Minibuffer ----------
@end group
@end example
@group
(read-command @var{prompt})
@equiv{}
-(intern (completing-read @var{prompt} obarray
+(intern (completing-read @var{prompt} obarray
'commandp t nil))
@end group
@end example
@group
(read-variable "Variable name? ")
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
+;; @r{After evaluation of the preceding expression,}
+;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
file name. It provides special features including automatic insertion
of the default directory.
-@defun read-file-name prompt &optional directory default existing initial
+@defun read-file-name prompt &optional directory default existing initial predicate
This function reads a file name in the minibuffer, prompting with
@var{prompt} and providing completion. If @var{default} is
non-@code{nil}, then the function returns @var{default} if the user just
@var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we
recommend using @var{default} rather than @var{initial} in most cases.
-Here is an example:
+If @var{predicate} is non-@code{nil}, it specifies a function of one
+argument that decides which file names are acceptable completion
+possibilities. A file name is an acceptable value if @var{predicate}
+returns non-@code{nil} for it.
+
+Here is an example:
@example
@group
(read-file-name "The file is ")
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
@end group
as the string @code{"/gp/gnu/elisp/manual.texi"}.
@end defun
+@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.
+@end defun
+
@defopt insert-default-directory
This variable is used by @code{read-file-name}. Its value controls
whether @code{read-file-name} starts by placing the name of the default
string.
@item
-@code{lambda} specifies a test for an exact match. The completion
+@code{lambda} specifies @code{test-completion}. The completion
function should return @code{t} if the specified string is an exact
match for some possibility; @code{nil} otherwise.
@end itemize
It would be consistent and clean for completion functions to allow
lambda expressions (lists that are functions) as well as function
symbols as @var{collection}, but this is impossible. Lists as
-completion tables are already assigned another meaning---as alists. It
-would be unreliable to fail to handle an alist normally because it is
-also a possible function. So you must arrange for any function you wish
-to use for completion to be encapsulated in a symbol.
+completion tables already have other meanings, and it would be
+unreliable to treat one differently just because it is also a possible
+function. So you must arrange for any function you wish to use for
+completion to be encapsulated in a symbol.
Emacs uses programmed completion when completing file names.
@xref{File Name Completion}.
+@defmac dynamic-completion-table function
+This macro is a convenient way to write a function that can act as
+programmed completion function. The argument @var{function} should be
+a function that takes one argument, a string, and returns an alist of
+possible completions of it. You can think of
+@code{dynamic-completion-table} as a transducer between that interface
+and the interface for programmed completion functions.
+@end defmac
+
@node Yes-or-No Queries
@section Yes-or-No Queries
@cindex asking the user questions
@group
(y-or-n-p "Do you need a lift? ")
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears in the echo area:}
@end group
@group
---------- Echo area ----------
-Do you need a lift? (y or n)
+Do you need a lift? (y or n)
---------- Echo area ----------
@end group
@group
---------- Echo area ----------
-Please answer y or n. Do you need a lift? (y or n)
+Please answer y or n. Do you need a lift? (y or n)
---------- Echo area ----------
@end group
@group
(yes-or-no-p "Do you really want to remove everything? ")
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
+;; @r{After evaluation of the preceding expression,}
+;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
@group
---------- Buffer: minibuffer ----------
-Do you really want to remove everything? (yes or no)
+Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
@end group
@end smallexample
locally inside the minibuffer (@pxref{Help Functions}).
@end defvar
+@defun minibufferp &optional buffer
+This function returns non-@code{nil} if @var{buffer} is a minibuffer.
+If @var{buffer} is omitted, it tests the current buffer.
+@end defun
+
@defun active-minibuffer-window
This function returns the currently active minibuffer window, or
@code{nil} if none is currently active.
minibuffer, it scrolls this window.
@end defvar
+@defun minibuffer-selected-window
+This function returns the window which was selected when the
+minibuffer was entered. If selected window is not a minibuffer
+window, it returns @code{nil}.
+@end defun
+
Finally, some functions and variables deal with recursive minibuffers
(@pxref{Recursive Editing}):
arguments even if it is invoked from the minibuffer. The minibuffer
command @code{next-matching-history-element} (normally @kbd{M-s} in the
minibuffer) uses this feature.
+
+@defun minibuffer-message string &optional timeout
+This function displays @var{string} temporarily at the end of the
+minibuffer text, for @var{timeout} seconds. (The default is 2
+seconds.)
+@end defun
+
+@ignore
+ arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
+@end ignore