CLIM provides a completion facility that completes a string provided by a user against some set of possible completions (which are themselves strings). Each completion is associated with some Lisp object. CLIM provides "chunkwise" completion; that is, if the user input consists of several tokens separated by "partial delimiters," CLIM completes each token separately against the set of possibilities.
*completion-gestures* Variable
Summary: A list of the gesture names that cause complete-input to complete the user's input as fully as possible. The exact global contents of this list is unspecified; it includes the :complete gesture name. *completion-gestures* is bound to (:complete).
Summary: A list of the gesture names that cause accept and complete-input to display a (possibly input context-sensitive) help message, and for some presentation types a list of possibilities as well. The exact global contents of this list is unspecified; it includes the :help gesture name. *help-gestures* is bound to (:help) in LispWorks CLIM and #\Meta-? in Liquid CL CLIM.
*possibilities-gestures* Variable
Summary: A list of the gesture names that cause complete-input to display a (possibly input context-sensitive) help message and a list of possibilities. The exact global contents of this list is unspecified; it includes the :possibilities gesture name. *possibilities-gestures* is bound to (:possibilities).
complete-input stream function &key partial-completers allow-any-input possibility-printer (help-displays-possibilities t)
Summary: Reads input from the user from the input editing stream stream, completing over a set of possibilities. complete-input only works on input editing streams.
function is a function of two arguments. It is called to generate the completion possibilities that match the user's input; it has dynamic extent. Usually, programmers will pass a function which calls either complete-from-possibilities or complete-from-generator as the value of function. Its first argument is a string containing the user's input "so far." Its second argument is the completion mode, one of the following:
:complete-limited—the function completes the input up to the next partial delimiter. This is the mode used when the user types a partial completer.:complete-maximal—the function completes the input as much as possible. This is the mode used when the user issues a gesture that matches any of the gesture names in *completion-gestures*.:complete—the function completes the input as much as possible, except that if the user's input exactly matches one of the possibilities, even if it is a left substring of another possibility, the shorter possibility is returned as the result. This is the mode used when the user issues a delimiter or activation gesture that is not a partial completer.:possibilities—the function returns an alist of the possible completions as its fifth value. This is the mode used when the user a gesture that matches any of the gesture names in *possibilities-gestures* or *help-gestures* (if help-displays-possibilities is t).
function returns five values:
t if completion was successful, otherwise nil.nil.:possibilities.
complete-input returns three values: object, success, and string. In addition, the printed representation of the completed input will be inserted into the input buffer of stream in place of the user-supplied string by calling replace-input.
partial-completers is a list of characters that delimit portions of a name that can be completed separately. The default is an empty list.
If the boolean allow-any-input is t, then complete-input returns as soon as the user issues an activation gesture, even if the input is not any of the possibilities. If the input is not one of the possibilities, the three values returned by complete-input will be nil, t, and the string. The default for allow-any-input is nil.
If possibility-printer is supplied, it must be a function of three arguments, a possibility, a presentation type, and a stream; it has dynamic extent and displays the possibility on the stream. The possibility will be a list of two elements, the first being a string and the second being the object corresponding to the string.
If help-display-possibilities is t (the default), then when the user issues a help gesture (a gesture that matches one of the gesture names in *help-gestures*), CLIM will display all the matching possibilities. If it is nil, then CLIM will not display the possibilities unless the user issues a possibility gesture (a gesture that matches one of the gesture names in *possibilities-gestures*).
Here is an example:
(defvar *my-possibilities* '(("Raspberry" :rasp)
("Strawberry" :straw)
("Blueberry" :blue)))
(flet ((possibilities-generator (string-so-far mode)
(complete-from-possibilities string-so-far
*my-possibilities*
nil
:action mode)))
(complete-input stream #'possibilities-generator))
complete-from-generator Function
complete-from-generator string generator delimiters &key (action :complete) predicate
Summary: Given an input string string and a list of delimiter characters delimiters that act as partial completion characters, complete-from-generator completes against possibilities that are generated by the function generator. generator is a function of two arguments, the string string and another function that it calls in order to process the possibility; it has dynamic extent.
action will be one of :complete, :complete-maximal, :complete-limited, or :possibilities. These are described under the function complete-input.
predicate is a function of one argument, an object. If the predicate returns t, the possibility corresponding to the object is processed. It has dynamic extent.
complete-from-generator returns five values, the completed input string, the success value (t if the completion was successful, otherwise nil), the object matching the completion (or nil if unsuccessful), the number of matches, and a list of possible completions if action was :possibilities.
A caller of this function will typically be passed as the second argument to complete-input.
complete-from-possibilities Function
complete-from-possibilities string completions delimiters &key (action :complete) predicate name-key value-key
Summary: Given an input string string and a list of delimiter characters delimiters that act as partial completion characters, complete-from-possibilities completes against the possibilities in the sequence completions. The completion string is extracted from the possibilities by applying name-key, which is a function of one argument. The object is extracted by applying value-key, which is a function of one argument. name-key defaults to first, and value-key defaults to second.
action will be one of :complete, :complete-maximal, :complete-limited, or :possibilities. These are described under the function complete-input.
predicate must be a function of one argument, an object. If the predicate returns t, the possibility corresponding to the object is processed, otherwise it is not.
predicate, name-key, and value-key have dynamic extent.
complete-from-possibilities returns five values, the completed input string, the success value (t if the completion was successful, nil otherwise), the object matching the completion (or nil if unsuccessful), the number of matches, and a list of possible completions if action was :possibilities.
A caller of this function will typically be passed as the second argument to complete-input.
completing-from-suggestions Macro
completing-from-suggestions (stream &key partial-completers allow-any-input possibility-printer) &body body
Summary: Reads input from input editing stream stream, completing over a set of possibilities generated by calls to suggest in body. Returns object, success, and string.
The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *query-io* is used.
See complete-input for partial-completers, allow-any-input, and possibility-printer.
For example:
(completing-from-suggestions (stream)
(map nil
#'(lambda (x)
(suggest
(car x) (cdr x)))
'(("One" . 1)
("Two" . 2)
("Three" . 3))))
suggest completion object
Summary: Specifies one possibility for completing-from-suggestions. completion is a string, the printed representation. object is the internal representation.
This function has lexical scope and is defined only within the body of completing-from-suggestions.
accept generates help messages based on the name of the presentation type, but sometimes this is not enough. Use with-accept-help to create more complex help messages.
with-accept-help options &body body
Summary: Binds the dynamic environment to control the documentation produced by help and possibilities gestures during user input in calls to accept with the dynamic scope of body. body may have zero or more declarations as its first forms.
options is a list of option specifications. Each specification is itself a list of the form (help-option help-string). help-option is either a symbol that is a help-type or a list of the form (help-type mode-flag). help-type must be one of:
:top-level-help—specifies that help-string be used instead of the default help documentation provided by accept.:subhelp—specifies that help-string be used in addition to the default help documentation provided by accept.
mode-flag must be one of:
:append—specifies that the current help string be appended to any previous help strings of the same help type. This is the default mode.:override—specifies that the current help string is the help for this help type; no lower-level calls to with-accept-help can override this. (:override works from the outside in.):establish-unless-overridden—specifies that the current help string be the help for this help type unless a higher-level call to with-accept-help has already established a help string for this help type in the :override mode. This is what accept uses to establish the default help.
help-string is a string or a function that returns a string. If it is a function, it receives three arguments, the stream, an action (either :help or :possibilities) and the help string generated so far.
None of the arguments are evaluated.
CLIM 2.0 User Guide - 01 Dec 2021 19:39:00