wiki:HemlockProgrammer/TheEchoArea

Back to Table of Contents

12. The Echo Area

Hemlock provides a number of facilities for displaying information and prompting the user for it. Most of these work through a small area displayed at the bottom of the screen, called the Echo Area.

12.1. Echo Area Functions

clear-echo-area [Function]

Clears the echo area.

message control-string &rest format-arguments [Function]
loud-message control-string &rest format-arguments [Function]

Displays a message in the echo area, replacing previous contents if any. loud-message is like message, but it also beeps.

beep [Function]

Gets the user's attention, typically by making a sound.

12.2. Prompting Functions

Prompting functions can be used to obtain short one-line input from the user.

Cocoa note: Because of implementation restrictions, only one buffer at a time is allowed to read prompted input. If a prompting function is invoked while a prompting operation is already in effect in another buffer, the attempt fails, telling the user "Buffer xxx is already waiting for input".

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.

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

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.

prompt-for-key-event &key :prompt :help [Function]

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

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

This function prompts for a key, a vector of key-events, suitable for passing to any of the functions that manipulate key bindings (page 29). 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.

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

This function prompts for an acceptable filename. "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.

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

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.

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

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.

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

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

prompt-for-string &key :prompt :help :default :default-string [Function]

This function prompts for a string; this cannot fail.

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

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.

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

This prompts for logical key events :Y 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.

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

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.

command-case ({key value}*){({({tag}*) | tag} help {form}*)}* [Macro]

This macro is analogous to the Common Lisp case macro. Commands such as Help 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 45) 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."
  (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.")
	((: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.
: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 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 helpstring, 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 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.

12.3. Control of Parsing Behavior

Beep On Ambiguity (initial value t) [Hemlock Variable]

If this variable is true, then an attempt to complete a parse which is ambiguous will result in a "beep".

12.4. Defining New Prompting Functions

Prompting functionality is implemented by the function parse-for-something in cooperation with commands defined in "Echo Area" mode on the buffer associated with the echo area. You can implement new prompting functions by invoking parse-for-something with appropriate arguments.

parse-for-something &key [Function]

This function enters a mode reading input from the user and echoing it in the echo area, and returns a value when done. The input is managed by commands bound in "Echo Area" mode on the buffer associated with the echo area. The following keyword arguments are accepted:

:verification-function
This is invoked by the Confirm Parse command (page 52). It does most of the work when parsing prompted input. Confirm Parse (page 52) calls it with one argument, which is the string that the user typed so far. The function should return a list of values which are to be the result of the recursive edit, or nil indicating that the parse failed. In order to return zero values, a non-nil second value may be returned along with a nil first value.
:string-tables
This is the list of string-tables, if any, that pertain to this parse.
:value-must-exist
This is referred to by the verification function, and possibly some of the commands.
:default
The string representing the default object when prompting the user. Confirm Parse supplies this to the parse verification function when the user input is empty.
:default-string
When prompting the user, if :default is not specified, Hemlock displays this string as a representation of the default object; for example, when prompting for a buffer, this argument would be a default buffer name.
:type
The kind of parse, e.g. :file, :keyword, :string. This tells the completion commands how to do completion, with :string disabling completion.
:prompt
The prompt to display to the user.
:help
The help string or function being used for the current parse.

12.5. Some Echo Area Commands

These are some of the Echo Area commands that coordinate with the prompting routines. Hemlock binds other commands specific to the Echo Area, but they are uninteresting to mention here, such as deleting to the beginning of the line or deleting backwards a word.

Help On Parse (bound to Home, C-_ in Echo Area mode) [Command]

Display the help text for the parse currently in progress.

Complete Keyword (bound to Escape in Echo Area mode) [Command]

This attempts to complete the current region. It signals an editor-error if the input is ambiguous or incorrect.

Complete Field (bound to Space in Echo Area mode) [Command]

Similar to Complete Keyword, but only attempts to complete up to and including the first character in the keyword with a non-zero :parse-field-separator attribute. If there is no field separator then attempt to complete the entire keyword. If it is not a keyword parse then just self-insert.

Confirm Parse (bound to Return in Echo Area mode) [Command]

Call the verification function with the current input. If it returns a non-nil value then that is returned as the value of the parse. A parse may return a nil value if the verification function returns a non-nil second value.

Back to Table of Contents