*** empty log message ***

[gnu-emacs] / lispref / minibuf.texi

diff --git a/lispref/minibuf.texi b/lispref/minibuf.texi
index 3ac750d76a1afb7b84afbe7a18e7a690333b44fe..a6153fdaca2a8fe1710c94736fdeee026fb7aee4 100644 (file)
--- a/lispref/minibuf.texi
+++ b/lispref/minibuf.texi
@@ -111,14 +111,15 @@ was supplied when Emacs was started.
   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
   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.
+either one.  There are also specialized commands for reading
+commands, variables, file names, etc. (@pxref{Completion}).

 
   In most cases, you should not call minibuffer input functions in the
 middle of a Lisp function.  Instead, do all minibuffer input as part of
 reading the arguments for a command, in the @code{interactive}
 specification.  @xref{Defining Commands}.
 
 
   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
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method keep-all

 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 non-@code{nil}, then it uses
 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 non-@code{nil}, then it uses


@@ -170,6 +171,9 @@ the setting of @code{enable-multibyte-characters} (@pxref{Text
 Representations}) from whichever buffer was current before entering the
 minibuffer.
 
 Representations}) from whichever buffer was current before entering the
 minibuffer.
 

+If @var{keep-all} is non-@code{nil}, even empty and duplicate inputs
+are added to the history list.
+

 Use of @var{initial-contents} is mostly deprecated; we recommend using
 a non-@code{nil} value only in conjunction with specifying a cons cell
 for @var{hist}.  @xref{Initial Input}.
 Use of @var{initial-contents} is mostly deprecated; we recommend using
 a non-@code{nil} value only in conjunction with specifying a cons cell
 for @var{hist}.  @xref{Initial Input}.


@@ -231,9 +235,11 @@ default, it makes the following bindings:
 @code{abort-recursive-edit}
 
 @item @kbd{M-n}
 @code{abort-recursive-edit}
 
 @item @kbd{M-n}

+@itemx @key{DOWN}

 @code{next-history-element}
 
 @item @kbd{M-p}
 @code{next-history-element}
 
 @item @kbd{M-p}

+@itemx @key{UP}

 @code{previous-history-element}
 
 @item @kbd{M-s}
 @code{previous-history-element}
 
 @item @kbd{M-s}


@@ -408,10 +414,9 @@ symbol, not a list; it is a variable whose value is a list of strings
 inputs.  It's the Lisp programmer's job to specify the right history
 list for each use of the minibuffer.
 
 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:
+  You specify the history list with the optional @var{hist} argument
+to either @code{read-from-minibuffer} or @code{completing-read}.  Here
+are the possible values for it:

 
 @table @asis
 @item @var{variable}
 
 @table @asis
 @item @var{variable}


@@ -581,17 +586,18 @@ for reading certain kinds of names with completion.
 @node Basic Completion
 @subsection Basic Completion Functions
 
 @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.
+  The completion functions @code{try-completion},
+@code{all-completions} and @code{test-completion} have nothing in
+themselves to do with minibuffers.  We describe them in this chapter
+so as to keep them near the higher-level completion features that do
+use the minibuffer.

 
 @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
 
 @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).
+@var{collection} must be a list of strings or symbols, an alist, an
+obarray, a hash table, or a function that implements a virtual set of
+strings (see below).

 
 Completion compares @var{string} against each of the permissible
 completions specified by @var{collection}; if the beginning of the
 
 Completion compares @var{string} against each of the permissible
 completions specified by @var{collection}; if the beginning of the


@@ -604,11 +610,13 @@ match.
 
 If @var{collection} is an alist (@pxref{Association Lists}), the
 permissible completions are the elements of the alist that are either
 
 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.
+strings, symbols, or conses whose @sc{car} is a string or symbol.
+Symbols are converted to strings using @code{symbol-name}.
+Other elements of the alist are ignored. (Remember that in Emacs Lisp,
+the elements of alists do not @emph{have} to be conses.)  As all
+elements of the alist can be strings, this case actually includes
+lists of strings or symbols, 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
 
 @cindex obarray in completion
 If @var{collection} is an obarray (@pxref{Creating Symbols}), the names


@@ -780,12 +788,12 @@ value @var{fun} returns becomes the permanent value of @var{var}.
 
 Here are two examples of use:
 
 
 Here are two examples of use:
 

-@example
+@smallexample

 (defvar foo (lazy-completion-table foo make-my-alist 'global))
 
 (make-local-variable 'bar)
 (setq bar (lazy-completion-table foo make-my-alist 'local)
 (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 smallexample

 @end defmac
 
 @node Minibuffer Completion
 @end defmac
 
 @node Minibuffer Completion


@@ -871,12 +879,9 @@ Complete a foo: fo@point{}
 If the user then types @kbd{@key{DEL} @key{DEL} b @key{RET}},
 @code{completing-read} returns @code{barfoo}.
 
 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 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}.
+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
 
 @node Completion Commands
 @end defun
 
 @node Completion Commands


@@ -890,55 +895,6 @@ some of the commands described below.  @xref{Completion Options,,,
 emacs, The GNU Emacs Manual}, for a short description of Partial
 Completion mode.
 
 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
 @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


@@ -952,6 +908,13 @@ passes to @code{try-completion}.  The variable is also used by the other
 minibuffer completion functions.
 @end defvar
 
 minibuffer completion functions.
 @end defvar
 

+@defvar minibuffer-completion-confirm
+When the value of this variable is non-@code{nil}, Emacs asks for
+confirmation of a completion before exiting the minibuffer.
+@code{completing-read} binds this variable, and the function
+@code{minibuffer-complete-and-exit} checks the value before exiting.
+@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,
 @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,


@@ -972,13 +935,6 @@ immediately---the command is programmed to work without confirmation
 when run twice in succession.
 @end deffn
 
 when run twice in succession.
 @end deffn
 

-@defvar minibuffer-completion-confirm
-When the value of this variable is non-@code{nil}, 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}
 @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}


@@ -1017,6 +973,55 @@ automatically display a list of possible completions whenever nothing
 can be completed because the next character is not uniquely determined.
 @end defopt
 
 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
+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
+

 @node High-Level Completion
 @subsection High-Level Completion  Functions
 
 @node High-Level Completion
 @subsection High-Level Completion  Functions
 


@@ -1281,6 +1286,18 @@ 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
 
 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
+
+@defvar read-file-name-completion-ignore-case
+If this variable is non-@code{nil}, @code{read-file-name} ignores case
+when performing completion.
+@end defvar
+

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


@@ -1289,9 +1306,9 @@ 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
 @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}.
+@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
 @end defun
 
 @defopt insert-default-directory


@@ -1723,14 +1740,14 @@ minibuffer.  If no minibuffer is active, it returns @code{nil}.
 
 @defun minibuffer-prompt-end
 @tindex minibuffer-prompt-end
 
 @defun minibuffer-prompt-end
 @tindex minibuffer-prompt-end

-This function, available starting in Emacs 21, returns the current
+This function 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
 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
+This function 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.
 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.


@@ -1744,7 +1761,7 @@ properties, just the characters themselves.  @xref{Text Properties}.
 
 @defun delete-minibuffer-contents
 @tindex delete-minibuffer-contents
 
 @defun delete-minibuffer-contents
 @tindex delete-minibuffer-contents

-This function, available starting in Emacs 21, erases the editable
+This function 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
 contents of the minibuffer (that is, everything except the prompt), if
 a minibuffer is current.  Otherwise, it erases the entire buffer.
 @end defun