@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 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
* 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.
marked as a field (@pxref{Fields}), so that certain motion functions,
including @code{beginning-of-line}, @code{forward-word},
@code{forward-sentence}, and @code{forward-paragraph}, stop at the
-boundary between the prompt and the actual text. (In older Emacs
-versions, the prompt was displayed using a special mechanism and was not
-part of the buffer contents.)
+boundary between the prompt and the actual text.
The minibuffer's window is normally a single line; it grows
-automatically if necessary if the contents require more space. You can
-explicitly resize it temporarily with the window sizing commands; it
-reverts to its normal size when the minibuffer is exited. You can
-resize it permanently by using the window sizing commands in the frame's
-other window, when the minibuffer is not active. If the frame contains
-just a minibuffer, you can change the minibuffer's size by changing the
+automatically if the contents require more space. You can explicitly
+resize it temporarily with the window sizing commands; it reverts to
+its normal size when the minibuffer is exited. You can resize it
+permanently by using the window sizing commands in the frame's other
+window, when the minibuffer is not active. If the frame contains just
+a minibuffer, you can change the minibuffer's size by changing the
frame's size.
Use of the minibuffer reads input events, and that alters the values
(@pxref{Command Loop Info}). Your program should bind them around the
code that uses the minibuffer, if you do not want that to change them.
- If a command uses a minibuffer while there is an active minibuffer,
-this is called a @dfn{recursive minibuffer}. The first minibuffer is
-named @w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
-incrementing the number at the end of the name. (The names begin with a
-space so that they won't show up in normal buffer lists.) Of several
-recursive minibuffers, the innermost (or most recently entered) is the
-active minibuffer. We usually call this ``the'' minibuffer. You can
-permit or forbid recursive minibuffers by setting the variable
-@code{enable-recursive-minibuffers} or by putting properties of that
-name on command symbols (@pxref{Recursive Mini}).
+ Under some circumstances, a command can use a minibuffer even if
+there is an active minibuffer; such minibuffers are called a
+@dfn{recursive minibuffer}. The first minibuffer is named
+@w{@samp{ *Minibuf-0*}}. Recursive minibuffers are named by
+incrementing the number at the end of the name. (The names begin with
+a space so that they won't show up in normal buffer lists.) Of
+several recursive minibuffers, the innermost (or most recently
+entered) is the active minibuffer. We usually call this ``the''
+minibuffer. You can permit or forbid recursive minibuffers by setting
+the variable @code{enable-recursive-minibuffers}, or by putting
+properties of that name on command symbols (@xref{Recursive Mini}.)
Like other buffers, a minibuffer uses a local keymap
(@pxref{Keymaps}) to specify special key bindings. The function that
@node Text from Minibuffer
@section Reading Text Strings with the Minibuffer
- Most often, the minibuffer is used to read text as a string. It can
-also be used to read a Lisp object in textual form. The most basic
-primitive for minibuffer input is @code{read-from-minibuffer}; it can
-do either one. Regular expressions (@pxref{Regular Expressions}) are
-a special kind of strings; use @code{read-regexp} for their minibuffer
-input. There are also specialized commands for reading commands,
-variables, file names, etc.@: (@pxref{Completion}).
+ The most basic primitive for minibuffer input is
+@code{read-from-minibuffer}, which can be used to read either a string
+or a Lisp object in textual form. The function @code{read-regexp} is
+used for reading regular expressions (@pxref{Regular Expressions}),
+which are a special kind of string. There are also specialized
+functions for reading commands, variables, file names, etc.@:
+(@pxref{Completion}).
In most cases, you should not call minibuffer input functions in the
middle of a Lisp function. Instead, do all minibuffer input as part of
specification. @xref{Defining Commands}.
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
-This function is the most general way to get input through the
+This function is the most general way to get input from the
minibuffer. By default, it accepts arbitrary text and returns it as a
string; however, if @var{read} is non-@code{nil}, then it uses
@code{read} to convert the text into a Lisp object (@pxref{Input
@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}
set to a non-@code{nil} value.
@end defvar
-@defvar history-length
+@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.
-@end defvar
+@end defopt
-@defvar history-delete-duplicates
+@defopt history-delete-duplicates
If the value of this variable is @code{t}, that means when adding a
new history element, all previous identical elements are deleted.
-@end defvar
+@end defopt
Here are some of the standard minibuffer history list variables:
@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
- (reading buffer name, file name, etc.)
+ (reading buffer name, file name, etc.).
* Reading File Names:: Using completion to read file names and
shell commands.
* Completion Styles:: Specifying rules for performing 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
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
@var{string}. The arguments to this function (aside from
@var{nospace}) are the same as those of @code{try-completion}. Also,
this function uses @code{completion-regexp-list} in the same way that
-@code{try-completion} does. The optional argument @var{nospace} only
-matters if @var{string} is the empty string. In that case, if
-@var{nospace} is non-@code{nil}, completions that start with a space
-are ignored.
+@code{try-completion} does.
+
+The optional argument @var{nospace} is obsolete. If it is
+non-@code{nil}, completions that start with a space are ignored unless
+@var{string} starts with a space.
If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
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
@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
@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:
@end example
@end defun
-@defvar 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.
-@end defvar
+@defopt read-buffer-function
+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
-@defvar read-buffer-completion-ignore-case
+@defopt read-buffer-completion-ignore-case
If this variable is non-@code{nil}, @code{read-buffer} ignores case
when performing completion.
-@end defvar
+@end defopt
@defun read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp
except that empty color names are allowed when @code{allow-empty} is
non-@code{nil} and the user enters null input.
-Interactively, or when @var{display} is non-@code{nill}, the return
+Interactively, or when @var{display} is non-@code{nil}, the return
value is also displayed in the echo area.
@end deffn
@cindex read file names
@cindex prompt for file name
- Here is a couple of other high-level completion functions, designed
-for reading file names and shell commands. They provide special
-features including automatic insertion of the default directory.
+ The high-level completion functions @code{read-file-name},
+@code{read-directory-name}, and @code{read-shell-command} are designed
+to read file names, directory names, and shell commands respectively.
+They provide special features, including automatic insertion of the
+default directory.
@defun read-file-name prompt &optional directory default require-match initial predicate
-This function reads a file name in the minibuffer, prompting with
-@var{prompt} and providing completion.
+This function reads a file name, prompting with @var{prompt} and
+providing completion.
+
+As an exception, this function reads a file name using a graphical
+file dialog instead of the minibuffer, if (i) it is invoked via a
+mouse command, and (ii) the selected frame is on a graphical display
+supporting such dialogs, and (iii) the variable @code{use-dialog-box}
+is non-@code{nil} (@pxref{Dialog Boxes,, Dialog Boxes, emacs, The GNU
+Emacs Manual}), and (iv) the @var{directory} argument, described
+below, does not specify a remote file (@pxref{Remote Files,, Remote
+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.
+
+@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.
The optional argument @var{require-match} has the same meaning as in
-@code{completing-read}. @xref{Minibuffer Completion}.
-
-@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}.
+@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}.
-@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert
in the buffer (after @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
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
doing its usual work.
@end defvar
-@defvar read-file-name-completion-ignore-case
+@defopt read-file-name-completion-ignore-case
If this variable is non-@code{nil}, @code{read-file-name} ignores case
when performing completion.
-@end defvar
+@end defopt
@defun read-directory-name prompt &optional directory default require-match initial
This function is like @code{read-file-name} but allows only directory
@var{all-completions} functions.
@end defvar
- By default, @code{completion-styles-alist} contains four pre-defined
+ By default, @code{completion-styles-alist} contains five pre-defined
completion styles: @code{basic}, a basic completion style;
@code{partial-completion}, which does partial completion (completing
each word in the input separately); @code{emacs22}, which performs
-completion according to the rules used in Emacs 22; and
-@code{emacs21}, which performs completion according to the rules used
-in Emacs 21.
+completion according to the rules used in Emacs 22; @code{emacs21},
+which performs completion according to the rules used in Emacs 21; and
+@code{initials}, which completes acronyms and initialisms.
@node Programmed Completion
@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:
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
@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
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
frame. If an integer, it specifies a number of lines.
@end defopt
-@defun minibuffer-message string
+@defun minibuffer-message string &rest args
This function displays @var{string} temporarily at the end of the
minibuffer text, for two seconds, or until the next input event
-arrives, whichever comes first.
+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
HCoop / bpt / emacs.git / blobdiff