X-Git-Url: https://git.hcoop.net/bpt/emacs.git/blobdiff_plain/74ca4d394be5ea982419b5a0203426b78cb5cc0c..ac57c3e728c65378f2c70b76ac4df6279189d528:/doc/lispref/minibuf.texi diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index d1cc33b9f0..e76b827cd2 100644 --- 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 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 @@ -101,7 +101,9 @@ the minibuffer is in a separate frame. @xref{Minibuffers and Frames}. 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 @@ -211,25 +213,39 @@ This function works by calling the @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 @@ -242,10 +258,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 @@ -772,7 +815,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 +929,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 +1144,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 +1155,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 +1162,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 @@ -1579,7 +1636,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 @@ -1679,7 +1736,7 @@ possible match, and ignore the match if the predicate returns @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 @@ -1759,6 +1816,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 @@ -1811,11 +1875,34 @@ next function in @code{completion-at-point-functions} instead of 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 @@ -1905,7 +1992,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 @@ -2061,7 +2148,8 @@ function @code{read-passwd}. @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 @@ -2204,12 +2292,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,