@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2014 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@node Minibuffers, Command Loop, Read and Print, Top
+@node Minibuffers
@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
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.
+was supplied when Emacs was started. This supports only basic input:
+none of the special minibuffer features (history, completion,
+password hiding, etc.) are available in batch mode.
@node Text from Minibuffer
@section Reading Text Strings with the Minibuffer
@end smallexample
@end defun
-@defun read-regexp prompt &optional default
+@defun read-regexp prompt &optional defaults 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}).
+minibuffer and returns it. If the minibuffer prompt string
+@var{prompt} does not end in @samp{:} (followed by optional
+whitespace), the function adds @samp{: } to the end, preceded by the
+default return value (see below), if that is non-empty.
-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.
+The optional argument @var{defaults} controls the default value to
+return if the user enters null input, and should be one of: a string;
+@code{nil}, which is equivalent to an empty string; a list of strings;
+or a symbol.
-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:
+If @var{defaults} is a symbol, @code{read-regexp} consults the value
+of the variable @code{read-regexp-defaults-function} (see below), and
+if that is non-@code{nil} uses it in preference to @var{defaults}.
+The value in this case should be either:
+
+@itemize @minus
+@item
+@code{regexp-history-last}, which means to use the first element of
+the appropriate minibuffer history list (see below).
+
+@item
+A function of no arguments, whose return value (which should be
+@code{nil}, a string, or a list of strings) becomes the value of
+@var{defaults}.
+@end itemize
+
+@code{read-regexp} now ensures that the result of processing
+@var{defaults} is a list (i.e., if the value is @code{nil} or a
+string, it converts it to a list of one element). To this list,
+@code{read-regexp} then appends a few potentially useful candidates for
+input. These are:
@itemize @minus
@item
The last string or pattern used in query-replace commands.
@end itemize
-This function works by calling the @code{read-from-minibuffer}
-function, after computing the list of defaults as described above.
+The function now has a list of regular expressions that it passes to
+@code{read-from-minibuffer} to obtain the user's input. The first
+element of the list is the default result in case of empty input. All
+elements of the list are available to the user as the ``future
+minibuffer history list'' (@pxref{Minibuffer History, future list,,
+emacs, The GNU Emacs Manual}).
+
+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}.
@end defun
+@defvar read-regexp-defaults-function
+The function @code{read-regexp} may use the value of this variable to
+determine its list of default regular expressions. If non-@code{nil},
+the value of this variable should be either:
+
+@itemize @minus
+@item
+The symbol @code{regexp-history-last}.
+
+@item
+A function of no arguments that returns either @code{nil}, a string,
+or a list of strings.
+@end itemize
+
+@noindent
+See @code{read-regexp} above for details of how these values are used.
+@end defvar
+
@defvar minibuffer-allow-text-properties
If this variable is @code{nil}, then @code{read-from-minibuffer}
and @code{read-string} strip all text properties from the minibuffer
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
-non-@code{nil}.
+@code{add-to-history}. The default value is @code{t}.
@end defvar
@defopt history-length
completions of @var{string} in @var{collection}.
@cindex completion table
-The @var{collection} argument is called the @dfn{completion table}.
-Its value must be a list of strings, an alist whose keys are strings
-or symbols, an obarray, a hash table, or a completion function.
-
-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
+@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
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
+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}.
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
This function returns a list of all possible completions of
@var{string}. The arguments to this function
@c (aside from @var{nospace})
-are the same as those of @code{try-completion}, and it
+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.
@end smallexample
@end defmac
+@c FIXME? completion-table-with-context?
+@findex completion-table-case-fold
+@findex completion-table-in-turn
+@findex completion-table-merge
+@findex completion-table-subvert
+@findex completion-table-with-quoting
+@findex completion-table-with-predicate
+@findex completion-table-with-terminator
+@cindex completion table, modifying
+@cindex completion tables, combining
+There are several functions that take an existing completion table and
+return a modified version. @code{completion-table-case-fold} returns
+a case-insensitive table. @code{completion-table-in-turn} and
+@code{completion-table-merge} combine multiple input tables in
+different ways. @code{completion-table-subvert} alters a table to use
+a different initial prefix. @code{completion-table-with-quoting}
+returns a table suitable for operating on quoted text.
+@code{completion-table-with-predicate} filters a table with a
+predicate function. @code{completion-table-with-terminator} adds a
+terminating string.
+
+
@node Minibuffer Completion
@subsection Completion and the Minibuffer
@cindex minibuffer completion
@file{*Completions*}.
@end deffn
-@defun display-completion-list completions &optional common-substring
+@defun display-completion-list completions
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}. A
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)
- (buffer-string)))
+ (all-completions (buffer-string) my-alist)))
@end example
@end defun
@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
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
@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
+@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
@item
A flag specifying the type of completion operation to perform. This
-is one of the following four values:
+flag may be one of the following values.
@table @code
@item nil
@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.
+current completion. The return value should have the form
+@code{(metadata . @var{alist})}, where @var{alist} is an alist whose
+elements are described below.
@end table
@noindent
and the interface for programmed completion functions.
@end defun
+@defun completion-table-with-cache function &optional ignore-case
+This is a wrapper for @code{completion-table-dynamic} that saves the
+last argument-result pair. This means that multiple lookups with the
+same argument only need to call @var{function} once. This can be useful
+when a slow operation is involved, such as calling an external process.
+@end defun
+
@node Completion in Buffers
@subsection Completion in Ordinary Buffers
@cindex inline completion
reporting a completion failure.
@end table
+Supplying a function for @var{collection} is strongly recommended if
+generating the list of completions is an expensive operation. Emacs
+may internally call functions in @code{completion-at-point-functions}
+many times, but care about the value of @var{collection} for only some
+of these calls. By supplying a function for @var{collection}, Emacs
+can defer generating completions until necessary. You can use
+@var{completion-table-dynamic} to create a wrapper function:
+
+@smallexample
+;; Avoid this pattern.
+(let ((beg ...) (end ...) (my-completions (my-make-completions)))
+ (list beg end my-completions))
+
+;; Use this instead.
+(let ((beg ...) (end ...))
+ (list beg
+ end
+ (completion-table-dynamic
+ (lambda (_)
+ (my-make-completions)))))
+@end smallexample
+
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}.
+function instead of a list as described above. 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
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}.
-
-@c Need an interactive example, because otherwise the return value
-@c obscures the display of the valid answer.
-@smallexample
-@group
-(defun ask ()
- (interactive)
- (y-or-n-p "Do you need a lift? "))
-
-;; @r{After evaluation of the preceding definition, @kbd{M-x ask}}
-;; @r{causes the following prompt to appear 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
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}. It works by setting up a timer; see @ref{Timers}.
-The argument @var{seconds} may be an integer or a floating point number.
+The argument @var{seconds} should be a number.
@end defun
@defun yes-or-no-p prompt
@defun read-passwd prompt &optional confirm default
This function reads a password, prompting with @var{prompt}. It does
not echo the password as the user types it; instead, it echoes @samp{.}
-for each character in the password.
+for each character in the password. (Note that in batch mode, the
+input is not hidden.)
The optional argument @var{confirm}, if non-@code{nil}, says to read the
password twice and insist it must be the same both times. If it isn't
properties, just the characters themselves. @xref{Text Properties}.
@end defun
-@defun 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
This function erases the editable contents of the minibuffer (that is,
everything except the prompt), if a minibuffer is current. Otherwise,
HCoop / bpt / emacs.git / blobdiff