X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/bbd347f5f7e99da1a559dad818b5fa8f59c0901e..299ccd03f94008a1580a0dbbfd56c32484dd20f8:/doc/lispref/minibuf.texi?ds=sidebyside diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index c840eb6ded..5b4e29c57a 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1,9 +1,9 @@ @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 @@ -57,16 +57,17 @@ including @code{beginning-of-line}, @code{forward-word}, @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 -@c FIXME? Works in 23.4, not 24.0.95. (Bug#11276) -resize it temporarily with the window sizing commands; it reverts to -its normal size when the minibuffer is exited. You can resize it -@c FIXME? Doesn't work in any version of Emacs? +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} @@ -210,22 +211,39 @@ This function works by calling the @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 @@ -238,10 +256,37 @@ The last string used in an incremental search. 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 @@ -511,8 +556,7 @@ duplicates, and to add @var{newelt} to the list even if it is empty. 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 @@ -664,25 +708,22 @@ This function returns the longest common substring of all possible 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 @@ -695,7 +736,7 @@ 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 +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}. @@ -718,8 +759,8 @@ handle @code{completion-regexp-list} itself.) 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 @@ -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}) -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. @@ -886,6 +927,28 @@ Here is an example: @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 @@ -1079,7 +1142,7 @@ The list of completions is displayed as text in a buffer named @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 @@ -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 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: @@ -1104,8 +1160,7 @@ common way to use it is together with @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 @@ -1218,11 +1273,9 @@ Buffer name (default foo): @point{} @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 @@ -1404,7 +1457,7 @@ returns the pre-inserted contents of the minibuffer. 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 @@ -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{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 @@ -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 -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 @@ -1760,6 +1814,13 @@ possible completions of it. You can think of 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 @@ -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 -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 @@ -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}. -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 @@ -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 -@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,