X-Git-Url: http://git.hcoop.net/bpt/emacs.git/blobdiff_plain/637821cd30f9bd3b523d032e2dda22ffee853d51..acaf905b1130aae80fa59d2c861ffd4c8eb75486:/doc/lispref/minibuf.texi diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 841c882318..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} @@ -646,9 +645,9 @@ 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 completion function (@pxref{Programmed -Completion}). +@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 no permissible @@ -659,11 +658,11 @@ 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 @@ -679,7 +678,7 @@ 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}. +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} @@ -812,6 +811,7 @@ unpredictable. If @var{collection} is a function, it is called with three arguments, 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} @@ -837,12 +837,13 @@ 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 @@ -1220,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 @@ -1382,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}. @@ -1440,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 @@ -1631,12 +1631,12 @@ 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}. Emacs uses -programmed completion when completing file names (@pxref{File Name -Completion}), among many other cases. + 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 function as the @var{collection} argument to @code{completing-read}. The function @@ -1664,7 +1664,7 @@ specifies which method to run. @end itemize There are currently four methods, i.e. four flag values, one for - each of the four different basic operations: +each of the four different basic operations: @itemize @bullet @item @@ -1690,19 +1690,11 @@ match for some possibility; @code{nil} otherwise. @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 +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 - 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. - @defun completion-table-dynamic function This function is a convenient way to write a function that can act as programmed completion function. The argument @var{function} should be @@ -2199,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