comparison doc/lispref/minibuf.texi @ 109689:ffde65bb1dd2

merge emacs-23

108493:e5f3704cf67a

@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 See the file elisp.texi for copying conditions.
@setfilename ../../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
@chapter Minibuffers
@cindex arguments, reading

@menu
* 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.
* 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.
* 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.
* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc::           Various customization hooks and variables.

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

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}.

  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}).

  To use this feature, pass a symbol with a function definition 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.

  The completion function should accept three arguments:

@itemize @bullet
@item

The predicate function to filter possible matches, or @code{nil} if
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.
@end itemize

  There are three flag values for three operations:

@itemize @bullet
@item
@code{nil} specifies @code{try-completion}.  The completion function
should return the completion of the specified string, or @code{t} if the

@item
@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

109689:ffde65bb1dd2

@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
@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
@chapter Minibuffers
@cindex arguments, reading

@menu
* 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.
* 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.
* 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.
* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc::           Various customization hooks and variables.

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}
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}.

  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.

  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}, @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:

@itemize @bullet
@item

The predicate function to filter possible matches, or @code{nil} if
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.  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 currently four methods, i.e. four flag values, one for
  each of the four different basic operations:

@itemize @bullet
@item
@code{nil} specifies @code{try-completion}.  The completion function
should return the completion of the specified string, or @code{t} if the

@item
@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.

@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
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