[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following functions provide a convenient and consistent interface for asking questions of the user. Questions are printed and the answers are read on the stream query-io, which normally is synonymous with terminal-io but can be rebound to another stream for special applications.
We will first describe two simple functions for yes-or-no questions, then the more general function on which all querying is built.
If the message argument is supplied, it will be printed on a fresh line (using the :fresh-line stream operation). Otherwise the caller is assumed to have printed the message already. If you want a question mark and/or a space at the end of the message, you must put it there yourself; y-or-n-p will not add it. stream defaults to the value of query-io.
y-or-n-p should only be used for questions which the user knows are coming. If the user is not going to be anticipating the question (e.g. if the question is "Do you really want to delete all of your files?" out of the blue) then y-or-n-p should not be used, because the user might type ahead a T, Y, N, space, or rubout, and therefore accidentally answer the question. In such cases, use yes-or-no-p.
If the message argument is supplied, it will be printed on a fresh line (using the :fresh-line stream operation). Otherwise the caller is assumed to have printed the message already. If you want a question mark and/or a space at the end of the message, you must put it there yourself; yes-or-no-p will not add it. stream defaults to the value of query-io.
To allow the user to answer a yes-or-no question with a single character, use y-or-n-p. yes-or-no-p should be used for unanticipated or momentous questions; this is why it beeps and why it requires several keystrokes to answer it.
options is a list of alternating keywords and values, used to select among a variety of features. Most callers will have a constant list which they pass as options (rather than consing up a list whose contents varies). The keywords allowed are:
The argument to the :choices option is a list each of whose elements is a choice. The cdr of a choice is a list of the user inputs which correspond to that choice. These should be characters for :type :tyi or strings for :type :readline. The car of a choice is either a symbol which fquery should return if the user answers with that choice, or a list whose first element is such a symbol and whose second element is the string to be echoed when the user selects the choice. In the former case nothing is echoed. In most cases :type :readline would use the first format, since the user's input has already been echoed, and :type :tyi would use the second format, since the input has not been echoed and furthermore is a single character, which would not be mnemonic to see on the display.
Perhaps this can be clarified by example. The yes-or-no-p function uses this list of choices:
((t "Yes") (nil "No")) |
(((t "Yes.") #/y #/t #\sp #\hand-up) ((nil "No.") #/n #\rubout #\hand-down)) |
If a condition is specified (or allowed to default to :fquery), before asking the question fquery will signal the condition. (See (condition) for information about conditions.) The handler will receive four arguments: the condition name, the options argument to fquery, the format-string argument to fquery, and the list of format-args arguments to fquery. As usual with conditions, if the handler returns nil the operation proceeds as if there had been no handler. If the handler returns two values, t and ans, fquery will immediately return ans. No conventions have yet been defined for standard condition names for use with fquery.
If you want to use the formatted output functions instead of format to produce the promting message, write
(fquery options (format:outfmt exp-or-string exp-or-string ...)) |
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |