---

12.2 Prompting Functions ¶

Most of the prompting functions accept the following keyword arguments:

:must-exist

If :must-exist has a non-nil value then the user is prompted until a valid response is obtained. If :must-exist is nil then return as a string whatever is input. The default is t.

:default

If null input is given when the user is prompted then this value is returned. If no default is given then some input must be given before anything interesting will happen.

:default-string

\If a :default is given then this is a string to be printed to indicate what the default is. The default is some representation of the value for :default, for example for a buffer it is the name of the buffer.

:prompt

This is the prompt string to display.

:help

This is similar to :prompt, except that it is displayed when the help command is typed during input.

This may also be a function. When called with no arguments, it should either return a string which is the help text or perform some action to help the user, returning nil.

Function: prompt-for-buffer &key :prompt :help :must-exist :default :default-string ¶

Prompts with completion for a buffer name and returns the corresponding buffer. If must-exist is nil, then it returns the input string if it is not a buffer name. This refuses to accept the empty string as input when :default and :default-string are nil. :default-string may be used to supply a default buffer name when :default is nil, but when :must-exist is non-nil, it must name an already existing buffer.

Macro: command-case ({key value}*) {({({tag}*) | tag help {form}*)}}* ¶

This macro is analogous to the Common Lisp case macro. Commands such as Query Replace use this to get a key-event, translate it to a character, and then to dispatch on the character to some case. In addition to character dispatching, this supports logical key-events (page logical-key-events) by using the input key-event directly without translating it to a character. Since the description of this macro is rather complex, first consider the following example:

(defcommand "Save All Buffers" (p)
  "Give the User a chance to save each modified buffer."
  "Give the User a chance to save each modified buffer."
  (dolist (b *buffer-list*)
    (select-buffer-command () b)
    (when (buffer-modified b)
      (command-case (:prompt "Save this buffer: [Y] "
		     :help "Save buffer, or do something else:")
	((:yes :confirm)
	 "Save this buffer and go on to the next."
	 (save-file-command () b))
	(:no "Skip saving this buffer, and go on to the next.")
	(:recursive-edit
	 "Go into a recursive edit in this buffer."
	 (do-recursive-edit) (reprompt))
	((:exit #\p) "Punt this silly loop."
	 (return nil))))))

command-case prompts for a key-event and then executes the code in the first branch with a logical key-event or a character (called tags) matching the input. Each character must be a standard-character, one that satisfies the Common Lisp standard-char-p predicate, and the dispatching mechanism compares the input key-event to any character tags by mapping the key-event to a character with ext:key-event-char. If the tag is a logical key-event, then the search for an appropriate case compares the key-event read with the tag using logical-key-event-p.

All uses of command-case have two default cases, :help and :abort. You can override these easily by specifying your own branches that include these logical key-event tags. The :help branch displays in a pop-up window the a description of the valid responses using the variously specified help strings. The :abort branch signals an editor-error.

The key/value arguments control the prompting. The following are valid values:

:help

The default :help case displays this string in a pop-up window. In addition it formats a description of the valid input including each case’s help string.

:prompt

This is the prompt used when reading the key-event.

:change-window

If this is non-nil (the default), then the echo area window becomes the current window while the prompting mechanism reads a key-event. Sometimes it is desirable to maintain the current window since it may be easier for users to answer the question if they can see where the current point is.

:bind

This specifies a variable to which the prompting mechanism binds the input key-event. Any case may reference this variable. If you wish to know what character corresponds to the key-event, use ext:key-event-char.

Instead of specifying a tag or list of tags, you may use t. This becomes the default branch, and its forms execute if no other branch is taken, including the default :help and :abort cases. This option has no help string, and the default :help case does not describe the default branch. Every command-case has a default branch; if none is specified, the macro includes one that system:beep’s and reprompt’s (see below).

Within the body of command-case, there is a defined reprompt macro. It causes the prompting mechanism and dispatching mechanism to immediately repeat without further execution in the current branch.

Function: prompt-for-key-event &key :prompt :change-window ¶

This function prompts for a key-event returning immediately when the user types the next key-event. command-case is more useful for most purposes. When appropriate, use logical key-events (page logical-key-events).

Function: prompt-for-key &key :prompt :help :must-exist :default :default-string ¶

This function prompts for a key, a vector of key-events, suitable for passing to any of the functions that manipulate key bindings (page key-bindings). If must-exist is true, then the key must be bound in the current environment, and the command currently bound is returned as the second value.

Function: prompt-for-file &key :prompt :help :must-exist :default :default-string ¶

This function prompts for an acceptable filename in some system dependent fashion. "Acceptable" means that it is a legal filename, and it exists if must-exist is non-nil. prompt-for-file returns a Common Lisp pathname.

If the file exists as entered, then this returns it, otherwise it is merged with default as by merge-pathnames.

Function: prompt-for-integer &key :prompt :help :must-exist :default :default-string ¶

This function prompts for a possibly signed integer. If must-exist is nil, then prompt-for-integer returns the input as a string if it is not a valid integer.

Function: prompt-for-keyword string-tables &key :prompt :help :must-exist :default :default-string ¶

This function prompts for a keyword with completion, using the string tables in the list string-tables. If must-exist is non-nil, then the result must be an unambiguous prefix of a string in one of the string-tables, and the returns the complete string even if only a prefix of the full string was typed. In addition, this returns the value of the corresponding entry in the string table as the second value.

If must-exist is nil, then this function returns the string exactly as entered. The difference between prompt-for-keyword with must-exist nil, and prompt-for-string, is the user may complete the input using the Complete Parse and Complete Field commands.

Function: prompt-for-expression &key :promptd :[help :must-exist :default :default-string ¶

This function reads a Lisp expression. If must-exist is nil, and a read error occurs, then this returns the string typed.

Function: prompt-for-string &key :prompt :help :default :default-string ¶

This function prompts for a string; this cannot fail.

Function: prompt-for-variable &key :prompt :help :must-exist :default :default-string ¶

This function prompts for a variable name. If must-exist is non-nil, then the string must be a variable defined in the current environment, in which case the symbol name of the variable found is returned as the second value.

Function: prompt-for-y-or-n &key :prompt :help :must-exist :default :default-string ¶

This prompts for y, Y, n, or N, returning t or nil without waiting for confirmation. When the user types a confirmation key, this returns default if it is supplied. If must-exist is nil, this returns whatever key-event the user first types; however, if the user types one of the above key-events, this returns t or nil. This is analogous to the Common Lisp function y-or-n-p.

Function: prompt-for-yes-or-no &key :prompt :help :must-exist :default :default-string ¶

This function is to prompt-for-y-or-n as yes-or-no-p is to y-or-n-p. "Yes" or "No" must be typed out in full and confirmation must be given.