prompt-for-symbol

prompt-for-symbol Function

Summary

Prompts the user for a symbol.

Package

capi

Signature

prompt-for-symbol message &key initial-value symbols package ok-check pane-args popup-args continuation => result, okp

Arguments

`message`⇩	A string or `nil`.
`initial-value`⇩	A symbol.
`symbols`⇩	A list of symbols.
`package`⇩	A package or `nil`.
`ok-check`⇩	A function, or `nil`.
`pane-args`⇩	Arguments to pass to the pane.
`popup-args`⇩	Arguments to pass to the confirmer.
`continuation`⇩	A function or `nil`.

Values

`result`	A symbol.
`okp`	A boolean.

Description

The function prompt-for-symbol prompts the user for a symbol which they should enter into the pane.

message supplies a title for the dialog.

initial-value, if non-nil, should be a symbol which is initially displayed in the pane.

The symbols that are valid can be constrained in a number of ways.

symbols, if non-nil, should be a list of all valid symbols. The default is nil, meaning all symbols are valid.

package, if non-nil, is a package in which the symbol must be available. The value nil means that the value of *package* is used, and this is the default.

ok-check is a function which when called on a symbol will return non-nil if the symbol is valid.

The prompter is created by calling prompt-for-string. Arguments can be passed to the make-instance of the pane and the call to popup-confirmer using pane-args and popup-args respectively, and an input history can be implemented by supplying a history-function or history-symbol in popup-args.

If continuation is non-nil, then it must be a function with a lambda list that accepts two arguments. continuation is called with the values that would normally be returned by prompt-for-symbol. On Cocoa, passing continuation causes the dialog to be made as a window-modal sheet and prompt-for-symbol returns immediately, leaving the dialog on the screen. The with-dialog-results macro provides a convenient way to create a continuation function.

Examples

(capi:prompt-for-symbol "Enter a symbol:")

(capi:prompt-for-symbol "Enter a symbol:"
                        :package 'cl)

(capi:prompt-for-symbol "Enter a symbol:"
                        :symbols 
                        '(foo bar baz))

(capi:prompt-for-symbol "Enter a symbol:"
                        :ok-check #'(lambda (symbol)
                                    (string< symbol "B")))

This last example shows how to implement a symbol prompter with an input history:

(defvar *my-history* (list "cdr" "car"))
 
(capi:prompt-for-symbol "Enter a symbol" 
                        :popup-args 
                        '(:history-symbol *my-history*))