-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
An `end-of-file' error is signaled if reading encounters an
unterminated list, vector, or string.
- - Function: read &optional STREAM
+ - Function: read &optional stream
This function reads one textual Lisp expression from STREAM,
returning it as a Lisp object. This is the basic Lisp input
function.
- - Function: read-from-string STRING &optional START END
+ - Function: read-from-string string &optional start end
This function reads the first textual Lisp expression from the
text in STRING. It returns a cons cell whose CAR is that
expression, and whose CDR is an integer giving the position of the
Finally, we show the use of a function as an output stream. The
function `eat-output' takes each character that it is given and conses
-it onto the front of the list `last-output' (*note Building Lists::.).
+it onto the front of the list `last-output' (*note Building Lists::).
At the end, the list contains all the characters output, but in reverse
order.
the previous section for a description of output streams.) If STREAM
is `nil' or omitted, it defaults to the value of `standard-output'.
- - Function: print OBJECT &optional STREAM
+ - Function: print object &optional stream
The `print' function is a convenient way of printing. It outputs
the printed representation of OBJECT to STREAM, printing in
addition one newline before OBJECT and another after it. Quoting
-|
=> " came back"
- - Function: prin1 OBJECT &optional STREAM
+ - Function: prin1 object &optional stream
This function outputs the printed representation of OBJECT to
STREAM. It does not print newlines to separate output as `print'
does, but it does use quoting characters just like `print'. It
-| The\ cat\ in"the hat"" came back"
=> " came back"
- - Function: princ OBJECT &optional STREAM
+ - Function: princ object &optional stream
This function outputs the printed representation of OBJECT to
STREAM. It returns OBJECT.
-| The cat in the "hat"
=> " in the \"hat\""
- - Function: terpri &optional STREAM
+ - Function: terpri &optional stream
This function outputs a newline to STREAM. The name stands for
"terminate print".
- - Function: write-char CHARACTER &optional STREAM
+ - Function: write-char character &optional stream
This function outputs CHARACTER to STREAM. It returns CHARACTER.
- - Function: prin1-to-string OBJECT &optional NOESCAPE
+ - Function: prin1-to-string object &optional noescape
This function returns a string containing the text that `prin1'
would have printed for the same argument.
objects will be written in `#[...]' form instead of in
`#<compiled-function [...]>' form, and two-element lists of the
form `(quote object)' will be written as the equivalent `'object'.
- Do not *set* this variable; bind it instead.
+ Do not _set_ this variable; bind it instead.
- Variable: print-length
The value of this variable is the maximum number of elements of a
===========================
In most ways, a minibuffer is a normal XEmacs buffer. Most
-operations *within* a buffer, such as editing commands, work normally
+operations _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
` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
`enable-recursive-minibuffers'.
Like other buffers, a minibuffer may use any of several local keymaps
-(*note Keymaps::.); these contain various exit commands and in some
-cases completion commands (*note Completion::.).
+(*note Keymaps::); these contain various exit commands and in some cases
+completion commands (*note Completion::).
* `minibuffer-local-map' is for ordinary input (no completion).
reading the arguments for a command, in the `interactive' spec. *Note
Defining Commands::.
- - Function: read-from-minibuffer PROMPT-STRING &optional
- INITIAL-CONTENTS KEYMAP READ HIST ABBREV-TABLE DEFAULT
+ - Function: read-from-minibuffer prompt-string &optional
+ 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
- convert the text into a Lisp object (*note Input Functions::.).
+ convert the text into a Lisp object (*note Input Functions::).
The first thing this function does is to activate a minibuffer and
display it with PROMPT-STRING as the prompt. This value must be a
applications such as completion.
The argument ABBREV-TABLE specifies `local-abbrev-table' in the
- minibuffer (*note Standard Abbrev Tables::.).
+ 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.
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
+ - 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'.
The optional argument HISTORY, if non-nil, specifies a history
- list and optionally the initial position in the list.
+ 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.
This section describes functions for reading Lisp objects with the
minibuffer.
- - Function: read-minibuffer PROMPT &optional INITIAL
+ - 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:
-
+
---------- Buffer: Minibuffer ----------
Enter an expression: (testing)-!-
---------- Buffer: Minibuffer ----------
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
+ - 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 (`"')
;; After evaluation of the preceding expression,
;; the following appears in the minibuffer:
-
+
---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)-!-
---------- Buffer: Minibuffer ----------
chapter so as to keep them near the higher-level completion features
that do use the minibuffer.
- - Function: try-completion STRING COLLECTION &optional PREDICATE
+ - Function: try-completion string collection &optional predicate
This function returns the longest common substring of all possible
completions of STRING in COLLECTION. The value of COLLECTION must
be an alist, an obarray, or a function that implements a virtual
longest initial sequence common to all the permissible completions
that match.
- If COLLECTION is an alist (*note Association Lists::.), the CARs
- of the alist elements form the set of permissible completions.
+ If COLLECTION is an alist (*note Association Lists::), the CARs of
+ the alist elements form the set of permissible completions.
- If COLLECTION is an obarray (*note Creating Symbols::.), the names
+ If COLLECTION is an obarray (*note Creating Symbols::), the names
of all symbols in the obarray form the set of permissible
completions. The global variable `obarray' holds an obarray
containing the names of all interned Lisp symbols.
of one argument. It is used to test each possible match, and the
match is accepted only if PREDICATE returns non-`nil'. The
argument given to PREDICATE is either a cons cell from the alist
- (the CAR of which is a string) or else it is a symbol (*not* a
+ (the CAR of which is a string) or else it is a symbol (_not_ a
symbol name) from the obarray.
You can also use a symbol that is a function as COLLECTION. Then
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
=> "fooba"
-
+
(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
=> t
(defun test (s)
(> (length (car s)) 6))
=> test
-
(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
=> "foobar"
- - Function: all-completions STRING COLLECTION &optional PREDICATE
- NOSPACE
+ - Function: all-completions string collection &optional predicate
+ nospace
This function returns a list of all possible completions of
STRING. The arguments to this function are the same as those of
`try-completion'.
(defun test (s)
(> (length (car s)) 6))
=> test
-
+
(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
This section describes the basic interface for reading from the
minibuffer with completion.
- - Function: completing-read PROMPT COLLECTION &optional PREDICATE
- REQUIRE-MATCH INITIAL HIST DEFAULT
+ - Function: completing-read prompt collection &optional predicate
+ 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',
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::.
"Complete a foo: "
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
nil t "fo")
-
+
;; After evaluation of the preceding expression,
;; the following appears in the minibuffer:
`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'
-
- `C-j'
- `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 `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.
-