bug#16555: 24.3.50; Company and CAPF: dealing with completion values containing extra text

[Dmitry Gutov <dgutov@yandex.ru>]

On 26.01.2014 08:23, Stefan Monnier wrote:
>> * Including extra text in completion table seems like it won't mesh well
>>    with the completion-at-point-functions interface, and specifically
>>    with the completion-at-point as the frontend. How would one write a
>>    CAPF function for clang or eclim with argument lists in mind?
>
>  From a CAPF point of view, I think it would work as follows:
> - all-completions would return the "cropped" names.
> - `annotate-function' would be used to add the arglists to *Completions*.

I played with this a bit, and looks like the proper way to make this 
work with the current completion-at-point code is to use text 
properties. I propertize the completions, and then the annotation 
function looks up the text property:

(add-hook 'completion-at-point-functions
            (lambda ()
              (let ((bounds (bounds-of-thing-at-point 'symbol)))
                (when bounds
                  (list
                   (car bounds)
                   (cdr bounds)
                   (list a1 a2 a3)
                   :annotation-function #'annota)))) nil t)

(setq a1 (propertize "aaa" 'a "a1")
       a2 (propertize "aaa" 'a "a2")
       a3 (propertize "aab" 'a "a3"))

(defun annota (s)
   (format "(%s)" (get-text-property 0 'a s)))

Using a hash table surprizingly didn't work, because:

* Without the additional text property, a1 and a2 are considered equal, 
and only one of them is listed in the completions buffer.
* If the hash table uses the `eq' test, lookup fails because the strings 
passed to the annotation function are not the same objects as those we 
return in the completions table.
* If the hash table uses the `equal' test, naturally it can't 
distinguish between a1 and a2 (lookup returns "a2" for both).

Is that how it's supposed to work?

And it looks to me that this approach is incompatible with the `value' 
command, if we want company-capf to support it. Using the annotation 
function, it would know how to get from value to value + annotation, but 
not the other way around.

Using `value' as described, aside from smoother transition from the 
current behavior, appealed to me because it allows to defer the string 
munging to the last possible moment, thus saving in performance on all 
strings that weren't displayed, when the candidates list is large.

But here's an extreme example, of sorts:

ELISP> (js2-time (all-completions "" obarray 'fboundp))
0.0121
ELISP> (js2-time (mapcar
            (lambda (s)
              (if (> (length s) 2)
                  (propertize s 's (substring s (/ (length s) 2)))
                s))
            (all-completions "" obarray 'fboundp)))
0.1318

The second measurement fluctuates between 130ms and 80ms, probably due 
to GC. Maybe this is negligible, considering that on my machine that's a 
collection with 19000 elements, and most completion lists will be 
considerably smaller.

On the other hand, using `annotate' cleanly separates the "meat" in 
completion candidates from the extra text, which can be used to e.g. 
visualize them differently, maybe with different faces and alignments in 
the popup. As long as we solve the issue of uniqueness.

> - `exit-function' would be used to insert the arglist after selecting
>    a candidate.

Yes, `exit-function' is the best match for `post-completion', but I 
don't see which value of STATUS should be considered as okay for 
insertion. `finished' seems to be a good candidate, but it does not seem 
to really correspond to when happens after `company-complete-selection' 
(the completion is inserted and the popup is closed). `finished' can 
only be the status when the inserted completion doesn't have any 
possible continuations in the completions table, whereas we obviously 
want to be able to do arglist insertion for these cases, too.

The reverse is also true: being able not to insert the arguments list 
for a sole candidate can also be useful, and in Company user can do that 
at least by repeatedly using TAB (company-complete-common) instead of 
`company-complete-selection'.