Clears the echo area.

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

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

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.

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.

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

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.

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.

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.

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

This function prompts for a string; this cannot fail.

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.

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.

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.

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 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.

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

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. It does most of the work when parsing prompted input. Confirm Parse 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.

Display the help text for the parse currently in progress.

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

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.

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.