Merge from emacs-24; up to 2014-03-21T21:27:25Z!dancol@dancol.org

[bpt/emacs.git] / doc / lispref / minibuf.texi

diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi
index 4cf096b..5b4e29c 100644 (file)
--- a/doc/lispref/minibuf.texi
+++ b/doc/lispref/minibuf.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Emacs Lisp Reference Manual.
 @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
 @c See the file elisp.texi for copying conditions.
 @node Minibuffers
 @chapter Minibuffers


@@ -211,22 +211,39 @@ This function works by calling the
 @end smallexample
 @end defun
 
 @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
 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
 
 @itemize @minus
 @item


@@ -239,10 +256,37 @@ The last string used in an incremental search.
 The last string or pattern used in query-replace commands.
 @end itemize
 
 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
 
 @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
 @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


@@ -664,25 +708,22 @@ This function returns the longest common substring of all possible
 completions of @var{string} in @var{collection}.
 
 @cindex completion table
 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.
 
 @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
 
 @cindex obarray in completion
 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names


@@ -772,7 +813,7 @@ too short).  Both of those begin with the string @samp{foobar}.
 This function returns a list of all possible completions of
 @var{string}.  The arguments to this function
 @c (aside from @var{nospace})
 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.
 
 uses @code{completion-regexp-list} in the same way that
 @code{try-completion} does.
 


@@ -886,6 +927,28 @@ Here is an example:
 @end smallexample
 @end defmac
 
 @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
 @node Minibuffer Completion
 @subsection Completion and the Minibuffer
 @cindex minibuffer completion


@@ -1079,7 +1142,7 @@ The list of completions is displayed as text in a buffer named
 @file{*Completions*}.
 @end deffn
 
 @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
 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


@@ -1090,13 +1153,6 @@ which is printed as if the strings were concatenated.  The first of
 the two strings is the actual completion, the second string serves as
 annotation.
 
 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:
 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:


@@ -1104,8 +1160,7 @@ common way to use it is together with
 @example
 (with-output-to-temp-buffer "*Completions*"
   (display-completion-list
 @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 example
 @end defun
 


@@ -1218,11 +1273,9 @@ Buffer name (default foo): @point{}
 @end defun
 
 @defopt read-buffer-function
 @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
 @end defopt
 
 @defopt read-buffer-completion-ignore-case


@@ -1581,7 +1634,7 @@ 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{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
 @var{string} according to the completion style).
 
 When the user calls a completion command like


@@ -1712,8 +1765,9 @@ string, and @var{end} is the position of the end boundary in
 
 @item metadata
 This specifies a request for information about the state of the
 
 @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
 @end table
 
 @noindent


@@ -1760,6 +1814,13 @@ possible completions of it.  You can think of
 and the interface for programmed completion functions.
 @end defun
 
 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
 @node Completion in Buffers
 @subsection Completion in Ordinary Buffers
 @cindex inline completion


@@ -1888,47 +1949,14 @@ Echo Area}), which uses the same screen space as the minibuffer.  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
 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
 
 @noindent
 We show successive lines of echo area messages, but only one actually


@@ -1939,7 +1967,7 @@ appears on the screen at a time.
 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}.
 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
 @end defun
 
 @defun yes-or-no-p prompt


@@ -2238,12 +2266,6 @@ This is like @code{minibuffer-contents}, except that it does not copy text
 properties, just the characters themselves.  @xref{Text Properties}.
 @end defun
 
 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,
 @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,