Re: /srv/bzr/emacs/elpa r395: * company.el (company-capf): Add support for `sorted' and `post-completion'.

[Dmitry Gutov <dgutov@yandex.ru>]

On 05.05.2013 10:32, Stefan Monnier wrote:
>>> ;; (defun company-my-backend (command &optional arg &rest ignored)
>>> -;;   (case command
>>> -;;     (prefix (when (looking-back "foo\\>")
>>> +;;   (pcase command
>>> +;;     (`prefix (when (looking-back "foo\\>")
>>> ;;               (match-string 0)))
>>> -;;     (candidates (list "foobar" "foobaz" "foobarbaz"))
>>> -;;     (meta (format "This value is named %s" arg))))
>>> +;;     (`candidates (list "foobar" "foobaz" "foobarbaz"))
>>> +;;     (`meta (format "This value is named %s" arg))))
>
>> Like the header in company.el says, we still try to support Emacs 22 and
>> 23. `pcase' was only added in 23.3, I believe.
>
> But this is in a comment, so it's not a problem.

I'm not sure recommending to users to write new backends in a way 
incompatible with older Emacs is good. They may wish to remain 
compatible, yet be unaware that `pcase' is a new feature.
That might make them sad upon discovery, and doubly so if they don't 
know about cl's `case'.

By the way, is there a reason to use backquotes here? I remember you 
removing quotes from all backends' `case' forms, and using unquoted 
symbols in `pcase' seems to work just as well:

(pcase 'boo (boo 'bah)) => 'bah

>>> +(defun company-capf (command &optional arg &rest _args)
>> ...
>>> +    (duplicates nil) ;Don't bother.
>>> +    (no-cache t)     ;FIXME: Improve!
>>> +    (meta nil)       ;FIXME: Return one-line docstring for `arg'.
>>> +    (doc-buffer nil) ;FIXME: Return help buffer for `arg'.
>>> +    (location nil)   ;FIXME: Return (BUF . POS) or (FILE . LINENB) of `arg'.
>>> +    (init nil)      ;Don't bother: plenty of other ways to initialize
>>> the code.
>> a) There's no need to return nils explicitly, other backends don't.
>
> Indeed, I only need them to have a place where to put the FIXMEs.

I guess I'll remove `(init nil)', then.
By the way, if you think that `init' is useless for all backends, I 
don't believe that's true for `ropemacs' and `clang'. Retrying 
initialization once per buffer is fairly useful.

>> b) Who are these FIXMEs for?
>
> Whoever takes on the challenge.
>
>> I guess `meta' can be implemented by
>> calling `:annotation-function' (don't know if it's appropriate), but
>> `doc-buffer' and `location' don't have anything corresponding in
>> `completion-extra-properties'.
>
> `completion-extra-properties' can have anything you want in it.
> Same for `completion-metadata'.  Of course, new entries in these
> alists/plists won't be understood by other users of
> completion-at-point-functions, but that's not a problem in itself.

Ah okay, so I guess that section has everything to do with moving some 
company backends to completion-at-point functions.

>>> +    (require-match nil)            ;This should be a property of the
>>> front-end!
>> Should it really?
>
> Hmm... after writing an answer and throwing it away a few times, I think
> you're right: this definitely makes sense for a backend and basically
> means "I, as a backend, know that only those elements make sense here".
>
> But in most cases the front-end can't use it to *prevent* the user from
> writing something else (Emacs likes to let the user shoot himself in the
> foot, on the assumption that the user knows better).  It could use it to
> highlight a non-matching entry, OTOH.

Yes, so different completion UIs can interpret that return value 
differently. `completion-at-point' will ignore it.

`company' front-ends can't highlight the non-matching input, though, 
because it effectively restarts completion after each character the user 
inputs (with some caching, to speed up the process), and so non-matching 
input aborts the completion and hides the candidates. This is somewhat 
difficult to change.

But anyway, it follows the model set by IDEs which usually require 
matching input during completion, because the completion dropdown is 
often used for API discovery by the programmer, and it's often not big 
enough to show all candidates at the same time.

The foot-shooting restriction is alleviated by the fact the the user can 
disable it (unless the backend returned `t', but, to my knowledge, none 
of them do that, and I might eventually remove that possibility), and 
that it only comes into play after the user has interacted with the 
completion interface, i.e. not when completion was just initiated by the 
timer.

>> It probably should, but, again, lexical-binding is not available in
>> Emacs < 24. ATM I'm only using it to improve some logic that uses
>> `boundp' in `company-elisp'.
>
> I work under the assumption that my time is better spent if
> I concentrate on users of Emacs-24 (users who want the newer features of
> company can upgrade to Emacs-24).

This is totally fine for `company-capf', but `company-begin-with' is an 
old function/feature. I wonder if anyone's actually using it, though.