[Emacs-diffs] Changes to emacs/lispref/minibuf.texi [gnus-5_10-branch]

[Miles Bader]

Index: emacs/lispref/minibuf.texi
diff -c /dev/null emacs/lispref/minibuf.texi:1.47.2.1
*** /dev/null   Sat Sep  4 12:02:44 2004
--- emacs/lispref/minibuf.texi  Sat Sep  4 12:01:14 2004
***************
*** 0 ****
--- 1,1861 ----
+ @c -*-texinfo-*-
+ @c This is part of the GNU Emacs Lisp Reference Manual.
+ @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999,
+ @c 2001, 2004
+ @c   Free Software Foundation, Inc.
+ @c See the file elisp.texi for copying conditions.
+ @setfilename ../info/minibuf
+ @node Minibuffers, Command Loop, Read and Print, Top
+ @chapter Minibuffers
+ @cindex arguments, reading
+ @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, 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 History::              Recording previous minibuffer inputs
+                               so the user can reuse them.
+ * Initial Input::             Specifying initial contents for the minibuffer.
+ * Completion::                How to invoke and customize completion.
+ * Yes-or-No Queries::         Asking a question with a simple answer.
+ * Multiple Queries::        Asking a series of similar questions.
+ * Reading a Password::              Reading a password from the terminal.
+ * Minibuffer 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 @address@hidden
+ address@hidden, 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
+ boundary between the prompt and the actual text.  (In older Emacs
+ versions, the prompt was displayed using a special mechanism and was not
+ part of the buffer contents.)
+ 
+   The minibuffer's window is normally a single line; it grows
+ automatically if necessary if the contents require more space.  You can
+ explicitly resize it temporarily with the window sizing commands; it
+ reverts to its normal size when the minibuffer is exited.  You can
+ resize it permanently by using the window sizing commands in the frame's
+ other window, when the minibuffer is not active.  If the frame contains
+ just a minibuffer, you can change the minibuffer's size by changing the
+ frame's size.
+ 
+   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.
+ 
+   If a command uses a minibuffer while there is an active minibuffer,
+ this is called a @dfn{recursive minibuffer}.  The first minibuffer is
+ named @address@hidden *Minibuf-0*}}.  Recursive minibuffers are named by
+ incrementing the number at the end of the name.  (The names begin with a
+ space so that they won't show up in normal buffer lists.)  Of several
+ recursive minibuffers, the innermost (or most recently entered) is the
+ active minibuffer.  We usually call this ``the'' minibuffer.  You can
+ permit or forbid recursive minibuffers by setting the variable
+ @code{enable-recursive-minibuffers} or by putting properties of that
+ name on command symbols (@pxref{Minibuffer Misc}).
+ 
+   Like other buffers, a minibuffer may use any of several local keymaps
+ (@pxref{Keymaps}); these contain various exit commands and in some cases
+ completion commands (@pxref{Completion}).
+ 
+ @itemize @bullet
+ @item
+ @code{minibuffer-local-map} is for ordinary input (no completion).
+ 
+ @item
+ @code{minibuffer-local-ns-map} is similar, except that @key{SPC} exits
+ just like @key{RET}.
+ 
+ @item
+ @code{minibuffer-local-completion-map} is for permissive completion.
+ 
+ @item
+ @code{minibuffer-local-must-match-map} is for strict completion and
+ for cautious completion.
+ @end itemize
+ 
+   When Emacs is running in batch mode, any request to read from the
+ minibuffer actually reads a line from the standard input descriptor that
+ was supplied when Emacs was started.
+ 
+ @node Text from Minibuffer
+ @section Reading Text Strings with the Minibuffer
+ 
+   Most often, the minibuffer is used to read text as a string.  It can
+ also be used to read a Lisp object in textual form.  The most basic
+ primitive for minibuffer input is @code{read-from-minibuffer}; it can do
+ either one.
+ 
+   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}.
+ 
+ @defun read-from-minibuffer prompt-string &optional initial-contents keymap 
read hist default inherit-input-method
+ This function is the most general way to get input through the
+ minibuffer.  By default, it accepts arbitrary text and returns it as a
+ string; however, if @var{read} is address@hidden, 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 address@hidden, @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 address@hidden, the user can access it using
+ @code{next-history-element}, usually bound in the minibuffer to
+ @kbd{M-n}.  If @var{read} is address@hidden, then @var{default} is
+ also used as the input to @code{read}, if the user enters empty input.
+ (If @var{read} is address@hidden and @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 is different from all
+ the other minibuffer input functions in this chapter.
+ 
+ If @var{keymap} is address@hidden, 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.
+ 
+ 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
+ address@hidden, 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 address@hidden, 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.
+ 
+ Use of @var{initial-contents} is mostly deprecated; we recommend using
+ a address@hidden value only in conjunction with specifying a cons cell
+ for @var{hist}.  @xref{Initial Input}.
+ @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 address@hidden, it also
+ specifies a default value to return if the user enters null input.  As
+ in @code{read-from-minibuffer} it should be a string, or @code{nil},
+ which is equivalent to an empty string.
+ 
+ This function is a simplified interface to the
+ @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})
+       @var{default}
+     value))
+ @end group
+ @end smallexample
+ @end defun
+ 
+ @defvar minibuffer-allow-text-properties
+ If this variable is @code{nil}, then @code{read-from-minibuffer} strips
+ all text properties from the minibuffer input before returning it.
+ This variable also affects @code{read-string}.  However,
+ @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
+ @anchor{Definition of 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}
+ 
+ @item @kbd{C-g}
+ @code{abort-recursive-edit}
+ 
+ @item @kbd{M-n}
+ @code{next-history-element}
+ 
+ @item @kbd{M-p}
+ @code{previous-history-element}
+ 
+ @item @kbd{M-s}
+ @code{next-matching-history-element}
+ 
+ @item @kbd{M-r}
+ @code{previous-matching-history-element}
+ @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
+ 
+ @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
+ 
+   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
+ This function reads a Lisp expression in the minibuffer, and then
+ evaluates it.  The difference between this command and
+ @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}.
+ 
+ The first thing @code{edit-and-eval-command} does is to activate the
+ minibuffer with @var{prompt} as the prompt.  Then it inserts the printed
+ representation of @var{form} in the minibuffer, and lets the user edit it.
+ When the user exits the minibuffer, the edited text is read with
+ @code{read} and then evaluated.  The resulting value becomes the value
+ of @code{edit-and-eval-command}.
+ 
+ In the following example, we offer the user an expression with initial
+ text which is a valid form already:
+ 
+ @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.
+ @code{edit-and-eval-command} returns @code{nil} in this example.
+ @end defun
+ 
+ @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
+ @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
+ behave as if @code{(elt @var{variable} (1- @var{STARTPOS}))} were the
+ 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
+ 
+   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.
+ 
+   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.
+ 
+ @defvar history-length
+ The value of this variable specifies the maximum length for all
+ history lists that don't specify their own maximum lengths.  If the
+ value is @code{t}, that means there no maximum (don't delete old
+ elements).
+ @end defvar
+ 
+   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
+ 
+ @node Initial Input
+ @section Initial Input
+ 
+ Several of the functions for minibuffer input have an argument called
+ @var{initial} or @var{initial-contents}.  This is a mostly-deprecated
+ feature for specifiying 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 address@hidden 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
+ @var{hist} or @var{history} argument.  @xref{Minibuffer History}.
+ 
+ @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,
+ 1 means the beginning of the string 2 means after the first character,
+ etc.
+ 
+ Use of a cons cell as the value for @var{initial} arguments is
+ deprecated in user code.
+ 
+ @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
+ 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.
+                              (These are too low level to use the minibuffer.)
+ * Minibuffer Completion::  Invoking the minibuffer with completion.
+ * Completion Commands::    Minibuffer commands that do completion.
+ * High-Level Completion::  Convenient special cases of completion
+                              (reading buffer name, file name, etc.)
+ * Reading File Names::     Using completion to read file names.
+ * Programmed Completion::  Writing your own completion-function.
+ @end menu
+ 
+ @node Basic Completion
+ @subsection Basic Completion Functions
+ 
+   The functions @code{try-completion}, @code{all-completions} and
+ @code{test-completion} have nothing in themselves to do with
+ minibuffers.  We describe them in this chapter so as to keep them near
+ the higher-level completion features that do use the minibuffer.
+ 
+ @defun try-completion string collection &optional predicate
+ This function returns the longest common substring of all possible
+ completions of @var{string} in @var{collection}.  The value of
+ @var{collection} must be a list of strings, an alist, an obarray, a
+ hash table, or a function that implements a virtual set of strings
+ (see below).
+ 
+ Completion compares @var{string} against each of the permissible
+ completions specified by @var{collection}; if the beginning of the
+ permissible completion equals @var{string}, it matches.  If no permissible
+ completions match, @code{try-completion} returns @code{nil}.  If only
+ one permissible completion matches, and the match is exact, then
+ @code{try-completion} returns @code{t}.  Otherwise, the value is the
+ longest initial sequence common to all the permissible completions that
+ match.
+ 
+ If @var{collection} is an alist (@pxref{Association Lists}), the
+ permissible completions are the elements of the alist that are either
+ strings or conses whose @sc{car} is a string.  Other elements of the
+ alist are ignored. (Remember that in Emacs Lisp, the elements of
+ alists do not @emph{have} to be conses.)  As all elements of the alist
+ can be strings, this case actually includes lists of strings, even
+ though we usually do not think of such lists as alists.
+ 
+ @cindex obarray in completion
+ If @var{collection} is an obarray (@pxref{Creating Symbols}), the names
+ of all symbols in the obarray form the set of permissible completions.  The
+ global variable @code{obarray} holds an obarray containing the names of
+ all interned Lisp symbols.
+ 
+ Note that the only valid way to make a new obarray is to create it
+ empty and then add symbols to it one by one using @code{intern}.
+ Also, you cannot intern a given symbol in more than one obarray.
+ 
+ If @var{collection} is a hash table, then the keys that are strings
+ are the possible completions.  Other keys are ignored.
+ 
+ You can also use a symbol that is a function as @var{collection}.  Then
+ the function is solely responsible for performing completion;
+ @code{try-completion} returns whatever this function returns.  The
+ function is called with three arguments: @var{string}, @var{predicate}
+ and @code{nil}.  (The reason for the third argument is so that the same
+ function can be used in @code{all-completions} and do the appropriate
+ thing in either case.)  @xref{Programmed Completion}.
+ 
+ If the argument @var{predicate} is address@hidden, 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 address@hidden  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
+ example, there is only one possible match, and it is exact, so the value
+ is @code{t}.
+ 
+ @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
+ 
+ @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 (aside from
+ @var{nospace}) are the same as those of @code{try-completion}.  Also,
+ this function uses @code{completion-regexp-list} in the same way that
+ @code{try-completion} does.  The optional argument @var{nospace} only
+ matters if @var{string} is the empty string.  In that case, if
+ @var{nospace} is address@hidden, completions that start with a space
+ are ignored.
+ 
+ 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 address@hidden if @var{string} is a valid
+ completion possibility specified by @var{collection} and
+ @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.
+ 
+ @code{test-completion} uses @code{completion-regexp-list} in the same
+ way that @code{try-completion} does.
+ 
+ If @var{predicate} is address@hidden 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.
+ @end defun
+ 
+ @defvar completion-ignore-case
+ If the value of this variable is address@hidden, Emacs does not
+ consider case significant in completion.
+ @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 &rest args
+ 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 the arguments @var{args}.  The
+ value @var{fun} returns becomes the permanent value of @var{var}.
+ 
+ Here are two examples of use:
+ 
+ @example
+ (defvar foo (lazy-completion-table foo make-my-alist 'global))
+ 
+ (make-local-variable 'bar)
+ (setq bar (lazy-completion-table foo make-my-alist 'local)
+ @end example
+ @end defmac
+ 
+ @node Minibuffer Completion
+ @subsection Completion and the Minibuffer
+ 
+   This section describes the basic interface for reading from the
+ 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.
+ Some of these commands also call @code{test-completion}.  Thus, if
+ @var{predicate} is address@hidden, it should be compatible with
+ @var{collection} and @code{completion-ignore-case}.  @xref{Definition
+ of test-completion}.
+ 
+ If @var{require-match} is @code{nil}, the exit commands work regardless
+ of the input in the minibuffer.  If @var{require-match} is @code{t}, the
+ usual minibuffer exit commands won't exit unless the input completes to
+ an element of @var{collection}.  If @var{require-match} is neither
+ @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}, or @code{""}, if @var{default} is @code{nil}.  The
+ value of @var{default} (if address@hidden) is also available to the
+ user through the history commands.
+ 
+ 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
+ address@hidden  @xref{Completion Commands}.
+ 
+ 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 argument @var{initial} is mostly deprecated; we recommend using a
+ address@hidden value only in conjunction with specifying a cons cell
+ for @var{hist}.  @xref{Initial Input}.  For default input, use
+ @var{default} instead.
+ 
+ If the argument @var{inherit-input-method} is address@hidden, 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.
+ 
+ Completion ignores case when comparing the input against the possible
+ matches, if the built-in variable @code{completion-ignore-case} is
+ address@hidden  @xref{Basic Completion}.
+ 
+ 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: address@hidden
+ ---------- Buffer: Minibuffer ----------
+ @end group
+ @end smallexample
+ 
+ @noindent
+ If the user then types @address@hidden @key{DEL} b @key{RET}},
+ @code{completing-read} returns @code{barfoo}.
+ 
+ The @code{completing-read} function binds three variables to pass
+ information to the commands that actually do completion.  These
+ variables are @code{minibuffer-completion-table},
+ @code{minibuffer-completion-predicate} and
+ @code{minibuffer-completion-confirm}.  For more information about them,
+ see @ref{Completion Commands}.
+ @end defun
+ 
+ @node Completion Commands
+ @subsection Minibuffer Commands that Do Completion
+ 
+   This section describes the keymaps, commands and user options used
+ in the minibuffer to do completion.  The description refers to the
+ situation when Partial Completion mode is disabled (as it is by
+ default).  When enabled, this minor mode uses its own alternatives to
+ some of the commands described below.  @xref{Completion Options,,,
+ emacs, The GNU Emacs Manual}, for a short description of Partial
+ Completion mode.
+ 
+ @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
+ with other characters bound as in @code{minibuffer-local-map}
+ (@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{?}
+ @code{minibuffer-completion-help}
+ 
+ @item @key{SPC}
+ @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
+ 
+ @noindent
+ with other characters bound as in @code{minibuffer-local-map}.
+ @end defvar
+ 
+ @defvar minibuffer-completion-table
+ The value of this variable is the collection 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}.
+ @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
+ 
+ @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
+ 
+ @defvar minibuffer-completion-confirm
+ When the value of this variable is address@hidden, Emacs asks for
+ confirmation of a completion before exiting the minibuffer.  The
+ function @code{minibuffer-complete-and-exit} checks the value of this
+ variable before it exits.
+ @end defvar
+ 
+ @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
+ @samp{*Completions*}.
+ @end deffn
+ 
+ @defun display-completion-list completions
+ 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.
+ 
+ This function is called by @code{minibuffer-completion-help}.  The
+ most common way to use it is together with
+ @code{with-output-to-temp-buffer}, like this:
+ 
+ @example
+ (with-output-to-temp-buffer "*Completions*"
+   (display-completion-list
+     (all-completions (buffer-string) my-alist)))
+ @end example
+ @end defun
+ 
+ @defopt completion-auto-help
+ If this variable is address@hidden, 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
+ 
+ @node High-Level Completion
+ @subsection High-Level Completion  Functions
+ 
+   This section describes the higher-level convenient functions for
+ 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}.
+ 
+ @defun read-buffer prompt &optional default existing
+ This function reads the name of a buffer and returns it as a string.
+ The argument @var{default} is the default name to use, the value to
+ return if the user exits with an empty minibuffer.  If address@hidden,
+ it should be a string or a buffer.  It is mentioned in the prompt, but
+ is not inserted in the minibuffer as initial input.
+ 
+ If @var{existing} is address@hidden, then the name specified must be
+ that of an existing buffer.  The usual commands to exit the minibuffer
+ do not exit if the text is not valid, and @key{RET} does completion to
+ attempt to find a valid name.  If @var{existing} is neither @code{nil}
+ nor @code{t}, confirmation is required after completion.  (However,
+ @var{default} is not checked for validity; it is returned, whatever it
+ is, if the user exits with the minibuffer empty.)
+ 
+ In the following example, the user enters @samp{minibuffer.t}, and
+ then types @key{RET}.  The argument @var{existing} is @code{t}, and the
+ only buffer name starting with the given input is
+ @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
+ 
+ @defvar read-buffer-function
+ This variable specifies how to read buffer names.  For example, if you
+ set this variable to @code{iswitchb-read-buffer}, all Emacs commands
+ that call @code{read-buffer} to read a buffer name will actually use the
+ @code{iswitchb} package to read it.
+ @end defvar
+ 
+ @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
+ 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{(intern "")}, that is, a
+ symbol whose name is an empty string.
+ 
+ @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}
+ 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{(intern "")}.
+ 
+ @example
+ @group
+ (read-variable "Variable name? ")
+ 
+ ;; @r{After evaluation of the preceding expression,}
+ ;;   @r{the following prompt appears,}
+ ;;   @r{with an empty minibuffer:}
+ @end group
+ 
+ @group
+ ---------- Buffer: Minibuffer ----------
+ Variable name? @point{}
+ ---------- Buffer: Minibuffer ----------
+ @end group
+ @end example
+ 
+ @noindent
+ If the user then types @kbd{fill-p @key{RET}}, @code{read-variable}
+ returns @code{fill-prefix}.
+ 
+ This function is similar to @code{read-command}, but uses the
+ predicate @code{user-variable-p} instead of @code{commandp}:
+ 
+ @cindex @code{user-variable-p} example
+ @example
+ @group
+ (read-variable @var{prompt})
+ @equiv{}
+ (intern
+  (completing-read @var{prompt} obarray
+                   '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{User-Chosen Coding Systems}.
+ 
+ @node Reading File Names
+ @subsection Reading File Names
+ 
+   Here is another high-level completion function, designed for reading a
+ file name.  It provides special features including automatic insertion
+ of the default directory.
+ 
+ @defun read-file-name prompt &optional directory default existing initial 
predicate
+ This function reads a file name in the minibuffer, prompting with
+ @var{prompt} and providing completion.
+ 
+ If @var{existing} is address@hidden, then the user must specify the name
+ of an existing file; @key{RET} performs completion to make the name
+ valid if possible, and then refuses to exit if it is not valid.  If the
+ value of @var{existing} is neither @code{nil} nor @code{t}, then
+ @key{RET} also requires confirmation after completion.  If
+ @var{existing} is @code{nil}, then the name of a nonexistent file is
+ acceptable.
+ 
+ The argument @var{directory} specifies the directory to use for
+ completion of relative file names.  It should be an absolute directory
+ name.  If @code{insert-default-directory} is address@hidden,
+ @var{directory} is also inserted in the minibuffer as initial input.
+ It defaults to the current buffer's value of @code{default-directory}.
+ 
+ @c Emacs 19 feature
+ If you specify @var{initial}, that is an initial file name to insert
+ in the buffer (after @var{directory}, if that is inserted).  In this
+ case, point goes at the beginning of @var{initial}.  The default for
+ @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{Please
+ note:} we recommend using @var{default} rather than @var{initial} in
+ most cases.
+ 
+ If @var{default} is address@hidden, 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 address@hidden, as it is by
+ default.  @var{default} is not checked for validity, regardless of the
+ value of @var{existing}.  However, if @var{existing} is
+ address@hidden, 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 address@hidden, 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
+ returns an empty string, regardless of the value of @var{existing}.
+ This is, for instance, how the user can make the current buffer visit
+ no file using @code{M-x set-visited-file-name}.
+ 
+ If @var{predicate} is address@hidden, it specifies a function of one
+ argument that decides which file names are acceptable completion
+ possibilities.  A file name is an acceptable value if @var{predicate}
+ returns address@hidden for it.
+ 
+ @code{read-file-name} does not automatically expand file names.  You
+ must call @code{expand-file-name} yourself if an absolute file name is
+ required.
+ 
+ Here is an example:
+ 
+ @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/address@hidden
+ ---------- 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
+ 
+ @defun read-directory-name prompt &optional directory default existing initial
+ This function is like @code{read-file-name} but allows only directory
+ names as completion possibilities.
+ 
+ If @var{default} is @code{nil} and @var{initial} is address@hidden,
+ @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 the
+ current buffer's default directory as substitute default, ignoring
+ @var{directory}.
+ @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
+ name if any.  If the value of this variable is @code{nil}, then
+ @code{read-file-name} does not place any initial input in the
+ minibuffer (unless you specify initial input with the @var{initial}
+ argument).  In that case, the default directory is still used for
+ completion of relative file names, but is not displayed.
+ 
+ If this variable is @code{nil} and the initial minibuffer contents are
+ empty, the user may have to explicitly fetch the next history element
+ to access a default value.  If the variable is address@hidden, the
+ initial minibuffer contents are always non-empty and the user can
+ always request a default value by immediately typing @key{RET} in an
+ unedited minibuffer.  (See above.)
+ 
+ For example:
+ 
+ @example
+ @group
+ ;; @r{Here the minibuffer starts out with the default directory.}
+ (let ((insert-default-directory t))
+   (read-file-name "The file is "))
+ @end group
+ 
+ @group
+ ---------- Buffer: Minibuffer ----------
+ The file is ~lewis/manual/@point{}
+ ---------- Buffer: Minibuffer ----------
+ @end group
+ 
+ @group
+ ;; @r{Here the minibuffer is empty and only the prompt}
+ ;;   @r{appears on its line.}
+ (let ((insert-default-directory nil))
+   (read-file-name "The file is "))
+ @end group
+ 
+ @group
+ ---------- Buffer: Minibuffer ----------
+ The file is @point{}
+ ---------- Buffer: Minibuffer ----------
+ @end group
+ @end example
+ @end defopt
+ 
+ @node Programmed Completion
+ @subsection Programmed Completion
+ @cindex programmed completion
+ 
+   Sometimes it is not possible to create an alist or an obarray
+ containing all the intended possible completions.  In such a case, you
+ can supply your own function to compute the completion of a given string.
+ This is called @dfn{programmed completion}.
+ 
+   To use this feature, pass a symbol with a function definition as the
+ @var{collection} argument to @code{completing-read}.  The function
+ @code{completing-read} arranges to pass your completion function along
+ to @code{try-completion} and @code{all-completions}, which will then let
+ your function do all the work.
+ 
+   The completion function should accept three arguments:
+ 
+ @itemize @bullet
+ @item
+ The string to be completed.
+ 
+ @item
+ The predicate function to filter possible matches, or @code{nil} if
+ none.  Your function should call the predicate for each possible match,
+ and ignore the possible match if the predicate returns @code{nil}.
+ 
+ @item
+ A flag specifying the type of operation.
+ @end itemize
+ 
+   There are three flag values for three operations:
+ 
+ @itemize @bullet
+ @item
+ @code{nil} specifies @code{try-completion}.  The completion function
+ should return the completion of the specified string, or @code{t} if the
+ 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
+ string.
+ 
+ @item
+ @code{lambda} specifies @code{test-completion}.  The completion
+ function should return @code{t} if the specified string is an exact
+ match for some possibility; @code{nil} otherwise.
+ @end itemize
+ 
+   It would be consistent and clean for completion functions to allow
+ lambda expressions (lists that are functions) as well as function
+ symbols as @var{collection}, but this is impossible.  Lists as
+ completion tables already have other meanings, and it would be
+ unreliable to treat one differently just because it is also a possible
+ function.  So you must arrange for any function you wish to use for
+ completion to be encapsulated in a symbol.
+ 
+   Emacs uses programmed completion when completing file names.
+ @xref{File Name Completion}.
+ 
+ @defmac dynamic-completion-table function
+ This macro is a convenient way to write a function that can act as
+ programmed completion function.  The argument @var{function} should be
+ a function that takes one argument, a string, and returns an alist of
+ possible completions of it.  You can think of
+ @code{dynamic-completion-table} as a transducer between that interface
+ and the interface for programmed completion functions.
+ @end defmac
+ 
+ @node Yes-or-No Queries
+ @section Yes-or-No Queries
+ @cindex asking the user questions
+ @cindex querying the user
+ @cindex yes-or-no questions
+ 
+   This section describes functions used to ask the user a yes-or-no
+ question.  The function @code{y-or-n-p} can be answered with a single
+ character; it is useful for questions where an inadvertent wrong answer
+ will not have serious consequences.  @code{yes-or-no-p} is suitable for
+ more momentous questions, since it requires three or four characters to
+ answer.
+ 
+    If either of these functions is called in a command that was invoked
+ using the mouse---more precisely, if @code{last-nonmenu-event}
+ (@pxref{Command Loop Info}) is either @code{nil} or a list---then it
+ uses a dialog box or pop-up menu to ask the question.  Otherwise, it
+ uses keyboard input.  You can force use of the mouse or use of keyboard
+ input by binding @code{last-nonmenu-event} to a suitable value around
+ the call.
+ 
+   Strictly speaking, @code{yes-or-no-p} uses the minibuffer and
+ @code{y-or-n-p} does not; but it seems best to describe them together.
+ 
+ @defun y-or-n-p prompt
+ This function asks the user a question, expecting input in the echo
+ area.  It returns @code{t} if the user types @kbd{y}, @code{nil} if the
+ user types @kbd{n}.  This function also accepts @key{SPC} to mean yes
+ and @key{DEL} to mean no.  It accepts @kbd{C-]} to mean ``quit'', like
+ @kbd{C-g}, because the question might look like a minibuffer and for
+ that reason the user might try to use @kbd{C-]} to get out.  The answer
+ is a single character, with no @key{RET} needed to terminate it.  Upper
+ and lower case are equivalent.
+ 
+ ``Asking the question'' means printing @var{prompt} in the echo area,
+ followed by the string @address@hidden(y or n) }}.  If the input is not one of
+ the expected answers (@kbd{y}, @kbd{n}, @address@hidden,
+ @address@hidden, or something that quits), the function responds
+ @samp{Please answer y or n.}, and repeats the request.
+ 
+ This function does not actually use the minibuffer, since it does not
+ allow editing of the answer.  It actually uses the echo area (@pxref{The
+ Echo Area}), which uses the same screen space as the minibuffer.  The
+ cursor moves to the echo area while the question is being asked.
+ 
+ The answers and their meanings, even @samp{y} and @samp{n}, are not
+ hardwired.  The keymap @code{query-replace-map} specifies them.
+ @xref{Search and Replace}.
+ 
+ In the following example, the user first types @kbd{q}, which is
+ invalid.  At the next prompt the user types @kbd{y}.
+ 
+ @smallexample
+ @group
+ (y-or-n-p "Do you need a lift? ")
+ 
+ ;; @r{After evaluation of the preceding expression,}
+ ;;   @r{the following prompt appears in the echo area:}
+ @end group
+ 
+ @group
+ ---------- Echo area ----------
+ Do you need a lift? (y or n)
+ ---------- Echo area ----------
+ @end group
+ 
+ ;; @r{If the user then types @kbd{q}, the following appears:}
+ 
+ @group
+ ---------- Echo area ----------
+ Please answer y or n.  Do you need a lift? (y or n)
+ ---------- Echo area ----------
+ @end group
+ 
+ ;; @r{When the user types a valid answer,}
+ ;;   @r{it is displayed after the question:}
+ 
+ @group
+ ---------- Echo area ----------
+ Do you need a lift? (y or n) y
+ ---------- Echo area ----------
+ @end group
+ @end smallexample
+ 
+ @noindent
+ We show successive lines of echo area messages, but only one actually
+ appears on the screen at a time.
+ @end defun
+ 
+ @defun y-or-n-p-with-timeout prompt seconds default-value
+ Like @code{y-or-n-p}, except that if the user fails to answer within
+ @var{seconds} seconds, this function stops waiting and returns
+ @var{default-value}.  It works by setting up a timer; see @ref{Timers}.
+ The argument @var{seconds} may be an integer or a floating point number.
+ @end defun
+ 
+ @defun yes-or-no-p prompt
+ This function asks the user a question, expecting input in the
+ minibuffer.  It returns @code{t} if the user enters @samp{yes},
+ @code{nil} if the user types @samp{no}.  The user must type @key{RET} to
+ finalize the response.  Upper and lower case are equivalent.
+ 
+ @code{yes-or-no-p} starts by displaying @var{prompt} in the echo area,
+ followed by @address@hidden(yes or no) }}.  The user must type one of the
+ expected responses; otherwise, the function responds @samp{Please answer
+ yes or no.}, waits about two seconds and repeats the request.
+ 
+ @code{yes-or-no-p} requires more work from the user than
+ @code{y-or-n-p} and is appropriate for more crucial decisions.
+ 
+ Here is an example:
+ 
+ @smallexample
+ @group
+ (yes-or-no-p "Do you really want to remove everything? ")
+ 
+ ;; @r{After evaluation of the preceding expression,}
+ ;;   @r{the following prompt appears,}
+ ;;   @r{with an empty minibuffer:}
+ @end group
+ 
+ @group
+ ---------- Buffer: minibuffer ----------
+ Do you really want to remove everything? (yes or no)
+ ---------- Buffer: minibuffer ----------
+ @end group
+ @end smallexample
+ 
+ @noindent
+ If the user first types @kbd{y @key{RET}}, which is invalid because this
+ function demands the entire word @samp{yes}, it responds by displaying
+ these prompts, with a brief pause between them:
+ 
+ @smallexample
+ @group
+ ---------- Buffer: minibuffer ----------
+ Please answer yes or no.
+ Do you really want to remove everything? (yes or no)
+ ---------- Buffer: minibuffer ----------
+ @end group
+ @end smallexample
+ @end defun
+ 
+ @node Multiple Queries
+ @section Asking Multiple Y-or-N Questions
+ 
+   When you have a series of similar questions to ask, such as ``Do you
+ want to save this buffer'' for each buffer in turn, you should use
+ @code{map-y-or-n-p} to ask the collection of questions, rather than
+ asking each question individually.  This gives the user certain
+ convenient facilities such as the ability to answer the whole series at
+ once.
+ 
+ @defun map-y-or-n-p prompter actor list &optional help action-alist 
no-cursor-in-echo-area
+ This function asks the user a series of questions, reading a
+ single-character answer in the echo area for each one.
+ 
+ The value of @var{list} specifies the objects to ask questions about.
+ It should be either a list of objects or a generator function.  If it is
+ a function, it should expect no arguments, and should return either the
+ next object to ask about, or @code{nil} meaning stop asking questions.
+ 
+ The argument @var{prompter} specifies how to ask each question.  If
+ @var{prompter} is a string, the question text is computed like this:
+ 
+ @example
+ (format @var{prompter} @var{object})
+ @end example
+ 
+ @noindent
+ where @var{object} is the next object to ask about (as obtained from
+ @var{list}).
+ 
+ If not a string, @var{prompter} should be a function of one argument
+ (the next object to ask about) and should return the question text.  If
+ the value is a string, that is the question to ask the user.  The
+ function can also return @code{t} meaning do act on this object (and
+ don't ask the user), or @code{nil} meaning ignore this object (and don't
+ ask the user).
+ 
+ The argument @var{actor} says how to act on the answers that the user
+ gives.  It should be a function of one argument, and it is called with
+ each object that the user says yes for.  Its argument is always an
+ object obtained from @var{list}.
+ 
+ If the argument @var{help} is given, it should be a list of this form:
+ 
+ @example
+ (@var{singular} @var{plural} @var{action})
+ @end example
+ 
+ @noindent
+ where @var{singular} is a string containing a singular noun that
+ describes the objects conceptually being acted on, @var{plural} is the
+ corresponding plural noun, and @var{action} is a transitive verb
+ describing what @var{actor} does.
+ 
+ If you don't specify @var{help}, the default is @code{("object"
+ "objects" "act on")}.
+ 
+ Each time a question is asked, the user may enter @kbd{y}, @kbd{Y}, or
+ @key{SPC} to act on that object; @kbd{n}, @kbd{N}, or @key{DEL} to skip
+ that object; @kbd{!} to act on all following objects; @key{ESC} or
+ @kbd{q} to exit (skip all following objects); @kbd{.} (period) to act on
+ the current object and then exit; or @kbd{C-h} to get help.  These are
+ the same answers that @code{query-replace} accepts.  The keymap
+ @code{query-replace-map} defines their meaning for @code{map-y-or-n-p}
+ as well as for @code{query-replace}; see @ref{Search and Replace}.
+ 
+ You can use @var{action-alist} to specify additional possible answers
+ and what they mean.  It is an alist of elements of the form
+ @code{(@var{char} @var{function} @var{help})}, each of which defines one
+ additional answer.  In this element, @var{char} is a character (the
+ answer); @var{function} is a function of one argument (an object from
+ @var{list}); @var{help} is a string.
+ 
+ When the user responds with @var{char}, @code{map-y-or-n-p} calls
+ @var{function}.  If it returns address@hidden, the object is considered
+ ``acted upon'', and @code{map-y-or-n-p} advances to the next object in
+ @var{list}.  If it returns @code{nil}, the prompt is repeated for the
+ same object.
+ 
+ Normally, @code{map-y-or-n-p} binds @code{cursor-in-echo-area} while
+ prompting.  But if @var{no-cursor-in-echo-area} is address@hidden, it
+ does not do that.
+ 
+ If @code{map-y-or-n-p} is called in a command that was invoked using the
+ mouse---more precisely, if @code{last-nonmenu-event} (@pxref{Command
+ Loop Info}) is either @code{nil} or a list---then it uses a dialog box
+ or pop-up menu to ask the question.  In this case, it does not use
+ keyboard input or the echo area.  You can force use of the mouse or use
+ of keyboard input by binding @code{last-nonmenu-event} to a suitable
+ value around the call.
+ 
+ The return value of @code{map-y-or-n-p} is the number of objects acted on.
+ @end defun
+ 
+ @node Reading a Password
+ @section Reading a Password
+ @cindex passwords, reading
+ 
+   To read a password to pass to another program, you can use the
+ function @code{read-passwd}.
+ 
+ @defun read-passwd prompt &optional confirm default
+ This function reads a password, prompting with @var{prompt}.  It does
+ not echo the password as the user types it; instead, it echoes @samp{.}
+ for each character in the password.
+ 
+ The optional argument @var{confirm}, if address@hidden, says to read the
+ password twice and insist it must be the same both times.  If it isn't
+ the same, the user has to type it over and over until the last two
+ times match.
+ 
+ The optional argument @var{default} specifies the default password to
+ return if the user enters empty input.  If @var{default} is @code{nil},
+ then @code{read-passwd} returns the null string in that case.
+ @end defun
+ 
+ @node Minibuffer Misc
+ @section Minibuffer Miscellany
+ 
+   This section describes some basic functions and variables related to
+ minibuffers.
+ 
+ @deffn Command exit-minibuffer
+ This command exits the active minibuffer.  It is normally bound to
+ keys in minibuffer local keymaps.
+ @end deffn
+ 
+ @deffn Command self-insert-and-exit
+ This command exits the active minibuffer after inserting the last
+ character typed on the keyboard (found in @code{last-command-char};
+ @pxref{Command Loop Info}).
+ @end deffn
+ 
+ @deffn Command previous-history-element n
+ This command replaces the minibuffer contents with the value of the
+ @var{n}th previous (older) history element.
+ @end deffn
+ 
+ @deffn Command next-history-element n
+ This command replaces the minibuffer contents with the value of the
+ @var{n}th more recent history element.
+ @end deffn
+ 
+ @deffn Command previous-matching-history-element pattern n
+ This command replaces the minibuffer contents with the value of the
+ @var{n}th previous (older) history element that matches @var{pattern} (a
+ regular expression).
+ @end deffn
+ 
+ @deffn Command next-matching-history-element pattern n
+ This command replaces the minibuffer contents with the value of the
+ @var{n}th next (newer) history element that matches @var{pattern} (a
+ regular expression).
+ @end deffn
+ 
+ @defun minibuffer-prompt
+ This function returns the prompt string of the currently active
+ minibuffer.  If no minibuffer is active, it returns @code{nil}.
+ @end defun
+ 
+ @defun minibuffer-prompt-end
+ @tindex minibuffer-prompt-end
+ This function, available starting in Emacs 21, returns the current
+ position of the end of the minibuffer prompt, if a minibuffer is
+ current.  Otherwise, it returns the minimum valid buffer position.
+ @end defun
+ 
+ @defun minibuffer-contents
+ @tindex minibuffer-contents
+ This function, available starting in Emacs 21, returns the editable
+ contents of the minibuffer (that is, everything except the prompt) as
+ a string, if a minibuffer is current.  Otherwise, it returns the
+ entire contents of the current buffer.
+ @end defun
+ 
+ @defun minibuffer-contents-no-properties
+ @tindex minibuffer-contents-no-properties
+ This is like @code{minibuffer-contents}, except that it does not copy text
+ properties, just the characters themselves.  @xref{Text Properties}.
+ @end defun
+ 
+ @defun delete-minibuffer-contents
+ @tindex delete-minibuffer-contents
+ This function, available starting in Emacs 21, erases the editable
+ contents of the minibuffer (that is, everything except the prompt), if
+ a minibuffer is current.  Otherwise, it erases the entire buffer.
+ @end defun
+ 
+ @defun minibuffer-prompt-width
+ This function returns the current display-width of the minibuffer
+ prompt, if a minibuffer is current.  Otherwise, it returns zero.
+ @end defun
+ 
+ @defvar minibuffer-setup-hook
+ This is a normal hook that is run whenever the minibuffer is entered.
+ @xref{Hooks}.
+ @end defvar
+ 
+ @defvar minibuffer-exit-hook
+ This is a normal hook that is run whenever the minibuffer is exited.
+ @xref{Hooks}.
+ @end defvar
+ 
+ @defvar minibuffer-help-form
+ @anchor{Definition of minibuffer-help-form}
+ The current value of this variable is used to rebind @code{help-form}
+ locally inside the minibuffer (@pxref{Help Functions}).
+ @end defvar
+ 
+ @defun minibufferp &optional buffer-or-name
+ This function returns address@hidden if @var{buffer-or-name} is a
+ minibuffer.  If @var{buffer-or-name} is omitted, it tests the current
+ buffer.
+ @end defun
+ 
+ @defun active-minibuffer-window
+ This function returns the currently active minibuffer window, or
+ @code{nil} if none is currently active.
+ @end defun
+ 
+ @defun minibuffer-window &optional frame
+ @anchor{Definition of minibuffer-window}
+ This function returns the minibuffer window used for frame @var{frame}.
+ If @var{frame} is @code{nil}, that stands for the current frame.  Note
+ that the minibuffer window used by a frame need not be part of that
+ frame---a frame that has no minibuffer of its own necessarily uses some
+ other frame's minibuffer window.
+ @end defun
+ 
+ @defun set-minibuffer-window window
+ This function specifies @var{window} as the minibuffer window to use.
+ This affects where the minibuffer is displayed if you put text in it
+ without invoking the usual minibuffer commands.  It has no effect on
+ the usual minibuffer input functions because they all start by
+ choosing the minibuffer window according to the current frame.
+ @end defun
+ 
+ @c Emacs 19 feature
+ @defun window-minibuffer-p &optional window
+ This function returns address@hidden if @var{window} is a minibuffer
+ window.
+ @var{window} defaults to the selected window.
+ @end defun
+ 
+ It is not correct to determine whether a given window is a minibuffer by
+ comparing it with the result of @code{(minibuffer-window)}, because
+ there can be more than one minibuffer window if there is more than one
+ frame.
+ 
+ @defun minibuffer-window-active-p window
+ This function returns address@hidden if @var{window}, assumed to be
+ a minibuffer window, is currently active.
+ @end defun
+ 
+ @defvar minibuffer-scroll-window
+ @anchor{Definition of minibuffer-scroll-window}
+ If the value of this variable is address@hidden, it should be a window
+ object.  When the function @code{scroll-other-window} is called in the
+ minibuffer, it scrolls this window.
+ @end defvar
+ 
+ @defun minibuffer-selected-window
+ This function returns the window which was selected when the
+ minibuffer was entered.  If selected window is not a minibuffer
+ window, it returns @code{nil}.
+ @end defun
+ 
+ Finally, some functions and variables deal with recursive minibuffers
+ (@pxref{Recursive Editing}):
+ 
+ @defun minibuffer-depth
+ This function returns the current depth of activations of the
+ minibuffer, a nonnegative integer.  If no minibuffers are active, it
+ returns zero.
+ @end defun
+ 
+ @defopt enable-recursive-minibuffers
+ If this variable is address@hidden, 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 address@hidden, then the command can use the minibuffer to read
+ arguments even if it is invoked from the minibuffer.  A command can
+ also achieve this by binding @code{enable-recursive-minibuffers}
+ to @code{t} in the interactive declaration (@pxref{Using Interactive}).
+ The minibuffer command @code{next-matching-history-element} (normally
+ @kbd{M-s} in the minibuffer) does the latter.
+ 
+ @defun minibuffer-message string
+ This function displays @var{string} temporarily at the end of the
+ minibuffer text, for two seconds, or until the next input event
+ arrives, whichever comes first.
+ @end defun
+ 
+ @ignore
+    arch-tag: bba7f945-9078-477f-a2ce-18818a6e1218
+ @end ignore