X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/2db38a6f98c2abb42b746064ce97417cccc27e68..acaf905b1130aae80fa59d2c861ffd4c8eb75486:/doc/lispref/minibuf.texi?ds=sidebyside diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 45335c2983..e300847023 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, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001, 2002, -@c 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. +@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 +@c Free Software Foundation, Inc. @c See the file elisp.texi for copying conditions. @setfilename ../../info/minibuf @node Minibuffers, Command Loop, Read and Print, Top @@ -22,13 +22,13 @@ argument. * Intro to Minibuffers:: Basic information about minibuffers. * Text from Minibuffer:: How to read a straight text string. * Object from Minibuffer:: How to read a Lisp object or expression. -* Minibuffer History:: Recording previous minibuffer inputs - so the user can reuse them. +* Minibuffer History:: Recording previous minibuffer inputs + so the user can reuse them. * Initial Input:: Specifying initial contents for the minibuffer. * Completion:: How to invoke and customize completion. * Yes-or-No Queries:: Asking a question with a simple answer. -* Multiple Queries:: Asking a series of similar questions. -* Reading a Password:: Reading a password from the terminal. +* Multiple Queries:: Asking a series of similar questions. +* Reading a Password:: Reading a password from the terminal. * Minibuffer Commands:: Commands used as key bindings in minibuffers. * Minibuffer Contents:: How such commands access the minibuffer text. * Minibuffer Windows:: Operating on the special minibuffer windows. @@ -433,18 +433,17 @@ expression, thus moving point forward one word. @cindex minibuffer history @cindex history list - A @dfn{minibuffer history list} records previous minibuffer inputs so -the user can reuse them conveniently. A history list is actually a -symbol, not a list; it is a variable whose value is a list of strings -(previous inputs), most recent first. + A @dfn{minibuffer history list} records previous minibuffer inputs +so the user can reuse them conveniently. It is a variable whose value +is a list of strings (previous inputs), most recent first. - There are many separate history lists, used for different kinds of -inputs. It's the Lisp programmer's job to specify the right history -list for each use of the minibuffer. + There are many separate minibuffer history lists, used for different +kinds of inputs. It's the Lisp programmer's job to specify the right +history list for each use of the minibuffer. - You specify the history list with the optional @var{hist} argument -to either @code{read-from-minibuffer} or @code{completing-read}. Here -are the possible values for it: + You specify a minibuffer history list with the optional @var{hist} +argument to @code{read-from-minibuffer} or @code{completing-read}. +Here are the possible values for it: @table @asis @item @var{variable} @@ -511,7 +510,7 @@ set to a non-@code{nil} value. @defopt history-length The value of this variable specifies the maximum length for all history lists that don't specify their own maximum lengths. If the -value is @code{t}, that means there no maximum (don't delete old +value is @code{t}, that means there is no maximum (don't delete old elements). The value of @code{history-length} property of the history list variable's symbol, if set, overrides this variable for that particular history list. @@ -626,7 +625,6 @@ for reading certain kinds of names with completion. @menu * Basic Completion:: Low-level functions for completing strings. - (These are too low level to use the minibuffer.) * Minibuffer Completion:: Invoking the minibuffer with completion. * Completion Commands:: Minibuffer commands that do completion. * High-Level Completion:: Convenient special cases of completion @@ -640,39 +638,31 @@ for reading certain kinds of names with completion. @node Basic Completion @subsection Basic Completion Functions - The completion functions @code{try-completion}, -@code{all-completions} and @code{test-completion} have nothing in -themselves to do with minibuffers. We describe them in this chapter -so as to keep them near the higher-level completion features that do -use the minibuffer. - - If you store a completion alist in a variable, you should mark the -variable as ``risky'' with a non-@code{nil} -@code{risky-local-variable} property. + The following completion functions have nothing in themselves to do +with minibuffers. We describe them here to keep them near the +higher-level completion features that do use the minibuffer. @defun try-completion string collection &optional predicate This function returns the longest common substring of all possible completions of @var{string} in @var{collection}. The value of -@var{collection} must be a list of strings or symbols, an alist, an -obarray, a hash table, or a function that implements a virtual set of -strings (see below). +@var{collection} must be a list of strings, an alist whose keys are +strings or symbols, an obarray, a hash table, or a completion function +(@pxref{Programmed Completion}). Completion compares @var{string} against each of the permissible -completions specified by @var{collection}; if the beginning of the -permissible completion equals @var{string}, it matches. If no permissible -completions match, @code{try-completion} returns @code{nil}. If only -one permissible completion matches, and the match is exact, then -@code{try-completion} returns @code{t}. Otherwise, the value is the -longest initial sequence common to all the permissible completions that -match. +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 +@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, symbols, or conses whose @sc{car} is a string or symbol. +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 or symbols is allowed, even though we usually do not +list of strings is allowed, even though we usually do not think of such lists as alists. @cindex obarray in completion @@ -688,13 +678,13 @@ Also, you cannot intern a given symbol in more than one obarray. If @var{collection} is a hash table, then the keys that are strings are the possible completions. Other keys are ignored. -You can also use a symbol that is a function as @var{collection}. Then -the function is solely responsible for performing completion; +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 +and @code{nil} (the reason for the 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}. +thing in either case). @xref{Programmed Completion}. If the argument @var{predicate} is non-@code{nil}, then it must be a function of one argument, unless @var{collection} is a hash table, in @@ -823,13 +813,37 @@ the values @var{string}, @var{predicate} and @code{lambda}; whatever it returns, @code{test-completion} returns in turn. @end defun +@defun completion-boundaries string collection predicate suffix +This function returns the boundaries of the field on which @var{collection} +will operate, assuming that @var{string} holds the text before point +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 +@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 +that the @var{collection} will only return completion information that +pertains to the area after @code{"/usr/"} and before @code{"/doc"}. +@end defun + +If you store a completion alist in a variable, you should mark the +variable as ``risky'' with a non-@code{nil} +@code{risky-local-variable} property. @xref{File Local Variables}. + @defvar completion-ignore-case -If the value of this variable is non-@code{nil}, Emacs does not -consider case significant in completion. Note, however, that this -variable is overridden by @code{read-file-name-completion-ignore-case} -within @code{read-file-name} (@pxref{Reading File Names}), and by -@code{read-buffer-completion-ignore-case} within @code{read-buffer} -(@pxref{High-Level Completion}). +If the value of this variable is non-@code{nil}, case is not +considered significant in completion. Within @code{read-file-name}, +this variable is overridden by +@code{read-file-name-completion-ignore-case} (@pxref{Reading File +Names}); within @code{read-buffer}, it is overridden by +@code{read-buffer-completion-ignore-case} (@pxref{High-Level +Completion}). @end defvar @defvar completion-regexp-list @@ -855,6 +869,23 @@ Here is an example of use: @end smallexample @end defmac +The function @code{completion-in-region} provides a convenient way to +perform completion on an arbitrary stretch of text in an Emacs buffer: + +@defun completion-in-region start end collection &optional predicate +This function completes the text in the current buffer between the +positions @var{start} and @var{end}, using @var{collection}. The +argument @var{collection} has the same meaning as in +@code{try-completion} (@pxref{Basic Completion}). + +This function inserts the completion text directly into the current +buffer. Unlike @code{completing-read} (@pxref{Minibuffer +Completion}), it does not activate the minibuffer. + +For this function to work, point must be somewhere between @var{start} +and @var{end}. +@end defun + @node Minibuffer Completion @subsection Completion and the Minibuffer @cindex minibuffer completion @@ -869,12 +900,12 @@ providing completion. It activates the minibuffer with prompt @var{prompt}, which must be a string. The actual completion is done by passing @var{collection} and -@var{predicate} to the function @code{try-completion}. This happens -in certain commands bound in the local keymaps used for completion. -Some of these commands also call @code{test-completion}. Thus, if -@var{predicate} is non-@code{nil}, it should be compatible with -@var{collection} and @code{completion-ignore-case}. @xref{Definition -of test-completion}. +@var{predicate} to the function @code{try-completion} (@pxref{Basic +Completion}). This happens in certain commands bound in the local +keymaps used for completion. Some of these commands also call +@code{test-completion}. Thus, if @var{predicate} is non-@code{nil}, +it should be compatible with @var{collection} and +@code{completion-ignore-case}. @xref{Definition of test-completion}. The value of the optional argument @var{require-match} determines how the user may exit the minibuffer: @@ -1190,10 +1221,11 @@ Buffer name (default foo): @point{} @end defun @defopt read-buffer-function -This variable specifies how to read buffer names. 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 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. @end defopt @defopt read-buffer-completion-ignore-case @@ -1352,17 +1384,19 @@ Files, emacs, The GNU Emacs Manual}). The exact behavior when using a graphical file dialog is platform-dependent. Here, we simply document the behavior when using the minibuffer. -The optional argument @var{require-match} has the same meaning as in -@code{completing-read}. @xref{Minibuffer Completion}. +@code{read-file-name} does not automatically expand the returned file +name. You must call @code{expand-file-name} yourself if an absolute +file name is required. -@code{read-file-name} uses -@code{minibuffer-local-filename-completion-map} as the keymap if -@var{require-match} is @code{nil}, and uses -@code{minibuffer-local-filename-must-match-map} if @var{require-match} -is non-@code{nil}. @xref{Completion Commands}. +The optional argument @var{require-match} has the same meaning as in +@code{completing-read}. @xref{Minibuffer Completion}. If +@var{require-match} is @code{nil}, the local keymap in the minibuffer +is @code{minibuffer-local-filename-completion-map}; otherwise, it is +@code{minibuffer-local-filename-must-match-map}. @xref{Completion +Commands}. The argument @var{directory} specifies the directory to use for -completion of relative file names. It should be an absolute directory +completing relative file names. It should be an absolute directory name. If @code{insert-default-directory} is non-@code{nil}, @var{directory} is also inserted in the minibuffer as initial input. It defaults to the current buffer's value of @code{default-directory}. @@ -1410,11 +1444,7 @@ argument that decides which file names are acceptable completion possibilities. A file name is an acceptable value if @var{predicate} returns non-@code{nil} for it. -@code{read-file-name} does not automatically expand file names. You -must call @code{expand-file-name} yourself if an absolute file name is -required. - -Here is an example: +Here is an example of using @code{read-file-name}: @example @group @@ -1601,16 +1631,19 @@ which performs completion according to the rules used in Emacs 21; and @subsection Programmed Completion @cindex programmed completion - Sometimes it is not possible to create an alist or an obarray -containing all the intended possible completions. In such a case, you -can supply your own function to compute the completion of a given string. -This is called @dfn{programmed completion}. + Sometimes it is not possible or convenient to create an alist or +an obarray containing all the intended possible completions ahead +of time. In such a case, you can supply your own function to compute +the completion of a given string. This is called @dfn{programmed +completion}. Emacs uses programmed completion when completing file +names (@pxref{File Name Completion}), among many other cases. - To use this feature, pass a symbol with a function definition as the -@var{collection} argument to @code{completing-read}. The function + To use this feature, pass a function as the @var{collection} +argument to @code{completing-read}. The function @code{completing-read} arranges to pass your completion function along -to @code{try-completion} and @code{all-completions}, which will then let -your function do all the work. +to @code{try-completion}, @code{all-completions}, and other basic +completion functions, which will then let your function do all +the work. The completion function should accept three arguments: @@ -1624,10 +1657,14 @@ none. Your function should call the predicate for each possible match, and ignore the possible match if the predicate returns @code{nil}. @item -A flag specifying the type of operation. +A flag specifying the type of operation. The best way to think about +it is that the function stands for an object (in the +``object-oriented'' sense of the word), and this third argument +specifies which method to run. @end itemize - There are three flag values for three operations: + There are currently four methods, i.e. four flag values, one for +each of the four different basic operations: @itemize @bullet @item @@ -1649,18 +1686,14 @@ string. @code{lambda} specifies @code{test-completion}. The completion function should return @code{t} if the specified string is an exact match for some possibility; @code{nil} otherwise. -@end itemize - It would be consistent and clean for completion functions to allow -lambda expressions (lists that are functions) as well as function -symbols as @var{collection}, but this is impossible. Lists as -completion tables already have other meanings, and it would be -unreliable to treat one differently just because it is also a possible -function. So you must arrange for any function you wish to use for -completion to be encapsulated in a symbol. - - Emacs uses programmed completion when completing file names. -@xref{File Name Completion}. +@item +@code{(boundaries . SUFFIX)} specifies @code{completion-boundaries}. +The function should return a value of the form @code{(boundaries +START . END)} where START is the position of the beginning boundary +in the string to complete, and END is the position of the end boundary +in SUFFIX. +@end itemize @defun completion-table-dynamic function This function is a convenient way to write a function that can act as @@ -1671,6 +1704,19 @@ possible completions of it. You can think of and the interface for programmed completion functions. @end defun +@defvar completion-annotate-function +The value of this variable, if non-@code{nil}, should be a function +for ``annotating'' the entries in the @samp{*Completions*} buffer. +The function should accept a single argument, the completion string +for an entry. It should return an additional string to display next +to that entry in the @samp{*Completions*} buffer, or @code{nil} if no +additional string is to be displayed. + +The function can determine the collection used for the current +completion via the variable @code{minibuffer-completion-table} +(@pxref{Completion Commands}). +@end defvar + @node Yes-or-No Queries @section Yes-or-No Queries @cindex asking the user questions @@ -2145,7 +2191,3 @@ arrives, whichever comes first. If @var{args} is non-@code{nil}, the actual message is obtained by passing @var{string} and @var{args} through @code{format}. @xref{Formatting Strings}. @end defun - -@ignore - arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218 -@end ignore