@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
@chapter Minibuffers
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 history
+@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}.
+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.
-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}.
+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} 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:
+@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
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
@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
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
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