-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
* 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.
\1f
apply to minibuffers. The name of a minibuffer always has the form
` *Minibuf-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. (Sometime frames have
+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 *Note Minibuffers and Frames::.)
* `minibuffer-local-map' is for ordinary input (no completion).
- * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
- like <RET>. This is used mainly for Mocklisp compatibility.
-
* `minibuffer-local-completion-map' is for permissive completion.
* `minibuffer-local-must-match-map' is for strict completion and for
Defining Commands::.
- Function: read-from-minibuffer prompt-string &optional
- initial-contents keymap read hist
+ initial-contents keymap read hist abbrev-table default
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 READ is non-`nil', then it uses `read' to
minibuffer but put point POSITION characters from the beginning,
rather than at the end.
+ When the user types a command to exit the minibuffer,
+ `read-from-minibuffer' constructs the return value from the text in
+ the minibuffer. Normally it returns a string containing that text.
+ However, if READ is non-`nil', `read-from-minibuffer' reads the
+ text and returns the resulting Lisp object, unevaluated. (*Note
+ Input Functions::, for information about reading.)
+
+ The argument DEFAULT specifies a default value to make available
+ through the history commands. It should be a string, or `nil'.
+
If KEYMAP is non-`nil', that keymap is the local keymap to use in
the minibuffer. If KEYMAP is omitted or `nil', the value of
`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 ABBREV-TABLE specifies `local-abbrev-table' in the
+ minibuffer (*note Standard Abbrev Tables::).
+
The argument HIST specifies which history list variable to use for
saving the input and for history commands used in the minibuffer.
It defaults to `minibuffer-history'. *Note Minibuffer History::.
reads the text and returns the resulting Lisp object, unevaluated.
(*Note Input Functions::, for information about reading.)
- - Function: read-string prompt &optional initial
+ *Usage note:* The INITIAL-CONTENTS argument and the DEFAULT
+ argument are two alternative features for more or less the same
+ job. It does not make sense to use both features in a single call
+ to `read-from-minibuffer'. In general, we recommend using
+ 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, INITIAL-CONTENTS may be preferred.
+
+ - Function: read-string prompt &optional initial history default-value
This function reads a string from the minibuffer and returns it.
The arguments PROMPT and INITIAL are used as in
`read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
- This is a simplified interface to the `read-from-minibuffer'
- function:
+ The optional argument HISTORY, if non-nil, specifies a history
+ list and optionally the initial position in the list. The optional
+ argument 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
+ `read-from-minibuffer' function:
- (read-string PROMPT INITIAL)
+ (read-string PROMPT INITIAL HISTORY DEFAULT)
==
- (read-from-minibuffer PROMPT INITIAL nil nil nil)
+ (read-from-minibuffer PROMPT INITIAL nil nil
+ HISTORY nil DEFAULT)))
- Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer.
By default, it makes the following bindings:
- <LFD>
+ `C-j'
`exit-minibuffer'
<RET>
`M-s'
`previous-matching-history-element'
- - Function: 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 PROMPT and INITIAL
- are used as in `read-from-minibuffer'.
-
- This is a simplified interface to the `read-from-minibuffer'
- function, and passes the value of the `minibuffer-local-ns-map'
- keymap as the KEYMAP argument for that function. Since the keymap
- `minibuffer-local-ns-map' does not rebind `C-q', it _is_ possible
- to put a space into the string, by quoting it.
-
- (read-no-blanks-input PROMPT INITIAL)
- ==
- (read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map)
-
- - Variable: minibuffer-local-ns-map
- This built-in variable is the keymap used as the minibuffer local
- keymap in the function `read-no-blanks-input'. By default, it
- makes the following bindings, in addition to those of
- `minibuffer-local-map':
-
- <SPC>
- `exit-minibuffer'
-
- <TAB>
- `exit-minibuffer'
-
- `?'
- `self-insert-and-exit'
-
\1f
File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
This section describes functions for reading Lisp objects with the
minibuffer.
- - Function: read-minibuffer prompt &optional initial
- This function reads a Lisp object in the minibuffer and returns it,
- without evaluating it. The arguments PROMPT and INITIAL are used
- as in `read-from-minibuffer'.
+ - Function: read-expression prompt &optional initial history
+ default-value
+ This function reads a Lisp object using the minibuffer, and
+ returns it without evaluating it. The arguments PROMPT and
+ INITIAL are used as in `read-from-minibuffer'.
+
+ The optional argument HISTORY, if non-nil, specifies a history
+ list and optionally the initial position in the list. The optional
+ argument 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 `read-from-minibuffer'
function:
- (read-minibuffer PROMPT INITIAL)
+ (read-expression PROMPT INITIAL HISTORY DEFAULT-VALUE)
==
- (read-from-minibuffer PROMPT INITIAL nil t)
+ (read-from-minibuffer PROMPT INITIAL nil t
+ HISTORY nil DEFAULT-VALUE)
Here is an example in which we supply the string `"(testing)"' as
initial input:
- (read-minibuffer
+ (read-expression
"Enter an expression: " (format "%s" '(testing)))
;; Here is how the minibuffer is displayed:
The user can type <RET> immediately to use the initial input as a
default, or can edit the input.
- - Function: eval-minibuffer prompt &optional initial
- This function reads a Lisp expression in the minibuffer, evaluates
- it, then returns the result. The arguments PROMPT and INITIAL are
- used as in `read-from-minibuffer'.
+ - Function: read-minibuffer prompt &optional initial history
+ default-value
+ This is a FSF Emacs compatible function. Use `read-expression'
+ instead.
+
+ - Function: 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 PROMPT and
+ INITIAL are used as in `read-from-minibuffer'.
+
+ The optional argument HISTORY, if non-nil, specifies a history
+ list and optionally the initial position in the list. The optional
+ argument 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
- `read-minibuffer':
+ `read-expression':
(eval-minibuffer PROMPT INITIAL)
==
- (eval (read-minibuffer PROMPT INITIAL))
+ (eval (read-expression PROMPT INITIAL))
- - Function: edit-and-eval-command prompt form
+ - Function: edit-and-eval-command prompt command &optional history
This function reads a Lisp expression in the minibuffer, and then
evaluates it. The difference between this command and
- `eval-minibuffer' is that here the initial FORM is not optional
+ `eval-minibuffer' is that here the initial COMMAND 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
`prin1', so if it is a string, double-quote characters (`"')
The first thing `edit-and-eval-command' does is to activate the
minibuffer with PROMPT as the prompt. Then it inserts the printed
- representation of FORM in the minibuffer, and lets the user edit.
- When the user exits the minibuffer, the edited text is read with
- `read' and then evaluated. The resulting value becomes the value
- of `edit-and-eval-command'.
+ representation of FORM in the minibuffer, and lets the user edit
+ it. When the user exits the minibuffer, the edited text is read
+ with `read' and then evaluated. The resulting value becomes the
+ value of `edit-and-eval-command'.
In the following example, we offer the user an expression with
initial text which is a valid form already:
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:
+
- Variable: minibuffer-history
The default history list for minibuffer history input.
- Function: all-completions string collection &optional predicate
nospace
This function returns a list of all possible completions of
- STRING. The parameters to this function are the same as to
+ STRING. The arguments to this function are the same as those of
`try-completion'.
If COLLECTION is a function, it is called with three arguments:
minibuffer with completion.
- Function: completing-read prompt collection &optional predicate
- require-match initial hist
+ require-match initial hist default
This function reads a string in the minibuffer, assisting the user
by providing completion. It activates the minibuffer with prompt
PROMPT, which must be a string. If INITIAL is non-`nil',
COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work
regardless of the input in the minibuffer.
+ However, empty input is always permitted, regardless of the value
+ of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT.
+ The value of DEFAULT (if non-`nil') is also available to the user
+ through the history commands.
+
The user can exit with null input by typing <RET> with an empty
- minibuffer. Then `completing-read' returns `nil'. This is how
- the user requests whatever default the command uses for the value
- being read. The user can return using <RET> in this way regardless
- of the value of REQUIRE-MATCH.
+ minibuffer. Then `completing-read' returns `""'. This is how the
+ user requests whatever default the command uses for the value being
+ read. The user can return using <RET> in this way regardless of
+ the value of REQUIRE-MATCH, and regardless of whether the empty
+ string is included in COLLECTION.
- The function `completing-read' works by calling `read-minibuffer'.
+ The function `completing-read' works by calling `read-expression'.
It uses `minibuffer-local-completion-map' as the keymap if
REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::.
`minibuffer-completion-confirm'. For more information about them,
see *Note Completion Commands::.
-\1f
-File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
-
-Minibuffer Commands That Do Completion
---------------------------------------
-
- This section describes the keymaps, commands and user options used in
-the minibuffer to do completion.
-
- - Variable: minibuffer-local-completion-map
- `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:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- with other characters bound as in `minibuffer-local-map' (*note
- Text from Minibuffer::).
-
- - Variable: minibuffer-local-must-match-map
- `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 `exit-minibuffer', the command that exits the
- minibuffer unconditionally. By default, this keymap makes the
- following bindings:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- <LFD>
- `minibuffer-complete-and-exit'
-
- <RET>
- `minibuffer-complete-and-exit'
-
- with other characters bound as in `minibuffer-local-map'.
-
- - Variable: minibuffer-completion-table
- The value of this variable is the alist or obarray used for
- completion in the minibuffer. This is the global variable that
- contains what `completing-read' passes to `try-completion'. It is
- used by minibuffer completion commands such as
- `minibuffer-complete-word'.
-
- - Variable: minibuffer-completion-predicate
- This variable's value is the predicate that `completing-read'
- passes to `try-completion'. The variable is also used by the other
- minibuffer completion functions.
-
- - 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,
- `minibuffer-complete-word' does not add any characters beyond the
- first character that is not a word constituent. *Note Syntax
- Tables::.
-
- - Command: minibuffer-complete
- This function completes the minibuffer contents as far as possible.
-
- - Command: minibuffer-complete-and-exit
- This function completes the minibuffer contents, and exits if
- confirmation is not required, i.e., if
- `minibuffer-completion-confirm' is non-`nil'. If confirmation
- _is_ required, it is given by repeating this command
- immediately--the command is programmed to work without confirmation
- when run twice in succession.
-
- - Variable: minibuffer-completion-confirm
- When the value of this variable is non-`nil', XEmacs asks for
- confirmation of a completion before exiting the minibuffer. The
- function `minibuffer-complete-and-exit' checks the value of this
- variable before it exits.
-
- - Command: minibuffer-completion-help
- This function creates a list of the possible completions of the
- current minibuffer contents. It works by calling `all-completions'
- using the value of the variable `minibuffer-completion-table' as
- the COLLECTION argument, and the value of
- `minibuffer-completion-predicate' as the PREDICATE argument. The
- list of completions is displayed as text in a buffer named
- `*Completions*'.
-
- - Function: display-completion-list completions
- This function displays COMPLETIONS to the stream in
- `standard-output', usually a buffer. (*Note Read and Print::, for
- more information about streams.) The argument COMPLETIONS is
- normally a list of completions just returned by `all-completions',
- but it does not have to be. Each element may be a symbol or a
- string, either of which is simply printed, or a list of two
- strings, which is printed as if the strings were concatenated.
-
- This function is called by `minibuffer-completion-help'. The most
- common way to use it is together with
- `with-output-to-temp-buffer', like this:
-
- (with-output-to-temp-buffer "*Completions*"
- (display-completion-list
- (all-completions (buffer-string) my-alist)))
-
- - User Option: completion-auto-help
- If this variable is non-`nil', the completion commands
- automatically display a list of possible completions whenever
- nothing can be completed because the next character is not
- uniquely determined.
-