diff options
Diffstat (limited to 'doc/lispref/minibuf.texi')
| -rw-r--r-- | doc/lispref/minibuf.texi | 183 |
1 files changed, 118 insertions, 65 deletions
diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 185d355ba70..d54c654562f 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -97,6 +97,14 @@ to be done. @xref{Text from Minibuffer}, for the non-completion minibuffer local maps. @xref{Completion Commands}, for the minibuffer local maps for completion. +@cindex active minibuffer + An active minibuffer usually has major mode @code{minibuffer-mode}. +This is an Emacs internal mode without any special features. To +customize the setup of minibuffers, we suggest you use +@code{minibuffer-setup-hook} (@pxref{Minibuffer Misc}) rather than +@code{minibuffer-mode-hook}, since the former is run later, after the +minibuffer has been fully initialized. + @cindex inactive minibuffer When a minibuffer is inactive, its major mode is @code{minibuffer-inactive-mode}, with keymap @@ -167,8 +175,10 @@ various applications such as completion. The argument @var{history} specifies a history list variable to use for saving the input and for history commands used in the minibuffer. -It defaults to @code{minibuffer-history}. You can optionally specify -a starting position in the history list as well. @xref{Minibuffer History}. +It defaults to @code{minibuffer-history}. If @var{history} is the +symbol @code{t}, history is not recorded. You can optionally specify +a starting position in the history list as well. @xref{Minibuffer +History}. If the variable @code{minibuffer-allow-text-properties} is non-@code{nil}, then the string that is returned includes whatever text @@ -379,8 +389,6 @@ default, it makes the following bindings: @end table @end defvar -@c In version 18, initial is required -@c Emacs 19 feature @defun read-no-blanks-input prompt &optional initial inherit-input-method This function reads a string from the minibuffer, but does not allow whitespace characters as part of the input: instead, those characters @@ -461,6 +469,18 @@ If @var{default} is a non-@code{nil} list, the first element of the list is used in the prompt. @end defun +@defvar read-minibuffer-restore-windows +If this option is non-@code{nil} (the default), getting input from the +minibuffer will restore, on exit, the window configurations of the frame +where the minibuffer was entered from and, if it is different, the frame +that owns the minibuffer window. This means that if, for example, a +user splits a window while getting input from the minibuffer on the same +frame, that split will be undone when exiting the minibuffer. + +If this option is @code{nil}, no such restorations are done. Hence, the +window split mentioned above will persist after exiting the minibuffer. +@end defvar + @node Object from Minibuffer @section Reading Lisp Objects with the Minibuffer @cindex minibuffer input, reading lisp objects @@ -701,8 +721,9 @@ A history list for numbers read by @code{read-number}. @end defvar @defvar goto-line-history -A history list for arguments to @code{goto-line}. This variable is -buffer local. +A history list for arguments to @code{goto-line}. This variable can +be made local in every buffer by customizing the user option +@code{goto-line-history-local}. @end defvar @c Less common: coding-system-history, input-method-history, @@ -971,16 +992,19 @@ and @var{suffix} holds the text after point. Normally completion operates on the whole string, so for all normal collections, this will always return @code{(0 . (length -@var{suffix}))}. But more complex completion such as completion on -files is done one field at a time. For example, completion of +@var{suffix}))}. But more complex completion, such as completion on +files, is done one field at a time. For example, completion of @code{"/usr/sh"} will include @code{"/usr/share/"} but not @code{"/usr/share/doc"} even if @code{"/usr/share/doc"} exists. Also @code{all-completions} on @code{"/usr/sh"} will not include @code{"/usr/share/"} but only @code{"share/"}. So if @var{string} is @code{"/usr/sh"} and @var{suffix} is @code{"e/doc"}, -@code{completion-boundaries} will return @code{(5 . 1)} which tells us +@code{completion-boundaries} will return @w{@code{(5 . 1)}} which tells us that the @var{collection} will only return completion information that pertains to the area after @code{"/usr/"} and before @code{"/doc"}. +@code{try-completion} is not affected by nontrivial boundaries; e.g., +@code{try-completion} on @code{"/usr/sh"} might still return +@code{"/usr/share/"}, not @code{"share/"}. @end defun If you store a completion alist in a variable, you should mark the @@ -1108,9 +1132,10 @@ The function @code{completing-read} uses @code{minibuffer-local-must-match-map} if @var{require-match} is non-@code{nil}. @xref{Completion Commands}. -The argument @var{history} specifies which history list variable to use for -saving the input and for minibuffer history commands. It defaults to -@code{minibuffer-history}. @xref{Minibuffer History}. +The argument @var{history} specifies which history list variable to +use for saving the input and for minibuffer history commands. It +defaults to @code{minibuffer-history}. If @var{history} is the symbol +@code{t}, history is not recorded. @xref{Minibuffer History}. The argument @var{initial} is mostly deprecated; we recommend using a non-@code{nil} value only in conjunction with specifying a cons cell @@ -1175,9 +1200,9 @@ in the minibuffer to do completion. @defvar minibuffer-completion-table The value of this variable is the completion table (@pxref{Basic Completion}) used for completion in the minibuffer. This is the -global variable that contains what @code{completing-read} passes to +buffer-local variable that contains what @code{completing-read} passes to @code{try-completion}. It is used by minibuffer completion commands -such as @code{minibuffer-complete-word}. +such as @code{minibuffer-complete}. @end defvar @defvar minibuffer-completion-predicate @@ -1188,7 +1213,7 @@ minibuffer completion functions. @defvar minibuffer-completion-confirm This variable determines whether Emacs asks for confirmation before -exiting the minibuffer; @code{completing-read} binds this variable, +exiting the minibuffer; @code{completing-read} sets this variable, and the function @code{minibuffer-complete-and-exit} checks the value before exiting. If the value is @code{nil}, confirmation is not required. If the value is @code{confirm}, the user may exit with an @@ -1806,12 +1831,10 @@ default to that string. @item :affixation-function The value should be a function to add prefixes and suffixes to completions. This function must accept one argument, a list of -completions, and should return such a list of completions where -each element contains a list of three elements: a completion, -a prefix string, and a suffix string. When this function -returns a list of two elements, it is interpreted as a list -of a completion and a suffix string like in @code{:annotation-function}. -This function takes priority over @code{:annotation-function}. +completions, and should return a list of annotated completions. Each +element of the returned list must be a three-element list, the +completion, a prefix string, and a suffix string. This function takes +priority over @code{:annotation-function}. @item :exit-function The value should be a function to run after performing completion. @@ -1884,6 +1907,13 @@ should return @code{(boundaries @var{start} . @var{end})}, where string, and @var{end} is the position of the end boundary in @var{suffix}. +If a Lisp program returns nontrivial boundaries, it should make sure that the +@code{all-completions} operation is consistent with them. The +completions returned by @code{all-completions} should only pertain to +the piece of the prefix and suffix covered by the completion +boundaries. @xref{Basic Completion}, for the precise expected semantics +of completion boundaries. + @item metadata This specifies a request for information about the state of the current completion. The return value should have the form @@ -1922,10 +1952,18 @@ completions. The function should take one argument, return such a list of @var{completions} where each element contains a list of three elements: a completion, a prefix which is displayed before the completion string in the @file{*Completions*} buffer, and -a suffix displayed after the completion string. When this function -returns a list of two elements, it is interpreted as a list of -a completion and a suffix string like in @code{annotation-function}. -This function takes priority over @code{annotation-function}. +a suffix displayed after the completion string. This function +takes priority over @code{annotation-function}. + +@item group-function +The value should be a function for grouping the completion candidates. +The function must take two arguments, @var{completion}, which is a +completion candidate and @var{transform}, which is a boolean flag. If +@var{transform} is @code{nil}, the function must return the group +title of the group to which the candidate belongs. The returned title +can also be @code{nil}. Otherwise the function must return the +transformed candidate. The transformation can for example remove a +redundant prefix, which is displayed in the group title. @item display-sort-function The value should be a function for sorting completions. The function @@ -1962,7 +2000,7 @@ was entered. The return value of @code{completion-table-dynamic} is a function that can be used as the 2nd argument to @code{try-completion} and @code{all-completions}. Note that this function will always return -empty metadata and trivial boundaries (@pxref{Programmed Completion}). +empty metadata and trivial boundaries. @end defun @defun completion-table-with-cache function &optional ignore-case @@ -2219,9 +2257,10 @@ This function asks the user a series of questions, reading a single-character answer in the echo area for each one. The value of @var{list} specifies the objects to ask questions about. -It should be either a list of objects or a generator function. If it is -a function, it should expect no arguments, and should return either the -next object to ask about, or @code{nil}, meaning to stop asking questions. +It should be either a list of objects or a generator function. If it +is a function, it will be called with no arguments, and should return +either the next object to ask about, or @code{nil}, meaning to stop +asking questions. The argument @var{prompter} specifies how to ask each question. If @var{prompter} is a string, the question text is computed like this: @@ -2232,19 +2271,20 @@ The argument @var{prompter} specifies how to ask each question. If @noindent where @var{object} is the next object to ask about (as obtained from -@var{list}). +@var{list}). @xref{Formatting Strings}, for more information about +@code{format}. -If not a string, @var{prompter} should be a function of one argument -(the next object to ask about) and should return the question text. If -the value is a string, that is the question to ask the user. The -function can also return @code{t}, meaning do act on this object (and -don't ask the user), or @code{nil}, meaning ignore this object (and don't -ask the user). +If @var{prompter} is not a string, it should be a function of one +argument (the object to ask about) and should return the question text +for that object. If the value @var{prompter} returns is a string, +that is the question to ask the user. The function can also return +@code{t}, meaning to act on this object without asking the user, or +@code{nil}, which means to silently ignore this object. -The argument @var{actor} says how to act on the answers that the user -gives. It should be a function of one argument, and it is called with -each object that the user says yes for. Its argument is always an -object obtained from @var{list}. +The argument @var{actor} says how to act on the objects for which the +user answers yes. It should be a function of one argument, and will +be called with each object from @var{list} for which the user answers +yes. If the argument @var{help} is given, it should be a list of this form: @@ -2254,34 +2294,49 @@ If the argument @var{help} is given, it should be a list of this form: @noindent where @var{singular} is a string containing a singular noun that -describes the objects conceptually being acted on, @var{plural} is the +describes a single object to be acted on, @var{plural} is the corresponding plural noun, and @var{action} is a transitive verb -describing what @var{actor} does. +describing what @var{actor} does with the objects. -If you don't specify @var{help}, the default is @code{("object" -"objects" "act on")}. +If you don't specify @var{help}, it defaults to the list +@w{@code{("object" "objects" "act on")}}. -Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or -@key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip -that object; @kbd{!} to act on all following objects; @key{ESC} or -@kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on -the current object and then exit; or @kbd{C-h} to get help. These are -the same answers that @code{query-replace} accepts. The keymap -@code{query-replace-map} defines their meaning for @code{map-y-or-n-p} -as well as for @code{query-replace}; see @ref{Search and Replace}. +Each time a question is asked, the user can answer as follows: + +@table @asis +@item @kbd{y}, @kbd{Y}, or @kbd{@key{SPC}} +act on the object +@item @kbd{n}, @kbd{N}, or @kbd{@key{DEL}} +skip the object +@item @kbd{!} +act on all the following objects +@item @kbd{@key{ESC}} or @kbd{q} +exit (skip all following objects) +@item @kbd{.} (period) +act on the object and then exit +@item @kbd{C-h} +get help +@end table + +@noindent +These are the same answers that @code{query-replace} accepts. The +keymap @code{query-replace-map} defines their meaning for +@code{map-y-or-n-p} as well as for @code{query-replace}; see +@ref{Search and Replace}. You can use @var{action-alist} to specify additional possible answers -and what they mean. It is an alist of elements of the form -@code{(@var{char} @var{function} @var{help})}, each of which defines one -additional answer. In this element, @var{char} is a character (the +and what they mean. If provided, @var{action-alist} should be an +alist whose elements are of the form @w{@code{(@var{char} +@var{function} @var{help})}}. Each of the alist elements defines one +additional answer. In each element, @var{char} is a character (the answer); @var{function} is a function of one argument (an object from -@var{list}); @var{help} is a string. - -When the user responds with @var{char}, @code{map-y-or-n-p} calls -@var{function}. If it returns non-@code{nil}, the object is considered -acted upon, and @code{map-y-or-n-p} advances to the next object in -@var{list}. If it returns @code{nil}, the prompt is repeated for the -same object. +@var{list}); and @var{help} is a string. When the user responds with +@var{char}, @code{map-y-or-n-p} calls @var{function}. If it returns +non-@code{nil}, the object is considered to have been acted upon, and +@code{map-y-or-n-p} advances to the next object in @var{list}. If it +returns @code{nil}, the prompt is repeated for the same object. If +the user requests help, the text in @var{help} is used to describe +these additional answers. Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while prompting. But if @var{no-cursor-in-echo-area} is non-@code{nil}, it @@ -2393,7 +2448,7 @@ minibuffer. @deffn Command exit-minibuffer This command exits the active minibuffer. It is normally bound to keys in minibuffer local keymaps. The command throws an error if the -current buffer is not the active minibuffer. +current buffer is a minibuffer, but not the active minibuffer. @end deffn @deffn Command self-insert-and-exit @@ -2474,7 +2529,6 @@ usual minibuffer input functions because they all start by choosing the minibuffer window according to the selected frame. @end defun -@c Emacs 19 feature @defun window-minibuffer-p &optional window This function returns @code{t} if @var{window} is a minibuffer window. @var{window} defaults to the selected window. @@ -2618,7 +2672,6 @@ when the minibuffer is active, not even if you switch to another window to do it. @end defopt -@c Emacs 19 feature If a command name has a property @code{enable-recursive-minibuffers} that is non-@code{nil}, then the command can use the minibuffer to read arguments even if it is invoked from the minibuffer. A command can |