All Manuals > CLIM 2.0 User Guide > 16 Input Editing and Completion Facilities

16.5 Completion

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

*help-gestures* Variable

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 Function

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:

function returns five values:

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 Function

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 Macro

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:

mode-flag must be one of:

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