comparison lispref/minibuf.texi @ 21682:90da2489c498

*** empty log message ***

21681:11eafe90b842

  A @dfn{minibuffer} is a special buffer that Emacs commands use to read
arguments more complicated than the single numeric prefix argument.
These arguments include file names, buffer names, and command names (as
in @kbd{M-x}).  The minibuffer is displayed on the bottom line of the
screen, in the same place as the echo area, but only while it is in
use for reading an argument.

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

The first thing this function does is to activate a minibuffer and 
display it with @var{prompt-string} as the prompt.  This value must be a
string.

Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end.  The
minibuffer appears with this text as its contents.

@strong{Usage note:} The @var{initial-contents} argument and the
@var{default} argument are two alternative features for the same job.
It usually does not make sense to use both at once.  In most cases, you
should use @var{default}, since this permits the user to insert the
default value but does not burden the user with deleting it from the
minibuffer.

@c Emacs 19 feature
The value of @var{initial-contents} may also be a cons cell of the form
@code{(@var{string} . @var{position})}.  This means to insert
@var{string} in the minibuffer but put point @var{position} characters
from the beginning, rather than at the end.

If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
value of @code{minibuffer-local-map} is used as the keymap.  Specifying
a keymap is the most important way to customize the minibuffer for

The argument @var{hist} specifies which history list variable to use
for saving the input and for history commands used in the minibuffer.
It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.

When the user types a command to exit the minibuffer,
@code{read-from-minibuffer} uses the text in the minibuffer to produce
its return value.  Normally it simply makes a string containing that
text.  However, if @var{read} is non-@code{nil},
@code{read-from-minibuffer} reads the text and returns the resulting
Lisp object, unevaluated.  (@xref{Input Functions}, for information
about reading.)

If the variable @code{minibuffer-allow-text-properties} is
non-@code{nil}, then the string which is returned includes whatever text
properties were present in the minibuffer.  Otherwise all the text
properties are stripped when the value is returned.

The argument @var{default} specifies a default value to make available
through the history list.  It should be a string, or @code{nil}.  If
@var{read} is non-@code{nil}, then @var{default} is passed through
@code{read}, just as ordinary user input would be.  Unlike many other
minibuffer functions, this function does @emph{not} return @var{default}
if the user enters empty input.  It returns @code{""} in that case.

If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.
@end defun

@defun read-string prompt &optional initial history default inherit-input-method
This function reads a string from the minibuffer and returns it.  The
arguments @var{prompt} and @var{initial} are used as in

@smallexample
@group
(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil nil
                      @var{history} @var{default} @var{inherit})
@end group
@end smallexample
@end defun

@defvar minibuffer-allow-text-properties

@defvar minibuffer-local-map
This is the default local keymap for reading from the minibuffer.  By
default, it makes the following bindings:

@table @asis
@item @key{LFD}
@code{exit-minibuffer}

@item @key{RET}
@code{exit-minibuffer}

@node Minibuffer History
@section Minibuffer History
@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.

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.

The basic minibuffer input functions @code{read-from-minibuffer} and
@code{completing-read} both accept an optional argument named @var{hist}
which is how you specify the history list.  Here are the possible
values:

@table @asis

If you specify @var{startpos}, then you should also specify that element
of the history as the initial minibuffer contents, for consistency.
@end table

If you don't specify @var{hist}, then the default history list
@code{minibuffer-history} is used.  For other standard history lists,
see below.  You can also create your own history list variable; just
initialize it to @code{nil} before the first use.

Both @code{read-from-minibuffer} and @code{completing-read} add new
elements to the history list automatically, and provide commands to
allow the user to reuse items on the list.  The only thing your program
needs to do to use a history list is to initialize it and to pass its
name to the input functions when you wish.  But it is safe to modify the
list by hand when the minibuffer input functions are not using it.

@defvar minibuffer-history
The default history list for minibuffer history input.
@end defvar

@end smallexample
@end defun

@defun all-completions string collection &optional predicate nospace
This function returns a list of all possible completions of
@var{string}.  The parameters to this function are the same as to
@code{try-completion}.

If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
returns whatever the function returns.  @xref{Programmed Completion}.

minibuffer with completion.

@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
This function reads a string in the minibuffer, assisting the user by
providing completion.  It activates the minibuffer with prompt
@var{prompt}, which must be a string.  If @var{initial} is
non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
part of the input.  Then it allows the user to edit the input, providing
several commands to attempt completion.

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.

@code{nil} nor @code{t}, then the exit commands won't exit unless the
input already in the buffer matches an element of @var{collection}.

However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns
@var{default}.

The user can exit with null input by typing @key{RET} with an empty
minibuffer.  Then @code{completing-read} returns @code{""}.  This is how
the user requests whatever default the command uses for the value being
read.  The user can return using @key{RET} in this way regardless of the

The argument @var{hist} 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 optional argument @var{default} specifies a default value to return
if the user enters null input; it should be a string.

If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.  @xref{Input Methods,,, emacs, The GNU

@code{minibuffer-complete-word}

@item @key{TAB}
@code{minibuffer-complete}

@item @key{LFD}
@code{minibuffer-complete-and-exit}

@item @key{RET}
@code{minibuffer-complete-and-exit}
@end table

@code{read-from-minibuffer}.  Recall that a command is anything for
which @code{commandp} returns @code{t}, and a command name is a symbol
for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.

The argument @var{default} specifies what to return if the user enters
null input.  It can be a symbol or a string, but the value returned by
@code{read-command} is always a symbol.  If @var{default} is @code{nil},
that means no default has been specified; then if the user enters null
input, the return value is @code{nil}.

@example
(read-command "Command name? ")

@group

@defun read-variable prompt &optional default
This function reads the name of a user variable and returns it as a
symbol.

The argument @var{default} specifies what to return if the user enters
null input.  It can be a symbol or a string, but the value returned by
@code{read-variable} is always a symbol.  If @var{default} is
@code{nil}, that means no default has been specified; then if the user
enters null input, the return value is @code{nil}.

@example
@group
(read-variable "Variable name? ")

                  'user-variable-p t nil))
@end group
@end example
@end defun

@tindex read-coding-system
@defun read-coding-system prompt default
This function reads a coding system using the minibuffer, prompting with
string @var{prompt}, and returns the coding system name as a symbol.  If
the user tries to enter null input, it asks the user to try again.
@xref{Coding Systems}.
@end defun

@tindex read-non-nil-coding-system
@defun read-non-nil-coding-system prompt
This function reads a coding system using the minibuffer, prompting with
string @var{prompt},and returns the coding system name as a symbol.  If
the user enters null input, it returns @var{default-coding-system}.
which should be a symbol or a string.  @xref{Coding Systems}.
@end defun

@node Reading File Names
@subsection Reading File Names

  Here is another high-level completion function, designed for reading a

@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert in
the buffer (after with @var{directory}, if that is inserted).  In this
case, point goes at the beginning of @var{initial}.  The default for
@var{initial} is @code{nil}---don't insert any file name.  To see what
@var{initial} does, try the command @kbd{C-x C-v}.

Here is an example: 

@example
@group

should return the completion of the specified string, or @code{t} if the
string is a unique and exact match already, or @code{nil} if the string
matches no possibility.

If the string is an exact match for one possibility, but also matches
other longer possibilities, the function shuold return the string, not
@code{t}.

@item
@code{t} specifies @code{all-completions}.  The completion function
should return a list of all possible completions of the specified

returns zero.
@end defun

@defopt enable-recursive-minibuffers
If this variable is non-@code{nil}, you can invoke commands (such as
@code{find-file}) that use minibuffers even while in the minibuffer
window.  Such invocation produces a recursive editing level for a new
minibuffer.  The outer-level minibuffer is invisible while you are
editing the inner one.

This variable only affects invoking the minibuffer while the
minibuffer window is selected.   If you switch windows while in the 
minibuffer, you can always invoke minibuffer commands while some other
window is selected.
@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

21682:90da2489c498

  A @dfn{minibuffer} is a special buffer that Emacs commands use to read
arguments more complicated than the single numeric prefix argument.
These arguments include file names, buffer names, and command names (as
in @kbd{M-x}).  The minibuffer is displayed on the bottom line of the
frame, in the same place as the echo area, but only while it is in use
for reading an argument.

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

The first thing this function does is to activate a minibuffer and
display it with @var{prompt-string} as the prompt.  This value must be a
string.  Then the user can edit text in the minibuffer.

When the user types a command to exit the minibuffer,
@code{read-from-minibuffer} constructs the return value from the text in
the minibuffer.  Normally it returns a string containing that text.
However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
reads the text and returns the resulting Lisp object, unevaluated.
(@xref{Input Functions}, for information about reading.)

The argument @var{default} specifies a default value to make available
through the history commands.  It should be a string, or @code{nil}.  If
@var{read} is non-@code{nil}, then @var{default} is also used as the
input to @code{read}, if the user enters empty input.  However, in the
usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
does not return @var{default} when the user enters empty input; it
returns an empty string, @code{""}.  In this respect, it is different
from all the other minibuffer input functions in this chapter.

If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
value of @code{minibuffer-local-map} is used as the keymap.  Specifying
a keymap is the most important way to customize the minibuffer for

The argument @var{hist} specifies which history list variable to use
for saving the input and for history commands used in the minibuffer.
It defaults to @code{minibuffer-history}.  @xref{Minibuffer History}.

If the variable @code{minibuffer-allow-text-properties} is
non-@code{nil}, then the string which is returned includes whatever text
properties were present in the minibuffer.  Otherwise all the text
properties are stripped when the value is returned.

If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.

If @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end, before the
user starts to edit the text.  The minibuffer appears with this text as
its initial contents.

Alternatively, @var{initial-contents} can be a cons cell of the form
@code{(@var{string} . @var{position})}.  This means to insert
@var{string} in the minibuffer but put point @var{position} characters
from the beginning, rather than at the end.

@strong{Usage note:} The @var{initial-contents} argument and the
@var{default} argument are two alternative features for more or less the
same job.  It does not make sense to use both features in a single call
to @code{read-from-minibuffer}.  In general, we recommend using
@var{default}, since this permits the user to insert the default value
when it is wanted, but does not burden the user with deleting it from
the minibuffer on other occasions.
@end defun

@defun read-string prompt &optional initial history default inherit-input-method
This function reads a string from the minibuffer and returns it.  The
arguments @var{prompt} and @var{initial} are used as in

@smallexample
@group
(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
@equiv{}
(let ((value
       (read-from-minibuffer @var{prompt} @var{initial} nil nil
                             @var{history} @var{default} @var{inherit})))
  (if (equal value "")
      @var{default}
    value))
@end group
@end smallexample
@end defun

@defvar minibuffer-allow-text-properties

@defvar minibuffer-local-map
This is the default local keymap for reading from the minibuffer.  By
default, it makes the following bindings:

@table @asis
@item @kbd{C-j}
@code{exit-minibuffer}

@item @key{RET}
@code{exit-minibuffer}

@node Minibuffer History
@section Minibuffer History
@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.

  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.

  The basic minibuffer input functions @code{read-from-minibuffer} and
@code{completing-read} both accept an optional argument named @var{hist}
which is how you specify the history list.  Here are the possible
values:

@table @asis

If you specify @var{startpos}, then you should also specify that element
of the history as the initial minibuffer contents, for consistency.
@end table

  If you don't specify @var{hist}, then the default history list
@code{minibuffer-history} is used.  For other standard history lists,
see below.  You can also create your own history list variable; just
initialize it to @code{nil} before the first use.

  Both @code{read-from-minibuffer} and @code{completing-read} add new
elements to the history list automatically, and provide commands to
allow the user to reuse items on the list.  The only thing your program
needs to do to use a history list is to initialize it and to pass its
name to the input functions when you wish.  But it is safe to modify the
list by hand when the minibuffer input functions are not using it.

  Here are some of the standard minibuffer history list variables:

@defvar minibuffer-history
The default history list for minibuffer history input.
@end defvar

@end smallexample
@end defun

@defun all-completions string collection &optional predicate nospace
This function returns a list of all possible completions of
@var{string}.  The arguments to this function are the same as those of
@code{try-completion}.

If @var{collection} is a function, it is called with three arguments:
@var{string}, @var{predicate} and @code{t}; then @code{all-completions}
returns whatever the function returns.  @xref{Programmed Completion}.

minibuffer with completion.

@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
This function reads a string in the minibuffer, assisting the user by
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.

@code{nil} nor @code{t}, then the exit commands won't exit unless the
input already in the buffer matches an element of @var{collection}.

However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns
@var{default}.  The value of @var{default} (if non-@code{nil}) is also
available to the user through the history commands.

The user can exit with null input by typing @key{RET} with an empty
minibuffer.  Then @code{completing-read} returns @code{""}.  This is how
the user requests whatever default the command uses for the value being
read.  The user can return using @key{RET} in this way regardless of the

The argument @var{hist} 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}.

If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
into the minibuffer as part of the input.  Then it allows the user to
edit the input, providing several commands to attempt completion.
In most cases, we recommend using @var{default}, and not @var{initial}.

If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.  @xref{Input Methods,,, emacs, The GNU

@code{minibuffer-complete-word}

@item @key{TAB}
@code{minibuffer-complete}

@item @kbd{C-j}
@code{minibuffer-complete-and-exit}

@item @key{RET}
@code{minibuffer-complete-and-exit}
@end table

@code{read-from-minibuffer}.  Recall that a command is anything for
which @code{commandp} returns @code{t}, and a command name is a symbol
for which @code{commandp} returns @code{t}.  @xref{Interactive Call}.

The argument @var{default} specifies what to return if the user enters
null input.  It can be a symbol or a string; if it is a string,
@code{read-command} interns it before returning it.  If @var{default} is
@code{nil}, that means no default has been specified; then if the user
enters null input, the return value is @code{nil}.

@example
(read-command "Command name? ")

@group

@defun read-variable prompt &optional default
This function reads the name of a user variable and returns it as a
symbol.

The argument @var{default} specifies what to return if the user enters
null input.  It can be a symbol or a string; if it is a string,
@code{read-variable} interns it before returning it.  If @var{default}
is @code{nil}, that means no default has been specified; then if the
user enters null input, the return value is @code{nil}.

@example
@group
(read-variable "Variable name? ")

                  'user-variable-p t nil))
@end group
@end example
@end defun

  See also the functions @code{read-coding-system} and
@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}.

@node Reading File Names
@subsection Reading File Names

  Here is another high-level completion function, designed for reading a

@c Emacs 19 feature
If you specify @var{initial}, that is an initial file name to insert in
the buffer (after with @var{directory}, if that is inserted).  In this
case, point goes at the beginning of @var{initial}.  The default for
@var{initial} is @code{nil}---don't insert any file name.  To see what
@var{initial} does, try the command @kbd{C-x C-v}.  @strong{Note:} we
recommend using @var{default} rather than @var{initial} in most cases.

Here is an example: 

@example
@group

should return the completion of the specified string, or @code{t} if the
string is a unique and exact match already, or @code{nil} if the string
matches no possibility.

If the string is an exact match for one possibility, but also matches
other longer possibilities, the function should return the string, not
@code{t}.

@item
@code{t} specifies @code{all-completions}.  The completion function
should return a list of all possible completions of the specified

returns zero.
@end defun

@defopt enable-recursive-minibuffers
If this variable is non-@code{nil}, you can invoke commands (such as
@code{find-file}) that use minibuffers even while the minibuffer window
is active.  Such invocation produces a recursive editing level for a new
minibuffer.  The outer-level minibuffer is invisible while you are
editing the inner one.

If this variable is @code{nil}, you cannot invoke minibuffer
commands when the minibuffer window 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