@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
@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
+@node Minibuffers
@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
* Multiple Queries:: Asking a series of similar questions.
* Reading a Password:: Reading a password from the terminal.
* Minibuffer Commands:: Commands used as key bindings in minibuffers.
-* Minibuffer Contents:: How such commands access the minibuffer text.
* Minibuffer Windows:: Operating on the special minibuffer windows.
+* Minibuffer Contents:: How such commands access the minibuffer text.
* Recursive Mini:: Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc:: Various customization hooks and variables.
@end menu
@code{forward-sentence}, and @code{forward-paragraph}, stop at the
boundary between the prompt and the actual text.
+@c See http://debbugs.gnu.org/11276
The minibuffer's window is normally a single line; it grows
-automatically if the contents require more space. You can explicitly
-resize it temporarily with the window sizing commands; it reverts to
-its normal size when the minibuffer is exited. You can resize it
+automatically if the contents require more space. Whilst it is
+active, you can explicitly resize it temporarily with the window
+sizing commands; it reverts to its normal size when the minibuffer is
+exited. When the minibuffer is not active, you can resize it
permanently by using the window sizing commands in the frame's other
-window, when the minibuffer is not active. If the frame contains just
-a minibuffer, you can change the minibuffer's size by changing the
-frame's size.
+window, or dragging the mode line with the mouse. (Due to details of
+the current implementation, for this to work @code{resize-mini-windows}
+must be @code{nil}.) If the 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}
code that uses the minibuffer, if you do not want that to change them.
Under some circumstances, a command can use a minibuffer even if
-there is an active minibuffer; such minibuffers are called a
+there is an active minibuffer; such a minibuffer is called a
@dfn{recursive minibuffer}. The first minibuffer is named
-@w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
+@w{@samp{ *Minibuf-1*}}. Recursive minibuffers are named by
incrementing the number at the end of the name. (The names begin with
a space so that they won't show up in normal buffer lists.) Of
several recursive minibuffers, the innermost (or most recently
minibuffer local maps. @xref{Completion Commands}, for the minibuffer
local maps for completion.
+@cindex inactive minibuffer
+ When a minibuffer is inactive, its major mode is
+@code{minibuffer-inactive-mode}, with keymap
+@code{minibuffer-inactive-mode-map}. This is only really useful if
+the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
+
When Emacs is running in batch mode, any request to read from the
minibuffer actually reads a line from the standard input descriptor that
was supplied when Emacs was started.
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 &optional initial keymap read history default inherit-input-method
This function is the most general way to get input from 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
Functions}).
The first thing this function does is to activate a minibuffer and
-display it with @var{prompt-string} as the prompt. This value must be a
-string. Then the user can edit text in the minibuffer.
+display it with @var{prompt} (which must be a string) as the
+prompt. Then the user can edit text in the minibuffer.
When the user types a command to exit the minibuffer,
@code{read-from-minibuffer} constructs the return value from the text in
The argument @var{default} specifies default values to make available
through the history commands. It should be a string, a list of
strings, or @code{nil}. The string or strings become the minibuffer's
-``future history,'' available to the user with @kbd{M-n}.
+``future history'', available to the user with @kbd{M-n}.
If @var{read} is non-@code{nil}, then @var{default} is also used
as the input to @code{read}, if the user enters empty input.
a keymap is the most important way to customize the minibuffer for
various applications such as completion.
-The argument @var{hist} specifies which history list variable to use
+The argument @var{history} specifies a history list variable to use
for saving the input and for history commands used in the minibuffer.
-It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
+It defaults to @code{minibuffer-history}. You can optionally specify
+a starting position in the history list as well. @xref{Minibuffer History}.
If the variable @code{minibuffer-allow-text-properties} is
-non-@code{nil}, then the string which is returned includes whatever text
+non-@code{nil}, then the string that is returned includes whatever text
properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
Representations}) from whichever buffer was current before entering the
minibuffer.
-Use of @var{initial-contents} is mostly deprecated; we recommend using
+Use of @var{initial} 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}.
+for @var{history}. @xref{Initial Input}.
@end defun
@defun read-string prompt &optional initial history default inherit-input-method
@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
specifies a default value to return if the user enters null input. As
in @code{read-from-minibuffer} it should be a string, a list of
-strings, or @code{nil} which is equivalent to an empty string. When
+strings, or @code{nil}, which is equivalent to an empty string. When
@var{default} is a string, that string is the default value. When it
is a list of strings, the first string is the default value. (All
these strings are available to the user in the ``future minibuffer
-history.'')
+history''.)
This function works by calling the
@code{read-from-minibuffer} function:
@end smallexample
@end defun
-@defun read-regexp prompt &optional default-value
+@defun read-regexp prompt &optional default history
This function reads a regular expression as a string from the
minibuffer and returns it. The argument @var{prompt} is used as in
-@code{read-from-minibuffer}. The keymap used is
-@code{minibuffer-local-map}, and @code{regexp-history} is used as the
-history list (@pxref{Minibuffer History, regexp-history}).
+@code{read-from-minibuffer}.
-The optional argument @var{default-value} specifies a default value to
+The optional argument @var{default} specifies a default value to
return if the user enters null input; it should be a string, or
-@code{nil} which is equivalent to an empty string.
+@code{nil}, which is equivalent to an empty string.
-In addition, @code{read-regexp} collects a few useful candidates for
-input and passes them to @code{read-from-minibuffer}, to make them
-available to the user as the ``future minibuffer history list''
-(@pxref{Minibuffer History, future list,, emacs, The GNU Emacs
-Manual}). These candidates are:
+The optional argument @var{history}, if non-@code{nil}, is a symbol
+specifying a minibuffer history list to use (@pxref{Minibuffer
+History}). If it is omitted or @code{nil}, the history list defaults
+to @code{regexp-history}.
+
+@code{read-regexp} also collects a few useful candidates for input and
+passes them to @code{read-from-minibuffer}, to make them available to
+the user as the ``future minibuffer history list'' (@pxref{Minibuffer
+History, future list,, emacs, The GNU Emacs Manual}). These
+candidates are:
@itemize @minus
@item
@end defun
@defvar minibuffer-allow-text-properties
-If this variable is @code{nil}, then @code{read-from-minibuffer} strips
-all text properties from the minibuffer input before returning it.
-This variable also affects @code{read-string}. However,
+If this variable is @code{nil}, then @code{read-from-minibuffer}
+and @code{read-string} strip all text properties from the minibuffer
+input before returning it. However,
@code{read-no-blanks-input} (see below), as well as
@code{read-minibuffer} and related functions (@pxref{Object from
Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
@item @kbd{M-r}
@code{previous-matching-history-element}
+
+@ignore
+@c Does not seem worth/appropriate mentioning.
+@item @kbd{C-@key{TAB}}
+@code{file-cache-minibuffer-complete}
+@end ignore
@end table
@end defvar
@end smallexample
@end defun
+@c Slightly unfortunate name, suggesting it might be related to the
+@c Nextstep port...
@defvar minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local keymap
in the function @code{read-no-blanks-input}. By default, it makes the
@end defun
@defun edit-and-eval-command prompt form
-This function reads a Lisp expression in the minibuffer, and then
-evaluates it. The difference between this command and
+This function reads a Lisp expression in the minibuffer, evaluates it,
+then returns the result. The difference between this command and
@code{eval-minibuffer} is that here the initial @var{form} is not
optional and it is treated as a Lisp object to be converted to printed
representation rather than as a string of text. It is printed with
@code{prin1}, so if it is a string, double-quote characters (@samp{"})
appear in the initial text. @xref{Output Functions}.
-The first thing @code{edit-and-eval-command} does is to activate the
-minibuffer with @var{prompt} as the prompt. Then it inserts the printed
-representation of @var{form} in the minibuffer, and lets the user edit it.
-When the user exits the minibuffer, the edited text is read with
-@code{read} and then evaluated. The resulting value becomes the value
-of @code{edit-and-eval-command}.
-
In the following example, we offer the user an expression with initial
-text which is a valid form already:
+text that is already a valid form:
@smallexample
@group
@noindent
Typing @key{RET} right away would exit the minibuffer and evaluate the
expression, thus moving point forward one word.
-@code{edit-and-eval-command} returns @code{nil} in this example.
@end defun
@node Minibuffer History
kinds of inputs. It's the Lisp programmer's job to specify the right
history list for each use of the minibuffer.
- You specify a minibuffer history list with the optional @var{hist}
+ You specify a minibuffer history list with the optional @var{history}
argument to @code{read-from-minibuffer} or @code{completing-read}.
Here are the possible values for it:
symbol @var{variable}. @code{previous-history-element} will display
the most recent element of the history list in the minibuffer. If you
specify a positive @var{startpos}, the minibuffer history functions
-behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
+behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
history element currently shown in the minibuffer.
For consistency, you should also specify that element of the history
to the minibuffer input function (@pxref{Initial Input}).
@end table
- If you don't specify @var{hist}, then the default history list
+ If you don't specify @var{history}, then the default history list
@code{minibuffer-history} is used. For other standard history lists,
see below. You can also create your own history list variable; just
initialize it to @code{nil} before the first use.
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.
+@code{add-to-history}. The default value is @code{t}.
@end defvar
@defopt 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 is no maximum (don't delete old
-elements). The value of @code{history-length} property of the history
-list variable's symbol, if set, overrides this variable for that
+elements). If a history list variable's symbol has a non-@code{nil}
+@code{history-length} property, it overrides this variable for that
particular history list.
@end defopt
A history list for arguments that are Lisp expressions to evaluate.
@end defvar
+@defvar face-name-history
+A history list for arguments that are faces.
+@end defvar
+
+@c Less common: coding-system-history, input-method-history,
+@c command-history, grep-history, grep-find-history,
+@c read-envvar-name-history, setenv-history, yes-or-no-p-history.
+
@node Initial Input
@section Initial Input
Several of the functions for minibuffer input have an argument called
-@var{initial} or @var{initial-contents}. This is a mostly-deprecated
+@var{initial}. This is a mostly-deprecated
feature for specifying that the minibuffer should start out with
certain text, instead of empty as usual.
There is just one situation where you should specify a string for an
@var{initial} argument. This is when you specify a cons cell for the
-@var{hist} or @var{history} argument. @xref{Minibuffer History}.
+@var{history} argument. @xref{Minibuffer History}.
@var{initial} can also be a cons cell of the form @code{(@var{string}
. @var{position})}. This means to insert @var{string} in the
of 0 means the beginning of the string, 1 means after the first
character, etc. In @code{read-minibuffer}, and the other
non-completion minibuffer input functions that support this argument,
-1 means the beginning of the string 2 means after the first character,
+1 means the beginning of the string, 2 means after the first character,
etc.
-Use of a cons cell as the value for @var{initial} arguments is
-deprecated in user code.
+Use of a cons cell as the value for @var{initial} arguments is deprecated.
@node Completion
@section Completion
user's input against a list of valid names and determining how much of
the name is determined uniquely by what the user has typed. For
example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
+@c "This is the sort of English up with which I will not put."
type the first few letters of the name of the buffer to which you wish
to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
extends the name as far as it can.
* Minibuffer Completion:: Invoking the minibuffer with completion.
* Completion Commands:: Minibuffer commands that do completion.
* High-Level Completion:: Convenient special cases of completion
- (reading buffer name, file name, etc.).
+ (reading buffer names, variable names, etc.).
* Reading File Names:: Using completion to read file names and
shell commands.
-* Completion Styles:: Specifying rules for performing completion.
-* Programmed Completion:: Writing your own completion-function.
+* Completion Variables:: Variables controlling completion behavior.
+* Programmed Completion:: Writing your own completion function.
+* Completion in Buffers:: Completing text in ordinary buffers.
@end menu
@node Basic 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 whose keys are
-strings or symbols, an obarray, a hash table, or a completion function
-(@pxref{Programmed Completion}).
-
-Completion compares @var{string} against each of the permissible
-completions specified by @var{collection}. If no permissible
-completions match, @code{try-completion} returns @code{nil}. If there
-is just one matching completion, and the match is exact, it returns
+completions of @var{string} in @var{collection}.
+
+@cindex completion table
+@var{collection} is called the @dfn{completion table}. Its value must
+be a list of strings or cons cells, an obarray, a hash table, or a
+completion function.
+
+@code{try-completion} compares @var{string} against each of the
+permissible completions specified by the completion table. If no
+permissible completions match, it returns @code{nil}. If there is
+just one matching completion, and the match is exact, it returns
@code{t}. Otherwise, it returns the longest initial sequence common
to all possible matching completions.
-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 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.) In particular, a
-list of strings is allowed, even though we usually do not
-think of such lists as alists.
+If @var{collection} is an list, the permissible completions are
+specified by the elements of the list, each of which should be either
+a string, or a cons cell whose @sc{car} is either a string or a symbol
+(a symbol is converted to a string using @code{symbol-name}). If the
+list contains elements of any other type, those are ignored.
@cindex obarray in completion
If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
-of all symbols in the obarray form the set of permissible completions. The
-global variable @code{obarray} holds an obarray containing the names of
-all interned Lisp symbols.
-
-Note that the only valid way to make a new obarray is to create it
-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.
+of all symbols in the obarray form the set of permissible completions.
If @var{collection} is a hash table, then the keys that are strings
are the possible completions. Other keys are ignored.
-You can also use a function as @var{collection}.
-Then the function is solely responsible for performing completion;
-@code{try-completion} returns whatever this function returns. The
-function is called with three arguments: @var{string}, @var{predicate}
-and @code{nil} (the reason for the third argument is so that the same
-function can be used in @code{all-completions} and do the appropriate
-thing in either case). @xref{Programmed Completion}.
+You can also use a function as @var{collection}. Then the function is
+solely responsible for performing completion; @code{try-completion}
+returns whatever this function returns. The function is called with
+three arguments: @var{string}, @var{predicate} and @code{nil} (the
+third argument is so that the same 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, unless @var{collection} is a hash table, in
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
-example, there is only one possible match, and it is exact, so the value
-is @code{t}.
+example, there is only one possible match, and it is exact, so the
+return value is @code{t}.
@smallexample
@group
@end smallexample
@end defun
-@defun all-completions string collection &optional predicate nospace
+@c Removed obsolete argument nospace.
+@defun all-completions string collection &optional predicate
This function returns a list of all possible completions of
-@var{string}. The arguments to this function (aside from
-@var{nospace}) are the same as those of @code{try-completion}. Also,
-this function uses @code{completion-regexp-list} in the same way that
+@var{string}. The arguments to this function
+@c (aside from @var{nospace})
+are the same as those of @code{try-completion}, and it
+uses @code{completion-regexp-list} in the same way that
@code{try-completion} does.
+@ignore
The optional argument @var{nospace} is obsolete. If it is
non-@code{nil}, completions that start with a space are ignored unless
@var{string} starts with a space.
+@end ignore
If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
@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
+completion alternative specified by @var{collection} and
@var{predicate}. The arguments are the same as in
@code{try-completion}. For instance, if @var{collection} is a list of
strings, this is true if @var{string} appears in the list and
@end defun
If you store a completion alist in a variable, you should mark the
-variable as ``risky'' with a non-@code{nil}
+variable as ``risky'' by giving it a non-@code{nil}
@code{risky-local-variable} property. @xref{File Local Variables}.
@defvar completion-ignore-case
It is done by calling @var{fun} with no arguments. The
value @var{fun} returns becomes the permanent value of @var{var}.
-Here is an example of use:
+Here is an example:
@smallexample
(defvar foo (lazy-completion-table foo make-my-alist))
@end smallexample
@end defmac
-The function @code{completion-in-region} provides a convenient way to
-perform completion on an arbitrary stretch of text in an Emacs buffer:
-
-@defun completion-in-region start end collection &optional predicate
-This function completes the text in the current buffer between the
-positions @var{start} and @var{end}, using @var{collection}. The
-argument @var{collection} has the same meaning as in
-@code{try-completion} (@pxref{Basic Completion}).
-
-This function inserts the completion text directly into the current
-buffer. Unlike @code{completing-read} (@pxref{Minibuffer
-Completion}), it does not activate the minibuffer.
-
-For this function to work, point must be somewhere between @var{start}
-and @var{end}.
-@end defun
-
@node Minibuffer Completion
@subsection Completion and the Minibuffer
@cindex minibuffer completion
This section describes the basic interface for reading from the
minibuffer with completion.
-@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
+@defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method
This function reads a string in the minibuffer, assisting the user by
providing completion. It activates the minibuffer with prompt
@var{prompt}, which must be a string.
-The actual completion is done by passing @var{collection} and
-@var{predicate} to the function @code{try-completion} (@pxref{Basic
-Completion}). This happens in certain commands bound in the local
-keymaps used for completion. Some of these commands also call
-@code{test-completion}. Thus, if @var{predicate} is non-@code{nil},
-it should be compatible with @var{collection} and
-@code{completion-ignore-case}. @xref{Definition of test-completion}.
+The actual completion is done by passing the completion table
+@var{collection} and the completion predicate @var{predicate} to the
+function @code{try-completion} (@pxref{Basic Completion}). This
+happens in certain commands bound in the local keymaps used for
+completion. Some of these commands also call @code{test-completion}.
+Thus, if @var{predicate} is non-@code{nil}, it should be compatible
+with @var{collection} and @code{completion-ignore-case}.
+@xref{Definition of test-completion}.
The value of the optional argument @var{require-match} determines how
the user may exit the minibuffer:
@code{minibuffer-local-must-match-map} if @var{require-match} is
non-@code{nil}. @xref{Completion Commands}.
-The argument @var{hist} specifies which history list variable to use for
+The argument @var{history} specifies which history list variable to use for
saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
The argument @var{initial} 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}. For default input, use
+for @var{history}. @xref{Initial Input}. For default input, use
@var{default} instead.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
(@pxref{Text Representations}) from whichever buffer was current before
entering the minibuffer.
-If the built-in variable @code{completion-ignore-case} is
+If the 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
They are described in the following section.
@end defun
+@defvar completing-read-function
+The value of this variable must be a function, which is called by
+@code{completing-read} to actually do its work. It should accept the
+same arguments as @code{completing-read}. This can be bound to a
+different function to completely override the normal behavior of
+@code{completing-read}.
+@end defvar
+
@node Completion Commands
@subsection Minibuffer Commands that Do Completion
in the minibuffer to do completion.
@defvar minibuffer-completion-table
-The value of this variable is the collection used for completion in
-the minibuffer. This is the global variable that contains what
+The value of this variable is the completion table used for completion
+in the minibuffer. This is the global variable that contains what
@code{completing-read} passes to @code{try-completion}. It is used by
-minibuffer completion commands such as @code{minibuffer-complete-word}.
+minibuffer completion commands such as
+@code{minibuffer-complete-word}.
@end defvar
@defvar minibuffer-completion-predicate
the @var{collection} argument, and the value of
@code{minibuffer-completion-predicate} as the @var{predicate} argument.
The list of completions is displayed as text in a buffer named
-@samp{*Completions*}.
+@file{*Completions*}.
@end deffn
@defun display-completion-list completions &optional common-substring
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
+This function is called by @code{minibuffer-completion-help}. A
+common way to use it is together with
@code{with-output-to-temp-buffer}, like this:
@example
@end table
@noindent
-with other characters bound as in @code{minibuffer-local-map}
+and uses @code{minibuffer-local-map} as its parent keymap
(@pxref{Definition of minibuffer-local-map}).
@end defvar
bindings:
@table @asis
-@item @kbd{?}
-@code{minibuffer-completion-help}
-
-@item @key{SPC}
-@code{minibuffer-complete-word}
-
-@item @key{TAB}
-@code{minibuffer-complete}
-
@item @kbd{C-j}
@code{minibuffer-complete-and-exit}
@end table
@noindent
-with other characters bound as in @code{minibuffer-local-map}.
+and uses @code{minibuffer-local-completion-map} as its parent keymap.
@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}.
+This is a sparse keymap that simply unbinds @key{SPC}; because
+filenames can contain spaces. The function @code{read-file-name}
+combines this keymap with either @code{minibuffer-local-completion-map}
+or @code{minibuffer-local-must-match-map}.
@end defvar
-@defvar minibuffer-local-filename-must-match-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
- This section describes the higher-level convenient functions for
+ This section describes the higher-level convenience functions for
reading certain sorts of names with completion.
In most cases, you should not call these functions in the middle of a
@end defun
@defopt read-buffer-function
-This variable specifies how to read buffer names. The function is
-called with the arguments passed to @code{read-buffer}. For example,
-if you set this variable to @code{iswitchb-read-buffer}, all Emacs
-commands that call @code{read-buffer} to read a buffer name will
-actually use the @code{iswitchb} package to read it.
+This variable, if non-@code{nil}, specifies a function for reading
+buffer names. @code{read-buffer} calls this function instead of doing
+its usual work, with the same arguments passed to @code{read-buffer}.
@end defopt
@defopt read-buffer-completion-ignore-case
The argument @var{default} specifies what to return if the user enters
null input. It can be a symbol, a string or a list of strings. If it
is a string, @code{read-command} interns it before returning it.
-If it is a list, @code{read-command} returns the first element of this list.
+If it is a list, @code{read-command} interns the first element of this list.
If @var{default} is @code{nil}, that means no default has been
specified; then if the user enters null input, the return value is
@code{(intern "")}, that is, a symbol whose name is an empty string.
@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.
-
-The argument @var{default} specifies the default value to return if
-the user enters null input. It can be a symbol, a string, or a list
-of strings. If it is a string, @code{read-variable} interns it to
-make the default value. If it is a list, @code{read-variable} interns
-the first element. If @var{default} is @code{nil}, that means no
-default has been specified; then if the user enters null input, the
-return value is @code{(intern "")}.
-
-@example
-@group
-(read-variable "Variable name? ")
-
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
-;; @r{with an empty minibuffer:}
-@end group
-
-@group
----------- Buffer: Minibuffer ----------
-Variable name? @point{}
----------- Buffer: Minibuffer ----------
-@end group
-@end example
-
-@noindent
-If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
-returns @code{fill-prefix}.
-
-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
-@group
-(read-variable @var{prompt})
-@equiv{}
-(intern
- (completing-read @var{prompt} obarray
- 'user-variable-p t nil))
-@end group
-@end example
+This function reads the name of a customizable variable and returns it
+as a symbol. Its arguments have the same form as those of
+@code{read-command}. It behaves just like @code{read-command}, except
+that it uses the predicate @code{custom-variable-p} instead of
+@code{commandp}.
@end defun
@deffn Command read-color &optional prompt convert allow-empty display
This function reads a string that is a color specification, either the
color's name or an RGB hex value such as @code{#RRRGGGBBB}. It
-prompts with @var{prompt} (default: @code{"Color (name or #R+G+B+):"})
+prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
and provides completion for color names, but not for hex RGB values.
In addition to names of standard colors, completion candidates include
the foreground and background colors at point.
Valid RGB values are described in @ref{Color Names}.
-The function's return value is the color name typed by the user in the
+The function's return value is the string typed by the user in the
minibuffer. However, when called interactively or if the optional
-argument @var{convert} is non-@code{nil}, it converts the name into
-the color's RGB value and returns that value as a string. If an
-invalid color name was specified, this function signals an error,
-except that empty color names are allowed when @code{allow-empty} is
+argument @var{convert} is non-@code{nil}, it converts any input color
+name into the corresponding RGB value string and instead returns that.
+This function requires a valid color specification to be input.
+Empty color names are allowed when @var{allow-empty} is
non-@code{nil} and the user enters null input.
Interactively, or when @var{display} is non-@code{nil}, the return
The high-level completion functions @code{read-file-name},
@code{read-directory-name}, and @code{read-shell-command} are designed
-to read file names, directory names, and shell commands respectively.
+to read file names, directory names, and shell commands, respectively.
They provide special features, including automatic insertion of the
default directory.
providing completion.
As an exception, this function reads a file name using a graphical
-file dialog instead of the minibuffer, if (i) it is invoked via a
-mouse command, and (ii) the selected frame is on a graphical display
-supporting such dialogs, and (iii) the variable @code{use-dialog-box}
-is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
-Emacs Manual}), and (iv) the @var{directory} argument, described
-below, does not specify a remote file (@pxref{Remote Files,, Remote
-Files, emacs, The GNU Emacs Manual}). The exact behavior when using a
-graphical file dialog is platform-dependent. Here, we simply document
-the behavior when using the minibuffer.
+file dialog instead of the minibuffer, if all of the following are
+true:
+
+@enumerate
+@item
+It is invoked via a mouse command.
+
+@item
+The selected frame is on a graphical display supporting such dialogs.
+
+@item
+The variable @code{use-dialog-box} is non-@code{nil}.
+@xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}.
+
+@item
+The @var{directory} argument, described below, does not specify a
+remote file. @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
+@end enumerate
+
+@noindent
+The exact behavior when using a graphical file dialog is
+platform-dependent. Here, we simply document the behavior when using
+the minibuffer.
@code{read-file-name} does not automatically expand the returned file
name. You must call @code{expand-file-name} yourself if an absolute
file name is required.
The optional argument @var{require-match} has the same meaning as in
-@code{completing-read}. @xref{Minibuffer Completion}. If
-@var{require-match} is @code{nil}, the local keymap in the minibuffer
-is @code{minibuffer-local-filename-completion-map}; otherwise, it is
-@code{minibuffer-local-filename-must-match-map}. @xref{Completion
-Commands}.
+@code{completing-read}. @xref{Minibuffer Completion}.
The argument @var{directory} specifies the directory to use for
completing relative file names. It should be an absolute directory
-name. If @code{insert-default-directory} is non-@code{nil},
+name. If the variable @code{insert-default-directory} is non-@code{nil},
@var{directory} is also inserted in the minibuffer as initial input.
It defaults to the current buffer's value of @code{default-directory}.
in the buffer (after @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
@var{initial} is @code{nil}---don't insert any file name. To see what
-@var{initial} does, try the command @kbd{C-x C-v}. @strong{Please
-note:} we recommend using @var{default} rather than @var{initial} in
-most cases.
+@var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting
+a file. @strong{Please note:} we recommend using @var{default} rather
+than @var{initial} in most cases.
If @var{default} is non-@code{nil}, then the function returns
@var{default} if the user exits the minibuffer with the same non-empty
If the user types @key{RET} in an empty minibuffer, this function
returns an empty string, regardless of the value of
@var{require-match}. This is, for instance, how the user can make the
-current buffer visit no file using @code{M-x set-visited-file-name}.
+current buffer visit no file using @kbd{M-x set-visited-file-name}.
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}
+alternatives. A file name is an acceptable value if @var{predicate}
returns non-@code{nil} for it.
Here is an example of using @code{read-file-name}:
@defun read-directory-name prompt &optional directory default require-match initial
This function is like @code{read-file-name} but allows only directory
-names as completion possibilities.
+names as completion alternatives.
If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
@code{read-directory-name} constructs a substitute default by
@xref{Interactive Codes,, Code Characters for interactive}.) Its
value controls whether @code{read-file-name} starts by placing the
name of the default directory in the minibuffer, plus the initial file
-name if any. If the value of this variable is @code{nil}, then
+name, if any. If the value of this variable is @code{nil}, then
@code{read-file-name} does not place any initial input in the
minibuffer (unless you specify initial input with the @var{initial}
argument). In that case, the default directory is still used for
@end example
@end defopt
-@defun read-shell-command prompt &optional initial-contents hist &rest args
+@defun read-shell-command prompt &optional initial history &rest args
This function reads a shell command from the minibuffer, prompting
with @var{prompt} and providing intelligent completion. It completes
the first word of the command using candidates that are appropriate
for command names, and the rest of the command words as file names.
This function uses @code{minibuffer-local-shell-command-map} as the
-keymap for minibuffer input. The @var{hist} argument specifies the
+keymap for minibuffer input. The @var{history} argument specifies the
history list to use; if is omitted or @code{nil}, it defaults to
@code{shell-command-history} (@pxref{Minibuffer History,
-shell-command-history}). The optional argument @var{initial-contents}
+shell-command-history}). The optional argument @var{initial}
specifies the initial content of the minibuffer (@pxref{Initial
Input}). The rest of @var{args}, if present, are used as the
@var{default} and @var{inherit-input-method} arguments in
@defvar minibuffer-local-shell-command-map
This keymap is used by @code{read-shell-command} for completing
-command and file names that are part of a shell command.
+command and file names that are part of a shell command. It uses
+@code{minibuffer-local-map} as its parent keymap, and binds @key{TAB}
+to @code{completion-at-point}.
@end defvar
-@node Completion Styles
-@subsection Completion Styles
-@cindex completion styles
+@node Completion Variables
+@subsection Completion Variables
- A @dfn{completion style} is a set of rules for generating
-completions. The user option @code{completion-styles} stores a list
-of completion styles, which are represented by symbols.
+ Here are some variables that can be used to alter the default
+completion behavior.
+@cindex completion styles
@defopt completion-styles
-This is a list of completion style symbols to use for performing
-completion. Each completion style in this list must be defined in
-@code{completion-styles-alist}.
+The value of this variable is a list of completion style (symbols) to
+use for performing completion. A @dfn{completion style} is a set of
+rules for generating completions. Each symbol occurring this list
+must have a corresponding entry in @code{completion-styles-alist}.
@end defopt
@defvar completion-styles-alist
This variable stores a list of available completion styles. Each
-element in the list must have the form @samp{(@var{name}
-@var{try-completion} @var{all-completions})}. Here, @var{name} is the
-name of the completion style (a symbol), which may be used in
-@code{completion-styles-alist} to refer to this style.
-
-@var{try-completion} is the function that does the completion, and
-@var{all-completions} is the function that lists the completions.
-These functions should accept four arguments: @var{string},
-@var{collection}, @var{predicate}, and @var{point}. The @var{string},
-@var{collection}, and @var{predicate} arguments have the same meanings
-as in @code{try-completion} (@pxref{Basic Completion}), and the
-@var{point} argument is the position of point within @var{string}.
-Each function should return a non-@code{nil} value if it performed its
-job, and @code{nil} if it did not (e.g., if there is no way to
-complete @var{string} according to the completion style).
-
-When the user calls a completion command, such as
+element in the list has the form
+
+@example
+(@var{style} @var{try-completion} @var{all-completions} @var{doc})
+@end example
+
+@noindent
+Here, @var{style} is the name of the completion style (a symbol),
+which may be used in the @code{completion-styles} variable to refer to
+this style; @var{try-completion} is the function that does the
+completion; @var{all-completions} is the function that lists the
+completions; and @var{doc} is a string describing the completion
+style.
+
+The @var{try-completion} and @var{all-completions} functions should
+each accept four arguments: @var{string}, @var{collection},
+@var{predicate}, and @var{point}. The @var{string}, @var{collection},
+and @var{predicate} arguments have the same meanings as in
+@code{try-completion} (@pxref{Basic Completion}), and the @var{point}
+argument is the position of point within @var{string}. Each function
+should return a non-@code{nil} value if it performed its job, and
+@code{nil} if it did not (e.g.@: if there is no way to complete
+@var{string} according to the completion style).
+
+When the user calls a completion command like
@code{minibuffer-complete} (@pxref{Completion Commands}), Emacs looks
for the first style listed in @code{completion-styles} and calls its
@var{try-completion} function. If this function returns @code{nil},
-Emacs moves to the next completion style listed in
-@code{completion-styles} and calls its @var{try-completion} function,
-and so on until one of the @var{try-completion} functions successfully
-performs completion and returns a non-@code{nil} value. A similar
-procedure is used for listing completions, via the
-@var{all-completions} functions.
+Emacs moves to the next listed completion style and calls its
+@var{try-completion} function, and so on until one of the
+@var{try-completion} functions successfully performs completion and
+returns a non-@code{nil} value. A similar procedure is used for
+listing completions, via the @var{all-completions} functions.
+
+@xref{Completion Styles,,, emacs, The GNU Emacs Manual}, for a
+description of the available completion styles.
@end defvar
- By default, @code{completion-styles-alist} contains five pre-defined
-completion styles: @code{basic}, a basic completion style;
-@code{partial-completion}, which does partial completion (completing
-each word in the input separately); @code{emacs22}, which performs
-completion according to the rules used in Emacs 22; @code{emacs21},
-which performs completion according to the rules used in Emacs 21; and
-@code{initials}, which completes acronyms and initialisms.
+@defopt completion-category-overrides
+This variable specifies special completion styles and other completion
+behaviors to use when completing certain types of text. Its value
+should be an alist with elements of the form @code{(@var{category}
+. @var{alist})}. @var{category} is a symbol describing what is being
+completed; currently, the @code{buffer}, @code{file}, and
+@code{unicode-name} categories are defined, but others can be defined
+via specialized completion functions (@pxref{Programmed Completion}).
+@var{alist} is an association list describing how completion should
+behave for the corresponding category. The following alist keys are
+supported:
+
+@table @code
+@item styles
+The value should be a list of completion styles (symbols).
+
+@item cycle
+The value should be a value for @code{completion-cycle-threshold}
+(@pxref{Completion Options,,, emacs, The GNU Emacs Manual}) for this
+category.
+@end table
+
+@noindent
+Additional alist entries may be defined in the future.
+@end defopt
+
+@defvar completion-extra-properties
+This variable is used to specify extra properties of the current
+completion command. It is intended to be let-bound by specialized
+completion commands. Its value should be a list of property and value
+pairs. The following properties are supported:
+
+@table @code
+@item :annotation-function
+The value should be a function to add annotations in the completions
+buffer. This function must accept one argument, a completion, and
+should either return @code{nil} or a string to be displayed next to
+the completion.
+
+@item :exit-function
+The value should be a function to run after performing completion.
+The function should accept two arguments, @var{string} and
+@var{status}, where @var{string} is the text to which the field was
+completed, and @var{status} indicates what kind of operation happened:
+@code{finished} if text is now complete, @code{sole} if the text
+cannot be further completed but completion is not finished, or
+@code{exact} if the text is a valid completion but may be further
+completed.
+@end table
+@end defvar
@node Programmed Completion
@subsection Programmed Completion
The string to be completed.
@item
-The predicate function to filter possible matches, or @code{nil} if
-none. Your function should call the predicate for each possible match,
-and ignore the possible match if the predicate returns @code{nil}.
-
-@item
-A flag specifying the type of operation. The best way to think about
-it is that the function stands for an object (in the
-``object-oriented'' sense of the word), and this third argument
-specifies which method to run.
-@end itemize
-
- There are currently four methods, i.e. four flag values, one for
-each of the four different basic operations:
-
-@itemize @bullet
-@item
-@code{nil} specifies @code{try-completion}. The completion function
-should return the completion of the specified string, or @code{t} if the
-string is a unique and exact match already, or @code{nil} if the string
-matches no possibility.
-
-If the string is an exact match for one possibility, but also matches
-other longer possibilities, the function should return the string, not
-@code{t}.
+A predicate function with which to filter possible matches, or
+@code{nil} if none. The function should call the predicate for each
+possible match, and ignore the match if the predicate returns
+@code{nil}.
@item
-@code{t} specifies @code{all-completions}. The completion function
+A flag specifying the type of completion operation to perform. This
+is one of the following four values:
+
+@table @code
+@item nil
+This specifies a @code{try-completion} operation. The function should
+return @code{t} if the specified string is a unique and exact match;
+if there is more than one match, it should return the common substring
+of all matches (if the string is an exact match for one completion
+alternative but also matches other longer alternatives, the return
+value is the string); if there are no matches, it should return
+@code{nil}.
+
+@item t
+This specifies an @code{all-completions} operation. The function
should return a list of all possible completions of the specified
string.
-@item
-@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.
+@item lambda
+This specifies a @code{test-completion} operation. The function
+should return @code{t} if the specified string is an exact match for
+some completion alternative; @code{nil} otherwise.
+
+@item (boundaries . @var{suffix})
+This specifies a @code{completion-boundaries} operation. The function
+should return @code{(boundaries @var{start} . @var{end})}, where
+@var{start} is the position of the beginning boundary in the specified
+string, and @var{end} is the position of the end boundary in
+@var{suffix}.
+
+@item metadata
+This specifies a request for information about the state of the
+current completion. The function should return an alist, as described
+below. The alist may contain any number of elements.
+@end table
-@item
-@code{(boundaries . SUFFIX)} specifies @code{completion-boundaries}.
-The function should return a value of the form @code{(boundaries
-START . END)} where START is the position of the beginning boundary
-in the string to complete, and END is the position of the end boundary
-in SUFFIX.
+@noindent
+If the flag has any other value, the completion function should return
+@code{nil}.
@end itemize
+The following is a list of metadata entries that a completion function
+may return in response to a @code{metadata} flag argument:
+
+@table @code
+@item category
+The value should be a symbol describing what kind of text the
+completion function is trying to complete. If the symbol matches one
+of the keys in @code{completion-category-overrides}, the usual
+completion behavior is overridden. @xref{Completion Variables}.
+
+@item annotation-function
+The value should be a function for @dfn{annotating} completions. The
+function should take one argument, @var{string}, which is a possible
+completion. It should return a string, which is displayed after the
+completion @var{string} in the @file{*Completions*} buffer.
+
+@item display-sort-function
+The value should be a function for sorting completions. The function
+should take one argument, a list of completion strings, and return a
+sorted list of completion strings. It is allowed to alter the input
+list destructively.
+
+@item cycle-sort-function
+The value should be a function for sorting completions, when
+@code{completion-cycle-threshold} is non-@code{nil} and the user is
+cycling through completion alternatives. @xref{Completion Options,,,
+emacs, The GNU Emacs Manual}. Its argument list and return value are
+the same as for @code{display-sort-function}.
+@end table
+
@defun completion-table-dynamic function
This function is a convenient way to write a function that can act as
-programmed completion function. The argument @var{function} should be
+a 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{completion-table-dynamic} as a transducer between that interface
and the interface for programmed completion functions.
@end defun
-@defvar completion-annotate-function
-The value of this variable, if non-@code{nil}, should be a function
-for ``annotating'' the entries in the @samp{*Completions*} buffer.
-The function should accept a single argument, the completion string
-for an entry. It should return an additional string to display next
-to that entry in the @samp{*Completions*} buffer, or @code{nil} if no
-additional string is to be displayed.
-
-The function can determine the collection used for the current
-completion via the variable @code{minibuffer-completion-table}
-(@pxref{Completion Commands}).
+@node Completion in Buffers
+@subsection Completion in Ordinary Buffers
+@cindex inline completion
+
+@findex completion-at-point
+ Although completion is usually done in the minibuffer, the
+completion facility can also be used on the text in ordinary Emacs
+buffers. In many major modes, in-buffer completion is performed by
+the @kbd{C-M-i} or @kbd{M-@key{TAB}} command, bound to
+@code{completion-at-point}. @xref{Symbol Completion,,, emacs, The GNU
+Emacs Manual}. This command uses the abnormal hook variable
+@code{completion-at-point-functions}:
+
+@defvar completion-at-point-functions
+The value of this abnormal hook should be a list of functions, which
+are used to compute a completion table for completing the text at
+point. It can be used by major modes to provide mode-specific
+completion tables (@pxref{Major Mode Conventions}).
+
+When the command @code{completion-at-point} runs, it calls the
+functions in the list one by one, without any argument. Each function
+should return @code{nil} if it is unable to produce a completion table
+for the text at point. Otherwise it should return a list of the form
+
+@example
+(@var{start} @var{end} @var{collection} . @var{props})
+@end example
+
+@noindent
+@var{start} and @var{end} delimit the text to complete (which should
+enclose point). @var{collection} is a completion table for completing
+that text, in a form suitable for passing as the second argument to
+@code{try-completion} (@pxref{Basic Completion}); completion
+alternatives will be generated from this completion table in the usual
+way, via the completion styles defined in @code{completion-styles}
+(@pxref{Completion Variables}). @var{props} is a property list for
+additional information; any of the properties in
+@code{completion-extra-properties} are recognized (@pxref{Completion
+Variables}), as well as the following additional ones:
+
+@table @code
+@item :predicate
+The value should be a predicate that completion candidates need to
+satisfy.
+
+@item :exclusive
+If the value is @code{no}, then if the completion table fails to match
+the text at point, @code{completion-at-point} moves on to the
+next function in @code{completion-at-point-functions} instead of
+reporting a completion failure.
+@end table
+
+A function in @code{completion-at-point-functions} may also return a
+function. In that case, that returned function is called, with no
+argument, and it is entirely responsible for performing the
+completion. We discourage this usage; it is intended to help convert
+old code to using @code{completion-at-point}.
+
+The first function in @code{completion-at-point-functions} to return a
+non-@code{nil} value is used by @code{completion-at-point}. The
+remaining functions are not called. The exception to this is when
+there is an @code{:exclusive} specification, as described above.
@end defvar
+ The following function provides a convenient way to perform
+completion on an arbitrary stretch of text in an Emacs buffer:
+
+@defun completion-in-region start end collection &optional predicate
+This function completes the text in the current buffer between the
+positions @var{start} and @var{end}, using @var{collection}. The
+argument @var{collection} has the same meaning as in
+@code{try-completion} (@pxref{Basic Completion}).
+
+This function inserts the completion text directly into the current
+buffer. Unlike @code{completing-read} (@pxref{Minibuffer
+Completion}), it does not activate the minibuffer.
+
+For this function to work, point must be somewhere between @var{start}
+and @var{end}.
+@end defun
+
+
@node Yes-or-No Queries
@section Yes-or-No Queries
@cindex asking the user questions
using the mouse---more precisely, if @code{last-nonmenu-event}
(@pxref{Command Loop Info}) is either @code{nil} or a list---then it
uses a dialog box or pop-up menu to ask the question. Otherwise, it
-uses keyboard input. You can force use of the mouse or use of keyboard
+uses keyboard input. You can force use either of the mouse or of keyboard
input by binding @code{last-nonmenu-event} to a suitable value around
the call.
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
cursor moves to the echo area while the question is being asked.
The answers and their meanings, even @samp{y} and @samp{n}, are not
-hardwired. The keymap @code{query-replace-map} specifies them.
-@xref{Search and Replace}.
-
-In the following example, the user first types @kbd{q}, which is
-invalid. At the next prompt the user types @kbd{y}.
-
-@smallexample
-@group
-(y-or-n-p "Do you need a lift? ")
-
-;; @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)
----------- Echo area ----------
-@end group
-
-;; @r{If the user then types @kbd{q}, the following appears:}
-
-@group
----------- Echo area ----------
-Please answer y or n. Do you need a lift? (y or n)
----------- Echo area ----------
-@end group
-
-;; @r{When the user types a valid answer,}
-;; @r{it is displayed after the question:}
-
-@group
----------- Echo area ----------
-Do you need a lift? (y or n) y
----------- Echo area ----------
-@end group
-@end smallexample
+hardwired, and are specified by the keymap @code{query-replace-map}
+(@pxref{Search and Replace}). In particular, if the user enters the
+special responses @code{recenter}, @code{scroll-up},
+@code{scroll-down}, @code{scroll-other-window}, or
+@code{scroll-other-window-down} (respectively bound to @kbd{C-l},
+@kbd{C-v}, @kbd{M-v}, @kbd{C-M-v} and @kbd{C-M-S-v} in
+@code{query-replace-map}), this function performs the specified window
+recentering or scrolling operation, and poses the question again.
@noindent
We show successive lines of echo area messages, but only one actually
appears on the screen at a time.
@end defun
-@defun y-or-n-p-with-timeout prompt seconds default-value
+@defun y-or-n-p-with-timeout prompt seconds default
Like @code{y-or-n-p}, except that if the user fails to answer within
@var{seconds} seconds, this function stops waiting and returns
-@var{default-value}. It works by setting up a timer; see @ref{Timers}.
+@var{default}. It works by setting up a timer; see @ref{Timers}.
The argument @var{seconds} may be an integer or a floating point number.
@end defun
The value of @var{list} specifies the objects to ask questions about.
It should be either a list of objects or a generator function. If it is
a function, it should expect no arguments, and should return either the
-next object to ask about, or @code{nil} meaning stop asking questions.
+next object to ask about, or @code{nil}, meaning to stop asking questions.
The argument @var{prompter} specifies how to ask each question. If
@var{prompter} is a string, the question text is computed like this:
If not a string, @var{prompter} should be a function of one argument
(the next object to ask about) and should return the question text. If
the value is a string, that is the question to ask the user. The
-function can also return @code{t} meaning do act on this object (and
-don't ask the user), or @code{nil} meaning ignore this object (and don't
+function can also return @code{t}, meaning do act on this object (and
+don't ask the user), or @code{nil}, meaning ignore this object (and don't
ask the user).
The argument @var{actor} says how to act on the answers that the user
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.
mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
Loop Info}) is either @code{nil} or a list---then it uses a dialog box
or pop-up menu to ask the question. In this case, it does not use
-keyboard input or the echo area. You can force use of the mouse or use
+keyboard input or the echo area. You can force use either of the mouse or
of keyboard input by binding @code{last-nonmenu-event} to a suitable
value around the call.
The return value of @code{map-y-or-n-p} is the number of objects acted on.
@end defun
+@c FIXME An example of this would be more useful than all the
+@c preceding examples of simple things.
@node Reading a Password
@section Reading a Password
regular expression).
@end deffn
+@deffn Command previous-complete-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th previous (older) history element that completes the current
+contents of the minibuffer before the point.
+@end deffn
+
+@deffn Command next-complete-history-element n
+This command replaces the minibuffer contents with the value of the
+@var{n}th next (newer) history element that completes the current
+contents of the minibuffer before the point.
+@end deffn
+
+
@node Minibuffer Windows
@section Minibuffer Windows
@cindex minibuffer windows
@defun active-minibuffer-window
This function returns the currently active minibuffer window, or
-@code{nil} if none is currently active.
+@code{nil} if there is none.
@end defun
@defun minibuffer-window &optional frame
frame.
@defun minibuffer-window-active-p window
-This function returns non-@code{nil} if @var{window}, assumed to be
-a minibuffer window, is currently active.
+This function returns non-@code{nil} if @var{window} is the currently
+active minibuffer window.
@end defun
@node Minibuffer Contents
@end defvar
@defun minibuffer-selected-window
-This function returns the window which was selected when the
+This function returns the window that was selected when the
minibuffer was entered. If selected window is not a minibuffer
window, it returns @code{nil}.
@end defun
frame. If an integer, it specifies a number of lines.
@end defopt
+@vindex minibuffer-message-timeout
@defun minibuffer-message string &rest args
This function displays @var{string} temporarily at the end of the
-minibuffer text, for two seconds, or until the next input event
-arrives, whichever comes first. If @var{args} is non-@code{nil}, the
-actual message is obtained by passing @var{string} and @var{args}
-through @code{format}. @xref{Formatting Strings}.
+minibuffer text, for a few seconds, or until the next input event
+arrives, whichever comes first. The variable
+@code{minibuffer-message-timeout} specifies the number of seconds to
+wait in the absence of input. It defaults to 2. If @var{args} is
+non-@code{nil}, the actual message is obtained by passing @var{string}
+and @var{args} through @code{format}. @xref{Formatting Strings}.
@end defun
+
+@deffn Command minibuffer-inactive-mode
+This is the major mode used in inactive minibuffers. It uses
+keymap @code{minibuffer-inactive-mode-map}. This can be useful
+if the minibuffer is in a separate frame. @xref{Minibuffers and Frames}.
+@end deffn
HCoop / bpt / emacs.git / blobdiff