xemacs-beta: man/lispref/minibuf.texi comparison

comparison man/lispref/minibuf.texi @ 412:697ef44129c6 r21-2-14

Import from CVS: tag r21-2-14

author	cvs
date	Mon, 13 Aug 2007 11:20:41 +0200
parents	2f8bb876ab1d
children

comparison

equal deleted inserted replaced

-:12e008d41344
+:697ef44129c6
 * Minibuffer History::	      Recording previous minibuffer inputs
 				so the user can reuse them.
 * 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
 @emph{within} a buffer, such as editing commands, work normally in a
 minibuffer.  However, many operations for managing buffers do not apply
 to minibuffers.  The name of a minibuffer always has the form @w{@samp{
 *Minibuf-@var{number}}}, and it cannot be changed.  Minibuffers are
 displayed only in special windows used only for minibuffers; these
-windows always appear at the bottom of a frame.  (Sometimes frames have
+windows always appear at the bottom of a frame.  (Sometime frames have
 no minibuffer window, and sometimes a special kind of frame contains
 nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
 The minibuffer's window is normally a single line.  You can resize it
 temporarily with the window sizing commands; it reverts to its normal
 @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}.  This is used mainly for Mocklisp compatibility.
+@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.
 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} spec.
 @xref{Defining Commands}.
-@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist abbrev-table default
+@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
 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
 @code{read} to convert the text into a Lisp object (@pxref{Input
 Functions}).
 The value of @var{initial-contents} may also be a cons cell of the form
 @code{(@var{string} . @var{position})}.  This means to insert
 @var{string} in the minibuffer but put point @var{position} characters
 from the beginning, rather than at the end.
-When the user types a command to exit the minibuffer,
-@code{read-from-minibuffer} constructs the return value from the text in
-the minibuffer.  Normally it returns a string containing that text.
-However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
-reads the text and returns the resulting Lisp object, unevaluated.
-(@xref{Input Functions}, for information about reading.)
-The argument @var{default} specifies a default value to make available
-through the history commands.  It should be a string, or @code{nil}.
 If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
 use in the minibuffer.  If @var{keymap} is omitted or @code{nil}, the
 value of @code{minibuffer-local-map} is used as the keymap.  Specifying
 a keymap is the most important way to customize the minibuffer for
 various applications such as completion.
-The argument @var{abbrev-table} specifies @code{local-abbrev-table} in
-the minibuffer (@pxref{Standard Abbrev Tables}).
 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}.
 its return value.  Normally it simply makes a string containing that
 text.  However, if @var{read} is non-@code{nil},
 @code{read-from-minibuffer} reads the text and returns the resulting
 Lisp object, unevaluated.  (@xref{Input Functions}, for information
 about reading.)
+@end defun
-@strong{Usage note:} The @var{initial-contents} argument and the
-@var{default} argument are two alternative features for more or less the
+@defun read-string prompt &optional initial
-same job.  It does not make sense to use both features in a single call
-to @code{read-from-minibuffer}.  In general, we recommend using
-@var{default}, since this permits the user to insert the default value
-when it is wanted, but does not burden the user with deleting it from
-the minibuffer on other occasions.  However, if user is supposed to edit
-default value, @var{initial-contents} may be preferred.
-@end defun
-@defun read-string prompt &optional initial history default-value
 This function reads a string from the minibuffer and returns it.  The
 arguments @var{prompt} and @var{initial} are used as in
 @code{read-from-minibuffer}.  The keymap used is
 @code{minibuffer-local-map}.
-The optional argument @var{history}, if non-nil, specifies a history
+This is a simplified interface to the
-list and optionally the initial position in the list.  The optional
-argument @var{default} specifies a default value to return if the user
-enters null input; it should be a 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})
+(read-string @var{prompt} @var{initial})
 @equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil nil
+(read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
-@var{history} nil @var{default})))
 @end group
 @end smallexample
 @end defun
 @defvar minibuffer-local-map
 This is the default local keymap for reading from the minibuffer.  By
 default, it makes the following bindings:
 @table @asis
-@item @kbd{C-j}
+@item @key{LFD}
 @code{exit-minibuffer}
 @item @key{RET}
 @code{exit-minibuffer}
 @item @kbd{M-s}
 @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
+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} and @var{initial} 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.
+@smallexample
+@group
+(read-no-blanks-input @var{prompt} @var{initial})
+@equiv{}
+(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-expression prompt &optional initial history default-value
+@defun read-minibuffer prompt &optional initial
-This function reads a Lisp object using the minibuffer, and returns it
+This function reads a Lisp object in the minibuffer and returns it,
 without evaluating it.  The arguments @var{prompt} and @var{initial} are
 used as in @code{read-from-minibuffer}.
-The optional argument @var{history}, if non-nil, specifies a history
-list and optionally the initial position in the list.  The optional
-argument @var{default-value} specifies a default value to return if the
-user enters null input; it should be a string.
 This is a simplified interface to the
 @code{read-from-minibuffer} function:
 @smallexample
 @group
-(read-expression @var{prompt} @var{initial} @var{history} @var{default-value})
+(read-minibuffer @var{prompt} @var{initial})
 @equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil t
+(read-from-minibuffer @var{prompt} @var{initial} nil t)
-@var{history} nil @var{default-value})
 @end group
 @end smallexample
 Here is an example in which we supply the string @code{"(testing)"} as
 initial input:
 @smallexample
 @group
-(read-expression
+(read-minibuffer
 "Enter an expression: " (format "%s" '(testing)))
 ;; @r{Here is how the minibuffer is displayed:}
 @end group
 @noindent
 The user can type @key{RET} immediately to use the initial input as a
 default, or can edit the input.
 @end defun
-@defun read-minibuffer prompt &optional initial history default-value
+@defun eval-minibuffer prompt &optional initial
+This function reads a Lisp expression in the minibuffer, evaluates it,
-This is a FSF Emacs compatible function.  Use @code{read-expression}
+then returns the result.  The arguments @var{prompt} and @var{initial}
-instead.
+are used as in @code{read-from-minibuffer}.
-@end defun
-@defun eval-minibuffer prompt &optional initial history default-value
-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}.
-The optional argument @var{history}, if non-nil, specifies a history
-list and optionally the initial position in the list.  The optional
-argument @var{default-value} specifies a default value to return if the
-user enters null input; it should be a string.
 This function simply evaluates the result of a call to
-@code{read-expression}:
+@code{read-minibuffer}:
 @smallexample
 @group
 (eval-minibuffer @var{prompt} @var{initial})
 @equiv{}
-(eval (read-expression @var{prompt} @var{initial}))
+(eval (read-minibuffer @var{prompt} @var{initial}))
 @end group
 @end smallexample
 @end defun
-@defun edit-and-eval-command prompt command &optional history
+@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{command} is not
+@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.
+representation of @var{form} in the minibuffer, and lets the user edit.
 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
 elements to the history list automatically, and provide commands to
 allow the user to reuse items on the list.  The only thing your program
 needs to do to use a history list is to initialize it and to pass its
 name to the input functions when you wish.  But it is safe to modify the
 list by hand when the minibuffer input functions are not using it.
-Here are some of the standard minibuffer history list variables:
 @defvar minibuffer-history
 The default history list for minibuffer history input.
 @end defvar
 @end smallexample
 @end defun
 @defun all-completions string collection &optional predicate nospace
 This function returns a list of all possible completions of
-@var{string}.  The arguments to this function are the same as those of
+@var{string}.  The parameters to this function are the same as to
 @code{try-completion}.
 If @var{collection} is a function, it is called with three arguments:
 @var{string}, @var{predicate} and @code{t}; then @code{all-completions}
 returns whatever the function returns.  @xref{Programmed Completion}.
 @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
+@defun completing-read prompt collection &optional predicate require-match initial hist
 This function reads a string in the minibuffer, assisting the user by
 providing completion.  It activates the minibuffer with prompt
 @var{prompt}, which must be a string.  If @var{initial} is
 non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
 part of the input.  Then it allows the user to edit the input, providing
 If @var{require-match} is neither @code{nil} nor @code{t}, then the exit
 commands won't exit unless the input typed is itself an element of
 @var{collection}.  If @var{require-match} is @code{nil}, the exit
 commands work regardless of the input in the minibuffer.
-However, empty input is always permitted, regardless of the value of
-@var{require-match}; in that case, @code{completing-read} returns
-@var{default}.  The value of @var{default} (if non-@code{nil}) is also
-available to the user through the history commands.
 The user can exit with null input by typing @key{RET} with an empty
-minibuffer.  Then @code{completing-read} returns @code{""}.  This is how
+minibuffer.  Then @code{completing-read} returns @code{nil}.  This is
-the user requests whatever default the command uses for the value being
+how the user requests whatever default the command uses for the value
-read.  The user can return using @key{RET} in this way regardless of the
+being read.  The user can return using @key{RET} in this way regardless
-value of @var{require-match}, and regardless of whether the empty string
+of the value of @var{require-match}.
-is included in @var{collection}.
 The function @code{completing-read} works by calling
-@code{read-expression}.  It uses @code{minibuffer-local-completion-map}
+@code{read-minibuffer}.  It uses @code{minibuffer-local-completion-map}
 as the keymap if @var{require-match} is @code{nil}, and uses
 @code{minibuffer-local-must-match-map} if @var{require-match} is
 non-@code{nil}.  @xref{Completion Commands}.
 The argument @var{hist} specifies which history list variable to use for
 @code{minibuffer-complete-word}
 @item @key{TAB}
 @code{minibuffer-complete}
-@item @kbd{C-j}
+@item @key{LFD}
 @code{minibuffer-complete-and-exit}
 @item @key{RET}
 @code{minibuffer-complete-and-exit}
 @end table
 @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
+@code{minibuffer-completion-confirm} is non-@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
 @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 &rest cl-keys
+@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
 @result{} "minibuffer.texi"
 @end group
 @end example
 @end defun
-@defun read-command prompt &optinal default-value
+@defun read-command prompt
 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-value} specifies what to return if the user
-enters null input.  It can be a symbol or a string; if it is a string,
-@code{read-command} interns it before returning it.  If @var{default} is
-@code{nil}, that means no default has been specified; then if the user
-enters null input, the return value is @code{nil}.
 @example
 (read-command "Command name? ")
 @group
 ;; @r{After evaluation of the preceding expression,}
 'commandp t nil))
 @end group
 @end example
 @end defun
-@defun read-variable prompt &optional default-value
+@defun read-variable prompt
 This function reads the name of a user variable and returns it as a
 symbol.
-The argument @var{default-value} specifies what to return if the user
-enters null input.  It can be a symbol or a string; if it is a string,
-@code{read-variable} interns it before returning it.  If @var{default}
-is @code{nil}, that means no default has been specified; then if the
-user enters null input, the return value is @code{nil}.
 @example
 @group
 (read-variable "Variable name? ")
 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 history
+@defun read-file-name prompt &optional directory default existing initial
 This function reads a file name in the minibuffer, prompting with
 @var{prompt} and providing completion.  If @var{default} is
 non-@code{nil}, then the function returns @var{default} if the user just
 types @key{RET}.  @var{default} is not checked for validity; it is
 returned, whatever it is, if the user exits with the minibuffer empty.
 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
+the buffer (after with @var{directory}, if that is inserted).  In this
 case, point goes at the beginning of @var{initial}.  The default for
 @var{initial} is @code{nil}---don't insert any file name.  To see what
 @var{initial} does, try the command @kbd{C-x C-v}.
 Here is an example:
 @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
+string is an exact match already, or @code{nil} if the string matches no
-matches no possibility.
+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.
 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 non-@code{nil}, 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.  It is translated to @samp{.}
-and inserted in the minibuffer. If @var{default} is @code{nil}, then
-@code{read-passwd} returns the null string in that case.
-@end defun
-@defopt passwd-invert-frame-when-keyboard-grabbed
-If non-nil swap the foreground and background colors of all faces while
-reading a password.  Default values is @code{t} unless feature
-@code{infodock} is provided.
-@end defopt
-@defopt passwd-echo
-This specifies the character echoed when typing a password.  When nil,
-nothing is echoed.
-@end defopt
 @node Minibuffer Misc
 @section Minibuffer Miscellany
 This section describes some basic functions and variables related to
 minibuffers.
 returns zero.
 @end defun
 @defopt enable-recursive-minibuffers
 If this variable is non-@code{nil}, you can invoke commands (such as
-@code{find-file}) that use minibuffers even while the minibuffer window
+@code{find-file}) that use minibuffers even while in the minibuffer
-is active.  Such invocation produces a recursive editing level for a new
+window.  Such invocation produces a recursive editing level for a new
 minibuffer.  The outer-level minibuffer is invisible while you are
 editing the inner one.
 This variable only affects invoking the minibuffer while the
 minibuffer window is selected.   If you switch windows while in the
 This is not implemented in XEmacs because it is a kludge.  If you
 want to explicitly set the value of @code{enable-recursive-minibuffers}
 in this fashion, just use an evaluated interactive spec and bind
 @code{enable-recursive-minibuffers} while reading from the minibuffer.
 See the definition of @code{next-matching-history-element} in
-@file{lisp/minibuf.el}.
+@file{lisp/prim/minibuf.el}.

Mercurial > hg > xemacs-beta

comparison man/lispref/minibuf.texi @ 412:697ef44129c6 r21-2-14