24.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 implementations are encouraged to provide "chunkwise" completion, that is, if the user input consists of several tokens separated by "partial delimiters", CLIM should complete each token separately against the set of possibilities. [annotate]

*completion-gestures*   [Variable]
          

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, but must include the :complete gesture name. [annotate]

[annotate]

Note: Why no `completion-gesture-p' like we have for activation and delimiter gestures? [edit]-- Troels "Athas" Henriksen 2006-10-26 18:57Z
 

*help-gestures*   [Variable]
          

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, but must include the :help gesture name. [annotate]

[annotate]

*possibilities-gestures*   [Variable]
          

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, but must include the :possibilities gesture name. [annotate]

[annotate]

complete-input  stream function &key partial-completers allow-any-input possibility-printer (help-displays-possibilities t) [Function]
          

Reads input from the user from the input editing stream stream, completing over a set of possibilities. complete-input is only required to work on input editing streams, but implementations may extend it to work on interactive streams as well. [annotate]

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 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: [annotate]

Note: Of course, complete-from-possiblities and complete-from-generator take more than two arguments, so they can't be passed as the value of function. One will need to construct a closure with two arguments that contains a call to one of these functions. [edit]-- Robert Strandh 2005-04-30 13:50Z
 

  • :complete-limited---the function must complete the input up to the next partial delimiter. This is the mode used when the user types one of the partial completers. [annotate]
  • :complete-maximal---the function must complete 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*. [annotate]
  • :complete---the function must complete 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. [annotate]
  • :possibilities---the function must return 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 true). [annotate]

function must return five values: [annotate]

  • string---the completed input string. [annotate]
  • success---true if completion was successful, otherwise false. [annotate]
  • object---the object corresponding to the completion, or nil if the completion was unsuccessful. [annotate]
  • nmatches---the number of possible completions of the input. [annotate]
  • possibilities---an alist of completions whose entries are a list of a string and an object, returned only when the completion mode is :possibilities. This list will be freshly created. [annotate]

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. [annotate]

partial-completers is a list of characters that delimit portions of a name that can be completed separately. The default is an empty list. [annotate]

If the boolean allow-any-input is true, then complete-input will return 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 false. [annotate]

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. The function 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. [annotate]

If help-display-possibilities is true (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 false, 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*). [annotate]

[annotate]

simple-completion-error   [Condition]
          

The error that is signalled by complete-input when no completion is found. This is a subclass of simple-parse-error. [annotate]

[annotate]

completing-from-suggestions  (stream &key partial-completers allow-any-input possibility-printer (help-displays-possibilities t)) &body body [Macro]
          

Reads input from the input editing stream stream, completing over a set of possibilities generated by calls to suggest within body. body may have zero or more declarations as its first forms. [annotate]

completing-from-suggestions returns three values, object, success, and string [annotate]

The stream argument is not evaluated, and must be a symbol that is bound to a stream. If stream is t (the default), *standard-input* is used. [annotate]

partial-completers, allow-any-input, and possibility-printer are as for complete-input. [annotate]

Implementations will probably use complete-from-generator to implement this. [annotate]

[annotate]

suggest  completion object [Function]
          

Specifies one possibility for completing-from-suggestions. completion is a string, the printed representation of object. object is the internal representation. [annotate]

It is permitted for this function to have lexical scope, and be defined only within the body of completing-from-suggestions. [annotate]

[annotate]

complete-from-generator  string function delimiters &key (action :complete) predicate [Function]
          

Given an input string string and a list of delimiter characters delimiters that act as partial completion characters, complete-from-generator completes against the 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. [annotate]

action will be one of :complete, :complete-maximal, :complete-limited, or :possibilities. These are described under the function complete-input. [annotate]

predicate must be a function of one argument, an object. If the predicate returns true, the possibility corresponding to the object is processed, otherwise it is not. It has dynamic extent. [annotate]

complete-from-generator returns five values, the completed input string, the success value (true if the completion was successful, otherwise false), the object matching the completion (or nil if unsuccessful), the number of matches, and a list of possible completions if action was :possibilities. [annotate]

This function is one that will typically be passed as the second argument to complete-input. [annotate]

[annotate]

complete-from-possibilities  string completions delimiters &key (action :complete) predicate name-key value-key [Function]
          

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 in completions 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. [annotate]

action will be one of :complete, :complete-maximal, :complete-limited, or :possibilities. These are described under the function complete-input. [annotate]

predicate must be a function of one argument, an object. If the predicate returns true, the possibility corresponding to the object is processed, otherwise it is not. [annotate]

predicate, name-key, and value-key have dynamic extent. [annotate]

complete-from-possibilities returns five values, the completed input string, the success value (true if the completion was successful, otherwise false), the object matching the completion (or nil if unsuccessful), the number of matches, and a list of possible completions if action was :possibilities. [annotate]

This function is one that will typically be passed as the second argument to complete-input. [annotate]

[annotate]

with-accept-help  options &body body [Macro]
          

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. [annotate]

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). [annotate]

help-type must be one of: [annotate]

  • :top-level-help---specifies that help-string be used instead of the default help documentation provided by accept. [annotate]
  • :subhelp---specifies that help-string be used in addition to the default help documentation provided by accept. [annotate]

mode-flag must be one of: [annotate]

  • :append---specifies that the current help string be appended to any previous help strings of the same help type. This is the default mode. [annotate]
  • :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 out-side in.) [annotate]
  • :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. [annotate]

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. [annotate]

None of the arguments is evaluated. [annotate]

[annotate]

Note:

With CLIM2: If _help-string_ is a function it is a function that writes the help to the stream given as its first arguments.

This actually makes sense and allows for formatting. However, what is the third argument, the help string sofar, doing there?

Further the _help-string_ actually is evaluated, it is only the _help-option_ that is not.

[edit]-- Gibert Baumann 2024-06-07 05:34Z