[ELPA] New package: company-eudc

[ELPA] New package: company-eudc

[Alexander Adolf]

Dear Emacs Developers,

I would kindly like to propose my new package company-eudc.el for
inclusion into ELPA. Here is an excerpt from the package's home page at
https://github.com/condition-alpha/company-eudc :

----------------------------------------------------------------------
What This Package Does

company-mode in conjunction with yasnippet makes composing emails a
breeze. Where things fall short, is the completion of email addresses,
however. Some Emacs MUA packages feed the addresses of emails in your
archive into the completion system. But what about those in your
contacts app, or those on the LDAP directory of your organisation?

The Emacs Unified Directory Client (EUDC), which is part of core Emacs,
can make information from your contacts app, or from LDAP servers
available. But there is no way of getting these to be presented as
completion candidates in company-mode.

company-eudc closes this gap by implementing a comapny back-end, that
retrieves names and email addresses from EUDC.


Limited Completion Scope

company-eudc will only provide completion candidates if, and only if,
all of the following apply:

1. the major mode of the current buffer is message-mode, or a derived
   mode (e.g. notmuch-message-mode);

2. the cursor is on the line of a message header field that requires one
   or more email addresses (From, To, Cc, Bcc, or Reply-to).

This prevents most likely useless completion proposals with email
addresses when typing names in the body of an email message ("Dear John,
..."), or in non email related modes.


Query Semantics

To assemble the query string, company-eudc collects all text preceding
the cursor, which is not part of the header field label, or another
email address. This means that you can e.g. type "John Smith", invoke
company-eudc-expand-inline, and "John Smith" will be passed to EUDC as
the query string. How EUDC handles multi-word queries is controlled by
the EUDC variable eudc-inline-query-format (which see).
----------------------------------------------------------------------

I have created an account on savannah.gnu.org yesterday (and am of
course not member of any projects there yet). I am subscribed to both,
emacs-devel@gnu.org, and bug-gnu-emacs@gnu.org. I have also signed a
copyright assignment form for everything Emacs (rt.gnu.org #1503473).


Many thanks and looking forward to your thoughts,

  --alexander

Re: [ELPA] New package: company-eudc

[Stefan Monnier]

> I would kindly like to propose my new package company-eudc.el for
> inclusion into ELPA. Here is an excerpt from the package's home page at
> https://github.com/condition-alpha/company-eudc :

I like this functionality, but:

- Why not add this directly to the EUDC code in Emacs itself?
- Why make it a Company backend instead of a CAPF function (since
  Company knows how to use CAPF functions as well)?


        Stefan

Re: [ELPA] New package: company-eudc

[Alexander Adolf]

Hello Stefan,

Many thanks for your swift response.

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> I would kindly like to propose my new package company-eudc.el for
>> inclusion into ELPA. Here is an excerpt from the package's home page at
>> https://github.com/condition-alpha/company-eudc :
>
> I like this functionality, but:
>
> - Why not add this directly to the EUDC code in Emacs itself?

I did propose it to the company maintainers, but it didn't fall on
fertile ground there.

> - Why make it a Company backend instead of a CAPF function (since
>   Company knows how to use CAPF functions as well)?
> [...]

That's one of the next things on my to-do list. ;-)


Cheers,

  --alexander

Re: [ELPA] New package: company-eudc

[Stefan Monnier]

>>> I would kindly like to propose my new package company-eudc.el for
>>> inclusion into ELPA. Here is an excerpt from the package's home page at
>>> https://github.com/condition-alpha/company-eudc :
>>
>> I like this functionality, but:
>> - Why not add this directly to the EUDC code in Emacs itself?
> I did propose it to the company maintainers, but it didn't fall on
> fertile ground there.

Hmm... not sure I understand.  I was proposing to add it to the EUDC
code in Emacs (e.g. `eudc.el`), not to the Company package.

>> - Why make it a Company backend instead of a CAPF function (since
>>   Company knows how to use CAPF functions as well)?
>> [...]
> That's one of the next things on my to-do list. ;-)

I think it would make a lot of sense to add such a CAPF directly to
`eudc.el`, and then to hook it into `message.el`.

I must admit, I don't know where `company-eudc-expand-inline` would end
up in that scenario, tho :-(

We could add a config var to control whether EUDC should be queried in
by default in `message-mode`, and we could easily add a command that
runs `completion-at-point` with EUDC's new CAPF enabled, but it would be
odd to run `company-begin-backend` from Emacs core code.  I guess we
could have a command that either runs `completion-at-point` or
`company-begin-backend` depending on a config var (e.g. whether
`company-mode` is enabled), but it would be nicer to make it work with
other completion UIs, like `corfu-mode`.


        Stefan

Re: [ELPA] New package: company-eudc

[Alexander Adolf]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>>> [...]
>>> I like this functionality, but:
>>> - Why not add this directly to the EUDC code in Emacs itself?
>> I did propose it to the company maintainers, but it didn't fall on
>> fertile ground there.
>
> Hmm... not sure I understand.  I was proposing to add it to the EUDC
> code in Emacs (e.g. `eudc.el`), not to the Company package.

EUDC does not contain any adapters/back-ends for other packages. And it
would have seemed odd to me, if a basic package contained code to adapt
itself to another package, which builds on top of itself.

>>> - Why make it a Company backend instead of a CAPF function (since
>>>   Company knows how to use CAPF functions as well)?
>>> [...]
>> That's one of the next things on my to-do list. ;-)
>
> I think it would make a lot of sense to add such a CAPF directly to
> `eudc.el`, and then to hook it into `message.el`.

Agreed; that's the plan (adding a new function to EUDC, which in turn
can be added to `completion-at-point-functions`).

> I must admit, I don't know where `company-eudc-expand-inline` would end
> up in that scenario, tho :-(
> [...]

Indeed; `company-eudc-expand-inline` is to cater for the particularity
of EUDC queries potentially taking very long. I have yet to research
whether CAPF has a similar function to start completion with a single,
specific back-end only, and which can be bound to a key. A `let`
statement shadowing `completion-at-point-functions` could be a (slightly
hacky though) way of achieving this.

Another issue to solve (showing off my lack of knowledge of CAPF here)
is providing the EUDC suggestions in suitable message header fields
only.

I'll need to scratch my head a bit more over these, and possibly further
things, I guess.


Cheers,

  --alexander

Re: [ELPA] New package: company-eudc

[Stefan Monnier]

> EUDC does not contain any adapters/back-ends for other packages. And it
> would have seemed odd to me, if a basic package contained code to adapt
> itself to another package, which builds on top of itself.

The "completion backends" used to be distributed with the Company
package, because that's what you need to do to get things started, but
fundamentally Company is a piece of infrastructure, and every backend
belongs with the package for which it provides completions rather than
with Company.

>>>> - Why make it a Company backend instead of a CAPF function (since
>>>>   Company knows how to use CAPF functions as well)?
>>>> [...]
>>> That's one of the next things on my to-do list. ;-)
>> I think it would make a lot of sense to add such a CAPF directly to
>> `eudc.el`, and then to hook it into `message.el`.
> Agreed; that's the plan (adding a new function to EUDC, which in turn
> can be added to `completion-at-point-functions`).

See below for a 100% untested first step.

>> I must admit, I don't know where `company-eudc-expand-inline` would end
>> up in that scenario, tho :-(
>> [...]
>
> Indeed; `company-eudc-expand-inline` is to cater for the particularity
> of EUDC queries potentially taking very long. I have yet to research
> whether CAPF has a similar function to start completion with a single,
> specific back-end only, and which can be bound to a key.

CAPF is only a backend, whereas "start completion" presumes a command
and that would inevitably be part of the UI.

> A `let` statement shadowing `completion-at-point-functions` could be
> a (slightly hacky though) way of achieving this.

Yes, that would be the natural way to do that, but the question is what
to put within this let-binding: you can either call
`company-begin-backend` or `completion-at-point`, or `corfu-<something>`,
or `auto-complete-<something>`, depending on the favorite UI of this user.

> Another issue to solve (showing off my lack of knowledge of CAPF here)
> is providing the EUDC suggestions in suitable message header fields
> only.

I think the patch below shows how this is done (I don't have an EUDC
setup here to test the code, sorry).

Should we add the company-specific code for now in `eudc.el` and then
work to replace it with a CAPF backend (bringing it to feature-parity
with the Company code will probably take some time and potentially
changes elsewhere, which is why I suggest to install the Company code
now even though the intention is to make it redundant).


        Stefan


diff --git a/company-eudc.el b/company-eudc.el
index 52dd21ce08..f89626225c 100644
--- a/company-eudc.el
+++ b/company-eudc.el
@@ -102,6 +102,36 @@ For the semantics of COMMAND, ARG, and IGNORED see `company-backends'."
     (`sorted t)
     (`ignore-case t)))
 
+(defvar eudc-completion-table
+  ;; FIXME: This belongs in `eudc.el'.
+  (completion-table-dynamic
+   (lambda (prefix)
+     ;; FIXME: completion tables can only do "prefix completion" so the
+     ;; `split-string' below won't give the intended result.
+     ;; The intended behavior is normally instead provided by
+     ;; a `completion-style' such as `orderless' which would call this
+     ;; completion tables several times (once per "word").
+     ;; A possible other solution is to use the "backend" (aka "passthrough")
+     ;; completion style which lets the completion table provide its own
+     ;; completion style.
+     (eudc-query-with-words (split-string prefix "[ \t]+")))))
+
+(defun message-eudc-capf ()
+  ;; FIXME: This belongs in `message.el' and is probably redundant there
+  ;; because there's already code doing that for other
+  ;; completion tables (bbdb, ecomplete, ...).
+  (let ((end (point))
+	(start (save-excursion
+		 (if (re-search-backward "\\([:,]\\|^\\)[ \t]*"
+					 (point-at-bol) 'move)
+		     (goto-char (match-end 0)))
+		 (point))))
+    (when (let ((case-fold-search t))
+	    (looking-back
+	     "^\\([^ :]*-\\)?\\(To\\|B?Cc\\|From\\|Reply-to\\):.*? *\\([^,;]*\\)"
+	     (line-beginning-position)))
+      (list start end eudc-completion-table))))
+
 ;;;###autoload
 (defun company-eudc-activate-autocomplete ()
   "Provide `company-eudc' completions under company mode control.