@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1997 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/minibuf.info
@node Minibuffers, Command Loop, Read and Print, Top
@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
+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.
default value, @var{initial-contents} may be preferred.
@end defun
-@defun read-string prompt &optional initial history
+@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
-list and optionally the initial position in the list.
+The optional argument @var{history}, if non-@code{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 is a simplified interface to the
@code{read-from-minibuffer} function:
@smallexample
@group
-(read-string @var{prompt} @var{initial})
+(read-string @var{prompt} @var{initial} @var{history} @var{default})
@equiv{}
-(read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
+(read-from-minibuffer @var{prompt} @var{initial} nil nil
+ @var{history} nil @var{default})))
@end group
@end smallexample
@end defun
This section describes functions for reading Lisp objects with the
minibuffer.
-@defun read-minibuffer prompt &optional initial
+@defun 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 @var{prompt} and @var{initial} are
used as in @code{read-from-minibuffer}.
+The optional argument @var{history}, if non-@code{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-minibuffer @var{prompt} @var{initial})
+(read-expression @var{prompt} @var{initial} @var{history} @var{default-value})
@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
@smallexample
@group
-(read-minibuffer
+(read-expression
"Enter an expression: " (format "%s" '(testing)))
;; @r{Here is how the minibuffer is displayed:}
default, or can edit the input.
@end defun
-@defun eval-minibuffer prompt &optional initial
+@defun read-minibuffer prompt &optional initial history default-value
+
+This is a FSF Emacs compatible function. Use @code{read-expression}
+instead.
+@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-@code{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-minibuffer}:
+@code{read-expression}:
@smallexample
@group
(eval-minibuffer @var{prompt} @var{initial})
@equiv{}
-(eval (read-minibuffer @var{prompt} @var{initial}))
+(eval (read-expression @var{prompt} @var{initial}))
@end group
@end smallexample
@end defun
-@defun edit-and-eval-command prompt form
+@defun edit-and-eval-command prompt form &optional history
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
@group
(edit-and-eval-command "Please edit: " '(forward-word 1))
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
@end group
features that do use the minibuffer.
@defun try-completion string collection &optional predicate
-This function returns the longest common substring of all possible
+This function returns the longest common prefix of all possible
completions of @var{string} in @var{collection}. The value of
@var{collection} must be an alist, an obarray, or a function that
implements a virtual set of strings (see below).
@smallexample
@group
-(try-completion
+(try-completion
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
@result{} "fooba"
@smallexample
@group
-(defun test (s)
+(defun test (s)
(> (length (car s)) 6))
@result{} test
@end group
@group
-(try-completion
+(try-completion
"foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
+ '(("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 are the same as those of
-@code{try-completion}.
+@defun all-completions string collection &optional predicate
+This function returns a list of all possible completions of @var{string}.
+The arguments to this function are the same as those of @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}.
-If @var{nospace} is non-@code{nil}, completions that start with a space
-are ignored unless @var{string} also starts with a space.
-
Here is an example, using the function @code{test} shown in the
example for @code{try-completion}:
@smallexample
@group
-(defun test (s)
+(defun test (s)
(> (length (car s)) 6))
@result{} test
@end group
@group
-(all-completions
+(all-completions
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
'test)
@end defun
@defvar completion-ignore-case
-If the value of this variable is
+If the value of this variable is
non-@code{nil}, XEmacs does not consider case significant in completion.
@end defvar
is included in @var{collection}.
The function @code{completing-read} works by calling
-@code{read-minibuffer}. It uses @code{minibuffer-local-completion-map}
+@code{read-expression}. 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}.
@end group
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
---------- Buffer: Minibuffer ----------
@samp{*Completions*}.
@end deffn
-@defun display-completion-list completions
+@defun display-completion-list completions &rest cl-keys
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
@example
(read-buffer "Buffer name? " "foo" t)
@group
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
@end example
@end defun
-@defun read-command prompt
+@defun read-command prompt &optional default-value
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,}
+;; @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 ----------
+Command name?
---------- Buffer: Minibuffer ----------
@end group
@end example
@group
(read-command @var{prompt})
@equiv{}
-(intern (completing-read @var{prompt} obarray
+(intern (completing-read @var{prompt} obarray
'commandp t nil))
@end group
@end example
@end defun
-@defun read-variable prompt
+@defun read-variable prompt &optional default-value
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-value}
+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? ")
-;; @r{After evaluation of the preceding expression,}
-;; @r{the following prompt appears,}
+;; @r{After evaluation of the preceding expression,}
+;; @r{the following prompt appears,}
;; @r{with an empty minibuffer:}
@end group
file name. It provides special features including automatic insertion
of the default directory.
-@defun read-file-name prompt &optional directory default existing initial
+@defun read-file-name prompt &optional directory default existing initial history
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
@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:
+Here is an example:
@example
@group
(read-file-name "The file is ")
-;; @r{After evaluation of the preceding expression,}
+;; @r{After evaluation of the preceding expression,}
;; @r{the following appears in the minibuffer:}
@end group
@group
(y-or-n-p "Do you need a lift? ")
-;; @r{After evaluation of the preceding expression,}
+;; @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)
+Do you need a lift? (y or n)
---------- Echo area ----------
@end group
@group
---------- Echo area ----------
-Please answer y or n. Do you need a lift? (y or n)
+Please answer y or n. Do you need a lift? (y or n)
---------- Echo area ----------
@end group
@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{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)
+Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
@end group
@end smallexample
@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
+If non-@code{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,
+This specifies the character echoed when typing a password. When @code{nil},
nothing is echoed.
@end defopt
@end defun
@c Emacs 19 feature
-@defun window-minibuffer-p window
+@defun window-minibuffer-p &optional window
This function returns non-@code{nil} if @var{window} is a minibuffer window.
@end defun
editing the inner one.
This variable only affects invoking the minibuffer while the
-minibuffer window is selected. If you switch windows while in the
+minibuffer window is selected. If you switch windows while in the
minibuffer, you can always invoke minibuffer commands while some other
window is selected.
@end defopt
projects / chise / xemacs-chise.git.1 / blobdiff