minibuf.texi 103 KB
Newer Older
Glenn Morris's avatar
Glenn Morris committed
1 2
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
Paul Eggert's avatar
Paul Eggert committed
3
@c Copyright (C) 1990-1995, 1998-1999, 2001-2019 Free Software
4
@c Foundation, Inc.
Glenn Morris's avatar
Glenn Morris committed
5
@c See the file elisp.texi for copying conditions.
6
@node Minibuffers
Glenn Morris's avatar
Glenn Morris committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
@chapter Minibuffers
@cindex arguments, reading
@cindex complex arguments
@cindex minibuffer

  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
(@pxref{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.
Glenn Morris's avatar
Glenn Morris committed
24 25
* Minibuffer History::        Recording previous minibuffer inputs
                                so the user can reuse them.
Glenn Morris's avatar
Glenn Morris committed
26 27 28
* 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.
29
* Multiple Queries::          Asking complex questions.
Glenn Morris's avatar
Glenn Morris committed
30
* Reading a Password::        Reading a password from the terminal.
Glenn Morris's avatar
Glenn Morris committed
31 32
* Minibuffer Commands::       Commands used as key bindings in minibuffers.
* Minibuffer Windows::        Operating on the special minibuffer windows.
33
* Minibuffer Contents::       How such commands access the minibuffer text.
Glenn Morris's avatar
Glenn Morris committed
34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57
* Recursive Mini::            Whether recursive entry to minibuffer is allowed.
* Minibuffer Misc::           Various customization hooks and variables.
@end menu

@node Intro to Minibuffers
@section Introduction to Minibuffers

  In most ways, a minibuffer is a normal Emacs buffer.  Most operations
@emph{within} a buffer, such as editing commands, work normally in a
minibuffer.  However, many operations for managing buffers do not apply
to minibuffers.  The name of a minibuffer always has the form @w{@samp{
*Minibuf-@var{number}*}}, and it cannot be changed.  Minibuffers are
displayed only in special windows used only for minibuffers; these
windows always appear at the bottom of a frame.  (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)

  The text in the minibuffer always starts with the @dfn{prompt string},
the text that was specified by the program that is using the minibuffer
to tell the user what sort of input to type.  This text is marked
read-only so you won't accidentally delete or change it.  It is also
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
58
boundary between the prompt and the actual text.
Glenn Morris's avatar
Glenn Morris committed
59

60
@c See https://debbugs.gnu.org/11276
Glenn Morris's avatar
Glenn Morris committed
61
  The minibuffer's window is normally a single line; it grows
62 63 64 65 66 67 68 69 70 71
automatically if the contents require more space.  Whilst the minibuffer
is active, you can explicitly resize its window temporarily with the
window sizing commands; the window reverts to its normal size when the
minibuffer is exited.  When the minibuffer is not active, you can resize
its window permanently by using the window sizing commands in the
frame's other window, or dragging the mode line with the mouse.  (Due to
details of the current implementation, for this to work
@code{resize-mini-windows} must be @code{nil}.)  If the frame contains
just a minibuffer window, you can change its size by changing the
frame's size.
Glenn Morris's avatar
Glenn Morris committed
72 73 74 75 76 77

  Use of the minibuffer reads input events, and that alters the values
of variables such as @code{this-command} and @code{last-command}
(@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.

78
  Under some circumstances, a command can use a minibuffer even if
79
there is an active minibuffer; such a minibuffer is called a
80
@dfn{recursive minibuffer}.  The first minibuffer is named
81
@w{@samp{ *Minibuf-1*}}.  Recursive minibuffers are named by
82 83 84
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
Paul Eggert's avatar
Paul Eggert committed
85
entered) is the active minibuffer.  We usually call this @emph{the}
86 87
minibuffer.  You can permit or forbid recursive minibuffers by setting
the variable @code{enable-recursive-minibuffers}, or by putting
88
properties of that name on command symbols (@xref{Recursive Mini}.)
Glenn Morris's avatar
Glenn Morris committed
89 90 91 92 93 94 95 96

  Like other buffers, a minibuffer uses a local keymap
(@pxref{Keymaps}) to specify special key bindings.  The function that
invokes the minibuffer also sets up its local map according to the job
to be done.  @xref{Text from Minibuffer}, for the non-completion
minibuffer local maps.  @xref{Completion Commands}, for the minibuffer
local maps for completion.

97
@cindex inactive minibuffer
Glenn Morris's avatar
Glenn Morris committed
98
  When a minibuffer is inactive, its major mode is
99 100 101 102
@code{minibuffer-inactive-mode}, with keymap
@code{minibuffer-inactive-mode-map}.  This is only really useful if
the minibuffer is in a separate frame.  @xref{Minibuffers and Frames}.

Glenn Morris's avatar
Glenn Morris committed
103 104
  When Emacs is running in batch mode, any request to read from the
minibuffer actually reads a line from the standard input descriptor that
105
was supplied when Emacs was started.  This supports only basic input:
Paul Eggert's avatar
Paul Eggert committed
106
none of the special minibuffer features (history, completion, etc.)@:
Michael Albinus's avatar
Michael Albinus committed
107
are available in batch mode.
Glenn Morris's avatar
Glenn Morris committed
108 109 110

@node Text from Minibuffer
@section Reading Text Strings with the Minibuffer
111
@cindex minibuffer input, reading text strings
Glenn Morris's avatar
Glenn Morris committed
112

113 114 115 116 117 118 119
  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}).
Glenn Morris's avatar
Glenn Morris committed
120 121 122 123 124 125

  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
reading the arguments for a command, in the @code{interactive}
specification.  @xref{Defining Commands}.

126
@defun read-from-minibuffer prompt &optional initial keymap read history default inherit-input-method
127
This function is the most general way to get input from the
Glenn Morris's avatar
Glenn Morris committed
128 129 130 131 132 133
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
134 135
display it with @var{prompt} (which must be a string) as the
prompt.  Then the user can edit text in the minibuffer.
Glenn Morris's avatar
Glenn Morris committed
136 137 138 139 140 141 142 143

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

Eli Zaretskii's avatar
Eli Zaretskii committed
144
@cindex future history in minibuffer input
145 146 147
The argument @var{default} specifies default values to make available
through the history commands.  It should be a string, a list of
strings, or @code{nil}.  The string or strings become the minibuffer's
148
``future history'', available to the user with @kbd{M-n}.
149

150 151 152 153 154 155 156 157
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.
If @var{default} is a list of strings, the first string is used as the input.
If @var{default} is @code{nil}, empty input results in an @code{end-of-file} error.
However, in the usual case (where @var{read} is @code{nil}),
@code{read-from-minibuffer} ignores @var{default} when the user enters
empty input and returns an empty string, @code{""}.  In this respect,
it differs from all the other minibuffer input functions in this chapter.
Glenn Morris's avatar
Glenn Morris committed
158 159 160 161 162 163 164

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
various applications such as completion.

165
The argument @var{history} specifies a history list variable to use
Glenn Morris's avatar
Glenn Morris committed
166
for saving the input and for history commands used in the minibuffer.
167 168
It defaults to @code{minibuffer-history}.  You can optionally specify
a starting position in the history list as well.  @xref{Minibuffer History}.
Glenn Morris's avatar
Glenn Morris committed
169 170

If the variable @code{minibuffer-allow-text-properties} is
171
non-@code{nil}, then the string that is returned includes whatever text
Glenn Morris's avatar
Glenn Morris committed
172 173 174
properties were present in the minibuffer.  Otherwise all the text
properties are stripped when the value is returned.

Paul Eggert's avatar
Paul Eggert committed
175
@vindex minibuffer-prompt-properties
176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191
The text properties in @code{minibuffer-prompt-properties} are applied
to the prompt.  By default, this property list defines a face to use
for the prompt.  This face, if present, is applied to the end of the
face list and merged before display.

If the user wants to completely control the look of the prompt, the
most convenient way to do that is to specify the @code{default} face
at the end of all face lists.  For instance:

@lisp
(read-from-minibuffer
 (concat
  (propertize "Bold" 'face '(bold default))
  (propertize " and normal: " 'face '(default))))
@end lisp

Glenn Morris's avatar
Glenn Morris committed
192 193 194 195 196 197
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method (@pxref{Input Methods}) and
the setting of @code{enable-multibyte-characters} (@pxref{Text
Representations}) from whichever buffer was current before entering the
minibuffer.

198
Use of @var{initial} is mostly deprecated; we recommend using
Glenn Morris's avatar
Glenn Morris committed
199
a non-@code{nil} value only in conjunction with specifying a cons cell
200
for @var{history}.  @xref{Initial Input}.
Glenn Morris's avatar
Glenn Morris committed
201 202 203 204 205 206 207 208 209 210 211
@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}, @var{initial}, @var{history} and
@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
The keymap used is @code{minibuffer-local-map}.

The optional argument @var{default} is used as in
@code{read-from-minibuffer}, except that, if non-@code{nil}, it also
specifies a default value to return if the user enters null input.  As
212
in @code{read-from-minibuffer} it should be a string, a list of
213
strings, or @code{nil}, which is equivalent to an empty string.  When
214 215
@var{default} is a string, that string is the default value.  When it
is a list of strings, the first string is the default value.  (All
216 217
these strings are available to the user in the ``future minibuffer
history''.)
218 219

This function works by calling the
Glenn Morris's avatar
Glenn Morris committed
220 221 222 223 224 225 226 227 228 229
@code{read-from-minibuffer} function:

@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 (and (equal value "") @var{default})
230
      (if (consp @var{default}) (car @var{default}) @var{default})
Glenn Morris's avatar
Glenn Morris committed
231 232 233 234 235
    value))
@end group
@end smallexample
@end defun

Glenn Morris's avatar
Glenn Morris committed
236
@defun read-regexp prompt &optional defaults history
237
This function reads a regular expression as a string from the
Glenn Morris's avatar
Glenn Morris committed
238 239 240 241
minibuffer and returns it.  If the minibuffer prompt string
@var{prompt} does not end in @samp{:} (followed by optional
whitespace), the function adds @samp{: } to the end, preceded by the
default return value (see below), if that is non-empty.
242

Glenn Morris's avatar
Glenn Morris committed
243 244 245 246
The optional argument @var{defaults} controls the default value to
return if the user enters null input, and should be one of: a string;
@code{nil}, which is equivalent to an empty string; a list of strings;
or a symbol.
247

Glenn Morris's avatar
Glenn Morris committed
248 249 250 251 252 253 254 255 256 257 258 259 260 261 262
If @var{defaults} is a symbol, @code{read-regexp} consults the value
of the variable @code{read-regexp-defaults-function} (see below), and
if that is non-@code{nil} uses it in preference to @var{defaults}.
The value in this case should be either:

@itemize @minus
@item
@code{regexp-history-last}, which means to use the first element of
the appropriate minibuffer history list (see below).

@item
A function of no arguments, whose return value (which should be
@code{nil}, a string, or a list of strings) becomes the value of
@var{defaults}.
@end itemize
263

Glenn Morris's avatar
Glenn Morris committed
264 265 266 267 268
@code{read-regexp} now ensures that the result of processing
@var{defaults} is a list (i.e., if the value is @code{nil} or a
string, it converts it to a list of one element).  To this list,
@code{read-regexp} then appends a few potentially useful candidates for
input.  These are:
269 270 271

@itemize @minus
@item
272
The word or symbol at point.
273 274 275 276 277 278 279 280
@item
The last regexp used in an incremental search.
@item
The last string used in an incremental search.
@item
The last string or pattern used in query-replace commands.
@end itemize

Glenn Morris's avatar
Glenn Morris committed
281 282 283
The function now has a list of regular expressions that it passes to
@code{read-from-minibuffer} to obtain the user's input.  The first
element of the list is the default result in case of empty input.  All
284 285
elements of the list are available to the user as the ``future
minibuffer history'' list (@pxref{Minibuffer History, future list,,
Glenn Morris's avatar
Glenn Morris committed
286 287 288 289 290 291
emacs, The GNU Emacs Manual}).

The optional argument @var{history}, if non-@code{nil}, is a symbol
specifying a minibuffer history list to use (@pxref{Minibuffer
History}).  If it is omitted or @code{nil}, the history list defaults
to @code{regexp-history}.
292 293
@end defun

294
@defopt read-regexp-defaults-function
Glenn Morris's avatar
Glenn Morris committed
295 296 297 298 299 300 301 302 303 304 305 306 307 308 309
The function @code{read-regexp} may use the value of this variable to
determine its list of default regular expressions.  If non-@code{nil},
the value of this variable should be either:

@itemize @minus
@item
The symbol @code{regexp-history-last}.

@item
A function of no arguments that returns either @code{nil}, a string,
or a list of strings.
@end itemize

@noindent
See @code{read-regexp} above for details of how these values are used.
310
@end defopt
Glenn Morris's avatar
Glenn Morris committed
311

Glenn Morris's avatar
Glenn Morris committed
312
@defvar minibuffer-allow-text-properties
313 314 315
If this variable is @code{nil}, then @code{read-from-minibuffer}
and @code{read-string} strip all text properties from the minibuffer
input before returning it.  However,
Glenn Morris's avatar
Glenn Morris committed
316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336
@code{read-no-blanks-input} (see below), as well as
@code{read-minibuffer} and related functions (@pxref{Object from
Minibuffer,, Reading Lisp Objects With the Minibuffer}), and all
functions that do minibuffer input with completion, discard text
properties unconditionally, regardless of the value of this variable.
@end defvar

@defvar minibuffer-local-map
This
@anchor{Definition of minibuffer-local-map}
@c avoid page break at anchor; work around Texinfo deficiency
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}

337 338 339
@item @key{M-<}
@code{minibuffer-beginning-of-buffer}

Glenn Morris's avatar
Glenn Morris committed
340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355
@item @kbd{C-g}
@code{abort-recursive-edit}

@item @kbd{M-n}
@itemx @key{DOWN}
@code{next-history-element}

@item @kbd{M-p}
@itemx @key{UP}
@code{previous-history-element}

@item @kbd{M-s}
@code{next-matching-history-element}

@item @kbd{M-r}
@code{previous-matching-history-element}
356 357 358 359 360 361

@ignore
@c Does not seem worth/appropriate mentioning.
@item @kbd{C-@key{TAB}}
@code{file-cache-minibuffer-complete}
@end ignore
Glenn Morris's avatar
Glenn Morris committed
362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391
@end table
@end defvar

@c In version 18, initial is required
@c Emacs 19 feature
@defun read-no-blanks-input prompt &optional initial inherit-input-method
This function reads a string from the minibuffer, but does not allow
whitespace characters as part of the input: instead, those characters
terminate the input.  The arguments @var{prompt}, @var{initial}, and
@var{inherit-input-method} are used as in @code{read-from-minibuffer}.

This is a simplified interface to the @code{read-from-minibuffer}
function, and passes the value of the @code{minibuffer-local-ns-map}
keymap as the @var{keymap} argument for that function.  Since the keymap
@code{minibuffer-local-ns-map} does not rebind @kbd{C-q}, it @emph{is}
possible to put a space into the string, by quoting it.

This function discards text properties, regardless of the value of
@code{minibuffer-allow-text-properties}.

@smallexample
@group
(read-no-blanks-input @var{prompt} @var{initial})
@equiv{}
(let (minibuffer-allow-text-properties)
  (read-from-minibuffer @var{prompt} @var{initial} minibuffer-local-ns-map))
@end group
@end smallexample
@end defun

392 393
@c Slightly unfortunate name, suggesting it might be related to the
@c Nextstep port...
Glenn Morris's avatar
Glenn Morris committed
394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415
@defvar minibuffer-local-ns-map
This built-in variable is the keymap used as the minibuffer local keymap
in the function @code{read-no-blanks-input}.  By default, it makes the
following bindings, in addition to those of @code{minibuffer-local-map}:

@table @asis
@item @key{SPC}
@cindex @key{SPC} in minibuffer
@code{exit-minibuffer}

@item @key{TAB}
@cindex @key{TAB} in minibuffer
@code{exit-minibuffer}

@item @kbd{?}
@cindex @kbd{?} in minibuffer
@code{self-insert-and-exit}
@end table
@end defvar

@node Object from Minibuffer
@section Reading Lisp Objects with the Minibuffer
416
@cindex minibuffer input, reading lisp objects
Glenn Morris's avatar
Glenn Morris committed
417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478

  This section describes functions for reading Lisp objects with the
minibuffer.

@defun read-minibuffer prompt &optional initial
This function reads a Lisp object using the minibuffer, and returns it
without evaluating it.  The arguments @var{prompt} and @var{initial} are
used as in @code{read-from-minibuffer}.

This is a simplified interface to the
@code{read-from-minibuffer} function:

@smallexample
@group
(read-minibuffer @var{prompt} @var{initial})
@equiv{}
(let (minibuffer-allow-text-properties)
  (read-from-minibuffer @var{prompt} @var{initial} nil t))
@end group
@end smallexample

Here is an example in which we supply the string @code{"(testing)"} as
initial input:

@smallexample
@group
(read-minibuffer
 "Enter an expression: " (format "%s" '(testing)))

;; @r{Here is how the minibuffer is displayed:}
@end group

@group
---------- Buffer: Minibuffer ----------
Enter an expression: (testing)@point{}
---------- Buffer: Minibuffer ----------
@end group
@end smallexample

@noindent
The user can type @key{RET} immediately to use the initial input as a
default, or can edit the input.
@end defun

@defun eval-minibuffer prompt &optional initial
This function reads a Lisp expression using the minibuffer, evaluates
it, then returns the result.  The arguments @var{prompt} and
@var{initial} are used as in @code{read-from-minibuffer}.

This function simply evaluates the result of a call to
@code{read-minibuffer}:

@smallexample
@group
(eval-minibuffer @var{prompt} @var{initial})
@equiv{}
(eval (read-minibuffer @var{prompt} @var{initial}))
@end group
@end smallexample
@end defun

@defun edit-and-eval-command prompt form
479 480
This function reads a Lisp expression in the minibuffer, evaluates it,
then returns the result.  The difference between this command and
Glenn Morris's avatar
Glenn Morris committed
481 482 483 484 485 486 487
@code{eval-minibuffer} is that here the initial @var{form} is not
optional and it is treated as a Lisp object to be converted to printed
representation rather than as a string of text.  It is printed with
@code{prin1}, so if it is a string, double-quote characters (@samp{"})
appear in the initial text.  @xref{Output Functions}.

In the following example, we offer the user an expression with initial
488
text that is already a valid form:
Glenn Morris's avatar
Glenn Morris committed
489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514

@smallexample
@group
(edit-and-eval-command "Please edit: " '(forward-word 1))

;; @r{After evaluation of the preceding expression,}
;;   @r{the following appears in the minibuffer:}
@end group

@group
---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)@point{}
---------- Buffer: Minibuffer ----------
@end group
@end smallexample

@noindent
Typing @key{RET} right away would exit the minibuffer and evaluate the
expression, thus moving point forward one word.
@end defun

@node Minibuffer History
@section Minibuffer History
@cindex minibuffer history
@cindex history list

515 516 517 518 519 520 521 522
  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 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.

523
  You specify a minibuffer history list with the optional @var{history}
524 525
argument to @code{read-from-minibuffer} or @code{completing-read}.
Here are the possible values for it:
Glenn Morris's avatar
Glenn Morris committed
526 527 528 529 530 531 532 533 534 535 536 537 538

@table @asis
@item @var{variable}
Use @var{variable} (a symbol) as the history list.

@item (@var{variable} . @var{startpos})
Use @var{variable} (a symbol) as the history list, and assume that the
initial history position is @var{startpos} (a nonnegative integer).

Specifying 0 for @var{startpos} is equivalent to just specifying the
symbol @var{variable}.  @code{previous-history-element} will display
the most recent element of the history list in the minibuffer.  If you
specify a positive @var{startpos}, the minibuffer history functions
539
behave as if @code{(elt @var{variable} (1- @var{startpos}))} were the
Glenn Morris's avatar
Glenn Morris committed
540 541 542 543 544 545 546
history element currently shown in the minibuffer.

For consistency, you should also specify that element of the history
as the initial minibuffer contents, using the @var{initial} argument
to the minibuffer input function (@pxref{Initial Input}).
@end table

547
  If you don't specify @var{history}, then the default history list
Glenn Morris's avatar
Glenn Morris committed
548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584
@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.

  Emacs functions that add a new element to a history list can also
delete old elements if the list gets too long.  The variable
@code{history-length} specifies the maximum length for most history
lists.  To specify a different maximum length for a particular history
list, put the length in the @code{history-length} property of the
history list symbol.  The variable @code{history-delete-duplicates}
specifies whether to delete duplicates in history.

@defun add-to-history history-var newelt &optional maxelt keep-all
This function adds a new element @var{newelt}, if it isn't the empty
string, to the history list stored in the variable @var{history-var},
and returns the updated history list.  It limits the list length to
the value of @var{maxelt} (if non-@code{nil}) or @code{history-length}
(described below).  The possible values of @var{maxelt} have the same
meaning as the values of @code{history-length}.

Normally, @code{add-to-history} removes duplicate members from the
history list if @code{history-delete-duplicates} is non-@code{nil}.
However, if @var{keep-all} is non-@code{nil}, that says not to remove
duplicates, and to add @var{newelt} to the list even if it is empty.
@end defun

@defvar history-add-new-input
If the value of this variable is @code{nil}, standard functions that
read from the minibuffer don't add new elements to the history list.
This lets Lisp programs explicitly manage input history by using
585
@code{add-to-history}.  The default value is @code{t}.
Glenn Morris's avatar
Glenn Morris committed
586 587
@end defvar

588
@defopt history-length
Glenn Morris's avatar
Glenn Morris committed
589 590
The value of this variable specifies the maximum length for all
history lists that don't specify their own maximum lengths.  If the
591
value is @code{t}, that means there is no maximum (don't delete old
592 593
elements).  If a history list variable's symbol has a non-@code{nil}
@code{history-length} property, it overrides this variable for that
Glenn Morris's avatar
Glenn Morris committed
594
particular history list.
595
@end defopt
Glenn Morris's avatar
Glenn Morris committed
596

597
@defopt history-delete-duplicates
Glenn Morris's avatar
Glenn Morris committed
598 599
If the value of this variable is @code{t}, that means when adding a
new history element, all previous identical elements are deleted.
600
@end defopt
Glenn Morris's avatar
Glenn Morris committed
601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636

  Here are some of the standard minibuffer history list variables:

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

@defvar query-replace-history
A history list for arguments to @code{query-replace} (and similar
arguments to other commands).
@end defvar

@defvar file-name-history
A history list for file-name arguments.
@end defvar

@defvar buffer-name-history
A history list for buffer-name arguments.
@end defvar

@defvar regexp-history
A history list for regular expression arguments.
@end defvar

@defvar extended-command-history
A history list for arguments that are names of extended commands.
@end defvar

@defvar shell-command-history
A history list for arguments that are shell commands.
@end defvar

@defvar read-expression-history
A history list for arguments that are Lisp expressions to evaluate.
@end defvar

637 638 639 640
@defvar face-name-history
A history list for arguments that are faces.
@end defvar

641 642 643 644 645 646
@findex read-variable@r{, history list}
@defvar custom-variable-history
A history list for variable-name arguments read by
@code{read-variable}.
@end defvar

647 648 649 650
@c Less common: coding-system-history, input-method-history,
@c command-history, grep-history, grep-find-history,
@c read-envvar-name-history, setenv-history, yes-or-no-p-history.

Glenn Morris's avatar
Glenn Morris committed
651 652 653 654
@node Initial Input
@section Initial Input

Several of the functions for minibuffer input have an argument called
655
@var{initial}.  This is a mostly-deprecated
Glenn Morris's avatar
Glenn Morris committed
656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671
feature for specifying that the minibuffer should start out with
certain text, instead of empty as usual.

If @var{initial} is a string, the minibuffer starts out containing the
text of the string, with point at the end, when the user starts to
edit the text.  If the user simply types @key{RET} to exit the
minibuffer, it will use the initial input string to determine the
value to return.

@strong{We discourage use of a non-@code{nil} value for
@var{initial}}, because initial input is an intrusive interface.
History lists and default values provide a much more convenient method
to offer useful default inputs to the user.

There is just one situation where you should specify a string for an
@var{initial} argument.  This is when you specify a cons cell for the
672
@var{history} argument.  @xref{Minibuffer History}.
Glenn Morris's avatar
Glenn Morris committed
673 674 675 676 677 678 679 680 681 682 683

@var{initial} can 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 at @var{position} within the string's text.

As a historical accident, @var{position} was implemented
inconsistently in different functions.  In @code{completing-read},
@var{position}'s value is interpreted as origin-zero; that is, a value
of 0 means the beginning of the string, 1 means after the first
character, etc.  In @code{read-minibuffer}, and the other
non-completion minibuffer input functions that support this argument,
684
1 means the beginning of the string, 2 means after the first character,
Glenn Morris's avatar
Glenn Morris committed
685 686
etc.

687
Use of a cons cell as the value for @var{initial} arguments is deprecated.
Glenn Morris's avatar
Glenn Morris committed
688 689 690 691 692 693 694 695 696 697

@node Completion
@section Completion
@cindex completion

  @dfn{Completion} is a feature that fills in the rest of a name
starting from an abbreviation for it.  Completion works by comparing the
user's input against a list of valid names and determining how much of
the name is determined uniquely by what the user has typed.  For
example, when you type @kbd{C-x b} (@code{switch-to-buffer}) and then
698
@c "This is the sort of English up with which I will not put."
Glenn Morris's avatar
Glenn Morris committed
699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722
type the first few letters of the name of the buffer to which you wish
to switch, and then type @key{TAB} (@code{minibuffer-complete}), Emacs
extends the name as far as it can.

  Standard Emacs commands offer completion for names of symbols, files,
buffers, and processes; with the functions in this section, you can
implement completion for other kinds of names.

  The @code{try-completion} function is the basic primitive for
completion: it returns the longest determined completion of a given
initial string, with a given set of strings to match against.

  The function @code{completing-read} provides a higher-level interface
for completion.  A call to @code{completing-read} specifies how to
determine the list of valid names.  The function then activates the
minibuffer with a local keymap that binds a few keys to commands useful
for completion.  Other functions provide convenient simple interfaces
for reading certain kinds of names with completion.

@menu
* Basic Completion::       Low-level functions for completing strings.
* Minibuffer Completion::  Invoking the minibuffer with completion.
* Completion Commands::    Minibuffer commands that do completion.
* High-Level Completion::  Convenient special cases of completion
723
                             (reading buffer names, variable names, etc.).
724 725
* Reading File Names::     Using completion to read file names and
                             shell commands.
726 727
* Completion Variables::   Variables controlling completion behavior.
* Programmed Completion::  Writing your own completion function.
728
* Completion in Buffers::  Completing text in ordinary buffers.
Glenn Morris's avatar
Glenn Morris committed
729 730 731 732 733
@end menu

@node Basic Completion
@subsection Basic Completion Functions

Chong Yidong's avatar
Chong Yidong committed
734 735 736
  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.
Glenn Morris's avatar
Glenn Morris committed
737 738 739

@defun try-completion string collection &optional predicate
This function returns the longest common substring of all possible
740 741 742
completions of @var{string} in @var{collection}.

@cindex completion table
743 744 745 746 747 748 749 750
@var{collection} is called the @dfn{completion table}.  Its value must
be a list of strings or cons cells, an obarray, a hash table, or a
completion function.

@code{try-completion} compares @var{string} against each of the
permissible completions specified by the completion table.  If no
permissible completions match, it returns @code{nil}.  If there is
just one matching completion, and the match is exact, it returns
Chong Yidong's avatar
Chong Yidong committed
751 752
@code{t}.  Otherwise, it returns the longest initial sequence common
to all possible matching completions.
Glenn Morris's avatar
Glenn Morris committed
753

754
If @var{collection} is a list, the permissible completions are
755 756 757 758
specified by the elements of the list, each of which should be either
a string, or a cons cell whose @sc{car} is either a string or a symbol
(a symbol is converted to a string using @code{symbol-name}).  If the
list contains elements of any other type, those are ignored.
Glenn Morris's avatar
Glenn Morris committed
759 760 761

@cindex obarray in completion
If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
762
of all symbols in the obarray form the set of permissible completions.
Glenn Morris's avatar
Glenn Morris committed
763

764 765
If @var{collection} is a hash table, then the keys that are strings or
symbols are the possible completions.  Other keys are ignored.
Glenn Morris's avatar
Glenn Morris committed
766

767 768 769 770
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
771
third argument is so that the same function can be used
772 773
in @code{all-completions} and do the appropriate thing in either
case).  @xref{Programmed Completion}.
Glenn Morris's avatar
Glenn Morris committed
774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793

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
which case it should be a function of two arguments.  It is used to
test each possible match, and the match is accepted only if
@var{predicate} returns non-@code{nil}.  The argument given to
@var{predicate} is either a string or a cons cell (the @sc{car} of
which is a string) from the alist, or a symbol (@emph{not} a symbol
name) from the obarray.  If @var{collection} is a hash table,
@var{predicate} is called with two arguments, the string key and the
associated value.

In addition, to be acceptable, a completion must also match all the
regular expressions in @code{completion-regexp-list}.  (Unless
@var{collection} is a function, in which case that function has to
handle @code{completion-regexp-list} itself.)

In the first of the following examples, the string @samp{foo} is
matched by three of the alist @sc{car}s.  All of the matches begin with
the characters @samp{fooba}, so that is the result.  In the second
794 795
example, there is only one possible match, and it is exact, so the
return value is @code{t}.
Glenn Morris's avatar
Glenn Morris committed
796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842

@smallexample
@group
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
     @result{} "fooba"
@end group

@group
(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
     @result{} t
@end group
@end smallexample

In the following example, numerous symbols begin with the characters
@samp{forw}, and all of them begin with the word @samp{forward}.  In
most of the symbols, this is followed with a @samp{-}, but not in all,
so no more than @samp{forward} can be completed.

@smallexample
@group
(try-completion "forw" obarray)
     @result{} "forward"
@end group
@end smallexample

Finally, in the following example, only two of the three possible
matches pass the predicate @code{test} (the string @samp{foobaz} is
too short).  Both of those begin with the string @samp{foobar}.

@smallexample
@group
(defun test (s)
  (> (length (car s)) 6))
     @result{} test
@end group
@group
(try-completion
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     @result{} "foobar"
@end group
@end smallexample
@end defun

843 844
@c Removed obsolete argument nospace.
@defun all-completions string collection &optional predicate
Glenn Morris's avatar
Glenn Morris committed
845
This function returns a list of all possible completions of
846 847
@var{string}.  The arguments to this function
@c (aside from @var{nospace})
848
are the same as those of @code{try-completion}, and it
849
uses @code{completion-regexp-list} in the same way that
850 851
@code{try-completion} does.

852
@ignore
853 854 855
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.
856
@end ignore
Glenn Morris's avatar
Glenn Morris committed
857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884

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

Here is an example, using the function @code{test} shown in the
example for @code{try-completion}:

@smallexample
@group
(defun test (s)
  (> (length (car s)) 6))
     @result{} test
@end group

@group
(all-completions
 "foo"
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 'test)
     @result{} ("foobar1" "foobar2")
@end group
@end smallexample
@end defun

@defun test-completion string collection &optional predicate
@anchor{Definition of test-completion}
This function returns non-@code{nil} if @var{string} is a valid
885
completion alternative specified by @var{collection} and
Glenn Morris's avatar
Glenn Morris committed
886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903
@var{predicate}.  The arguments are the same as in
@code{try-completion}.  For instance, if @var{collection} is a list of
strings, this is true if @var{string} appears in the list and
@var{predicate} is satisfied.

This function uses @code{completion-regexp-list} in the same
way that @code{try-completion} does.

If @var{predicate} is non-@code{nil} and if @var{collection} contains
several strings that are equal to each other, as determined by
@code{compare-strings} according to @code{completion-ignore-case},
then @var{predicate} should accept either all or none of them.
Otherwise, the return value of @code{test-completion} is essentially
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.
904
@end defun
905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922

@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"}.
Glenn Morris's avatar
Glenn Morris committed
923 924
@end defun

Chong Yidong's avatar
Chong Yidong committed
925
If you store a completion alist in a variable, you should mark the
Paul Eggert's avatar
Paul Eggert committed
926
variable as risky by giving it a non-@code{nil}
Chong Yidong's avatar
Chong Yidong committed
927 928
@code{risky-local-variable} property.  @xref{File Local Variables}.

Glenn Morris's avatar
Glenn Morris committed
929
@defvar completion-ignore-case
930 931 932 933 934 935 936
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}).
Glenn Morris's avatar
Glenn Morris committed
937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954
@end defvar

@defvar completion-regexp-list
This is a list of regular expressions.  The completion functions only
consider a completion acceptable if it matches all regular expressions
in this list, with @code{case-fold-search} (@pxref{Searching and Case})
bound to the value of @code{completion-ignore-case}.
@end defvar

@defmac lazy-completion-table var fun
This macro provides a way to initialize the variable @var{var} as a
collection for completion in a lazy way, not computing its actual
contents until they are first needed.  You use this macro to produce a
value that you store in @var{var}.  The actual computation of the
proper value is done the first time you do completion using @var{var}.
It is done by calling @var{fun} with no arguments.  The
value @var{fun} returns becomes the permanent value of @var{var}.

955
Here is an example:
Glenn Morris's avatar
Glenn Morris committed
956 957 958 959 960 961

@smallexample
(defvar foo (lazy-completion-table foo make-my-alist))
@end smallexample
@end defmac

962 963 964
@c FIXME?  completion-table-with-context?
@findex completion-table-case-fold
@findex completion-table-in-turn
965
@findex completion-table-merge
966
@findex completion-table-subvert
967
@findex completion-table-with-quoting
968 969
@findex completion-table-with-predicate
@findex completion-table-with-terminator
970 971
@cindex completion table, modifying
@cindex completion tables, combining
972 973
There are several functions that take an existing completion table and
return a modified version.  @code{completion-table-case-fold} returns
974 975 976 977
a case-insensitive table.  @code{completion-table-in-turn} and
@code{completion-table-merge} combine multiple input tables in
different ways.  @code{completion-table-subvert} alters a table to use
a different initial prefix.  @code{completion-table-with-quoting}
978
returns a table suitable for operating on quoted text.
979
@code{completion-table-with-predicate} filters a table with a
980 981
predicate function.  @code{completion-table-with-terminator} adds a
terminating string.
982 983


Glenn Morris's avatar
Glenn Morris committed
984 985 986 987 988 989 990 991
@node Minibuffer Completion
@subsection Completion and the Minibuffer
@cindex minibuffer completion
@cindex reading from minibuffer with completion

  This section describes the basic interface for reading from the
minibuffer with completion.

992
@defun completing-read prompt collection &optional predicate require-match initial history default inherit-input-method
Glenn Morris's avatar
Glenn Morris committed
993 994 995 996
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.

997 998 999 1000 1001 1002 1003 1004
The actual completion is done by passing the completion table
@var{collection} and the completion predicate @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}.
Glenn Morris's avatar
Glenn Morris committed
1005

1006 1007 1008
@xref{Programmed Completion}, for detailed requirements when
@var{collection} is a function.

1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035
The value of the optional argument @var{require-match} determines how
the user may exit the minibuffer:

@itemize @bullet
@item
If @code{nil}, the usual minibuffer exit commands work regardless of
the input in the minibuffer.

@item
If @code{t}, the usual minibuffer exit commands won't exit unless the
input completes to an element of @var{collection}.

@item
If @code{confirm}, the user can exit with any input, but is asked for
confirmation if the input is not an element of @var{collection}.

@item
If @code{confirm-after-completion}, the user can exit with any input,
but is asked for confirmation if the preceding command was a
completion command (i.e., one of the commands in
@code{minibuffer-confirm-exit-commands}) and the resulting input is
not an element of @var{collection}.  @xref{Completion Commands}.

@item
Any other value of @var{require-match} behaves like @code{t}, except
that the exit commands won't exit if it performs completion.
@end itemize
Glenn Morris's avatar
Glenn Morris committed
1036 1037

However, empty input is always permitted, regardless of the value of
1038 1039
@var{require-match}; in that case, @code{completing-read} returns the
first element of @var{default}, if it is a list; @code{""}, if
Juri Linkov's avatar
Juri Linkov committed
1040 1041
@var{default} is @code{nil}; or @var{default}.  The string or strings
in @var{default} are also available to the user through the history
1042
commands.
Glenn Morris's avatar
Glenn Morris committed
1043 1044 1045 1046 1047 1048 1049

The function @code{completing-read} uses
@code{minibuffer-local-completion-map} as the keymap if
@var{require-match} is @code{nil}, and uses
@code{minibuffer-local-must-match-map} if @var{require-match} is
non-@code{nil}.  @xref{Completion Commands}.

1050
The argument @var{history} specifies which history list variable to use for
Glenn Morris's avatar
Glenn Morris committed
1051 1052 1053 1054 1055
saving the input and for minibuffer history commands.  It defaults to
@code{minibuffer-history}.  @xref{Minibuffer History}.

The argument @var{initial} is mostly deprecated; we recommend using a
non-@code{nil} value only in conjunction with specifying a cons cell
1056
for @var{history}.  @xref{Initial Input}.  For default input, use
Glenn Morris's avatar
Glenn Morris committed
1057 1058 1059 1060 1061 1062 1063 1064
@var{default} instead.

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

1065
If the variable @code{completion-ignore-case} is
Glenn Morris's avatar
Glenn Morris committed
1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099
non-@code{nil}, completion ignores case when comparing the input
against the possible matches.  @xref{Basic Completion}.  In this mode
of operation, @var{predicate} must also ignore case, or you will get
surprising results.

Here's an example of using @code{completing-read}:

@smallexample
@group
(completing-read
 "Complete a foo: "
 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
 nil t "fo")
@end group

@group
;; @r{After evaluation of the preceding expression,}
;;   @r{the following appears in the minibuffer:}

---------- Buffer: Minibuffer ----------
Complete a foo: fo@point{}
---------- Buffer: Minibuffer ----------
@end group
@end smallexample

@noindent
If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
@code{completing-read} returns @code{barfoo}.

The @code{completing-read} function binds variables to pass
information to the commands that actually do completion.
They are described in the following section.
@end defun

1100 1101 1102 1103 1104 1105 1106 1107
@defvar completing-read-function
The value of this variable must be a function, which is called by
@code{completing-read} to actually do its work.  It should accept the
same arguments as @code{completing-read}.  This can be bound to a
different function to completely override the normal behavior of
@code{completing-read}.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
1108 1109 1110 1111
@node Completion Commands
@subsection Minibuffer Commands that Do Completion

  This section describes the keymaps, commands and user options used
1112
in the minibuffer to do completion.
Glenn Morris's avatar
Glenn Morris committed
1113 1114

@defvar minibuffer-completion-table
1115 1116 1117 1118 1119
The value of this variable is the completion table (@pxref{Basic
Completion}) used for completion in the minibuffer.  This is the
global variable that contains what @code{completing-read} passes to
@code{try-completion}.  It is used by minibuffer completion commands
such as @code{minibuffer-complete-word}.
Glenn Morris's avatar
Glenn Morris committed
1120 1121 1122 1123 1124 1125 1126 1127 1128
@end defvar

@defvar minibuffer-completion-predicate
This variable's value is the predicate that @code{completing-read}
passes to @code{try-completion}.  The variable is also used by the other
minibuffer completion functions.
@end defvar

@defvar minibuffer-completion-confirm
1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147
This variable determines whether Emacs asks for confirmation before
exiting the minibuffer; @code{completing-read} binds this variable,
and the function @code{minibuffer-complete-and-exit} checks the value
before exiting.  If the value is @code{nil}, confirmation is not
required.  If the value is @code{confirm}, the user may exit with an
input that is not a valid completion alternative, but Emacs asks for
confirmation.  If the value is @code{confirm-after-completion}, the
user may exit with an input that is not a valid completion
alternative, but Emacs asks for confirmation if the user submitted the
input right after any of the completion commands in
@code{minibuffer-confirm-exit-commands}.
@end defvar

@defvar minibuffer-confirm-exit-commands
This variable holds a list of commands that cause Emacs to ask for
confirmation before exiting the minibuffer, if the @var{require-match}
argument to @code{completing-read} is @code{confirm-after-completion}.
The confirmation is requested if the user attempts to exit the
minibuffer immediately after calling any command in this list.
Glenn Morris's avatar
Glenn Morris committed
1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176
@end defvar

@deffn Command minibuffer-complete-word
This function completes the minibuffer contents by at most a single
word.  Even if the minibuffer contents have only one completion,
@code{minibuffer-complete-word} does not add any characters beyond the
first character that is not a word constituent.  @xref{Syntax Tables}.
@end deffn

@deffn Command minibuffer-complete
This function completes the minibuffer contents as far as possible.
@end deffn

@deffn Command minibuffer-complete-and-exit
This function completes the minibuffer contents, and exits if
confirmation is not required, i.e., if
@code{minibuffer-completion-confirm} is @code{nil}.  If confirmation
@emph{is} required, it is given by repeating this command
immediately---the command is programmed to work without confirmation
when run twice in succession.
@end deffn

@deffn Command minibuffer-completion-help
This function creates a list of the possible completions of the
current minibuffer contents.  It works by calling @code{all-completions}
using the value of the variable @code{minibuffer-completion-table} as
the @var{collection} argument, and the value of
@code{minibuffer-completion-predicate} as the @var{predicate} argument.
The list of completions is displayed as text in a buffer named
1177
@file{*Completions*}.
Glenn Morris's avatar
Glenn Morris committed
1178 1179
@end deffn

1180
@defun display-completion-list completions
Glenn Morris's avatar
Glenn Morris committed
1181 1182 1183 1184 1185 1186 1187 1188 1189 1190
This function displays @var{completions} to the stream in
@code{standard-output}, usually a buffer.  (@xref{Read and Print}, for more
information about streams.)  The argument @var{completions} is normally
a list of completions just returned by @code{all-completions}, but it
does not have to be.  Each element may be a symbol or a string, either
of which is simply printed.  It can also be a list of two strings,
which is printed as if the strings were concatenated.  The first of
the two strings is the actual completion, the second string serves as
annotation.

1191 1192
This function is called by @code{minibuffer-completion-help}.  A
common way to use it is together with
Glenn Morris's avatar
Glenn Morris committed
1193 1194 1195 1196 1197
@code{with-output-to-temp-buffer}, like this:

@example
(with-output-to-temp-buffer "*Completions*"
  (display-completion-list
1198
    (all-completions (buffer-string) my-alist)))
Glenn Morris's avatar
Glenn Morris committed
1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224
@end example
@end defun

@defopt completion-auto-help
If this variable is non-@code{nil}, the completion commands
automatically display a list of possible completions whenever nothing
can be completed because the next character is not uniquely determined.
@end defopt

@defvar minibuffer-local-completion-map
@code{completing-read} uses this value as the local keymap when an
exact match of one of the completions is not required.  By default, this
keymap makes the following bindings:

@table @asis
@item @kbd{?}
@code{minibuffer-completion-help}

@item @key{SPC}
@code{minibuffer-complete-word}

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

@noindent
1225
and uses @code{minibuffer-local-map} as its parent keymap
Glenn Morris's avatar
Glenn Morris committed
1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244
(@pxref{Definition of minibuffer-local-map}).
@end defvar

@defvar minibuffer-local-must-match-map
@code{completing-read} uses this value as the local keymap when an
exact match of one of the completions is required.  Therefore, no keys
are bound to @code{exit-minibuffer}, the command that exits the
minibuffer unconditionally.  By default, this keymap makes the following
bindings:

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

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

@noindent
1245
and uses @code{minibuffer-local-completion-map} as its parent keymap.
Glenn Morris's avatar
Glenn Morris committed
1246 1247 1248
@end defvar

@defvar minibuffer-local-filename-completion-map
1249 1250 1251 1252
This is a sparse keymap that simply unbinds @key{SPC}; because
filenames can contain spaces.  The function @code{read-file-name}
combines this keymap with either @code{minibuffer-local-completion-map}
or @code{minibuffer-local-must-match-map}.
Glenn Morris's avatar
Glenn Morris committed
1253 1254
@end defvar

1255 1256 1257 1258 1259 1260 1261 1262
@defvar minibuffer-beginning-of-buffer-movement
If non-@code{nil}, the @kbd{M-<} command will move to the end of the
prompt if point is after the end of the prompt.  If point is at or
before the end of the prompt, move to the start of the buffer.  If
this variable is @code{nil}, the command behaves like
@code{beginning-of-buffer}.
@end defvar

Glenn Morris's avatar
Glenn Morris committed
1263 1264

@node High-Level Completion
1265
@subsection High-Level Completion Functions
Glenn Morris's avatar
Glenn Morris committed
1266

1267
  This section describes the higher-level convenience functions for
Glenn Morris's avatar
Glenn Morris committed
1268 1269 1270 1271 1272 1273 1274
reading certain sorts of names with completion.

  In most cases, you should not call these functions in the middle of a
Lisp function.  When possible, do all minibuffer input as part of
reading the arguments for a command, in the @code{interactive}
specification.  @xref{Defining Commands}.

1275
@defun read-buffer prompt &optional default require-match predicate
Glenn Morris's avatar
Glenn Morris committed
1276
This function reads the name of a buffer and returns it as a string.
1277 1278 1279 1280 1281 1282
It prompts with @var{prompt}.  The argument @var{default} is the
default name to use, the value to return if the user exits with an
empty minibuffer.  If non-@code{nil}, it should be a string, a list of
strings, or a buffer.  If it is a list, the default value is the first
element of this list.  It is mentioned in the prompt, but is not
inserted in the minibuffer as initial input.
Glenn Morris's avatar
Glenn Morris committed
1283 1284 1285 1286 1287 1288

The argument @var{prompt} should be a string ending with a colon and a
space.  If @var{default} is non-@code{nil}, the function inserts it in
@var{prompt} before the colon to follow the convention for reading from
the minibuffer with a default value (@pxref{Programming Tips}).

1289 1290
The optional argument @var{require-match} has the same meaning as in
@code{completing-read}.  @xref{Minibuffer Completion}.
Glenn Morris's avatar
Glenn Morris committed
1291

1292 1293 1294 1295 1296 1297
The optional argument @var{predicate}, if non-@code{nil}, specifies a
function to filter the buffers that should be considered: the function
will be called with every potential candidate as its argument, and
should return @code{nil} to reject the candidate, non-@code{nil} to
accept it.

Glenn Morris's avatar
Glenn Morris committed
1298
In the following example, the user enters @samp{minibuffer.t}, and
1299 1300
then types @key{RET}.  The argument @var{require-match} is @code{t},
and the only buffer name starting with the given input is
Glenn Morris's avatar
Glenn Morris committed
1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323
@samp{minibuffer.texi}, so that name is the value.

@example
(read-buffer "Buffer name: " "foo" t)
@group
;; @r{After evaluation of the preceding expression,}
;;   @r{the following prompt appears,}
;;   @r{with an empty minibuffer:}
@end group

@group
---------- Buffer: Minibuffer ----------
Buffer name (default foo): @point{}
---------- Buffer: Minibuffer ----------
@end group

@group
;; @r{The user types @kbd{minibuffer.t @key{RET}}.}
     @result{} "minibuffer.texi"
@end group
@end example
@end defun

1324
@defopt read-buffer-function
1325 1326 1327
This variable, if non-@code{nil}, specifies a function for reading
buffer names.  @code{read-buffer} calls this function instead of doing
its usual work, with the same arguments passed to @code{read-buffer}.
1328
@end defopt
Glenn Morris's avatar
Glenn Morris committed
1329

1330
@defopt read-buffer-completion-ignore-case
1331
If this variable is non-@code{nil}, @code{read-buffer} ignores case
1332
when performing completion while reading the buffer name.
1333
@end defopt
1334

Glenn Morris's avatar
Glenn Morris committed
1335 1336 1337 1338 1339 1340 1341 1342
@defun read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp
symbol.  The argument @var{prompt} is used as in
@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
1343 1344
null input.  It can be a symbol, a string or a list of strings.  If it
is a string, @code{read-command} interns it before returning it.
1345
If it is a list, @code{read-command} interns the first element of this list.
1346 1347
If @var{default} is @code{nil}, that means no default has been
specified; then if the user enters null input, the return value is
1348 1349
@code{(intern "")}, that is, a symbol whose name is an empty string,
and whose printed representation is @code{##} (@pxref{Symbol Type}).
Glenn Morris's avatar
Glenn Morris committed
1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387

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

@group
;; @r{After evaluation of the preceding expression,}
;;   @r{the following prompt appears with an empty minibuffer:}
@end group

@group
---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------
@end group
@end example

@noindent
If the user types @kbd{forward-c @key{RET}}, then this function returns
@code{forward-char}.

The @code{read-command} function is a simplified interface to
@code{completing-read}.  It uses the variable @code{obarray} so as to
complete in the set of extant Lisp symbols, and it uses the
@code{commandp} predicate so as to accept only command names:

@cindex @code{commandp} example
@example
@group
(read-command @var{prompt})
@equiv{}
(intern (completing-read @var{prompt} obarray
                         'commandp t nil))
@end group
@end example
@end defun

@defun read-variable prompt &optional default
@anchor{Definition of read-variable}
Chong Yidong's avatar
Chong Yidong committed
1388 1389 1390 1391 1392
This function reads the name of a customizable variable and returns it
as a symbol.  Its arguments have the same form as those of
@code{read-command}.  It behaves just like @code{read-command}, except
that it uses the predicate @code{custom-variable-p} instead of
@code{commandp}.
Glenn Morris's avatar
Glenn Morris committed
1393 1394
@end defun

1395 1396 1397
@deffn Command read-color &optional prompt convert allow-empty display
This function reads a string that is a color specification, either the
color's name or an RGB hex value such as @code{#RRRGGGBBB}.  It
1398
prompts with @var{prompt} (default: @code{"Color (name or #RGB triplet):"})
1399 1400 1401 1402 1403 1404
and provides completion for color names, but not for hex RGB values.
In addition to names of standard colors, completion candidates include
the foreground and background colors at point.

Valid RGB values are described in @ref{Color Names}.

1405
The function's return value is the string typed by the user in the
1406
minibuffer.  However, when called interactively or if the optional
1407 1408 1409
argument @var{convert} is non-@code{nil}, it converts any input color
name into the corresponding RGB value string and instead returns that.
This function requires a valid color specification to be input.
1410
Empty color names are allowed when @var{allow-empty} is
1411 1412
non-@code{nil} and the user enters null input.

1413
Interactively, or when @var{display} is non-@code{nil}, the return
1414 1415 1416
value is also displayed in the echo area.
@end deffn

Glenn Morris's avatar
Glenn Morris committed
1417 1418 1419 1420 1421 1422 1423 1424 1425
  See also the functions @code{read-coding-system} and
@code{read-non-nil-coding-system}, in @ref{User-Chosen Coding Systems},
and @code{read-input-method-name}, in @ref{Input Methods}.

@node Reading File Names
@subsection Reading File Names
@cindex read file names
@cindex prompt for file name

1426 1427
  The high-level completion functions @code{read-file-name},
@code{read-directory-name}, and @code{read-shell-command} are designed
1428
to read file names, directory names, and shell commands, respectively.
1429 1430
They provide special features, including automatic insertion of the
default directory.
Glenn Morris's avatar
Glenn Morris committed
1431

1432
@defun read-file-name prompt &optional directory default require-match initial predicate
1433 1434 1435 1436
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
1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459
file dialog instead of the minibuffer, if all of the following are
true:

@enumerate
@item
It is invoked via a mouse command.

@item
The selected frame is on a graphical display supporting such dialogs.

@item
The variable @code{use-dialog-box} is non-@code{nil}.
@xref{Dialog Boxes,, Dialog Boxes, emacs, The GNU Emacs Manual}.

@item
The @var{directory} argument, described below, does not specify a
remote file.  @xref{Remote Files,, Remote Files, emacs, The GNU Emacs Manual}.
@end enumerate

@noindent
The exact behavior when using a graphical file dialog is
platform-dependent.  Here, we simply document the behavior when using
the minibuffer.
Glenn Morris's avatar
Glenn Morris committed
1460

1461
@code{read-file-name} does not automatically expand the returned file
Paul Eggert's avatar
Paul Eggert committed
1462
name.  You can call @code{expand-file-name} yourself if an absolute
1463
file name is required.
Glenn Morris's avatar
Glenn Morris committed
1464

1465
The optional argument @var{require-match} has the same meaning as in
1466
@code{completing-read}.  @xref{Minibuffer Completion}.
Glenn Morris's avatar
Glenn Morris committed
1467 1468

The argument @var{directory} specifies the directory to use for
1469
completing relative file names.  It should be an absolute directory
1470
name.  If the variable @code{insert-default-directory} is non-@code{nil},
Glenn Morris's avatar
Glenn Morris committed
1471 1472 1473 1474 1475 1476 1477
@var{directory} is also inserted in the minibuffer as initial input.
It defaults to the current buffer's value of @code{default-directory}.

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
@var{initial} is @code{nil}---don't insert any file name.  To see what
1478 1479 1480
@var{initial} does, try the command @kbd{C-x C-v} in a buffer visiting
a file.  @strong{Please note:} we recommend using @var{default} rather
than @var{initial} in most cases.
Glenn Morris's avatar
Glenn Morris committed
1481 1482 1483 1484 1485 1486 1487

If @var{default} is non-@code{nil}, then the function returns
@var{default} if the user exits the minibuffer with the same non-empty
contents that @code{read-file-name} inserted initially.  The initial
minibuffer contents are always non-empty if
@code{insert-default-directory} is non-@code{nil}, as it is by
default.  @var{default} is not checked for validity, regardless of the
1488
value of @var{require-match}.  However, if @var{require-match} is
Glenn Morris's avatar
Glenn Morris committed
1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507
non-@code{nil}, the initial minibuffer contents should be a valid file
(or directory) name.  Otherwise @code{read-file-name} attempts
completion if the user exits without any editing, and does not return
@var{default}.  @var{default} is also available through the history
commands.

If @var{default} is @code{nil}, @code{read-file-name} tries to find a
substitute default to use in its place, which it treats in exactly the
same way as if it had been specified explicitly.  If @var{default} is
@code{nil}, but @var{initial} is non-@code{nil}, then the default is
the absolute file name obtained from @var{directory} and
@var{initial}.  If both @var{default} and @var{initial} are @code{nil}
and the buffer is visiting a file, @code{read-file-name} uses the
absolute file name of that file as default.  If the buffer is not
visiting a file, then there is no default.  In that case, if the user
types @key{RET} without any editing, @code{read-file-name} simply
returns the pre-inserted contents of the minibuffer.

If the user types @key{RET} in an empty minibuffer, this function
1508 1509
returns an empty string, regardless of the value of
@var{require-match}.  This is, for instance, how the user can make the
1510
current buffer visit no file using @kbd{M-x set-visited-file-name}.
Glenn Morris's avatar
Glenn Morris committed
1511 1512 1513

If @var{predicate} is non-@code{nil}, it specifies a function of one
argument that decides which file names are acceptable completion
1514
alternatives.  A file name is an acceptable value if @var{predicate}
Glenn Morris's avatar
Glenn Morris committed
1515 1516
returns non-@code{nil} for it.

1517
Here is an example of using @code{read-file-name}:
Glenn Morris's avatar
Glenn Morris committed
1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557

@example
@group
(read-file-name "The file is ")

;; @r{After evaluation of the preceding expression,}
;;   @r{the following appears in the minibuffer:}
@end group

@group
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/@point{}
---------- Buffer: Minibuffer ----------
@end group
@end example

@noindent
Typing @kbd{manual @key{TAB}} results in the following:

@example
@group
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/manual.texi@point{}
---------- Buffer: Minibuffer ----------
@end group
@end example

@c Wordy to avoid overfull hbox in smallbook mode.
@noindent
If the user types @key{RET}, @code{read-file-name} returns the file name
as the string @code{"/gp/gnu/elisp/manual.texi"}.
@end defun

@defvar read-file-name-function
If non-@code{nil}, this should be a function that accepts the same
arguments as @code{read-file-name}.  When @code{read-file-name} is
called, it calls this function with the supplied arguments instead of
doing its usual work.
@end defvar

1558
@defopt read-file-name-completion-ignore-case
Glenn Morris's avatar
Glenn Morris committed
1559 1560
If this variable is non-@code{nil}, @code{read-file-name} ignores case
when performing completion.
1561
@end defopt
Glenn Morris's avatar
Glenn Morris committed
1562

1563
@defun read-directory-name prompt &optional directory default require-match initial
Glenn Morris's avatar
Glenn Morris committed
1564
This function is like @code{read-file-name} but allows only directory
1565
names as completion alternatives.
Glenn Morris's avatar
Glenn Morris committed
1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582

If @var{default} is @code{nil} and @var{initial} is non-@code{nil},
@code{read-directory-name} constructs a substitute default by
combining @var{directory} (or the current buffer's default directory
if @var{directory} is @code{nil}) and @var{initial}.  If both
@var{default} and @var{initial} are @code{nil}, this function uses
@var{directory} as substitute default, or the current buffer's default
directory if @var{directory} is @code{nil}.
@end defun

@defopt insert-default-directory
This variable is used by @code{read-file-name}, and thus, indirectly,
by most commands reading file names.  (This includes all commands that
use the code letters @samp{f} or @samp{F} in their interactive form.
@xref{Interactive Codes,, Code Characters for interactive}.)  Its
value controls whether @code{read-file-name} starts by placing the
name of the default directory in the minibuffer, plus the initial file
1583
name, if any.  If the value of this variable is @code{nil}, then
Glenn Morris's avatar
Glenn Morris committed
1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595