@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
@end smallexample
@end defun
-@defun read-regexp prompt &optional default
+@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} 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.
-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
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
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-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} combines
+multiple input tables. @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
@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
@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 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
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